Skip to main content

max / makeover-tui

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