autumn-web 0.9.0

//! Typed accessible UI primitives — accessibility conformance by construction
//! (issue #1706).
//!
//! Autumn renders every view through Maud, which means an inaccessible page is
//! usually just a missing attribute away: an `<img>` with no `alt`, an
//! icon-only `<button>` with no accessible name, an `<input>` with no
//! associated `<label>`. Those omissions compile cleanly and only surface in an
//! audit (or, worse, for a user relying on assistive technology).
//!
//! The primitives in this module make the accessible name a **type-level
//! obligation** rather than a convention. Each one maps to a WCAG 2.1 success
//! criterion and is constructed so that the inaccessible form does not compile:
//!
//! - [`Img`](crate::a11y::Img) — WCAG 1.1.1 Non-text Content. The alt text is a
//!   mandatory positional argument of [`Img::new`](crate::a11y::Img::new); there
//!   is no alt-less constructor. Decorative images opt in explicitly with
//!   [`Img::decorative`](crate::a11y::Img::decorative).
//! - [`Button`](crate::a11y::Button) — WCAG 4.1.2 Name, Role, Value. The
//!   accessible name is a required argument; an icon-only button routes it to
//!   `aria-label` via [`Button::icon`](crate::a11y::Button::icon).
//! - [`Link`](crate::a11y::Link) — WCAG 2.4.4 Link Purpose (In Context) / 4.1.2
//!   Name, Role, Value. The link text is a required argument of
//!   [`Link::new`](crate::a11y::Link::new); an icon-only link routes its name to
//!   `aria-label` via [`Link::icon`](crate::a11y::Link::icon). There is no
//!   text-less constructor.
//! - [`MenuItem`](crate::a11y::MenuItem) — WCAG 4.1.2 Name, Role, Value. A menu
//!   item carries an explicit `role="menuitem"` and a required accessible name
//!   from [`MenuItem::new`](crate::a11y::MenuItem::new); an icon-only item routes
//!   that name to `aria-label`.
//! - [`TextField`](crate::a11y::TextField) — WCAG 1.3.1 Info and Relationships /
//!   3.3.2 Labels or Instructions / 4.1.2 Name, Role, Value. A
//!   [`TextField`](crate::a11y::TextField)`<NoLabel>` has no
//!   way to render; only after a label is attached (producing a
//!   [`TextField`](crate::a11y::TextField)`<Labeled>`) does the type implement
//!   [`maud::Render`]. An
//!   unlabeled field is therefore unrepresentable as markup. The field can
//!   still carry presentational and validation attributes — `class`,
//!   `aria-invalid`/`aria-describedby` error wiring, and the HTML5 constraints
//!   `required`/`aria-required`/`minlength`/`maxlength`/`min`/`max`/`step` —
//!   without weakening that obligation: those setters are available in both
//!   states, but none of them supplies an accessible name, so a label is still
//!   required before the field can render.
//! - [`TextArea`](crate::a11y::TextArea) — WCAG 1.3.1 Info and Relationships /
//!   3.3.2 Labels or Instructions / 4.1.2 Name, Role, Value. The multi-line
//!   counterpart to [`TextField`](crate::a11y::TextField): only
//!   [`TextArea`](crate::a11y::TextArea)`<Labeled>` implements
//!   [`maud::Render`], and the value is carried as the element's text content
//!   rather than a `value=` attribute.
//! - [`Select`](crate::a11y::Select) (with [`SelectOption`](crate::a11y::SelectOption))
//!   — WCAG 1.3.1 / 3.3.2 / 4.1.2. A `<select>` whose options are typed
//!   [`SelectOption`](crate::a11y::SelectOption) values; only
//!   [`Select`](crate::a11y::Select)`<Labeled>` implements
//!   [`maud::Render`].
//! - [`Checkbox`](crate::a11y::Checkbox) — WCAG 1.3.1 / 3.3.2 / 4.1.2. A
//!   single boolean `<input type="checkbox">`; only
//!   [`Checkbox`](crate::a11y::Checkbox)`<Labeled>` implements
//!   [`maud::Render`].
//! - [`FileField`](crate::a11y::FileField) — WCAG 1.3.1 / 3.3.2 / 4.1.2. A
//!   typed, explicitly-labeled `<input type="file">`; only
//!   [`FileField`](crate::a11y::FileField)`<Labeled>` implements
//!   [`maud::Render`].
//!
//! - [`RadioGroup`](crate::a11y::RadioGroup) (with
//!   [`RadioOption`](crate::a11y::RadioOption)) — WCAG 1.3.1 / 3.3.2 / 4.1.2. A
//!   radio group needs two names: one per choice and one for the group.
//!   [`RadioOption::new`](crate::a11y::RadioOption::new) requires the choice
//!   label, and only
//!   [`RadioGroup`](crate::a11y::RadioGroup)`<Labeled>` implements
//!   [`maud::Render`].
//!
//! The types prove that a name is *present*, not that it holds text:
//! `Img::new(src, "")` compiles. Every entry point that takes a name has a
//! `debug_assert!`, so an empty or blank name panics at the call site in a
//! debug build. A release build renders the name as it is.
//!
//! All six form primitives also accept arbitrary `hx-*` attributes through an
//! `hx(name, value)` escape hatch, so the htmx (`--live-validation`) rendering
//! path keeps the typed label obligation instead of dropping to raw markup.
//!
//! All of these implement [`maud::Render`], so they splice directly into an
//! `html!` block:
//!
//! ```rust
//! use autumn_web::a11y::{Button, Img, TextField};
//! use autumn_web::html;
//!
//! let page = html! {
//!     (Img::new("/logo.svg", "Autumn logo"))
//!     (TextField::new("email").input_type("email").label("Email address"))
//!     (Button::new("Save").submit())
//! };
//! assert!(page.into_string().contains("alt=\"Autumn logo\""));
//! ```

use std::fmt::Write as _;

use maud::{Escaper, Markup, PreEscaped, Render, html};

/// An informative or decorative image with a mandatory accessible name
/// (WCAG 1.1.1 Non-text Content).
///
/// Construct an informative image with [`Img::new`], which requires the `alt`
/// text as a positional argument — there is no way to build an `Img` without
/// one. Purely decorative images use [`Img::decorative`], which sets an
/// explicit empty `alt=""` so assistive technology skips them.
#[derive(Debug, Clone)]
pub struct Img {
    src: String,
    alt: String,
    class: Option<String>,
    width: Option<u32>,
    height: Option<u32>,
}

impl Img {
    /// Build an informative image. The accessible name (`alt`) is required.
    ///
    /// ```rust
    /// use autumn_web::a11y::Img;
    /// use maud::Render;
    ///
    /// let markup = Img::new("/hero.png", "A field at sunrise").render();
    /// assert!(markup.into_string().contains("alt=\"A field at sunrise\""));
    /// ```
    #[track_caller]
    pub fn new(src: impl Into<String>, alt: impl Into<String>) -> Self {
        Self {
            src: src.into(),
            alt: checked_name("Img::new", alt),
            class: None,
            width: None,
            height: None,
        }
    }

    /// Build a decorative image with an explicit empty `alt=""`.
    ///
    /// This documents intent: the image conveys no information, so assistive
    /// technology should ignore it. An empty `alt` is the WCAG-valid marker
    /// for a decorative image — distinct from a *missing* `alt`.
    pub fn decorative(src: impl Into<String>) -> Self {
        Self {
            src: src.into(),
            alt: String::new(),
            class: None,
            width: None,
            height: None,
        }
    }

    /// Set the `class` attribute.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Set the `width` attribute (in pixels).
    #[must_use]
    pub const fn width(mut self, width: u32) -> Self {
        self.width = Some(width);
        self
    }

    /// Set the `height` attribute (in pixels).
    #[must_use]
    pub const fn height(mut self, height: u32) -> Self {
        self.height = Some(height);
        self
    }
}

impl Render for Img {
    fn render(&self) -> Markup {
        html! {
            img
                src=(self.src)
                alt=(self.alt)
                class=[self.class.as_deref()]
                width=[self.width]
                height=[self.height];
        }
    }
}

/// The `type` of a [`Button`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ButtonType {
    /// `type="button"` — an inert button driven by JavaScript/htmx.
    #[default]
    Button,
    /// `type="submit"` — submits the enclosing form.
    Submit,
    /// `type="reset"` — resets the enclosing form.
    Reset,
}

impl ButtonType {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Button => "button",
            Self::Submit => "submit",
            Self::Reset => "reset",
        }
    }
}

/// A button with a mandatory accessible name (WCAG 4.1.2 Name, Role, Value).
///
/// [`Button::new`] takes the visible text label as a required argument.
/// [`Button::icon`] builds an icon-only button whose accessible name becomes an
/// `aria-label`, so an icon button can never ship without a name. There is no
/// name-less constructor.
#[derive(Debug, Clone)]
pub struct Button {
    accessible_name: String,
    icon: Option<Markup>,
    kind: ButtonType,
    class: Option<String>,
}

impl Button {
    /// Build a button with a visible text label, which is also its accessible
    /// name. The label is required.
    ///
    /// ```rust
    /// use autumn_web::a11y::Button;
    /// use maud::Render;
    ///
    /// assert!(Button::new("Save").render().into_string().contains("Save"));
    /// ```
    #[track_caller]
    pub fn new(accessible_name: impl Into<String>) -> Self {
        Self {
            accessible_name: checked_name("Button::new", accessible_name),
            icon: None,
            kind: ButtonType::default(),
            class: None,
        }
    }

    /// Build an icon-only button. The `accessible_name` becomes the button's
    /// `aria-label`, since the icon carries no text for assistive technology.
    ///
    /// ```rust
    /// use autumn_web::a11y::Button;
    /// use autumn_web::html;
    /// use maud::Render;
    ///
    /// let trash = html! { span aria-hidden="true" { "🗑" } };
    /// let markup = Button::icon(trash, "Delete item").render().into_string();
    /// assert!(markup.contains("aria-label=\"Delete item\""));
    /// ```
    #[track_caller]
    pub fn icon(icon: Markup, accessible_name: impl Into<String>) -> Self {
        Self {
            accessible_name: checked_name("Button::icon", accessible_name),
            icon: Some(icon),
            kind: ButtonType::default(),
            class: None,
        }
    }

    /// Set the button `type` explicitly.
    #[must_use]
    pub const fn kind(mut self, kind: ButtonType) -> Self {
        self.kind = kind;
        self
    }

    /// Shorthand for `type="submit"`.
    #[must_use]
    pub const fn submit(mut self) -> Self {
        self.kind = ButtonType::Submit;
        self
    }

    /// Shorthand for `type="button"` (the default).
    #[must_use]
    pub const fn button(mut self) -> Self {
        self.kind = ButtonType::Button;
        self
    }

    /// Set the `class` attribute.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }
}

impl Render for Button {
    fn render(&self) -> Markup {
        self.icon.as_ref().map_or_else(
            || {
                html! {
                    button type=(self.kind.as_str()) class=[self.class.as_deref()] {
                        (self.accessible_name)
                    }
                }
            },
            |icon| {
                html! {
                    button
                        type=(self.kind.as_str())
                        aria-label=(self.accessible_name)
                        class=[self.class.as_deref()] {
                        (icon)
                    }
                }
            },
        )
    }
}

/// A hyperlink with a mandatory accessible name (WCAG 2.4.4 Link Purpose (In
/// Context) / 4.1.2 Name, Role, Value).
///
/// [`Link::new`] takes the visible link text as a required positional argument,
/// so a text-less link cannot be built. [`Link::icon`] builds an icon-only link
/// whose accessible name becomes an `aria-label`. There is no name-less
/// constructor.
#[derive(Debug, Clone)]
pub struct Link {
    href: String,
    accessible_name: String,
    icon: Option<Markup>,
    class: Option<String>,
    new_tab: bool,
}

impl Link {
    /// Build a link with visible text, which is also its accessible name. Both
    /// the `href` and the `text` are required.
    ///
    /// ```rust
    /// use autumn_web::a11y::Link;
    /// use maud::Render;
    ///
    /// let markup = Link::new("/about", "About us").render().into_string();
    /// assert!(markup.contains("href=\"/about\""));
    /// assert!(markup.contains(">About us<"));
    /// ```
    #[track_caller]
    pub fn new(href: impl Into<String>, text: impl Into<String>) -> Self {
        Self {
            href: href.into(),
            accessible_name: checked_name("Link::new", text),
            icon: None,
            class: None,
            new_tab: false,
        }
    }

    /// Build an icon-only link. The `accessible_name` becomes the link's
    /// `aria-label`, since the icon carries no text for assistive technology.
    ///
    /// ```rust
    /// use autumn_web::a11y::Link;
    /// use autumn_web::html;
    /// use maud::Render;
    ///
    /// let glyph = html! { span aria-hidden="true" { "gh" } };
    /// let markup = Link::icon("https://example.com", glyph, "GitHub")
    ///     .render()
    ///     .into_string();
    /// assert!(markup.contains("aria-label=\"GitHub\""));
    /// ```
    #[track_caller]
    pub fn icon(href: impl Into<String>, icon: Markup, accessible_name: impl Into<String>) -> Self {
        Self {
            href: href.into(),
            accessible_name: checked_name("Link::icon", accessible_name),
            icon: Some(icon),
            class: None,
            new_tab: false,
        }
    }

    /// Open the link in a new browsing context (`target="_blank"`), adding
    /// `rel="noopener noreferrer"` so the opened page cannot reach back through
    /// `window.opener`.
    #[must_use]
    pub const fn new_tab(mut self) -> Self {
        self.new_tab = true;
        self
    }

    /// Set the `class` attribute.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }
}

impl Render for Link {
    fn render(&self) -> Markup {
        let target = self.new_tab.then_some("_blank");
        let rel = self.new_tab.then_some("noopener noreferrer");
        self.icon.as_ref().map_or_else(
            || {
                html! {
                    a href=(self.href) target=[target] rel=[rel] class=[self.class.as_deref()] {
                        (self.accessible_name)
                    }
                }
            },
            |icon| {
                html! {
                    a
                        href=(self.href)
                        aria-label=(self.accessible_name)
                        target=[target]
                        rel=[rel]
                        class=[self.class.as_deref()] {
                        (icon)
                    }
                }
            },
        )
    }
}

/// An interactive menu item with a mandatory accessible name and an explicit
/// `role="menuitem"` (WCAG 4.1.2 Name, Role, Value).
///
/// [`MenuItem::new`] takes the visible label as a required argument. By default
/// the item renders as a `<button type="button" role="menuitem">`; attaching an
/// [`href`](MenuItem::href) renders it as an `<a role="menuitem">` instead.
/// Adding an [`icon`](MenuItem::icon) routes the accessible name to
/// `aria-label`, so an icon-only item can never ship without a name. There is
/// no name-less constructor.
#[derive(Debug, Clone)]
pub struct MenuItem {
    accessible_name: String,
    href: Option<String>,
    icon: Option<Markup>,
    class: Option<String>,
}

impl MenuItem {
    /// Build a menu item with a visible label, which is also its accessible
    /// name. The label is required.
    ///
    /// ```rust
    /// use autumn_web::a11y::MenuItem;
    /// use maud::Render;
    ///
    /// let markup = MenuItem::new("Settings").render().into_string();
    /// assert!(markup.contains("role=\"menuitem\""));
    /// assert!(markup.contains(">Settings<"));
    /// ```
    #[track_caller]
    pub fn new(accessible_name: impl Into<String>) -> Self {
        Self {
            accessible_name: checked_name("MenuItem::new", accessible_name),
            href: None,
            icon: None,
            class: None,
        }
    }

    /// Render the item as a link (`<a role="menuitem" href=…>`) rather than the
    /// default button.
    #[must_use]
    pub fn href(mut self, href: impl Into<String>) -> Self {
        self.href = Some(href.into());
        self
    }

    /// Add a leading icon. The visible label from [`MenuItem::new`] moves to
    /// `aria-label`, keeping the accessible name intact for icon-only items.
    #[must_use]
    pub fn icon(mut self, icon: Markup) -> Self {
        self.icon = Some(icon);
        self
    }

    /// Set the `class` attribute.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }
}

impl Render for MenuItem {
    fn render(&self) -> Markup {
        // An icon-only item routes its accessible name to `aria-label`; a text
        // item renders the name as visible content.
        let aria_label = self.icon.is_some().then_some(self.accessible_name.as_str());
        self.href.as_deref().map_or_else(
            || {
                html! {
                    button
                        type="button"
                        role="menuitem"
                        aria-label=[aria_label]
                        class=[self.class.as_deref()] {
                        @match &self.icon {
                            Some(icon) => (icon),
                            None => (self.accessible_name),
                        }
                    }
                }
            },
            |href| {
                html! {
                    a href=(href) role="menuitem" aria-label=[aria_label] class=[self.class.as_deref()] {
                        @match &self.icon {
                            Some(icon) => (icon),
                            None => (self.accessible_name),
                        }
                    }
                }
            },
        )
    }
}

/// Typestate marker: a [`TextField`] with no label attached yet. This state
/// does **not** implement [`maud::Render`], so it cannot be turned into markup.
#[derive(Debug, Clone, Copy)]
pub struct NoLabel;

/// Typestate marker: a [`TextField`] whose label has been attached. Only this
/// state implements [`maud::Render`].
#[derive(Debug, Clone, Copy)]
pub struct Labeled;

/// Convert the accessible name given to `entry`, and make sure that it is not
/// blank.
///
/// The typestate proves that a name is present. It does not prove that the
/// name holds text: `""`, `" "` or a zero-width space gives an element with no
/// name (WCAG 4.1.2). A debug build panics at the caller. A release build keeps
/// the text as it is.
#[track_caller]
fn checked_name(entry: &str, name: impl Into<String>) -> String {
    let name = name.into();
    debug_assert!(
        !is_blank(&name),
        "{entry}: the text is empty or blank, so the element has no accessible name{}",
        if entry == "Img::new" {
            "; use Img::decorative(src) for an image that carries no information"
        } else {
            ""
        }
    );
    name
}

/// Whether `text` shows nothing: only white space and zero-width characters.
///
/// Such a text gives no accessible name, and the name check of every
/// primitive rejects it. Use this to give a name from data a fallback:
///
/// ```rust
/// use autumn_web::a11y::is_blank;
///
/// let title = "\u{200B}".to_owned();
/// let label = if is_blank(&title) { "Untitled".to_owned() } else { title };
/// assert_eq!(label, "Untitled");
/// ```
#[must_use]
pub fn is_blank(text: &str) -> bool {
    text.chars().all(|c| {
        c.is_whitespace()
            || matches!(
                c,
                '\u{200B}' | '\u{200C}' | '\u{200D}' | '\u{2060}' | '\u{FEFF}'
            )
    })
}

/// How a [`TextField`]'s accessible name is provided.
#[derive(Debug, Clone)]
enum LabelSource {
    /// A visible `<label for=…>` element.
    Visible(String),
    /// An `aria-label` attribute (no visible label).
    Aria(String),
    /// An `aria-labelledby` reference to an existing element's `id`.
    LabelledBy(String),
}

/// `visible_label`, `aria_label`, `aria_labelledby`, `aria_invalid`,
/// `aria_required`, in the order [`label_render_attrs`] returns them.
type LabelRenderAttrs<'a> = (
    Option<&'a str>,
    Option<&'a str>,
    Option<&'a str>,
    Option<&'static str>,
    Option<&'static str>,
);

/// Resolves a `<Labeled>` primitive's label and validity state into the
/// markup attributes every one of them renders the same way: WCAG
/// 1.3.1/3.3.2/4.1.2 requires exactly one accessible-name attribute, and
/// `aria-invalid`/`aria-required` follow the same `Option<bool>`/`bool`
/// mapping regardless of which primitive carries them. `TextField`,
/// `TextArea`, `Select`, `Checkbox`, `FileField` and `RadioGroup` all call
/// this with their own `label`/`aria_invalid`/`aria_required` fields.
fn label_render_attrs(
    label: Option<&LabelSource>,
    aria_invalid: Option<bool>,
    aria_required: bool,
) -> LabelRenderAttrs<'_> {
    let (visible_label, aria_label, aria_labelledby) = match label {
        Some(LabelSource::Visible(text)) => (Some(text.as_str()), None, None),
        Some(LabelSource::Aria(text)) => (None, Some(text.as_str()), None),
        Some(LabelSource::LabelledBy(id)) => (None, None, Some(id.as_str())),
        None => (None, None, None),
    };
    let aria_invalid = aria_invalid.map(|invalid| if invalid { "true" } else { "false" });
    let aria_required = aria_required.then_some("true");
    (
        visible_label,
        aria_label,
        aria_labelledby,
        aria_invalid,
        aria_required,
    )
}

/// Returns `true` when `name` is a valid `hx-*` attribute suffix: a non-empty
/// run of ASCII lowercase letters, digits, or `-`.
///
/// This mirrors the attribute-name validation in [`crate::links`]
/// (`is_valid_attr_name`) but narrows the alphabet to the `hx-*` suffix
/// grammar. It deliberately excludes whitespace and `=` — which
/// [`maud::Escaper`] does **not** escape — so a caller-supplied name can never
/// break out of the `hx-{name}="…"` attribute into a separate, injected
/// attribute.
fn is_valid_hx_suffix(name: &str) -> bool {
    !name.is_empty()
        && name
            .bytes()
            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
}

/// Splice a dynamic set of `hx-*` attributes into an already-rendered element.
///
/// maud requires a *static* attribute name (its `Named` attribute parses an
/// `HtmlName`, not a splice), so an arbitrary, caller-supplied `hx-{name}` set
/// cannot be expressed inside the `html!` tag syntax and control flow is not
/// permitted in attribute position either. Because maud escapes every `>` in
/// text and attribute values to `&gt;`, the first literal `>` in a rendered
/// element is always the end of its opening tag, so inserting the attributes
/// immediately before it is unambiguous. The value is HTML-attribute-escaped
/// via [`maud::Escaper`], preserving maud's own escaping guarantees. An empty
/// set returns the element byte-for-byte unchanged.
///
/// Each attribute name is validated against [`is_valid_hx_suffix`]: an invalid
/// name trips a [`debug_assert`] (surfacing the developer error in debug
/// builds) and is skipped in release builds, so a malformed or injected
/// attribute is never emitted.
fn with_hx_attrs(element: Markup, hx: &[(String, String)]) -> Markup {
    if hx.is_empty() {
        return element;
    }
    let rendered = element.into_string();
    let mut attrs = String::new();
    for (name, value) in hx {
        debug_assert!(
            is_valid_hx_suffix(name),
            "invalid hx-* attribute name {name:?}: only lowercase ASCII letters, \
             digits, and '-' are permitted"
        );
        if !is_valid_hx_suffix(name) {
            continue;
        }
        attrs.push_str(" hx-");
        // `name` is validated to the safe `[a-z0-9-]` alphabet, so it needs no
        // escaping (mirroring `links::push_attr`, which pushes the validated
        // name verbatim); the value keeps maud's attribute escaping.
        attrs.push_str(name);
        attrs.push_str("=\"");
        let _ = write!(Escaper::new(&mut attrs), "{value}");
        attrs.push('"');
    }
    match rendered.find('>') {
        Some(idx) => {
            let mut out = String::with_capacity(rendered.len() + attrs.len());
            out.push_str(&rendered[..idx]);
            out.push_str(&attrs);
            out.push_str(&rendered[idx..]);
            PreEscaped(out)
        }
        None => PreEscaped(rendered),
    }
}

/// A text input whose label association is enforced by the type system
/// (WCAG 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions,
/// 4.1.2 Name, Role, Value).
///
/// [`TextField::new`] returns a `TextField<NoLabel>`, which has no way to
/// render. Attaching a label with [`label`](TextField::label),
/// [`aria_label`](TextField::aria_label), or
/// [`labelled_by`](TextField::labelled_by) consumes it and returns a
/// `TextField<Labeled>`, the only state that implements [`maud::Render`]. An
/// unlabeled field therefore cannot be turned into markup — the accessible
/// name obligation is discharged at compile time.
///
/// The value/type/required attributes — along with the presentational
/// [`class`](TextField::class) / [`label_class`](TextField::label_class), the error-wiring
/// [`aria_invalid`](TextField::aria_invalid) /
/// [`described_by`](TextField::described_by), and the HTML5 validation
/// constraints [`aria_required`](TextField::aria_required) /
/// [`minlength`](TextField::minlength) / [`maxlength`](TextField::maxlength) /
/// [`min`](TextField::min) / [`max`](TextField::max) / [`step`](TextField::step)
/// — are chainable in either state. None of them provides an accessible name, so
/// none of them lifts the compile-time label obligation: they can be set on a
/// `TextField<NoLabel>`, but the field still cannot be rendered until a label is
/// attached.
#[derive(Debug, Clone)]
pub struct TextField<State> {
    name: String,
    input_type: String,
    value: Option<String>,
    required: bool,
    aria_required: bool,
    class: Option<String>,
    label_class: Option<String>,
    aria_invalid: Option<bool>,
    described_by: Option<String>,
    minlength: Option<u32>,
    maxlength: Option<u32>,
    min: Option<String>,
    max: Option<String>,
    step: Option<String>,
    hx: Vec<(String, String)>,
    label: Option<LabelSource>,
    _state: std::marker::PhantomData<State>,
}

impl TextField<NoLabel> {
    /// Start building a text field with the given form `name`. The returned
    /// value has no label yet and cannot be rendered until one is attached.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            input_type: "text".to_owned(),
            value: None,
            required: false,
            aria_required: false,
            class: None,
            label_class: None,
            aria_invalid: None,
            described_by: None,
            minlength: None,
            maxlength: None,
            min: None,
            max: None,
            step: None,
            hx: Vec::new(),
            label: None,
            _state: std::marker::PhantomData,
        }
    }

    /// Attach a visible `<label for=…>` and transition to the renderable
    /// [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn label(self, text: impl Into<String>) -> TextField<Labeled> {
        self.with_label(LabelSource::Visible(checked_name("TextField::label", text)))
    }

    /// Attach an `aria-label` (no visible label) and transition to the
    /// renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn aria_label(self, text: impl Into<String>) -> TextField<Labeled> {
        self.with_label(LabelSource::Aria(checked_name(
            "TextField::aria_label",
            text,
        )))
    }

    /// Reference an existing element's `id` via `aria-labelledby` and
    /// transition to the renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn labelled_by(self, id: impl Into<String>) -> TextField<Labeled> {
        self.with_label(LabelSource::LabelledBy(checked_name(
            "TextField::labelled_by",
            id,
        )))
    }

    fn with_label(self, label: LabelSource) -> TextField<Labeled> {
        TextField {
            name: self.name,
            input_type: self.input_type,
            value: self.value,
            required: self.required,
            aria_required: self.aria_required,
            class: self.class,
            label_class: self.label_class,
            aria_invalid: self.aria_invalid,
            described_by: self.described_by,
            minlength: self.minlength,
            maxlength: self.maxlength,
            min: self.min,
            max: self.max,
            step: self.step,
            hx: self.hx,
            label: Some(label),
            _state: std::marker::PhantomData,
        }
    }
}

impl<State> TextField<State> {
    /// Set the input `type` (e.g. `"email"`, `"password"`). Available before or
    /// after a label is attached.
    #[must_use]
    pub fn input_type(mut self, input_type: impl Into<String>) -> Self {
        self.input_type = input_type.into();
        self
    }

    /// Set the input's initial `value`.
    #[must_use]
    pub fn value(mut self, value: impl Into<String>) -> Self {
        self.value = Some(value.into());
        self
    }

    /// Mark the input as `required`.
    #[must_use]
    pub const fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Add a mirroring `aria-required="true"` alongside the native `required`
    /// attribute, matching the ARIA wiring the scaffold generator emits for
    /// non-nullable fields. Available before or after a label is attached.
    ///
    /// ```rust
    /// use autumn_web::a11y::TextField;
    /// use maud::Render;
    ///
    /// let markup = TextField::new("name")
    ///     .required()
    ///     .aria_required()
    ///     .label("Name")
    ///     .render()
    ///     .into_string();
    /// assert!(markup.contains("aria-required=\"true\""));
    /// ```
    #[must_use]
    pub const fn aria_required(mut self) -> Self {
        self.aria_required = true;
        self
    }

    /// Set the `class` attribute on the `<input>`. Available before or after a
    /// label is attached.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Sets the `class` attribute on the visible `<label>` element.
    ///
    /// Only affects rendering when a visible label was set via [`label`](Self::label);
    /// `aria_label`/`labelled_by` variants render no `<label>` element.
    #[must_use]
    pub fn label_class(mut self, class: impl Into<String>) -> Self {
        self.label_class = Some(class.into());
        self
    }

    /// Set `aria-invalid` to `"true"` or `"false"`, wiring the field to its
    /// validation state. When left unset the attribute is omitted entirely.
    ///
    /// ```rust
    /// use autumn_web::a11y::TextField;
    /// use maud::Render;
    ///
    /// let markup = TextField::new("email")
    ///     .aria_invalid(true)
    ///     .label("Email address")
    ///     .render()
    ///     .into_string();
    /// assert!(markup.contains("aria-invalid=\"true\""));
    /// ```
    #[must_use]
    pub const fn aria_invalid(mut self, invalid: bool) -> Self {
        self.aria_invalid = Some(invalid);
        self
    }

    /// Reference the `id` of the element describing this field (typically an
    /// inline error container) via `aria-describedby`, so assistive technology
    /// announces the error alongside the input.
    ///
    /// ```rust
    /// use autumn_web::a11y::TextField;
    /// use maud::Render;
    ///
    /// let markup = TextField::new("email")
    ///     .described_by("email-error")
    ///     .aria_invalid(true)
    ///     .label("Email address")
    ///     .render()
    ///     .into_string();
    /// assert!(markup.contains("aria-describedby=\"email-error\""));
    /// ```
    #[must_use]
    pub fn described_by(mut self, id: impl Into<String>) -> Self {
        self.described_by = Some(id.into());
        self
    }

    /// Set the HTML5 `minlength` validation constraint (minimum character
    /// count), matching the scaffold generator's `text{min=…}` DSL modifier.
    #[must_use]
    pub const fn minlength(mut self, minlength: u32) -> Self {
        self.minlength = Some(minlength);
        self
    }

    /// Set the HTML5 `maxlength` validation constraint (maximum character
    /// count), matching the scaffold generator's `text{max=…}` DSL modifier.
    #[must_use]
    pub const fn maxlength(mut self, maxlength: u32) -> Self {
        self.maxlength = Some(maxlength);
        self
    }

    /// Set the HTML5 `min` validation constraint for numeric inputs. The value
    /// is passed through verbatim (e.g. an integer or decimal bound), matching
    /// the scaffold generator's numeric `{min=…}` DSL modifier.
    #[must_use]
    pub fn min(mut self, min: impl Into<String>) -> Self {
        self.min = Some(min.into());
        self
    }

    /// Set the HTML5 `max` validation constraint for numeric inputs, matching
    /// the scaffold generator's numeric `{max=…}` DSL modifier.
    #[must_use]
    pub fn max(mut self, max: impl Into<String>) -> Self {
        self.max = Some(max.into());
        self
    }

    /// Set the HTML5 `step` attribute for numeric inputs (e.g. `"any"` for a
    /// constrained float), matching the scaffold generator's `step="any"` on
    /// `f32`/`f64` fields.
    #[must_use]
    pub fn step(mut self, step: impl Into<String>) -> Self {
        self.step = Some(step.into());
        self
    }

    /// Attach an arbitrary `hx-*` attribute, preserving the typed label
    /// obligation while opting into htmx behaviour (e.g. the scaffold
    /// generator's `--live-validation` path). The `name` is the suffix after
    /// `hx-`, so `.hx("post", "/validate")` renders `hx-post="/validate"`.
    /// Multiple calls are emitted in insertion order. Available before or after
    /// a label is attached.
    ///
    /// ```rust
    /// use autumn_web::a11y::TextField;
    /// use maud::Render;
    ///
    /// let markup = TextField::new("email")
    ///     .hx("post", "/validate/email")
    ///     .hx("trigger", "blur")
    ///     .label("Email address")
    ///     .render()
    ///     .into_string();
    /// assert!(markup.contains("hx-post=\"/validate/email\""));
    /// assert!(markup.contains("hx-trigger=\"blur\""));
    /// ```
    #[must_use]
    pub fn hx(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.hx.push((name.into(), value.into()));
        self
    }
}

impl Render for TextField<Labeled> {
    fn render(&self) -> Markup {
        // `label` is always `Some` in the `Labeled` state — it is set on every
        // transition out of `NoLabel` — but match defensively rather than
        // unwrap. The label source only changes the label wiring (a preceding
        // `<label for=…>` vs an `aria-label`/`aria-labelledby` on the input);
        // every other attribute is shared, so compute the label bits once and
        // emit a single `<input>`.
        let (visible_label, aria_label, aria_labelledby, aria_invalid, aria_required) =
            label_render_attrs(self.label.as_ref(), self.aria_invalid, self.aria_required);
        let input = html! {
            input
                type=(self.input_type)
                id=(self.name)
                name=(self.name)
                aria-label=[aria_label]
                aria-labelledby=[aria_labelledby]
                class=[self.class.as_deref()]
                value=[self.value.as_deref()]
                minlength=[self.minlength]
                maxlength=[self.maxlength]
                min=[self.min.as_deref()]
                max=[self.max.as_deref()]
                step=[self.step.as_deref()]
                aria-invalid=[aria_invalid]
                aria-describedby=[self.described_by.as_deref()]
                aria-required=[aria_required]
                required[self.required];
        };
        html! {
            @if let Some(text) = visible_label {
                label for=(self.name) class=[self.label_class.as_deref()] { (text) }
            }
            (with_hx_attrs(input, &self.hx))
        }
    }
}

/// A multi-line text input whose label association is enforced by the type
/// system (WCAG 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions,
/// 4.1.2 Name, Role, Value).
///
/// [`TextArea::new`] returns a `TextArea<NoLabel>`, which has no way to render.
/// Attaching a label with [`label`](TextArea::label),
/// [`aria_label`](TextArea::aria_label), or
/// [`labelled_by`](TextArea::labelled_by) consumes it and returns a
/// `TextArea<Labeled>`, the only state that implements [`maud::Render`] — so an
/// unlabeled `<textarea>` is unrepresentable as markup, exactly like
/// [`TextField`].
///
/// Unlike [`TextField`], the current value is carried as the element's **text
/// content** (`<textarea>…value…</textarea>`), never a `value=` attribute,
/// matching HTML's model for a `<textarea>`.
#[derive(Debug, Clone)]
pub struct TextArea<State> {
    name: String,
    value: Option<String>,
    required: bool,
    aria_required: bool,
    class: Option<String>,
    label_class: Option<String>,
    aria_invalid: Option<bool>,
    described_by: Option<String>,
    minlength: Option<u32>,
    maxlength: Option<u32>,
    rows: Option<u32>,
    cols: Option<u32>,
    hx: Vec<(String, String)>,
    label: Option<LabelSource>,
    _state: std::marker::PhantomData<State>,
}

impl TextArea<NoLabel> {
    /// Start building a text area with the given form `name`. The returned value
    /// has no label yet and cannot be rendered until one is attached.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            value: None,
            required: false,
            aria_required: false,
            class: None,
            label_class: None,
            aria_invalid: None,
            described_by: None,
            minlength: None,
            maxlength: None,
            rows: None,
            cols: None,
            hx: Vec::new(),
            label: None,
            _state: std::marker::PhantomData,
        }
    }

    /// Attach a visible `<label for=…>` and transition to the renderable
    /// [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn label(self, text: impl Into<String>) -> TextArea<Labeled> {
        self.with_label(LabelSource::Visible(checked_name("TextArea::label", text)))
    }

    /// Attach an `aria-label` (no visible label) and transition to the
    /// renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn aria_label(self, text: impl Into<String>) -> TextArea<Labeled> {
        self.with_label(LabelSource::Aria(checked_name(
            "TextArea::aria_label",
            text,
        )))
    }

    /// Reference an existing element's `id` via `aria-labelledby` and transition
    /// to the renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn labelled_by(self, id: impl Into<String>) -> TextArea<Labeled> {
        self.with_label(LabelSource::LabelledBy(checked_name(
            "TextArea::labelled_by",
            id,
        )))
    }

    fn with_label(self, label: LabelSource) -> TextArea<Labeled> {
        TextArea {
            name: self.name,
            value: self.value,
            required: self.required,
            aria_required: self.aria_required,
            class: self.class,
            label_class: self.label_class,
            aria_invalid: self.aria_invalid,
            described_by: self.described_by,
            minlength: self.minlength,
            maxlength: self.maxlength,
            rows: self.rows,
            cols: self.cols,
            hx: self.hx,
            label: Some(label),
            _state: std::marker::PhantomData,
        }
    }
}

impl<State> TextArea<State> {
    /// Set the text area's initial `value`, rendered as its text content.
    #[must_use]
    pub fn value(mut self, value: impl Into<String>) -> Self {
        self.value = Some(value.into());
        self
    }

    /// Mark the text area as `required`.
    #[must_use]
    pub const fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Add a mirroring `aria-required="true"` alongside the native `required`
    /// attribute. Available before or after a label is attached.
    #[must_use]
    pub const fn aria_required(mut self) -> Self {
        self.aria_required = true;
        self
    }

    /// Set the `class` attribute on the `<textarea>`.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Set the `class` attribute on the visible `<label>` element. Only affects
    /// rendering when a visible label was set via [`label`](Self::label).
    #[must_use]
    pub fn label_class(mut self, class: impl Into<String>) -> Self {
        self.label_class = Some(class.into());
        self
    }

    /// Set `aria-invalid` to `"true"` or `"false"`. When left unset the
    /// attribute is omitted entirely.
    #[must_use]
    pub const fn aria_invalid(mut self, invalid: bool) -> Self {
        self.aria_invalid = Some(invalid);
        self
    }

    /// Reference the `id` of the element describing this field (typically an
    /// inline error container) via `aria-describedby`.
    #[must_use]
    pub fn described_by(mut self, id: impl Into<String>) -> Self {
        self.described_by = Some(id.into());
        self
    }

    /// Set the HTML5 `minlength` validation constraint (minimum character
    /// count).
    #[must_use]
    pub const fn minlength(mut self, minlength: u32) -> Self {
        self.minlength = Some(minlength);
        self
    }

    /// Set the HTML5 `maxlength` validation constraint (maximum character
    /// count).
    #[must_use]
    pub const fn maxlength(mut self, maxlength: u32) -> Self {
        self.maxlength = Some(maxlength);
        self
    }

    /// Set the visible `rows` (height in text lines) of the text area.
    #[must_use]
    pub const fn rows(mut self, rows: u32) -> Self {
        self.rows = Some(rows);
        self
    }

    /// Set the visible `cols` (width in average character widths) of the text
    /// area.
    #[must_use]
    pub const fn cols(mut self, cols: u32) -> Self {
        self.cols = Some(cols);
        self
    }

    /// Attach an arbitrary `hx-*` attribute (the `name` is the suffix after
    /// `hx-`), preserving the typed label obligation. Emitted in insertion
    /// order. Available before or after a label is attached.
    #[must_use]
    pub fn hx(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.hx.push((name.into(), value.into()));
        self
    }
}

impl Render for TextArea<Labeled> {
    fn render(&self) -> Markup {
        let (visible_label, aria_label, aria_labelledby, aria_invalid, aria_required) =
            label_render_attrs(self.label.as_ref(), self.aria_invalid, self.aria_required);
        let textarea = html! {
            textarea
                id=(self.name)
                name=(self.name)
                aria-label=[aria_label]
                aria-labelledby=[aria_labelledby]
                class=[self.class.as_deref()]
                minlength=[self.minlength]
                maxlength=[self.maxlength]
                rows=[self.rows]
                cols=[self.cols]
                aria-invalid=[aria_invalid]
                aria-describedby=[self.described_by.as_deref()]
                aria-required=[aria_required]
                required[self.required] {
                    @if let Some(v) = &self.value { (v) }
                }
        };
        html! {
            @if let Some(text) = visible_label {
                label for=(self.name) class=[self.label_class.as_deref()] { (text) }
            }
            (with_hx_attrs(textarea, &self.hx))
        }
    }
}

/// A single `<option>` for a [`Select`].
///
/// Named `SelectOption` rather than `Option` deliberately: a public `Option`
/// exported from this module would shadow [`std::option::Option`] at any call
/// site that glob-imports `a11y`, so the primitive carries a qualified name.
#[derive(Debug, Clone)]
pub struct SelectOption {
    value: String,
    label: String,
    selected: bool,
    disabled: bool,
}

impl SelectOption {
    /// Build an option with a submitted `value` and a human-visible `label`.
    #[track_caller]
    pub fn new(value: impl Into<String>, label: impl Into<String>) -> Self {
        Self {
            value: value.into(),
            label: checked_name("SelectOption::new", label),
            selected: false,
            disabled: false,
        }
    }

    /// Mark this option `selected`.
    #[must_use]
    pub const fn selected(mut self) -> Self {
        self.selected = true;
        self
    }

    /// Mark this option `disabled`. Combined with an empty value this renders
    /// the conventional `— Select —` placeholder.
    #[must_use]
    pub const fn disabled(mut self) -> Self {
        self.disabled = true;
        self
    }
}

/// A `<select>` dropdown whose label association is enforced by the type system
/// (WCAG 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions, 4.1.2
/// Name, Role, Value).
///
/// [`Select::new`] returns a `Select<NoLabel>`, which has no way to render.
/// Attaching a label with [`label`](Select::label),
/// [`aria_label`](Select::aria_label), or
/// [`labelled_by`](Select::labelled_by) consumes it and returns a
/// `Select<Labeled>`, the only state that implements [`maud::Render`]. A
/// nullable/tri-state boolean field is modelled as a `Select` (an empty-value
/// placeholder option), not a [`Checkbox`], which is bool-only.
#[derive(Debug, Clone)]
pub struct Select<State> {
    name: String,
    options: Vec<SelectOption>,
    required: bool,
    aria_required: bool,
    class: Option<String>,
    label_class: Option<String>,
    aria_invalid: Option<bool>,
    described_by: Option<String>,
    hx: Vec<(String, String)>,
    label: Option<LabelSource>,
    _state: std::marker::PhantomData<State>,
}

impl Select<NoLabel> {
    /// Start building a select with the given form `name`. The returned value
    /// has no label yet and cannot be rendered until one is attached.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            options: Vec::new(),
            required: false,
            aria_required: false,
            class: None,
            label_class: None,
            aria_invalid: None,
            described_by: None,
            hx: Vec::new(),
            label: None,
            _state: std::marker::PhantomData,
        }
    }

    /// Attach a visible `<label for=…>` and transition to the renderable
    /// [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn label(self, text: impl Into<String>) -> Select<Labeled> {
        self.with_label(LabelSource::Visible(checked_name("Select::label", text)))
    }

    /// Attach an `aria-label` (no visible label) and transition to the
    /// renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn aria_label(self, text: impl Into<String>) -> Select<Labeled> {
        self.with_label(LabelSource::Aria(checked_name("Select::aria_label", text)))
    }

    /// Reference an existing element's `id` via `aria-labelledby` and transition
    /// to the renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn labelled_by(self, id: impl Into<String>) -> Select<Labeled> {
        self.with_label(LabelSource::LabelledBy(checked_name(
            "Select::labelled_by",
            id,
        )))
    }

    fn with_label(self, label: LabelSource) -> Select<Labeled> {
        Select {
            name: self.name,
            options: self.options,
            required: self.required,
            aria_required: self.aria_required,
            class: self.class,
            label_class: self.label_class,
            aria_invalid: self.aria_invalid,
            described_by: self.described_by,
            hx: self.hx,
            label: Some(label),
            _state: std::marker::PhantomData,
        }
    }
}

impl<State> Select<State> {
    /// Append a single option built from a `value` and visible `label`.
    #[must_use]
    #[track_caller]
    pub fn option(mut self, value: impl Into<String>, label: impl Into<String>) -> Self {
        self.options.push(SelectOption::new(value, label));
        self
    }

    /// Append a batch of pre-built [`SelectOption`]s, preserving their order.
    #[must_use]
    pub fn options(mut self, options: impl IntoIterator<Item = SelectOption>) -> Self {
        self.options.extend(options);
        self
    }

    /// Authoritatively set the single selected option: the option whose `value`
    /// matches is marked `selected` and every other option's `selected` flag is
    /// cleared. `<select>` is single-select, so this guarantees at most one
    /// `selected` option in the rendered markup — any prior selection (e.g. from
    /// [`SelectOption::selected`]) is overridden.
    #[must_use]
    pub fn selected_value(mut self, value: impl Into<String>) -> Self {
        let value = value.into();
        for opt in &mut self.options {
            opt.selected = opt.value == value;
        }
        self
    }

    /// Mark the select as `required`.
    #[must_use]
    pub const fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Add a mirroring `aria-required="true"` alongside the native `required`
    /// attribute. Available before or after a label is attached.
    #[must_use]
    pub const fn aria_required(mut self) -> Self {
        self.aria_required = true;
        self
    }

    /// Set the `class` attribute on the `<select>`.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Set the `class` attribute on the visible `<label>` element. Only affects
    /// rendering when a visible label was set via [`label`](Self::label).
    #[must_use]
    pub fn label_class(mut self, class: impl Into<String>) -> Self {
        self.label_class = Some(class.into());
        self
    }

    /// Set `aria-invalid` to `"true"` or `"false"`. When left unset the
    /// attribute is omitted entirely.
    #[must_use]
    pub const fn aria_invalid(mut self, invalid: bool) -> Self {
        self.aria_invalid = Some(invalid);
        self
    }

    /// Reference the `id` of the element describing this field via
    /// `aria-describedby`.
    #[must_use]
    pub fn described_by(mut self, id: impl Into<String>) -> Self {
        self.described_by = Some(id.into());
        self
    }

    /// Attach an arbitrary `hx-*` attribute (the `name` is the suffix after
    /// `hx-`), preserving the typed label obligation. Emitted in insertion
    /// order. Available before or after a label is attached.
    #[must_use]
    pub fn hx(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.hx.push((name.into(), value.into()));
        self
    }
}

impl Render for Select<Labeled> {
    fn render(&self) -> Markup {
        let (visible_label, aria_label, aria_labelledby, aria_invalid, aria_required) =
            label_render_attrs(self.label.as_ref(), self.aria_invalid, self.aria_required);
        let select = html! {
            select
                id=(self.name)
                name=(self.name)
                aria-label=[aria_label]
                aria-labelledby=[aria_labelledby]
                class=[self.class.as_deref()]
                aria-invalid=[aria_invalid]
                aria-describedby=[self.described_by.as_deref()]
                aria-required=[aria_required]
                required[self.required] {
                    @for opt in &self.options {
                        option value=(opt.value) selected[opt.selected] disabled[opt.disabled] {
                            (opt.label)
                        }
                    }
                }
        };
        html! {
            @if let Some(text) = visible_label {
                label for=(self.name) class=[self.label_class.as_deref()] { (text) }
            }
            (with_hx_attrs(select, &self.hx))
        }
    }
}

/// A single boolean `<input type="checkbox">` whose label association is
/// enforced by the type system (WCAG 1.3.1 / 3.3.2 / 4.1.2).
///
/// [`Checkbox::new`] returns a `Checkbox<NoLabel>`, which has no way to render.
/// Attaching a label with [`label`](Checkbox::label),
/// [`aria_label`](Checkbox::aria_label), or
/// [`labelled_by`](Checkbox::labelled_by) consumes it and returns a
/// `Checkbox<Labeled>`, the only state that implements [`maud::Render`].
///
/// A `Checkbox` models a plain `bool`. A nullable/tri-state boolean is **not** a
/// checkbox — it reuses [`Select`] (with an empty-value placeholder option) —
/// so this primitive stays strictly two-state.
///
/// For a visible label the `<input>` is emitted first, followed by a
/// `<label for=…>` (the conventional checkbox layout); the `aria-label` /
/// `aria-labelledby` variants place the accessible name on the input itself and
/// render no `<label>`.
#[derive(Debug, Clone)]
pub struct Checkbox<State> {
    name: String,
    value: Option<String>,
    checked: bool,
    required: bool,
    aria_required: bool,
    class: Option<String>,
    label_class: Option<String>,
    aria_invalid: Option<bool>,
    described_by: Option<String>,
    hx: Vec<(String, String)>,
    label: Option<LabelSource>,
    _state: std::marker::PhantomData<State>,
}

impl Checkbox<NoLabel> {
    /// Start building a checkbox with the given form `name`. The returned value
    /// has no label yet and cannot be rendered until one is attached.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            value: None,
            checked: false,
            required: false,
            aria_required: false,
            class: None,
            label_class: None,
            aria_invalid: None,
            described_by: None,
            hx: Vec::new(),
            label: None,
            _state: std::marker::PhantomData,
        }
    }

    /// Attach a visible `<label for=…>` and transition to the renderable
    /// [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn label(self, text: impl Into<String>) -> Checkbox<Labeled> {
        self.with_label(LabelSource::Visible(checked_name("Checkbox::label", text)))
    }

    /// Attach an `aria-label` (no visible label) and transition to the
    /// renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn aria_label(self, text: impl Into<String>) -> Checkbox<Labeled> {
        self.with_label(LabelSource::Aria(checked_name(
            "Checkbox::aria_label",
            text,
        )))
    }

    /// Reference an existing element's `id` via `aria-labelledby` and transition
    /// to the renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn labelled_by(self, id: impl Into<String>) -> Checkbox<Labeled> {
        self.with_label(LabelSource::LabelledBy(checked_name(
            "Checkbox::labelled_by",
            id,
        )))
    }

    fn with_label(self, label: LabelSource) -> Checkbox<Labeled> {
        Checkbox {
            name: self.name,
            value: self.value,
            checked: self.checked,
            required: self.required,
            aria_required: self.aria_required,
            class: self.class,
            label_class: self.label_class,
            aria_invalid: self.aria_invalid,
            described_by: self.described_by,
            hx: self.hx,
            label: Some(label),
            _state: std::marker::PhantomData,
        }
    }
}

impl<State> Checkbox<State> {
    /// Set the submitted `value` attribute (e.g. `"true"`). Omitted when unset.
    #[must_use]
    pub fn value(mut self, value: impl Into<String>) -> Self {
        self.value = Some(value.into());
        self
    }

    /// Set the initial `checked` state.
    #[must_use]
    pub const fn checked(mut self, checked: bool) -> Self {
        self.checked = checked;
        self
    }

    /// Mark the checkbox as `required` (the box must be ticked to submit).
    #[must_use]
    pub const fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Add a mirroring `aria-required="true"` alongside the native `required`
    /// attribute. Available before or after a label is attached.
    #[must_use]
    pub const fn aria_required(mut self) -> Self {
        self.aria_required = true;
        self
    }

    /// Set the `class` attribute on the `<input>`.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Set the `class` attribute on the visible `<label>` element. Only affects
    /// rendering when a visible label was set via [`label`](Self::label).
    #[must_use]
    pub fn label_class(mut self, class: impl Into<String>) -> Self {
        self.label_class = Some(class.into());
        self
    }

    /// Set `aria-invalid` to `"true"` or `"false"`. When left unset the
    /// attribute is omitted entirely.
    #[must_use]
    pub const fn aria_invalid(mut self, invalid: bool) -> Self {
        self.aria_invalid = Some(invalid);
        self
    }

    /// Reference the `id` of the element describing this field via
    /// `aria-describedby`.
    #[must_use]
    pub fn described_by(mut self, id: impl Into<String>) -> Self {
        self.described_by = Some(id.into());
        self
    }

    /// Attach an arbitrary `hx-*` attribute (the `name` is the suffix after
    /// `hx-`), preserving the typed label obligation. Emitted in insertion
    /// order. Available before or after a label is attached.
    #[must_use]
    pub fn hx(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.hx.push((name.into(), value.into()));
        self
    }
}

impl Render for Checkbox<Labeled> {
    fn render(&self) -> Markup {
        let (visible_label, aria_label, aria_labelledby, aria_invalid, aria_required) =
            label_render_attrs(self.label.as_ref(), self.aria_invalid, self.aria_required);
        let input = html! {
            input
                type="checkbox"
                id=(self.name)
                name=(self.name)
                value=[self.value.as_deref()]
                aria-label=[aria_label]
                aria-labelledby=[aria_labelledby]
                class=[self.class.as_deref()]
                aria-invalid=[aria_invalid]
                aria-describedby=[self.described_by.as_deref()]
                aria-required=[aria_required]
                checked[self.checked]
                required[self.required];
        };
        html! {
            (with_hx_attrs(input, &self.hx))
            @if let Some(text) = visible_label {
                label for=(self.name) class=[self.label_class.as_deref()] { (text) }
            }
        }
    }
}

/// A `<input type="file">` whose label association is enforced by the type
/// system (WCAG 1.3.1 Info and Relationships, 3.3.2 Labels or Instructions,
/// 4.1.2 Name, Role, Value).
///
/// [`FileField::new`] returns a `FileField<NoLabel>`, which has no way to
/// render. Attaching a label with [`label`](FileField::label),
/// [`aria_label`](FileField::aria_label), or
/// [`labelled_by`](FileField::labelled_by) consumes it and returns a
/// `FileField<Labeled>`, the only state that implements [`maud::Render`].
///
/// This is the typed, explicitly-labeled file input planned in issue #1933. It
/// resolves the accessible-name caveat of the older
/// `storage::form_helper::direct_upload_input` helper, whose *derived*
/// `aria-label` takes ARIA precedence over a caller's visible `<label>`: with a
/// visible label a `FileField` emits **no** competing `aria-label`, so the
/// caller's `<label for=…>` is the control's accessible name.
///
/// A file input has no repopulate-on-error value (a browser will not let markup
/// pre-fill a file control), so `FileField` deliberately carries no `value`.
#[derive(Debug, Clone)]
pub struct FileField<State> {
    name: String,
    accept: Option<String>,
    multiple: bool,
    required: bool,
    aria_required: bool,
    class: Option<String>,
    label_class: Option<String>,
    aria_invalid: Option<bool>,
    described_by: Option<String>,
    hx: Vec<(String, String)>,
    label: Option<LabelSource>,
    _state: std::marker::PhantomData<State>,
}

impl FileField<NoLabel> {
    /// Start building a file input with the given form `name`. The returned
    /// value has no label yet and cannot be rendered until one is attached.
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            accept: None,
            multiple: false,
            required: false,
            aria_required: false,
            class: None,
            label_class: None,
            aria_invalid: None,
            described_by: None,
            hx: Vec::new(),
            label: None,
            _state: std::marker::PhantomData,
        }
    }

    /// Attach a visible `<label for=…>` and transition to the renderable
    /// [`Labeled`] state. With a visible label the field emits no `aria-label`,
    /// so the visible label is the caller-controlled accessible name.
    #[must_use]
    #[track_caller]
    pub fn label(self, text: impl Into<String>) -> FileField<Labeled> {
        self.with_label(LabelSource::Visible(checked_name("FileField::label", text)))
    }

    /// Attach an `aria-label` (no visible label) and transition to the
    /// renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn aria_label(self, text: impl Into<String>) -> FileField<Labeled> {
        self.with_label(LabelSource::Aria(checked_name(
            "FileField::aria_label",
            text,
        )))
    }

    /// Reference an existing element's `id` via `aria-labelledby` and transition
    /// to the renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn labelled_by(self, id: impl Into<String>) -> FileField<Labeled> {
        self.with_label(LabelSource::LabelledBy(checked_name(
            "FileField::labelled_by",
            id,
        )))
    }

    fn with_label(self, label: LabelSource) -> FileField<Labeled> {
        FileField {
            name: self.name,
            accept: self.accept,
            multiple: self.multiple,
            required: self.required,
            aria_required: self.aria_required,
            class: self.class,
            label_class: self.label_class,
            aria_invalid: self.aria_invalid,
            described_by: self.described_by,
            hx: self.hx,
            label: Some(label),
            _state: std::marker::PhantomData,
        }
    }
}

impl<State> FileField<State> {
    /// Set the `accept` attribute (a comma-separated list of MIME types or file
    /// extensions the picker should filter to).
    #[must_use]
    pub fn accept(mut self, accept: impl Into<String>) -> Self {
        self.accept = Some(accept.into());
        self
    }

    /// Allow selecting more than one file (`multiple`).
    #[must_use]
    pub const fn multiple(mut self) -> Self {
        self.multiple = true;
        self
    }

    /// Mark the file input as `required`.
    #[must_use]
    pub const fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Add a mirroring `aria-required="true"` alongside the native `required`
    /// attribute. Available before or after a label is attached.
    #[must_use]
    pub const fn aria_required(mut self) -> Self {
        self.aria_required = true;
        self
    }

    /// Set the `class` attribute on the `<input>`.
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Set the `class` attribute on the visible `<label>` element. Only affects
    /// rendering when a visible label was set via [`label`](Self::label).
    #[must_use]
    pub fn label_class(mut self, class: impl Into<String>) -> Self {
        self.label_class = Some(class.into());
        self
    }

    /// Set `aria-invalid` to `"true"` or `"false"`. When left unset the
    /// attribute is omitted entirely.
    #[must_use]
    pub const fn aria_invalid(mut self, invalid: bool) -> Self {
        self.aria_invalid = Some(invalid);
        self
    }

    /// Reference the `id` of the element describing this field via
    /// `aria-describedby`.
    #[must_use]
    pub fn described_by(mut self, id: impl Into<String>) -> Self {
        self.described_by = Some(id.into());
        self
    }

    /// Attach an arbitrary `hx-*` attribute (the `name` is the suffix after
    /// `hx-`), preserving the typed label obligation. Emitted in insertion
    /// order. Available before or after a label is attached.
    #[must_use]
    pub fn hx(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.hx.push((name.into(), value.into()));
        self
    }
}

impl Render for FileField<Labeled> {
    fn render(&self) -> Markup {
        // With a visible label we deliberately emit NO `aria-label`: the
        // `<label for=…>` is the caller-controlled accessible name. This is the
        // fix for the `direct_upload_input` derived-aria-label precedence caveat
        // (issue #1933).
        let (visible_label, aria_label, aria_labelledby, aria_invalid, aria_required) =
            label_render_attrs(self.label.as_ref(), self.aria_invalid, self.aria_required);
        let input = html! {
            input
                type="file"
                id=(self.name)
                name=(self.name)
                accept=[self.accept.as_deref()]
                aria-label=[aria_label]
                aria-labelledby=[aria_labelledby]
                class=[self.class.as_deref()]
                aria-invalid=[aria_invalid]
                aria-describedby=[self.described_by.as_deref()]
                aria-required=[aria_required]
                multiple[self.multiple]
                required[self.required];
        };
        html! {
            @if let Some(text) = visible_label {
                label for=(self.name) class=[self.label_class.as_deref()] { (text) }
            }
            (with_hx_attrs(input, &self.hx))
        }
    }
}

/// One choice in a [`RadioGroup`], carrying its own visible label.
///
/// [`RadioOption::new`] takes the submitted `value` and the human-visible
/// `label` as required positional arguments, so an unlabeled choice cannot be
/// built (WCAG 1.3.1 Info and Relationships, 4.1.2 Name, Role, Value).
#[derive(Debug, Clone)]
pub struct RadioOption {
    value: String,
    label: String,
    checked: bool,
    disabled: bool,
}

impl RadioOption {
    /// Build a choice with a submitted `value` and a human-visible `label`.
    #[track_caller]
    pub fn new(value: impl Into<String>, label: impl Into<String>) -> Self {
        Self {
            value: value.into(),
            label: checked_name("RadioOption::new", label),
            checked: false,
            disabled: false,
        }
    }

    /// Pre-select this choice. A group holds one selection, so if more than one
    /// choice is marked, only the first renders as `checked`;
    /// [`RadioGroup::checked_value`] sets it authoritatively.
    #[must_use]
    pub const fn checked(mut self) -> Self {
        self.checked = true;
        self
    }

    /// Mark this choice `disabled`.
    #[must_use]
    pub const fn disabled(mut self) -> Self {
        self.disabled = true;
        self
    }
}

/// A set of mutually exclusive radio buttons whose group label is enforced by
/// the type system (WCAG 1.3.1 Info and Relationships, 3.3.2 Labels or
/// Instructions, 4.1.2 Name, Role, Value).
///
/// A radio group needs **two** accessible names: one per choice, and one for
/// the group itself — without the group name a screen reader announces
/// "Standard, radio button" with no clue what is being chosen. Both are
/// obligations here: [`RadioOption::new`] requires the choice label, and
/// [`RadioGroup::new`] returns a `RadioGroup<NoLabel>`, which has no way to
/// render. Attaching the group name with [`label`](RadioGroup::label),
/// [`aria_label`](RadioGroup::aria_label), or
/// [`labelled_by`](RadioGroup::labelled_by) consumes it and returns a
/// `RadioGroup<Labeled>`, the only state that implements [`maud::Render`].
///
/// A group of choices with no choices is equally meaningless, so
/// [`RadioGroup::new`] takes the first [`RadioOption`] as a required argument:
/// every group carries at least one control.
///
/// A visible group name renders `<fieldset><legend>…</legend>`, the native
/// grouping HTML gives for free; the `aria-label` / `aria-labelledby` variants
/// render a `<div>` instead. Both carry `role="radiogroup"` — `<fieldset>`
/// alone maps to role `group`, which does not support `aria-required`.
///
/// `aria-invalid` and any `hx-*` attributes land on each `<input>`, where
/// assistive technology announces validity and where htmx reads a value;
/// `aria-describedby` and `aria-required` stay on the group, which is what they
/// describe.
///
/// ```rust
/// use autumn_web::a11y::{RadioGroup, RadioOption};
/// use maud::Render;
///
/// let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
///     .option(RadioOption::new("express", "Express"))
///     .checked_value("express")
///     .label("Shipping speed")
///     .render()
///     .into_string();
/// assert!(markup.contains("<legend>Shipping speed</legend>"));
/// ```
#[derive(Debug, Clone)]
pub struct RadioGroup<State> {
    name: String,
    id_prefix: Option<String>,
    options: Vec<RadioOption>,
    required: bool,
    aria_required: bool,
    class: Option<String>,
    label_class: Option<String>,
    aria_invalid: Option<bool>,
    described_by: Option<String>,
    hx: Vec<(String, String)>,
    label: Option<LabelSource>,
    _state: std::marker::PhantomData<State>,
}

impl RadioGroup<NoLabel> {
    /// Start building a radio group with the given form `name` and its first
    /// choice. The returned value has no group label yet and cannot be rendered
    /// until one is attached.
    pub fn new(name: impl Into<String>, first: RadioOption) -> Self {
        Self {
            name: name.into(),
            id_prefix: None,
            options: vec![first],
            required: false,
            aria_required: false,
            class: None,
            label_class: None,
            aria_invalid: None,
            described_by: None,
            hx: Vec::new(),
            label: None,
            _state: std::marker::PhantomData,
        }
    }

    /// Attach a visible `<legend>` and transition to the renderable
    /// [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn label(self, text: impl Into<String>) -> RadioGroup<Labeled> {
        self.with_label(LabelSource::Visible(checked_name(
            "RadioGroup::label",
            text,
        )))
    }

    /// Attach an `aria-label` (no visible legend) and transition to the
    /// renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn aria_label(self, text: impl Into<String>) -> RadioGroup<Labeled> {
        self.with_label(LabelSource::Aria(checked_name(
            "RadioGroup::aria_label",
            text,
        )))
    }

    /// Reference an existing element's `id` via `aria-labelledby` and
    /// transition to the renderable [`Labeled`] state.
    #[must_use]
    #[track_caller]
    pub fn labelled_by(self, id: impl Into<String>) -> RadioGroup<Labeled> {
        self.with_label(LabelSource::LabelledBy(checked_name(
            "RadioGroup::labelled_by",
            id,
        )))
    }

    fn with_label(self, label: LabelSource) -> RadioGroup<Labeled> {
        RadioGroup {
            name: self.name,
            id_prefix: self.id_prefix,
            options: self.options,
            required: self.required,
            aria_required: self.aria_required,
            class: self.class,
            label_class: self.label_class,
            aria_invalid: self.aria_invalid,
            described_by: self.described_by,
            hx: self.hx,
            label: Some(label),
            _state: std::marker::PhantomData,
        }
    }
}

impl<State> RadioGroup<State> {
    /// Append a choice. Choices render in insertion order.
    ///
    /// This takes a built [`RadioOption`], as [`RadioGroup::new`] does, so a
    /// choice is built the same way in both places. [`Select::option`] takes
    /// the `(value, label)` pair instead.
    #[must_use]
    pub fn option(mut self, option: RadioOption) -> Self {
        self.options.push(option);
        self
    }

    /// Append several choices at once.
    #[must_use]
    pub fn options(mut self, options: impl IntoIterator<Item = RadioOption>) -> Self {
        self.options.extend(options);
        self
    }

    /// Prefix every choice `id` with `prefix`.
    ///
    /// Ids derive from the group name and the choice value, which is enough
    /// while each group appears once. The same group rendered repeatedly — one
    /// per table row, say — shares its form name by design, so the caller
    /// supplies the discriminator that keeps the ids unique in the document.
    #[must_use]
    pub fn id_prefix(mut self, prefix: impl Into<String>) -> Self {
        self.id_prefix = Some(prefix.into());
        self
    }

    /// Authoritatively set the single checked choice: the choice whose `value`
    /// matches is marked `checked` and every other choice's flag is cleared.
    /// A radio group holds one selection, so this guarantees at most one
    /// `checked` control — any prior [`RadioOption::checked`] is overridden.
    #[must_use]
    pub fn checked_value(mut self, value: impl Into<String>) -> Self {
        let value = value.into();
        for option in &mut self.options {
            option.checked = option.value == value;
        }
        self
    }

    /// Mark the group as `required` — one choice must be selected. The
    /// attribute lands on every control in the group, which is how a browser
    /// reads a required radio group.
    #[must_use]
    pub const fn required(mut self) -> Self {
        self.required = true;
        self
    }

    /// Add a mirroring `aria-required="true"` on the group element.
    #[must_use]
    pub const fn aria_required(mut self) -> Self {
        self.aria_required = true;
        self
    }

    /// Set the `class` attribute on the group element (`<fieldset>` or
    /// `<div role="radiogroup">`).
    #[must_use]
    pub fn class(mut self, class: impl Into<String>) -> Self {
        self.class = Some(class.into());
        self
    }

    /// Set the `class` attribute on the visible `<legend>`. Only affects
    /// rendering when a visible group name was set via [`label`](Self::label).
    #[must_use]
    pub fn label_class(mut self, class: impl Into<String>) -> Self {
        self.label_class = Some(class.into());
        self
    }

    /// Set `aria-invalid` on the group to `"true"` or `"false"`. When left
    /// unset the attribute is omitted entirely.
    #[must_use]
    pub const fn aria_invalid(mut self, invalid: bool) -> Self {
        self.aria_invalid = Some(invalid);
        self
    }

    /// Reference the `id` of the element describing this group via
    /// `aria-describedby`.
    #[must_use]
    pub fn described_by(mut self, id: impl Into<String>) -> Self {
        self.described_by = Some(id.into());
        self
    }

    /// Attach an arbitrary `hx-*` attribute to the group element (the `name` is
    /// the suffix after `hx-`), preserving the typed label obligation. Emitted
    /// in insertion order. Available before or after a label is attached.
    #[must_use]
    pub fn hx(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
        self.hx.push((name.into(), value.into()));
        self
    }
}

/// One `id` per choice, unique within the group and, for most names, across
/// groups. Some names still collide across groups (#3454).
///
/// The id pairs each `<input>` with its `<label for=…>`, so a duplicate would
/// break the very association the primitive exists to guarantee. Each part is
/// reduced to the safe `[A-Za-z0-9_-]` alphabet, and a `-` inside a part is
/// doubled so the single `-` that joins the parts cannot be mistaken for one:
/// without that, group `a-b` choice `c` and group `a` choice `b-c` would both
/// read `a-b-c`, and no per-group check can see the other group. Two choices
/// that still reduce to the same text within one group are separated by an
/// index suffix, so those ids depend on the order they were added. The lead
/// part goes through [`selector_safe`], so every id is a valid CSS selector.
fn radio_option_ids(prefix: Option<&str>, name: &str, options: &[RadioOption]) -> Vec<String> {
    let group = prefix.map_or_else(
        || selector_safe(&id_part(name)),
        |prefix| format!("{}-{}", selector_safe(&id_part(prefix)), id_part(name)),
    );
    let mut seen = std::collections::HashSet::new();
    let mut ids = Vec::with_capacity(options.len());
    for (index, option) in options.iter().enumerate() {
        let base = format!("{group}-{}", id_part(&option.value));
        let mut id = base.clone();
        let mut suffix = index;
        while !seen.insert(id.clone()) {
            id = format!("{base}-{suffix}");
            suffix += 1;
        }
        ids.push(id);
    }
    ids
}

/// One part of a choice `id`: reduced to the `[A-Za-z0-9_-]` alphabet an HTML
/// `id` can safely carry, with every `-` doubled so a part never contains the
/// single `-` that separates parts.
fn id_part(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    for c in text.chars() {
        if c == '-' {
            out.push_str("--");
        } else if c.is_ascii_alphanumeric() || c == '_' {
            out.push(c);
        } else {
            out.push_str("--");
        }
    }
    out
}

/// Make the first part of an id safe as the start of a CSS selector, so
/// `#id` works in `querySelector` and `hx-target`.
///
/// If the part, after any leading `_`, does not start with a letter, the part
/// gets one more `_` at the start: `1plan` becomes `_1plan`, and `_1plan`
/// becomes `__1plan`. Thus two different parts never give the same result.
/// `verification/radio_choice_id.rs` proves both rules.
fn selector_safe(part: &str) -> String {
    if part
        .trim_start_matches('_')
        .starts_with(|c: char| c.is_ascii_alphabetic())
    {
        part.to_owned()
    } else {
        format!("_{part}")
    }
}

impl Render for RadioGroup<Labeled> {
    fn render(&self) -> Markup {
        let (visible_label, aria_label, aria_labelledby, aria_invalid, aria_required) =
            label_render_attrs(self.label.as_ref(), self.aria_invalid, self.aria_required);
        let ids = radio_option_ids(self.id_prefix.as_deref(), &self.name, &self.options);
        // A group holds one selection: more than one `checked` control is a
        // document-conformance error, and a browser would keep only the last,
        // so the rendered state would disagree with what the user sees. Only
        // the first checked choice renders as checked.
        let checked_at = self.options.iter().position(|o| o.checked);
        let controls = html! {
            @for (index, (option, id)) in self.options.iter().zip(&ids).enumerate() {
                (with_hx_attrs(html! {
                    input
                        type="radio"
                        id=(id)
                        name=(self.name)
                        value=(option.value)
                        checked[checked_at == Some(index)]
                        disabled[option.disabled]
                        required[self.required]
                        aria-invalid=[aria_invalid];
                }, &self.hx))
                label for=(id) { (option.label) }
            }
        };
        // A visible name uses the native grouping element; an ARIA name uses an
        // explicit role, so the group keeps its semantics without a second name.
        visible_label.map_or_else(
            || {
                html! {
                    div
                        role="radiogroup"
                        aria-label=[aria_label]
                        aria-labelledby=[aria_labelledby]
                        class=[self.class.as_deref()]
                        aria-describedby=[self.described_by.as_deref()]
                        aria-required=[aria_required] {
                            (controls)
                        }
                }
            },
            |text| {
                html! {
                    fieldset
                        role="radiogroup"
                        class=[self.class.as_deref()]
                        aria-describedby=[self.described_by.as_deref()]
                        aria-required=[aria_required] {
                            legend class=[self.label_class.as_deref()] { (text) }
                            (controls)
                        }
                }
            },
        )
    }
}

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

    #[test]
    fn img_new_requires_and_renders_alt() {
        let markup = Img::new("/logo.png", "Company logo").render().into_string();
        assert!(markup.contains("src=\"/logo.png\""));
        assert!(markup.contains("alt=\"Company logo\""));
    }

    #[test]
    fn img_decorative_sets_empty_alt() {
        let markup = Img::decorative("/divider.png").render().into_string();
        assert!(markup.contains("alt=\"\""));
    }

    #[test]
    fn img_escapes_alt_text() {
        let markup = Img::new("/x.png", "a \"quoted\" & <tagged> name")
            .render()
            .into_string();
        assert!(!markup.contains("<tagged>"));
        assert!(markup.contains("&lt;tagged&gt;"));
    }

    #[test]
    fn button_new_renders_visible_label() {
        let markup = Button::new("Save").submit().render().into_string();
        assert!(markup.contains("type=\"submit\""));
        assert!(markup.contains(">Save<"));
        assert!(!markup.contains("aria-label"));
    }

    #[test]
    fn button_icon_uses_aria_label() {
        let icon = html! { span aria-hidden="true" { "x" } };
        let markup = Button::icon(icon, "Close dialog").render().into_string();
        assert!(markup.contains("aria-label=\"Close dialog\""));
    }

    #[test]
    fn text_field_visible_label_is_associated() {
        let markup = TextField::new("email")
            .input_type("email")
            .label("Email address")
            .render()
            .into_string();
        assert!(markup.contains("<label for=\"email\">Email address</label>"));
        assert!(markup.contains("id=\"email\""));
        assert!(markup.contains("name=\"email\""));
        assert!(markup.contains("type=\"email\""));
    }

    #[test]
    fn text_field_aria_label_variant() {
        let markup = TextField::new("q")
            .aria_label("Search")
            .render()
            .into_string();
        assert!(markup.contains("aria-label=\"Search\""));
    }

    #[test]
    fn text_field_labelled_by_variant() {
        let markup = TextField::new("q")
            .labelled_by("search-heading")
            .render()
            .into_string();
        assert!(markup.contains("aria-labelledby=\"search-heading\""));
    }

    #[test]
    fn text_field_required_and_value() {
        let markup = TextField::new("name")
            .value("Ada")
            .required()
            .label("Name")
            .render()
            .into_string();
        assert!(markup.contains("value=\"Ada\""));
        assert!(markup.contains("required"));
    }

    #[test]
    fn text_field_carries_class_and_error_wiring() {
        let markup = TextField::new("email")
            .input_type("email")
            .class("autumn-field__input autumn-field__input--invalid")
            .aria_invalid(true)
            .described_by("email-error")
            .label("Email address")
            .render()
            .into_string();
        assert!(
            markup.contains("class=\"autumn-field__input autumn-field__input--invalid\""),
            "{markup}"
        );
        assert!(markup.contains("aria-invalid=\"true\""), "{markup}");
        assert!(
            markup.contains("aria-describedby=\"email-error\""),
            "{markup}"
        );
        // The label obligation is still discharged via the visible label.
        assert!(
            markup.contains("<label for=\"email\">Email address</label>"),
            "{markup}"
        );
    }

    #[test]
    fn text_field_aria_invalid_false_renders_explicitly() {
        let markup = TextField::new("email")
            .aria_invalid(false)
            .label("Email address")
            .render()
            .into_string();
        assert!(markup.contains("aria-invalid=\"false\""), "{markup}");
    }

    #[test]
    fn text_field_aria_invalid_omitted_when_unset() {
        let markup = TextField::new("email")
            .label("Email address")
            .render()
            .into_string();
        assert!(!markup.contains("aria-invalid"), "{markup}");
        assert!(!markup.contains("aria-describedby"), "{markup}");
    }

    #[test]
    fn text_field_string_length_constraints() {
        let markup = TextField::new("title")
            .minlength(3)
            .maxlength(120)
            .required()
            .aria_required()
            .label("Title")
            .render()
            .into_string();
        assert!(markup.contains("minlength=\"3\""), "{markup}");
        assert!(markup.contains("maxlength=\"120\""), "{markup}");
        assert!(markup.contains("required"), "{markup}");
        assert!(markup.contains("aria-required=\"true\""), "{markup}");
    }

    #[test]
    fn text_field_numeric_constraints() {
        let markup = TextField::new("ratio")
            .input_type("number")
            .min("0")
            .max("1")
            .step("any")
            .label("Ratio")
            .render()
            .into_string();
        assert!(markup.contains("type=\"number\""), "{markup}");
        assert!(markup.contains("min=\"0\""), "{markup}");
        assert!(markup.contains("max=\"1\""), "{markup}");
        assert!(markup.contains("step=\"any\""), "{markup}");
    }

    #[test]
    fn text_field_label_class_is_emitted() {
        let html = TextField::new("email")
            .label("Email address")
            .label_class("autumn-field__label")
            .render()
            .into_string();
        assert!(
            html.contains(
                r#"<label for="email" class="autumn-field__label">Email address</label>"#
            ),
            "got: {html}"
        );
    }

    #[test]
    fn text_field_label_class_omitted_when_unset() {
        let html = TextField::new("email")
            .label("Email address")
            .render()
            .into_string();
        assert!(
            html.contains(r#"<label for="email">Email address</label>"#),
            "got: {html}"
        );
        assert!(
            !html.contains("class="),
            "label should have no class when unset, got: {html}"
        );
    }

    #[test]
    fn text_field_new_attrs_survive_aria_label_variant() {
        // The new attributes are set on the `NoLabel` builder before the label
        // transition; they must survive `with_label` into the `Labeled` state.
        let markup = TextField::new("q")
            .class("search")
            .aria_invalid(true)
            .aria_label("Search")
            .render()
            .into_string();
        assert!(markup.contains("aria-label=\"Search\""), "{markup}");
        assert!(markup.contains("class=\"search\""), "{markup}");
        assert!(markup.contains("aria-invalid=\"true\""), "{markup}");
    }

    #[test]
    fn is_valid_hx_suffix_accepts_safe_alphabet_only() {
        // Valid suffixes: lowercase letters, digits, and '-', non-empty.
        assert!(is_valid_hx_suffix("post"));
        assert!(is_valid_hx_suffix("trigger"));
        assert!(is_valid_hx_suffix("on-2"));
        assert!(is_valid_hx_suffix("swap-oob"));
        // Invalid: empty, whitespace, '=', and other injection characters that
        // `maud::Escaper` does not escape.
        assert!(!is_valid_hx_suffix(""));
        assert!(!is_valid_hx_suffix("post autofocus"));
        assert!(!is_valid_hx_suffix("post=x"));
        assert!(!is_valid_hx_suffix("Post"));
        assert!(!is_valid_hx_suffix("po st"));
        assert!(!is_valid_hx_suffix("post\"onload"));
        assert!(!is_valid_hx_suffix("hx_post"));
    }

    // ── RadioGroup ─────────────────────────────────────────────────────────

    /// The opening `<input>` tag carrying `value="{value}"`, so an assertion
    /// binds an attribute to a control without pinning attribute order.
    fn open_tag_of_input<'m>(markup: &'m str, value: &str) -> &'m str {
        let needle = format!(r#"value="{value}""#);
        let tag = markup
            .split("<input")
            .find(|fragment| fragment.contains(&needle))
            .unwrap_or_else(|| panic!("no <input> with {needle} in {markup}"));
        &tag[..tag.find('>').expect("input tag closes")]
    }

    /// The opening tag of the group element (`<fieldset>` or `<div>`).
    fn open_tag_of_group(markup: &str) -> &str {
        &markup[..markup.find('>').expect("group opens")]
    }

    #[test]
    fn radio_group_renders_fieldset_legend_and_options() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .option(RadioOption::new("express", "Express"))
            .label("Shipping speed")
            .render()
            .into_string();
        assert!(markup.contains("<fieldset"), "{markup}");
        assert!(
            markup.contains("<legend>Shipping speed</legend>"),
            "{markup}"
        );
        // Every option carries its own input/label pair, associated by id.
        assert!(
            markup.contains(r#"id="speed-standard""#) && markup.contains(r#"for="speed-standard""#),
            "{markup}"
        );
        assert!(
            markup.contains(r#"id="speed-express""#) && markup.contains(r#"for="speed-express""#),
            "{markup}"
        );
        // One radio group: every input shares the form name.
        assert_eq!(markup.matches(r#"name="speed""#).count(), 2, "{markup}");
        assert_eq!(markup.matches(r#"type="radio""#).count(), 2, "{markup}");
    }

    #[test]
    fn radio_group_aria_label_uses_radiogroup_role() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .aria_label("Shipping speed")
            .render()
            .into_string();
        assert!(markup.contains(r#"role="radiogroup""#), "{markup}");
        assert!(
            markup.contains(r#"aria-label="Shipping speed""#),
            "{markup}"
        );
        // An aria-named group renders no competing visible legend.
        assert!(!markup.contains("<legend"), "{markup}");
        assert!(!markup.contains("<fieldset"), "{markup}");
        // …and still renders its controls, each paired with its own label.
        assert_eq!(markup.matches(r#"type="radio""#).count(), 1, "{markup}");
        assert!(
            markup.contains(r#"id="speed-standard""#) && markup.contains(r#"for="speed-standard""#),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_labelled_by_uses_radiogroup_role() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .labelled_by("speed-heading")
            .render()
            .into_string();
        assert!(markup.contains(r#"role="radiogroup""#), "{markup}");
        assert!(
            markup.contains(r#"aria-labelledby="speed-heading""#),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_marks_the_checked_option_only() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .option(RadioOption::new("express", "Express").checked())
            .label("Shipping speed")
            .render()
            .into_string();
        assert_eq!(markup.matches(" checked").count(), 1, "{markup}");
        assert!(
            open_tag_of_input(&markup, "express").contains(" checked"),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_disambiguates_colliding_option_ids() {
        // Two values that sanitize to the same id must not produce duplicate
        // ids: a duplicate id breaks the `for=`/`id=` label association.
        let markup = RadioGroup::new("plan", RadioOption::new("a b", "A B"))
            .options([
                RadioOption::new("a-b", "A-B"),
                // Collides with the disambiguated id of the pair above, so the
                // retry loop must run more than once.
                RadioOption::new("a b", "A B again"),
            ])
            .label("Plan")
            .render()
            .into_string();
        let ids: Vec<&str> = markup
            .match_indices(r#" id=""#)
            .map(|(at, _)| {
                let rest = &markup[at + 5..];
                &rest[..rest.find('"').expect("id closes")]
            })
            .collect();
        // A `-` inside a part is doubled, so all three reduce to `plan-a--b`
        // and the index suffix separates them.
        assert_eq!(
            ids,
            vec!["plan-a--b", "plan-a--b-1", "plan-a--b-2"],
            "{markup}"
        );
        for id in &ids {
            assert!(markup.contains(&format!(r#"for="{id}""#)), "{markup}");
        }
    }

    #[test]
    fn radio_group_ids_do_not_collide_across_groups() {
        // `("a-b", "c")` and `("a", "b-c")` would both reduce to `a-b-c` if the
        // separator were ambiguous. Two groups cannot see each other's `seen`
        // set, so the derivation itself has to keep them apart.
        let one = RadioGroup::new("a-b", RadioOption::new("c", "C"))
            .label("One")
            .render()
            .into_string();
        let two = RadioGroup::new("a", RadioOption::new("b-c", "BC"))
            .label("Two")
            .render()
            .into_string();
        let id_of = |markup: &str| {
            let at = markup.find(r#" id=""#).expect("an id") + 5;
            markup[at..][..markup[at..].find('"').expect("id closes")].to_owned()
        };
        assert_ne!(id_of(&one), id_of(&two), "{one}\n{two}");
    }

    #[test]
    fn radio_group_ids_keep_the_plain_shape_when_nothing_needs_escaping() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .label("Shipping speed")
            .render()
            .into_string();
        assert!(markup.contains(r#"id="speed-standard""#), "{markup}");
    }

    #[test]
    fn radio_group_id_prefix_separates_repeated_groups() {
        // The same group rendered per table row needs distinct ids; the form
        // name is shared by design, so the caller supplies the discriminator.
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .id_prefix("row-7")
            .label("Shipping speed")
            .render()
            .into_string();
        assert!(markup.contains(r#"id="row--7-speed-standard""#), "{markup}");
        assert!(
            markup.contains(r#"for="row--7-speed-standard""#),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_carries_required_and_error_wiring() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .option(RadioOption::new("express", "Express"))
            .required()
            .aria_required()
            .aria_invalid(true)
            .described_by("speed-error")
            .class("field")
            .label_class("field__legend")
            .label("Shipping speed")
            .render()
            .into_string();
        // `required` marks the group by marking each control in it.
        assert_eq!(markup.matches(" required").count(), 2, "{markup}");
        assert!(
            open_tag_of_input(&markup, "standard").contains(" required"),
            "{markup}"
        );
        // The group carries what describes the group; the controls carry what
        // assistive technology reads per control.
        let group = open_tag_of_group(&markup);
        assert!(group.contains(r#"aria-required="true""#), "{markup}");
        assert!(
            group.contains(r#"aria-describedby="speed-error""#),
            "{markup}"
        );
        assert!(group.contains(r#"class="field""#), "{markup}");
        assert!(!group.contains("aria-invalid"), "{markup}");
        assert!(
            open_tag_of_input(&markup, "standard").contains(r#"aria-invalid="true""#),
            "{markup}"
        );
        assert!(markup.contains(r#"class="field__legend""#), "{markup}");
    }

    #[test]
    fn radio_group_accepts_hx_attributes() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .hx("post", "/quote")
            .label("Shipping speed")
            .render()
            .into_string();
        assert!(markup.contains(r#"hx-post="/quote""#), "{markup}");
    }

    #[test]
    fn radio_group_disabled_option_renders_disabled() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .option(RadioOption::new("overnight", "Overnight").disabled())
            .label("Shipping speed")
            .render()
            .into_string();
        assert_eq!(markup.matches(" disabled").count(), 1, "{markup}");
        assert!(
            open_tag_of_input(&markup, "overnight").contains(" disabled"),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_fieldset_carries_the_radiogroup_role() {
        // `<fieldset>` maps to role `group`, which does not support
        // `aria-required`. An explicit `role="radiogroup"` (allowed on
        // `fieldset` by ARIA in HTML) makes the attribute legal and announces
        // the group for what it is.
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .aria_required()
            .label("Shipping speed")
            .render()
            .into_string();
        let group = open_tag_of_group(&markup);
        assert!(group.contains("<fieldset"), "{markup}");
        assert!(group.contains(r#"role="radiogroup""#), "{markup}");
        assert!(group.contains(r#"aria-required="true""#), "{markup}");
    }

    #[test]
    fn radio_group_checks_at_most_one_option() {
        // More than one checked radio in a group is a document-conformance
        // error, and browsers keep only the last — so server state would
        // silently disagree with what the user sees.
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard").checked())
            .option(RadioOption::new("express", "Express").checked())
            .label("Shipping speed")
            .render()
            .into_string();
        assert_eq!(markup.matches(" checked").count(), 1, "{markup}");
        assert!(
            open_tag_of_input(&markup, "standard").contains(" checked"),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_checked_value_overrides_every_option() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard").checked())
            .option(RadioOption::new("express", "Express"))
            .checked_value("express")
            .label("Shipping speed")
            .render()
            .into_string();
        assert_eq!(markup.matches(" checked").count(), 1, "{markup}");
        let express = markup
            .split(r#"value="express""#)
            .nth(1)
            .expect("express option rendered");
        assert!(express.starts_with(" checked"), "{markup}");
    }

    #[test]
    fn radio_group_aria_invalid_lands_on_every_control() {
        // Assistive technology announces invalidity per control, not per
        // container, so `aria-invalid` belongs on the inputs.
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .option(RadioOption::new("express", "Express"))
            .aria_invalid(true)
            .described_by("speed-error")
            .label("Shipping speed")
            .render()
            .into_string();
        assert_eq!(
            markup.matches(r#"aria-invalid="true""#).count(),
            2,
            "{markup}"
        );
        let group = open_tag_of_group(&markup);
        assert!(!group.contains("aria-invalid"), "{markup}");
        // The error description stays on the group, which is where it reads.
        assert!(
            group.contains(r#"aria-describedby="speed-error""#),
            "{markup}"
        );
    }

    #[test]
    fn radio_group_label_class_is_ignored_without_a_visible_legend() {
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .label_class("field__legend")
            .aria_label("Shipping speed")
            .render()
            .into_string();
        assert!(!markup.contains("field__legend"), "{markup}");
    }

    #[test]
    fn radio_group_hx_attributes_land_on_every_control() {
        // htmx defaults to the `change` trigger on an input and submits that
        // input's value; on the group container it would fire on any click and
        // carry no selection.
        let markup = RadioGroup::new("speed", RadioOption::new("standard", "Standard"))
            .option(RadioOption::new("express", "Express"))
            .hx("post", "/quote")
            .label("Shipping speed")
            .render()
            .into_string();
        assert_eq!(markup.matches(r#"hx-post="/quote""#).count(), 2, "{markup}");
        assert!(!open_tag_of_group(&markup).contains("hx-post"), "{markup}");
    }

    /// Builds one primitive, and renders nothing.
    type Build = Box<dyn Fn() + std::panic::RefUnwindSafe>;

    /// Every entry point that takes an accessible name, called with `name`.
    /// Each closure renders nothing; it only builds the value.
    fn name_entry_points(name: &'static str) -> Vec<(&'static str, Build)> {
        let first = || RadioOption::new("a", "A");
        vec![
            ("Img::new", Box::new(move || drop(Img::new("/x.png", name)))),
            ("Button::new", Box::new(move || drop(Button::new(name)))),
            (
                "Button::icon",
                Box::new(move || drop(Button::icon(html! {}, name))),
            ),
            ("Link::new", Box::new(move || drop(Link::new("/", name)))),
            (
                "Link::icon",
                Box::new(move || drop(Link::icon("/", html! {}, name))),
            ),
            ("MenuItem::new", Box::new(move || drop(MenuItem::new(name)))),
            (
                "SelectOption::new",
                Box::new(move || drop(SelectOption::new("v", name))),
            ),
            (
                "Select::option",
                Box::new(move || drop(Select::new("f").option("v", name))),
            ),
            (
                "RadioOption::new",
                Box::new(move || drop(RadioOption::new("v", name))),
            ),
            (
                "TextField::label",
                Box::new(move || drop(TextField::new("f").label(name))),
            ),
            (
                "TextField::aria_label",
                Box::new(move || drop(TextField::new("f").aria_label(name))),
            ),
            (
                "TextField::labelled_by",
                Box::new(move || drop(TextField::new("f").labelled_by(name))),
            ),
            (
                "TextArea::label",
                Box::new(move || drop(TextArea::new("f").label(name))),
            ),
            (
                "TextArea::aria_label",
                Box::new(move || drop(TextArea::new("f").aria_label(name))),
            ),
            (
                "TextArea::labelled_by",
                Box::new(move || drop(TextArea::new("f").labelled_by(name))),
            ),
            (
                "Select::label",
                Box::new(move || drop(Select::new("f").label(name))),
            ),
            (
                "Select::aria_label",
                Box::new(move || drop(Select::new("f").aria_label(name))),
            ),
            (
                "Select::labelled_by",
                Box::new(move || drop(Select::new("f").labelled_by(name))),
            ),
            (
                "Checkbox::label",
                Box::new(move || drop(Checkbox::new("f").label(name))),
            ),
            (
                "Checkbox::aria_label",
                Box::new(move || drop(Checkbox::new("f").aria_label(name))),
            ),
            (
                "Checkbox::labelled_by",
                Box::new(move || drop(Checkbox::new("f").labelled_by(name))),
            ),
            (
                "FileField::label",
                Box::new(move || drop(FileField::new("f").label(name))),
            ),
            (
                "FileField::aria_label",
                Box::new(move || drop(FileField::new("f").aria_label(name))),
            ),
            (
                "FileField::labelled_by",
                Box::new(move || drop(FileField::new("f").labelled_by(name))),
            ),
            (
                "RadioGroup::label",
                Box::new(move || drop(RadioGroup::new("g", first()).label(name))),
            ),
            (
                "RadioGroup::aria_label",
                Box::new(move || drop(RadioGroup::new("g", first()).aria_label(name))),
            ),
            (
                "RadioGroup::labelled_by",
                Box::new(move || drop(RadioGroup::new("g", first()).labelled_by(name))),
            ),
        ]
    }

    /// Issue #2666: the typestate proves a name is present. An empty or blank
    /// name is not a name, so a debug build stops at the call site.
    #[test]
    #[cfg(debug_assertions)]
    fn an_empty_or_blank_accessible_name_trips_a_debug_assert() {
        for name in ["", " ", "\t\n", "\u{200B}", "\u{FEFF} "] {
            for (entry, build) in name_entry_points(name) {
                let result = std::panic::catch_unwind(&*build);
                assert!(
                    result.is_err(),
                    "{entry}({name:?}) must not accept an empty name"
                );
            }
        }
    }

    #[test]
    fn a_real_accessible_name_is_accepted_everywhere() {
        for (entry, build) in name_entry_points("Name") {
            let result = std::panic::catch_unwind(&*build);
            assert!(result.is_ok(), "{entry} rejected a real name");
        }
    }

    #[test]
    #[cfg(debug_assertions)]
    fn the_empty_name_panic_names_the_primitive() {
        let err = std::panic::catch_unwind(|| Img::new("/x.png", "")).expect_err("must panic");
        let message = err
            .downcast_ref::<String>()
            .map(String::as_str)
            .or_else(|| err.downcast_ref::<&str>().copied())
            .unwrap_or_default();
        assert!(message.contains("Img::new"), "{message}");
        assert!(message.contains("Img::decorative"), "{message}");
    }

    #[test]
    fn is_blank_matches_what_the_name_check_rejects() {
        for text in ["", " ", "\t\n", "\u{200B}", "\u{FEFF} ", "\u{2060}"] {
            assert!(is_blank(text), "{text:?}");
        }
        for text in ["a", " a ", "\u{200B}a"] {
            assert!(!is_blank(text), "{text:?}");
        }
    }

    #[test]
    fn an_empty_value_is_not_a_name_and_stays_allowed() {
        // The `— Select —` placeholder has an empty value and a real label.
        let markup = Select::new("s")
            .options([SelectOption::new("", "— Select —").disabled()])
            .label("Size")
            .render()
            .into_string();
        assert!(markup.contains(r#"value="""#), "{markup}");
        let markup = RadioGroup::new("g", RadioOption::new("", "None"))
            .label("Choice")
            .render()
            .into_string();
        assert!(markup.contains(r#"value="""#), "{markup}");
        assert!(
            Img::decorative("/x.png")
                .render()
                .into_string()
                .contains(r#"alt="""#)
        );
    }

    /// The first choice `id` in `markup`.
    fn first_id(markup: &str) -> String {
        let at = markup.find(r#" id=""#).expect("an id") + 5;
        markup[at..][..markup[at..].find('"').expect("id closes")].to_owned()
    }

    /// A CSS identifier over the ASCII alphabet an id here can carry: it
    /// starts with a letter or `_`, and holds only `[A-Za-z0-9_-]`.
    fn is_css_ident(id: &str) -> bool {
        id.chars()
            .next()
            .is_some_and(|c| c.is_ascii_alphabetic() || c == '_')
            && id
                .chars()
                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
    }

    /// Issue #2666: `#1plan-2x` is not a valid selector, so
    /// `querySelector` and `hx-target` throw on it.
    #[test]
    fn a_digit_led_group_name_gets_a_selector_safe_id() {
        let markup = RadioGroup::new("1plan", RadioOption::new("2x", "Two"))
            .label("Plan")
            .render()
            .into_string();
        assert_eq!(first_id(&markup), "_1plan-2x", "{markup}");
        assert!(markup.contains(r#"for="_1plan-2x""#), "{markup}");
    }

    #[test]
    fn an_empty_group_name_and_value_get_a_selector_safe_id() {
        let markup = RadioGroup::new("", RadioOption::new("", "None"))
            .label("Plan")
            .render()
            .into_string();
        assert_eq!(first_id(&markup), "_-", "{markup}");
    }

    #[test]
    fn a_digit_led_id_prefix_gets_a_selector_safe_id() {
        let markup = RadioGroup::new("speed", RadioOption::new("fast", "Fast"))
            .id_prefix("7")
            .label("Speed")
            .render()
            .into_string();
        assert_eq!(first_id(&markup), "_7-speed-fast", "{markup}");
    }

    #[test]
    fn an_underscore_led_name_cannot_collide_with_an_escaped_one() {
        // `1plan` becomes `_1plan`, so `_1plan` itself must move too.
        let escaped = RadioGroup::new("1plan", RadioOption::new("a", "A"))
            .label("One")
            .render()
            .into_string();
        let underscored = RadioGroup::new("_1plan", RadioOption::new("a", "A"))
            .label("Two")
            .render()
            .into_string();
        assert_eq!(first_id(&underscored), "__1plan-a", "{underscored}");
        assert_ne!(first_id(&escaped), first_id(&underscored));
    }

    #[test]
    fn a_letter_led_or_underscore_letter_name_keeps_its_id() {
        for (name, id) in [
            ("speed", "speed-a"),
            ("_speed", "_speed-a"),
            ("Speed", "Speed-a"),
        ] {
            let markup = RadioGroup::new(name, RadioOption::new("a", "A"))
                .label("Speed")
                .render()
                .into_string();
            assert_eq!(first_id(&markup), id, "{markup}");
        }
    }

    proptest::proptest! {
        /// Every choice id is a valid CSS identifier, so `#id` is a valid
        /// selector.
        #[test]
        fn every_choice_id_is_a_css_identifier(
            prefix in proptest::option::of("[a-z0-9_ .-]{0,6}"),
            name in "[A-Za-z0-9_ .\\[\\]-]{0,8}",
            values in proptest::collection::vec("[A-Za-z0-9_ .-]{0,6}", 1..4),
        ) {
            let options: Vec<RadioOption> =
                values.iter().map(|v| RadioOption::new(v.as_str(), "Choice")).collect();
            let ids = radio_option_ids(prefix.as_deref(), &name, &options);
            for id in &ids {
                proptest::prop_assert!(is_css_ident(id), "{id:?}");
            }
        }

        /// The rule is injective: two different parts never give one result
        /// (the Verus spec in `verification/radio_choice_id.rs` proves the
        /// same rule).
        #[test]
        fn the_selector_safe_rule_is_injective(a in "[A-Za-z0-9_-]{0,6}", b in "[A-Za-z0-9_-]{0,6}") {
            proptest::prop_assume!(a != b);
            proptest::prop_assert_ne!(selector_safe(&a), selector_safe(&b));
        }

        /// The one case that can collide: a part that gets the `_`, and the
        /// same part with a `_` already in front.
        #[test]
        fn an_escaped_part_never_meets_its_underscored_twin(a in "([0-9_-][A-Za-z0-9_-]{0,5})?") {
            proptest::prop_assert_ne!(selector_safe(&a), selector_safe(&format!("_{a}")));
        }
    }
}