Skip to main content

max / makeover-tui

65.1 KB · 1679 lines History Blame Raw
1 //! The pieces every terminal app draws, drawn once.
2 //!
3 //! # Called `widget` until 0.19.0
4 //!
5 //! Renamed because `makeover-layout` 0.20.0 took the word for something else,
6 //! and the two meanings do not sit together. A `Region::Widget` there is
7 //! host-agnostic: a named assembly of primitives that every renderer draws its
8 //! own way. What is in this module is the opposite end — renderer-local, the
9 //! answer to *what a meter looks like in cells*, taking a description plus what
10 //! only a terminal knows.
11 //!
12 //! One word for both would have made the tier unreadable in the crate that
13 //! implements it. This half moved because the other half is the ecosystem-facing
14 //! one: a second or third party naming a widget is naming the layout kind, and
15 //! nothing outside this tree ever needed a word for a drawing routine.
16 //!
17 //! `WidgetStyle` went with it and is `PieceStyle`.
18 //!
19 //! Arrived in 0.16.0 out of `quasi-tui`, which had written all of them and was
20 //! the second consumer to do so. A meter, a badge, a control, a figure and a
21 //! form field are what a screen is made of below the level [`table`](crate::table)
22 //! works at, and every one of them had been hand-rolled at least twice in this
23 //! tree before it was lifted.
24 //!
25 //! [`activity`] and [`awaiting`] joined them in 0.35.0, out of wiki
26 //! `loading-and-progress-standard`. They are the one pair here that arrived
27 //! before their second consumer rather than after it: nothing in the tree drew
28 //! a wait at all, on any surface, which is why the crate that had the vocabulary
29 //! for one had never been asked for the drawing.
30 //!
31 //! # What these take, and what they leave alone
32 //!
33 //! Each takes a `makeover-layout` description, a [`PieceStyle`], and whatever
34 //! the *host* knows that a description never carries. That last part is the
35 //! shape worth copying: [`field`] takes what is currently typed in the box as a
36 //! separate argument, because [`Field`] deliberately does not carry a value and
37 //! is not going to. `makeover-immediate` reached the same seam from the other
38 //! side with its `Filling`, and [`Held`] is that seam here.
39 //!
40 //! Focus is the other one. Nothing in a description says which control the user
41 //! is on, so every drawing here takes `focused` as an argument and the caller
42 //! is what counts. What focus *looks like* is this crate's answer and not the
43 //! caller's, which is the point of it being here: see
44 //! [`PieceStyle::focused`].
45 //!
46 //! # What they do not do
47 //!
48 //! No layout. Each answers rows for a width, or draws into the rect it is
49 //! given, top-aligned, and never below it. Nothing here measures twice and
50 //! nothing here places anything relative to anything else, because the moment
51 //! it did it would be a layout engine with one consumer's flow baked into it.
52
53 use makeover_layout::{
54 Act, Awaiting, Field, FieldKind, Figure, Heading, Meter, ThemeVariant, Token, Tone,
55 };
56 use ratatui::buffer::Buffer;
57 use ratatui::layout::Rect;
58 use ratatui::style::{Modifier, Style};
59 use ratatui::text::{Line, Span};
60
61 use crate::text;
62 use std::time::Duration;
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)]
79 pub 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 /// What "you are on this one" adds to whatever it lands on.
110 ///
111 /// Reversed video by default, which is the affordance a cell has left once
112 /// colour is spent on tone and bold on weight. A webview says it with an
113 /// outline; a terminal has no outline that is not four more cells.
114 pub focus: Modifier,
115 /// How many cells [`meter`] spends on its bar.
116 pub meter_cells: u16,
117 /// The filled part of a bar.
118 pub meter_full: char,
119 /// The empty part of a bar.
120 pub meter_empty: char,
121 /// What marks a compulsory field, appended to its label.
122 ///
123 /// A knob for `makeover-immediate`'s reason: it is the one piece of *copy*
124 /// here, and copy is not a renderer's call.
125 pub required_marker: &'static str,
126 }
127
128 impl Default for PieceStyle {
129 /// Modifiers only, no foreground: what survives a terminal with two
130 /// colours.
131 fn default() -> Self {
132 Self {
133 content: Style::new(),
134 secondary: Style::new(),
135 muted: Style::new().add_modifier(Modifier::DIM),
136 info: Style::new(),
137 success: Style::new(),
138 warning: Style::new(),
139 danger: Style::new().add_modifier(Modifier::BOLD),
140 page: Style::new().add_modifier(Modifier::BOLD),
141 section: Style::new().add_modifier(Modifier::BOLD),
142 subsection: Style::new(),
143 action: Style::new().add_modifier(Modifier::UNDERLINED),
144 filled: Style::new().add_modifier(Modifier::REVERSED),
145 sunken: Style::new().add_modifier(Modifier::DIM),
146 focus: Modifier::REVERSED,
147 meter_cells: 10,
148 meter_full: '#',
149 meter_empty: '-',
150 required_marker: "*",
151 }
152 }
153 }
154
155 impl PieceStyle {
156 /// The house widgets, from a loaded theme.
157 ///
158 /// The lift this module exists for. `quasi-tui` carried every line of this
159 /// as private methods on its own renderer; a second terminal app wanting a
160 /// toned control had no way to reach them and would have picked its own
161 /// colours for the same five tones.
162 #[cfg(feature = "theme")]
163 #[must_use]
164 pub fn from_theme(theme: &crate::Theme) -> Self {
165 Self {
166 content: Style::new().fg(theme.content_primary),
167 secondary: Style::new().fg(theme.content_secondary),
168 muted: Style::new().fg(theme.content_muted),
169 info: Style::new().fg(theme.status_info),
170 success: Style::new().fg(theme.status_success),
171 warning: Style::new().fg(theme.status_warning),
172 danger: Style::new().fg(theme.status_danger),
173 // Three depths and two of them are bold, which is the whole of what
174 // a terminal has: there is no type scale in a grid of one cell
175 // size. A page title takes bold and the accent, a section bold, a
176 // subsection the secondary colour. That is the emphasis order a
177 // webview's type scale says with size, said with the two axes a
178 // cell has.
179 page: Style::new()
180 .fg(theme.action_primary)
181 .add_modifier(Modifier::BOLD),
182 section: Style::new()
183 .fg(theme.content_primary)
184 .add_modifier(Modifier::BOLD),
185 subsection: Style::new().fg(theme.content_secondary),
186 action: Style::new().fg(theme.action_primary),
187 filled: Style::new().fg(theme.selection_on).bg(theme.action_primary),
188 sunken: Style::new().bg(theme.surface_sunken),
189 focus: Modifier::REVERSED,
190 meter_cells: 10,
191 meter_full: '#',
192 meter_empty: '-',
193 required_marker: "*",
194 }
195 }
196
197 /// The style a tone reads as.
198 ///
199 /// [`Tone`] is closed and stays closed, so this is total and needs no
200 /// fallback arm.
201 #[must_use]
202 pub const fn tone(&self, tone: Tone) -> Style {
203 match tone {
204 Tone::Neutral => self.content,
205 Tone::Info => self.info,
206 Tone::Success => self.success,
207 Tone::Warning => self.warning,
208 Tone::Danger => self.danger,
209 }
210 }
211
212 /// The style a heading reads as.
213 #[must_use]
214 pub const fn heading(&self, level: Heading) -> Style {
215 match level {
216 Heading::Page => self.page,
217 Heading::Section => self.section,
218 Heading::Subsection => self.subsection,
219 }
220 }
221
222 /// `style`, plus the mark that says the user is on this one.
223 ///
224 /// Takes the flag rather than being called behind an `if`, because every
225 /// caller has a bool in hand and the branch is the part that gets forgotten.
226 #[must_use]
227 pub fn focused(&self, focused: bool, style: Style) -> Style {
228 if focused {
229 style.add_modifier(self.focus)
230 } else {
231 style
232 }
233 }
234 }
235
236 /// What a field currently holds, which a description never carries.
237 ///
238 /// The terminal counterpart of `makeover_immediate::Filling`, and the same seam:
239 /// there the widget writes through a `&mut` as the value is edited, and here the
240 /// caller keeps an edit buffer and lends it out for the draw. Neither is
241 /// something [`Field`] could carry without becoming a form model.
242 ///
243 /// An enum rather than a bag of options, for `Filling`'s reason: a checkbox
244 /// holding a string is unsayable here, where a struct would let it be said and
245 /// then have to cope.
246 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
247 pub enum Held<'a> {
248 /// Nothing typed and nothing chosen. The control draws empty.
249 #[default]
250 Absent,
251 /// What is in the box, or the `value` of the chosen [`Choice`].
252 ///
253 /// [`Choice`]: makeover_layout::Choice
254 Text(&'a str),
255 /// A checkbox, on or off.
256 On(bool),
257 /// Both ends of a [`FieldKind::Interval`], lower first.
258 ///
259 /// Two values rather than one string with a separator, which is
260 /// [`makeover_layout::Field::upper_name`]'s reason one level down: an
261 /// interval is submitted under two names, so it is held as two values, and
262 /// a delimiter this crate owned could appear inside either of them.
263 ///
264 /// Either end may be empty while the other stands. An open end is an
265 /// answer -- "over 120 BPM" -- rather than a half-filled box.
266 ///
267 /// Added 0.33.0 with makeover-layout 0.34.0.
268 Between {
269 /// What the lower box holds now.
270 lower: &'a str,
271 /// What the upper box holds now.
272 upper: &'a str,
273 },
274 }
275
276 impl<'a> Held<'a> {
277 /// What is typed, as a string. A checkbox has no text and answers empty.
278 #[must_use]
279 pub const fn text(self) -> &'a str {
280 match self {
281 Self::Text(text) | Self::Between { lower: text, .. } => text,
282 Self::Absent | Self::On(_) => "",
283 }
284 }
285
286 /// The upper end, for the one variant that has one.
287 #[must_use]
288 pub const fn upper(self) -> &'a str {
289 match self {
290 Self::Between { upper, .. } => upper,
291 Self::Absent | Self::Text(_) | Self::On(_) => "",
292 }
293 }
294
295 /// Whether a checkbox is ticked.
296 #[must_use]
297 pub const fn on(self) -> bool {
298 matches!(self, Self::On(true))
299 }
300 }
301
302 /// What a host can see about a wait that is running.
303 ///
304 /// Neither half is derivable from a description, which is why both are here and
305 /// not on [`Awaiting`]. That type says how big the payload is; how much of it
306 /// has landed is a fact about a transfer in flight, and only whoever is running
307 /// the transfer knows it.
308 ///
309 /// The same shape `makeover-immediate` carries, deliberately: a wait is one
310 /// reading on every surface and the two renderers should not disagree about
311 /// what a host owes them.
312 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
313 pub struct Progress {
314 /// How much has arrived, in whatever unit the description counted.
315 pub delivered: Option<u64>,
316 /// How long the wait has lasted so far.
317 ///
318 /// The one time value a wait may show. See [`awaiting`] for the three it
319 /// may not.
320 pub elapsed: Option<Duration>,
321 }
322
323 /// The activity mark: one cell, lit or dark.
324 ///
325 /// Rule 2 of wiki `loading-and-progress-standard`, and the surface the metaphor
326 /// came from. A hard-disk light is one cell that blinks, and a terminal draws
327 /// that with no metaphor in the way — where a webview needs a keyframe and egui
328 /// needs a repaint schedule, this is a character.
329 ///
330 /// The two glyphs are [`PieceStyle::meter_full`] and
331 /// [`PieceStyle::meter_empty`], not a third pair. A bar's filled cell and a lit
332 /// mark are the same statement in the same alphabet, and a terminal that had to
333 /// render two vocabularies of "on" would be saying there are two kinds of on.
334 ///
335 /// **Dark, not absent.** A mark that is drawn half the time is a hole in the
336 /// line, and the line reflows around it or the reader loses where to look. It
337 /// occupies its cell either way.
338 ///
339 /// `lit` is the caller's: this module holds no clock. [`crate::activity_lit`]
340 /// is the one place the phase is worked out from the cadence, so a caller
341 /// should reach for that rather than dividing by 500 itself.
342 #[must_use]
343 pub fn activity(style: &PieceStyle, lit: bool) -> Span<'static> {
344 if lit {
345 Span::styled(style.meter_full.to_string(), style.action)
346 } else {
347 Span::styled(style.meter_empty.to_string(), style.muted)
348 }
349 }
350
351 /// A wait as one line, drawn from what is actually known about it.
352 ///
353 /// [`Awaiting::is_determinate`] is the first branch and there is a second the
354 /// description cannot answer: whether anything is watching the transfer. A bar
355 /// wants a total and a numerator both, so a described amount with no
356 /// [`Progress::delivered`] beside it draws the mark and the size it is waiting
357 /// on, rather than an empty trough implying somebody is counting.
358 ///
359 /// So three drawings for three states, which is the point:
360 ///
361 /// ```text
362 /// unmeasured # a blinking cell
363 /// measured, nothing watching # 41943040 the cell, and how much there is
364 /// measured and observed ####------ 17825792/41943040 4s
365 /// ```
366 ///
367 /// **What the bar may not do**, from rule 1 of the standard and from
368 /// [`Awaiting`]'s own docs: what is done over what there is, plus the time it
369 /// has taken. Never a remaining time, an arrival time, or a rate extrapolated
370 /// forward. A prediction is wrong the moment the transfer stalls, and being
371 /// confidently wrong is worse than being honestly indeterminate.
372 ///
373 /// The numbers are raw. The unit is the app's — bytes for an upload, rows for
374 /// an import — and a renderer that formatted one as a file size would be
375 /// dressing up a quantity it was deliberately not told about.
376 #[must_use]
377 pub fn awaiting(
378 style: &PieceStyle,
379 awaiting: Awaiting,
380 progress: Progress,
381 lit: bool,
382 ) -> Line<'static> {
383 let Some(total) = awaiting.amount else {
384 return Line::from(vec![activity(style, lit)]);
385 };
386 let Some(done) = progress.delivered else {
387 return Line::from(vec![
388 activity(style, lit),
389 Span::styled(format!(" {total}"), style.muted),
390 ]);
391 };
392 let cells = u32::from(style.meter_cells);
393 // In cells rather than in floating point, the way `meter` does it: a
394 // terminal's bar has ten states and rounding through an f64 to reach one of
395 // ten is arithmetic nobody needs. Saturating rather than wrapping, because
396 // a transfer that over-delivers is a real case and a panicking bar is not
397 // the way to report it.
398 let filled = u32::try_from(
399 done.saturating_mul(u64::from(cells))
400 .checked_div(total)
401 .unwrap_or(0),
402 )
403 .unwrap_or(cells)
404 .min(cells);
405 let bar = format!(
406 "{}{}",
407 style.meter_full.to_string().repeat(filled as usize),
408 style
409 .meter_empty
410 .to_string()
411 .repeat((cells - filled) as usize)
412 );
413 let reading = match progress.elapsed {
414 Some(elapsed) => format!(" {done}/{total} {}s", elapsed.as_secs()),
415 None => format!(" {done}/{total}"),
416 };
417 Line::from(vec![
418 Span::styled(bar, style.action),
419 Span::styled(reading, style.muted),
420 ])
421 }
422
423 /// A proportion as one line: the bar, then the reading beside it.
424 ///
425 /// The reading is built here from the two numbers and the noun rather than
426 /// taken assembled, which is what [`Meter::label`] carrying the noun alone is
427 /// for: a terminal at one line and a tooltip want different sentence orders.
428 #[must_use]
429 pub fn meter(style: &PieceStyle, meter: &Meter<'_>) -> Line<'static> {
430 let cells = u32::from(style.meter_cells);
431 let filled = meter
432 .done
433 .checked_mul(cells)
434 .and_then(|reached| reached.checked_div(meter.total))
435 .unwrap_or(0)
436 .min(cells);
437 let bar = format!(
438 "{}{}",
439 style.meter_full.to_string().repeat(filled as usize),
440 style
441 .meter_empty
442 .to_string()
443 .repeat((cells - filled) as usize)
444 );
445 let reading = match meter.label {
446 Some(label) => format!(" {}/{} {label}", meter.done, meter.total),
447 None => format!(" {}/{}", meter.done, meter.total),
448 };
449 Line::from(vec![
450 Span::styled(bar, style.tone(meter.tone)),
451 Span::styled(reading, style.muted),
452 ])
453 }
454
455 /// A badge or a chip as one span.
456 ///
457 /// Round for a badge, square for a chip. A chip answers a press and a badge does
458 /// not, and the bracket is the only affordance a cell has left once colour is
459 /// spent on the tone.
460 ///
461 /// `latched` is a chip that is switched on, and it reads as reversed. So does
462 /// focus, which is a collision a terminal cannot avoid: latched is "this filter
463 /// is on" and focused is "you are here", and there is one spare axis for two
464 /// facts. Said here rather than resolved by inventing a third look nobody would
465 /// read.
466 ///
467 /// A chip's removable half is not drawn. The `x` a webview hangs on a chip is a
468 /// second control inside one span, and a terminal reaches a control by focusing
469 /// it; two targets in one cell run is a question for whoever owns the
470 /// interaction, not for a drawing.
471 #[must_use]
472 pub fn token(
473 style: &PieceStyle,
474 label: &str,
475 kind: Token,
476 tone: Tone,
477 latched: bool,
478 focused: bool,
479 ) -> Span<'static> {
480 let painted = style.tone(tone);
481 let painted = if latched {
482 painted.add_modifier(style.focus)
483 } else {
484 style.focused(focused, painted)
485 };
486 match kind {
487 Token::Badge => Span::styled(format!("({label})"), painted),
488 Token::Chip { .. } => Span::styled(format!("[{label}]"), painted),
489 }
490 }
491
492 /// A control as one line.
493 ///
494 /// `< Label > (key)`, and the key only where the description named one. That
495 /// member is the one place `makeover-layout` anticipated a terminal before there
496 /// was one, and this is the renderer that reads it.
497 ///
498 /// A disabled control is drawn muted and is not marked focused, whatever the
499 /// caller passed: it is present, visible and not answering, so a focus mark on
500 /// it would be an affordance that lies. Whether it is reachable at all is the
501 /// caller's count to keep — ask [`Act::disabled`].
502 #[must_use]
503 pub fn act(style: &PieceStyle, act: &Act<'_>, focused: bool) -> Line<'static> {
504 let painted = if act.disabled() {
505 style.muted
506 } else {
507 style.focused(focused, style.tone(act.tone))
508 };
509 let label = match act.key {
510 Some(key) => format!("< {} > ({key})", act.label),
511 None => format!("< {} >", act.label),
512 };
513 Line::from(Span::styled(label, painted))
514 }
515
516 /// A control filled with the action colour, for the one press a screen is about.
517 ///
518 /// `[ Label ]` rather than `< Label >`, which is the weight difference a webview
519 /// carries as a primary-versus-secondary button. A form's submit is the case
520 /// this exists for.
521 #[must_use]
522 pub fn filled_act(style: &PieceStyle, label: &str, focused: bool) -> Line<'static> {
523 Line::from(Span::styled(
524 format!("[ {label} ]"),
525 style.focused(focused, style.filled),
526 ))
527 }
528
529 /// The rows [`figure`] wants at `width`.
530 #[must_use]
531 pub fn figure_height(figure: &Figure<'_>, width: u16) -> u16 {
532 text::height(figure.value, width) + text::height(figure.caption, width)
533 }
534
535 /// A figure: the number, then what it counts under it.
536 ///
537 /// The tone lands on the value and its change rather than on the caption, which
538 /// is what [`Figure::tone`] means: the figure is an ordinary fact and it is the
539 /// movement that reads as good or bad.
540 pub fn figure(style: &PieceStyle, figure: &Figure<'_>, area: Rect, buf: &mut Buffer) -> u16 {
541 let value = match figure.change {
542 Some(change) => format!("{} {change}", figure.value),
543 None => figure.value.to_owned(),
544 };
545 let used = text::draw(
546 &value,
547 style.tone(figure.tone).add_modifier(Modifier::BOLD),
548 area,
549 buf,
550 );
551 used + text::draw(figure.caption, style.muted, below(area, used), buf)
552 }
553
554 /// The rows [`field`] wants at `width`.
555 ///
556 /// A label row, the control's rows, and a row for whatever went wrong. A hidden
557 /// field is nothing at all, which is the one field kind a terminal and a webview
558 /// agree on completely.
559 #[must_use]
560 pub fn field_height(style: &PieceStyle, field: &Field<'_>, width: u16) -> u16 {
561 if !field.kind.visible() {
562 return 0;
563 }
564 let label = text::height(&label_of(style, field), width);
565 // A range is one row like every other single control: the bar, its two ends
566 // and the reading are one line by construction, and a bar that wrapped
567 // would stop being a bar.
568 let body = match field.kind {
569 // Both multi-line kinds get the same three rows, keyed on the
570 // description's own `multiline` rather than on the member: a markdown
571 // field falling through to the single-row arm is one line for a value
572 // whose whole point is that it has several. What a terminal does *with*
573 // the markdown is another question and the answer here is nothing --
574 // the source is the text, and drawing it as text is honest.
575 kind if kind.multiline() => 3,
576 kind if kind.offers_options() => u16::try_from(field.options.len()).unwrap_or(u16::MAX),
577 // A row per theme, a row per group heading, and a row for the follow
578 // entry when there is one. The headings are counted by walking the
579 // variants rather than by assuming three, because a machine with only
580 // dark themes installed draws one heading and reserving three would
581 // leave two blank rows under every picker.
582 kind if kind.offers_themes() => {
583 let mut variants = 0u16;
584 let mut open: Option<ThemeVariant> = None;
585 for theme in field.themes {
586 if open != Some(theme.variant) {
587 variants = variants.saturating_add(1);
588 open = Some(theme.variant);
589 }
590 }
591 let rows = u16::try_from(field.themes.len()).unwrap_or(u16::MAX);
592 rows.saturating_add(variants)
593 .saturating_add(u16::from(field.follows.is_some()))
594 }
595 _ => 1,
596 };
597 let note = message_of(style, field).map_or(0, |(text, _)| text::height(text, width));
598 label + body + note
599 }
600
601 /// A question: its label, the box, and its standing help or what is wrong now.
602 ///
603 /// `held` is what the user has done to it since the screen arrived, which is the
604 /// argument a description cannot supply. See [`Held`].
605 ///
606 /// `focused` marks the box rather than the label, because the box is where the
607 /// typing lands.
608 ///
609 /// [`makeover_layout::Field::as_instant`] is carried and not honoured. It asks
610 /// for a wall-clock value to be submitted as the moment it names, and this
611 /// renderer has no submission: it draws the box and the runtime above it
612 /// gathers what a submit sends, so the conversion belongs where that gathering
613 /// happens. The value drawn and read here is the local one, in
614 /// `makeover_layout::DATETIME_FORMAT`.
615 pub fn field(
616 style: &PieceStyle,
617 field: &Field<'_>,
618 held: Held<'_>,
619 focused: bool,
620 area: Rect,
621 buf: &mut Buffer,
622 ) -> u16 {
623 // A hidden field is data travelling with the form. There is nothing to
624 // draw, and whoever submits carries it.
625 if !field.kind.visible() || area.width == 0 || area.height == 0 {
626 return 0;
627 }
628
629 let mut used = text::draw(&label_of(style, field), style.secondary, area, buf);
630
631 let well = style.focused(focused, style.content);
632 let placeholder = field.placeholder.unwrap_or_default();
633
634 used += match field.kind {
635 FieldKind::Checkbox => text::draw(
636 if held.on() { "[x]" } else { "[ ]" },
637 well,
638 below(area, used),
639 buf,
640 ),
641 // A range's two ends are what the question means, so they are drawn
642 // rather than left to a hint. A terminal has the bar already: this is
643 // `meter`'s cells with the extent read out at either side of them.
644 //
645 // An unbounded range has no extent to draw and falls through to the
646 // text path, which is `makeover-immediate`'s answer as well and for the
647 // same reason: bounds this crate invented are bounds the user would
648 // then drag against.
649 FieldKind::Range if field.bounded() => {
650 let line = range_line(style, field, held.text(), well);
651 text::draw_line(&line, below(area, used), buf)
652 }
653 // One question, so one line. The two ends read left to right with the
654 // word between them, which is what a terminal has instead of two boxes
655 // side by side: a second row would read as a second question, and that
656 // is the reading the kind exists to prevent.
657 FieldKind::Interval => {
658 let line = interval_line(style, field, held, well);
659 text::draw_line(&line, below(area, used), buf)
660 }
661 // The grouping comes out of the order, not out of a group list:
662 // `Field::themes` arrives sorted by variant, so the run of one variant
663 // is the group and a heading opens whenever the variant changes. Same
664 // walk the other two renderers do, which is what keeps three renderers
665 // from disagreeing about where a group starts.
666 //
667 // Drawn as the radio group above rather than as a closed control,
668 // because a terminal has no closed control: the list is already on
669 // screen and always was, so the group headings cost a row each and buy
670 // the structure the description finally carries.
671 kind if kind.offers_themes() => {
672 let mut rows = 0;
673 if let Some(follow) = field.follows {
674 // First, and under no heading. It names no theme and sits in no
675 // variant, so a heading over it would be inventing a fourth
676 // variant for one row.
677 let chosen = held.text() == follow.value;
678 let (mark, painted) = if chosen {
679 ("(*)", well)
680 } else {
681 ("( )", style.secondary)
682 };
683 rows += text::draw(
684 &format!("{mark} {}", follow.label),
685 painted,
686 below(area, used + rows),
687 buf,
688 );
689 }
690 let mut open: Option<ThemeVariant> = None;
691 for theme in field.themes {
692 if open != Some(theme.variant) {
693 // Muted, which is the one place it is the truth rather than
694 // the lie: a heading will not answer, exactly as an
695 // unavailable option will not.
696 rows += text::draw(
697 theme.variant.heading(),
698 style.muted,
699 below(area, used + rows),
700 buf,
701 );
702 open = Some(theme.variant);
703 }
704 let chosen = held.text() == theme.id;
705 let (mark, painted) = if chosen {
706 ("(*)", well)
707 } else {
708 ("( )", style.secondary)
709 };
710 rows += text::draw(
711 &format!("{mark} {} [{}]", theme.name, theme.contrast.badge()),
712 painted,
713 below(area, used + rows),
714 buf,
715 );
716 }
717 rows
718 }
719 kind if kind.offers_options() => {
720 let mut rows = 0;
721 for choice in field.options {
722 let chosen = held.text() == choice.value;
723 // An option that cannot be picked yet reads as inert, which is
724 // the one place muted is the truth rather than the lie below:
725 // it will not answer, and the reason it will not is on the row
726 // beside it rather than nowhere.
727 let (mark, painted, suffix) = match choice.unavailable {
728 Some(reason) => ("( )", style.muted, format!(": {reason}")),
729 None if chosen => ("(*)", well, String::new()),
730 // An option that is not chosen is still an option: pressing
731 // it chooses it. So it takes the secondary content intent
732 // and not the muted one, which is what disabled looks like
733 // (`State::Disabled` resolves to it). Muted here read as a
734 // list of five where four were greyed out.
735 None => ("( )", style.secondary, String::new()),
736 };
737 rows += text::draw(
738 &format!("{mark} {}{suffix}", choice.label),
739 painted,
740 below(area, used + rows),
741 buf,
742 );
743 }
744 rows
745 }
746 // A secret's dots come from the caller's buffer and can come from
747 // nowhere else: a password that comes back down the wire is a password
748 // in a page and in a proxy log, so a description carries nothing to dot
749 // out. This is the one control that would be undrawable without `held`.
750 FieldKind::Secret if !held.text().is_empty() => {
751 let dots = "*".repeat(held.text().chars().count());
752 text::draw(&dots, well, below(area, used), buf).max(1)
753 }
754 // A file field has no way back on a terminal any more than it has on an
755 // HTTP host. The name is drawn and picking one belongs to whoever owns
756 // the interaction.
757 //
758 // makeover-layout 0.31.0 gave the description an accept list and a
759 // multiplicity, and neither changes anything drawn here. Both are the
760 // picker's business, and the picker is the caller's: this crate draws
761 // what was picked. A terminal that grows its own picker reads them off
762 // `Field::accept` and `Field::multiple` at that point rather than
763 // through a second spelling invented here.
764 _ if held.text().is_empty() => {
765 empty_well(style, placeholder, well, focused, below(area, used), buf)
766 }
767 _ => text::draw(&measured(field, held.text()), well, below(area, used), buf),
768 };
769
770 // Error, then note, then hint -- the order `Field::note` names, and the
771 // order a webview draws them in. Once something has gone wrong that is the
772 // sentence worth the row; failing that, what the chosen answer costs beats
773 // standing help about how the field works.
774 match message_of(style, field) {
775 Some((text, painted)) => used + text::draw(text, painted, below(area, used), buf),
776 None => used,
777 }
778 }
779
780 /// A bounded number as one line: the low end, the bar, the high end, then what
781 /// it currently reads.
782 ///
783 /// The two ends are drawn because they are the question. A threshold of 0.72
784 /// says nothing without them, which is the whole argument for
785 /// [`FieldKind::Range`] being a kind rather than a number with bounds, and a
786 /// terminal is where it would be easiest to quietly drop them and show a figure.
787 ///
788 /// The bar is [`meter`]'s cells, so a range and a proportion read as the same
789 /// object in the same app. What differs is the reading beside it: a meter counts
790 /// something and a range holds a value.
791 ///
792 /// A value the host cannot read as a number empties the bar and is still shown
793 /// as itself. That is [`empty_well`]'s position on an unreadable value: the app
794 /// put it there, and a terminal that silently rounded it to a bound would be
795 /// reporting a value nobody set.
796 fn range_line(style: &PieceStyle, field: &Field<'_>, value: &str, well: Style) -> Line<'static> {
797 let cells = usize::from(style.meter_cells);
798 let ends = field
799 .min
800 .zip(field.max)
801 .and_then(|(min, max)| Some((min.parse::<f64>().ok()?, max.parse::<f64>().ok()?)));
802 let filled = match (ends, value.parse::<f64>()) {
803 (Some((min, max)), Ok(number)) if max > min => {
804 // Where the value sits is the curve's answer, not a proportion of
805 // the extent (makeover-layout 0.32.0). Under `Curve::Linear` the two
806 // are the same number, which is why the bar was right before and is
807 // unchanged for every range described so far; under a constant ratio
808 // they are not, and a bar drawn linearly would put an envelope's
809 // whole useful half inside its first cell.
810 #[expect(
811 clippy::cast_possible_truncation,
812 clippy::cast_sign_loss,
813 reason = "`position_of` returns 0..=1, and the cell count came from a u16"
814 )]
815 let reached = (field.curve.position_of(number, min, max) * cells as f64) as usize;
816 reached.min(cells)
817 }
818 _ => 0,
819 };
820 let bar = format!(
821 "{}{}",
822 style.meter_full.to_string().repeat(filled),
823 style.meter_empty.to_string().repeat(cells - filled)
824 );
825 Line::from(vec![
826 Span::styled(format!("{} ", field.min.unwrap_or_default()), style.muted),
827 Span::styled(bar, well),
828 Span::styled(format!(" {}", field.max.unwrap_or_default()), style.muted),
829 Span::styled(format!(" {}", measured(field, value)), well),
830 ])
831 }
832
833 /// An interval as one line: the low end, the word, the high end.
834 ///
835 /// One line because it is one question. Two rows would read as two questions,
836 /// which is exactly what [`FieldKind::Interval`] exists to stop the description
837 /// saying, and a terminal has no side-by-side boxes to fall back on.
838 ///
839 /// # An open end draws the bound it falls back to
840 ///
841 /// Muted, because it is where the axis ends rather than a value anybody set.
842 /// With no bound to fall back on there is nothing honest to draw and the end
843 /// stays blank: a terminal inventing a number here would report a filter the
844 /// user never applied, which is [`range_line`]'s position on an unreadable
845 /// value.
846 ///
847 /// # The word, not a dash
848 ///
849 /// A dash between two numbers is a minus sign to anyone reading a signed axis,
850 /// and half the measured axes are signed -- audiofiles filters loudness in
851 /// dBFS. `to` costs two cells and cannot be misread.
852 fn interval_line(
853 style: &PieceStyle,
854 field: &Field<'_>,
855 held: Held<'_>,
856 well: Style,
857 ) -> Line<'static> {
858 let end = |value: &str, fallback: Option<&str>| match (value.is_empty(), fallback) {
859 (false, _) => Span::styled(measured(field, value), well),
860 (true, Some(bound)) => Span::styled(measured(field, bound), style.muted),
861 (true, None) => Span::styled(String::new(), style.muted),
862 };
863 Line::from(vec![
864 end(held.text(), field.min),
865 Span::styled(" to ", style.secondary),
866 end(held.upper(), field.max),
867 ])
868 }
869
870 /// The unit to draw beside this field's value, if there is one to draw.
871 ///
872 /// Two conditions rather than one: the field has to carry a unit and its kind
873 /// has to be one that means anything by it. `FieldKind::measurable` is the
874 /// description answering the second, so this renderer keeps no list of its own
875 /// of which kinds are quantities.
876 fn unit_of<'a>(field: &Field<'a>) -> Option<&'a str> {
877 field.unit.filter(|_| field.kind.measurable())
878 }
879
880 /// A value with what it is measured in, as one string.
881 ///
882 /// The unit rides on the value rather than on the label, which is
883 /// `makeover-layout` 0.33.0's rule and is what a terminal wants anyway: the
884 /// label is a line above and the number is the line the eye is on.
885 fn measured(field: &Field<'_>, value: &str) -> String {
886 match unit_of(field) {
887 Some(unit) => format!("{value} {unit}"),
888 None => value.to_owned(),
889 }
890 }
891
892 /// The label, marked where the field is compulsory.
893 fn label_of(style: &PieceStyle, field: &Field<'_>) -> String {
894 if field.required {
895 format!("{} {}", field.label, style.required_marker)
896 } else {
897 field.label.to_owned()
898 }
899 }
900
901 /// What goes under the box, and how it is painted.
902 ///
903 /// A terminal field has room for exactly one line, so the three message
904 /// channels compete for it and the precedence is decided in
905 /// [`makeover_layout::Field::note`]'s docs rather than three times here:
906 /// **error, then note, then hint**. What is wrong outranks what the answer
907 /// costs, which outranks how the field works.
908 ///
909 /// The tone comes with the note; an error is always danger and a hint is
910 /// always muted, because neither carries one.
911 fn message_of<'a>(style: &PieceStyle, field: &Field<'a>) -> Option<(&'a str, Style)> {
912 if let Some(error) = field.error {
913 return Some((error, style.danger));
914 }
915 if let Some((tone, note)) = field.note {
916 return Some((note, style.tone(tone)));
917 }
918 field.hint.map(|hint| (hint, style.muted))
919 }
920
921 /// A box with nothing in it: the ghost text, and the caret when it has focus.
922 ///
923 /// The caret is not decoration. An empty field under a style is an empty field,
924 /// so a focused one with no placeholder drew literally nothing and there was no
925 /// way to tell the box was where the typing would go. A browser has a blinking
926 /// bar for this and gets it without asking; a terminal has one cell of reversed
927 /// video, put on the first column, which is where the first character lands.
928 fn empty_well(
929 style: &PieceStyle,
930 placeholder: &str,
931 well: Style,
932 focused: bool,
933 area: Rect,
934 buf: &mut Buffer,
935 ) -> u16 {
936 let used = text::draw(placeholder, style.muted, area, buf).max(1);
937 if focused
938 && area.height > 0
939 && area.width > 0
940 && let Some(cell) = buf.cell_mut((area.x, area.y))
941 {
942 cell.set_style(well);
943 }
944 used
945 }
946
947 /// What is left of `area` after `used` rows from the top.
948 fn below(area: Rect, used: u16) -> Rect {
949 let used = used.min(area.height);
950 Rect {
951 x: area.x,
952 y: area.y + used,
953 width: area.width,
954 height: area.height - used,
955 }
956 }
957
958 #[cfg(test)]
959 mod tests {
960
961 #[test]
962 fn one_line_takes_the_error_then_the_note_then_the_hint() {
963 // A terminal field has room for exactly one message, so the three
964 // channels compete and `Field::note` decides the order.
965 let style = PieceStyle::default();
966 let mut f = Field::new(FieldKind::Text, "title", "Title");
967 f.hint = Some("how it works");
968 assert_eq!(message_of(&style, &f).unwrap().0, "how it works");
969
970 f.note = Some((Tone::Warning, "what it costs"));
971 assert_eq!(message_of(&style, &f).unwrap().0, "what it costs");
972 assert_eq!(message_of(&style, &f).unwrap().1, style.warning);
973
974 f.error = Some("what is wrong");
975 assert_eq!(message_of(&style, &f).unwrap().0, "what is wrong");
976 assert_eq!(message_of(&style, &f).unwrap().1, style.danger);
977
978 // A note carries its own tone, so a quiet one is not painted as a
979 // warning just for being a note.
980 f.error = None;
981 f.note = Some((Tone::Neutral, "an ordinary fact"));
982 assert_eq!(message_of(&style, &f).unwrap().1, style.content);
983 }
984 use super::*;
985 use makeover_layout::{Choice, State};
986
987 /// The style the drawings are read against: one distinguishable modifier
988 /// per role, so a test can say which style landed without a colour.
989 fn style() -> PieceStyle {
990 PieceStyle {
991 content: Style::new().add_modifier(Modifier::BOLD),
992 secondary: Style::new().add_modifier(Modifier::ITALIC),
993 muted: Style::new().add_modifier(Modifier::DIM),
994 danger: Style::new().add_modifier(Modifier::CROSSED_OUT),
995 ..PieceStyle::default()
996 }
997 }
998
999 fn buffer(width: u16, height: u16) -> Buffer {
1000 Buffer::empty(Rect::new(0, 0, width, height))
1001 }
1002
1003 /// Everything in the buffer, one string per row.
1004 fn rows(buf: &Buffer) -> Vec<String> {
1005 (0..buf.area.height)
1006 .map(|y| {
1007 (0..buf.area.width)
1008 .map(|x| {
1009 buf.cell((x, y))
1010 .map_or(' ', |c| c.symbol().chars().next().unwrap_or(' '))
1011 })
1012 .collect::<String>()
1013 .trim_end()
1014 .to_owned()
1015 })
1016 .collect()
1017 }
1018
1019 #[test]
1020 fn a_bar_fills_in_proportion_and_reads_out_the_two_numbers() {
1021 let style = style();
1022 let line = meter(&style, &Meter::new(3, 10).label("subtasks"));
1023 let drawn: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
1024 assert_eq!(drawn, "###------- 3/10 subtasks");
1025 // The noun is optional and the ratio is not, because a bar with no
1026 // reading is a bar you cannot check.
1027 let bare = meter(&style, &Meter::new(3, 10));
1028 let drawn: String = bare.spans.iter().map(|s| s.content.as_ref()).collect();
1029 assert_eq!(drawn, "###------- 3/10");
1030 }
1031
1032 #[test]
1033 fn an_empty_set_is_an_empty_bar_rather_than_a_divide_by_zero() {
1034 // `Meter::total` of zero means there is no set, and the checked
1035 // division is what keeps that from being a panic in a draw.
1036 let line = meter(&style(), &Meter::new(0, 0));
1037 let drawn: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
1038 assert_eq!(drawn, "---------- 0/0");
1039 }
1040
1041 #[test]
1042 fn an_over_run_fills_the_bar_and_still_reports_the_overflow() {
1043 // The clamp is for drawing only. The reading is what keeps the fact
1044 // `Meter::percent` destroys.
1045 let line = meter(&style(), &Meter::new(14, 10));
1046 let drawn: String = line.spans.iter().map(|s| s.content.as_ref()).collect();
1047 assert_eq!(drawn, "########## 14/10");
1048 }
1049
1050 #[test]
1051 fn a_badge_is_round_and_a_chip_is_square() {
1052 // The one affordance a cell has left once colour is spent on the tone,
1053 // and the whole of how a terminal says "this one answers a press".
1054 let style = style();
1055 let badge = token(&style, "draft", Token::Badge, Tone::Neutral, false, false);
1056 assert_eq!(badge.content.as_ref(), "(draft)");
1057 let chip = token(
1058 &style,
1059 "rust",
1060 Token::Chip { removable: false },
1061 Tone::Neutral,
1062 false,
1063 false,
1064 );
1065 assert_eq!(chip.content.as_ref(), "[rust]");
1066 }
1067
1068 #[test]
1069 fn a_latched_chip_reads_the_same_as_a_focused_one() {
1070 // The collision a terminal cannot avoid, asserted rather than left to
1071 // be rediscovered: latched is "this filter is on" and focused is "you
1072 // are here", and there is one spare axis for two facts.
1073 let style = style();
1074 let kind = Token::Chip { removable: false };
1075 let latched = token(&style, "rust", kind, Tone::Neutral, true, false);
1076 let focused = token(&style, "rust", kind, Tone::Neutral, false, true);
1077 assert_eq!(latched.style, focused.style);
1078 assert!(latched.style.add_modifier.contains(Modifier::REVERSED));
1079 }
1080
1081 #[test]
1082 fn a_control_draws_its_key_only_where_one_was_named() {
1083 let style = style();
1084 let line = act(&style, &Act::new("Delete"), false);
1085 assert_eq!(line.spans[0].content.as_ref(), "< Delete >");
1086 let line = act(&style, &Act::new("Quit").key("q"), false);
1087 assert_eq!(line.spans[0].content.as_ref(), "< Quit > (q)");
1088 }
1089
1090 #[test]
1091 fn a_disabled_control_is_never_marked_focused() {
1092 // Present, visible, and not answering. A focus mark on it would be an
1093 // affordance that lies, so the flag is overridden rather than trusted.
1094 let style = style();
1095 let disabled = Act::new("Save").state(State::Disabled);
1096 let line = act(&style, &disabled, true);
1097 assert!(
1098 !line.spans[0]
1099 .style
1100 .add_modifier
1101 .contains(Modifier::REVERSED)
1102 );
1103 assert_eq!(line.spans[0].style, style.muted);
1104 // The same call on a control the description says nothing about: the
1105 // mark is this renderer's own focus flag and always was, which is why
1106 // only `Disabled` can override it.
1107 let unstated = Act::new("Save");
1108 let line = act(&style, &unstated, true);
1109 assert!(
1110 line.spans[0]
1111 .style
1112 .add_modifier
1113 .contains(Modifier::REVERSED)
1114 );
1115 }
1116
1117 #[test]
1118 fn a_danger_control_keeps_its_tone_under_focus() {
1119 // Focus adds a modifier rather than repainting, so the fact that this
1120 // is the button that destroys something survives being landed on.
1121 let style = style();
1122 let line = act(&style, &Act::new("Delete").tone(Tone::Danger), true);
1123 assert_eq!(
1124 line.spans[0].style.add_modifier,
1125 style.danger.add_modifier | Modifier::REVERSED
1126 );
1127 }
1128
1129 #[test]
1130 fn a_figure_puts_the_number_over_what_it_counts() {
1131 let style = style();
1132 let figure_ = Figure::new("42", "open tasks");
1133 let mut buf = buffer(20, 4);
1134 let used = figure(&style, &figure_, buf.area, &mut buf);
1135 assert_eq!(used, 2);
1136 assert_eq!(rows(&buf)[..2], ["42".to_owned(), "open tasks".to_owned()]);
1137 assert_eq!(figure_height(&figure_, 20), 2);
1138 }
1139
1140 #[test]
1141 fn a_figures_change_rides_on_the_value_row() {
1142 // The delta is the toned part and the value is an ordinary fact, so the
1143 // two share a row rather than the caption growing a second sentence.
1144 let style = style();
1145 let figure_ = Figure::new("42", "open tasks")
1146 .change("+3")
1147 .tone(Tone::Success);
1148 let mut buf = buffer(20, 4);
1149 figure(&style, &figure_, buf.area, &mut buf);
1150 assert_eq!(rows(&buf)[0], "42 +3");
1151 }
1152
1153 #[test]
1154 fn a_compulsory_field_says_so_in_its_label() {
1155 let style = style();
1156 let mut field_ = Field::new(FieldKind::Text, "email", "Email");
1157 field_.required = true;
1158 let mut buf = buffer(20, 4);
1159 field(&style, &field_, Held::Absent, false, buf.area, &mut buf);
1160 assert_eq!(rows(&buf)[0], "Email *");
1161 }
1162
1163 #[test]
1164 fn a_hidden_field_costs_no_rows_at_all() {
1165 // The one field kind a terminal and a webview agree on completely.
1166 let style = style();
1167 let field_ = Field::new(FieldKind::Hidden, "csrf", "Token");
1168 let mut buf = buffer(20, 4);
1169 assert_eq!(
1170 field(
1171 &style,
1172 &field_,
1173 Held::Text("abc"),
1174 false,
1175 buf.area,
1176 &mut buf
1177 ),
1178 0
1179 );
1180 assert_eq!(field_height(&style, &field_, 20), 0);
1181 assert_eq!(rows(&buf)[0], "");
1182 }
1183
1184 #[test]
1185 fn a_secret_is_dotted_from_the_callers_buffer_and_never_from_the_description() {
1186 // The one control that would be undrawable without `held`: a password
1187 // that came back down the wire is a password in a page and in a log.
1188 let style = style();
1189 let field_ = Field::new(FieldKind::Secret, "password", "Password");
1190 let mut buf = buffer(20, 4);
1191 field(
1192 &style,
1193 &field_,
1194 Held::Text("hunter2"),
1195 false,
1196 buf.area,
1197 &mut buf,
1198 );
1199 assert_eq!(rows(&buf)[1], "*******");
1200 }
1201
1202 #[test]
1203 fn an_error_takes_the_row_the_hint_would_have_had() {
1204 // Once something has gone wrong that is the sentence worth the row,
1205 // which is the order a webview uses too.
1206 let style = style();
1207 let mut field_ = Field::new(FieldKind::Text, "email", "Email");
1208 field_.hint = Some("work address");
1209 field_.error = Some("not an address");
1210 let mut buf = buffer(20, 5);
1211 field(
1212 &style,
1213 &field_,
1214 Held::Text("nope"),
1215 false,
1216 buf.area,
1217 &mut buf,
1218 );
1219 assert_eq!(rows(&buf)[2], "not an address");
1220 assert_eq!(field_height(&style, &field_, 20), 3);
1221 }
1222
1223 #[test]
1224 fn a_focused_empty_box_shows_where_the_typing_will_land() {
1225 // An empty field under a style is an empty field. Without the caret a
1226 // focused box with no placeholder drew literally nothing.
1227 let style = style();
1228 let field_ = Field::new(FieldKind::Text, "email", "Email");
1229 let mut buf = buffer(20, 4);
1230 field(&style, &field_, Held::Absent, true, buf.area, &mut buf);
1231 let caret = buf.cell((0, 1)).expect("the well's first cell").style();
1232 assert!(caret.add_modifier.contains(Modifier::REVERSED));
1233 }
1234
1235 #[test]
1236 fn a_choice_field_marks_the_chosen_option_and_costs_a_row_each() {
1237 let style = style();
1238 let mut field_ = Field::new(FieldKind::Radio, "size", "Size");
1239 let options = [Choice::plain("small"), Choice::plain("large")];
1240 field_.options = &options;
1241 let mut buf = buffer(20, 5);
1242 field(
1243 &style,
1244 &field_,
1245 Held::Text("large"),
1246 false,
1247 buf.area,
1248 &mut buf,
1249 );
1250 assert_eq!(rows(&buf)[1], "( ) small");
1251 assert_eq!(rows(&buf)[2], "(*) large");
1252 assert_eq!(field_height(&style, &field_, 20), 3);
1253 }
1254
1255 #[test]
1256 fn a_range_draws_its_two_ends_and_where_the_value_sits_between_them() {
1257 let style = style();
1258 let field_ = Field::range("review", "Review above", "0", "1");
1259 let mut buf = buffer(40, 3);
1260 field(
1261 &style,
1262 &field_,
1263 Held::Text("0.5"),
1264 false,
1265 buf.area,
1266 &mut buf,
1267 );
1268 // Ten cells by default, half of them filled, with the extent read out
1269 // at either side: 0.5 means nothing without the 0 and the 1.
1270 assert_eq!(rows(&buf)[1].trim_end(), "0 #####----- 1 0.5");
1271 assert_eq!(field_height(&style, &field_, 40), 2);
1272 }
1273
1274 #[test]
1275 fn a_unit_rides_on_the_value_and_not_on_the_label() {
1276 // The label is a line above; the number is the line the eye is on.
1277 let style = style();
1278 let field_ = Field {
1279 unit: Some("s"),
1280 ..Field::range("attack", "Attack", "0", "5")
1281 };
1282 let mut buf = buffer(40, 3);
1283 field(
1284 &style,
1285 &field_,
1286 Held::Text("2.5"),
1287 false,
1288 buf.area,
1289 &mut buf,
1290 );
1291 assert_eq!(rows(&buf)[0].trim_end(), "Attack");
1292 assert_eq!(rows(&buf)[1].trim_end(), "0 #####----- 5 2.5 s");
1293 }
1294
1295 #[test]
1296 fn a_typed_number_reads_with_its_unit_too() {
1297 let style = style();
1298 let field_ = Field {
1299 unit: Some("ms"),
1300 ..Field::new(FieldKind::Number, "fade", "Fade")
1301 };
1302 let mut buf = buffer(40, 3);
1303 field(&style, &field_, Held::Text("50"), false, buf.area, &mut buf);
1304 assert_eq!(rows(&buf)[1].trim_end(), "50 ms");
1305 }
1306
1307 #[test]
1308 fn a_unit_on_a_kind_that_is_not_a_quantity_is_ignored() {
1309 // Which kinds are quantities is the description's answer, not a
1310 // `matches!` kept in this crate.
1311 let style = style();
1312 let field_ = Field {
1313 unit: Some("s"),
1314 ..Field::new(FieldKind::Text, "name", "Name")
1315 };
1316 let mut buf = buffer(40, 3);
1317 field(
1318 &style,
1319 &field_,
1320 Held::Text("kick"),
1321 false,
1322 buf.area,
1323 &mut buf,
1324 );
1325 assert_eq!(rows(&buf)[1].trim_end(), "kick");
1326 }
1327
1328 #[test]
1329 fn an_interval_is_one_line_with_both_ends_on_it() {
1330 // One question, one line. Two rows would read as two questions, which
1331 // is the reading the kind exists to prevent.
1332 let style = style();
1333 let field_ = Field {
1334 min: Some("0"),
1335 max: Some("300"),
1336 unit: Some("BPM"),
1337 ..Field::interval("bpm_min", "bpm_max", "BPM range")
1338 };
1339 let mut buf = buffer(40, 3);
1340 field(
1341 &style,
1342 &field_,
1343 Held::Between {
1344 lower: "90",
1345 upper: "130",
1346 },
1347 false,
1348 buf.area,
1349 &mut buf,
1350 );
1351 assert_eq!(rows(&buf)[0].trim_end(), "BPM range");
1352 assert_eq!(rows(&buf)[1].trim_end(), "90 BPM to 130 BPM");
1353 assert_eq!(rows(&buf)[2].trim_end(), "");
1354 }
1355
1356 #[test]
1357 fn an_open_end_falls_back_to_the_bound_it_means() {
1358 // "Over 120" is an answer rather than a half-filled box, and where the
1359 // axis ends is what the empty end stands for.
1360 let style = style();
1361 let field_ = Field {
1362 min: Some("0"),
1363 max: Some("300"),
1364 ..Field::interval("bpm_min", "bpm_max", "BPM range")
1365 };
1366 let mut buf = buffer(40, 3);
1367 field(
1368 &style,
1369 &field_,
1370 Held::Between {
1371 lower: "120",
1372 upper: "",
1373 },
1374 false,
1375 buf.area,
1376 &mut buf,
1377 );
1378 assert_eq!(rows(&buf)[1].trim_end(), "120 to 300");
1379 }
1380
1381 #[test]
1382 fn an_unbounded_open_end_draws_nothing_rather_than_a_number() {
1383 // A terminal inventing a bound here would report a filter nobody
1384 // applied, which is `range_line`'s position on an unreadable value.
1385 // What is left reads as the sentence it is: up to 130.
1386 let style = style();
1387 let field_ = Field::interval("bpm_min", "bpm_max", "BPM range");
1388 let mut buf = buffer(40, 3);
1389 field(
1390 &style,
1391 &field_,
1392 Held::Between {
1393 lower: "",
1394 upper: "130",
1395 },
1396 false,
1397 buf.area,
1398 &mut buf,
1399 );
1400 assert_eq!(rows(&buf)[1].trim_end(), "to 130");
1401 }
1402
1403 #[test]
1404 fn a_range_holding_something_unreadable_still_shows_it() {
1405 // The app put the value there. A terminal that quietly rounded it to a
1406 // bound would be reporting a value nobody set, which is `empty_well`'s
1407 // position on the same problem.
1408 let style = style();
1409 let field_ = Field::range("review", "Review above", "0", "1");
1410 let mut buf = buffer(40, 3);
1411 field(
1412 &style,
1413 &field_,
1414 Held::Text("unset"),
1415 false,
1416 buf.area,
1417 &mut buf,
1418 );
1419 assert_eq!(rows(&buf)[1].trim_end(), "0 ---------- 1 unset");
1420 }
1421
1422 #[test]
1423 fn an_unbounded_range_is_typed_into_rather_than_dragged() {
1424 // Bounds this crate invented are bounds the user would then drag
1425 // against. The text path takes every answer the bar would.
1426 let style = style();
1427 let field_ = Field {
1428 max: Some("1"),
1429 ..Field::new(FieldKind::Range, "review", "Review above")
1430 };
1431 let mut buf = buffer(40, 3);
1432 field(
1433 &style,
1434 &field_,
1435 Held::Text("0.5"),
1436 false,
1437 buf.area,
1438 &mut buf,
1439 );
1440 assert_eq!(rows(&buf)[1].trim_end(), "0.5");
1441 }
1442
1443 #[test]
1444 fn an_unavailable_option_reads_as_inert_and_says_why() {
1445 // The one place muted is the truth rather than the lie the convention
1446 // warns about: this option will not answer, and the reason is on the
1447 // row rather than nowhere.
1448 let style = style();
1449 let options = [
1450 Choice::new("chromatic", "Chromatic"),
1451 Choice::new("multi", "Multi-sample").unless("Drop a second sample."),
1452 ];
1453 let mut field_ = Field::new(FieldKind::Radio, "mode", "Mode");
1454 field_.options = &options;
1455 let mut buf = buffer(46, 4);
1456 field(
1457 &style,
1458 &field_,
1459 Held::Text("chromatic"),
1460 false,
1461 buf.area,
1462 &mut buf,
1463 );
1464 assert_eq!(rows(&buf)[1].trim_end(), "(*) Chromatic");
1465 assert_eq!(
1466 rows(&buf)[2].trim_end(),
1467 "( ) Multi-sample: Drop a second sample."
1468 );
1469 let muted = buf.cell((0, 2)).expect("the unavailable row").style();
1470 assert!(muted.add_modifier.contains(Modifier::DIM));
1471 }
1472
1473 #[test]
1474 fn an_unchosen_option_does_not_read_as_disabled() {
1475 // The three-tone convention: muted is inert, and every option in this
1476 // list answers a press. Drawn muted, a five-option radio read as one
1477 // live row and four dead ones.
1478 let style = style();
1479 let mut field_ = Field::new(FieldKind::Radio, "size", "Size");
1480 let options = [Choice::plain("small"), Choice::plain("large")];
1481 field_.options = &options;
1482 let mut buf = buffer(20, 5);
1483 field(
1484 &style,
1485 &field_,
1486 Held::Text("large"),
1487 false,
1488 buf.area,
1489 &mut buf,
1490 );
1491 let unchosen = buf.cell((0, 1)).expect("the first option").style();
1492 assert_eq!(unchosen.add_modifier, style.secondary.add_modifier);
1493 assert_ne!(unchosen.add_modifier, style.muted.add_modifier);
1494 }
1495
1496 #[test]
1497 fn a_checkbox_reads_a_bool_rather_than_a_submitted_string() {
1498 // `Held::On` exists so a host's own submission convention -- quasi
1499 // sends "value" -- stays the host's and never reaches a drawing.
1500 let style = style();
1501 let field_ = Field::new(FieldKind::Checkbox, "agree", "Agree");
1502 let mut buf = buffer(20, 4);
1503 field(&style, &field_, Held::On(true), false, buf.area, &mut buf);
1504 assert_eq!(rows(&buf)[1], "[x]");
1505 let mut buf = buffer(20, 4);
1506 field(&style, &field_, Held::On(false), false, buf.area, &mut buf);
1507 assert_eq!(rows(&buf)[1], "[ ]");
1508 }
1509
1510 #[test]
1511 fn a_markdown_field_gets_the_rows_a_textarea_does() {
1512 // Keyed on `multiline`, so a member added upstream does not silently
1513 // land on the single-row arm. One row for a value whose whole point is
1514 // that it has several is the failure this replaced.
1515 let style = PieceStyle::default();
1516 let rich = Field::new(FieldKind::Rich, "body", "Body");
1517 let textarea = Field::new(FieldKind::Textarea, "body", "Body");
1518 let plain = Field::new(FieldKind::Text, "body", "Body");
1519
1520 assert_eq!(
1521 field_height(&style, &rich, 40),
1522 field_height(&style, &textarea, 40)
1523 );
1524 assert!(field_height(&style, &rich, 40) > field_height(&style, &plain, 40));
1525 }
1526
1527 #[test]
1528 fn a_tone_and_a_heading_map_without_a_fallback_arm() {
1529 // Both source enums are closed, which is what lets these be total. A
1530 // renderer that had to guess would be picking its own colours again.
1531 let style = style();
1532 assert_eq!(style.tone(Tone::Neutral), style.content);
1533 assert_eq!(style.tone(Tone::Danger), style.danger);
1534 assert_eq!(style.heading(Heading::Page), style.page);
1535 assert_eq!(style.heading(Heading::Subsection), style.subsection);
1536 }
1537
1538 #[test]
1539 fn the_default_style_carries_no_colour_at_all() {
1540 // A two-colour terminal is the case where a foreground will not land,
1541 // so the default is modifiers only rather than a placeholder palette.
1542 let style = PieceStyle::default();
1543 for painted in [style.content, style.danger, style.page, style.action] {
1544 assert_eq!(painted.fg, None);
1545 assert_eq!(painted.bg, None);
1546 }
1547 }
1548
1549 #[test]
1550 fn the_three_states_of_a_wait_are_three_drawings() {
1551 // The whole done condition of `5db1e0ed`: a measured wait and an
1552 // unmeasured one stopped being the same line.
1553 let style = PieceStyle::default();
1554 let bare = awaiting(&style, Awaiting::unmeasured(), Progress::default(), true);
1555 let sized = awaiting(&style, Awaiting::of(41_943_040), Progress::default(), true);
1556 let watched = awaiting(
1557 &style,
1558 Awaiting::of(40),
1559 Progress {
1560 delivered: Some(20),
1561 elapsed: Some(Duration::from_secs(4)),
1562 },
1563 true,
1564 );
1565 let read = |line: &Line<'_>| {
1566 line.spans
1567 .iter()
1568 .map(|s| s.content.to_string())
1569 .collect::<String>()
1570 };
1571 assert_eq!(read(&bare), "#");
1572 assert_eq!(read(&sized), "# 41943040");
1573 assert_eq!(read(&watched), "#####----- 20/40 4s");
1574 }
1575
1576 #[test]
1577 fn a_dark_mark_still_occupies_its_cell() {
1578 // Not absent. A line that reflowed every half second would move the
1579 // content beside it, and the reader would lose where to look.
1580 let style = PieceStyle::default();
1581 assert_eq!(activity(&style, true).content.chars().count(), 1);
1582 assert_eq!(activity(&style, false).content.chars().count(), 1);
1583 }
1584
1585 #[test]
1586 fn an_over_delivered_wait_clamps_and_does_not_panic() {
1587 // A transfer can hand over more than the size it announced, and the
1588 // bar has ten cells whatever happens.
1589 let style = PieceStyle::default();
1590 let over = awaiting(
1591 &style,
1592 Awaiting::of(4),
1593 Progress {
1594 delivered: Some(9),
1595 elapsed: None,
1596 },
1597 true,
1598 );
1599 assert!(over.spans[0].content.chars().all(|c| c == '#'));
1600 assert_eq!(over.spans[0].content.chars().count(), 10);
1601 // A zero payload is no payload rather than a finished one.
1602 let empty = awaiting(
1603 &style,
1604 Awaiting::of(0),
1605 Progress {
1606 delivered: Some(9),
1607 elapsed: None,
1608 },
1609 true,
1610 );
1611 assert!(empty.spans[0].content.starts_with('-'));
1612 }
1613
1614 #[test]
1615 fn a_theme_picker_heads_each_group_and_marks_each_tier() {
1616 const THEMES: &[makeover_layout::ThemeChoice<'_>] = &[
1617 makeover_layout::ThemeChoice::new(
1618 "goingson",
1619 "GoingsOn",
1620 ThemeVariant::Light,
1621 makeover_layout::Contrast::High,
1622 ),
1623 makeover_layout::ThemeChoice::new(
1624 "carbonfox",
1625 "Carbonfox",
1626 ThemeVariant::Dark,
1627 makeover_layout::Contrast::Standard,
1628 ),
1629 ];
1630 let style = style();
1631 let field_ = Field::theme("theme", "Theme", THEMES)
1632 .following(makeover_layout::Choice::new("system", "Follow System"));
1633 let mut buf = buffer(32, 8);
1634 field(
1635 &style,
1636 &field_,
1637 Held::Text("carbonfox"),
1638 false,
1639 buf.area,
1640 &mut buf,
1641 );
1642
1643 let rows = rows(&buf);
1644 assert_eq!(rows[1], "( ) Follow System");
1645 assert_eq!(rows[2], "Light");
1646 assert_eq!(rows[3], "( ) GoingsOn [AA]");
1647 assert_eq!(rows[4], "Dark");
1648 assert_eq!(rows[5], "(*) Carbonfox [OK]");
1649 }
1650
1651 #[test]
1652 fn a_theme_picker_asks_for_the_rows_it_draws() {
1653 // Label, follow, two headings, two themes. A height that counted the
1654 // themes alone would clip the last group off every picker.
1655 const THEMES: &[makeover_layout::ThemeChoice<'_>] = &[
1656 makeover_layout::ThemeChoice::new(
1657 "goingson",
1658 "GoingsOn",
1659 ThemeVariant::Light,
1660 makeover_layout::Contrast::High,
1661 ),
1662 makeover_layout::ThemeChoice::new(
1663 "carbonfox",
1664 "Carbonfox",
1665 ThemeVariant::Dark,
1666 makeover_layout::Contrast::Standard,
1667 ),
1668 ];
1669 let style = style();
1670 let field_ = Field::theme("theme", "Theme", THEMES)
1671 .following(makeover_layout::Choice::new("system", "Follow System"));
1672 assert_eq!(field_height(&style, &field_, 32), 6);
1673
1674 // One variant, no follow row: one heading, not three.
1675 let one = Field::theme("theme", "Theme", &THEMES[..1]);
1676 assert_eq!(field_height(&style, &one, 32), 3);
1677 }
1678 }
1679