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
//! [`list::narrowing_css`] and [`list::grid_template_columns`] 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 lays itself out
//!
//! [`list::narrowing_css`] emits the track list and has to be called with the
//! columns, so it works where the columns are known at build time. A table a
//! description produced knows its columns at render time, and the rules would
//! have to travel with the markup: a `<style>` element per table, which needs
//! `style-src 'unsafe-inline'`, or the head, which an htmx fragment swap does
//! not carry. [`table_rules`] lays a table out with `display: table` instead,
//! which aligns columns across rows knowing nothing about how many there are.
//! [`Priority`](makeover_layout::Priority) hiding is one rule per drop class,
//! and [`list::column_classes`] is what puts those classes on a cell. **A header
//! row emitted by a renderer's own code has to call it too**, or the header and
//! the body disagree about which column just dropped.
//!
//! `.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.
//!
//! `.card` and `.button` are the same depth *and* controls, and they take their
//! states from [`surface_rules`], which is where a state belongs: on the thing
//! that claims to answer a pointer.
//!
//! # 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;

/// 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: goingson builds
// `tables.css` in its own build.rs from [`list::narrowing_css`], and those
// rules are as generated as the ones here.
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,
    /// Prefix for emitted class names, without the leading dot.
    pub class_prefix: &'static str,
}

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

/// 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",
    }
}

/// 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;
    format!(
        "inset {w} {w} 0 var(--{}), inset -{w} -{w} 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] {
        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 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
}

/// 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: `.card` and `.button` are the
/// same depth *and* controls, and they 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.
fn surface_rules(opts: &Emit) -> String {
    let mut css = String::new();
    for name in ["button", "card"] {
        let c = class(name, opts);
        css.push_str(&depth_rule(&c, Depth::Raised));
        css.push_str(&interactive_rules(&c, 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));

    // 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
    );
    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 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.
    let _ = writeln!(css, ".{badge} {{\n    color: var(--content-muted);\n}}");
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{badge}[data-tone=\"{0}\"] {{\n    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.
    //
    // Colour and not a fill, matching the badge. A red surface is a decision
    // about emphasis that belongs to an app's own layer, and two of them
    // fighting is worse than neither.
    let button = class("button", opts);
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{button}[data-tone=\"{0}\"] {{\n    color: var(--{0});\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 };
    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));
        css.push_str(&depth_rule(&format!("{c}.chosen"), selector.chosen()));
    }
    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)
    );

    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`, which is exact. The browser wraps
/// the run when the members no longer fit, deciding that from their own
/// intrinsic widths, which is the derived minimum doing the whole job.
///
/// [`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}}");
        }
    }

    // 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 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.
    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 arrangement and the type scale are 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.
fn figure_rules(opts: &Emit) -> String {
    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();

    // `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.
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{figure}[data-tone=\"{0}\"] > .{change} {{\n    color: var(--{0});\n}}",
            tone.token()
        );
        let _ = writeln!(
            css,
            ".{figure}[data-tone=\"{0}\"]:not(:has(> .{change})) > .{value} \
             {{\n    color: var(--{0});\n}}",
            tone.token()
        );
    }
    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()
    );

    // 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.
    let _ = writeln!(
        css,
        ".{heading}[data-sortable]::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=\"{}\"]::after \
             {{\n    content: \" {}\";\n    color: var(--content);\n}}",
            direction.as_str(),
            css_escape(direction.glyph())
        );
    }
    css
}

/// The frame a table sits in.
///
/// # Why this is a CSS table and not the grid the rest of the module assumes
///
/// A grid row needs `grid-template-columns`, which has to name every column in
/// order, so it cannot be written without knowing the columns. That is what
/// [`list::narrowing_css`] is for, and it works: goingson builds `tables.css` in
/// its own `build.rs` out of it, and nothing here changes that.
///
/// It does not work for a table a *description* produced. Those columns are
/// known at render time rather than at build time, and the rules would have to
/// travel with the markup: a `<style>` element per table, which needs
/// `style-src 'unsafe-inline'` and so blocks the MNW server's standing plan to
/// drop it. The head is not an escape: a table swapped in by htmx after a
/// delete arrives as a fragment with no head at all.
///
/// A CSS table aligns its columns across rows knowing nothing about how many
/// there are, so there is no track list to emit and nothing per-table to carry.
/// The cost is that a described table cannot take a per-column fixed length,
/// which costs nothing today: [`Sizing`](list::Sizing) is looked up by column
/// name and a description carries no lengths to put in it, so every track a
/// described table could ask for is already content, fill or auto.
///
/// [`Priority`] hiding is unchanged in kind. It moves from a generated
/// `display: none` per dropped column to one rule per drop class, which is the
/// same fact addressed by class rather than by cutoff, and still never by
/// position.
fn table_rules(opts: &Emit) -> String {
    let table = class("table", opts);
    let head = class("table-head", opts);
    let row = class("table-row", opts);
    let heading = class("table-heading", opts);
    let cell = class("cell", opts);
    let mut css = String::new();

    // The table model, wiki `table-model`: specimen C with D's header strip, as
    // Max picked it off rendered specimens. The table paints its own raised
    // ground inside a hairline frame, so the row tones hold whatever it sits
    // on. Text is the note size, 14px at the default base.
    let bw = opts.border_width;
    let _ = writeln!(
        css,
        ".{table} {{\n    display: table;\n    width: 100%;\n    \
         border-collapse: collapse;\n    border: {bw} solid var(--row-rule);\n    \
         background: var(--surface-raised);\n    font-size: var(--text-note);\n}}"
    );
    let _ = writeln!(css, ".{head},\n.{row} {{\n    display: table-row;\n}}");
    // A minimum rather than a height, since a table row grows to fit its
    // tallest cell: a cell holding more than a line grows the row.
    let _ = writeln!(css, ".{table} .{row} {{\n    height: var(--row-block);\n}}");

    // The header strip. Its ink goes on the heading row and is inherited,
    // because `state_rules` colours the sort caret on `.table-heading::after`
    // and a colour on the heading itself would override it. `content-secondary`
    // rather than muted: the strip separates the header now, so the label does
    // not have to stay quiet by being pale. The edge sits under the strip, as
    // in the specimen. Tracking is typography's to own and nothing in the
    // family owns it yet, so it is a property with the specimen's value behind it.
    let _ = writeln!(
        css,
        ".{table} .{head} {{\n    color: var(--content-secondary);\n}}"
    );
    let _ = writeln!(
        css,
        ".{table} .{heading} {{\n    background: var(--surface-sunken);\n    \
         border-bottom: {bw} solid var(--bevel-dark);\n    font-size: var(--text-fine);\n    \
         font-weight: bold;\n    letter-spacing: var(--table-heading-tracking, 0.06em);\n    \
         text-transform: uppercase;\n    text-align: start;\n    vertical-align: bottom;\n    \
         white-space: nowrap;\n    padding: var(--gap-peer) var(--gap-group);\n}}"
    );

    // Rows: a hairline between rows, a stripe on alternate rows, and a hover,
    // at every row count. Between rows and not above the first, where the
    // header's edge already draws the line.
    let _ = writeln!(
        css,
        ".{table} .{row} > .{cell} {{\n    padding: var(--gap-bound) var(--gap-group);\n    \
         vertical-align: middle;\n}}"
    );
    let _ = writeln!(
        css,
        ".{table} .{row} + .{row} > .{cell} {{\n    border-top: {bw} solid var(--row-rule);\n}}"
    );
    // Parity of rows, never position of columns: the stripe alternates by what
    // a row is, and `of .{row}` keeps a header row out of the count.
    let _ = writeln!(
        css,
        ".{table} .{row}:nth-child(even of .{row}) {{\n    background: var(--row-stripe);\n}}"
    );
    let _ = writeln!(
        css,
        "@media (hover: hover) and (pointer: fine) {{\n    \
         .{table} .{row}:hover {{\n        background: var(--row-hover);\n    }}\n}}"
    );
    // Scoped under `.{table}` rather than keyed on the classes alone. The
    // table model is what a cell takes *by being in a table*, and only there:
    // goingson's task headings are `.table-heading` inside a CSS grid, so the
    // unscoped rule reached them, and the sort caret and the sortable cursor
    // -- which `state_rules` keys on `.table-heading` and rightly still does
    // -- came with a `display` the grid had to blockify away.
    //
    // It costs no markup anywhere: quasi-webview always nests the heading
    // inside the table (`quasi-webview/src/node.rs:1591`, `:1605`, `:1615`).
    let _ = writeln!(
        css,
        ".{table} .{heading},\n.{table} .{cell} {{\n    display: table-cell;\n}}"
    );

    // A content column shrinks to what is in it. `width: 1%` is how a CSS table
    // is told that: auto layout hands the slack to the columns that asked for
    // room, and a column asking for almost none gets what it needs and no more.
    // The `nowrap` is what stops it being given less by wrapping.
    let _ = writeln!(
        css,
        ".{} {{\n    white-space: nowrap;\n    width: 1%;\n}}",
        class("cell-content", opts)
    );

    // A fixed column has no length to be fixed to. The description carries none
    // and `Sizing` is not reachable from here, so it behaves as content: the
    // honest answer to a width nobody supplied, and the same one `Sizing::track`
    // gives it.
    let _ = writeln!(
        css,
        ".{} {{\n    white-space: nowrap;\n}}",
        class("cell-fixed", opts)
    );

    // Optional columns go at the narrowest class, secondary ones go with them,
    // which is the cutoff walk `kept_at` describes said as two media queries.
    // Essential columns have no rule at all, because never dropping is what not
    // being mentioned already means.
    //
    // Scoped under `.{table}` for the same reason the cell's `display` is, and
    // because of it: `.table .cell` sits at (0,2,0), so a bare `.cell-drops-*`
    // at (0,1,0) lost to it in every table and no column ever dropped. At equal
    // specificity the drop comes later in the sheet and wins.
    for (size, drops) in [
        (
            SizeClass::Compact,
            &["cell-drops-first", "cell-drops-next"][..],
        ),
        (SizeClass::Medium, &["cell-drops-first"][..]),
    ] {
        let selectors: Vec<String> = drops
            .iter()
            .map(|drop| format!(".{table} .{}", class(drop, opts)))
            .collect();
        css.push_str(&gated(
            Some(&size.media_condition()),
            &format!("{} {{\n    display: none;\n}}\n", selectors.join(",\n")),
        ));
    }

    // What is inside a cell, which the table side could not say until
    // makeover-layout 0.14.0. Every cell was one `.cell` and one content
    // colour, so a button in a cell was painted as text -- the drift
    // `RowPart::intent` has prevented for list rows since 0.2.0 and prevented
    // for nothing here.
    //
    // The colour goes on `.cell-value` rather than on `.cell`, and that
    // placement is the whole fix. On the container it would cascade into the
    // tokens and the controls sitting beside the text, which is the bug said
    // in one rule; on the part that is text, it reaches text and stops.
    for part in [
        CellPart::Value,
        CellPart::Tokens,
        CellPart::Actions,
        CellPart::Link,
    ] {
        // Two of the four inherit: a token carries its own tone and an action
        // is a control rather than text. A link is text, the title of its row,
        // so it takes its intent like a value does. Left to inherit, it took
        // nothing: the colour is on `.cell-value` rather than on `.cell`, and an
        // anchor with no colour of its own draws in the browser's link blue.
        //
        // Written as a skip-list rather than as a match on Value, so a member
        // added upstream gets its intent emitted rather than being silently
        // dropped. That is the same trade `part_class`'s fallback makes: land
        // plainly, never land as nothing.
        if !matches!(part, CellPart::Tokens | CellPart::Actions) {
            // The underline says "this goes somewhere" in running text. In a
            // table the row already says it, by being the thing that activates.
            let underline = if part == CellPart::Link {
                "\n    text-decoration: none;"
            } else {
                ""
            };
            let _ = writeln!(
                css,
                ".{} {{\n    color: var(--{});{underline}\n}}",
                class(cell_part_class(part), opts),
                part.intent()
            );
        }
    }

    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(&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::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;