makeover-immediate 0.27.0

//! The immediate-mode renderer for [`makeover_layout`].
//!
//! <!-- wiki: makeover-immediate -->
//!
//! Named for the mode, not the library, the way `makeover-tui` is named for
//! the target and not for ratatui. Immediate mode is the constraint that
//! actually separates this renderer from the other two, and egui is the
//! backend it is written against.
//!
//! It is the harshest renderer the description has to survive: no
//! `box-shadow`, no `inset`, no cascade, no retained tree to mutate, and
//! `Visuals.widgets.*.bg_stroke` is a single stroke with no per-side control.
//! A two-tone lit edge is not something egui can be configured into producing,
//! so it gets painted by hand here, once, instead of in every consuming app.
//!
//! # What this crate does and does not own
//!
//! It owns the *expression*: two mitred polylines for a bevel and a `Frame`
//! for a filled region. It owns no colours and no sizes, and no longer owns a
//! substitution: it briefly supplied the page for a well, which was a stand-in
//! for `surface-well` before makeover derived it, and every consumer reads the
//! real token now. [`Palette`] is supplied by the caller,
//! already resolved, and every radius, margin and stroke width arrives in
//! [`FrameStyle`].
//!
//! That split is why the crate has no dependency on `makeover` itself: the app
//! already resolves a theme, and coupling a renderer to a colour crate's
//! version would buy nothing.
//!
//! # The cascade is the real difference
//!
//! A stylesheet can say "a pressed button inverts its bevel" once and let the
//! cascade carry it. An immediate-mode renderer has nowhere to put that, so
//! every call site decides. [`makeover_layout::Depth::pressed`] is what keeps
//! the decision from being re-derived per widget.
//!
//! # 0.11.0: the overlay becomes reachable
//!
//! 0.10.0 answered what overlaying means in immediate mode with
//! [`Palette::cast`], and nothing could ask: the description had no
//! `Depth::Overlay` until `makeover-layout` 0.14.0, so the answer sat beside a
//! question that could not be posed. [`frame`] now hands the cast shadow to the
//! `egui::Frame` for any depth whose fill is [`Fill::Overlay`], keyed off the
//! fill rather than the variant.
//!
//! The same release brings `makeover_layout::CellPart`, which 0.11.0 carried
//! and did not draw. [`table`] draws it, below.
//!
//! # 0.12.0: the table
//!
//! [`table`] is the vocabulary 0.11.0 took without using. The consumer is
//! audiofiles, whose file list is the only table in the tree exercising all four
//! of what the description says about one at once: sortable headings with
//! carets, fixed and remainder tracks, and buttons inside cells.
//!
//! Two things it forces, both named where they land:
//!
//! - **`egui_extras`**, this crate's first dependency past egui. egui has no
//!   table, and `Grid` gives no per-column sizing, no sticky header and no
//!   scroll sync, which is why audiofiles reached for `egui_extras` rather than
//!   building on `Grid`. A third answer here would reimplement that crate worse.
//! - **[`Palette::action`]**, on the footing [`Palette::content`] arrived on: a
//!   link in a cell is the first thing here needing the action intent.
//!
//! Narrowing works differently from the terminal's and the module header says
//! why: a content column cannot be measured before the app's closure has drawn
//! it, so `egui_extras` sizes it and the declared floor budgets it.
//!
//! # 0.13.0: what the adoption found missing
//!
//! 0.12.0 shipped [`table`] before audiofiles had taken it, and taking it found
//! three things the file list already did that the function could not say. All
//! three are host idiom rather than description, which is why they land here and
//! not in `makeover-layout`, and all three are answered on a handle the app
//! never sees: the `egui_extras` row and builder this crate owns. That is
//! [`table::cell`]'s reasoning again: what the app cannot reach, the renderer
//! owes it.
//!
//! - **A selected row.** [`table::Body::selected`], a predicate asked per row,
//!   because `set_selected` is a method on the row. Without it a file list has
//!   no way to show what is selected, which is most of what a file list does.
//! - **Scrolling a row into view.** [`table::Body::scroll_to`], because
//!   `scroll_to_row` is a method on the builder. A keyboard cursor that moves
//!   off-screen and stays there is the bug this prevents.
//! - **Dragging a divider.** [`table::TableStyle::resizable`], which passes the
//!   test `sticky_header` failed in 0.12.0: egui_extras offers two settings here
//!   and a renderer can honestly make either choice.
//!
//! A fourth was found and is not a knob. Cells are centred on the row's centre
//! line, always, because there is no second honest answer and egui's own default
//! (top-aligned) is the one thing it cannot be.
//!
//! [`table::Body`] is also what splits a table's per-frame facts from its
//! description and from its style. A row count, a selection and a scroll request
//! are none of them style, and none of them survive the frame.
//!
//! # 0.18.0: the nodes that were not fields, tables or frames
//!
//! [`widget`] draws a meter, a token, a control and a figure. `makeover-tui` has
//! had all four for releases and this crate had none of them, which stayed
//! invisible while the only consumer was an app calling [`field`] and [`table`]
//! directly. It stopped being invisible the moment anything tried to draw a
//! whole `quasi_router::Screen` in egui: the four are ordinary nodes, so a
//! screen walk would have had to draw them itself, one copy per consumer.
//!
//! [`Palette`] grows the three status intents with it. They arrive together
//! rather than one per widget for the reason [`Palette::fill`] is an `Option`:
//! `Tone` is five members wide, and a resolver missing one has to invent a
//! colour, which is the substitution 0.2.0 spent a release removing.
//!
//! # Forms
//!
//! 0.5.0 adds the field vocabulary on top of the depth vocabulary:
//! [`makeover_layout::Field`] rendered to egui widgets, in [`field`], and a set
//! of them laid down a column in [`group`]. Before it, a description saying
//! "text field, labelled, required, with this hint" had no way to become a
//! widget here, and audiofiles' forms stayed hand-rolled.
//!
//! `makeover-webview` got there first and its form emitter is the precedent
//! followed rather than re-derived, including the parts that are bug fixes: a
//! select handed a value none of its options carries keeps that value visible
//! instead of silently reading as the first option, which is a save-the-wrong-
//! thing bug goingson hit for real.
//!
//! What differs is forced by the mode and not chosen:
//!
//! - **The value arrives as a `&mut`.** [`Filling`] borrows the app's own field
//!   and the widget writes through it. There is no DOM to read back out of,
//!   which is also why the description deliberately does not carry the value.
//! - **A text control is drawn as a well and a select is not.** The description
//!   holds that a well is for anything the user looks *into*, and a text field
//!   is its own example; a select and a checkbox are pressed rather than looked
//!   into, so they keep egui's own control painting.
//! - **Focus is not describable, and egui owns all of it here.** **Reach**,
//!   **focus** and the **focus ring** are this renderer's three answers and
//!   egui already has all three: its own id stack decides what is reachable,
//!   its own state decides what holds the keyboard, and it paints exactly one
//!   ring. A description states none of them — `makeover_layout` removed the
//!   member that used to try in 0.19.0 — and drawing a second ring on top of
//!   egui's would break the one-ring rule it would have come from. The terms
//!   are defined once in `makeover_layout`'s crate header, "Reach, focus and
//!   the focus ring". [`makeover_layout::State::Disabled`] *is* drawn, because
//!   egui has no opinion about it until told.
//! - **App-level chrome is not drawn here, and it is not this crate's to
//!   draw.** `quasi-router` names the affordances that outlive one screen: a
//!   `Chrome` of key bindings, and an `Outcome::Over` for a screen drawn over
//!   another. Both are answered by `quasi-webview` and `quasi-tui`, and neither
//!   is answerable here, because this crate depends on `makeover-layout` and
//!   not on `quasi-router` — it is the peer of `makeover-webview` and
//!   `makeover-tui`, one layer below the renderers that consume a `Screen`.
//!   What is missing is the egui crate at *that* layer, which does not exist:
//!   nothing renders a quasi `Screen` in egui at all, and chrome is one item on
//!   the list such a crate would owe. Said here because this is where a reader
//!   looks for it, and because the silent version reads as "egui does not need
//!   a palette" rather than "nobody has built the renderer yet".

#![forbid(unsafe_code)]

use egui::{
    Color32, ComboBox, CornerRadius, Margin, Painter, Rect, Response, RichText, Shape, Stroke,
    TextEdit, Ui,
};
use makeover_layout::{Bevel, Choice, Depth, Edge, Field, FieldKind, Fill, State, Tone};

/// Columns, narrowing, cell parts and the sort caret, over `egui_extras`.
pub mod table;
pub mod widget;

/// The resolved colours this renderer needs, as flat values.
///
/// Built by the app from whatever it already uses to resolve a theme, then
/// held and reused. Deliberately not a trait and not string-keyed: a bevel is
/// painted per widget per frame, and a map lookup per edge is a cost with
/// nothing to show for it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Palette {
    /// `surface-page`.
    pub page: Color32,
    /// `surface-raised`.
    pub raised: Color32,
    /// `surface-overlay`.
    pub overlay: Color32,
    /// `surface-well`.
    ///
    /// Required, not optional. makeover derives it for every theme from 2.3.0,
    /// so a resolved palette without a well is not a thing that exists here.
    /// It was an `Option` while that was untrue, and this renderer substituted
    /// the page; `makeover-tui` keeps its own `Option` for a different reason,
    /// since a terminal can have the colour and still be unable to show it.
    pub well: Color32,
    /// `surface-sunken`.
    ///
    /// A surface set back from the one it sits on, by colour and nothing else.
    /// Not a well: a well is a hole with an edge, and this has no edge. An
    /// immediate-mode renderer paints an arbitrary rect, so unlike
    /// `makeover-tui` it has no excuse for declining this one.
    ///
    /// Required rather than optional, on the same footing as `well`: all 31
    /// themes makeover embeds author it.
    pub sunken: Color32,
    /// `bevel-light`.
    pub bevel_light: Color32,
    /// `bevel-dark`.
    pub bevel_dark: Color32,
    /// `elevation`.
    ///
    /// What a surface that floats OVER the page is cast onto it with. The one
    /// intent here that is about a surface's relationship to the page rather
    /// than about the surface, which is why it is a translucent near-black on
    /// every theme rather than something read off the palette's own ramp.
    ///
    /// **Only for a surface that overlays.** A menu, a tooltip, a modal. A
    /// surface *in* the layout takes a bevel, and reaching for this on a panel
    /// or a card is how a pre-Platinum look survives a conversion under a new
    /// name.
    ///
    /// egui has a real answer for this where a terminal does not: see
    /// [`Palette::cast`], which is the shadow to hand an
    /// [`egui::Frame`](egui::Frame).
    pub elevation: Color32,
    /// `content`.
    ///
    /// Ordinary text. Added 0.5.0 with the field renderer, which is the first
    /// thing here that draws any: until then this crate painted surfaces and
    /// edges and let the caller's own egui visuals answer for text.
    pub content: Color32,
    /// `content-secondary`.
    ///
    /// Inactive but usable: it still answers a press. The middle tone of the
    /// three (wiki `three-tone-convention`), and the one an unchosen option in
    /// a choice field takes. Added 0.26.0 for that widget, which drew every
    /// option at full `content` and so said nothing about which one was
    /// chosen beyond the dot egui paints.
    ///
    /// Not [`content_muted`](Self::content_muted), which carries a claim:
    /// `State::Disabled` resolves to it, so a live control wearing it tells the
    /// user it will not answer. `makeover-tui` draws the same widget the same
    /// way from `makeover-tui@230bf63`.
    ///
    /// A step of `content` toward the page, derived at load by `makeover`
    /// rather than authored, so it is read off the resolved theme here like
    /// any other token and never re-derived.
    pub content_secondary: Color32,
    /// `content-muted`.
    ///
    /// A field's hint, and what
    /// [`makeover_layout::State::Disabled`](makeover_layout::State::Disabled)
    /// resolves to. Both readings come from the description rather than from
    /// here: `State::Disabled` names this intent by token.
    pub content_muted: Color32,
    /// `action-primary`.
    ///
    /// What a control is drawn in. Added 0.12.0 with the table renderer, for the
    /// reason `content` was added 0.5.0 with the field renderer: a link in a
    /// cell is the first thing here that needs the action intent, and a palette
    /// should carry what is used.
    ///
    /// This is the intent [`CellPart`](makeover_layout::CellPart) exists to
    /// separate. A cell holding a control took the cell's text colour until the
    /// description could say otherwise, which is the drift `makeover-layout`
    /// 0.14.0 named and `makeover-webview` 0.25.0 fixed on its own side.
    pub action: Color32,
    /// `danger`.
    ///
    /// A field's error message, a destructive control, a bar that has run over.
    pub danger: Color32,
    /// `success`.
    ///
    /// Added 0.18.0 with [`widget`], which is the first thing here that draws a
    /// [`Tone`]. The three status intents arrive together and not one at a
    /// time: [`Tone`] is five members wide and a resolver missing one has to
    /// invent a colour for it, which is the substitution this crate spent
    /// 0.2.0 removing from [`Palette::fill`].
    pub success: Color32,
    /// `warning`.
    pub warning: Color32,
    /// `info`.
    pub info: Color32,
}

impl Palette {
    /// Resolve a surface intent, or `None` for one this renderer does not know.
    ///
    /// A plain lookup. There is still no substitution: the old one existed only
    /// while `surface-well` was underived, and every consumer reads the real
    /// token now.
    ///
    /// `Option` since 0.3.0, because [`Fill`] became `#[non_exhaustive]` in
    /// `makeover-layout` 0.4.0 and a total function over an open enum can only
    /// stay total by inventing a colour for a member it has never heard of.
    /// That is the substitution this crate spent 0.2.0 removing, so the return
    /// type moved instead. Every member the description has today is answered
    /// with `Some`.
    #[must_use]
    pub const fn fill(&self, fill: Fill) -> Option<Color32> {
        match fill {
            Fill::Page => Some(self.page),
            Fill::Raised => Some(self.raised),
            Fill::Overlay => Some(self.overlay),
            Fill::Well => Some(self.well),
            Fill::Sunken => Some(self.sunken),
            _ => None,
        }
    }

    /// The colour a [`Tone`] reads as.
    ///
    /// Total, unlike [`fill`](Self::fill), and the difference is not an
    /// inconsistency. `Fill` is `#[non_exhaustive]` and `Tone` is not: the
    /// description layer settled tone at five members and grows surfaces, so a
    /// total function here cannot be made to invent a colour by an upstream
    /// release the way a total `fill` could.
    ///
    /// [`Tone::Neutral`] is [`content`](Self::content) rather than a colour of
    /// its own, which is what "an ordinary fact" means: a neutral badge is text
    /// in a box, not a fifth status.
    #[must_use]
    pub const fn tone(&self, tone: Tone) -> Color32 {
        match tone {
            Tone::Neutral => self.content,
            Tone::Info => self.info,
            Tone::Success => self.success,
            Tone::Warning => self.warning,
            Tone::Danger => self.danger,
        }
    }

    /// The cast shadow for a surface that overlays the page.
    ///
    /// What "overlaying" means in immediate mode, answered rather than skipped.
    /// egui already paints shadows for its menus and windows through
    /// [`egui::Frame::shadow`], so the honest port is to hand that machinery the
    /// theme's tone instead of egui's own default, not to invent a painter here
    /// the way [`paint_bevel`] had to.
    ///
    /// The geometry matches what `makeover-webview` composes, in points rather
    /// than pixels: a small downward offset and a wide soft blur. A Platinum-era
    /// menu sits just off the page rather than hovering above it.
    ///
    /// ```no_run
    /// # let palette: makeover_immediate::Palette = unimplemented!();
    /// # let ui: &mut egui::Ui = unimplemented!();
    /// egui::Frame::popup(ui.style())
    ///     .shadow(palette.cast())
    ///     .show(ui, |ui| { ui.label("over the page"); });
    /// ```
    #[must_use]
    pub const fn cast(&self) -> egui::Shadow {
        egui::Shadow {
            offset: [0, 2],
            blur: 24,
            spread: 0,
            color: self.elevation,
        }
    }

    /// Resolve a bevel edge intent.
    #[must_use]
    pub const fn edge(&self, edge: Edge) -> Color32 {
        match edge {
            Edge::Light => self.bevel_light,
            Edge::Dark => self.bevel_dark,
        }
    }
}

/// The geometry a framed region is drawn with.
///
/// Every field is a value, which is why they all arrive from the caller:
/// radius and border width belong to `makeover-geometry`, and margins come
/// from its relational gaps.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FrameStyle {
    /// Corner radius. Square under the Platinum default.
    pub radius: CornerRadius,
    /// Inner margin between the frame and its contents.
    pub margin: Margin,
    /// Bevel stroke width, in points.
    pub stroke: f32,
}

impl Default for FrameStyle {
    /// A one-point square frame with no inner margin.
    fn default() -> Self {
        Self {
            radius: CornerRadius::ZERO,
            margin: Margin::ZERO,
            stroke: 1.0,
        }
    }
}

/// Paint a two-tone edge just inside `rect`.
///
/// Fill first, bevel after: this adds two polylines and nothing else, so it
/// composes over whatever is already there. That is what lets it go over an
/// [`egui::TextEdit`] after `ui.add`, where the widget's own fill has landed.
///
/// Two three-point polylines meeting at opposite corners, rather than four
/// segments, so egui mitres the corner joins instead of leaving a notch.
///
/// The dark polyline is drawn second, so the two corners where the runs meet
/// take its tone. That is the right answer here rather than a concession.
/// [`makeover_layout::Bevel`] holds those corners to belong to both edges, and
/// a renderer with room to divide one should; at the default one-point stroke
/// the corner is a one-point square, so the division is sub-pixel and
/// antialiasing resolves it to the same blend the mitre already gives. Splitting
/// it would add a seam and no information. `makeover-tui` does split, because a
/// terminal cell is large enough that not splitting costs a visible cell of edge
/// weight — the same rule, at a resolution where it has something to say.
pub fn paint_bevel(painter: &Painter, rect: Rect, bevel: Bevel, palette: &Palette, stroke: f32) {
    let (top_left, bottom_right) = bevel.edges();

    // Inset by half a stroke so the line lands inside `rect` rather than
    // straddling its edge, which on a fractional-scale display is the
    // difference between one crisp pixel and two dim ones.
    let r = rect.shrink(stroke / 2.0);

    painter.add(Shape::line(
        vec![r.left_bottom(), r.left_top(), r.right_top()],
        Stroke::new(stroke, palette.edge(top_left)),
    ));
    painter.add(Shape::line(
        vec![r.right_top(), r.right_bottom(), r.left_bottom()],
        Stroke::new(stroke, palette.edge(bottom_right)),
    ));
}

/// Draw a region at a given [`Depth`]: its fill and its edge, together.
///
/// [`Depth::Flat`] gets neither, and inherits whatever it sits on. That is the
/// difference between level-with and painted-the-same-colour, and it is the
/// reason `Depth::fill` returns an [`Option`] rather than defaulting to the
/// page.
pub fn frame<R>(
    ui: &mut Ui,
    depth: Depth,
    palette: &Palette,
    style: FrameStyle,
    add_contents: impl FnOnce(&mut Ui) -> R,
) -> R {
    let mut f = egui::Frame::new()
        .corner_radius(style.radius)
        .inner_margin(style.margin);
    // Two ways there is no fill to paint, and they collapse to the same
    // outcome: the depth names none (Depth::Flat), or it names one this
    // renderer cannot resolve. Either way the frame goes unfilled and the
    // bevel below carries the depth on its own, which is the rule this
    // module already documents for Flat.
    if let Some(fill) = depth.fill().and_then(|f| palette.fill(f)) {
        f = f.fill(fill);
    }
    // A surface that overlays the page is cast onto it. [`Palette::cast`] has
    // answered what that means here since 0.10.0 and nothing could reach it: a
    // description had no way to say Overlay until makeover-layout 0.14.0, so
    // the answer sat beside the question. Keyed off the fill rather than the
    // variant, so it stays right for whatever else the description calls an
    // overlay later.
    if depth.fill() == Some(Fill::Overlay) {
        f = f.shadow(palette.cast());
    }
    let framed = f.show(ui, add_contents);
    if let Some(bevel) = depth.bevel() {
        paint_bevel(
            ui.painter(),
            framed.response.rect,
            bevel,
            palette,
            style.stroke,
        );
    }
    framed.inner
}

/// The geometry a field group is drawn with.
///
/// Values again, for the reason [`FrameStyle`] is: every number here belongs to
/// `makeover-geometry` and arrives already resolved.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FieldStyle {
    /// The well a text control sits in.
    pub frame: FrameStyle,
    /// Between a field's own parts: its label, its control, its hint and its
    /// error.
    pub gap: f32,
    /// Between one field and the next.
    pub group_gap: f32,
    /// What marks a required field, appended to its label.
    ///
    /// A knob rather than a constant, because it is the one piece of *copy* in
    /// this crate and copy is not a renderer's call. A webview does not need it
    /// at all — it emits the `required` attribute and the browser answers — so
    /// this renderer is the first place where a compulsory field either shows
    /// that it is or silently does not.
    pub required_marker: &'static str,
}

impl Default for FieldStyle {
    /// The default frame, no gaps, and an asterisk.
    fn default() -> Self {
        Self {
            frame: FrameStyle::default(),
            gap: 0.0,
            group_gap: 0.0,
            required_marker: "*",
        }
    }
}

/// What the field currently holds, borrowed from wherever the app keeps it.
///
/// The immediate-mode counterpart of `makeover_webview::form::Value`, and the
/// place the two renderers are forced apart: there the value is read back out
/// of the DOM after the fact, and here the widget writes through this borrow as
/// it is edited. Same reason the description carries neither.
///
/// An enum rather than a bag of options, on the reasoning
/// `makeover_webview::form::Value` records: a checkbox holding a string is
/// unsayable here, where a struct would let it be said and then have to cope.
#[derive(Debug, Default)]
pub enum Filling<'a> {
    /// Nothing to edit. The control is drawn and does not answer.
    #[default]
    Absent,
    /// The buffer behind anything that takes typed text, a select included:
    /// what a select holds is the `value` of one of its [`Choice`]s.
    ///
    /// [`Choice`]: makeover_layout::Choice
    Text(&'a mut String),
    /// A checkbox, on or off.
    On(&'a mut bool),
}

/// The label, marked if the field is compulsory.
fn label_text(field: &Field<'_>, style: &FieldStyle) -> String {
    if field.required {
        format!("{} {}", field.label, style.required_marker)
    } else {
        field.label.to_owned()
    }
}

/// The four shapes a control comes in here, which is fewer than there are
/// kinds.
///
/// [`FieldKind`] is `#[non_exhaustive]` and grows; this does not, because the
/// ways egui has of asking for a value do not. Reducing the open set to this
/// closed one in one total function is what keeps a new kind from needing a new
/// arm at every match below.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Control {
    /// Typed into, so it is drawn as a well: the user looks into it.
    Typed,
    /// Picked from a control that shows one option at a time. Pressed rather
    /// than looked into, so egui's own control painting stands.
    Chosen,
    /// Picked from options that are all on screen at once.
    ///
    /// Apart from [`Chosen`](Self::Chosen) because the description holds them
    /// apart, and holding them apart is the whole content of
    /// [`FieldKind::Radio`]: same question, and an answer the user can read
    /// without opening anything.
    Listed,
    /// Held on or off.
    Toggled,
}

/// Which shape a kind takes.
///
/// The wildcard falls to [`Control::Typed`] on purpose: a kind added to the
/// description since this renderer was built degrades to a text box, which
/// accepts any value the others would, rather than to nothing drawn at all.
///
/// `FieldKind::File` lands there as of makeover-layout 0.11.0, and it is left
/// there rather than grown a shape of its own. egui's honest answer is a button
/// that opens a native picker, which is a fifth control and a file-dialog
/// dependency; no consumer of this crate asks for a file field yet. Same
/// position this crate took on `Meter` at 0.10.0: the membership test is that
/// every renderer *could* answer honestly, not that each one does on the day.
/// A path in a text box is not nothing, and it is what an app that needs this
/// tomorrow gets today.
///
/// `FieldKind::Date` and `FieldKind::DateTime` land there too, as of
/// makeover-layout 0.15.0, on the same footing and with one thing owed. A
/// calendar is a sixth control and bare `egui` has none, so a typed value is
/// the honest answer here; what the app gets is the format the description
/// names, `makeover_layout::DATE_FORMAT` and `DATETIME_FORMAT`, which is why
/// those are constants rather than a sentence. audiofiles is the only consumer
/// of this crate and asks for neither today. A calendar popup is the upgrade
/// whenever one does.
const fn control_shape(kind: FieldKind) -> Control {
    match kind {
        FieldKind::Select => Control::Chosen,
        FieldKind::Radio => Control::Listed,
        FieldKind::Checkbox => Control::Toggled,
        _ => Control::Typed,
    }
}

/// What a select shows for the value it currently holds.
///
/// A value no option carries stays on screen as itself rather than reading as
/// whichever option happens to be first. goingson saved a backup retention of
/// 10 against a 1/3/7/14/0 list and the browser silently showed it as 1, so the
/// next save wrote a value nobody chose; `makeover-webview` grew the fix as a
/// stray `<option>` and this is the same fix in the shape egui allows.
fn shown_label<'a>(options: &'a [Choice<'a>], value: &'a str) -> &'a str {
    options
        .iter()
        .find(|opt| opt.value == value)
        .map_or(value, |opt| opt.label)
}

/// What one option in a choice field is drawn in.
///
/// The chosen one is the emphasised thing and takes `content`; the rest take
/// [`content_secondary`](Palette::content_secondary), because an option that is
/// not chosen is still an option and pressing it chooses it. Muted would be the
/// lie: [`State::Disabled`] resolves to it, so a five-option field read as one
/// live row and four dead ones. `makeover-tui` draws it the same way
/// (`makeover-tui@230bf63`); wiki `three-tone-convention` is the table.
fn option_color(value: &str, option: &str, palette: &Palette) -> Color32 {
    if value == option {
        palette.content
    } else {
        palette.content_secondary
    }
}

/// The control alone, without its label, hint or error.
fn control(
    ui: &mut Ui,
    field: &Field<'_>,
    filling: Filling<'_>,
    palette: &Palette,
    style: &FieldStyle,
) -> Response {
    // The mismatch path: described as one thing and filled as another. Nothing
    // here can fix it, so it is drawn as the empty, inert version of what was
    // described — visible on screen, in the way an empty select is at the
    // webview renderer, rather than reported in a log nobody reads.
    let mut discard = String::new();
    let mut off = false;

    match control_shape(field.kind) {
        Control::Typed => {
            let text = match filling {
                Filling::Text(text) => text,
                _ => &mut discard,
            };
            // An empty frame and no margin: the well is this crate's, and egui's
            // own control background and padding would sit underneath it saying
            // something different about both.
            let mut edit = if matches!(field.kind, FieldKind::Textarea) {
                TextEdit::multiline(text)
            } else {
                TextEdit::singleline(text)
            }
            .frame(egui::Frame::NONE)
            .margin(Margin::ZERO)
            .text_color(palette.content)
            .password(field.kind.confidential());
            if let Some(ghost) = field.placeholder {
                edit = edit.hint_text(RichText::new(ghost).color(palette.content_muted));
            }
            frame(ui, Depth::Well, palette, style.frame, |ui| ui.add(edit))
        }
        Control::Toggled => {
            let on = match filling {
                Filling::On(on) => on,
                _ => &mut off,
            };
            ui.checkbox(on, RichText::new(field.label).color(palette.content))
        }
        Control::Listed => {
            let value = match filling {
                Filling::Text(text) => text,
                _ => &mut discard,
            };
            // No `shown_label` counterpart, and none is needed: a value no
            // option carries leaves every button unfilled, which is already
            // the honest report on screen. The select needs the fix because it
            // has one slot and must put *something* in it.
            let group = ui.vertical(|ui| {
                let mut answered: Option<Response> = None;
                for opt in field.options {
                    let picked = ui.radio_value(
                        value,
                        opt.value.to_owned(),
                        RichText::new(opt.label).color(option_color(value, opt.value, palette)),
                    );
                    answered = Some(match answered {
                        Some(prev) => prev.union(picked),
                        None => picked,
                    });
                }
                answered
            });
            // A group described with no options answers as its own empty area
            // rather than as no response at all, which keeps the caller's
            // `.changed()` chain working on a field whose option list has not
            // loaded yet.
            group.inner.unwrap_or(group.response)
        }
        Control::Chosen => {
            let value = match filling {
                Filling::Text(text) => text,
                _ => &mut discard,
            };
            let shown = shown_label(field.options, value);
            ComboBox::from_id_salt(field.name)
                .selected_text(RichText::new(shown).color(palette.content))
                .show_ui(ui, |ui| {
                    for opt in field.options {
                        ui.selectable_value(
                            value,
                            opt.value.to_owned(),
                            RichText::new(opt.label).color(option_color(value, opt.value, palette)),
                        );
                    }
                })
                .response
        }
    }
}

/// One field, as the column the app drops into its form.
///
/// The anatomy is `makeover-webview`'s, so the two renderers put a form
/// together the same way: label, control, hint, error, top to bottom, with a
/// checkbox labelling itself instead of taking a label above.
///
/// Returns [`None`] for a [`FieldKind::Hidden`] field, which is what
/// [`FieldKind::visible`] means and is the honest answer here: a webview still
/// emits an input for it because the form submits, and an immediate-mode
/// renderer has no form and no submission, so a hidden field is a value the app
/// already holds and there is nothing to draw or to respond to.
///
/// `state` is the description's interaction axis.
/// [`State::Disabled`] greys the field and stops it answering, through
/// [`State::suppresses_interaction`] rather than through a second reading of
/// what disabled means. Focus is not on that axis and never reaches here: egui
/// owns reach, focus and the ring for this renderer, and one ring means not a
/// second one per renderer that happens to have opinions.
pub fn field(
    ui: &mut Ui,
    field: &Field<'_>,
    filling: Filling<'_>,
    state: Option<State>,
    palette: &Palette,
    style: &FieldStyle,
) -> Option<Response> {
    if !field.kind.visible() {
        return None;
    }
    let enabled = !state.is_some_and(State::suppresses_interaction);
    let text = if enabled {
        palette.content
    } else {
        palette.content_muted
    };

    let response = ui
        .vertical(|ui| {
            ui.spacing_mut().item_spacing.y = style.gap;

            // A checkbox labels itself, on the right of the box.
            // `FieldKind::labels_itself` is the description saying so, and both
            // webview apps special-cased it inline before it did.
            if !field.kind.labels_itself() {
                ui.label(RichText::new(label_text(field, style)).color(text));
            }

            let response = ui
                .add_enabled_ui(enabled, |ui| control(ui, field, filling, palette, style))
                .inner;

            // Standing help first, then what is wrong now. Both, in that order,
            // for the reason the webview renderer names both in
            // `aria-describedby`: an error appearing must not take the hint
            // away with it.
            if let Some(hint) = field.hint {
                ui.label(RichText::new(hint).color(palette.content_muted));
            }
            if let Some(error) = field.error {
                ui.label(RichText::new(error).color(palette.danger));
            }
            response
        })
        .inner;

    Some(response)
}

/// A set of fields, laid down a column.
///
/// `show_extended` is the disclosure, and it is a parameter rather than state
/// held here because the disclosure belongs to the *form* and not to any field:
/// [`Field::extended`] marks which fields are behind one, and the app owns
/// whether it is open. That is the same division `makeover-webview` draws when
/// it marks the group `data-extended` and emits no control to toggle it.
///
/// `draw` is called once per field that should be visible, in order. Taking a
/// callback rather than a slice of [`Filling`]s is what keeps the app's own
/// values borrowed one at a time: a form's fields usually live in different
/// structs, and a parallel array would have to be built each frame and kept in
/// step with the description by hand.
pub fn group<'a>(
    ui: &mut Ui,
    fields: &'a [Field<'a>],
    show_extended: bool,
    style: &FieldStyle,
    mut draw: impl FnMut(&mut Ui, &'a Field<'a>),
) {
    ui.vertical(|ui| {
        ui.spacing_mut().item_spacing.y = style.group_gap;
        for f in fields {
            if f.extended && !show_extended {
                continue;
            }
            draw(ui, f);
        }
    });
}

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

    fn palette(well: Color32) -> Palette {
        Palette {
            page: Color32::from_rgb(1, 1, 1),
            raised: Color32::from_rgb(2, 2, 2),
            overlay: Color32::from_rgb(3, 3, 3),
            well,
            sunken: Color32::from_rgb(4, 4, 4),
            bevel_light: Color32::WHITE,
            bevel_dark: Color32::BLACK,
            elevation: Color32::from_black_alpha(46),
            content: Color32::from_rgb(5, 5, 5),
            content_secondary: Color32::from_rgb(55, 55, 55),
            content_muted: Color32::from_rgb(6, 6, 6),
            action: Color32::from_rgb(7, 7, 7),
            danger: Color32::from_rgb(8, 8, 8),
            success: Color32::from_rgb(9, 9, 9),
            warning: Color32::from_rgb(10, 10, 10),
            info: Color32::from_rgb(11, 11, 11),
        }
    }

    /// The cast is egui's own shadow type carrying the theme's tone, which is
    /// the whole of what this crate had to decide for it: unlike a bevel, egui
    /// already knows how to paint one.
    #[test]
    fn the_cast_hands_egui_the_themes_tone() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        let cast = p.cast();
        assert_eq!(cast.color, p.elevation);
        assert!(cast.blur > 0, "a cast shadow is soft");
        assert_eq!(cast.offset, [0, 2], "it falls downward and only a little");
    }

    #[test]
    fn a_well_resolves_to_its_own_token() {
        // No substitution left. The page-filled well was a stand-in for a
        // token that did not exist yet; it exists now.
        let w = Color32::from_rgb(9, 9, 9);
        let p = palette(w);
        assert_eq!(p.fill(Fill::Well), Some(w));
        assert_ne!(p.fill(Fill::Well), Some(p.page));
    }

    #[test]
    fn every_intent_is_a_plain_lookup() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        assert_eq!(p.fill(Fill::Page), Some(p.page));
        assert_eq!(p.fill(Fill::Raised), Some(p.raised));
        assert_eq!(p.fill(Fill::Overlay), Some(p.overlay));
    }

    /// Sunken is its own colour, not the well's and not the page's. The two
    /// are authored in opposite directions and an earlier cut of the
    /// description conflated them.
    #[test]
    fn sunken_is_neither_the_well_nor_the_page() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        assert_eq!(p.fill(Fill::Sunken), Some(p.sunken));
        assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Well));
        assert_ne!(p.fill(Fill::Sunken), p.fill(Fill::Page));
    }

    #[test]
    fn a_raised_region_never_resolves_to_the_well_fill() {
        // The cross-app bug, asserted at the renderer boundary this time.
        let p = palette(Color32::from_rgb(9, 9, 9));
        let raised = Depth::Raised.fill().and_then(|f| p.fill(f));
        let well = Depth::Well.fill().and_then(|f| p.fill(f));
        assert_eq!(raised, Some(p.raised));
        assert_ne!(raised, well);
    }

    #[test]
    fn an_overlay_is_cast_onto_the_page_and_takes_no_edge() {
        // makeover-layout 0.14.0 is what made this reachable. The answer was
        // already here at 0.10.0 and the question could not be asked.
        let p = palette(Color32::from_rgb(9, 9, 9));
        assert_eq!(
            Depth::Overlay.fill().and_then(|f| p.fill(f)),
            Some(p.overlay)
        );
        assert_eq!(Depth::Overlay.bevel(), None);
        // The shadow `frame` reaches for is the theme's tone rather than
        // egui's default, which is the whole reason `cast` exists.
        assert_eq!(p.cast().color, p.elevation);
    }

    #[test]
    fn the_lit_edge_swaps_when_a_card_is_pressed() {
        let p = palette(Color32::from_rgb(9, 9, 9));
        let (tl, _) = Depth::Raised.bevel().unwrap().edges();
        let (ptl, _) = Depth::Raised.pressed().bevel().unwrap().edges();
        assert_eq!(p.edge(tl), p.bevel_light);
        assert_eq!(p.edge(ptl), p.bevel_dark);
    }

    #[test]
    fn flat_asks_for_neither_fill_nor_edge() {
        assert!(Depth::Flat.fill().is_none());
        assert!(Depth::Flat.bevel().is_none());
    }

    #[test]
    fn a_select_keeps_a_value_none_of_its_options_carries() {
        // The save-the-wrong-thing bug, asserted at the second renderer so it
        // is not re-found there. goingson's own numbers.
        let options = [
            Choice::plain("1"),
            Choice::plain("3"),
            Choice::plain("7"),
            Choice::plain("14"),
        ];
        assert_eq!(shown_label(&options, "10"), "10");
        // And a value that does match reads as its label, not as itself.
        let spelled = [Choice {
            value: "7",
            label: "One week",
        }];
        assert_eq!(shown_label(&spelled, "7"), "One week");
    }

    #[test]
    fn only_a_required_field_is_marked() {
        let style = FieldStyle::default();
        let plain = Field::new(FieldKind::Text, "title", "Title");
        assert_eq!(label_text(&plain, &style), "Title");

        let required = Field {
            required: true,
            ..plain
        };
        assert_eq!(label_text(&required, &style), "Title *");

        // The marker is copy and the app owns it, which is why it is a knob.
        let house = FieldStyle {
            required_marker: "(required)",
            ..style
        };
        assert_eq!(label_text(&required, &house), "Title (required)");
    }

    #[test]
    fn a_select_and_a_checkbox_are_pressed_and_everything_else_is_typed_into() {
        // What decides whether the control gets a well. A well is for what the
        // user looks into, and only one of these is.
        assert_eq!(control_shape(FieldKind::Select), Control::Chosen);
        assert_eq!(control_shape(FieldKind::Radio), Control::Listed);
        assert_eq!(control_shape(FieldKind::Checkbox), Control::Toggled);
        for k in [
            FieldKind::Text,
            FieldKind::Secret,
            FieldKind::Number,
            FieldKind::Email,
            FieldKind::Url,
            FieldKind::Tel,
            FieldKind::Textarea,
        ] {
            assert_eq!(control_shape(k), Control::Typed, "{k:?} is typed into");
        }
    }

    #[test]
    fn the_two_option_taking_kinds_are_drawn_differently_on_purpose() {
        // The description holds Select and Radio apart, and a renderer that
        // collapsed them would silently answer a question the app did not ask:
        // audiofiles' storage style is irreversible and its alternatives have
        // to be readable without opening anything. Asserting the two shapes
        // differ is asserting that distinction survives the trip.
        assert!(FieldKind::Select.offers_options());
        assert!(FieldKind::Radio.offers_options());
        assert_ne!(
            control_shape(FieldKind::Select),
            control_shape(FieldKind::Radio)
        );
    }

    #[test]
    fn an_unchosen_option_is_secondary_and_never_muted() {
        let p = palette(Color32::from_rgb(4, 4, 4));
        assert_eq!(option_color("wav", "wav", &p), p.content);
        assert_eq!(option_color("wav", "aiff", &p), p.content_secondary);
        // The whole point of the distinction: muted is what Disabled resolves
        // to, so an option wearing it would claim it does not answer a press.
        assert_ne!(option_color("wav", "aiff", &p), p.content_muted);
    }

    #[test]
    fn a_hidden_field_draws_nothing_and_answers_nothing() {
        // Where the two renderers legitimately part: a webview still emits an
        // input because the form submits, and there is no form here.
        let f = Field::new(FieldKind::Hidden, "id", "Id");
        let p = palette(Color32::from_rgb(9, 9, 9));
        egui::__run_test_ui(|ui| {
            let drawn = field(ui, &f, Filling::Absent, None, &p, &FieldStyle::default());
            assert!(drawn.is_none());
        });
    }

    #[test]
    fn a_disabled_field_stops_answering_and_an_unstated_one_does_not() {
        let f = Field::new(FieldKind::Text, "title", "Title");
        let p = palette(Color32::from_rgb(9, 9, 9));
        let style = FieldStyle::default();
        egui::__run_test_ui(|ui| {
            let mut text = String::from("x");
            let disabled = field(
                ui,
                &f,
                Filling::Text(&mut text),
                Some(State::Disabled),
                &p,
                &style,
            )
            .unwrap();
            assert!(!disabled.enabled());

            // Stating no state is the ordinary case and answers. Focus used to
            // be the counter-example here; it is egui's now and a description
            // cannot state it at all.
            let mut text = String::from("x");
            let plain = field(ui, &f, Filling::Text(&mut text), None, &p, &style).unwrap();
            assert!(plain.enabled(), "an unstated field still answers");
        });
    }

    #[test]
    fn a_field_described_one_way_and_filled_another_is_drawn_inert() {
        // No panic and no write-through. A checkbox handed a string cannot be
        // filled, so it is drawn off and left alone.
        let f = Field::new(FieldKind::Checkbox, "done", "Done");
        let p = palette(Color32::from_rgb(9, 9, 9));
        let mut text = String::from("untouched");
        egui::__run_test_ui(|ui| {
            let drawn = field(
                ui,
                &f,
                Filling::Text(&mut text),
                None,
                &p,
                &FieldStyle::default(),
            );
            assert!(drawn.is_some());
        });
        assert_eq!(text, "untouched");
    }

    #[test]
    fn the_disclosure_belongs_to_the_form_and_not_to_the_field() {
        let fields = [
            Field::new(FieldKind::Text, "title", "Title"),
            Field {
                extended: true,
                ..Field::new(FieldKind::Text, "notes", "Notes")
            },
        ];
        let style = FieldStyle::default();

        let mut closed = Vec::new();
        egui::__run_test_ui(|ui| {
            group(ui, &fields, false, &style, |_, f| closed.push(f.name));
        });
        assert_eq!(closed, ["title"]);

        let mut open = Vec::new();
        egui::__run_test_ui(|ui| {
            group(ui, &fields, true, &style, |_, f| open.push(f.name));
        });
        assert_eq!(open, ["title", "notes"]);
    }

    #[test]
    fn the_default_frame_is_square_and_one_point() {
        let d = FrameStyle::default();
        assert_eq!(d.radius, CornerRadius::ZERO);
        assert_eq!(d.margin, Margin::ZERO);
        assert!((d.stroke - 1.0).abs() < f32::EPSILON);
    }
}