Skip to main content

max / makeover-tui

34.6 KB · 827 lines History Blame Raw
1 //! The terminal renderer for [`makeover_layout`].
2 //!
3 //! <!-- wiki: makeover-tui -->
4 //!
5 //! Named for the target and not for ratatui, the same way
6 //! `makeover-immediate` is named for the mode and not for egui.
7 //!
8 //! # What a terminal actually costs you
9 //!
10 //! Not colour. That was the original assumption here and it is wrong on any
11 //! terminal built this decade. Measured across the 31 shipped themes
12 //! (`makeover`'s `well_fidelity` example):
13 //!
14 //! | | ANSI-16 | ANSI-256 | truecolor |
15 //! |---|---|---|---|
16 //! | a well collapses onto its face | 18/31 | 4/31 | 2/31 |
17 //! | at least one bevel edge vanishes into its face | 31/31 | 4/31 | 0 |
18 //!
19 //! The threshold is 256, not 24-bit, and the two failures that survive at
20 //! truecolor are not terminal failures at all: they are the themes whose
21 //! raised surface is already white, so the lightening clamps and the well
22 //! lands exactly on its face. Those render identically in a browser.
23 //! `makeover`'s own `well_is_distinct_from_its_face` test already names them.
24 //!
25 //! **What a terminal costs is geometry, and no amount of colour fixes it.**
26 //! An edge occupies a whole cell on each side. A cell is roughly 8x17 pixels,
27 //! so a one-pixel bevel becomes something an order of magnitude heavier, which
28 //! is why [`frame`] hands back a shrunk [`Rect`] instead of pretending the
29 //! region survived intact. There is nowhere to put a corner radius, so
30 //! `radius_control` and `radius_container` mean the same thing here. A fill
31 //! can only begin and end on a cell boundary.
32 //!
33 //! That is the constraint worth designing against. It does not improve, it is
34 //! not detectable, and it applies equally to the best terminal ever written.
35 //!
36 //! What it does not mean is that the shape inside the cell stops mattering.
37 //! Half of a cell is still addressable, and a bevel drawn in half-blocks reads
38 //! as a lit edge where the same bevel in box-drawing reads as a line: `─` and
39 //! `│` are one stroke through the middle, identical on all four sides, saying
40 //! nothing about where the light is. Half-blocks also make the two corners
41 //! where light meets shadow expressible, since a glyph that fills half a cell
42 //! leaves the other half to the second tone.
43 //!
44 //! # Where fidelity does matter
45 //!
46 //! At [`Fidelity::Ansi16`] the depth vocabulary collapses outright: a well
47 //! cannot be filled distinctly on most themes *and* a bevel loses an edge on
48 //! every one of them, so a raised card and a well both read as a single-tone
49 //! box. Colour cannot carry the distinction, so [`frame`] carries it with the
50 //! glyphs instead.
51 //!
52 //! Above that, colour carries it and the glyph fallback never fires.
53 //!
54 //! [`Palette::shows`] is worth reading correctly in light of the numbers: it
55 //! is **not** a low-colour workaround. It is a correctness check that a fill
56 //! will be visible against what is behind it, and at truecolor it fires on
57 //! exactly the two clamping themes, which is precisely when it should.
58 //!
59 //! # 0.13.0: a modal, and two cues four ports were about to each invent
60 //!
61 //! [`Depth::Overlay`](makeover_layout::Depth::Overlay) arrives in
62 //! makeover-layout 0.14.0 and needed nothing here: [`Palette::fill`] has
63 //! answered `Fill::Overlay` since this crate had a palette, so what was missing
64 //! was the route from a description rather than the drawing. A test asserts it,
65 //! because a route nothing exercises is one a refactor can quietly lose.
66 //!
67 //! [`Theme::selection_on`] and [`Theme::focus_ring`] are the other half, and
68 //! both are DERIVED rather than authored. Every consumer measured did selection
69 //! with `REVERSED`, for want of an on-accent foreground; every one that wanted
70 //! a focus ring either spent makeover's `border-strong` on it, which is a
71 //! divider at 1.63:1 on Akari Dawn, or derived its own the way `alloy_tui`
72 //! does. Four terminal ports were each about to answer that separately.
73 //!
74 //! Derived, not authored, because the direction is one-way. An authored key can
75 //! fall back to a derivation and break no theme on disk; a key this crate
76 //! started requiring would break every theme that lacks it. So the theme format
77 //! does not change and nothing on disk grows, and the promotion stays available
78 //! for a theme that ever needs to tune either.
79 //!
80 //! # 0.14.0: the first structural widget
81 //!
82 //! [`table`] is the first thing here that draws content rather than a surface,
83 //! and it exists because 14 call sites across `mnw-cli` and `viewer` were
84 //! already drawing one. `mnw-cli` had written the mapping layer by hand
85 //! (`src/tui/widgets.rs`: a muted bold header, a selected row carried by the
86 //! background alone) and `viewer` had written a smaller one, which is two
87 //! answers to a question this crate is supposed to answer once.
88 //!
89 //! It is a mapping layer over [`ratatui::widgets::Table`] rather than a table
90 //! implementation, because ratatui already lays tracks out, draws a header,
91 //! highlights a row and scrolls. What it has no answer for is content
92 //! measurement and narrowing, and those are what the module is.
93 //!
94 //! # 0.19.0: `widget` is [`piece`], because the word went to the description
95 //!
96 //! `makeover-layout` 0.20.0 added `Region::Widget`, the third tier between a
97 //! primitive and `Region::Bespoke`: a named assembly of primitives that each
98 //! renderer draws its own way. That is host-agnostic and sits *above* every
99 //! renderer.
100 //!
101 //! This crate's `widget` module is the opposite end of the same stack —
102 //! renderer-local, the answer to what a meter looks like in cells, taking a
103 //! description plus what only a terminal knows. Two different things wearing
104 //! one word, and the collision would have been worst exactly here, in a crate
105 //! that has to implement the tier.
106 //!
107 //! So this half moved and the description's half kept the word. That direction
108 //! is not arbitrary: a second or third party naming a widget is naming the
109 //! layout kind, and nothing outside this tree ever needed a word for a drawing
110 //! routine. `WidgetStyle` is `PieceStyle`.
111 //!
112 //! # 0.27.0: a bar for a bounded number, and an option that is not offered yet
113 //!
114 //! `makeover-layout` 0.28.0's form findings, at the renderer that has the bar
115 //! already. A [`makeover_layout::FieldKind::Range`] is drawn as [`piece::meter`]'s
116 //! cells with its two ends read out either side, because the ends are what the
117 //! question means and a terminal is where it would be easiest to quietly show a
118 //! figure instead. An unbounded range falls back to the text path rather than
119 //! to bounds this crate invented.
120 //!
121 //! `Choice::unavailable` is the one place the three-tone convention's muted is
122 //! the truth rather than the lie it warns about: that option will not answer,
123 //! and the reason it will not now sits on its row.
124 //!
125 //! `Field::placeholder` on a chooser, the third finding, is already answered
126 //! here and needed nothing: this renderer draws every option of a select at
127 //! once, so an unanswered one is a list with no mark against any row rather
128 //! than an empty box with nothing in it.
129 //!
130 //! # The correction this renderer forced
131 //!
132 //! [`makeover_layout::Fill`] briefly carried a `fallback` method, returning
133 //! `Page` for `Well` so a consumer without `surface-well` had something to
134 //! use. That is an answer for a renderer that can always paint a colour. Here
135 //! it is actively wrong: page *is* the surface a well is usually cut into, so
136 //! falling back to it produces the exact invisibility the fallback was meant
137 //! to avoid.
138 //!
139 //! Substituting one intent for another is renderer policy, not description.
140 //! The fallback moved out of the description and into
141 //! `makeover-immediate`, where it belongs, which is the first thing a second
142 //! renderer was built to find.
143
144 #![forbid(unsafe_code)]
145
146 use makeover_layout::{Bevel, Depth, Edge, Fill};
147 use ratatui::buffer::Buffer;
148 use ratatui::layout::Rect;
149 use ratatui::style::Color;
150
151 /// The description this crate renders, re-exported.
152 ///
153 /// Every entry point here takes a type from it, so a consumer would otherwise
154 /// have to depend on the description separately and keep two version
155 /// requirements in step to name the argument it is already being handed.
156 pub use makeover_layout;
157
158 /// A loaded makeover theme, resolved to the colours ratatui draws with.
159 ///
160 /// Behind the `theme` feature: it is the only thing here that needs `makeover`
161 /// itself, and that crate embeds the shipped theme files. A consumer that wants
162 /// [`frame`] and nothing else should not carry them.
163 #[cfg(feature = "theme")]
164 pub mod theme;
165
166 #[cfg(feature = "theme")]
167 pub use theme::{Mode, Quantize, Theme, ThemeError};
168
169 /// Columns, narrowing, cell parts and the sort caret, over ratatui's own
170 /// [`Table`](ratatui::widgets::Table).
171 ///
172 /// Not feature-gated. It needs no theme: [`TableStyle`](table::TableStyle)
173 /// carries the tones, and a caller with a loaded theme gets them from
174 /// `TableStyle::from_theme` instead of supplying them.
175 pub mod table;
176
177 /// Word wrapping that answers a height and a drawing from the same measurement.
178 ///
179 /// The half ratatui's `Paragraph` leaves out. A flow layout asks for rows at a
180 /// width and then draws into the rect it was given, and if the two disagree by
181 /// one row a node draws over the one under it.
182 pub mod text;
183
184 /// A meter, a badge, a control, a figure and a form field.
185 ///
186 /// The pieces below the level [`table`] works at. Not feature-gated, on
187 /// [`table`]'s footing: [`PieceStyle`](piece::PieceStyle) carries the tones,
188 /// and a caller with a loaded theme reaches for `PieceStyle::from_theme`.
189 pub mod piece;
190
191 /// How many colours the terminal can actually show.
192 ///
193 /// Only [`Fidelity::Ansi16`] changes what this crate draws. Above it, colour
194 /// separates a raised surface from a well on every shipped theme, and the
195 /// glyph fallback below never fires. Recorded rather than inferred, because a
196 /// caller that quantised its palette knows the answer and this crate cannot
197 /// recover it from the colours afterwards.
198 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
199 pub enum Fidelity {
200 /// Sixteen colours. Depth cannot be carried by colour: a well collapses
201 /// onto its face on 18 of 31 themes and a bevel loses an edge on all 31.
202 Ansi16,
203 /// The 6x6x6 cube and the grey ramp. Enough on 27 of 31 themes.
204 Ansi256,
205 /// 24-bit. The only failures left belong to the theme, not the terminal.
206 #[default]
207 TrueColor,
208 }
209
210 impl Fidelity {
211 /// Read the terminal's own claim, from `COLORTERM` then `TERM`.
212 ///
213 /// Deliberately credulous, and the fall-through is where that is decided.
214 /// An unrecognised `TERM` is assumed capable, because the two wrong answers
215 /// do not cost the same: guessing [`TrueColor`](Self::TrueColor) on a
216 /// limited terminal costs some fidelity, and guessing
217 /// [`Ansi16`](Self::Ansi16) on a capable one throws away colour the user
218 /// paid for — and, for a caller that quantises its palette off this answer,
219 /// throws away the whole theme. `COLORTERM` is routinely stripped by ssh
220 /// and by multiplexers, so an unrecognised name is the common case rather
221 /// than the exotic one: `foot`, `xterm` and `screen` all land here.
222 ///
223 /// So sixteen colours is reached by naming the terminals that really have
224 /// them. The list is short and it does not grow: these are the fixed
225 /// consoles, and `TERM=linux` is the case this exists for — the Linux
226 /// virtual console, which is what an installer and a machine with no
227 /// desktop draw on.
228 #[must_use]
229 pub fn detect() -> Self {
230 Self::from_env(
231 &std::env::var("COLORTERM").unwrap_or_default(),
232 &std::env::var("TERM").unwrap_or_default(),
233 )
234 }
235
236 /// [`detect`](Self::detect) with the environment passed in, so the decision
237 /// can be tested without mutating a process-wide variable from a parallel
238 /// test.
239 #[must_use]
240 pub fn from_env(colorterm: &str, term: &str) -> Self {
241 if colorterm.contains("truecolor") || colorterm.contains("24bit") {
242 return Self::TrueColor;
243 }
244 match term {
245 "linux" | "vt100" | "vt220" | "ansi" | "dumb" => Self::Ansi16,
246 _ if term.contains("256color") || term.contains("direct") => Self::Ansi256,
247 _ => Self::TrueColor,
248 }
249 }
250
251 /// Whether colour alone can tell a raised surface from a well here.
252 #[must_use]
253 pub const fn separates_depth(self) -> bool {
254 !matches!(self, Self::Ansi16)
255 }
256 }
257
258 /// The resolved colours this renderer needs.
259 ///
260 /// Supply them already quantised to whatever the terminal can show. That is
261 /// what makes [`Palette::shows`] a plain inequality rather than a colour-space
262 /// calculation: by the time a colour reaches here, the question of what the
263 /// terminal will actually paint has been answered.
264 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
265 pub struct Palette {
266 /// `surface-page`.
267 pub page: Color,
268 /// `surface-raised`.
269 pub raised: Color,
270 /// `surface-overlay`.
271 pub overlay: Color,
272 /// `surface-well`, absent on makeover before 2.3.0.
273 pub well: Option<Color>,
274 /// `bevel-light`.
275 pub bevel_light: Color,
276 /// `bevel-dark`.
277 pub bevel_dark: Color,
278 /// What the terminal can show. Defaults to [`Fidelity::TrueColor`].
279 pub fidelity: Fidelity,
280 }
281
282 impl Palette {
283 /// Resolve a surface intent, or `None` where this renderer has no colour
284 /// for it.
285 ///
286 /// No substitution happens here. A missing intent stays missing, and
287 /// [`frame`] answers it with structure instead of with a different colour.
288 /// That rule is what lets the wildcard below be a real answer rather than
289 /// a hole: [`Fill`] is `#[non_exhaustive]` from `makeover-layout` 0.4.0
290 /// onward, so the description can name a surface this renderer has not
291 /// learned to paint, and saying so is better than failing to build.
292 #[must_use]
293 pub const fn fill(&self, fill: Fill) -> Option<Color> {
294 match fill {
295 Fill::Page => Some(self.page),
296 Fill::Raised => Some(self.raised),
297 Fill::Overlay => Some(self.overlay),
298 Fill::Well => self.well,
299 // Includes Fill::Sunken, which this renderer has no tone for: a
300 // terminal cell has one background, so a surface set back by
301 // colour alone is not a thing it can say. The chosen tab is drawn
302 // forward instead.
303 _ => None,
304 }
305 }
306
307 /// Resolve a bevel edge intent.
308 #[must_use]
309 pub const fn edge(&self, edge: Edge) -> Color {
310 match edge {
311 Edge::Light => self.bevel_light,
312 Edge::Dark => self.bevel_dark,
313 }
314 }
315
316 /// Whether painting `fill` over `behind` would show anything.
317 ///
318 /// The whole of the terminal's problem in one predicate. On a truecolor
319 /// terminal this is almost always true; in sixteen colours it is false
320 /// often enough that a design relying on fills is a design that vanishes.
321 #[must_use]
322 pub fn shows(fill: Color, behind: Color) -> bool {
323 fill != behind
324 }
325
326 /// Whether this palette can express a bevel as two distinct edges.
327 ///
328 /// Measured, this is the wrong thing to worry about: the two edge colours
329 /// never quantise onto each other, at any depth, on any shipped theme.
330 /// What does happen is an edge vanishing into the *face* it is drawn on,
331 /// on every theme at sixteen colours. Kept because a hand-built palette
332 /// can still collide, and cheap to ask.
333 #[must_use]
334 pub fn two_tone(&self) -> bool {
335 self.bevel_light != self.bevel_dark
336 }
337
338 /// Whether depth has to be carried by glyphs rather than by colour.
339 ///
340 /// True when the terminal cannot separate the two surfaces, which is the
341 /// sixteen-colour case and nothing else.
342 #[must_use]
343 pub const fn needs_glyph_depth(&self) -> bool {
344 !self.fidelity.separates_depth()
345 }
346 }
347
348 /// The characters a frame's edges and corners are drawn with.
349 ///
350 /// Per side rather than per axis, because the set that reads best as a bevel
351 /// does not use the same glyph on opposite sides: a half-block edge is only
352 /// half a cell, and which half it occupies is what says where the edge is.
353 /// Box-drawing sets fill `top`/`bottom` and `left`/`right` with the same
354 /// character and lose nothing by it.
355 ///
356 /// Three sets. [`BEVEL`] is what a terminal that can show two tones gets. The
357 /// other two exist because at sixteen colours the glyphs are the only thing
358 /// left to carry depth: a well cannot be filled distinctly and a bevel loses
359 /// an edge, so a raised card and a well would otherwise be the same
360 /// single-tone box. A doubled line reads as standing off the page and a light
361 /// one as cut into it, which is the same claim the fill and the bevel make in
362 /// colour.
363 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
364 pub(crate) struct GlyphSet {
365 pub(crate) top: &'static str,
366 pub(crate) bottom: &'static str,
367 pub(crate) left: &'static str,
368 pub(crate) right: &'static str,
369 pub(crate) top_left: &'static str,
370 pub(crate) top_right: &'static str,
371 pub(crate) bottom_left: &'static str,
372 pub(crate) bottom_right: &'static str,
373 /// Whether the two corners where light meets shadow carry both tones in
374 /// one cell, foreground over background.
375 ///
376 /// Only a half-cell glyph can: it already divides the cell, so the split
377 /// costs nothing and the corner reads as a transition rather than as one
378 /// edge overrunning the other. A box-drawing corner is a single stroke
379 /// with no such division, so those sets say `false` and both shared
380 /// corners go to dark — see [`paint_bevel_with`] for why that particular
381 /// fallback and not the other one.
382 pub(crate) split_corners: bool,
383 }
384
385 /// Half-blocks, which is what a bevel actually wants.
386 ///
387 /// A cell is roughly 8x17 device pixels, so a half-block along the top and a
388 /// half-cell column down the side are about the same number of pixels and the
389 /// edge reads as even thickness. Box-drawing cannot do that: `─` and `│` are
390 /// both a thin stroke through the middle of the cell, identical on all four
391 /// sides, which draws a *line* rather than a lit edge and gives up the light
392 /// model that makes a bevel legible.
393 ///
394 /// Adopted from `alloy_tui`, which reached this independently and got there
395 /// first (2026-07-26, two days before this crate existed).
396 pub(crate) const BEVEL: GlyphSet = GlyphSet {
397 top: "▀",
398 bottom: "▄",
399 left: "▌",
400 right: "▐",
401 top_left: "▛",
402 // The two shared corners are the split ones: an upper half continues the
403 // lit top edge while the lower half starts the shaded right edge, and the
404 // mirror of that at bottom left.
405 top_right: "▀",
406 bottom_left: "▄",
407 bottom_right: "▟",
408 split_corners: true,
409 };
410
411 pub(crate) const LIGHT: GlyphSet = GlyphSet {
412 top: "─",
413 bottom: "─",
414 left: "│",
415 right: "│",
416 top_left: "┌",
417 top_right: "┐",
418 bottom_left: "└",
419 bottom_right: "┘",
420 split_corners: false,
421 };
422
423 pub(crate) const DOUBLE: GlyphSet = GlyphSet {
424 top: "═",
425 bottom: "═",
426 left: "║",
427 right: "║",
428 top_left: "╔",
429 top_right: "╗",
430 bottom_left: "╚",
431 bottom_right: "╝",
432 split_corners: false,
433 };
434
435 /// Paint a two-tone edge around the outside of `area`.
436 ///
437 /// Light takes the top and left, dark the bottom and right. What happens at
438 /// the two corners where they meet depends on what the terminal can show.
439 /// Above sixteen colours the edge is drawn in half-blocks and those corners
440 /// carry both tones, one per half-cell. At sixteen it is box-drawing, whose
441 /// single stroke has no half to give, so both shared corners go to dark.
442 ///
443 /// Costs a cell on each side, which a pixel renderer's bevel does not. Use the
444 /// [`Rect`] returned by [`frame`] rather than assuming the area is intact.
445 pub fn paint_bevel(buf: &mut Buffer, area: Rect, bevel: Bevel, palette: &Palette) {
446 paint_bevel_with(buf, area, bevel, palette, set_for(palette, None));
447 }
448
449 /// Which glyphs to draw with, given what the terminal can show.
450 ///
451 /// Above sixteen colours the two tones are available and [`BEVEL`] renders
452 /// them as light. At sixteen the tones collapse, so the box-drawing sets carry
453 /// the distinction in weight instead, and `depth` picks which: a doubled frame
454 /// for a raised card and a light one for everything else. `None` means the
455 /// caller is drawing a bevel with no depth behind it, which is never the
456 /// doubled case.
457 fn set_for(palette: &Palette, depth: Option<Depth>) -> GlyphSet {
458 if !palette.needs_glyph_depth() {
459 return BEVEL;
460 }
461 match depth {
462 Some(Depth::Raised) => DOUBLE,
463 _ => LIGHT,
464 }
465 }
466
467 fn paint_bevel_with(buf: &mut Buffer, area: Rect, bevel: Bevel, palette: &Palette, set: GlyphSet) {
468 if area.width < 2 || area.height < 2 {
469 return;
470 }
471 let (top_left, bottom_right) = bevel.edges();
472 let light = palette.edge(top_left);
473 let dark = palette.edge(bottom_right);
474
475 let (x0, y0) = (area.x, area.y);
476 let (x1, y1) = (area.right() - 1, area.bottom() - 1);
477
478 // Light first: top edge and left edge, corners included.
479 for x in x0..=x1 {
480 buf[(x, y0)].set_symbol(set.top).set_fg(light);
481 }
482 for y in y0..=y1 {
483 buf[(x0, y)].set_symbol(set.left).set_fg(light);
484 }
485 // Dark second, so on a set without split corners the two shared ones land
486 // on it by draw order alone.
487 for x in x0..=x1 {
488 buf[(x, y1)].set_symbol(set.bottom).set_fg(dark);
489 }
490 for y in y0..=y1 {
491 buf[(x1, y)].set_symbol(set.right).set_fg(dark);
492 }
493
494 buf[(x0, y0)].set_symbol(set.top_left).set_fg(light);
495 buf[(x1, y1)].set_symbol(set.bottom_right).set_fg(dark);
496
497 if set.split_corners {
498 // Where light meets shadow, both tones share the cell: the half the
499 // glyph fills is the foreground and the half it leaves is the
500 // background, so the corner is a transition rather than one edge
501 // overrunning the other.
502 buf[(x1, y0)]
503 .set_symbol(set.top_right)
504 .set_fg(light)
505 .set_bg(dark);
506 buf[(x0, y1)]
507 .set_symbol(set.bottom_left)
508 .set_fg(dark)
509 .set_bg(light);
510 } else {
511 // Both shared corners to dark. Not arbitrary: it is the same rule
512 // `makeover-immediate` produces by drawing its dark polyline second,
513 // so a control does not change which corner is lit when it moves
514 // between a terminal and a window. A single-stroke corner has no half
515 // to give the other tone, so this is the only rule available to these
516 // sets anyway.
517 buf[(x1, y0)].set_symbol(set.top_right).set_fg(dark);
518 buf[(x0, y1)].set_symbol(set.bottom_left).set_fg(dark);
519 }
520 }
521
522 /// Draw a region at a given [`Depth`] and return the area left for content.
523 ///
524 /// The fill is painted only when it would be visible against what is already
525 /// in the buffer. Everything else is the edge, which is why a well still reads
526 /// as a well on a terminal that cannot colour one.
527 pub fn frame(buf: &mut Buffer, area: Rect, depth: Depth, palette: &Palette) -> Rect {
528 if area.is_empty() {
529 return area;
530 }
531 let behind = buf[(area.x, area.y)].bg;
532
533 if let Some(color) = depth.fill().and_then(|f| palette.fill(f))
534 && Palette::shows(color, behind)
535 {
536 for y in area.top()..area.bottom() {
537 for x in area.left()..area.right() {
538 buf[(x, y)].set_bg(color);
539 }
540 }
541 }
542
543 match depth.bevel() {
544 Some(bevel) if area.width >= 2 && area.height >= 2 => {
545 // Colour separates raised from well wherever it can. Where it
546 // cannot, the glyphs do, and only then: a doubled frame on every
547 // terminal would be shouting.
548 let set = set_for(palette, Some(depth));
549 paint_bevel_with(buf, area, bevel, palette, set);
550 Rect::new(area.x + 1, area.y + 1, area.width - 2, area.height - 2)
551 }
552 _ => area,
553 }
554 }
555
556 #[cfg(test)]
557 mod tests {
558 use super::*;
559
560 fn palette(well: Option<Color>) -> Palette {
561 Palette {
562 page: Color::Indexed(7),
563 raised: Color::Indexed(15),
564 overlay: Color::Indexed(8),
565 well,
566 bevel_light: Color::Indexed(15),
567 bevel_dark: Color::Indexed(0),
568 fidelity: Fidelity::TrueColor,
569 }
570 }
571
572 fn buffer() -> Buffer {
573 Buffer::empty(Rect::new(0, 0, 6, 4))
574 }
575
576 #[test]
577 fn a_well_that_cannot_be_coloured_is_still_drawn() {
578 // The 18-of-31 case: no surface-well token at all.
579 let p = palette(None);
580 let mut buf = buffer();
581 frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Well, &p);
582 // No fill was available, but the region still reads as recessed.
583 assert_eq!(buf[(0, 0)].symbol(), BEVEL.top_left);
584 assert_eq!(buf[(0, 0)].bg, Color::Reset);
585 }
586
587 #[test]
588 fn a_fill_that_matches_its_surroundings_is_not_painted() {
589 let p = palette(Some(Color::Indexed(7)));
590 let mut buf = buffer();
591 // Everything behind is already page-coloured, and the well quantised
592 // onto it. Painting it would be a no-op that hides the real problem.
593 for y in 0..4 {
594 for x in 0..6 {
595 buf[(x, y)].set_bg(Color::Indexed(7));
596 }
597 }
598 frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Well, &p);
599 assert!(!Palette::shows(Color::Indexed(7), Color::Indexed(7)));
600 // The edge is what carries the meaning here.
601 assert_eq!(buf[(5, 3)].symbol(), BEVEL.bottom_right);
602 }
603
604 #[test]
605 fn a_visible_fill_is_painted() {
606 let p = palette(Some(Color::Indexed(4)));
607 let mut buf = buffer();
608 frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Well, &p);
609 assert_eq!(buf[(2, 2)].bg, Color::Indexed(4));
610 }
611
612 #[test]
613 fn an_overlay_is_painted_and_left_unedged() {
614 // makeover-layout 0.14.0's Depth::Overlay, and the wiring under it was
615 // already here: `Palette::fill` has answered `Fill::Overlay` since this
616 // crate had a palette. So this asserts the route rather than building
617 // one, and it is the assertion that would catch the route being lost.
618 let p = palette(None);
619 let mut buf = buffer();
620 let inner = frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Overlay, &p);
621
622 assert_eq!(buf[(2, 2)].bg, p.overlay);
623 // A surface over the page is separated by the lift and by what sits
624 // behind it, so it takes no edge -- and with no edge drawn, nothing is
625 // given up to one: the content area is the whole region.
626 assert_eq!(buf[(0, 0)].symbol(), " ");
627 assert_eq!(inner, Rect::new(0, 0, 6, 4));
628 }
629
630 #[test]
631 fn the_light_falls_from_the_top_left() {
632 let p = palette(None);
633 let mut buf = buffer();
634 paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised, &p);
635 assert_eq!(buf[(0, 0)].fg, p.bevel_light); // top-left
636 assert_eq!(buf[(3, 0)].fg, p.bevel_light); // top edge
637 assert_eq!(buf[(0, 2)].fg, p.bevel_light); // left edge
638 assert_eq!(buf[(5, 3)].fg, p.bevel_dark); // bottom-right
639 assert_eq!(buf[(3, 3)].fg, p.bevel_dark); // bottom edge
640 assert_eq!(buf[(5, 2)].fg, p.bevel_dark); // right edge
641 }
642
643 // Half-cell glyphs divide the cell already, so the corner where light
644 // meets shadow can hold both rather than picking one.
645 #[test]
646 fn the_shared_corners_carry_both_tones_when_the_glyph_can_split() {
647 let p = palette(None);
648 let mut buf = buffer();
649 paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised, &p);
650 let top_right = &buf[(5, 0)];
651 assert_eq!(top_right.fg, p.bevel_light);
652 assert_eq!(top_right.bg, p.bevel_dark);
653 let bottom_left = &buf[(0, 3)];
654 assert_eq!(bottom_left.fg, p.bevel_dark);
655 assert_eq!(bottom_left.bg, p.bevel_light);
656 }
657
658 // A single-stroke corner has no half to give the second tone, so the
659 // box-drawing sets keep the old rule: both shared corners to dark, which
660 // is what makeover-immediate produces by drawing its dark polyline second.
661 // Changing that would move the lit corner between a terminal and a window.
662 #[test]
663 fn box_drawing_corners_stay_dark_and_match_the_immediate_renderer() {
664 let p = Palette {
665 fidelity: Fidelity::Ansi16,
666 ..palette(None)
667 };
668 let mut buf = buffer();
669 paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised, &p);
670 assert_eq!(buf[(5, 0)].symbol(), LIGHT.top_right);
671 assert_eq!(buf[(5, 0)].fg, p.bevel_dark);
672 assert_eq!(buf[(5, 0)].bg, Color::Reset, "a stroke has no second tone");
673 assert_eq!(buf[(0, 3)].fg, p.bevel_dark);
674 }
675
676 // The whole outline, as a reader sees it. Asserted as glyphs because the
677 // shape is the point: an even-weight edge on all four sides, which is what
678 // box-drawing could not give.
679 #[test]
680 fn a_bevel_draws_an_even_outline_and_leaves_the_middle_alone() {
681 let p = palette(None);
682 let mut buf = Buffer::empty(Rect::new(0, 0, 5, 4));
683 paint_bevel(&mut buf, Rect::new(0, 0, 5, 4), Bevel::Raised, &p);
684 let rows: Vec<String> = (0..4)
685 .map(|y| (0..5).map(|x| buf[(x, y)].symbol()).collect())
686 .collect();
687 assert_eq!(rows, vec!["▛▀▀▀▀", "▌ ▐", "▌ ▐", "▄▄▄▄▟"]);
688 }
689
690 #[test]
691 fn pressing_swaps_the_lit_side() {
692 let p = palette(None);
693 let mut buf = buffer();
694 paint_bevel(&mut buf, Rect::new(0, 0, 6, 4), Bevel::Raised.pressed(), &p);
695 assert_eq!(buf[(0, 0)].fg, p.bevel_dark);
696 }
697
698 #[test]
699 fn a_sixteen_colour_terminal_can_lose_the_second_tone() {
700 // Not a failure: one box is still a boundary. The palette says so
701 // rather than the renderer pretending otherwise.
702 let flat = Palette {
703 bevel_dark: Color::Indexed(15),
704 ..palette(None)
705 };
706 assert!(!flat.two_tone());
707 assert!(palette(None).two_tone());
708 }
709
710 #[test]
711 fn an_edge_costs_a_cell_on_every_side() {
712 let p = palette(None);
713 let mut buf = buffer();
714 let inner = frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
715 assert_eq!(inner, Rect::new(1, 1, 4, 2));
716 // Flat takes no cells, because it draws no edge.
717 let same = frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Flat, &p);
718 assert_eq!(same, Rect::new(0, 0, 6, 4));
719 }
720
721 #[test]
722 fn sixteen_colours_carries_depth_in_the_glyphs_instead() {
723 // Colour cannot separate raised from well here: the fill collapses on
724 // most themes and an edge vanishes on all of them. The frame has to
725 // say it some other way or the two become the same box.
726 let p = Palette {
727 fidelity: Fidelity::Ansi16,
728 ..palette(None)
729 };
730 assert!(p.needs_glyph_depth());
731 let mut raised = buffer();
732 frame(&mut raised, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
733 let mut well = buffer();
734 frame(&mut well, Rect::new(0, 0, 6, 4), Depth::Well, &p);
735 assert_eq!(raised[(0, 0)].symbol(), DOUBLE.top_left);
736 assert_eq!(well[(0, 0)].symbol(), LIGHT.top_left);
737 assert_ne!(raised[(0, 0)].symbol(), well[(0, 0)].symbol());
738 }
739
740 #[test]
741 fn above_sixteen_colours_the_glyphs_stay_out_of_it() {
742 // The doubled fallback must not fire where colour already works, or
743 // every modern terminal gets a heavier frame it did not need. What it
744 // gets instead is the half-block bevel.
745 for f in [Fidelity::Ansi256, Fidelity::TrueColor] {
746 let p = Palette {
747 fidelity: f,
748 ..palette(Some(Color::Indexed(4)))
749 };
750 assert!(!p.needs_glyph_depth());
751 let mut buf = buffer();
752 frame(&mut buf, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
753 assert_eq!(
754 buf[(0, 0)].symbol(),
755 BEVEL.top_left,
756 "{f:?} got a heavier frame"
757 );
758 assert_ne!(buf[(0, 0)].symbol(), DOUBLE.top_left);
759 }
760 }
761
762 // Raised and well are both bevels and differ only in which way they are
763 // lit, so above sixteen colours they draw the same glyphs and the tones
764 // carry the difference. That is exactly what stops holding at Ansi16, and
765 // why the doubled set exists.
766 #[test]
767 fn colour_alone_separates_raised_from_well_where_it_can() {
768 let p = palette(Some(Color::Indexed(4)));
769 let mut raised = buffer();
770 frame(&mut raised, Rect::new(0, 0, 6, 4), Depth::Raised, &p);
771 let mut well = buffer();
772 frame(&mut well, Rect::new(0, 0, 6, 4), Depth::Well, &p);
773 assert_eq!(raised[(0, 0)].symbol(), well[(0, 0)].symbol());
774 assert_eq!(raised[(0, 0)].fg, p.bevel_light);
775 assert_eq!(well[(0, 0)].fg, p.bevel_dark);
776 }
777
778 #[test]
779 fn detection_defaults_generously_and_only_downgrades_on_evidence() {
780 assert!(Fidelity::default().separates_depth());
781 assert!(Fidelity::TrueColor.separates_depth());
782 assert!(Fidelity::Ansi256.separates_depth());
783 assert!(!Fidelity::Ansi16.separates_depth());
784 }
785
786 // Sixteen colours is reached by naming a console, never by failing to
787 // recognise a terminal. `COLORTERM` is stripped by ssh and by every
788 // multiplexer, so an unrecognised name carries no evidence at all, and a
789 // caller quantising its palette off this answer would flatten a whole theme
790 // on the strength of it.
791 #[test]
792 fn an_unrecognised_terminal_is_assumed_capable() {
793 let f = Fidelity::from_env;
794 assert_eq!(f("", "foot"), Fidelity::TrueColor);
795 assert_eq!(f("", "xterm"), Fidelity::TrueColor);
796 assert_eq!(f("", "screen"), Fidelity::TrueColor);
797 assert_eq!(f("", ""), Fidelity::TrueColor);
798 }
799
800 #[test]
801 fn a_console_that_really_has_sixteen_colours_is_named() {
802 let f = Fidelity::from_env;
803 assert_eq!(f("", "linux"), Fidelity::Ansi16);
804 assert_eq!(f("", "vt100"), Fidelity::Ansi16);
805 assert_eq!(f("", "dumb"), Fidelity::Ansi16);
806 }
807
808 #[test]
809 fn a_terminal_naming_its_depth_is_taken_at_its_word() {
810 let f = Fidelity::from_env;
811 assert_eq!(f("", "xterm-256color"), Fidelity::Ansi256);
812 assert_eq!(f("", "screen-256color"), Fidelity::Ansi256);
813 assert_eq!(f("", "xterm-direct"), Fidelity::Ansi256);
814 // And a claim of 24-bit beats the name, which is only ever a floor.
815 assert_eq!(f("truecolor", "xterm-256color"), Fidelity::TrueColor);
816 assert_eq!(f("24bit", "linux"), Fidelity::TrueColor);
817 }
818
819 #[test]
820 fn a_region_too_small_for_an_edge_is_left_alone() {
821 let p = palette(None);
822 let mut buf = buffer();
823 let inner = frame(&mut buf, Rect::new(0, 0, 1, 1), Depth::Raised, &p);
824 assert_eq!(inner, Rect::new(0, 0, 1, 1));
825 }
826 }
827