makeover_layout/

lib.rs

//! The renderer-agnostic half of the make-family design system.
//!
//! <!-- wiki: makeover-layout -->
//!
//! `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.** [`Bevel`], [`Edge`], [`Fill`], [`Depth`]: the bevel and the
//!   surfaces it shapes. Fill and bevel are named together, so a raised bevel
//!   over a recessed fill is unrepresentable.
//! - **Components.** [`Token`] (badge against chip), [`Notice`] (toast against
//!   banner), [`RowPart`], [`CellPart`], [`Heading`], [`Selector`],
//!   [`Readiness`], [`Awaiting`], [`Meter`], [`Figure`], [`Track`],
//!   and [`Tone`], the one intent family they share.
//! - **Schemas.** [`Field`] for forms, [`Column`] for lists and tables,
//!   [`Facet`] for the dimensions a set is narrowed by.
//! - **Structure.** [`Region`] for the parts of a screen, [`Arrangement`] for
//!   how a screen is put together, [`Showing`] for how many of a region's
//!   children are visible at once.
//!
//! # What a member is admitted on
//!
//! 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. Three tests, all of which have to pass:
//!
//! - **Generic against bespoke.** Is this furniture any app would have, or is
//!   it this app's own? A rule that withholds a word until a second app has
//!   duplicated the code guarantees the duplication. Bespoke keeps
//!   [`Region::Bespoke`].
//! - **Every host has an honest answer.** A member no renderer can express
//!   without borrowing one host's idiom is not a description.
//! - **It can be laid out before it is filled.** See *First paint is final
//!   paint* below.
//!
//! Count the members a thing needs before refusing it. A refusal is only worth
//! as much as the measurement under it.
//!
//! # What this crate cannot say
//!
//! - **An address.** What a control calls, and where a button goes. [`Act`]
//!   names the act and holds no destination.
//! - **A current value.** A webview reads it out of the DOM and an
//!   immediate-mode renderer holds a `&mut` to the app's own field. A
//!   description carrying it would be a form model.
//! - **What has focus.** See below.
//! - **A duration or a clock.** No estimate of time remaining, no autosave
//!   interval, no animation length.
//! - **A colour, a size or a position.** The deferral rule.
//!
//! # Reach, focus and the focus ring
//!
//! Three terms, and no others, for what sits outside 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 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, read as dead lists if they wear
//! it. 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
//!
//! 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. 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
//!
//! 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. It is not a quota, and the goal is every screen described.
//!
//! A timeline is describable. What it needs and could not previously get is two
//! integers, where a thing starts and how long it lasts, which is [`Track`].
//! Slot heights, gridline colour, how overlapping things stack and which hour
//! scrolls into view stay the renderer's, and `Track` carries none of them.
//!
//! A kanban board is describable, and the member is [`Region::Columns`]. Every
//! card fact is already sayable through `Row`'s parts; what nothing else could
//! say is that the columns are *peers*, since [`Arrangement`] offers only
//! list-detail and sidebar-content and a board described as either is a lie
//! about the screen. Dragging a card between columns does not enter into it: a
//! drop's effect is "set status", a discrete action `Row`'s menu already
//! carries, and the drag itself is affordance.
//!
//! A calendar takes no members. 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, and routes, search and ranking do that job better.
//! 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`], and [`Track::days`] is it.
//! 2. **Density at a glance**, which weeks were heavy. That is a heatmap, and a
//!    heatmap describes as a list.
//! 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.
//!
//! Job 3 is the only open question, and nothing in the tree asks for it. A
//! month grid otherwise renders as a [`Table`](crate::Column): seven weekday
//! columns, weeks as rows, blanks for the offset. If a screen wants one,
//! measure the members it needs before adding any.
//!
//! [`Region::Bespoke`] remains for the genuinely app-owned. 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 screens
//! that make an app worth using would need a second, undescribed path beside
//! the router, and two paths is how a vocabulary drifts from its app.
//!
//! [`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
//! 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. 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.
    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 already has the surface: `makeover-tui` carries
    /// `Palette::overlay`, `makeover-immediate` `Palette::elevation`, and
    /// `makeover-webview` emits `--elevation-overlay`. This variant is the
    /// route from a description to any of them, which is why it 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<Bevel> {
        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<Fill> {
        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 is not on this axis. 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.
///
/// `#[non_exhaustive]`: a renderer carries a wildcard arm, so a new part is not
/// a lockstep event across three renderers.
///
/// # 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,
        }
    }
}

/// How deep a row sits inside a set: a tree, an outline, a threaded list.
///
/// [`RowPart`] below already names what is *in* a row; nothing named where a
/// row sits relative to its siblings, so every consumer that had a hierarchy
/// carried a bare number and every renderer decided for itself what one was
/// worth.
///
/// # Not `Depth`, and the collision is the reason
///
/// [`Depth`] is taken and means something else entirely: surface bevel --
/// `Flat`, `Raised`, `Well`, `Sunken`, `Overlay` -- a fact about a surface
/// rather than a position in a hierarchy. Two meanings under one word in one
/// crate is the collision that costs a reader an hour, and the word this
/// concept wants is the one that would cause it.
///
/// # The magnitude is the renderer's, and that is the precedent
///
/// [`Awaiting`] is the shape: this crate names the fact and declines to name
/// what it is worth. makeover-webview writes the rule as a custom property with
/// a fallback -- the way it writes `margin-inline-start: var(--awaiting-gap,
/// 0.5ch)` -- so a level has one answer per renderer and an app can override
/// it. A terminal spends columns, a browser spends inline space, and neither
/// number belongs in a description.
///
/// # Zero is a real answer
///
/// [`top`](Self::top) is the default and is what a flat list says: every row is
/// at the top level, which is true and is the reading a renderer needs. An
/// `Option` here would make "not nested" and "nested at zero" two spellings of
/// one thing, the same argument `Discovery`'s `indexable` makes about defaults
/// that are meaningful.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default, PartialOrd, Ord)]
#[non_exhaustive]
pub struct Nesting {
    /// How many levels in, counting from zero.
    ///
    /// `u8` because a hierarchy a reader can follow is not 256 deep, and a
    /// renderer indenting by a level has to multiply it by something -- a wider
    /// integer here is a wider integer in every renderer's arithmetic for a
    /// range nothing will use.
    pub level: u8,
}

impl Nesting {
    /// The top level: not nested. The default, and what a flat list says.
    #[must_use]
    pub const fn top() -> Self {
        Self { level: 0 }
    }

    /// A row this many levels in.
    #[must_use]
    pub const fn at(level: u8) -> Self {
        Self { level }
    }

    /// Whether this row sits under another.
    ///
    /// The question every renderer asks before it spends anything on indenting,
    /// answered once here rather than by a `> 0` in each -- which is
    /// [`Awaiting::is_determinate`]'s reason too.
    #[must_use]
    pub const fn is_nested(self) -> bool {
        self.level > 0
    }
}

#[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.
    ///
    /// A row holds no nodes, by the rule that a row part may not carry an
    /// arbitrary node, which is 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.
    ///
    /// 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
///
/// Naming only `Ready` and `Pending` leaves a screen whose list came back empty
/// with nothing to say about it, so it renders an empty region or invents its
/// own placeholder text and neither says what it is. Left to the apps, the
/// class family drifts: `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<u64>,
}

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.
///
/// 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. 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.
    ///
    /// 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.
///
/// 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'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<f32> {
        (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
///
/// Emitting the webview's `loading="lazy"` for every picture reads one
/// consumer's 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,
}

/// 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.
#[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
///
/// The argument against naming a timeline is that a description expressive
/// enough to draw one is a component library wearing a description's name. It
/// does not hold here, and being precise about why matters, because the
/// reasoning applies to real cases.
///
/// 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. A control's focus is not sayable here at
    /// all: see the crate header, "Reach, focus and the focus ring".
    pub state: Option<State>,
    /// 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
    ///
    /// A hint left to `quasi_router::Act` alone means each renderer draws 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.
    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]`, for [`RowPart`]'s and [`Readiness`]' 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`] names, which the vocabulary otherwise
    /// cannot contain. 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).
    ///
    /// # 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. A timeline is describable because [`Track`] was added
    /// to say it, not because a screen was dressed 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.
///
/// One sentence covering three shapes: *this region holds several children and
/// shows some of them, and the reader can change which.* A tab group, a
/// carousel and a disclosure all need it, and without it a renderer has two
/// moves: hardcode a widget name, or draw every child. That is what puts
/// per-widget code in renderers.
///
/// # 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<usize>,
}

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<usize> {
        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<usize> {
        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<usize> {
        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<usize> {
        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<usize> {
        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<usize> {
        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<usize> {
        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.
///
/// 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.
///
/// Three, and no one of them is a variant of another. goingson is list-detail,
/// Balanced Breakfast is sidebar plus content, and MNW's embeds are one region
/// filling the document. 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
///
/// 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,
    },
    /// One region, filling the document.
    ///
    /// The other two are both about dividing a width between two regions, so a
    /// screen that is one region had to borrow one of them and then undo it:
    /// MNW's five embeds said `list_detail(title, false)` and the host spent a
    /// `display: block` cancelling the grid that produced. A host writing CSS
    /// to contradict the description rather than to add to it is the thing
    /// this member ends.
    ///
    /// Carries no [`Share`], because there is no division to describe. That is
    /// why [`share`](Self::share) answers `None` here.
    Single,
}

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, when two regions divide it.
    ///
    /// `None` for [`Single`](Self::Single): one region takes the width, and a
    /// renderer that asked how to divide it was asking the wrong question. It
    /// answers `Option` rather than a full-width `Share` so that a host cannot
    /// quietly draw a one-region screen as a grid with an empty second column.
    #[must_use]
    pub const fn share(self) -> Option<Share> {
        match self {
            Self::ListDetail { share, .. } | Self::SidebarContent { share } => Some(share),
            Self::Single => None,
        }
    }

    /// The same arrangement, at this share.
    ///
    /// [`Single`](Self::Single) is returned unchanged: it has no division to
    /// set, so a share named for it is a statement about nothing rather than an
    /// error worth refusing a screen over.
    #[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 },
            Self::Single => Self::Single,
        }
    }
}

/// How wide the content of a whole screen runs.
///
/// 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.
#[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
    /// `<input type="range">`, egui has `Slider`, a terminal draws a bar and
    /// takes arrow keys, a CLI takes a bounded argument.
    ///
    /// # It owes its bounds
    ///
    /// [`min`](Field::min) and [`max`](Field::max) are `Option` for every other
    /// kind and are **required** here, in the sense the description can require
    /// anything: [`Field::bounded`] is the check, and a range missing one has no
    /// extent for a renderer to draw. What a renderer does with an unbounded
    /// range is its own call and both answers are honest — fall back to a typed
    /// number, or pick a host default — so this is stated rather than enforced,
    /// the way every other constraint here is.
    ///
    /// [`Field::step`] is the third fact and is genuinely optional: absent, the
    /// host's own granularity stands.
    Range,
    /// One question with two ends: a lower value and an upper one, submitted
    /// under two names.
    ///
    /// "Show me samples between 90 and 130 BPM" has a single answer with two
    /// ends, and the ends constrain each other: a minimum above the maximum is
    /// not a wrong value, it is an empty result nobody asked for. Described as
    /// two [`Number`](Self::Number) fields that is unsayable — nothing says they
    /// are one question, so a renderer draws two controls with two labels and no
    /// relationship, and [`Field::error`] can only be attached to one side of a
    /// fault that belongs to both.
    ///
    /// Not [`Range`](Self::Range), which was the reading to resist and the
    /// resistance is the same one `Range` itself needed against `Number`. A
    /// range describes *one* value inside an extent; this describes two, and the
    /// extent is a bound on each rather than the question's meaning. The two
    /// come apart in the answer: a range has a value, an interval has a pair,
    /// and either end may be absent while the other stands.
    ///
    /// # It states both names
    ///
    /// [`Field::name`] is the lower end and [`Field::upper_name`] is the upper
    /// one, stated rather than derived. One member instead of a naming
    /// convention this crate would then own forever.
    ///
    /// Direction is carried by which member the name sits in, so nothing
    /// separate says which end is which.
    ///
    /// # What it does not enforce
    ///
    /// The crossing rule. A lower end above the upper one is describable here
    /// and always was, exactly as an out-of-[`min`](Field::min) number is: this
    /// crate carries constraints and never checks them, and deciding a value is
    /// wrong stays with whoever validated. What the description buys is that the
    /// fault now has one place to be reported rather than two.
    ///
    /// # Both ends take the same facts
    ///
    /// [`min`](Field::min), [`max`](Field::max), [`step`](Field::step) and
    /// [`unit`](Field::unit) describe the axis rather than one end of it, so
    /// they are read once and applied to both. Six of audiofiles' filter axes
    /// are exactly this: one extent, one unit, one granularity, two ends.
    ///
    /// The bounds are optional here, unlike `Range`. They are a rule the answer
    /// is checked against rather than the control's extent, which is
    /// [`Number`](Self::Number)'s arrangement and not a slider's.
    Interval,
    /// An email address.
    ///
    /// Distinct from [`Text`](Self::Text) because the distinction is not
    /// decoration: a webview renderer emits `type="email"`, which on a touch
    /// device changes the keyboard that appears and turns on the platform's own
    /// validation. goingson ships to iOS, so collapsing this into text costs a
    /// keyboard with no `@` on it.
    Email,
    /// A URL. Same reasoning as [`Email`](Self::Email).
    Url,
    /// A telephone number. Same reasoning as [`Email`](Self::Email), and the
    /// clearest case of it: the keyboard is a numeric pad rather than letters.
    Tel,
    /// A calendar day, with no time of day in it.
    ///
    /// [`Email`](Self::Email)'s argument, and it carries further: a webview
    /// emits `type="date"`, which is a native picker, the platform's own
    /// validation, and on a touch device the date keyboard. Described as
    /// [`Text`](Self::Text) with a hint reading "YYYY-MM-DD", all three are
    /// lost and the hint is doing the platform's job in prose.
    ///
    /// The membership test passes on every host without stretching: a webview
    /// and a Tauri app emit the input, egui has a date picker, a terminal
    /// prompts for a day and can validate it, a CLI takes an argument.
    ///
    /// # The value is ISO 8601, `YYYY-MM-DD`
    ///
    /// Named here rather than left to each host, because a host that picks
    /// differently sends a server something it parses differently, and the
    /// failure is silent and per-host. It is `<input type="date">`'s own wire
    /// format, so the webview renderer owes nothing to honour it and the other
    /// hosts have one spelling to meet. [`DATE_FORMAT`] is the constant, and a
    /// test asserts this doc and that constant agree.
    Date,
    /// A calendar day and a time of day together.
    ///
    /// Apart from [`Date`](Self::Date) because the question is different rather
    /// than more precise: "which day does this expire" and "at what moment does
    /// this publish" are asked by different screens and answered by different
    /// controls. A webview emits `type="datetime-local"` for one and
    /// `type="date"` for the other, and a host that collapsed them would ask
    /// half the tree for a precision it does not want.
    ///
    /// Both arrived together on measurement rather than on symmetry: 13 sites
    /// of each across the MNW server and goingson, and **zero** of `time`,
    /// `month` or `week`, which is why those are not here. A member added for a
    /// case nobody has is a member designed against nothing, which is
    /// [`File`](Self::File)'s reasoning about `accept` applied to a whole
    /// member.
    ///
    /// # The value is `YYYY-MM-DDTHH:MM`, local, with no zone
    ///
    /// `<input type="datetime-local">`'s own format, and the "local" is the
    /// load-bearing half: the value carries no offset and no `Z`, so the moment
    /// it names is only fixed once something supplies a zone. That is the app's
    /// business and not the description's. Seconds are absent, which is the
    /// browser's own default and is left as the rule rather than restated as a
    /// constraint. [`DATETIME_FORMAT`] is the constant.
    ///
    /// [`Field::min`] and [`Field::max`] already take "the host's own spelling
    /// of a bound", so a floor of *not in the past* needs nothing new here: it
    /// is a string in this same format.
    DateTime,
    /// Several lines of text.
    Textarea,
    /// Several lines of text the user writes markdown in.
    ///
    /// The editing counterpart of prose a description carries as markdown
    /// source, and the reason it can exist at all is the same one that lets the
    /// source be carried: editing markdown is editing text, so a terminal, an
    /// immediate-mode host and a webview all have an honest answer, and none of
    /// them has to refuse. A kind that meant "rich text" in the WYSIWYG sense
    /// would have been a document model, and two of the three hosts would have
    /// had to draw something they cannot.
    ///
    /// What the mark buys over [`Textarea`](Self::Textarea) is that a renderer
    /// may offer the affordances markdown has and plain text does not — a
    /// preview, a syntax pass, a monospaced face for the source — and that a
    /// host reading the value back knows what it is holding. A renderer with
    /// none of that draws a textarea, which is why this is additive rather than
    /// a second control.
    ///
    /// It says nothing about **when** the value is saved. Autosave is a clock,
    /// clocks are not described here, and the four MNW editors this was measured
    /// against each keep their own.
    ///
    /// Sanitising stays where it already is for markdown that is only displayed:
    /// with the renderer, at the point markup is produced. Being described is
    /// not a safety property, and a host with its own sanitiser and its own
    /// content-security posture still owns both.
    Rich,
    /// One of a fixed set, offered behind a control that shows one at a time.
    Select,
    /// One of a fixed set, with every option on screen at once.
    ///
    /// Not a presentation of [`Select`](Self::Select), which is the reading to
    /// resist: what differs is a property of the *question*. A choice that is
    /// consequential or irreversible has to be readable without opening
    /// anything, because a closed control shows one option and hides the rest,
    /// and the one it shows is whichever was current before the user had read
    /// the alternatives. audiofiles asks whether a library copies samples into
    /// its store or references them where they lie — which cannot be changed
    /// afterwards — and had already promoted that out of a checkbox by hand,
    /// with a comment giving this reason, before the description could say it.
    ///
    /// Everything here is an `<input type=...>`, a `<select>` or a
    /// `<textarea>`, and the way this enum grows is by a site being measured
    /// rather than by a list being completed. No member is ever "the last one".
    Radio,
    /// On or off.
    Checkbox,
    /// A file the user picks from wherever the host keeps files.
    ///
    /// It was filed as a router finding — a control whose destination is a
    /// host capability rather than an address — and splitting it is what made
    /// it two answers instead of one member satisfying neither. *Opening* a
    /// file is a one-way handoff and needs no new API. *Picking* one returns a
    /// value into a write, which is a form concern, which is this.
    ///
    /// The membership test passes on every host and not by a stretch: a Tauri
    /// app opens a native picker, a server renders `<input type="file">`, a
    /// terminal prompts for a path, a CLI takes an argument. That is closer to
    /// [`Email`](Self::Email), which exists because it changes the keyboard,
    /// than to anything bespoke.
    ///
    /// # The four things an upload says, and where each of them lives
    ///
    /// | axis | where |
    /// |---|---|
    /// | what it accepts | [`Field::accept`] |
    /// | one file or several | [`Field::multiple`] |
    /// | where the bytes go | the router's action, not here |
    /// | how far along it is | [`Awaiting`] on that action |
    ///
    /// Only the first two are this crate's, and that split is the answer to
    /// "describe an upload in full" rather than a gap in it. A destination is an
    /// address and this crate holds no addresses; progress is a live number and
    /// a description is built once, so the number is the renderer's to observe
    /// against the size [`Awaiting::amount`] carried before the transfer began.
    ///
    /// # How the file is handed over is the host's
    ///
    /// A drop area, a button opening a native picker, a path typed at a prompt:
    /// all three are the same field, and every measured site has the first. It
    /// is not described for the reason no gesture is — this crate owns no
    /// coordinates and no pointer, and a terminal that cannot be dropped on
    /// would be refusing a description it can otherwise honour completely.
    ///
    /// [`Field::accept`] and [`Field::multiple`] are measured rather than
    /// deferred. A member designed against nothing is the rule to keep: count
    /// the sites before adding one.
    File,
    /// Which theme the app wears.
    ///
    /// The one member here that names a *subject* rather than a shape of
    /// answer, and it is worth saying why that is not the door it looks like.
    /// Every other kind is a question a screen might ask about anything; this
    /// one is a specific question every app in the family asks, once, on its
    /// settings screen, and three of them wrote the same control by hand.
    ///
    /// # It is furniture, and the measurement is what says so
    ///
    /// The reading to resist is that this is [`Select`](Self::Select) with a
    /// grouped option list. Max rejected that: `optgroup` appears at one live
    /// site in the tree and the non-theme grouping count is zero, so the thing
    /// that recurs is this picker rather than option lists that group.
    ///
    /// # What it carries that a select cannot
    ///
    /// [`Field::themes`] rather than [`Field::options`], because a theme is
    /// four facts and an option is two. The two extra facts are the ones no
    /// app can supply without redoing work the theme layer has already done:
    /// which [`ThemeVariant`] group a theme is in, and how legible its muted
    /// text measured. `Choice::new(id, format!("{name} ({variant})"))` is what
    /// the three apps had, and it flattens the group into prose and loses the
    /// tier entirely.
    ///
    /// [`Field::follows`] carries the entry that is not a theme.
    ///
    /// # The cost, stated rather than discovered later
    ///
    /// This puts one screen's shape into a vocabulary that otherwise holds
    /// none, which was the objection raised against it and accepted going in.
    /// The mitigation is narrowness: this describes a theme picker, not a
    /// general "list the host resolved" mechanism. A second host-resolved list
    /// is when that generalisation gets measured, and not before.
    ///
    /// A renderer that has not heard of it draws a select over
    /// [`Field::themes`]' names and loses the grouping, which is the state
    /// every app was in before this member. Degrading to the status quo ante
    /// is the floor the member is designed against.
    Theme,
    /// Carried through the form and never shown.
    Hidden,
}

/// The wire format a [`FieldKind::Date`] value takes: ISO 8601, `YYYY-MM-DD`.
///
/// A constant rather than a sentence in a doc comment, because the reason to
/// name the format at all is that a host picking its own would fail silently
/// against a server parsing another. A host that cannot emit the native control
/// still has one spelling to meet, and can say which one it meant.
pub const DATE_FORMAT: &str = "%Y-%m-%d";

/// The wire format a [`FieldKind::DateTime`] value takes: `YYYY-MM-DDTHH:MM`,
/// local, carrying no zone and no seconds.
///
/// [`DATE_FORMAT`]'s sibling and there for its reason. The absent zone is a
/// property of the value rather than an omission: the moment is not fixed until
/// something outside the description supplies one.
pub const DATETIME_FORMAT: &str = "%Y-%m-%dT%H:%M";

impl FieldKind {
    /// Whether the value the kind takes is a moment rather than a string.
    ///
    /// Named once here for the reason [`offers_options`](Self::offers_options)
    /// is: two kinds answer yes, and a host that has to parse or format a value
    /// needs to ask without spelling the pair out at each renderer. A third
    /// temporal kind should land here and nowhere else.
    ///
    /// The format each one takes is [`DATE_FORMAT`] and [`DATETIME_FORMAT`].
    #[must_use]
    pub const fn temporal(self) -> bool {
        matches!(self, Self::Date | Self::DateTime)
    }

    /// Whether the field is drawn at all.
    #[must_use]
    pub const fn visible(self) -> bool {
        !matches!(self, Self::Hidden)
    }

    /// Whether the value must be kept out of logs and diagnostics.
    #[must_use]
    pub const fn confidential(self) -> bool {
        matches!(self, Self::Secret)
    }

    /// Where the field's own label sits.
    ///
    /// A checkbox labels itself on the right of the box; everything else takes
    /// a label above. Both webview apps already do this and both special-case
    /// it inline, which is the tell that it belongs in the description.
    ///
    /// A [`Radio`](Self::Radio) is not one of them, and the near-miss is worth
    /// naming: its *options* each label themselves, but the field still asks a
    /// question above them, so the group takes a label like everything else.
    #[must_use]
    pub const fn labels_itself(self) -> bool {
        matches!(self, Self::Checkbox)
    }

    /// Whether the kind reads [`Field::options`].
    ///
    /// Two kinds do, so the pair is named once here rather than spelled out at
    /// each renderer and again in [`Field::options`]' own doc, where "every
    /// kind but `Select`" was true for exactly one release. A third
    /// option-taking kind should land here and nowhere else.
    #[must_use]
    pub const fn offers_options(self) -> bool {
        matches!(self, Self::Select | Self::Radio)
    }

    /// Whether the kind reads [`Field::themes`] and [`Field::follows`].
    ///
    /// One member answers yes, and it gets a name for
    /// [`takes_files`](Self::takes_files)'s reason rather than in spite of
    /// being alone: four renderers ask it before they read either member, and
    /// a `matches!` per renderer is where the next one goes missing.
    ///
    /// Deliberately not folded into
    /// [`offers_options`](Self::offers_options). A theme picker offers no
    /// [`Choice`]es at all, so a renderer walking `options` for it walks an
    /// empty slice and draws an empty control.
    #[must_use]
    pub const fn offers_themes(self) -> bool {
        matches!(self, Self::Theme)
    }

    /// Whether the value runs to more than one line.
    ///
    /// Named once here for [`temporal`](Self::temporal)'s reason: two kinds
    /// answer yes, every renderer has to ask it before it can size anything,
    /// and a `matches!` per renderer is the pair drifting apart one member at a
    /// time. What a host does with the markdown, if anything, it reads from the
    /// kind itself; this is only whether one line is enough.
    #[must_use]
    pub const fn multiline(self) -> bool {
        matches!(self, Self::Textarea | Self::Rich)
    }

    /// Whether the value is a file the host picks rather than a string typed
    /// into a box.
    ///
    /// One member answers yes, which is [`visible`](Self::visible)'s and
    /// [`confidential`](Self::confidential)'s footing rather than a departure
    /// from it: the question gets a name because three renderers ask it before
    /// they can read [`Field::accept`] or [`Field::multiple`], and a `matches!`
    /// per renderer is where a second file-taking kind would go missing.
    #[must_use]
    pub const fn takes_files(self) -> bool {
        matches!(self, Self::File)
    }

    /// Whether the value is a quantity, so [`Field::unit`] means something.
    ///
    /// The numeric kinds and nothing else. A date is a quantity in the sense
    /// that it is ordered, and it is not one in the sense that matters here:
    /// its unit is fixed by the kind, so `Date` carrying `days` would be the
    /// description restating what [`kind`](Field::kind) already said.
    ///
    /// [`takes_files`](Self::takes_files)'s footing, and for its reason: the
    /// renderers ask this before they decide where a unit goes, and a
    /// `matches!` per renderer is where the next measurable kind goes missing.
    ///
    /// [`Interval`](Self::Interval) is measurable too: an axis is measured in
    /// something and both its ends are in it.
    #[must_use]
    pub const fn measurable(self) -> bool {
        matches!(self, Self::Number | Self::Range | Self::Interval)
    }
}

/// A family of media a file can belong to.
///
/// Three members, because three is what a media type's own first segment offers
/// that a renderer can do anything with. `text` and `application` are families
/// too and neither buys a disclosure — there is no preview of an
/// `application/octet-stream` — so naming them would be a member added for a
/// case nobody has.
///
/// It is the answer to "which disclosure", not a validation rule.
/// [`Field::accept`] is what a host filters on.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Family {
    /// A still picture.
    Image,
    /// Sound.
    Audio,
    /// Moving pictures, with or without sound.
    Video,
}

impl Family {
    /// The wildcard media type that means the whole family.
    ///
    /// `image/*` and its two siblings, which is what the measured sites write
    /// and what a webview puts in an `accept` attribute. Named here so the three
    /// renderers do not each spell the star.
    #[must_use]
    pub const fn wildcard(self) -> &'static str {
        match self {
            Self::Image => "image/*",
            Self::Audio => "audio/*",
            Self::Video => "video/*",
        }
    }

    /// The family a media type's first segment names, if it is one of these.
    ///
    /// Case-insensitive on the segment, because a media type is
    /// case-insensitive and half the tree writes them lowercase by habit rather
    /// than by rule.
    #[must_use]
    pub fn of_type(media_type: &str) -> Option<Self> {
        let (top, _) = media_type.split_once('/')?;
        if top.eq_ignore_ascii_case("image") {
            Some(Self::Image)
        } else if top.eq_ignore_ascii_case("audio") {
            Some(Self::Audio)
        } else if top.eq_ignore_ascii_case("video") {
            Some(Self::Video)
        } else {
            None
        }
    }
}

/// One entry in a file field's accept list.
///
/// Three shapes rather than a string, and all three are in the measured sites:
/// the MNW server writes `image/*`, `image/jpeg,image/png,image/webp`,
/// `.zip,.dmg,.exe,.appimage,.deb,.tar.gz,.clap,.vst3` and, in one place,
/// `.csv,text/csv`. A single string would carry all of them and answer nothing
/// about any of them.
///
/// # Why the list is not just a filter
///
/// It is read twice. Once to decide what the picker offers, which any of the
/// three shapes serves, and once to decide **which disclosure** the field gets:
/// a preview for a picture, a duration or a waveform for a sound. There is one
/// upload shape and a media upload is that shape with more of it shown, so the
/// accept list is what says which more. [`family`](Self::family) is that
/// question answered once here instead of a media-type parser in each renderer.
///
/// # A suffix names no family, on purpose
///
/// `.mp3` is audio in fact, and nothing here says so. A suffix-to-family table
/// in a published crate is a mapping that goes stale, disagrees with the host's
/// own idea of what a file is, and is wrong the first time somebody hands it a
/// container. A call site that wants a picture's preview writes
/// [`Family::Image`] or `image/jpeg`; a call site listing installer suffixes
/// wants no disclosure anyway, which is the measured case.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Accepted<'a> {
    /// Every file of a family: `image/*` and its siblings.
    Family(Family),
    /// One media type, written the way a media type is written:
    /// `image/jpeg`, `text/csv`.
    Type(&'a str),
    /// One file-name suffix, written with its leading dot: `.zip`, `.tar.gz`.
    ///
    /// A suffix and not an extension, because `.tar.gz` is a measured site and
    /// is two dots.
    Suffix(&'a str),
}

impl<'a> Accepted<'a> {
    /// The family this entry belongs to, when it names one.
    ///
    /// [`None`] for a [`Suffix`](Self::Suffix) and for any media type outside
    /// the three families, which is the honest answer rather than a missing
    /// one: the description did not say.
    #[must_use]
    pub fn family(self) -> Option<Family> {
        match self {
            Self::Family(family) => Some(family),
            Self::Type(media_type) => Family::of_type(media_type),
            Self::Suffix(_) => None,
        }
    }

    /// How a host that wants one string writes this entry.
    ///
    /// A webview's `accept` attribute takes exactly these spellings, and a
    /// terminal listing what it will take reads the same words.
    #[must_use]
    pub const fn as_str(self) -> &'a str {
        match self {
            Self::Family(family) => family.wildcard(),
            Self::Type(text) | Self::Suffix(text) => text,
        }
    }
}

/// One option offered by a field [`FieldKind::offers_options`] accepts.
///
/// Two strings, because the submitted value and the read label are different
/// facts and every renderer that has tried to collapse them has had to
/// un-collapse them later. `makeover-webview` invented this shape writing its
/// form emitter and it is taken here unchanged; moving it down rather than
/// re-deriving it is the point, since the second and third renderers were each
/// going to arrive at a near-miss of it.
/// `#[non_exhaustive]`, which every type here that a renderer matches or builds
/// carries. Without it a new member is a breaking change at every literal site
/// in the tree.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct Choice<'a> {
    /// What is submitted.
    pub value: &'a str,
    /// What is read.
    pub label: &'a str,
    /// Why it cannot be picked right now, when it cannot.
    ///
    /// One member rather than an `available: bool` beside a reason, and the
    /// conflation is the point: an option greyed out with no explanation is a
    /// dead end the user cannot act on, and it is exactly the state the app
    /// that found this gap had to patch by hand with a line of prose under the
    /// control. Making the reason mandatory means the description cannot say
    /// the useless half.
    ///
    /// The option stays in the list. Dropping it is what an app does today, and
    /// it costs the user the knowledge that the thing exists at all —
    /// audiofiles' multi-sample mode appears on its own once a second sample is
    /// dropped, so a user who never sees it never learns what to drop.
    ///
    /// **Not [`Field::error`], and not [`Field::hint`].** An error is about the
    /// answer and a hint is standing help for the whole question; this is about
    /// one option among several, which is the level neither of those reaches.
    ///
    /// **Not disabled-the-state.** `State::Disabled` is about a whole field
    /// refusing to answer. This says the field is live and one of its answers
    /// is not available yet, which is a different sentence and the reason the
    /// tone rule matters here: the *other* options are still usable.
    pub unavailable: Option<&'a str>,
    /// The line under the label that says what picking this means.
    ///
    /// A choice between three plans is a choice nobody can make from three
    /// names, and until this existed the description had nowhere to put the
    /// sentence that made it makeable. What the corpus did instead is the
    /// tell: four of the six measured sites fold it into the label —
    /// `<strong>Public</strong>: Anyone can see this repository` in MNW's git
    /// settings, the same shape in its project-basics AI tier and its cart's
    /// currency conversion, and `Mislabeled (wrong AI tier or category)` in
    /// its report modal. The described screens do it too, in miniature: `Every
    /// 15 minutes (recommended)`, `Reference samples in place (loose-files
    /// mode)`. One fact, six spellings, no member.
    ///
    /// # Where it goes is the host's, and the rule already exists
    ///
    /// This is [`unavailable`](Self::unavailable)'s question met a third time
    /// and it takes the same answer, which is the strongest evidence one member
    /// is right rather than two. A radio group has room and gives the line its
    /// own element beside the label. A `<select>`'s option takes no elements,
    /// no second line and no title a keyboard reaches, so the line runs into
    /// the option's own text — exactly as a precondition does, and as a theme's
    /// contrast badge does in brackets. A terminal has rows and puts it on one
    /// under the option.
    ///
    /// # Not a price, and that is a measurement rather than a preference
    ///
    /// The site that asked for this is MNW's fee calculator, whose tier cards
    /// carry a name, a price *and* a description, so a second member for the
    /// price was on the table. It loses on the count: the tree's other three
    /// priced tier lists — `project.html`, `project_paywall.html`,
    /// `index.html` — are not option lists at all. Each card carries its own
    /// submit, which makes it a region with a heading, a fact and an act, and
    /// it is sayable already. So a price member would have exactly one
    /// consumer, and it would mean this crate growing a money type it does not
    /// have: [`Unit`] is a time axis, and every amount in the described tree is
    /// text.
    ///
    /// The price therefore leads the line: `$24/mo. 2GB/file, 100GB total.
    /// Fits audio, plugins, binaries.` What would reopen it is a **second**
    /// priced option list, not a judgement about how that reads.
    ///
    /// # What it is not
    ///
    /// Not [`unavailable`](Self::unavailable), which says the option cannot be
    /// picked. This says what it means to pick it, and the two are drawn
    /// together on an option that carries both: the description that says a
    /// tier is out of stock *and* what the tier is has said two things.
    ///
    /// Not [`Field::hint`], which is standing help for the whole question, and
    /// not markup. One line of plain text, for [`Candidate::detail`]'s reason:
    /// an option list is a place a renderer lays out, and a description that
    /// put a block in one would be handing every host a layout problem for the
    /// benefit of one.
    pub detail: Option<&'a str>,
}

impl<'a> Choice<'a> {
    /// An option whose submitted value is also its label.
    #[must_use]
    pub const fn plain(value: &'a str) -> Self {
        Self::new(value, value)
    }

    /// An option that submits one string and reads as another.
    ///
    /// A constructor rather than a literal, which is what `#[non_exhaustive]`
    /// costs and buys: outside this crate the struct cannot be built by naming
    /// its members, so every call site goes through here and the next member
    /// added breaks none of them.
    #[must_use]
    pub const fn new(value: &'a str, label: &'a str) -> Self {
        Self {
            value,
            label,
            unavailable: None,
            detail: None,
        }
    }

    /// The same option, not pickable yet, and why.
    ///
    /// Builder-shaped because the reason is the rare case: 39 of the 40 option
    /// sites measured across the tree do not have one.
    #[must_use]
    pub const fn unless(mut self, reason: &'a str) -> Self {
        self.unavailable = Some(reason);
        self
    }

    /// The same option, with the line that says what picking it means.
    ///
    /// Builder-shaped for [`unless`](Self::unless)'s reason, and it is the
    /// commoner of the two: six measured sites want this and one wants a
    /// precondition. See [`detail`](Self::detail).
    #[must_use]
    pub const fn detailing(mut self, detail: &'a str) -> Self {
        self.detail = Some(detail);
        self
    }

    /// Whether the option can be picked right now.
    ///
    /// The predicate a renderer branches on, so that "unavailable" is read as
    /// one condition in one place rather than as `unavailable.is_some()` at
    /// three renderers, one of which will invert it.
    #[must_use]
    pub const fn available(&self) -> bool {
        self.unavailable.is_none()
    }
}

/// One entry in a field's suggestion list.
///
/// A suggestion-only type rather than a fourth member on [`Choice`], ruled by
/// Max. The two are near-identical and that is the accepted drift risk, so the
/// mitigation is written here: **an
/// option and a candidate are submitted the same way and read differently.**
/// An option is a thing you pick from a known set, and the set is the whole of
/// what there is. A candidate is a thing you are being *oriented* toward out of
/// a set nobody can see, which is why it carries [`detail`](Self::detail) and
/// an option does not.
///
/// This reverses a position quasi-router stated in its own doc, that a
/// candidate is [`Choice`] "because a candidate is submitted under one string
/// and read under another, which is what an option is". True and not
/// sufficient: how a thing is submitted was never the half that differed.
///
/// # Why the second string is not folded into the label
///
/// Because every renderer wants it separately, and the two measured sites both
/// draw it by hand today. The MNW server's tag box computes its context as the
/// parent path -- "the parent path orients an otherwise ambiguous leaf:
/// 'Format' appears under audio, software, writing, and video" -- and a list of
/// four identical rows reading "Format" is not a usable list. In a webview the
/// second string is styled differently, in a terminal it wants the remaining
/// columns rather than a dash, and in neither is it part of what the typed
/// value matches against. `Choice::new(slug, format!("{label} - {context}"))`
/// loses all three of those facts, which is the condition this type exists to
/// end.
///
/// # No `unavailable`
///
/// [`Choice::unavailable`] has no counterpart here, and the omission is the
/// implementer's call recorded rather than an oversight. A suggestion that
/// cannot be picked is arguably not a suggestion: an option list is a fixed set
/// a user is owed an explanation about, and a candidate list is whatever a
/// route decided to offer, so a route with nothing to say simply does not offer
/// the row. Add it if a measured site ever wants it.
///
/// # What it does not carry, and where that lives
///
/// What *happens* when a candidate is picked. Picking is local by default -- it
/// writes [`value`](Self::value) into the field that owns the list -- and a
/// candidate that does something else says so with an action. An action is not
/// a word this crate has, exactly as [`Field`] here has no `suggests` member,
/// so both live on the router's owned mirror of this type.
///
/// `#[non_exhaustive]` from birth. Non-negotiable: adding it later means a
/// breaking change at every literal site in the tree.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct Candidate<'a> {
    /// What is submitted, and what picking writes into the field.
    pub value: &'a str,
    /// What is read.
    pub label: &'a str,
    /// The second line: what orients this candidate among rows that read alike.
    ///
    /// Optional because a candidate list whose labels are already distinct
    /// wants nothing here, and a renderer given [`None`] draws one line rather
    /// than an empty second one.
    pub detail: Option<&'a str>,
}

impl<'a> Candidate<'a> {
    /// A candidate whose submitted value is also its label.
    #[must_use]
    pub const fn plain(value: &'a str) -> Self {
        Self::new(value, value)
    }

    /// A candidate that submits one string and reads as another.
    ///
    /// A constructor rather than a literal, which is what `#[non_exhaustive]`
    /// costs and buys: outside this crate the struct cannot be built by naming
    /// its members, so every call site goes through here and the next member
    /// added breaks none of them.
    #[must_use]
    pub const fn new(value: &'a str, label: &'a str) -> Self {
        Self {
            value,
            label,
            detail: None,
        }
    }

    /// The same candidate, with the line that tells it from its neighbours.
    #[must_use]
    pub const fn detailed(mut self, detail: &'a str) -> Self {
        self.detail = Some(detail);
        self
    }
}

/// Which ambient mode a theme is written for.
///
/// The vocabulary's own spelling of what `makeover` calls a theme's variant,
/// and the duplication is deliberate rather than an oversight. This crate has
/// no dependencies by charter — it emits nothing, reads nothing and resolves
/// nothing — so it cannot take the crate that owns the file format, and a
/// renderer that must group a picker needs the three groups as values.
///
/// The two are kept in step by the app that converts between them, which is a
/// three-arm `match` at each adopter and the price of the layering. If a fourth
/// mode is ever authored, this enum and `makeover::Variant` move together.
///
/// Three, not two: one shipped theme is high contrast, and an app matching on
/// light-or-dark alone files it under the wrong one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[non_exhaustive]
pub enum ThemeVariant {
    /// Written for a light ambient mode.
    Light,
    /// Written for a dark ambient mode.
    Dark,
    /// Written to be legible before it is pretty.
    HighContrast,
}

impl ThemeVariant {
    /// The machine spelling, matching the theme file's own `meta.variant`.
    ///
    /// A data attribute, a stored value, a test assertion. Not a heading: what
    /// a group is *called* on screen is [`heading`](Self::heading).
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            ThemeVariant::Light => "light",
            ThemeVariant::Dark => "dark",
            ThemeVariant::HighContrast => "high-contrast",
        }
    }

    /// What the group of themes in this variant is called on screen.
    ///
    /// Here rather than at each renderer, which is the whole argument for the
    /// member existing: three renderers picking their own headings is one
    /// picker reading three ways, and the spellings below are the ones
    /// goingson's shipped picker used before it was described.
    #[must_use]
    pub const fn heading(self) -> &'static str {
        match self {
            ThemeVariant::Light => "Light",
            ThemeVariant::Dark => "Dark",
            ThemeVariant::HighContrast => "High Contrast",
        }
    }
}

impl std::fmt::Display for ThemeVariant {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// How legible a theme measured, as a picker reports it.
///
/// A measurement carried into the description, which is unusual here and is the
/// one case that earns it: the number comes off the theme's resolved colours,
/// so the layer that loaded the theme is the only party that has it, and an app
/// re-deriving it would be parsing every theme file a second time to learn what
/// was already known. What a renderer does with it is a badge beside the name.
///
/// Ordered worst-first, matching `makeover::ContrastTier`, so the two sort the
/// same way and an adopter's `match` cannot invert an ordering by accident.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
#[non_exhaustive]
pub enum Contrast {
    /// Muted text below the 3:1 floor for large text and UI parts.
    Low,
    /// Muted text clears 3:1 but not the 4.5:1 bar for normal text.
    Standard,
    /// Muted text meets WCAG AA on every panel ground.
    High,
}

impl Contrast {
    /// The machine spelling, for a data attribute or a test.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Contrast::Low => "low",
            Contrast::Standard => "standard",
            Contrast::High => "high",
        }
    }

    /// The short mark shown beside a theme's name.
    ///
    /// One spelling for the tree, for [`ThemeVariant::heading`]'s reason. These
    /// are the marks audiofiles shipped before its picker was described, which
    /// is the only implementation that ever drew them.
    ///
    /// [`Standard`](Self::Standard) is not the absence of a mark: a reader
    /// scanning a column of badges learns more from three marks than from two
    /// and a gap, and "OK" is the honest reading of a theme that clears the UI
    /// floor and misses the text one.
    #[must_use]
    pub const fn badge(self) -> &'static str {
        match self {
            Contrast::Low => "low",
            Contrast::Standard => "OK",
            Contrast::High => "AA",
        }
    }
}

impl std::fmt::Display for Contrast {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// One theme, as a picker offers it.
///
/// Four facts where a [`Choice`] has two, and the two extra ones are why this
/// is its own type rather than options with the variant folded into the label.
/// Both are facts the theme layer resolved and neither survives being written
/// into a string: a group is structure and a badge is a second column.
///
/// # No `unavailable`
///
/// [`Choice::unavailable`]'s counterpart is absent for its own sibling's
/// reason. A theme that is installed can be picked, and a theme that is not
/// installed is not in the list. There is no third state for a reason to
/// explain.
///
/// `#[non_exhaustive]` from birth, so a new member costs no call site.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct ThemeChoice<'a> {
    /// What is submitted, and what the app stores.
    pub id: &'a str,
    /// What is read.
    pub name: &'a str,
    /// Which group it belongs to.
    pub variant: ThemeVariant,
    /// How legible its muted text measured.
    pub contrast: Contrast,
}

impl<'a> ThemeChoice<'a> {
    /// A theme, with everything a picker needs to place and mark it.
    ///
    /// Every fact is an argument and none is a builder, which is the opposite
    /// of [`Choice`]'s arrangement and is deliberate: a theme missing its
    /// variant has no group to sit in and a theme missing its tier has no badge
    /// to draw, so both are the control rather than embellishments on it. The
    /// same reasoning [`Field::range`] applies to its bounds.
    #[must_use]
    pub const fn new(
        id: &'a str,
        name: &'a str,
        variant: ThemeVariant,
        contrast: Contrast,
    ) -> Self {
        Self {
            id,
            name,
            variant,
            contrast,
        }
    }
}

/// One field of a form.
///
/// Borrowed rather than owned: a description is built, read once by a renderer,
/// and dropped. Nothing here outlives the screen it describes.
///
/// # What it carries, and what it does not
///
/// Stated here so the next renderer does not re-ask, which is what the first
/// two both did. It carries everything a renderer needs to *draw* the field:
/// its kind, what it is called, what it is asked for, its standing help, what
/// is wrong with it now, whether it is compulsory, whether it hides behind a
/// disclosure, its ghost text, and the options it offers.
///
/// It does not carry the **current value**, and it is not going to. That is the
/// one thing here that is genuinely renderer state: a webview reads it back out
/// of the DOM, an immediate-mode renderer holds a `&mut` to the app's own field
/// and writes through it, and a terminal keeps an edit buffer. A description
/// that carried the value would have to carry a way to write it back, at which
/// point it is a form model and no longer a description.
///
/// **Constraints** are here and enforcement is not, which is one line rather
/// than two. [`required`], [`max_length`], [`min`] and [`max`] are facts about
/// the *question*, so a renderer can emit its host's idiom for each — an HTML
/// attribute, a marked label, a clamped spinner — and the platform helps the
/// user before anything is submitted. Deciding that a value is wrong stays with
/// whoever validated, and [`error`] is that decision arriving back.
///
/// The set stops before `pattern`, and stops there on both tests at once. A
/// regex has an honest answer in a webview and none anywhere else: egui would
/// have to run it per keystroke and decide what a half-typed value means,
/// which is enforcement wearing description's clothes. And it is one site in
/// goingson and none in Balanced Breakfast, against 8 and 1 for `maxlength`.
///
/// [`error`]: Field::error
/// [`required`]: Field::required
/// [`max_length`]: Field::max_length
/// [`min`]: Field::min
/// [`max`]: Field::max
/// How a slider's position becomes its value, and how finely it moves.
///
/// **The data of a slider is a fraction and a function taking numbers to
/// numbers.** Stated by Max, and it is what [`min`](Field::min) and
/// [`max`](Field::max) are not: they were never the control's extent.
/// A slider's extent is always 0 to 1 — a thumb at 40% of a track — and the
/// bounds are `f(0)` and `f(1)`. Linear is the constant-slope case, which is
/// exactly why nobody noticed the function was there: when `f` is
/// `min + t * (max - min)` the extent and the bounds coincide numerically and
/// the mapping is invisible.
///
/// So this is not a scale flag bolted onto a range. Every range described
/// before it had a mapping, and four renderers each hard-coded the same one.
///
/// # Why a closed family and not a function
///
/// `fn(f64) -> f64` is the literal reading and it does not survive the
/// description boundary. A fn pointer cannot be emitted into a browser, and it
/// cannot be compared or hashed in a way that means anything, which this struct
/// needs. A named family is the same semantics with arbitrary closures given
/// up, and nothing measured wants one: the tree has a single non-linear shape
/// across five controls and no second shape at all.
///
/// # Why the step is here
///
/// Max, in the same breath: if the family is prescriptive anyway, the step
/// spacing belongs in it. On a slider the granularity and the mapping are one
/// decision — a curve chosen without saying how finely it moves is half an
/// answer — and holding them apart is what let a 0-to-1 threshold ship as a
/// two-position control, since the host default of 1 was applied to a mapping
/// nobody had named. It also un-overloads [`Field::step`], which stays as it
/// was for a *typed* value, where there is no mapping and the granularity is a
/// plain fact about the number.
///
/// A future curve carrying a fact of its own — an exponent, an inflection —
/// puts it in its own variant rather than on the struct, which is the second
/// reason this shape is right.
///
/// **The step is in the value's own units under every curve.** What a curve
/// changes is the mapping, not the units the granularity is measured in: a step
/// of `0.001` on an envelope time is three decimals whether the track is
/// logarithmic or not, and a renderer that reads the step for display precision
/// keeps reading it the same way.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Curve<'a> {
    /// Constant slope: `f(t) = min + t * (max - min)`.
    ///
    /// What every described range meant before this enum existed, and the
    /// default, so a site that says nothing is correct unchanged.
    Linear {
        /// The granularity, in the value's own units. `None` is the host's own.
        step: Option<&'a str>,
    },
    /// Constant ratio: `f(t) = min * (max / min).powf(t)`.
    ///
    /// The mapping for a question whose extent spans orders of magnitude and
    /// whose interesting half is the small end. audiofiles' envelope times run
    /// 0.001 to 5 seconds, where a 5 ms attack and a 50 ms attack are audibly
    /// different instruments and a linear track puts both inside its first one
    /// percent.
    ///
    /// # It needs positive bounds
    ///
    /// A constant ratio is undefined across zero, so this asks for `min > 0`.
    /// A range that does not have that is mapped [`Linear`](Self::Linear)ly
    /// instead — see [`value_at`](Self::value_at). Stated rather than enforced,
    /// the way every other constraint in this crate is, and it is not a
    /// hypothetical: an envelope's sustain is a 0-to-1 level and is linear for
    /// this reason rather than by oversight.
    Logarithmic {
        /// The granularity, in the value's own units. `None` is the host's own.
        step: Option<&'a str>,
    },
}

impl Default for Curve<'_> {
    fn default() -> Self {
        Self::Linear { step: None }
    }
}

impl<'a> Curve<'a> {
    /// The granularity this curve moves in, whichever curve it is.
    ///
    /// Every variant carries one, so reading it does not need a match at each
    /// of the four renderers.
    #[must_use]
    pub const fn step(self) -> Option<&'a str> {
        // No wildcard: `#[non_exhaustive]` binds downstream, not here, so a
        // curve added later has to answer this rather than fall through to a
        // granularity nobody chose.
        match self {
            Self::Linear { step } | Self::Logarithmic { step } => step,
        }
    }

    /// Whether this curve maps as a constant ratio *given these bounds*.
    ///
    /// The bounds are the argument because [`Logarithmic`](Self::Logarithmic)
    /// is a request rather than a guarantee: it needs `0 < min < max`, and a
    /// range that does not have that is drawn linearly. A renderer asks this
    /// instead of matching on the variant, so the fallback is decided in one
    /// place rather than four.
    #[must_use]
    pub fn is_ratio(self, min: f64, max: f64) -> bool {
        matches!(self, Self::Logarithmic { .. }) && min > 0.0 && max > min
    }

    /// The value at a position along the track, where `position` is 0 to 1.
    ///
    /// `f`. The whole point of the type, and it lives here rather than in each
    /// renderer so that a terminal's bar, an egui slider and a browser's input
    /// cannot disagree about where a value sits.
    ///
    /// A position outside 0 to 1 is clamped, and bounds that are equal or
    /// inverted give `min` back: a track with no extent has one value on it.
    #[must_use]
    pub fn value_at(self, position: f64, min: f64, max: f64) -> f64 {
        let position = position.clamp(0.0, 1.0);
        // NaN named rather than fallen through: `max <= min` is false for a NaN
        // bound, so without it a track with no numbers on it would be mapped as
        // if it had two.
        if max <= min || min.is_nan() || max.is_nan() {
            return min;
        }
        if self.is_ratio(min, max) {
            min * (max / min).powf(position)
        } else {
            position.mul_add(max - min, min)
        }
    }

    /// The position a value sits at, where the answer is 0 to 1.
    ///
    /// `f` inverted, which is what a renderer needs to *draw* a value it was
    /// handed. Same clamping and the same degenerate answer as
    /// [`value_at`](Self::value_at).
    #[must_use]
    pub fn position_of(self, value: f64, min: f64, max: f64) -> f64 {
        if max <= min || min.is_nan() || max.is_nan() {
            return 0.0;
        }
        let value = value.clamp(min, max);
        let position = if self.is_ratio(min, max) {
            (value / min).ln() / (max / min).ln()
        } else {
            (value - min) / (max - min)
        };
        position.clamp(0.0, 1.0)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Field<'a> {
    /// What kind of value it takes.
    pub kind: FieldKind,
    /// The name the value is submitted under.
    ///
    /// The *lower* end's name for a [`FieldKind::Interval`], whose upper end is
    /// [`upper_name`](Self::upper_name). Every other kind submits one value and
    /// this is the whole of it.
    pub name: &'a str,
    /// The name a [`FieldKind::Interval`]'s upper end is submitted under.
    ///
    /// [`None`] for every other kind, and sayable-and-ignored there the way
    /// [`options`](Self::options) is on a kind that offers none.
    ///
    /// Stated rather than derived from [`name`](Self::name), and
    /// [`FieldKind::Interval`] carries the measurement that decided it: the two
    /// sites in this tree disagree about affix order, so a derived rule would
    /// rename one of them. Which member a name sits in is also what says which
    /// end it is, so nothing separate carries the direction.
    ///
    /// An interval missing it is an interval with one end that can be submitted,
    /// which is a description a renderer may draw honestly and no better than
    /// that. [`Field::interval`] is what makes forgetting it unsayable, on the
    /// same footing as [`Field::range`] and its bounds.
    pub upper_name: Option<&'a str>,
    /// What the user is asked for.
    pub label: &'a str,
    /// Standing help, shown whether or not anything is wrong.
    pub hint: Option<&'a str>,
    /// What is currently wrong with the value.
    pub error: Option<&'a str>,
    /// A consequence of the answer the user has given, carrying its own tone.
    ///
    /// The third message channel, between [`hint`](Self::hint) and
    /// [`error`](Self::error) and overlapping neither. A hint is standing help
    /// that does not depend on the value; an error says the value is not
    /// acceptable. A note is the case in the middle: the value is perfectly
    /// acceptable and choosing it costs something the user should know about.
    ///
    /// The first consumer is audiofiles' export Format field, where choosing
    /// WAV or AIFF over Original re-encodes and silently drops embedded BWF,
    /// iXML, loop points, cue markers and ID3. That is not a validation
    /// failure and it is not standing help — it is true of one answer to one
    /// question — and it was hand-drawn in the app's own draw callback for
    /// want of anywhere to say it.
    ///
    /// The tone is carried rather than fixed at [`Tone::Warning`] because the
    /// channel is not only for warnings: the same slot says "this is the
    /// recommended one" ([`Tone::Success`]) and "this is what that setting
    /// implies" ([`Tone::Info`]). A renderer gets the announcement behaviour
    /// off the tone for free — makeover-webview emits `data-tone` and treats
    /// Warning and Danger as assertive for `aria-live`.
    ///
    /// It does **not** make the field invalid. [`invalid`](Self::invalid) stays
    /// `error.is_some()`, so a note never marks the group as a problem.
    ///
    /// # Precedence, for a renderer with room for one
    ///
    /// Error, then note, then hint. A renderer that shows every message shows
    /// them in that order too. makeover-tui is the one with room for exactly
    /// one line, and it is why the order is decided here rather than three
    /// times: what is wrong outranks what it costs, which outranks how it
    /// works.
    pub note: Option<(Tone, &'a str)>,
    /// Ghost text shown while the field is empty.
    ///
    /// User-facing text, and it sits with `label` and `hint` rather than with
    /// the value because it is a property of the *question* and not of the
    /// answer.
    ///
    /// Not a substitute for a label. A field labelled only by its placeholder
    /// loses its label the moment anything is typed, and no renderer here can
    /// make that not happen, so the description keeps both.
    pub placeholder: Option<&'a str>,
    /// The options offered, in the order they are offered.
    ///
    /// Empty for every kind [`FieldKind::offers_options`] rejects. A field
    /// described with no options is sayable on purpose: it is what an app with
    /// an unfinished-loading option list actually has, and a renderer showing
    /// an empty control says so on screen rather than in a log.
    ///
    /// Which option is *current* is not here. That is the value, and the value
    /// is renderer state.
    pub options: &'a [Choice<'a>],
    /// The themes offered, in the order they are offered.
    ///
    /// Empty for every kind [`FieldKind::offers_themes`] rejects, and sayable
    /// as empty for the one that accepts it: an app whose theme directories
    /// hold nothing has a picker offering only [`follows`](Self::follows),
    /// which is a true description of that machine.
    ///
    /// **The order is the grouping.** Entries arrive sorted by
    /// [`ThemeVariant`] and then by [`Contrast`] within each variant, so a
    /// renderer that draws headings walks the run of one variant and a renderer
    /// that cannot still gets the useful order. Handing back groups would force
    /// the second renderer to flatten what the first wanted.
    ///
    /// Nothing here sorts. The description carries the order it was given, and
    /// the sort belongs with whoever measured the tiers — `makeover::theme_options`
    /// is what produces it, and re-sorting here would be this crate deciding a
    /// question it cannot see the inputs to.
    ///
    /// Which theme is *current* is not here. That is the value, and the value
    /// is renderer state, exactly as it is for [`options`](Self::options).
    pub themes: &'a [ThemeChoice<'a>],
    /// The entry that follows the ambient mode instead of naming a theme.
    ///
    /// [`None`] for a picker that does not offer one, which is a real answer:
    /// an app whose host has no ambient mode to follow should not offer a row
    /// that does nothing.
    ///
    /// A [`Choice`] rather than a bare label, because the *value* is the app's.
    /// Every store in the family spells it `system` today and none of them is
    /// obliged to; a description that hardcoded the spelling would be this
    /// crate holding a fact about somebody else's config table.
    ///
    /// It is not a [`ThemeChoice`] with an absent variant. Following is a
    /// standing instruction that resolves differently as the desktop flips, and
    /// a theme id is an answer that does not — which is the distinction
    /// `makeover::ThemeSelection` exists to hold, carried here rather than
    /// blurred.
    pub follows: Option<Choice<'a>>,
    /// What a file field takes, in the order a host offering the list shows it.
    ///
    /// Empty for every kind [`FieldKind::takes_files`] rejects, and empty is
    /// also a real answer for one that accepts it: a field that takes any file
    /// says so by listing nothing, which is what an `<input type="file">` with
    /// no `accept` does and what most of the measured sites are.
    ///
    /// It is a filter and it is the disclosure cue, and [`Accepted`]'s doc
    /// carries which reading is which. Nothing here validates: a host may hand
    /// back a file the list does not cover, exactly as a browser does when the
    /// user switches the picker to "All Files", and deciding a value is wrong
    /// stays with whoever validated.
    pub accept: &'a [Accepted<'a>],
    /// Whether more than one file may be picked at once.
    ///
    /// Only [`FieldKind::takes_files`] reads it. A multi-valued answer to any
    /// other question is a different shape — a set of options, a repeated
    /// group — and neither is this flag with a different kind beside it.
    ///
    /// False is the common case: 4 of the MNW server's 16 file inputs carry it.
    pub multiple: bool,
    /// Whether the form refuses to submit without it.
    pub required: bool,
    /// The longest the value may be, in characters.
    pub max_length: Option<u32>,
    /// The lowest value accepted, as the host would write it.
    ///
    /// Text rather than a number, because the bound is only a number for some
    /// of the kinds that take one. goingson's own sites are `min="1"` on a
    /// duration and `min="2026-08-09T14:30"` on a datetime, and a numeric member
    /// could say the first and not the second. The [`kind`](Self::kind) already
    /// says how to read it, the same way it does for the value.
    pub min: Option<&'a str>,
    /// The highest value accepted, as the host would write it. See
    /// [`min`](Self::min).
    pub max: Option<&'a str>,
    /// The granularity the value moves in, as the host would write it.
    ///
    /// Text for [`min`](Self::min)'s reason, and it earns it twice over: the
    /// step of a date is a day and the step of a threshold is 0.01, and a
    /// numeric member could say one of them.
    ///
    /// Absent means the host's own granularity, which is the honest default
    /// rather than a missing value: a webview's `<input>` steps by 1 unless told
    /// otherwise, and that is the browser's rule and not this crate's to
    /// restate.
    ///
    /// # It is the granularity of a *typed* value
    ///
    /// [`FieldKind::Range`] reads its own from [`curve`](Self::curve) and
    /// ignores this. On a slider the granularity and the mapping are one
    /// decision, and on a typed number there is no mapping to decide with. See
    /// [`Curve`], "Why the step is here".
    pub step: Option<&'a str>,
    /// How a slider's position becomes its value, and how finely it moves.
    ///
    /// [`FieldKind::Range`]'s, and nothing else reads it: a typed number has a
    /// granularity but no mapping, and takes [`step`](Self::step) instead.
    ///
    /// Defaults to [`Curve::Linear`] with no step, which is what an
    /// undescribed range means.
    pub curve: Curve<'a>,
    /// What the number is measured in: `s`, `ms`, `dB`, `GiB`.
    ///
    /// A fact about the value, not part of the question's name, and that
    /// distinction is the whole reason it is a member. The two readings come
    /// apart the moment anything reads a field back rather than drawing it: a
    /// [`max`](Self::max) of `-96` and a bound of `-96 dBFS` are the same number
    /// and not the same answer, and under the convention this replaces the unit
    /// could only be recovered by parsing it back out of a label.
    ///
    /// # Where a renderer draws it
    ///
    /// Beside the value, wherever that host puts a value. Not in the label: a
    /// label is the sentence above the control, so unit-in-label reads the same
    /// on every host and is wrong on any host with somewhere better. egui puts
    /// it inside
    /// the slider where the readout already is, a terminal appends it to the
    /// value in the edit line, a webview sets it adjacent to the input.
    ///
    /// # Which kinds read it
    ///
    /// [`FieldKind::measurable`] answers, and it is
    /// [`takes_files`](FieldKind::takes_files)'s footing: three renderers ask
    /// before they can decide whether to draw this, and a `matches!` per
    /// renderer is where the next measurable kind goes missing. A unit on a kind
    /// that rejects it is sayable and ignored, the same way
    /// [`options`](Self::options) is on a kind that offers none.
    ///
    /// # Why a string
    ///
    /// The measured sites are `GiB`, `dBFS`, `s` and `ms`. An enum would have to
    /// grow a member for every unit any consumer ever wants, and this crate does
    /// not know them; it knows that a number has one.
    ///
    /// Written as the symbol alone, with no brackets and no leading space. The
    /// spacing is the renderer's, because a slider's readout and a sentence want
    /// different answers.
    pub unit: Option<&'a str>,
    /// Whether the field lives behind a "more options" disclosure.
    pub extended: bool,
    /// Whether this local wall-clock value is submitted as an absolute instant.
    ///
    /// [`FieldKind::DateTime`] asks for a time the way a person says one --
    /// "the 14th at half past two" -- and that names a different moment in
    /// Denver than it does in Berlin. A route that stores an instant needs the
    /// moment, so somebody has to convert. This member says the description
    /// wants that conversion; it does not say how.
    ///
    /// # The conversion belongs to the renderer
    ///
    /// Because the renderer is the only party that knows what "your computer's
    /// time zone" means for its host. A browser has one and the user is sitting
    /// in it; a TUI reads the host clock; an egui app reads the same clock a
    /// different way. Nothing above the renderer can answer it, and the
    /// alternatives all try: a hidden IANA-zone field needs a host capability
    /// for reading the zone that three hosts answer differently, plus a kind
    /// that does not exist, plus a wire-contract change; a timezone on the
    /// user's profile is a product decision wearing a bug's clothes. Say it
    /// here, and the next reader does not propose them again.
    ///
    /// # What a renderer does
    ///
    /// Draws the same control it always did -- the flag changes what is
    /// *submitted*, not what is shown -- and converts the local value to an
    /// absolute instant on the way out. A renderer that cannot convert submits
    /// the local value unchanged, which is what every renderer did before this
    /// existed.
    ///
    /// No wire contract moves when a site adopts it: the route was already
    /// receiving an instant. What changes is who computed it.
    ///
    /// # Which kinds read it
    ///
    /// [`FieldKind::DateTime`]'s. `Date` and `Time` are each half a moment and
    /// cannot name one on their own, so the flag is sayable and ignored there,
    /// the way [`options`](Self::options) is on a kind that offers none.
    pub as_instant: bool,
}

impl<'a> Field<'a> {
    /// A plain required-nothing field of the given kind.
    #[must_use]
    pub const fn new(kind: FieldKind, name: &'a str, label: &'a str) -> Self {
        Self {
            kind,
            name,
            upper_name: None,
            label,
            hint: None,
            error: None,
            note: None,
            placeholder: None,
            options: &[],
            themes: &[],
            follows: None,
            accept: &[],
            multiple: false,
            required: false,
            max_length: None,
            min: None,
            max: None,
            step: None,
            curve: Curve::Linear { step: None },
            unit: None,
            extended: false,
            as_instant: false,
        }
    }

    /// A bounded number the user drags across its whole extent.
    ///
    /// The third under-described kind, and it gets a constructor for
    /// [`select`](Self::select)'s reason: a range is the one kind whose bounds
    /// are not a rule but the control itself, so a call site that forgot them
    /// has a slider with nothing to slide across. Taking them as arguments is
    /// what makes that unsayable.
    ///
    /// The granularity stays a field rather than a fourth argument, and it is
    /// [`curve`](Self::curve)'s: it is genuinely optional, since the host's own
    /// is a real answer, and the two bounds are not.
    #[must_use]
    pub const fn range(name: &'a str, label: &'a str, min: &'a str, max: &'a str) -> Self {
        Self {
            min: Some(min),
            max: Some(max),
            ..Self::new(FieldKind::Range, name, label)
        }
    }

    /// One question with two ends, taking the name each end submits under.
    ///
    /// A constructor for [`range`](Self::range)'s reason inverted: a range's
    /// bounds are what a call site cannot forget, and an interval's second name
    /// is. An interval built through [`new`](Self::new) has an upper end with
    /// nowhere to be submitted, and nothing downstream can invent one, so taking
    /// it as an argument is what makes that unsayable.
    ///
    /// The extent, the granularity and the unit stay members. They describe the
    /// axis rather than either end and they are genuinely optional, which is
    /// [`FieldKind::Number`]'s arrangement and the one an interval takes.
    #[must_use]
    pub const fn interval(name: &'a str, upper_name: &'a str, label: &'a str) -> Self {
        Self {
            upper_name: Some(upper_name),
            ..Self::new(FieldKind::Interval, name, label)
        }
    }

    /// A file field, taking the given accept list.
    ///
    /// The fourth under-described kind and it gets a constructor for
    /// [`range`](Self::range)'s reason rather than [`select`](Self::select)'s:
    /// a file field with no accept list is not broken, it is a field that takes
    /// anything, and the hazard is the opposite one. A call site that meant to
    /// restrict and forgot has a picker offering every file on the machine and
    /// a server refusing the upload afterwards, which is the failure the list
    /// exists to move forward. Taking it as an argument is what makes an
    /// accidental omission a deliberate `&[]`.
    ///
    /// [`multiple`](Self::multiple) stays a field. One file is the common case
    /// and the honest default; several is the thing worth saying.
    #[must_use]
    pub const fn upload(name: &'a str, label: &'a str, accept: &'a [Accepted<'a>]) -> Self {
        Self {
            accept,
            ..Self::new(FieldKind::File, name, label)
        }
    }

    /// A select offering the given options.
    ///
    /// One of the two kinds under-described by [`Field::new`], so it gets a
    /// constructor rather than leaving every call site to remember that a
    /// select with an empty `options` renders as an empty select.
    #[must_use]
    pub const fn select(name: &'a str, label: &'a str, options: &'a [Choice<'a>]) -> Self {
        Self::offering(FieldKind::Select, name, label, options)
    }

    /// A radio group offering the given options.
    ///
    /// The other. Same hazard as [`select`](Self::select) and a worse one: a
    /// radio group with no options draws nothing at all, so a call site that
    /// forgot them has an empty rectangle rather than a visibly empty control.
    #[must_use]
    pub const fn radio(name: &'a str, label: &'a str, options: &'a [Choice<'a>]) -> Self {
        Self::offering(FieldKind::Radio, name, label, options)
    }

    /// A theme picker over the themes the host resolved.
    ///
    /// A constructor for [`select`](Self::select)'s reason and one of its own.
    /// The shared reason: a theme picker built through [`new`](Self::new) has
    /// an empty [`themes`](Self::themes) list and draws an empty control. Its
    /// own: the list is the *only* thing this kind takes that a call site
    /// cannot get wrong by omission and can get wrong by substitution, since
    /// [`options`](Self::options) is right there and reads as if it would work.
    ///
    /// [`following`](Self::following) is the builder rather than a fourth
    /// argument, because a picker with no follow-the-system row is a real
    /// picker and every renderer draws it honestly.
    #[must_use]
    pub const fn theme(name: &'a str, label: &'a str, themes: &'a [ThemeChoice<'a>]) -> Self {
        Self {
            themes,
            ..Self::new(FieldKind::Theme, name, label)
        }
    }

    /// The same picker, offering a row that tracks the ambient mode.
    ///
    /// The [`Choice`] carries the value the app's own store spells it with.
    #[must_use]
    pub const fn following(mut self, follow: Choice<'a>) -> Self {
        self.follows = Some(follow);
        self
    }

    /// The shared body of the two constructors that take options.
    ///
    /// Private, and keyed on the kind rather than exposed, because the two
    /// public names are the point: a call site says which question it is
    /// asking, not which flag it is setting.
    const fn offering(
        kind: FieldKind,
        name: &'a str,
        label: &'a str,
        options: &'a [Choice<'a>],
    ) -> Self {
        Self {
            options,
            ..Self::new(kind, name, label)
        }
    }

    /// Whether the field is currently reporting a problem.
    ///
    /// Read this rather than testing `error.is_some()` at each renderer: the
    /// error state has to mark the field's whole group and not only the
    /// message, because a renderer with no descendant selectors (egui, a
    /// terminal) cannot find the group from the message. goingson already marks
    /// the group and Balanced Breakfast does not, so goingson's shape is the
    /// one taken here.
    ///
    /// [`note`](Self::note) is deliberately not consulted. A note says the
    /// answer costs something, not that it is unacceptable, and a field the
    /// user may submit as it stands is not invalid.
    #[must_use]
    pub const fn invalid(&self) -> bool {
        self.error.is_some()
    }

    /// Whether the field carries both ends of its extent.
    ///
    /// Only [`FieldKind::Range`] owes them, and it owes them absolutely: a
    /// slider with one end missing has no extent to draw. Named here rather
    /// than left to each renderer to test `min.is_some() && max.is_some()`,
    /// which is three renderers arriving at the same condition and one of them
    /// getting it wrong, and named as a question about the *field* rather than
    /// about the kind because the kind cannot see the bounds.
    ///
    /// It is a check and not a guarantee. Nothing here refuses to build an
    /// unbounded range — [`Field::range`] is what makes the bounded one easy —
    /// so a renderer asks this and falls back to whatever its host does
    /// honestly with a number.
    #[must_use]
    pub const fn bounded(&self) -> bool {
        self.min.is_some() && self.max.is_some()
    }

    /// Whether anything in [`accept`](Self::accept) names a media family.
    ///
    /// The question a renderer asks before it decides to keep room for a
    /// preview, and it is deliberately the *whole list* rather than one entry:
    /// the media dropzone this was measured against takes `image/*,video/*`, so
    /// there is no single family to return and there is still a disclosure to
    /// offer. Which one it turns out to be is known once a file is picked, which
    /// is renderer-side and after the description is gone.
    ///
    /// False for an empty list, for a list of suffixes, and for `text/csv`. A
    /// renderer that wants the family of a particular entry reads
    /// [`Accepted::family`].
    #[must_use]
    pub fn accepts_media(&self) -> bool {
        self.accept.iter().any(|one| one.family().is_some())
    }
}

/// How much room a placement asks for.
///
/// A column says it, and so does a [`Field`]. An intent, so the actual floor
/// stays with `makeover-geometry`. goingson's task table spells these as
/// `minmax(200px, 1fr)`, `140px` and content-sized; only the first three words
/// of that survive deferral.
/// `#[non_exhaustive]`, for the reason [`Fill`] and [`FieldKind`] are: a
/// renderer matches on this and a vocabulary that grows must not break every
/// renderer when it does.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Width {
    /// Takes what it needs and no more.
    Content,
    /// A fixed share, the same at every width.
    Fixed,
    /// Absorbs whatever is left over.
    ///
    /// **Several fills divide what is left equally.** Stated because it would
    /// otherwise be undefined and each renderer would invent something, and
    /// stated this way because equal division is the only sharing rule that
    /// answers to "Any width, one answer" without a tiebreak: allocating in
    /// declaration order makes the result depend on the order the description
    /// was written in, which is a fact about the source file and not about the
    /// screen. It documents what both renderers already do — CSS grid gives
    /// `1fr 1fr`, ratatui gives each a `Constraint::Fill(1)` — rather than
    /// changing anything.
    ///
    /// So a row of fills is a legal thing to describe, and there is no rule
    /// against it.
    Fill,
}

/// What a member is worth when there is not room for all of them.
///
/// Written for table columns and no longer only theirs. Three shapes ask the
/// same question and this answers all three: a table too narrow for its
/// columns, a row too narrow for its parts (see [`RowPart::priority`]), and a
/// group of regions sharing one run of room -- goingson's tab strip and the
/// [`Region::Band`] beside it, which is the case wiki `layout-room-and-fallback`
/// was ruled on. It is what any member of a group is worth, not a table
/// concept, and [`Fallback::Shed`] is what reads it.
///
/// The doc below is the column argument, which is where the type was measured;
/// the sentence that gave it away is [`Priority::Essential`]'s, which was
/// already written about a row.
///
/// Ordered: [`Priority::Optional`] drops first, [`Priority::Essential`] never
/// drops. This replaces addressing columns by position, which is what both
/// webview apps do today and is a live bug rather than only verbosity. goingson
/// hides mobile columns with `nth-child(n+5)` against a seven-column table, so
/// inserting a column silently hides the wrong one.
/// `#[non_exhaustive]`, same reasoning as [`Width`]. Note the ordering is the
/// whole point of the type, so a new tier has to be declared in its place in
/// the sequence rather than appended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum Priority {
    /// Dropped first.
    Optional,
    /// Dropped once the optional members are gone.
    Secondary,
    /// Never dropped. Without it the group does not identify itself.
    Essential,
}

/// What a group does when it runs out of room.
///
/// Authored, and required: the field carrying this has no `Default` and a group
/// cannot be described without saying what it does when it runs out of room.
/// Max ruled on that: more intentionality from layout designers is
/// acceptable so long as the constraints are solvable, because the goal is
/// enabling good layouts rather than rescuing bad ones. A default here would be
/// the crate guessing, and the guess would be silently wrong on the screens
/// that matter.
///
/// Relief resolves inside-out. A group asks its children to fall back before
/// falling back itself, or an outer group collapses while an inner one still
/// had slack.
///
/// # No `Swap`
///
/// An authored alternate group for the tight case is deliberately out of the
/// first cut. It doubles the description for that group and the two halves can
/// drift, which is the failure this vocabulary exists to end. Add it when a
/// site proves it needs one.
///
/// `#[non_exhaustive]`, [`Width`]'s reasoning. Unlike [`Priority`] there is no
/// order to preserve, so a member can be appended.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Fallback {
    /// One row becomes two. Every member stays, in the order described.
    Wrap,
    /// A row becomes a column. Every member stays, full width.
    Stack,
    /// Members drop by [`Priority`], down to [`Priority::Essential`].
    ///
    /// What a narrow table already does with its columns, applied to a group.
    /// What drops is gone from the screen, so this is right when the dropped
    /// members are facts the reader can do without and wrong when they are the
    /// only way to act.
    Shed,
    /// The members [`Shed`](Self::Shed) would drop move into one overflow
    /// control instead.
    ///
    /// The answer when a group holds actions. A control is not a fact: dropping
    /// it does not cost the reader a detail, it costs them the only way to act,
    /// which is [`RowPart::priority`]'s argument one level up.
    Menu,
}

/// One column of a table.
///
/// Described once. The grid track, the cell order and the drop behaviour are
/// all derived from this, rather than being three hand-written encodings that
/// must agree and are never checked against each other.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Column<'a> {
    /// The heading, and the name the cell is addressed by.
    pub name: &'a str,
    /// How much room it asks for.
    pub width: Width,
    /// What it is worth when room runs out.
    pub priority: Priority,
    /// Whether the user can reorder the table by this column.
    ///
    /// What reordering *calls* is not here — that is an address, and this
    /// crate names none — so a host pairs this with the route the way it pairs
    /// a row's parts with the row's activation. This says the affordance
    /// exists, which is what a renderer needs to draw a header a user can
    /// press rather than a heading they cannot.
    pub sortable: bool,
    /// Which way the table is ordered by this column, if it is.
    ///
    /// `None` on every column but the one in force. A renderer draws the caret
    /// from this and a webview sets `aria-sort`, which is why it is per column
    /// rather than a single fact on the table: the host idiom is a property of
    /// the header cell.
    ///
    /// Independent of [`sortable`](Self::sortable) rather than implied by it,
    /// because both combinations mean something. A column sorted and not
    /// sortable is a list ordered by a key the user cannot change, which is a
    /// real thing to describe and a caret worth drawing.
    pub sorted: Option<Sort>,
}

/// Which way a column is ordered.
///
/// Two, because there is no third. "Unsorted" is [`Column::sorted`] being
/// `None`, and folding it in here would be the same absence said twice.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Sort {
    /// Smallest, earliest or first alphabetically at the top.
    Ascending,
    /// The other way.
    Descending,
}

impl Sort {
    /// The other direction, for a header that flips when pressed.
    #[must_use]
    pub const fn reversed(self) -> Self {
        match self {
            Self::Ascending => Self::Descending,
            Self::Descending => Self::Ascending,
        }
    }

    /// What a webview writes into `aria-sort`.
    ///
    /// Named here rather than in the webview renderer because a terminal and an
    /// immediate-mode painter both want the same two words for a caret's label,
    /// and three renderers picking their own is the drift this crate ends.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Ascending => "ascending",
            Self::Descending => "descending",
        }
    }

    /// The caret a renderer draws for this direction.
    ///
    /// Here for [`as_str`](Self::as_str)'s reason, said about a glyph rather
    /// than a word: three renderers picking their own is the drift this crate
    /// ends. They had picked their own — two on the solid triangles and
    /// `makeover-webview` on the arrows U+2191/U+2193 — and agreeing by
    /// coincidence in three files is not agreement.
    ///
    /// The reason generalizes past this pair and is the house rule now —
    /// prefer the bolder, simpler glyph over the thinner or more complicated
    /// one. A third spelling is not open for re-argument.
    ///
    /// **Bare, with no spacing.** Where the gap goes is each renderer's
    /// business: `makeover-tui` and `makeover-immediate` carry a leading space
    /// inside their `TableStyle` string and a webview emits its own in
    /// `content`, so folding a space in here would make one of the two wrong.
    ///
    /// Neither face the web apps self-host carries these — IBM Plex Mono has one
    /// glyph in the whole geometric-shapes block and Lato has none — so a
    /// browser falls back per glyph until the in-house face ships with them
    /// drawn in (wiki `typography-standard`). Cosmetic
    /// drift in one renderer, not a reason to spell it three ways.
    #[must_use]
    pub const fn glyph(self) -> &'static str {
        match self {
            Self::Ascending => "\u{25B2}",
            Self::Descending => "\u{25BC}",
        }
    }
}

impl<'a> Column<'a> {
    /// A column that absorbs slack and drops after the optional ones.
    #[must_use]
    pub const fn new(name: &'a str) -> Self {
        Self {
            name,
            width: Width::Fill,
            priority: Priority::Secondary,
            sortable: false,
            sorted: None,
        }
    }

    /// Whether this column survives at the given cutoff.
    ///
    /// A renderer narrows by raising the cutoff, and never by counting
    /// positions.
    #[must_use]
    pub const fn kept_at(&self, cutoff: Priority) -> bool {
        (self.priority as u8) >= (cutoff as u8)
    }
}

/// What a table cell holds.
///
/// [`RowPart`] for tables, and it exists for the same reason: a part that
/// carries a control is not text, and a renderer with one class for the whole
/// cell paints it as though it were: a button in a cell inherits the cell's
/// content colour, which is the drift [`RowPart::intent`] prevents for rows.
///
/// Four members, and the count is what quasi's `Cell` was measured to carry: a
/// value, tokens, actions and a link. Nothing was added past what something
/// holds.
///
/// `#[non_exhaustive]` for [`RowPart`]'s reason: growth here must not be a
/// lockstep event across three renderers.
///
/// # No hover-reveal
///
/// This enum never gets one. A cell's actions are shown at rest in every
/// consumer measured, and a member nothing uses is one three renderers owe an
/// answer for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum CellPart {
    /// The cell's own text.
    Value,
    /// Small labelled things in the cell: a status badge, a chip.
    Tokens,
    /// Controls that act on what the row is about.
    Actions,
    /// The cell's value, where the value is itself a link.
    Link,
}

impl CellPart {
    /// The content intent the part takes.
    ///
    /// One part is text and three are not, so three answer with the intent
    /// inheriting already gives. That is [`RowPart::intent`]'s shape with the
    /// text side narrower: a cell's secondary and muted readings are the
    /// column's business, not the cell's.
    #[must_use]
    pub const fn intent(self) -> &'static str {
        match self {
            Self::Value => "content",
            // A token carries its own tone, and a part-level intent underneath
            // it would fight the token sitting on it.
            Self::Tokens => "content",
            // Actions carry controls rather than text.
            Self::Actions => "content",
            // A link takes the action colour from the control it is, rather
            // than the cell's text colour from the cell it sits in.
            Self::Link => "content",
        }
    }
}

/// A named dimension a set can be narrowed by.
///
/// One word for six things that were six mechanisms. MNW's discover page filters
/// by free text, a flat any-of over item types, a tree of tags, a numeric range
/// over price, a nested one-of over AI tier, and a browse position in the tag
/// tree held separately from the tag selection — and the last two being separate
/// is the whole reason a filter row there needs a tick box *and* a chevron. The
/// panel is a mixed bag of hand-written controls because nothing named the thing
/// they all are.
///
/// Deliberately wider than that one page. audiofiles' library browser and
/// goingson's filters are the same shape, and a word that only fitted discover
/// would be discover's markup with a neutral name on it.
///
/// # What it does not say
///
/// **What picking a value calls.** This crate names no address, so a facet is
/// paired with routes the way a column's [`sortable`](Column::sortable) flag is
/// paired with what reordering calls.
///
/// **How a tree is drawn.** Indented rows, a column of panes, a breadcrumb and a
/// list: all four are honest renderings of the same described facet, and a
/// terminal will not pick the same one a browser does. [`FacetValue::depth`] is
/// what a renderer needs to draw any of them; the choice is not described.
///
/// **Which values to show.** A tag tree has thousands of nodes and a panel shows
/// a handful. Deciding which handful is the app's — it is the same question as
/// which rows go in a table, and no table member answers it either.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct Facet<'a> {
    /// What the dimension is called, as the user reads it.
    pub name: &'a str,
    /// How many of its values may be in force, and in what shape.
    pub mode: Selecting,
    /// The values on offer, in the order they are drawn.
    ///
    /// A [`Selecting::Text`] facet has none: the value is whatever was typed,
    /// and a description that listed the possible strings would be listing the
    /// corpus. A [`Selecting::Range`] facet has none either, for the reason
    /// [`FieldKind::Range`] takes bounds rather than options — the ends are the
    /// question and the values between them are not enumerable.
    pub values: &'a [FacetValue<'a>],
}

impl<'a> Facet<'a> {
    /// A dimension with values to pick from.
    #[must_use]
    pub const fn new(name: &'a str, mode: Selecting, values: &'a [FacetValue<'a>]) -> Self {
        Self { name, mode, values }
    }

    /// Whether the facet is narrowing the set right now.
    ///
    /// The question a renderer asks to decide whether to offer a way out of it,
    /// and the reason it is derived rather than carried: a facet with nothing
    /// standing is unengaged by construction, so a member saying so could
    /// disagree with the values beside it. [`Standing::Inherited`] does not
    /// count — something further up is what is doing the narrowing, and clearing
    /// a child that was never picked clears nothing.
    ///
    /// Always false for [`Selecting::Text`] and [`Selecting::Range`], which
    /// carry no values. A host that wants a clear affordance on those knows
    /// whether its own box is empty; the description does not hold the typed
    /// string.
    #[must_use]
    pub fn engaged(&self) -> bool {
        self.values.iter().any(|value| value.standing.is_picked())
    }

    /// The deepest value in the facet, or zero when it is flat.
    ///
    /// What an indenting renderer needs to reserve a gutter before it draws the
    /// first row, which is "First paint is final paint" applied to a tree: a
    /// gutter widened as deeper values arrive is the reflow that rule forbids.
    #[must_use]
    pub fn reach(&self) -> u8 {
        self.values
            .iter()
            .map(|value| value.depth.level)
            .max()
            .unwrap_or(0)
    }
}

/// How many of a [`Facet`]'s values may be in force, and in what shape.
///
/// Five, and the fifth is what made this an enum rather than a bool. `one-of`,
/// `any-of`, a range and free text are the four a form vocabulary already has in
/// [`FieldKind`]; a tree's selection is none of them, and describing tags as
/// any-of was what forced browsing to be a second mechanism beside filtering.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Selecting {
    /// Exactly one value, and picking another replaces it.
    ///
    /// MNW's AI tier, whose three options are nested ranges rather than
    /// independent values, so two of them at once means nothing.
    OneOf,
    /// Any number of values, each independent of the others.
    AnyOf,
    /// A low end, a high end, or both.
    ///
    /// Carries no values for [`FieldKind::Range`]'s reason: the ends are the
    /// question.
    Range,
    /// Whatever the user types.
    Text,
    /// A position in a tree, edited by taking branches in and pruning branches
    /// out.
    ///
    /// The one mode that is not reducible to the others, and the one gesture
    /// that replaced two. Picking a value narrows the set to it *and* reveals
    /// its children, so browsing a tree and filtering by it stop being separate
    /// mechanisms with separate state. What a selection then is: a set of
    /// branches taken and a set pruned, resolved nearest-ancestor-first, so
    /// `music` in and `music/synths` out is sayable and no flat mode can say it.
    ///
    /// Resolution happens in the app, and what reaches a renderer is the
    /// [`Standing`] each drawn value ended up with. A renderer walking ancestors
    /// itself would be a renderer that can disagree with the results beside it.
    Subtree,
}

impl Selecting {
    /// Whether the mode picks from values the description lists.
    ///
    /// False for [`Text`](Self::Text) and [`Range`](Self::Range), which are the
    /// two whose answer is not one of a set. A renderer asks this before it
    /// looks at [`Facet::values`], the way it asks
    /// [`FieldKind::offers_options`] before it looks at [`Field::options`].
    #[must_use]
    pub const fn offers_values(self) -> bool {
        matches!(self, Self::OneOf | Self::AnyOf | Self::Subtree)
    }

    /// Whether a value can be pruned as well as picked.
    ///
    /// [`Subtree`](Self::Subtree) alone. Excluding a value from a flat facet is
    /// the same fact as not picking it, so an exclude affordance there would be
    /// a second control for a state the first one already holds.
    #[must_use]
    pub const fn prunes(self) -> bool {
        matches!(self, Self::Subtree)
    }

    /// Whether picking a second value keeps the first.
    #[must_use]
    pub const fn accumulates(self) -> bool {
        matches!(self, Self::AnyOf | Self::Subtree)
    }
}

/// One value a [`Facet`] offers, as it currently stands.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub struct FacetValue<'a> {
    /// What identifies it, and what a host keys its route on.
    ///
    /// [`Choice::value`]'s split, and a tree is why it is not optional: two
    /// leaves under different parents are legitimately both called "Ambient",
    /// and the path is the only thing telling them apart. It is also what
    /// nearest-ancestor-wins resolves over, so an app that carried only labels
    /// could not compute the [`standing`](Self::standing) it hands back here.
    pub value: &'a str,
    /// What it is called, as the user reads it.
    ///
    /// The leaf's own name rather than its path: a facet drawn as an indented
    /// tree repeats every ancestor on every line otherwise, and one drawn as a
    /// breadcrumb has the ancestors already.
    pub label: &'a str,
    /// How many members of the set carry it.
    ///
    /// Optional, and settled that way rather than made mandatory: a count is a
    /// measured fact the app may not have. Counting a tag subtree under an
    /// active text search is a second query, and an app that will not pay for it
    /// should be able to describe the facet anyway rather than write a zero that
    /// reads as "none of them". That is [`Awaiting::amount`]'s rule in a second
    /// place — state a number when it was measured, and nothing when it was not.
    pub count: Option<u64>,
    /// Whether it is narrowing the set, and how it came to be.
    pub standing: Standing,
    /// How far down the tree it sits, counting from zero at the root.
    ///
    /// Always zero for a flat facet, which is what makes an indenting renderer
    /// one code path rather than two. A renderer that draws no tree at all still
    /// reads this, since a value's depth is what distinguishes two same-named
    /// leaves under different parents.
    pub depth: Nesting,
    /// Whether taking it reveals values under it.
    ///
    /// Distinct from having a nonzero [`depth`](Self::depth): a leaf deep in the
    /// tree branches no further, and a root with children does. Both facts are
    /// needed and neither implies the other, which is why the pair is two
    /// members rather than one count.
    pub branching: bool,
}

impl<'a> FacetValue<'a> {
    /// An unpicked value at the root of the facet.
    #[must_use]
    pub const fn new(value: &'a str, label: &'a str) -> Self {
        Self {
            value,
            label,
            count: None,
            standing: Standing::Open,
            depth: Nesting::top(),
            branching: false,
        }
    }

    /// A value whose identifier is also what the user reads.
    ///
    /// [`Choice::of`]'s convenience, and it is the flat case: a type or a tier
    /// is its own name, and only a tree needs a path that is not one.
    #[must_use]
    pub const fn of(value: &'a str) -> Self {
        Self::new(value, value)
    }

    /// How many members carry it, when that was measured.
    #[must_use]
    pub const fn counted(mut self, count: u64) -> Self {
        self.count = Some(count);
        self
    }

    /// How it stands in the current selection.
    #[must_use]
    pub const fn standing(mut self, standing: Standing) -> Self {
        self.standing = standing;
        self
    }

    /// Where it sits in the tree, and whether anything hangs off it.
    #[must_use]
    pub const fn at(mut self, depth: Nesting, branching: bool) -> Self {
        self.depth = depth;
        self.branching = branching;
        self
    }
}

/// Whether a [`FacetValue`] is narrowing the set, and how it came to be.
///
/// Four rather than a bool, and the two extra members are what a tree costs. A
/// pruned branch and an untaken one are not the same state — one was decided
/// against and the other was never reached — and a child under a taken parent is
/// in force without anybody having picked it. A renderer given a bool either
/// marks every descendant of a taken branch, which reads as forty deliberate
/// choices, or marks none of them, which reads as unfiltered.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
#[non_exhaustive]
pub enum Standing {
    /// Not picked, and nothing above it is either.
    #[default]
    Open,
    /// Picked here. The set is narrowed to it and whatever hangs off it.
    Taken,
    /// In force because something above it was taken.
    Inherited,
    /// Pruned out, though something above it was taken.
    ///
    /// The state that only [`Selecting::Subtree`] can reach, and the reason
    /// exclusion is drawn as a visible affordance beside each label rather than
    /// as a modifier on the ordinary one: a gesture a terminal cannot express is
    /// a gesture half the renderers would have to leave out, and an affordance
    /// nothing teaches is one users do not find.
    Pruned,
}

impl Standing {
    /// Whether the user decided this value, either way.
    ///
    /// True for [`Taken`](Self::Taken) and [`Pruned`](Self::Pruned) — both are
    /// choices, and both are things a "clear this" affordance has to clear.
    /// [`Inherited`](Self::Inherited) is not: clearing it clears nothing,
    /// because the decision is further up.
    #[must_use]
    pub const fn is_picked(self) -> bool {
        matches!(self, Self::Taken | Self::Pruned)
    }

    /// Whether the value narrows the set in.
    ///
    /// [`Taken`](Self::Taken) and [`Inherited`](Self::Inherited): one was picked
    /// and one came down from above, and to the set they mean the same thing.
    /// The pair is named here so a renderer colouring in-force values does not
    /// have to know which is which.
    #[must_use]
    pub const fn in_force(self) -> bool {
        matches!(self, Self::Taken | Self::Inherited)
    }

    /// The content intent the value takes.
    ///
    /// [`Pruned`](Self::Pruned) reads back a step, which is the three-tone rule
    /// above rather than a new decision: a pruned branch is still a live control
    /// — pressing it takes the prune off — so it may not wear `content-muted`,
    /// and it is not the thing itself either.
    #[must_use]
    pub const fn intent(self) -> &'static str {
        match self {
            Self::Taken | Self::Inherited | Self::Open => "content",
            Self::Pruned => "content-secondary",
        }
    }
}

#[cfg(test)]
mod tests {
    /// The concept is named here and its magnitude is not, which is
    /// `Awaiting`'s split and is why a renderer can disagree with another
    /// about what a level is worth without either of them being wrong.
    #[test]
    fn nesting_says_how_deep_and_not_how_wide() {
        assert_eq!(Nesting::default(), Nesting::top());
        assert_eq!(Nesting::top().level, 0);
        assert!(!Nesting::top().is_nested());

        let under = Nesting::at(2);
        assert_eq!(under.level, 2);
        assert!(under.is_nested());

        // Ordered, so a renderer walking a flat list of rows can compare two
        // levels rather than reaching into the field.
        assert!(Nesting::top() < under);
    }

    use super::*;

    #[test]
    fn a_markdown_field_is_multiline_and_offers_nothing() {
        // The editing counterpart of markdown prose is still text: every host
        // can draw it, which is the whole reason the kind was addable.
        assert!(FieldKind::Rich.multiline());
        assert!(FieldKind::Textarea.multiline());
        assert!(!FieldKind::Text.multiline());
        // It is not a chooser and not a moment.
        assert!(!FieldKind::Rich.offers_options());
        assert!(!FieldKind::Rich.temporal());
        assert!(FieldKind::Rich.visible());
    }

    #[test]
    fn only_the_numeric_kinds_are_measurable() {
        assert!(FieldKind::Number.measurable());
        assert!(FieldKind::Range.measurable());
        // An axis is measured in something and both its ends are in it, so the
        // unit is read once for the pair rather than per end.
        assert!(FieldKind::Interval.measurable());
        // A date is ordered and is not a quantity with a unit to choose: its
        // unit is fixed by the kind, so saying one would restate `kind`.
        for kind in [
            FieldKind::Text,
            FieldKind::Date,
            FieldKind::DateTime,
            FieldKind::Select,
            FieldKind::Checkbox,
            FieldKind::File,
        ] {
            assert!(!kind.measurable(), "{kind:?}");
        }
    }

    #[test]
    fn a_field_carries_no_unit_until_one_is_given() {
        // Additive: absent is what every field described before 0.33.0 meant.
        let plain = Field::new(FieldKind::Number, "attack", "Attack");
        assert_eq!(plain.unit, None);
        let measured = Field {
            unit: Some("s"),
            ..Field::range("attack", "Attack", "0.001", "5")
        };
        assert_eq!(measured.unit, Some("s"));
        assert!(measured.kind.measurable());
    }

    #[test]
    fn an_interval_states_both_ends_names() {
        // Stated rather than derived: the two measured sites disagree about
        // affix order, so a rule here would rename one of them.
        let suffixed = Field::interval("bpm_min", "bpm_max", "BPM");
        assert_eq!(suffixed.name, "bpm_min");
        assert_eq!(suffixed.upper_name, Some("bpm_max"));
        let prefixed = Field::interval("min_price", "max_price", "Price");
        assert_eq!(prefixed.name, "min_price");
        assert_eq!(prefixed.upper_name, Some("max_price"));
        assert_eq!(suffixed.kind, FieldKind::Interval);
    }

    #[test]
    fn every_other_kind_has_no_upper_end() {
        // Additive: absent is what every field described before 0.34.0 meant.
        for kind in [FieldKind::Text, FieldKind::Number, FieldKind::Range] {
            assert_eq!(Field::new(kind, "n", "N").upper_name, None, "{kind:?}");
        }
        assert_eq!(Field::range("t", "T", "0", "1").upper_name, None);
    }

    #[test]
    fn an_interval_owes_no_bounds_and_takes_the_axis_facts_once() {
        // A range's bounds are the control's extent and are owed; an interval's
        // are a rule on each end, which is Number's arrangement.
        let plain = Field::interval("bpm_min", "bpm_max", "BPM");
        assert!(!plain.bounded());
        let axis = Field {
            min: Some("0"),
            max: Some("300"),
            step: Some("1"),
            unit: Some("BPM"),
            ..Field::interval("bpm_min", "bpm_max", "BPM")
        };
        assert!(axis.bounded());
        assert_eq!(axis.unit, Some("BPM"));
        // Nothing here checks the crossing rule, exactly as nothing checks
        // `min` for a number: the description carries constraints and whoever
        // validated decides a value is wrong.
        assert!(axis.error.is_none());
    }

    #[test]
    fn only_a_subtree_prunes_and_only_the_listing_modes_offer_values() {
        // Excluding a value from a flat facet is the same fact as not picking
        // it, so the affordance exists in exactly one mode.
        assert!(Selecting::Subtree.prunes());
        for mode in [
            Selecting::OneOf,
            Selecting::AnyOf,
            Selecting::Range,
            Selecting::Text,
        ] {
            assert!(!mode.prunes(), "{mode:?}");
        }
        // Text and Range answer with something that is not one of a set.
        assert!(!Selecting::Text.offers_values());
        assert!(!Selecting::Range.offers_values());
        assert!(Selecting::OneOf.offers_values());
        assert!(Selecting::AnyOf.accumulates());
        assert!(!Selecting::OneOf.accumulates());
    }

    #[test]
    fn an_inherited_value_is_in_force_without_having_been_picked() {
        // The distinction a bool cannot hold, and the reason Standing has four
        // members: a child under a taken parent narrows the set, and clearing
        // it clears nothing.
        assert!(Standing::Inherited.in_force());
        assert!(!Standing::Inherited.is_picked());
        assert!(Standing::Taken.in_force());
        assert!(Standing::Taken.is_picked());
        // A prune is a decision that takes the value out.
        assert!(Standing::Pruned.is_picked());
        assert!(!Standing::Pruned.in_force());
        assert!(!Standing::Open.is_picked());
        assert!(!Standing::Open.in_force());
        // A pruned branch still answers a press, so it may not read as inert.
        assert_ne!(Standing::Pruned.intent(), "content-muted");
    }

    #[test]
    fn a_facet_is_engaged_by_a_decision_and_not_by_an_inherited_value() {
        let inherited = [
            FacetValue::of("music")
                .standing(Standing::Taken)
                .at(Nesting::at(0), true),
            FacetValue::new("music/synths", "synths")
                .standing(Standing::Inherited)
                .at(Nesting::at(1), false),
        ];
        let facet = Facet::new("Tag", Selecting::Subtree, &inherited);
        assert!(facet.engaged());
        // The gutter an indenting renderer reserves before its first paint.
        assert_eq!(facet.reach(), 1);

        let untouched = [
            FacetValue::of("music").at(Nesting::at(0), true),
            FacetValue::new("music/synths", "synths")
                .standing(Standing::Inherited)
                .at(Nesting::at(1), false),
        ];
        // Inherited alone is something further up doing the narrowing, and
        // there is nothing further up here.
        assert!(!Facet::new("Tag", Selecting::Subtree, &untouched).engaged());

        // A text facet lists nothing, so it is flat and never reads as engaged
        // from its values: the typed string is not held here.
        let typed = Facet::new("Search", Selecting::Text, &[]);
        assert!(!typed.engaged());
        assert_eq!(typed.reach(), 0);
    }

    #[test]
    fn a_count_is_absent_rather_than_zero_when_it_was_not_measured() {
        // Awaiting::amount's rule in a second place: a written zero reads as
        // "none of them", which is a different claim from "not counted".
        assert_eq!(FacetValue::of("Ambient").count, None);
        assert_eq!(FacetValue::of("Ambient").counted(0).count, Some(0));
    }

    #[test]
    fn one_kind_takes_files_and_the_two_file_members_are_its_alone() {
        assert!(FieldKind::File.takes_files());
        for kind in [
            FieldKind::Text,
            FieldKind::Textarea,
            FieldKind::Rich,
            FieldKind::Select,
            FieldKind::Checkbox,
            FieldKind::Hidden,
        ] {
            assert!(!kind.takes_files());
        }
        // The default is a field that takes any one file, which is what an
        // input with no accept and no multiple already is.
        let plain = Field::new(FieldKind::File, "cover", "Cover");
        assert!(plain.accept.is_empty());
        assert!(!plain.multiple);
    }

    #[test]
    fn an_accept_list_says_which_disclosure_and_a_suffix_says_none() {
        // The three shapes are the MNW server's own three, and the family is
        // the question a renderer asks before it keeps room for a preview.
        assert_eq!(
            Accepted::Family(Family::Image).family(),
            Some(Family::Image)
        );
        assert_eq!(Accepted::Type("image/jpeg").family(), Some(Family::Image));
        assert_eq!(Accepted::Type("audio/flac").family(), Some(Family::Audio));
        assert_eq!(
            Accepted::Type("video/quicktime").family(),
            Some(Family::Video)
        );
        // A media type outside the three families names none, and neither does
        // a suffix. `.mp3` is audio in fact and this crate will not infer it:
        // the table that said so would rot.
        assert_eq!(Accepted::Type("text/csv").family(), None);
        assert_eq!(Accepted::Suffix(".mp3").family(), None);
        assert_eq!(Accepted::Suffix(".tar.gz").family(), None);
        // Media types are case-insensitive and half the tree writes them
        // lowercase by habit rather than by rule.
        assert_eq!(Accepted::Type("IMAGE/PNG").family(), Some(Family::Image));
    }

    #[test]
    fn every_accepted_entry_has_one_spelling_a_host_can_write() {
        assert_eq!(Accepted::Family(Family::Image).as_str(), "image/*");
        assert_eq!(Accepted::Family(Family::Audio).as_str(), "audio/*");
        assert_eq!(Accepted::Family(Family::Video).as_str(), "video/*");
        assert_eq!(Accepted::Type("text/csv").as_str(), "text/csv");
        assert_eq!(Accepted::Suffix(".tar.gz").as_str(), ".tar.gz");
    }

    #[test]
    fn a_list_accepting_two_families_still_has_a_disclosure_to_offer() {
        // The measured dropzone: `accept="image/*,video/*"`. There is no single
        // family to return and there is still a preview to keep room for, which
        // is why the question is asked of the list rather than of one entry.
        const MEDIA: &[Accepted<'_>] = &[
            Accepted::Family(Family::Image),
            Accepted::Family(Family::Video),
        ];
        assert!(Field::upload("media", "Media", MEDIA).accepts_media());
        // An installer's suffix list wants no disclosure, which is the measured
        // case rather than a hypothetical one.
        const BUILDS: &[Accepted<'_>] = &[Accepted::Suffix(".zip"), Accepted::Suffix(".dmg")];
        assert!(!Field::upload("build", "Build", BUILDS).accepts_media());
        // And a field that takes anything says so by listing nothing.
        assert!(!Field::upload("any", "File", &[]).accepts_media());
    }

    #[test]
    fn an_upload_carries_its_list_and_takes_one_file_until_it_says_otherwise() {
        const IMAGES: &[Accepted<'_>] = &[
            Accepted::Type("image/jpeg"),
            Accepted::Type("image/png"),
            Accepted::Type("image/webp"),
        ];
        let avatar = Field::upload("avatar", "Avatar", IMAGES);
        assert_eq!(avatar.kind, FieldKind::File);
        assert_eq!(avatar.accept, IMAGES);
        assert!(!avatar.multiple);
        let several = Field {
            multiple: true,
            ..avatar
        };
        assert!(several.multiple);
    }

    #[test]
    fn the_four_readiness_states_are_one_axis_and_only_one_shows_content() {
        // Mutually exclusive is the test for one enum against several fields: a
        // region shows its content, or that it is coming, or that there is none,
        // or that it broke. Never two.
        assert!(Readiness::Ready.shows_content());
        for state in [Readiness::Pending, Readiness::Empty, Readiness::Failed] {
            assert!(!state.shows_content());
        }
    }

    #[test]
    fn a_region_shows_all_of_its_children_unless_it_says_otherwise() {
        // The default is the behaviour every region had before this member
        // existed, which is what keeps it additive: a description written
        // against 0.22.0 says the same thing under 0.23.0.
        assert_eq!(Showing::default(), Showing::All);
        assert!(!Showing::All.selective());
    }

    #[test]
    fn only_a_disclosure_can_show_nothing() {
        // The two derived idioms differ in one respect and this is it. A
        // carousel's row moves between frames and never reaches empty; a
        // disclosure's summary line is the same control wearing its closed
        // state, so a renderer has to know which it is drawing.
        assert!(Showing::AtMostOne.dismissible());
        assert!(!Showing::One.dismissible());
        assert!(!Showing::All.dismissible());

        // Both are selective, though. Deriving chrome is one question and
        // whether that chrome closes is another.
        assert!(Showing::One.selective());
        assert!(Showing::AtMostOne.selective());
    }

    #[test]
    fn an_empty_region_is_not_a_broken_one() {
        // An empty list is the normal state of a new install. Drawing it in a
        // danger tone reports a fault where there is none, and this is the one
        // place the distinction is carried.
        assert_eq!(Readiness::Empty.tone(), Tone::Neutral);
        assert_eq!(Readiness::Failed.tone(), Tone::Danger);
        assert_eq!(Readiness::Pending.tone(), Tone::Neutral);
    }

    #[test]
    fn a_column_can_be_sorted_without_being_sortable() {
        // Both combinations mean something, which is why the two fields are
        // independent rather than one implying the other. A list ordered by a
        // key the user cannot change is a real thing with a caret worth drawing.
        let fixed = Column {
            sorted: Some(Sort::Descending),
            ..Column::new("Created")
        };

        assert!(!fixed.sortable);
        assert_eq!(fixed.sorted.map(Sort::as_str), Some("descending"));

        let offered = Column {
            sortable: true,
            ..Column::new("Name")
        };
        assert_eq!(offered.sorted, None);
    }

    #[test]
    fn a_direction_flips_and_says_what_it_is() {
        assert_eq!(Sort::Ascending.reversed(), Sort::Descending);
        assert_eq!(Sort::Descending.reversed().reversed(), Sort::Descending);
        assert_eq!(Sort::Ascending.as_str(), "ascending");
    }

    #[test]
    fn a_direction_carries_its_caret_and_the_two_are_not_the_same_glyph() {
        // The spelling every renderer reads, so that agreeing is composition
        // rather than three files happening to hold the same literal.
        assert_eq!(Sort::Ascending.glyph(), "\u{25B2}");
        assert_eq!(Sort::Descending.glyph(), "\u{25BC}");
        assert_ne!(Sort::Ascending.glyph(), Sort::Descending.glyph());
        // Bare. The gap is the renderer's, and a space here would be a second
        // one wherever a renderer already carries its own.
        for d in [Sort::Ascending, Sort::Descending] {
            assert_eq!(d.glyph().trim(), d.glyph());
        }
    }

    #[test]
    fn a_figure_carries_its_tone_because_no_renderer_can_derive_it() {
        // Three of goingson's five sites tone the figure by their own means, so
        // tone is carried at every site that needs it and derived at none. The
        // same reasoning `Meter` reached, from a different direction.
        let streak = Figure::new("0", "Current Streak").tone(Tone::Warning);
        assert_eq!(streak.tone, Tone::Warning);
        assert_eq!(Figure::new("17", "Total").tone, Tone::Neutral);
    }

    #[test]
    fn a_figures_change_is_the_toned_part_and_is_absent_by_default() {
        // 0.13.0. The MNW server's stat card is a label, a value and a delta,
        // across four screens, and the delta is what reads as good or bad. Tone
        // had no consumer before this: the figure itself is an ordinary fact.
        let views = Figure::new("1,204", "Views")
            .change("+12.5%")
            .tone(Tone::Success);
        assert_eq!(views.change, Some("+12.5%"));
        assert_eq!(views.tone, Tone::Success);

        // A figure with nothing to compare against says so by having no change,
        // rather than by carrying an empty string a renderer has to test for.
        assert_eq!(Figure::new("3.1%", "Conversion").change, None);
    }

    #[test]
    fn a_figures_value_is_text_because_only_the_app_knows_what_it_is() {
        // "84%", "12/30", "3d". A figure is whatever the app computed, already
        // formatted, and that is the line between this and `Meter`: a meter is
        // a proportion a renderer draws, a figure is a fact it sets in type.
        for value in ["84%", "12/30", "3d"] {
            assert_eq!(Figure::new(value, "Rate").value, value);
        }
    }

    #[test]
    fn a_proportion_is_a_row_part_and_takes_no_intent_of_its_own() {
        // The meter carries the tone, so a part-level intent underneath would
        // fight it. Same answer `Tokens` needed, for the same reason.
        assert_eq!(RowPart::Proportion.intent(), RowPart::Tokens.intent());
    }

    #[test]
    fn a_file_field_is_drawn_and_offers_no_options() {
        // It is a control the user operates, unlike `Hidden`, and it does not
        // pick from a list the description carries, unlike `Select`.
        assert!(FieldKind::File.visible());
        assert!(!FieldKind::File.offers_options());
        assert!(!FieldKind::File.confidential());
    }

    #[test]
    fn a_constraint_is_a_fact_about_the_question_and_not_a_verdict() {
        // The whole model: the description carries the rule, the renderer emits
        // its host's idiom, and `error` is what arrives back when someone
        // validated. Nothing here decides a value is wrong.
        let field = Field {
            max_length: Some(100),
            min: Some("1"),
            max: Some("240"),
            required: true,
            ..Field::new(FieldKind::Number, "minutes", "Minutes")
        };
        assert!(!field.invalid());

        // A bound is text because it is only a number for some of the kinds
        // that take one. goingson has both shapes live.
        let when = Field {
            min: Some("2026-08-09T14:30"),
            ..Field::new(FieldKind::Text, "starts", "Starts")
        };
        assert_eq!(when.min, Some("2026-08-09T14:30"));
    }

    #[test]
    fn a_meter_keeps_the_over_run_the_percentage_throws_away() {
        // The whole reason this is a pair. goingson's `Task::time_progress`
        // clamps to 100 and then carries `is_over_estimate` beside it to say
        // what the clamp dropped; a meter says both from one fact.
        let over = Meter::new(45, 30);
        assert_eq!(over.percent(), 100);
        assert!(over.overflowing());

        let exact = Meter::new(30, 30);
        assert_eq!(exact.percent(), over.percent());
        assert!(!exact.overflowing());
    }

    #[test]
    fn an_empty_set_does_not_divide_by_zero() {
        // Sayable on purpose, so it has to be answerable. A meter over an
        // unloaded count is what an app actually has for a frame.
        let none = Meter::new(0, 0);
        assert_eq!(none.percent(), 0);
        assert!(none.is_empty());
        assert!(!none.overflowing());
    }

    #[test]
    fn the_ratio_survives_where_a_percentage_would_not() {
        // Given 43 nothing can recover "3 of 7", which is why the numbers are
        // carried and the label names only the noun.
        let m = Meter::new(3, 7).label("subtasks");
        assert_eq!(m.percent(), 42);
        assert_eq!((m.done, m.total), (3, 7));
        assert_eq!(m.label, Some("subtasks"));
    }

    #[test]
    fn tone_is_carried_because_no_renderer_can_derive_it() {
        // The same fullness means opposite things on two of goingson's bars,
        // and only the app knows which.
        let subtasks = Meter::new(9, 10).tone(Tone::Success);
        let estimate = Meter::new(9, 10).tone(Tone::Danger);
        assert_eq!(subtasks.percent(), estimate.percent());
        assert_ne!(subtasks.tone, estimate.tone);
        // Untoned by default: a bar says nothing about status until something
        // says so, the same way a row is not selectable until told.
        assert_eq!(Meter::new(9, 10).tone, Tone::Neutral);
    }

    #[test]
    fn an_act_is_reachable_until_it_is_disabled() {
        // The one member a renderer must branch on, and since 0.19.0 the only
        // member there is. A stated state is not by itself a reason to stop
        // answering, which is the distinction `State` makes and every
        // hand-rolled button in the tree had to remember.
        assert!(!Act::new("Save").disabled());
        assert!(Act::new("Save").state(State::Disabled).disabled());
    }

    #[test]
    fn an_act_carries_its_key_because_a_terminal_has_nothing_else() {
        // No key is the ordinary case, and the webview hosts that ignore it
        // are why it stayed optional.
        assert_eq!(Act::new("Delete").key, None);
        let quit = Act::new("Quit").key("q").tone(Tone::Danger);
        assert_eq!(quit.key, Some("q"));
        assert_eq!(quit.tone, Tone::Danger);
    }

    #[test]
    fn a_meter_does_not_overflow_on_large_counts() {
        // done * 100 in u32 would wrap somewhere past 42 million. Counts that
        // size are not tasks, but a description layer that silently reports 3%
        // for a full bar is worse than one that is slow.
        let big = Meter::new(u32::MAX, u32::MAX);
        assert_eq!(big.percent(), 100);
        assert!(!big.overflowing());
    }

    #[test]
    fn inset_is_raised_with_the_light_moved() {
        let (rl, rd) = Bevel::Raised.edges();
        let (il, id) = Bevel::Inset.edges();
        assert_eq!((rl, rd), (Edge::Light, Edge::Dark));
        assert_eq!((il, id), (rd, rl));
    }

    #[test]
    fn pressing_twice_is_a_no_op() {
        for b in [Bevel::Raised, Bevel::Inset] {
            assert_eq!(b.pressed().pressed(), b);
        }
    }

    #[test]
    fn a_raised_region_is_never_filled_with_a_recessed_surface() {
        // The bug this vocabulary exists to make unrepresentable.
        assert_eq!(Depth::Raised.fill(), Some(Fill::Raised));
        assert_eq!(Depth::Raised.bevel(), Some(Bevel::Raised));
        assert_eq!(Depth::Well.bevel(), Some(Bevel::Inset));
        assert_ne!(Depth::Well.fill(), Depth::Raised.fill());
    }

    #[test]
    fn state_is_orthogonal_to_depth() {
        // The reason State is its own axis and not a Depth member: a disabled
        // button and a disabled field are both disabled and are not the same
        // shape, which one shared variant could not have said.
        assert_eq!(Depth::Raised.fill(), Some(Fill::Raised));
        assert_eq!(Depth::Well.fill(), Some(Fill::Well));
        assert!(State::Disabled.suppresses_interaction());
    }

    #[test]
    fn only_disabled_stops_answering() {
        // Kept in spirit from the version where `Focus` was the counter-example:
        // suppressing interaction is `Disabled`'s alone, so a member added here
        // later does not get to inherit it by being a state.
        assert!(State::Disabled.suppresses_interaction());
    }

    #[test]
    fn disabled_resolves_against_an_intent_makeover_already_derives() {
        // No new token, so this costs no `makeover` release.
        assert_eq!(State::Disabled.token(), "content-muted");
    }

    #[test]
    fn flat_has_neither_edge_nor_fill() {
        assert_eq!(Depth::Flat.bevel(), None);
        assert_eq!(Depth::Flat.fill(), None);
    }

    #[test]
    fn sunken_is_recessed_by_colour_with_no_edge() {
        // The one member carrying a fill without a bevel. A renderer that
        // assumes the two arrive together drops the fill silently, which is
        // exactly what makeover-webview did before 0.3.0.
        assert_eq!(Depth::Sunken.fill(), Some(Fill::Sunken));
        assert_eq!(Depth::Sunken.bevel(), None);
    }

    #[test]
    fn sunken_and_flat_are_different_claims() {
        // Both edgeless, and only one of them needs a colour. Collapsing them
        // is what left an unchosen tab unsayable.
        assert_eq!(Depth::Flat.bevel(), Depth::Sunken.bevel());
        assert_ne!(Depth::Flat.fill(), Depth::Sunken.fill());
    }

    #[test]
    fn a_sunken_surface_is_not_a_well() {
        // Authored in opposite directions: makeover derives surface-well by
        // inverting against the theme's content colour, while surface-sunken is
        // authored and may sit darker than raised.
        assert_ne!(Fill::Sunken, Fill::Well);
        assert_eq!(Fill::Sunken.token(), "surface-sunken");
        assert_eq!(Fill::Well.token(), "surface-well");
    }

    #[test]
    fn every_selector_describes_both_of_its_states() {
        // The gap 0.3.0 closed. Before it, only `chosen` existed and the
        // unchosen option fell through to Flat at every renderer.
        for s in [Selector::Tabs, Selector::Segmented, Selector::Toggle] {
            assert_ne!(
                s.chosen(),
                s.unchosen(),
                "{s:?} cannot tell picked from unpicked"
            );
        }
    }

    #[test]
    fn only_a_tab_inverts_the_other_way() {
        // Tabs recede so the chosen one comes forward; a segment and a toggle
        // stand up so the chosen one is held in. That inversion is the whole
        // content of "picked" once colour is deferred, and it is why the three
        // are not one member with a flag.
        assert_eq!(Selector::Tabs.unchosen(), Depth::Sunken);
        assert_eq!(Selector::Tabs.chosen(), Depth::Raised);

        for s in [Selector::Segmented, Selector::Toggle] {
            assert_eq!(s.unchosen(), Depth::Raised);
            assert_eq!(s.chosen(), Depth::Well);
            // Held in is what pressing produces: one appearance, two reasons.
            assert_eq!(s.unchosen().pressed(), s.chosen());
        }
    }

    #[test]
    fn pressing_a_card_makes_a_well() {
        assert_eq!(Depth::Raised.pressed(), Depth::Well);
        assert_eq!(
            Depth::Raised.pressed().bevel(),
            Depth::Raised.bevel().map(Bevel::pressed)
        );
        // Only raised regions respond to being pressed.
        assert_eq!(Depth::Flat.pressed(), Depth::Flat);
        assert_eq!(Depth::Well.pressed(), Depth::Well);
        // An overlay is a surface, not a control.
        assert_eq!(Depth::Overlay.pressed(), Depth::Overlay);
    }

    #[test]
    fn an_overlay_is_lifted_rather_than_edged() {
        // The wave-2 rule: a surface over the page takes elevation, a surface
        // in the page takes a bevel. Both halves come off the one Depth, so
        // they cannot disagree.
        assert_eq!(Depth::Overlay.fill(), Some(Fill::Overlay));
        assert_eq!(Depth::Overlay.bevel(), None);

        // Three depths have no bevel and they are not the same claim. Flat has
        // nothing to separate from, Sunken's colour is doing the separating,
        // and an overlay is separated by the lift.
        assert_ne!(Depth::Overlay.fill(), Depth::Sunken.fill());
        assert_ne!(Depth::Overlay.fill(), Depth::Flat.fill());
    }

    #[test]
    fn a_note_is_neither_a_hint_nor_an_error() {
        // audiofiles' export Format field: choosing WAV over Original
        // re-encodes and drops the embedded metadata. Perfectly valid, and it
        // costs something.
        let format = Field {
            note: Some((Tone::Warning, "Re-encoding drops embedded BWF and iXML")),
            ..Field::select("format", "Format", &[])
        };
        assert!(!format.invalid(), "a note is not a validation failure");
        assert!(format.hint.is_none());
        assert!(format.error.is_none());
        assert_eq!(format.note.unwrap().0, Tone::Warning);

        // The default is no note, so the 15 in-tree `..Field::new(..)`
        // literals absorb the member with no call-site edit.
        assert!(Field::new(FieldKind::Text, "title", "Title").note.is_none());
    }

    #[test]
    fn neutral_is_content_not_muted_content() {
        // Neutral means "no status", and that is all it means. It answered
        // `content-muted` until 2026-08-27, which muted a figure's headline
        // number to the colour of its own caption. What makes a badge quiet
        // is `Token::Badge` answering no click, which lives on the renderer.
        assert_eq!(Tone::Neutral.token(), "content");
        assert!(!Token::Badge.interactive());
        assert_eq!(State::Disabled.token(), "content-muted");
    }

    #[test]
    fn intents_name_makeover_tokens_and_nothing_else() {
        assert_eq!(Edge::Light.token(), "bevel-light");
        assert_eq!(Edge::Dark.token(), "bevel-dark");
        assert_eq!(Fill::Raised.token(), "surface-raised");
        assert_eq!(Fill::Well.token(), "surface-well");
        // No value ever leaves this crate.
        for t in [
            Edge::Light.token(),
            Edge::Dark.token(),
            Tone::Danger.token(),
            Tone::Neutral.token(),
            State::Disabled.token(),
        ] {
            assert!(!t.starts_with('#'), "{t} looks like a value");
            assert!(
                !t.chars().next().unwrap().is_ascii_digit(),
                "{t} is a value"
            );
        }
    }

    #[test]
    fn a_badge_cannot_be_pressed_and_a_chip_latches() {
        // The one line that runs through all three apps' taxonomies.
        assert!(!Token::Badge.interactive());
        assert!(Token::Chip { removable: false }.interactive());
        assert!(Token::Chip { removable: true }.interactive());

        // A badge is a label, so giving it an edge would lie about it.
        assert_eq!(Token::Badge.depth(false), Depth::Flat);
        assert_eq!(Token::Badge.depth(true), Depth::Flat);

        // A latched chip wears the same shape a pressed one does.
        let chip = Token::Chip { removable: false };
        assert_eq!(chip.depth(false), Depth::Raised);
        assert_eq!(chip.depth(true), Depth::Raised.pressed());
    }

    #[test]
    fn a_toast_and_a_banner_differ_in_more_than_placement() {
        assert!(Notice::Toast.transient());
        assert!(!Notice::Banner.transient());
        // A toast floats above the page; a banner rests in the flow.
        assert_eq!(Notice::Toast.fill(), Fill::Overlay);
        assert_eq!(Notice::Banner.fill(), Fill::Raised);
    }

    #[test]
    fn emphasis_falls_off_down_the_row() {
        // `revealed_on_hover` was asserted here until 0.13.0 retired it. It said
        // a row's actions stay hidden until hover, which stopped being true when
        // makeover-webview 0.23.0 showed them at rest, and nothing had consumed
        // it for a release either way.
        assert_eq!(RowPart::Primary.intent(), "content");
        assert_eq!(RowPart::Secondary.intent(), "content-secondary");
        assert_eq!(RowPart::Meta.intent(), "content-muted");
    }

    #[test]
    fn a_token_part_carries_no_intent_of_its_own() {
        // Each token carries its own tone, so a part-level intent underneath
        // would fight the thing sitting on it. Same reasoning as actions, which
        // is why they answer alike.
        assert_eq!(RowPart::Tokens.intent(), RowPart::Actions.intent());
        assert_eq!(RowPart::Tokens.intent(), "content");
    }

    #[test]
    fn the_two_temporal_kinds_are_the_two_that_name_a_moment() {
        // The pair is named once so a host with parsing to do asks here rather
        // than spelling it out, which is `offers_options`' reason.
        assert!(FieldKind::Date.temporal());
        assert!(FieldKind::DateTime.temporal());

        for kind in [
            FieldKind::Text,
            FieldKind::Secret,
            FieldKind::Number,
            FieldKind::Email,
            FieldKind::Url,
            FieldKind::Tel,
            FieldKind::Range,
            FieldKind::Textarea,
            FieldKind::Rich,
            FieldKind::Select,
            FieldKind::Radio,
            FieldKind::Checkbox,
            FieldKind::File,
            FieldKind::Hidden,
        ] {
            assert!(!kind.temporal(), "{kind:?}");
        }
    }

    #[test]
    fn a_date_carries_no_time_and_a_datetime_carries_no_zone() {
        // The formats are the whole reason the members are worth naming apart
        // from text, so the doc comments and the constants have to agree. A
        // host reading one and meeting the other is the silent failure.
        assert_eq!(DATE_FORMAT, "%Y-%m-%d");
        assert!(!DATE_FORMAT.contains("%H"), "a day carries no hour");

        assert_eq!(DATETIME_FORMAT, "%Y-%m-%dT%H:%M");
        assert!(
            DATETIME_FORMAT.starts_with(DATE_FORMAT),
            "a moment starts with the day it is on"
        );
        // Local, and that is a property of the value rather than an omission.
        assert!(!DATETIME_FORMAT.contains("%Z"), "no zone name");
        assert!(!DATETIME_FORMAT.ends_with('Z'), "not UTC-stamped");
        assert!(!DATETIME_FORMAT.contains("%S"), "no seconds by default");
    }

    #[test]
    fn a_temporal_kind_takes_a_label_above_it_and_offers_no_options() {
        // Neither is a checkbox and neither is a fixed set, so both fall where
        // text does. Asserted because a new kind lands in three predicates and
        // only one of them is the interesting one.
        for kind in [FieldKind::Date, FieldKind::DateTime] {
            assert!(kind.visible(), "{kind:?}");
            assert!(!kind.confidential(), "{kind:?}");
            assert!(!kind.labels_itself(), "{kind:?}");
            assert!(!kind.offers_options(), "{kind:?}");
        }
    }

    #[test]
    fn a_cell_part_names_an_intent_and_only_the_value_is_text() {
        // The table half of what RowPart::intent does for rows. A cell holding
        // a control and a cell holding text answered alike until 0.14.0, and a
        // control in a cell took the cell's text colour.
        assert_eq!(CellPart::Value.intent(), "content");

        for part in [CellPart::Tokens, CellPart::Actions, CellPart::Link] {
            // Each for its own reason -- a token carries its tone, an action is
            // a control, a link takes the action colour -- and all three reach
            // the intent inheriting already gives.
            assert_eq!(part.intent(), CellPart::Value.intent(), "{part:?}");
        }
    }

    #[test]
    fn every_cell_part_answers_with_a_token_and_never_a_value() {
        for part in [
            CellPart::Value,
            CellPart::Tokens,
            CellPart::Actions,
            CellPart::Link,
        ] {
            let intent = part.intent();
            assert!(!intent.is_empty(), "{part:?} names nothing");
            assert!(!intent.starts_with('#'), "{part:?} looks like a value");
        }
    }

    #[test]
    fn a_separator_is_what_tells_a_section_from_a_subsection() {
        assert!(Heading::Section.separated());
        assert!(!Heading::Subsection.separated());
        assert!(!Heading::Page.separated());
    }

    #[test]
    fn a_chosen_segment_is_held_in_and_a_chosen_tab_comes_forward() {
        assert_eq!(Selector::Segmented.chosen(), Depth::Well);
        assert_eq!(Selector::Toggle.chosen(), Depth::Well);
        // The exception, and the whole folder semantic: the open tab joins its
        // pane rather than sinking away from it.
        assert_eq!(Selector::Tabs.chosen(), Depth::Raised);

        // A held-in segment is indistinguishable from a pressed raised one,
        // which is the economy the light model buys over a colour swap.
        assert_eq!(Selector::Segmented.chosen(), Depth::Raised.pressed());

        // A toggle stands alone; the other two are built out of parts that
        // touch.
        assert!(Selector::Segmented.abutting());
        assert!(Selector::Tabs.abutting());
        assert!(!Selector::Toggle.abutting());
    }

    #[test]
    fn columns_are_peers_and_a_split_is_not() {
        // The distinction the member exists for. A split's two panes stand in a
        // master-detail relationship; columns choose nothing about each other.
        // Both are flat, so depth cannot tell them apart and the doc has to.
        assert_eq!(Region::Columns.depth(), Depth::Flat);
        assert_eq!(Region::Split.depth(), Depth::Flat);
        assert_ne!(Region::Columns, Region::Split);
    }

    #[test]
    fn columns_carry_no_count_and_no_share() {
        // The two things a board is always asked to carry and must not. How
        // many is what the children say; how wide is settled by "peers are
        // equal".
        //
        // The guard is the binding itself and it is a compile-time one: adding
        // a field to `Columns` stops this line compiling, which is a better
        // failure than any assertion about it. Written out rather than inlined
        // for exactly that reason.
        let columns: Region<'_> = Region::Columns;
        assert_eq!(columns.name(), None);
    }

    #[test]
    fn columns_are_described_and_the_escape_hatch_is_still_one_member() {
        // A board's contents are ordinary description all the way down, so a
        // renderer that does not lay them across still draws every column.
        // Stacking them vertically is honouring this member, not degrading it.
        assert!(Region::Columns.described());
        assert!(!Region::Bespoke { name: "timeline" }.described());
    }

    #[test]
    fn a_span_never_has_zero_minutes_however_it_is_asked_for() {
        // Every renderer divides by this. A caller passing a backwards or empty
        // span is a bug, but it is not a bug worth a panic three renderers deep.
        assert_eq!(Span::new(600, 600).length(), 1);
        assert_eq!(Span::new(600, 300).length(), 1);
        assert_eq!(Span::DAY.length(), 1440);
    }

    #[test]
    fn a_span_can_run_past_midnight_without_a_second_date() {
        // 22:00 to 02:00. The alternative was carrying a date, which drags a
        // timezone into the vocabulary for the sake of one night shift.
        let overnight = Span::new(1320, 1560);
        assert_eq!(overnight.length(), 240);
        assert!(overnight.holds(1500));
        assert!(!overnight.holds(1200));
    }

    #[test]
    fn overlap_is_computed_rather_than_declared() {
        // The reason Placement carries no `conflicts` flag: the times already
        // say it, and a second source for one fact is how a stale conflict
        // badge outlives the conflict.
        let morning = Placement::new(540, 60); // 09:00-10:00
        let overlapping = Placement::new(570, 60); // 09:30-10:30
        let after = Placement::new(600, 60); // 10:00-11:00

        assert!(morning.overlaps(overlapping));
        assert!(overlapping.overlaps(morning), "overlap is symmetric");
        // Touching end to end is not overlapping: `to` is exclusive, so a
        // 10:00 start does not collide with a 10:00 end.
        assert!(!morning.overlaps(after));
        assert!(!after.overlaps(morning));
    }

    #[test]
    fn a_placement_is_always_drawable() {
        assert_eq!(Placement::new(540, 0).length(), 1);
        assert_eq!(Placement::new(540, 30).end(), 570);
    }

    #[test]
    fn a_track_places_the_fraction_every_renderer_would_otherwise_compute() {
        let day = Track::DAY;
        assert!((day.fraction(0) - 0.0).abs() < f32::EPSILON);
        assert!((day.fraction(720) - 0.5).abs() < f32::EPSILON);
        // Clamped rather than off the end: an event running past the span's
        // close draws at the edge, which beats panicking or drawing nowhere.
        assert!((day.fraction(2000) - 1.0).abs() < f32::EPSILON);
    }

    #[test]
    fn a_track_counts_its_slots_and_never_divides_by_zero() {
        assert_eq!(Track::DAY.slots(), 96);
        assert_eq!(Track::over(Span::new(540, 1020)).slots(), 32);
        // A span that does not divide evenly keeps a slot for its tail.
        assert_eq!(Track::over(Span::new(0, 50)).slots(), 4);
        // slot: 0 is a caller bug that reads as one slot, not a panic.
        let degenerate = Track {
            span: Span::DAY,
            slot: 0,
            tick: 60,
            unit: Unit::Minutes,
        };
        assert_eq!(degenerate.slots(), 1);
    }

    #[test]
    fn a_track_carries_facts_and_no_presentation() {
        // The guard on the thing the withdrawn refusal was right about. If a
        // pixel measure, a scroll offset or a colour ever lands on Track, the
        // member has stopped being a fact about the data and the timeline
        // really has become a component library wearing a description's name.
        let day = Track::DAY;
        assert_eq!(day.span, Span::DAY);
        assert_eq!(day.slot, 15);
        assert_eq!(day.tick, 60);
        assert_eq!(day.unit, Unit::Minutes);

        // Three fields when this was written, and the fourth came here to say
        // why, which is the whole point of the assertion. `unit` is what the
        // integers COUNT -- a fact about the data, unavailable from the numbers
        // themselves, and the absence of it is what let a month strip render
        // under a wall clock. A fifth field still has to argue, and "the
        // renderer would find it handy" is still not the argument.
        // Destructured rather than rebuilt: this is the form that names every
        // field and stops compiling when a fifth arrives, without binding
        // anything a lint has to forgive.
        let Track {
            span: _,
            slot: _,
            tick: _,
            unit: _,
        } = day;
    }

    #[test]
    fn a_day_strip_is_the_same_arithmetic_under_a_different_unit() {
        // The probe that found the defect, kept as a test. Fifteen days from
        // day three, on a thirty-one day month: the geometry was always right
        // and only the label was wrong, which is why `unit` is a fact and not
        // presentation.
        let march = Track::days(Span::new(0, 31));
        assert_eq!(march.slots(), 31);
        assert_eq!(march.unit, Unit::Days);

        let leave = Placement::new(2, 15);
        assert!((march.fraction(leave.at()) - 2.0 / 31.0).abs() < 0.0001);
        assert!((march.fraction(leave.end()) - 17.0 / 31.0).abs() < 0.0001);
    }

    #[test]
    fn a_pane_is_looked_into_and_a_band_is_not() {
        assert_eq!(Region::Pane.depth(), Depth::Well);
        assert_eq!(Region::Modal.depth(), Depth::Raised);
        for r in [
            Region::Band,
            Region::Sidebar,
            Region::Group,
            Region::Split,
            Region::TabGroup,
        ] {
            assert_eq!(r.depth(), Depth::Flat, "{r:?} should carry no edge");
        }
    }

    #[test]
    fn exactly_one_region_is_opaque() {
        // The escape hatch is one member and stays one member. If a second
        // undescribed region ever appears, the description has started
        // conceding rather than deferring.
        for r in [
            Region::Band,
            Region::Sidebar,
            Region::Pane,
            Region::Group,
            Region::Split,
            Region::TabGroup,
            Region::Modal,
            // A widget is described, and that is the whole of what separates it
            // from a bespoke here. Both carry a name this crate never reads;
            // only one of them has contents under it that a renderer which does
            // not know the name can still walk.
            Region::Widget { name: "carousel" },
        ] {
            assert!(r.described(), "{r:?} should be describable");
        }
        assert!(!Region::Bespoke { name: "day-plan" }.described());
    }

    #[test]
    fn a_group_contains_a_section_without_claiming_to_be_a_pane() {
        // The whole of why this is a member rather than a `Pane`. A pane is
        // looked into and scrolls; a group is neither, and four groups inside a
        // settings pane described as panes are four wells inside a well.
        assert_eq!(Region::Pane.depth(), Depth::Well);
        assert_eq!(Region::Group.depth(), Depth::Flat);
        assert_ne!(Region::Group, Region::Pane);

        // Described, and it carries no name: a group is a primitive every
        // renderer draws from scratch, which is what separates it from the two
        // members that do carry one.
        assert!(Region::Group.described());
        assert_eq!(Region::Group.name(), None);
    }

    #[test]
    fn a_section_heading_names_a_block_that_now_exists() {
        // `Heading::Section` has said "names a block within the screen" since
        // 0.2.0 and there was no block. The pairing is the point, and it is the
        // reason a group carries no heading of its own: the heading is an
        // ordinary node in the body, and a group without one is legal.
        assert!(Heading::Section.separated());
        assert_eq!(Region::Group.depth(), Depth::Flat);
    }

    #[test]
    fn a_widget_inherits_its_depth_the_way_a_bespoke_does() {
        // Stronger than the bespoke case: a widget is drawn by whichever
        // renderer recognises the name, so a depth chosen here would be this
        // crate deciding a carousel is raised on every host.
        assert_eq!(Region::Widget { name: "carousel" }.depth(), Depth::Flat);
        assert_eq!(Region::Widget { name: "pager" }.depth(), Depth::Flat);
    }

    #[test]
    fn a_name_is_readable_without_asking_which_member_carried_it() {
        // A renderer dispatching on a name wants the string, not the member.
        // Writing that `matches!` at each renderer is how the two drift apart.
        assert_eq!(Region::Widget { name: "carousel" }.name(), Some("carousel"));
        assert_eq!(
            Region::Bespoke { name: "day-plan" }.name(),
            Some("day-plan")
        );

        for r in [
            Region::Band,
            Region::Sidebar,
            Region::Pane,
            Region::Group,
            Region::Split,
            Region::TabGroup,
            Region::Modal,
        ] {
            assert_eq!(r.name(), None, "{r:?} names nothing an app chose");
        }
    }

    #[test]
    fn a_bespoke_region_inherits_its_depth_rather_than_choosing_one() {
        // The app owns the contents, not the placement. An app that wants its
        // timeline in a well frames it in a Pane.
        assert_eq!(Region::Bespoke { name: "day-plan" }.depth(), Depth::Flat);
        assert_eq!(Region::Bespoke { name: "kanban" }.depth(), Depth::Flat);
    }

    #[test]
    fn a_screen_with_a_bespoke_region_is_still_a_whole_screen() {
        // The argument the member exists for: goingson's day-plan has to be
        // routable, or the description covers only the boring screens and the
        // interesting four need a second path beside the router.
        let day_plan = [
            Region::Band,
            Region::Bespoke { name: "day-plan" },
            Region::Sidebar,
        ];
        assert_eq!(day_plan.iter().filter(|r| r.described()).count(), 2);
        assert_eq!(day_plan.iter().filter(|r| !r.described()).count(), 1);
    }

    #[test]
    fn a_secret_field_is_marked_as_one_and_a_hidden_field_is_not_drawn() {
        let secret = Field::new(FieldKind::Secret, "password", "Password");
        assert!(secret.kind.confidential());
        assert!(secret.kind.visible());

        assert!(!FieldKind::Hidden.visible());
        // Nothing else is confidential, or the marker means nothing.
        for k in [
            FieldKind::Text,
            FieldKind::Number,
            FieldKind::Textarea,
            FieldKind::Rich,
            FieldKind::Select,
            FieldKind::Checkbox,
            FieldKind::Hidden,
        ] {
            assert!(!k.confidential(), "{k:?} should not be confidential");
        }

        // Only a checkbox carries its own label.
        assert!(FieldKind::Checkbox.labels_itself());
        assert!(!FieldKind::Text.labels_itself());
    }

    #[test]
    fn a_plain_field_offers_nothing_and_a_select_offers_its_options() {
        let text = Field::new(FieldKind::Text, "title", "Title");
        assert!(text.options.is_empty());
        assert_eq!(text.placeholder, None);

        let sizes = [Choice::plain("small"), Choice::plain("large")];
        let select = Field::select("size", "Size", &sizes);
        assert_eq!(select.kind, FieldKind::Select);
        assert_eq!(select.options.len(), 2);
    }

    #[test]
    fn a_choice_says_what_submits_and_what_is_read_apart() {
        // The whole reason it is two strings. `plain` is the case where they
        // coincide, and it is a shorthand rather than the general shape.
        let plain = Choice::plain("7");
        assert_eq!((plain.value, plain.label), ("7", "7"));

        let spelled = Choice::new("7", "One week");
        assert_ne!(spelled.value, spelled.label);
        assert!(
            spelled.available(),
            "an option is pickable until it says not"
        );
    }

    #[test]
    fn a_candidate_carries_the_line_that_tells_it_from_its_neighbours() {
        // The gap this type was born for: two candidates whose labels read
        // alike, told apart by the second string and by nothing else. The
        // measured site is the MNW tag box, where "Format" is a leaf under
        // audio, software, writing and video.
        let audio = Candidate::new("audio/format", "Format").detailed("Audio");
        let writing = Candidate::new("writing/format", "Format").detailed("Writing");

        assert_eq!(audio.label, writing.label);
        assert_ne!(audio.detail, writing.detail);
        assert_ne!(
            audio, writing,
            "two rows a user cannot tell apart are two rows the type can"
        );
    }

    #[test]
    fn a_candidate_is_read_differently_from_an_option_and_written_the_same() {
        // The ruling's own distinction, held as a test so the two types do not
        // drift back together. Submitting is identical; the second line is the
        // whole of what differs, and it is absent by default because a list of
        // distinct labels wants nothing there.
        let candidate = Candidate::plain("rust");
        assert_eq!((candidate.value, candidate.label), ("rust", "rust"));
        assert_eq!(
            candidate.detail, None,
            "one line unless the route says otherwise"
        );

        let option = Choice::plain("rust");
        assert_eq!(
            (candidate.value, candidate.label),
            (option.value, option.label)
        );
    }

    #[test]
    fn a_radio_asks_the_same_question_as_a_select_and_is_not_the_same_kind() {
        // Both offer a fixed set and both read `options`, so the two
        // constructors differ in exactly one thing. That one thing is the
        // point: a renderer decides whether the alternatives are readable
        // without opening anything, and it can only decide that if the
        // description said which question was asked.
        let styles = [
            Choice::new("copy", "Copy samples in"),
            Choice::new("reference", "Reference in place"),
        ];
        let radio = Field::radio("storage", "Storage style", &styles);
        let select = Field::select("storage", "Storage style", &styles);

        assert_eq!(radio.kind, FieldKind::Radio);
        assert_ne!(radio.kind, select.kind);
        assert_eq!(radio.options, select.options);
        assert_eq!(
            Field {
                kind: select.kind,
                ..radio
            },
            select
        );
    }

    #[test]
    fn an_unavailable_option_cannot_be_silent_about_it() {
        // The whole content of the one-member shape: saying an option is not
        // pickable and saying why are the same act, so the greyed-out-with-no-
        // reason state is unsayable rather than merely discouraged.
        let multi =
            Choice::new("multi", "Multi-sample").unless("Drop a second sample onto the keyboard.");
        assert!(!multi.available());
        assert_eq!(
            multi.unavailable,
            Some("Drop a second sample onto the keyboard.")
        );

        // And the option is still in the list, carrying what it submits, so a
        // renderer draws it rather than the app dropping it.
        assert_eq!(multi.value, "multi");
        assert_eq!(multi.label, "Multi-sample");
    }

    #[test]
    fn an_option_can_say_what_picking_it_means_and_why_it_cannot_be_picked() {
        // `5e21dcfc`. Two different sentences about one option, and an option
        // that has both has said two things: what the tier is, and that it is
        // not available yet. Folding them would be the label-folding this
        // member exists to end.
        let tier = Choice::new("24", "Small Files")
            .detailing("$24/mo. 2GB/file, 100GB total. Fits audio, plugins, binaries.")
            .unless("Sold out while the founder window is open.");

        assert_eq!(
            tier.detail,
            Some("$24/mo. 2GB/file, 100GB total. Fits audio, plugins, binaries.")
        );
        assert_eq!(
            tier.unavailable,
            Some("Sold out while the founder window is open.")
        );
        assert!(!tier.available());

        // Neither is implied by the other, which is what keeps a renderer from
        // reading a detail as a reason: an ordinary option with a second line
        // is still pickable.
        let plain = Choice::new("free", "Free").detailing("No charge. Available to everyone.");
        assert!(plain.available());
        assert_eq!(plain.detail, Some("No charge. Available to everyone."));
        assert_eq!(Choice::new("free", "Free").detail, None);
    }

    #[test]
    fn a_range_carries_both_ends_and_a_validated_number_need_not() {
        // The distinction the kind exists for, asserted rather than only
        // written down: bounds are a rule for one and the control itself for
        // the other.
        let threshold = Field::range("review", "Review above", "0", "1");
        assert_eq!(threshold.kind, FieldKind::Range);
        assert!(threshold.bounded());
        assert_eq!(threshold.min, Some("0"));
        assert_eq!(threshold.max, Some("1"));
        // Granularity is the host's until an app says otherwise.
        assert_eq!(threshold.step, None);

        // goingson's duration: a typed number with a floor, and it must not
        // read as a slider.
        let minutes = Field {
            min: Some("1"),
            ..Field::new(FieldKind::Number, "minutes", "Minutes")
        };
        assert_ne!(minutes.kind, FieldKind::Range);
        assert!(!minutes.bounded(), "one end is a rule, not an extent");
    }

    #[test]
    fn a_range_described_with_one_end_says_so_rather_than_being_refused() {
        // Nothing here enforces the pair, for the reason nothing here enforces
        // `required`: the description states the constraint and the renderer
        // asks. What it must not do is look bounded.
        let half = Field {
            max: Some("1"),
            ..Field::new(FieldKind::Range, "review", "Review above")
        };
        assert!(!half.bounded());
    }

    #[test]
    fn exactly_the_option_taking_kinds_say_so() {
        // The renderers branch on this rather than on a list of their own, so
        // a kind added without a decision here renders its options nowhere.
        assert!(FieldKind::Select.offers_options());
        assert!(FieldKind::Radio.offers_options());
        for kind in [
            FieldKind::Text,
            FieldKind::Secret,
            FieldKind::Number,
            FieldKind::Email,
            FieldKind::Url,
            FieldKind::Tel,
            FieldKind::Range,
            FieldKind::Textarea,
            FieldKind::Rich,
            FieldKind::Checkbox,
            FieldKind::Hidden,
        ] {
            assert!(!kind.offers_options(), "{kind:?} does not offer options");
        }
    }

    #[test]
    fn a_radio_group_takes_a_label_even_though_its_options_carry_their_own() {
        // The near-miss: each option is labelled beside its own button, so a
        // renderer could plausibly read the group as self-labelling and drop
        // the question. Checkbox is the only kind that does that.
        assert!(!FieldKind::Radio.labels_itself());
        assert!(FieldKind::Checkbox.labels_itself());
    }

    #[test]
    fn a_select_with_no_options_is_sayable() {
        // An app whose option list has not loaded has exactly this. Making it
        // unrepresentable would push the state somewhere less visible, and a
        // renderer drawing an empty select reports it on screen.
        let loading = Field::select("project", "Project", &[]);
        assert!(loading.options.is_empty());
    }

    #[test]
    fn the_description_carries_the_question_and_never_the_answer() {
        // The line 0.8.0 drew. Placeholder and options are properties of what
        // is being asked; the current value is what came back, and no field
        // here holds one.
        let f = Field {
            placeholder: Some("yyyy-mm-dd"),
            ..Field::new(FieldKind::Text, "due", "Due")
        };
        assert_eq!(f.placeholder, Some("yyyy-mm-dd"));
        // A placeholder is not a label, and having one does not excuse the
        // field from carrying the other.
        assert_eq!(f.label, "Due");
    }

    #[test]
    fn a_field_reports_its_own_error_state() {
        let mut f = Field::new(FieldKind::Text, "title", "Title");
        assert!(!f.invalid());
        f.error = Some("Required");
        assert!(f.invalid());
    }

    #[test]
    fn columns_drop_by_priority_and_never_by_position() {
        let cols = [
            Column {
                width: Width::Fill,
                priority: Priority::Essential,
                ..Column::new("Title")
            },
            Column {
                width: Width::Fixed,
                priority: Priority::Secondary,
                ..Column::new("Due")
            },
            Column {
                width: Width::Fixed,
                priority: Priority::Optional,
                ..Column::new("Estimate")
            },
        ];

        // Widest: everything survives.
        assert_eq!(
            cols.iter()
                .filter(|c| c.kept_at(Priority::Optional))
                .count(),
            3
        );
        // Narrower: the optional column goes first.
        let kept: Vec<_> = cols
            .iter()
            .filter(|c| c.kept_at(Priority::Secondary))
            .map(|c| c.name)
            .collect();
        assert_eq!(kept, ["Title", "Due"]);
        // Narrowest: only what identifies the row.
        let kept: Vec<_> = cols
            .iter()
            .filter(|c| c.kept_at(Priority::Essential))
            .map(|c| c.name)
            .collect();
        assert_eq!(kept, ["Title"]);
    }

    #[test]
    fn inserting_a_column_does_not_move_what_gets_dropped() {
        // The bug the ordinal form has and this form cannot: goingson hides
        // `nth-child(n+5)` against a seven-column table, so a column inserted
        // anywhere to the left silently hides a different one.
        let before = [
            Column::new("Title"),
            Column {
                width: Width::Fixed,
                priority: Priority::Optional,
                ..Column::new("Estimate")
            },
        ];
        let after = [
            Column::new("Title"),
            Column::new("Project"), // inserted
            Column {
                width: Width::Fixed,
                priority: Priority::Optional,
                ..Column::new("Estimate")
            },
        ];

        fn dropped<'a>(cols: &[Column<'a>]) -> Vec<&'a str> {
            cols.iter()
                .filter(|c| !c.kept_at(Priority::Secondary))
                .map(|c| c.name)
                .collect()
        }
        assert_eq!(dropped(&before), ["Estimate"]);
        assert_eq!(dropped(&after), ["Estimate"]);
    }

    #[test]
    fn an_arrangement_carries_the_tab_group_as_a_modifier() {
        // goingson uses the tab group inside the content region rather than
        // instead of one, so it is not a third arrangement.
        let go = Arrangement::list_detail(true);
        let plain = Arrangement::list_detail(false);
        assert_ne!(go, plain);
        assert_ne!(go, Arrangement::sidebar_content());
    }

    #[test]
    fn a_share_is_a_proportion_and_resolves_the_same_way_everywhere() {
        // The point of the member: a terminal reading columns and a webview
        // reading a grid honour one fact, so two hosts showing one screen agree
        // about its proportions.
        assert_eq!(Share::LIST.as_percent(), 40);
        assert_eq!(Share::LIST.of(100), 40);
        assert_eq!(
            Share::SIDEBAR.of(96),
            24,
            "quasi-tui's 24 columns, said as a quarter"
        );
    }

    #[test]
    fn a_region_never_resolves_to_nothing() {
        // A region the description named should be visible. A zero-width one
        // reads on screen as a region that vanished, which is the hardest kind
        // of bug to find from what is drawn.
        assert_eq!(Share::percent(5).of(1), 1);
        assert_eq!(Share::percent(5).of(0), 1);
    }

    #[test]
    fn a_share_outside_the_range_is_clamped_rather_than_refused() {
        assert_eq!(Share::percent(0), Share::percent(5));
        assert_eq!(Share::percent(200), Share::percent(95));
    }

    #[test]
    fn the_share_rides_on_the_arrangement_that_knows_which_question_it_is() {
        // 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 is being
        // asked.
        assert_eq!(Arrangement::sidebar_content().share(), Some(Share::SIDEBAR));
        assert_eq!(Arrangement::list_detail(false).share(), Some(Share::LIST));
        // One region divides nothing, so there is no share to answer with.
        assert_eq!(Arrangement::Single.share(), None);
        assert_eq!(
            Arrangement::Single.with_share(Share::percent(20)),
            Arrangement::Single
        );

        let narrow = Arrangement::sidebar_content().with_share(Share::percent(20));
        assert_eq!(narrow.share(), Some(Share::percent(20)));
        assert!(matches!(narrow, Arrangement::SidebarContent { .. }));
    }

    #[test]
    fn a_measure_defaults_to_the_one_53_of_69_templates_asked_for() {
        // The default is meaningful: a screen nobody said anything about uses
        // the window it was given.
        assert_eq!(Measure::default(), Measure::Wide);
        assert_eq!(Measure::Reading.as_str(), "reading");
    }

    #[test]
    fn readiness_names_the_state_and_not_the_shimmer() {
        // Two members and no third. If a skeleton ever appears in this enum,
        // the deferral rule has been broken.
        assert_ne!(Readiness::Ready, Readiness::Pending);
    }

    #[test]
    fn a_window_with_no_length_still_answers_what_it_can() {
        // The uncounted case is the common one, not the degenerate one: a query
        // that asked for 51 to learn there were more than 50 knows there are,
        // and not how many.
        let uncounted = Window::new(100, 50);
        assert_eq!(uncounted.index(), Some(2));
        assert_eq!(uncounted.windows(), None);
        assert!(uncounted.has_before());
        // Unknown length cannot rule out more, and offering a way forward that
        // turns out empty is the cheaper mistake.
        assert!(uncounted.has_after());
    }

    #[test]
    fn a_counted_window_knows_where_it_ends() {
        let last = Window::new(350, 50).of(400);
        assert_eq!(last.index(), Some(7));
        assert_eq!(last.windows(), Some(8));
        assert!(last.has_before());
        assert!(!last.has_after());

        let first = Window::new(0, 50).of(400);
        assert!(!first.has_before());
        assert!(first.has_after());
    }

    #[test]
    fn a_window_that_does_not_divide_evenly_rounds_up() {
        // 401 rows in pages of 50 is eight pages and a straggler, which is nine
        // pages. Rounding down would make the last one unreachable.
        assert_eq!(Window::new(0, 50).of(401).windows(), Some(9));
    }

    #[test]
    fn a_zero_count_answers_none_rather_than_dividing() {
        let empty = Window::new(0, 0).of(400);
        assert_eq!(empty.index(), None);
        assert_eq!(empty.windows(), None);
        // And it still clamps rather than panicking.
        assert_eq!(Window::new(900, 0).of(400).clamped().from, 399);
    }

    #[test]
    fn a_window_past_the_end_clamps_inside_rather_than_vanishing() {
        // `Slot::current`'s reasoning, one layer down: a description pointing
        // past the end is a host bug, and answering it by drawing nothing
        // reports a region that vanished.
        assert_eq!(Window::new(900, 50).of(400).clamped().from, 350);
        // Nothing to clamp against when the length is unknown.
        assert_eq!(Window::new(900, 50).clamped().from, 900);
    }

    #[test]
    fn a_carousel_frame_is_a_window_of_one() {
        // The shape a carousel instantiates. Same code as a paged list, which is
        // the whole reason `Window` exists rather than two copies of it.
        let third = Window::frame(2, 5);
        assert_eq!(third.index(), Some(2));
        assert_eq!(third.windows(), Some(5));
        assert!(third.has_before());
        assert!(third.has_after());

        let last = Window::frame(4, 5);
        assert!(!last.has_after());
    }

    #[test]
    fn numbered_pages_read_from_one_and_load_more_has_no_page() {
        // The page number is read aloud, so it is one-based; `Window::index` is
        // the zero-based form for indexing.
        let third = Paging::pages(100, 50).of(400);
        assert_eq!(third.page(), Some(3));
        assert_eq!(third.pages_total(), Some(8));
        assert_eq!(third.total(), Some(400));
        assert!(third.has_previous());
        assert!(third.has_more());

        // Load-more grew a window from the start, so "page 2" would name
        // nothing and the type says so rather than inventing one.
        let grown = Paging::more(150).of(400);
        assert_eq!(grown.page(), None);
        assert_eq!(grown.pages_total(), None);
        assert_eq!(grown.shown(), 150);
        assert!(!grown.has_previous());
        assert!(grown.has_more());
    }

    #[test]
    fn an_uncounted_paging_offers_forward_and_admits_no_total() {
        // What a host that will not pay for a COUNT describes. `None` here is
        // permanent: a total arriving later would widen the text that prints it,
        // which is the reflow "first paint is final paint" forbids.
        let feed = Paging::more(50);
        assert_eq!(feed.total(), None);
        assert_eq!(feed.pages_total(), None);
        assert_eq!(feed.remaining(), None);
        assert!(feed.has_more());
    }

    #[test]
    fn what_is_left_is_derived_and_never_underflows() {
        assert_eq!(Paging::more(150).of(400).remaining(), Some(250));
        assert_eq!(Paging::pages(350, 50).of(400).remaining(), Some(0));
        // A host that overshot its own total gets zero rather than a wrapped
        // usize, which would print as "18446744073709551516 remaining".
        assert_eq!(Paging::more(500).of(400).remaining(), Some(0));
    }

    #[test]
    fn a_fallback_is_authored_and_a_group_cannot_omit_it() {
        // No `Default`. The compiler is what enforces rule 2, so the assertion
        // that matters is one this file cannot write; what it can say is that
        // the four authored answers are distinct and none is privileged.
        let all = [
            Fallback::Wrap,
            Fallback::Stack,
            Fallback::Shed,
            Fallback::Menu,
        ];
        for (i, a) in all.iter().enumerate() {
            for b in &all[i + 1..] {
                assert_ne!(a, b);
            }
        }
    }

    #[test]
    fn shedding_stops_at_essential_whatever_the_group_holds() {
        // Priority is read the same way for a group member as for a column,
        // which is the whole claim of generalising it off `Column`.
        let members = [
            ("tabs", Priority::Essential),
            ("search", Priority::Secondary),
            ("count", Priority::Optional),
        ];
        let kept: Vec<_> = members
            .iter()
            .filter(|(_, p)| *p >= Priority::Essential)
            .map(|(n, _)| *n)
            .collect();
        assert_eq!(kept, ["tabs"]);
    }

    #[test]
    fn a_role_says_what_a_part_is_worth_when_the_run_does_not_fit() {
        // The row still identifies itself after everything droppable has gone,
        // which is the property the ladder exists for.
        assert_eq!(RowPart::Primary.priority(), Priority::Essential);
        // A control is not a fact. Room comes out of what the row says, never
        // out of what it offers.
        assert_eq!(RowPart::Actions.priority(), Priority::Essential);
        assert_eq!(RowPart::Meta.priority(), Priority::Optional);
        assert_eq!(RowPart::Proportion.priority(), Priority::Optional);
        assert_eq!(RowPart::Secondary.priority(), Priority::Secondary);
        // Tokens sit in the middle deliberately: a toned badge is often the
        // most scannable thing in a row, so it does not go first.
        assert_eq!(RowPart::Tokens.priority(), Priority::Secondary);
    }

    #[test]
    fn a_run_is_one_line_unless_the_description_says_two() {
        // The default is what every part did before flows existed, so a
        // description written against the old vocabulary keeps its rendering.
        assert_eq!(Flow::default(), Flow::Tight);
        assert_eq!(Flow::Tight.lines(), 1);
        assert_eq!(Flow::Relaxed.lines(), 2);
    }

    #[test]
    fn an_unknown_flow_reads_as_one_line() {
        // `#[non_exhaustive]`'s cost, taken deliberately. A tier added upstream
        // reaches an old renderer as one line rather than as a build break, and
        // one line is the reading that cannot break a neighbour's layout. The
        // match in `lines` is what this holds; it fails if a new tier is given
        // an arm that returns something unbounded.
        for flow in [Flow::Tight, Flow::Relaxed] {
            assert!((1..=2).contains(&flow.lines()));
        }
    }

    #[test]
    fn an_awaiting_mark_is_indeterminate_until_something_is_measured() {
        // The default is the common case: a call waits, and nothing about it is
        // countable. A determinate bar is the exception and says so.
        assert_eq!(Awaiting::default(), Awaiting::unmeasured());
        assert!(!Awaiting::unmeasured().is_determinate());
        assert!(Awaiting::of(40 * 1024 * 1024).is_determinate());
        assert_eq!(Awaiting::of(7).amount, Some(7));
    }

    // A slider is a fraction and a mapping
    //
    // `Curve` is the one thing in this crate that computes rather than
    // describes, and it does so because four renderers would otherwise each
    // write these two formulas and drift. So the formulas are pinned here.

    /// The bounds of audiofiles' envelope attack, the curve's first consumer.
    const ATTACK: (f64, f64) = (0.001, 5.0);

    #[test]
    fn a_curve_is_linear_with_no_step_until_a_field_says_otherwise() {
        assert_eq!(Curve::default(), Curve::Linear { step: None });
        let plain = Field::range("t", "T", "0", "1");
        assert_eq!(plain.curve, Curve::Linear { step: None });
        assert_eq!(plain.curve.step(), None);
    }

    #[test]
    fn every_curve_carries_its_own_granularity() {
        assert_eq!(Curve::Linear { step: Some("0.01") }.step(), Some("0.01"));
        assert_eq!(
            Curve::Logarithmic {
                step: Some("0.001")
            }
            .step(),
            Some("0.001")
        );
    }

    #[test]
    fn both_ends_of_the_track_are_the_bounds_under_either_curve() {
        // `min` and `max` are `f(0)` and `f(1)`. That is the whole reframe, and
        // it has to hold for a mapping that is not the identity or the bounds
        // have stopped meaning what the field says they mean.
        let (min, max) = ATTACK;
        for curve in [
            Curve::Linear { step: None },
            Curve::Logarithmic { step: None },
        ] {
            assert!((curve.value_at(0.0, min, max) - min).abs() < 1e-12);
            assert!((curve.value_at(1.0, min, max) - max).abs() < 1e-12);
        }
    }

    #[test]
    fn a_linear_midpoint_is_the_average_and_a_ratio_midpoint_is_the_geometric_mean() {
        let (min, max) = ATTACK;
        let linear = Curve::Linear { step: None }.value_at(0.5, min, max);
        assert!((linear - 2.5005).abs() < 1e-9);

        // The reason the envelope is not linear: half way along a log track is
        // 70 ms, and half way along a linear one is 2.5 seconds. Every attack a
        // sampler is actually played with lives below the first.
        let ratio = Curve::Logarithmic { step: None }.value_at(0.5, min, max);
        assert!((ratio - (min * max).sqrt()).abs() < 1e-12);
        assert!(ratio < 0.08);
    }

    #[test]
    fn a_position_and_a_value_round_trip_under_either_curve() {
        let (min, max) = ATTACK;
        for curve in [
            Curve::Linear { step: None },
            Curve::Logarithmic { step: None },
        ] {
            for position in [0.0, 0.1, 0.25, 0.5, 0.75, 0.99, 1.0] {
                let back = curve.position_of(curve.value_at(position, min, max), min, max);
                assert!(
                    (back - position).abs() < 1e-9,
                    "{curve:?} lost {position} (got {back})"
                );
            }
        }
    }

    #[test]
    fn a_ratio_curve_across_zero_is_drawn_linearly_rather_than_refused() {
        // An envelope's sustain is a 0-to-1 level. A constant ratio is
        // undefined there, and the answer is the linear mapping rather than a
        // NaN reaching a renderer that would paint it.
        let curve = Curve::Logarithmic { step: None };
        assert!(!curve.is_ratio(0.0, 1.0));
        assert!((curve.value_at(0.5, 0.0, 1.0) - 0.5).abs() < 1e-12);
        assert!(curve.value_at(0.5, -96.0, -20.0).is_finite());
        assert!(curve.is_ratio(ATTACK.0, ATTACK.1));
    }

    #[test]
    fn a_track_with_no_extent_has_one_value_on_it() {
        for curve in [
            Curve::Linear { step: None },
            Curve::Logarithmic { step: None },
        ] {
            assert!((curve.value_at(0.7, 4.0, 4.0) - 4.0).abs() < f64::EPSILON);
            assert!(curve.position_of(4.0, 4.0, 4.0).abs() < f64::EPSILON);
            // Inverted bounds are the same degenerate answer, not a negative
            // extent a renderer would draw backwards.
            assert!((curve.value_at(0.7, 9.0, 2.0) - 9.0).abs() < f64::EPSILON);
        }
    }

    #[test]
    fn a_position_or_a_value_outside_the_track_is_clamped_to_it() {
        let (min, max) = ATTACK;
        let curve = Curve::Logarithmic { step: None };
        assert!((curve.value_at(-3.0, min, max) - min).abs() < 1e-12);
        assert!((curve.value_at(4.0, min, max) - max).abs() < 1e-12);
        assert!(curve.position_of(0.0, min, max).abs() < 1e-12);
        assert!((curve.position_of(500.0, min, max) - 1.0).abs() < 1e-12);
    }

    #[test]
    fn a_typed_number_keeps_its_own_step_and_a_range_reads_its_curve() {
        // The split the 0.32.0 narrowing is: two granularities that were one
        // member, and the kinds that take them do not overlap.
        let typed = Field {
            step: Some("5"),
            ..Field::new(FieldKind::Number, "port", "Port")
        };
        assert_eq!(typed.step, Some("5"));

        let slid = Field {
            curve: Curve::Logarithmic {
                step: Some("0.001"),
            },
            ..Field::range("attack", "Attack", "0.001", "5")
        };
        assert_eq!(slid.step, None);
        assert_eq!(slid.curve.step(), Some("0.001"));
    }

    #[test]
    fn a_theme_picker_offers_themes_and_no_options() {
        // The substitution hazard the constructor exists against: `options` is
        // right there and reads as if it would work, and a renderer walking it
        // for a theme picker draws an empty control.
        let themes = [
            ThemeChoice::new("goingson", "GoingsOn", ThemeVariant::Light, Contrast::High),
            ThemeChoice::new("dracula", "Dracula", ThemeVariant::Dark, Contrast::Standard),
        ];
        let field = Field::theme("theme", "Theme", &themes);

        assert_eq!(field.kind, FieldKind::Theme);
        assert!(field.kind.offers_themes());
        assert!(!field.kind.offers_options());
        assert_eq!(field.themes.len(), 2);
        assert!(field.options.is_empty());
        assert_eq!(field.follows, None);
    }

    #[test]
    fn following_carries_the_store_s_own_spelling() {
        // Not hardcoded here: the value belongs to the app's config table, and
        // this crate holds no facts about somebody else's store.
        let field =
            Field::theme("theme", "Theme", &[]).following(Choice::new("system", "Follow System"));
        let follow = field.follows.expect("the row was offered");
        assert_eq!(follow.value, "system");
        assert_eq!(follow.label, "Follow System");
    }

    #[test]
    fn a_picker_with_nothing_resolved_is_sayable() {
        // A machine whose theme directories hold nothing. The description is
        // true and a renderer says so on screen rather than in a log, which is
        // `Field::options`' own arrangement.
        let field = Field::theme("theme", "Theme", &[]);
        assert!(field.themes.is_empty());
    }

    #[test]
    fn every_kind_but_theme_offers_no_themes() {
        for kind in [
            FieldKind::Text,
            FieldKind::Select,
            FieldKind::Radio,
            FieldKind::Checkbox,
            FieldKind::File,
            FieldKind::Hidden,
        ] {
            assert!(
                !kind.offers_themes(),
                "{kind:?} does not read Field::themes"
            );
        }
    }

    #[test]
    fn a_contrast_tier_reads_worst_first() {
        // Matches `makeover::ContrastTier`, so an adopter's conversion cannot
        // invert an ordering by accident and a sort agrees across the seam.
        assert!(Contrast::Low < Contrast::Standard);
        assert!(Contrast::Standard < Contrast::High);
    }

    #[test]
    fn the_groups_and_badges_have_one_spelling_each() {
        // The whole argument for these living here: three renderers picking
        // their own is one picker reading three ways.
        assert_eq!(ThemeVariant::Light.heading(), "Light");
        assert_eq!(ThemeVariant::Dark.heading(), "Dark");
        assert_eq!(ThemeVariant::HighContrast.heading(), "High Contrast");

        assert_eq!(ThemeVariant::HighContrast.as_str(), "high-contrast");

        assert_eq!(Contrast::High.badge(), "AA");
        assert_eq!(Contrast::Standard.badge(), "OK");
        assert_eq!(Contrast::Low.badge(), "low");
    }

    #[test]
    fn the_variant_spelling_matches_the_theme_file_s_own() {
        // The seam this enum is duplicated across. `makeover::parse_meta` reads
        // `meta.variant` as one of these three strings; a rename on either side
        // that does not move together silently regroups every picker.
        for (variant, spelling) in [
            (ThemeVariant::Light, "light"),
            (ThemeVariant::Dark, "dark"),
            (ThemeVariant::HighContrast, "high-contrast"),
        ] {
            assert_eq!(variant.as_str(), spelling);
            assert_eq!(variant.to_string(), spelling);
        }
    }
}