//! Stepper / wizard widget — a horizontal multi-step progress indicator: a row

//! of numbered step circles with labels, joined by connector lines. Completed

//! and current steps are highlighted in the accent colour; upcoming steps (and

//! the connectors that lead to them) are muted.

//!

//! This is a blend of [`crate::widgets::segmented::Segmented`] (a horizontal row

//! of clickable items whose clicked index is derived from sibling position and

//! whose active item is live-restyled via `set_css_property`) and the filled-track

//! look of [`crate::widgets::progressbar::ProgressBar`] (the accent connector).

//!

//! Steps are CLICKABLE (free navigation, like a segmented control): clicking

//! step `i` sets `current_step = i`, invokes the optional `on_step_change(state)`,

//! and live-restyles every circle / connector / label to reflect the new

//! position — no DOM rebuild. (A non-clickable, display-only stepper is also a

//! valid design; this widget chooses clickable to exercise the segmented restyle

//! pattern, and `set_current_step` still drives it from app code on rebuild.)

//!

//! A circle is "reached" (accent) iff its index `<= current_step`; the connector

//! gap between circle `i` and `i+1` is accent iff `i < current_step`. Clicking the

//! already-current step is a no-op (no callback).

//!

//! Key types: [`Stepper`], [`StepperState`], [`StepperOnStepChange`].

use std::vec::Vec;

use azul_core::{

    callbacks::{CoreCallbackData, Update},

    dom::{Dom, IdOrClass, IdOrClass::Class, IdOrClassVec, TabIndex},

    refany::RefAny,

};

use azul_css::dynamic_selector::{CssPropertyWithConditions, CssPropertyWithConditionsVec};

use azul_css::{

    props::{

        basic::{color::ColorU, PixelValue, StyleFontSize},

        layout::{LayoutDisplay, LayoutFlexDirection, LayoutAlignItems, LayoutFlexGrow, LayoutFlexBasis, LayoutWidth, LayoutJustifyContent, LayoutHeight, LayoutMinWidth, LayoutPaddingTop},

        property::{CssProperty, LayoutFlexBasisValue, LayoutWidthValue},

        style::{StyleBackgroundContent, StyleBackgroundContentVec, StyleCursor, StyleBorderTopLeftRadius, StyleBorderTopRightRadius, StyleBorderBottomLeftRadius, StyleBorderBottomRightRadius, StyleTextAlign, StyleUserSelect, StyleTextColor},

    },

    impl_option_inner, AzString, StringVec,

};

use crate::callbacks::CallbackInfo;

static STEPPER_CLASS: &[IdOrClass] = &[Class(AzString::from_const_str("__azul-native-stepper"))];

static STEPPER_STEP_CLASS: &[IdOrClass] =

    &[Class(AzString::from_const_str("__azul-native-stepper-step"))];

static STEPPER_ROW_CLASS: &[IdOrClass] =

    &[Class(AzString::from_const_str("__azul-native-stepper-row"))];

static STEPPER_CIRCLE_CLASS: &[IdOrClass] =

    &[Class(AzString::from_const_str("__azul-native-stepper-circle"))];

static STEPPER_CONNECTOR_CLASS: &[IdOrClass] =

    &[Class(AzString::from_const_str("__azul-native-stepper-connector"))];

static STEPPER_LABEL_CLASS: &[IdOrClass] =

    &[Class(AzString::from_const_str("__azul-native-stepper-label"))];

/// Callback function type invoked when the current step changes.

pub type StepperOnStepChangeCallbackType =

    extern "C" fn(RefAny, CallbackInfo, StepperState) -> Update;

impl_widget_callback!(

    StepperOnStepChange,

    OptionStepperOnStepChange,

    StepperOnStepChangeCallback,

    StepperOnStepChangeCallbackType

);

azul_core::impl_managed_callback! {

    wrapper:        StepperOnStepChangeCallback,

    info_ty:        CallbackInfo,

    return_ty:      Update,

    default_ret:    Update::DoNothing,

    invoker_static: STEPPER_ON_STEP_CHANGE_INVOKER,

    invoker_ty:     AzStepperOnStepChangeCallbackInvoker,

    thunk_fn:       az_stepper_on_step_change_callback_thunk,

    setter_fn:      AzApp_setStepperOnStepChangeCallbackInvoker,

    from_handle_fn: AzStepperOnStepChangeCallback_createFromHostHandle,

    extra_args:     [ state: StepperState ],

}

/// A horizontal numbered-step progress indicator with a step-change callback.

#[derive(Debug, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct Stepper {

    pub stepper_state: StepperStateWrapper,

    /// The label of each step, in order. The step count is `labels.len()`.

    pub labels: StringVec,

    /// Style for the row container.

    pub container_style: CssPropertyWithConditionsVec,

}

#[derive(Debug, Default, Clone, PartialEq, Eq)]

#[repr(C)]

pub struct StepperStateWrapper {

    /// The current step + total step count.

    pub inner: StepperState,

    /// Optional: function to call when the current step changes.

    pub on_step_change: OptionStepperOnStepChange,

}

/// State of a [`Stepper`]: the zero-based current step and the total step count.

#[derive(Debug, Copy, Clone, PartialEq, Eq, Default)]

#[repr(C)]

pub struct StepperState {

    /// Zero-based index of the current (active) step.

    pub current_step: usize,

    /// Total number of steps.

    pub total_steps: usize,

}

// ---- colours ----

/// Accent (reached/current) colour (#0d6efd).

const ACCENT_COLOR: ColorU = ColorU { r: 13, g: 110, b: 253, a: 255 };

/// Accent text colour (white) — the number inside a reached circle.

const WHITE: ColorU = ColorU { r: 255, g: 255, b: 255, a: 255 };

/// Upcoming-circle background (#e9ecef, light grey).

const MUTED_CIRCLE_COLOR: ColorU = ColorU { r: 233, g: 236, b: 239, a: 255 };

/// Muted text colour (#868e96) — upcoming numbers/labels.

const MUTED_TEXT_COLOR: ColorU = ColorU { r: 134, g: 142, b: 150, a: 255 };

/// Reached-label text colour (#212529, dark).

const DARK_TEXT_COLOR: ColorU = ColorU { r: 33, g: 37, b: 41, a: 255 };

/// Upcoming-connector colour (#ced4da).

const CONNECTOR_MUTED_COLOR: ColorU = ColorU { r: 206, g: 212, b: 218, a: 255 };

/// Transparent — used for the (absent) connector at the row's two ends.

const TRANSPARENT_COLOR: ColorU = ColorU { r: 0, g: 0, b: 0, a: 0 };

const ACCENT_BG_ITEMS: &[StyleBackgroundContent] = &[StyleBackgroundContent::Color(ACCENT_COLOR)];

const ACCENT_BG: StyleBackgroundContentVec =

    StyleBackgroundContentVec::from_const_slice(ACCENT_BG_ITEMS);

const MUTED_CIRCLE_BG_ITEMS: &[StyleBackgroundContent] =

    &[StyleBackgroundContent::Color(MUTED_CIRCLE_COLOR)];

const MUTED_CIRCLE_BG: StyleBackgroundContentVec =

    StyleBackgroundContentVec::from_const_slice(MUTED_CIRCLE_BG_ITEMS);

const CONNECTOR_MUTED_BG_ITEMS: &[StyleBackgroundContent] =

    &[StyleBackgroundContent::Color(CONNECTOR_MUTED_COLOR)];

const CONNECTOR_MUTED_BG: StyleBackgroundContentVec =

    StyleBackgroundContentVec::from_const_slice(CONNECTOR_MUTED_BG_ITEMS);

const TRANSPARENT_BG_ITEMS: &[StyleBackgroundContent] =

    &[StyleBackgroundContent::Color(TRANSPARENT_COLOR)];

const TRANSPARENT_BG: StyleBackgroundContentVec =

    StyleBackgroundContentVec::from_const_slice(TRANSPARENT_BG_ITEMS);

const CIRCLE_SIZE: isize = 28;

const CIRCLE_RADIUS: isize = 14;

const CONNECTOR_HEIGHT: isize = 2;

/// Connector fill state for one half-segment.

#[derive(Copy, Clone)]

enum ConnFill {

    /// Reached (accent).

    Accent,

    /// Not reached (muted grey).

    Muted,

    /// At a row end — drawn transparent so the line doesn't stick out.

    Hidden,

}

impl ConnFill {

        }

}

/// Row container: a horizontal flex row whose steps spread evenly.

static STEPPER_CONTAINER_STYLE: &[CssPropertyWithConditions] = &[

    CssPropertyWithConditions::simple(CssProperty::const_display(LayoutDisplay::Flex)),

    CssPropertyWithConditions::simple(CssProperty::const_flex_direction(LayoutFlexDirection::Row)),

    CssPropertyWithConditions::simple(CssProperty::const_align_items(LayoutAlignItems::Start)),

    CssPropertyWithConditions::simple(CssProperty::const_flex_grow(LayoutFlexGrow::const_new(0))),

];

/// One step cell: a vertical flex column (indicator row over label) that grows to

/// an equal share of the row (`flex-grow: 1; flex-basis: 0`).

static STEPPER_STEP_STYLE: &[CssPropertyWithConditions] = &[

    CssPropertyWithConditions::simple(CssProperty::const_display(LayoutDisplay::Flex)),

    CssPropertyWithConditions::simple(CssProperty::const_flex_direction(LayoutFlexDirection::Column)),

    CssPropertyWithConditions::simple(CssProperty::const_align_items(LayoutAlignItems::Center)),

    CssPropertyWithConditions::simple(CssProperty::const_flex_grow(LayoutFlexGrow::const_new(1))),

    CssPropertyWithConditions::simple(CssProperty::FlexBasis(LayoutFlexBasisValue::Exact(

        LayoutFlexBasis::Exact(PixelValue::const_px(0)),

    ))),

    CssPropertyWithConditions::simple(CssProperty::const_cursor(StyleCursor::Pointer)),

];

/// Builds the indicator-row style: a full-width flex row that vertically centres

/// the connectors (height `CONNECTOR_HEIGHT`) on the circle.

        )),

        // Full cell width so the flex-grow connectors actually have space to fill.

    ])

/// Builds the style for one numbered circle. Background + number colour are the

/// only reached-dependent properties.

    } else {

    };

        )),

        )),

            CIRCLE_SIZE,

        ))),

            CIRCLE_SIZE,

        ))),

            CIRCLE_SIZE,

        ))),

        )),

        )),

        )),

        )),

    ])

/// Builds the style for one connector half-line (left or right of a circle).

            CONNECTOR_HEIGHT,

        ))),

    ])

/// Builds the style for one step label.

            6,

        ))),

    ])

/// Connector fill for the left half-line of step `i` (the gap entering circle `i`).

    } else {

    }

/// Connector fill for the right half-line of step `i` (the gap leaving circle `i`).

    } else {

    }

impl Stepper {

    /// Creates a stepper from the given step labels, with the first step current.

    /// Sets the current (zero-based) step, clamped into `[0, total_steps - 1]`.

    #[inline]

        } else {

        };

    /// Builder-style setter for the current step.

    #[inline]

    #[inline]

    #[inline]

    #[inline]

        use azul_core::{

            callbacks::CoreCallback,

            dom::{EventFilter, HoverEventFilter},

            refany::OptionRefAny,

        };

        // One shared RefAny across every step's callback (RefAny::clone shares the

        // underlying state — same pattern as segmented/pagination/map).

}

impl Default for Stepper {

}

/// Click handler shared by all step cells. Resolves the clicked cell from its

/// sibling position (= the zero-based step index), and — only if the step

/// actually changed — updates the state, invokes the user callback, and

/// live-restyles every circle / connector / label (the segmented pattern).

    use azul_core::dom::DomNodeId;

    };

    // Collect the step cells in document order.

    };

        };

    };

        // Clicked the already-current step — no change, no callback.

        };

            }

        }

    };

    // Live-restyle every cell: circle (reached → accent fill + white number),

    // its two connector half-lines, and its label colour.

        };

            } else {

            };

            );

            );

    }

impl From<Stepper> for Dom {

}

#[cfg(test)]

mod autotest_generated {

    use std::{

        collections::{BTreeMap, HashMap, HashSet},

        sync::{Arc, Mutex},

    };

    use azul_core::{

        dom::{DomId, DomNodeId, EventFilter, HoverEventFilter, NodeId, NodeType},

        geom::{LogicalRect, OptionLogicalPosition},

        gl::OptionGlContextPtr,

        hit_test::ScrollPosition,

        refany::OptionRefAny,

        resources::RendererResources,

        styled_dom::{NodeHierarchyItemId, StyledDom},

        window::{MonitorVec, RawWindowHandle},

    };

    use azul_css::{

        props::basic::{length::SizeMetric, pixel::PixelValue},

        system::SystemStyle,

    };

    use rust_fontconfig::FcFontCache;

    use super::*;

    #[cfg(feature = "icu")]

    use crate::icu::IcuLocalizerHandle;

    use crate::{

        callbacks::{CallbackChange, CallbackInfoRefData, ExternalSystemCallbacks},

        solver3::{display_list::DisplayList, layout_tree::LayoutTree},

        window::{DomLayoutResult, LayoutWindow},

        window_state::FullWindowState,

    };

    // ------------------------------------------------------------------

    // Const-evaluated extremes

    //

    // `conn_left_fill` / `conn_right_fill` are `const fn`, so evaluating them at

    // the integer extremes in a `const` item makes the compiler itself prove

    // there is no overflow / no const-eval panic on the whole `usize` range.

    // ------------------------------------------------------------------

    const _LEFT_AT_MAX: ConnFill = conn_left_fill(usize::MAX, usize::MAX);

    const _LEFT_MAX_AT_ZERO: ConnFill = conn_left_fill(usize::MAX, 0);

    const _LEFT_ZERO_AT_MAX: ConnFill = conn_left_fill(0, usize::MAX);

    const _RIGHT_AT_MAX: ConnFill = conn_right_fill(usize::MAX, usize::MAX, usize::MAX);

    const _RIGHT_MAX_AT_ZERO: ConnFill = conn_right_fill(usize::MAX, 0, 0);

    const _RIGHT_ZERO_AT_MAX: ConnFill = conn_right_fill(0, usize::MAX, usize::MAX);

    // ------------------------------------------------------------------

    // Flattened node layout

    //

    // `convert_dom_into_compact_dom` walks the tree in pre-order, and one step

    // cell contributes exactly eight nodes — the circle and the label are both

    // `<p>` boxes wrapping one bare text node each (the widget label convention):

    //

    //     cell → row → [conn-left, circle <p> → text, conn-right] , label <p> → text

    //

    // so step `i` occupies `1 + 8*i ..= 8 + 8*i`. `flattened_layout_is_eight_nodes_per_step`

    // pins this against the real hierarchy so the click tests below cannot drift.

    // ------------------------------------------------------------------

    const NODES_PER_STEP: usize = 8;

    fn cell_node(i: usize) -> usize {

        1 + NODES_PER_STEP * i

    }

    fn row_node(i: usize) -> usize {

        2 + NODES_PER_STEP * i

    }

    fn conn_left_node(i: usize) -> usize {

        3 + NODES_PER_STEP * i

    }

    /// The circle's `<p>` box — the node the restyle writes to.

    fn circle_node(i: usize) -> usize {

        4 + NODES_PER_STEP * i

    }

    fn conn_right_node(i: usize) -> usize {

        6 + NODES_PER_STEP * i

    }

    /// The label's `<p>` box — the node the restyle writes to.

    fn label_node(i: usize) -> usize {

        7 + NODES_PER_STEP * i

    }

    // ------------------------------------------------------------------

    // Helpers

    // ------------------------------------------------------------------

    fn labels(v: &[&str]) -> StringVec {

        StringVec::from_vec(v.iter().map(|s| AzString::from(*s)).collect::<Vec<_>>())

    }

    /// `n` distinct labels: `s0, s1, … s{n-1}`.

    fn n_labels(n: usize) -> StringVec {

        StringVec::from_vec((0..n).map(|i| AzString::from(format!("s{i}"))).collect::<Vec<_>>())

    }

    fn stepper(v: &[&str]) -> Stepper {

        Stepper::create(labels(v))

    }

    /// The declared properties of a style vec, in declaration order.

    fn properties(v: &CssPropertyWithConditionsVec) -> Vec<CssProperty> {

        v.as_ref().iter().map(|p| p.property.clone()).collect()

    }

    /// The *kind* of every declared property, in order (ignores the values).

    fn property_kinds(

        v: &CssPropertyWithConditionsVec,

    ) -> Vec<core::mem::Discriminant<CssProperty>> {

        v.as_ref().iter().map(|p| core::mem::discriminant(&p.property)).collect()

    }

    /// Asserts a style vec declares each property kind at most once and attaches

    /// no selector conditions. A duplicate is silently last-wins (hiding a value

    /// conflict); a stray condition leaves the node unstyled until some selector

    /// state happens to match.

    fn assert_unconditional_and_unique(v: &CssPropertyWithConditionsVec, ctx: &str) {

        let mut seen = HashSet::new();

        for p in v.as_ref() {

            assert!(

                p.apply_if.as_ref().is_empty(),

                "{ctx}: {:?} is conditional, not an unconditional declaration",

                p.property

            );

            assert!(

                seen.insert(core::mem::discriminant(&p.property)),

                "{ctx}: {:?} is declared twice",

                p.property

            );

        }

        assert_eq!(seen.len(), v.as_ref().len(), "{ctx}: declaration count / kind count disagree");

    }

    /// The single background layer of a background vec, asserting there is

    /// exactly one and that it is a flat colour (a gradient would not be `Color`).

    fn only_color(bg: &StyleBackgroundContentVec) -> ColorU {

        assert_eq!(bg.as_ref().len(), 1, "a stepper fill must be a single background layer");

        match &bg.as_ref()[0] {

            StyleBackgroundContent::Color(c) => *c,

            other => panic!("stepper background is not a flat colour: {other:?}"),

        }

    }

    /// `ConnFill` derives neither `Debug` nor `PartialEq`, so the three variants

    /// are compared through the one thing they actually control: the colour.

    fn fill_color(f: ConnFill) -> ColorU {

        only_color(&f.bg())

    }

    fn background_color(props: &[CssProperty]) -> Option<ColorU> {

        let found: Vec<&StyleBackgroundContentVec> = props

            .iter()

            .filter_map(|p| match p {

                CssProperty::BackgroundContent(v) => v.get_property(),

                _ => None,

            })

            .collect();

        assert!(found.len() <= 1, "a stepper node must declare at most one background");

        found.first().map(|bg| only_color(bg))

    }

    fn text_color(props: &[CssProperty]) -> Option<ColorU> {

        let found: Vec<ColorU> = props

            .iter()

            .filter_map(|p| match p {

                CssProperty::TextColor(v) => v.get_property().map(|c| c.inner),

                _ => None,

            })

            .collect();

        assert!(found.len() <= 1, "a stepper node must declare at most one text colour");

        found.first().copied()

    }

    /// The raw `PixelValue` of `width` / `height` (the sizing *enums*), so the

    /// metric can be asserted separately — the circle is absolute `px`, the

    /// indicator row is a `%`.

    fn width_value(props: &[CssProperty]) -> Option<PixelValue> {

        props.iter().find_map(|p| match p {

            CssProperty::Width(v) => match v.get_property() {

                Some(LayoutWidth::Px(pv)) => Some(*pv),

                _ => None,

            },

            _ => None,

        })

    }

    fn height_value(props: &[CssProperty]) -> Option<PixelValue> {

        props.iter().find_map(|p| match p {

            CssProperty::Height(v) => match v.get_property() {

                Some(LayoutHeight::Px(pv)) => Some(*pv),

                _ => None,

            },

            _ => None,

        })

    }

    fn min_width_value(props: &[CssProperty]) -> Option<PixelValue> {

        props.iter().find_map(|p| match p {

            CssProperty::MinWidth(v) => v.get_property().map(|x| x.inner),

            _ => None,

        })

    }

    fn font_size_value(props: &[CssProperty]) -> Option<PixelValue> {

        props.iter().find_map(|p| match p {

            CssProperty::FontSize(v) => v.get_property().map(|x| x.inner),

            _ => None,

        })

    }

    fn padding_top_value(props: &[CssProperty]) -> Option<PixelValue> {

        props.iter().find_map(|p| match p {

            CssProperty::PaddingTop(v) => v.get_property().map(|x| x.inner),

            _ => None,

        })

    }

    fn flex_grow_value(props: &[CssProperty]) -> Option<f32> {

        props.iter().find_map(|p| match p {

            CssProperty::FlexGrow(v) => v.get_property().map(|f| f.inner.get()),

            _ => None,

        })

    }

    /// The four corner radii as `(top-left, top-right, bottom-left, bottom-right)`.

    fn radii(props: &[CssProperty]) -> (Option<PixelValue>, Option<PixelValue>, Option<PixelValue>, Option<PixelValue>) {

        let find = |f: &dyn Fn(&CssProperty) -> Option<PixelValue>| props.iter().find_map(f);

        (

            find(&|p| match p {

                CssProperty::BorderTopLeftRadius(v) => v.get_property().map(|r| r.inner),

                _ => None,

            }),

            find(&|p| match p {

                CssProperty::BorderTopRightRadius(v) => v.get_property().map(|r| r.inner),

                _ => None,

            }),

            find(&|p| match p {

                CssProperty::BorderBottomLeftRadius(v) => v.get_property().map(|r| r.inner),

                _ => None,

            }),

            find(&|p| match p {

                CssProperty::BorderBottomRightRadius(v) => v.get_property().map(|r| r.inner),

                _ => None,

            }),

        )

    }

    /// The `f32` of a `PixelValue`, asserting it is an absolute `px` length. An

    /// `em`/`%` slipping into the circle geometry would resolve against the

    /// parent font/box instead of the intended fixed size.

    fn px(pv: PixelValue) -> f32 {

        assert_eq!(pv.metric, SizeMetric::Px, "stepper geometry must be absolute px, got {:?}", pv.metric);

        pv.number.get()

    }

    /// Perceived brightness (0..=255) of an sRGB colour, Rec.709 weights. Kept to

    /// plain `+`/`*` (no gamma expansion) so the readability assertions stay exact

    /// and toolchain-independent.

    fn luma(c: ColorU) -> f32 {

        0.2126 * f32::from(c.r) + 0.7152 * f32::from(c.g) + 0.0722 * f32::from(c.b)

    }

    /// The text of a text node, looking through the `<p>` block wrapper the

    /// label convention mandates (`p > text`).

    fn text_of(node: &Dom) -> Option<&str> {

        match node.root.get_node_type() {

            NodeType::Text(s) => Some(s.as_ref().as_str()),

            NodeType::P => match node.children.as_ref() {

                [only] => match only.root.get_node_type() {

                    NodeType::Text(s) => Some(s.as_ref().as_str()),

                    _ => None,

                },

                _ => None,

            },

            _ => None,

        }

    }

    /// The properties of a rendered node's *inline* style, in declaration order.

    fn inline_properties(node: &Dom) -> Vec<CssProperty> {

        node.root.style.iter_inline_properties().map(|(p, _)| p.clone()).collect()

    }

    /// The true recursive descendant count of a `Dom` — what

    /// `estimated_total_children` is documented to cache. Under-counting makes

    /// `convert_dom_into_compact_dom` under-allocate and panic.

    fn recursive_descendants(node: &Dom) -> usize {

        node.children.as_ref().iter().map(|c| 1 + recursive_descendants(c)).sum()

    }

    fn step_cell(dom: &Dom, i: usize) -> &Dom {

        &dom.children.as_ref()[i]

    }

    fn row_of(cell: &Dom) -> &Dom {

        &cell.children.as_ref()[0]

    }

    fn label_of(cell: &Dom) -> &Dom {

        &cell.children.as_ref()[1]

    }

    fn conn_left_of(row: &Dom) -> &Dom {

        &row.children.as_ref()[0]

    }

    fn circle_of(row: &Dom) -> &Dom {

        &row.children.as_ref()[1]

    }

    fn conn_right_of(row: &Dom) -> &Dom {

        &row.children.as_ref()[2]

    }

    /// Boundary + "negative" step indices. `usize` has no negative values, so a

    /// `-1` handed in through FFI arrives here as `usize::MAX`; both wrapped

    /// forms are included so the setter is exercised at the two's-complement ends.

    fn boundary_indices() -> Vec<usize> {

        vec![

            0,

            1,

            2,

            usize::MAX / 2,

            usize::MAX / 2 + 1,

            usize::MAX - 1,

            usize::MAX,

            (-1i64) as usize,

            i64::MIN as usize,

            u32::MAX as usize,

        ]

    }

    /// Adversarial step labels: empty, whitespace, combining marks, ZWJ emoji,

    /// RTL, embedded NULs (`AzString` is length-based, so a NUL must not

    /// truncate), control characters, and a string far longer than any plausible

    /// step caption.

    fn adversarial_strings() -> Vec<String> {

        let mut v: Vec<String> = [

            "",

            "Details",

            " ",

            "e\u{0301}",                                   // e + combining acute

            "\u{1F469}\u{200D}\u{1F469}\u{200D}\u{1F467}", // ZWJ family emoji

            "\u{5E9}\u{5DC}\u{5D5}\u{5DD}",                // RTL Hebrew

            "\0",                                          // a single NUL

            "a\0b",                                        // embedded NUL

            "\u{FFFD}\u{202E}\u{200B}",                    // replacement, RTL override, ZWSP

            "line\nbreak\ttab",                            // control characters

            "-9223372036854775808",                        // i64::MIN as a caption

        ]

        .iter()

        .map(|s| (*s).to_string())

        .collect();

        v.push("x".repeat(100_000));

        v

    }

    /// Forces the `fn`-item -> `fn`-pointer coercion the `Into` bound needs.

    fn cb(f: StepperOnStepChangeCallbackType) -> StepperOnStepChangeCallback {

        f.into()

    }

    /// A `RefAny` payload recording every state a user `on_step_change` observes.

    struct StepLog {

        seen: Vec<StepperState>,

    }

    extern "C" fn record_step(mut data: RefAny, _: CallbackInfo, state: StepperState) -> Update {

        if let Some(mut log) = data.downcast_mut::<StepLog>() {

            log.seen.push(state);

        }

        Update::RefreshDom

    }

    extern "C" fn step_do_nothing(_: RefAny, _: CallbackInfo, _: StepperState) -> Update {

        Update::DoNothing

    }

    extern "C" fn step_refresh_all(_: RefAny, _: CallbackInfo, state: StepperState) -> Update {

        // `current_step` is read (and discarded) purely so this body cannot be

        // identical-code-folded onto another handler; the tests below compare

        // callback function pointers for equality/inequality.

        let _ = state.current_step;

        Update::RefreshDomAllWindows

    }

    /// A payload whose callback tries to read the *same* `StepperStateWrapper`

    /// `RefAny` that the handler is currently holding a mutable borrow on.

    struct ReentrantProbe {

        /// A clone of the state `RefAny` the handler was invoked with.

        state: RefAny,

        /// `Some(step)` if the re-entrant read succeeded, `None` if it was

        /// refused. Starts as `Some(usize::MAX)` so "never ran" is distinguishable.

        saw_step: Option<usize>,

        calls: usize,

    }

    extern "C" fn probe_state_reentrantly(

        mut data: RefAny,

        _: CallbackInfo,

        _: StepperState,

    ) -> Update {

        if let Some(mut probe) = data.downcast_mut::<ReentrantProbe>() {

            probe.calls += 1;

            let mut state = probe.state.clone();

            probe.saw_step = state.downcast_ref::<StepperStateWrapper>().map(|w| w.inner.current_step);

        }

        Update::DoNothing

    }

    fn logged(data: &mut RefAny) -> Vec<StepperState> {

        data.downcast_ref::<StepLog>().expect("payload must still be a StepLog").seen.clone()

    }

    fn current_step_of(data: &mut RefAny) -> usize {

        data.downcast_ref::<StepperStateWrapper>()

            .expect("payload must still be a StepperStateWrapper")

            .inner

            .current_step

    }

    /// The `RefAny` carried by step `i`'s click callback.

    fn step_state(dom: &Dom, i: usize) -> RefAny {

        dom.children.as_ref()[i]

            .root

            .get_callbacks()

            .as_ref()

            .first()

            .expect("every step cell must carry the click callback")

            .refany

            .clone()

    }

    fn node(idx: usize) -> DomNodeId {

        DomNodeId {

            dom: DomId::ROOT_ID,

            node: NodeHierarchyItemId::from_crate_internal(Some(NodeId::new(idx))),

        }

    }

    /// A `DomNodeId` whose node component is `None` — the "no concrete node was

    /// hit" case. `CallbackInfo::set_css_property` *panics* on such an id, so the

    /// handler must bail out long before reaching the restyle loop.

    fn node_none() -> DomNodeId {

        DomNodeId {

            dom: DomId::ROOT_ID,

            node: NodeHierarchyItemId::NONE,

        }

    }

    /// A `DomLayoutResult` with an *empty* layout tree: `on_step_click` only walks

    /// `styled_dom.node_hierarchy`, so no real layout (and no font) is needed.

    fn layout_result(styled_dom: StyledDom) -> DomLayoutResult {

        DomLayoutResult {

            styled_dom,

            layout_tree: LayoutTree {

                nodes: Vec::new(),

                warm: Vec::new(),

                cold: Vec::new(),

                root: 0,

                dom_to_layout: BTreeMap::new(),

                children_arena: Vec::new(),

                children_offsets: Vec::new(),

                subtree_needs_intrinsic: Vec::new(),

            },

            calculated_positions: Vec::new(),

            viewport: LogicalRect::zero(),

            display_list: Arc::new(DisplayList::default()),

            scroll_ids: HashMap::new(),

            scroll_id_to_node_id: HashMap::new(),

        }

    }

    /// Renders `s`, then hands back both the flattened DOM *and* the very `RefAny`

    /// the widget registered on step 0's mouse-up callback. Driving the handler

    /// with these two is the real wiring — nothing is re-created by hand, so a

    /// mismatch between what `dom()` stores and what the handler expects cannot

    /// hide behind the fixture. Requires at least one label.

    fn flatten(s: Stepper) -> (StyledDom, RefAny) {

        let dom = s.dom();

        let state = step_state(&dom, 0);

        (StyledDom::create_from_dom(dom), state)

    }

    /// Invokes `on_step_click` against a `LayoutWindow` holding `styled` (or

    /// nothing at all, when `styled` is `None`), with `hit` as the hit node.

    /// Returns the `Update` plus every recorded `CallbackChange`.

    fn run_click(

        styled: Option<StyledDom>,

        hit: DomNodeId,

        data: RefAny,

    ) -> (Update, Vec<CallbackChange>) {

        let mut layout_window =

            LayoutWindow::new(FcFontCache::default()).expect("LayoutWindow::new failed");

        if let Some(sd) = styled {

            layout_window.layout_results.insert(DomId::ROOT_ID, layout_result(sd));

        }

        let renderer_resources = RendererResources::default();

        let previous_window_state: Option<FullWindowState> = None;

        let current_window_state = FullWindowState::default();

        let gl_context = OptionGlContextPtr::None;

        let scroll_states: BTreeMap<DomId, BTreeMap<NodeHierarchyItemId, ScrollPosition>> =

            BTreeMap::new();

        let window_handle = RawWindowHandle::Unsupported;

        let system_callbacks = ExternalSystemCallbacks::rust_internal();

        let ref_data = CallbackInfoRefData {

            layout_window: &layout_window,

            renderer_resources: &renderer_resources,

            previous_window_state: &previous_window_state,

            current_window_state: &current_window_state,

            gl_context: &gl_context,

            current_scroll_manager: &scroll_states,

            current_window_handle: &window_handle,

            system_callbacks: &system_callbacks,

            system_style: Arc::new(SystemStyle::default()),

            monitors: Arc::new(Mutex::new(MonitorVec::from_const_slice(&[]))),

            #[cfg(feature = "icu")]

            icu_localizer: IcuLocalizerHandle::default(),

            ctx: OptionRefAny::None,

        };

        let changes: Arc<Mutex<Vec<CallbackChange>>> = Arc::new(Mutex::new(Vec::new()));

        let info = CallbackInfo::new(

            &ref_data,

            &changes,

            hit,

            OptionLogicalPosition::None,

            OptionLogicalPosition::None,

        );

        let update = on_step_click(data, info);

        let recorded = core::mem::take(&mut *changes.lock().expect("change log poisoned"));

        (update, recorded)

    }

    /// Every colour the live restyle wrote, as `(flattened node index, "bg" |

    /// "text", colour)` in emission order. Panics on any property other than the

    /// two the handler is documented to write.

    fn restyle_writes(changes: &[CallbackChange]) -> Vec<(usize, &'static str, ColorU)> {

        let mut out = Vec::new();

        for change in changes {

            let CallbackChange::ChangeNodeCssProperties { node_id, properties, .. } = change else {

                panic!("the restyle must only emit ChangeNodeCssProperties, got {change:?}");

            };

            for p in properties.as_ref() {

                match p {

                    CssProperty::BackgroundContent(v) => {

                        let layers =

                            v.get_property().expect("the restyle must write an exact background");

                        out.push((node_id.index(), "bg", only_color(layers)));

                    }

                    CssProperty::TextColor(v) => {

                        let c =

                            v.get_property().expect("the restyle must write an exact text colour");

                        out.push((node_id.index(), "text", c.inner));

                    }

                    other => panic!("unexpected restyle property: {other:?}"),

                }

            }

        }

        out

    }

    /// What a correct restyle of an `n`-step stepper landing on `clicked` looks

    /// like: per step the circle fill + number, both connector halves and the

    /// label colour, in the handler's documented emission order.

    fn expected_restyle(n: usize, clicked: usize) -> Vec<(usize, &'static str, ColorU)> {

        let last = n.saturating_sub(1);

        let mut out = Vec::with_capacity(5 * n);

        for i in 0..n {

            let reached = i <= clicked;

            out.push((

                circle_node(i),

                "bg",

                if reached { ACCENT_COLOR } else { MUTED_CIRCLE_COLOR },

            ));

            out.push((circle_node(i), "text", if reached { WHITE } else { MUTED_TEXT_COLOR }));

            out.push((conn_left_node(i), "bg", fill_color(conn_left_fill(i, clicked))));

            out.push((conn_right_node(i), "bg", fill_color(conn_right_fill(i, last, clicked))));

            out.push((

                label_node(i),

                "text",

                if reached { DARK_TEXT_COLOR } else { MUTED_TEXT_COLOR },

            ));

        }

        out

    }

    // ==================================================================

    // ConnFill::bg

    // ==================================================================

    #[test]

    fn conn_fill_bg_maps_each_variant_to_its_own_flat_colour() {

        assert_eq!(fill_color(ConnFill::Accent), ACCENT_COLOR);

        assert_eq!(fill_color(ConnFill::Muted), CONNECTOR_MUTED_COLOR);

        assert_eq!(fill_color(ConnFill::Hidden), TRANSPARENT_COLOR);

    }

    #[test]

    fn conn_fill_bg_colours_are_pairwise_distinct_and_correctly_opaque() {

        let accent = fill_color(ConnFill::Accent);

        let muted = fill_color(ConnFill::Muted);

        let hidden = fill_color(ConnFill::Hidden);

        assert_ne!(accent, muted, "reached and unreached connectors must be distinguishable");

        assert_ne!(accent, hidden);

        assert_ne!(muted, hidden);

        assert_eq!(accent.a, 255, "a translucent accent track lets the page bleed through");

        assert_eq!(muted.a, 255, "a translucent muted track lets the page bleed through");

        assert_eq!(hidden.a, 0, "the row-end connector must be fully transparent, not merely pale");

    }

    #[test]

    fn conn_fill_bg_is_pure_and_single_layered() {

        // Called four times per step on every click; a hidden `static mut` cache

        // or an accumulating vec would show up as drift between two calls.

        for f in [ConnFill::Accent, ConnFill::Muted, ConnFill::Hidden] {

            let a = f.bg();

            let b = f.bg();

            assert_eq!(a, b, "ConnFill::bg is not pure");

            assert_eq!(a.as_ref().len(), 1, "a connector fill is exactly one layer");

        }

    }

    // ==================================================================

    // row_style

    // ==================================================================

    #[test]

    fn row_style_is_a_full_width_vertically_centred_flex_row() {

        let style = row_style();

        let props = properties(&style);

        assert_eq!(props.len(), 4, "the indicator row declares exactly four properties");

        assert!(

            props.iter().any(|p| matches!(

                p, CssProperty::Display(d) if d.get_property() == Some(&LayoutDisplay::Flex))),

            "the indicator row must be a flex box"

        );

        assert!(

            props.iter().any(|p| matches!(

                p, CssProperty::FlexDirection(d)

                    if d.get_property() == Some(&LayoutFlexDirection::Row))),

            "connectors sit left/right of the circle, so the row is horizontal"

        );

        assert!(

            props.iter().any(|p| matches!(

                p, CssProperty::AlignItems(a)

                    if a.get_property() == Some(&LayoutAlignItems::Center))),

            "the 2px connectors must be centred on the 28px circle"

        );

    }

    #[test]

    fn row_style_width_is_a_full_percentage_not_a_pixel_length() {

        // A `px` width here would stop the flex-grow connectors from having any

        // space to fill, collapsing the track to nothing at every cell width.

        let style = row_style();

        let w = width_value(&properties(&style)).expect("the indicator row must declare a width");

        assert_eq!(w.metric, SizeMetric::Percent, "the row width must be relative to the cell");

        assert!(

            (w.number.get() - 100.0).abs() < f32::EPSILON,

            "the row must span the whole cell, got {}",

            w.number.get()

        );

    }

    #[test]

    fn row_style_is_unconditional_unique_and_pure() {

        assert_unconditional_and_unique(&row_style(), "row_style");

        assert_eq!(properties(&row_style()), properties(&row_style()), "row_style is not pure");

    }

    // ==================================================================

    // circle_style

    // ==================================================================

    #[test]

    fn circle_style_declares_the_same_property_set_for_both_states() {

        // A property present in one state but not the other would not be reset on

        // restyle — the circle would keep a stale declaration after a click.

        let reached = circle_style(true);

        let unreached = circle_style(false);

        assert_eq!(reached.as_ref().len(), 18, "the circle declares eighteen properties");

        assert_eq!(unreached.as_ref().len(), 18);

        assert_eq!(

            property_kinds(&reached),

            property_kinds(&unreached),

            "the two circle states must declare the same properties in the same order"

        );

    }

    #[test]

    fn circle_style_colours_are_the_only_reached_dependent_declarations() {

        let reached = properties(&circle_style(true));

        let unreached = properties(&circle_style(false));

        assert_eq!(background_color(&reached), Some(ACCENT_COLOR));

        assert_eq!(text_color(&reached), Some(WHITE));

        assert_eq!(background_color(&unreached), Some(MUTED_CIRCLE_COLOR));

        assert_eq!(text_color(&unreached), Some(MUTED_TEXT_COLOR));

        // Everything that is not a colour must be byte-identical between states.

        let strip = |v: &[CssProperty]| -> Vec<CssProperty> {

            v.iter()

                .filter(|p| {

                    !matches!(

                        p,

                        CssProperty::BackgroundContent(_) | CssProperty::TextColor(_)

                    )

                })

                .cloned()

                .collect()

        };

        assert_eq!(

            strip(&reached),

            strip(&unreached),

            "reached-ness leaked into a non-colour property"

        );

    }

    #[test]

    fn circle_style_geometry_is_a_fixed_pixel_circle() {

        for reached in [false, true] {

            let props = properties(&circle_style(reached));

            let ctx = format!("reached={reached}");

            let w = px(width_value(&props).expect("width"));

            let h = px(height_value(&props).expect("height"));

            let mw = px(min_width_value(&props).expect("min-width"));

            assert!((w - CIRCLE_SIZE as f32).abs() < f32::EPSILON, "{ctx}: width");

            assert!((h - CIRCLE_SIZE as f32).abs() < f32::EPSILON, "{ctx}: height");

            assert!(

                (mw - CIRCLE_SIZE as f32).abs() < f32::EPSILON,

                "{ctx}: without a min-width the circle would squash in a tight flex row"

            );

            assert!((w - h).abs() < f32::EPSILON, "{ctx}: a circle must be square");

            let (tl, tr, bl, br) = radii(&props);

            let r = CIRCLE_RADIUS as f32;

            for (corner, v) in [("top-left", tl), ("top-right", tr), ("bottom-left", bl), ("bottom-right", br)] {

                let v = px(v.unwrap_or_else(|| panic!("{ctx}: missing {corner} radius")));

                assert!((v - r).abs() < f32::EPSILON, "{ctx}: {corner} radius is {v}, want {r}");

            }

            assert_eq!(

                CIRCLE_RADIUS * 2,

                CIRCLE_SIZE,

                "a radius that is not half the box renders a rounded square, not a circle"

            );

            assert_eq!(

                flex_grow_value(&props),

                Some(0.0),

                "{ctx}: the circle must keep its fixed size, not stretch"

            );

            assert!(

                (px(font_size_value(&props).expect("font size")) - 13.0).abs() < f32::EPSILON,

                "{ctx}: font size"

            );

        }

    }