//! The renderer-agnostic half of the make-family design system.
//!
//!
//!
//! `makeover` answers *what colour*, and varies by theme. `makeover-geometry`
//! answers *how much space*, and varies by density and surface. This crate
//! answers *what the thing is*, and varies by nothing.
//!
//! # The deferral rule
//!
//! A description names intents and relationships, never values. Say
//! [`Fill::Raised`], never `#D9DDF4`. Say `Gap::Peer`, never `6px`. What is
//! left once colour and spacing are deferred is **composition**: which edges
//! are lit, what inverts on press, what nests in what.
//!
//! The constraint that shapes all of it: a renderer that can only paint
//! rectangles has to be able to express the result. egui has no
//! `box-shadow: inset` and one stroke per widget with no per-side control; a
//! terminal has box-drawing characters and one cell of resolution, and cannot
//! draw a two-tone lit edge at all. A description that assumes per-side edges
//! is a CSS description wearing a neutral name. So this crate names the
//! *intent* — this region is a well — and each renderer chooses an expression
//! it can actually produce, including dropping half of one.
//!
//! # Scope
//!
//! Depth came first: the bevel and the surfaces it shapes. That much was
//! settled the hard way — the vocabulary here was read off audiofiles'
//! `ui::theme` and `ui::widgets`, which are the only implementation written
//! by a consumer with no CSS, then checked against both webview apps. All
//! three agreed once Balanced Breakfast's fills were corrected.
//!
//! 0.2.0 adds the rest of the description, each member drawn the same way,
//! from what the three apps already hand-write rather than from a taxonomy:
//!
//! - Components. [`Token`] (badge against chip), [`Notice`] (toast against
//! banner), [`RowPart`], [`Heading`], [`Selector`], [`Readiness`], and
//! [`Tone`], which is the one intent family they share.
//! - Schemas. [`Field`] for forms and [`Column`] for lists and tables.
//! - Structure. [`Region`] for the parts of a screen, [`Arrangement`] for how
//! a screen is put together.
//!
//! **Validation** was absent on purpose here, on the grounds that neither app
//! had a shared story. That reasoning is retired — see 0.11.0 below, which is
//! where the constraints arrived and why the argument did not survive contact
//! with what the apps were measured to do.
//!
//! 0.3.0 closes a gap the first real adoption found, which is what adopting
//! against goingson first was for. [`Selector`] described only the *chosen*
//! option, so an unchosen one fell through to [`Depth::Flat`] and no renderer
//! drew it; goingson's tab strip recesses its unchosen tabs by hand and could
//! not delete the line, because being recessed is *why* the chosen tab reads as
//! coming forward. So [`Selector::unchosen`] joins `chosen`, and saying it
//! needed [`Fill::Sunken`] and [`Depth::Sunken`]: a surface set back by colour
//! with no edge, which is neither a well nor level-with.
//!
//! 0.7.0 adds [`State`], the interaction axis, closing the gap that adopting
//! against three apps rather than one made visible. The description named
//! rest and, through [`Depth::pressed`], pressed. It named neither focus nor
//! disabled, so `makeover-webview` emitted a hover rule and stopped, and each
//! consumer completed the primitive from outside by out-specifying a rule it
//! did not own: 19 such rules in goingson, 21 in the MNW server, a further set
//! in Balanced Breakfast, and three focus rings that do not match. The axis is
//! deliberately two members wide, because hover and pressed belong where they
//! already are. [`State`]'s own docs carry that argument.
//!
//! 0.8.0 finishes [`Field`], which described a field well enough to label it and
//! not well enough to draw it. Writing `makeover-webview`'s form emitter found
//! three things missing and the renderer supplied all three from outside: the
//! current value, a select's options, and the placeholder. Two of those move
//! here and one does not.
//!
//! - [`Field::placeholder`] is user-facing text sitting beside `label` and
//! `hint`. There was never a reading on which it was renderer state; it was
//! outside only because adding a field to a published struct is breaking.
//! - [`Field::options`] moves because every renderer needs them and each was
//! going to invent its own shape. [`Choice`] is the shape `makeover-webview`
//! already arrived at, taken as-is rather than redesigned.
//! - The current value stays renderer-side and is not coming here. It is the
//! one of the three that is genuinely state: a webview reads it out of the
//! DOM, an immediate-mode renderer holds a `&mut` to the app's own field, and
//! a description that carried it would be a form model.
//!
//! 0.9.0 opens [`RowPart`], which was the last closed enum in the vocabulary,
//! and adds [`RowPart::Tokens`]. Both halves come from the same finding, made
//! by the first two real screens described through the router rather than by
//! reading a stylesheet.
//!
//! A goingson project card carries two trailing badges, a type and a toned
//! status; a contact card carries a primary email *and* a strip of tags. `Meta`
//! is one slot and one string, so both ports joined their facts with a
//! separator and lost what the second one was: a status reads as text where it
//! used to read as colour. [`Token`] already says exactly the right thing — a
//! small labelled thing with a kind, a tone and an optional action — and could
//! only ever be a node in its own right, never inside a row.
//!
//! So the missing thing was permission rather than a concept. `Tokens` is that
//! permission, and `#[non_exhaustive]` arrives with it so the next member is not
//! a lockstep event across three renderers. The pairing is the point: this
//! enum's own consumer in `makeover-webview` carried a comment predicting it
//! would stop compiling one day, which is a lockstep break written down and
//! waited for rather than prevented.
//!
//! Balanced Breakfast was checked before the member was added, because one
//! consumer wanting something is not evidence. It packs a count and two icon
//! buttons into the same single `Meta` slot while leaving `Actions` empty, so
//! the slot was already straining under a second consumer for a different
//! reason.
//!
//! 0.10.0 adds [`Meter`], a proportion carried as a pair rather than as a
//! percentage. Its own docs carry the argument; the short form is that the
//! percentage shape had already been tried in goingson and had already needed a
//! companion flag to recover what rounding and clamping threw away.
//!
//! 0.11.0 is four members from the quasi proving ground, batched into one
//! release because pre-1.0 a minor is breaking and a cascade is nine repos.
//! Three findings that arrived with them turned out not to belong here at all:
//! this crate has no notion of an action, a route or a destination, so anything
//! asking what a control *calls* was never the vocabulary's to say.
//!
//! - [`Figure`], a value with a caption. goingson had five of them across five
//! screens with five class vocabularies for the one shape, which is the
//! divergence this crate exists to end, sitting in plain sight and counted for
//! the first time.
//! - [`RowPart::Proportion`], so a [`Meter`] can sit in a row. `Meter` reached
//! two of its seven sites at 0.10.0 and the other five are row-shaped. Exactly
//! [`RowPart::Tokens`]'s problem with a different payload, and it takes
//! `Tokens`' answer: the part carries the description of a bar, not a node.
//! - [`Field::max_length`], [`Field::min`] and [`Field::max`], joining
//! [`Field::required`], which had been sitting here as the sole constraint
//! while the header above claimed there were none. The set stops before
//! `pattern`, which fails the renderer test and is one site in one app.
//! - [`FieldKind::File`]. Every host has an honest answer — a native picker, an
//! `Public : Anyone can see this repository` in git settings,
//! the same shape in the project-basics AI tier and the cart's currency
//! conversion, `Mislabeled (wrong AI tier or category)` in the report modal.
//! The item-type and item-pricing wizards give it its own span. The described
//! screens fold it in miniature: `Every 15 minutes (recommended)`. One fact,
//! six spellings, and the folding is what says the member was missing.
//! - **It is not a price**, and the count is what decided that rather than
//! taste. The site that asked carries a name, a price and a description; the
//! tree's other three priced tier lists are not option lists at all — each
//! card carries its own submit, so each is a region with a heading, a fact
//! and an act and is sayable today. A price member would have one consumer
//! and would mean growing a money type this crate does not have.
//! - **Where it is drawn is [`unavailable`](Choice::unavailable)'s question met
//! a third time**, and it takes the same answer: its own element in a radio
//! group, run into the option's own text in a ``, a row of its own on
//! a terminal. A rule the crate had already paid for twice is the cheapest
//! evidence that one member is the right size.
//! - **This does not reopen 0.35.0.** That release ruled [`Candidate`] a type
//! of its own rather than a `Choice` with a second line, and it stays one:
//! what separates them is that an option is picked out of a set the user can
//! see whole and a candidate is offered out of one nobody can see. The
//! argument 0.35.0 made against a member here — that it would land on every
//! option list including the ones with nowhere to draw it — is answered by
//! the two sentences above: it lands as `None` on the ones that do not ask,
//! and the one host with nowhere to draw it already had a rule.
//!
//! 0.38.0 describes the theme picker. [`FieldKind::Theme`], [`ThemeChoice`],
//! [`ThemeVariant`], [`Contrast`], [`Field::themes`] and [`Field::follows`] are
//! one screen's control named as furniture. Ruled by Max 2026-08-28
//! (`70028e00`), against the grouped option list that was the obvious answer.
//!
//! - **The measurement is what rejected `Choice::group`.** `optgroup` appears
//! at exactly one live site in the tree, in the one app not yet ported, and
//! the non-theme grouping count is zero. Two apps' grouped pickers were
//! deleted by their ports and both described replacements dropped the
//! grouping on purpose. So the thing that recurs is not option lists that
//! group; it is this picker, hand-written three times.
//! - **Two of the four facts cannot come from an app.** A theme's group and its
//! measured contrast tier come off the resolved theme, so the layer that
//! loaded it is the only party holding them. `Choice::new(id, "{name}
//! ({variant})")` is what all three apps wrote, and it turns structure into
//! prose and drops the tier entirely.
//! - **The order is the grouping**, rather than a returned list of groups. A
//! renderer that draws headings walks the run of one variant; one that cannot
//! still gets the useful order, and neither shape is made to flatten the
//! other's.
//! - **[`ThemeVariant`] is spelled twice on purpose.** This crate takes no
//! dependencies, so it cannot name `makeover::Variant`, and a renderer that
//! groups needs the groups as values. The adopter converts, in a three-arm
//! match.
//! - **The cost is stated rather than found later.** This is the first member
//! here that names a subject instead of a shape of answer. It stays narrow: a
//! theme picker, not a general host-resolved list. A second such list is when
//! the generalisation gets measured.
//!
//! 0.35.0 gives a suggestion its second line. [`Candidate`] is the entry in a
//! field's suggestion list: a value, a label, and the [`detail`] that orients
//! it. Ruled by Max 2026-08-21 (`1fcf2e9b`) after the combobox member shipped
//! and was then held against the two sites it was designed from, which is an
//! order worth not repeating.
//!
//! - **A candidate is not a [`Choice`], and the difference is in the reading
//! rather than the writing.** Both submit one string and read as another. An
//! option is picked out of a set the user can see whole; a candidate is
//! offered out of a set nobody can see, so it has to say what tells it from
//! its neighbours. Both measured sites draw that second string today, by
//! hand, in a second span.
//! - **It is its own type rather than a member on [`Choice`].** `Choice` is the
//! most-consumed struct in the vocabulary and the member would have landed on
//! every option list in the tree the day it shipped, including the ones with
//! nowhere to draw it.
//! - **[`Candidate`] is `#[non_exhaustive]` from birth**, which is the whole of
//! what 0.28.0 cost and is not being paid twice.
//! - No `unavailable`. A suggestion that cannot be picked is a row a route
//! should not have offered.
//!
//! [`detail`]: Candidate::detail
//!
//! 0.34.0 gives an interval a description. [`FieldKind::Interval`] and
//! [`Field::upper_name`] say that two values are one question with two ends.
//! Ruled by Max 2026-08-21 against audiofiles' six filter axes and the MNW
//! server's price pair, which is HTML saying the grouping in an ARIA
//! `role="group"` and nowhere else.
//!
//! - **The ends constrain each other, and nothing else in the vocabulary could
//! say so.** Two [`FieldKind::Number`] fields are two questions: a renderer
//! draws two labels with no relationship, and [`Field::error`] attaches to one
//! side of a fault that belongs to both.
//! - **It is not [`FieldKind::Range`]**, which is the reading to resist and the
//! same resistance `Range` needed against `Number`. A range is one value
//! inside an extent; this is two, and the extent is a bound on each rather
//! than the question's meaning.
//! - **Both names are stated rather than derived.** Measured the same day, the
//! two sites disagree about affix order -- `bpm_min`/`bpm_max` against
//! `min_price`/`max_price` -- so any rule renames one of them. One member
//! instead of a naming convention this crate would own forever, and which
//! member a name sits in is what says which end it is.
//! - The crossing rule is not enforced, exactly as [`Field::min`] is not. What
//! the description buys is one place to report the fault rather than two.
//!
//! [`Field::upper_name`] is a member on a struct that is not
//! `#[non_exhaustive]`, so this is a formal break for crates.io and zero
//! call-site edits in the tree: every literal builds on a constructor.
//!
//! 0.33.0 gives a number its unit. [`Field::unit`] carries what the value is
//! measured in, and [`FieldKind::measurable`] says which kinds read it. Decided
//! by Max 2026-08-21 (`32215e21`) against eight sites across four audiofiles
//! files that had each independently put the unit in parentheses at the end of
//! the label -- three of them written while the gap was a known open question.
//!
//! - **A unit is a fact about the value, not part of the question's name.** The
//! two readings come apart the moment anything reads a field back rather than
//! drawing it, which is the argument that decided it.
//! - **The convention it replaces froze the worst placement.** A label is the
//! sentence above the control, so unit-in-label was the same answer on every
//! host -- including the host that had somewhere better, since egui's slider
//! already draws a suffix beside the readout, which is what these controls did
//! before they were described.
//! - A string rather than a closed family, which is [`Curve`]'s argument
//! inverted and correctly so: a curve is a mapping this crate computes, and a
//! unit is a symbol it only carries. The measured set is `GiB`, `dBFS`, `s`
//! and `ms`, and this crate does not know what the next consumer measures in.
//!
//! Additive: absent is what every field meant before.
//!
//! 0.32.0 is the slider's real shape. **The data of a slider is a fraction and
//! a function taking numbers to numbers** (Max, 2026-08-21), so [`Curve`]
//! arrives and [`Field::curve`] with it. [`Field::min`] and [`Field::max`] were
//! never the control's extent: a slider's extent is always 0 to 1, and the
//! bounds are `f(0)` and `f(1)`. Linear is the constant-slope case, which is
//! why the mapping was invisible — under it the extent and the bounds coincide
//! numerically — and why four renderers each hard-coded it without anyone
//! deciding to.
//!
//! - It is not a scale flag on a range. The question this replaced asked
//! whether to name a decoration; what was unnamed is half of what a slider
//! *is*, which is why the member is a mapping and not an adjective.
//! - **The step spacing rides on the curve.** Max, in the same breath: if the
//! family is prescriptive anyway, the granularity belongs in it. On a slider
//! the two are one decision, and holding them apart is what let a 0-to-1
//! threshold ship as a two-position control. [`Field::step`] narrows to the
//! *typed* kinds, where there is no mapping to decide with.
//! - A closed family rather than `fn(f64) -> f64`, which is the literal reading
//! and does not cross the description boundary: a fn pointer cannot be
//! emitted into a browser and cannot be compared or hashed meaningfully,
//! which [`Field`] needs. Nothing measured wants an arbitrary function — one
//! non-linear shape across five controls, and no second shape.
//! - The mapping computes here rather than in each renderer
//! ([`Curve::value_at`], [`Curve::position_of`]), so a terminal's bar, an
//! egui slider and a browser's input cannot disagree about where a value
//! sits. This crate otherwise describes rather than computes; four copies of
//! two formulas is the cost of holding that line here.
//!
//! Additive: [`Curve::Linear`] with no step is what every range meant before,
//! so no existing site changes meaning. Consumers: audiofiles' ADSR envelope
//! (three logarithmic times) and its storage cap picker.
//!
//! 0.31.0 finishes the file field. [`FieldKind::File`] arrived at 0.11.0
//! carrying neither an accepted-types list nor a multiplicity flag, and said so
//! in its own doc: `accept` appeared at zero sites in either app, and a member
//! added for a case nobody has is a member designed against nothing. That count
//! was taken over goingson and Balanced Breakfast, and the MNW server is a third
//! consumer with 14 `accept` lists across 10 templates and 4 of its 16 file
//! inputs marked `multiple`. The reasoning was right and the measurement went
//! stale, so [`Field::accept`] and [`Field::multiple`] arrive now.
//!
//! - [`Accepted`] is an enum rather than the comma-joined string the templates
//! hold, because the list is read twice and only one of the readings is
//! filtering. The other is which disclosure to offer — a preview, a duration,
//! a waveform — and a renderer deciding that from raw strings is three
//! renderers each writing a media-type parser. [`Accepted::family`] answers it
//! once. All three shapes are in the measured sites and none can be dropped:
//! `image/*` is a [`Family`], `image/jpeg` and `text/csv` are a
//! [`Type`](Accepted::Type), and `.zip`, `.tar.gz` and `.clap` are a
//! [`Suffix`](Accepted::Suffix). One site carries `.csv,text/csv`, which is
//! both in one list.
//! - A suffix carries no family and this crate will not infer one. `.mp3` is
//! audio in fact, and a table here saying so is a mapping that rots in a
//! published crate and is wrong for the first container format someone hands
//! it. A call site that wants the disclosure writes the family or the media
//! type, which is what the sites offering previews already do.
//! - There is one upload shape, not one per type. What a media upload shows
//! beyond a plain one is disclosure layered on this shape, which is why the
//! accept list is load-bearing beyond validation and why nothing here names a
//! media upload as its own kind.
//! - Progress is not a member and needs none. An upload in flight is a control
//! in flight with a number attached, so it is [`Awaiting`] with the file's
//! length as its [`amount`](Awaiting::amount) — the case that type's own doc
//! names. Where the bytes go is an address, and this crate holds none; that is
//! the router's [`Action`], which the field already points at when it writes
//! on its own.
//!
//! # Reach, focus and the focus ring
//!
//! Three terms, and no others, for what 0.19.0 moved out of the description.
//! **Reach** is which things can take focus and in what order; a browser reads
//! it off the document, a TUI derives it from draw order, egui from its own id
//! stack. **Focus** is which reached thing has the keyboard right now: the
//! renderer's, live, never described and never round-tripped through a
//! description. The **focus ring** is the visible cue; the token (`focus-ring`,
//! derived by `makeover` from the action colour) is the one shared artifact and
//! the drawing is the renderer's. Retired as names for any of this: "focus
//! stroke", "focus cue", "wants focus". "Caret" is a different thing — the text
//! cursor inside a field — and keeps its name.
//!
//! # The three tones, and what a colour claims
//!
//! One rule, settled 2026-08-16, for how colour says whether a thing can be
//! used. Every renderer answers to it, and it is stated here because the
//! description is what names the intents.
//!
//! | the thing | intent |
//! |-----------|--------|
//! | active, emphasised, the thing itself | `content` |
//! | inactive but usable: it still answers a press | `content-secondary` |
//! | inert: disabled, or not a control at all | `content-muted` |
//!
//! `content-muted` is the one with a claim in it. [`State::Disabled`] resolves
//! to it, so a live control wearing it is telling the user it will not answer —
//! and being wrong about that is worse than being quiet, because the user's
//! response is to stop trying. A sortable column heading that was never sorted,
//! and every unchosen option in a radio group, both read as dead lists that way;
//! those are the two this rule was written out of. What is legitimately muted is
//! a caption, a hint, a placeholder, a meter's reading, an axis label: text that
//! was never going to answer anything.
//!
//! The three are one ramp and not three colours. `makeover`'s `Emphasis` derives
//! the quieter two from the ink, so "one step back" means the same distance in
//! every theme and a renderer cannot land between them by picking its own.
//!
//! # First paint is final paint
//!
//! One rule, settled 2026-08-16. Nothing may change size or position after it is
//! first drawn, and nothing may stand in for content that has not arrived yet.
//! Both halves are absolute.
//!
//! It is stated here, rather than left to each renderer, because a renderer can
//! only reserve space the description gave it enough to size. A member whose
//! size depends on its content therefore owes whatever makes it sizeable while
//! the content is still absent, and that is the second admission test for a new
//! member: not only does it compose something this crate already names, it can
//! be laid out before it is filled.
//!
//! The mechanism is a reservation, and [`Sort`]'s caret is the worked example.
//! The caret is drawn into a box its own width whether or not the column is
//! sorted, so pressing a heading cannot reflow the row it sits in. The box names
//! no magnitude, which is what keeps it out of `makeover-geometry`'s territory.
//! Reserve from what is known; never discover geometry from what has not
//! arrived.
//!
//! The trap is an `Option` that means "not yet". [`Readiness::Pending`] is the
//! honest way to say a region is still waiting. An optional *measurement* is
//! not: a count that shows up later widens the text that prints it and moves
//! everything beside it, which is the reflow this rule exists to forbid. So an
//! `Option` on a measurement means the host will never know it — a property of
//! the query, fixed for the life of the screen — and a renderer sizes for the
//! answer it was handed rather than for the one it hopes is coming.
//!
//! # Any width, one answer
//!
//! The sibling of the rule above, and settled the same day. That one is
//! independence from *when*; this one is independence from *how you got here*.
//!
//! A rendering is a pure function of the description and the viewport. The same
//! description at the same width is the same output, whatever widths came
//! before it. No renderer may carry geometry across frames, and none may narrow
//! by counting.
//!
//! The failure this forbids is ordinary enough to be the default everywhere
//! else: a page that hides its sidebar below some width, remembers that it hid
//! it, and does not bring it back the same way. Layout there is a function of
//! `(width, history)`, so dragging a window to 900 wide is a different screen
//! depending on whether you came from 1400 or from 600. Nobody chose that; it
//! is what measuring and remembering produce.
//!
//! The mechanism is [`Width`] for what grows and [`Priority`] for what drops.
//! Both are declared, both are read off the description, and neither needs a
//! measurement. A renderer narrows by raising a cutoff over a total order,
//! never by counting what fits and stopping — `makeover-tui`'s table states
//! that as its own rule and tests it, and `makeover-webview` reaches the same
//! place with `@media` and `display: none`, which is path-independent by
//! construction because CSS has nowhere to keep the previous width.
//!
//! Two things follow for anything new. A member that would need last frame's
//! size to lay out this frame is refused, the same way a member that cannot be
//! sized before it is filled is refused. And a fact about what disappears
//! belongs in the description, because a host that has to infer it can only
//! infer it from a measurement.
//!
//! # Where the description stops
//!
//! The rule is that a member is added when an app needs a fact the vocabulary
//! cannot state, and refused when what it wants is presentation it should be
//! asking a renderer for. That is the whole test. It is not a quota, and the
//! goal is every screen described.
//!
//! ## What the timeline refusal got wrong, 2026-08-15
//!
//! This section used to read "a day-plan timeline, a kanban board and a
//! calendar are not describable here and will not become describable", and it
//! propagated: 12 files across three apps, three libraries and the design wiki
//! cited it, including audiofiles and the MNW server, neither of which has a
//! timeline. It is withdrawn, and [`Track`] is the member it was refusing.
//!
//! The error was pricing. The argument assumed a timeline needs a component
//! library's worth of vocabulary, and nobody measured it. Held against
//! goingson's `day-planning-render.js`, the members it actually needed and
//! could not get were two integers: where a thing starts, and how long it
//! lasts. Labels, gridlines, item bodies and tones were all furniture this
//! crate already named. A refusal that expensive should have carried a
//! measurement, and did not.
//!
//! The reasoning underneath it survives and is still the test: slot heights,
//! gridline colour, how overlapping things stack, which hour scrolls into view.
//! Those are presentation, they stay the renderer's, and [`Track`] carries none
//! of them. What changed is the conclusion, not the principle.
//!
//! ## The other two, measured 2026-08-15
//!
//! The same sentence refused a kanban board and a calendar. Both were counted
//! the way the timeline should have been, and neither came out where the
//! refusal put it.
//!
//! **Kanban: one member, and it is [`Region::Columns`].** Held against
//! goingson's `tasks-kanban.js`, every card fact was already sayable — title,
//! project, due date, the blocked and unblocks badges, subtask progress, the
//! open action and the context menu are `Row`'s existing parts. A column is a
//! heading, a count and a list. What nothing could say was that the columns are
//! *peers*: [`Arrangement`] offers list-detail and sidebar-content, and a board
//! described as either is a lie about the screen. Dragging a card between
//! columns never entered into it — a drop's effect is "set status", a discrete
//! action `Row`'s menu already carries, and the drag itself is affordance.
//!
//! **Calendar: no members, no consumer, and a sharper reason (Max,
//! 2026-08-15).** The month grid's primacy in calendar apps is an artifact of
//! paper: paper cannot be queried, so it has to show every day at once as a
//! fallback index. Routes, search and ranking do that job better, which is the
//! argument `events-calendar.js` already lost to a segmented list on
//! 2026-08-11.
//!
//! Three jobs survive that reasoning, and only one of them needs a grid:
//!
//! 1. **Spans across days** — a stretch of leave, a trip, a sprint. You cannot
//! see "away the 3rd to the 17th" in a list without diffing dates. This is
//! [`Track`] with [`Unit::Days`], not a calendar, and
//! [`Track::days`] is it.
//! 2. **Density at a glance** — which weeks were heavy. That is a heatmap, and
//! goingson describes both of its heatmaps as lists already.
//! 3. **Weekday periodicity** — "every other Tuesday", "the 15th is a
//! Saturday". This is the only job that needs the seven-column wrap, because
//! alignment is the whole of what makes it visible.
//!
//! So the open question is not "is a calendar describable" but "is job 3 worth
//! a member", and nothing in the tree asks for job 3 yet. GoingsOn
//! quasicoherent `4a1237b6`.
//!
//! A month grid renders today as a
//! [`Table`](crate::Column): seven weekday columns, weeks as rows, blanks for
//! the offset. goingson's monthly review reached this conclusion before this
//! note did and describes its month as a list of days that had something on
//! them, marking today with an ordinary badge. What the tree actually contains
//! is two completion heatmaps — one scalar per day — and no calendar at all:
//! `events-calendar.js` was deleted 2026-08-11 in favour of a segmented list,
//! and no MNW template mentions one. So the refusal was defending a screen
//! nobody has. If one is built, measure again; the facts already fit and only
//! the grid's shape would be in question.
//!
//! The pattern worth keeping from all three: one sentence refused three things
//! for one reason, and the reason was wrong three different ways. Count the
//! members.
//!
//! [`Region::Bespoke`] remains for the genuinely app-owned, and its
//! justification does not depend on the withdrawn claim. The
//! description names the *place* and the app owns the contents, so a screen
//! containing a timeline is still a whole screen and still routable. Without
//! it, the four goingson screens that make the app worth using would need a
//! second, undescribed path beside the router, and two paths is how a
//! vocabulary starts drifting from its app again.
//!
//! [`Region::Widget`] sits between that limit and the primitives, and it does
//! not move the limit. A widget is an assembly of members this crate *already*
//! has, under a name a renderer may or may not recognise. Anything that needs a
//! member the vocabulary does not have is still a finding about the vocabulary
//! or still bespoke; naming an assembly buys no new expressive power, which is
//! exactly why it is safe to let the set grow outside this crate.
#![forbid(unsafe_code)]
/// A colour intent this crate refers to but never resolves.
///
/// The string is the token name `makeover` publishes, so a renderer can look
/// it up without this crate knowing what colour came back.
pub trait Intent {
/// The `makeover` intent token this resolves against.
fn token(self) -> &'static str;
}
/// Which way the light falls across a two-tone edge.
///
/// The whole content of a bevel, once colour and thickness are deferred. The
/// light is always assumed to come from the top left: every consumer measured
/// agreed on that and none of them ever varied it, so it is an invariant here
/// rather than a parameter.
///
/// # The two corners that belong to both edges
///
/// Top-right and bottom-left are where the lit run meets the shaded one, and
/// the description's claim is that they belong to *both*. How a renderer says
/// that is its own business, because the answer is bounded by resolution and
/// not by taste:
///
/// - A terminal cell is roughly 8x17 device pixels, so giving the whole corner
/// to one tone thickens that edge by a cell and reads as one run overrunning
/// the other. A half-cell glyph divides the cell already, so `makeover-tui`
/// splits it and recovers real information. Its box-drawing fallback cannot:
/// a single stroke has no half to give, so there both corners go to dark.
/// - A pixel bevel is a one-point stroke by default, which makes the corner a
/// one-point square. There is nothing to divide — a diagonal seam across one
/// point is sub-pixel, and antialiasing renders it as the blend a mitred join
/// already produces. So `makeover-immediate` mitres and is *not* diverging;
/// it is the same rule at a resolution where the split degenerates.
///
/// Stated here so the difference reads as a decision rather than as drift. A
/// renderer with room to divide the corner should; one without should mitre or
/// pick the shaded tone, and neither is a bug.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Bevel {
/// Lit from the top left: light on top and left, dark on bottom and right.
Raised,
/// The same edge inverted, which is also the pressed state of anything
/// that draws itself [`Bevel::Raised`].
Inset,
}
impl Bevel {
/// The edge intents, as `(top_left, bottom_right)`.
///
/// Split out from any painting because the inversion *is* the idea, and
/// it is the one part every renderer implements identically.
#[must_use]
pub const fn edges(self) -> (Edge, Edge) {
match self {
Self::Raised => (Edge::Light, Edge::Dark),
Self::Inset => (Edge::Dark, Edge::Light),
}
}
/// Pressing inverts. A raised control reads as inset while held.
///
/// Stated here rather than left to each consumer because a cascade can
/// carry a pressed state and an immediate-mode renderer cannot: audiofiles
/// resolves this per call site, eighteen times.
#[must_use]
pub const fn pressed(self) -> Self {
match self {
Self::Raised => Self::Inset,
Self::Inset => Self::Raised,
}
}
}
/// One side of a bevel, named by the intent it takes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Edge {
/// The lit side.
Light,
/// The shadowed side.
Dark,
}
impl Intent for Edge {
fn token(self) -> &'static str {
match self {
Self::Light => "bevel-light",
Self::Dark => "bevel-dark",
}
}
}
/// A surface intent a region is filled with.
///
/// `#[non_exhaustive]`, so a renderer must carry a wildcard arm and a new
/// member is additive rather than breaking. Added 0.4.0, after [`Sunken`]
/// (an additive member, 0.3.0) hard-broke `makeover-tui` and
/// `makeover-immediate` at compile time and left neither able to move until
/// both published. The vocabulary exists to grow and the renderers exist to
/// disagree about how much of it they answer, so growth must not be a
/// lockstep event. The renderer's wildcard is not a hole: [`Fill`] is
/// resolved through a fallible lookup, and a missing intent is answered with
/// structure rather than with a substituted colour.
///
/// [`Sunken`]: Fill::Sunken
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Fill {
/// The page behind everything.
Page,
/// A surface lifted off the page: cards, controls, menus, toasts.
Raised,
/// A surface floating above the page rather than resting on it.
Overlay,
/// The inside of a well.
Well,
/// A surface set back from the one it sits on, by colour and nothing else.
///
/// Not a well. A well is a hole with an edge, and the two are authored in
/// opposite directions: `makeover` derives `surface-well` by inverting
/// against the theme's own content colour, while `surface-sunken` is
/// authored and free to sit darker than raised (goingson's does). Naming
/// only the well left the recessed-with-no-edge surface unsayable, which is
/// what an unchosen tab is: it recedes so the chosen one can come forward,
/// and it carries no bevel of its own.
///
/// Added 0.3.0, from goingson's tab strip, which hand-writes exactly this
/// and could not delete the line because no member described it.
Sunken,
}
// No `fallback` here, deliberately. An earlier cut had `Fill::Well` fall back
// to `Fill::Page` so a consumer on makeover 2.2.0, which has no `surface-well`,
// had something to paint. makeover-tui found that wrong within a day: page is
// the surface a well is usually cut into, so on a terminal that substitution
// produces exactly the invisibility it was meant to prevent, and the right
// answer there is a drawn edge rather than a different colour.
//
// Substituting one intent for another is renderer policy. The description says
// what the region is and stops.
impl Intent for Fill {
fn token(self) -> &'static str {
match self {
Self::Page => "surface-page",
Self::Raised => "surface-raised",
Self::Overlay => "surface-overlay",
Self::Well => "surface-well",
Self::Sunken => "surface-sunken",
}
}
}
/// How a region sits relative to the surface behind it.
///
/// Fill and bevel are named together because naming them apart is what let
/// them disagree. Every consumer measured had at least one region carrying a
/// raised bevel over a recessed fill: audiofiles fixed it in `raised_frame`
/// and recorded the bug in its doc comment, and Balanced Breakfast still had
/// twelve of them a year later. A single name for the pair makes that
/// unrepresentable.
/// `#[non_exhaustive]` for the same reason as [`Fill`], and in the same
/// release: a depth this renderer has no drawing for should cost it a
/// wildcard arm, not a compile error and a wait on someone else's publish.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Depth {
/// Level with its surroundings. No edge.
Flat,
/// A card laid on the panel it sits in.
Raised,
/// A hole in the panel, with content down inside it. For anything the
/// user looks *into*: a table body, a tag tree, a text field.
Well,
/// Set back from what it sits on, by colour alone. No edge.
///
/// The one member carrying a fill without a bevel, so a renderer cannot
/// assume the two arrive together. That is deliberate and it is still the
/// pairing rule: both halves come off the same `Depth`, so they cannot
/// disagree, and here one half is legitimately absent.
///
/// Distinct from [`Depth::Flat`], which has no fill either and inherits.
/// Recessed and level-with are different claims, and only one of them
/// needs a colour.
Sunken,
/// A surface sitting *over* the page rather than in it. A modal, a popover,
/// a menu.
///
/// Takes elevation and no bevel: a surface overlaying the page is lifted
/// off it, and a surface in the page is cut into it. That is the same
/// pairing rule the rest of the enum holds, applied to the one case where
/// the separation is not an edge at all — the lift and the scrim behind it
/// are already saying where the surface is.
///
/// Every renderer had the surface before it had this variant.
/// `makeover-tui` carries `Palette::overlay`, `makeover-immediate` gained
/// `Palette::elevation` at 0.10.0, and `makeover-webview` emits
/// `--elevation-overlay`. What was missing was the route from a description
/// to any of them, which is why this is one variant rather than a feature.
Overlay,
}
impl Depth {
/// The edge this depth is drawn with, if it has one.
#[must_use]
pub const fn bevel(self) -> Option {
match self {
// Sunken joins Flat here, for the opposite reason: Flat has no edge
// because nothing separates it from its surroundings, and Sunken has
// none because its colour is already doing the separating.
Self::Flat | Self::Sunken => None,
// A third reason to have no edge, which is why it gets its own arm
// rather than joining the two above: an overlay is separated by the
// lift and by the scrim behind it, so an edge would be a second
// answer to a question already answered.
Self::Overlay => None,
Self::Raised => Some(Bevel::Raised),
Self::Well => Some(Bevel::Inset),
}
}
/// The surface this depth is filled with.
///
/// [`Depth::Flat`] has no fill of its own: it inherits whatever it sits on,
/// which is the difference between level-with and painted-the-same-colour.
#[must_use]
pub const fn fill(self) -> Option {
match self {
Self::Flat => None,
Self::Raised => Some(Fill::Raised),
Self::Well => Some(Fill::Well),
Self::Sunken => Some(Fill::Sunken),
Self::Overlay => Some(Fill::Overlay),
}
}
/// Pressing a raised region reads as a well, and nothing else moves.
///
/// [`Depth::Overlay`] is untouched along with the rest: an overlay is a
/// surface, not a control, so there is nothing there to press.
#[must_use]
pub const fn pressed(self) -> Self {
match self {
Self::Raised => Self::Well,
other => other,
}
}
}
/// An interaction state a region can be in, beside whatever [`Depth`] it is.
///
/// Orthogonal to depth on purpose. A disabled button is still [`Depth::Raised`]
/// and a disabled field is still a [`Depth::Well`], so folding either member
/// into `Depth` would make [`Depth::bevel`] and [`Depth::fill`] answer for
/// something that is not a depth, and would leave disabled-button and
/// disabled-field sharing one variant that cannot tell them apart.
///
/// # Why hover and pressed are not members
///
/// The line is whether every renderer has the state to express, not whether CSS
/// does. Hover is renderer policy and `makeover-webview` says so in its own
/// header: a terminal and an immediate-mode painter have no pointer hovering
/// over anything, and pressed already arrives through [`Bevel::pressed`] and
/// [`Depth::pressed`], where it belongs, because pressing is a depth inversion
/// rather than a separate condition.
///
/// Focus and disabled are different in kind. A TUI has a focused widget and a
/// greyed-out one; so does egui. Both were unsayable here, so all three webview
/// consumers supplied them from outside the primitive by out-specifying rules
/// they did not own: goingson alone carries 19 of them, and the MNW server
/// another 21. That is the divergence this crate exists to end, arriving one
/// layer down.
///
/// # The principle this encodes
///
/// A primitive owns every state it implies. A renderer that emits a hover rule
/// for a thing owes disabled and the capability answer for that same thing,
/// because anything less exports the completion work to N consumers who will
/// each do it differently.
///
/// Focus is not on that list and was removed from this axis in 0.19.0. It is
/// the renderer's, decided after the description; see the crate header, "Reach,
/// focus and the focus ring", for the three terms and who owns each.
///
/// `#[non_exhaustive]` for the reason [`Fill`] and [`Depth`] carry it: growth
/// must not be a lockstep event across the three renderers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum State {
/// Present, visible, and not answering.
///
/// Not the same as absent, and deliberately not a [`Fill`]: a disabled
/// control keeps the surface it always had and stops responding, so what
/// changes is its content and its interactivity rather than what it is.
Disabled,
}
impl State {
/// Whether a region in this state stops answering the pointer.
///
/// Stated in the description rather than left to each renderer, on the same
/// reasoning as [`Bevel::pressed`]: a cascade carries it for free and an
/// immediate-mode renderer resolves it per call site, so leaving it unsaid
/// means resolving it once per consumer and disagreeing.
#[must_use]
pub const fn suppresses_interaction(self) -> bool {
// A match rather than a bare `true`, so a member added to this
// `#[non_exhaustive]` axis has to answer the question rather than
// inheriting an answer.
match self {
Self::Disabled => true,
}
}
}
impl Intent for State {
fn token(self) -> &'static str {
match self {
// Reusing the muted content intent rather than minting a
// `disabled` colour. Disabled is a reduction and not a status, and
// `makeover-webview`'s progress rules already record the reading
// that `content-muted` is what disabled looks like.
Self::Disabled => "content-muted",
}
}
}
/// What a region is saying, when it is saying something.
///
/// The one intent family shared by badges, notices and nothing else. Kept
/// separate from [`Fill`] because a surface is where a thing sits and a tone is
/// what it means, and the three apps agree on the four statuses:
/// `info_banner` / `warning_banner` in audiofiles, `.toast-info` /
/// `.toast-success` / `.toast-error` in goingson, `.toast.success` /
/// `.toast.error` in Balanced Breakfast.
///
/// The per-tag palette (`category-one` through `category-six`) is deliberately
/// not here. Which colour a *particular* tag takes is app domain, and both
/// webview apps already carry it as a `data-color` attribute.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Tone {
/// No status.
///
/// Ordinary content, at full weight. It does not also mean muted: a
/// badge reads quiet because [`Token::Badge`] answers no click, which is
/// the renderer's knowledge and not this axis's. A renderer wanting a
/// muted badge reaches for [`Token::interactive`] itself rather than
/// expecting `Neutral` to have muted it.
Neutral,
/// Something worth knowing and nothing to do about it.
Info,
/// Something finished and it worked.
Success,
/// Something the user should look at before continuing.
Warning,
/// Something broken, or something about to be destroyed.
Danger,
}
impl Intent for Tone {
fn token(self) -> &'static str {
match self {
// Neutral has no status token of its own, so it takes the plain
// content intent. It used to answer `content-muted`, which read
// "no status" as "de-emphasised" and muted every figure value in
// the webview. Muting is a renderer's call about a particular
// token, not something the status axis knows.
Self::Neutral => "content",
Self::Info => "info",
Self::Success => "success",
Self::Warning => "warning",
Self::Danger => "danger",
}
}
}
/// A small labelled thing that sits inside something else.
///
/// Two members, because the three apps drew three taxonomies and only one line
/// runs through all of them: does it answer a click. audiofiles has
/// `classification_badge` (a label) against `tag_chip`, `tag_chip_removable`
/// and `selectable_tag` (all of which do). Balanced Breakfast has `.tag` and
/// `.badge` against `.tag-chip`. goingson is the one that has to move: its
/// `.tag` and `.badge` are a single CSS rule, so every call site has to be read
/// to decide which of the two it always was.
///
/// The evidence that a chip is a real concept rather than a badge with a
/// cursor: audiofiles inverts its bevel on press and Balanced Breakfast latches
/// `.tag-chip.active` with the inset bevel. Two independent arrivals at "a chip
/// holds itself down", which is exactly what [`Depth::pressed`] already says.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Token {
/// Non-interactive status or count. Answers no click.
Badge,
/// An interactive or removable token. Answers a click, and latches if it
/// stands for a filter that is either on or off.
Chip {
/// Whether it carries its own remove affordance.
removable: bool,
},
}
impl Token {
/// Whether this answers a click.
///
/// The whole difference between the two members, and the reason a renderer
/// with no hover (a touch surface, a terminal) can still tell them apart.
#[must_use]
pub const fn interactive(self) -> bool {
matches!(self, Self::Chip { .. })
}
/// How it sits, given whether it is currently latched down.
///
/// A badge is flat: it is a label, and giving it an edge would say it can
/// be pressed. A chip is raised, and inset while latched.
#[must_use]
pub const fn depth(self, latched: bool) -> Depth {
match self {
Self::Badge => Depth::Flat,
Self::Chip { .. } if latched => Depth::Well,
Self::Chip { .. } => Depth::Raised,
}
}
}
/// Something the app is telling the user, unprompted.
///
/// Two concepts, not one with a placement. They differ in more than where they
/// sit: a toast is transient, stacked and self-dismissing, and a banner is
/// persistent, in flow, one per region, and dismissed by fixing the condition
/// it reports. Folding them into one member with a placement parameter would
/// make lifetime, stacking and dismissal all placement-dependent, which is the
/// description leaking renderer policy.
///
/// All three apps have banners: `info_banner` and `warning_banner` in
/// audiofiles, five of them in goingson (sync, sync-result, vacation-day,
/// timer-active, past-review), `.update-banner` in Balanced Breakfast. The two
/// webview apps also have toasts. So neither member is speculative, and no app
/// gains a concept it lacks except audiofiles, whose renderer may legitimately
/// decline to draw a toast at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Notice {
/// Transient, stacked, dismisses itself.
Toast,
/// Persistent, in flow, one per region, dismissed by fixing the cause.
Banner,
}
impl Notice {
/// Whether it goes away on its own.
#[must_use]
pub const fn transient(self) -> bool {
matches!(self, Self::Toast)
}
/// How it sits.
///
/// A toast floats above the page rather than resting on it, which is
/// [`Fill::Overlay`]'s whole reason to exist. A banner is a card in the
/// flow. Both are raised, and they are raised off different things.
#[must_use]
pub const fn fill(self) -> Fill {
match self {
Self::Toast => Fill::Overlay,
Self::Banner => Fill::Raised,
}
}
}
/// The parts of a list row.
///
/// Four to begin with, taken from Balanced Breakfast, which was the only
/// consumer that had all of them (`row-primary`, `row-secondary`, `row-meta`,
/// `row-actions`). audiofiles has two and no slot structure at all, so it gains
/// meta and actions as real work rather than a rename; goingson moves off
/// `task-row` / `task-cell`.
///
/// [`Tokens`](Self::Tokens) joined at 0.9.0, and `#[non_exhaustive]` with it.
/// See the crate header for why the two arrived together.
///
/// # Meta against Tokens
///
/// The line is whether the thing has its own standing. `Meta` is one short
/// trailing fact about the row, written as text: a count, a size, a date.
/// `Tokens` is a set of small labelled things, each of which can be toned and
/// can answer a click. "3 files" is meta. A status badge that is amber, and a
/// tag you can click to filter by, are tokens.
///
/// Keeping them apart is what a single widened slot would have foreclosed. A
/// renderer can right-align one string and cannot usefully do the same to a
/// strip of chips, and a fact that is not clickable should not be drawn as
/// though it were.
/// How much vertical room a part's text may take.
///
/// A row is an inline run and every part in it is a leaf, so a part's text has
/// always been drawn on one line and no description could say otherwise. Two
/// apps say otherwise in their own stylesheets, both to the same number and
/// both with a comment explaining it: Balanced Breakfast clamps a feed row's
/// title to two lines (`.row--article .row-primary`, whose comment reads
/// "overrides .row-primary's single flex line"), and goingson clamps a
/// problem's body to two ("two lines is enough to recognize one, and the full
/// text is in the task once promoted").
///
/// Two named tiers rather than a line count, and the count is what the measured
/// demand argues against. Both sites want exactly one tier past the default,
/// and a number invites a row whose primary is a paragraph, which is a block
/// and has no business in a run. A third tier is a decision, made here, rather
/// than something a call site can reach for.
///
/// What a renderer owes it: `Tight` is what a run already does and needs no
/// answer. `Relaxed` is at most two lines and then truncation, however that
/// renderer truncates -- a webview clamps, a terminal wraps into two rows of
/// cells, an immediate-mode renderer caps the galley. A renderer that cannot
/// give two lines may draw one; what it may not do is grow without bound,
/// because the run is a line and the row's neighbours are relying on that.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Flow {
/// One line. What every part did before this type existed.
#[default]
Tight,
/// Up to two lines, then truncated.
Relaxed,
}
impl Flow {
/// How many lines the part may take.
///
/// A number here rather than in the enum, because a renderer needs one and
/// a call site does not. That asymmetry is the whole argument for the
/// tiers: the description says how much room the thing deserves and this
/// says what that costs, so a third tier changes one line rather than every
/// consumer's arithmetic.
#[must_use]
pub const fn lines(self) -> u8 {
match self {
Self::Relaxed => 2,
// Including any tier added later: one line is the safe reading of
// an unknown flow, since it is what the run guaranteed before flows
// existed.
_ => 1,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum RowPart {
/// The thing itself. What the row is called.
Primary,
/// Supporting text under the primary.
Secondary,
/// A short trailing fact: a count, a size, a date.
Meta,
/// Controls that act on this row.
Actions,
/// Small labelled things belonging to the row: badges, chips, tags.
///
/// Each carries its own [`Token`] kind and [`Tone`], so a renderer with no
/// colour still has the kind to work with, and one with no chips still has
/// the label. That is the constrained-consumer test this vocabulary exists
/// to pass, and it is why the tone lives on the token rather than on the
/// part.
Tokens,
/// How much of a set the row's thing has done: a [`Meter`] in the row.
///
/// Added 0.11.0, `da5666ae`, and it is [`Tokens`](Self::Tokens)'s problem
/// again with a different payload. [`Meter`] arrived at 0.10.0 and closed
/// two of the seven sites that asked for it; the other five sit in rows, and
/// a row holds no nodes by the ruling that a row part may not carry an
/// arbitrary node — the door through which a description becomes a
/// templating language. So the part carries the *description of a bar*
/// rather than a node, exactly as `Tokens` carries tags rather than nodes.
///
/// Without it a row flattens the proportion into [`Meta`](Self::Meta) as
/// "3/7 subtasks", which keeps both numbers and loses the reading, the same
/// way a toned status badge read as prose before `Tokens`.
Proportion,
}
impl RowPart {
/// What the part is worth when the run does not fit.
///
/// The default only. A part may say otherwise, and a renderer reads the
/// part rather than the role; this is what a description that has never
/// heard of [`Priority`] means, which is every description written before
/// the field existed.
///
/// Deriving it from the role is the thing this vocabulary has otherwise
/// been moving away from, and it is right here for one reason: the roles
/// already encode this ranking and every consumer already assumes it.
/// [`Primary`](Self::Primary) is what the row is called, and
/// [`Priority::Essential`]'s own doc was written about exactly that --
/// "without it the row does not identify itself".
///
/// [`Actions`](Self::Actions) is `Essential` and it is the interesting one.
/// A control is not a fact, so dropping it does not cost the reader a
/// detail; it costs them the only way to act on the row, and in a terminal
/// it silently removes something focus had already been claimed for. A
/// renderer that needs room takes it from what the row *says*, never from
/// what it *offers*.
///
/// An unknown member reads as [`Priority::Secondary`]: droppable, but not
/// first, since guessing `Optional` for something this crate has not been
/// taught would make a new member the first thing to vanish.
#[must_use]
pub const fn priority(self) -> Priority {
match self {
Self::Primary | Self::Actions => Priority::Essential,
Self::Meta | Self::Proportion => Priority::Optional,
_ => Priority::Secondary,
}
}
/// The content intent the part takes.
#[must_use]
pub const fn intent(self) -> &'static str {
match self {
Self::Primary => "content",
Self::Secondary => "content-secondary",
Self::Meta => "content-muted",
// Actions carry controls rather than text, so they inherit.
Self::Actions => "content",
// So do tokens: each one carries its own tone, and a part-level
// intent underneath it would fight the token that sits on it.
Self::Tokens => "content",
// And so does a proportion, for the same reason: the meter carries
// the tone, and it is about the ratio rather than about the row.
Self::Proportion => "content",
}
}
}
/// How far down the heading tree a title sits.
///
/// Three, and only the three that are actually headings. The bands those used
/// to be filed with (goingson's `.page-header`, Balanced Breakfast's `.header`
/// and `.detail-header`) are arrangement, not type, and live at
/// [`Region::Band`]. One of them contains no text at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Heading {
/// Names the whole screen. One per screen.
Page,
/// Names a block within the screen.
Section,
/// Names a sub-block inside an already-named section.
Subsection,
}
impl Heading {
/// Whether a rule follows the heading.
///
/// audiofiles' `section_header` draws a separator and its
/// `subsection_label` deliberately does not, which is the only thing
/// distinguishing the two once weight and colour are deferred.
#[must_use]
pub const fn separated(self) -> bool {
matches!(self, Self::Section)
}
}
/// A control that picks between things.
///
/// Three, because three distinct behaviours are in play and collapsing any two
/// loses something. A segmented control picks a value; a tab picks a pane; a
/// toggle picks nothing and simply holds itself on or off.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Selector {
/// Exactly one of N, and the options abut.
Segmented,
/// Independent on or off, on its own.
Toggle,
/// Navigation between panes. The folder semantic.
Tabs,
}
impl Selector {
/// How the chosen option sits.
///
/// Held in for a segmented control and a toggle, which is the same shape
/// pressing produces and the whole economy of the idiom: one appearance,
/// two reasons to wear it. A tab is the exception, because the selected
/// folder tab comes *forward* to join the pane it opens.
#[must_use]
pub const fn chosen(self) -> Depth {
match self {
Self::Segmented | Self::Toggle => Depth::Well,
Self::Tabs => Depth::Raised,
}
}
/// How the options that were *not* picked sit.
///
/// Added 0.3.0. Describing only [`Selector::chosen`] left the unchosen
/// option falling through to [`Depth::Flat`], which says it is level with
/// the strip it sits in, and no renderer emitted anything for it. That is
/// wrong in both directions and goingson proved it: its unchosen tabs are
/// recessed by hand, and being recessed is *why* the chosen one reads as
/// coming forward. Against a flat strip, a raised chosen tab is a bevel
/// drawn on the strip's own colour, which is a much weaker folder effect
/// than the contrast the idiom is named after.
///
/// Each member is the inverse of its chosen state, which is the whole
/// content of "picked" once colour is deferred:
///
/// - Tabs recede, so the chosen one comes forward.
/// - A segment and a toggle stand up, so the chosen one is held in.
#[must_use]
pub const fn unchosen(self) -> Depth {
match self {
Self::Tabs => Depth::Sunken,
Self::Segmented | Self::Toggle => Depth::Raised,
}
}
/// Whether the options touch.
///
/// The gap is the entire difference between a segmented control and a row
/// of buttons that happen to sit near each other, which is what audiofiles'
/// `segmented_control` says in its own comment and why it zeroes the
/// spacing by hand.
#[must_use]
pub const fn abutting(self) -> bool {
matches!(self, Self::Segmented | Self::Tabs)
}
}
/// What is in a region right now.
///
/// The state, not the shimmer. Whether pending paints a skeleton, a spinner or
/// nothing at all is renderer policy, the same class of decision that got
/// `Fill::fallback` deleted from this crate. goingson and Balanced Breakfast
/// each grew a skeleton with differently-named parts; both keep them, as the
/// webview renderer's expression of [`Readiness::Pending`]. audiofiles has none
/// and needs none, because an immediate-mode renderer simply repaints.
///
/// # Four states and not two, as of 0.12.0
///
/// `703f4cd2`. It named `Ready` and `Pending` and stopped, so a described screen
/// whose list came back empty had to render an empty region or invent its own
/// placeholder text, and neither says what it is. goingson draws one at 27 sites
/// across 12 files and Balanced Breakfast at 9, with a class family that had
/// already drifted into `empty-state`, `empty-state--error`, `error-state` and
/// six more.
///
/// The four are one axis because they are mutually exclusive: a region shows its
/// content, or a sign that it is coming, or a sign that there is none, or a sign
/// that it broke. Never two. That is the test for one enum against several
/// fields, and it is why this grew rather than a new member arriving beside it.
///
/// # What is not here
///
/// **The message.** "No projects yet" is content, and this names a state. It
/// lives with whatever holds the region — in quasi's case a `Slot` — alongside
/// the action that leads out of the emptiness, since an address is the one thing
/// this crate never names.
///
/// **How much room it gets.** goingson's `--compact`, `--dashboard` and
/// `--padded` are the same state at three sizes, and a size is
/// `makeover-geometry`'s question. Naming them here would be this crate stating
/// values again.
///
/// **The icon.** Presentation, and each host has its own answer or none.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Readiness {
/// The content is here.
Ready,
/// The content is on its way.
///
/// For a region that changes *after* the first paint, and never for the
/// first paint itself: see "First paint is final paint" in the crate header.
/// A host that renders once, with its data already in hand, has nothing to
/// say this about, and a screen arriving in this state is describing a
/// moment its host should not have been in.
///
/// What stands in occupies the geometry the content will occupy. A stand-in
/// sized to itself rather than to what replaces it is the reflow the rule
/// forbids, arriving one repaint later.
Pending,
/// The content arrived and there is none of it.
///
/// Not a failure. An empty list is the normal state of a new install, and a
/// renderer that drew it in a danger tone would be reporting a fault where
/// there is none.
Empty,
/// The content did not arrive.
Failed,
}
impl Readiness {
/// Whether the region draws its own content, or something standing in for
/// it.
///
/// The question every renderer asks first, so it is answered once here
/// rather than by a `matches!` in each. A state added later is a stand-in
/// until proven otherwise: falling back to drawing content that may not be
/// there is the worse of the two mistakes.
#[must_use]
pub const fn shows_content(self) -> bool {
matches!(self, Self::Ready)
}
/// What the state means, for a renderer choosing a colour.
///
/// Derived rather than carried, which is the opposite of [`Meter`] and
/// [`Figure`], and the difference is worth stating: a proportion's meaning
/// depends on what is being counted and only the app knows it, while
/// "nothing here yet" and "this broke" mean the same thing in every app that
/// will ever have them.
#[must_use]
pub const fn tone(self) -> Tone {
match self {
Self::Failed => Tone::Danger,
_ => Tone::Neutral,
}
}
}
/// An action is waiting on something that resolves once, in expected finite
/// time.
///
/// The control-side sibling of [`Readiness`]. That enum names four states for a
/// region and named nothing at all for the button that is currently doing what
/// it was clicked for, so the in-flight treatment is hand-written wherever it
/// exists: the MNW server carries 57 in-flight indicators against 2 guards
/// against a second press, which is the spinner mostly present and the guard
/// mostly absent, on a codebase whose money path is a purchase button.
///
/// # What is described here, and what is not
///
/// The fact is that there is an outstanding thing which will complete. Not that
/// the address is remote: a heavy local query waits too, and a server calling a
/// payment provider is not the browser leaving the app. Not that the call is
/// slow either, which is a judgement about a call rather than a property of one.
///
/// Resolving **once** is the boundary, and it is what separates this from a
/// screen that keeps changing. A live screen never resolves and has no name in
/// this crate yet.
///
/// # One mark, two renderings
///
/// | what reads it | what it does |
/// |---|---|
/// | a control that was pressed | goes busy and refuses a second press until it resolves |
/// | a region fed by it | stands in as [`Readiness::Pending`], then fills |
///
/// The two were on the table separately and both were taken. Controls alone
/// leaves a slow region hand-split into its own route, which is what MNW's user
/// dashboard does with its payout summary; regions alone leaves the purchase
/// button unguarded.
///
/// # A quantity when it is measured, never a duration
///
/// [`amount`](Self::amount) is stated only when it is a measured fact about the
/// payload. An upload's file length, yes; a round trip to a payment provider,
/// [`None`]. A duration is described nowhere, and a renderer may not manufacture
/// one from the amount either: a determinate bar shows what is done over what
/// there is, plus the time it has taken so far, and never a remaining time, an
/// arrival time or a rate extrapolated forwards. A prediction is wrong the
/// moment the transfer stalls, and being confidently wrong is worse than being
/// honestly indeterminate.
///
/// This is why the crate refuses to say how long an undo stays offered and
/// accepts a byte count here. The refusal is about naming a decision that
/// belongs to the renderer; a file's length is not a decision, nobody chose it.
///
/// # Not [`Meter`]
///
/// [`Meter`] is how much of a set is done, and its own docs refuse the progress
/// of an operation on the grounds that a description is built once and dropped
/// while an operation runs between renders. That refusal stands. This names the
/// operation and its size, which is all that is known before it starts; how much
/// of it has gone through is the renderer's to observe live, and nothing round
/// trips through a description to say so.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub struct Awaiting {
/// Total work to get through, when it is a measured fact about the payload.
///
/// `None` when the wait has no countable size, which is the common case and
/// the default.
///
/// Unit-agnostic on purpose. Bytes for an upload, rows for an import; what
/// is being counted is the app's business and a renderer draws a proportion
/// either way.
pub amount: Option,
}
impl Awaiting {
/// A wait with no countable size.
#[must_use]
pub const fn unmeasured() -> Self {
Self { amount: None }
}
/// A wait whose size is known.
///
/// Reach for it only with a measured figure. An estimate written in here is
/// a prediction wearing a fact's clothes, and the renderer has no way to
/// tell the two apart.
#[must_use]
pub const fn of(amount: u64) -> Self {
Self {
amount: Some(amount),
}
}
/// Whether there is a proportion to draw.
///
/// The question every renderer asks first, answered once here rather than by
/// a `matches!` in each. False means indeterminate, which is the honest
/// drawing when nothing countable was measured.
#[must_use]
pub const fn is_determinate(self) -> bool {
self.amount.is_some()
}
}
/// How much of a set is done.
///
/// Added 0.10.0. Nine sites across the two webview apps drew a bar and nothing
/// here named one, so every described screen concatenated the two numbers into
/// its heading text instead: "Subtasks 3/7", "Time Tracking 45m tracked / 30m
/// est, over". Every fact survives that and the reading does not, which is the
/// same loss `RowPart::Tokens` closed when a toned status badge became prose.
///
/// # Why a pair and not a percentage
///
/// Both numbers, not the percentage the apps compute from them. The percentage
/// was the obvious shape and it had already been tried: goingson's
/// `Task::time_progress` divides, rounds, and then clamps to 100, which throws
/// away the one case the bar exists to show — 45 minutes tracked against a
/// 30-minute estimate. It carries a separate `is_over_estimate` boolean beside
/// it to recover the fact the clamp dropped. A pair keeps the over-run without a
/// companion flag, and [`percent`](Meter::percent) is still one call away for a
/// renderer that wants it.
///
/// The pair is also what the apps already have at every site. All seven
/// determinate bars write the ratio into the accessible layer and never the
/// percentage: `title="3/7 subtasks"`, `aria-label="3 of 7 subtasks completed"`,
/// a milestone's own `3/7` span. Given 43 nothing can recover "3 of 7", so a
/// percentage member would have made [`label`](Meter::label) mandatory at every
/// call site, which is the concatenated text this member removes, moved one
/// layer down.
///
/// # What this is not
///
/// The progress of an *operation*. Two of the nine sites are that — goingson's
/// focus timer, Balanced Breakfast's feed fetch — and they get nothing here, on
/// purpose. Both are imperative controllers over a live handle, driven by a tick
/// or an event stream, and a description is built once and dropped. Holding one
/// would mean growing a way to update a description between renders, which is a
/// different feature. [`Readiness::Pending`] and a [`Notice::Toast`] carry the
/// honest part.
///
/// The two cases are distinguishable in the markup rather than by taste: every
/// determinate bar in both apps carries a tone, and neither operation bar
/// carries one. Two codebases drew that line the same way without coordinating.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Meter<'a> {
/// How much is done. May exceed [`total`](Self::total), and that is the
/// case worth drawing.
pub done: u32,
/// How much there is to do. Zero means there is no set, not that the set is
/// complete.
pub total: u32,
/// What the proportion means right now.
///
/// Carried rather than derived, because no renderer can work it out. The
/// same 90% is [`Tone::Success`] on a subtask rollup and [`Tone::Danger`] on
/// a time estimate, and goingson picks between them from `is_over_estimate`,
/// a fact about the data and not about the number.
pub tone: Tone,
/// What is being counted, if the bar says so: "subtasks", "tasks".
///
/// The noun, not the ratio. A renderer builds "3 of 7 subtasks" from this
/// and the two numbers; handing it the assembled string would put the
/// sentence order in the description, where a terminal at one line and a
/// tooltip want different ones.
pub label: Option<&'a str>,
}
impl<'a> Meter<'a> {
/// A proportion with no tone and no label.
#[must_use]
pub const fn new(done: u32, total: u32) -> Self {
Self {
done,
total,
tone: Tone::Neutral,
label: None,
}
}
/// What the proportion means.
#[must_use]
pub const fn tone(mut self, tone: Tone) -> Self {
self.tone = tone;
self
}
/// What is being counted.
#[must_use]
pub const fn label(mut self, label: &'a str) -> Self {
self.label = Some(label);
self
}
/// How full the bar is, 0 to 100, clamped.
///
/// For drawing, which is the only thing a clamped number is good for. Ask
/// [`overflowing`](Self::overflowing) before reporting it as a fact, or this
/// is `time_progress`'s bug again with the clamp moved.
///
/// An empty set reads as 0. Nothing is done, because there is nothing to do
/// and no bar to fill; the apps guard on the count before drawing at all.
#[must_use]
pub const fn percent(&self) -> u8 {
if self.total == 0 {
return 0;
}
let scaled = (self.done as u64 * 100) / self.total as u64;
if scaled > 100 { 100 } else { scaled as u8 }
}
/// Whether more is done than there was to do.
///
/// The fact [`percent`](Self::percent) destroys, kept reachable so a
/// renderer can mark the over-run rather than drawing a full bar and
/// implying it landed exactly.
#[must_use]
pub const fn overflowing(&self) -> bool {
self.done > self.total
}
/// Whether there is a set at all.
///
/// A meter over nothing is sayable on purpose, for the same reason a field
/// with no options is: it is what an app with an unloaded count actually
/// has, and a renderer that shows an empty bar says so on screen rather than
/// dividing by zero.
#[must_use]
pub const fn is_empty(&self) -> bool {
self.total == 0
}
}
/// One figure with a caption: a number and what it counts.
///
/// The dashboard shape. A large value over a small caption, several of them in a
/// strip: a current streak, a completion rate, a total. Added 0.11.0,
/// `93c6a174`, after goingson turned out to have five of them across five
/// screens with five class vocabularies for the one shape — `task-overview-stat`,
/// `stat-box`, `month-stat-item`, `contact-summary-stat`, `sync-stat`. Four put
/// the value above the caption and one inverts it, which is drift inside the
/// shape rather than a second shape.
///
/// # Why the value is text
///
/// "17", "84%", "12/30", "3d". A figure is whatever the app computed, already
/// formatted, and the formatting is the app's because only it knows whether the
/// number is a percentage, a duration or a ratio. This carries none of the
/// arithmetic [`Meter`] carries, and that is the difference between them: a
/// meter is a proportion a renderer draws, and a figure is a fact a renderer
/// sets in type.
///
/// # Tone is carried, for [`Meter`]'s reason
///
/// Three of the five sites tone the figure by their own means — `red`/`blue` on
/// the weekly review, a `${type}` class on the monthly one, `sync-stat-warn` on
/// sync. So tone is carried at every site that needs it and derived at none, and
/// no renderer can work out that a streak of zero is worth colouring.
///
/// # What is not here
///
/// Whether the figure answers a click. One of the five is a control — sync's
/// "Not Applied: 3" opens the list — and an action is not something this crate
/// can name: nothing here knows what a route is. That belongs beside the figure
/// in whatever layer holds the actions, the same way a row's activation sits
/// beside its parts rather than inside them.
///
/// The arrangement is not here either. Several figures in a strip is a set, and
/// a renderer given them one at a time cannot tell it is looking at one; the
/// layer that holds the tree is where the set gets said.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Figure<'a> {
/// The number, formatted the way the app means it to read.
pub value: &'a str,
/// What it counts. The caption under the value.
pub caption: &'a str,
/// How the value has moved, if the app is tracking that.
///
/// Added 0.13.0. Text, for [`value`](Self::value)'s reason: only the app
/// knows whether a move reads as `+12.5%`, `+3` or `2x`, and a renderer
/// handed a number would have to guess.
///
/// This is what [`tone`](Self::tone) was for and had no consumer of. The MNW
/// server has four screens whose stat card is a label, a value and a delta,
/// and the delta is the toned part: the figure itself is an ordinary fact
/// and it is the movement that reads as good or bad. Without this the delta
/// has to be folded into the caption, which loses the tone and reads as a
/// longer caption rather than as a second, smaller line.
pub change: Option<&'a str>,
/// What the figure means right now. [`Tone::Neutral`] is an ordinary fact.
///
/// Applies to [`change`](Self::change) where there is one, since that is the
/// part that carries the judgement, and to the value where there is not.
pub tone: Tone,
}
impl<'a> Figure<'a> {
/// A figure that is an ordinary fact.
#[must_use]
pub const fn new(value: &'a str, caption: &'a str) -> Self {
Self {
value,
caption,
change: None,
tone: Tone::Neutral,
}
}
/// How the value has moved.
#[must_use]
pub const fn change(mut self, change: &'a str) -> Self {
self.change = Some(change);
self
}
/// What the figure means.
#[must_use]
pub const fn tone(mut self, tone: Tone) -> Self {
self.tone = tone;
self
}
}
/// Something the user can do, and what it costs to say so.
///
/// Added 0.17.0, out of `quasi-tui`: the terminal renderer had drawn one of
/// these for months and every other consumer that wanted a button had written
/// its own, because this layer named [`RowPart::Actions`] as a *slot* and never
/// named the thing that goes in it. Beside [`Meter`] and [`Figure`] for the
/// reason those are here: a renderer that is handed the parts has to decide how
/// to say them, and a renderer that is handed a finished string has already had
/// the decision made for it.
///
/// No address. Where a control goes is the app's business and every host
/// follows it differently — an `hx-get`, a protocol URL, a function call — so
/// the description says what the control *is* and the caller keeps what it
/// does. That is the same split [`Choice`] makes.
///
/// No confirmation flag either, and that one is a finding rather than an
/// omission: a question asked *after* a control is pressed belongs to whatever
/// is holding the interaction, and a renderer that drew it would be asking
/// before there was anything to answer.
/// How a picture sits in the box it is given.
///
/// An intent rather than a value, so a renderer picks the expression it has:
/// `object-fit` in a webview, a texture's UV rect in egui, and in a terminal a
/// choice about how many cells the blit gets. Named because MNW already makes
/// the distinction deliberately at 17 sites and makes it three different ways,
/// which is a policy the app decided rather than one a shared crate would be
/// picking by accident.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Fit {
/// The picture's own proportions, and the box takes the height they imply.
///
/// The default because it is the only one that shows the whole picture at
/// its own shape, so a renderer that ignores this enum entirely is still
/// right about the common case. A screenshot wants this; the shipped MNW
/// carousel sets no `object-fit` at all, which is this.
#[default]
Natural,
/// Fill the box and crop whatever does not fit.
///
/// For a picture in a slot whose shape the layout fixed: a thumbnail, an
/// avatar, cover art. 15 of MNW's 17 sites.
Cover,
/// Fit inside the box whole, leaving space on two sides.
///
/// The letterbox. For when the whole picture matters more than filling the
/// space, and the space is not the picture's shape.
Contain,
}
/// A picture, and what it says to someone who is not looking at it.
///
/// # No source
///
/// [`Act`]'s split, for [`Act`]'s reason. A source is an address, and this
/// crate has no notion of an address: it says what a thing *is* and the caller
/// keeps what it points at. The three findings dropped from 0.11.0 were all
/// this same shape.
///
/// It matters more here than it does for a control, because a picture is the
/// one member where the address is most of what a webview needs and *none* of
/// what the description knows. `quasi_router::Node::Image` carries the URL, the
/// way it carries an `Action` for a control.
///
/// # Why [`alt`](Self::alt) is not optional
///
/// Every other host has to draw something, and for two of the three the alt
/// text is not a fallback but the whole rendering: a terminal without a
/// graphics protocol has the words and nothing else. Making it optional would
/// make "this picture is invisible on a terminal" the default, and the
/// description would be carrying a webview assumption in its shape.
///
/// An image that genuinely says nothing — a rule, a spacer, a decoration
/// repeating what the text beside it already said — is an empty `alt`, which is
/// the same thing HTML means by it and is a claim rather than an oversight.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Image<'a> {
/// What the picture says, for anything not showing it.
///
/// Empty means the picture is decorative and adds nothing to the text
/// around it. See the type's own docs on why this is not an `Option`.
pub alt: &'a str,
/// A visible line under the picture, where the app wants one.
///
/// Distinct from [`alt`](Self::alt) and the difference is who it is for: a
/// caption is content everybody reads, alt text is what stands in for the
/// picture. A screenshot captioned "The library view" still needs alt text
/// describing what is in the shot.
pub caption: Option<&'a str>,
/// How it sits in the box it is given.
pub fit: Fit,
/// The picture's own dimensions, where the app knows them.
///
/// **Not a display size**, and that distinction is what makes this belong
/// here rather than fall foul of the deferral rule. Saying a picture should
/// be 320 points wide is a layout value and is not the description's to
/// give. Saying the file is 5120x3412 is a fact *about the picture*, the
/// same kind of fact [`alt`](Self::alt) is, and no renderer can find it out
/// without fetching the bytes.
///
/// # What it is for, and it is not decoration
///
/// Without it a renderer cannot reserve room, so the picture occupies
/// nothing until it arrives and then takes its full height at once,
/// shoving everything below it down the screen. Measured on MNW's landing
/// page 2026-08-14: a 478px jump per frame, and a cumulative layout shift
/// of 0.087 for the page, which is most of the way to the 0.1 that counts
/// as bad.
///
/// Every host wants it and none can derive it. A webview writes `width` and
/// `height` so the browser holds the space; egui sizes a texture; a
/// terminal with a graphics protocol scales a blit into cells. This was
/// missing from 0.21.0, which is the release that added [`Image`], and its
/// absence is the defect rather than an omission.
///
/// `None` is honest and common: a creator-uploaded image whose dimensions
/// the app never recorded genuinely does not know. It means the renderer
/// cannot reserve, not that the picture has no size.
pub intrinsic: Option,
/// Whether the picture is needed with the screen, or can arrive later.
pub loading: Loading,
}
/// A picture's own pixel dimensions.
///
/// Deliberately not [`makeover_geometry`]'s business. Geometry answers *how
/// much space a thing should get*, which is a scale question with the same
/// answer on every screen. This is the intrinsic size of one asset, which is a
/// fact about that asset and varies per picture.
///
/// [`makeover_geometry`]: https://docs.rs/makeover-geometry
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Extent {
/// Width in the picture's own pixels.
pub width: u32,
/// Height in the picture's own pixels.
pub height: u32,
}
impl Extent {
/// A picture's dimensions.
#[must_use]
pub const fn new(width: u32, height: u32) -> Self {
Self { width, height }
}
/// Width over height, or `None` if either side is zero.
///
/// The form a renderer actually reserves space with: a box that knows its
/// proportion holds the right height at any width, which is what a
/// responsive picture needs and what a fixed pixel height cannot give.
#[must_use]
pub fn ratio(self) -> Option {
(self.width > 0 && self.height > 0).then(|| self.width as f32 / self.height as f32)
}
}
/// When a picture is needed.
///
/// A claim about *importance and position* rather than a fetch mechanism, which
/// is why it is the description's to make: only the app knows whether a picture
/// is the first thing on the screen or the fortieth thing down a list.
///
/// # Eager is the default, and that is a correctness choice
///
/// 0.21.0 emitted the webview's `loading="lazy"` for every picture, on the
/// evidence that the one consumer measured wrote it. That was reading a habit
/// as a rule. Deferring a picture that is on screen at first paint does not
/// save anything -- it is needed immediately either way -- and it delays the
/// arrival, so the space it eventually takes is claimed later and the shift is
/// more visible, not less.
///
/// So the safe answer is the default and the optimisation is opted into. A
/// carousel is the case that proves the two cannot be one setting for the
/// renderer to choose: its first frame is on screen and its other frames are
/// not, in the same widget, at the same moment.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Loading {
/// Needed with the screen. Fetch it now.
#[default]
Eager,
/// Not on screen yet. It can wait until it is near.
Lazy,
}
impl<'a> Image<'a> {
/// A picture that carries its own proportions.
#[must_use]
pub const fn new(alt: &'a str) -> Self {
Self {
alt,
caption: None,
fit: Fit::Natural,
intrinsic: None,
loading: Loading::Eager,
}
}
/// The picture's own dimensions, so a renderer can hold its place.
#[must_use]
pub const fn intrinsic(mut self, width: u32, height: u32) -> Self {
self.intrinsic = Some(Extent::new(width, height));
self
}
/// This picture is not on screen yet; it can arrive when it is near.
#[must_use]
pub const fn lazy(mut self) -> Self {
self.loading = Loading::Lazy;
self
}
/// A visible line under it.
#[must_use]
pub const fn caption(mut self, caption: &'a str) -> Self {
self.caption = Some(caption);
self
}
/// How it sits in its box.
#[must_use]
pub const fn fit(mut self, fit: Fit) -> Self {
self.fit = fit;
self
}
/// Whether the picture adds anything for someone not looking at it.
///
/// A renderer with no way to show a picture uses this to decide between
/// drawing the alt text and drawing nothing at all. Both are correct and
/// the difference is this flag: standing in for a decorative rule with the
/// word "decoration" is worse than leaving the space empty.
#[must_use]
pub const fn speaks(self) -> bool {
!self.alt.is_empty()
}
}
/// What a [`Track`]'s integers count.
///
/// `Track::fraction` never needed this -- the arithmetic is the same whatever
/// the numbers mean -- which is exactly how the ruler came to assume minutes
/// and print `00:00` over a month. A renderer drawing an axis has to write a
/// label, and it cannot derive the unit from the numbers.
///
/// Added 2026-08-15, after a probe put a fifteen-day span on a
/// thirty-one-slot track and got correct geometry under a wall clock.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Unit {
/// Minutes from the start of a day. A day view.
#[default]
Minutes,
/// Whole days. A month strip, a sprint, a stretch of leave.
///
/// A day-granularity axis is a *strip*, not a calendar: one line with
/// spans laid along it. What it deliberately does not do is wrap into
/// weeks, which is the shape that makes weekday periodicity visible and
/// the one job of a month grid that a strip cannot take over. See the
/// crate header.
Days,
}
/// A window on an axis, in whatever [`Unit`] its [`Track`] counts.
///
/// The axis a [`Track`] draws. Offsets rather than instants, because a
/// description carrying a `DateTime` would carry a timezone with it and the
/// vocabulary has no business holding one. The app knows which day or month
/// this is; the description says how far along it a thing sits.
///
/// `to` is exclusive and may exceed the natural period, which is how a span
/// running past the end is said without a second date: under
/// [`Unit::Minutes`], `Span::new(1320, 1560)` is 22:00 to 02:00.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Span {
from: u16,
to: u16,
}
impl Span {
/// Midnight to midnight, the ordinary day.
pub const DAY: Self = Self { from: 0, to: 1440 };
/// A span, clamped to a sane one.
///
/// An empty or backwards span is a caller bug that should not cost a
/// renderer a division by zero, so `to` is forced at least one minute past
/// `from` rather than returning an error nobody can act on. Same reasoning
/// as [`Share::percent`], which clamps rather than refuses.
#[must_use]
pub const fn new(from: u16, to: u16) -> Self {
Self {
from,
to: if to > from { to } else { from + 1 },
}
}
/// The first minute on the axis.
#[must_use]
pub const fn from(self) -> u16 {
self.from
}
/// One past the last minute on the axis.
#[must_use]
pub const fn to(self) -> u16 {
self.to
}
/// How much the axis covers, in its track's unit. Never zero.
#[must_use]
pub const fn length(self) -> u16 {
self.to - self.from
}
/// Whether an offset falls on this axis.
#[must_use]
pub const fn holds(self, minute: u16) -> bool {
minute >= self.from && minute < self.to
}
}
impl Default for Span {
fn default() -> Self {
Self::DAY
}
}
/// Where a thing sits on a [`Track`], and for how long.
///
/// The one fact a list cannot carry and the whole reason this primitive exists.
/// A list says what order things come in; a track says a thing starts 135
/// minutes along and lasts 45, which is a different claim and not derivable
/// from the first.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Placement {
at: u16,
length: u16,
}
impl Placement {
/// A placement, clamped to a drawable one.
///
/// Zero length becomes one for the same reason [`Span::new`] clamps: a
/// zero-height thing is invisible rather than expressive, and every
/// renderer would need its own guard.
#[must_use]
pub const fn new(at: u16, length: u16) -> Self {
Self {
at,
length: if length == 0 { 1 } else { length },
}
}
/// Offset from the axis origin, matching [`Span`]'s.
#[must_use]
pub const fn at(self) -> u16 {
self.at
}
/// How long it lasts, in its track's unit. Never zero.
#[must_use]
pub const fn length(self) -> u16 {
self.length
}
/// One past its last minute.
#[must_use]
pub const fn end(self) -> u16 {
self.at + self.length
}
/// Whether two placements cover any of the same time.
///
/// Geometry, and deliberately not a described field. Whether an overlap is
/// a *conflict* is the app's judgment -- a meeting inside a block of free
/// time overlaps and is fine -- and that judgment travels the way every
/// other judgment does, as a [`Tone`] on the thing itself. What a renderer
/// needs in order to lay two things side by side instead of on top of each
/// other is this, and it can compute it.
///
/// The alternative was a `conflicts: bool` on each entry, which is state
/// that can disagree with the times beside it. Two sources for one fact is
/// how a screen starts rendering a conflict badge on a thing that no longer
/// conflicts.
#[must_use]
pub const fn overlaps(self, other: Self) -> bool {
self.at < other.end() && other.at < self.end()
}
}
/// A time axis: things placed by when they happen, rather than flowed.
///
/// # Why this is a primitive
///
/// This crate refused to name it until 2026-08-15, on the argument that a
/// description expressive enough to draw a timeline is a component library
/// wearing a description's name. The refusal is withdrawn, and it is worth
/// being precise about what was wrong with it, because the reasoning it used
/// applies to real cases and should not be discarded with it.
///
/// What a timeline needs that a [`List`](Region::Pane) does not is **one**
/// thing: placement. Where a thing sits is a fact about the thing, the way a
/// row's primary text is, and it is not derivable from order. Everything else a
/// day view draws -- the labels, the gridlines, the item bodies, the tones --
/// is furniture this vocabulary already names. Measured against goingson's
/// `day-planning-render.js`, the only members it needed and could not get were
/// `at` and `minutes`.
///
/// So the timeline was never a component library's worth of vocabulary. It was
/// two integers, and the refusal was priced as though it were the whole widget.
/// The test that matters is not "does this shape look complicated" but "how
/// many members does it actually add, and are they facts or presentation".
/// Slot heights, gridline colour, how overlaps stack and which hour scrolls
/// into view on open are all presentation and all stay the renderer's, which is
/// why they are absent here.
///
/// # What it does not carry
///
/// No pixel measure, no scroll offset, no drag affordance. A renderer draws the
/// span at whatever density its host uses; `makeover-geometry` owns that the
/// way it owns everything else measured in pixels.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Track {
/// The window the axis covers.
pub span: Span,
/// The granularity a thing can be placed on, in minutes.
///
/// goingson's day view is 15, giving 96 slots across a day. A renderer uses
/// it to decide where gridlines fall and what a drop lands on; it does not
/// constrain [`Placement`], because data arriving from a calendar does not
/// respect anyone's grid.
pub slot: u16,
/// How often the axis labels itself, in its own unit.
///
/// 60 gives an hourly ruler over a 15-minute grid, which is the common
/// shape and the reason this is separate from `slot`. Zero means an
/// unlabelled axis.
pub tick: u16,
/// What `span`, `slot`, `tick` and every [`Placement`] on it count.
///
/// The one field here a renderer cannot derive, and the reason it exists:
/// [`fraction`](Self::fraction) is unit-agnostic, so a day-granularity
/// track produced correct geometry under an hours-and-minutes ruler until
/// this was added. Geometry never needed it; a label always did.
pub unit: Unit,
}
impl Track {
/// An ordinary day: midnight to midnight, quarter-hour slots, hourly ticks.
pub const DAY: Self = Self {
span: Span::DAY,
slot: 15,
tick: 60,
unit: Unit::Minutes,
};
/// A track over `span`, with the day's usual granularity.
#[must_use]
pub const fn over(span: Span) -> Self {
Self {
span,
slot: 15,
tick: 60,
unit: Unit::Minutes,
}
}
/// A strip of whole days: one slot a day, a label a week.
///
/// The shape a stretch of leave or a sprint is drawn on. Not a calendar --
/// it does not wrap into weeks, and the crate header says why that
/// distinction is the whole of what a month grid still has over this.
#[must_use]
pub const fn days(span: Span) -> Self {
Self {
span,
slot: 1,
tick: 7,
unit: Unit::Days,
}
}
/// How many slots the axis holds.
///
/// Rounded up, so a span that does not divide evenly by `slot` still has a
/// slot covering its tail rather than dropping it. Never zero: `slot` of 0
/// reads as one slot spanning the whole axis rather than a division by
/// zero, since a renderer asking this question has already committed to
/// drawing something.
#[must_use]
pub const fn slots(self) -> u16 {
if self.slot == 0 {
1
} else {
self.span.length().div_ceil(self.slot)
}
}
/// Where a placement sits on the axis, as a fraction from 0.0 to 1.0.
///
/// The one calculation every renderer would otherwise write itself, and the
/// place the three would drift apart. Clamped, so a placement outside the
/// span draws at the edge rather than off it -- an event running past
/// midnight is a real thing and truncating it is better than either
/// panicking or drawing it somewhere impossible.
#[must_use]
pub fn fraction(self, minute: u16) -> f32 {
let span = f32::from(self.span.length());
let offset = f32::from(minute.saturating_sub(self.span.from()));
(offset / span).clamp(0.0, 1.0)
}
}
impl Default for Track {
fn default() -> Self {
Self::DAY
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Act<'a> {
/// What the control says.
pub label: &'a str,
/// The key that reaches it where a host has keys.
///
/// The one member written for a terminal before there was one. A webview
/// hangs it off `accesskey` or ignores it; a terminal has nothing else to
/// offer, so this is the whole of how a control is reached there.
pub key: Option<&'a str>,
/// What pressing it means. [`Tone::Danger`] is the destructive one.
pub tone: Tone,
/// Disabled, or nothing said.
///
/// [`State::Disabled`] is what changes what a renderer may do: see
/// [`State::suppresses_interaction`], which is what says a disabled control
/// is drawn and not reachable. It was the only member from 0.19.0 to
/// 0.40.0, and a control's focus is not sayable here at all — see the crate
/// header, "Reach, focus and the focus ring".
pub state: Option,
/// A sentence that is always true of this control, shown rather than hunted
/// for.
///
/// Standing help, not a message and not a tooltip. Half the hosts that read
/// this have no pointer: a hover is one spelling of it, and the shipped
/// apps reached for that spelling only because egui and a browser both had
/// one. What is being said is that the sentence is true, never that it is
/// hidden until a pointer arrives.
///
/// # Why it is here rather than a layer up
///
/// It was in `quasi_router::Act` alone until 0.40.0, and each renderer drew
/// it for itself: `makeover_tui` had no hint to read, so quasi-tui built
/// the muted line, and quasi-immediate called `on_hover_text` outside
/// [`crate::Act`] rather than inside it. `Field::hint` was here the whole
/// time, so the same idea sat at two layers depending on which thing
/// carried it, and a host that was not quasi could say it of a field and
/// not of a control.
///
/// What kept it out was price rather than doubt: this crate declares
/// `links`, so a member here moves 25 manifests across 12 repos. That is a
/// release's forward-fix pass, which is a cost and was being read as a
/// barrier.
///
/// # What a renderer owes it
///
/// Somewhere to put it, or nothing. Dropping it is legitimate; drawing it
/// *instead of* the label is not, and neither is drawing it in a way that
/// takes it out of the accessible tree, which is the failure `title` alone
/// has on a browser. Nothing may live only in a hint.
///
/// `None` is a control whose label is the whole of it, which is nearly all
/// of them.
///
/// Added 0.40.0.
pub hint: Option<&'a str>,
}
impl<'a> Act<'a> {
/// An ordinary control, reachable, with no key.
#[must_use]
pub const fn new(label: &'a str) -> Self {
Self {
label,
key: None,
tone: Tone::Neutral,
state: None,
hint: None,
}
}
/// The sentence that is always true of it; see [`hint`](Self::hint).
///
/// A renderer with nowhere to put it drops it, so this must never be the
/// only place a fact appears.
#[must_use]
pub const fn hinted(mut self, hint: &'a str) -> Self {
self.hint = Some(hint);
self
}
/// The key that reaches it.
#[must_use]
pub const fn key(mut self, key: &'a str) -> Self {
self.key = Some(key);
self
}
/// What pressing it means.
#[must_use]
pub const fn tone(mut self, tone: Tone) -> Self {
self.tone = tone;
self
}
/// Focus, or disabled.
#[must_use]
pub const fn state(mut self, state: State) -> Self {
self.state = Some(state);
self
}
/// Whether the control is drawn and does not answer.
#[must_use]
pub fn disabled(&self) -> bool {
self.state.is_some_and(State::suppresses_interaction)
}
}
/// A named part of a screen.
///
/// The thing `makeover-geometry` deliberately does not name: it names the space
/// *between* things by relationship, and nothing named the things. Six named
/// members, taken from what the two webview apps actually use, plus
/// [`Region::Bespoke`] for the parts no description should reach. Both apps'
/// `layout.css` currently names exactly two things, `.raised` and `.well`, so
/// this layer is absent rather than divergent, which makes it the cheapest of
/// the schemas to add and the easiest to over-build.
///
/// `#[non_exhaustive]` arrives with [`Region::Widget`], the pairing [`RowPart`]
/// made at 0.9.0 and [`Readiness`] at 0.12.0, and for the same reason: the
/// member after this one should not be a lockstep event across three renderers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Region<'a> {
/// A full-width strip with a title slot and an actions cluster, either of
/// which may be empty. goingson's `.page-header`, Balanced Breakfast's
/// `.header` and `.detail-header` are all this, differing only in which
/// slots they fill.
Band,
/// A persistent column beside the content, holding navigation.
Sidebar,
/// A region of content with its own scroll.
Pane,
/// Things that belong together, and nothing else.
///
/// The block [`Heading::Section`] has been naming since 0.2.0 without the
/// vocabulary being able to contain it. A section heading is a leaf sitting
/// *beside* the things it names, so nothing said where a section started or
/// ended and a renderer learned one had ended only because the next heading
/// arrived.
///
/// # The measurement
///
/// 41 [`Heading::Section`] sites across the ten screens described through
/// the router, not one of them contained. audiofiles' settings screen is the
/// clearest: one pane holding a heading, a field, a heading, two toggles, a
/// heading, a toggle and a heading, which is four sections and no
/// containers. Under the hand-written CSS the ports are replacing the same
/// block is spelled `.settings-section` in goingson, `.form-section` and
/// `.content-section` in the MNW server, `.help-section` in Balanced
/// Breakfast: three apps, four names, one shape.
///
/// # Why the existing members were the wrong answer
///
/// [`Pane`](Self::Pane) is what apps reached for, and it is 28 of the 45
/// regions in the described screens. It claims a scroll of its own and
/// [`Depth::Well`], so four settings groups inside a pane are four wells
/// inside a well and four scroll contexts. Neither claim is true of a group.
///
/// [`Widget`](Self::Widget) is wrong from the other side. Its own docs say a
/// widget is never how a primitive gets added by the back door, and a run of
/// related controls under a heading is furniture any app would have, which
/// is the generic-against-bespoke bar a primitive has to clear.
///
/// # What it does not carry
///
/// **A heading.** A group usually has one and it is an ordinary node in the
/// body, the way it already was. A group of related toggles with no heading
/// is a real thing and a mandatory slot would forbid it.
///
/// **A depth.** [`Depth::Flat`], on [`Bespoke`](Self::Bespoke)'s reasoning:
/// it inherits, and an app that wants its group in a well puts it in a
/// [`Pane`](Self::Pane), which composes rather than adding a knob here.
///
/// **A colour.** Distinguishing sibling groups by colour is the thing this
/// member was asked for and it is deliberately not stated here. The
/// description says these things belong together; which of the theme's
/// categorical colours a renderer reaches for, and whether it reaches for
/// one at all, is derived from sibling order at the renderer. A terminal
/// that tints nothing and separates with a rule is honouring this.
Group,
/// Two panes side by side, where the left chooses what the right shows.
Split,
/// Peer regions across, all of them equals.
///
/// A kanban board's columns, and the shape [`Split`](Self::Split) is not:
/// a split's two panes stand in a master-detail relationship, where the
/// left chooses what the right shows. These choose nothing about each
/// other. Each is a whole region and the set is the arrangement.
///
/// # What it does not carry
///
/// **How many.** The children say, and a count here would be a second
/// source for something the description already states by containing them.
///
/// **How wide.** Peers are equal by definition, so there is no [`Share`] to
/// state. A board whose columns wanted different widths would be a
/// different member, and no app has one.
///
/// **What happens when there is no room.** Scroll across, wrap, or collapse
/// to one column at a time: all three are right on some host, none is
/// derivable from the description, and every one of them is presentation.
/// A terminal that stacks them vertically is honouring this, not degrading
/// it.
///
/// # Why it is not an `Arrangement`
///
/// [`Arrangement`] is the page's shape, and a board is usually a region
/// *inside* a page that also has a band over it. Naming it here composes;
/// naming it there would make a screen either a board or a list-detail and
/// never a band above a board. It also keeps [`Arrangement::share`]
/// meaningful, which a peer arrangement has no answer for.
Columns,
/// A set of panes, one visible at a time, and a [`Selector::Tabs`] that
/// chooses between them.
///
/// Says nothing about where the strip sits. A row over the panes, a column
/// beside them, a wrapped run of links under them: all three are the same
/// member drawn by a renderer that knows its host, the way the strip's
/// overflow is.
TabGroup,
/// Content over a scrim, taking input until dismissed.
Modal,
/// A region this crate names the *place* of and nothing else. The app owns
/// what goes in it.
///
/// The escape hatch, and the thing that keeps the description honest about
/// its own limits. A day-plan timeline, a kanban board, a calendar and the
/// paint interaction over the timeline are not describable here and are not
/// going to become describable: a description expressive enough to produce
/// a timeline is a widget library wearing a description's name.
///
/// But a screen containing one still has to be a screen. Without this
/// member the description covers only the boring screens, and the four that
/// make goingson worth using would need a second, undescribed path beside
/// the router. Two paths is how the vocabulary starts drifting from the app
/// again, which is the exact failure this crate exists to end.
///
/// So the description says "a thing called `day-plan` goes here" and stops.
/// The name is opaque: this crate never interprets it, and no renderer is
/// expected to know what it means beyond handing the space over.
Bespoke {
/// What the app calls it. Never interpreted here.
name: &'a str,
},
/// A named assembly of things the vocabulary already says.
///
/// The third tier, between a primitive and [`Bespoke`](Self::Bespoke).
/// Stated by Max 2026-08-12 answering the carousel: "something in between a
/// primitive and a bespoke interface, like a widget, which is just an
/// assembly of primitives." Full note: wiki `widget-tier`.
///
/// # What separates it from the two members either side
///
/// A primitive is a thing every renderer draws from scratch, and the test
/// it has to pass is that every host has an honest answer. A carousel fails
/// that test — a terminal has no carousel — which is the same refusal
/// `Node::Html` got and is why the carousel sat unsayable for months.
///
/// [`Bespoke`](Self::Bespoke) fails it from the other side. Bespoke is for
/// what one app owns and nobody will build twice, and it carries *no*
/// contents: the description names the place and stops. A carousel is
/// furniture any app would have, and every part of it — an ordered set of
/// frames, a position, prev and next, a strip of position indicators — is
/// already sayable. Only the assembly had no name.
///
/// So this member is the pair the other two are not: a name **and**
/// contents. The contents are the assembly, in the region's own body, said
/// in members that already exist.
///
/// # Why the name does not have to be understood
///
/// A renderer that recognises the name draws it the way its host does it: a
/// carousel in a webview, a pager with a count in a terminal, a selector in
/// egui. A renderer that does not recognise it walks the body, which is
/// primitives all the way down and which it can already draw.
///
/// That is what lets the widget set be **open** without every renderer
/// knowing every widget. An unrecognised widget degrades to its assembly
/// instead of failing, so a second or third party can name one without
/// three renderers releasing in lockstep to accept it. Contrast
/// [`Bespoke`](Self::Bespoke), which no renderer can degrade: there is
/// nothing under it to fall back to.
///
/// # What it does not do
///
/// A widget is an assembly of things the vocabulary *already* says, so it
/// buys no expressive power. Anything needing a member the vocabulary does
/// not have is a finding about the vocabulary, and the answer to a finding
/// is to add the member. A widget is never the way a primitive gets added
/// by the back door.
///
/// This used to say "it does not make a timeline describable, and the
/// refusal in the crate header stands unchanged". The timeline is
/// describable as of 2026-08-15 -- see [`Track`] -- and it got there the
/// way the paragraph above says it should have: by adding the two members
/// that were missing, not by dressing the screen up as an assembly.
Widget {
/// What the assembly is called. This crate never interprets it, and a
/// renderer is free not to know it.
name: &'a str,
},
}
impl<'a> Region<'a> {
/// How the region sits on what is behind it.
#[must_use]
pub const fn depth(self) -> Depth {
match self {
Self::Band | Self::Sidebar | Self::Split | Self::TabGroup => Depth::Flat,
// Flat, and it inherits. A group says its contents belong together
// and says nothing about the surface they sit on, so a group in a
// pane is in a well and a group on the page is on the page. An app
// wanting one lifted puts it in a `Pane`.
Self::Group => Depth::Flat,
// Flat, and it is the container rather than the columns. Each
// column is its own region and brings its own depth; a well here
// would put a second edge around a row of wells.
Self::Columns => Depth::Flat,
// A pane is looked into, the same as a table body or a tag tree.
Self::Pane => Depth::Well,
Self::Modal => Depth::Raised,
// Flat because it inherits: a bespoke region takes the depth of
// whatever frames it. An app that wants its timeline in a well puts
// it in a `Pane`, which composes rather than adding a knob here.
//
// A widget inherits for the same reason and it matters more here,
// because a widget is drawn by whichever renderer recognises it. A
// depth set here would be this crate deciding that a carousel is
// raised on every host, which is the kind of value the deferral
// rule exists to refuse.
Self::Bespoke { .. } | Self::Widget { .. } => Depth::Flat,
}
}
/// Whether this crate can say anything about the region's contents.
///
/// A renderer walks the description and hands every region it understands
/// to the right drawing code. This is how it tells the two apart, and the
/// reason it is a method rather than a `matches!` at each renderer: there
/// is exactly one opaque member and there should stay exactly one.
///
/// [`Widget`](Self::Widget) is described, and that is the whole of what
/// separates it from [`Bespoke`](Self::Bespoke) here. Both carry a name
/// this crate never interprets; only one of them carries contents under it.
/// A renderer that does not recognise a widget's name still walks its body,
/// so there is nothing for it to hand over and nothing it cannot draw.
#[must_use]
pub const fn described(self) -> bool {
!matches!(self, Self::Bespoke { .. })
}
/// The name an app gave this region, if it gave one.
///
/// [`Bespoke`](Self::Bespoke) and [`Widget`](Self::Widget) are the two
/// members that carry a name, for two different purposes: one says what the
/// app will fill the space with, the other says what the assembly under it
/// is called. A renderer dispatching on either wants the string without
/// caring which member it came from, and writing that `matches!` at each
/// renderer is how the two drift apart.
#[must_use]
pub const fn name(self) -> Option<&'a str> {
match self {
Self::Bespoke { name } | Self::Widget { name } => Some(name),
// Spelled out rather than a wildcard, so a member added later has
// to answer whether it carries a name instead of inheriting `None`
// by sitting under a `_`.
Self::Band
| Self::Sidebar
| Self::Pane
| Self::Group
| Self::Split
| Self::Columns
| Self::TabGroup
| Self::Modal => None,
}
}
}
/// How many of a region's children are visible at once.
///
/// `4dcd241b`. Three findings turned out to be one sentence the vocabulary
/// could not say: *this region holds several children and shows some of them,
/// and the reader can change which.* [`Region::TabGroup`] existed with nothing
/// saying which tab was open, a carousel had nothing saying which frame was up,
/// and a disclosure had nothing saying whether its one child was showing at all.
///
/// Because the fact lived nowhere, a renderer had two moves: hardcode a widget
/// name, or draw every child. That is what put per-widget code in renderers, and
/// it was the missing member rather than the widget tier that put it there.
///
/// # What is here and what is not
///
/// The *kind*, and only the kind. Which child is currently up is the current
/// answer, and a layer that defers every address does not hold the current
/// answer either — the split [`Selector`] already makes, where this crate says
/// what kind of chooser a thing is and the router says which option is picked.
/// So a holder of regions carries the index and the per-child label beside this.
///
/// # What a renderer does with it
///
/// Derives its chrome, once, for every widget rather than per name:
///
/// - Children carrying labels get a strip of the labels, the current one marked.
/// - Children carrying none get previous, position, next.
/// - [`AtMostOne`](Self::AtMostOne) over one child gets a summary line that
/// opens.
///
/// The name on [`Region::Widget`] survives as app vocabulary, for a renderer
/// that wants to do something *special* with one, which is what it should have
/// been from the start.
///
/// Degradation runs the way it already did: a renderer ignoring this draws every
/// child, which is more content rather than less.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Showing {
/// Every child, in order. What every region did before this existed.
#[default]
All,
/// Exactly one. A carousel, a tab group.
One,
/// One, or none. A disclosure, which is closed until it is opened.
AtMostOne,
}
impl Showing {
/// Whether the reader can change which child is up.
///
/// The question every renderer's region arm asks before deriving any
/// chrome, and a method rather than a `matches!` at each renderer for
/// [`Region::name`]'s reason: three renderers writing the same comparison is
/// how they come to disagree about a member added later.
#[must_use]
pub const fn selective(self) -> bool {
!matches!(self, Self::All)
}
/// Whether showing nothing is a legal state.
///
/// True only for [`AtMostOne`](Self::AtMostOne). A renderer needs this to
/// know whether its control closes as well as moves: a carousel's row moves
/// between frames and never reaches empty, and a disclosure's summary line
/// is the same control wearing its closed state.
#[must_use]
pub const fn dismissible(self) -> bool {
matches!(self, Self::AtMostOne)
}
}
/// A window onto a sequence: where it starts, how much it covers, and how long
/// the sequence is when that is known.
///
/// The mechanism under two things the vocabulary deliberately keeps apart. A
/// carousel is a window of one frame over children that are all present; a
/// paged list is a window of a page over rows most of which were never fetched.
/// Those are different facts and they stay different types — [`Showing`] says
/// which child is up, [`Paging`] says where a reader is in a query — but the
/// arithmetic underneath is one piece of code, so a terminal and a browser
/// cannot come to disagree about which frame is last.
///
/// # Why `of` is optional and `count` is not
///
/// `count` is what is on screen and is therefore always known. `of` is the
/// length of the thing being windowed, and a host that cannot count says so by
/// leaving it empty **for the life of the screen**. It is never "not counted
/// yet": see "First paint is final paint" in the crate header. A total that
/// turns up on a later pass widens the text that prints it.
///
/// # Clamping
///
/// Every derivation clamps rather than refusing, and a zero `count` answers
/// `None` rather than dividing. A window past the end is a bug in the host, and
/// a renderer that answered it by drawing nothing would report a region that
/// vanished, which is the hardest kind of bug to find from what is on screen.
/// [`Share::percent`] clamps for the same reason.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Window {
/// The index into the sequence where the window starts.
pub from: usize,
/// How many the window covers. One, for a carousel.
pub count: usize,
/// How long the sequence is, when the host can say.
pub of: Option,
}
impl Window {
/// A window of `count`, starting at `from`, over a sequence of unknown
/// length.
#[must_use]
pub const fn new(from: usize, count: usize) -> Self {
Self {
from,
count,
of: None,
}
}
/// How long the sequence is.
#[must_use]
pub const fn of(mut self, of: usize) -> Self {
self.of = Some(of);
self
}
/// One item of a sequence whose length is known. A carousel frame.
#[must_use]
pub const fn frame(at: usize, of: usize) -> Self {
Self {
from: at,
count: 1,
of: Some(of),
}
}
/// Which window this is, counting from zero.
///
/// `None` when `count` is zero, which is the only input with no answer
/// rather than a clamped one.
#[must_use]
pub const fn index(self) -> Option {
if self.count == 0 {
return None;
}
Some(self.from / self.count)
}
/// How many windows the sequence holds.
///
/// `None` unless both the length and a non-zero `count` are known. A
/// partial answer here would be a renderer drawing "of 0".
#[must_use]
pub const fn windows(self) -> Option {
match self.of {
Some(of) if self.count > 0 => Some(of.div_ceil(self.count)),
_ => None,
}
}
/// Whether anything sits before this window.
#[must_use]
pub const fn has_before(self) -> bool {
self.from > 0
}
/// How many sit after this window, when the length is known.
///
/// Here rather than in each renderer for [`Showing::selective`]'s reason:
/// three of them writing the same subtraction is how they come to disagree,
/// and this one has an underflow in it for whoever writes it fourth.
#[must_use]
pub const fn after(self) -> Option {
match self.of {
Some(of) => Some(of.saturating_sub(self.from.saturating_add(self.count))),
None => None,
}
}
/// Whether anything sits after it.
///
/// `true` when the length is unknown: a host that cannot count cannot rule
/// out more, and offering a way forward that turns out to be empty is the
/// cheaper of the two mistakes.
#[must_use]
pub const fn has_after(self) -> bool {
match self.of {
Some(of) => self.from.saturating_add(self.count) < of,
None => true,
}
}
/// The window with `from` brought inside the sequence.
///
/// A no-op when the length is unknown, since there is nothing to clamp
/// against.
#[must_use]
pub const fn clamped(mut self) -> Self {
if let Some(of) = self.of
&& self.from >= of
{
// `max(1)` by hand: `Ord::max` is not const yet, and a zero-count
// window would otherwise clamp onto the end rather than inside it.
let step = if self.count == 0 { 1 } else { self.count };
self.from = of.saturating_sub(step);
}
self
}
}
/// Where a reader is in a set that arrived in parts.
///
/// A [`Window`] wearing the paged reading of itself. Distinct from a carousel's
/// window at the top level on purpose, because the intent differs and a call
/// site should say which one it means, while the arithmetic below is shared so
/// the two cannot drift apart.
///
/// # The two idioms, and which one a renderer may draw
///
/// Load-more and numbered pages are both this type. Which is honest is
/// [`paged`](Self::paged): a set whose page size is known can be drawn as
/// "Page 3 of 8", and one without can only be drawn as "150 of 400" and a way
/// forward. Saying it here rather than letting each renderer guess is the point
/// — three renderers inferring it from the numbers is how they come to disagree.
///
/// # What it does not carry
///
/// No addresses. `makeover-layout` cannot name an action, and the way to ask for
/// the next part is the host's: `quasi_router` pairs this with the addresses the
/// same way `Row` pairs its parts with `Row::activate`. That split is the reason
/// this type is reusable by a carousel, which has nothing to ask.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Paging {
/// The window onto the set.
pub window: Window,
/// Whether the parts are a fixed size, and so whether pages are countable.
///
/// `false` for load-more, where the window simply grew and "page 2" would
/// name nothing.
pub paged: bool,
}
impl Paging {
/// A page of `per`, starting at `from`.
#[must_use]
pub const fn pages(from: usize, per: usize) -> Self {
Self {
window: Window::new(from, per),
paged: true,
}
}
/// The first `shown`, with more behind them.
///
/// The load-more shape: the window starts at the beginning and grows, so
/// there is no page to number.
#[must_use]
pub const fn more(shown: usize) -> Self {
Self {
window: Window::new(0, shown),
paged: false,
}
}
/// How many there are altogether.
///
/// Left unsaid by a host that cannot count, and left unsaid **for good**:
/// a total arriving later widens whatever prints it. See "First paint is
/// final paint" in the crate header.
#[must_use]
pub const fn of(mut self, of: usize) -> Self {
self.window = self.window.of(of);
self
}
/// Which page this is, counting from one, when pages are countable.
///
/// One-based because it is read aloud. [`Window::index`] is the zero-based
/// form for anyone indexing with it.
#[must_use]
pub const fn page(self) -> Option {
if !self.paged {
return None;
}
match self.window.index() {
Some(index) => Some(index + 1),
None => None,
}
}
/// How many pages there are, when that is countable.
#[must_use]
pub const fn pages_total(self) -> Option {
if !self.paged {
return None;
}
self.window.windows()
}
/// How many are on screen.
#[must_use]
pub const fn shown(self) -> usize {
self.window.count
}
/// How many there are, when the host counted.
#[must_use]
pub const fn total(self) -> Option {
self.window.of
}
/// How many are not shown yet, when the host counted.
///
/// The figure a load-more control puts in its label. `None` is the honest
/// and common case: a set that cannot say how many more there are still has
/// a way to ask for them.
#[must_use]
pub const fn remaining(self) -> Option {
self.window.after()
}
/// Whether there is anything further on.
#[must_use]
pub const fn has_more(self) -> bool {
self.window.has_after()
}
/// Whether there is anything back the other way.
#[must_use]
pub const fn has_previous(self) -> bool {
self.window.has_before()
}
}
/// How much of the width an arrangement's first region takes.
///
/// `e0fd485e`. Nothing said how much room a region got, so every renderer
/// invented its own number and two hosts showing one screen disagreed about
/// its proportions. A webview never noticed, because the stylesheet answered
/// once for every consumer; a terminal has no stylesheet to inherit from, so
/// `quasi-tui` picked 24 columns for a sidebar and 40% for a list pane and
/// neither had anything behind it.
///
/// # A proportion, never a unit
///
/// Held as a percentage, and that is the only form it comes in. A description
/// carrying columns would be describing a terminal and one carrying pixels a
/// webview, and the whole point is that both honour the same fact: a terminal
/// resolves it against a column count, a webview writes it into a grid, and
/// neither has to know what the other did.
///
/// It is not [`makeover_geometry::Ratio`]'s job either, which was the first
/// guess. Geometry is scales that answer the same for every screen and takes
/// no input that would let a sidebar screen differ from a list-detail one.
///
/// [`makeover_geometry::Ratio`]: https://docs.rs/makeover-geometry
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct Share(u8);
impl Share {
/// What a sidebar takes, when nobody says otherwise.
///
/// A quarter. `quasi-tui` drew 24 columns, which is a quarter of a
/// 96-column terminal and about a fifth of a wide one; a quarter is that
/// number said in the form a webview can honour too.
pub const SIDEBAR: Self = Self(25);
/// What the list side of a list-detail takes, when nobody says otherwise.
///
/// `quasi-tui`'s 40%, which was already a proportion and is the one number
/// this member did not have to invent.
pub const LIST: Self = Self(40);
/// A share of the width, as a percentage.
///
/// Clamped to 5..=95 rather than refused. A description that asked for a
/// region of nothing is a bug in the app, and a renderer drawing a region
/// zero cells wide reports it as a region that vanished, which is the
/// hardest kind of bug to find from what is on the screen.
#[must_use]
pub const fn percent(percent: u8) -> Self {
Self(if percent < 5 {
5
} else if percent > 95 {
95
} else {
percent
})
}
/// The share as a percentage.
#[must_use]
pub const fn as_percent(self) -> u8 {
self.0
}
/// This share of a width, rounded to the nearest whole unit.
///
/// What a terminal calls to turn the proportion into columns. At least one,
/// because a region the description named should be visible: a screen
/// 3 columns wide is unusable either way, and a sidebar that is there is a
/// truer picture of the description than a sidebar that is not.
#[must_use]
pub const fn of(self, whole: u16) -> u16 {
let taken = (whole as u32 * self.0 as u32).div_ceil(100);
if taken == 0 { 1 } else { taken as u16 }
}
}
/// How a screen is laid out.
///
/// Two, and the second is not a variant of the first. goingson is list-detail,
/// Balanced Breakfast is sidebar plus content, and neither app has a third.
/// The tab group is a modifier rather than a member, because goingson uses it
/// *inside* the same content region rather than instead of one.
///
/// This exists at all because the router has to be able to express a screen
/// rather than only a control. Discovering the arrangement layer missing after
/// the renderers exist is a redesign; naming two now is a morning.
///
/// # Why the share rides here
///
/// `e0fd485e`. A share is per-arrangement: how much a sidebar takes and how
/// much a list side takes are different questions, and this enum is the only
/// thing that knows which one is being asked. Geometry would have had to invent
/// a channel to be told.
///
/// [`list_detail`](Self::list_detail) and
/// [`sidebar_content`](Self::sidebar_content) build these with the default
/// shares, so a screen that has no opinion does not have to have one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Arrangement {
/// A list that chooses what the detail beside it shows.
ListDetail {
/// Whether the detail side is a [`Region::TabGroup`].
tabbed: bool,
/// How much of the width the list side takes.
share: Share,
},
/// Navigation down the side, content filling the rest.
SidebarContent {
/// How much of the width the sidebar takes.
share: Share,
},
}
impl Arrangement {
/// A list and a detail beside it, at the default share.
#[must_use]
pub const fn list_detail(tabbed: bool) -> Self {
Self::ListDetail {
tabbed,
share: Share::LIST,
}
}
/// A sidebar and content beside it, at the default share.
#[must_use]
pub const fn sidebar_content() -> Self {
Self::SidebarContent {
share: Share::SIDEBAR,
}
}
/// How much of the width the first region takes.
#[must_use]
pub const fn share(self) -> Share {
match self {
Self::ListDetail { share, .. } | Self::SidebarContent { share } => share,
}
}
/// The same arrangement, at this share.
#[must_use]
pub const fn with_share(self, share: Share) -> Self {
match self {
Self::ListDetail { tabbed, .. } => Self::ListDetail { tabbed, share },
Self::SidebarContent { .. } => Self::SidebarContent { share },
}
}
}
/// How wide the content of a whole screen runs.
///
/// `0eccff0d`, and [`Share`]'s sibling one level up: that one says how a
/// screen's width is divided between regions, this says how much of the window
/// the screen uses in the first place. Both are the description's, which is
/// what answering the two together settled.
///
/// Measured in the MNW server, where 69 of 72 templates carry exactly one of
/// three mutually exclusive classes and the choice is per screen. GoingsOn
/// reaches for `max-width` 56 times and Balanced Breakfast 12, neither with a
/// token for it, so three apps were solving one thing by hand.
///
/// # Named for the measure, not for MNW's classes
///
/// A renderer that is not a browser has to answer this too, and `padded-page`
/// tells a terminal nothing. The three say how wide the text runs, which is a
/// question every renderer can answer: a webview with a `max-width`, a terminal
/// with gutters, an immediate-mode frame with its own width.
///
/// `#[non_exhaustive]` for [`Fill`]'s reason. The set is closed today because
/// the measurement found three, and a fourth arriving should not be a lockstep
/// release across nine repos.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Measure {
/// The whole width, with gutters. The default, and 53 of the 69.
///
/// What a dashboard, a table and a settings screen want: the content is
/// wide because the content *is* wide, and constraining it would waste the
/// window.
#[default]
Wide,
/// Capped at a comfortable page width, centred. 13 of the 69.
///
/// A form, a sign-in, a purchase. Content that does not get better by
/// getting wider, but is not prose either.
Contained,
/// Capped at a line length that reads well. 3 of the 69.
///
/// Prose. The narrowest of the three, and the one with a reason outside
/// taste: a line of text past roughly 75 characters costs the reader the
/// return sweep.
Reading,
}
impl Measure {
/// A stable name, for a renderer that needs to spell it.
///
/// Here rather than in each renderer for [`Sort::as_str`]'s reason: three
/// renderers spelling one enum is three chances to spell it differently.
#[must_use]
pub const fn as_str(self) -> &'static str {
match self {
Self::Wide => "wide",
Self::Contained => "contained",
Self::Reading => "reading",
}
}
}
/// What kind of value a form field takes.
///
/// The union of the two vocabularies that diverged, which is what triggered
/// this crate. They have since converged on their own: both apps now have a
/// `renderFormField` emitting the same anatomy, and what is left differing is
/// the kind set, the error shape, and whether the return is a string or a node.
///
/// Validation is deliberately absent. Neither app has a shared story (goingson
/// validates after collecting the form data, with per-field transform hooks;
/// Balanced Breakfast has `required` and nothing else), and a schema that
/// describes fields but not constraints acquires a constraint layer per app,
/// which is exactly how the current divergence started. Naming it absent is a
/// decision; leaving it unmentioned would not be.
/// `#[non_exhaustive]` for the reason [`Fill`] is: renderers match on this and
/// the set keeps growing, so growth must not be a lockstep event. Email, Url
/// and Tel arriving in 0.5.0 is the second growth in two releases.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum FieldKind {
/// A single line of text.
Text,
/// A single line of text that must never be echoed, logged or round-tripped
/// through anything that might persist it.
Secret,
/// A number.
Number,
/// A number inside bounds the user drags across, where the range being
/// visible is the point.
///
/// Not [`Number`](Self::Number) with [`min`](Field::min) and
/// [`max`](Field::max), which is the reading to resist and is the same
/// resistance [`Radio`](Self::Radio) needed against `Select`. A bounded
/// number and a validated number are different *questions*. A validated
/// number is typed and can be wrong: the bounds are a rule the answer is
/// checked against, and being told "must be at least 1" afterwards is the
/// normal course of it. A range cannot be out of range at all, because the
/// bounds are the control's extent rather than a rule, and the two ends are
/// what the question means — audiofiles asks for a classifier threshold
/// between 0 and 1, where 0 is never and 1 is only-on-certainty, and a typed
/// 0.72 says nothing without both ends on screen beside it.
///
/// A renderer cannot infer which one is meant from `min`/`max` alone, which
/// is why this is a kind and not an inference: goingson's `min="1"` duration
/// is a validated number and would become a slider.
///
/// The membership test passes without stretching: a webview emits
/// `` or a `