makeover_webview/

form.rs

//! Phase B, the forms half: [`makeover_layout::Field`] rendered to HTML.
//!
//! # Why this emits strings
//!
//! Both webview apps build their markup as strings and hand it to `innerHTML`:
//! goingson's `renderFormField` returns a template literal that fifteen call
//! sites interpolate into larger literals, and Balanced Breakfast's builds
//! nodes but appends them into the same string-built forms. Returning nodes
//! would rewrite the surrounding templates as well, which makes it a migration
//! rather than an adoption. So: strings, and the escaping comes with them.
//!
//! # Why one escaper is enough here
//!
//! goingson carries four escapers and 543 call sites that must pick between
//! them, because `escapeHtml` is built on `textContent` serialization and
//! **`textContent` refuses to encode `"`**. That is what makes it unsound in an
//! attribute, and it is the whole reason the choice exists. Its `escape.js`
//! records the finding as the CHRONIC-XSS seal, and its test suite has a gate
//! keeping the unsafe one off the namespace.
//!
//! [`escape`] here is not built on that, so it encodes the quote along with
//! everything else, which makes one function sound in both sinks. The four-way
//! choice does not move into Rust: it disappears. Nothing in this module hands
//! an unescaped value to the output except through [`Markup`], which a caller
//! has to name.
//!
//! # What the description does not carry
//!
//! One thing: the **current value**, which arrives in [`Filling`].
//!
//! It used to be three. Writing this emitter is what found them, and the other
//! two turned out not to be renderer state at all — the placeholder is
//! user-facing text that sits with `label` and `hint`, and a select's options
//! are needed by every renderer, which is how each of them ends up inventing a
//! near-miss of the same struct. Both moved down into `makeover-layout` 0.8.0,
//! `Choice` included, and this crate reads them off [`Field`] now.
//!
//! The value stays, and it is not a leftover. A webview reads it back out of
//! the DOM, an immediate-mode renderer writes through a `&mut`, and a terminal
//! keeps an edit buffer; a description carrying it would have to carry a way to
//! write it back, at which point it is a form model.

use crate::{Emit, class, push_class};
use makeover_layout::{Choice, Depth, Field, FieldKind, Intent as _, Selector, ThemeVariant, Tone};
use std::fmt::Write as _;

/// Every class this module can put in markup.
///
/// [`crate::facet::FACET_CLASSES`]' obligation, and the module where it was
/// missing longest. Most of these carry no rule and never will: `.form-group`,
/// `.form-label`, `.form-hint` and `.form-error` are the apps' own names, kept
/// so adoption deletes goingson's `renderFormField` rather than restyling
/// anything, and phase A emits only what it can generate from the description.
/// A class with no rule is invisible to [`crate::vocabulary::vocabulary`],
/// which reads the generated sheet, so the unruled half of a renderer's
/// vocabulary can only be written down.
///
/// What went wrong without it: an app checking its stylesheet against
/// [`crate::vocabulary::names`] concluded that its live `.form-group` and
/// `.form-label` rules matched nothing and were safe to delete. quasi-webview
/// carried them in a `MAKEOVER_UNLISTED` constant of its own until 0.59.0
/// rather than let that happen.
pub const FIELD_CLASSES: &[&str] = &[
    "field",
    "form-checkbox-label",
    "form-editor-modes",
    "form-editor-preview",
    "form-error",
    "form-group",
    "form-hint",
    "form-interval",
    "form-label",
    "form-note",
    "form-option-detail",
    "form-option-reason",
    "form-radio-group",
    "form-radio-label",
    "form-unit",
];

// `form-suggestions`, `form-suggestion` and `form-suggestion-detail` are
// deliberately absent: [`suggestion_rules`] writes their look and
// `quasi-webview` writes their markup, because a suggestion source is a route
// and no description layer carries one. They reach the vocabulary through the
// generated sheet, which is where a name this crate rules but does not emit
// belongs.

/// The state classes a field carries, which take no prefix.
///
/// `chosen` and `latched`'s convention, stated in
/// [`crate::vocabulary::vocabulary`]: a state qualifies a prefixed component
/// (`.mk-form-group.has-error`) rather than standing on its own, so a prefix
/// moves the thing and not its state.
///
/// `has-error` marks the group and `visible` marks the message, which is
/// [`makeover_layout::Field::invalid`]'s own reasoning: a renderer with no
/// descendant selectors cannot find the group from the message, so both are
/// told.
pub const FIELD_STATE_CLASSES: &[&str] = &["has-error", "visible"];

/// A string that is already markup, and is emitted without escaping.
///
/// The one hole in the escaping, and it has to be named to be used. goingson
/// has two live callers that need it, both passing a recurrence-config block
/// built elsewhere, and both would otherwise have their markup rendered as
/// visible angle brackets. A caller constructing this is stating that the
/// contents are trusted; nothing here can check that for them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Markup<'a>(pub &'a str);

/// What the field currently holds.
///
/// An enum rather than a bag of optional fields, on the same reasoning
/// [`makeover_layout::Depth`] is one: a checkbox holding a string is unsayable
/// here, where a struct would let it be said and then have to cope.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Value<'a> {
    /// Nothing yet.
    #[default]
    Absent,
    /// The value of anything that takes typed text, a select included: what a
    /// select holds is the `value` of one of [`Field::options`]'s
    /// [`Choice`]s.
    ///
    /// It carried the options too until makeover-layout 0.8.0 moved them onto
    /// the field, which collapsed a `Chosen { options, value }` variant into
    /// this one. `makeover-immediate` arrived at the same single-variant shape
    /// on its own, from the other direction.
    Text(&'a str),
    /// A checkbox, on or off.
    On(bool),
    /// Both ends of a [`FieldKind::Interval`], lower first.
    ///
    /// Two values rather than one string with a separator, for
    /// [`makeover_layout::Field::upper_name`]'s reason one level down: an
    /// interval submits under two names, so it comes back as two values, and a
    /// delimiter this crate owned could appear inside either of them.
    ///
    /// Either end may be empty while the other stands. "Over 120 BPM" is a
    /// lower end and no upper one, and it is an answer rather than a
    /// half-filled form.
    ///
    /// Added 0.56.0 with makeover-layout 0.34.0.
    Between {
        /// What the lower box holds now.
        lower: &'a str,
        /// What the upper box holds now.
        upper: &'a str,
    },
}

impl<'a> Value<'a> {
    /// The value as text, for the kinds that submit one.
    const fn as_text(&self) -> &'a str {
        match self {
            Self::Text(text) | Self::Between { lower: text, .. } => text,
            Self::Absent | Self::On(_) => "",
        }
    }
}

impl<'a> Value<'a> {
    /// The upper end, for the one variant that has one.
    const fn upper_text(&self) -> &'a str {
        match self {
            Self::Between { upper, .. } => upper,
            Self::Absent | Self::Text(_) | Self::On(_) => "",
        }
    }
}

/// Everything about the field that the description does not carry.
#[derive(Debug, Clone, Copy, Default)]
pub struct Filling<'a> {
    /// What the field holds now.
    pub value: Value<'a>,
    /// Markup appended inside the group, after the hint. Not escaped.
    pub trailing: Option<Markup<'a>>,
    /// Attributes written onto the control element itself. Not escaped.
    ///
    /// [`trailing`](Self::trailing)'s argument at attribute scale: a host knows
    /// facts about the control that no description layer carries, and until
    /// this existed the only way to attach one was to stop calling this emitter
    /// and write a second one. quasi's suggestion source is the first caller —
    /// a field that owns a list of candidates is a `role="combobox"` pointing
    /// at the list it owns, and neither half is anything
    /// [`makeover_layout::Field`] can say.
    ///
    /// Written verbatim, so a caller supplies `attr="value"` pairs with no
    /// leading space and does its own escaping. It is [`Markup`]'s hole in the
    /// same wall, named the same way so a caller has to state that the contents
    /// are trusted.
    ///
    /// A [`FieldKind::Radio`] drops them, and that is deliberate rather than an
    /// oversight: a radio group is a set of sibling inputs with no one control
    /// element, so there is nowhere honest to put an attribute meant for the
    /// control. The group carries the descriptions for the same reason.
    pub control_attrs: Option<Markup<'a>>,
    /// Scopes the `id` attributes to one instance of the form.
    ///
    /// The field's `name` is what the value submits under and is the same
    /// wherever the form appears; its `id` has to be unique in the document,
    /// and those two facts stop agreeing the moment a form appears twice.
    /// goingson hits this directly: its new-task and edit-task modals are the
    /// same field set, so it prefixes `form-modal-task-new` or `-edit` to keep
    /// `label for` and `aria-describedby` pointing at the right control.
    ///
    /// Applies to `id`, `for` and the `-hint` / `-error` associations. Never to
    /// `name`, which would change what the form submits.
    pub id_prefix: Option<&'a str>,
}

impl<'a> Filling<'a> {
    /// A filling that carries a value and nothing else.
    #[must_use]
    pub const fn of(value: Value<'a>) -> Self {
        Self {
            value,
            trailing: None,
            control_attrs: None,
            id_prefix: None,
        }
    }

    /// The document-unique id for a field of this name.
    fn id_for(&self, name: &str) -> String {
        let mut id = String::new();
        if let Some(prefix) = self.id_prefix {
            escape_into(prefix, &mut id);
            id.push('-');
        }
        escape_into(name, &mut id);
        id
    }
}

/// Encode the five characters that let a value stop being a value, into a
/// buffer the caller already has.
///
/// The form the emitters use. [`escape`] is this with a `String` allocated
/// around it, and the allocation is the whole difference: a described screen
/// escapes once per attribute and once per run of text, so a function that
/// returns a `String` allocates a few thousand times to produce one page, where
/// a template engine writes its escaped bytes straight into the output buffer.
/// Measured 2026-08-14 against a real pane, that gap was 85% of a 42x rendering
/// cost, and this is the half of the fix that lives in this crate.
///
/// Sound in element text and in a double-quoted attribute alike, which is the
/// property `textContent`-based escaping cannot have. Both sinks are covered by
/// one function so that no call site has to choose, here or downstream.
///
/// Copies in runs rather than per character. All five encoded characters are
/// ASCII, so a byte scan cannot land inside a multi-byte character and the
/// slice between two of them is always a valid `&str`. Text with nothing to
/// encode — which is most text — is one `push_str` of the whole thing.
pub fn escape_into(text: &str, out: &mut String) {
    let mut start = 0;
    for (index, byte) in text.bytes().enumerate() {
        let encoded = match byte {
            b'&' => "&amp;",
            b'<' => "&lt;",
            b'>' => "&gt;",
            b'"' => "&quot;",
            b'\'' => "&#39;",
            _ => continue,
        };
        out.push_str(&text[start..index]);
        out.push_str(encoded);
        start = index + 1;
    }
    out.push_str(&text[start..]);
}

/// Encode the five characters that let a value stop being a value.
///
/// [`escape_into`] with a buffer of its own, for the callers that want a value
/// rather than an append: a caller assembling an attribute out of several
/// pieces, and everything outside this crate that took this function before the
/// buffer-writing form existed. Emitting into a buffer you already hold is the
/// cheaper path and the one this crate's own emitters take.
#[must_use]
pub fn escape(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    escape_into(text, &mut out);
    out
}

/// The `type` an input takes for a kind.
///
/// [`FieldKind::Secret`] is `password`, which both apps already map by hand.
const fn input_type(kind: FieldKind) -> &'static str {
    match kind {
        FieldKind::Secret => "password",
        FieldKind::Number => "number",
        FieldKind::Checkbox => "checkbox",
        FieldKind::File => "file",
        FieldKind::Hidden => "hidden",
        // Not decoration. Each of these changes the keyboard a touch device
        // offers and turns on the platform's own validation, which is why the
        // description names them apart from text rather than letting the app
        // pass an HTML type through.
        FieldKind::Email => "email",
        FieldKind::Url => "url",
        FieldKind::Tel => "tel",
        // The same argument, and it buys more here than anywhere else in this
        // list: a native picker as well as the keyboard and the validation.
        // Both submit the format `makeover-layout` names, `DATE_FORMAT` and
        // `DATETIME_FORMAT`, so honouring it costs this renderer nothing.
        FieldKind::Date => "date",
        FieldKind::DateTime => "datetime-local",
        FieldKind::Radio => "radio",
        // The clearest case in this list that a kind is not decoration: a
        // number and a range submit the same value and are different controls,
        // and the browser is the one drawing the difference.
        FieldKind::Range => "range",
        // Select and Textarea are not inputs at all; they never reach here.
        // Radio is one, but it is emitted once per option by `radio_html` and
        // so does not reach here either.
        FieldKind::Text | FieldKind::Select | FieldKind::Textarea | FieldKind::Rich => "text",
        // A kind added to the description since this renderer was built. Text
        // accepts any value the others would, so it degrades rather than
        // dropping the field.
        _ => "text",
    }
}

/// The attributes every visible control carries, error state included.
///
/// `aria-invalid` is the whole reason the error state is readable at all: the
/// generated stylesheet keys the danger ring on `[aria-invalid="true"]` rather
/// than on a class, so a control rendered already-invalid without it is styled
/// as if nothing were wrong. goingson's runtime validation path sets the
/// attribute and its initial render does not, which is exactly the drift one
/// emitter removes.
/// `id` and `name` arrive separately because they are not the same fact. The
/// name is what submits and is fixed by the description; the id has to be
/// unique in the document and so carries [`Filling::id_prefix`] when a form
/// appears more than once.
/// The `accept` attribute, from the description's accept list.
///
/// makeover-layout 0.31.0. The list is comma-joined because that is the
/// attribute's own format, and each entry writes itself: a family is its
/// wildcard media type, a media type is itself, a suffix is itself with its
/// leading dot. Nothing is normalised on the way through -- `.tar.gz` is two
/// dots and the browser is fine with it.
///
/// An empty list emits no attribute at all, which is the browser's own "any
/// file" and is what the description means by listing nothing. Emitting
/// `accept=""` instead would be a filter that matches nothing on some browsers
/// and everything on others.
///
/// It is a filter and not a guarantee, on the browser's side as much as here:
/// the picker keeps an "All Files" escape and the user may take it. Whoever
/// validated still validates.
fn push_accept(out: &mut String, field: &Field<'_>) {
    if field.accept.is_empty() {
        return;
    }
    out.push_str(" accept=\"");
    for (index, one) in field.accept.iter().enumerate() {
        if index > 0 {
            out.push(',');
        }
        escape_into(one.as_str(), out);
    }
    out.push('"');
}

/// The extent and the granularity, as the browser spells them.
///
/// Its own function because an interval writes them onto both of its ends: they
/// describe the axis rather than either end of it, which is what
/// [`FieldKind::Interval`] says and what the six audiofiles filter axes are.
fn push_bounds(out: &mut String, field: &Field<'_>) {
    if let Some(min) = field.min {
        out.push_str(" min=\"");
        escape_into(min, out);
        out.push('"');
    }
    if let Some(max) = field.max {
        out.push_str(" max=\"");
        escape_into(max, out);
        out.push('"');
    }
    // The browser's own default is `step="1"`, which turns a 0-to-1 threshold
    // into a two-position control. That is the granularity the description
    // means when it says nothing, so this is emitted only when an app has said
    // otherwise rather than defaulted here.
    //
    // A range takes its granularity from its curve as of makeover-layout
    // 0.32.0, and every other kind keeps `Field::step`. See the crate header on
    // what this renderer can and cannot do with a curve.
    let step = if field.kind == FieldKind::Range {
        field.curve.step()
    } else {
        field.step
    };
    if let Some(step) = step {
        out.push_str(" step=\"");
        escape_into(step, out);
        out.push('"');
    }
}

fn push_control_attributes(
    out: &mut String,
    field: &Field<'_>,
    filling: &Filling<'_>,
    id: &str,
    name: &str,
) {
    let _ = write!(out, " id=\"{id}\" name=\"");
    escape_into(name, out);
    out.push('"');
    if field.required {
        out.push_str(" required");
    }
    // makeover-layout 0.11.0's constraints. The description carries the rule and
    // this emits the browser's idiom for it, which is the model `required` has
    // been using since before the crate wrote down that it carried none.
    // Enforcement is still whoever validated's, and arrives back as `error`.
    if let Some(limit) = field.max_length {
        let _ = write!(out, " maxlength=\"{limit}\"");
    }
    push_bounds(out, field);
    // The description asks for the wall-clock value to be submitted as the
    // moment it names, and in a browser that conversion is script's: `<input
    // type="datetime-local">` submits what the user typed and nothing in HTML
    // turns it into an instant. So this emits the mark and quasi-webview's
    // `instant.js` does the converting -- the same division as `data-clock`,
    // where the markup says what to do and the shipped script is what a browser
    // knows that a description cannot.
    //
    // Only DateTime. A date and a time are each half a moment and cannot name
    // one on their own, so the flag is ignored there rather than emitting a
    // mark nothing can honour.
    if field.as_instant && matches!(field.kind, FieldKind::DateTime) {
        out.push_str(" data-instant=\"true\"");
    }
    if field.invalid() {
        out.push_str(" aria-invalid=\"true\"");
    }

    push_described_by(out, field, id);

    // Last, so that a host attaching a fact of its own can see everything this
    // emitter decided and cannot be overwritten by it. Duplicate attributes are
    // the caller's to avoid: HTML takes the first of a repeated pair, so an
    // attribute spelled here as well as there keeps this crate's answer.
    if let Some(Markup(attrs)) = filling.control_attrs {
        out.push(' ');
        out.push_str(attrs);
    }
}

/// The `aria-describedby` naming whatever of the hint and the error exist.
///
/// Both associations, in the order they are useful: the standing help, then
/// what is currently wrong. goingson's runtime path points describedby at the
/// error alone and drops the hint association it never made in the first place;
/// naming both here means the hint survives an error appearing.
///
/// Its own function because a radio group carries it on the group rather than
/// on a control, and one reading of "what describes this field" is the point.
fn push_described_by(out: &mut String, field: &Field<'_>, id: &str) {
    let unit = unit_of(field).is_some();
    if field.hint.is_none() && field.error.is_none() && field.note.is_none() && !unit {
        return;
    }
    let mut written = false;
    out.push_str(" aria-describedby=\"");
    if field.hint.is_some() {
        let _ = write!(out, "{id}-hint");
        written = true;
    }
    // The unit before the error and after the hint, which is the order they are
    // useful in: what the number is measured in is standing context like the
    // hint, and what is wrong with it now comes last.
    if unit {
        if written {
            out.push(' ');
        }
        let _ = write!(out, "{id}-unit");
        written = true;
    }
    // The note after the unit and before the error, matching the order the
    // three are drawn in and the order they are useful in: what the answer
    // costs is context, and what is wrong with it now still comes last.
    if field.note.is_some() {
        if written {
            out.push(' ');
        }
        let _ = write!(out, "{id}-note");
        written = true;
    }
    if field.error.is_some() {
        if written {
            out.push(' ');
        }
        let _ = write!(out, "{id}-error");
    }
    out.push('"');
}

/// The unit to draw beside this field's value, if there is one to draw.
///
/// Two conditions rather than one: the field has to carry a unit and its kind
/// has to be one that means anything by it. `FieldKind::measurable` is the
/// description answering the second, so this renderer keeps no list of its own
/// of which kinds are quantities.
fn unit_of<'a>(field: &Field<'a>) -> Option<&'a str> {
    field.unit.filter(|_| field.kind.measurable())
}

/// Whether the field's control is a set of elements rather than one.
///
/// A DOM concern rather than a description one, which is why it is decided here
/// and not in `makeover-layout`: `for` and `id` are an HTML association and
/// egui has no counterpart to get wrong. A `<label for>` aimed at a radio group
/// points at nothing, because no single element carries the group's id, so the
/// association has to invert — the label takes an id and the group names itself
/// with `aria-labelledby`.
const fn is_group_control(kind: FieldKind) -> bool {
    matches!(kind, FieldKind::Radio | FieldKind::Interval)
}

/// An interval: two number boxes inside one labelled group.
///
/// The markup MNW's discover sidebar writes by hand -- a `role="group"` with
/// `aria-labelledby` pointing at the question, holding `min_price` and
/// `max_price` -- which is HTML saying by hand exactly what
/// [`FieldKind::Interval`] now says in the description. So this emits what that
/// page already proved is right, rather than inventing a shape.
///
/// The group carries the error state and the descriptions, for
/// [`push_radio`]'s reason: what is wrong is the answer, and marking one box
/// invalid would name the wrong half of a fault that belongs to both ends.
///
/// # Both boxes take the same extent
///
/// [`Field::min`], [`Field::max`] and [`Field::step`] describe the axis rather
/// than either end, so [`push_bounds`] writes them onto both. The crossing rule
/// is not emitted, because the description does not carry it and the browser
/// has no attribute for it: an upper end below the lower one is a refusal
/// whoever validated hands back as [`Field::error`], which lands on the group.
///
/// # Which end is which, in words
///
/// `aria-label`, because the description states direction structurally -- the
/// lower end's name is [`Field::name`] and the upper one's is
/// [`Field::upper_name`] -- and never in words. Words for the ends are the
/// host's, the same way a slider's readout is, and a page with visible Min and
/// Max captions supplies them through [`Filling::trailing`] rather than having
/// this crate own two strings of English.
fn push_interval(out: &mut String, field: &Field<'_>, filling: &Filling<'_>, opts: &Emit) {
    let id = filling.id_for(field.name);

    out.push_str("<div class=\"");
    push_class(out, "form-interval", opts);
    let _ = write!(out, "\" role=\"group\" aria-labelledby=\"{id}-label\"");
    if field.invalid() {
        out.push_str(" aria-invalid=\"true\"");
    }
    push_described_by(out, field, &id);
    out.push('>');

    // An interval with no upper name has one end that can be submitted, which
    // is what the description said and is drawn honestly rather than repaired:
    // `Field::interval` is what makes it unsayable, and inventing a name here
    // would submit a parameter no handler is reading.
    let ends: [(&str, &str, &str); 2] = [
        ("lower", field.name, filling.value.as_text()),
        (
            "upper",
            field.upper_name.unwrap_or(""),
            filling.value.upper_text(),
        ),
    ];
    for (end, name, value) in ends {
        if name.is_empty() {
            continue;
        }
        out.push_str("<input type=\"number\" class=\"");
        push_class(out, "field", opts);
        let _ = write!(out, "\" id=\"{id}-{end}\" name=\"");
        escape_into(name, out);
        let _ = write!(out, "\" aria-label=\"{end}\"");
        if field.required {
            out.push_str(" required");
        }
        push_bounds(out, field);
        if let Some(text) = field.placeholder {
            out.push_str(" placeholder=\"");
            escape_into(text, out);
            out.push('"');
        }
        out.push_str(" value=\"");
        escape_into(value, out);
        out.push_str("\">");
    }

    out.push_str("</div>");
}

/// A radio group: the options as sibling inputs sharing one `name`.
///
/// The group carries the error state and the descriptions, and the inputs carry
/// what submits. That split is [`Field::invalid`]'s reasoning applied one level
/// down: marking a single input invalid would say the wrong thing, since what
/// is wrong is the answer to the question and not one of the alternatives.
///
/// Ids are numbered rather than built from the option values, which can hold
/// anything a `&str` can — spaces and quotes included — and would otherwise
/// have to be slugged into something unique by a rule this crate would then own.
///
/// `required` lands on every input, which is how HTML says a group is
/// compulsory: the constraint is satisfied when any one of them is checked.
fn push_radio(out: &mut String, field: &Field<'_>, filling: &Filling<'_>, opts: &Emit) {
    let id = filling.id_for(field.name);
    let value = filling.value.as_text();
    let name = escape(field.name);

    out.push_str("<div class=\"");
    push_class(out, "form-radio-group", opts);
    let _ = write!(out, "\" role=\"radiogroup\" aria-labelledby=\"{id}-label\"");
    if field.invalid() {
        out.push_str(" aria-invalid=\"true\"");
    }
    push_described_by(out, field, &id);
    out.push('>');

    // A group described with no options emits an empty group, for the reason
    // `Field::options` gives: an app whose option list has not loaded has
    // exactly that, and an empty group says so on screen rather than in a log.
    for (index, opt) in field.options.iter().enumerate() {
        out.push_str("<label class=\"");
        push_class(out, "form-radio-label", opts);
        let _ = write!(
            out,
            "\"><input type=\"radio\" id=\"{id}-{index}\" name=\"{name}\" value=\""
        );
        escape_into(opt.value, out);
        out.push('"');
        if opt.value == value {
            out.push_str(" checked");
        }
        if field.required {
            out.push_str(" required");
        }
        // A radio group has room a `<select>` does not, so the reason gets its
        // own element beside the label rather than being run into it. The class
        // is what a stylesheet mutes; the text is there either way, which is
        // the half that matters — the finding was a greyed control with its
        // explanation behind a hover.
        if opt.unavailable.is_some() {
            out.push_str(" disabled");
        }
        out.push_str("><span>");
        escape_into(opt.label, out);
        out.push_str("</span>");
        // What picking it means, on the line under the label. `5e21dcfc`, and
        // the same treatment the reason gets one line down: a radio group has
        // room, so the sentence sits in its own element rather than being run
        // into the label the way a `<select>`'s has to be.
        //
        // Before the reason, which is the order the two read in: what this
        // option *is* comes ahead of why it cannot be picked, and an option
        // carrying both has said two things rather than one long one.
        if let Some(detail) = opt.detail {
            out.push_str("<span class=\"");
            push_class(out, "form-option-detail", opts);
            out.push_str("\">");
            escape_into(detail, out);
            out.push_str("</span>");
        }
        if let Some(reason) = opt.unavailable {
            out.push_str("<span class=\"");
            push_class(out, "form-option-reason", opts);
            out.push_str("\">");
            escape_into(reason, out);
            out.push_str("</span>");
        }
        out.push_str("</label>");
    }

    out.push_str("</div>");
}

/// The options of a select: the unanswered instruction, an unmatched current
/// value carried as its own, then the options themselves.
///
/// A select handed a value no option carries renders with nothing selected, the
/// browser falls back to the first option, and the next save writes a value
/// nobody chose. goingson hit exactly that with a backup-retention default of
/// 10 against a 1/3/7/14/0 list, and grew this stray-option fix locally; it is
/// here so the second app gets it without hitting the bug first.
fn push_options(out: &mut String, field: &Field<'_>, options: &[Choice<'_>], value: &str) {
    // The unanswered state, which HTML has no attribute for: `placeholder` is
    // not a `<select>` attribute, and the idiom is an empty option that cannot
    // be chosen back. `disabled` is what stops it being re-selected once the
    // user has answered, and `selected` is what puts it in the closed control
    // while the value is empty; together they read as an instruction rather
    // than as an option.
    //
    // `required` keeps working through it rather than around it: the option's
    // value is empty, so a required select with this showing is invalid, which
    // is the true report on a question nobody has answered.
    //
    // Emitted only while the value is empty, so it does not sit in the open
    // list once the field is answered. A non-empty value no option carries is a
    // wrong answer rather than an absent one and takes the stray-option path
    // below.
    if value.is_empty()
        && let Some(text) = field.placeholder
    {
        out.push_str("<option value=\"\" disabled selected>");
        escape_into(text, out);
        out.push_str("</option>");
    }
    if !value.is_empty() && !options.iter().any(|opt| opt.value == value) {
        // The one place an escaped value is worth keeping: it is written twice,
        // as the option's value and as its text.
        let escaped = escape(value);
        let _ = write!(
            out,
            "<option value=\"{escaped}\" selected data-unmatched=\"true\">{escaped}</option>"
        );
    }
    for opt in options {
        out.push_str("<option value=\"");
        escape_into(opt.value, out);
        out.push('"');
        if opt.value == value {
            out.push_str(" selected");
        }
        // `disabled` is what the browser reads, and it says nothing about why.
        // The reason goes in the option's own text, because a `<select>` gives
        // its options no room for anything else: no title attribute the
        // keyboard reaches, no second line, no element inside. So the row reads
        // "Multi-sample: Drop a second sample onto the keyboard." and is the
        // one place the precondition can be both attached to its option and
        // read without a pointer.
        if opt.unavailable.is_some() {
            out.push_str(" disabled");
        }
        out.push('>');
        escape_into(opt.label, out);
        // Both extra strings run into the row's text, for the reason above:
        // this is the one control with nowhere else to put either of them.
        // `5e21dcfc` did not invent that rule, it met it.
        if let Some(detail) = opt.detail {
            out.push_str(": ");
            escape_into(detail, out);
        }
        if let Some(reason) = opt.unavailable {
            out.push_str(": ");
            escape_into(reason, out);
        }
        out.push_str("</option>");
    }
}

/// The themes, as one `<optgroup>` per variant with a contrast mark per row.
///
/// # The grouping comes out of the order, not out of a group list
///
/// [`makeover_layout::Field::themes`] arrives sorted by variant and then by
/// measured contrast, and the run of one variant is the group. So this walks
/// the list once and opens a new `<optgroup>` whenever the variant changes,
/// which is the whole of the grouping logic and cannot disagree with the order
/// the way a separately-carried group list could.
///
/// A theme whose variant equals its predecessor's never opens a group, so a
/// list that arrived unsorted would emit repeated groups rather than silently
/// merging distant rows. That is the honest report on a description that broke
/// its own contract, and it is visible on screen rather than in a log.
///
/// # The follow row is not in a group
///
/// It names no theme and sits in no variant, so it is emitted first and bare.
/// Grouping it under a heading would be inventing a fourth variant for one row.
///
/// # The badge is text, because a `<select>` has nowhere else to put it
///
/// A `<select>`'s options take no elements, no second line and no title the
/// keyboard reaches, which is [`push_options`]' finding about
/// [`Choice::unavailable`] met a second time. So the tier rides in the option's
/// own text, in brackets after the name, and it is
/// [`makeover_layout::Contrast::badge`]'s spelling rather than one invented
/// here — three renderers picking their own is one picker reading three ways.
fn push_theme_options(out: &mut String, field: &Field<'_>, value: &str) {
    if let Some(follow) = field.follows {
        out.push_str("<option value=\"");
        escape_into(follow.value, out);
        out.push('"');
        if follow.value == value {
            out.push_str(" selected");
        }
        out.push('>');
        escape_into(follow.label, out);
        out.push_str("</option>");
    }

    // A stored id naming a theme that is no longer installed. `push_options`'
    // reasoning applies unchanged: a value no row carries is a wrong answer
    // rather than an absent one, and dropping it would silently show the user
    // a different theme than the one their config names.
    let known = field.themes.iter().any(|theme| theme.id == value)
        || field.follows.is_some_and(|follow| follow.value == value);
    if !value.is_empty() && !known {
        let escaped = escape(value);
        let _ = write!(
            out,
            "<option value=\"{escaped}\" selected data-unmatched=\"true\">{escaped}</option>"
        );
    }

    let mut open: Option<ThemeVariant> = None;
    for theme in field.themes {
        if open != Some(theme.variant) {
            if open.is_some() {
                out.push_str("</optgroup>");
            }
            out.push_str("<optgroup label=\"");
            escape_into(theme.variant.heading(), out);
            out.push_str("\" data-variant=\"");
            out.push_str(theme.variant.as_str());
            out.push_str("\">");
            open = Some(theme.variant);
        }

        out.push_str("<option value=\"");
        escape_into(theme.id, out);
        out.push_str("\" data-contrast=\"");
        out.push_str(theme.contrast.as_str());
        out.push('"');
        if theme.id == value {
            out.push_str(" selected");
        }
        out.push('>');
        escape_into(theme.name, out);
        out.push_str(" (");
        out.push_str(theme.contrast.badge());
        out.push(')');
        out.push_str("</option>");
    }
    if open.is_some() {
        out.push_str("</optgroup>");
    }
}

/// The control itself, without its label, hint or error.
fn push_control(out: &mut String, field: &Field<'_>, filling: &Filling<'_>, opts: &Emit) {
    // Emitted before anything else is computed: a radio group carries its
    // descriptions on the group rather than on a control, so none of the
    // attributes below belong to it.
    if matches!(field.kind, FieldKind::Radio) {
        push_radio(out, field, filling, opts);
        return;
    }
    // The same split one kind along: an interval is two inputs and one
    // question, so the group carries the error and the descriptions and the
    // boxes carry what submits.
    if matches!(field.kind, FieldKind::Interval) {
        push_interval(out, field, filling, opts);
        return;
    }

    let id = filling.id_for(field.name);
    let placeholder = |out: &mut String| {
        if let Some(text) = field.placeholder {
            out.push_str(" placeholder=\"");
            escape_into(text, out);
            out.push('"');
        }
    };

    match field.kind {
        // Both multi-line kinds are a `<textarea>`, and the markdown one says so
        // in an attribute rather than in a class: what the value *is* is not a
        // styling hook, and a progressive enhancement looking for editors to
        // upgrade needs a selector that survives `Emit`'s class prefixing.
        // Without the mark, a described editor is a plain box and the four
        // hand-written MNW editors have nothing to convert onto.
        //
        // `data-format` and not `data-value`: this names the shape of the
        // value, and `facet` already spends `data-facet-value` on carrying an
        // actual one. Two attributes a letter apart meaning opposite things is
        // how a renderer's own vocabulary starts drifting.
        kind if kind.multiline() => {
            let rich = matches!(kind, FieldKind::Rich);
            if rich {
                push_editor_open(out, opts);
            }
            out.push_str("<textarea class=\"");
            push_class(out, "field", opts);
            out.push('"');
            if rich {
                out.push_str(" data-format=\"markdown\"");
            }
            push_control_attributes(out, field, filling, &id, field.name);
            placeholder(out);
            out.push('>');
            escape_into(filling.value.as_text(), out);
            out.push_str("</textarea>");
            if rich {
                push_editor_close(out, opts);
            }
        }
        FieldKind::Select => {
            out.push_str("<select class=\"");
            push_class(out, "field", opts);
            out.push('"');
            push_control_attributes(out, field, filling, &id, field.name);
            out.push('>');
            // A select described with no options emits an empty select, which
            // says so on screen rather than in a log. That is the description's
            // own position on `Field::options`, not a fallback invented here.
            push_options(out, field, field.options, filling.value.as_text());
            out.push_str("</select>");
        }
        // The one place this renderer emits `<optgroup>`, and it emits it
        // because the description finally says there is a group. The measured
        // history is the argument: `optgroup` appears at one live site in the
        // whole tree, and the two apps that had grouped theme pickers lost the
        // grouping the moment they were described, because `Choice` is a value
        // and a label and a group is neither.
        FieldKind::Theme => {
            out.push_str("<select class=\"");
            push_class(out, "field", opts);
            out.push('"');
            push_control_attributes(out, field, filling, &id, field.name);
            out.push('>');
            push_theme_options(out, field, filling.value.as_text());
            out.push_str("</select>");
        }
        FieldKind::Checkbox => {
            out.push_str("<label class=\"");
            push_class(out, "form-checkbox-label", opts);
            out.push_str("\"><input type=\"checkbox\"");
            push_control_attributes(out, field, filling, &id, field.name);
            if matches!(filling.value, Value::On(true)) {
                out.push_str(" checked");
            }
            out.push_str("><span>");
            escape_into(field.label, out);
            out.push_str("</span></label>");
        }
        // A secret never carries its value into the markup. `FieldKind::secret`
        // is documented as a value that must not be round-tripped through
        // anything that might persist it, and the DOM is such a thing: it is
        // read by every extension on the page and is the first thing a crash
        // reporter serialises. Neither app pre-fills one today, so this costs
        // nothing and closes the door before something does.
        FieldKind::Secret => {
            out.push_str("<input type=\"password\" class=\"");
            push_class(out, "field", opts);
            out.push('"');
            push_control_attributes(out, field, filling, &id, field.name);
            placeholder(out);
            out.push('>');
        }
        // A file input carries no value, and this is the browser's rule rather
        // than a preference: setting one from markup is refused, because a page
        // that could preselect a path could read a file the user never offered.
        // Nothing upstream needs to know, which is why the exception is here.
        FieldKind::File => {
            out.push_str("<input type=\"file\" class=\"");
            push_class(out, "field", opts);
            out.push('"');
            push_control_attributes(out, field, filling, &id, field.name);
            push_accept(out, field);
            if field.multiple {
                out.push_str(" multiple");
            }
            out.push('>');
        }
        kind => {
            let _ = write!(out, "<input type=\"{}\" class=\"", input_type(kind));
            push_class(out, "field", opts);
            out.push('"');
            push_control_attributes(out, field, filling, &id, field.name);
            placeholder(out);
            out.push_str(" value=\"");
            escape_into(filling.value.as_text(), out);
            out.push_str("\">");
        }
    }
}

/// The chrome a markdown field gets and a plain textarea does not: the two
/// modes, and the pane a preview lands in.
///
/// # Why this is the one field with markup around it
///
/// [`FieldKind::Rich`]'s own doc says the mark buys a renderer permission to
/// offer a preview or a syntax pass, and that a renderer with neither draws a
/// textarea. A renderer taking the permission and emitting the same box as
/// [`FieldKind::Textarea`] leaves an app converting onto the member with less
/// than it had written by hand: MNW's `partial-item-text-editor.js` has a
/// Write/Preview pair and a pane behind it, and describing the field without
/// this would delete both. So the pair is here, on `facet`'s argument one
/// field down -- the markup it replaces is not markup an app is keeping.
///
/// # Nothing here renders markdown, and that is where the sanitising stays
///
/// The pane arrives empty and this crate never turns a value into markup.
/// Converting markdown is the host's, which is where the sanitiser already is:
/// MNW renders through `docengine` over ammonia and holds an allowlist beside
/// it. A converter here would move that guarantee into a crate with no view of
/// the host's content-security posture, and `Rich`'s doc is explicit that a
/// host with its own sanitiser still owns it. What this emits is a hook, and
/// whatever fills it fills it with markup it has already made safe.
///
/// # The direction the enhancement runs
///
/// [`crate::stylesheet`]'s rule for a showing region, and for its reason: a
/// control rendered into a document with no script is a control that looks live
/// and answers nothing. Nothing is hidden here and no control is shown until
/// whatever binds the editor sets `data-ready` on the wrapper, so a reader with
/// no script gets the textarea alone -- what 0.50.0 emitted -- and a reader with
/// script gets the modes. A bound editor says which mode it is in with
/// `data-mode`, and [`editor_rules`] reads that.
fn push_editor_open(out: &mut String, opts: &Emit) {
    // The mark sits on the wrapper as well as on the control, saying one thing
    // about two: this control's value is markdown, and this editor edits
    // markdown. The rules gate on the wrapper and they are attribute rules
    // rather than class rules for `data-format`'s own reason -- the gate has to
    // survive `Emit`'s class prefixing, because the enhancement selects on it
    // too.
    out.push_str("<div data-format=\"markdown\"><div class=\"");
    push_class(out, "form-editor-modes", opts);
    out.push_str("\">");
    push_mode(out, "write", "Write", true, opts);
    push_mode(out, "preview", "Preview", false, opts);
    out.push_str("</div>");
}

/// One of the two modes, as a segment of the pair.
///
/// [`crate::option_class`] for [`Selector::Segmented`] rather than a name of
/// its own: a Write/Preview pair is a segmented control, and spelling it as one
/// gets it the depth, the focus ring and the chosen state every described
/// selector gets, from rules that already exist. The words are written here for
/// the reason `facet`'s exclude button writes its own: a description carrying
/// them would be choosing them for the terminal as well.
fn push_mode(out: &mut String, mode: &str, label: &str, chosen: bool, opts: &Emit) {
    out.push_str("<button type=\"button\" class=\"");
    push_class(out, crate::option_class(Selector::Segmented), opts);
    if chosen {
        // The sheet keys the held-in segment on the class and a screen reader
        // reads the attribute. Both, because they are two readings of one fact,
        // which is the arrangement a facet value already has.
        out.push_str(" chosen");
    }
    let _ = write!(
        out,
        "\" data-editor-mode=\"{mode}\" aria-pressed=\"{chosen}\">{label}</button>"
    );
}

/// The preview pane, and the wrapper closing over both halves.
fn push_editor_close(out: &mut String, opts: &Emit) {
    out.push_str("<div class=\"");
    push_class(out, "form-editor-preview", opts);
    // `data-editor-preview` and not an id: a form appears twice in a document
    // often enough that `Filling::id_prefix` exists for it, and a binder holding
    // the control can reach this without either of them being unique.
    out.push_str("\" data-editor-preview></div></div>");
}

/// The rules the markdown editor's chrome needs.
///
/// The one place this module writes CSS. The class names [`field_html`] emits
/// are goingson's and are deliberately unruled -- `.form-group`, `.form-label`,
/// `.form-hint` and `.form-error` are the app's own, and phase A emits only what
/// it can generate from the description -- but the two names here have no app
/// counterpart to keep, because the chrome did not exist before the member did.
///
/// Every rule is gated on `[data-format="markdown"]`, which is what keeps them
/// off a plain textarea, and every rule that hides content is gated on
/// `data-ready` as well, which is what keeps them out of a document with no
/// script.
pub(crate) fn editor_rules(opts: &Emit) -> String {
    let mut css = String::new();
    let modes = class("form-editor-modes", opts);
    let preview = class("form-editor-preview", opts);
    let field = class("field", opts);

    // Hidden until something binds the editor, which is the whole argument in
    // `push_editor_open`.
    let _ = writeln!(
        css,
        "[data-format=\"markdown\"] > .{modes} {{\n    display: none;\n}}"
    );
    // Block, and nothing about how the two segments sit in it. A button is
    // inline already, so they make a row without this crate saying so, and
    // saying so is where a gap would follow -- a magnitude, and
    // `makeover-geometry`'s.
    let _ = writeln!(
        css,
        "[data-format=\"markdown\"][data-ready] > .{modes} {{\n    display: block;\n}}"
    );

    // The pane is empty until the host fills it, so it is out of flow in every
    // state but the one where a bound editor is showing it. An empty box under
    // the control is chrome claiming a preview nobody rendered.
    let _ = writeln!(
        css,
        "[data-format=\"markdown\"] > .{preview} {{\n    display: none;\n}}"
    );
    let _ = writeln!(
        css,
        "[data-format=\"markdown\"][data-ready][data-mode=\"preview\"] > .{preview} \
         {{\n    display: block;\n}}"
    );
    // One at a time. The source and the preview are the same content read two
    // ways, and a field showing both answers its own question twice.
    let _ = writeln!(
        css,
        "[data-format=\"markdown\"][data-ready][data-mode=\"preview\"] > .{field} \
         {{\n    display: none;\n}}"
    );

    // The pane stands where the control stood, so it reads as the surface the
    // control was: `.field` is a well, and this is the well it stands in for.
    // Nothing about size -- how tall a preview is is the app's, the way the
    // height of a track is.
    let _ = write!(
        css,
        "[data-format=\"markdown\"] > .{preview} {{\n{}}}\n",
        crate::depth_declarations(Depth::Well)
    );

    css
}

/// The rule a field's unit needs.
///
/// [`suggestion_rules`]' precedent and its argument: `.form-group`,
/// `.form-label`, `.form-hint` and `.form-error` are the apps' own names and
/// stay unruled here, and this one has no app counterpart to keep because
/// nothing emitted it before `Field::unit` existed.
///
/// One declaration, and it is the whole look. A unit is a fact about the number
/// beside it rather than a second thing to read, so it takes the muted content
/// intent -- the same reading `.figure-caption` and `.track-tick` take, and for
/// the same reason.
///
/// Nothing about placement or spacing. Where the span sits relative to the
/// control is the app's layout, exactly as `.form-hint`'s is, and a margin
/// asserted here would be this crate deciding a magnitude that belongs to
/// `makeover-geometry`.
/// The rules a field's note needs.
///
/// [`unit_rules`]' precedent and its argument: `.form-hint` and `.form-error`
/// are the apps' own names and stay unruled here, and this one has no app
/// counterpart to keep because nothing emitted it before [`Field::note`]
/// existed.
///
/// Colour only, and the tones are the four a badge carries. The bare class is
/// `content` rather than `content-muted`: a note is a consequence the user is
/// meant to read before answering, so muting it by default would be this crate
/// deciding it does not matter.
pub(crate) fn note_rules(opts: &Emit) -> String {
    let note = class("form-note", opts);
    let mut css = String::new();
    let _ = writeln!(css, ".{note} {{\n    color: var(--content);\n}}");
    for tone in [Tone::Info, Tone::Success, Tone::Warning, Tone::Danger] {
        let _ = writeln!(
            css,
            ".{note}[data-tone=\"{0}\"] {{\n    color: var(--{0});\n}}",
            tone.token()
        );
    }
    css
}

pub(crate) fn unit_rules(opts: &Emit) -> String {
    let unit = class("form-unit", opts);
    let mut css = String::new();
    let _ = writeln!(css, ".{unit} {{\n    color: var(--content-muted);\n}}");
    css
}

/// The rules an option's second line needs.
///
/// [`unit_rules`]' argument, and it is worth saying why this one is ruled where
/// `.form-option-reason` beside it is not: that class shipped at 0.28.0, before
/// the test the two functions above state — rule what has no app counterpart to
/// keep — and nothing has been written against it since. This one has none
/// either, and an unruled second line renders identically to the label it sits
/// under, which is a worse default than the hand-written markup it replaces.
/// MNW spells that markup `.card--selectable-desc` and mutes it.
///
/// Colour only, and muted, which is the same reading `.form-unit` and
/// `.form-suggestion-detail` take: the line orients the label rather than
/// competing with it. Nothing about placement or spacing, for `unit_rules`'
/// reason — a magnitude asserted here belongs to `makeover-geometry`.
pub(crate) fn option_detail_rules(opts: &Emit) -> String {
    let detail = class("form-option-detail", opts);
    let mut css = String::new();
    let _ = writeln!(css, ".{detail} {{\n    color: var(--content-muted);\n}}");
    css
}

/// The rules a field's suggestion list needs.
///
/// [`editor_rules`]' precedent and its argument: the class names this module's
/// markup emits are the apps' own and stay unruled, and these three have no app
/// counterpart to keep because the list did not exist before the member did.
/// The markup is `quasi-webview`'s rather than this crate's — a suggestion
/// source is a route, which no description layer carries — and the look is
/// still this crate's, because a renderer inventing how a list of candidates
/// reads is the drift the vocabulary check exists to catch.
///
/// # In flow, and not floating
///
/// An absolutely positioned list needs a positioned ancestor, and the only
/// candidate is `.form-group`, which is the app's class and deliberately
/// unruled here. So the list stands under the control and moves what is below
/// it. An app that wants it over the form positions the group itself, which is
/// one declaration and is the app's call about its own layout.
///
/// `:empty` is what takes it away, so a route that answers with no candidates
/// leaves no box behind. It is a content question rather than a whitespace one
/// only because the emitter writes no whitespace inside the container, which is
/// stated in `quasi-webview`'s own test.
///
/// # Nothing about size
///
/// No height, no scroll ceiling, no padding. How tall a list of candidates gets
/// to be before it scrolls is a magnitude, and magnitudes are
/// `makeover-geometry`'s, exactly as the preview pane's height is.
pub(crate) fn suggestion_rules(opts: &Emit) -> String {
    let list = class("form-suggestions", opts);
    let entry = class("form-suggestion", opts);
    let detail = class("form-suggestion-detail", opts);
    let mut css = String::new();

    let _ = writeln!(css, ".{list}:empty {{\n    display: none;\n}}");
    // Over what it covers, which is what a list of candidates is even in flow:
    // it is answering the box above it and goes away when the answer is taken.
    css.push_str(&crate::depth_rule(&list, Depth::Overlay));
    // An entry answers a click, so it gets every state one implies.
    css.push_str(&crate::interactive_rules(&entry, Depth::Flat, opts));
    // The keyboard's highlight and the pointer's are the same surface. They are
    // the same fact told two ways, and a list where arrowing and hovering look
    // different is a list that has two current entries.
    //
    // Keyed on `aria-selected` rather than on a class, for the reason
    // `aria-invalid` carries the error state: it is what a screen reader hears,
    // so a look keyed on it cannot drift from what is announced. A `.current`
    // class would also be a name apps already spell for their own reasons --
    // the MNW server has one -- and unlayered app CSS beats this layer in
    // silence.
    let _ = writeln!(
        css,
        ".{entry}[aria-selected=\"true\"] {{\n    background: var(--hover-surface);\n}}"
    );
    // The second line, muted rather than disabled. `1fcf2e9b` replaced the
    // unavailable reason this rule used to draw: a candidate carries no
    // `unavailable`, and what sits beside the label now is what tells one row
    // from another that reads the same. Disabled would say the row cannot be
    // picked, which is the opposite of what the detail is for.
    let _ = writeln!(css, ".{detail} {{\n    color: var(--content-muted);\n}}");

    css
}

/// One field, as the group the app drops into its form.
///
/// The shape is goingson's, down to the class names, so adoption there deletes
/// `renderFormField` rather than restyling anything. That is also why the class
/// names are not emitted by [`crate::stylesheet`]: `.form-group`, `.form-label`,
/// `.form-hint` and `.form-error` are the apps' own, and phase A deliberately
/// emits only what it can generate from the description. Whether they should
/// move into the description is the next question this raises, not one it
/// answers.
///
/// A [`FieldKind::Hidden`] field is the input alone: no group, no label, and
/// nothing drawn, which is what [`FieldKind::visible`] means.
///
/// The error marks the group as well as the control. That is
/// [`Field::invalid`]'s own reasoning: a renderer with no descendant selectors
/// cannot find the group from the message, so the group has to be told.
///
/// ```
/// use makeover_layout::{Field, FieldKind};
/// use makeover_webview::{Emit, form::{Filling, Value, field_html}};
///
/// let field = Field::new(FieldKind::Text, "title", "Title");
/// let html = field_html(&field, &Filling::of(Value::Text("Ship it")), &Emit::default());
///
/// assert!(html.contains(r#"<label class="form-label" for="title">Title</label>"#));
/// assert!(html.contains(r#"value="Ship it""#));
/// ```
#[must_use]
pub fn field_html(field: &Field<'_>, filling: &Filling<'_>, opts: &Emit) -> String {
    let mut html = String::new();
    field_html_into(field, filling, opts, &mut html);
    html
}

/// One field, written into a buffer the caller already has.
///
/// [`field_html`]'s streaming form, byte-identical to it. A form is a run of
/// these, so a host building one should hold a single buffer and append each
/// field into it rather than take a `String` per field and concatenate.
pub fn field_html_into(field: &Field<'_>, filling: &Filling<'_>, opts: &Emit, out: &mut String) {
    let id = filling.id_for(field.name);

    if !field.kind.visible() {
        // Name only, no id: a hidden field is never pointed at by a label or a
        // description, so the one attribute it needs is the one that submits.
        out.push_str("<input type=\"hidden\" name=\"");
        escape_into(field.name, out);
        out.push_str("\" value=\"");
        escape_into(filling.value.as_text(), out);
        out.push_str("\">");
        return;
    }

    out.push_str("<div class=\"");
    push_class(out, "form-group", opts);
    if field.invalid() {
        out.push_str(" has-error");
    }
    if field.extended {
        // The disclosure that hides these is a property of the form, not of the
        // field, so the field is marked and the app opens or closes the group.
        out.push_str("\" data-extended=\"true");
    }
    out.push_str("\">");

    // A checkbox labels itself, on the right of the box. Both apps special-case
    // this inline today, which is the tell that it belongs in the description;
    // `FieldKind::labels_itself` is where it went.
    if !field.kind.labels_itself() {
        out.push_str("<label class=\"");
        push_class(out, "form-label", opts);
        // A group control is named *by* its label rather than pointing at it,
        // so the two carry opposite halves of the association. See
        // `is_group_control`.
        if is_group_control(field.kind) {
            let _ = write!(out, "\" id=\"{id}-label\">");
        } else {
            let _ = write!(out, "\" for=\"{id}\">");
        }
        escape_into(field.label, out);
        out.push_str("</label>");
    }

    push_control(out, field, filling, opts);

    // Adjacent text, because HTML has no unit attribute and inventing one would
    // be markup nothing reads. Pointed at by `aria-describedby` so it is not
    // decoration a screen reader skips: the number and what it is measured in
    // are one fact, and reading the first without the second is reading it
    // wrong.
    if let Some(unit) = unit_of(field) {
        out.push_str("<span class=\"");
        push_class(out, "form-unit", opts);
        let _ = write!(out, "\" id=\"{id}-unit\">");
        escape_into(unit, out);
        out.push_str("</span>");
    }

    if let Some(hint) = field.hint {
        out.push_str("<div class=\"");
        push_class(out, "form-hint", opts);
        let _ = write!(out, "\" id=\"{id}-hint\">");
        escape_into(hint, out);
        out.push_str("</div>");
    }
    // A consequence of the answer, between the standing help and the failure.
    // The tone rides on `data-tone` -- the same attribute every other toned
    // thing in this crate takes -- and it also picks the live region: Warning
    // and Danger are assertive, which is quasi-webview's own reading at
    // `node.rs:1403` and is honoured here rather than restated differently.
    if let Some((tone, note)) = field.note {
        out.push_str("<div class=\"");
        push_class(out, "form-note", opts);
        let assertive = matches!(tone, Tone::Warning | Tone::Danger);
        let _ = write!(
            out,
            "\" id=\"{id}-note\" role=\"{}\"",
            if assertive { "alert" } else { "status" }
        );
        // Neutral is the bare class rather than a variant, matching every
        // other toned component here: it is the absence of a status.
        if tone != Tone::Neutral {
            let _ = write!(out, " data-tone=\"{}\"", tone.token());
        }
        out.push('>');
        escape_into(note, out);
        out.push_str("</div>");
    }
    if let Some(Markup(markup)) = filling.trailing {
        out.push_str(markup);
    }
    if let Some(error) = field.error {
        out.push_str("<div class=\"");
        push_class(out, "form-error", opts);
        let _ = write!(out, " visible\" id=\"{id}-error\" role=\"alert\">");
        escape_into(error, out);
        out.push_str("</div>");
    }

    out.push_str("</div>");
}

#[cfg(test)]
mod tests {
    use super::*;
    use makeover_layout::{Accepted, Curve, Family};

    fn field(kind: FieldKind) -> Field<'static> {
        Field::new(kind, "title", "Title")
    }

    #[test]
    fn a_value_cannot_break_out_of_the_attribute_it_sits_in() {
        // The payload from goingson's own CHRONIC-XSS regression test.
        let filling = Filling::of(Value::Text("x\" onfocus=alert(1) autofocus=\""));
        let html = field_html(&field(FieldKind::Text), &filling, &Emit::default());
        // The payload survives as text, which is the point: it is inert
        // because the quote that would have closed the attribute is encoded,
        // not because the words were filtered.
        assert!(!html.contains("\" onfocus"), "{html}");
        assert!(
            html.contains("value=\"x&quot; onfocus=alert(1) autofocus=&quot;\""),
            "{html}"
        );
    }

    /// The seam quasi's suggestion source needs: a host's own attributes land
    /// on the control, unescaped, and after everything this crate decided.
    #[test]
    fn a_host_can_write_its_own_attributes_onto_the_control() {
        let mut filling = Filling::of(Value::Text("ru"));
        filling.control_attrs = Some(Markup(
            r#"role="combobox" aria-expanded="false" aria-controls="title-suggestions""#,
        ));
        let html = field_html(&field(FieldKind::Text), &filling, &Emit::default());
        assert!(html.contains(r#"role="combobox""#), "{html}");
        assert!(
            html.contains(r#"aria-controls="title-suggestions""#),
            "{html}"
        );
        // After the id, which is what "last" buys: a host can read what this
        // emitter wrote and cannot be overwritten by it.
        let id = html.find(r#"id="title""#).expect("id");
        let role = html.find(r#"role="combobox""#).expect("role");
        assert!(id < role, "{html}");
    }

    /// A radio group has no one control element, so there is nowhere honest to
    /// put an attribute meant for the control. Documented on the member.
    #[test]
    fn a_radio_group_drops_control_attributes() {
        let mut f = field(FieldKind::Radio);
        let options = [Choice::new("a", "A")];
        f.options = &options;
        let filling = Filling {
            control_attrs: Some(Markup(r#"data-host="1""#)),
            ..Filling::default()
        };
        let html = field_html(&f, &filling, &Emit::default());
        assert!(!html.contains("data-host"), "{html}");
    }

    #[test]
    fn a_label_cannot_open_a_tag() {
        let mut f = field(FieldKind::Text);
        f.label = "<script>alert(1)</script>";
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(!html.contains("<script>"), "{html}");
        assert!(html.contains("&lt;script&gt;"), "{html}");
    }

    #[test]
    fn every_escaped_sink_is_covered_by_the_one_escaper() {
        assert_eq!(escape("&<>\"'"), "&amp;&lt;&gt;&quot;&#39;");
        // The character `textContent` serialization leaves alone, which is why
        // the app needs two escapers and this needs one.
        assert!(escape("\"").contains("&quot;"));
    }

    /// The streaming escaper is the one the emitters call and [`escape`] is a
    /// buffer around it, so the two cannot be allowed to drift. It copies in
    /// runs between the encoded characters, which is where a multi-byte
    /// character would break it if the scan were not restricted to ASCII.
    #[test]
    fn the_streaming_escaper_appends_what_the_returning_one_returns() {
        for text in [
            "",
            "plain",
            "&<>\"'",
            "&&&",
            "a & b",
            "trailing&",
            "&leading",
            "é世 & <b>naïve</b> \u{1f600}",
        ] {
            let mut out = String::from("kept: ");
            escape_into(text, &mut out);
            assert_eq!(out, format!("kept: {}", escape(text)), "{text:?}");
        }
    }

    /// Same obligation one layer up: a form is a run of fields appended into one
    /// buffer, and the two ways to get one have to agree byte for byte.
    #[test]
    fn a_streamed_field_is_the_field_the_other_form_returns() {
        let kinds = [
            FieldKind::Text,
            FieldKind::Secret,
            FieldKind::Number,
            FieldKind::Checkbox,
            FieldKind::Radio,
            FieldKind::Select,
            FieldKind::Textarea,
            FieldKind::File,
            FieldKind::Hidden,
        ];
        let choices = [Choice::plain("one"), Choice::plain("two")];
        let opts = Emit {
            class_prefix: "mk-",
            ..Emit::default()
        };
        for kind in kinds {
            let described = Field {
                hint: Some("a hint"),
                error: Some("wrong <here>"),
                placeholder: Some("x\" y"),
                options: &choices,
                required: true,
                max_length: Some(40),
                min: Some("1"),
                max: Some("9"),
                extended: true,
                ..Field::new(kind, "the & name", "The <label>")
            };
            let filling = Filling {
                value: Value::Text("one"),
                trailing: Some(Markup("<i>t</i>")),
                control_attrs: Some(Markup(r#"data-host="1""#)),
                id_prefix: Some("modal"),
            };
            let mut streamed = String::new();
            field_html_into(&described, &filling, &opts, &mut streamed);
            assert_eq!(
                streamed,
                field_html(&described, &filling, &opts),
                "{kind:?}"
            );

            // And the bare field, where every optional half is absent.
            let plain = Field::new(kind, "name", "Label");
            let mut streamed = String::new();
            field_html_into(&plain, &Filling::default(), &opts, &mut streamed);
            assert_eq!(
                streamed,
                field_html(&plain, &Filling::default(), &opts),
                "{kind:?}"
            );
        }
    }

    #[test]
    fn markup_is_the_only_way_past_the_escaping() {
        let filling = Filling {
            trailing: Some(Markup("<div class=\"recurrence-config\"></div>")),
            ..Filling::default()
        };
        let html = field_html(&field(FieldKind::Text), &filling, &Emit::default());
        assert!(
            html.contains("<div class=\"recurrence-config\"></div>"),
            "{html}"
        );
    }

    #[test]
    fn an_invalid_field_carries_the_attribute_its_own_stylesheet_keys_on() {
        let mut f = field(FieldKind::Text);
        f.error = Some("Required");
        let opts = Emit::default();
        let html = field_html(&f, &Filling::default(), &opts);
        assert!(html.contains("aria-invalid=\"true\""), "{html}");
        // The selector the CSS side emits for exactly this state.
        assert!(crate::stylesheet(&opts).contains("[aria-invalid=\"true\"]"));
        // And the group is marked too, which a renderer without descendant
        // selectors depends on.
        assert!(html.contains("has-error"), "{html}");
    }

    #[test]
    fn a_valid_field_claims_nothing_about_being_invalid() {
        let html = field_html(
            &field(FieldKind::Text),
            &Filling::default(),
            &Emit::default(),
        );
        assert!(!html.contains("aria-invalid"), "{html}");
        assert!(!html.contains("has-error"), "{html}");
    }

    #[test]
    fn a_note_sits_between_the_hint_and_the_error_and_carries_its_tone() {
        let mut f = field(FieldKind::Text);
        f.hint = Some("Keep it short");
        f.note = Some((Tone::Warning, "Re-encoding drops embedded BWF"));
        f.error = Some("Required");
        let html = field_html(&f, &Filling::default(), &Emit::default());

        // All three associated, in the order they are drawn.
        assert!(
            html.contains(r#"aria-describedby="title-hint title-note title-error""#),
            "{html}"
        );
        assert!(
            html.contains(r#"id="title-note" role="alert" data-tone="warning""#),
            "{html}"
        );
        // And in that order in the document, so the reading order matches.
        let hint = html.find("title-hint").unwrap();
        let note = html.rfind("title-note").unwrap();
        let err = html.rfind("title-error").unwrap();
        assert!(hint < note && note < err, "{html}");
    }

    #[test]
    fn a_quiet_note_is_polite_and_wears_no_tone_attribute() {
        // Neutral is the bare class, matching every other toned component
        // here, and only Warning and Danger interrupt.
        let mut f = field(FieldKind::Text);
        f.note = Some((Tone::Info, "This is what that setting implies"));
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains(r#"role="status" data-tone="info""#), "{html}");

        f.note = Some((Tone::Neutral, "An ordinary fact"));
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains(r#"id="title-note" role="status">"#), "{html}");
        assert!(!html.contains("data-tone"), "{html}");
    }

    #[test]
    fn a_note_does_not_mark_the_group_invalid() {
        // `Field::invalid` stays `error.is_some()`, and the renderer's
        // `has-error` follows it rather than any message being present.
        let mut f = field(FieldKind::Text);
        f.note = Some((Tone::Danger, "This cannot be undone"));
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(!html.contains("has-error"), "{html}");
        assert!(!html.contains(r#"aria-invalid="true""#), "{html}");
    }

    #[test]
    fn the_hint_survives_an_error_arriving() {
        let mut f = field(FieldKind::Text);
        f.hint = Some("Keep it short");
        f.error = Some("Required");
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(
            html.contains("aria-describedby=\"title-hint title-error\""),
            "{html}"
        );
    }

    #[test]
    fn a_secret_never_carries_its_value_into_the_markup() {
        let filling = Filling::of(Value::Text("hunter2"));
        let html = field_html(&field(FieldKind::Secret), &filling, &Emit::default());
        assert!(!html.contains("hunter2"), "{html}");
        assert!(html.contains("type=\"password\""), "{html}");
    }

    #[test]
    fn a_hidden_field_is_the_input_and_nothing_else() {
        let filling = Filling::of(Value::Text("42"));
        let html = field_html(&field(FieldKind::Hidden), &filling, &Emit::default());
        assert_eq!(html, "<input type=\"hidden\" name=\"title\" value=\"42\">");
    }

    #[test]
    fn a_checkbox_labels_itself_and_takes_no_separate_label() {
        let html = field_html(
            &field(FieldKind::Checkbox),
            &Filling::of(Value::On(true)),
            &Emit::default(),
        );
        assert!(!html.contains("form-label"), "{html}");
        assert!(html.contains("checked"), "{html}");
        assert!(html.contains("<span>Title</span>"), "{html}");
    }

    #[test]
    fn a_select_keeps_a_value_no_option_carries() {
        let options = [Choice::plain("1"), Choice::plain("3"), Choice::plain("7")];
        let f = Field::select("title", "Title", &options);
        let html = field_html(&f, &Filling::of(Value::Text("10")), &Emit::default());
        assert!(html.contains("data-unmatched=\"true\""), "{html}");
        // Selected, so the next save round-trips it rather than writing the
        // first option over the top of it.
        assert!(html.contains("<option value=\"10\" selected"), "{html}");
    }

    #[test]
    fn a_select_with_no_options_emits_an_empty_select() {
        // The description says a select with no options is sayable, because an
        // app whose option list has not loaded has exactly that. Emitting the
        // empty select reports it on screen rather than in a log.
        let f = Field::select("title", "Title", &[]);
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains("<select"), "{html}");
        assert!(!html.contains("<option"), "{html}");
    }

    #[test]
    fn an_unanswered_select_shows_its_ghost_text_and_cannot_be_chosen_back() {
        let options = [Choice::new("sp404", "SP-404")];
        let f = Field {
            placeholder: Some("Select device..."),
            ..Field::select("device", "Conform for device", &options)
        };
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert!(
            html.contains("<option value=\"\" disabled selected>Select device...</option>"),
            "{html}"
        );
        // First, so the closed control reads it rather than the first real
        // option.
        assert!(
            html.find("Select device...") < html.find("SP-404"),
            "{html}"
        );
    }

    #[test]
    fn an_answered_select_drops_the_ghost_text() {
        // It is an instruction about an empty field, so it has nothing to say
        // once the field is answered, and leaving it in the list is one dead
        // row every time the control is opened afterwards.
        let options = [Choice::new("sp404", "SP-404")];
        let f = Field {
            placeholder: Some("Select device..."),
            ..Field::select("device", "Conform for device", &options)
        };
        let html = field_html(&f, &Filling::of(Value::Text("sp404")), &Emit::default());
        assert!(!html.contains("Select device..."), "{html}");
    }

    #[test]
    fn a_wrong_answer_is_kept_and_is_not_the_ghost_text() {
        // The two paths through `push_options` meet here. An unmatched value is
        // an answer that is wrong and stays visible as itself; only the empty
        // value is unanswered.
        let options = [Choice::plain("1"), Choice::plain("7")];
        let f = Field {
            placeholder: Some("Pick one"),
            ..Field::select("retention", "Keep backups for", &options)
        };
        let html = field_html(&f, &Filling::of(Value::Text("10")), &Emit::default());
        assert!(html.contains("data-unmatched=\"true\""), "{html}");
        assert!(!html.contains("Pick one"), "{html}");
    }

    #[test]
    fn a_range_is_a_range_input_and_carries_its_extent() {
        let f = Field {
            curve: Curve::Linear { step: Some("0.01") },
            ..Field::range("review", "Review above", "0", "1")
        };
        let html = field_html(&f, &Filling::of(Value::Text("0.72")), &Emit::default());
        assert!(html.contains("type=\"range\""), "{html}");
        assert!(html.contains("min=\"0\""), "{html}");
        assert!(html.contains("max=\"1\""), "{html}");
        // Without it the browser steps by 1 and a 0-to-1 question becomes a
        // two-position control.
        assert!(html.contains("step=\"0.01\""), "{html}");
    }

    #[test]
    fn a_range_reads_its_granularity_off_the_curve_and_not_off_field_step() {
        // The 0.32.0 narrowing, at the renderer. `Field::step` on a range is a
        // site that has not been moved over, and emitting it would make the
        // control step by a number the curve never agreed to.
        let f = Field {
            step: Some("99"),
            ..Field::range("review", "Review above", "0", "1")
        };
        let html = field_html(&f, &Filling::of(Value::Text("0.5")), &Emit::default());
        assert!(!html.contains("step="), "{html}");
    }

    #[test]
    fn a_unit_is_adjacent_text_and_the_control_points_at_it() {
        // Not decoration: the number and what it is measured in are one fact,
        // so the association is what makes this worth emitting at all.
        let f = Field {
            unit: Some("dBFS"),
            ..Field::range("threshold", "Threshold", "-96", "-20")
        };
        let html = field_html(&f, &Filling::of(Value::Text("-40")), &Emit::default());
        assert!(html.contains(r#"id="threshold-unit""#), "{html}");
        assert!(html.contains(">dBFS</span>"), "{html}");
        assert!(
            html.contains(r#"aria-describedby="threshold-unit""#),
            "{html}"
        );
        // The label is the question's name and keeps no unit in it.
        assert!(html.contains(">Threshold</label>"), "{html}");
    }

    #[test]
    fn a_unit_takes_its_place_between_the_hint_and_the_error() {
        let f = Field {
            unit: Some("ms"),
            hint: Some("How long the fade runs."),
            error: Some("Too long."),
            ..Field::new(FieldKind::Number, "fade", "Fade")
        };
        let html = field_html(&f, &Filling::of(Value::Text("50")), &Emit::default());
        assert!(
            html.contains(r#"aria-describedby="fade-hint fade-unit fade-error""#),
            "{html}"
        );
    }

    #[test]
    fn a_unit_on_a_kind_that_is_not_a_quantity_is_ignored() {
        // Sayable and ignored, the way `options` is on a kind that offers none.
        // The renderer asks the description which kinds are measurable rather
        // than keeping its own list.
        let f = Field {
            unit: Some("s"),
            ..Field::new(FieldKind::Text, "name", "Name")
        };
        let html = field_html(&f, &Filling::of(Value::Text("kick")), &Emit::default());
        assert!(!html.contains("name-unit"), "{html}");
        assert!(!html.contains("aria-describedby"), "{html}");
    }

    #[test]
    fn a_unit_cannot_break_out_of_the_span_it_sits_in() {
        let f = Field {
            unit: Some("</span><script>"),
            ..Field::new(FieldKind::Number, "n", "N")
        };
        let html = field_html(&f, &Filling::of(Value::Text("1")), &Emit::default());
        assert!(!html.contains("<script>"), "{html}");
        assert!(html.contains("&lt;script&gt;"), "{html}");
    }

    #[test]
    fn a_constant_ratio_curve_is_answered_with_a_linear_track() {
        // The decided answer, not a shortfall: HTML has no logarithmic range
        // input, so the browser draws the extent linearly. The value it submits
        // is still a value in the field's own units, which is what every
        // handler on this path reads. See the crate header.
        let f = Field {
            curve: Curve::Logarithmic {
                step: Some("0.001"),
            },
            ..Field::range("attack", "Attack", "0.001", "5")
        };
        let html = field_html(&f, &Filling::of(Value::Text("0.005")), &Emit::default());
        assert!(html.contains("type=\"range\""), "{html}");
        assert!(html.contains("min=\"0.001\""), "{html}");
        assert!(html.contains("max=\"5\""), "{html}");
        assert!(html.contains("step=\"0.001\""), "{html}");
    }

    #[test]
    fn a_number_with_bounds_is_still_typed_into() {
        // The distinction the kind exists for, at the renderer where getting it
        // wrong is most visible: goingson's `min="1"` duration must not come
        // back as a slider.
        let f = Field {
            min: Some("1"),
            ..Field::new(FieldKind::Number, "minutes", "Minutes")
        };
        let html = field_html(&f, &Filling::of(Value::Text("30")), &Emit::default());
        assert!(html.contains("type=\"number\""), "{html}");
        assert!(!html.contains("type=\"range\""), "{html}");
        // And nothing invents a step for it.
        assert!(!html.contains("step="), "{html}");
    }

    #[test]
    fn an_unavailable_option_is_disabled_and_says_why() {
        let options = [
            Choice::new("chromatic", "Chromatic"),
            Choice::new("multi", "Multi-sample").unless("Drop a second sample."),
        ];
        let f = Field::radio("mode", "Mode", &options);
        let html = field_html(&f, &Filling::of(Value::Text("chromatic")), &Emit::default());

        assert!(html.contains(" disabled"), "{html}");
        assert!(html.contains("Drop a second sample."), "{html}");
        // The option is still offered: dropping it is what costs the user the
        // knowledge that the mode exists.
        assert!(html.contains("value=\"multi\""), "{html}");
        // And the reason is its own element, not run into the label.
        assert!(html.contains("form-option-reason"), "{html}");
    }

    #[test]
    fn an_unavailable_select_option_carries_its_reason_in_its_text() {
        // A `<select>` gives an option no room for a second element, so the
        // reason has to be in the text or be unreadable without a pointer.
        let options = [Choice::new("multi", "Multi-sample").unless("Drop a second sample.")];
        let f = Field::select("mode", "Mode", &options);
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(
            html.contains(">Multi-sample: Drop a second sample.</option>"),
            "{html}"
        );
        assert!(html.contains("disabled"), "{html}");
    }

    #[test]
    fn an_option_can_say_what_picking_it_means() {
        // makeover-layout 0.39.0. A radio group has room, so the line gets its
        // own element under the label, and it is muted rather than unruled: an
        // unruled second line renders identically to the label above it, which
        // is a worse default than the markup this replaces.
        let options = [
            Choice::new("16", "Basic").detailing("$16/mo. Fits text, blogs, newsletters."),
            Choice::new("24", "Small Files"),
        ];
        let f = Field::radio("tier", "Content tier", &options);
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert!(html.contains("form-option-detail"), "{html}");
        assert!(
            html.contains(">$16/mo. Fits text, blogs, newsletters.</span>"),
            "{html}"
        );
        // One option carries it and the other does not, so the class appears
        // once rather than on every label.
        assert_eq!(html.matches("form-option-detail").count(), 1, "{html}");
        assert!(
            option_detail_rules(&Emit::default()).contains("var(--content-muted)"),
            "the line orients the label rather than competing with it"
        );
    }

    #[test]
    fn an_option_reads_what_it_is_before_why_it_cannot_be_picked() {
        // Two different sentences, drawn in the order they read in. A tier that
        // is sold out is still a tier the reader is owed a description of.
        let options = [Choice::new("24", "Small Files")
            .detailing("$24/mo. Fits audio, plugins, binaries.")
            .unless("Sold out while the founder window is open.")];
        let f = Field::radio("tier", "Content tier", &options);
        let html = field_html(&f, &Filling::default(), &Emit::default());

        let detail = html.find("form-option-detail").expect("the detail");
        let reason = html.find("form-option-reason").expect("the reason");
        assert!(detail < reason, "{html}");
        assert!(html.contains(" disabled"), "{html}");

        // A `<select>` has room for neither element, so both run into the
        // row's own text in the same order.
        let f = Field::select("tier", "Content tier", &options);
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(
            html.contains(concat!(
                ">Small Files: $24/mo. Fits audio, plugins, binaries.",
                ": Sold out while the founder window is open.</option>"
            )),
            "{html}"
        );
    }

    #[test]
    fn a_radio_group_is_named_by_its_label_instead_of_pointing_at_it() {
        // The association inverts, and getting it wrong is silent: a
        // `<label for>` aimed at a group points at no element, so the group
        // simply has no accessible name and nothing reports that.
        let options = [Choice::plain("copy"), Choice::plain("reference")];
        let f = Field::radio("storage", "Storage style", &options);
        let html = field_html(&f, &Filling::of(Value::Text("copy")), &Emit::default());

        assert!(html.contains("id=\"storage-label\""), "{html}");
        assert!(!html.contains("for=\"storage\""), "{html}");
        assert!(html.contains("role=\"radiogroup\""), "{html}");
        assert!(html.contains("aria-labelledby=\"storage-label\""), "{html}");
    }

    #[test]
    fn an_interval_is_one_labelled_group_holding_both_ends() {
        // The markup MNW's discover sidebar writes by hand, which is the
        // measurement that decided the member: `role="group"` naming the
        // question, two number boxes under it.
        let f = Field::interval("min_price", "max_price", "Price");
        let html = field_html(
            &f,
            &Filling::of(Value::Between {
                lower: "5",
                upper: "40",
            }),
            &Emit::default(),
        );

        assert!(html.contains("role=\"group\""), "{html}");
        assert!(
            html.contains("aria-labelledby=\"min_price-label\""),
            "{html}"
        );
        assert!(html.contains("id=\"min_price-label\""), "{html}");
        assert!(!html.contains("for=\"min_price\""), "{html}");
        assert!(html.contains("name=\"min_price\""), "{html}");
        assert!(html.contains("name=\"max_price\""), "{html}");
        assert!(html.contains("value=\"5\""), "{html}");
        assert!(html.contains("value=\"40\""), "{html}");
        assert_eq!(html.matches("type=\"number\"").count(), 2, "{html}");
    }

    #[test]
    fn both_ends_of_an_interval_take_the_whole_extent() {
        // The extent describes the axis rather than either end of it, so a
        // browser refuses the same values in both boxes.
        let f = Field {
            min: Some("0"),
            max: Some("300"),
            step: Some("1"),
            ..Field::interval("bpm_min", "bpm_max", "BPM")
        };
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert_eq!(html.matches("min=\"0\"").count(), 2, "{html}");
        assert_eq!(html.matches("max=\"300\"").count(), 2, "{html}");
        assert_eq!(html.matches("step=\"1\"").count(), 2, "{html}");
        // Neither box holds anything, which is the open interval rather than an
        // empty form: no filter on this axis at all.
        assert_eq!(html.matches("value=\"\"").count(), 2, "{html}");
    }

    #[test]
    fn an_interval_carries_the_fault_on_the_group_and_not_on_one_end() {
        // A crossed interval is wrong about the answer, and the answer is the
        // pair. This is the half two `Number` fields could not say.
        let f = Field {
            error: Some("The high end is below the low one."),
            hint: Some("Leave an end empty for no bound."),
            ..Field::interval("bpm_min", "bpm_max", "BPM")
        };
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert_eq!(html.matches("aria-invalid=\"true\"").count(), 1, "{html}");
        let group = html.find("role=\"group\"").expect("group");
        let invalid = html.find("aria-invalid").expect("invalid");
        let first_input = html.find("<input").expect("input");
        assert!(invalid > group && invalid < first_input, "{html}");
        assert!(
            html.contains("aria-describedby=\"bpm_min-hint bpm_min-error\""),
            "{html}"
        );
    }

    #[test]
    fn an_interval_with_one_end_named_draws_one_box() {
        // Drawn as described rather than repaired. Inventing a name for the
        // upper end would submit a parameter no handler reads, and
        // `Field::interval` is what makes the omission unsayable at the source.
        let f = Field::new(FieldKind::Interval, "bpm_min", "BPM");
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert_eq!(html.matches("<input").count(), 1, "{html}");
        assert!(html.contains("name=\"bpm_min\""), "{html}");
    }

    #[test]
    fn every_option_shares_the_name_and_only_the_current_one_is_checked() {
        // One `name` is what makes them one answer rather than three; distinct
        // ids are what keep each `<label>` wrapping its own input.
        let options = [
            Choice::plain("copy"),
            Choice::plain("reference"),
            Choice::plain("link"),
        ];
        let f = Field::radio("storage", "Storage style", &options);
        let html = field_html(&f, &Filling::of(Value::Text("reference")), &Emit::default());

        assert_eq!(html.matches("name=\"storage\"").count(), 3, "{html}");
        assert_eq!(html.matches(" checked").count(), 1, "{html}");
        assert!(
            html.contains("value=\"reference\" checked"),
            "the checked one is the one held: {html}"
        );
        for index in 0..3 {
            assert!(html.contains(&format!("id=\"storage-{index}\"")), "{html}");
        }
    }

    #[test]
    fn a_radio_group_carries_the_error_rather_than_any_one_option() {
        // What is wrong is the answer, not one of the alternatives, so marking
        // a single input invalid would say something false. Same reading
        // `Field::invalid` gives one level up.
        let options = [Choice::plain("copy"), Choice::plain("reference")];
        let f = Field {
            error: Some("Pick one."),
            hint: Some("Cannot be changed later."),
            ..Field::radio("storage", "Storage style", &options)
        };
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert_eq!(html.matches("aria-invalid=\"true\"").count(), 1, "{html}");
        assert!(
            html.contains("aria-describedby=\"storage-hint storage-error\""),
            "{html}"
        );
        // The group is the element that carries them, so they land before the
        // first option rather than on it.
        let group = html.find("role=\"radiogroup\"").expect("group");
        let first = html.find("type=\"radio\"").expect("an option");
        assert!(group < first, "{html}");
    }

    #[test]
    fn a_compulsory_radio_group_marks_every_option() {
        // How HTML says a group is compulsory: the constraint reads as
        // satisfied when any one of them is checked.
        let options = [Choice::plain("copy"), Choice::plain("reference")];
        let f = Field {
            required: true,
            ..Field::radio("storage", "Storage style", &options)
        };
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert_eq!(html.matches(" required").count(), 2, "{html}");
    }

    #[test]
    fn a_radio_option_cannot_break_out_of_its_attribute() {
        // Values are `&str` and carry whatever the app put in them. The ids are
        // numbered rather than derived from the value for the same reason.
        let hostile = [Choice::new(
            "x\" onclick=alert(1) data-x=\"",
            "<script>alert(1)</script>",
        )];
        let f = Field::radio("storage", "Storage style", &hostile);
        let html = field_html(&f, &Filling::default(), &Emit::default());

        // The payload survives as text; what must not survive is the quote
        // that would end the attribute and let the rest of it become markup.
        assert!(html.contains("value=\"x&quot; onclick=alert(1)"), "{html}");
        assert!(!html.contains("<script>"), "{html}");
        assert!(html.contains("id=\"storage-0\""), "{html}");
    }

    #[test]
    fn a_radio_group_with_no_options_emits_an_empty_group() {
        // Same position the select takes, and the description's own.
        let f = Field::radio("storage", "Storage style", &[]);
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains("role=\"radiogroup\""), "{html}");
        assert!(!html.contains("type=\"radio\""), "{html}");
    }

    #[test]
    fn a_placeholder_comes_off_the_description_and_is_escaped() {
        // It arrived in `Filling` until makeover-layout 0.8.0 and was never
        // covered here; it is a value in an attribute like any other.
        let f = Field {
            placeholder: Some("x\" onfocus=alert(1) autofocus=\""),
            ..field(FieldKind::Text)
        };
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains("placeholder=\""), "{html}");
        assert!(!html.contains("\" onfocus"), "{html}");
    }

    #[test]
    fn a_select_marks_the_option_that_matches() {
        let options = [Choice::plain("1"), Choice::plain("3")];
        let f = Field::select("title", "Title", &options);
        let html = field_html(&f, &Filling::of(Value::Text("3")), &Emit::default());
        assert!(
            html.contains("<option value=\"3\" selected>3</option>"),
            "{html}"
        );
        assert!(html.contains("<option value=\"1\">1</option>"), "{html}");
        assert!(!html.contains("data-unmatched"), "{html}");
    }

    #[test]
    fn a_textarea_carries_its_value_as_text_and_not_as_an_attribute() {
        let filling = Filling::of(Value::Text("two\nlines"));
        let html = field_html(&field(FieldKind::Textarea), &filling, &Emit::default());
        assert!(html.contains(">two\nlines</textarea>"), "{html}");
    }

    #[test]
    fn a_markdown_field_is_a_textarea_that_says_what_its_value_is() {
        // The mark is the whole difference. Without it a described editor is a
        // plain box, and an enhancement looking for editors to upgrade has
        // nothing to find -- which is the state MNW's four hand-written section
        // editors would have had to keep living in.
        let filling = Filling::of(Value::Text("# Heading"));
        let html = field_html(&field(FieldKind::Rich), &filling, &Emit::default());
        assert!(html.contains("<textarea"), "{html}");
        assert!(html.contains(r#"data-format="markdown""#), "{html}");
        assert!(html.contains("># Heading</textarea>"), "{html}");

        // A plain textarea claims nothing about its value, so the marker has to
        // be absent rather than present-and-different.
        let plain = field_html(&field(FieldKind::Textarea), &filling, &Emit::default());
        assert!(!plain.contains("data-format"), "{plain}");

        // And it is not an input: the catch-all in `input_type` would have
        // degraded it to a single-line text box, which is the wrong shape for
        // markdown rather than a lossless fallback.
        assert!(!html.contains("<input"), "{html}");
    }

    #[test]
    fn a_markdown_field_gets_the_preview_the_member_permits() {
        // The mark on its own is what 0.50.0 shipped, and nothing read it. What
        // a conversion needs is the pair MNW's `partial-item-text-editor.js`
        // already draws, so describing the field is not a way to lose it.
        let filling = Filling::of(Value::Text("# Heading"));
        let html = field_html(&field(FieldKind::Rich), &filling, &Emit::default());
        assert!(html.contains("data-editor-mode=\"write\""), "{html}");
        assert!(html.contains("data-editor-mode=\"preview\""), "{html}");
        assert!(html.contains("data-editor-preview"), "{html}");
        // Write is the mode a fresh editor is in, and the segment says so twice
        // because the sheet reads one and a screen reader reads the other.
        assert!(
            html.contains(
                "class=\"segment chosen\" data-editor-mode=\"write\" aria-pressed=\"true\""
            ),
            "{html}"
        );
        assert!(
            html.contains("data-editor-mode=\"preview\" aria-pressed=\"false\""),
            "{html}"
        );
        // The value is still the textarea's, and still text rather than an
        // attribute. The chrome sits around the control, not in place of it.
        assert!(html.contains("># Heading</textarea>"), "{html}");
    }

    #[test]
    fn a_plain_textarea_gets_no_editor_chrome() {
        let filling = Filling::of(Value::Text("plain"));
        let html = field_html(&field(FieldKind::Textarea), &filling, &Emit::default());
        assert!(!html.contains("data-editor-mode"), "{html}");
        assert!(!html.contains("data-editor-preview"), "{html}");
        assert!(!html.contains("segment"), "{html}");
    }

    #[test]
    fn nothing_the_editor_emits_renders_the_value_as_markup() {
        // The whole of this crate's half of the sanitising question: the pane is
        // empty, so no value reaches markup through it, and the host's own
        // renderer keeps the guarantee it already has.
        let filling = Filling::of(Value::Text("<img src=x onerror=alert(1)>"));
        let html = field_html(&field(FieldKind::Rich), &filling, &Emit::default());
        assert!(html.contains("data-editor-preview></div>"), "{html}");
        assert!(!html.contains("<img"), "{html}");
        assert!(
            html.contains("&lt;img src=x onerror=alert(1)&gt;"),
            "{html}"
        );
    }

    #[test]
    fn the_editor_rules_gate_on_the_attribute_and_on_a_binding() {
        let css = editor_rules(&Emit::default());
        // Behind the attribute, which is the reason the mark is an attribute:
        // a class-keyed gate would be prefixed away from the enhancement that
        // selects on it.
        for line in css.lines().filter(|line| line.contains('{')) {
            assert!(line.contains("[data-format=\"markdown\"]"), "{line}");
        }
        // Nothing is hidden and no control appears until something binds the
        // editor. A reader with no script gets the textarea alone.
        assert!(
            css.contains(
                "[data-format=\"markdown\"] > .form-editor-modes {\n    display: none;\n}"
            )
        );
        assert!(css.contains(
            "[data-format=\"markdown\"][data-ready] > .form-editor-modes {\n    display: block;\n}"
        ));
        assert!(css.contains(
            "[data-ready][data-mode=\"preview\"] > .form-editor-preview {\n    display: block;\n}"
        ));
        assert!(
            css.contains("[data-ready][data-mode=\"preview\"] > .field {\n    display: none;\n}")
        );
        // No magnitude, the line this crate holds everywhere else.
        assert!(!css.contains("px"), "{css}");
        assert!(!css.contains("rem"), "{css}");
    }

    /// The prefix reaches the chrome as well, and the gate deliberately does
    /// not: an app assembling the sheet with its own prefix still has the
    /// selector an enhancement finds the editors by.
    #[test]
    fn the_editor_chrome_is_prefixed_and_its_gate_is_not() {
        let opts = Emit {
            class_prefix: "mk-",
            ..Emit::default()
        };
        let html = field_html(&field(FieldKind::Rich), &Filling::default(), &opts);
        assert!(html.contains("class=\"mk-form-editor-modes\""), "{html}");
        assert!(html.contains("class=\"mk-form-editor-preview\""), "{html}");
        assert!(html.contains("class=\"mk-segment chosen\""), "{html}");
        assert!(html.contains("data-format=\"markdown\""), "{html}");

        let css = editor_rules(&opts);
        assert!(css.contains(".mk-form-editor-modes"), "{css}");
        assert!(css.contains("[data-format=\"markdown\"]"), "{css}");
    }

    /// Every class the editor puts in markup is one the generated sheet rules,
    /// which is `FACET_CLASSES`' obligation without a list to keep: these two
    /// have rules, so the vocabulary seal picks them up from the sheet itself.
    #[test]
    fn the_editor_classes_are_in_the_vocabulary() {
        let opts = Emit::default();
        let names = crate::vocabulary::names(&opts);
        for name in ["form-editor-modes", "form-editor-preview", "segment"] {
            assert!(names.contains(name), "{name} is not in the vocabulary");
        }
    }

    #[test]
    fn the_class_prefix_reaches_the_markup_as_well_as_the_stylesheet() {
        let opts = Emit {
            class_prefix: "mk-",
            ..Emit::default()
        };
        let html = field_html(&field(FieldKind::Text), &Filling::default(), &opts);
        assert!(html.contains("class=\"mk-form-group\""), "{html}");
        assert!(html.contains("class=\"mk-field\""), "{html}");
    }

    #[test]
    fn a_datetime_asking_for_an_instant_is_marked_for_the_script_that_converts_it() {
        let mut f = field(FieldKind::DateTime);
        f.as_instant = true;
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains("data-instant=\"true\""), "{html}");
        // The control is unchanged: the flag says what is submitted, not what
        // is drawn.
        assert!(html.contains("type=\"datetime-local\""), "{html}");
    }

    #[test]
    fn only_a_datetime_can_name_a_moment_so_only_a_datetime_is_marked() {
        for kind in [FieldKind::Date, FieldKind::Text, FieldKind::Number] {
            let mut f = field(kind);
            f.as_instant = true;
            let html = field_html(&f, &Filling::default(), &Emit::default());
            assert!(!html.contains("data-instant"), "{kind:?}: {html}");
        }
    }

    #[test]
    fn a_datetime_that_did_not_ask_carries_no_mark() {
        let html = field_html(
            &field(FieldKind::DateTime),
            &Filling::default(),
            &Emit::default(),
        );
        assert!(!html.contains("data-instant"), "{html}");
    }

    #[test]
    fn an_extended_field_says_so_and_leaves_the_disclosure_to_the_form() {
        let mut f = field(FieldKind::Text);
        f.extended = true;
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains("data-extended=\"true\""), "{html}");
    }

    /// The prefix scopes the id and leaves the name alone. Prefixing the name
    /// too would change what the form submits, which is the failure this pair
    /// of assertions exists to catch rather than describe.
    #[test]
    fn the_id_prefix_scopes_the_id_and_never_the_name() {
        let mut f = field(FieldKind::Text);
        f.hint = Some("Keep it short");
        f.error = Some("Required");
        let filling = Filling {
            id_prefix: Some("form-modal-task-edit"),
            ..Filling::default()
        };
        let html = field_html(&f, &filling, &Emit::default());

        assert!(
            html.contains(r#"id="form-modal-task-edit-title""#),
            "{html}"
        );
        assert!(html.contains(r#"name="title""#), "{html}");
        assert!(
            !html.contains(r#"name="form-modal-task-edit-title""#),
            "{html}"
        );

        // The label and both associations follow the id, or they point at
        // nothing once the same form is on screen twice.
        assert!(
            html.contains(r#"for="form-modal-task-edit-title""#),
            "{html}"
        );
        assert!(
            html.contains(
                r#"aria-describedby="form-modal-task-edit-title-hint form-modal-task-edit-title-error""#
            ),
            "{html}"
        );
        assert!(
            html.contains(r#"id="form-modal-task-edit-title-hint""#),
            "{html}"
        );
    }

    #[test]
    fn a_hidden_field_submits_its_bare_name_under_a_prefix() {
        let filling = Filling {
            value: Value::Text("42"),
            id_prefix: Some("scoped"),
            ..Filling::default()
        };
        let html = field_html(&field(FieldKind::Hidden), &filling, &Emit::default());
        assert_eq!(html, r#"<input type="hidden" name="title" value="42">"#);
    }

    /// These three exist so a touch keyboard and the platform's validation
    /// arrive with the field. Emitting text for any of them is the regression
    /// the variants were added to prevent, so the type is asserted directly.
    #[test]
    fn a_constraint_becomes_the_browsers_own_attribute() {
        // makeover-layout 0.11.0's model: the description carries the rule and
        // each renderer emits its host's idiom for it. Enforcement is still
        // whoever validated's, and arrives back as `error`.
        let html = field_html(
            &Field {
                max_length: Some(100),
                min: Some("1"),
                max: Some("240"),
                required: true,
                ..Field::new(FieldKind::Number, "minutes", "Minutes")
            },
            &Filling::default(),
            &Emit::default(),
        );
        assert!(html.contains(r#"maxlength="100""#));
        assert!(html.contains(r#"min="1""#));
        assert!(html.contains(r#"max="240""#));
        assert!(html.contains(" required"));
    }

    #[test]
    fn a_bound_is_emitted_as_written_and_escaped_like_anything_else() {
        // The bound is text because it is only a number for some of the kinds
        // that take one; goingson's own sites are a duration and a datetime.
        let html = field_html(
            &Field {
                min: Some("2026-08-09T14:30"),
                ..Field::new(FieldKind::Text, "starts", "Starts")
            },
            &Filling::default(),
            &Emit::default(),
        );
        assert!(html.contains(r#"min="2026-08-09T14:30""#));
    }

    #[test]
    fn a_file_field_is_a_file_input() {
        // `844b5ae0`. A field that takes any file emits no `accept` at all,
        // which is the browser's own "any file". `accept=""` is a filter that
        // means nothing on one browser and everything on another.
        let html = field_html(
            &Field::new(FieldKind::File, "attachment", "Attachment"),
            &Filling::default(),
            &Emit::default(),
        );
        assert!(html.contains(r#"type="file""#));
        assert!(!html.contains("accept="));
        assert!(!html.contains("multiple"));
        // And it never carries a value: a file input's value is not settable
        // from markup, and the browser refuses one that tries.
        assert!(!html.contains("value="));
    }

    #[test]
    fn an_accept_list_is_comma_joined_in_the_attributes_own_format() {
        // `f7261a5a`, makeover-layout 0.31.0. Each entry writes itself: a
        // family is its wildcard, a media type is itself, a suffix keeps its
        // leading dot and however many more it has.
        const MIXED: &[Accepted<'_>] = &[
            Accepted::Family(Family::Image),
            Accepted::Type("text/csv"),
            Accepted::Suffix(".tar.gz"),
        ];
        let html = field_html(
            &Field {
                multiple: true,
                ..Field::upload("drop", "Drop files", MIXED)
            },
            &Filling::default(),
            &Emit::default(),
        );
        assert!(
            html.contains(r#"accept="image/*,text/csv,.tar.gz""#),
            "{html}"
        );
        assert!(html.contains(" multiple"), "{html}");
    }

    #[test]
    fn an_accept_entry_cannot_end_the_attribute_it_sits_in() {
        // The list reaches an attribute value, so it is escaped like every
        // other string that does. Nothing in the tree writes a quote into one;
        // that it cannot is the point.
        const HOSTILE: &[Accepted<'_>] = &[Accepted::Type(r#"image/x" onload="x"#)];
        let html = field_html(
            &Field::upload("cover", "Cover", HOSTILE),
            &Filling::default(),
            &Emit::default(),
        );
        assert!(!html.contains(r#"onload="x"#), "{html}");
    }

    #[test]
    fn the_typed_text_kinds_keep_their_input_type() {
        for (kind, expected) in [
            (FieldKind::Email, "email"),
            (FieldKind::Url, "url"),
            (FieldKind::Tel, "tel"),
            (FieldKind::Date, "date"),
            (FieldKind::DateTime, "datetime-local"),
        ] {
            let html = field_html(&field(kind), &Filling::default(), &Emit::default());
            assert!(
                html.contains(&format!(r#"type="{expected}""#)),
                "{kind:?} emitted {html}"
            );
        }
    }

    #[test]
    fn a_temporal_field_is_a_native_control_and_not_a_hinted_text_box() {
        // The regression this closes: described as text with a hint reading
        // "YYYY-MM-DD", which loses the picker, the platform's validation and
        // the touch keyboard, and asks prose to do all three.
        for kind in [FieldKind::Date, FieldKind::DateTime] {
            let html = field_html(&field(kind), &Filling::default(), &Emit::default());
            assert!(!html.contains(r#"type="text""#), "{kind:?} emitted {html}");
        }
    }

    #[test]
    fn no_prefix_leaves_the_id_as_the_name() {
        let html = field_html(
            &field(FieldKind::Text),
            &Filling::default(),
            &Emit::default(),
        );
        assert!(html.contains(r#"id="title" name="title""#), "{html}");
    }

    /// Two variants and two tiers, which is the smallest list that can show
    /// where a group opens and that two badges differ.
    const THEMES: &[makeover_layout::ThemeChoice<'_>] = &[
        makeover_layout::ThemeChoice::new(
            "goingson",
            "GoingsOn",
            ThemeVariant::Light,
            makeover_layout::Contrast::High,
        ),
        makeover_layout::ThemeChoice::new(
            "ayu-light",
            "Ayu Light",
            ThemeVariant::Light,
            makeover_layout::Contrast::Low,
        ),
        makeover_layout::ThemeChoice::new(
            "carbonfox",
            "Carbonfox",
            ThemeVariant::Dark,
            makeover_layout::Contrast::High,
        ),
    ];

    #[test]
    fn a_theme_picker_opens_one_optgroup_per_variant() {
        let f = Field::theme("theme", "Theme", THEMES);
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert_eq!(html.matches("<optgroup").count(), 2, "{html}");
        assert_eq!(html.matches("</optgroup>").count(), 2, "{html}");
        assert!(
            html.contains(r#"<optgroup label="Light" data-variant="light">"#),
            "{html}"
        );
        assert!(
            html.contains(r#"<optgroup label="Dark" data-variant="dark">"#),
            "{html}"
        );
        // The two light themes share one group: a new group opens on a change
        // of variant and on nothing else.
        assert!(
            html.find("Ayu Light") < html.find("<optgroup label=\"Dark\""),
            "{html}"
        );
    }

    #[test]
    fn every_theme_carries_its_measured_tier() {
        // The fact the three hand-written pickers lost. It rides in the text
        // because a `<select>`'s options take no elements, and in an attribute
        // because a stylesheet cannot read text.
        let f = Field::theme("theme", "Theme", THEMES);
        let html = field_html(&f, &Filling::default(), &Emit::default());

        assert!(html.contains(r#"data-contrast="high""#), "{html}");
        assert!(html.contains(r#"data-contrast="low""#), "{html}");
        assert!(html.contains("GoingsOn (AA)"), "{html}");
        assert!(html.contains("Ayu Light (low)"), "{html}");
    }

    #[test]
    fn the_follow_row_is_first_and_sits_in_no_group() {
        // It names no theme and belongs to no variant, so grouping it would be
        // inventing a fourth variant for one row.
        let f = Field::theme("theme", "Theme", THEMES)
            .following(Choice::new("system", "Follow System"));
        let html = field_html(&f, &Filling::default(), &Emit::default());

        let follow = html.find("Follow System").expect("the row was offered");
        assert!(follow < html.find("<optgroup").expect("groups"), "{html}");
    }

    #[test]
    fn the_stored_theme_is_the_selected_one() {
        let f = Field::theme("theme", "Theme", THEMES)
            .following(Choice::new("system", "Follow System"));

        let named = field_html(&f, &Filling::of(Value::Text("carbonfox")), &Emit::default());
        assert!(
            named.contains(r#"value="carbonfox" data-contrast="high" selected"#),
            "{named}"
        );
        assert!(!named.contains(r#"value="system" selected"#), "{named}");

        let following = field_html(&f, &Filling::of(Value::Text("system")), &Emit::default());
        assert!(
            following.contains(r#"value="system" selected"#),
            "{following}"
        );
    }

    #[test]
    fn a_theme_that_is_no_longer_installed_keeps_its_value() {
        // `push_options`' rule, met again: a value no row carries is a wrong
        // answer rather than an absent one, and dropping it would save a
        // different theme over the user's on the next write.
        let f = Field::theme("theme", "Theme", THEMES);
        let html = field_html(
            &f,
            &Filling::of(Value::Text("deleted-theme")),
            &Emit::default(),
        );
        assert!(html.contains(r#"data-unmatched="true""#), "{html}");
        assert!(
            html.contains(r#"<option value="deleted-theme" selected"#),
            "{html}"
        );
    }

    #[test]
    fn the_follow_row_is_not_a_stray_value() {
        // The near-miss: `system` is carried by no `ThemeChoice`, so a check
        // that only walked the theme list would emit a duplicate unmatched row
        // beside the real one.
        let f = Field::theme("theme", "Theme", THEMES)
            .following(Choice::new("system", "Follow System"));
        let html = field_html(&f, &Filling::of(Value::Text("system")), &Emit::default());
        assert!(!html.contains("data-unmatched"), "{html}");
    }

    #[test]
    fn a_machine_with_no_themes_still_gets_a_picker() {
        // `Field::themes`' own position: an app whose theme directories hold
        // nothing has exactly this, and the empty control says so on screen.
        let f =
            Field::theme("theme", "Theme", &[]).following(Choice::new("system", "Follow System"));
        let html = field_html(&f, &Filling::default(), &Emit::default());
        assert!(html.contains("<select"), "{html}");
        assert!(!html.contains("<optgroup"), "{html}");
        assert!(html.contains("Follow System"), "{html}");
    }
}