teksilo_widgets/

breadcrumb.rs

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

//! Breadcrumb — a navigational trail with automatic overflow into a `…` menu.
//!
//! `Breadcrumb` renders a horizontal row of labelled segments separated by
//! chevron glyphs, representing a hierarchical path (file system, settings
//! hierarchy, wizard steps, etc.). When the trail is too wide to fit its
//! container, middle segments are automatically collapsed into a `…` popover
//! menu — the root and the current (last) segment always stay visible,
//! matching Windows Explorer, macOS path bar, and web breadcrumb conventions.
//!
//! ## Building a trail
//!
//! ```rust
//! # use teksilo_widgets::{Breadcrumb, BreadcrumbItem};
//! # use teksilo_core::Intent;
//! # use teksilo_i18n::lit;
//! let _bc = Breadcrumb::new()
//!     .item(BreadcrumbItem::new(lit!("Home"))
//!         .on_activate_fn(|ctx| ctx.send_intent(Intent::new("app.nav.home"))))
//!     .item(BreadcrumbItem::new(lit!("Projects"))
//!         .on_activate_fn(|ctx| ctx.send_intent(Intent::new("app.nav.projects"))))
//!     .item(BreadcrumbItem::current(lit!("Teksilo")));
//! ```
//!
//! ## Accessibility
//!
//! The container uses `Role::Navigation`; each segment uses `Role::Link`.
//! The current crumb sets `aria-current="page"`. The decorative separator
//! chevrons are hidden from the AT tree. The `…` overflow button declares
//! `HasPopup::Menu`.
//!
//! ## Touch and pen
//!
//! A crumb navigates on the release. It is as wide as its label, so a short one
//! ("A / B / C", a drive letter) can land under the 24 dp target floor; it
//! declares a `Widget::hit_outset` that makes the shortfall up between the
//! pointer and the arena, so the trail's own geometry never moves. The current
//! crumb and a trail with no navigation action declare none — a widened node
//! that then refuses the press is a hole in whatever is behind it.

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

use teksilo_canvas::{Canvas, Rect, Size, SizeProposal};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::accesskit::HasPopup;
use teksilo_core::binding::BindingLevel;
use teksilo_core::build_context::BuildContext;
use teksilo_core::environment::LayoutDirection;
use teksilo_core::event::{EventResponse, Key, WidgetEvent};
use teksilo_core::overlay::OverlayPlacement;
use teksilo_core::signal::Signal;
use teksilo_core::widget::{
    CursorIcon, EventContext, LayoutContext, PaintContext, PendingChild, Widget, WidgetPlacement,
};
use teksilo_core::widget_builder::HandlerSet;
use teksilo_core::widget_id::WidgetId;
use teksilo_tokens::{Color, CornerRadius, InputTokens};

use crate::button::{Button, ButtonVariant};
use crate::menu_item::MenuItem;
use crate::menu_list::MenuList;
use crate::popover_widget::PopoverButton;
use crate::primitives::{HStack, IconWidget, Spacer};
use teksilo_core::styles::FocusRingStroke;
use teksilo_core::styles::density::spacing;
use teksilo_i18n::LocalizedString;

const FALLBACK_CHAR_WIDTH: f32 = 8.0;
const FALLBACK_LINE_HEIGHT: f32 = 16.0;

/// Shared activation closure. `Rc` (not `Box`) so a crumb's action can be
/// fired from BOTH its inline segment AND its row in the overflow menu.
type CommandFactory = Rc<dyn Fn(&mut EventContext)>;

struct BreadcrumbEntry {
    label: LocalizedString,
    action: Option<CommandFactory>,
    current: bool,
    tooltip_text: Option<LocalizedString>,
    rich_tooltip_source: Option<crate::tooltip::RichTooltipSource>,
    composite_tooltip_content: Option<Box<dyn Widget>>,
}

impl std::fmt::Debug for BreadcrumbEntry {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("BreadcrumbEntry")
            .field("label", &self.label)
            .field("current", &self.current)
            .finish()
    }
}

/// Minimum height of a single breadcrumb segment in logical pixels.
pub const BREADCRUMB_ITEM_HEIGHT: f32 = 20.0;
/// Horizontal inner padding of each segment pill in logical pixels.
pub const BREADCRUMB_ITEM_PADDING_HORIZONTAL: f32 = 6.0;

/// [`BREADCRUMB_ITEM_PADDING_HORIZONTAL`] scaled by the density's `spacing_factor`
/// (1.00 / 1.15 / 1.30).
pub fn breadcrumb_item_padding_horizontal(tokens: &InputTokens) -> f32 {
    spacing(BREADCRUMB_ITEM_PADDING_HORIZONTAL, tokens)
}
/// Gap reserved for the chevron separator between adjacent segments.
pub const BREADCRUMB_SEPARATOR_GAP: f32 = 4.0;

/// [`BREADCRUMB_SEPARATOR_GAP`] scaled by the density's `spacing_factor`
/// (1.00 / 1.15 / 1.30).
pub fn breadcrumb_separator_gap(tokens: &InputTokens) -> f32 {
    spacing(BREADCRUMB_SEPARATOR_GAP, tokens)
}
/// Corner radius of the interactive segment hover/focus rectangle.
pub const BREADCRUMB_CORNER_RADIUS: f32 = 4.0;

/// A single breadcrumb segment definition.
pub struct BreadcrumbItem {
    label: LocalizedString,
    action: Option<CommandFactory>,
    current: bool,
    /// 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 std::fmt::Debug for BreadcrumbItem {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("BreadcrumbItem")
            .field("label", &self.label)
            .field("current", &self.current)
            .finish()
    }
}

impl BreadcrumbItem {
    /// Construct a non-current (navigable) breadcrumb segment.
    pub fn new(label: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = label.into();
        Self {
            label: ls,
            action: None,
            current: false,
            tooltip_text: None,
            rich_tooltip_source: None,
            composite_tooltip_content: None,
        }
    }

    /// Construct the current (last) breadcrumb segment, announced
    /// with `aria-current="page"`. Current segments are never
    /// collapsed into the overflow `…` menu.
    pub fn current(label: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = label.into();
        Self {
            label: ls,
            action: None,
            current: true,
            tooltip_text: None,
            rich_tooltip_source: None,
            composite_tooltip_content: None,
        }
    }

    /// Closure invoked on activation.
    pub fn on_activate_fn(mut self, f: impl Fn(&mut EventContext) + 'static) -> Self {
        self.action = Some(Rc::new(f));
        self
    }

    /// Attach a plain single-line tooltip to this breadcrumb segment, shown
    /// after a hover delay. Clears any previously set rich or composite tooltip.
    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 to this breadcrumb segment, looked up by registry
    /// key. Clears any previously set plain or 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 to this breadcrumb segment from inline content.
    /// Clears any previously set plain or 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 (arbitrary widget tree) to this breadcrumb
    /// segment. Clears any previously set plain or rich tooltip.
    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
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum SegmentInteraction {
    Idle,
    Hovered,
    Focused,
}

struct BreadcrumbSegment {
    label: LocalizedString,
    action: Option<CommandFactory>,
    current: bool,
    interaction: Signal<SegmentInteraction>,
    /// The crumb's laid-out size, recorded at paint so `hit_outset` can ask
    /// whether *this* crumb fell short. A crumb is text-width: "A / B / C"
    /// makes three of them narrower than a finger.
    painted_size: std::cell::Cell<Size>,
    /// Whether this crumb navigates, recorded so it survives mounting.
    ///
    /// [`is_interactive`](Self::is_interactive) asks whether `action` is still
    /// present, and `build` **moves** it out into the tap / key / AT closures.
    /// So that question answers `false` for every crumb that has been built,
    /// and anything consulted after mount — the hit outset is, on every press —
    /// has to ask this instead.
    navigates: std::cell::Cell<bool>,
    tooltip_text: Option<LocalizedString>,
    rich_tooltip_source: Option<crate::tooltip::RichTooltipSource>,
    composite_tooltip_content: Option<Box<dyn Widget>>,
}

impl std::fmt::Debug for BreadcrumbSegment {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("BreadcrumbSegment")
            .field("label", &self.label)
            .field("current", &self.current)
            .field("interaction", &self.interaction.get())
            .finish()
    }
}

impl BreadcrumbSegment {
    fn new(label: LocalizedString, action: Option<CommandFactory>, current: bool) -> Self {
        let navigates = !current && action.is_some();
        Self {
            label,
            action,
            current,
            navigates: std::cell::Cell::new(navigates),
            interaction: Signal::new(SegmentInteraction::Idle),
            painted_size: std::cell::Cell::new(Size::ZERO),
            tooltip_text: None,
            rich_tooltip_source: None,
            composite_tooltip_content: None,
        }
    }

    /// Move a [`BreadcrumbItem`]'s tooltip slots onto the built segment.
    /// The three are mutually exclusive by construction (every `BreadcrumbItem`
    /// setter clears the other two), so at most one is ever `Some`.
    fn with_tooltip(
        mut self,
        tooltip_text: Option<LocalizedString>,
        rich_tooltip_source: Option<crate::tooltip::RichTooltipSource>,
        composite_tooltip_content: Option<Box<dyn Widget>>,
    ) -> Self {
        self.tooltip_text = tooltip_text;
        self.rich_tooltip_source = rich_tooltip_source;
        self.composite_tooltip_content = composite_tooltip_content;
        self
    }

    fn is_interactive(&self) -> bool {
        !self.current && self.action.is_some()
    }

    fn estimate_width(&self, ctx: &LayoutContext) -> f32 {
        let pad_h = breadcrumb_item_padding_horizontal(&ctx.theme.input);
        let envelope = ctx.theme.shape.focus_ring_envelope();
        let resolved = self.label.resolve_now();
        let text_width = if let Some(backend) = ctx.text_backend {
            backend
                .borrow_mut()
                .layout_single_line(&resolved, &ctx.theme.typography.small, None)
                .width
        } else {
            resolved.len() as f32 * FALLBACK_CHAR_WIDTH
        };
        text_width + pad_h * 2.0 + envelope * 2.0
    }
}

impl Widget for BreadcrumbSegment {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        let self_id = ctx.self_id();
        let interaction = ctx.signal(SegmentInteraction::Idle);
        let registry = ctx.binding_registry();
        interaction.bind_to(self_id, registry, BindingLevel::RepaintOnly);
        // Locale changes can alter the resolved label (and its width), so
        // re-measure + repaint this custom-painted segment on locale switch.
        ctx.locale_signal()
            .bind_to(self_id, registry, BindingLevel::Relayout);
        self.interaction = interaction.clone();

        let interactive = self.is_interactive();
        let action = self.action.take();
        let action_for_tap = action.clone();
        let action_for_key = action.clone();
        let action_for_access = action;

        let handler_set = HandlerSet::new()
            .on_tap({
                let interaction = interaction.clone();
                move |_pos, ctx: &mut EventContext| {
                    if !interactive {
                        return;
                    }
                    if let Some(ref action) = action_for_tap {
                        action(ctx);
                    }
                    interaction.set(SegmentInteraction::Hovered);
                }
            })
            .on_hover({
                let interaction = interaction.clone();
                move |entered: bool, _ctx: &mut EventContext| {
                    if !interactive {
                        interaction.set(SegmentInteraction::Idle);
                        return;
                    }
                    if interaction.get() == SegmentInteraction::Focused {
                        return;
                    }
                    interaction.set(if entered {
                        SegmentInteraction::Hovered
                    } else {
                        SegmentInteraction::Idle
                    });
                }
            })
            .on_focus({
                let interaction = interaction.clone();
                move |gained: bool, _ctx: &mut EventContext| {
                    if !interactive {
                        interaction.set(SegmentInteraction::Idle);
                        return;
                    }
                    interaction.set(if gained {
                        SegmentInteraction::Focused
                    } else {
                        SegmentInteraction::Idle
                    });
                }
            })
            .on_key({
                let interaction = interaction.clone();
                move |event: &WidgetEvent, ctx: &mut EventContext| -> EventResponse {
                    if !interactive {
                        return EventResponse::Ignored;
                    }
                    match event {
                        WidgetEvent::KeyDown {
                            key: Key::Enter | Key::Space,
                            ..
                        } => {
                            if let Some(ref action) = action_for_key {
                                action(ctx);
                            }
                            interaction.set(SegmentInteraction::Focused);
                            EventResponse::Handled
                        }
                        _ => EventResponse::Ignored,
                    }
                }
            })
            .on_access_action(move |action, ctx: &mut EventContext| {
                if interactive && action == teksilo_core::accesskit::Action::Click {
                    if let Some(ref action) = action_for_access {
                        action(ctx);
                    }
                    EventResponse::Handled
                } else {
                    EventResponse::Ignored
                }
            })
            .focusable(interactive)
            .cursor(if interactive {
                CursorIcon::Pointer
            } else {
                CursorIcon::Default
            });

        ctx.apply_self_handlers(handler_set);

        // Attach the tooltip carried over from `BreadcrumbItem`. The segment
        // paints itself and returns no children, so it is its own anchor.
        // Default `Below` placement: the crumbs sit in one non-wrapping row, so
        // a tip under one covers no sibling crumb.
        if let Some(content) = self.composite_tooltip_content.take() {
            let delay = ctx.theme().motion.tooltip_delay_heavy;
            crate::tooltip::attach_composite_tooltip_boxed(ctx, self_id, content, delay);
        } else if let Some(source) = self.rich_tooltip_source.take() {
            let delay = ctx.theme().motion.tooltip_delay;
            crate::tooltip::attach_rich_tooltip_source(ctx, self_id, source, delay);
        } else if let Some(tooltip_text) = self.tooltip_text.clone() {
            let delay = ctx.theme().motion.tooltip_delay;
            crate::tooltip::attach_plain_tooltip(ctx, self_id, tooltip_text, delay);
        }

        Vec::new()
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        let envelope = ctx.theme.shape.focus_ring_envelope();
        let width = proposal.width.unwrap_or_else(|| self.estimate_width(ctx));
        let text_height = if let Some(backend) = ctx.text_backend {
            backend
                .borrow_mut()
                .layout_single_line(&self.label.resolve_now(), &ctx.theme.typography.small, None)
                .height
        } else {
            FALLBACK_LINE_HEIGHT
        };
        let visual_h = text_height.max(BREADCRUMB_ITEM_HEIGHT);
        Size::new(width, visual_h + envelope * 2.0).into()
    }

    /// A crumb is as wide as its label, so a short one ("A / B / C", a drive
    /// letter, a one-word folder) can land under the 24 dp floor on the axis
    /// that matters most — and it cannot grow, because the crumbs and their
    /// chevrons are laid out edge to edge and widening the paint would move the
    /// whole trail. The shortfall is made up between the pointer and the arena.
    ///
    /// Zero for the current crumb and for a trail with no navigation action:
    /// neither takes a press, and widening a node that then ignores one is a
    /// hole punched in whatever is behind it.
    fn hit_outset(
        &self,
        kind: teksilo_tokens::PointerKind,
        tokens: &teksilo_tokens::InputTokens,
    ) -> teksilo_canvas::EdgeInsets {
        if !self.navigates.get() {
            return teksilo_canvas::EdgeInsets::ZERO;
        }
        crate::button::target_outset(self.painted_size.get(), kind, tokens)
    }

    fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext) {
        self.painted_size.set(bounds.size());
        let colors = &ctx.theme.colors;
        let shape = &ctx.theme.shape;
        let envelope = shape.focus_ring_envelope();
        let interaction = self.interaction.get();
        // Not `is_interactive()`: `build` has moved the action out by now.
        let interactive = self.navigates.get();

        // Visual bounds — inset by the focus-ring envelope.
        let visual = bounds.inset(envelope, envelope, envelope, envelope);

        if interactive {
            let background = if interaction == SegmentInteraction::Hovered {
                colors.accent.with_alpha(0.08)
            } else if interaction == SegmentInteraction::Focused {
                colors.accent.with_alpha(0.12)
            } else {
                Color::TRANSPARENT
            };
            if background.a() > 0.0 {
                canvas.fill_rounded_rect(
                    visual,
                    CornerRadius::uniform(BREADCRUMB_CORNER_RADIUS),
                    background,
                );
            }
            // Focus ring: drawn around the visual, inside the reserved
            // envelope. A negative offset lays it over the visual's edge.
            if interaction == SegmentInteraction::Focused {
                let ring = FocusRingStroke::around(visual, BREADCRUMB_CORNER_RADIUS, shape);
                canvas.stroke_rounded_rect(
                    ring.rect,
                    CornerRadius::uniform(ring.corner_radius),
                    colors.focus_ring,
                    shape.focus_ring_width,
                );
            }
        }

        let text_color = if self.current {
            colors.text_primary
        } else if interactive && interaction == SegmentInteraction::Hovered {
            colors.accent_hover
        } else if interactive {
            colors.accent
        } else {
            colors.text_secondary
        };

        let pad_h = breadcrumb_item_padding_horizontal(&ctx.theme.input);
        let text_bounds = Rect::new(
            visual.x + pad_h,
            visual.y,
            (visual.width - pad_h * 2.0).max(0.0),
            visual.height,
        );
        canvas.draw_text(
            &self.label.resolve_now(),
            text_bounds,
            &ctx.theme.typography.small,
            text_color,
        );
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        // Every crumb keeps Role::Link — ARIA convention is that the
        // current page is still announced as a link, just tagged with
        // `aria-current="page"` so screen readers say "current page,
        // <label>". Replaces the earlier Label-role + synthesized
        // i18n `set_value` workaround which didn't map to a standard
        // ARIA pattern.
        builder.set_role(teksilo_core::accesskit::Role::Link);
        builder.set_name(self.label.resolve_now());
        if self.current {
            builder.set_aria_current(teksilo_core::accesskit::AriaCurrent::Page);
        } else if self.navigates.get() {
            // Not `is_interactive()`: `build` has moved the action out by now.
            builder.add_action(teksilo_core::accesskit::Action::Click);
            builder.add_action(teksilo_core::accesskit::Action::Focus);
        }
    }
}

#[derive(Debug)]
struct BreadcrumbSeparator;

impl Widget for BreadcrumbSeparator {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        // Repaint on locale change so the chevron can flip with the layout
        // direction (it points toward the next crumb: right in LTR, left in
        // RTL).
        let self_id = ctx.self_id();
        let registry = ctx.binding_registry();
        ctx.locale_signal()
            .bind_to(self_id, registry, BindingLevel::RepaintOnly);
        Vec::new()
    }

    fn layout_response(
        &self,
        _proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        Size::new(
            breadcrumb_separator_gap(&ctx.theme.input) * 3.0,
            BREADCRUMB_ITEM_HEIGHT,
        )
        .into()
    }

    fn paint(&self, bounds: Rect, canvas: &mut Canvas, ctx: &PaintContext) {
        let size = 10.0;
        let icon_bounds = Rect::new(
            bounds.x + (bounds.width - size) / 2.0,
            bounds.y + (bounds.height - size) / 2.0,
            size,
            size,
        );
        // Role-based: IconWidget resolves against the current theme at paint,
        // so this stays reactive across theme switches. The chevron mirrors
        // under RTL — it always points toward the *next* crumb.
        let icon = if ctx.layout_direction == LayoutDirection::RightToLeft {
            IconWidget::chevron_left(size)
        } else {
            IconWidget::chevron_right(size)
        }
        .color(teksilo_tokens::TextRole::Secondary);
        icon.paint(icon_bounds, canvas, ctx);
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        // Decorative chevron between crumbs. Screen readers would
        // otherwise enumerate a generic container between every pair
        // of links; `set_hidden()` keeps the node in the layout tree
        // but removes it from the platform a11y tree.
        builder.set_role(teksilo_core::accesskit::Role::GenericContainer);
        builder.set_hidden();
    }
}

enum BreadcrumbSlot {
    Entry(Box<BreadcrumbEntry>),
    Id(WidgetId),
}

/// Menu-form of a collapsible crumb — the row shown in the overflow `…` menu.
struct CrumbMenuForm {
    slot: usize,
    label: LocalizedString,
    action: Option<CommandFactory>,
}

/// A breadcrumb navigation row with **automatic overflow**: when the trail is
/// too wide, the middle crumbs collapse into a trailing-of-root `…` menu while
/// the root and the current (last) crumb stay visible — the standard breadcrumb
/// collapse (Windows Explorer / web breadcrumbs / macOS path bar).
pub struct Breadcrumb {
    slots: Vec<BreadcrumbSlot>,
    trailing_slot: Option<PendingChild>,
    label: Option<LocalizedString>,

    // Reactive state.
    /// Per-slot collapsed flag (`true` = hidden in the `…` menu). Only
    /// collapsible slots are ever set; index-aligned with the slots.
    collapsed: Signal<Vec<bool>>,
    /// Whether any crumb is currently collapsed (drives the chevron).
    is_overflowing: Signal<bool>,

    // Build state.
    /// Per-slot "unit" id (the slot's segment, plus its leading separator for
    /// slots after the first) — measured to compute overflow.
    unit_ids: Vec<WidgetId>,
    /// Per-slot: can this crumb collapse? (Entry crumbs that are neither first
    /// nor last; pre-registered `item_id` crumbs never collapse.)
    collapsible: Vec<bool>,
    /// Menu-form per collapsible crumb, for the overflow `…` menu rows.
    menu_forms: Rc<Vec<CrumbMenuForm>>,
    /// The `[separator, …-button]` unit id (measured + gated on overflow).
    ellipsis_unit_id: Option<WidgetId>,
    trailing_id: Option<WidgetId>,
    root_child_id: Option<WidgetId>,
    /// Cached flags to avoid redundant signal writes.
    last_flags: RefCell<Vec<bool>>,
}

impl Breadcrumb {
    /// Construct an empty breadcrumb trail. Add segments with
    /// [`item`](Self::item) and [`item_id`](Self::item_id).
    pub fn new() -> Self {
        Self {
            slots: Vec::new(),
            trailing_slot: None,
            label: None,
            collapsed: Signal::new(Vec::new()),
            is_overflowing: Signal::new(false),
            unit_ids: Vec::new(),
            collapsible: Vec::new(),
            menu_forms: Rc::new(Vec::new()),
            ellipsis_unit_id: None,
            trailing_id: None,
            root_child_id: None,
            last_flags: RefCell::new(Vec::new()),
        }
    }

    /// Accessible name for the `Navigation` landmark — distinguishes
    /// this breadcrumb from other nav landmarks on the page
    /// (e.g. "Files", "Settings"). Screen readers announce it as the
    /// name of the landmark when it gains focus or is summoned.
    pub fn label(mut self, text: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = text.into();
        self.label = Some(ls);
        self
    }

    /// Append a `BreadcrumbItem` segment to the trail. Items are rendered
    /// in insertion order, separated by chevron glyphs. Middle items (neither
    /// root nor current) may be collapsed into the `…` overflow menu.
    pub fn item(mut self, item: BreadcrumbItem) -> Self {
        self.slots
            .push(BreadcrumbSlot::Entry(Box::new(BreadcrumbEntry {
                label: item.label,
                action: item.action,
                current: item.current,
                tooltip_text: item.tooltip_text,
                rich_tooltip_source: item.rich_tooltip_source,
                composite_tooltip_content: item.composite_tooltip_content,
            })));
        self
    }

    /// Append several `BreadcrumbItem` segments from an iterator, in order.
    ///
    /// The loop form of [`item`](Self::item), and the usual one: a trail is
    /// normally walked out of a path rather than written crumb by crumb.
    pub fn items(self, items: impl IntoIterator<Item = BreadcrumbItem>) -> Self {
        items.into_iter().fold(self, Self::item)
    }

    /// Insert a pre-registered widget as a breadcrumb segment slot.
    /// The caller is responsible for the segment's visual + interaction.
    /// Note: a pre-registered crumb never collapses into the overflow menu
    /// (the breadcrumb has no label/action to synthesize a menu row from) —
    /// it is treated like the root/current crumbs as always-visible.
    pub fn item_id(mut self, id: WidgetId) -> Self {
        self.slots.push(BreadcrumbSlot::Id(id));
        self
    }

    /// Insert several pre-registered widgets as breadcrumb segment slots.
    ///
    /// The id-carrying twin of [`items`](Self::items). Like `item_id`, none of
    /// these crumbs ever collapses into the overflow menu.
    pub fn item_ids(self, ids: impl IntoIterator<Item = WidgetId>) -> Self {
        ids.into_iter().fold(self, Self::item_id)
    }

    /// Append a trailing widget after all segments, pushed to the far edge
    /// by an intervening `Spacer`. Common uses: a search icon, refresh button,
    /// or current-path copy button. When a trailing slot is set, the breadcrumb
    /// spans the full proposed width.
    pub fn trailing_slot(mut self, widget: impl teksilo_core::IntoTeksiChild) -> Self {
        self.trailing_slot = Some(teksilo_core::IntoTeksiChild::into_pending(widget));
        self
    }

    /// Reactive signal that is `true` whenever any crumb is collapsed into the
    /// overflow `…` menu — for adaptive chrome.
    pub fn is_overflowing(&self) -> Signal<bool> {
        self.is_overflowing.clone()
    }
}

impl Default for Breadcrumb {
    fn default() -> Self {
        Self::new()
    }
}

impl std::fmt::Debug for Breadcrumb {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Breadcrumb")
            .field("item_count", &self.slots.len())
            .finish()
    }
}

impl Widget for Breadcrumb {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        let slots = std::mem::take(&mut self.slots);
        let n = slots.len();

        let mut unit_ids: Vec<WidgetId> = Vec::with_capacity(n);
        let mut collapsible: Vec<bool> = Vec::with_capacity(n);
        let mut menu_forms: Vec<CrumbMenuForm> = Vec::new();

        for (i, slot) in slots.into_iter().enumerate() {
            let is_first = i == 0;
            let is_last = i + 1 == n;

            // Resolve the slot to a segment id + (for Entry slots) a menu form.
            let (seg_id, form): (WidgetId, Option<(LocalizedString, Option<CommandFactory>)>) =
                match slot {
                    BreadcrumbSlot::Entry(entry) => {
                        let action = entry.action;
                        let seg = BreadcrumbSegment::new(
                            entry.label.clone(),
                            action.clone(),
                            entry.current,
                        )
                        .with_tooltip(
                            entry.tooltip_text,
                            entry.rich_tooltip_source,
                            entry.composite_tooltip_content,
                        );
                        (ctx.add(seg), Some((entry.label, action)))
                    }
                    BreadcrumbSlot::Id(id) => (id, None),
                };

            // A crumb can collapse only if it's an Entry and neither the root
            // nor the current (last) crumb.
            let can_collapse = form.is_some() && !is_first && !is_last;
            collapsible.push(can_collapse);

            // The unit is the segment, prefixed by a leading separator for
            // every crumb after the first. The separator lives inside the unit
            // so it hides together with its crumb — no dangling chevrons.
            let unit_id = if is_first {
                seg_id
            } else {
                let sep_id = ctx.add(BreadcrumbSeparator);
                ctx.add(HStack::new().spacing(0.0).child(sep_id).child(seg_id))
            };
            unit_ids.push(unit_id);

            if can_collapse {
                let collapsed = self.collapsed.clone();
                ctx.visible_when(
                    unit_id,
                    collapsed.map(move |flags| flags.get(i).copied() != Some(true)),
                );
                if let Some((label, action)) = form {
                    menu_forms.push(CrumbMenuForm {
                        slot: i,
                        label,
                        action,
                    });
                }
            }
        }

        self.collapsible = collapsible;
        self.menu_forms = Rc::new(menu_forms);
        self.collapsed.set(vec![false; n]);
        *self.last_flags.borrow_mut() = vec![false; n];

        // Overflow chevron: a `…` PopoverButton (HasPopup::Menu) whose content
        // is a `MenuList` with one row per collapsible crumb, each gated via
        // `item_when(collapsed[slot])`. Only currently-collapsed rows are shown
        // (zero-height + nav-skipped otherwise), so the menu reconciles
        // reactively as the trail resizes — no rebuild of the dormant popover.
        let has_collapsible = self.collapsible.iter().any(|&c| c);
        self.ellipsis_unit_id = if has_collapsible {
            let menu_forms = self.menu_forms.clone();
            let mut menu = MenuList::new();
            for form in menu_forms.iter() {
                let slot = form.slot;
                let action = form.action.clone();
                let mut row = MenuItem::new(form.label.clone()).enabled(action.is_some());
                if let Some(act) = action {
                    row = row.on_activate_fn(move |ctx| {
                        act(ctx);
                        ctx.dismiss_self_overlay_chain();
                    });
                }
                let collapsed = self.collapsed.clone();
                let visible = collapsed.map(move |flags| flags.get(slot).copied() == Some(true));
                menu = menu.item_when(row, visible);
            }

            let trigger = Button::new(teksilo_i18n::lit!("…"))
                .variant(ButtonVariant::Ghost)
                .tooltip(teksilo_i18n::tr_widget!(breadcrumb_overflow()));
            let chevron = PopoverButton::new(trigger)
                .content(menu)
                // `MenuList` self-chromes via the Menu `PopoverStyle`.
                .bare()
                .placement(OverlayPlacement::BelowPreferred)
                .has_popup_kind(HasPopup::Menu);
            let chevron_id = ctx.add(chevron);

            let sep_id = ctx.add(BreadcrumbSeparator);
            let unit_id = ctx.add(HStack::new().spacing(0.0).child(sep_id).child(chevron_id));
            ctx.visible_when(unit_id, self.is_overflowing.clone());
            Some(unit_id)
        } else {
            None
        };

        // Assemble the row: [root] [… (after root)] [crumb 1] … [current]
        // [Spacer trailing?].
        let mut row = HStack::new().spacing(0.0);
        for (i, &uid) in unit_ids.iter().enumerate() {
            row = row.child(uid);
            if i == 0 {
                if let Some(eu) = self.ellipsis_unit_id {
                    row = row.child(eu);
                }
            }
        }
        self.unit_ids = unit_ids;

        if let Some(trailing) = self.trailing_slot.take() {
            let trailing_id = match trailing {
                PendingChild::Id(id) => id,
                PendingChild::Deferred(w) => ctx.add_boxed(w),
            };
            self.trailing_id = Some(trailing_id);
            row = row.child(Spacer::new()).child(trailing_id);
        }

        let root_id = ctx.add(row);
        self.root_child_id = Some(root_id);
        vec![root_id]
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        let Some(root) = self.root_child_id else {
            return proposal.resolve(0.0, 0.0).into();
        };

        // Natural width = sum of every crumb unit's INTRINSIC width (measured
        // regardless of its current collapse state, so this is stable and the
        // overflow decision can't oscillate). The `…` chevron is excluded — it
        // only appears when something is already collapsed.
        let probe = SizeProposal::unspecified();
        let mut natural_w = 0.0_f32;
        for &uid in &self.unit_ids {
            if let Some(s) = ctx.measure_intrinsic(uid, probe) {
                natural_w += s.width;
            }
        }
        let has_trailing = self.trailing_id.is_some();
        if let Some(tid) = self.trailing_id
            && let Some(s) = ctx.measure_intrinsic(tid, probe)
        {
            natural_w += s.width;
        }

        // With a trailing slot the breadcrumb spans the offered width (the
        // Spacer pushes the trailing control to the edge); otherwise it
        // shrink-wraps to its content, clamped to the offered width so it never
        // spills its container.
        let width = if has_trailing {
            proposal.width.unwrap_or(natural_w)
        } else {
            proposal
                .width
                .map(|w| natural_w.min(w))
                .unwrap_or(natural_w)
        };

        let height = ctx
            .child_size(root, proposal)
            .map(|s| s.height)
            .unwrap_or(BREADCRUMB_ITEM_HEIGHT);
        Size::new(width, height).into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        ctx: &LayoutContext,
    ) {
        for child in children.iter_mut() {
            child.origin = bounds.origin();
            child.size = bounds.size();
        }

        // Compute the collapse set from intrinsic widths (measured even while
        // hidden) against the width left for the crumbs.
        let probe = SizeProposal::unspecified();
        let trailing_w = self
            .trailing_id
            .and_then(|tid| ctx.measure_intrinsic(tid, probe))
            .map(|s| s.width)
            .unwrap_or(0.0);
        let avail = (bounds.width - trailing_w).max(0.0);

        let unit_w: Vec<f32> = self
            .unit_ids
            .iter()
            .map(|&uid| {
                ctx.measure_intrinsic(uid, probe)
                    .map(|s| s.width)
                    .unwrap_or(0.0)
            })
            .collect();
        let ellipsis_w = self
            .ellipsis_unit_id
            .and_then(|eu| ctx.measure_intrinsic(eu, probe))
            .map(|s| s.width)
            .unwrap_or(0.0);

        let flags = compute_breadcrumb_overflow(avail, &unit_w, &self.collapsible, ellipsis_w);

        if *self.last_flags.borrow() != flags {
            *self.last_flags.borrow_mut() = flags.clone();
            let any = flags.iter().any(|&c| c);
            self.collapsed.set(flags);
            if self.is_overflowing.get() != any {
                self.is_overflowing.set(any);
            }
        }
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        builder.set_role(teksilo_core::accesskit::Role::Navigation);
        if let Some(ref label) = self.label {
            builder.set_name(label.clone());
        }
    }

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

/// Decide which crumbs collapse into the overflow `…` menu.
///
/// Returns a per-slot `collapsed` flag (`true` = hidden). The root and current
/// crumbs (and any non-collapsible pre-registered crumb) are kept; collapsible
/// crumbs are hidden from the **left-middle outward** (lowest index first) until
/// the shown crumbs — plus the `…` chevron once anything is hidden — fit in
/// `avail`. If even the kept crumbs + chevron don't fit, the remainder overflows
/// residually (nothing left to collapse).
fn compute_breadcrumb_overflow(
    avail: f32,
    unit_w: &[f32],
    collapsible: &[bool],
    ellipsis_w: f32,
) -> Vec<bool> {
    let n = unit_w.len();
    let mut collapsed = vec![false; n];
    if n == 0 {
        return collapsed;
    }
    let full: f32 = unit_w.iter().sum();
    if full <= avail + 0.5 {
        return collapsed; // everything fits — no chevron
    }
    loop {
        let any_hidden = collapsed.iter().any(|&c| c);
        let shown: f32 = (0..n)
            .filter(|&i| !collapsed[i])
            .map(|i| unit_w[i])
            .sum::<f32>()
            + if any_hidden { ellipsis_w } else { 0.0 };
        if shown <= avail + 0.5 {
            break;
        }
        match (0..n).find(|&i| collapsible[i] && !collapsed[i]) {
            Some(i) => collapsed[i] = true,
            None => break, // nothing left to collapse — residual overflow
        }
    }
    collapsed
}

#[cfg(test)]
mod tests {
    use super::*;
    use teksilo_canvas::MockTextBackend;
    use teksilo_core::widget_tree::WidgetTree;
    use teksilo_i18n::lit;

    fn themed_tree() -> WidgetTree {
        WidgetTree::new()
            .with_theme(teksilo_core::presets::intui::light())
            .with_text_backend(Rc::new(RefCell::new(MockTextBackend::new())))
    }

    fn trail(n: usize) -> Breadcrumb {
        let mut bc = Breadcrumb::new();
        for i in 0..n {
            let last = i + 1 == n;
            let item = if last {
                BreadcrumbItem::current(lit!(format!("Crumb {i}")))
            } else {
                BreadcrumbItem::new(lit!(format!("Crumb {i}"))).on_activate_fn(|_| {})
            };
            bc = bc.item(item);
        }
        bc
    }

    // ── focus ring ───────────────────────────────────────────────────────────

    /// The focused crumb's ring and its visual (the focused background
    /// fill) under a theme whose `focus_ring_offset` is `offset` (width 2),
    /// each as `[x, y, width, height]`.
    fn crumb_ring_and_visual(offset: f32) -> ([f32; 4], [f32; 4]) {
        let mut theme = teksilo_core::presets::intui::light();
        theme.shape.focus_ring_offset = offset;
        theme.shape.focus_ring_width = 2.0;
        let ring_color = theme.colors.focus_ring.to_array();
        let fill_color = theme.colors.accent.with_alpha(0.12).to_array();
        let mut tree = WidgetTree::new()
            .with_theme(theme)
            .with_text_backend(Rc::new(RefCell::new(MockTextBackend::new())));
        tree.add(trail(2));
        tree.layout(SizeProposal::exact(400.0, 60.0));
        let crumb = tree
            .find_by_label("Crumb 0")
            .expect("the first crumb renders");
        tree.focus(crumb);
        tree.layout(SizeProposal::exact(400.0, 60.0));
        let frame = tree.render();
        let ring = frame
            .shapes
            .iter()
            .find(|s| s.color == ring_color && s.stroke_width > 0.0)
            .expect("a focused crumb strokes its ring")
            .screen;
        let visual = frame
            .shapes
            .iter()
            .find(|s| s.color == fill_color && s.stroke_width == 0.0)
            .expect("a focused crumb fills its visual")
            .screen;
        (ring, visual)
    }

    #[test]
    fn a_negative_focus_ring_offset_lays_the_ring_over_the_crumb_edge() {
        let (outer, outer_visual) = crumb_ring_and_visual(2.0);
        let (inner, inner_visual) = crumb_ring_and_visual(-1.0);
        // Offset 2: centre line 3 dp outside the visual. Offset -1, width
        // 2: centred on the visual's edge.
        assert!((outer[2] - outer_visual[2] - 6.0).abs() < 1e-3);
        assert!((inner[2] - inner_visual[2]).abs() < 1e-3);
        assert!((inner[3] - inner_visual[3]).abs() < 1e-3);

        let (deep, _) = crumb_ring_and_visual(-100.0);
        assert!(deep[2] >= 0.0 && deep[3] >= 0.0, "ring inverted: {deep:?}");
    }

    // ── tooltips ─────────────────────────────────────────────────────────────

    #[test]
    fn breadcrumb_tooltip_appears_after_the_hover_delay() {
        // Regression: `BreadcrumbItem::tooltip()` / `.rich_tooltip*()` /
        // `.composite_tooltip()` set their fields, but `Breadcrumb::item()`
        // copied only label/action/current into the entry — so all four
        // setters were silently dead. Nothing in this module hovered a
        // segment, so nothing caught it.
        let mut tree = themed_tree();
        let bc = Breadcrumb::new()
            .item(BreadcrumbItem::new(lit!("Home")).on_activate_fn(|_| {}))
            .item(BreadcrumbItem::current(lit!("Here")).tooltip(lit!("Where you are")));
        tree.add(bc);
        tree.layout(SizeProposal::exact(400.0, 60.0));

        let segment = tree
            .find_by_label("Here")
            .expect("the current crumb renders");
        tree.pointer_move(tree.bounds(segment).center());
        assert!(
            tree.active_overlays().is_empty(),
            "must wait for the hover delay"
        );

        let delay = tree.theme().motion.tooltip_delay;
        tree.advance_time(delay + std::time::Duration::from_millis(50));
        assert_eq!(
            tree.active_overlays().len(),
            1,
            "a breadcrumb crumb's tooltip must actually open"
        );
        assert!(tree.find_by_label("Where you are").is_some());
    }

    #[test]
    fn a_crumb_contributes_a_tooltip_entry_only_when_it_has_one() {
        // Measured as a delta against the identical trail, so the count is
        // unaffected by whatever chrome the breadcrumb attaches on its own
        // (the overflow chevron carries a tooltip of its own).
        let mut bare = themed_tree();
        bare.add(trail(3));
        bare.layout(SizeProposal::exact(400.0, 60.0));
        let baseline = bare.tooltip_entry_count();

        let mut tipped = themed_tree();
        let bc = Breadcrumb::new()
            .item(BreadcrumbItem::new(lit!("Crumb 0")).on_activate_fn(|_| {}))
            .item(BreadcrumbItem::new(lit!("Crumb 1")).on_activate_fn(|_| {}))
            .item(BreadcrumbItem::current(lit!("Crumb 2")).tooltip(lit!("Tip")));
        tipped.add(bc);
        tipped.layout(SizeProposal::exact(400.0, 60.0));

        assert_eq!(
            tipped.tooltip_entry_count(),
            baseline + 1,
            "exactly the one crumb carrying a tooltip adds an entry"
        );
    }

    // ── compute_breadcrumb_overflow ──────────────────────────────────────────

    #[test]
    fn nothing_collapses_when_it_all_fits() {
        let flags = compute_breadcrumb_overflow(
            500.0,
            &[40.0, 40.0, 40.0, 40.0, 40.0],
            &[false, true, true, true, false],
            30.0,
        );
        assert_eq!(flags, vec![false; 5]);
    }

    #[test]
    fn middle_collapses_from_the_left_keeping_root_and_current() {
        // full = 200 > 160. hide #1 → 40*4+30=190 > 160; hide #2 → 40*3+30=150 ≤ 160.
        let flags = compute_breadcrumb_overflow(
            160.0,
            &[40.0, 40.0, 40.0, 40.0, 40.0],
            &[false, true, true, true, false],
            30.0,
        );
        assert_eq!(flags, vec![false, true, true, false, false]);
    }

    #[test]
    fn all_middle_collapses_when_very_narrow() {
        let flags = compute_breadcrumb_overflow(
            100.0,
            &[40.0, 40.0, 40.0, 40.0, 40.0],
            &[false, true, true, true, false],
            30.0,
        );
        assert_eq!(
            flags,
            vec![false, true, true, true, false],
            "root and current always survive; all middle collapse"
        );
    }

    #[test]
    fn two_crumbs_never_collapse() {
        let flags = compute_breadcrumb_overflow(10.0, &[40.0, 40.0], &[false, false], 30.0);
        assert_eq!(flags, vec![false, false], "no collapsible middle to hide");
    }

    // ── Integration ──────────────────────────────────────────────────────────

    #[test]
    fn wide_trail_does_not_overflow_narrow_does() {
        let bc = trail(6);
        let overflowing = bc.is_overflowing();
        let mut tree = themed_tree();
        let _id = tree.add(bc);

        tree.layout(SizeProposal::exact(2000.0, 30.0));
        assert!(!overflowing.get(), "a wide trail should not overflow");

        tree.layout(SizeProposal::exact(160.0, 30.0));
        assert!(
            overflowing.get(),
            "a narrow trail should collapse middle crumbs into the … menu"
        );

        tree.layout(SizeProposal::exact(2000.0, 30.0));
        assert!(
            !overflowing.get(),
            "re-widening restores all crumbs (intrinsic measure → no stale collapse)"
        );
    }

    #[test]
    fn overflow_menu_rows_are_dormant_while_the_chevron_is_closed() {
        // The collapsed crumbs' menu rows live in the (closed) chevron popover;
        // they must not render until it opens.
        let bc = trail(6);
        let mut tree = themed_tree();
        let _id = tree.add(bc);
        tree.layout(SizeProposal::exact(160.0, 30.0)); // narrow → middle collapses

        let active_menu_items: u32 = tree
            .widget_type_histogram()
            .iter()
            .filter(|(k, _)| k.contains("menu_item::MenuItem"))
            .map(|(_, v)| *v)
            .sum();
        assert_eq!(
            active_menu_items, 0,
            "overflow menu rows stay dormant until the … chevron opens"
        );
    }

    #[test]
    fn builds_under_rtl() {
        use teksilo_core::environment::LayoutDirection;
        let bc = trail(5);
        let mut tree = themed_tree();
        tree.set_layout_direction(LayoutDirection::RightToLeft);
        let id = tree.add(bc);
        tree.layout(SizeProposal::exact(200.0, 30.0));
        assert!(tree.bounds(id).width > 0.0);
    }

    /// A crumb clears the 24 dp floor at Compact whenever its label gives it
    /// the width, which is the usual case — and where it does not, the
    /// `hit_outset` on `BreadcrumbSegment` makes the shortfall up between the
    /// pointer and the arena rather than moving the trail. This pins the first
    /// half; the second is the shared `target_outset` contract, covered where
    /// it can be measured (`primitives::twist_arrow`).
    #[test]
    fn a_crumb_clears_the_conformance_floor_at_compact() {
        let theme = teksilo_core::presets::intui::light();
        let floor = theme.input.min_target_conformance;
        let mut tree = WidgetTree::new().with_theme(theme);
        let bc = tree.add(
            Breadcrumb::new()
                .item(BreadcrumbItem::new(lit!("A")).on_activate_fn(|_| {}))
                .item(BreadcrumbItem::new(lit!("Files"))),
        );
        tree.layout(SizeProposal::exact(300.0, 40.0));
        let _ = tree.render();
        let crumb = first_crumb(&tree, bc).expect("the trail has crumbs");
        assert!(
            crumb.height >= floor,
            "a Compact crumb measured {crumb:?}, under the {floor} dp floor",
        );
    }

    /// A crumb that measures under the 24 dp floor, in a real trail, inside a
    /// path bar that takes taps of its own.
    ///
    /// The crumb is nameless — an icon-only root crumb, an unnamed drive —
    /// because that is the only label `MockTextBackend` can measure under the
    /// floor: it bills every character at a flat 8 dp and the segment adds 12
    /// dp of padding and 8 dp of focus-ring envelope, so even a one-letter
    /// label comes out at 28 dp. With a real proportional font at
    /// `typography.small`, a drive letter or a one-word folder lands in the
    /// same place, which is the case the module doc names.
    ///
    /// The bar is what makes this test discriminate. The miss-only slop pass
    /// only wins when the exact hit's bubble path carries no eligible handler,
    /// or when its candidate is strictly closer than that path's owner; the bar
    /// owns the press at distance zero, and a near-miss does not beat zero. So
    /// the only mechanism left that can carry a press beside the crumb onto it
    /// is `BreadcrumbSegment`'s own `hit_outset`.
    fn narrow_crumb_in_a_tappable_bar(
        hits: Rc<std::cell::Cell<u32>>,
        bar_taps: Rc<std::cell::Cell<u32>>,
    ) -> (WidgetTree, WidgetId) {
        use teksilo_core::widget_builder::WidgetBuilder;

        let mut tree = themed_tree();
        let trail = tree.add(
            Breadcrumb::new()
                .item(
                    BreadcrumbItem::new(lit!("")).on_activate_fn(move |_| hits.set(hits.get() + 1)),
                )
                .item(BreadcrumbItem::new(lit!("Users")))
                .item(BreadcrumbItem::new(lit!("cyril"))),
        );
        let _bar = tree.add(
            crate::primitives::HStack::new()
                .child(trail)
                .on_tap(move |_e, _c| bar_taps.set(bar_taps.get() + 1)),
        );
        tree.layout(SizeProposal::exact(300.0, 40.0));
        let _ = tree.render();
        let crumb = first_segment_id(&tree, trail).expect("the trail has crumbs");
        (tree, crumb)
    }

    /// The trail's segments, in reading order.
    fn segment_ids(tree: &WidgetTree, trail: WidgetId) -> Vec<WidgetId> {
        let mut found: Vec<(WidgetId, f32)> = Vec::new();
        let mut stack = vec![trail];
        while let Some(id) = stack.pop() {
            if tree
                .widget_type_name(id)
                .is_some_and(|n| n.contains("BreadcrumbSegment"))
            {
                found.push((id, tree.bounds(id).x));
            }
            stack.extend(tree.children(id).iter().copied());
        }
        found.sort_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal));
        found.into_iter().map(|(id, _)| id).collect()
    }

    /// The leading, narrowest segment of the trail.
    fn first_segment_id(tree: &WidgetTree, trail: WidgetId) -> Option<WidgetId> {
        segment_ids(tree, trail).into_iter().next()
    }

    /// A crumb that lands under the floor earns the shortfall between the
    /// pointer and the arena, so the trail's own geometry never moves.
    #[test]
    fn a_finger_just_outside_a_narrow_crumb_still_navigates() {
        use crate::button::press_test_support::{finger, touch};
        use teksilo_core::pointer::PointerPhase;

        let hits = Rc::new(std::cell::Cell::new(0_u32));
        let bar_taps = Rc::new(std::cell::Cell::new(0_u32));
        let (mut tree, crumb) = narrow_crumb_in_a_tappable_bar(hits.clone(), bar_taps.clone());
        let b = tree.bounds(crumb);
        assert!(
            b.width < 24.0,
            "the crumb is meant to be under the floor, got {b:?}"
        );
        // 1.5 dp past the crumb, inside the 24 dp target the outset earns it.
        let at = teksilo_canvas::Point::new(b.right() + 1.5, b.center().y);
        let id = finger();
        tree.dispatch_pointer(touch(id, PointerPhase::Down, at, 0));
        tree.dispatch_pointer(touch(id, PointerPhase::Up, at, 30));
        assert_eq!(hits.get(), 1, "the crumb's outset did not take the press");
        assert_eq!(bar_taps.get(), 0, "and the bar must not have taken it too");
    }

    /// The current crumb navigates nowhere, so it claims no widened target: a
    /// node that widens itself and then refuses the press is a hole punched in
    /// the path bar behind it.
    ///
    /// Read off the **mounted** crumbs, because the outset is derived from what
    /// each one painted — an unmounted segment has painted nothing and would
    /// report `ZERO` whatever the gate said.
    #[test]
    fn only_the_navigating_crumb_declares_an_outset() {
        use teksilo_tokens::PointerKind;

        let mut tree = themed_tree();
        // Two nameless crumbs, so both land on the same 20 dp geometry: the
        // first navigates, the last is the current one.
        let trail = tree.add(
            Breadcrumb::new()
                .item(BreadcrumbItem::new(lit!("")).on_activate_fn(|_| {}))
                .item(BreadcrumbItem::new(lit!(""))),
        );
        tree.layout(SizeProposal::exact(300.0, 40.0));
        let _ = tree.render();

        let crumbs = segment_ids(&tree, trail);
        assert_eq!(crumbs.len(), 2, "two crumbs, got {crumbs:?}");
        for id in &crumbs {
            assert!(
                tree.bounds(*id).width < 24.0,
                "premise: both crumbs are under the floor",
            );
        }
        assert_ne!(
            tree.widget_hit_outset(crumbs[0], PointerKind::Touch),
            teksilo_canvas::EdgeInsets::ZERO,
            "the navigating crumb earns its shortfall",
        );
        assert_eq!(
            tree.widget_hit_outset(crumbs[1], PointerKind::Touch),
            teksilo_canvas::EdgeInsets::ZERO,
            "the current crumb navigates nowhere and must claim nothing",
        );
    }

    /// A built crumb that navigates still offers AT a way to activate it, and
    /// the current one offers none. Read off the **mounted** crumbs: `build`
    /// moves the action out, so a check that asked for it would see none.
    #[test]
    fn a_built_navigating_crumb_advertises_click_and_focus() {
        use teksilo_core::accesskit::Action;

        let mut tree = themed_tree();
        let trail = tree.add(trail(2));
        tree.layout(SizeProposal::exact(300.0, 40.0));
        let _ = tree.render();

        let crumbs = segment_ids(&tree, trail);
        assert_eq!(crumbs.len(), 2, "two crumbs, got {crumbs:?}");
        let navigating = tree.accessibility_node(crumbs[0]);
        assert!(
            navigating.actions().contains(&Action::Click),
            "a navigating crumb must advertise Click, or AT cannot follow it",
        );
        assert!(
            navigating.actions().contains(&Action::Focus),
            "a navigating crumb must advertise Focus",
        );
        let current = tree.accessibility_node(crumbs[1]);
        assert!(
            !current.actions().contains(&Action::Click),
            "the current crumb navigates nowhere and must not advertise Click",
        );
    }

    /// A mouse is exact: the same press lands on the path bar, exactly as it
    /// did before the touch programme.
    #[test]
    fn a_mouse_just_outside_a_narrow_crumb_lands_on_the_bar() {
        let hits = Rc::new(std::cell::Cell::new(0_u32));
        let bar_taps = Rc::new(std::cell::Cell::new(0_u32));
        let (mut tree, crumb) = narrow_crumb_in_a_tappable_bar(hits.clone(), bar_taps.clone());
        let b = tree.bounds(crumb);
        let at = teksilo_canvas::Point::new(b.right() + 1.5, b.center().y);
        tree.pointer_down_button(at, teksilo_core::event::PointerButton::Primary);
        tree.pointer_up_button(at, teksilo_core::event::PointerButton::Primary);
        assert_eq!(
            hits.get(),
            0,
            "a mouse must not be given the crumb's outset"
        );
        assert_eq!(bar_taps.get(), 1);
    }

    /// A finger tap navigates on the release, like every other tap target in
    /// the sweep.
    #[test]
    fn a_touch_tap_on_a_crumb_navigates_on_release() {
        use crate::button::press_test_support::{finger, touch};
        use teksilo_core::pointer::PointerPhase;

        let hits = std::rc::Rc::new(std::cell::Cell::new(0_u32));
        let count = hits.clone();
        let mut tree = WidgetTree::new().with_theme(teksilo_core::presets::intui::light());
        let bc = tree.add(
            Breadcrumb::new()
                .item(
                    BreadcrumbItem::new(lit!("A"))
                        .on_activate_fn(move |_| count.set(count.get() + 1)),
                )
                .item(BreadcrumbItem::new(lit!("Files"))),
        );
        tree.layout(SizeProposal::exact(300.0, 40.0));
        let _ = tree.render();
        let crumb = first_crumb(&tree, bc).expect("the trail has crumbs");
        let at = crumb.center();
        let id = finger();
        tree.dispatch_pointer(touch(id, PointerPhase::Down, at, 0));
        assert_eq!(hits.get(), 0, "the press navigates nowhere");
        tree.dispatch_pointer(touch(id, PointerPhase::Up, at, 30));
        assert_eq!(hits.get(), 1, "the release does");
    }

    fn first_crumb(
        tree: &WidgetTree,
        trail: teksilo_core::widget_id::WidgetId,
    ) -> Option<teksilo_canvas::Rect> {
        let mut best: Option<teksilo_canvas::Rect> = None;
        let mut stack = vec![trail];
        while let Some(id) = stack.pop() {
            if tree
                .widget_type_name(id)
                .is_some_and(|t| t.contains("BreadcrumbSegment"))
            {
                let b = tree.bounds(id);
                if best.is_none_or(|c| b.x < c.x) {
                    best = Some(b);
                }
            }
            stack.extend(tree.children(id).iter().copied());
        }
        best
    }
}