Skip to main content

max / makeover-tui

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