teksilo_widgets/

spin_box.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! `SpinBox` — numeric input with increment/decrement buttons.
//!
//! A generic composite over [`SpinValue`]
//! (integer and floating-point primitives), pairing the
//! [`TextInputField`] editing
//! primitive with a stacked pair of up/down step buttons. Semantics
//! are a synthesis of Qt's `QSpinBox` / `QDoubleSpinBox`, WinUI 3's
//! `NumberBox`, GTK's `GtkSpinButton`, and the W3C ARIA
//! `spinbutton` role.
//!
//! # Behaviour
//!
//! - **Value binding**: a `Signal<T>` is the single source of truth.
//!   Typing and stepping update it; external writes re-format the
//!   editable text.
//! - **Commit model**: the user can type freely (subject to the
//!   per-character input filter, which only the default parser has:
//!   a custom [`value_from_text`](SpinBox::value_from_text) is handed
//!   every character). The value is *committed* on
//!   [`Enter`](teksilo_core::event::Key::Enter) or on focus loss —
//!   at commit time the text is parsed, clamped into `[min, max]`
//!   (or wrapped, per [`WrapMode`]), and reformatted. Invalid input
//!   reverts to the last known good value.
//! - **Stepping over typed text**: every step (key, wheel, button,
//!   assistive `Increment` / `Decrement`) starts from what the field
//!   shows. Text typed and not yet committed is read first, exactly as
//!   `Enter` would read it, and the step moves on from there: type 35,
//!   press `Up` with a step of 5, and the value is 40, reported once.
//!   Text that cannot be read steps nothing; the value goes back into
//!   the field, and the next press steps from it. This is
//!   `QAbstractSpinBox::stepBy`.
//! - **Keyboard**:
//!   - `Up` / `Down` → ±[`single_step`](SpinBox::single_step)
//!   - `PageUp` / `PageDown` → ±[`page_step`](SpinBox::page_step)
//!     (default: `10 × single_step`)
//!   - `Enter` → commit (stays focused)
//!   - `Home` / `End` stay bound to the text cursor. `QAbstractSpinBox`
//!     routes both to its inner `QLineEdit`, and WinUI's `NumberBox`,
//!     Blink, Avalonia and jQuery UI bind neither; typing the number
//!     reaches min and max anyway. See `docs/range-keyboard.md`.
//!   - A chord holding `Ctrl`, `Alt` or `Super` is not the spin box's
//!     and falls through to the application; `Shift` does not change
//!     the step.
//! - **Mouse wheel**: adjusts by `single_step` — wheel **down**
//!   decreases, wheel **up** increases, matching `QAbstractSpinBox`,
//!   `GtkSpinButton` and WinUI's `NumberBox`. Gated by
//!   [`wheel_mode`](SpinBox::wheel_mode) (default: only when
//!   focused, to avoid accidental scroll changes).
//! - **Buttons**: up/down buttons stack to the right of the field
//!   by default; can be hidden with
//!   [`button_layout`](SpinBox::button_layout).
//! - **Special value text**: when the current value equals `min`
//!   and [`special_value_text`](SpinBox::special_value_text) is
//!   set, the field shows that string instead of the formatted
//!   number (Qt's "Auto" / "None" / "Unlimited" affordance). It
//!   stays while the field has focus, as in Qt: keyboard focus
//!   selects it, so a number typed replaces it.
//! - **Adaptive step**: with
//!   [`StepType::Adaptive`], the effective step
//!   tracks the decimal magnitude of the current value (Qt's
//!   `AdaptiveDecimalStepType`). Useful for values that span many
//!   orders of magnitude in the same control.
//! - **Locale**: the number follows the active locale's decimal
//!   separator, digits and minus sign
//!   ([`localized`](SpinBox::localized), on by default); thousands
//!   separators are opt-in
//!   ([`use_grouping`](SpinBox::use_grouping), off by default, as in
//!   Qt). Display, commit parse, stepping and the per-character
//!   input filter all read one `NumberPresentation`, which a live
//!   language switch replaces, so they cannot disagree about which
//!   separator the field is using: a French user sees `12,5`,
//!   types `12,5`, and the numeric keypad's `.` still works.
//!   Rendering is a string transform over the value's
//!   own `Display`, never an `f64` round-trip, so a `SpinBox<i64>`
//!   stays exact past 2^53. Turn it off for a number that is an
//!   *identifier* rather than a quantity (port, version component,
//!   database id). With no `I18nManager` installed the active locale
//!   is the C locale and this is a no-op.
//! - **Custom formatter / parser**: full override via
//!   [`text_from_value`](SpinBox::text_from_value) and
//!   [`value_from_text`](SpinBox::value_from_text); together they
//!   let you implement currency, percentages with stored fraction,
//!   hex, duration, anything. A custom formatter/parser owns the
//!   whole convention — it is not re-punctuated by the locale layer.
//!
//! # Accessibility
//!
//! The editing field is the spin button: one AccessKit node with
//! [`Role::SpinButton`](teksilo_core::accesskit::Role::SpinButton),
//! the [`label`](SpinBox::label) as its name, the numeric value, min,
//! max, step and jump, the field's text as its value and its text
//! runs, and the
//! [`Increment`](teksilo_core::accesskit::Action::Increment),
//! [`Decrement`](teksilo_core::accesskit::Action::Decrement),
//! [`SetValue`](teksilo_core::accesskit::Action::SetValue), and
//! [`Focus`](teksilo_core::accesskit::Action::Focus) actions. It is
//! the node that holds focus, so a focus change reports the field's
//! name and value once, and a step moves the number a screen reader
//! is following. The composite's own node is structure and collapses;
//! it names the field as its
//! [`accessibility_proxy`](teksilo_core::widget::Widget::accessibility_proxy),
//! so an `access_label`, a `FormLayout` label, an
//! `access_described_by` or a tooltip given to the spin box lands on
//! the field. The [`suffix`](SpinBox::suffix) is painted and not part
//! of the text, so it is not announced.
//!
//! `SetValue` accepts either payload shape, because both are sent in
//! the field: a number (macOS `setAccessibilityValue:` with an
//! `NSNumber`, AT-SPI's `Value.SetCurrentValue`) is clamped and
//! published as sent; a string (an `NSString`, the automation
//! `set_value` tool) takes the same parse `Enter` takes, so a custom
//! [`value_from_text`](SpinBox::value_from_text) and the locale's
//! decimal separator are honoured, and an unparseable one reverts the
//! display and is reported unhandled. A
//! [`read_only`](SpinBox::read_only) spin box advertises and services
//! none of the three mutating actions. The step buttons are
//! structurally part of the SpinBox and publish no separate a11y
//! nodes; stepping is the spin button's `Increment` and `Decrement`.
//!
//! # Example
//!
//! ```ignore
//! use teksilo::widgets::{SpinBox, WrapMode};
//!
//! let font_size = ctx.signal(12_i32);
//! ctx.add(
//!     SpinBox::new(font_size, 4, 72)
//!         .single_step(1)
//!         .page_step(10)
//!         .suffix(" pt"),
//! );
//!
//! let gain_db = ctx.signal(0.0_f32);
//! ctx.add(
//!     SpinBox::new(gain_db, -60.0, 12.0)
//!         .single_step(0.5)
//!         .decimals(1)
//!         .suffix(" dB")
//!         .wrap_mode(WrapMode::Clamp),
//! );
//! ```
//!
//! ## Touch and pen
//!
//! The step buttons are the controls sweep's one **unreachable target**, and
//! the reason is recorded rather than papered over. Each is 18 x 13 dp inside a
//! trailing column exactly its own width and exactly two buttons tall, so a
//! `Widget::hit_outset` has nowhere to grow (an outset never escapes its
//! parent); the field beside them takes presses of its own, so the miss-only
//! slop pass has an eligible bubble owner at distance zero; and two conforming
//! targets stacked need 88 dp of column, which no density projection of the
//! field produces. Reaching the floor here is a *layout* change — the desktop
//! stacked pair replaced by a side-by-side −/+ at coarse densities, as Material
//! does — and that is a design decision, not a targeting one. The value stays
//! fully reachable by keyboard (Up/Down, PageUp/PageDown) and by the
//! `Increment` / `Decrement` assistive actions.
//!
//! One thing the sweep did fix. A step still fires on the *press* and arms
//! hold-to-repeat from it (Qt's `QAbstractSpinBox` convention — there is no
//! release to start a repeat from), but the repeat now stops on a
//! `PointerCancel`: a pan claimant winning the press used to leave the box
//! stepping for the rest of the session, because a cancel is terminal and no
//! `PointerUp` follows it.
//!
//! What the box does about panning, it does by omission. It declares no
//! [`touch_action`] and makes no pan claim, so its subtree keeps the default
//! [`TouchAction::AUTO`] and a finger that comes to rest on it and then drags
//! is won by the enclosing scroller rather than changing the value. The
//! `on_scroll` handler below is a *wheel* handler and not a pan; it never sees
//! a finger.
//!
//! Two tests in `spin_box/tests.rs` cover that, and only one of them can see
//! the second half of it. `a_finger_pan_over_the_spin_box_scrolls_its_container`
//! shows the pan reaching the scroller, but its box has the default
//! [`WheelMode::Focused`] and its fixture never focuses the field, so the
//! `on_scroll` below declines before the pan question is reached — a pan that
//! DID arrive would leave the value unchanged there anyway.
//! `a_finger_pan_over_a_hover_wheel_spin_box_scrolls_its_container` is the one
//! that can observe the claim: with [`WheelMode::Hover`] the handler runs for
//! every scroll that reaches the box, so a claim would step the value once per
//! synthesised sample.
//!
//! P22, the scrollables migration, looked at the explicit
//! `touch_action(PAN_Y)` this file was asked for and **decided against it**.
//! It is a *narrowing* on top of the behaviour above rather than a restatement
//! of it: it would additionally forbid a horizontal pan and a pinch through
//! the field — a real cost to a spin box in a horizontally-scrolling toolbar,
//! or on a pinch-zoomable page — and it would buy nothing the omission does
//! not already give, because the claimant chain visits only the pan candidates
//! and never the generic bubble, so a boundary pan cannot reach the `on_scroll`
//! below however far it travels. The omission is the decision; the
//! hover-wheel test named above is what can witness it. P24 owns
//! `spin_box/step_button.rs`.
//!
//! [`touch_action`]: teksilo_core::widget_builder::WidgetBuilder::touch_action
//! [`TouchAction::AUTO`]: teksilo_core::pointer::touch_action::TouchAction::AUTO

mod step_button;
#[cfg(test)]
mod tests;
mod value;

use std::cell::RefCell;
use std::rc::Rc;

pub use self::value::SpinValue;

use teksilo_canvas::{Path, Point, Rect, Size, SizeProposal};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::build_context::BuildContext;
use teksilo_core::event::{EventResponse, ScrollDelta, WidgetEvent};
use teksilo_core::signal::{Prop, Signal};
use teksilo_core::widget::{EventContext, LayoutContext, Widget, WidgetPlacement};
use teksilo_core::widget_builder::{HandlerSet, WidgetBuilder};
use teksilo_core::widget_id::WidgetId;
use teksilo_text::SharedTypesetter;
use teksilo_tokens::{CornerRadius, InputTokens, TargetRole, TextStyle};

use crate::common::range_nav::{self, RangeAxis, RangeKind, RangeMove};
use crate::primitives::icon_widget::IconWidget;
use crate::primitives::text_input_field::{TextFieldHandle, TextInputField};
use crate::primitives::{MinSize, Padding};

use self::step_button::StepButton;

// ── Enums ──────────────────────────────────────────────────────────

/// Out-of-range behavior when stepping past `min` or `max`.
///
/// Set via [`SpinBox::wrap_mode`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum WrapMode {
    /// Clamp to `min` / `max` (default).
    #[default]
    Clamp,
    /// Wrap around: past `max` jumps to `min`, past `min` jumps to
    /// `max`. Matches Qt's `QAbstractSpinBox::wrapping`.
    Wrap,
}

/// Step-size policy for each key/button press.
///
/// Set via [`SpinBox::step_type`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum StepType {
    /// Always step by `single_step` (default).
    #[default]
    Fixed,
    /// Step by the decimal power-of-ten immediately below the
    /// current value's magnitude — e.g. values 1–9 step by 1,
    /// 10–99 by 10, 100–999 by 100. Matches Qt's
    /// `AdaptiveDecimalStepType`. Integer types honor the same
    /// rule using the magnitude of the absolute value.
    Adaptive,
}

pub use teksilo_core::styles::ButtonLayout;
use teksilo_core::styles::density::dp;
use teksilo_i18n::LocalizedString;

/// When the mouse wheel is allowed to adjust the value.
///
/// Set via [`SpinBox::wheel_mode`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum WheelMode {
    /// Wheel adjusts only when the field is focused. Default —
    /// prevents accidental changes when the user is scrolling a
    /// larger surrounding view.
    #[default]
    Focused,
    /// Wheel adjusts whenever the pointer is over the widget.
    Hover,
    /// Wheel never adjusts the value; events bubble to the
    /// surrounding scroll container.
    Disabled,
}

/// How the SpinBox decides its horizontal size envelope.
///
/// Chosen via the [`width`](SpinBox::width),
/// [`width_chars`](SpinBox::width_chars), and
/// [`fill_width`](SpinBox::fill_width) builder methods — the enum
/// itself is the storage, not a separate public configuration
/// API.
#[derive(Debug, Clone)]
pub enum WidthPolicy {
    /// Cap the widget at a fixed logical-pixel width. Default is
    /// `DEFAULT_PREFERRED_WIDTH` (120 dp), matching Qt's
    /// `QSpinBox` sizeHint.
    Pixels(f32),
    /// Size the widget to fit this many reference digits (`'0'`)
    /// plus the configured suffix, padding, and step buttons.
    /// Measurement uses the theme font at build time.
    Chars(u32),
    /// Let the widget expand horizontally to fill whatever space
    /// the parent offers. Equivalent to an infinite pixel cap.
    Fill,
}

// ── Type aliases for builder closures ──────────────────────────────

type TextFromValue<T> = Rc<dyn Fn(T) -> LocalizedString>;
type ValueFromText<T> = Rc<dyn Fn(&str) -> Option<T>>;
type OnValueChangedFn<T> = Rc<dyn Fn(T, &mut EventContext)>;

/// What one step did, for a caller that has an `EventContext` to report it
/// with.
enum StepOutcome<T> {
    /// Nothing moved and the field already showed the value.
    Unchanged,
    /// The value stayed, and the field was put back to showing it over text
    /// the user had typed.
    Restored,
    /// The value moved to this.
    Changed(T),
}

/// Minimum total width. Below this the stacked step buttons stop
/// fitting next to the field. Widgets narrower than this are
/// enforced to the minimum at layout time via `MinSize`.
/// Painted width of one stacked step button, in dp.
///
/// Below the 24 dp WCAG floor, and **no hit mechanism reaches it** — see the
/// "Touch and pen" section of this module and `StepButton::children` for the
/// measurement. The two steps are separate nodes stacked in a trailing column
/// exactly one button wide, so there is nothing for `Widget::hit_outset` to
/// grow into and nothing for `partition_targets` to carve; growing the paint
/// instead would widen every numeric field on a form. Named here so the hit
/// mechanisms and the `chrome` arithmetic below read the same number.
pub const SPIN_BOX_STEP_BUTTON_WIDTH: f32 = 18.0;

/// Painted height of one stacked step button, in dp. Only a fallback — the
/// real height is half the field's inner height (see `build_step_buttons`).
pub const SPIN_BOX_STEP_BUTTON_HEIGHT: f32 = 12.0;

const MIN_WIDTH_WITH_BUTTONS: f32 = 72.0;

/// [`MIN_WIDTH_WITH_BUTTONS`] raised to the density's `target_size`
/// (24 / 32 / 44 dp). The identity at Compact.
fn min_width_with_buttons(tokens: &InputTokens) -> f32 {
    dp(MIN_WIDTH_WITH_BUTTONS, TargetRole::Target, tokens)
}
/// Minimum total width when buttons are hidden — the field alone
/// plus padding still reads as a numeric control.
const MIN_WIDTH_NO_BUTTONS: f32 = 48.0;

/// [`MIN_WIDTH_NO_BUTTONS`] raised to the density's `target_size`
/// (24 / 32 / 44 dp). The identity at Compact.
fn min_width_no_buttons(tokens: &InputTokens) -> f32 {
    dp(MIN_WIDTH_NO_BUTTONS, TargetRole::Target, tokens)
}
/// Default maximum width. Matches Qt's `QSpinBox` sizeHint for a
/// 4-digit value + unit suffix and stays tight in Int UI-style
/// dense forms.
const DEFAULT_PREFERRED_WIDTH: f32 = 120.0;

/// [`DEFAULT_PREFERRED_WIDTH`] raised to the density's `target_size`
/// (24 / 32 / 44 dp). The identity at Compact.
fn default_preferred_width(tokens: &InputTokens) -> f32 {
    dp(DEFAULT_PREFERRED_WIDTH, TargetRole::Target, tokens)
}

// ── SpinBox ────────────────────────────────────────────────────────

/// Numeric input with step buttons. Generic over
/// [`SpinValue`] — pre-implemented for `i32`, `i64`, `u32`, `u64`,
/// `usize`, `f32`, and `f64`.
pub struct SpinBox<T: SpinValue> {
    // ── Required configuration ──────────────────────────────────────
    value: Signal<T>,
    min: T,
    max: T,

    // ── Optional configuration (builders) ───────────────────────────
    single_step: T,
    page_step: Option<T>,
    decimals: u8,
    suffix: String,
    /// Whether the displayed number follows the active locale's
    /// conventions. See [`localized`](SpinBox::localized).
    localized: bool,
    /// Whether the displayed number carries thousands separators.
    /// Off by default — see [`use_grouping`](SpinBox::use_grouping).
    use_grouping: bool,
    special_value_text: Option<LocalizedString>,
    wrap_mode: WrapMode,
    step_type: StepType,
    button_layout: ButtonLayout,
    wheel_mode: WheelMode,
    /// Horizontal sizing policy. One of [`WidthPolicy::Pixels`]
    /// (fixed cap), [`WidthPolicy::Chars`] (font-metric-based),
    /// or [`WidthPolicy::Fill`] (stretch to parent). Set by the
    /// [`width`](SpinBox::width), [`width_chars`](SpinBox::width_chars),
    /// and [`fill_width`](SpinBox::fill_width) builder methods.
    width_policy: WidthPolicy,
    label: Option<LocalizedString>,
    placeholder: LocalizedString,
    /// Enabled state, static or reactive; forwarded to the arena at
    /// build time. Also captured as a build-time snapshot for the two
    /// build-time decisions inside `build()` that need a plain `bool`
    /// (seeding the inner `TextInputField`'s own `enabled` prop, and
    /// deriving the step buttons' enabled signals). The key-preview
    /// and scroll handlers deliberately do NOT read it — the
    /// dispatcher gates on `arena.is_enabled` first, and a build-time
    /// snapshot would leave a `Signal`-enabled spin box with a dead
    /// keyboard and wheel.
    enabled: Prop<bool>,
    read_only: bool,
    text_from_value: Option<TextFromValue<T>>,
    value_from_text: Option<ValueFromText<T>>,
    on_value_changed: Option<OnValueChangedFn<T>>,

    // ── Internal state (set during build) ───────────────────────────
    text_signal: Signal<String>,
    /// Tracks whether any descendant of the SpinBox root holds focus —
    /// in practice, the inner `TextInputField`. Driven by
    /// `WidgetBuilder::focus_within` on the root frame; replaces the
    /// previous multi-state `InteractionState` signal that was piped
    /// in/out of the field via `interaction_signal()`. The outer SpinBox
    /// only ever cared about Focused vs not.
    focused: Signal<bool>,
    can_step_up: Signal<bool>,
    can_step_down: Signal<bool>,
    /// Cached horizontal cap in pixels, resolved from `width_policy`
    /// at build time (Chars mode measures the theme font). `None`
    /// when the policy is `Fill`. Applied by `size_that_fits` by
    /// narrowing the proposal before delegating to the child — this
    /// replaces wrapping the subtree in a `MaxSize`, which clips
    /// children and would truncate the focus-state border stroke
    /// against its own shape quad.
    pixel_cap: Option<f32>,
    /// Floor width so the field and step buttons always fit. Also
    /// resolved at build from `button_layout`.
    min_width: f32,
    /// Per-call style override for the SpinBox chrome. Higher
    /// precedence than the theme-wide `style_slots.spin_box` slot.
    style_override: Option<teksilo_core::styles::SharedSpinBoxStyle>,
    root_child_id: Option<WidgetId>,
    field_id: Option<WidgetId>,

    // ── Tooltip slots (mutually exclusive; last setter wins) ─────────
    /// Optional plain tooltip text shown after a hover delay. Mutually
    /// exclusive with the rich / composite slots — every setter clears
    /// the other two so the last call wins.
    tooltip_text: Option<LocalizedString>,
    /// Optional rich tooltip source (registry key or inline content).
    rich_tooltip_source: Option<crate::tooltip::RichTooltipSource>,
    /// Optional composite tooltip body (arbitrary widget tree).
    composite_tooltip_content: Option<Box<dyn Widget>>,
}

impl<T: SpinValue> std::fmt::Debug for SpinBox<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SpinBox")
            .field("min", &self.min)
            .field("max", &self.max)
            .field("single_step", &self.single_step)
            .field("decimals", &self.decimals)
            .field("localized", &self.localized)
            .field("use_grouping", &self.use_grouping)
            .field("wrap_mode", &self.wrap_mode)
            .finish_non_exhaustive()
    }
}

impl<T: SpinValue> SpinBox<T> {
    /// Construct a new SpinBox bound to `value` with the given
    /// inclusive range. `min` must be ≤ `max`.
    pub fn new(value: Signal<T>, min: T, max: T) -> Self {
        // `single_step` defaults to 1 on the value's f64 scale —
        // works naturally for integers and for decimal floats.
        // Callers with a different natural step (0.1, 0.5, 10, …)
        // override via `single_step(...)`.
        let default_step = T::from_f64_saturating(1.0);
        Self {
            value,
            min,
            max,
            single_step: default_step,
            page_step: None,
            decimals: if T::is_integer() { 0 } else { 2 },
            suffix: String::new(),
            localized: true,
            use_grouping: false,
            special_value_text: None,
            wrap_mode: WrapMode::Clamp,
            step_type: StepType::Fixed,
            button_layout: ButtonLayout::Stacked,
            wheel_mode: WheelMode::Focused,
            width_policy: WidthPolicy::Pixels(DEFAULT_PREFERRED_WIDTH),
            label: None,
            placeholder: LocalizedString::literal(String::new()),
            enabled: Prop::Static(true),
            read_only: false,
            text_from_value: None,
            value_from_text: None,
            on_value_changed: None,
            text_signal: Signal::new(String::new()),
            focused: Signal::new(false),
            can_step_up: Signal::new(true),
            can_step_down: Signal::new(true),
            pixel_cap: None,
            min_width: MIN_WIDTH_WITH_BUTTONS,
            style_override: None,
            root_child_id: None,
            field_id: None,
            tooltip_text: None,
            rich_tooltip_source: None,
            composite_tooltip_content: None,
        }
    }

    /// Per-call style override. Higher precedence than the theme-wide
    /// `style_slots.spin_box` slot.
    pub fn style(mut self, style: impl teksilo_core::styles::SpinBoxStyle) -> Self {
        self.style_override = Some(Rc::new(style));
        self
    }

    // ── Builder methods ─────────────────────────────────────────────

    /// Set the step size for `Up` / `Down` / single wheel tick /
    /// button tap.
    pub fn single_step(mut self, step: T) -> Self {
        self.single_step = step;
        self
    }

    /// Set the step size for `PageUp` / `PageDown`. When unset,
    /// defaults to `10 × single_step` at build time.
    pub fn page_step(mut self, step: T) -> Self {
        self.page_step = Some(step);
        self
    }

    /// Number of decimal places shown for floating-point types.
    /// Ignored for integer types.
    pub fn decimals(mut self, decimals: u8) -> Self {
        self.decimals = decimals;
        self
    }

    /// Whether the number follows the active locale's conventions —
    /// decimal separator, digits, and minus sign. **On by default.**
    ///
    /// A French user sees `12,5`, not `12.5`, and can type either: the
    /// commit path de-localizes before parsing, and the input filter
    /// accepts both the locale's separator and the ASCII one, so a
    /// numeric keypad still works.
    ///
    /// Turn it **off** for a number that is an identifier rather than a
    /// quantity — a port number, a version component, a database id, a
    /// pixel offset in a file format. Those read wrong grouped or
    /// re-punctuated, and their conventional form is the C-locale one.
    ///
    /// Localization is a string transform over the value's own
    /// `Display`, not a round-trip through `f64`, so a `SpinBox<i64>`
    /// keeps full precision past 2^53.
    ///
    /// With no `I18nManager` installed the active locale resolves to the
    /// C locale, so this is a no-op in tests and in apps that have not
    /// opted into i18n.
    pub fn localized(mut self, on: bool) -> Self {
        self.localized = on;
        self
    }

    /// Whether the displayed number carries thousands separators.
    /// **Off by default**, matching Qt (`QAbstractSpinBox::
    /// isGroupSeparatorShown` is false unless asked for).
    ///
    /// Separators help a large read-only quantity and get in the way of
    /// a field being typed into, so this is opt-in per SpinBox rather
    /// than a locale-wide default. Grouping follows the locale's own
    /// group sizes, including the Indic lakh system (`12,34,567`).
    ///
    /// Has no effect when [`localized`](Self::localized) is off.
    pub fn use_grouping(mut self, on: bool) -> Self {
        self.use_grouping = on;
        self
    }

    /// Qt-style non-editable trailing unit (e.g. `" %"`, `" px"`,
    /// `" dB"`). Rendered flush-right inside the field's border;
    /// the caret cannot enter it.
    pub fn suffix(mut self, text: impl Into<String>) -> Self {
        self.suffix = text.into();
        self
    }

    /// Text shown in place of the formatted value when the current
    /// value equals `min`. Use for "Auto", "None", "Off",
    /// "Unlimited" affordances where the minimum has special
    /// semantics. The text stays while the field has focus, as
    /// Qt's `specialValueText` does: keyboard focus selects it, so a
    /// number typed replaces it, and a step moves off it.
    pub fn special_value_text(mut self, text: impl Into<LocalizedString>) -> Self {
        self.special_value_text = Some(text.into());
        self
    }

    /// Set the out-of-range behavior when stepping past `min` or `max`
    /// (default: `Clamp`).
    pub fn wrap_mode(mut self, mode: WrapMode) -> Self {
        self.wrap_mode = mode;
        self
    }

    /// Set the step-size policy (default: `Fixed`). Use
    /// `StepType::Adaptive` for values that span many orders of magnitude.
    pub fn step_type(mut self, step_type: StepType) -> Self {
        self.step_type = step_type;
        self
    }

    /// Override the step-button layout (default: `Stacked` — stacked
    /// up/down buttons to the right of the field).
    pub fn button_layout(mut self, layout: ButtonLayout) -> Self {
        self.button_layout = layout;
        self
    }

    /// Convenience wrapper over [`button_layout`](Self::button_layout):
    /// `true` → `ButtonLayout::Stacked`, `false` → `ButtonLayout::Hidden`.
    /// Matches the Int UI guideline that SpinBoxes in dense forms
    /// often hide the step buttons to reduce visual noise and let
    /// keyboard / wheel carry the affordance — pass
    /// `.show_buttons(false)` on those call sites.
    pub fn show_buttons(mut self, show: bool) -> Self {
        self.button_layout = if show {
            ButtonLayout::Stacked
        } else {
            ButtonLayout::Hidden
        };
        self
    }

    /// Set when the mouse wheel adjusts the value (default: `Focused` —
    /// only when the inner field holds focus).
    pub fn wheel_mode(mut self, mode: WheelMode) -> Self {
        self.wheel_mode = mode;
        self
    }

    /// Cap the widget's horizontal size at a fixed logical-pixel
    /// width. If the parent offers less, the SpinBox shrinks (down
    /// to the internal 72 dp / 48 dp floor that keeps the buttons
    /// and field from overlapping). Default: 120 dp, matching Qt
    /// `QSpinBox` sizeHint and Int UI form density.
    ///
    /// ```rust
    /// # use teksilo_widgets::SpinBox;
    /// # use teksilo_core::signal::Signal;
    /// # let v = Signal::new(0_i32);
    /// let _w = SpinBox::new(v.clone(), 0, 9999).width(80.0);        // narrow
    /// let _w = SpinBox::new(v.clone(), 0, 9999).width(200.0);       // wider
    /// let _w = SpinBox::new(v.clone(), 0, 9999).fill_width();       // stretch to parent
    /// let _w = SpinBox::new(v.clone(), 0, 9999).width_chars(5);     // "fits 5 digits"
    /// ```
    pub fn width(mut self, width: f32) -> Self {
        self.width_policy = WidthPolicy::Pixels(width.max(0.0));
        self
    }

    /// Size the widget to fit exactly `chars` reference digits plus
    /// the configured suffix, padding, and step buttons. The
    /// measurement uses the actual theme font at build time (same
    /// `SharedTypesetter` the field draws with), so values stay
    /// right under runtime theme switches and HiDPI scale changes.
    ///
    /// ```rust
    /// # use teksilo_widgets::SpinBox;
    /// # use teksilo_core::signal::Signal;
    /// # let port = Signal::new(8080_i32);
    /// # let pct = Signal::new(0_i32);
    /// let _w = SpinBox::new(port, 0, 65_535).width_chars(5);           // 5 digits
    /// let _w = SpinBox::new(pct, 0, 100).suffix(" %").width_chars(3);  // 3 + " %"
    /// ```
    pub fn width_chars(mut self, chars: u32) -> Self {
        self.width_policy = WidthPolicy::Chars(chars);
        self
    }

    /// Let the widget expand to fill the horizontal space offered
    /// by its parent, instead of capping at [`width`](Self::width).
    /// Use inside toolbars, inspector panels, or an
    /// `Expand::horizontal` column that should stretch with the
    /// surrounding layout.
    pub fn fill_width(mut self) -> Self {
        self.width_policy = WidthPolicy::Fill;
        self
    }

    /// Set the accessible name announced by screen readers as the
    /// control's label. ARIA requires spin buttons to have a label;
    /// when none is set here the caller is responsible for labelling
    /// via a `FormLayout` line, `access_labelled_by` or `access_label`
    /// on the spin box, which all reach the editing field that holds
    /// focus and publishes the spin button.
    pub fn label(mut self, label: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = label.into();
        self.label = Some(ls);
        self
    }

    /// Set the placeholder text shown in the field when it is empty.
    pub fn placeholder(mut self, text: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = text.into();
        self.placeholder = ls;
        self
    }

    /// Set the enabled state, statically or reactively. Forwarded to
    /// the arena at build time via
    /// `ctx.enabled_when(spinbox_id, self.enabled.clone())`.
    pub fn enabled(mut self, enabled: impl Into<Prop<bool>>) -> Self {
        self.enabled = enabled.into();
        self
    }

    /// Make the value uneditable: no typing, no keyboard or wheel stepping,
    /// no step buttons, and no assistive-technology `Increment` / `Decrement`
    /// / `SetValue`. Matches `QAbstractSpinBox::readOnly`, which likewise
    /// stops `stepBy`. The field keeps focus and selection, so the value can
    /// still be read and copied.
    pub fn read_only(mut self, read_only: bool) -> Self {
        self.read_only = read_only;
        self
    }

    /// Override the value → display-string conversion. Receives the
    /// raw value; returns whatever string should appear in the
    /// field. Suffix and `special_value_text` still apply on top of
    /// the returned string.
    pub fn text_from_value(mut self, f: impl Fn(T) -> LocalizedString + 'static) -> Self {
        self.text_from_value = Some(Rc::new(f));
        self
    }

    /// Override the parse step. Receives the field's raw text
    /// (without the suffix, which is never part of the editable
    /// content); returns `Some(value)` to accept or `None` to
    /// reject. Invalid input reverts to the last good value on
    /// commit.
    ///
    /// Installing a parser also lifts the per-character input filter,
    /// which admits only what the default numeric parse can read. The
    /// parser owns the text convention, so a month field reading
    /// `"march"` as 3 can be typed by name: every character reaches the
    /// field, and whatever the parser refuses is reverted at commit.
    pub fn value_from_text(mut self, f: impl Fn(&str) -> Option<T> + 'static) -> Self {
        self.value_from_text = Some(Rc::new(f));
        self
    }

    /// Closure fired each time the value is committed (keyboard
    /// step, button tap, wheel tick, Enter, blur). Bound observers
    /// on the value signal also see every change; use this hook
    /// when the caller needs an `EventContext` (e.g. to fire an
    /// intent).
    pub fn on_value_changed(mut self, f: impl Fn(T, &mut EventContext) + 'static) -> Self {
        self.on_value_changed = Some(Rc::new(f));
        self
    }

    // ── Tooltip builder methods ─────────────────────────────────────

    /// Attach a plain single-line tooltip shown after a hover delay.
    ///
    /// Mutually exclusive with [`rich_tooltip`](Self::rich_tooltip),
    /// [`rich_tooltip_content`](Self::rich_tooltip_content), and
    /// [`composite_tooltip`](Self::composite_tooltip) — each setter
    /// clears the other two so the last call wins.
    pub fn tooltip(mut self, text: impl Into<LocalizedString>) -> Self {
        self.tooltip_text = Some(text.into());
        self.rich_tooltip_source = None;
        self.composite_tooltip_content = None;
        self
    }

    /// Attach a rich tooltip looked up by registry key.
    ///
    /// The key must match a [`TooltipContent`](crate::tooltip::TooltipContent)
    /// registered in the application's tooltip registry. Mutually
    /// exclusive with [`tooltip`](Self::tooltip),
    /// [`rich_tooltip_content`](Self::rich_tooltip_content), and
    /// [`composite_tooltip`](Self::composite_tooltip).
    pub fn rich_tooltip(mut self, key: impl Into<String>) -> Self {
        self.rich_tooltip_source = Some(crate::tooltip::RichTooltipSource::Key(key.into()));
        self.tooltip_text = None;
        self.composite_tooltip_content = None;
        self
    }

    /// Attach a rich tooltip with inline content (no registry key
    /// required). Mutually exclusive with [`tooltip`](Self::tooltip),
    /// [`rich_tooltip`](Self::rich_tooltip), and
    /// [`composite_tooltip`](Self::composite_tooltip).
    pub fn rich_tooltip_content(mut self, content: crate::tooltip::TooltipContent) -> Self {
        self.rich_tooltip_source = Some(crate::tooltip::RichTooltipSource::Content(content));
        self.tooltip_text = None;
        self.composite_tooltip_content = None;
        self
    }

    /// Attach a composite tooltip whose body is an arbitrary widget
    /// tree. Mutually exclusive with [`tooltip`](Self::tooltip),
    /// [`rich_tooltip`](Self::rich_tooltip), and
    /// [`rich_tooltip_content`](Self::rich_tooltip_content).
    pub fn composite_tooltip(mut self, content: impl Widget + 'static) -> Self {
        self.composite_tooltip_content = Some(Box::new(content));
        self.tooltip_text = None;
        self.rich_tooltip_source = None;
        self
    }

    /// Like [`composite_tooltip`](Self::composite_tooltip) but accepts
    /// an already-boxed widget body. Used by wrapper widgets that
    /// forward a boxed composite body.
    pub(crate) fn composite_tooltip_boxed(mut self, content: Box<dyn Widget>) -> Self {
        self.composite_tooltip_content = Some(content);
        self.tooltip_text = None;
        self.rich_tooltip_source = None;
        self
    }

    // ── Signal accessors (call before add to tree) ──────────────────

    /// The bound numeric value signal.
    pub fn value(&self) -> Signal<T> {
        self.value.clone()
    }
}

impl<T: SpinValue> Widget for SpinBox<T> {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        // Sanity-check the range once. A malformed range is a
        // programming error, not a runtime user error.
        debug_assert!(self.min <= self.max, "SpinBox min must be <= max");

        // SpinBox reads theme tokens once for static layout params
        // (padding, focus-ring width, body typography). Colors resolve
        // through role props against the current theme at paint time,
        // so runtime theme switches re-paint without riding through
        // per-widget zips.
        //
        // The snapshot is OWNED (`theme_signal.get()` clones), because the
        // body typography is read further down in `build()` — past many
        // `ctx.add(...)` / `ctx.effect(...)` calls that need a mutable
        // borrow of `ctx`. A `ctx.theme()` borrow would hold `ctx`
        // immutable across those calls and fail the borrow checker.
        let theme = ctx.theme_signal().get();
        use crate::styles::recipe_text_input_style as field_dims;
        let field_border_width = field_dims::TEXT_FIELD_BORDER_WIDTH;
        let focus_ring_width = theme.shape.focus_ring_width;

        // Capture configuration into owned clones for the effect
        // closures. The builder closures are `Rc`-wrapped already.
        let min = self.min;
        let max = self.max;
        let decimals = self.decimals;
        let suffix_str = self.suffix.clone();
        let special_text = self.special_value_text.clone();
        let text_from_value = self.text_from_value.clone();
        let value_from_text = self.value_from_text.clone();
        let wrap_mode = self.wrap_mode;
        let step_type = self.step_type;
        let single_step = self.single_step;
        let page_step = self
            .page_step
            .unwrap_or_else(|| single_step.saturating_mul_u32(10));
        let on_value_changed = self.on_value_changed.clone();
        let self_id = ctx.self_id();
        // Forward the enabled state into the arena; see IconButton.
        ctx.enabled_when(self_id, self.enabled.clone());
        // Snapshot the build-time enabled state into a local for
        // closures that capture it for read-only-style guards on
        // wheel events / step buttons. The framework's event gate
        // already refuses to dispatch to disabled subtrees, so the
        // value here only matters for the few build-time decisions
        // (e.g. seeding the inner TextInputField's read_only mode).
        let enabled = self.enabled.get();
        let read_only = self.read_only;
        let wheel_mode = self.wheel_mode;

        // The locale's number conventions, and the *same* value for the
        // display path, the commit parse, the step and the input filter.
        // Split resolution would let them disagree about which separator
        // this field uses, which `DateEdit` avoids by deriving format, parse
        // and mask from one `ParsedPattern`.
        //
        // A cell every path reads as it runs, not a copy each captures. A
        // locale switch rebuilds nothing (`WidgetTree::set_locale` marks the
        // tree dirty and stops there), so a copy taken here kept every path
        // but the re-render in the build-time locale: after a switch to
        // French the field showed `12,5`, dropped the comma typed into it,
        // and committed 125. The effect on `ctx.locale_signal()` below
        // replaces the value in the step that re-renders the text, so the
        // text shown and the conventions it is read with are one locale's.
        let presentation = LivePresentation::new(NumberPresentation::resolve(
            self.localized,
            self.use_grouping,
        ));

        // A handle on the editing field, handed out before the field exists
        // (it is built further down) so the commit and step closures can
        // read what the field holds rather than the signal it mirrors into
        // a frame late. `share_handle` binds it when the field is built.
        let field_handle = TextFieldHandle::detached();

        // Every string this widget puts in the field goes through `show`,
        // which remembers it. The field's text is the user's to edit, so
        // whatever it holds that differs from `last_shown` was typed. That
        // comparison is exact whatever the locale, the formatter or the
        // special-value text made of the number: telling typing from the
        // widget's own output never means rendering the value again and
        // hoping it comes out the same.
        //
        // The write is unconditional. The bound signal can still hold this
        // very string while the field shows something typed since (typing
        // reaches the signal a frame late), and only a write makes the field
        // replace its text; the field compares before it rewrites, so a
        // redundant write costs one string comparison.
        let last_shown: Rc<RefCell<String>> = Rc::new(RefCell::new(String::new()));
        let show: Rc<dyn Fn(String)> = {
            let text_signal = self.text_signal.clone();
            let last_shown = last_shown.clone();
            Rc::new(move |text: String| {
                last_shown.replace(text.clone());
                text_signal.set(text);
            })
        };

        // Seed the text signal from the current value.
        show(format_for_display(
            self.value.get(),
            decimals,
            special_text.as_ref(),
            text_from_value.as_deref(),
            min,
            &presentation.get(),
        ));

        // Effect: when the value signal changes externally, reformat
        // the text. This also fires on startup with the initial value
        // (guaranteed by `ctx.effect`). Skipped when the field is
        // focused so typing isn't interrupted by our own round-trip
        // writes — on commit we explicitly re-sync.
        {
            let show = show.clone();
            let text_from_value = text_from_value.clone();
            let special_text = special_text.clone();
            let focused = self.focused.clone();
            let can_up = self.can_step_up.clone();
            let can_down = self.can_step_down.clone();
            let min_cap = min;
            let max_cap = max;
            let presentation = presentation.clone();
            ctx.effect(&self.value, move |new_value| {
                // Update the can-step signals any time the value
                // changes so the buttons and a11y reflect whether
                // further stepping is possible under clamp mode.
                let is_focused = focused.get();
                if wrap_mode == WrapMode::Wrap {
                    can_up.set(true);
                    can_down.set(true);
                } else {
                    can_up.set(*new_value < max_cap);
                    can_down.set(*new_value > min_cap);
                }
                if !is_focused {
                    show(format_for_display(
                        *new_value,
                        decimals,
                        special_text.as_ref(),
                        text_from_value.as_deref(),
                        min_cap,
                        &presentation.get(),
                    ));
                }
            });
        }

        // Effect: re-format on locale change so special_value_text
        // and custom formatters re-resolve with the new locale.
        {
            let show = show.clone();
            let text_from_value = text_from_value.clone();
            let special_text = special_text.clone();
            let value_signal = self.value.clone();
            let locale_signal = ctx.locale_signal();
            let presentation = presentation.clone();
            // A locale switch re-renders the number in place, in the new
            // locale's conventions, which from here on are the ones every
            // other path reads the number with.
            let localized = self.localized;
            let grouping = self.use_grouping;
            ctx.effect(&locale_signal, move |_| {
                presentation.set(NumberPresentation::resolve(localized, grouping));
                show(format_for_display(
                    value_signal.get(),
                    decimals,
                    special_text.as_ref(),
                    text_from_value.as_deref(),
                    min,
                    &presentation.get(),
                ));
            });
        }

        // Three commit helpers follow: `set_committed` (the tail —
        // clamp, reformat, publish, notify), `commit_text` (the one
        // parse site, with the revert on failure) and `commit` (what
        // Enter and blur call: reads the field text, hands it over).
        // The commit *tail*: clamp into `[min, max]`, reformat the field
        // text, publish the value and fire `on_value_changed`. Split out of
        // `commit` because the AccessKit `SetValue` path is handed a *number*
        // and has nothing to parse — and routing a number back through the
        // parser would hand a machine-generated string to a user-supplied
        // `value_from_text` that never agreed to read one. The reformat runs
        // even when the value is unchanged, so `007` still normalises to `7`.
        let set_committed: Rc<dyn Fn(T, &mut EventContext)> = {
            let value_signal = self.value.clone();
            let show = show.clone();
            let text_from_value = text_from_value.clone();
            let special_text = special_text.clone();
            let on_value_changed = on_value_changed.clone();
            let presentation = presentation.clone();
            Rc::new(move |candidate: T, ctx: &mut EventContext| {
                let old = value_signal.get();
                let new_value = candidate.clamp_value(min, max);
                show(format_for_display(
                    new_value,
                    decimals,
                    special_text.as_ref(),
                    text_from_value.as_deref(),
                    min,
                    &presentation.get(),
                ));
                if approx_ne(new_value, old) {
                    value_signal.set(new_value);
                    if let Some(cb) = on_value_changed.as_ref() {
                        cb(new_value, ctx);
                    }
                }
            })
        };

        // Commit a string. The one parse site: Enter, blur and the AccessKit
        // `SetValue` string payload all arrive here, so an assistive-technology
        // write honours a custom `value_from_text` and the active locale's
        // decimal separator exactly as a typed one does. Reports whether the
        // string parsed; on failure the display is restored from the value the
        // field still holds — the revert a typed rubbish string gets — and the
        // caller decides how loudly to say so.
        //
        // The parse itself is its own closure because a step reads typed text
        // too, and must read it exactly as Enter would.
        let parse: Rc<dyn Fn(&str) -> Option<T>> = {
            let value_from_text = value_from_text.clone();
            let presentation = presentation.clone();
            Rc::new(move |raw: &str| {
                // A user-supplied parser gets the raw text: it owns the
                // whole convention, and de-localizing first would hand it
                // a string it never agreed to read.
                match value_from_text.as_deref() {
                    Some(f) => f(raw.trim()),
                    None => presentation.get().parse::<T>(raw),
                }
            })
        };
        let commit_text: Rc<dyn Fn(&str, &mut EventContext) -> bool> = {
            let value_signal = self.value.clone();
            let parse = parse.clone();
            let set_committed = set_committed.clone();
            Rc::new(move |raw: &str, ctx: &mut EventContext| {
                match parse(raw) {
                    Some(v) => {
                        set_committed(v, ctx);
                        true
                    }
                    None => {
                        // Revert: reformat from the value still held.
                        set_committed(value_signal.get(), ctx);
                        false
                    }
                }
            })
        };

        let commit: Rc<dyn Fn(&mut EventContext)> = {
            let text_signal = self.text_signal.clone();
            let field_handle = field_handle.clone();
            let commit_text = commit_text.clone();
            Rc::new(move |ctx: &mut EventContext| {
                // The field, not the signal it mirrors typing into a frame
                // late: Enter delivered in the same batch as the digit before
                // it would otherwise commit the text without that digit. The
                // signal is the fallback for a field that cannot answer.
                let raw = field_handle
                    .text_as_typed()
                    .unwrap_or_else(|| text_signal.get());
                let _ = commit_text(&raw, ctx);
            })
        };

        // ── Step helpers ───────────────────────────────────────────
        //
        // Two closures cover the two firing pathways:
        //
        // - `step` is called from event handlers (keyboard, wheel,
        //   button tap, a11y action) and takes an `EventContext`
        //   so it can fire the user's `on_value_changed` callback
        //   and request a frame.
        //
        // - `step_silent` is called from signal-only contexts
        //   (hold-to-repeat on the step buttons, which lives in a
        //   frame-tick effect that has no `EventContext` to hand).
        //   It mutates `value` and `text_signal` and lets the
        //   bindings on those signals trigger the redraw. The
        //   user's `on_value_changed` callback is deliberately
        //   skipped — signal observers still see every change,
        //   which is the primary notification channel.
        //
        // `can_step_up` / `can_step_down` are kept in sync by the
        // value-effect above.

        fn apply_step<T: SpinValue>(
            dir: i32,
            page: bool,
            step_type: StepType,
            wrap_mode: WrapMode,
            single_step: T,
            page_step: T,
            min: T,
            max: T,
            current: T,
        ) -> T {
            let base_step = if page { page_step } else { single_step };
            let effective = resolve_effective_step(step_type, current, base_step);
            let stepped = if dir > 0 {
                current.saturating_add(effective)
            } else {
                current.saturating_sub(effective)
            };
            if stepped < min || stepped > max {
                match wrap_mode {
                    WrapMode::Clamp => stepped.clamp_value(min, max),
                    WrapMode::Wrap => {
                        if stepped > max {
                            min
                        } else {
                            max
                        }
                    }
                }
            } else {
                stepped
            }
        }

        // Signal-only step: publishes the new value and its text, and says
        // what it did so the caller can fire `on_value_changed` after the
        // fact.
        //
        // A step starts from what the field shows, which is not always the
        // value: somebody who types 35 and presses Up has just heard the field
        // say 35, and stepping from the value committed before the typing
        // threw the typing away and moved from a number nobody could hear.
        // This is `QAbstractSpinBox::stepBy`, which interprets the pending text
        // before it steps. So typed text (anything the field holds that
        // `show` did not put there) is read first, exactly as Enter reads it:
        // parsed, clamped, and stepped from. The typed number and the step are
        // one change, with one signal write and one notification.
        //
        // Text that does not parse steps nothing: the value goes back into the
        // field and the press ends there, so what the user hears is the number
        // the next press will step from, not one two moves removed from
        // anything they were told. Qt does the same, for the same reason.
        //
        // The auto-repeat of a held step button calls this directly. Its first
        // step went through `step` below, which has already read the typing,
        // so every repeat finds the field showing what `show` wrote.
        let step_silent: Rc<dyn Fn(i32, bool) -> StepOutcome<T>> = {
            let value_signal = self.value.clone();
            let field_handle = field_handle.clone();
            let last_shown = last_shown.clone();
            let parse = parse.clone();
            let show = show.clone();
            let text_from_value = text_from_value.clone();
            let special_text = special_text.clone();
            let presentation = presentation.clone();
            Rc::new(move |dir: i32, page: bool| {
                if read_only {
                    return StepOutcome::Unchanged;
                }
                let display = |value: T| {
                    format_for_display(
                        value,
                        decimals,
                        special_text.as_ref(),
                        text_from_value.as_deref(),
                        min,
                        &presentation.get(),
                    )
                };
                let current = value_signal.get();
                let typed = field_handle
                    .text_as_typed()
                    .filter(|text| *text != *last_shown.borrow());
                let from = match typed.as_deref().map(|text| parse(text)) {
                    None => current,
                    Some(Some(read)) => read.clamp_value(min, max),
                    Some(None) => {
                        show(display(current));
                        return StepOutcome::Restored;
                    }
                };
                let new_value = apply_step(
                    dir,
                    page,
                    step_type,
                    wrap_mode,
                    single_step,
                    page_step,
                    min,
                    max,
                    from,
                );
                if approx_eq(new_value, current) {
                    // Typing that came to the value already held still leaves
                    // the field showing the typing; put the value's own text
                    // back.
                    if typed.is_some() {
                        show(display(new_value));
                        return StepOutcome::Restored;
                    }
                    return StepOutcome::Unchanged;
                }
                value_signal.set(new_value);
                show(display(new_value));
                StepOutcome::Changed(new_value)
            })
        };

        // Contextful step: wraps `step_silent` and fires the user
        // callback + frame request on change.
        let step: Rc<dyn Fn(i32, bool, &mut EventContext)> = {
            let step_silent = step_silent.clone();
            let on_value_changed = on_value_changed.clone();
            Rc::new(move |dir: i32, page: bool, ctx: &mut EventContext| {
                match step_silent(dir, page) {
                    StepOutcome::Changed(new_value) => {
                        if let Some(cb) = on_value_changed.as_ref() {
                            cb(new_value, ctx);
                        }
                        ctx.request_frame();
                    }
                    StepOutcome::Restored => ctx.request_frame(),
                    StepOutcome::Unchanged => {}
                }
            })
        };

        // ── Inner editing field ────────────────────────────────────
        //
        // Uses `TextInputField` directly rather than the `TextInput`
        // composite — the composite's border / padding / placeholder
        // overlay is reproduced here around both the field and the
        // buttons in one shared frame, instead of framing the text
        // by itself.
        let inner_height =
            (field_dims::TEXT_FIELD_HEIGHT - 2.0 * field_dims::TEXT_FIELD_BORDER_WIDTH).max(0.0);
        let text_area_height =
            (inner_height - 2.0 * field_dims::TEXT_FIELD_PADDING_VERTICAL).max(0.0);

        let mut field = TextInputField::new(self.text_signal.clone())
            .share_handle(&field_handle)
            .enabled(enabled)
            // An assistive-technology `SetValue` on the inner text node is a
            // finished edit, not a keystroke, so it takes the same parse,
            // clamp and revert `Enter` takes. Handed the string rather than
            // reading `text_signal`, which this edit has not synced yet.
            .on_access_set_value({
                let commit_text = commit_text.clone();
                move |text: &str, ctx: &mut EventContext| commit_text(text, ctx)
            })
            .read_only(read_only)
            .placeholder(self.placeholder.clone())
            .text_height(text_area_height);
        // The per-character filter speaks for the default parser and for it
        // alone: it admits exactly what `NumberPresentation::parse` can read. A
        // custom `value_from_text` owns the whole text convention (a month
        // typed as "march", a duration as "1h30"), and filtering for digits in
        // front of it dropped the very characters it was installed to read,
        // before it ever saw them. So with one installed every character
        // reaches the field, and the parser is the only judge, at commit, with
        // the usual revert for what it refuses.
        if value_from_text.is_none() {
            field = field.char_filter({
                let presentation = presentation.clone();
                move |c| presentation.get().accepts_char::<T>(c)
            });
        }
        // Suffix wiring:
        //   • plain static suffix              → `.suffix(..)` (no signal)
        //   • static suffix + special_value    → reactive: hide the suffix
        //     when `value == min`, where the field shows the special text
        //     whether or not it has focus, so `"Auto"` reads cleanly without
        //     a trailing unit. A number typed over it takes its unit when it
        //     is committed.
        //   • no suffix and no special         → nothing to do.
        //
        // The reactive case uses a mutable intermediate signal
        // rather than feeding `TextInputField::suffix` a
        // derived signal directly — `ctx.effect` requires a
        // mutable source, and the field needs to drive a
        // relayout + re-measure when the suffix flips on/off.
        // Driven by the value, never by the text: the field writes its text
        // out while it holds its own state, and a suffix change re-enters
        // that state to measure the new suffix.
        if !suffix_str.is_empty() {
            if self.special_value_text.is_some() {
                let unit_for = {
                    let unit = suffix_str.clone();
                    move |v: T| {
                        if approx_eq(v, min) {
                            String::new()
                        } else {
                            unit.clone()
                        }
                    }
                };
                // Seeded here: an effect fires on a change, never as it is
                // registered, and the field reads its first suffix at build.
                let suffix_live = ctx.signal(unit_for(self.value.get()));
                let suffix_for_value = suffix_live.clone();
                ctx.effect(&self.value, move |v| {
                    let next = unit_for(*v);
                    if suffix_for_value.get() != next {
                        suffix_for_value.set(next);
                    }
                });
                field = field.suffix(suffix_live);
            } else {
                field = field.suffix(suffix_str.clone());
            }
        }
        // Submit on Enter: commit in-place, keep focus.
        {
            let commit = commit.clone();
            field = field.on_submit_fn(move |ctx| commit(ctx));
        }
        // Commit on blur: after the field clears its selection and
        // resets scroll.
        {
            let commit = commit.clone();
            field = field.on_blur_fn(move |ctx| commit(ctx));
        }

        // Focus changes nothing in the text. The field used to swap a
        // `special_value_text` for the plain number as focus arrived, in the
        // update that moved focus, so a screen reader landing on "Auto" was
        // told "0" and never what 0 means here; a step back to `min` and a
        // commit there both put the special text back into the focused field
        // anyway. Qt's `QSpinBox` keeps `specialValueText` through focus (Qt
        // 5.15, measured: a Tab focus leaves "Auto" in the field, selected),
        // and so does this: keyboard focus selects the whole text, so a number
        // typed replaces it, and a step moves off it.

        // The field is the spin button. It holds focus, the caret and the
        // text, so it is the node a focus change reports and the one a
        // screen reader names. The ARIA spinbutton pattern puts the role on
        // the focusable element, which is usually the one taking the text, and
        // AccessKit's consumer counts `Role::SpinButton` as a text input
        // (`NodeRef::is_text_input`), so this one node carries the text runs
        // and gets AT-SPI's Text, EditableText and Value interfaces, UIA's
        // Text, Value and RangeValue patterns, and on macOS an
        // `AXIncrementor` with the text attributes. With the name on an outer
        // node instead, a focus change reported a nameless text field; with
        // it on both, two nodes said it. And Orca speaks a value change only
        // on the object with focus, so the number moves where the focus is,
        // or an arrow press is silent.
        //
        // The composite's own node is structure (see `accessibility` and
        // `accessibility_proxy` below), and whatever an application attaches
        // to the spin box's id lands here, after this.
        //
        // Its value stays the field's own, the text as shown and typed, which
        // is what its text runs review. The suffix is painted beside that text
        // and is in neither: appending it here made the node announce "100 %"
        // and review "100", the divergence `audit::text_range_divergences`
        // exists to catch. The unit reaches a reader once the field emits it
        // as text; `engineering/docs/accessibility-internal-audit.md` records the gap.
        let field = field.access_customize({
            let label = self.label.clone();
            let value = self.value.clone();
            move |builder: &mut AccessNodeBuilder| {
                use teksilo_core::accesskit::{Action, Role};
                builder.set_role(Role::SpinButton);
                if let Some(label) = &label {
                    builder.set_name(label.resolve_now());
                }
                builder.set_numeric_value(value.get().to_f64());
                builder.set_min_numeric_value(min.to_f64());
                builder.set_max_numeric_value(max.to_f64());
                builder.set_numeric_value_step(single_step.to_f64());
                builder.set_numeric_value_jump(page_step.to_f64());
                // The field advertises `SetValue` and `Focus` itself; stepping
                // is the spin box's, serviced by its handler when the action
                // bubbles up from here. A read-only spin box offers neither:
                // macOS gates settability on the advertisement alone.
                if !read_only {
                    builder.add_action(Action::Increment);
                    builder.add_action(Action::Decrement);
                }
            }
        });
        let field_id = ctx.add(field);
        self.field_id = Some(field_id);

        // Wrap field in vertical padding so it aligns inside the frame.
        // (Horizontal Expand is owned by the active SpinBoxStyle so a
        // custom recipe can re-arrange the row.)
        let padded_field_id = ctx.add(
            Padding::new(
                field_dims::TEXT_FIELD_PADDING_VERTICAL,
                0.0,
                field_dims::TEXT_FIELD_PADDING_VERTICAL,
                0.0,
            )
            .child(field_id),
        );

        // ── Step buttons ───────────────────────────────────────────
        let (step_up_id, step_down_id) = if self.button_layout != ButtonLayout::Hidden {
            let (u, d) = build_step_buttons(
                ctx,
                &step,
                &step_silent,
                self.can_step_up.clone(),
                self.can_step_down.clone(),
                enabled && !read_only,
                field_dims::TEXT_FIELD_HEIGHT,
                field_dims::TEXT_FIELD_CORNER_RADIUS,
            );
            (Some(u), Some(d))
        } else {
            (None, None)
        };

        // ── Delegate visual chrome (row layout + divider + bordered
        // surface) to the active SpinBoxStyle.
        let style =
            crate::styles::recipe_spin_box_style::resolve_spin_box_style(&self.style_override, ctx);
        // Derive the disabled state from the arena rather than from the
        // build-time `enabled` snapshot above, so a bound `Signal<bool>`
        // (or a disabled *ancestor*) re-tints the chrome with no rebuild.
        let is_disabled = ctx.effective_enabled_signal(self_id).map(|on| !*on);
        let cfg = teksilo_core::styles::SpinBoxStyleConfig {
            field: padded_field_id,
            step_up: step_up_id,
            step_down: step_down_id,
            layout: self.button_layout,
            is_focused: self.focused.clone(),
            is_disabled,
        };
        let zstack_id = style.make_body(&cfg, ctx);
        let _ = focus_ring_width;
        let _ = field_border_width;

        // Resolve the width policy into a concrete pixel cap (or
        // `None` for `Fill`). Char-mode measurement uses the app-
        // wide `SharedTypesetter` — same backend the field paints
        // with — so the result tracks runtime theme switches and
        // HiDPI scale changes. `'0'` is the reference digit since
        // Inter and most UI sans-serifs ship tabular-figure
        // numerals; the suffix is measured separately because it
        // may have different glyph advances (e.g. `" %"`).
        let min_width = match self.button_layout {
            ButtonLayout::Stacked => min_width_with_buttons(&theme.input),
            ButtonLayout::Hidden => min_width_no_buttons(&theme.input),
        };
        let pixel_cap: Option<f32> = match self.width_policy {
            WidthPolicy::Fill => None,
            WidthPolicy::Pixels(px) => Some(px.max(min_width)),
            WidthPolicy::Chars(chars) => {
                let style = &theme.typography.body;
                let sample: String = "0".repeat(chars as usize);
                let digits_w = measure_width_px(ctx, &sample, style);
                let suffix_w = if suffix_str.is_empty() {
                    0.0
                } else {
                    measure_width_px(ctx, &suffix_str, style)
                };
                let button_chrome = match self.button_layout {
                    // step button + 4 dp divider padding + 1 dp divider
                    ButtonLayout::Stacked => SPIN_BOX_STEP_BUTTON_WIDTH + 4.0 + 1.0,
                    ButtonLayout::Hidden => 0.0,
                };
                // 2 dp slack so the caret and a trailing zero never
                // paint flush against the right edge.
                let chrome = field_dims::TEXT_FIELD_PADDING_HORIZONTAL * 2.0 + button_chrome + 2.0;
                Some((digits_w + suffix_w + chrome).max(min_width))
            }
        };

        // Size envelope:
        //   MinSize  → enforce a floor so the field and buttons
        //              still fit even when a narrow parent would
        //              otherwise squash the widget.
        //   The horizontal cap (when `pixel_cap` is `Some`) is
        //   applied by `SpinBox::size_that_fits` narrowing the
        //   proposal, NOT by wrapping in `MaxSize`. `MaxSize`
        //   clips its children, which would truncate the outer
        //   half of the focus-state border stroke against the
        //   widget's own shape quad (visible as a ring clipped on
        //   all four sides).
        let sized_id = ctx.add(
            MinSize::new(
                min_width,
                crate::styles::TextInputRecipe::for_tokens(&ctx.theme().input).height,
            )
            .child(zstack_id),
        );
        // Stash the resolved cap + floor on `self` for
        // `size_that_fits` to read at layout time.
        self.pixel_cap = pixel_cap;
        self.min_width = min_width;

        // ── Root: attach key + wheel handlers on the outer sized id ─
        //
        // Preview-pass `on_key_preview` claims Up / Down / PageUp /
        // PageDown before the focused `TextInputField` ever sees them;
        // the handler below says why preview rather than bubble.
        let root_id = sized_id;
        self.root_child_id = Some(root_id);

        let step_for_key = step.clone();
        let step_for_wheel = step.clone();
        let set_committed_for_a11y = set_committed.clone();
        let commit_text_for_a11y = commit_text.clone();

        let handlers = HandlerSet::new()
            // The SpinBox is not itself focusable — focus lands inside the
            // inner TextInputField. `focus_within` writes `true` whenever
            // any descendant (in practice, the field) holds focus, driving
            // the unified outer focus ring + the suffix / text-formatting
            // effects that previously read an `interaction_signal` piped
            // out of the field.
            .focus_within(self.focused.clone())
            // Preview-pass dispatch — claims ArrowUp/ArrowDown/PageUp/PageDown
            // for stepping BEFORE the focused TextInputField sees them. The
            // bubble-pass `on_key` previously relied on the field happening
            // not to bind arrow keys; preview makes the contract explicit so
            // future field changes (multiline caret motion, etc.) cannot
            // silently break stepping. Non-arrow keys return `Ignored` and
            // fall through to the field for normal text input.
            .on_key_preview(move |event, ctx| {
                // `enabled` needs no test: the dispatcher gates on
                // `arena.is_enabled` before any handler runs.
                if read_only {
                    return EventResponse::Ignored;
                }
                let WidgetEvent::KeyDown { key, modifiers, .. } = event else {
                    return EventResponse::Ignored;
                };
                // `TextEditable` is what leaves `Home` / `End` to the caret,
                // and `Vertical` is what leaves it the horizontal arrows. Both
                // are decisions rather than omissions, and both are asserted in
                // `common::range_nav`'s own tests. `rtl` is never consulted:
                // no horizontal arrow is claimed.
                match range_nav::range_move(
                    *key,
                    *modifiers,
                    RangeKind::TextEditable,
                    RangeAxis::Vertical,
                    false,
                ) {
                    Some(RangeMove::Step { increase }) => {
                        (step_for_key)(if increase { 1 } else { -1 }, false, ctx);
                        EventResponse::Handled
                    }
                    Some(RangeMove::Page { increase }) => {
                        (step_for_key)(if increase { 1 } else { -1 }, true, ctx);
                        EventResponse::Handled
                    }
                    // A `TextEditable` never reaches an extremum — swept in
                    // `range_nav`'s tests — so this arm states the contract
                    // rather than guarding a case that can occur.
                    Some(RangeMove::ToMin | RangeMove::ToMax) | None => EventResponse::Ignored,
                }
            })
            .on_scroll({
                let focused = self.focused.clone();
                move |event, ctx| {
                    // `enabled` is deliberately absent, for the reason the key
                    // handler above states: the dispatcher gates on
                    // `arena.is_enabled` before any handler runs, and the local
                    // is a *build-time* snapshot — a `Signal`-bound spin box
                    // enabled after it was built would keep a dead wheel.
                    if read_only || wheel_mode == WheelMode::Disabled {
                        return EventResponse::Ignored;
                    }
                    // `Focused` wheel mode only fires when the
                    // inner field currently holds focus. `Hover` is
                    // the natural fallthrough — scroll events reach
                    // the widget only when the pointer is over it.
                    if wheel_mode == WheelMode::Focused && !focused.get() {
                        return EventResponse::Ignored;
                    }
                    let WidgetEvent::Scroll { delta, .. } = event else {
                        return EventResponse::Ignored;
                    };
                    let y = match delta {
                        ScrollDelta::Lines { y, .. } => *y,
                        ScrollDelta::Pixels { y, .. } => *y,
                    };
                    if y == 0.0 {
                        return EventResponse::Ignored;
                    }
                    // Teksilo's `ScrollDelta` is a *scroll offset* delta, not
                    // a raw wheel reading: `translate_mouse_wheel` negates
                    // winit's natural sign so that **positive y scrolls
                    // down** (the offset grows, content moves up) — which is
                    // what `ScrollArea` and every data view add straight to
                    // their scroll position. So a wheel-down notch arrives
                    // as `y > 0` and must *decrement*, matching every other
                    // stepper on the platform.
                    let dir = if y > 0.0 { -1 } else { 1 };
                    (step_for_wheel)(dir, false, ctx);
                    EventResponse::Handled
                }
            })
            // Full-payload AccessKit handler. `SetValue` carries its value in
            // `ActionData`, which `on_access_action` cannot see, so Increment
            // and Decrement sit beside it here: the whole action set reads as
            // one match rather than being split across two slots. Both payload
            // shapes are serviced, because both are sent in the field:
            //   * `NumericValue(f64)` — macOS `setAccessibilityValue:` with an
            //     `NSNumber` (a `Role::SpinButton` publishes a numeric
            //     `AXValue`), and AT-SPI's `Value.SetCurrentValue`, which is how
            //     Orca sets a spin button. AT-SPI publishes the `Value`
            //     interface off `numeric_value` alone, so that door is open
            //     whether or not the action is advertised.
            //   * `Value(Box<str>)` — macOS with an `NSString`, and Teksilo's
            //     own automation `set_value` tool, which sends only this shape.
            // These arrive from the field, which is the spin button node and
            // leaves stepping to its host: an action unhandled there bubbles up
            // to here. `Action::Focus` has no arm: the dispatcher services it
            // before any widget sees it, on the field, which is focusable.
            .on_access_action_request(move |action, _target_node, data, ctx| {
                use teksilo_core::accesskit::{Action, ActionData};
                // A read-only spin box refuses every mutating action rather
                // than reporting a success that never happened — the contract
                // an automation client relies on to learn its call did nothing.
                if read_only {
                    return EventResponse::Ignored;
                }
                match (action, data) {
                    (Action::Increment, _) => {
                        (step)(1, false, ctx);
                        EventResponse::Handled
                    }
                    (Action::Decrement, _) => {
                        (step)(-1, false, ctx);
                        EventResponse::Handled
                    }
                    // A number goes straight to the commit tail: clamp,
                    // reformat, publish, notify.
                    (Action::SetValue, Some(ActionData::NumericValue(v))) => {
                        // `from_f64_saturating` maps NaN to zero; writing 0 for
                        // a malformed request is worse than declining it.
                        if !v.is_finite() {
                            return EventResponse::Ignored;
                        }
                        (set_committed_for_a11y)(T::from_f64_saturating(v), ctx);
                        ctx.request_frame();
                        EventResponse::Handled
                    }
                    // A string takes the same parse Enter takes, so a custom
                    // `value_from_text` and the locale's decimal separator are
                    // honoured. An unparseable string reverts the display and
                    // is reported unhandled, so the caller hears about it
                    // instead of watching a silent no-op.
                    (Action::SetValue, Some(ActionData::Value(v))) => {
                        let parsed = (commit_text_for_a11y)(v.as_ref(), ctx);
                        ctx.request_frame();
                        if parsed {
                            EventResponse::Handled
                        } else {
                            EventResponse::Ignored
                        }
                    }
                    _ => EventResponse::Ignored,
                }
            });
        // Bind `value` to the field, which publishes the spin button's numeric
        // value, so that node refreshes on every change even when the text
        // does not (a formatter can show two values alike).
        self.value.bind_to(
            field_id,
            ctx.binding_registry(),
            teksilo_core::binding::BindingLevel::AccessibilityOnly,
        );

        ctx.apply_self_handlers(handlers);

        // ── Tooltip attachment ─────────────────────────────────────
        if let Some(content) = self.composite_tooltip_content.take() {
            let delay = ctx.theme().motion.tooltip_delay_heavy;
            crate::tooltip::attach_composite_tooltip_boxed(ctx, root_id, content, delay);
        } else if let Some(source) = self.rich_tooltip_source.clone() {
            let delay = ctx.theme().motion.tooltip_delay;
            crate::tooltip::attach_rich_tooltip_source(ctx, root_id, source, delay);
        } else if let Some(text) = self.tooltip_text.clone() {
            let delay = ctx.theme().motion.tooltip_delay;
            crate::tooltip::attach_plain_tooltip(ctx, root_id, text, delay);
        }

        vec![root_id]
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        // Narrow the parent's proposal by `pixel_cap` (if any)
        // before delegating. This enforces the `.width(...)` /
        // `.width_chars(...)` caps without wrapping the subtree
        // in a clipping `MaxSize` — the focus-state border stroke
        // can then extend 1 dp outside the visual bounds
        // (Int UI focus thickening) without being chopped off
        // against the shape quad.
        // `pixel_cap` / `min_width` are measured at 1.0 scale in `build()`. The
        // inner field grows its text by `ctx.text_scale`, so the cap must grow
        // too or the scaled digits clip against an un-grown width cap.
        let scale = ctx.text_scale;
        let pixel_cap = self.pixel_cap.map(|c| c * scale);
        let min_width = self.min_width * scale;
        let effective_proposal = SizeProposal {
            width: match (proposal.width, pixel_cap) {
                (Some(w), Some(cap)) => Some(w.min(cap).max(min_width)),
                (None, Some(cap)) => Some(cap.max(min_width)),
                (w, None) => w,
            },
            height: proposal.height,
        };
        let child_size = self
            .root_child_id
            .and_then(|id| ctx.child_size(id, effective_proposal))
            .unwrap_or_else(|| effective_proposal.resolve(0.0, 0.0));
        // Claim the (cap-narrowed) proposal width on the cross axis — the
        // inner `ZStack` queries its children with `SizeProposal::unspecified`,
        // so the offered width never reaches the inner `HStack` during
        // measurement; without this clamp the chain returns just
        // `MinSize`'s floor and the SpinBox collapses regardless of
        // `WidthPolicy::Fill` or `Pixels`/`Chars` caps.
        let w = match effective_proposal.width {
            Some(pw) => pw.max(child_size.width),
            None => child_size.width,
        };
        Size::new(w, child_size.height).into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        _ctx: &LayoutContext,
    ) {
        if let Some(p) = children.first_mut() {
            p.origin = Point::new(bounds.x, bounds.y);
            p.size = bounds.size();
        }
    }

    fn children(&self) -> Vec<WidgetId> {
        self.root_child_id.into_iter().collect()
    }

    /// Structure. The spin button is the editing field, which holds focus
    /// and says the name, the value and the range (see `build`); a second
    /// node saying them around it is what made a screen reader either name
    /// the field twice or not at all. `GenericContainer` is what the
    /// presentational pass collapses.
    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        builder.set_role(teksilo_core::accesskit::Role::GenericContainer);
    }

    /// The editing field stands for the spin box, so what an application
    /// attaches to the spin box's id (`access_label`, a `FormLayout`'s
    /// `labelled_by`, `access_described_by`, the tooltip) lands on the node
    /// that holds focus.
    fn accessibility_proxy(&self) -> Option<WidgetId> {
        self.field_id
    }
}

// ── Helpers ────────────────────────────────────────────────────────

/// Build the stacked up/down step buttons. Returns the two
/// `WidgetId`s (up, down) for the caller to pass to the active
/// `SpinBoxStyle` through `SpinBoxStyleConfig`, which owns the row.
///
/// `step` (with `EventContext`) is called on the initial tap;
/// `step_silent` is called from the hold-to-repeat timer, which
/// runs inside a frame-tick effect with no `EventContext` to hand.
fn build_step_buttons<T: SpinValue>(
    ctx: &mut BuildContext,
    step: &Rc<dyn Fn(i32, bool, &mut EventContext)>,
    step_silent: &Rc<dyn Fn(i32, bool) -> StepOutcome<T>>,
    can_up: Signal<bool>,
    can_down: Signal<bool>,
    enabled: bool,
    frame_height: f32,
    corner_radius: f32,
) -> (WidgetId, WidgetId) {
    // Each button is half of the field's inner height (minus the
    // borders and a 1 px gutter between the two).
    let button_height = ((frame_height - 2.0) * 0.5).max(8.0);
    let button_width = SPIN_BOX_STEP_BUTTON_WIDTH;

    let up_icon = chevron_up_icon(8.0);
    let down_icon = chevron_down_icon(8.0);

    // Derived enabled signals: OR with the caller-wide `enabled`.
    let up_enabled = if enabled { can_up } else { Signal::new(false) };
    let down_enabled = if enabled {
        can_down
    } else {
        Signal::new(false)
    };

    let step_for_up_tap = step.clone();
    let silent_for_up_auto = step_silent.clone();
    let up_button = StepButton::new(up_icon, up_enabled, move |ctx| {
        (step_for_up_tap)(1, false, ctx);
    })
    .on_auto_repeat(move || {
        (silent_for_up_auto)(1, false);
    })
    .size(button_width, button_height)
    .corner_radius(CornerRadius {
        top_left: 0.0,
        top_right: corner_radius,
        bottom_left: 0.0,
        bottom_right: 0.0,
    });

    let step_for_down_tap = step.clone();
    let silent_for_down_auto = step_silent.clone();
    let down_button = StepButton::new(down_icon, down_enabled, move |ctx| {
        (step_for_down_tap)(-1, false, ctx);
    })
    .on_auto_repeat(move || {
        (silent_for_down_auto)(-1, false);
    })
    .size(button_width, button_height)
    .corner_radius(CornerRadius {
        top_left: 0.0,
        top_right: 0.0,
        bottom_left: 0.0,
        bottom_right: corner_radius,
    });

    (ctx.add(up_button), ctx.add(down_button))
}

/// Small chevron-up icon at `size` px. Mirrors the shape of the
/// `chevron_down` icon provided by `IconWidget`.
fn chevron_up_icon(size: f32) -> IconWidget {
    let mut path = Path::new();
    let s = size;
    path.move_to(Point::new(s * 0.25, s * 0.65));
    path.line_to(Point::new(s * 0.5, s * 0.35));
    path.line_to(Point::new(s * 0.75, s * 0.65));
    IconWidget::from_path(path, size)
}

fn chevron_down_icon(size: f32) -> IconWidget {
    let mut path = Path::new();
    let s = size;
    path.move_to(Point::new(s * 0.25, s * 0.35));
    path.line_to(Point::new(s * 0.5, s * 0.65));
    path.line_to(Point::new(s * 0.75, s * 0.35));
    IconWidget::from_path(path, size)
}

/// How the number itself is rendered and read back: the locale's
/// conventions, or the C locale.
///
/// Held in one [`LivePresentation`] per spin box and read from there by
/// the format and parse paths together, so the two can never disagree
/// about which separator this field is using: the single-source
/// discipline `DateEdit` gets from its one `ParsedPattern`.
#[derive(Clone)]
pub(crate) struct NumberPresentation {
    symbols: Option<Rc<teksilo_i18n::NumberSymbols>>,
    grouping: bool,
}

impl NumberPresentation {
    /// Resolve against the active locale. `localized == false` yields a
    /// presentation that is the identity in both directions.
    pub(crate) fn resolve(localized: bool, grouping: bool) -> Self {
        Self {
            symbols: localized.then(teksilo_i18n::NumberSymbols::current),
            grouping,
        }
    }

    /// C-locale digits in, display string out.
    fn render(&self, plain: String) -> String {
        match &self.symbols {
            Some(sym) => sym.localize(&plain, self.grouping),
            None => plain,
        }
    }

    /// Display string in, C-locale digits out. `None` when the text
    /// cannot be a number in this locale.
    fn read(&self, raw: &str) -> Option<String> {
        match &self.symbols {
            Some(sym) => sym.delocalize(raw),
            None => Some(raw.trim().to_string()),
        }
    }

    /// Parse user input into a value, going through the locale first.
    fn parse<T: SpinValue>(&self, raw: &str) -> Option<T> {
        T::parse(&self.read(raw)?)
    }

    /// Per-character input filter. Widens the type's own filter with the
    /// characters this locale writes numbers with, so a French user can
    /// type `,` and an Egyptian user can type `٫` or Arabic-Indic
    /// digits — while the ASCII forms keep working everywhere, because
    /// people type on the keyboard they have.
    fn accepts_char<T: SpinValue>(&self, c: char) -> bool {
        if T::is_valid_input_char(c) {
            return true;
        }
        let Some(sym) = &self.symbols else {
            return false;
        };
        if sym.has_non_ascii_digits() && sym.delocalize(&c.to_string()).is_some() {
            return true;
        }
        // The group separator is only typeable when this field shows
        // groups; otherwise it is noise the user cannot have meant.
        [
            Some(sym.decimal_separator()),
            Some(sym.minus_sign()),
            Some(sym.plus_sign()),
            self.grouping.then(|| sym.group_separator()),
        ]
        .into_iter()
        .flatten()
        .any(|sep| sep.chars().any(|sc| sc == c))
    }
}

/// The [`NumberPresentation`] one spin box renders and reads its number
/// with, shared by every path that does either and replaced in place when
/// the locale changes. See `build` for why a copy per path does not do.
#[derive(Clone)]
struct LivePresentation(Rc<RefCell<NumberPresentation>>);

impl LivePresentation {
    fn new(presentation: NumberPresentation) -> Self {
        Self(Rc::new(RefCell::new(presentation)))
    }

    /// The presentation in force now. A clone, two words, so no borrow is
    /// held across the call that uses it.
    fn get(&self) -> NumberPresentation {
        self.0.borrow().clone()
    }

    fn set(&self, presentation: NumberPresentation) {
        self.0.replace(presentation);
    }
}

/// Format `value` for display, honoring `special_value_text` when
/// applicable and deferring to a user-supplied formatter when set.
///
/// A user-supplied `custom` formatter owns the whole string and is
/// **not** localized afterwards: it already returns exactly what the
/// caller wants shown, and re-punctuating it would corrupt formats the
/// caller composed deliberately.
fn format_for_display<T: SpinValue>(
    value: T,
    decimals: u8,
    special: Option<&LocalizedString>,
    custom: Option<&dyn Fn(T) -> LocalizedString>,
    min: T,
    presentation: &NumberPresentation,
) -> String {
    if let Some(special_text) = special
        && approx_eq(value, min)
    {
        return special_text.resolve_now();
    }
    match custom {
        Some(f) => f(value).resolve_now(),
        None => presentation.render(value.format(decimals)),
    }
}

/// Decide the effective step for an [`Adaptive`](StepType::Adaptive)
/// step type given the current value. For a value ∈ [10^n,
/// 10^(n+1)) the effective step is 10^n from 10 upwards; below 10
/// the step stays at `base_step`, which also keeps it from
/// vanishing inside [0, 1).
fn resolve_effective_step<T: SpinValue>(step_type: StepType, current: T, base_step: T) -> T {
    if step_type == StepType::Fixed {
        return base_step;
    }
    let abs = current.to_f64().abs();
    if abs < 10.0 {
        return base_step;
    }
    let pow = abs.log10().floor();
    let magnitude = 10f64.powf(pow);
    let adaptive = T::from_f64_saturating(magnitude);
    // Fall back to the user's base step if adaptive truncates to
    // zero (possible for integer types when pow < 0).
    let adaptive_f = adaptive.to_f64();
    if adaptive_f.abs() < 1e-12 {
        base_step
    } else {
        adaptive
    }
}

/// Approximate equality. Integer types compare bit-exactly;
/// floats tolerate sub-unit-in-last-place jitter. Used throughout
/// to suppress redundant signal sets.
fn approx_eq<T: SpinValue>(a: T, b: T) -> bool {
    if T::is_integer() {
        a.to_f64() == b.to_f64()
    } else {
        // Relative epsilon scaled by value magnitude so both near-zero
        // and large-value comparisons behave.
        let af = a.to_f64();
        let bf = b.to_f64();
        let scale = af.abs().max(bf.abs()).max(1.0);
        (af - bf).abs() <= scale * 1e-9
    }
}

fn approx_ne<T: SpinValue>(a: T, b: T) -> bool {
    !approx_eq(a, b)
}

/// Measure the advance width of `text` in logical pixels using the
/// app-wide `SharedTypesetter` (the same backend the field paints
/// with). Falls back to a rough heuristic when no typesetter is
/// installed (headless tests) so the caller still gets a non-zero
/// width and the resolved `pixel_cap` behaves reasonably.
fn measure_width_px(ctx: &mut BuildContext, text: &str, style: &TextStyle) -> f32 {
    if text.is_empty() {
        return 0.0;
    }
    if let Some(ts) = ctx.app_state::<SharedTypesetter>() {
        let backend = ts.as_text_backend();
        let layout = backend.borrow_mut().layout_single_line(text, style, None);
        return layout.width;
    }
    // Headless fallback: ~0.55 × font size per ASCII char is a
    // close approximation for Inter Regular at body weight.
    text.chars().count() as f32 * style.size * 0.55
}