Expand description
The terminal renderer for makeover_layout.
Named for the target and not for ratatui, the same way
makeover-immediate is named for the mode and not for egui.
§What a terminal costs
Geometry, not colour. Above sixteen colours colour separates every depth the vocabulary has. The two cases that still collapse at truecolor are themes whose raised surface is already white, so the well’s lightening clamps onto its face; those render identically in a browser.
An edge occupies a whole cell on each side. A cell is roughly 8x17
pixels, so a one-pixel bevel becomes something an order of magnitude
heavier, which is why frame hands back a shrunk Rect instead of
pretending the region survived intact. There is nowhere to put a corner
radius, so radius_control and radius_container mean the same thing here.
A fill can only begin and end on a cell boundary. That is the constraint to
design against: it does not improve and it is not detectable.
What it does not mean is that the shape inside the cell stops mattering.
Half of a cell is still addressable, and a bevel drawn in half-blocks reads
as a lit edge where the same bevel in box-drawing reads as a line: ─ and
│ are one stroke through the middle, identical on all four sides, saying
nothing about where the light is. Half-blocks also make the two corners
where light meets shadow expressible, since a glyph that fills half a cell
leaves the other half to the second tone.
§Where fidelity does matter
At Fidelity::Ansi16 the depth vocabulary collapses outright: a well
cannot be filled distinctly on most themes and a bevel loses an edge on
every one of them, so a raised card and a well both read as a single-tone
box. Colour cannot carry the distinction, so frame carries it with the
glyphs instead.
Above that, colour carries it and the glyph fallback never fires.
Palette::shows is not a low-colour workaround. It is a correctness check
that a fill will be visible against what is behind it, and at truecolor it
fires on exactly the clamping themes, which is when it should.
§Overlays, selection and the focus ring
Palette::fill answers Fill::Overlay, so
Depth::Overlay needs nothing beyond the
route from a description. A test asserts that route, because a route nothing
exercises is one a refactor can quietly lose.
Theme::selection_on and Theme::focus_ring are DERIVED rather than
authored, and the direction is one-way: an authored key can fall back to a
derivation and break no theme on disk, while a key this crate started
requiring would break every theme that lacks it. So the theme format does not
change, and the promotion stays available for a theme that ever needs to tune
either. Without them a port does selection with REVERSED for want of an
on-accent foreground, and spends makeover’s border-strong on a focus ring,
which is a divider at 1.63:1 on Akari Dawn.
§The table
table is the one thing here that draws content rather than a surface. It
is a mapping layer over ratatui::widgets::Table rather than a table
implementation, because ratatui already lays tracks out, draws a header,
highlights a row and scrolls. What it has no answer for is content
measurement and narrowing, and those are what the module is.
§piece, not widget
makeover-layout owns Region::Widget, the tier between a primitive and
Region::Widget: a named assembly of primitives that each renderer draws
its own way. That is host-agnostic and sits above every renderer.
This crate’s piece module is the opposite end of the same stack:
renderer-local, the answer to what a badge looks like in cells, taking a
description plus what only a terminal knows. Two different things must not
wear one word, least of all in a crate that has to implement the tier. Its
types are piece::PieceStyle, the marks, and piece::Ink, the marks
and the Palette’s tones resolved together.
§Every colour is in the palette
Palette holds the surfaces and bevel pair a frame needs and the
Tones text and tables are drawn in. The styles hold metrics and marks
only. A tone the palette leaves empty is said with a modifier instead, so a
terminal with no colour to spend still separates every role.
§The vocabulary’s members are drawn by the host
A meter, a control, a figure, facts, a form field and a chart are drawn by
quasi-tui, which owns those types, on top of piece::Ink and text.
This crate draws what every terminal app needs whether or not it speaks
that vocabulary: surfaces, tables, badges, waits and wrapped text.
§Substitution is renderer policy
Substituting one intent for another belongs to a renderer, never to the
description. Falling back from Fill::Well to Page is an answer for a
renderer that can always paint a colour; here it is wrong, because the page
is the surface a well is usually cut into, so the substitution produces the
exact invisibility it was meant to avoid. makeover-immediate wants that
fallback and this renderer does not.
Re-exports§
pub use makeover_layout;
Modules§
- piece
- The pieces every terminal app draws, drawn once.
- table
- Column layout and row structure for tables.
- text
- Words into cells.
Structs§
- Palette
- The resolved colours this renderer needs.
- Tones
- The colours text, controls and tables are drawn in.
Enums§
- Fidelity
- How many colours the terminal can actually show.
- Motion
Preference - Whether the reader asked for less motion, as
activity_littakes it. Whether the reader has asked for less motion, as their platform reported it.
Functions§
- activity_
lit - Whether the activity mark is lit, this far into a wait.
- frame
- Draw a region at a given
Depthand return the area left for content. - paint_
bevel - Paint a two-tone edge around the outside of
area.