makeover-webview 0.100.0

//! A dimension a set is narrowed by, rendered as a list of values.
//!
//! The fourth phase-B emitter, beside [`form`](crate::form),
//! [`list`](crate::list) and [`meter`](crate::meter). Same split as those: this
//! owns the structure of the panel and the app owns the routes. A value's
//! identifier leaves in `data-facet-value`, which is the hook an app wires its
//! own request onto, exactly as [`list`](crate::list) writes `data-column` and
//! lets the app decide what pressing a heading calls.
//!
//! # Why this is markup and not only CSS
//!
//! Phase A's rule is that an app keeps its markup and gains the classes, and
//! that rule works because the markup already existed. Here it mostly does not:
//! a facet panel is the shape MNW's discover page reached by writing a tick box
//! and a chevron per row because filtering and browsing were two mechanisms, and
//! the whole point of [`makeover_layout::Selecting::Subtree`] is that they stop
//! being two. There is nothing to keep.
//!
//! # The one thing drawn that no flat control has
//!
//! An exclude affordance beside each value, in a subtree facet only. It is a
//! visible control rather than a modifier or a long press, and that was ruled
//! rather than chosen here: a gesture a terminal cannot express is a gesture
//! half the renderers leave out, and an affordance nothing teaches is one users
//! do not find. The glyph is this renderer's pick, and it takes the standing
//! preference for the heavier, simpler mark.
//!
//! # What the depth does and does not do
//!
//! `--facet-depth` carries the tree level as a number, and the indent rule
//! multiplies it by one geometry step. That keeps the whole tree one flat list
//! in the DOM rather than nested lists, which is what lets a renderer draw the
//! same description as a breadcrumb or a column of panes without the markup
//! disagreeing. It is not a size: the number is the level, and the step is
//! `makeover-geometry`'s.

use crate::form::escape_into;
use crate::reset::Reset;
use crate::{Emit, class, push_class};
use makeover_layout::{Depth, Facet, FacetValue, GroupRank, Join, Selecting, Standing};
use std::fmt::Write as _;

/// The classes this module can put in markup.
///
/// [`crate::list::ROW_PART_CLASSES`]' obligation, and it exists for the same
/// reason: every class here is also ruled by `facet_rules`, so the vocabulary
/// seal picks them up from the generated sheet, and this list is what a test
/// checks that against.
pub const FACET_CLASSES: &[&str] = &[
    "facet",
    "facet-name",
    "facet-values",
    "facet-value",
    "facet-take",
    "facet-count",
    "facet-prune",
    "facet-rank",
    "facet-start",
    "facet-cut",
    "facet-join",
    "facet-join-word",
];

/// What a value is to a reader, as `data-kind` says it: a pick, a group's
/// heading (pressing opens it), or a link row (pressing is its whole meaning).
#[must_use]
pub const fn kind_name(value: &FacetValue<'_>) -> &'static str {
    if value.pickable {
        "value"
    } else if value.branching {
        "heading"
    } else {
        "link"
    }
}

/// The name a selection mode goes by in `data-selecting`.
///
/// An attribute rather than a class, for `data-selector`'s reason on a selector
/// group: the mode changes what the panel *means*, not how one value is
/// painted, and a class there would read as the styling hook the value's class
/// actually is.
#[must_use]
pub const fn selecting_name(mode: Selecting) -> &'static str {
    match mode {
        Selecting::OneOf => "one-of",
        Selecting::AnyOf => "any-of",
        Selecting::Range => "range",
        Selecting::Text => "text",
        Selecting::Subtree => "subtree",
        // A mode added to the description since this renderer was built.
        // `Selecting` is `#[non_exhaustive]`, and an unknown mode reads as the
        // one that offers no values and prunes nothing: drawing a value list
        // for a mode whose values mean something else is the worse mistake.
        _ => "unknown",
    }
}

/// The name a standing goes by in `data-standing`.
#[must_use]
pub const fn standing_name(standing: Standing) -> &'static str {
    match standing {
        Standing::Open => "open",
        Standing::Taken => "taken",
        Standing::Inherited => "inherited",
        Standing::Pruned => "pruned",
        Standing::PrunedAbove => "pruned-above",
        // Unknown reads as open, which is the state that claims nothing about
        // the set.
        _ => "open",
    }
}

/// A facet as a labelled list of values.
///
/// ```
/// use makeover_layout::{Facet, FacetValue, Nesting, Selecting, Standing};
/// use makeover_webview::{Emit, facet::facet_html};
///
/// let values = [
///     FacetValue::new("music", "Music")
///         .standing(Standing::Taken)
///         .counted(128)
///         .at(Nesting::at(0), true),
///     FacetValue::new("music/synths", "Synths").at(Nesting::at(1), false),
/// ];
/// let facet = Facet::new("Tag", Selecting::Subtree, &values);
/// let html = facet_html(&facet, &Emit::default());
///
/// assert!(html.contains(r#"data-selecting="subtree""#));
/// assert!(html.contains(r#"data-facet-value="music/synths""#));
/// // A subtree is the one mode that offers a way to prune a branch out.
/// assert!(html.contains("facet-prune"));
/// ```
///
/// A [`Selecting::Text`] or [`Selecting::Range`] facet lists nothing, so what
/// comes back is the panel and its name with an empty list inside it. That is
/// deliberate rather than an empty string: the app puts its own box in the
/// panel, and the panel is what gives the box the group label and the shared
/// geometry.
#[must_use]
pub fn facet_html(facet: &Facet<'_>, opts: &Emit) -> String {
    let mut html = String::new();
    facet_html_into(facet, opts, &mut html);
    html
}

/// A facet, written into a buffer the caller already has.
///
/// [`facet_html`]'s streaming form, byte-identical to it.
pub fn facet_html_into(facet: &Facet<'_>, opts: &Emit, out: &mut String) {
    emit_facet(facet, opts, out, None);
}

/// A facet, saying where each value landed.
///
/// Byte-identical to [`facet_html_into`], and it appends one entry to `placed`
/// per value drawn, in order: the offsets in `out` between which that value's
/// whole `<li>` was written. For a caller compiling this markup into a
/// template: a value's label may appear elsewhere in the document, so the
/// writer is the only source for which bytes one value produced.
pub fn facet_html_placed(
    facet: &Facet<'_>,
    opts: &Emit,
    out: &mut String,
    placed: &mut Vec<core::ops::Range<usize>>,
) {
    emit_facet(facet, opts, out, Some(placed));
}

fn emit_facet(
    facet: &Facet<'_>,
    opts: &Emit,
    out: &mut String,
    mut placed: Option<&mut Vec<core::ops::Range<usize>>>,
) {
    out.push_str("<div class=\"");
    push_class(out, "facet", opts);
    out.push_str("\" role=\"group\" data-selecting=\"");
    out.push_str(selecting_name(facet.mode));
    // The gutter an indenting renderer reserves before it draws anything, so
    // the panel does not widen as deeper values arrive. "First paint is final
    // paint" applied to a tree.
    let _ = write!(
        out,
        "\" {}=\"--facet-reach: {}\">",
        crate::VARS_ATTR,
        facet.reach()
    );

    out.push_str("<p class=\"");
    push_class(out, "facet-name", opts);
    out.push_str("\">");
    escape_into(facet.name, out);
    out.push_str("</p>");

    out.push_str("<ul class=\"");
    push_class(out, "facet-values", opts);
    out.push_str("\">");
    if facet.mode.offers_values() {
        for value in facet.values {
            let at = out.len();
            value_html_into(facet, value, opts, out);
            if let Some(placed) = placed.as_deref_mut() {
                placed.push(at..out.len());
            }
        }
    }
    out.push_str("</ul></div>");
}

fn value_html_into(facet: &Facet<'_>, value: &FacetValue<'_>, opts: &Emit, out: &mut String) {
    out.push_str("<li class=\"");
    push_class(out, "facet-value", opts);
    out.push_str("\" data-standing=\"");
    out.push_str(standing_name(value.standing));
    out.push_str("\" data-kind=\"");
    out.push_str(kind_name(value));
    let _ = write!(
        out,
        "\" {}=\"--facet-depth: {}\">",
        crate::VARS_ATTR,
        value.depth.level
    );

    out.push_str("<button type=\"button\" class=\"");
    push_class(out, "facet-take", opts);
    out.push_str("\" data-facet-value=\"");
    escape_into(value.value, out);
    out.push('"');
    // `aria-pressed` and not `aria-selected`: the values are toggles over a set
    // rather than options in a listbox, and an inherited value is pressed in
    // fact even though nobody pressed it. That is `Standing::in_force`, which
    // exists so a renderer does not have to know which of the two it has. A
    // heading or a link row picks nothing, so it is not a toggle at all.
    if value.pickable {
        out.push_str(" aria-pressed=\"");
        out.push_str(if value.standing.in_force() {
            "true\""
        } else {
            "false\""
        });
    }
    // A branch that opens says so, so a reader is told there is more before
    // pressing rather than after. Open is its own state where the app keeps
    // one, since opening a group is not picking it.
    if value.branching {
        out.push_str(" aria-expanded=\"");
        out.push_str(if value.is_open() { "true\"" } else { "false\"" });
    }
    out.push('>');
    escape_into(value.label, out);

    // Absent rather than zero when it was not measured, which is the
    // description's own position: a written zero reads as "none of them". A
    // gain is what picking adds beside a pick already made under the same
    // parent, so it carries its sign.
    if let Some(count) = value.count {
        out.push_str("<span class=\"");
        push_class(out, "facet-count", opts);
        let sign = if value.gain { "+" } else { "" };
        let _ = write!(out, "\">{sign}{count}</span>");
    } else if let Some(rank) = value.rank {
        rank_html_into(rank, opts, out);
    }
    out.push_str("</button>");

    if !value.pickable
        && value.is_open()
        && let Some(join) = value.join
    {
        join_html_into(value, join, opts, out);
    }

    if facet.mode.prunes() && value.pickable {
        out.push_str("<button type=\"button\" class=\"");
        push_class(out, "facet-prune", opts);
        out.push_str("\" data-facet-value=\"");
        escape_into(value.value, out);
        out.push_str("\" aria-pressed=\"");
        out.push_str(if value.standing == Standing::Pruned {
            "true\""
        } else {
            "false\""
        });
        // The accessible name is built here rather than described: a tooltip
        // wants a sentence and a terminal wants a glyph, and a description shipping either would choose for
        // both.
        out.push_str(" aria-label=\"");
        escape_into(opts.exclude_label, out);
        out.push(' ');
        escape_into(value.label, out);
        // The heavier, simpler mark. It is the glyph and not a class, because a
        // renderer that swaps it is not changing what the control means.
        out.push_str("\">\u{2715}</button>");
    }

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

/// Where a group ranks, at the end of its heading: the start mark, then a bar
/// whose length is the cut, or a word when the group is in use or dead.
///
/// The bar is drawn, not written: its length is `--facet-cut` through
/// [`VARS_ATTR`](crate::VARS_ATTR), as the depth is, so a strict style policy
/// refuses nothing. It is hidden from the accessibility tree, since the order
/// of the groups already says what the bars do.
pub fn rank_html_into(rank: GroupRank, opts: &Emit, out: &mut String) {
    out.push_str("<span class=\"");
    push_class(out, "facet-rank", opts);
    out.push_str("\">");
    if rank.start {
        out.push_str("<span class=\"");
        push_class(out, "facet-start", opts);
        out.push_str("\">");
        escape_into(opts.start_label, out);
        out.push_str("</span>");
    }
    if rank.in_use || !rank.live {
        out.push_str("<span class=\"");
        push_class(out, "facet-count", opts);
        out.push_str("\">");
        escape_into(
            if rank.in_use {
                opts.in_use_label
            } else {
                opts.dead_label
            },
            out,
        );
        out.push_str("</span>");
    } else {
        out.push_str("<span class=\"");
        push_class(out, "facet-cut", opts);
        let _ = write!(
            out,
            "\" aria-hidden=\"true\" {}=\"--facet-cut: {}%\"></span>",
            crate::VARS_ATTR,
            rank.cut
        );
    }
    out.push_str("</span>");
}

/// The toggle on an open group: how the picks under it combine. Two words, the
/// one in force pressed, each naming the group in `data-facet-value` and its
/// word in `data-facet-join` for the app to wire, as the take and the prune do.
fn join_html_into(value: &FacetValue<'_>, join: Join, opts: &Emit, out: &mut String) {
    out.push_str("<span class=\"");
    push_class(out, "facet-join", opts);
    out.push_str("\" role=\"group\" aria-label=\"");
    escape_into(opts.join_label, out);
    out.push(' ');
    escape_into(value.label, out);
    out.push_str("\">");
    for (word, label) in [(Join::Any, opts.any_label), (Join::All, opts.all_label)] {
        out.push_str("<button type=\"button\" class=\"");
        push_class(out, "facet-join-word", opts);
        out.push_str("\" data-facet-value=\"");
        escape_into(value.value, out);
        out.push_str("\" data-facet-join=\"");
        out.push_str(join_name(word));
        out.push_str("\" aria-pressed=\"");
        out.push_str(if word == join { "true\">" } else { "false\">" });
        escape_into(label, out);
        out.push_str("</button>");
    }
    out.push_str("</span>");
}

/// The name a join goes by in `data-facet-join`.
#[must_use]
pub const fn join_name(join: Join) -> &'static str {
    match join {
        Join::All => "all",
        // Unknown reads as any, the default every parent starts at.
        _ => "any",
    }
}

/// The rules for a facet panel.
///
/// Depth comes from the description: a value at rest sits as
/// [`Depth::Flat`] and a taken one is held in, which is
/// [`makeover_layout::Selector::chosen`]'s shape for a segment and is the same
/// sentence, this one is picked, so it is pressed. Nothing here states a
/// colour or a size; the indent is a count multiplied by a geometry step, and
/// the step is the one variable this crate is allowed to read.
pub(crate) fn facet_rules(opts: &Emit) -> String {
    let mut css = String::new();
    let panel = class("facet", opts);
    let name = class("facet-name", opts);
    let values = class("facet-values", opts);
    let value = class("facet-value", opts);
    let take = class("facet-take", opts);
    let count = class("facet-count", opts);
    let prune = class("facet-prune", opts);

    // The name of the dimension. A caption, and captions are legitimately
    // muted: it was never going to answer a press.
    let _ = writeln!(css, ".{name} {{\n    color: var(--content-muted);\n}}");

    // The list gives back what a `<ul>` brought, the same ask `row_rules`
    // makes: a described set of tags is not a bulleted list and rendered as one
    // because nothing said otherwise.
    css.push_str(&Reset::BULLETS.rule(&format!(".{values}")));

    // A value is one line: its control, then its exclude control. The indent
    // is the level times one geometry step. `--facet-depth` is written per value
    // and `--facet-reach` per panel; the panel one reserves the gutter so
    // nothing moves as deeper values arrive. Both read `--gap-group`, which
    // makeover-geometry defines: they read `--space-tight`, which nothing
    // defines, and so always took the literal fallback.
    let _ = writeln!(
        css,
        ".{value} {{\n    display: flex;\n    align-items: center;\n    gap: var(--gap-bound);\n    padding-inline-start: calc(var(--facet-depth, 0) * var(--gap-group));\n}}"
    );

    let _ = writeln!(
        css,
        ".{panel} {{\n    min-inline-size: calc(var(--facet-reach, 0) * var(--gap-group));\n}}"
    );

    // The value's own control. Flat at rest, held in when it is in force, and
    // that is the segmented control's sentence rather than a new one.
    //
    // Flat states nothing, no fill and no bevel, so `depth_rule` emitted an
    // empty string and saying it was the whole of what this arm did. Where an
    // app hands makeover the cascade with `revert-layer`, an empty layer rolls
    // the handoff past makeover to the app's own bare `button` rule and the
    // value renders raised, with `[aria-pressed="true"]` its only true state.
    // Flat here has to be said out loud, which is what the reset is for.
    css.push_str(&Reset::FLAT_BUTTON.rule(&format!(".{take}")));
    // The control fills the line, label at its start and count at its end, so
    // the counts of a column of values line up. It reads as content whichever
    // element it is: a host giving a value a real address draws an anchor,
    // which would otherwise wear link colour and an underline.
    let _ = writeln!(
        css,
        ".{take} {{\n    display: flex;\n    flex: 1 1 auto;\n    align-items: center;\n    justify-content: space-between;\n    gap: var(--gap-peer);\n    min-block-size: var(--tap-target, 2rem);\n    padding: 0 var(--gap-bound);\n    color: var(--content);\n    text-decoration: none;\n    text-align: start;\n    font: inherit;\n}}"
    );
    css.push_str(&crate::interactive_rules(&take, Depth::Flat, opts));
    css.push_str(&held_rules(&take));

    // A pruned branch reads one step back and stays live: pressing it takes the
    // prune off, so it may not wear `content-muted`. `Standing::intent` is
    // where that is decided. A value out because a branch above it was pruned
    // reads the same, since to the set the two mean the same thing; the
    // attribute keeps the difference for whoever wants it, as with inherited.
    for standing in [Standing::Pruned, Standing::PrunedAbove] {
        let _ = writeln!(
            css,
            ".{value}[data-standing=\"{}\"] .{take} {{\n    color: var(--{});\n}}",
            standing_name(standing),
            standing.intent()
        );
    }

    // Inherited is in force and was not chosen. It reads as the thing itself,
    // like a taken value, and the difference is carried by the attribute for
    // whoever wants it rather than by a colour claiming something.
    // Figures of one width, so a column of counts reads down.
    let _ = writeln!(
        css,
        ".{count} {{\n    color: var(--content-muted);\n    font-variant-numeric: tabular-nums;\n}}"
    );

    // Same withdrawal as the take, for the same reason, and a square target at
    // the end of the line. It reads one step back: it is an offer about the
    // value, not the value.
    css.push_str(&Reset::FLAT_BUTTON.rule(&format!(".{prune}")));
    let _ = writeln!(
        css,
        ".{prune} {{\n    display: inline-flex;\n    align-items: center;\n    justify-content: center;\n    min-block-size: var(--tap-target, 2rem);\n    min-inline-size: var(--tap-target, 2rem);\n    color: var(--content-secondary);\n    text-decoration: none;\n    font: inherit;\n}}"
    );
    css.push_str(&crate::interactive_rules(&prune, Depth::Flat, opts));
    css.push_str(&held_rules(&prune));

    // A group's heading reads as a heading: the label carries the weight a
    // section caption does, and nothing about it says pressed, because
    // opening a group picks nothing.
    let rank = class("facet-rank", opts);
    let start = class("facet-start", opts);
    let cut = class("facet-cut", opts);
    let join = class("facet-join", opts);
    let word = class("facet-join-word", opts);
    let _ = writeln!(
        css,
        ".{value}[data-kind=\"heading\"] .{take} {{\n    font-weight: bold;\n}}"
    );
    // A link row is an offer about the list, not a member of it: one step
    // back, and live.
    let _ = writeln!(
        css,
        ".{value}[data-kind=\"link\"] .{take} {{\n    color: var(--content-secondary);\n}}"
    );

    // The rank sits where a count would, at the line's end: the start mark,
    // then the bar. The bar's track is the ramp's own neutral step and its
    // fill the content tone, so no hue claims anything about a group.
    let _ = writeln!(
        css,
        ".{rank} {{\n    display: inline-flex;\n    align-items: center;\n    gap: var(--gap-peer);\n    font-weight: normal;\n}}"
    );
    let _ = writeln!(css, ".{start} {{\n    color: var(--content-secondary);\n}}");
    let _ = writeln!(
        css,
        ".{cut} {{\n    inline-size: calc(var(--gap-pane) * 2);\n    block-size: var(--gap-bound);\n    background: linear-gradient(to right, var(--content-secondary) var(--facet-cut, 0%), var(--surface-raised) 0);\n}}"
    );

    // The join toggle: two words, the one in force held in, the segmented
    // control's sentence again.
    let _ = writeln!(
        css,
        ".{join} {{\n    display: inline-flex;\n    flex: none;\n}}"
    );
    css.push_str(&Reset::FLAT_BUTTON.rule(&format!(".{word}")));
    let _ = writeln!(
        css,
        ".{word} {{\n    min-block-size: var(--tap-target, 2rem);\n    padding: 0 var(--gap-bound);\n    color: var(--content-secondary);\n    font: inherit;\n}}"
    );
    css.push_str(&crate::interactive_rules(&word, Depth::Flat, opts));
    css.push_str(&held_rules(&word));

    css
}

/// A control held in while it is in force, whichever element it turned out to
/// be.
///
/// This emitter writes buttons, which say it with `aria-pressed`. A host that
/// gives a value a real address writes an anchor for a read, and an anchor says
/// it with `aria-current`, since `aria-pressed` means nothing on one. Keyed on
/// the first alone, a taken value drawn as a link looked exactly like an
/// untaken one.
fn held_rules(class: &str) -> String {
    let mut css = String::new();
    for state in ["aria-pressed", "aria-current"] {
        css.push_str(&crate::depth_rule(
            &format!("{class}[{state}=\"true\"]"),
            Depth::Well,
        ));
    }
    css
}

#[cfg(test)]
mod tests {
    use super::*;
    use makeover_layout::Nesting;

    fn tag_values() -> [FacetValue<'static>; 3] {
        [
            FacetValue::new("music", "Music")
                .standing(Standing::Taken)
                .counted(128)
                .at(Nesting::at(0), true),
            FacetValue::new("music/synths", "Synths")
                .standing(Standing::Inherited)
                .at(Nesting::at(1), false),
            FacetValue::new("music/drums", "Drums")
                .standing(Standing::Pruned)
                .at(Nesting::at(1), false),
        ]
    }

    #[test]
    fn a_streamed_facet_is_the_facet_the_other_form_returns() {
        let opts = Emit {
            class_prefix: "mk-",
            ..Emit::default()
        };
        let values = tag_values();
        for facet in [
            Facet::new("Tag", Selecting::Subtree, &values),
            Facet::new("Type", Selecting::AnyOf, &values),
            Facet::new("Search", Selecting::Text, &[]),
        ] {
            let mut streamed = String::new();
            facet_html_into(&facet, &opts, &mut streamed);
            assert_eq!(streamed, facet_html(&facet, &opts));
        }
    }

    #[test]
    fn only_a_subtree_draws_an_exclude_affordance() {
        // The one control a flat facet has no use for: excluding a value there
        // is the same fact as not picking it.
        let values = tag_values();
        let subtree = facet_html(
            &Facet::new("Tag", Selecting::Subtree, &values),
            &Emit::default(),
        );
        assert!(subtree.contains("facet-prune"));
        assert!(subtree.contains(r#"aria-label="Exclude Drums""#));

        let flat = facet_html(
            &Facet::new("Type", Selecting::AnyOf, &values),
            &Emit::default(),
        );
        assert!(!flat.contains("facet-prune"));
    }

    #[test]
    fn an_inherited_value_reads_as_pressed_without_having_been_pressed() {
        // The distinction `Standing` has four members for. A renderer given a
        // bool marks every descendant of a taken branch or marks none, and both
        // are wrong on screen.
        let values = tag_values();
        let html = facet_html(
            &Facet::new("Tag", Selecting::Subtree, &values),
            &Emit::default(),
        );
        let synths = html
            .split("<li")
            .find(|chunk| chunk.contains("music/synths"))
            .expect("the inherited value");
        assert!(synths.contains(r#"data-standing="inherited""#));
        assert!(synths.contains(r#"aria-pressed="true""#));

        let drums = html
            .split("<li")
            .find(|chunk| chunk.contains("music/drums"))
            .expect("the pruned value");
        // Pruned is a decision and it is not in force, so the take control is
        // not pressed and the prune control is.
        assert!(drums.contains(r#"data-standing="pruned""#));
        assert!(drums.contains(r#"aria-pressed="false""#));
        assert!(drums.contains(r#"aria-label="Exclude Drums""#));
    }

    #[test]
    fn a_value_is_one_line_laid_out_with_geometry_that_exists() {
        let css = facet_rules(&Emit::default());
        // `--space-tight` is defined nowhere, so a rule reading it always took
        // its literal fallback.
        assert!(!css.contains("--space-tight"), "{css}");
        assert!(css.contains("var(--gap-group)"), "{css}");
        assert!(css.contains("justify-content: space-between"), "{css}");
        assert!(css.contains("font-variant-numeric: tabular-nums"), "{css}");
        assert!(css.contains("text-decoration: none"), "{css}");
    }

    #[test]
    fn a_value_drawn_as_a_link_is_held_in_while_it_is_in_force() {
        let css = facet_rules(&Emit::default());
        for control in ["facet-take", "facet-prune"] {
            assert!(
                css.contains(&format!(r#".{control}[aria-current="true"]"#)),
                "{control} drawn as an anchor must read pressed in force: {css}"
            );
            assert!(css.contains(&format!(r#".{control}[aria-pressed="true"]"#)));
        }
    }

    #[test]
    fn a_value_under_a_prune_is_named_and_reads_back_like_one() {
        let values = [FacetValue::new("music/drums/808", "808")
            .standing(Standing::PrunedAbove)
            .at(Nesting::at(2), false)];
        let html = facet_html(
            &Facet::new("Tag", Selecting::Subtree, &values),
            &Emit::default(),
        );
        assert!(html.contains(r#"data-standing="pruned-above""#), "{html}");
        // Not a decision: its own prune control is not pressed.
        assert!(
            !html
                .contains(r#"facet-prune" data-facet-value="music/drums/808" aria-pressed="true""#)
        );

        let css = facet_rules(&Emit::default());
        assert!(
            css.contains(r#"[data-standing="pruned-above"]"#),
            "the sheet reads a value under a prune back a step: {css}"
        );
    }

    #[test]
    fn a_mode_that_lists_nothing_still_renders_its_panel() {
        // The app puts its own box in; the panel is what gives it the group
        // label and the shared geometry.
        let html = facet_html(
            &Facet::new("Search", Selecting::Text, &[]),
            &Emit::default(),
        );
        assert!(html.contains("facet-name"));
        assert!(html.contains(r#"data-selecting="text""#));
        assert!(!html.contains("facet-take"));
    }

    #[test]
    fn an_unmeasured_count_emits_no_number_at_all() {
        // A written zero reads as "none of them", which is a different claim
        // from "not counted".
        let values = [FacetValue::of("Ambient")];
        let html = facet_html(
            &Facet::new("Tag", Selecting::AnyOf, &values),
            &Emit::default(),
        );
        assert!(!html.contains("facet-count"));

        let counted = [FacetValue::of("Ambient").counted(0)];
        let html = facet_html(
            &Facet::new("Tag", Selecting::AnyOf, &counted),
            &Emit::default(),
        );
        assert!(html.contains(">0</span>"));
    }

    #[test]
    fn the_gutter_is_reserved_from_the_deepest_value_before_anything_is_drawn() {
        // "First paint is final paint" applied to a tree: a gutter widened as
        // deeper values arrive is the reflow that rule forbids.
        let values = tag_values();
        let html = facet_html(
            &Facet::new("Tag", Selecting::Subtree, &values),
            &Emit::default(),
        );
        assert!(html.contains("--facet-reach: 1"));
        assert!(html.contains("--facet-depth: 0"));
        assert!(html.contains("--facet-depth: 1"));
    }

    #[test]
    fn labels_and_identifiers_are_escaped_like_every_other_string() {
        // Both arrive from the app, and a tag path is user-supplied on a system
        // where a user names their own tags.
        let values = [FacetValue::new("a&b", "A & B")];
        let html = facet_html(
            &Facet::new("T<ag>", Selecting::AnyOf, &values),
            &Emit::default(),
        );
        assert!(html.contains("A &amp; B"));
        assert!(html.contains(r#"data-facet-value="a&amp;b""#));
        assert!(html.contains("T&lt;ag&gt;"));
        assert!(!html.contains("<ag>"));
    }

    #[test]
    fn a_value_reads_flat_before_it_is_touched() {
        // The reason the arm exists: `Depth::Flat` declares nothing, so an app
        // handing makeover the cascade with `revert-layer` rolled the handoff
        // past an empty layer onto its own bare `button` rule and the value
        // came out raised. Both controls say flat out loud now, and the states
        // below it are what a press is allowed to change.
        let css = facet_rules(&Emit::default());
        for name in ["facet-take", "facet-prune"] {
            assert!(
                css.contains(&format!(
                    ".{name} {{\n    background: none;\n    border: none;\n    box-shadow: none;\n}}"
                )),
                "{name} is not withdrawn: {css}"
            );
        }
    }

    #[test]
    fn every_class_this_module_emits_is_one_the_stylesheet_rules() {
        // `ROW_PART_CLASSES`' obligation: a class this crate writes and the
        // sheet does not rule is invisible to the dead-vocabulary seal.
        let names = crate::vocabulary::names(&Emit::default());
        for name in FACET_CLASSES {
            assert!(
                names.contains(&crate::class(name, &Emit::default())),
                "{name} is not in the vocabulary"
            );
        }
    }

    #[test]
    fn the_prefix_reaches_every_class_in_the_markup() {
        // A prefixed build claims its own names, and the emitted CSS selects
        // descendants: miss one and the rule stops matching.
        let opts = Emit {
            class_prefix: "mo-",
            ..Emit::default()
        };
        let values = tag_values();
        let mut html = facet_html(&Facet::new("Tag", Selecting::Subtree, &values), &opts);
        let groups = group_values();
        html.push_str(&facet_html(
            &Facet::new("Tags", Selecting::Subtree, &groups),
            &opts,
        ));
        for name in FACET_CLASSES {
            assert!(html.contains(&format!("mo-{name}")), "{name} is unprefixed");
        }
    }

    /// A ranked tree: an open group with a pick under it, a closed group
    /// marked as where to start, a dead one, and a link row.
    fn group_values() -> [FacetValue<'static>; 5] {
        [
            FacetValue::new("genre", "Genre")
                .heading()
                .at(Nesting::at(0), true)
                .opened(true)
                .joined(Join::All)
                .ranked(GroupRank::in_use()),
            FacetValue::new("genre.ambient", "Ambient")
                .standing(Standing::Taken)
                .counted(12)
                .at(Nesting::at(1), false),
            FacetValue::new("genre.drone", "Drone")
                .counted(3)
                .gained()
                .at(Nesting::at(1), false),
            FacetValue::new("mood", "Mood")
                .heading()
                .at(Nesting::at(0), true)
                .opened(false)
                .joined(Join::Any)
                .ranked(GroupRank::cutting(70).starting()),
            FacetValue::new("more", "More groups (2)").heading(),
        ]
    }

    #[test]
    fn a_group_opens_rather_than_picks_and_says_how_its_picks_combine() {
        let groups = group_values();
        let html = facet_html(
            &Facet::new("Tags", Selecting::Subtree, &groups),
            &Emit::default(),
        );
        // The heading is no toggle: it opens, and offers no exclude.
        let genre = html.split("<li").nth(1).unwrap();
        assert!(genre.contains(r#"data-kind="heading""#), "{genre}");
        assert!(genre.contains(r#"aria-expanded="true""#), "{genre}");
        assert!(!genre.contains("aria-pressed=\"false\">Genre"), "{genre}");
        assert!(!genre.contains("facet-prune"), "{genre}");
        assert!(genre.contains("in use"), "{genre}");
        // Open, so its join toggle shows with all pressed.
        assert!(
            genre.contains(r#"data-facet-join="all" aria-pressed="true""#),
            "{genre}"
        );
        // A gain carries its sign.
        assert!(html.contains(">+3</span>"), "{html}");
        // A closed group keeps its join out of sight, and shows its bar.
        let mood = html.split("<li").nth(4).unwrap();
        assert!(!mood.contains("facet-join"), "{mood}");
        assert!(mood.contains("start here"), "{mood}");
        assert!(mood.contains("--facet-cut: 70%"), "{mood}");
        // A link row neither toggles nor branches.
        let more = html.split("<li").nth(5).unwrap();
        assert!(more.contains(r#"data-kind="link""#), "{more}");
        assert!(
            !more.contains("aria-pressed") && !more.contains("aria-expanded"),
            "{more}"
        );
    }
}