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
//!
//! The stylesheet half needs no markup of the app's to change: an app that
//! writes its own markup keeps every line of it and gains the classes, which is
//! why adopting the generated stylesheet is not a migration.
//!
//! Adoption is not a deletion either. A rule loses its depth declarations and
//! gains a variant selector next to it, so an app's file stays about the same
//! size. What moves is where depth is defined, not how much CSS exists.
//!
//! 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's names, and the hosts' markup
//!
//! The vocabulary's members (fields, choices, columns, figures, meters, charts,
//! acts and the rest) are drawn by the quasi hosts: `quasi-webview` for this
//! renderer. What phase B keeps here is everything those hosts and the
//! hand-written apps have to agree with this crate about:
//!
//! - [`form`]: the one escaper, [`form::Markup`] and [`form::Filling`], the
//!   field classes and the rules behind them. One function covers element text
//!   and attribute values, where the apps needed four and had to choose
//!   correctly at every call site.
//! - [`list`]: column names as classes, the kind, part and flow classes, the
//!   cell wrapper and sizer, and the `short-N` and `stacks-N` ladders a table
//!   narrows and stacks by.
//! - [`chart`], [`figure`], [`meter`]: class lists and rules only.
//! - [`facet`] renders `makeover_layout::Facet` itself: 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.
//! - [`placeholder`] draws the stand-in a region shows while it has nothing.
//!
//! Every class a host's markup can carry is in one of the modules' class lists,
//! and [`vocabulary::names`] is their union with the generated sheet.
//!
//! # 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-layout`'s `Affordance`
//! answers whether a fingertip has hover and `makeover-geometry` spells the condition; this crate
//! asks and does not decide, so no app has to take the hover state back on
//! touch.
//!
//! # The layer contract
//!
//! [`stylesheet`] emits into the `makeover` cascade layer ([`CSS_LAYER`], which
//! lives in `makeover-geometry` because that is the one crate every CSS emitter
//! in the family already depends on). `makeover-geometry` does the same for
//! `geometry.css`.
//!
//! The cascade resolves origin and importance, then layer, then specificity,
//! then source order, and **unlayered normal declarations outrank every named
//! layer**. An unlayered generated file therefore beats every rule an app owns,
//! regardless of specificity and regardless of loading last. Nothing errors when
//! that happens: the CSS is valid, the minifier is happy, and buttons and badges
//! look subtly wrong. The layer belongs here rather than in each app, because an
//! app cannot fix it from its own stylesheet: the fix is to layer the file it
//! does not own.
//!
//! An app should declare the order once, or the layer's position is decided by
//! whichever generated file the browser happens to see first:
//!
//! ```css
//! @layer makeover, base, components, responsive;
//! ```
//!
//! [`in_css_layer`] is re-exported for an app that assembles its own stylesheet
//! from this crate's pieces: rules an app generates from them are as generated
//! as the ones here, so they belong in the same layer and this crate cannot put
//! them there on the app's behalf.
//!
//! # Form rules
//!
//! The field markup is the hosts', and the look is this crate's, because a
//! renderer inventing how a label or an error reads is the drift the
//! vocabulary check exists to catch. A few rules spend a mark the markup
//! carries rather than a class:
//!
//! - A markdown field is marked `data-format="markdown"`, and
//!   `form::editor_rules` 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. **This crate renders
//!   no markdown**: the pane is filled by whatever binds the editor, which is
//!   where the host's sanitiser already is.
//! - A suggestion's second line, `.form-suggestion-detail`, 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, `.form-option-detail` and `.form-unit` included.
//! - An unavailable option's reason is `.form-option-reason`, and a group with
//!   an error carries `has-error` while its message carries `visible`
//!   ([`form::FIELD_STATE_CLASSES`]).
//!
//! # A cell says what it holds
//!
//! [`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
//! [`Prominence::intent`](makeover_layout::Prominence) prevents for list rows.
//!
//! A cell's part is a [`CellPart`] and never a [`Prominence`]: the two answer
//! different questions, and only one of them is about a cell.
//!
//! # A table narrows itself
//!
//! A table a description produced knows its columns at render time, so no rule
//! can be written per table: it would have to travel with the markup, as a
//! `<style>` element that needs `style-src 'unsafe-inline'` or in a head an htmx
//! fragment swap does not carry. `table_rules` lays every table out as flex
//! rows instead, each column starting at its declared floor and giving up room
//! by its [`Priority`](makeover_layout::Priority), so the browser narrows a
//! table at the width its floors add up to. A host puts the column's classes
//! on every cell (its name through [`list::push_column_name`], its width and
//! drop tiers from [`list::CELL_WIDTH_CLASSES`] and [`list::CELL_DROP_CLASSES`],
//! its kind from [`list::kind_class`]), and every cell's contents go in
//! [`list::CELL_IN`]. **A header row emitted by a renderer's own code has to do
//! both too**, or the header and the body disagree about which column just
//! closed and how wide the rest are.
//!
//! `.button` takes the four tones as colour, off `data-tone`, the way the badge
//! does, so a destructive button has somewhere for its tone to land. A list is
//! reset rather than left as a bulleted list.
//!
//! A row's actions are never revealed on hover. Hiding them until
//! hover hides them from pointer users alone, who are the ones scanning a list
//! to learn what can be done to a row, and every escape the rule grows
//! (`focus-within` for the keyboard, a capability gate for a fingertip) is a
//! report that hiding was wrong for somebody.
//!
//! # The depth classes are not controls
//!
//! `.raised` is a statement about shape and carries no interactive set, so the
//! vocabulary has a raised surface that is merely an object. An app that wants
//! one does not have to take a control class and cancel the control half.
//!
//! `.button` is the same depth *and* a control, and takes its states from
//! `surface_rules`, which is where a state belongs: on the thing that claims
//! to answer a pointer. `.card` is a raised object, and it answers a pointer
//! only when the element it is written on is a control, `a`, `button`,
//! `label`, or anything carrying `data-act`, so one name serves the card
//! that is read and the card that is pressed.
//!
//! # Substitution, three ways
//!
//! A theme with no `surface-well` is answered differently by each renderer,
//! which is why substitution belongs to a renderer and not to the description:
//!
//! - `makeover-immediate` substitutes the page in Rust.
//! - `makeover-tui` refuses to substitute and draws an edge instead, because a
//!   terminal would quantise the two together.
//! - here, CSS already has the mechanism: `var(--surface-well,
//!   var(--surface-page))` falls back in the browser, and nothing in Rust
//!   decides anything.

#![forbid(unsafe_code)]

#[cfg(feature = "build")]
pub mod build;
pub mod chart;
mod css_lex;
pub mod facet;
pub mod figure;
pub mod form;
pub mod list;
pub mod meter;
pub mod placeholder;
pub mod reset;
pub mod vocabulary;

mod table;
use table::table_rules;

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

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

/// How the emitted CSS and markup are shaped, and the copy they carry.
///
/// Built with [`Emit::new`] and its setters. `#[non_exhaustive]`, so a new
/// knob is not a breaking change for anyone who configures one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct Emit {
    /// Bevel thickness, as a CSS length.
    ///
    /// A value, so it arrives from the caller: this crate names no sizes of its
    /// own. The default is `makeover_geometry::Stroke::Hairline`, and
    /// [`focus_width`](Self::focus_width)'s is `Stroke::Mark`; a test holds
    /// both equal to the scale.
    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, 2px, is what every consumer had chosen for its own ring.
    pub focus_width: &'static str,
    /// The smallest a target may be drawn, as a CSS length.
    ///
    /// A value for [`border_width`](Self::border_width)'s reason: a floor is a
    /// size, and this crate names no sizes of its own.
    ///
    /// The default reads `makeover_geometry`'s density-aware floor (24px under
    /// a pointer, 44px under touch), falling back to WCAG 2.2's 24px where the
    /// geometry layer is absent. An absolute, never a step: a floor that scales
    /// with the reader's root size is not a floor.
    pub target_min: &'static str,
    /// Prefix for emitted class names, without the leading dot.
    pub class_prefix: &'static str,
    /// What marks a compulsory field, appended to its label.
    ///
    /// `makeover-tui`'s `PieceStyle::required_marker` and
    /// `makeover-immediate`'s `FieldStyle::required_marker`, said here for the
    /// third renderer, with their default. A knob for their reason: it is the
    /// one piece of *copy* this crate emits, and copy is not a renderer's
    /// call.

    ///
    /// # Why it is hidden from the accessibility tree here and nowhere else
    ///
    /// The control already carries `required`, which a screen reader
    /// announces. A marker read out beside it is the same fact twice, so the
    /// span is `aria-hidden`. The other two renderers have no such attribute
    /// to lean on, which is why the marker is part of the label string there
    /// and an element here.
    pub required_marker: &'static str,
    /// The accessible name's lead on a facet value's exclude button, before
    /// the value's own label: "Exclude Drums". Copy, for
    /// [`required_marker`](Self::required_marker)'s reason.
    pub exclude_label: &'static str,
    /// The markdown editor's two modes, as the segments say them.
    pub write_label: &'static str,
    /// See [`write_label`](Self::write_label).
    pub preview_label: &'static str,
    /// The accessible names of an interval's two boxes.
    pub lower_label: &'static str,
    /// See [`lower_label`](Self::lower_label).
    pub upper_label: &'static str,
    /// The words a facet group's join toggle offers: picks under it combine
    /// when any of them holds, or only when all do.
    pub any_label: &'static str,
    /// See [`any_label`](Self::any_label).
    pub all_label: &'static str,
    /// The accessible name's lead on a join toggle, before the group's label:
    /// "Combine picks under Genre".
    pub join_label: &'static str,
    /// What marks the group a newcomer should start with.
    pub start_label: &'static str,
    /// What a ranked group says when a pick inside it is already in force.
    pub in_use_label: &'static str,
    /// What a ranked group says when no pick inside it would leave anything.
    pub dead_label: &'static str,
}

impl Emit {
    /// The defaults: the measured widths above, no prefix, and English copy.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            border_width: "1px",
            focus_width: "2px",
            target_min: "var(--target-least, 24px)",
            class_prefix: "",
            required_marker: "*",
            exclude_label: "Exclude",
            write_label: "Write",
            preview_label: "Preview",
            lower_label: "lower",
            upper_label: "upper",
            any_label: "any",
            all_label: "all",
            join_label: "Combine picks under",
            start_label: "start here",
            in_use_label: "in use",
            dead_label: "no effect",
        }
    }
}

/// One setter per field, named after it, for building an [`Emit`] outside this
/// crate: `Emit::new().class_prefix("mk-")`.
macro_rules! setters {
    ($($field:ident),* $(,)?) => {
        impl Emit {
            $(
                #[doc = concat!("Set [`", stringify!($field), "`](Self::", stringify!($field), ").")]
                #[must_use]
                pub const fn $field(mut self, value: &'static str) -> Self {
                    self.$field = value;
                    self
                }
            )*
        }
    };
}

setters!(
    border_width,
    focus_width,
    target_min,
    class_prefix,
    required_marker,
    exclude_label,
    write_label,
    preview_label,
    lower_label,
    upper_label,
    any_label,
    all_label,
    join_label,
    start_label,
    in_use_label,
    dead_label,
);

impl Default for Emit {
    fn default() -> Self {
        Self::new()
    }
}

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

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

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

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

/// The custom properties both bevels resolve through.
///
/// Emitted as properties rather than inlined into every rule because that is
/// what the apps already do, and because a consumer that wants the edge
/// without the fill reads the property directly.
#[must_use]
pub fn bevel_properties(opts: &Emit) -> String {
    let mut css = String::new();
    for bevel in [Bevel::Raised, Bevel::Inset, Bevel::RaisedOpen] {
        let _ = writeln!(
            css,
            "    {}: {};",
            bevel_var(bevel),
            bevel_shadow(bevel, opts)
        );
    }
    let _ = writeln!(css, "    {OPEN_SIDE_VAR}: {};", open_side_shadow(opts));
    css.push_str(ELEVATION_PROPERTY);
    // The edge a surface draws when its depth alone does not separate it: a
    // field, a button, a card, a toast. One shorthand, so no rule spells out
    // its own `1px solid`.
    let _ = writeln!(
        css,
        "    --edge-control: {} solid var(--border);",
        opts.border_width
    );
    css
}

/// The property holding [`Bevel::RaisedOpen`] turned a quarter.
///
/// Which run of an open bevel is left off is the arrangement's, not the edge's:
/// the run facing the surface the tab opens into. A strip across its pane
/// opens downward, which is the composition under [`bevel_var`]; a strip
/// running down beside its pane opens toward the inline end, and this is that.
/// Not a member of [`Bevel`], for the reason [`Selector`] carries no direction:
/// the description says what joins, and the renderer drawing the arrangement
/// says which side.
const OPEN_SIDE_VAR: &str = "--bevel-raised-open-side";

/// [`bevel_shadow`] for a tab that joins its pane on the inline-end side.
///
/// The lit run stays on top and left, and the shaded run drops its horizontal
/// offset instead of its vertical one, so it lands on the bottom alone and the
/// right run is not drawn. Physical rather than logical sides, as every bevel
/// here is: `box-shadow` has no logical form.
fn open_side_shadow(opts: &Emit) -> String {
    let (top_left, bottom_right) = Bevel::RaisedOpen.edges();
    let w = opts.border_width;
    format!(
        "inset {w} {w} 0 var(--{}), inset 0 -{w} 0 var(--{})",
        top_left.token(),
        bottom_right.token()
    )
}

/// 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.
///
/// A hard offset with no blur, down and to the right: a Platinum menu sits
/// just off the page with a crisp edge, not hovering in a haze.
const ELEVATION_PROPERTY: &str = "    --elevation-overlay: 3px 3px 0 var(--elevation);\n";

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

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

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

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

/// The script that applies [`VARS_ATTR`], for a host to serve beside its other
/// assets.
///
/// Without it every number the rules read from that attribute is missing: bars
/// and charts flat, tree rows unindented, a split screen at even halves.
///
/// It also restores this device's density choice onto the root element
/// ([`DENSITY_STORE_KEY`] into
/// [`DENSITY_ATTRIBUTE`](makeover_geometry::DENSITY_ATTRIBUTE)) and answers a
/// [`DENSITY_CHOICE_ATTR`] picker, for the same reason it is not deferred: a
/// choice applied after first paint is a page that jumps. Serve
/// it as a classic script in the head, not deferred, so its observer is
/// running before the parser reaches the body and the first paint already has
/// every property.
///
/// ```no_run
/// # fn main() -> std::io::Result<()> {
/// std::fs::write("static/vars.js", makeover_webview::VARS_JS)?;
/// # Ok(())
/// # }
/// ```
pub const VARS_JS: &str = include_str!("vars.js");

/// The attribute a [`FieldKind::Density`](makeover_layout::FieldKind::Density)
/// picker carries, which is how [`VARS_JS`] finds it.
///
/// The picker is a `<select>` with this attribute and **no `name`**, so no
/// form or htmx request ever submits it: the device holds the answer, and the
/// script reads and writes it there.
pub const DENSITY_CHOICE_ATTR: &str = "data-density-choice";

/// The browser storage key a device's density choice is kept under.
///
/// The value is [`Density::attribute_value`](makeover_geometry::Density::attribute_value),
/// and an absent key is "follow detection". Per origin, which is per device
/// for a hosted app and per app for a desktop one: both are what the choice
/// is about.
pub const DENSITY_STORE_KEY: &str = "makeover-density";

/// Write the options of a density picker, in
/// [`DENSITY_CHOICES`](makeover_layout::DENSITY_CHOICES) order.
///
/// None is marked selected. The server cannot know what this device chose,
/// so [`VARS_JS`] sets the picker's value from storage as it arrives, which
/// is before first paint on a page load and on insertion after a swap.
///
/// ```
/// let mut out = String::new();
/// makeover_webview::density_options_into(&mut out);
/// assert!(out.starts_with("<option value=\"\">Automatic</option>"));
/// assert!(out.contains("<option value=\"touch\">Touch</option>"));
/// ```
pub fn density_options_into(out: &mut String) {
    for (density, label) in makeover_layout::DENSITY_CHOICES {
        out.push_str("<option value=\"");
        out.push_str(density.map_or("", makeover_geometry::Density::attribute_value));
        out.push_str("\">");
        form::escape_into(label, out);
        out.push_str("</option>");
    }
}

/// 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",
        // A selector this crate has not learned draws as tabs, the plainest
        // of the three, rather than as nothing.
        _ => "tab",
    }
}

/// 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-layout`'s
/// [`Affordance`] 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.
pub(crate) 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())
    }
}

/// The tones that carry a status, each of which a toned member draws.
pub(crate) const STATUS_TONES: [Tone; 4] = [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger];

/// The disabled state, native or announced, as one selector suffix.
pub(crate) const DISABLED: &str = ":is(:disabled, [aria-disabled=\"true\"])";

/// One `{selector}[data-tone="…"]` rule per status tone, `body` writing the
/// declarations for a tone token.
pub(crate) fn tone_rules(css: &mut String, selector: &str, body: impl Fn(&str) -> String) {
    for tone in STATUS_TONES {
        let tone = tone.token();
        let _ = writeln!(css, "{selector}[data-tone=\"{tone}\"] {{\n{}}}", body(tone));
    }
}

/// A status drawn as an edge on the start side, the words keeping their ink.
pub(crate) fn status_edge(width: &str, tone: &str) -> String {
    format!(
        "    border-inline-start: {width} solid var(--{tone});\n    \
         padding-inline-start: var(--step-snug);\n"
    )
}

/// A status drawn as a tinted ground edged in the tone.
fn toned_surface(tone: &str) -> String {
    format!("    background: var(--{tone}-surface);\n    border-color: var(--{tone});\n")
}

/// Put a rule inside a media query, or leave it alone.
pub(crate) 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{}    color: var(--{});\n    cursor: not-allowed;\n}}\n",
        rest_declarations(depth),
        State::Disabled.token()
    )
}

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

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

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

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

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

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

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

    // A multiline field shows its value, not a window onto it: a whole message
    // is content, not a scroll. `field-sizing: content` grows the `<textarea>`
    // with its value up to its container's ceiling; the floor is three lines,
    // the resting height and the answer for an engine without the property.
    // Scoped to `textarea`: a single-line input or select is already its own
    // size and must not grow. The floor rides a custom property the way the
    // table's `ch` floors do, so an app that wants a taller resting field says
    // so once instead of restyling the rule.
    let _ = writeln!(
        css,
        "textarea.{field} {{\n    field-sizing: content;\n    min-block-size: var(--field-min-lines, 3lh);\n}}\n"
    );

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

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

    // The default-button ring, on the one control that commits
    // (the act that commits, wiki `explicit-commit-affordance`).
    // A flush frame twice the border width, composed after the bevel for the
    // invalid ring's reason, and outside the element, so the focus outline,
    // which stands off by its own width, lands beside it rather than over it.
    // The label keeps the weight every button has: the ring is the whole mark,
    // and a bold label made the default a different width from its neighbours.
    // Pressed keeps the ring and inverts only the bevel. Disabled drops the
    // ring: the ring says "this is what Return does",
    // and a control Return cannot reach is not the default. goingson's bulk
    // bars are the site: Complete and Delete stand disabled until a row is
    // ticked, and ringed they read as the strongest controls on a page with
    // nothing selected.
    //
    // An attribute rather than a class, for `data-tone`'s reason: it is a fact
    // about the act, and a renderer writes it beside the tone.
    let ring = format!("0 0 0 calc(2 * {})", opts.border_width);
    let _ = writeln!(
        css,
        ".{button}[data-commits] {{\n    box-shadow: var({}), {ring} var(--border-strong);\n}}",
        bevel_var(Bevel::Raised)
    );
    let _ = writeln!(
        css,
        ".{button}[data-commits]:active {{\n    box-shadow: var({}), {ring} var(--border-strong);\n}}",
        bevel_var(Bevel::Inset)
    );
    let _ = writeln!(
        css,
        ".{button}[data-commits]{DISABLED} {{\n    box-shadow: var({});\n}}",
        bevel_var(Bevel::Raised)
    );

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

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

    let _ = writeln!(
        css,
        ".{link} {{\n    color: var(--action);\n    \
         text-decoration: underline;\n}}"
    );
    // The pointer-target floor, and the scope is the whole of the design in it.
    //
    // A bare `.link` is its own line box, 21px at the body size, under the
    // floor `Emit::target_min` names. Applied to every `.link`
    // that floor would reach an anchor set in running prose, where growing the
    // box sets the leading of the paragraph around it: the fix would cost more
    // than the defect. So it is scoped to a link laid out as a piece rather
    // than set in text, which in the emitted markup is one inside a run or a
    // cell, a footer strip, a row of places, a table cell.
    //
    // Both sides, since a one-word link can be narrower than the touch floor.
    // `min-block-size` rather than padding: padding adds to the line box and
    // grows whatever holds the link, where a minimum lets the anchor take room
    // its container usually already has. `inline-flex` is what makes the
    // minimum apply to an inline element at all, and `align-items: center`
    // keeps the text on the box's centre line rather than its top.
    let run = class("run", opts);
    let cell = class("cell", opts);
    let least = opts.target_min;
    let _ = writeln!(
        css,
        ".{run} .{link},\n.{cell} .{link} {{\n    display: inline-flex;\n    \
         align-items: center;\n    min-block-size: {least};\n    \
         min-inline-size: {least};\n}}"
    );
    // The hover step is the same one every other control takes, and it is a
    // colour rather than a surface: a link has no box to raise.
    css.push_str(&gated(
        hover_condition(),
        &format!(".{link}:hover {{\n    color: var(--action-hover);\n}}\n"),
    ));
    // The one ring, placed as on anything standing level with the page.
    css.push_str(&focus_rule(&link, Depth::Flat, opts));
    // 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`.
    //
    // A badge is a chip, wiki `table-model`: an opaque fill inside an edge, in
    // the theme's own ink at normal weight. Coloured text was never ratified
    // and measured 1.34:1 on goingson's warning; muted text 2.78:1 on
    // solarized-dark. So the ink is `content` and what says which kind of
    // token it is moves to the fill and the edge: the table's raised ground for
    // a neutral chip, makeover's `*-surface` for a status, edged in its tone.
    // Still no bevel: a label with a raised edge says it can be pressed.
    //
    // `inline-block`, not a flex row: a badge whose label outruns its column
    // ends in an ellipsis, and `text-overflow` reads the text as inline content
    // rather than as a flex item. `min-width: 0` overrides the flex-item
    // `min-width: auto`, which would otherwise hold the badge at its label's
    // full width and refuse to shrink to the ellipsis.
    let bw = opts.border_width;
    let _ = writeln!(
        css,
        ".{badge} {{\n    display: inline-block;\n    min-width: 0;\n    max-inline-size: 100%;\n    \
         overflow: hidden;\n    text-overflow: ellipsis;\n    white-space: nowrap;\n    \
         padding: 0 var(--step-snug);\n    border: {bw} solid var(--border);\n    \
         border-radius: var(--radius-fine);\n    background: var(--surface-raised);\n    \
         color: var(--content);\n    font-weight: normal;\n}}"
    );
    tone_rules(&mut css, &format!(".{badge}"), toned_surface);

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

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

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

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

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

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

    // A strip that runs down its pane joins it on the side, and the join above
    // is written for a strip that runs across. Which way a strip runs is not
    // on [`Selector`], and it should not be: it is the arrangement, and the
    // renderer drawing the arrangement is the one that knows.
    //
    // `aria-orientation` is how that renderer has to say it anyway. It is
    // ARIA's word rather than a private attribute, required on any vertical
    // tablist for a screen reader, so keying on it couples this to the
    // standard and not to one caller's markup.
    //
    // The join turned a quarter: the open run faces the pane at the inline end,
    // the pull is one border width toward it rather than down, and the corners
    // round on the side away from the pane. Every tab in the column takes those
    // corners, chosen or not, for the across strip's reason: the corners are
    // the strip's shape, not the chosen option's. The pane has to sit against
    // the strip for this to read, which is the arrangement sheet's to say.
    let _ = writeln!(
        css,
        "[aria-orientation=\"vertical\"] .{selector} {{\n    \
         border-radius: var(--radius-control) 0 0 var(--radius-control);\n}}"
    );
    let _ = writeln!(
        css,
        "[aria-orientation=\"vertical\"] .{selector}.chosen {{\n    \
         box-shadow: var({OPEN_SIDE_VAR});\n    \
         margin-block-end: 0;\n    \
         margin-inline-end: calc(-1 * {});\n}}",
        opts.border_width
    );

    // A column of tabs that has folded over its pane runs across it, so inside
    // a folded strip the join turns back: corners round at the top and the
    // chosen tab pulls down. The arrangement sheet decides when a column folds
    // and says so by naming the container; `aria-orientation` cannot, since it
    // describes the keys and not the drawing.
    let _ = writeln!(
        css,
        "@container {STRIP_CONTAINER} (inline-size < {STRIP_FOLD}) {{\n\
         [aria-orientation=\"vertical\"] .{selector} {{\n    \
         border-radius: var(--radius-control) var(--radius-control) 0 0;\n}}\n\
         [aria-orientation=\"vertical\"] .{selector}.chosen {{\n    \
         box-shadow: var({});\n    \
         margin-inline-end: 0;\n    \
         margin-block-end: calc(-1 * {});\n}}\n}}",
        bevel_var(Bevel::RaisedOpen),
        opts.border_width
    );
    css
}

/// The container a vertical tab strip's arrangement names when it can fold the
/// strip over its pane.
pub const STRIP_CONTAINER: &str = "tab-strip";

/// The inline size of [`STRIP_CONTAINER`] under which a vertical strip runs
/// across its pane. An arrangement that folds the strip folds at this width,
/// or the tabs draw one way while laid out the other.
pub const STRIP_FOLD: &str = "36rem";

/// The parts of a list row.
///
/// The list is written out rather than derived because `Prominence` 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))));

    // A run of badges, controls or a meter takes its holding class in place of
    // one of these, so the intent never sits under a thing that carries its
    // own colour.
    for part in [Prominence::Lead, Prominence::Support, Prominence::Quiet] {
        let c = class(part_class(part), opts);
        let _ = writeln!(css, ".{c} {{\n    color: var(--{});\n}}", part.intent());

        // A row's actions are shown at rest. A hover-reveal method 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.
    // makeover-layout names the concept `Nesting`, deliberately not `Depth`,
    // which is surface bevel in that crate, and this is the rule. Without it a
    // described outline in a browser is a flat list with chevrons in it: the
    // folding works and the indent does not exist.
    //
    // The magnitude is a custom property with a fallback, which is this crate's
    // own shape: `--awaiting-gap` above is the precedent, and an app overriding
    // `--row-indent` is how a level becomes worth more or less. What a level IS
    // stays the description's; what it is WORTH is a renderer's, and a terminal
    // spending columns for the same fact is not disagreeing.
    //
    // Here rather than in each app, and that was a live option rather than an
    // oversight. `row-select`, `row-current` and `row-chosen` are app-styled by
    // design; the indent is not decoration, it is what the description MEANS,
    // and three apps agreeing about it by accident is not agreement.
    //
    // `padding` and not `margin`: a row is a box that can be selected and
    // hovered, and indenting with margin would take the indent out of the
    // highlight, so the shading under a nested row would start where its text
    // does rather than where its row does.
    let _ = writeln!(
        css,
        ".{} {{\n    padding-inline-start: calc(var(--row-depth, 0) * var(--row-indent, 1.5ch));\n}}",
        class("row-nested", opts)
    );

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

    // How a part holds what is in it, for a row and for a table cell. Here
    // rather than in quasi-webview's arrangement sheet because these are names
    // this crate emits, so a row an app writes by hand gets them too. The row
    // itself stays quasi-webview's: where a part sits in the line is the screen
    // renderer's arrangement, and nothing here says it.
    //
    // A token or a control never breaks across two lines. What gives when the
    // line runs short is the row's text.
    let tokens = class(list::ROW_TOKENS, opts);
    let actions = class(list::ROW_ACTIONS, opts);
    let proportion = class(list::ROW_PROPORTION, opts);
    let fallback = class("row-part", opts);
    let cell_tokens = class(cell_part_class(CellPart::Tokens), opts);
    let cell_actions = class(cell_part_class(CellPart::Actions), opts);
    let cell_fallback = class("cell-part", opts);
    let _ = writeln!(
        css,
        ".{fallback},\n.{cell_fallback} {{\n    min-width: 0;\n}}"
    );
    let _ = writeln!(
        css,
        ".{tokens} {{\n    display: flex;\n    flex-wrap: wrap;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    let _ = writeln!(
        css,
        ".{actions} {{\n    display: flex;\n    flex: none;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    // A cell's parts sit inside the cell's own box, so they are inline: the
    // cell's alignment, which the column kind sets, still places them.
    let _ = writeln!(
        css,
        ".{cell_tokens},\n.{cell_actions} {{\n    display: inline-flex;\n    align-items: center;\n    gap: var(--gap-bound);\n}}"
    );
    // Wrapping, and no wider than the cell: a badge already ends in an
    // ellipsis at its container's width, and an inline run sized by its
    // contents gave it a container as wide as the badge, so a long token was
    // clipped at the cell edge instead.
    let _ = writeln!(
        css,
        ".{cell_tokens} {{\n    flex-wrap: wrap;\n    max-inline-size: 100%;\n}}"
    );
    // A part that follows another keeps the same gap from it that its own
    // members keep from each other: a title ran into its New version badge, a
    // split into its Invited one, and a value into the value after it. Every
    // part after the first, not just tokens and actions. Not after the sizer,
    // which is a block of its own above the run.
    let sizer = class(list::CELL_SIZER, opts);
    let cell_in = class(list::CELL_IN, opts);
    let _ = writeln!(
        css,
        ".{cell_in} > :not(.{sizer}) + * {{\n    \
         margin-inline-start: var(--gap-bound);\n}}"
    );
    let _ = writeln!(
        css,
        ".{tokens} > *,\n.{actions} > *,\n.{cell_tokens} > *,\n.{cell_actions} > * {{\n    white-space: nowrap;\n}}"
    );
    // A proportion is a meter, and a meter is as wide as the row lets it be.
    let _ = writeln!(css, ".{proportion} {{\n    flex: 1 1 auto;\n}}");

    css
}

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

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

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

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

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

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

    // The tab strip inside such a run, which is the member whose tabs fold.
    // The run going back to `nowrap` is not enough on its own: the strip is a
    // wrapping row in its own right, and the floor above holds it at its
    // min-content, so it either wrapped to more lines or pushed the run wider
    // than its pane. Neither overflows, and a strip that never overflows never
    // folds: eight tabs drew as three rows. So the strip takes the room the
    // run has and no more, holds one line, keeps each tab at its own width,
    // and clips across, which is the overflow the script measures. `clip` and
    // not `hidden`: `hidden` would make the block axis scroll too, and a
    // chosen tab's pull over its pane is drawn below the strip's box.
    //
    // The floor comes off this one member deliberately. It exists so members
    // push rather than overlap; a clipped strip overlaps nothing, and what it
    // clips is moved into the menu before anyone sees it.
    let strip =
        format!("{menu}[data-menu] > [role=\"tablist\"]:not([aria-orientation=\"vertical\"])");
    let _ = writeln!(
        css,
        ".{strip} {{\n    flex: 1 1 auto;\n    flex-wrap: nowrap;\n    min-width: 0;\n    overflow-x: clip;\n}}"
    );
    let _ = writeln!(css, ".{strip} > * {{\n    flex-shrink: 0;\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",
    }
}

/// 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, marking the control
/// `data-awaiting-watched` while it does.
///
/// A determinate control nobody is watching draws the mark with the total
/// beside it in the reading's ink, `content: attr(data-awaiting-amount)`: the
/// size is known and the delivery is not, which is what the tui and egui
/// renderers draw for the same wait. The attribute is the binder's because no
/// rule can tell an unset share from a zero one. A watched control whose share
/// is still unset draws an empty trough, never a full one.
///
/// **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 [`build`](mod@crate::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",
    );
    // The same blink for a mark drawn as an image beside text, where the
    // background colour is the text's ground and must not change.
    css.push_str(
        "@keyframes makeover-activity-beside {\n    \
         0%, 49.99% {\n        background-image: linear-gradient(var(--action), var(--action));\n    }\n    \
         50%, 100% {\n        background-image: linear-gradient(var(--surface-sunken), 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.
    //
    // `to right` and a right-to-left override rather than `to inline-end`:
    // no browser takes a logical direction in a gradient, and the declaration
    // that names one is dropped whole, leaving no fill at all.
    //
    // 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 right,\n        \
         var(--action) 0 calc(var(--awaiting-share, 0) * 100%),\n        \
         var(--surface-sunken) 0\n    \
         );\n\
         }}",
        opts.border_width, opts.border_width
    );

    // Measured and unwatched: the mark, then the total. One pseudo-element
    // still, so the mark is an image painted at the inline start and the
    // total is the content beside it. More specific than the bar by the
    // `:not`, so it wins whatever the order.
    let _ = writeln!(
        css,
        "[data-awaiting=\"determinate\"][aria-busy=\"true\"]:not([data-awaiting-watched])::after {{\n    \
         content: attr(data-awaiting-amount);\n    \
         inline-size: auto;\n    \
         block-size: auto;\n    \
         outline: none;\n    \
         color: var(--content-muted);\n    \
         padding-inline-start: calc(var(--awaiting-mark, 0.5em) + var(--awaiting-gap, 0.5ch));\n    \
         background: linear-gradient(var(--action), var(--action)) no-repeat \
         left center / var(--awaiting-mark, 0.5em) var(--awaiting-mark, 0.5em);\n    \
         animation: makeover-activity-beside calc(var(--cadence-activity) * 2) \
         step-end infinite;\n\
         }}"
    );

    // Right to left, the fill grows from the right and the mark sits there.
    let _ = writeln!(
        css,
        "[data-awaiting=\"determinate\"][aria-busy=\"true\"][data-awaiting-watched]:dir(rtl)::after {{\n    \
         background: linear-gradient(\n        \
         to left,\n        \
         var(--action) 0 calc(var(--awaiting-share, 0) * 100%),\n        \
         var(--surface-sunken) 0\n    \
         );\n\
         }}\n\
         [data-awaiting=\"determinate\"][aria-busy=\"true\"]:not([data-awaiting-watched]):dir(rtl)::after {{\n    \
         background-position: right center;\n\
         }}"
    );

    css
}

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

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

/// 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 `--track-at: 37.5%; --track-for: 4.166%` in [`VARS_ATTR`] 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();

    // An empty stand-in is a slot with nothing in it yet, and it draws as one:
    // a box on the page's own ground with a dashed edge from the neutral ramp.
    // A muted sentence loose on the page read as a stray line, and the way
    // out beneath it as an unrelated control; inside the box they read as one
    // thing that says what will be here and how to put it there. A waiting
    // stand-in keeps its sunken ground (below), so the two states stay apart.
    let _ = writeln!(
        css,
        ".{placeholder}:not([data-state=\"pending\"]) {{\n    \
         border: 1px dashed var(--border);\n    border-radius: var(--radius-fine);\n    \
         padding: var(--gap-section);\n}}"
    );
    // A stand-in's sentence wraps at the reading measure rather than running
    // the pane's width: goingson's Problems empty state was 172 characters on
    // one line at 1440. The token is quasi-webview's, the one a screen's
    // `Measure::Reading` already answers to, and the fallback is the value it
    // falls back to, so a page that sets neither still gets a line that reads.
    let _ = writeln!(
        css,
        ".{placeholder} > .{text} {{\n    max-inline-size: var(--measure-reading, 42rem);\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. The tone is an edge and
    // the sentence takes content ink, a step up from the muted one an empty
    // stand-in reads in: a failure is read, and a status colour is never the
    // colour of words (wiki `quasi-vocabulary-findings`).
    let _ = writeln!(
        css,
        ".{placeholder}[data-tone=\"{0}\"] > .{text} {{\n    color: var(--content);\n{1}}}",
        Tone::Danger.token(),
        status_edge(opts.focus_width, Tone::Danger.token())
    );
    // A stand-in that is waiting draws on a sunken ground, so it does not
    // read as one that is empty: both say a sentence where content will be,
    // and only the ground says whether anything is coming. A step of the
    // neutral ramp rather than a tone, since waiting is not a status. The
    // sentence carries the same news to a screen reader through the region's
    // own `aria-busy`. The inset is a gap step, so the ground reads as a
    // ground rather than a highlight under the words.
    let _ = writeln!(
        css,
        ".{placeholder}[data-state=\"pending\"] {{\n    background: var(--surface-sunken);\n    \
         padding: var(--gap-bound) var(--gap-peer);\n    \
         border-radius: var(--radius-fine);\n}}"
    );
    // A sentence that carries a status draws an edge in that status, the way
    // a figure does, and keeps its ink. A bare sentence was the one member
    // that accepted a tone and drew none of it; drawing the words in the tone
    // is what a figure's numbers measured at 1.24:1 to 2.27:1, and a
    // sentence is read the same way. Same edge and inset as the figure's.
    let sentence = class("text", opts);
    tone_rules(&mut css, &format!(".{sentence}"), |tone| {
        status_edge(opts.focus_width, tone)
    });
    // A sentence at a measure band sits on that band's step of the neutral
    // ramp, sized to its words so the band reads as the value's and not the
    // line's. Band 0 is the ground and draws nothing.
    for band in 1..makeover_layout::HEAT_BANDS {
        let heat = makeover_layout::Heat(band).token();
        let _ = writeln!(
            css,
            ".{sentence}[data-heat=\"{heat}\"] {{\n    background: var(--{heat});\n    \
             inline-size: fit-content;\n    \
             padding-inline: var(--step-snug);\n    \
             border-radius: var(--radius-fine);\n}}"
        );
    }
    // The way out stands a group apart from the sentence it answers. A gap
    // step rather than a size: how much room the stand-in gets is still the
    // app's.
    let _ = writeln!(
        css,
        ".{placeholder} > .{} {{\n    margin-block-start: var(--gap-group);\n}}",
        class("placeholder-action", opts)
    );

    // A header that reorders the table is a control, and the pointer is the
    // only part of saying so that is not the app's own type and spacing.
    let _ = writeln!(
        css,
        ".{heading}[data-sortable] {{\n    cursor: pointer;\n}}"
    );
    // The caret carries its own leading space, the way `makeover-tui` and
    // `makeover-immediate` both write `" \u{25B2}"`. An app adding the gap
    // itself would do it the obvious way, as `content`, and app CSS outranks
    // this crate's cascade layer, so it would win over the glyph and leave the
    // heading with no caret at all. 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 draws its glyph rather than hiding it and
    // reserving the box, so there is no reservation to get right.
    //
    // The glyph is `Sort::glyph`, escaped rather than written: a CSS `content`
    // string cannot carry the character literally through this file's own
    // escaping, and spelling it here as well would put the third copy back that
    // `makeover-layout` 0.27.5 exists to remove.
    //
    // On the heading's `.cell-in`, so the caret sits beside the label inside
    // its padding rather than at the far edge of a column that grew.
    let cell_in = class("cell-in", opts);
    let _ = writeln!(
        css,
        ".{heading}[data-sortable] > .{cell_in}::after \
         {{\n    content: \" {}\";\n    color: var(--content-secondary);\n}}",
        css_escape(Sort::Ascending.glyph())
    );
    for direction in [Sort::Ascending, Sort::Descending] {
        let _ = writeln!(
            css,
            ".{heading}[aria-sort=\"{}\"] > .{cell_in}::after \
             {{\n    content: \" {}\";\n    color: var(--content);\n}}",
            direction.as_str(),
            css_escape(direction.glyph())
        );
    }
    css
}

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

/// A notice that leaves on its own, floating over the page.
///
/// Its look is this crate's and where it floats is the host's: a toast takes
/// [`Notice::Toast`]'s fill, the control edge, the overlay cast and the notice
/// layer, and no position, because a window and a phone put it in different
/// places. A toned toast is the banner's answer: the tone's surface under the
/// theme's own ink, edged in the tone.
fn toast_rules(opts: &Emit) -> String {
    let toast = class("toast", opts);
    let mut css = String::new();
    let _ = writeln!(
        css,
        ".{toast} {{\n    background: var(--{});\n    color: var(--content);\n    \
         border: var(--edge-control);\n    box-shadow: var(--elevation-overlay);\n    \
         padding: var(--gap-peer) var(--gap-group);\n    z-index: var(--layer-notice);\n}}",
        makeover_layout::Notice::Toast.fill().token()
    );
    tone_rules(&mut css, &format!(".{toast}"), toned_surface);
    css
}

/// A notice that stays until dealt with, across whatever it is about.
///
/// A banner holds a sentence someone has to read, so it is left-aligned and its
/// words stop at the reading measure while its ground keeps the width of the
/// box it was put in. The words are a bare text node beside an optional act, so
/// the measure is the far padding rather than a cap on a child: what is left of
/// the box past the measure, or the ordinary inset once the box is narrower
/// than that.
///
/// A status is the chip's answer: `*-surface` under the theme's own ink, edged
/// in the tone. A status colour is never the colour of words.
fn banner_rules(opts: &Emit) -> String {
    let banner = class("banner", opts);
    let mut css = String::new();
    let _ = writeln!(
        css,
        ".{banner} {{\n    padding-block: var(--gap-peer);\n    \
         padding-inline-start: var(--gap-section);\n    \
         padding-inline-end: max(var(--gap-section), 100% - var(--measure-reading, 42rem));\n    \
         border-inline-start: {} solid var(--border);\n    \
         color: var(--content);\n    text-align: start;\n}}",
        opts.focus_width
    );
    tone_rules(&mut css, &format!(".{banner}"), |tone| {
        format!(
            "    background: var(--{tone}-surface);\n    border-inline-start-color: var(--{tone});\n"
        )
    });
    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`.
/// The `build` module 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 ink a native control draws its tick, dot and fill in.
///
/// A checkbox, a radio, a range and a `<progress>` are drawn by the browser,
/// and without this they draw in its own blue against a themed page: every
/// tick in goingson (Notifications, row selection, the All day box) was
/// user-agent blue in both themes. `accent-color` is inherited, so one
/// declaration on `:root` reaches every native control in the document,
/// including the ones no emitter here wrote, such as an app's own row-select
/// box. `--content`, not `--action`: a tick is a state mark, and the accent is
/// reserved for the primary action (accent-as-state ruling).
///
/// The browser picks the tick's own colour against that ink for contrast, so
/// `--content-on-action` has nothing to do here.
const NATIVE_ACCENT: &str = "    accent-color: var(--content);\n";

/// 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{}{NATIVE_ACCENT}}}\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 test_support;
#[cfg(test)]
mod tests;