makeover_webview/

lib.rs

//! The webview renderer for [`makeover_layout`].
//!
//! <!-- wiki: makeover-webview -->
//!
//! # The renderer that needs no palette
//!
//! `makeover-immediate` and `makeover-tui` both take a `Palette`, because egui
//! and a terminal need an actual colour before they can put anything on
//! screen. A webview does not: `var(--surface-raised)` *is* the late binding,
//! and the browser resolves it against whatever `themes.js` last wrote onto
//! `:root`.
//!
//! So this crate emits text naming intents, and never learns a colour. It is
//! the deferral rule with no adapter in the way, and it is why the webview was
//! always the wrong renderer to derive a vocabulary from: it can express
//! anything, so it never pushes back.
//!
//! # Phase A: the stylesheet
//!
//! This module emits component CSS and no markup, deliberately. GoingsOn has
//! 145 `innerHTML` sites and Balanced Breakfast 175 `createElement` sites, so
//! moving markup is a migration where adopting a generated stylesheet is not.
//! The apps keep every line of their markup and gain the classes.
//!
//! It is not a deletion either, which this header claimed until the measurement
//! came in. Adoption across goingson removed 49 declarations net and *added* 25
//! lines: a rule loses its depth declarations and gains a variant selector next
//! to it, so the file stays the same size. What phase A moves is where depth is
//! defined, not how much CSS exists. Numbers and method in the wiki note under
//! "The deletion test, run".
//!
//! The bevel properties are byte-identical to what both apps already
//! hand-write, which is asserted below.
//!
//! Some of what phase A emits is not a look but the withdrawal of one. A
//! renderer that picks its element from the description inherits that element's
//! user-agent chrome, and [`reset`] is where a primitive says which parts of it
//! were never asked for.
//!
//! # Phase B: the markup, one description at a time
//!
//! [`form`] renders [`makeover_layout::Field`], which is the half of phase B
//! whose description is settled. It emits strings, because both apps
//! interpolate their fields into larger string-built forms and returning nodes
//! would rewrite those too. It owns its own escaping, on the reasoning in that
//! module: a Rust encoder can cover element text and attribute values with one
//! function, where the apps need four and have to choose correctly at every
//! call site.
//!
//! [`facet`] renders `makeover_layout::Facet`: a dimension a set is narrowed by,
//! and the one phase-B emitter whose markup an app is not keeping, because the
//! markup it replaces was two mechanisms rather than one. A tag's selection and
//! a tag's browse position were separate state on MNW's discover page, which is
//! why every filter row there carries a tick box *and* a chevron; one gesture
//! doing both is what lets the second one go.
//!
//! [`list`] is the other half: column tracks, the narrowing rules, and the cell
//! containers a row is made of. It stops at the cell boundary and does not
//! render what goes inside one, on the reasoning in that module. So phase B is
//! now the frame around content in both directions, and what an app still owns
//! is the content itself.
//!
//! # What phase A settled, and what it costs
//!
//! Measured against goingson's `styles.css` rather than against a component
//! list: `.btn`, `.card` and `.tag, .badge` each hand-write the same
//! composition, so three quarters of phase A is one rule with several names.
//!
//! Two of the four decisions change how goingson looks, and adoption should
//! not be described as a pure deletion:
//!
//! - **Pressed carries its fill.** [`interactive_rules`] emits
//!   [`Depth::pressed`] whole. goingson presses to `--surface-sunken` today and
//!   will press to `--surface-well`, and hovers to `--surface-overlay` today
//!   and will hover to `--hover-surface`. Since `surface-well` inverts by theme
//!   where `surface-sunken` does not, a dark theme presses *lighter* than it
//!   hovers. That falls out of `makeover`'s own derivation, which says outright
//!   that `surface-sunken` cannot serve as a well, so if it reads wrong the
//!   answer is there and not here.
//! - **Badges go flat.** See [`token_rules`].
//!
//! The other two: the progress trough is renderer-local and the scrollbar
//! track was dropped ([`component_rules`]), and no class prefix ships by
//! default, so adoption means deleting the app's hand-written rule in the same
//! commit that adds the generated one. `.card`, `.badge` and the tab classes
//! all already exist in goingson, and while both rules exist the cascade order
//! decides which wins. That is the one real risk in adopting this, and it is
//! why the migration lands per component rather than in one commit.
//!
//! # Interaction states
//!
//! [`interactive_rules`] emits four states, in emission order, and the order is
//! load-bearing: they are all specificity (0,2,0), so disabled beats hover by
//! coming last and by nothing else. Nothing here reaches for `:not(:disabled)`,
//! which would raise a selector this crate wraps in its own layer.
//!
//! Emitting the states here is what keeps an app from completing the primitive
//! from outside, by out-specifying a rule it does not own. Those overrides are
//! also what breaks under cascade layers: an app that declares `@layer` puts
//! its own rules in a named layer, and unlayered declarations outrank every
//! named layer regardless of specificity.
//!
//! Hover sits inside a capability query. `makeover-touch` answers whether a
//! fingertip has hover and `makeover-geometry` spells the condition; this crate
//! asks and does not decide, so no app has to take the hover state back on
//! touch.
//!
//! # The layer contract
//!
//! [`stylesheet`] emits into the `makeover` cascade layer ([`CSS_LAYER`], which
//! lives in `makeover-geometry` because that is the one crate every CSS emitter
//! in the family already depends on). `makeover-geometry` does the same for
//! `geometry.css`.
//!
//! The cascade resolves origin and importance, then layer, then specificity,
//! then source order, and **unlayered normal declarations outrank every named
//! layer**. An unlayered generated file therefore beats every rule an app owns,
//! regardless of specificity and regardless of loading last. Nothing errors when
//! that happens: the CSS is valid, the minifier is happy, and buttons and badges
//! look subtly wrong. The layer belongs here rather than in each app, because an
//! app cannot fix it from its own stylesheet: the fix is to layer the file it
//! does not own.
//!
//! An app should declare the order once, or the layer's position is decided by
//! whichever generated file the browser happens to see first:
//!
//! ```css
//! @layer makeover, base, components, responsive;
//! ```
//!
//! [`in_css_layer`] is re-exported for an app that assembles its own stylesheet
//! from this crate's pieces: rules an app generates from them are as generated
//! as the ones here, so they belong in the same layer and this crate cannot put
//! them there on the app's behalf.
//!
//! # Suggestions
//!
//! `Outcome::Suggestions` carries `Candidate` rather than `Choice`, and a
//! candidate has no `unavailable`: a suggestion that cannot be picked is a row
//! a route should not have offered. What it has instead is a `detail`, the line
//! that tells it from a row reading the same, and it is drawn in
//! `--content-muted` rather than in the disabled token. A detail orients rather
//! than refuses, and every other secondary line in this crate reads the same
//! way. The class is `.form-suggestion-detail`.
//!
//! # An interval is one question with two ends
//!
//! [`makeover_layout::FieldKind::Interval`] emits a `role="group"` named by the
//! field's label, holding one `<input type="number">` per end.
//!
//! - **The group carries the error and the descriptions**, on the split
//!   [`makeover_layout::FieldKind::Radio`] already uses here: what is wrong is
//!   the answer, and a crossed interval is not the fault of either end.
//! - **Both boxes take the whole extent.** `min`, `max` and `step` describe the
//!   axis, so they are written twice. The crossing rule is not emitted, because
//!   HTML has no attribute for it and the description does not carry it: it
//!   comes back as an error on the group, like every other refusal.
//! - **Which end is which is `aria-label` and nothing more.** The description
//!   states direction structurally, by which member holds which name, and never
//!   in words. Visible Min and Max captions are a page's own and reach the
//!   group through [`form::Filling::trailing`].
//!
//! [`form::Value::Between`] is the second value. A separator inside one string
//! would make this crate the owner of a delimiter that either end could contain.
//!
//! # A number's unit is adjacent text
//!
//! HTML has no unit attribute and inventing one would be markup nothing reads,
//! so `Field::unit` is a `<span>` after the control. It is named in
//! `aria-describedby` rather than left as decoration, because a number and what
//! it is measured in are one fact and reading the first without the second is
//! reading it wrong. What that buys is a unit a consumer can read back rather
//! than a suffix on a label it would have to parse.
//!
//! # A curve this renderer can carry, and one it declines
//!
//! A range takes its granularity from the curve (`Field::curve.step()`), every
//! other kind keeps `Field::step`, and `Curve::Linear` emits a plain range.
//!
//! **A constant-ratio curve emits a linear track, and that is the answer, not a
//! debt.** HTML has no logarithmic range input, so a described screen asking
//! for one is asking the browser for something it does not have, the same class
//! of request as [`makeover_layout::FieldKind::Date`] on a host with no
//! calendar. The renderer answers with the nearest control the host really
//! offers and keeps every fact that survives the translation: the extent, the
//! granularity, and the value's own units. What does not survive is resolution
//! at the small end. The value submitted is still a value in the field's own
//! units, which is what every handler on this path reads.
//!
//! The alternatives are worse in the specific way this stack exists to avoid.
//! Shipping JS that maps thumb position to value puts app code back in the
//! renderer. Changing what the control submits from a value to a fraction moves
//! the mapping to whoever reads the form, and a server reading these forms with
//! its own handlers would take a fraction where a value is expected, silently.
//!
//! When this reopens: the day a described screen on the webview path asks for a
//! non-linear range. The answer then is mapping in `quasi-router`, where one
//! implementation serves every host, not JS here.
//!
//! # A markdown field gets a preview
//!
//! A [`makeover_layout::FieldKind::Rich`] field is marked
//! `data-format="markdown"`, and [`form::editor_rules`] is what spends that
//! mark. The Write/Preview pair is a segmented control, so it takes the depth,
//! the focus ring and the chosen state from rules that already exist; the
//! preview pane is a well, because it stands where the control stood. Both are
//! gated on the attribute rather than on a class, which is what the attribute is
//! for. A permission taken and not spent turns every conversion into a
//! regression.
//!
//! **This crate renders no markdown.** The pane arrives empty and is filled by
//! whatever binds the editor, which is where the host's sanitiser already is. A
//! converter here would move that guarantee into a crate with no view of the
//! host's content-security posture.
//!
//! # Ranges, ghost text, and an option that cannot be picked
//!
//! - `FieldKind::Range` emits `<input type="range">`, and `Field::step` emits
//!   `step`. The step is emitted only when the description carries one: the
//!   browser's own default is `step="1"`, which is what a description means by
//!   saying nothing, and is also what turns a 0-to-1 threshold into a
//!   two-position control.
//! - A select with nothing chosen emits a disabled, selected, valueless first
//!   option carrying `Field::placeholder`. HTML has no placeholder attribute on
//!   `<select>`; this is the idiom, and `required` keeps working through it
//!   because the option's value is empty.
//! - `Choice::unavailable` emits `disabled` plus the reason. Where it goes
//!   differs by control and the difference is forced: a radio group gets a
//!   `.form-option-reason` span beside the label, and a `<select>` option has
//!   room for no element at all, so the reason runs into its text.
//! - `Choice::detail` takes the same split for the same reason: a
//!   `.form-option-detail` span in a radio group, run into the text of a
//!   `<select>`'s option. An option carrying both reads what it is before why it
//!   cannot be picked.
//!
//! # A cell says what it holds
//!
//! [`CellPart`](makeover_layout::CellPart) names the four things a cell holds,
//! and [`table_rules`] turns them into `.cell-value`, `.cell-tokens`,
//! `.cell-actions` and `.cell-link`. The value and the link take a colour: a
//! token carries its own tone and an action is a control rather than text.
//!
//! The colour goes on `.cell-value` rather than on `.cell`. On the container it
//! cascades into the parts that are not text, and a control in a cell is painted
//! as text, which is the drift
//! [`RowPart::intent`](makeover_layout::RowPart) prevents for list rows.
//!
//! [`list::Cell::part`] is `Option<CellPart>` and never `Option<RowPart>`: the
//! two answer different questions, and only one of them is about a cell.
//!
//! # A table narrows itself
//!
//! A table a description produced knows its columns at render time, so no rule
//! can be written per table: it would have to travel with the markup, as a
//! `<style>` element that needs `style-src 'unsafe-inline'` or in a head an htmx
//! fragment swap does not carry. [`table_rules`] lays every table out as flex
//! rows instead, each column starting at its declared floor and giving up room
//! by its [`Priority`](makeover_layout::Priority), so the browser narrows a
//! table at the width its floors add up to. [`list::column_classes`] is what
//! puts the column's classes on a cell, and every cell's contents go in
//! [`list::CELL_IN`]. **A header row emitted by a renderer's own code has to do
//! both too**, or the header and the body disagree about which column just
//! closed and how wide the rest are.
//!
//! `.button` takes the four tones as colour, off `data-tone`, the way the badge
//! does, so a destructive button has somewhere for its tone to land. A list is
//! reset rather than left as a bulleted list.
//!
//! `RowPart::revealed_on_hover` is not honoured. Hiding a row's actions until
//! hover hides them from pointer users alone, who are the ones scanning a list
//! to learn what can be done to a row, and every escape the rule grows
//! (`focus-within` for the keyboard, a capability gate for a fingertip) is a
//! report that hiding was wrong for somebody.
//!
//! # The depth classes are not controls
//!
//! `.raised` is a statement about shape and carries no interactive set, so the
//! vocabulary has a raised surface that is merely an object. An app that wants
//! one does not have to take a control class and cancel the control half.
//!
//! `.button` is the same depth *and* a control, and takes its states from
//! [`surface_rules`], which is where a state belongs: on the thing that claims
//! to answer a pointer. `.card` is a raised object, and it answers a pointer
//! only when the element it is written on is a control -- `a`, `button`,
//! `label`, or anything carrying `data-act` -- so one name serves the card
//! that is read and the card that is pressed.
//!
//! # Substitution, three ways
//!
//! A theme with no `surface-well` is answered differently by each renderer,
//! which is why substitution belongs to a renderer and not to the description:
//!
//! - `makeover-immediate` substitutes the page in Rust.
//! - `makeover-tui` refuses to substitute and draws an edge instead, because a
//!   terminal would quantise the two together.
//! - here, CSS already has the mechanism: `var(--surface-well,
//!   var(--surface-page))` falls back in the browser, and nothing in Rust
//!   decides anything.

#![forbid(unsafe_code)]

pub mod chart;
pub mod facet;
pub mod figure;
pub mod form;
pub mod list;
pub mod meter;
pub mod placeholder;
pub mod reset;
pub mod vocabulary;

mod table;
use table::table_rules;

/// A render of every emitter, scraped for the classes it wrote.
///
/// Test-only, and the guard behind [`vocabulary::names`]. See the module's own
/// header for why the check renders rather than reads the source.
#[cfg(test)]
mod corpus;

use crate::list::{cell_part_class, part_class};
use crate::reset::{Chrome, Reset};
use makeover_geometry::{Density, SizeClass};
// Re-exported rather than redefined. An app assembling its own stylesheet out
// of this crate's pieces needs the same layer name, and most such apps depend
// on this crate and not on `makeover-geometry` directly.
pub use makeover_geometry::{CSS_LAYER, in_css_layer};

/// This crate's version, as the generated stylesheet reports it.
///
/// A consumer whose lockfile still pins an old `makeover-webview` gets a
/// well-formed sheet with components missing and no error anywhere, so the
/// emitter has to name itself in what it writes. Read by
/// `makeover_build::layout_css` through [`stylesheet`].
pub const VERSION: &str = env!("CARGO_PKG_VERSION");
use makeover_layout::{
    Bevel, CellPart, Depth, Fallback, Fill, Flow, Intent, RowPart, Selector, Sort, State, Token,
    Tone,
};
use makeover_touch::Affordance;
use std::fmt::Write as _;

/// How the emitted CSS is shaped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Emit {
    /// Bevel thickness, as a CSS length.
    ///
    /// A value, so it arrives from the caller: border widths belong to
    /// `makeover-geometry` and will come from there once it carries them.
    pub border_width: &'static str,
    /// Focus ring thickness, as a CSS length.
    ///
    /// Separate from [`border_width`](Self::border_width), and never derived
    /// from it: a bevel and a focus indicator answer different questions, and
    /// only one of them has to be noticed from across a desk.
    ///
    /// The default is the measured consensus rather than a new opinion. Every
    /// consumer had already written its own ring and all three chose at least
    /// 2px: the MNW server 2px across 10 rules, Balanced Breakfast 2px,
    /// goingson 2px on three rules and 3px on the one covering twelve
    /// selectors. The design system was the only thing in the tree saying 1px.
    pub focus_width: &'static str,
    /// The smallest a pointer target may be drawn, as a CSS length.
    ///
    /// A value for [`border_width`](Self::border_width)'s reason, and it goes
    /// to `makeover-geometry` on the same trip: a floor is a size, and this
    /// crate names no sizes of its own.
    ///
    /// The default is WCAG 2.2's target minimum. It is an absolute rather than
    /// a step off the geometry base, and that is deliberate on two counts: a
    /// floor that scales with the reader's root size is not a floor, and the
    /// touch density opens the gaps *between* targets rather than licensing a
    /// smaller one for a pointer.
    pub target_min: &'static str,
    /// Prefix for emitted class names, without the leading dot.
    pub class_prefix: &'static str,
    /// What marks a compulsory field, appended to its label.
    ///
    /// `makeover-tui`'s `PieceStyle::required_marker` and
    /// `makeover-immediate`'s `FieldStyle::required_marker`, said here for the
    /// third renderer, with their default. A knob for their reason: it is the
    /// one piece of *copy* this crate emits, and copy is not a renderer's
    /// call.
    ///
    /// This crate was the outlier. `Field::required` reached it as the HTML
    /// attribute and nothing else, so a browser refused an empty submit and
    /// the screen never said which fields would do that, while both sibling
    /// renderers had marked the label since they were written.
    ///
    /// # Why it is hidden from the accessibility tree here and nowhere else
    ///
    /// The control already carries `required`, which a screen reader
    /// announces. A marker read out beside it is the same fact twice, so the
    /// span is `aria-hidden`. The other two renderers have no such attribute
    /// to lean on, which is why the marker is part of the label string there
    /// and an element here.
    pub required_marker: &'static str,
}

impl Default for Emit {
    fn default() -> Self {
        Self {
            border_width: "1px",
            focus_width: "2px",
            target_min: "24px",
            class_prefix: "",
            required_marker: "*",
        }
    }
}

/// A string as CSS escapes, for a `content` value.
///
/// `\u{25B2}` becomes `\25B2`. Emitted escaped rather than literally so the
/// stylesheet is ASCII whatever the description spells: a `content` string is
/// read by whatever encoding the consumer serves the file as, and a caret that
/// depends on that is a caret that works on one machine.
///
/// Terminated by the closing quote at every site here. A CSS hex escape takes
/// up to six digits and ends at the first character that cannot be one, so an
/// escape followed by more text would need a space that these do not.
fn css_escape(text: &str) -> String {
    text.chars().fold(String::new(), |mut out, c| {
        let _ = write!(out, "\\{:X}", c as u32);
        out
    })
}

/// The CSS custom property holding a bevel's composition.
#[must_use]
pub fn bevel_var(bevel: Bevel) -> &'static str {
    match bevel {
        Bevel::Raised => "--bevel-raised",
        Bevel::Inset => "--bevel-inset",
        Bevel::RaisedOpen => "--bevel-raised-open",
        // An edge added to the description since this renderer was last
        // built. The raised edge rather than no edge: a control with no
        // box-shadow reads as flat, which is a different claim, where a
        // closed edge is at worst the same shape drawn one run too many.
        _ => "--bevel-raised",
    }
}

/// A `var()` reference to a fill intent, with the browser's own fallback where
/// the intent may be absent.
///
/// The fallback is CSS syntax, not a decision made here. That is the whole
/// difference between this renderer and the other two.
#[must_use]
pub fn fill_var(fill: Fill) -> String {
    match fill {
        Fill::Well => format!("var(--{}, var(--{}))", fill.token(), Fill::Page.token()),
        other => format!("var(--{})", other.token()),
    }
}

/// The two-tone edge as a `box-shadow` value.
///
/// Two inset shadows, one per corner pair: the light one offset down and
/// right so it lands on the top and left edges, the dark one the other way.
/// The same assignment `makeover-immediate` draws with polylines and
/// `makeover-tui` draws with box-drawing characters.
#[must_use]
pub fn bevel_shadow(bevel: Bevel, opts: &Emit) -> String {
    let (top_left, bottom_right) = bevel.edges();
    let w = opts.border_width;
    // The shaded run's vertical offset is what puts it on the bottom edge. At
    // zero it lands on the right edge alone, which is the open bevel: three
    // sides drawn and the fourth left for the surface below to continue
    // through. Same two shadows either way, so nothing downstream has to know
    // which it got.
    // The sign belongs to the value rather than to the template: writing
    // `-{down}` against a zero emits `-0`, which is a length no stylesheet
    // should carry even where a parser accepts it.
    let down = if bevel.draws_bottom() {
        format!("-{w}")
    } else {
        "0".to_string()
    };
    format!(
        "inset {w} {w} 0 var(--{}), inset -{w} {down} 0 var(--{})",
        top_left.token(),
        bottom_right.token()
    )
}

/// The custom properties both bevels resolve through.
///
/// Emitted as properties rather than inlined into every rule because that is
/// what the apps already do, and because a consumer that wants the edge
/// without the fill reads the property directly.
#[must_use]
pub fn bevel_properties(opts: &Emit) -> String {
    let mut css = String::new();
    for bevel in [Bevel::Raised, Bevel::Inset, Bevel::RaisedOpen] {
        let _ = writeln!(
            css,
            "    {}: {};",
            bevel_var(bevel),
            bevel_shadow(bevel, opts)
        );
    }
    css.push_str(ELEVATION_PROPERTY);
    css
}

/// The cast shadow of a surface that floats over the page.
///
/// Composed here for the reason the bevel pair is: `makeover` derives the tone,
/// this crate owns the geometry, and neither has to know the other's numbers.
///
/// **Only for a surface that overlays the page.** A menu, a toast, a popover, a
/// dropdown. A surface *in* the page takes `.raised` and its bevel, and a rule
/// that reaches for this on a card or a plate has renamed a literal rather than
/// replaced it.
///
/// Two lengths rather than one, because a single blur reads as a smudge at
/// plate size and as a halo at menu size. The offset is small and downward: a
/// Platinum-era menu sits just off the page rather than hovering above it.
const ELEVATION_PROPERTY: &str =
    "    --elevation-overlay: 0 2px 4px var(--elevation), 0 8px 24px var(--elevation);\n";

/// The class name for a depth.
#[must_use]
pub fn depth_class(depth: Depth, opts: &Emit) -> Option<String> {
    let name = match depth {
        Depth::Flat => return None,
        Depth::Raised => "raised",
        Depth::Well => "well",
        Depth::Sunken => "sunken",
        // A depth added to the description since this renderer was last
        // built. No class, on the same footing as Flat: emitting a name
        // whose rule body we cannot write would put a class in the markup
        // that the stylesheet never defines.
        _ => return None,
    };
    Some(format!("{}{name}", opts.class_prefix))
}

/// A prefixed class name.
///
/// Public, for the renderers that emit markup this crate does not. A screen
/// renderer writing `class="row"` has to prefix it the way the stylesheet half
/// does, or a prefixed app gets rules matching everything except the elements
/// that renderer wrote, and the failure is invisible: the CSS stays valid and
/// one element is unstyled. Call this rather than copying it.
#[must_use]
pub fn class(name: &str, opts: &Emit) -> String {
    let mut out = String::with_capacity(opts.class_prefix.len() + name.len());
    push_class(&mut out, name, opts);
    out
}

/// A prefixed class name, written into a buffer the caller already has.
///
/// The form the emitters use, and the reason it exists is [`escape_into`]'s:
/// putting every class on every element through a `format!` allocates even in
/// the default case, where the prefix is empty and the answer is the argument.
/// A described table row carries roughly eighty transient allocations that way,
/// and this and the escaper are most of them.
///
/// [`class`] stays for callers holding a name rather than a buffer.
///
/// [`escape_into`]: crate::form::escape_into
pub fn push_class(out: &mut String, name: &str, opts: &Emit) {
    out.push_str(opts.class_prefix);
    out.push_str(name);
}

/// The attribute an element's custom properties ride in, instead of `style`.
///
/// A number this crate hands the stylesheet -- a bar's value and its axis, a
/// facet's depth, a meter's fill -- is a custom property the rules divide or
/// multiply. It used to be written as `style="--value: 4210"`, and a
/// `style-src` without `'unsafe-inline'` refuses every style attribute, so a
/// page under that policy drew every chart flat. The same text in this
/// attribute is data a policy does not police, and the host's script sets each
/// property through the CSSOM, which the policy allows: quasi-webview's
/// `VARS_JS`.
///
/// The value is `--name: value` pairs separated by `;`, the declaration syntax
/// the `style` attribute already had, so the numbers still reach the markup as
/// themselves. That is the property the residual seam needs: see the
/// [`chart`](crate::chart) module header.
///
/// Only custom properties. A script that applied any declaration from markup
/// would hand the policy's refusal straight back.
pub const VARS_ATTR: &str = "data-vars";

/// The class an option of a selector carries, which is what the rules key off.
///
/// Named for the option and not for the group: [`selector_rules`] styles the
/// thing that gets picked, so `Selector::Tabs` is `tab` and not `tabs`. The
/// distinction is not pedantry. quasi-webview spelled these `tabs`, `segmented`
/// and `option`, put `toggle` on the wrapping element rather than on the
/// buttons inside it, and every described selector in that renderer came out
/// with no depth, no focus ring and no chosen state, while the toggle group got
/// a bevel meant for its buttons.
///
/// The chosen option additionally carries `chosen`, the same way a latched chip
/// carries `latched`. That name is this crate's too; there is no reason for a
/// caller to spell it, and [`selector_rules`] is where it is written down.
#[must_use]
pub fn option_class(selector: Selector) -> &'static str {
    match selector {
        Selector::Tabs => "tab",
        Selector::Segmented => "segment",
        Selector::Toggle => "toggle",
    }
}

/// The fill and edge declarations for a depth, as a rule body.
///
/// Empty for [`Depth::Flat`], which has neither and inherits what it sits on.
/// Callers lean on the emptiness to skip the rule rather than emit a class that
/// sets nothing: a class that sets no properties is a class that means "I
/// thought about this", which is what comments are for.
///
/// The two halves are emitted independently because [`Depth::Sunken`] has a
/// fill and no bevel. Requiring both would silently drop the fill for exactly
/// that case. Independent does not
/// mean unpaired: both halves still come off one `Depth`, so they cannot
/// disagree about what the region is.
#[must_use]
pub fn depth_declarations(depth: Depth) -> String {
    let mut css = String::new();
    if let Some(fill) = depth.fill() {
        let _ = writeln!(css, "    background: {};", fill_var(fill));
    }
    if let Some(bevel) = depth.bevel() {
        let _ = writeln!(css, "    box-shadow: var({});", bevel_var(bevel));
    }
    css
}

/// One rule giving a selector a depth, or nothing when the depth declares
/// nothing.
#[must_use]
pub fn depth_rule(selector: &str, depth: Depth) -> String {
    let body = depth_declarations(depth);
    if body.is_empty() {
        return String::new();
    }
    format!(".{selector} {{\n{body}}}\n")
}

/// The media condition a hover rule has to sit inside, or `None` if hover is
/// unconditional.
///
/// Two crates answer this and neither answer is made here. `makeover-touch`
/// owns *whether* hover exists at a density, and `makeover-geometry` owns how
/// that capability is spelled as a media condition. Asking both is what stops
/// this renderer minting a third opinion, which is what all three apps did:
/// goingson sniffed the user agent, Balanced Breakfast used `(hover: none)`
/// alone, and the MNW server had no gate at all.
///
/// [`SizeClass`] is required by [`Affordance::available`] and ignored by this
/// member, which reports as much through `reads_size`. Passing Compact is not
/// a claim about width; the test below pins that every class agrees.
fn hover_condition() -> Option<&'static str> {
    if Affordance::Hover.available(Density::Touch, SizeClass::Compact) {
        // A fingertip grew a hover state. Nothing to gate, and this renderer
        // should not invent a reason to gate anyway.
        None
    } else {
        Some(Density::Pointer.media_condition())
    }
}

/// Put a rule inside a media query, or leave it alone.
fn gated(condition: Option<&str>, rule: &str) -> String {
    let Some(condition) = condition else {
        return rule.to_string();
    };
    let mut css = format!("@media {condition} {{\n");
    for line in rule.lines() {
        // Blank lines stay blank. Indenting one leaves trailing whitespace,
        // which is the sort of thing a formatter later reverts and calls a diff.
        if line.is_empty() {
            css.push('\n');
        } else {
            let _ = writeln!(css, "    {line}");
        }
    }
    css.push_str("}\n");
    css
}

/// The keyboard focus ring, placed by the depth it lands on.
///
/// This is the webview's **focus ring** and nothing more. **Reach** and
/// **focus** are both the browser's — the document decides what is reachable
/// and `:focus-visible` decides which reached thing wears the ring — and no
/// description states either. The three terms are defined once in
/// `makeover_layout`'s crate header, "Reach, focus and the focus ring".
///
/// One ring for the whole system, because a focus ring's job is to be
/// recognised and three apps having three of them is the failure. What varies
/// is where it sits, and that comes off [`Depth`] rather than off a per-
/// component choice: a well takes the ring inside its own edge, and anything
/// standing proud of the page takes it outside.
///
/// `outline` rather than the composed `box-shadow` the invalid-field ring at
/// [`field_rules`] uses, and deliberately the one place the two rings are built
/// differently. A `box-shadow` ring has to restate the bevel beside it, because
/// `box-shadow` is not additive and a lone ring silently drops the well out
/// from under the element. That restatement is a second copy of the depth,
/// living in a different function from the first, and it is exactly the
/// duplication `Depth` exists to prevent. `outline` occupies its own property,
/// so the bevel survives untouched and there is nothing to keep in agreement.
/// They render the same: both are a flush ring one border-width wide.
#[must_use]
pub fn focus_rule(selector: &str, depth: Depth, opts: &Emit) -> String {
    let w = opts.focus_width;
    // Same magnitude either way, and only the sign comes off the depth. Both
    // values are what the consumers had already converged on independently:
    // 2px out is what all three wrote, and 2px in is the MNW server's own
    // answer for the one inset ring it had.
    let offset = match depth.bevel() {
        // Inside the well, clear of its edge rather than painted over it.
        Some(Bevel::Inset) => format!("calc(-1 * {w})"),
        // Raised, or no edge at all. Outside, standing off by its own width.
        _ => w.to_string(),
    };
    // The token by name. It is `makeover`'s, derived from the action colour,
    // and reaching it through a description member was a second path to the
    // same variable for as long as one existed.
    format!(
        ".{selector}:focus-visible {{\n    outline: {w} solid var(--focus-ring);\n    outline-offset: {offset};\n}}\n"
    )
}

/// A rest depth said out loud on both axes, for a rule that has to beat the
/// states above it.
///
/// [`depth_declarations`] states an axis only when the depth has something to
/// say about it, which is right for a rest rule: a [`Depth::Flat`] region
/// inherits what it sits on, and asserting `background: none` there would be
/// the difference between level-with and painted-transparent. It is wrong for
/// a rule whose whole job is to take a state back. An axis left unstated is an
/// axis the state above keeps, so `Flat` re-asserted nothing at all and a
/// disabled control kept whatever hover had given it.
///
/// So the axes the depth is silent on are withdrawn rather than skipped, and
/// the withdrawal is spelled by [`reset`] rather than here, so a disabled
/// control and a flat one say the same words. Reaches further than the fill:
/// [`Depth::Sunken`] and [`Depth::Overlay`] have no bevel either, and the
/// pressed rule above hands out an inset one.
fn rest_declarations(depth: Depth) -> String {
    let mut css = String::new();
    match depth.fill() {
        Some(fill) => {
            let _ = writeln!(css, "    background: {};", fill_var(fill));
        }
        None => css.push_str(&Reset::NOTHING.and(Chrome::Fill).declarations()),
    }
    match depth.bevel() {
        Some(bevel) => {
            let _ = writeln!(css, "    box-shadow: var({});", bevel_var(bevel));
        }
        None => css.push_str(&Reset::NOTHING.and(Chrome::Shadow).declarations()),
    }
    css
}

/// Present, visible, and not answering.
///
/// Matches the ARIA attribute as well as the pseudo-class, because `:disabled`
/// only matches form elements and half the things this crate emits are not
/// one: a `div` carrying `.chip` or `.tab` can never be `:disabled`. Keying on
/// the accessible state is the pattern [`field_rules`] already establishes for
/// `aria-invalid`, on the reasoning that one fact read by both the styling and
/// the accessibility tree cannot drift from itself.
///
/// The rest depth is re-asserted rather than assumed, because this rule has to
/// beat the hover and pressed rules above it. It does that on source order at
/// equal specificity, not by out-specifying them: every rule this function's
/// caller emits is (0,2,0), and adding a `:not(:disabled)` anywhere would raise
/// one of them and have to be unpicked when this output moves inside its own
/// cascade layer.
///
/// Re-asserted on **both** axes, through [`rest_declarations`].
/// `depth_declarations` alone is empty for [`Depth::Flat`], so a flat control
/// would win the contest with nothing to say and keep the hover surface
/// underneath a control that had stopped answering.
#[must_use]
pub fn disabled_rule(selector: &str, depth: Depth) -> String {
    format!(
        ".{selector}:disabled,\n.{selector}[aria-disabled=\"true\"] {{\n{}    color: var(--{});\n    cursor: not-allowed;\n}}\n",
        rest_declarations(depth),
        State::Disabled.token()
    )
}

/// Every state a selector that answers a click implies: hover, pressed, focus
/// and disabled, in that order.
///
/// Order is the whole cascade mechanism here. All four selectors are
/// specificity (0,2,0), so disabled wins over hover and pressed by coming last
/// and by nothing else.
///
/// Pressed emits [`Depth::pressed`] in full, fill and edge together. Emitting
/// only the edge is what left goingson hand-writing `background:
/// var(--surface-sunken)` on three separate rules, and a fill that does not
/// travel with its edge is precisely the disagreement `Depth` exists to make
/// unrepresentable. So the pressed fill comes from the description
/// (`--surface-well`) rather than from whatever each app reached for.
///
/// Hover has no member in the description and is renderer policy: a terminal
/// and an immediate-mode painter have no hover to express. It resolves against
/// `--hover-surface`, which `makeover` already derives and which nothing
/// consumed until now. What it *is* gated on is capability, via
/// [`hover_condition`]. Before that gate existed the apps each wrote their own:
/// goingson's section 60 exists solely to take back the hover state this
/// function had just handed it, by out-specifying a rule it does not own.
///
/// `depth` is the selector's **rest** depth, used to place the focus ring and
/// to restore the surface under a disabled control. The pressed rule keeps
/// inverting from [`Depth::Raised`] regardless: a tab's unchosen depth is
/// [`Depth::Sunken`], and `Sunken.pressed()` is `Sunken`, so deriving the press
/// from the rest depth would leave a tab with no press at all.
#[must_use]
pub fn interactive_rules(selector: &str, depth: Depth, opts: &Emit) -> String {
    let mut css = gated(
        hover_condition(),
        &format!(".{selector}:hover {{\n    background: var(--hover-surface);\n}}\n"),
    );
    css.push_str(&depth_rule(
        &format!("{selector}:active"),
        Depth::Raised.pressed(),
    ));
    css.push_str(&focus_rule(selector, depth, opts));
    css.push_str(&disabled_rule(selector, depth));
    css
}

/// The compound a card's interactive states are written against: the class
/// on an element that is itself a control.
///
/// `label` for a card wrapping a choice, `[data-act]` for an act a renderer
/// drew on some other element. Without the class prefix, the way every
/// selector handed to [`interactive_rules`] is.
#[must_use]
pub fn pressable_card(card: &str) -> String {
    format!("{card}:is(a, button, label, [data-act])")
}

/// One rule per depth: its fill and its edge, together.
///
/// A depth and nothing else. `.raised` says a surface sits on what is behind
/// it, which is a statement about the shape and not about what happens when a
/// pointer arrives, so it emits no hover, press, focus or disabled rule. The
/// named surfaces are where interaction lives: `.button`, and `.card` written
/// on a control, get their states from [`surface_rules`].
///
/// Giving this class the interactive set leaves the vocabulary with no raised
/// surface that is merely an object, so a consumer that needs one has to take a
/// control class and cancel half of it.
#[must_use]
pub fn depth_rules(opts: &Emit) -> String {
    let mut css = String::new();
    for depth in [Depth::Raised, Depth::Well] {
        let Some(class) = depth_class(depth, opts) else {
            continue;
        };
        css.push_str(&depth_rule(&class, depth));
    }
    css
}

/// The three surfaces that are a depth with a name.
///
/// `button` and `card` are both [`Depth::Raised`], and `field` is a
/// [`Depth::Well`] because that is the reading `Depth`'s own documentation
/// gives a text field. Their bodies come out identical by construction rather
/// than by hand: three hand-written copies in goingson's stylesheet is what
/// phase A deletes, and generating them from one call is what stops them
/// drifting apart again.
///
/// A card's states hang off [`pressable_card`] rather than the bare class. A
/// card is a raised object that answers a pointer only when it is written on a
/// control, which is what lets one name cover both: a store tile that is one
/// link, a tier picker that is a label round a radio, and a use-case card that
/// does nothing and so has no hover to cancel.
fn surface_rules(opts: &Emit) -> String {
    let mut css = String::new();
    let button = class("button", opts);
    css.push_str(&depth_rule(&button, Depth::Raised));
    css.push_str(&interactive_rules(&button, Depth::Raised, opts));

    let card = class("card", opts);
    css.push_str(&depth_rule(&card, Depth::Raised));
    css.push_str(&interactive_rules(
        &pressable_card(&card),
        Depth::Raised,
        opts,
    ));

    let field = class("field", opts);
    css.push_str(&depth_rule(&field, Depth::Well));

    // A field takes focus and refuses input like everything else here, and got
    // neither until now, which is why all three apps hand-write a focus ring
    // for it and no two of them match. No hover or pressed: a text field does
    // not light up under the pointer and does not invert when clicked, so the
    // two states `interactive_rules` would add are the two it does not have.
    css.push_str(&focus_rule(&field, Depth::Well, opts));
    css.push_str(&disabled_rule(&field, Depth::Well));

    // A file field's own button is a button. `::file-selector-button` is the
    // one part of an `<input type="file">` a stylesheet reaches, and without a
    // rule the platform's grey control sits inside a well drawn in the theme's.
    // Raised, with the hover and the press a button has; no focus ring, because
    // the focus belongs to the input the pseudo-element is part of, and the
    // field's own ring already draws it.
    let chooser = format!("{field}::file-selector-button");
    css.push_str(&depth_rule(&chooser, Depth::Raised));
    let _ = writeln!(
        css,
        ".{chooser} {{\n    border: none;\n    color: inherit;\n    font: inherit;\n    padding: var(--gap-bound) var(--gap-peer);\n    margin-inline-end: var(--gap-peer);\n    cursor: pointer;\n}}"
    );
    css.push_str(&gated(
        hover_condition(),
        &format!(".{chooser}:hover {{\n    background: var(--hover-surface);\n}}\n"),
    ));
    css.push_str(&depth_rule(
        &format!("{chooser}:active"),
        Depth::Raised.pressed(),
    ));

    // Keyed on the ARIA attribute rather than on a class, so the visual state
    // and the accessible state cannot drift apart: there is one fact and both
    // read it. goingson already drove its invalid styling this way and was
    // right to; the `.invalid` class this emitted before 0.5.0 was a second
    // place to forget.
    //
    // The ring composes *after* the bevel rather than replacing it. box-shadow
    // is not additive, so a lone ring silently dropped the well out from under
    // an invalid field. Flat and unlit: this edge is saying "wrong", and
    // lighting one side would have it say "raised" at the same time.
    let _ = writeln!(
        css,
        ".{field}[aria-invalid=\"true\"] {{\n    box-shadow: var({}), 0 0 0 {} var(--danger);\n}}",
        bevel_var(Bevel::Inset),
        opts.border_width
    );

    // The default-button ring, on the one control that commits
    // (`makeover_layout::Act::commits`, wiki `explicit-commit-affordance`).
    // A flush frame twice the border width, composed after the bevel for the
    // invalid ring's reason, and outside the element, so the focus outline,
    // which stands off by its own width, lands beside it rather than over it.
    // Pressed keeps the ring and inverts only the bevel; disabled keeps it in
    // the muted ink, the way a disabled control keeps its bevel.
    //
    // An attribute rather than a class, for `data-tone`'s reason: it is a fact
    // about the act, and a renderer writes it beside the tone.
    let ring = format!("0 0 0 calc(2 * {})", opts.border_width);
    let _ = writeln!(
        css,
        ".{button}[data-commits] {{\n    box-shadow: var({}), {ring} var(--border-strong);\n    font-weight: bold;\n}}",
        bevel_var(Bevel::Raised)
    );
    let _ = writeln!(
        css,
        ".{button}[data-commits]:active {{\n    box-shadow: var({}), {ring} var(--border-strong);\n}}",
        bevel_var(Bevel::Inset)
    );
    let _ = writeln!(
        css,
        ".{button}[data-commits]:is(:disabled, [aria-disabled=\"true\"]) {{\n    box-shadow: var({}), {ring} var(--content-muted);\n}}",
        bevel_var(Bevel::Raised)
    );

    // The act the screen is for (`makeover_layout::Act::leading`).
    //
    // **Leading fills and committing outlines**, which is what lets a control
    // wear both. The ring above is a frame outside the bevel and this is the
    // ground inside it, so the two compose rather than compete: a form that is
    // the screen's own work draws a filled button with the default ring round
    // it, and a sub-form's Add keeps the ring alone.
    //
    // `--content-on-action` rather than a hand-picked ink. The theme derives it
    // with `readable_on(action)`, so a theme whose action hue is pale gets dark
    // text without this file knowing which themes those are.
    //
    // The bevel stays. A leading control is still a button, and dropping its
    // raise to signal importance would make the one control a reader most needs
    // to press the one that least looks pressable.
    // `:not([data-tone])` is load-bearing, and a render caught it missing.
    // A toned control already says what pressing it means, and that outranks
    // how badly the screen wants it pressed -- the rule `makeover-tui` states
    // and this file did not. Without the guard, goingson's compose drew Queue
    // with the Success tone's pale ground under `--content-on-action`'s near
    // white ink, which is a label nobody can read.
    //
    // The tone keeps the control; `leading` adds nothing to it. That is a
    // deliberate loss: a screen whose primary act is destructive or toned has
    // to lead by order and by what the tone already says.
    let _ = writeln!(
        css,
        ".{button}[data-leading]:not([data-tone]) {{\n    background: var(--action);\n    color: var(--content-on-action);\n}}"
    );
    // Hover keeps the derived pair, so the fill does not fall back to the
    // ordinary button's ground mid-hover and leave `--content-on-action`
    // stranded on a surface it was never measured against.
    //
    // Gated through `hover_condition` like every other hover rule here: whether
    // a hover state exists at a density is `makeover-touch`'s to answer, and a
    // rule written outside the gate is this renderer inventing a second answer.
    // The vocabulary test catches exactly that, and caught this.
    css.push_str(&gated(
        hover_condition(),
        &format!(
            ".{button}[data-leading]:not([data-tone]):hover {{\n    background: var(--action-hover);\n    color: var(--content-on-action);\n}}\n"
        ),
    ));
    // Disabled drops to the muted ink on the ordinary button ground: a filled
    // control that cannot be pressed still reads as the thing to press, which
    // is the one thing the fill must not say when it cannot be pressed.
    //
    // Through `fill_var` rather than naming the token, so this follows the
    // ordinary button if the raised fill is ever re-pointed.
    let _ = writeln!(
        css,
        ".{button}[data-leading]:not([data-tone]):is(:disabled, [aria-disabled=\"true\"]) {{\n    background: {};\n    color: var(--content-muted);\n}}",
        fill_var(Fill::Raised)
    );
    css
}

/// Badges and chips.
///
/// The one place phase A changes how goingson looks rather than only where its
/// rules live. [`Token::Badge`] is [`Depth::Flat`], so a badge emits no fill
/// and no edge at all, where goingson ships `.tag, .badge` as a single rule
/// carrying the raised bevel. Splitting that means reading every call site to
/// decide which of the two it always was.
///
/// What a badge does carry is a [`Tone`], the intent family it shares with
/// notices and nothing else. Neutral is the bare class rather than a variant,
/// because it is the absence of a status and not a status called "none".
/// Text that goes somewhere.
///
/// The one inline control. A table cell carries `cell-link` instead, which
/// reads as its row's title rather than as a link; this is the same thing
/// outside a table, which is what a described run holds when a sentence
/// contains a link.
///
/// Colour and underline only. Whether a link is inline in a sentence or sitting
/// on its own line is the app's layout, and how much room it takes is
/// `makeover-geometry`'s. What is here is the pair of signals that say "this
/// goes somewhere" and nothing that says where it sits.
///
/// The visited arm is deliberately absent. A link inside an app points at the
/// app's own screens, which the user is expected to have been to, so painting
/// them differently marks almost everything and distinguishes nothing.
fn link_rules(opts: &Emit) -> String {
    let mut css = String::new();
    let link = class("link", opts);

    let _ = writeln!(
        css,
        ".{link} {{\n    color: var(--action);\n    \
         text-decoration: underline;\n}}"
    );
    // The pointer-target floor, and the scope is the whole of the design in it.
    //
    // A bare `.link` is its own line box, 21px at the body size, under the 24
    // that `makeover_geometry::TARGET_LEAST` names. Applied to every `.link`
    // that floor would reach an anchor set in running prose, where growing the
    // box sets the leading of the paragraph around it: the fix would cost more
    // than the defect. So it is scoped to a link laid out as a piece rather
    // than set in text, which in the emitted markup is one inside a run or a
    // cell -- a footer strip, a row of places, a table cell.
    //
    // `min-block-size` rather than padding: padding adds to the line box and
    // grows whatever holds the link, where a minimum lets the anchor take room
    // its container usually already has. `inline-flex` is what makes the
    // minimum apply to an inline element at all, and `align-items: center`
    // keeps the text on the box's centre line rather than its top.
    let run = class("run", opts);
    let cell = class("cell", opts);
    let least = makeover_geometry::TARGET_LEAST.token();
    let _ = writeln!(
        css,
        ".{run} .{link},\n.{cell} .{link} {{\n    display: inline-flex;\n    \
         align-items: center;\n    min-block-size: var(--{least});\n}}"
    );
    // The hover step is the same one every other control takes, and it is a
    // colour rather than a surface: a link has no box to raise.
    let _ = writeln!(
        css,
        "@media (hover: hover) and (pointer: fine) {{\n    .{link}:hover \
         {{\n        color: var(--action-hover);\n    }}\n}}"
    );
    let _ = writeln!(
        css,
        ".{link}:focus-visible {{\n    outline: {} solid var(--focus-ring);\n    \
         outline-offset: 2px;\n}}",
        opts.focus_width
    );
    // A link is often a `<button>` rather than an `<a>`: a renderer picks the
    // element from the method, so a link that writes is a button that has to
    // stop looking like one. What that costs is named in [`reset`].
    css.push_str(&Reset::TEXT_BUTTON.rule(&format!("button.{link}")));
    css
}

fn token_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // No `depth_rule` call here, deliberately: `Token::Badge.depth(_)` is Flat,
    // and a label with an edge says it can be pressed.
    let badge = class("badge", opts);
    // `content-muted` literally, not `Tone::Neutral.token()`. What makes a
    // badge quiet is `Token::Badge` answering no click, which this crate holds
    // and `Tone` genuinely does not know. Routing it through Neutral put the
    // claim where the evidence was not, and the bill arrived on the figure
    // value: it took the same muting from the same call and read as its own
    // caption. Neutral answers `content` from makeover-layout 0.36.0.
    //
    // A badge is a chip, wiki `table-model`: an opaque fill inside an edge, in
    // the theme's own ink at normal weight. Coloured text was never ratified
    // and measured 1.34:1 on goingson's warning; muted text 2.78:1 on
    // solarized-dark. So the ink is `content` and what says which kind of
    // token it is moves to the fill and the edge: the table's raised ground for
    // a neutral chip, makeover's `*-surface` for a status, edged in its tone.
    // Still no bevel: a label with a raised edge says it can be pressed.
    let bw = opts.border_width;
    let _ = writeln!(
        css,
        ".{badge} {{\n    display: inline-flex;\n    align-items: center;\n    \
         padding: 0 var(--step-snug);\n    border: {bw} solid var(--border);\n    \
         border-radius: var(--radius-fine);\n    background: var(--surface-raised);\n    \
         color: var(--content);\n    font-weight: normal;\n}}"
    );
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{badge}[data-tone=\"{0}\"] {{\n    background: var(--{0}-surface);\n    \
             border-color: var(--{0});\n}}",
            tone.token()
        );
    }

    // A button carries the four tones a badge does. It had none, on the reading
    // that a control's colour is its surface rather than its text, and that
    // reading has one hole big enough to matter: the button that destroys
    // something. Every consumer had written that rule itself, and a description
    // that says `Tone::Danger` on an act had nowhere for it to land.
    //
    // A fill and not the text, matching the badge exactly. This emitted
    // `color: var(--danger)` until 0.86.0, which is the shape wiki
    // `table-model` ratified against for status text and `{tone}-surface`'s own
    // derivation comment names: the tone colours are fills, and a fill used as
    // ink measures 3.36:1 for danger and 1.84:1 for success on goingson's
    // theme. Both are under the 4.5:1 floor, and success is under it by more
    // than the floor itself.
    //
    // It read as ratified for longer than it was because goingson set
    // `color` on `.button` in a later layer, so no described tone ever reached
    // a button and nobody saw the colour it would have drawn.
    //
    // The earlier note here said a red surface belongs to an app's own layer.
    // That argument was against a *saturated* fill, and it still holds: this is
    // the ground with 12 percent of the tone in it, which is the same tint a
    // status chip carries and is not something an app would draw over.
    //
    // The fill and NOT the edge, which is where this differs from the badge.
    // A badge's border is makeover's, so the badge tones it. A button's is the
    // app's: goingson writes `border: ... solid var(--border)` on `.button` in
    // a later layer, and a shorthand cancels a generated `border-color` the
    // same way its `color` cancelled the tone for months. goingson's own drift
    // check caught it on the first build. An edge an app silently overrides is
    // worse than no edge, so the tint carries the tone alone.
    let button = class("button", opts);
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{button}[data-tone=\"{0}\"] {{\n    background: var(--{0}-surface);\n}}",
            tone.token()
        );
        // The pointer answer, at the specificity the tone rule just took. The
        // plain `.button:hover` is (0,2,0) and sits earlier in this sheet, so
        // without this a toned button is the one control on the screen that
        // does not move under a pointer.
        //
        // The fallback is for the version skew, and it is not decoration: the
        // hover tint is a `makeover` 3.8 token and this sheet is emitted from a
        // crate an app can upgrade on its own. An unresolved custom property
        // makes the whole declaration invalid at computed-value time rather
        // than dropping to the cascade, so without it a toned button on an
        // older theme would hover to `transparent`.
        css.push_str(&gated(
            hover_condition(),
            &format!(
                ".{button}[data-tone=\"{0}\"]:hover {{\n    background: \
                 var(--{0}-surface-hover, var(--hover-surface));\n}}\n",
                tone.token()
            ),
        ));
    }

    // A chip holds itself down, which is `Depth::pressed` arrived at
    // independently by two apps. `removable` is a remove affordance, so it is
    // markup and waits for phase B.
    let chip = class("chip", opts);
    let unlatched = Token::Chip { removable: false };

    // The pointer floor, and the one number in this file that does not scale.
    // A chip drawn from its padding alone came out 23px at every width and
    // every density in goingson: 36 of one ui-fuzz run's 51 target findings
    // were this single rule. The length arrives from the caller, the way every
    // other length in this crate does -- see `Emit::target_min` for why the
    // floor is an absolute rather than a `--step-*`.
    //
    // A floor and not a height: a chip with two lines of text or a larger root
    // size still grows. `.chip` is already `inline-flex` with its items
    // centred, from quasi-webview's box rules, so the extra block size opens
    // around the label rather than under it. `.chip.latched` takes it through
    // the same class; `.badge` is a separate class and deliberately does not,
    // because a badge is a label and never a target.
    let _ = writeln!(
        css,
        ".{chip} {{\n    min-block-size: {};\n}}",
        opts.target_min
    );

    css.push_str(&depth_rule(&chip, unlatched.depth(false)));
    css.push_str(&interactive_rules(&chip, unlatched.depth(false), opts));
    css.push_str(&depth_rule(
        &format!("{chip}.latched"),
        unlatched.depth(true),
    ));
    css
}

/// The three selectors, each named by what it picks.
///
/// A tab comes *forward* to join the pane it opens, which is why
/// [`Selector::Tabs`] chooses [`Depth::Raised`] where a segment and a toggle
/// are held in. That is the folder semantic, and it is the whole reason the
/// three are not one member with a flag.
///
/// [`Selector::abutting`] is not emitted: whether the options touch is
/// spacing, and spacing is `makeover-geometry`'s question to answer.
///
/// Both states emit. Naming only the chosen option leaves an unchosen one
/// falling through to [`Depth::Flat`] with nothing drawn for it, so an app has
/// to hand-write the recess that makes its chosen tab read as forward.
fn selector_rules(opts: &Emit) -> String {
    let mut css = String::new();
    for selector in [Selector::Tabs, Selector::Segmented, Selector::Toggle] {
        let c = class(option_class(selector), opts);
        css.push_str(&depth_rule(&c, selector.unchosen()));
        css.push_str(&interactive_rules(&c, selector.unchosen(), opts));
        if selector.joins_its_pane() {
            // Every tab in a folder strip rounds at the top and stays square
            // at the bottom, chosen or not: the corners belong to the strip's
            // shape rather than to which option is up. On the base class and
            // not only on the chosen arm, so that an app has no reason left to
            // carry a radius of its own. goingson's unlayered `.tab` rule beat
            // a chosen-only version of this outright, an unlayered rule being
            // ahead of every layer whatever its specificity.
            let _ = writeln!(
                css,
                ".{c} {{\n    border-radius: var(--radius-control) var(--radius-control) 0 0;\n}}"
            );
            css.push_str(&joined_rule(&c, selector.chosen(), opts));
        } else {
            css.push_str(&depth_rule(&format!("{c}.chosen"), selector.chosen()));
        }
    }
    css
}

/// The chosen option of a selector that joins what it opens.
///
/// [`depth_rule`] draws a closed box, which is right for anything standing on
/// its own and wrong for a folder tab: a closed bottom run reads as a chip
/// resting near its pane rather than as the front of it. Three things make the
/// join, and all three are needed, which is why this is one rule rather than a
/// property added to the depth:
///
/// - The depth's own fill, so the tab and the pane are the same surface. Taken
///   from [`Depth::fill`] rather than named here, so the pairing rule holds.
/// - [`Bevel::RaisedOpen`], so the run between the two is not drawn.
/// - A pull down by one border width, so the tab covers the pane's own top
///   run where it passes underneath. Without it the pane's lit edge draws
///   straight across the join and the tab reads as sitting on a line.
///
/// The corners round at the top and stay square at the bottom for the same
/// reason: a rounded bottom corner puts a notch of page colour either side of
/// the join. `makeover-geometry` has no per-corner member and does not need
/// one, since which corners round is a consequence of the join rather than a
/// scale a consumer picks.
fn joined_rule(selector: &str, depth: Depth, opts: &Emit) -> String {
    let mut body = String::new();
    if let Some(fill) = depth.fill() {
        let _ = writeln!(body, "    background: {};", fill_var(fill));
    }
    let _ = writeln!(
        body,
        "    box-shadow: var({});",
        bevel_var(Bevel::RaisedOpen)
    );
    // No radius here. Every tab in a joining strip already rounds at the top
    // from the base rule, chosen or not, and repeating it on this arm would be
    // a second copy of one decision.
    let _ = writeln!(
        body,
        "    margin-block-end: calc(-1 * {});",
        opts.border_width
    );
    // And it has to paint above what it overlaps. Both the tab and the pane are
    // in flow, the pane is the later sibling, so without this the pane draws
    // over the run the pull-down just covered and the join is undone by the
    // pane's own lit edge. Positioned, not raised by `z-index`: being
    // positioned is enough to paint above an unpositioned sibling, and a stack
    // index here would be a number this crate has no way to keep true against
    // whatever an app stacks around it.
    let _ = writeln!(body, "    position: relative;");
    let mut css = format!(".{selector}.chosen {{\n{body}}}\n");

    // A strip that runs down its pane joins it on the side, and the join above
    // is written for a strip that runs across. Which way a strip runs is not
    // on [`Selector`], and it should not be: it is the arrangement, and the
    // renderer drawing the arrangement is the one that knows.
    //
    // `aria-orientation` is how that renderer has to say it anyway. It is
    // ARIA's word rather than a private attribute, required on any vertical
    // tablist for a screen reader, so keying on it couples this to the
    // standard and not to one caller's markup. Until the side join is drawn,
    // a vertical strip takes the closed edge back and reads as a raised chip
    // beside its pane, which is what it drew before this rule existed.
    let _ = writeln!(
        css,
        "[aria-orientation=\"vertical\"] .{selector}.chosen {{\n    \
         box-shadow: var({});\n    border-radius: var(--radius-control);\n    \
         margin-block-end: 0;\n}}",
        bevel_var(Bevel::Raised)
    );
    css
}

/// The parts of a list row.
///
/// The list is written out rather than derived because `RowPart` is
/// `#[non_exhaustive]`, so there is nothing to iterate. A member added upstream emits no rule until it is named here, which
/// is the trade `non_exhaustive` makes: a silent gap instead of a build break.
/// [`part_class`] carries the same list and the same obligation.
fn row_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // The container the rows sit in, giving back what a `<ul>` brought. Not a
    // size: there is no magnitude in it, which is the line this crate holds.
    css.push_str(&Reset::BULLETS.rule(&format!(".{}", class("list", opts))));

    for part in [
        RowPart::Primary,
        RowPart::Secondary,
        RowPart::Meta,
        RowPart::Actions,
        RowPart::Tokens,
        RowPart::Proportion,
    ] {
        let c = class(part_class(part), opts);

        // Actions carry controls rather than text, and `RowPart::intent` says
        // so by returning the same intent inheriting already gives. Pinning it
        // would be louder than saying nothing. Tokens answer alike, for their
        // own reason: each token carries its own tone, and a colour on the
        // strip would fight the things sitting in it. A proportion is the same
        // case again: the meter inside carries the tone.
        if !matches!(
            part,
            RowPart::Actions | RowPart::Tokens | RowPart::Proportion
        ) {
            let _ = writeln!(css, ".{c} {{\n    color: var(--{});\n}}", part.intent());
        }

        // A row's actions are shown at rest. `RowPart::revealed_on_hover` said
        // otherwise and was not honoured here from 0.23.0; makeover-layout
        // 0.13.0 retired the method, so there is no longer a description saying
        // one thing and a renderer doing another.
        //
        // The rule was `opacity: 0` gated to pointer devices, revealed on
        // `:hover` and on `:focus-within`. Each escape it needed was a report
        // that hiding was wrong for somebody: `focus-within` because tabbing
        // could never reach an action; the gate because a fingertip had no way
        // to unhide, which both webview apps had already hand-written
        // `opacity: 1` to undo. What was left was a control hidden from
        // exactly one group: people using a pointer, who are also the group
        // scanning a list to find out what can be done to a row.
        //
        // A settings screen is where that reads worst: the whole reason to be
        // on it is to remove a key, and the button doing so was invisible
        // until pointed at. A table cell's actions were never hidden, so the
        // two arrangements now agree.
    }

    // A part that may take two lines. `Flow::Tight` gets no rule: one line is
    // what a run already does, and restating it here would put a declaration on
    // every part in every row to say nothing.
    //
    // This is the shape both webview apps had already written by hand and
    // commented -- Balanced Breakfast on a feed row's title, goingson on a
    // problem's body -- which is the whole argument for the description
    // carrying it. `-webkit-` prefixed and unprefixed together: the prefixed
    // trio is what every engine actually implements, and `line-clamp` is the
    // standard property landing behind it.
    let _ = writeln!(
        css,
        ".{} {{\n    display: -webkit-box;\n    -webkit-box-orient: vertical;\n    -webkit-line-clamp: {lines};\n    line-clamp: {lines};\n    overflow: hidden;\n}}",
        class("row-relaxed", opts),
        lines = Flow::Relaxed.lines()
    );

    // A row inside a hierarchy: a tree, an outline, a threaded list.
    // `edf33114`, decided 2026-08-30 (Max). makeover-layout names the concept
    // as `Nesting` -- deliberately not `Depth`, which is surface bevel in that
    // crate -- and this is the rule.
    //
    // Measured 2026-08-30: quasi-webview has been emitting `row-nested` with
    // `style="--row-depth:N"` on every described hierarchy, and **no stylesheet
    // anywhere in the tree read any of it**. So a described outline in a
    // browser was a flat list with chevrons in it -- the folding worked and the
    // indent did not exist.
    //
    // The magnitude is a custom property with a fallback, which is this crate's
    // own shape: `--awaiting-gap` above is the precedent, and an app overriding
    // `--row-indent` is how a level becomes worth more or less. What a level IS
    // stays the description's; what it is WORTH is a renderer's, and a terminal
    // spending columns for the same fact is not disagreeing.
    //
    // Here rather than in each app, and that was a live option rather than an
    // oversight. `row-select`, `row-current` and `row-chosen` are app-styled by
    // design; the indent is not decoration, it is what the description MEANS,
    // and three apps agreeing about it by accident is not agreement.
    //
    // `padding` and not `margin`: a row is a box that can be selected and
    // hovered, and indenting with margin would take the indent out of the
    // highlight, so the shading under a nested row would start where its text
    // does rather than where its row does.
    let _ = writeln!(
        css,
        ".{} {{\n    padding-inline-start: calc(var(--row-depth, 0) * var(--row-indent, 1.5ch));\n}}",
        class("row-nested", opts)
    );

    // The two halves of a branch, emitted by quasi-webview and unstyled until
    // now for the same reason.
    //
    // A branch row is the one a reader can fold, and the chevron is its hit
    // target. The chevron is drawn by the app or the description -- this says
    // where it sits and how big the target is, which is the accessibility fact
    // rather than the decorative one: a control smaller than this is one a
    // finger misses.
    let _ = writeln!(
        css,
        ".{} {{\n    display: flex;\n    align-items: baseline;\n    gap: var(--row-disclose-gap, 0.5ch);\n}}",
        class("row-branch", opts)
    );
    let _ = writeln!(
        css,
        ".{} {{\n    flex: none;\n    min-inline-size: var(--tap-target, 2rem);\n    min-block-size: var(--tap-target, 2rem);\n    background: none;\n    border: 0;\n    color: inherit;\n    cursor: pointer;\n}}",
        class("row-disclose", opts)
    );

    // How a part holds what is in it, for a row and for a table cell. These
    // were quasi-webview's arrangement sheet's until 0.82.0, which ruled names
    // this crate emits, so a row an app wrote by hand got none of it. The row
    // itself stays quasi-webview's: where a part sits in the line is the screen
    // renderer's arrangement, and nothing here says it.
    //
    // A token or a control never breaks across two lines. What gives when the
    // line runs short is the row's text.
    let tokens = class(part_class(RowPart::Tokens), opts);
    let actions = class(part_class(RowPart::Actions), opts);
    let proportion = class(part_class(RowPart::Proportion), opts);
    let fallback = class("row-part", opts);
    let cell_tokens = class(cell_part_class(CellPart::Tokens), opts);
    let cell_actions = class(cell_part_class(CellPart::Actions), opts);
    let cell_fallback = class("cell-part", opts);
    let _ = writeln!(
        css,
        ".{fallback},\n.{cell_fallback} {{\n    min-width: 0;\n}}"
    );
    let _ = writeln!(
        css,
        ".{tokens} {{\n    display: flex;\n    flex-wrap: wrap;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    let _ = writeln!(
        css,
        ".{actions} {{\n    display: flex;\n    flex: none;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    // A cell's parts sit inside the cell's own box, so they are inline: the
    // cell's alignment, which the column kind sets, still places them.
    let _ = writeln!(
        css,
        ".{cell_tokens},\n.{cell_actions} {{\n    display: inline-flex;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    let _ = writeln!(css, ".{cell_tokens} {{\n    flex-wrap: wrap;\n}}");
    let _ = writeln!(
        css,
        ".{tokens} > *,\n.{actions} > *,\n.{cell_tokens} > *,\n.{cell_actions} > * {{\n    white-space: nowrap;\n}}"
    );
    // A proportion is a meter, and a meter is as wide as the row lets it be.
    let _ = writeln!(css, ".{proportion} {{\n    flex: 1 1 auto;\n}}");

    css
}

/// A row of things that share their space, and what each fallback gets here.
///
/// Ruling: wiki `layout-room-and-fallback`, Max. Rule 1 is that every described
/// member is in flow, and these rules are how that is kept rather than asked
/// for. A member taken out of flow with `position: absolute` contributes zero
/// width to the row it shares, so nothing can collide with it and nothing
/// prevents the collision.
///
/// # The floor, which is most of the fix
///
/// `.run > *` gets `min-width: min-content`. That is the derived minimum the
/// ruling asks for, in this renderer's own unit and stated by the browser
/// rather than by anybody: a member cannot be squeezed narrower than what is
/// in it, so members in one flow push each other instead of overlapping. It
/// costs no query and no number, and it is what fixes all four measured widths
/// whichever fallback the group declared.
///
/// # A member that asks to fill
///
/// `.run > [data-width="fill"]` gets `flex: 1 1 0`, which is the second half of
/// what a column has always been able to say, reaching a row of regions.
/// `flex-basis: 0` and not `auto` is what makes several fills divide the room
/// equally rather than dividing the leftovers in proportion to their contents;
/// equal division is [`makeover_layout::Width::Fill`]'s own stated rule. The
/// floor above still applies, so a fill cannot shrink under what is in it.
///
/// A member that says nothing gets nothing, because a flex item with the floor
/// and no grow is already content-sized. That is why the omitted value here is
/// `Content` while a control omits `Fill`: each position leaves out what it
/// already did.
///
/// # What each fallback gets, exactly
///
/// [`Fallback::Wrap`] is `flex-wrap: wrap`, and a member that asks to fill gets
/// a stated room to start from.
///
/// Wrapping on its own was not exact, which `4f5705b1` measured. A flex line
/// breaks on each member's hypothetical size, a fill member's basis is `0`, and
/// the floor above is `min-content`, so the line breaks only once the members'
/// intrinsic widths no longer fit. A member holding a table reports almost
/// nothing for that: a table's headings and cells are `container-type:
/// inline-size`, so the size container refuses to be measured through and a few
/// headings are all that is left. Two fill members each holding a table drew as
/// two slivers side by side at 420 while both tables overflowed, and the page
/// scrolled sideways.
///
/// So under `Wrap` a fill member's `flex-basis` is
/// `min(100%, var(--run-room, 20rem))` rather than `0`: room the description
/// states, rather than room measured through a container that will not report
/// it. `min(100%, ...)` is what keeps a lone member from overflowing a run
/// narrower than the room, and it is the shape quasi's own `main.list-detail`
/// regions already fold on. The custom property is how an app says what the
/// room is, because the number is a size and sizes are the app's; the fallback
/// is a default rather than this crate settling a width.
///
/// Only under `Wrap`. A fill member in a run that does not wrap keeps
/// `flex: 1 1 0`, where equal division is the whole of what it asked for and
/// there is no line to break.
///
/// [`Fallback::Stack`] is wrap plus `flex: 1 1 max-content` on the members, so
/// a member that cannot sit beside its sibling takes a line of its own and
/// fills it. For the two-member run this was ruled on -- a tab strip and a
/// band -- that is precisely "a row becomes a column".
///
/// [`Fallback::Shed`] and [`Fallback::Menu`] get wrap, and this renderer is
/// honouring less than the description says. **CSS cannot express either one
/// without breaking the ruling's own first constraint.** Both need to know that
/// the run is out of room in order to take a member out of it, a container
/// query is the only construct that can ask, and `@container` compares against
/// a `<length>` -- there is no `@container (inline-size < min-content)`. So
/// every honest spelling of Shed here needs an authored breakpoint, which is
/// the thing the ruling exists to forbid, and the dishonest ones are worse: a
/// clamped height clips by document order rather than by [`Priority`], and
/// `display: none` under a viewport `@media` is the `nth-child(n+5)` bug the
/// vocabulary replaced.
///
/// Wrapping is the right thing to do instead. It keeps every member reachable,
/// which is the property that was actually broken -- goingson's new-contact
/// button left the viewport entirely at 560 -- and it keeps rule 1. A renderer
/// answering with less than was described is precedented and deliberate here:
/// [`makeover_layout::Region::Columns`] says a terminal stacking a board's
/// columns is honouring the description rather than degrading it.
///
/// The real mechanism needs the shed members to have somewhere to go, which is
/// markup and belongs to quasi-webview: an overflow control is a member of the
/// run, and the description does not yet say that a member *is* one.
///
/// # Menu, once a script is measuring
///
/// That is now built, in `quasi-webview`'s `menu.js`, and this crate's half of
/// it is two classes and one override. A script that has taken a menu run over
/// marks it `data-menu`, and a marked run goes back to `nowrap`: wrapping is
/// what hides the overflow condition the script is trying to measure. The
/// unmarked rule above is untouched, so a page that ships no script still
/// wraps, which is rule 1 — every member reachable — rather than a strip with
/// tabs squeezed off the end.
///
/// `.run-overflow` is the control the shed members move into and
/// `.run-overflow-items` is where they land. The geometry is this crate's the
/// way every other surface's is; what is *in* it is the script's, because which
/// members no longer fit is a measurement and not a description.
fn run_rules(opts: &Emit) -> String {
    let run = class("run", opts);
    let mut css = String::new();

    // `flex-wrap: nowrap` is stated rather than left to the default, because
    // the fallbacks below are read as overrides of this line and a reader
    // should not have to know which way flexbox leans to see that.
    //
    // No gap. Spacing between members is the app's, the same way this crate
    // states no margins anywhere else; a gap here would be a size, and the one
    // hardcoded size in the mechanism is makeover-geometry's contact patch.
    let _ = writeln!(
        css,
        ".{run} {{\n    display: flex;\n    flex-wrap: nowrap;\n    align-items: center;\n}}"
    );

    // The derived minimum, and the whole reason a member can no longer be
    // overlapped. `min-width: auto` is flexbox's default for a flex item and is
    // *not* the same thing: auto lets an item be compressed below its content
    // in a nowrap run, which is how a toolbar ends up drawn over a tab strip
    // even without anything leaving the flow.
    let _ = writeln!(css, ".{run} > * {{\n    min-width: min-content;\n}}");

    // A member that absorbs what is left. `flex-basis: 0` rather than `auto` is
    // what makes several fills divide the room equally instead of dividing the
    // leftovers in proportion to what is already in them, which is
    // `Width::Fill`'s own rule and the one thing that type states about more
    // than one of them.
    //
    // The `min-width: min-content` floor above is deliberately not overridden.
    // A fill that could shrink below its contents would overlap its neighbour,
    // which is rule 1, and equal division under a floor is still equal division
    // everywhere the floor is not reached.
    //
    // Attribute rather than class, because the width is a fact the description
    // carried rather than a hook this crate invented: the same division
    // `data-tone` and `data-selector` are on the right side of. It beats the
    // `Stack` rule below on specificity whichever order they are written in,
    // which is what a member asking to fill should do to a blanket.
    let _ = writeln!(
        css,
        ".{run} > [data-width=\"fill\"] {{\n    flex: 1 1 0;\n}}"
    );

    for fallback in [
        Fallback::Wrap,
        Fallback::Stack,
        Fallback::Shed,
        Fallback::Menu,
    ] {
        let name = fallback_class(fallback);
        let c = class(name, opts);
        let _ = writeln!(css, ".{c} {{\n    flex-wrap: wrap;\n}}");
        if matches!(fallback, Fallback::Stack) {
            let _ = writeln!(css, ".{c} > * {{\n    flex: 1 1 max-content;\n}}");
        }
        // The stated room, and only here. Written after the blanket fill rule
        // above so it overrides the basis it set; the grow and shrink that rule
        // states are deliberately left alone, so several fills still divide one
        // line equally and the min-content floor still stops any of them
        // shrinking under its contents.
        if matches!(fallback, Fallback::Wrap) {
            let _ = writeln!(
                css,
                ".{c} > [data-width=\"fill\"] {{\n    \
                 flex-basis: min(100%, var(--run-room, 20rem));\n}}"
            );
        }
    }

    // A menu run a script has taken over. The mark is the script's and this is
    // the only rule that reads it: wrapping is what a run does when nothing is
    // measuring, and it is also what makes the overflow unmeasurable, since a
    // wrapped run always fits. The two cannot both be on.
    let menu = class(fallback_class(Fallback::Menu), opts);
    let _ = writeln!(css, ".{menu}[data-menu] {{\n    flex-wrap: nowrap;\n}}");

    // The overflow control, and it is a member of the run like any other: in
    // flow, at the end, taking the width of what is in it. `relative` is what
    // the items hang off.
    let overflow = class("run-overflow", opts);
    let items = class("run-overflow-items", opts);
    let _ = writeln!(css, ".{overflow} {{\n    position: relative;\n}}");

    // Overlaid rather than in flow, for the reason every menu is: a control
    // that pushed the page down when it opened would change the layout it was
    // opened to escape. `inset-inline-end: 0` rather than a left, so the panel
    // stays on the page in both writing directions.
    //
    // No width, no padding and no border. All three are sizes and sizes are
    // makeover-geometry's; what is stated here is placement, the surface and
    // the shadow that separates it from the page, which is the same division
    // `figure_rules` and the timeline entry make. The elevation shadow is what
    // an overlaid surface takes instead of an edge -- see `ELEVATION_PROPERTY`.
    let _ = writeln!(
        css,
        ".{items} {{\n    \
         position: absolute;\n    \
         inset-block-start: 100%;\n    \
         inset-inline-end: 0;\n    \
         z-index: 1;\n    \
         display: flex;\n    \
         flex-direction: column;\n    \
         align-items: stretch;\n    \
         background: var(--surface-raised);\n    \
         box-shadow: var(--elevation-overlay);\n\
         }}"
    );

    // `hidden` is how the script closes it, and a flex display would otherwise
    // beat the attribute's own `display: none`.
    let _ = writeln!(css, ".{items}[hidden] {{\n    display: none;\n}}");

    css
}

/// Every class [`fallback_class`] can return, plus the run itself.
///
/// [`ROW_PART_CLASSES`](crate::list::ROW_PART_CLASSES)'s reasoning and the same
/// obligation: a `match` over a `#[non_exhaustive]` enum cannot be enumerated
/// from outside, so the list sits beside it and a test holds the two together.
/// `run` is in it because it is emitted in its own right rather than only as a
/// fallback's fallback.
pub const RUN_CLASSES: &[&str] = &[
    "run",
    "run-wrap",
    "run-stack",
    "run-shed",
    "run-menu",
    // Not returned by `fallback_class`: these two are the overflow control a
    // measuring renderer builds, and they are in the list because the list is
    // what a host seals its vocabulary against. A class emitted by a script and
    // missing from here is a control with no surface and no edge.
    "run-overflow",
    "run-overflow-items",
];

/// The class a run carries for what it does when it is tight.
///
/// A run always carries `.run` as well, so an unrecognised fallback -- the enum
/// is `#[non_exhaustive]` -- lands as a plain nowrap row with the min-content
/// floor still under it. That is the safe failure: every member in flow and
/// none overlapped, which is the property, with only the rearrangement missing.
#[must_use]
pub fn fallback_class(fallback: Fallback) -> &'static str {
    match fallback {
        Fallback::Wrap => "run-wrap",
        Fallback::Stack => "run-stack",
        Fallback::Shed => "run-shed",
        Fallback::Menu => "run-menu",
        _ => "run",
    }
}

/// The progress trough these rules fill.
///
/// [`meter::meter_html`](crate::meter::meter_html) is what fills these.
///
/// The rules stay a superset of what a description can ask for. An app drawing
/// its own bar keeps these classes, which is what the four goingson grew
/// independently were adopted onto.
///
/// The trough is a [`Depth::Well`], the same reading a text field gets:
/// something with its content down inside it.
fn progress_rules(opts: &Emit) -> String {
    let progress = class("progress", opts);
    // `progress-fill` rather than a bare `fill`: an unprefixed build claims
    // these names in the app's own stylesheet, and `.fill` is grabby enough to
    // catch things that have nothing to do with progress. goingson already
    // calls it `.progress-fill`, so this is also the name that deletes.
    let fill = class("progress-fill", opts);
    let mut css = depth_rule(&progress, Depth::Well);

    // The trough's block size, and the fill filling it. The fill is an empty
    // block, so a trough nothing sized had no height and the meter drew nothing:
    // goingson carried the size in its own sheet, and MNW, which did not, drew
    // its Cloud Sync storage meter as a blank gap. Width stays the app's, below;
    // a height is not taste, it is whether the bar exists.
    let _ = writeln!(
        css,
        ".{progress} {{\n    block-size: var(--meter-block, 0.625rem);\n    overflow: hidden;\n}}"
    );

    // The untoned bar is `--action`, not [`Tone::Neutral`]. That is the one
    // place this differs from the badge rules, and deliberately: a badge with
    // no status is a muted label, while a bar with no status is still
    // reporting progress, and `content-muted` would read as disabled.
    //
    // The width is the two counts the meter emitter hands over in `data-vars`,
    // DIVIDED HERE. `meter::meter_html_into` used to hand over a finished
    // percentage, which is a number worked out from two others and therefore
    // not a stand-in a residual filler can find: one request's width baked into
    // the template. This division is the half of the contract the markup cannot
    // state on its own, exactly as `chart_rules` says of a bar's height.
    //
    // `min(done, total)` is the clamp `Meter::percent` used to apply, moved
    // here with it: an over-run draws a full bar rather than one wider than its
    // trough. `max(var(--meter-total), 1)` rather than a guard, for
    // `chart_rules`' reason -- dividing by zero makes the whole declaration
    // invalid at computed-value time, which drops the width to `auto`, and an
    // auto-width block is the whole trough, reading as done.
    //
    // Both fallbacks are 0, so an element with neither property draws an empty
    // bar rather than a full one, which is the reading the old `0%` default had.
    //
    // On the fill alone, not under `.progress >`: a rule names every class in
    // its selector to a consumer's drift check, and the trough's width is the
    // app's to set. goingson sizes `.progress` and failed its build on a width
    // this rule never gave the trough.
    let _ = writeln!(
        css,
        ".{fill} {{\n    width: calc(\n        min(var(--meter-done, 0), var(--meter-total, 0))\n        \
         * 100% / max(var(--meter-total, 1), 1)\n    );\n    block-size: 100%;\n}}"
    );
    let _ = writeln!(
        css,
        ".{progress} > .{fill} {{\n    background: var(--action);\n}}"
    );

    // A bar can be saying something, same as a badge: goingson colours subtask
    // progress as success and an over-estimate as danger, which is real
    // information rather than decoration. Emitting the tones is what lets that
    // survive adoption instead of staying hand-written.
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{progress} > .{fill}[data-tone=\"{0}\"] {{\n    background: var(--{0});\n}}",
            tone.token()
        );
    }
    css
}

/// What a wait looks like, for the attribute that has been describing one to
/// nobody.
///
/// Wiki `loading-and-progress-standard`, phase 2. `data-awaiting` is emitted
/// as `data-awaiting="determinate"` with a `data-awaiting-amount` beside it, or
/// `data-awaiting="indeterminate"` alone. This is the half that styles them,
/// without which the two render identically.
///
/// # Why it is keyed on `aria-busy` and not on the attribute alone
///
/// `data-awaiting` is a fact about the control: pressing this waits. It is true
/// when the page is painted and it stays true. Whether a wait is *running* is
/// true only between two events, so it is the binder's to set, and `aria-busy`
/// is the standard spelling of it — announced as well as drawn, which a class
/// of our own would not be.
///
/// That also keeps this crate out of any one client library's vocabulary.
/// `quasi-webview` sets `aria-busy` from htmx's request events; a host driving
/// the same markup another way sets it the same way and gets the same drawing.
///
/// # The two drawings
///
/// One pseudo-element either way, so no renderer has to emit an extra node.
///
/// Indeterminate is the activity mark of rule 2: a small square that blinks.
/// Determinate is a trough with a fill, drawn as a single gradient whose stop is
/// `--awaiting-share`, a plain number from 0 to 1 that the binder sets from
/// bytes it has actually watched land. A determinate control with nothing
/// setting the share draws an empty trough rather than a full one, which is the
/// honest reading: the size is known and the delivery is not.
///
/// **What the bar may not do**, from rule 1 and from `Awaiting`'s own docs:
/// what is done over what there is, and never a remaining time, an arrival time
/// or a rate extrapolated forward. Nothing here can express one, which is
/// deliberate — the only input is a share of a measured payload.
///
/// # Sizes, and the deferral rule
///
/// `progress_rules` emits the tones and never the width, because the width is
/// not this crate's to know. A pseudo-element has no intrinsic size at all, so
/// the same treatment would render nothing anywhere. Both sizes are therefore
/// custom properties with defaults: an app that wants a different mark sets
/// `--awaiting-mark` and `--awaiting-bar` once, and one that says nothing gets a
/// mark that is visible.
///
/// # The cadence, and what happens without it
///
/// `--cadence-activity` comes from `makeover-timing` through `makeover-build`,
/// and is a half-period, so a full cycle is twice it. It is used bare rather
/// than with a fallback: a number written here would be a second heartbeat for
/// a mark three renderers draw.
///
/// A sheet assembled without the time axis leaves `animation-duration` invalid,
/// which resolves to `0s`, which runs no animation and leaves the base style —
/// a lit, still mark. That is also exactly what the reduced-motion block does,
/// since it sets the cadence to `0ms`. Both fall out of one rule because the
/// base style is lit and the keyframes do the dimming, which is the ordering
/// `makeover_timing::reduced_motion_css` asks its consumers for by name.
fn awaiting_rules(opts: &Emit) -> String {
    let mut css = String::new();

    // Dimming rather than lighting, so a zero-length animation leaves a lit
    // mark rather than a blank one. See `makeover_timing::reduced_motion_css`.
    css.push_str(
        "@keyframes makeover-activity {\n    \
         0%, 49.99% {\n        background: var(--action);\n    }\n    \
         50%, 100% {\n        background: var(--surface-sunken);\n    }\n\
         }\n",
    );

    // Nothing is drawn until something is waiting. `content` on the base rule
    // rather than on the busy one keeps the box the same box across the
    // transition, so a mark appearing does not reflow the line it is in.
    let _ = writeln!(
        css,
        "[data-awaiting]::after {{\n    \
         content: \"\";\n    \
         display: none;\n    \
         margin-inline-start: var(--awaiting-gap, 0.5ch);\n    \
         vertical-align: baseline;\n\
         }}"
    );

    let _ = writeln!(
        css,
        "[data-awaiting][aria-busy=\"true\"]::after {{\n    \
         display: inline-block;\n    \
         inline-size: var(--awaiting-mark, 0.5em);\n    \
         block-size: var(--awaiting-mark, 0.5em);\n    \
         background: var(--action);\n    \
         opacity: 1;\n    \
         animation: makeover-activity calc(var(--cadence-activity) * 2) \
         step-end infinite;\n\
         }}"
    );

    // The measured half. A wider box, no blink, and a gradient whose stop is
    // the share: the fill and the trough in one paint, so the markup stays one
    // pseudo-element on both branches.
    //
    // `--awaiting-share` unset is an empty trough, not a full one. A bar that
    // read full because nobody was counting would be the confidently-wrong
    // drawing rule 1 exists to forbid.
    //
    // The trough takes an edge for the reason a well does: a bar at zero share
    // is otherwise a rectangle of the surface it sits on, which is nothing at
    // all. `border_width` rather than a literal, the way `depth_rule` and
    // `track_rules` write theirs.
    let _ = writeln!(
        css,
        "[data-awaiting=\"determinate\"][aria-busy=\"true\"]::after {{\n    \
         inline-size: var(--awaiting-bar, 6em);\n    \
         animation: none;\n    \
         outline: {} solid var(--border);\n    \
         outline-offset: -{};\n    \
         background: linear-gradient(\n        \
         to inline-end,\n        \
         var(--action) 0 calc(var(--awaiting-share, 0) * 100%),\n        \
         var(--surface-sunken) 0\n    \
         );\n\
         }}",
        opts.border_width, opts.border_width
    );

    css
}

/// A strip of figures, and the two spans inside each one.
///
/// Colour only, which is the deferral rule applied to a component that badly
/// wants to break it. A figure reads as a figure because the value is set large
/// over a small caption, and that is a size: `makeover-geometry` answers how
/// much space and this crate answers what the thing is. Emitting `font-size`
/// here would be this crate naming a value, which is the one thing it is defined
/// by not doing, and `progress_rules` is the precedent — it emits the tones and
/// never the width, because the width is not its to know.
///
/// So the type scale is the app's, and what is generated is the part an app
/// cannot get right by itself: which of the two spans carries the tone, and,
/// from 0.82.0, the strip the figures sit in.
/// A definition list, and the two tracks that make its values line up.
///
/// **The alignment is the whole member.** Five goingson panes were saying
/// labelled facts as a row each, and rendered that way every value started
/// after its own label, so no column formed and the eye had nothing to run
/// down. A grid with one label track sized to the longest label is the fix, and
/// it is something only the set can do -- which is why `Node::Facts` carries
/// the set rather than each pair.
///
/// `max-content` on the first track and not a fixed width: the label column is
/// as wide as the longest label and no wider, which is what keeps a pane of
/// short labels from leaving a canyon before the values.
///
/// The value takes `content` and the label reads back. goingson had that the
/// other way round -- muted values against unmuted labels -- so the part a
/// person came for was the quieter of the two. Same rule `figure_rules` states
/// for a value against its caption, and `row` for primary against meta.
fn facts_rules(opts: &Emit) -> String {
    let facts = class("facts", opts);
    let label = class("facts-label", opts);
    let value = class("facts-value", opts);
    let mut css = String::new();

    let _ = writeln!(
        css,
        ".{facts} {{\n    display: grid;\n    grid-template-columns: max-content 1fr;\n    \
         column-gap: var(--gap-section);\n    row-gap: var(--gap-peer);\n    margin: 0;\n}}"
    );
    // `dt` and `dd` both carry a browser margin that would break the tracks.
    let _ = writeln!(
        css,
        ".{facts} > .{label} {{\n    margin: 0;\n    color: var(--content-secondary);\n}}"
    );
    let _ = writeln!(
        css,
        ".{facts} > .{value} {{\n    margin: 0;\n    color: var(--content);\n}}"
    );
    css
}

fn figure_rules(opts: &Emit) -> String {
    let figures = class("figures", opts);
    let figure = class("figure", opts);
    let value = class("figure-value", opts);
    let caption = class("figure-caption", opts);
    let change = class("figure-change", opts);
    let mut css = String::new();

    // A strip of tiles that wraps rather than overflows, a section apart. It
    // was quasi-webview's arrangement sheet's to say, for a name this crate
    // emits.
    //
    // **The strip is one object, and its cells are even.** It was a flex row
    // with a gap and nothing else, so a set of figures read as its values and
    // captions scattered along a line: every figure started where the last one
    // ended, no column formed, and four numbers looked like eight loose words.
    // That is the defect [`facts_rules`] already records for a labelled row,
    // and the answer is the same one -- alignment only the SET can give, which
    // is why `Node::Stats` carries the set rather than each figure.
    //
    // A ground with its own air, sized to what it holds. The ground is what
    // makes a set read as a set; the derived width is what stops it reading as
    // a banner with its contents in one corner.
    //
    // `max-content` under `max-width: 100%` rather than `fit-content`, which
    // says the same thing and is not a value this crate may name: the literal
    // guard takes `max-content` as "a derived width and not one anybody chose"
    // and refuses `fit-content`, and the pair comes to the same layout.
    //
    // Both halves were measured on MNW's waitlist at 1440, where the strip
    // holds four figures and the page runs 1376px. Stretching the cells to
    // share the line (`flex: 1 1 0`) put `4 Pending` and `15 Creators` at
    // opposite ends of the screen with a third of the window empty between
    // them, which trades scattered text for a scattered row. Letting the band
    // run full width left the four figures huddled in its left corner. Cells at
    // their natural width inside a band that hugs them is the one of the three
    // that reads as a group.
    //
    // `max-width: 100%` so the band still yields at a narrow window: the cells
    // wrap inside it rather than pushing the document sideways.
    //
    // The ground is a step of the theme's own neutral ramp, never a tone, and
    // the fallback chain is the one this crate's header states for a well, so a
    // theme naming no sunken surface gets a readable band rather than a missing
    // colour. Not a raised surface per figure: that makes four cards out of a
    // summary, and a summary is rarely the point of the page it sits on.
    let _ = writeln!(
        css,
        ".{figures} {{\n    display: flex;\n    flex-wrap: wrap;\n    gap: var(--gap-pane);\n    \
         padding: var(--gap-section);\n    width: max-content;\n    max-width: 100%;\n    \
         background: var(--surface-sunken, var(--surface-raised));\n}}"
    );

    // `content` literally. A figure's value is the thing itself, at full
    // weight -- wiki `three-tone-convention` classes it "active, emphasised",
    // and both other renderers already draw it that way (makeover-tui
    // `piece.rs:391` bold, makeover-immediate `widget.rs:244`). It reached
    // here through `Tone::Neutral.token()` and came out `content-muted`, so
    // the headline number sat at the colour of its own caption.
    let _ = writeln!(
        css,
        ".{figure} > .{value} {{\n    color: var(--content);\n}}"
    );
    let _ = writeln!(
        css,
        ".{figure} > .{caption} {{\n    color: var(--content-muted);\n}}"
    );
    let _ = writeln!(
        css,
        ".{figure} > .{change} {{\n    color: var(--content-muted);\n}}"
    );

    // A toned figure tones one part and never the caption. The caption is the
    // noun and stays muted.
    //
    // Which part depends on whether there is a change, and that is the whole of
    // what 0.13.0 changed here. A figure with a delta is an ordinary number that
    // has moved in a direction worth reading, so the delta takes the colour and
    // the number stays plain; a figure without one has nowhere else to put it.
    // `:has` is what lets one attribute mean both, and the alternative was the
    // emitter deciding by writing the attribute onto a different element, which
    // leaves two elements able to disagree about a figure's one meaning.
    // The tone is an edge, and neither number is drawn in it. Both were until
    // 0.86.0, and both failed the same way `{tone}-surface`'s derivation
    // comment describes: measured on goingson, a toned value read 1.24:1, 1.53:1
    // and 2.27:1 against the ground it sits on. A figure's value is the
    // largest text on the screen and the one most worth reading, so it keeps
    // `content` whatever the tone is.
    //
    // An edge rather than the tinted fill a chip and a button take. A figure
    // has no box of its own -- it is a bare pair of spans in a flex strip --
    // and giving the toned ones a fill would give a strip of figures two
    // different shapes depending on which of them had news. The rule sits on
    // the side so a neutral figure is untouched and the tint never has to exist.
    //
    // This also retires the `:has` split. It existed to choose which of the two
    // elements took the colour; with neither taking it, a figure with a delta
    // and a figure without one want the same rule, and the two elements can no
    // longer disagree about one tone because neither states it.
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{figure}[data-tone=\"{0}\"] {{\n    border-inline-start: {1} solid \
             var(--{0});\n    padding-inline-start: var(--step-snug);\n}}",
            tone.token(),
            opts.focus_width
        );
    }
    css
}

/// A picture, its frame and its caption.
///
/// # The frame is a border, and this is the one place a bevel is wrong
///
/// Emitting [`Depth::Raised`] here through [`depth_rule`], the same call
/// `button` and `card` make, is wrong, and MNW's landing page is where it
/// showed: **the frames had no visible edge at all.**
///
/// `Depth::Raised`'s edge is `--bevel-raised`, which is an *inset* shadow — a
/// 1px light run at the top-left and a dark one at the bottom-right, drawn
/// **inside** the element's box. On a button or a card that box is a surface
/// this crate owns, so an inset edge reads as the surface catching the light.
/// On a picture it is drawn on top of the picture, over whatever pixels the
/// image happens to have at its border. MNW's screenshots are light-on-light
/// parchment, so the light half landed on a light image and the frame
/// disappeared.
///
/// **You cannot bevel a surface you do not own.** A picture's content is the
/// app's, arrives at request time, and can be any colour, so its edge has to
/// sit *outside* the content rather than on it. That is a border.
///
/// The fill stays, and it is not decoration: it is what shows through a
/// transparent PNG and what stands in the frame's place while the image is
/// still loading.
///
/// This is a real limit on [`Depth`] rather than a special case. Every other
/// consumer of a depth draws its own surface; a picture is the first member
/// whose surface belongs to someone else.
///
/// # No size
///
/// `width: 100%` and nothing else. How large a picture is depends on the box it
/// was put in, which is the app's arrangement and `makeover-geometry`'s scales,
/// and a renderer that picked one would be answering for every consumer at
/// once. This is where `figure_rules` landed for the same reason.
fn picture_rules(opts: &Emit) -> String {
    let picture = class("picture", opts);
    let img = class("picture-img", opts);
    let caption = class("picture-caption", opts);
    let mut css = String::new();

    // Block, or an inline image sits on the text baseline and carries a
    // descender's worth of space under it that no app ever wants and every app
    // deletes by hand. The border is the frame; see the type docs for why it is
    // not the bevel every other surface here gets.
    let _ = writeln!(
        css,
        ".{img} {{\n    display: block;\n    width: 100%;\n    height: auto;\n    \
         background: var(--{});\n    border: {} solid var(--border);\n}}",
        Fill::Raised.token(),
        opts.border_width
    );

    // The two fits that need a rule. `Fit::Natural` emits no attribute at all,
    // so it is the bare rule above and needs nothing here.
    let _ = writeln!(
        css,
        ".{img}[data-fit=\"cover\"] {{\n    height: 100%;\n    object-fit: cover;\n}}"
    );
    let _ = writeln!(
        css,
        ".{img}[data-fit=\"contain\"] {{\n    height: 100%;\n    object-fit: contain;\n}}"
    );

    // A caption reads back one step, which is `figure-caption`'s answer and the
    // same claim: it says what the thing above it is, and it is not the thing.
    let _ = writeln!(
        css,
        ".{picture} > .{caption} {{\n    color: var(--content-muted);\n}}"
    );

    css
}

/// A region showing one child at a time, and the chrome that moves between them.
///
/// [`makeover_layout::Showing`] lets a description say that a region holds
/// several children and shows some of them. A renderer derives its own chrome
/// from that, which is what stops every renderer growing a `match` on a widget
/// name; these are the rules the derived chrome needs.
///
/// # Why the default is every child, and the enhancement takes them away
///
/// The controls are a lie until something binds them. A prev button rendered
/// into a document with no script is a control that looks live and answers
/// nothing, and the reader it lies to is exactly the one who cannot see the
/// other children either — the collapsing and the moving are the same half.
///
/// So the rules run in the direction the enhancement does. Nothing here hides a
/// child and nothing here shows a control. Whatever binds the region sets
/// `data-ready` on it, and that is what collapses the stack to one and reveals
/// the row that moves it. A reader with no script gets every child in order and
/// no controls, which is more content rather than less, and a reader with
/// script gets a settled page rather than a stack that jumps to one frame after
/// load.
///
/// MNW proved this shape by hand — a `<noscript>` stylesheet opening its
/// carousel back out — and it is here rather than there because the property is
/// the description's, not one app's.
///
/// # Not spacing
///
/// The row's gaps are `makeover-geometry`'s question and are absent for
/// [`row_rules`]'s reason. What is here is `display`, which carries no
/// magnitude, and the muted readout, which is the same claim `picture-caption`
/// makes: it says where you are among the children and it is not one of them.
fn showing_rules(opts: &Emit) -> String {
    let controls = class("showing", opts);
    let position = class("showing-position", opts);
    let frame = class("showing-frame", opts);
    let mut css = String::new();

    // Hidden until something binds it, which is the whole argument above.
    let _ = writeln!(css, ".{controls} {{\n    display: none;\n}}");
    // Block, and nothing about how the three sit in it. A button and a span are
    // inline already, so they make a row without this crate saying so, and
    // saying so is where `align-items` and a gap would follow -- both spacing,
    // both `makeover-geometry`'s, and `row_rules` refuses them for the same
    // reason.
    let _ = writeln!(
        css,
        "[data-ready] > .{controls} {{\n    display: block;\n}}"
    );

    // A child is in flow until the region is bound, and then only the current
    // one is. `.current` is a modifier for the reason `.chosen` and `.latched`
    // are: one name for the state, set by whoever knows it.
    let _ = writeln!(
        css,
        "[data-ready] > .{frame}:not(.current) {{\n    display: none;\n}}"
    );

    // Reads back one step. `picture-caption`'s rule and its reason.
    let _ = writeln!(css, ".{position} {{\n    color: var(--content-muted);\n}}");

    css
}

/// A time axis: the container, its gridlines and ruler, and the placed things.
///
/// [`Track`](makeover_layout::Track), the one member here whose whole point is
/// *position*. That makes the magnitude line this crate keeps worth restating
/// rather than assuming.
///
/// # Where the numbers come from
///
/// Every value that varies per item is a custom property the caller sets
/// inline, and every rule here reads one. `--track-at` and `--track-for` are
/// percentages of the span, which
/// [`Track::fraction`](makeover_layout::Track::fraction) computes once so three
/// renderers cannot disagree about it. Nothing here knows a pixel.
///
/// That is what lets the stylesheet stay static while the items move: an entry
/// carries `style="--track-at: 37.5%; --track-for: 4.166%"` and the rule below
/// turns it into a box. The alternative was emitting a rule per item, which is
/// a stylesheet that grows with the data.
///
/// **The height of the track is the app's**, not this crate's. 96 quarter-hour
/// slots at some slot height is a size, and a size is `makeover-geometry`'s
/// question -- the same refusal `figure_rules` and `placeholder_rules` make.
/// Percentages need a resolved height above them, so `.track` gets
/// `position: relative` and nothing else; the app says how tall a day is.
///
/// # Overlap
///
/// Two things at the same time is intrinsic to an axis and has no analogue in a
/// list. The description does not declare it -- `Placement::overlaps` derives it
/// from the times -- so what arrives here is a lane index and a lane count, and
/// the rule divides the width. A renderer that would rather stack them ignores
/// both properties and the defaults give it one full-width lane.
fn track_rules(opts: &Emit) -> String {
    let track = class("track", opts);
    let slot = class("track-slot", opts);
    let tick = class("track-tick", opts);
    let entry = class("track-entry", opts);
    let mut css = String::new();

    // The positioning context every entry resolves against, and the whole of
    // what this crate says about the container. No height: see the doc above.
    let _ = writeln!(css, ".{track} {{\n    position: relative;\n}}");

    // Gridlines and the ruler are the axis reading itself back, which is
    // `picture-caption` and `showing-position`'s claim: about the thing rather
    // than one of the things.
    //
    // `border_width` rather than a literal, the way `depth_rule` writes its
    // edge. A gridline is the one place a timeline would most naturally reach
    // for a hardcoded 1px, and a hardcoded 1px is this crate naming a size.
    let _ = writeln!(
        css,
        ".{slot} {{\n    border-top: {} solid var(--border);\n}}",
        opts.border_width
    );
    let _ = writeln!(css, ".{tick} {{\n    color: var(--content-muted);\n}}");

    // The one rule that does real work. Top and height are the placement;
    // left and width are the lane. Both lane properties default so an entry
    // that names neither is full width, which is the common case and the one a
    // renderer gets for free.
    let _ = writeln!(
        css,
        ".{entry} {{\n    \
         position: absolute;\n    \
         top: var(--track-at, 0%);\n    \
         height: var(--track-for, 100%);\n    \
         left: calc(var(--track-lane, 0) / var(--track-lanes, 1) * 100%);\n    \
         width: calc(100% / var(--track-lanes, 1));\n\
         }}"
    );

    css
}

/// A region's stand-in, and the header of a table that can be reordered.
///
/// Both are colour and affordance only, the same place `figure_rules` lands:
/// emitting a type scale is not this crate's. How much room
/// a stand-in gets is a size — goingson has the same one at three, as
/// `--compact`, `--dashboard` and `--padded` — and a size is
/// `makeover-geometry`'s question.
///
/// The caret is the one thing here that is neither colour nor affordance, and it
/// is a renderer's own expression rather than a value the description named:
/// `aria-sort` is what the table actually says, and this turns it into something
/// visible for everyone not using a screen reader. A terminal draws its own; an
/// immediate-mode painter draws its own.
fn state_rules(opts: &Emit) -> String {
    let placeholder = class("placeholder", opts);
    let text = class("placeholder-text", opts);
    let heading = class("table-heading", opts);
    let mut css = String::new();

    let _ = writeln!(
        css,
        ".{placeholder} > .{text} {{\n    color: var(--content-muted);\n}}"
    );
    // Only the failure is toned. An empty list is the normal state of a new
    // install, and `Readiness::tone` is what says so.
    let _ = writeln!(
        css,
        ".{placeholder}[data-tone=\"{0}\"] > .{text} {{\n    color: var(--{0});\n}}",
        Tone::Danger.token()
    );
    // The way out stands a group apart from the sentence it answers. A gap
    // step rather than a size: how much room the stand-in gets is still the
    // app's.
    let _ = writeln!(
        css,
        ".{placeholder} > .{} {{\n    margin-block-start: var(--gap-group);\n}}",
        class("placeholder-action", opts)
    );

    // A header that reorders the table is a control, and the pointer is the
    // only part of saying so that is not the app's own type and spacing.
    let _ = writeln!(
        css,
        ".{heading}[data-sortable] {{\n    cursor: pointer;\n}}"
    );
    // The caret carries its own leading space, the way `makeover-tui` and
    // `makeover-immediate` both write `" \u{25B2}"`. It used to be emitted bare,
    // and both apps that adopted the vocabulary had to put the gap back in their
    // own stylesheets on the same afternoon -- each having to work out first that
    // app CSS outranks this crate's cascade layer, so adding the space the
    // obvious way, as `content`, silently wins over the glyph and leaves the
    // heading with no caret at all. A consumer should not have to know that, and
    // with the space emitted here there is nothing left for one to add.
    //
    // Three states, three tones, on the convention in wiki
    // `three-tone-convention`. A column in force is `content`; a column offering
    // to reorder and not doing it now is `content-secondary`, because it still
    // answers a press; a column that is not sortable emits no caret at all and
    // takes nothing. The idle arm used to hide its glyph and reserve the box,
    // which cost a reflow-free press and said nothing. It draws now, and the
    // reservation stops being a thing to get right.
    //
    // The glyph is `Sort::glyph`, escaped rather than written: a CSS `content`
    // string cannot carry the character literally through this file's own
    // escaping, and spelling it here as well would put the third copy back that
    // `makeover-layout` 0.27.5 exists to remove.
    //
    // On the heading's `.cell-in`, so the caret sits beside the label inside
    // its padding rather than at the far edge of a column that grew.
    let cell_in = class("cell-in", opts);
    let _ = writeln!(
        css,
        ".{heading}[data-sortable] > .{cell_in}::after \
         {{\n    content: \" {}\";\n    color: var(--content-secondary);\n}}",
        css_escape(Sort::Ascending.glyph())
    );
    for direction in [Sort::Ascending, Sort::Descending] {
        let _ = writeln!(
            css,
            ".{heading}[aria-sort=\"{}\"] > .{cell_in}::after \
             {{\n    content: \" {}\";\n    color: var(--content);\n}}",
            direction.as_str(),
            css_escape(direction.glyph())
        );
    }
    css
}

/// The component layer: every named thing phase A emits.
///
/// No scrollbar track. It was on the phase A list and came off: eight lines of
/// `::-webkit-scrollbar` with no shape a terminal or an immediate-mode painter
/// would want handed to it, so it stays with the apps.
#[must_use]
pub fn component_rules(opts: &Emit) -> String {
    let mut css = String::new();
    css.push_str(&surface_rules(opts));
    css.push_str(&link_rules(opts));
    css.push_str(&token_rules(opts));
    css.push_str(&selector_rules(opts));
    css.push_str(&row_rules(opts));
    css.push_str(&run_rules(opts));
    css.push_str(&progress_rules(opts));
    css.push_str(&chart::rules(opts));
    css.push_str(&awaiting_rules(opts));
    css.push_str(&figure_rules(opts));
    css.push_str(&facts_rules(opts));
    css.push_str(&picture_rules(opts));
    css.push_str(&showing_rules(opts));
    css.push_str(&track_rules(opts));
    css.push_str(&state_rules(opts));
    css.push_str(&table_rules(opts));
    css.push_str(&facet::facet_rules(opts));
    css.push_str(&form::group_rules(opts));
    css.push_str(&form::editor_rules(opts));
    css.push_str(&form::suggestion_rules(opts));
    css.push_str(&form::unit_rules(opts));
    css.push_str(&form::option_detail_rules(opts));
    css.push_str(&form::note_rules(opts));
    css.push_str(&leaving_rules());
    css
}

/// How a transient notice goes away.
///
/// `makeover-timing` says that `Intent::Dismiss` is how long a notice lives
/// *before it starts to leave*, and that the leaving itself is `Motion::Fade`.
/// `makeover-build` writes `--motion-fade` into every consumer's `timing.css`,
/// and this is the rule that reads it. Removing the node the moment the dismiss
/// is up skips the leaving entirely.
///
/// # Why an attribute and not a class
///
/// [`Emit`]'s prefix moves every class this crate writes, so a class here would
/// have to be resolved through `class()` by whoever sets it -- and the party
/// setting it is a script, which has no prefix to hand. `data-leaving` is
/// outside that namespace, so a renderer can set it from JavaScript with no
/// coordination.
///
/// The transition sits on the notice and the opacity on the leaving state, so
/// the element is transitionable before the attribute arrives; a transition
/// declared in the same rule as the value it changes has nothing to animate
/// from.
///
/// # Reduced motion is handled by the token, not by a second rule here
///
/// `timing.css` already zeroes `--motion-fade` under `prefers-reduced-motion`.
/// The reader who asked for less motion gets an instant change rather than a
/// fade, and the renderer that sets the attribute must still remove the node on
/// a timer rather than on `transitionend` -- a zero-length transition may fire
/// no event at all, and a node waiting on one that never comes stays forever.
///
/// The fallback is `0ms` and not a guessed duration: a page with no timing
/// sheet has not opted into this vocabulary, and the honest answer there is the
/// behaviour it had before, which is the notice going away at once.
fn leaving_rules() -> String {
    let mut css = String::new();
    let _ = writeln!(
        css,
        "[data-notice] {{\n    transition: opacity var(--motion-fade, 0ms) \
         ease-out;\n}}"
    );
    let _ = writeln!(css, "[data-notice][data-leaving] {{\n    opacity: 0;\n}}");
    css
}

/// The whole phase-A stylesheet: properties, depth rules and components, in
/// [`CSS_LAYER`], under a generated-file banner.
///
/// The banner sits outside the layer, because a comment participates in no
/// cascade and a reader opening the file should see what it is before seeing
/// an at-rule.
#[must_use]
pub fn stylesheet(opts: &Emit) -> String {
    let body = in_css_layer(&format!(
        ":root {{\n{}}}\n\n{}\n{}",
        bevel_properties(opts),
        depth_rules(opts),
        component_rules(opts)
    ));
    // Counted from the body rather than through `vocabulary::names`, which
    // calls back into here.
    let classes = vocabulary::classes_in_css(&body).len();
    let version = VERSION;
    format!(
        "/* Generated by makeover-webview {version} from makeover-layout, \
         {classes} classes.\n   \
         Do not edit. The version and the count are here because a stale\n   \
         lockfile fails silently: an older emitter writes a well-formed sheet\n   \
         with components missing, and nothing else in the file says so. If\n   \
         this version trails what the manifest asks for, re-resolve.\n\n   \
         Depth is a fill and an edge together; naming them apart is what let\n   \
         them disagree. See the crate's README and wiki note makeover-layout.\n\n   \
         Everything below is in the `{CSS_LAYER}` cascade layer. Declare the\n   \
         order once in your own stylesheet, or this layer's position is decided\n   \
         by whichever generated file the browser happens to see first:\n\n   \
         @layer {CSS_LAYER}, base, components, responsive; */\n{body}"
    )
}

#[cfg(test)]
mod tests;