makeover_tui/piece.rs
1//! The pieces every terminal app draws, drawn once.
2//!
3//! # Not `widget`
4//!
5//! `makeover-layout` owns that word for something else, and the two meanings do
6//! not sit together. A `Region::Widget` there is host-agnostic: a named
7//! assembly of primitives that every renderer draws its own way. What is in
8//! this module is the opposite end, renderer-local, the answer to *what a meter
9//! looks like in cells*, taking a description plus what only a terminal knows.
10//! The style type is `PieceStyle`.
11//!
12//! A meter, a badge, a control, a figure and a form field are what a screen is
13//! made of below the level [`table`](crate::table) works at. [`activity`] and
14//! [`awaiting`] draw a wait, out of wiki `loading-and-progress-standard`.
15//!
16//! # What these take, and what they leave alone
17//!
18//! Each takes a `makeover-layout` description, a [`PieceStyle`], and whatever
19//! the *host* knows that a description never carries. That last part is the
20//! shape worth copying: [`field`] takes what is currently typed in the box as a
21//! separate argument, because [`Field`] deliberately does not carry a value and
22//! is not going to. `makeover-immediate` reached the same seam from the other
23//! side with its `Filling`, and [`Held`] is that seam here.
24//!
25//! Focus is the other one. Nothing in a description says which control the user
26//! is on, so every drawing here takes `focused` as an argument and the caller
27//! is what counts. What focus *looks like* is this crate's answer and not the
28//! caller's, which is the point of it being here: see
29//! [`PieceStyle::focused`].
30//!
31//! # What they do not do
32//!
33//! No layout. Each answers rows for a width, or draws into the rect it is
34//! given, top-aligned, and never below it. Nothing here measures twice and
35//! nothing here places anything relative to anything else, because the moment
36//! it did it would be a layout engine with one consumer's flow baked into it.
37
38use makeover_layout::{
39 Act, Awaiting, Bar, Chart, Fact, Field, FieldKind, Figure, Heading, Meter, ThemeVariant, Token,
40 Tone,
41};
42use ratatui::buffer::Buffer;
43use ratatui::layout::Rect;
44use ratatui::style::{Modifier, Style};
45use ratatui::text::{Line, Span};
46
47use crate::text;
48use std::time::Duration;
49
50/// What a badge of one tone is drawn in, when it is drawn filled.
51///
52/// Two styles and not one, because a filled badge is three spans: an edge, the
53/// label, an edge. The label takes [`fill`](Self::fill) whole. An edge takes
54/// the fill's background with [`edge`](Self::edge)'s foreground over it, so
55/// the half of the cell the glyph leaves empty is the badge's own ground.
56#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
57pub struct BadgeStyle {
58 /// The ground and the ink.
59 pub fill: Style,
60 /// The edge, as a foreground.
61 pub edge: Style,
62}
63
64/// The colours and marks the drawings below use.
65///
66/// [`TableStyle`](crate::table::TableStyle)'s shape, for its reasons: an
67/// ungated struct of styles with a [`Default`], plus a
68/// [`from_theme`](Self::from_theme) that is what a consumer holding a loaded
69/// theme should reach for first. A consumer painting bevels and nothing else
70/// should not have to supply text tones it never uses, and gating the whole
71/// module on `theme` would make these unreachable to anyone hand-picking
72/// colours.
73///
74/// The default is the one that survives a terminal with no colour at all:
75/// modifiers only, no foreground anywhere. That is not a placeholder. A
76/// two-colour terminal is the case where a `Style` carrying a foreground is a
77/// foreground that will not land, and bold-and-reversed is what is left.
78#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub struct PieceStyle {
80 /// Ordinary content, and what [`Tone::Neutral`] reads as.
81 pub content: Style,
82 /// Content one step back: a field's label, a quoted run.
83 pub secondary: Style,
84 /// Content two steps back: a caption, a hint, a meter's reading.
85 pub muted: Style,
86 /// Something worth knowing and nothing to do about it.
87 pub info: Style,
88 /// Something finished and it worked.
89 pub success: Style,
90 /// Something the user should look at.
91 pub warning: Style,
92 /// Something broken, or about to be destroyed.
93 pub danger: Style,
94 /// A page title.
95 pub page: Style,
96 /// A section title.
97 pub section: Style,
98 /// A subsection title.
99 pub subsection: Style,
100 /// Text that goes somewhere, and a control's label.
101 pub action: Style,
102 /// A control filled with the action colour, for the one on a screen that is
103 /// the thing to press. A form's submit is the case that has it.
104 pub filled: Style,
105 /// A surface set back from the one it sits on, by colour and nothing else.
106 /// What a code run takes, since every cell is monospace and the thing a
107 /// webview says with a typeface cannot be said that way here.
108 pub sunken: Style,
109 /// A badge of each tone, in [`Tone`]'s order: neutral, info, success,
110 /// warning, danger. Read through [`badge`](Self::badge).
111 pub badges: [BadgeStyle; 5],
112 /// The glyphs either side of a filled badge, or `None` to draw a badge as
113 /// its label in parentheses, in its tone.
114 ///
115 /// `None` by default, since a fill is a colour and the default has none to
116 /// spend.
117 pub badge_edges: Option<[&'static str; 2]>,
118 /// What "you are on this one" adds to whatever it lands on.
119 ///
120 /// Reversed video by default, which is the affordance a cell has left once
121 /// colour is spent on tone and bold on weight. A webview says it with an
122 /// outline; a terminal has no outline that is not four more cells.
123 pub focus: Modifier,
124 /// How many cells [`meter`] spends on its bar.
125 pub meter_cells: u16,
126 /// The filled part of a bar.
127 pub meter_full: char,
128 /// The empty part of a bar.
129 pub meter_empty: char,
130 /// What marks a compulsory field, appended to its label.
131 ///
132 /// A knob for `makeover-immediate`'s reason: it is the one piece of *copy*
133 /// here, and copy is not a renderer's call.
134 pub required_marker: &'static str,
135}
136
137impl Default for PieceStyle {
138 /// Modifiers only, no foreground: what survives a terminal with two
139 /// colours.
140 fn default() -> Self {
141 Self {
142 content: Style::new(),
143 secondary: Style::new(),
144 muted: Style::new().add_modifier(Modifier::DIM),
145 info: Style::new(),
146 success: Style::new(),
147 warning: Style::new(),
148 danger: Style::new().add_modifier(Modifier::BOLD),
149 page: Style::new().add_modifier(Modifier::BOLD),
150 section: Style::new().add_modifier(Modifier::BOLD),
151 subsection: Style::new(),
152 action: Style::new().add_modifier(Modifier::UNDERLINED),
153 filled: Style::new().add_modifier(Modifier::REVERSED),
154 sunken: Style::new().add_modifier(Modifier::DIM),
155 badges: [BadgeStyle::default(); 5],
156 badge_edges: None,
157 focus: Modifier::REVERSED,
158 meter_cells: 10,
159 meter_full: '#',
160 meter_empty: '-',
161 required_marker: "*",
162 }
163 }
164}
165
166impl PieceStyle {
167 /// The house widgets, from a loaded theme.
168 ///
169 /// The lift this module exists for. `quasi-tui` carried every line of this
170 /// as private methods on its own renderer; a second terminal app wanting a
171 /// toned control had no way to reach them and would have picked its own
172 /// colours for the same five tones.
173 #[cfg(feature = "theme")]
174 #[must_use]
175 pub fn from_theme(theme: &crate::Theme) -> Self {
176 Self {
177 content: Style::new().fg(theme.content_primary),
178 secondary: Style::new().fg(theme.content_secondary),
179 muted: Style::new().fg(theme.content_muted),
180 info: Style::new().fg(theme.status_info),
181 success: Style::new().fg(theme.status_success),
182 warning: Style::new().fg(theme.status_warning),
183 danger: Style::new().fg(theme.status_danger),
184 // Three depths and two of them are bold, which is the whole of what
185 // a terminal has: there is no type scale in a grid of one cell
186 // size. A page title takes bold and the accent, a section bold, a
187 // subsection the secondary colour. That is the emphasis order a
188 // webview's type scale says with size, said with the two axes a
189 // cell has.
190 page: Style::new()
191 .fg(theme.action_primary)
192 .add_modifier(Modifier::BOLD),
193 section: Style::new()
194 .fg(theme.content_primary)
195 .add_modifier(Modifier::BOLD),
196 subsection: Style::new().fg(theme.content_secondary),
197 action: Style::new().fg(theme.action_primary),
198 filled: Style::new().fg(theme.selection_on).bg(theme.action_primary),
199 sunken: Style::new().bg(theme.surface_sunken),
200 // The chip of wiki `table-model`: a fill, an edge in the tone, and
201 // the label in content. A status fills with makeover's
202 // `<tone>-surface` and a neutral badge with the hover's step, which
203 // is the weight the tone fills sit at and shows on a striped row
204 // as well as a plain one. The raised surface the webview fills a
205 // neutral chip with would vanish into the table ground here, where
206 // no hairline edge is thin enough to draw around it.
207 badges: {
208 let badge = |fill, edge| BadgeStyle {
209 fill: Style::new().fg(theme.content_primary).bg(fill),
210 edge: Style::new().fg(edge),
211 };
212 [
213 badge(theme.row_hover, theme.line_border),
214 badge(theme.status_info_surface, theme.status_info),
215 badge(theme.status_success_surface, theme.status_success),
216 badge(theme.status_warning_surface, theme.status_warning),
217 badge(theme.status_danger_surface, theme.status_danger),
218 ]
219 },
220 // Half blocks, the bevel's glyphs: the outer half of each end cell
221 // is the edge and the inner half is fill, so the label sits half a
222 // cell in. The same two cells the parentheses took, so a badge
223 // gaining its fill moves nothing beside it.
224 badge_edges: Some(["\u{258C}", "\u{2590}"]),
225 focus: Modifier::REVERSED,
226 meter_cells: 10,
227 meter_full: '#',
228 meter_empty: '-',
229 required_marker: "*",
230 }
231 }
232
233 /// The style a tone reads as.
234 ///
235 /// [`Tone`] is closed and stays closed, so this is total and needs no
236 /// fallback arm.
237 #[must_use]
238 pub const fn tone(&self, tone: Tone) -> Style {
239 match tone {
240 Tone::Neutral => self.content,
241 Tone::Info => self.info,
242 Tone::Success => self.success,
243 Tone::Warning => self.warning,
244 Tone::Danger => self.danger,
245 }
246 }
247
248 /// What a badge of this tone is drawn in.
249 #[must_use]
250 pub const fn badge(&self, tone: Tone) -> BadgeStyle {
251 self.badges[match tone {
252 Tone::Neutral => 0,
253 Tone::Info => 1,
254 Tone::Success => 2,
255 Tone::Warning => 3,
256 Tone::Danger => 4,
257 }]
258 }
259
260 /// The style a heading reads as.
261 #[must_use]
262 pub const fn heading(&self, level: Heading) -> Style {
263 match level {
264 Heading::Page => self.page,
265 Heading::Section => self.section,
266 Heading::Subsection => self.subsection,
267 }
268 }
269
270 /// `style`, plus the mark that says the user is on this one.
271 ///
272 /// Takes the flag rather than being called behind an `if`, because every
273 /// caller has a bool in hand and the branch is the part that gets forgotten.
274 #[must_use]
275 pub fn focused(&self, focused: bool, style: Style) -> Style {
276 if focused {
277 style.add_modifier(self.focus)
278 } else {
279 style
280 }
281 }
282}
283
284/// What a field currently holds, which a description never carries.
285///
286/// The terminal counterpart of `makeover_immediate::Filling`, and the same seam:
287/// there the widget writes through a `&mut` as the value is edited, and here the
288/// caller keeps an edit buffer and lends it out for the draw. Neither is
289/// something [`Field`] could carry without becoming a form model.
290///
291/// An enum rather than a bag of options, for `Filling`'s reason: a checkbox
292/// holding a string is unsayable here, where a struct would let it be said and
293/// then have to cope.
294#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
295pub enum Held<'a> {
296 /// Nothing typed and nothing chosen. The control draws empty.
297 #[default]
298 Absent,
299 /// What is in the box, or the `value` of the chosen [`Choice`].
300 ///
301 /// [`Choice`]: makeover_layout::Choice
302 Text(&'a str),
303 /// A checkbox, on or off.
304 On(bool),
305 /// Both ends of a [`FieldKind::Interval`], lower first.
306 ///
307 /// Two values rather than one string with a separator, which is
308 /// [`makeover_layout::Field::upper_name`]'s reason one level down: an
309 /// interval is submitted under two names, so it is held as two values, and
310 /// a delimiter this crate owned could appear inside either of them.
311 ///
312 /// Either end may be empty while the other stands. An open end is an
313 /// answer -- "over 120 BPM" -- rather than a half-filled box.
314 Between {
315 /// What the lower box holds now.
316 lower: &'a str,
317 /// What the upper box holds now.
318 upper: &'a str,
319 },
320}
321
322impl<'a> Held<'a> {
323 /// What is typed, as a string. A checkbox has no text and answers empty.
324 #[must_use]
325 pub const fn text(self) -> &'a str {
326 match self {
327 Self::Text(text) | Self::Between { lower: text, .. } => text,
328 Self::Absent | Self::On(_) => "",
329 }
330 }
331
332 /// The upper end, for the one variant that has one.
333 #[must_use]
334 pub const fn upper(self) -> &'a str {
335 match self {
336 Self::Between { upper, .. } => upper,
337 Self::Absent | Self::Text(_) | Self::On(_) => "",
338 }
339 }
340
341 /// Whether a checkbox is ticked.
342 #[must_use]
343 pub const fn on(self) -> bool {
344 matches!(self, Self::On(true))
345 }
346}
347
348/// What a host can see about a wait that is running.
349///
350/// Neither half is derivable from a description, which is why both are here and
351/// not on [`Awaiting`]. That type says how big the payload is; how much of it
352/// has landed is a fact about a transfer in flight, and only whoever is running
353/// the transfer knows it.
354///
355/// The same shape `makeover-immediate` carries, deliberately: a wait is one
356/// reading on every surface and the two renderers should not disagree about
357/// what a host owes them.
358#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
359pub struct Progress {
360 /// How much has arrived, in whatever unit the description counted.
361 pub delivered: Option<u64>,
362 /// How long the wait has lasted so far.
363 ///
364 /// The one time value a wait may show. See [`awaiting`] for the three it
365 /// may not.
366 pub elapsed: Option<Duration>,
367}
368
369/// The activity mark: one cell, lit or dark.
370///
371/// Rule 2 of wiki `loading-and-progress-standard`, and the surface the metaphor
372/// came from. A hard-disk light is one cell that blinks, and a terminal draws
373/// that with no metaphor in the way — where a webview needs a keyframe and egui
374/// needs a repaint schedule, this is a character.
375///
376/// The two glyphs are [`PieceStyle::meter_full`] and
377/// [`PieceStyle::meter_empty`], not a third pair. A bar's filled cell and a lit
378/// mark are the same statement in the same alphabet, and a terminal that had to
379/// render two vocabularies of "on" would be saying there are two kinds of on.
380///
381/// **Dark, not absent.** A mark that is drawn half the time is a hole in the
382/// line, and the line reflows around it or the reader loses where to look. It
383/// occupies its cell either way.
384///
385/// `lit` is the caller's: this module holds no clock. [`crate::activity_lit`]
386/// is the one place the phase is worked out from the cadence, so a caller
387/// should reach for that rather than dividing by 500 itself.
388#[must_use]
389pub fn activity(style: &PieceStyle, lit: bool) -> Span<'static> {
390 if lit {
391 Span::styled(style.meter_full.to_string(), style.action)
392 } else {
393 Span::styled(style.meter_empty.to_string(), style.muted)
394 }
395}
396
397/// A wait as one line, drawn from what is actually known about it.
398///
399/// [`Awaiting::is_determinate`] is the first branch and there is a second the
400/// description cannot answer: whether anything is watching the transfer. A bar
401/// wants a total and a numerator both, so a described amount with no
402/// [`Progress::delivered`] beside it draws the mark and the size it is waiting
403/// on, rather than an empty trough implying somebody is counting.
404///
405/// So three drawings for three states, which is the point:
406///
407/// ```text
408/// unmeasured # a blinking cell
409/// measured, nothing watching # 41943040 the cell, and how much there is
410/// measured and observed ####------ 17825792/41943040 4s
411/// ```
412///
413/// **What the bar may not do**, from rule 1 of the standard and from
414/// [`Awaiting`]'s own docs: what is done over what there is, plus the time it
415/// has taken. Never a remaining time, an arrival time, or a rate extrapolated
416/// forward. A prediction is wrong the moment the transfer stalls, and being
417/// confidently wrong is worse than being honestly indeterminate.
418///
419/// The numbers are raw. The unit is the app's — bytes for an upload, rows for
420/// an import — and a renderer that formatted one as a file size would be
421/// dressing up a quantity it was deliberately not told about.
422#[must_use]
423pub fn awaiting(
424 style: &PieceStyle,
425 awaiting: Awaiting,
426 progress: Progress,
427 lit: bool,
428) -> Line<'static> {
429 let Some(total) = awaiting.amount else {
430 return Line::from(vec![activity(style, lit)]);
431 };
432 let Some(done) = progress.delivered else {
433 return Line::from(vec![
434 activity(style, lit),
435 Span::styled(format!(" {total}"), style.muted),
436 ]);
437 };
438 let cells = u32::from(style.meter_cells);
439 // In cells rather than in floating point, the way `meter` does it: a
440 // terminal's bar has ten states and rounding through an f64 to reach one of
441 // ten is arithmetic nobody needs. Saturating rather than wrapping, because
442 // a transfer that over-delivers is a real case and a panicking bar is not
443 // the way to report it.
444 let filled = u32::try_from(
445 done.saturating_mul(u64::from(cells))
446 .checked_div(total)
447 .unwrap_or(0),
448 )
449 .unwrap_or(cells)
450 .min(cells);
451 let bar = format!(
452 "{}{}",
453 style.meter_full.to_string().repeat(filled as usize),
454 style
455 .meter_empty
456 .to_string()
457 .repeat((cells - filled) as usize)
458 );
459 let reading = match progress.elapsed {
460 Some(elapsed) => format!(" {done}/{total} {}s", elapsed.as_secs()),
461 None => format!(" {done}/{total}"),
462 };
463 Line::from(vec![
464 Span::styled(bar, style.action),
465 Span::styled(reading, style.muted),
466 ])
467}
468
469/// A proportion as one line: the bar, then the reading beside it.
470///
471/// The reading is built here from the two numbers and the noun rather than
472/// taken assembled, which is what [`Meter::label`] carrying the noun alone is
473/// for: a terminal at one line and a tooltip want different sentence orders.
474#[must_use]
475pub fn meter(style: &PieceStyle, meter: &Meter<'_>) -> Line<'static> {
476 // `usize` the whole way, which is what `Meter`'s widening bought rather
477 // than cost. The counts are `usize` now, `str::repeat` wants `usize`, and
478 // `meter_cells` converts infallibly from `u16`, so the two `as usize`
479 // casts this held before are gone and there is no narrowing anywhere: the
480 // proportion is computed in the counts' own domain and lands directly in
481 // the unit the bar is drawn in.
482 //
483 // `checked_mul` still earns its place. A stand-in count crossing a
484 // residual is around 9.09e15, and multiplying that by the cell width is
485 // the one place here that can still overflow.
486 let cells = usize::from(style.meter_cells);
487 let filled = meter
488 .done
489 .checked_mul(cells)
490 .and_then(|reached| reached.checked_div(meter.total))
491 .unwrap_or(0)
492 .min(cells);
493 let bar = format!(
494 "{}{}",
495 style.meter_full.to_string().repeat(filled),
496 style.meter_empty.to_string().repeat(cells - filled)
497 );
498 let reading = match meter.label {
499 Some(label) => format!(" {}/{} {label}", meter.done, meter.total),
500 None => format!(" {}/{}", meter.done, meter.total),
501 };
502 Line::from(vec![
503 Span::styled(bar, style.tone(meter.tone)),
504 Span::styled(reading, style.muted),
505 ])
506}
507
508/// A badge or a chip as a line.
509///
510/// A chip is its label in square brackets, in its tone: it answers a press, and
511/// the bracket says so. A badge answers nothing and is drawn filled where the
512/// style has [`badge_edges`](PieceStyle::badge_edges), as an edge, the label on
513/// its fill, and an edge (wiki `table-model`), and in round brackets in its tone
514/// where it has none. Every spelling is the label and two cells, so the width
515/// does not depend on which one a terminal gets.
516///
517/// `latched` is a chip that is switched on, and it reads as reversed. So does
518/// focus, which is a collision a terminal cannot avoid: latched is "this filter
519/// is on" and focused is "you are here", and there is one spare axis for two
520/// facts. Said here rather than resolved by inventing a third look nobody would
521/// read.
522///
523/// A chip's removable half is not drawn. The `x` a webview hangs on a chip is a
524/// second control inside one span, and a terminal reaches a control by focusing
525/// it; two targets in one cell run is a question for whoever owns the
526/// interaction, not for a drawing.
527#[must_use]
528pub fn token(
529 style: &PieceStyle,
530 label: &str,
531 kind: Token,
532 tone: Tone,
533 latched: bool,
534 focused: bool,
535) -> Line<'static> {
536 let mark = |painted: Style| {
537 if latched {
538 painted.add_modifier(style.focus)
539 } else {
540 style.focused(focused, painted)
541 }
542 };
543 match (kind, style.badge_edges) {
544 (Token::Badge, Some([open, close])) => {
545 let badge = style.badge(tone);
546 let edge = mark(badge.fill.patch(badge.edge));
547 Line::from(vec![
548 Span::styled(open, edge),
549 Span::styled(label.to_owned(), mark(badge.fill)),
550 Span::styled(close, edge),
551 ])
552 }
553 (Token::Badge, None) => {
554 Line::from(Span::styled(format!("({label})"), mark(style.tone(tone))))
555 }
556 (Token::Chip { .. }, _) => {
557 Line::from(Span::styled(format!("[{label}]"), mark(style.tone(tone))))
558 }
559 }
560}
561
562/// A control as one line.
563///
564/// `< Label > (key)`, and the key only where the description named one. That
565/// member is the one place `makeover-layout` anticipated a terminal before there
566/// was one, and this is the renderer that reads it.
567///
568/// A control that commits ([`Act::commits`]) is `[ Label ]` filled with the
569/// action colour, which is the weight difference a webview carries as its
570/// default-button ring. Its tone still says what pressing it means: a
571/// committing delete is filled in the danger colour, not the action colour.
572///
573/// A disabled control is drawn muted and is not marked focused, whatever the
574/// caller passed: it is present, visible and not answering, so a focus mark on
575/// it would be an affordance that lies. Whether it is reachable at all is the
576/// caller's count to keep — ask [`Act::disabled`]. A disabled commit keeps its
577/// brackets, for the reason a disabled button keeps its bevel.
578///
579/// # The brackets are the commit and the fill is the lead
580///
581/// Two marks for two questions, which is what lets a control wear both:
582/// `[ Label ]` says pressing this commits what you staged, and the reversed
583/// fill says this is the act the screen is for. The suite's rule is that
584/// leading fills and committing outlines, and a terminal's outline is its
585/// brackets.
586///
587/// The fill sat on `commits` until [`Act::leading`] existed, which made every
588/// sub-form's submit the brightest thing on its screen. On goingson's task
589/// overview that was a subtask's Add, drawn louder than the Start and Complete
590/// the screen is actually for. The brackets have not moved; only the fill has.
591///
592/// A toned act keeps its tone rather than taking the fill, unchanged from
593/// before: a leading Danger control stays the danger colour, because what
594/// pressing it means outranks how badly the screen wants it pressed.
595#[must_use]
596pub fn act(style: &PieceStyle, act: &Act<'_>, focused: bool) -> Line<'static> {
597 let painted = if act.disabled() {
598 style.muted
599 } else if act.leading && act.tone == Tone::Neutral {
600 style.focused(focused, style.filled)
601 } else {
602 style.focused(focused, style.tone(act.tone))
603 };
604 let (open, close) = if act.commits { ("[", "]") } else { ("<", ">") };
605 let label = match act.key {
606 Some(key) => format!("{open} {} {close} ({key})", act.label),
607 None => format!("{open} {} {close}", act.label),
608 };
609 Line::from(Span::styled(label, painted))
610}
611
612/// The muted line a control's [`Act::hint`] draws as, or `None` where it has
613/// none.
614///
615/// A terminal has no pointer, so the hover the other two renderers spend a hint
616/// on is not available and is not the thing anyway: what the description says
617/// is that the sentence is true, never that it is hidden. A row under the
618/// control is this renderer's answer, and it is the same muted row
619/// [`field`] gives a field's note, so the two read alike wherever they land.
620///
621/// Its own function rather than extra lines out of [`act`], because a control
622/// is one [`Line`] everywhere it is drawn and a caller laying out a run needs
623/// to know it is placing two things.
624#[must_use]
625pub fn act_note(style: &PieceStyle, act: &Act<'_>) -> Option<Line<'static>> {
626 act.hint
627 .map(|hint| Line::from(Span::styled(hint.to_owned(), style.muted)))
628}
629
630/// The rows [`figure`] wants at `width`.
631#[must_use]
632pub fn figure_height(figure: &Figure<'_>, width: u16) -> u16 {
633 text::height(figure.value, width) + text::height(figure.caption, width)
634}
635
636/// A figure: the number, then what it counts under it.
637///
638/// The tone lands on the value and its change rather than on the caption, which
639/// is what [`Figure::tone`] means: the figure is an ordinary fact and it is the
640/// movement that reads as good or bad.
641pub fn figure(style: &PieceStyle, figure: &Figure<'_>, area: Rect, buf: &mut Buffer) -> u16 {
642 let value = match figure.change {
643 Some(change) => format!("{} {change}", figure.value),
644 None => figure.value.to_owned(),
645 };
646 let used = text::draw(
647 &value,
648 style.tone(figure.tone).add_modifier(Modifier::BOLD),
649 area,
650 buf,
651 );
652 used + text::draw(figure.caption, style.muted, below(area, used), buf)
653}
654
655/// The rows [`facts`] wants at `width`.
656///
657/// One per fact, plus whatever a long value wraps to. The label never wraps:
658/// the column is sized to the longest label, so a label that would not fit is a
659/// pane whose labels are too long for this terminal, and wrapping it would
660/// destroy the alignment that is the whole member.
661#[must_use]
662pub fn facts_height(facts: &[Fact<'_>], width: u16) -> u16 {
663 let label = label_column(facts, width);
664 let rest = width.saturating_sub(label).saturating_sub(1);
665 facts
666 .iter()
667 .map(|fact| text::height(fact.value, rest).max(1))
668 .sum()
669}
670
671/// How wide the label column is: the longest label, and never past half.
672///
673/// The cap is the terminal's own answer to a problem a webview does not have.
674/// `max-content` in a grid is bounded by the box; here a 40-character label in
675/// an 80-column pane would leave nothing for the values, so the column stops at
676/// half the width and a longer label is cut. A cut label beside a readable
677/// value is the better of the two losses.
678fn label_column(facts: &[Fact<'_>], width: u16) -> u16 {
679 let longest = facts
680 .iter()
681 .map(|fact| u16::try_from(text::cells(fact.label)).unwrap_or(u16::MAX))
682 .max()
683 .unwrap_or(0);
684 longest.min(width / 2)
685}
686
687/// Labelled facts, with their values in one column.
688///
689/// **The alignment is the member.** Five goingson panes were drawing this as a
690/// row each and every value started after its own label, so no column formed.
691/// Here that is a label column sized to the longest label, every value starting
692/// at the same cell.
693///
694/// The label reads back and the value takes content, which is the rule
695/// [`figure`] states for a value against its caption. A fact with nothing to
696/// say never reaches this: `Node::facts` drops it as it builds.
697pub fn facts(style: &PieceStyle, facts: &[Fact<'_>], area: Rect, buf: &mut Buffer) -> u16 {
698 let column = label_column(facts, area.width);
699 let mut used = 0;
700 for fact in facts {
701 if used >= area.height {
702 break;
703 }
704 let line = below(area, used);
705 // Cut to the column in cells, a wide glyph that would straddle its
706 // edge left out whole.
707 let mut label = String::new();
708 let mut taken = 0;
709 for c in fact.label.chars() {
710 let wide = unicode_width::UnicodeWidthChar::width(c).unwrap_or(0);
711 if taken + wide > usize::from(column) {
712 break;
713 }
714 taken += wide;
715 label.push(c);
716 }
717 // Padded rather than positioned, so the value column is one place and
718 // not two arithmetics that can disagree.
719 label.extend(std::iter::repeat_n(
720 ' ',
721 usize::from(column).saturating_sub(taken),
722 ));
723 text::draw(&label, style.muted, line, buf);
724 let values = Rect {
725 x: line.x.saturating_add(column).saturating_add(1),
726 width: line.width.saturating_sub(column).saturating_sub(1),
727 ..line
728 };
729 used += text::draw(fact.value, style.content, values, buf).max(1);
730 }
731 used
732}
733
734/// The rows [`field`] wants at `width`.
735///
736/// A label row, the control's rows, and a row for whatever went wrong. A hidden
737/// field is nothing at all, which is the one field kind a terminal and a webview
738/// agree on completely.
739#[must_use]
740pub fn field_height(style: &PieceStyle, field: &Field<'_>, width: u16) -> u16 {
741 if !field.kind.visible() {
742 return 0;
743 }
744 let label = text::height(&label_of(style, field), width);
745 // A range is one row like every other single control: the bar, its two ends
746 // and the reading are one line by construction, and a bar that wrapped
747 // would stop being a bar.
748 let body = match field.kind {
749 // Both multi-line kinds get the same three rows, keyed on the
750 // description's own `multiline` rather than on the member: a markdown
751 // field falling through to the single-row arm is one line for a value
752 // whose whole point is that it has several. What a terminal does *with*
753 // the markdown is another question and the answer here is nothing --
754 // the source is the text, and drawing it as text is honest.
755 kind if kind.multiline() => 3,
756 kind if kind.offers_options() => u16::try_from(field.options.len()).unwrap_or(u16::MAX),
757 // A row per theme, a row per group heading, and a row for the follow
758 // entry when there is one. The headings are counted by walking the
759 // variants rather than by assuming three, because a machine with only
760 // dark themes installed draws one heading and reserving three would
761 // leave two blank rows under every picker.
762 kind if kind.offers_themes() => {
763 let mut variants = 0u16;
764 let mut open: Option<ThemeVariant> = None;
765 for theme in field.themes {
766 if open != Some(theme.variant) {
767 variants = variants.saturating_add(1);
768 open = Some(theme.variant);
769 }
770 }
771 let rows = u16::try_from(field.themes.len()).unwrap_or(u16::MAX);
772 rows.saturating_add(variants)
773 .saturating_add(u16::from(field.follows.is_some()))
774 }
775 _ => 1,
776 };
777 let note = message_of(style, field).map_or(0, |(text, _)| text::height(text, width));
778 label + body + note
779}
780
781/// A question: its label, the box, and its standing help or what is wrong now.
782///
783/// `held` is what the user has done to it since the screen arrived, which is the
784/// argument a description cannot supply. See [`Held`].
785///
786/// `focused` marks the box rather than the label, because the box is where the
787/// typing lands.
788///
789/// [`makeover_layout::Field::as_instant`] is carried and not honoured. It asks
790/// for a wall-clock value to be submitted as the moment it names, and this
791/// renderer has no submission: it draws the box and the runtime above it
792/// gathers what a submit sends, so the conversion belongs where that gathering
793/// happens. The value drawn and read here is the local one, in
794/// `makeover_layout::DATETIME_FORMAT`.
795pub fn field(
796 style: &PieceStyle,
797 field: &Field<'_>,
798 held: Held<'_>,
799 focused: bool,
800 area: Rect,
801 buf: &mut Buffer,
802) -> u16 {
803 field_at(style, field, held, focused, None, area, buf)
804}
805
806/// [`field`], with the option the caret is on.
807///
808/// `cursor` is an index into [`Field::options`], and it is what a terminal has
809/// instead of a pointer: a reader picking from a list walks along it, and the
810/// row being walked past has to be visible or the key that ticks it ticks a row
811/// nobody can see. While there is a cursor it takes the focus mark, and a
812/// chosen option is told by its box alone, so the two never read alike.
813///
814/// Only an option-taking field reads it, and only while `focused`. Beside
815/// [`field`] rather than an argument on it, because every caller with no list
816/// to walk would otherwise pass `None` to say so.
817pub fn field_at(
818 style: &PieceStyle,
819 field: &Field<'_>,
820 held: Held<'_>,
821 focused: bool,
822 cursor: Option<usize>,
823 area: Rect,
824 buf: &mut Buffer,
825) -> u16 {
826 // A hidden field is data travelling with the form. There is nothing to
827 // draw, and whoever submits carries it.
828 if !field.kind.visible() || area.width == 0 || area.height == 0 {
829 return 0;
830 }
831
832 let mut used = text::draw(&label_of(style, field), style.secondary, area, buf);
833
834 let well = style.focused(focused, style.content);
835 let placeholder = field.placeholder.unwrap_or_default();
836
837 used += match field.kind {
838 FieldKind::Checkbox => text::draw(
839 if held.on() { "[x]" } else { "[ ]" },
840 well,
841 below(area, used),
842 buf,
843 ),
844 // A range's two ends are what the question means, so they are drawn
845 // rather than left to a hint. A terminal has the bar already: this is
846 // `meter`'s cells with the extent read out at either side of them.
847 //
848 // An unbounded range has no extent to draw and falls through to the
849 // text path, which is `makeover-immediate`'s answer as well and for the
850 // same reason: bounds this crate invented are bounds the user would
851 // then drag against.
852 FieldKind::Range if field.bounded() => {
853 let line = range_line(style, field, held.text(), well);
854 text::draw_line(&line, below(area, used), buf)
855 }
856 // One question, so one line. The two ends read left to right with the
857 // word between them, which is what a terminal has instead of two boxes
858 // side by side: a second row would read as a second question, and that
859 // is the reading the kind exists to prevent.
860 FieldKind::Interval => {
861 let line = interval_line(style, field, held, well);
862 text::draw_line(&line, below(area, used), buf)
863 }
864 // The grouping comes out of the order, not out of a group list:
865 // `Field::themes` arrives sorted by variant, so the run of one variant
866 // is the group and a heading opens whenever the variant changes. Same
867 // walk the other two renderers do, which is what keeps three renderers
868 // from disagreeing about where a group starts.
869 //
870 // Drawn as the radio group above rather than as a closed control,
871 // because a terminal has no closed control: the list is already on
872 // screen and always was, so the group headings cost a row each and buy
873 // the structure the description finally carries.
874 kind if kind.offers_themes() => {
875 let mut rows = 0;
876 if let Some(follow) = field.follows {
877 // First, and under no heading. It names no theme and sits in no
878 // variant, so a heading over it would be inventing a fourth
879 // variant for one row.
880 let chosen = held.text() == follow.value;
881 let (mark, painted) = if chosen {
882 ("(*)", well)
883 } else {
884 ("( )", style.secondary)
885 };
886 rows += text::draw(
887 &format!("{mark} {}", follow.label),
888 painted,
889 below(area, used + rows),
890 buf,
891 );
892 }
893 let mut open: Option<ThemeVariant> = None;
894 for theme in field.themes {
895 if open != Some(theme.variant) {
896 // Muted, which is the one place it is the truth rather than
897 // the lie: a heading will not answer, exactly as an
898 // unavailable option will not.
899 rows += text::draw(
900 theme.variant.heading(),
901 style.muted,
902 below(area, used + rows),
903 buf,
904 );
905 open = Some(theme.variant);
906 }
907 let chosen = held.text() == theme.id;
908 let (mark, painted) = if chosen {
909 ("(*)", well)
910 } else {
911 ("( )", style.secondary)
912 };
913 rows += text::draw(
914 &format!("{mark} {} [{}]", theme.name, theme.contrast.badge()),
915 painted,
916 below(area, used + rows),
917 buf,
918 );
919 }
920 rows
921 }
922 kind if kind.offers_options() => {
923 // A checklist's answer is a set, so its options mark themselves
924 // with `Choice::chosen` and no one held value names any of them. A
925 // single answer is marked either way, which is `chosen`'s rule for
926 // every renderer. The box says which of the two the question is.
927 let several = kind.takes_several();
928 let (open, ticked) = if several {
929 ("[ ]", "[x]")
930 } else {
931 ("( )", "(*)")
932 };
933 let walking = focused && cursor.is_some();
934 let marked = if walking { style.content } else { well };
935 let mut rows = 0;
936 for (index, choice) in field.options.iter().enumerate() {
937 let chosen = choice.chosen || (!several && held.text() == choice.value);
938 let walked = walking && cursor == Some(index);
939 // An option that cannot be picked yet reads as inert, which is
940 // the one place muted is the truth rather than the lie below:
941 // it will not answer, and the reason it will not is on the row
942 // beside it rather than nowhere.
943 let (mark, painted, suffix) = match choice.unavailable {
944 Some(reason) => (open, style.muted, format!(": {reason}")),
945 None if chosen => (ticked, marked, String::new()),
946 // An option that is not chosen is still an option: pressing
947 // it chooses it. So it takes the secondary content intent
948 // and not the muted one, which is what disabled looks like
949 // (`State::Disabled` resolves to it). Muted here read as a
950 // list of five where four were greyed out.
951 None => (open, style.secondary, String::new()),
952 };
953 // The row the caret is on takes the focus mark, so the key that
954 // ticks or picks lands on a row the reader can see.
955 rows += text::draw(
956 &format!("{mark} {}{suffix}", choice.label),
957 style.focused(walked, painted),
958 below(area, used + rows),
959 buf,
960 );
961 // What picking it means, on a row of its own under the option.
962 // makeover-layout 0.39.0, and this is the host with the most
963 // room of the three: a browser's `<select>` has to run the line
964 // into the option's text and a terminal does not, so it does
965 // not.
966 //
967 // Indented past the mark, so the line reads as belonging to the
968 // option above it rather than as another option. Muted, which
969 // is the truth here rather than the lie the arms above are
970 // careful about: the row is not a thing to press.
971 if let Some(detail) = choice.detail {
972 rows += text::draw(detail, style.muted, indented(area, used + rows), buf);
973 }
974 }
975 rows
976 }
977 // A secret's dots come from the caller's buffer and can come from
978 // nowhere else: a password that comes back down the wire is a password
979 // in a page and in a proxy log, so a description carries nothing to dot
980 // out. This is the one control that would be undrawable without `held`.
981 FieldKind::Secret if !held.text().is_empty() => {
982 let dots = "*".repeat(held.text().chars().count());
983 text::draw(&dots, well, below(area, used), buf).max(1)
984 }
985 // A file field has no way back on a terminal any more than it has on an
986 // HTTP host. The name is drawn and picking one belongs to whoever owns
987 // the interaction.
988 //
989 // makeover-layout 0.31.0 gave the description an accept list and a
990 // multiplicity, and neither changes anything drawn here. Both are the
991 // picker's business, and the picker is the caller's: this crate draws
992 // what was picked. A terminal that grows its own picker reads them off
993 // `Field::accept` and `Field::multiple` at that point rather than
994 // through a second spelling invented here.
995 _ if held.text().is_empty() => {
996 empty_well(style, placeholder, well, focused, below(area, used), buf)
997 }
998 _ => text::draw(&measured(field, held.text()), well, below(area, used), buf),
999 };
1000
1001 // Error, then note, then hint -- the order `Field::note` names, and the
1002 // order a webview draws them in. Once something has gone wrong that is the
1003 // sentence worth the row; failing that, what the chosen answer costs beats
1004 // standing help about how the field works.
1005 match message_of(style, field) {
1006 Some((text, painted)) => used + text::draw(text, painted, below(area, used), buf),
1007 None => used,
1008 }
1009}
1010
1011/// A bounded number as one line: the low end, the bar, the high end, then what
1012/// it currently reads.
1013///
1014/// The two ends are drawn because they are the question. A threshold of 0.72
1015/// says nothing without them, which is the whole argument for
1016/// [`FieldKind::Range`] being a kind rather than a number with bounds, and a
1017/// terminal is where it would be easiest to quietly drop them and show a figure.
1018///
1019/// The bar is [`meter`]'s cells, so a range and a proportion read as the same
1020/// object in the same app. What differs is the reading beside it: a meter counts
1021/// something and a range holds a value.
1022///
1023/// A value the host cannot read as a number empties the bar and is still shown
1024/// as itself. That is [`empty_well`]'s position on an unreadable value: the app
1025/// put it there, and a terminal that silently rounded it to a bound would be
1026/// reporting a value nobody set.
1027fn range_line(style: &PieceStyle, field: &Field<'_>, value: &str, well: Style) -> Line<'static> {
1028 let cells = usize::from(style.meter_cells);
1029 let ends = field
1030 .min
1031 .zip(field.max)
1032 .and_then(|(min, max)| Some((min.parse::<f64>().ok()?, max.parse::<f64>().ok()?)));
1033 let filled = match (ends, value.parse::<f64>()) {
1034 (Some((min, max)), Ok(number)) if max > min => {
1035 // Where the value sits is the curve's answer, not a proportion of
1036 // the extent (makeover-layout 0.32.0). Under `Curve::Linear` the two
1037 // are the same number, which is why the bar was right before and is
1038 // unchanged for every range described so far; under a constant ratio
1039 // they are not, and a bar drawn linearly would put an envelope's
1040 // whole useful half inside its first cell.
1041 #[expect(
1042 clippy::cast_possible_truncation,
1043 clippy::cast_sign_loss,
1044 reason = "`position_of` returns 0..=1, and the cell count came from a u16"
1045 )]
1046 let reached = (field.curve.position_of(number, min, max) * cells as f64) as usize;
1047 reached.min(cells)
1048 }
1049 _ => 0,
1050 };
1051 let bar = format!(
1052 "{}{}",
1053 style.meter_full.to_string().repeat(filled),
1054 style.meter_empty.to_string().repeat(cells - filled)
1055 );
1056 Line::from(vec![
1057 Span::styled(format!("{} ", field.min.unwrap_or_default()), style.muted),
1058 Span::styled(bar, well),
1059 Span::styled(format!(" {}", field.max.unwrap_or_default()), style.muted),
1060 Span::styled(format!(" {}", measured(field, value)), well),
1061 ])
1062}
1063
1064/// An interval as one line: the low end, the word, the high end.
1065///
1066/// One line because it is one question. Two rows would read as two questions,
1067/// which is exactly what [`FieldKind::Interval`] exists to stop the description
1068/// saying, and a terminal has no side-by-side boxes to fall back on.
1069///
1070/// # An open end draws the bound it falls back to
1071///
1072/// Muted, because it is where the axis ends rather than a value anybody set.
1073/// With no bound to fall back on there is nothing honest to draw and the end
1074/// stays blank: a terminal inventing a number here would report a filter the
1075/// user never applied, which is [`range_line`]'s position on an unreadable
1076/// value.
1077///
1078/// # The word, not a dash
1079///
1080/// A dash between two numbers is a minus sign to anyone reading a signed axis,
1081/// and half the measured axes are signed -- audiofiles filters loudness in
1082/// dBFS. `to` costs two cells and cannot be misread.
1083fn interval_line(
1084 style: &PieceStyle,
1085 field: &Field<'_>,
1086 held: Held<'_>,
1087 well: Style,
1088) -> Line<'static> {
1089 let end = |value: &str, fallback: Option<&str>| match (value.is_empty(), fallback) {
1090 (false, _) => Span::styled(measured(field, value), well),
1091 (true, Some(bound)) => Span::styled(measured(field, bound), style.muted),
1092 (true, None) => Span::styled(String::new(), style.muted),
1093 };
1094 Line::from(vec![
1095 end(held.text(), field.min),
1096 Span::styled(" to ", style.secondary),
1097 end(held.upper(), field.max),
1098 ])
1099}
1100
1101/// The unit to draw beside this field's value, if there is one to draw.
1102///
1103/// Two conditions rather than one: the field has to carry a unit and its kind
1104/// has to be one that means anything by it. `FieldKind::measurable` is the
1105/// description answering the second, so this renderer keeps no list of its own
1106/// of which kinds are quantities.
1107fn unit_of<'a>(field: &Field<'a>) -> Option<&'a str> {
1108 field.unit.filter(|_| field.kind.measurable())
1109}
1110
1111/// A value with what it is measured in, as one string.
1112///
1113/// The unit rides on the value rather than on the label, which is what a
1114/// terminal wants: the label is a line above and the number is the line the eye
1115/// is on.
1116fn measured(field: &Field<'_>, value: &str) -> String {
1117 match unit_of(field) {
1118 Some(unit) => format!("{value} {unit}"),
1119 None => value.to_owned(),
1120 }
1121}
1122
1123/// The label, marked where the field is compulsory.
1124fn label_of(style: &PieceStyle, field: &Field<'_>) -> String {
1125 if field.required {
1126 format!("{} {}", field.label, style.required_marker)
1127 } else {
1128 field.label.to_owned()
1129 }
1130}
1131
1132/// What goes under the box, and how it is painted.
1133///
1134/// A terminal field has room for exactly one line, so the three message
1135/// channels compete for it and the precedence is decided in
1136/// [`makeover_layout::Field::note`]'s docs rather than three times here:
1137/// **error, then note, then hint**. What is wrong outranks what the answer
1138/// costs, which outranks how the field works.
1139///
1140/// The tone comes with the note; an error is always danger and a hint is
1141/// always muted, because neither carries one.
1142fn message_of<'a>(style: &PieceStyle, field: &Field<'a>) -> Option<(&'a str, Style)> {
1143 if let Some(error) = field.error {
1144 return Some((error, style.danger));
1145 }
1146 if let Some((tone, note)) = field.note {
1147 return Some((note, style.tone(tone)));
1148 }
1149 field.hint.map(|hint| (hint, style.muted))
1150}
1151
1152/// A box with nothing in it: the ghost text, and the caret when it has focus.
1153///
1154/// The caret is not decoration. An empty field under a style is an empty field,
1155/// so a focused one with no placeholder drew literally nothing and there was no
1156/// way to tell the box was where the typing would go. A browser has a blinking
1157/// bar for this and gets it without asking; a terminal has one cell of reversed
1158/// video, put on the first column, which is where the first character lands.
1159fn empty_well(
1160 style: &PieceStyle,
1161 placeholder: &str,
1162 well: Style,
1163 focused: bool,
1164 area: Rect,
1165 buf: &mut Buffer,
1166) -> u16 {
1167 let used = text::draw(placeholder, style.muted, area, buf).max(1);
1168 if focused
1169 && area.height > 0
1170 && area.width > 0
1171 && let Some(cell) = buf.cell_mut((area.x, area.y))
1172 {
1173 cell.set_style(well);
1174 }
1175 used
1176}
1177
1178/// What is left of `area` after `used` rows from the top.
1179/// The rows under what has been drawn, inset by the width of an option's mark.
1180///
1181/// An option's second line has to read as belonging to the option above it rather than as another option, and the only thing that
1182/// says so on a terminal is where it starts. The inset is `text::draw`'s to
1183/// honour as an area rather than as spaces in the string: the drawing wraps on
1184/// words, so leading spaces would survive the first line and vanish from every
1185/// one after it.
1186///
1187/// Four columns, which is `"( ) "`. Named against the mark rather than picked,
1188/// so a mark that changes width takes this with it.
1189fn indented(area: Rect, used: u16) -> Rect {
1190 const MARK: u16 = 4;
1191 let area = below(area, used);
1192 Rect {
1193 x: area.x + MARK.min(area.width),
1194 width: area.width.saturating_sub(MARK),
1195 ..area
1196 }
1197}
1198
1199fn below(area: Rect, used: u16) -> Rect {
1200 let used = used.min(area.height);
1201 Rect {
1202 x: area.x,
1203 y: area.y + used,
1204 width: area.width,
1205 height: area.height - used,
1206 }
1207}
1208
1209#[cfg(test)]
1210mod tests;
1211
1212/// A chart, one line per bar.
1213///
1214/// # Why the bars lie down here
1215///
1216/// A webview draws a chart as columns standing on an axis, and a terminal has
1217/// one glyph per cell and a handful of rows. Standing the bars up would mean
1218/// drawing each one as a stack of partial blocks and giving up the labels,
1219/// which are the half a reader actually reads. Laid down, every bar keeps its
1220/// place on the axis, its magnitude and its reading, and the drawing is
1221/// [`meter`]'s repeated -- which is the honest answer for the same reason
1222/// `quasi-tui`'s timeline draws no gridlines: a terminal draws what a terminal
1223/// draws rather than an impression of the other renderer.
1224///
1225/// The axis is not drawn as a rule or a scale, for that same reason. It is
1226/// stated instead: every bar is `meter_cells` wide and full means
1227/// [`Chart::most`], so the widths are comparable across the run, which is the
1228/// one thing a chart has to get right.
1229///
1230/// # What is left out
1231///
1232/// [`Chart::label`] is not drawn. It names what the magnitudes are and every
1233/// bar's own [`Bar::reading`] already carries the units, so drawing it would be
1234/// a heading this function does not own the room for. A caller that wants it
1235/// says it as a heading, which is what a description does anyway.
1236///
1237/// Labels are padded to the widest, in cells, so the bars line up.
1238#[must_use]
1239pub fn chart(style: &PieceStyle, chart: &Chart<'_>, bars: &[Bar<'_>]) -> Vec<Line<'static>> {
1240 let widest = bars
1241 .iter()
1242 .map(|bar| text::cells(bar.at))
1243 .max()
1244 .unwrap_or(0);
1245 bars.iter()
1246 .map(|bar| chart_line(style, chart, bar, widest))
1247 .collect()
1248}
1249
1250/// One bar's line: where it sits, how far it reaches, and what it says.
1251fn chart_line(
1252 style: &PieceStyle,
1253 chart: &Chart<'_>,
1254 bar: &Bar<'_>,
1255 widest: usize,
1256) -> Line<'static> {
1257 let cells = usize::from(style.meter_cells);
1258 // Rounded rather than truncated, so a bar that is nearly full does not read
1259 // as one cell short of every other. The multiplication is done before the
1260 // division for the reason it is in `meter`: in integers, the other order is
1261 // zero.
1262 let filled = if chart.most == 0 {
1263 0
1264 } else {
1265 let scaled = (bar.value as u128 * cells as u128).div_ceil(chart.most as u128);
1266 (scaled as usize).min(cells)
1267 };
1268
1269 let mut spans = vec![Span::styled(
1270 format!(
1271 "{}{} ",
1272 bar.at,
1273 " ".repeat(widest.saturating_sub(text::cells(bar.at)))
1274 ),
1275 style.secondary,
1276 )];
1277 spans.push(Span::styled(
1278 format!(
1279 "{}{}",
1280 style.meter_full.to_string().repeat(filled),
1281 style.meter_empty.to_string().repeat(cells - filled)
1282 ),
1283 style.tone(chart.tone),
1284 ));
1285 if let Some(reading) = chart_reading(bar) {
1286 spans.push(Span::styled(reading, style.muted));
1287 }
1288 Line::from(spans)
1289}
1290
1291/// What a bar says beside its own drawing, or nothing.
1292///
1293/// The webview's `bar_text` in this renderer's spelling. Both facts joined the
1294/// same way, and both left out when the description carried neither.
1295fn chart_reading(bar: &Bar<'_>) -> Option<String> {
1296 match (bar.reading, bar.note) {
1297 (Some(reading), Some(note)) => Some(format!(" {reading} / {note}")),
1298 (Some(only), None) | (None, Some(only)) => Some(format!(" {only}")),
1299 (None, None) => None,
1300 }
1301}