teksilo_widgets/

grid_view.rs

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

//! Virtualized 2D tile grid bound to a `ListModel<T>` / `ListDataSource`.
//!
//! `GridView` is the photo-gallery / icon-view / file-manager-grid /
//! collection-view widget — the 2D sibling of [`ListView`](crate::list_view::ListView)
//! and [`TableView`](crate::table_view::TableView). It realizes only the
//! tiles currently visible (plus a buffer), reflows on resize, supports
//! single / multi selection with 2D keyboard navigation, and is fully
//! accessible (`Role::Grid` → `Role::GridCell`).
//!
//! The layout is pluggable via `GridLayoutStrategy`: the stock
//! [`UniformGrid`] gives fixed tile size / fixed column count /
//! adaptive min-width grids, [`VariableRowGrid`] sizes each row to its
//! tallest tile, and [`VirtualizedMasonry`] flows items into the
//! currently-shortest column. Marquee selection, drag-reorder, sections
//! and sticky headers are layered over whichever one is in force.
//!
//! ```ignore
//! GridView::new(model, |tc| {
//!     Box::new(Card::new().child(TextWidget::new(lit!(&tc.item.name))))
//! })
//! .sizing(GridSizing::Adaptive { min_width: 120.0, max_width: None, height: 140.0 })
//! .spacing(8.0)
//! .selection(selection_model)
//! ```
//!
//! ## Column bounds and alignment
//!
//! [`GridView::min_columns`] and [`GridView::max_columns`] bound the column
//! count that [`GridSizing::Fixed`] and [`GridSizing::Adaptive`] derive from the
//! width ([`GridSizing::FixedColumnCount`] ignores both). A floor the width
//! cannot afford **narrows** the tiles to share it, never overflowing
//! horizontally; the tile height stays the sizing's. [`GridView::column_alignment`]
//! places a block of columns narrower than the content at the leading edge (the
//! default), the centre or the trailing edge, swapping sides in a right-to-left
//! layout. Section headers and the detail band keep spanning the content width;
//! tiles, the rubber band, the insertion bar and the focus ring follow the
//! offset. An album grid of fixed 182 dp cards, two to ten columns, centred:
//!
//! ```ignore
//! GridView::new(albums, |tc| album_card(tc))
//!     .sizing(GridSizing::Fixed { width: 182.0, height: 230.0 })
//!     .min_columns(2)
//!     .max_columns(10)
//!     .column_alignment(HAlignment::Center)
//! ```
//!
//! ## Selection by position or by key
//!
//! [`GridView::selection`] takes a [`SelectionModel`], which holds positions.
//! A grid that is sorted or filtered under its selection, or fed by a lazy
//! source, is built with [`GridView::from_source_keyed`] instead: a
//! [`KeyedSelectionModel`] holds the source's keys, so the selection stays on
//! the same items when they move. Both reach the grid through the facade the
//! other data views use (`data_views::RowSelection`), which turns each click,
//! key and rubber band into an index or a key.
//!
//! ## The detail band
//!
//! [`GridView::detail_row`] gives a tile a full-width band that opens directly
//! under the row holding it, the "album expansion" of a music library. The
//! band is not a tile and not a row of the grid: a layout strategy wrapped
//! around the grid's own (`detail::DetailRowStrategy`) moves everything below
//! the open row down by the band, so virtualization, the scroll range, the
//! focus ring and the rubber band account for it without knowing about it, and
//! tiles keep their row and column numbers. The band widget is a child of this
//! root rather than of the body pane, so it survives the pane's rebuilds on
//! scroll and resize, and a lazy source loading a window. A waterfall has no
//! rows and ignores it. See the module docs of `grid_view/detail.rs`.
//!
//! Focus inside the band is revealed like focus anywhere: this root answers
//! the framework's `WidgetEvent::ScrollIntoView`, which a scroll container is
//! sent when a descendant it clips takes focus.
//!
//! ## Scrolling from outside
//!
//! [`GridView::handle`] returns a [`GridViewHandle`], a cheap clone usable
//! before the grid is mounted and through all its rebuilds:
//! [`scroll_to_index`](GridViewHandle::scroll_to_index),
//! [`ensure_index_visible`](GridViewHandle::ensure_index_visible) and
//! [`reveal_band`](GridViewHandle::reveal_band) (a tile and its open band
//! together). A handle computes no offset when it is called: it records the
//! request, and the next layout applies it once the band is measured and the
//! scroll anchoring has run. Opening a band and scrolling to a tile under it
//! in one turn therefore lands the tile where it was asked to be, which an
//! offset written from outside does not: the layout keeps the content under
//! the top edge still across the band opening, and takes that offset for
//! one of the old layout. The builder's own `scroll_to_index` and
//! `ensure_index_visible` act at call time, so before the first layout they
//! do nothing.
//!
//! ```ignore
//! let handle = grid.handle();
//! // later, from a command:
//! expanded.set(Some(album));
//! handle.reveal_band(album);
//! ```
//!
//! ## The keyboard cursor
//!
//! The grid has one current tile, its keyboard cursor: the tile the arrow
//! keys step from, the one the focus ring marks while the grid holds keyboard
//! focus, and the one it names to assistive technology as its active
//! descendant. The same [`GridViewHandle`] reads and moves it:
//! [`cursor`](GridViewHandle::cursor),
//! [`set_cursor`](GridViewHandle::set_cursor) (clamped to the last tile;
//! keyboard focus, the selection and the scroll offset are left alone) and
//! [`cursor_signal`](GridViewHandle::cursor_signal), which an application
//! observes to key a status line or its context actions on the current tile.
//! Like a reveal, a cursor set before the grid is mounted is there at its
//! first build.
//!
//! The cursor and the selection are one tile in a single selection: the keys
//! move them together, and a selection written from outside moves the cursor
//! onto it. In a multiple selection they are **separate**: `Ctrl+Arrow` moves
//! the cursor and leaves the selection, so after `→`, `Ctrl+→`, `Ctrl+↓` the
//! selection is still tile 0 while the cursor, the ring and the active
//! descendant are on tile 4 (in three columns), and a selection written from
//! outside leaves the cursor where it was. Read the cursor, not the first
//! selected tile, for "the tile the user is on".
//!
//! An open [detail band](GridView::detail_row) is on the keyboard path
//! already: `↓` on the open tile moves focus into its band, onto its first
//! control, while the cursor stays on the tile, and `↑` from the band's top
//! comes back to it. A band with no control to focus is stepped over. An
//! application has no walk of its own to write.
//!
//! ## A long band
//!
//! A band that holds hundreds of rows, an album's tracks say, need not build
//! them all. [`GridView::detail_visible_span_signal`] publishes the part of
//! the open band on screen, in band-local coordinates, and only when it
//! changes, so the band can realize the rows in the span and stand spacers
//! in for the rest, with no copy of the grid's placement arithmetic:
//!
//! ```ignore
//! const ROW: f32 = 24.0;
//! let grid = GridView::new(albums, album_card);
//! let span = grid.detail_visible_span_signal().clone();
//! grid.detail_row(move |tc| {
//!     let n = tc.item.tracks.len();
//!     let first = span.map(|s| s.as_ref().map_or(0, |r| (r.start / ROW) as usize));
//!     let last = span.map(move |s| {
//!         s.as_ref().map_or(0, |r| ((r.end / ROW).ceil() as usize).min(n))
//!     });
//!     // `window` holds tracks[first..last], refilled when the span moves.
//!     let window = track_window(&tc.item.tracks, &first, &last);
//!     Some(Box::new(
//!         VStack::new()
//!             .child(FixedSize::new().height(first.map(|f| *f as f32 * ROW)))
//!             .child(Repeater::new(window, |track| track_row(track)))
//!             .child(FixedSize::new().height(last.map(move |l| (n - *l) as f32 * ROW))),
//!     ))
//! })
//! ```
//!
//! ## Pan to scroll
//!
//! The view installs [`common::scrollable::ScrollableBehavior`](crate::common::scrollable::ScrollableBehavior),
//! which gives it the shared wheel arithmetic, a finger's pan and the
//! `PanClaim` that puts it on a pan's claimant chain. A pan scrolls it, the
//! release coasts, and a pan it cannot absorb hands the **whole** event to the
//! container outside — never a residual. Vertical only, despite the grid: this
//! view owns no horizontal offset, so a horizontal pan is declined and chains
//! outward. A pan that starts on a tile scrolls rather than activating it.
//!
//! ## The rubber band, and why it is not on this node
//!
//! In [`teksilo_data::SelectionMode::Multi`] a drag on the empty background
//! sweeps a selection rectangle. That drag deliberately does **not** live on
//! this view's own node, which is the one carrying the `PanClaim`.
//!
//! The reason it *was* structural has since been fixed in the framework: a node
//! that both declares a claim and carries `on_drag` is now given a say through
//! `PointerSequence::defer_own_drag`, which resolves its
//! [`teksilo_tokens::DragActivation`] against the claim it is competing with.
//! Before that arm existed the claim holder's own drag latched at `drag_slop`
//! and decided the sequence before the claim could win at `pan_slop`, so a
//! `Multi`-selection grid did not scroll under a finger from anywhere at all,
//! and a finger on the background swept a band immediately rather than after a
//! hold.
//!
//! What the surface still buys is **scope**, and that is why it stays. This
//! root's children are the body pane, the scrollbar, the pinned section header,
//! the empty view, the loading view and the focus overlay — all siblings, most
//! of them filling the same rectangle. A marquee hung here would be a drag
//! ancestor of every one of them; hung on a `DragSurface` that encloses the body
//! pane alone, it sweeps the background and nothing else. The wrapper is also
//! not this view's to remove in any case: the four row views wrap each **row**
//! in one, and a row is not a claimant, so `defer_own_drag` — which refuses
//! anything but a live `MemberRole::Pan` member — cannot reach it. See
//! `crate::data_views::DragSurface`.
//!
//! So the body pane carries a no-op tap that gives it an arena of its own (the
//! press is captured *inside* the surface, not by it) and the marquee's drag
//! hangs on a `DragSurface` that strictly encloses the pane — the shape the tree
//! arms `DragActivation` for through its ancestor walk, which is what makes the
//! marquee wait for a long press under a finger and latch at 5 dp under a mouse.
//!
//! Every **tile** carries that same no-op tap as well, for a reason with nothing
//! to do with dragging. With the pane holding one, a tile without an arena of
//! its own leaves the *pane* as the press captor — and a release is dispatched
//! to the captor and then bubbled target→root, which never reaches a tile
//! beneath it. A plain selectable grid lost both its finger tap and, under a
//! mouse, the release that collapses a multi-selection that way.

pub(crate) mod a11y;
pub(crate) mod body_pane;
pub(crate) mod detail;
pub(crate) mod drag;
pub(crate) mod handle;
pub(crate) mod keyboard;
pub mod layout;
pub mod sections;
pub(crate) mod selection;
pub(crate) mod selection_count;
#[cfg(test)]
mod tests;

use std::cell::{Cell, RefCell};
use std::collections::BTreeSet;
use std::rc::Rc;

use teksilo_canvas::{EdgeInsets, Point, Rect, Size, SizeProposal};
use teksilo_core::accessibility::{AccessNodeBuilder, widget_id_to_node_id};
use teksilo_core::binding::BindingLevel;
use teksilo_core::build_context::BuildContext;
use teksilo_core::drag_payload::DragPayload;
use teksilo_core::event::{EventResponse, WidgetEvent};
use teksilo_core::kinetic::KineticScroller;
use teksilo_core::pointer::touch_action::PanAxes;
use teksilo_core::signal::{Prop, Signal};
use teksilo_core::styles::GridViewStyle;
use teksilo_core::widget::{LayoutContext, PaintContext, Widget, WidgetPlacement};
use teksilo_core::widget_builder::HandlerSet;
use teksilo_core::widget_id::WidgetId;
use teksilo_data::{
    DataChange, DropPosition, DropResponse, ItemKey, KeyedSelectionModel, ListModel, SelectionMode,
    SelectionModel,
};
use teksilo_tokens::{HAlignment, OverscrollStyle, SurfaceRole};

use std::time::Duration;

use crate::common::scroll::OverscrollBehavior;
use crate::data_views::{
    DragTransferMode, RowDragData, RowSelection, ViewId, ViewKind, flat_insertion_target,
};
use crate::list_source::ListSource;
use crate::primitives::TextWidget;
use crate::scroll_area::ScrollBarMode;
use crate::scroll_bar::{ScrollBar, ScrollBarOrientation, ScrollBarVisual};

use body_pane::{GridBodyPane, TileDelegate};
use keyboard::{GridKeyConfig, build_grid_key_handler};
use layout::masonry::VirtualizedMasonry;
use layout::sectioned::SectionedGrid;
use layout::strategy::{GridLayoutStrategy, TileRect};
use layout::uniform::UniformGrid;
use layout::variable_row::VariableRowGrid;
use sections::SectionData;
use selection::{MarqueeConfig, MarqueeState, build_marquee_handler};
use selection_count::{SelectionCountVoice, selection_count_words};

/// [`SectionProvider`] under the name it first shipped with, when only
/// `GridView` had sections. Both names are the one trait.
pub use sections::SectionProvider as GridSectionProvider;
pub use sections::{GroupingSections, SectionProvider, grouping_sections};

/// Which layout strategy `GridView` builds.
#[derive(Debug, Clone, Copy)]
enum StrategyKind {
    /// Fixed row height (the default).
    Uniform,
    /// Each row sized to its tallest tile; `estimated` seeds unmeasured rows.
    VariableRow { estimated: f32 },
    /// Pinterest-style column-balanced waterfall; per-item variable height.
    Waterfall { estimated: f32 },
}

pub use handle::GridViewHandle;
pub use keyboard::GridTabTraversal;
pub use layout::{GridSizing, ScrollAnchor};

/// The erased `can_accept` closure type carried by the grid's source.
type CanAcceptFn = Rc<dyn Fn(&DragPayload, usize, DropPosition, ViewId) -> DropResponse>;

/// Whether a drop at flat insertion `idx` is allowed: the source accepts it
/// (same-view reorder, or a source that handles the foreign payload directly),
/// the grid accepts foreign exported tiles via `accept_foreign_rows`, OR it is
/// a foreign payload and the grid carries an app-level `on_item_drop` handler.
fn drop_allowed<T: 'static>(
    can_accept: &CanAcceptFn,
    payload: &DragPayload,
    idx: usize,
    len: usize,
    view_id: ViewId,
    has_drop_cb: bool,
    export: &crate::data_views::RowExport<T>,
) -> bool {
    match flat_insertion_target(idx, len) {
        Some((target, position)) => match (can_accept)(payload, target, position, view_id) {
            DropResponse::Accept | DropResponse::Redirect(_) => true,
            DropResponse::Reject => {
                let foreign = is_foreign::<T>(payload, view_id);
                foreign && (has_drop_cb || export.accepts_foreign_export(payload, view_id))
            }
        },
        None => false,
    }
}

/// A payload is foreign to this grid when it is not a `RowDragData<T>`
/// originating here (an external app/OS drop, or a tile dragged from
/// another view).
fn is_foreign<T: 'static>(payload: &DragPayload, view_id: ViewId) -> bool {
    payload
        .get_typed::<RowDragData<T>>()
        .is_none_or(|rd| rd.source != view_id)
}

/// Scrollbar thickness, matching `ListView` / `TableView`.
const SCROLLBAR_THICKNESS: f32 = 12.0;

/// Context passed to the tile delegate for each realized tile.
///
/// Richer than `ListView`'s `(index, &item, selected)` — carries the 2D
/// grid coordinates and focus state (mirrors `TableView`'s `CellContext`).
/// There is intentionally **no** `is_hovered`: hover changes on every
/// mouse-move and is handled per-tile inside the delegate's own widget
/// (its interaction signal), never by rebuilding the grid.
pub struct TileContext<'a, T: 'static> {
    /// Flat model index.
    pub index: usize,
    /// Row in the logical grid (0-based).
    pub row: usize,
    /// Column in the logical grid (0-based).
    pub col: usize,
    /// Borrow of the item.
    pub item: &'a T,
    /// Whether this tile is in the selection set.
    pub is_selected: bool,
    /// Whether this tile is the keyboard-focus current item. A build-time
    /// snapshot — the canonical focus indicator is the grid's painted focus
    /// ring (it does not rebuild tiles), so a delegate reading this for
    /// custom styling accepts a one-rebuild lag.
    pub is_focused: bool,
}

/// A virtualized 2D tile grid backed by a `ListModel<T>`.
pub struct GridView<T: 'static> {
    source: ListSource<T>,
    delegate: TileDelegate<T>,

    // Layout configuration (consumed when the strategy is first built).
    /// The resolved tile sizing. When `sizing_signal` is set (a reactive
    /// `.sizing(signal)`), `build()` refreshes this from the signal and rebuilds
    /// the cached strategy on change — the slider-driven live-resize path.
    sizing: GridSizing,
    /// Reactive tile sizing, if bound via `.sizing(impl Into<Prop<GridSizing>>)`.
    /// `None` for the static `.sizing(GridSizing::…)` / `.tile_size` / `.column_count`
    /// sugar. Mirrors `TabWidget`'s `sizing: Option<Signal<TabSizing>>`.
    sizing_signal: Option<Signal<GridSizing>>,
    col_gap: f32,
    row_gap: f32,
    inset: EdgeInsets,
    /// Column-count bounds and leftover alignment, handed to the strategy.
    column_options: layout::columns::ColumnOptions,
    strategy_kind: StrategyKind,
    /// Exact per-item natural height (the variable-height fast-path).
    #[allow(clippy::type_complexity)]
    exact_item_height: Option<Rc<dyn Fn(usize) -> f32>>,
    /// Lazily built on first `build()` and cached so variable-height
    /// strategies keep their measurement caches across rebuilds.
    strategy: Option<Rc<dyn GridLayoutStrategy>>,

    // Selection / focus
    /// The index-based [`SelectionModel`] or a [`KeyedSelectionModel`] behind
    /// the facade every data view reads its selection through. Clicks, keys,
    /// the marquee and the tiles all work in indices; the keyed backing turns
    /// them into keys, so the selection follows its items through a sort, a
    /// filter or a window slide.
    selection: Option<RowSelection>,
    #[allow(clippy::type_complexity)]
    on_selection_changed: Option<Rc<dyn Fn(&BTreeSet<usize>)>>,
    focused_index: Signal<Option<usize>>,
    /// Enable rubber-band marquee (default true; only active in Multi mode).
    marquee_selection: bool,
    marquee: Signal<Option<MarqueeState>>,

    // Keyboard
    wrap_navigation: bool,
    tab_traversal: GridTabTraversal,

    // Scroll
    show_scrollbar: bool,
    overscroll_behavior: OverscrollBehavior,
    /// Animate wheel scrolling instead of snapping to the new offset.
    /// Enabled by default — mirrors `ScrollArea`.
    smooth_scrolling: bool,
    /// Duration of the smooth scroll animation.
    smooth_scroll_duration: Duration,
    /// How the scroll bar is displayed. Defaults to `Permanent` (reserves
    /// a layout column); `Overlay` / `Thin` float over the content.
    scroll_bar_style: ScrollBarMode,
    scroll_y: Signal<f32>,
    max_scroll_y: Signal<f32>,
    viewport_ratio_y: Signal<f32>,
    /// Shared with every [`GridViewHandle`]: the reveal a handle recorded,
    /// for `place_children` to apply, and the trigger it relays out with.
    reveal: Rc<handle::RevealShared>,
    /// Live column count for the current viewport width. Written in
    /// `place_children`; drives the body pane's reflow rebuild on resize and
    /// is read by the keyboard handler.
    column_count: Signal<usize>,

    // Drag-to-reorder + drop
    reorderable: bool,
    #[allow(clippy::type_complexity)]
    on_item_drop: Option<
        Rc<
            dyn Fn(
                teksilo_core::drag_payload::DragPayload,
                usize,
                &mut teksilo_core::widget::EventContext,
            ) -> bool,
        >,
    >,
    /// Insertion index during a reorder drag (painted by `GridOverlay`).
    insertion: Signal<Option<usize>>,
    /// Stable, kind-tagged ID for this GridView instance (identifies its own
    /// reorder vs. a foreign drop, even across widget kinds / windows).
    model_id: ViewId,

    /// Cross-widget export / foreign-receive machinery — the builders
    /// (`.exportable`, `.export_external`, `.accept_foreign_rows`,
    /// `.on_rows_received`, `.on_rows_transferred_out`), the drag-start payload
    /// build, and the move-out completion, shared by all five data views.
    export: crate::data_views::RowExport<T>,

    // Activation / context menu / type-ahead
    #[allow(clippy::type_complexity)]
    on_tile_activate: Option<Rc<dyn Fn(usize, &mut teksilo_core::widget::EventContext)>>,
    /// Whether tile activation is a single or double click (default
    /// `DoubleClick`). Enter always activates.
    activate_on: crate::data_views::ActivateOn,
    #[allow(clippy::type_complexity)]
    tile_context_menu: Option<
        Rc<
            dyn Fn(
                usize,
                Point,
                &mut teksilo_core::widget::EventContext,
            ) -> Option<Box<dyn Widget>>,
        >,
    >,
    type_ahead_timeout: std::time::Duration,
    /// Accumulate-and-search state for type-ahead. A widget field, not a
    /// handler local: the buffer has to survive the rebuild a selection or
    /// scroll change triggers, or a two-key search resets between the
    /// keystrokes. `common::type_ahead`'s module doc says as much, and
    /// `ListView` has always held it this way.
    type_ahead: Rc<crate::common::type_ahead::TypeAheadState>,
    #[allow(clippy::type_complexity)]
    type_ahead_label: Option<Rc<dyn Fn(usize) -> String>>,
    /// Per-tile accessible name — sets each `GridCell`'s `Node::label` so a
    /// screen reader announces a concise item name ("Title, Type") instead of
    /// only the grid coordinates. `None` leaves the cell name to its contents.
    #[allow(clippy::type_complexity)]
    tile_a11y_label: Option<Rc<dyn Fn(usize) -> String>>,

    // Empty / loading state
    #[allow(clippy::type_complexity)]
    empty_view: Option<Rc<dyn Fn() -> Box<dyn Widget>>>,
    #[allow(clippy::type_complexity)]
    loading_view: Option<Rc<dyn Fn() -> Box<dyn Widget>>>,
    is_loading: Option<Prop<bool>>,
    loading_id: Option<WidgetId>,

    // Sections
    section_data: Option<SectionData>,
    #[allow(clippy::type_complexity)]
    header_delegate: Option<Rc<dyn Fn(usize, &str) -> Box<dyn Widget>>>,
    header_height: f32,
    pinned_section_headers: bool,
    current_section: Signal<usize>,
    pinned_header_id: Option<WidgetId>,

    // Accessibility
    a11y_label: Option<String>,
    /// Shared map (flat index → tile wrapper id), written by the body pane,
    /// read by `accessibility` for `active_descendant` roving focus.
    tile_map: Rc<std::cell::RefCell<Vec<(usize, WidgetId)>>>,

    /// Per-call Tier-3 decoration style override (focus ring / marquee /
    /// insertion bar / pinned header). `None` → theme slot → stock default.
    style: Option<Rc<dyn GridViewStyle>>,

    // Geometry (synchronous cells, read within the layout pass)
    viewport_width: Rc<Cell<f32>>,
    viewport_height: Rc<Cell<f32>>,
    /// This surface's pan physics: the range a finger's pan is clamped to and
    /// the offset it is currently holding. Owned by the view rather than by
    /// the [`ScrollableBehavior`](crate::common::scrollable::ScrollableBehavior)
    /// so it survives a rebuild, and so `place_children` — the only pass that
    /// knows the viewport extent — can publish into it.
    scroller: Rc<RefCell<KineticScroller>>,
    /// The grid body pane's absolute (window) origin, published by
    /// `GridBodyPane::place_children` (`None` until laid out). Shared into the
    /// keyboard handler so it can chase the focused tile into any enclosing
    /// scroll area (`ctx.ensure_visible`).
    viewport_origin: Rc<Cell<Option<Point>>>,
    /// Remembered scrollbar decision so each layout queries the strategy at a
    /// single, stable body width — querying at two widths per frame would
    /// thrash a variable strategy's per-row measurement cache.
    last_needs_scrollbar: Cell<bool>,

    // Build state
    body_pane_id: Option<WidgetId>,
    empty_id: Option<WidgetId>,
    scrollbar_id: Option<WidgetId>,
    overlay_id: Option<WidgetId>,

    /// Whole-view enabled state, statically or reactively. Forwarded to the
    /// arena via `ctx.enabled_when(self_id, self.enabled.clone())` at build
    /// time; a disabled view greys out and stops accepting focus /
    /// selection / keyboard input (arena-gated).
    enabled: Prop<bool>,

    // Detail band
    /// The disclosed tile (`expanded_index`). A default signal when the
    /// application supplies none, so activation still opens and closes it.
    expanded: Signal<Option<usize>>,
    detail_row: Option<detail::DetailBuilder<T>>,
    /// Which tiles have a band (`detail_row_when`); `None`: every tile may.
    detail_row_when: Option<detail::DetailWhen<T>>,
    detail_row_height: Option<detail::DetailHeightFn>,
    /// Built on the first build when a band is in force, and kept: the
    /// layout, the tiles, the keys and the band share it across rebuilds.
    detail: Option<Rc<detail::DetailState>>,
    /// The layout strategy with the band inserted, kept as its concrete
    /// type for `place_children`, which measures and places the band.
    detail_layout: Option<Rc<detail::DetailRowStrategy>>,
    /// The disclosed tile's anchor, for finding it again after a reset.
    detail_anchor: Rc<RefCell<Option<crate::data_views::RowAnchor>>>,
    band_id: Option<WidgetId>,
    /// The part of the open band on screen, in band-local coordinates
    /// (`detail_visible_span_signal`). Written by `place_children`.
    detail_visible_span: Signal<Option<std::ops::Range<f32>>>,
}

impl<T: 'static> GridView<T> {
    /// Create a grid backed by a `ListModel<T>`. The `delegate` builds the
    /// widget for each tile from a [`TileContext`].
    pub fn new(
        model: ListModel<T>,
        delegate: impl Fn(&TileContext<'_, T>) -> Box<dyn Widget> + 'static,
    ) -> Self {
        Self::create(ListSource::from_model(model), delegate)
    }

    /// Create a grid backed by any `ListDataSource` (large / external data).
    pub fn from_source<S: teksilo_data::ListDataSource<Item = T>>(
        source: S,
        delegate: impl Fn(&TileContext<'_, T>) -> Box<dyn Widget> + 'static,
    ) -> Self {
        Self::create(erase_source(Rc::new(source)), delegate)
    }

    /// Create a grid backed by any `ListDataSource` with **keyed** selection.
    ///
    /// The `KeyedSelectionModel<S::Key>` holds the selected items by the
    /// source's key, not by position, so a selection survives the grid being
    /// sorted (by artist, by year), narrowed by a filter, or a lazy source
    /// sliding its loaded window: it stays on the same items. Clicks,
    /// Ctrl/⌘-clicks, Shift-clicks, the keyboard and the rubber band all write
    /// keys. An item the source no longer shows (removed, or filtered out
    /// here) leaves the selection, as in [`ListView`](crate::ListView).
    ///
    /// [`on_selection_changed`](Self::on_selection_changed) still reports
    /// indices: the positions the selected keys have when the selection
    /// changes. A sort moves them without changing the selection, so it does
    /// not fire. The view stays `GridView<T>`; the index↔key mapping is
    /// captured from the concrete source here. Mutually exclusive with
    /// [`selection`](Self::selection) (the last one set wins).
    pub fn from_source_keyed<S: teksilo_data::ListDataSource<Item = T>>(
        source: S,
        keyed: KeyedSelectionModel<S::Key>,
        delegate: impl Fn(&TileContext<'_, T>) -> Box<dyn Widget> + 'static,
    ) -> Self
    where
        S::Key: ItemKey,
    {
        let s = Rc::new(source);
        let key_at = {
            let s = s.clone();
            Rc::new(move |i| s.key_at(i)) as Rc<dyn Fn(usize) -> Option<S::Key>>
        };
        let len = {
            let s = s.clone();
            Rc::new(move || s.len()) as Rc<dyn Fn() -> usize>
        };
        // Existence for the prune after a removal is the keys of the index
        // space the grid shows, which a lazy source knows before its items
        // load: what `ListView::from_source_keyed` asks too, gathered once per
        // prune instead of scanned once per selected key.
        let selection = RowSelection::from_keyed_flat(keyed, key_at, len);
        let mut view = Self::create(erase_source(s), delegate);
        view.selection = Some(selection);
        view
    }

    fn create(
        source: ListSource<T>,
        delegate: impl Fn(&TileContext<'_, T>) -> Box<dyn Widget> + 'static,
    ) -> Self {
        Self {
            source,
            delegate: Rc::new(delegate),
            sizing: GridSizing::Adaptive {
                min_width: 120.0,
                max_width: None,
                height: 120.0,
            },
            sizing_signal: None,
            col_gap: 8.0,
            row_gap: 8.0,
            inset: EdgeInsets::ZERO,
            column_options: layout::columns::ColumnOptions::default(),
            strategy_kind: StrategyKind::Uniform,
            exact_item_height: None,
            strategy: None,
            selection: None,
            on_selection_changed: None,
            focused_index: Signal::new(None),
            marquee_selection: true,
            marquee: Signal::new(None),
            wrap_navigation: false,
            tab_traversal: GridTabTraversal::OutOfGrid,
            show_scrollbar: true,
            overscroll_behavior: OverscrollBehavior::default(),
            smooth_scrolling: true,
            smooth_scroll_duration: Duration::from_millis(150),
            scroll_bar_style: ScrollBarMode::Permanent,
            scroll_y: Signal::new_animated(0.0),
            max_scroll_y: Signal::new(0.0),
            viewport_ratio_y: Signal::new(1.0),
            reveal: handle::RevealShared::new(),
            column_count: Signal::new(1),
            reorderable: false,
            on_item_drop: None,
            insertion: Signal::new(None),
            model_id: ViewId::next(ViewKind::Grid),
            export: crate::data_views::RowExport::default(),
            on_tile_activate: None,
            activate_on: crate::data_views::ActivateOn::default(),
            tile_context_menu: None,
            type_ahead_timeout: std::time::Duration::from_millis(500),
            type_ahead: crate::common::type_ahead::TypeAheadState::new(),
            type_ahead_label: None,
            tile_a11y_label: None,
            empty_view: None,
            loading_view: None,
            is_loading: None,
            loading_id: None,
            section_data: None,
            header_delegate: None,
            header_height: 28.0,
            pinned_section_headers: false,
            current_section: Signal::new(0),
            pinned_header_id: None,
            a11y_label: None,
            tile_map: Rc::new(std::cell::RefCell::new(Vec::new())),
            style: None,
            viewport_width: Rc::new(Cell::new(400.0)),
            viewport_height: Rc::new(Cell::new(400.0)),
            scroller: Rc::new(RefCell::new(KineticScroller::new(OverscrollStyle::Clamp))),
            viewport_origin: Rc::new(Cell::new(None)),
            last_needs_scrollbar: Cell::new(false),
            body_pane_id: None,
            empty_id: None,
            scrollbar_id: None,
            overlay_id: None,
            enabled: Prop::Static(true),
            expanded: Signal::new(None),
            detail_row: None,
            detail_row_when: None,
            detail_row_height: None,
            detail: None,
            detail_layout: None,
            detail_anchor: Rc::new(RefCell::new(None)),
            band_id: None,
            detail_visible_span: Signal::new(None),
        }
    }

    /// Enable or disable the whole view. A disabled view greys out and stops
    /// accepting focus / selection / keyboard input (arena-gated).
    pub fn enabled(mut self, enabled: impl Into<Prop<bool>>) -> Self {
        self.enabled = enabled.into();
        self
    }

    // ── Tile sizing & layout ────────────────────────────────────────────

    /// Set the tile sizing / column-count policy.
    ///
    /// Accepts a plain [`GridSizing`] (static) **or** a `Signal<GridSizing>`
    /// (reactive). A bound signal is observed at [`BindingLevel::Rebuild`]: when
    /// it changes, `build()` rebuilds the cached layout strategy and reflows —
    /// the internal `scroll_y` / `focused_index` / selection are field signals on
    /// the same widget instance, so they survive the rebuild (no scroll jump).
    /// This is the card-size-slider path; mirrors
    /// [`TabWidget::sizing`](crate::TabWidget::sizing).
    pub fn sizing(mut self, sizing: impl Into<Prop<GridSizing>>) -> Self {
        let sig = sizing.into().as_signal();
        self.sizing = sig.get();
        self.sizing_signal = Some(sig);
        self
    }

    /// Sugar for [`GridSizing::Fixed`] — every tile is exactly `width` × `height`.
    pub fn tile_size(mut self, width: f32, height: f32) -> Self {
        self.sizing = GridSizing::Fixed { width, height };
        self.sizing_signal = None;
        self
    }

    /// Sugar for [`GridSizing::FixedColumnCount`] — exactly `count` columns.
    pub fn column_count(mut self, count: usize, tile_height: f32) -> Self {
        self.sizing = GridSizing::FixedColumnCount {
            count,
            height: tile_height,
        };
        self.sizing_signal = None;
        self
    }

    /// Switch to variable row heights: each row is sized to its tallest
    /// tile (SwiftUI `LazyVGrid` semantics). `estimated` seeds rows that
    /// haven't been measured yet; the scroll position is anchored when an
    /// estimate is later corrected. Combine with
    /// [`item_height`](Self::item_height) for exact heights.
    pub fn variable_row_heights(mut self, estimated: f32) -> Self {
        self.strategy_kind = StrategyKind::VariableRow {
            estimated: estimated.max(1.0),
        };
        self
    }

    /// Supply an exact per-**item** natural height. Width-independent, so it
    /// doesn't depend on the runtime column count: `VariableRowGrid` sizes
    /// each row to `max(item_height(i))` over its items. Implies variable row
    /// heights, gives an exact scrollbar, and removes anchoring jitter.
    pub fn item_height(mut self, f: impl Fn(usize) -> f32 + 'static) -> Self {
        self.exact_item_height = Some(Rc::new(f));
        if matches!(self.strategy_kind, StrategyKind::Uniform) {
            self.strategy_kind = StrategyKind::VariableRow {
                estimated: self.sizing.tile_height().max(1.0),
            };
        }
        self
    }

    /// Switch to a Pinterest-style waterfall: per-item variable heights flow
    /// into the currently-shortest column. Column count comes from the
    /// configured [`sizing`](Self::sizing); heights are auto-measured (or
    /// exact via [`item_height`](Self::item_height)). `estimated` seeds
    /// unmeasured items.
    pub fn waterfall(mut self, estimated: f32) -> Self {
        self.strategy_kind = StrategyKind::Waterfall {
            estimated: estimated.max(1.0),
        };
        self
    }

    // ── Spacing & insets ────────────────────────────────────────────────

    /// Horizontal gap between tiles (default 8).
    pub fn column_spacing(mut self, spacing: f32) -> Self {
        self.col_gap = spacing.max(0.0);
        self
    }

    /// Vertical gap between tile rows (default 8).
    pub fn row_spacing(mut self, spacing: f32) -> Self {
        self.row_gap = spacing.max(0.0);
        self
    }

    /// Set both column and row spacing.
    pub fn spacing(mut self, spacing: f32) -> Self {
        self.col_gap = spacing.max(0.0);
        self.row_gap = spacing.max(0.0);
        self
    }

    /// Inset from the scroll-content edge to the tiles.
    pub fn content_inset(mut self, inset: EdgeInsets) -> Self {
        self.inset = inset;
        self
    }

    // ── Column bounds & alignment ───────────────────────────────────────

    /// Never fewer than `count` columns (at least 1).
    ///
    /// Bounds the count a [`GridSizing::Fixed`] or [`GridSizing::Adaptive`]
    /// derives from the width; ignored by [`GridSizing::FixedColumnCount`],
    /// whose count is already the answer. When the width cannot afford
    /// `count` columns of the sizing's width, the tiles **narrow** to share
    /// the width — the grid never overflows horizontally. The tile height is
    /// kept as the sizing gives it (a card gets narrower, not shorter), so a
    /// tile that must hold its aspect ratio sizes its own content from the
    /// width it is handed. If `min_columns` exceeds
    /// [`max_columns`](Self::max_columns), the maximum wins.
    pub fn min_columns(mut self, count: usize) -> Self {
        self.column_options.min_columns = Some(count.max(1));
        self
    }

    /// Never more than `count` columns (at least 1), however wide the viewport.
    ///
    /// Bounds the count a [`GridSizing::Fixed`] or [`GridSizing::Adaptive`]
    /// derives from the width; ignored by [`GridSizing::FixedColumnCount`].
    /// Under `Fixed` the tiles keep their width and the leftover is placed by
    /// [`column_alignment`](Self::column_alignment); under `Adaptive` they
    /// stretch to share the width of the capped count, up to `max_width`.
    pub fn max_columns(mut self, count: usize) -> Self {
        self.column_options.max_columns = Some(count.max(1));
        self
    }

    /// Where the block of columns sits in the viewport when it is narrower
    /// than the content: [`HAlignment::Leading`] (the default, the tiles
    /// against the leading inset, leftover trailing), `Center` or
    /// `Trailing`. Leading and trailing swap in a right-to-left layout. Only
    /// the columns move: a section header and a [`detail_row`](Self::detail_row)
    /// band span the content width. The order of the columns within the
    /// block is the same in both directions.
    ///
    /// Only a layout that leaves width over has anything to place: a
    /// [`GridSizing::Fixed`] grid, an `Adaptive` one with `max_width`, or any
    /// grid capped by [`max_columns`](Self::max_columns).
    pub fn column_alignment(mut self, alignment: HAlignment) -> Self {
        self.column_options.alignment = alignment;
        self
    }

    // ── Selection ───────────────────────────────────────────────────────

    /// Set the index-based selection model (modes `None` / `Single` /
    /// `Multi`). It holds positions: for a selection that stays on its items
    /// through a sort or a filter, build the grid with
    /// [`from_source_keyed`](Self::from_source_keyed) instead.
    pub fn selection(mut self, sel: SelectionModel) -> Self {
        self.selection = Some(RowSelection::from_index(sel));
        self
    }

    /// Called whenever the selection set changes — including programmatic
    /// changes — with the new set of selected indices. For a keyed selection
    /// these are the positions its keys have at that moment.
    ///
    /// Because it also fires for programmatic changes, it carries no input
    /// modifiers and no [`EventContext`](teksilo_core::widget::EventContext);
    /// for the modifiers held at the moment of input, use
    /// [`on_tile_activate`](Self::on_tile_activate), which receives one.
    pub fn on_selection_changed(mut self, f: impl Fn(&BTreeSet<usize>) + 'static) -> Self {
        self.on_selection_changed = Some(Rc::new(f));
        self
    }

    /// Enable / disable rubber-band marquee selection (default enabled; only
    /// active when the selection model is in `Multi` mode).
    pub fn marquee_selection(mut self, enabled: bool) -> Self {
        self.marquee_selection = enabled;
        self
    }

    // ── Keyboard ────────────────────────────────────────────────────────

    /// Whether arrow navigation wraps across row/grid edges (default false).
    pub fn wrap_navigation(mut self, enabled: bool) -> Self {
        self.wrap_navigation = enabled;
        self
    }

    /// How Tab moves out of (or within) the grid (default `OutOfGrid`).
    pub fn tab_traversal(mut self, traversal: GridTabTraversal) -> Self {
        self.tab_traversal = traversal;
        self
    }

    // ── Scrolling ───────────────────────────────────────────────────────

    /// Suppress the internal scrollbar (mount your own via the signal
    /// accessors so it survives rebuilds).
    pub fn show_scrollbar(mut self, show: bool) -> Self {
        self.show_scrollbar = show;
        self
    }

    /// Scroll-chaining behavior at the boundary (default `Chain`).
    pub fn overscroll_behavior(mut self, behavior: OverscrollBehavior) -> Self {
        self.overscroll_behavior = behavior;
        self
    }

    /// Enable or disable animated wheel scrolling (enabled by default).
    pub fn smooth_scrolling(mut self, enabled: bool) -> Self {
        self.smooth_scrolling = enabled;
        self
    }

    /// Duration of the smooth scroll animation (default 150 ms).
    pub fn smooth_scroll_duration(mut self, duration: Duration) -> Self {
        self.smooth_scroll_duration = duration;
        self
    }

    /// How the scroll bar is displayed (default `Permanent`). `Overlay`
    /// and `Thin` float the bar over the content instead of reserving a
    /// layout column, mirroring `ScrollArea::scroll_bar_style`.
    pub fn scroll_bar_style(mut self, style: ScrollBarMode) -> Self {
        self.scroll_bar_style = style;
        self
    }

    /// The vertical scroll offset signal.
    pub fn scroll_y_signal(&self) -> &Signal<f32> {
        &self.scroll_y
    }

    /// The maximum scroll offset signal (`content_height - viewport_height`).
    pub fn max_scroll_y_signal(&self) -> &Signal<f32> {
        &self.max_scroll_y
    }

    /// The vertical viewport-to-content ratio signal (drives the thumb size).
    pub fn viewport_ratio_y_signal(&self) -> &Signal<f32> {
        &self.viewport_ratio_y
    }

    /// The part of the open detail band that is on screen, in band-local
    /// coordinates: `max(0, scroll_y − band.y) .. min(band.height, scroll_y +
    /// viewport_height − band.y)`, where `band.y` is the band's top in the
    /// grid's content. `None` while no band is open, and while the open band
    /// is entirely off screen.
    ///
    /// Written by each layout after the scroll offset is clamped, and only
    /// when it changes, so an observer is not told of a scroll that leaves
    /// the band's visible part as it was. Meant for a band holding far more
    /// than a viewport shows, hundreds of tracks say, that realizes only the
    /// rows in the span: a window of rows between two spacers, with no copy
    /// of the grid's placement arithmetic. See the module docs, "A long
    /// band".
    pub fn detail_visible_span_signal(&self) -> &Signal<Option<std::ops::Range<f32>>> {
        &self.detail_visible_span
    }

    /// A [`GridViewHandle`] on this grid: scroll it to a tile, or to a tile
    /// and its detail band, from outside the widget.
    ///
    /// Usable at once and for the grid's whole life: a request made before
    /// the grid is mounted is applied at its first layout, and the handle
    /// keeps working through every rebuild. A request is applied by the
    /// layout, after it has measured the detail band and settled the scroll
    /// anchoring, so one made in the same turn as opening a band lands where
    /// the new layout puts the tile. Prefer it to
    /// [`scroll_to_index`](Self::scroll_to_index) and
    /// [`ensure_index_visible`](Self::ensure_index_visible), which compute
    /// the offset when they are called.
    pub fn handle(&self) -> GridViewHandle {
        GridViewHandle::new(
            self.reveal.clone(),
            self.focused_index.clone(),
            self.source.len_fn.clone(),
        )
    }

    /// Bring `index` into view: nothing when the tile is already fully
    /// visible, otherwise a scroll per `anchor`, as
    /// [`scroll_to_index`](Self::scroll_to_index).
    ///
    /// Computed at call time from the last layout's geometry and clamped to
    /// its scroll range. Before the grid has been laid out there is no
    /// geometry and this does nothing, and a change of layout made in the
    /// same turn (a detail band opened above the tile) is not yet counted.
    /// [`GridViewHandle::ensure_index_visible`] has neither limit.
    pub fn ensure_index_visible(&self, index: usize, anchor: ScrollAnchor) {
        self.reveal_now(handle::RevealRequest::Ensure { index, anchor });
    }

    /// Scroll to `index`, forcing its position in the viewport per `anchor`;
    /// [`ScrollAnchor::Auto`] scrolls the least that shows it.
    ///
    /// Computed at call time, with the limits
    /// [`ensure_index_visible`](Self::ensure_index_visible) documents: it
    /// does nothing before the grid's first layout.
    /// [`GridViewHandle::scroll_to_index`] has neither limit.
    pub fn scroll_to_index(&self, index: usize, anchor: ScrollAnchor) {
        self.reveal_now(handle::RevealRequest::ScrollTo { index, anchor });
    }

    /// Apply `request` now, against the last layout.
    fn reveal_now(&self, request: handle::RevealRequest) {
        let Some(ref strategy) = self.strategy else {
            return;
        };
        if let Some(target) = scroll_for_request(
            strategy.as_ref(),
            self.detail_layout.as_deref(),
            request,
            self.source.len(),
            self.scroll_y.get(),
            self.viewport_height.get(),
            self.viewport_width.get(),
            self.max_scroll_y.get(),
        ) {
            self.scroll_y.set(target);
        }
    }

    /// In a single selection, put the keyboard cursor back on the selection
    /// whenever the selection moves without it.
    ///
    /// `ListView::follow_the_selection_in_single_mode` states the defect: a
    /// selection written from outside left the cursor, which the view
    /// publishes as its active descendant, on a tile no action used. The
    /// cursor is **moved** onto the selected tile rather than cleared, because
    /// a grid nominates `focused_index` alone as its active descendant and
    /// paints its focus ring there — cleared, the grid would announce and show
    /// no current tile at all. The model-change observer shifts the cursor
    /// before it shifts the selection, so a move made here is never shifted a
    /// second time. A grid with no cursor yet gets none from here.
    ///
    /// The selection is read live, never from the notification's value: an
    /// observer registered earlier may rewrite the selection while it is being
    /// notified, and the notification it interrupted still arrives afterwards,
    /// carrying the value that was just discarded.
    fn follow_the_selection_in_single_mode(&self, ctx: &mut BuildContext) {
        let Some(selection) = self.selection.clone() else {
            return;
        };
        if selection.mode() != teksilo_data::SelectionMode::Single {
            return;
        }
        let focused_index = self.focused_index.clone();
        let live = selection.clone();
        let handle = selection.observe_for_rebuild(move || {
            put_the_cursor_on_the_selection(&focused_index, &live);
        });
        ctx.own_handle(handle);
    }

    /// Scroll the tile the keyboard is on into view when this grid takes
    /// focus.
    ///
    /// Only the tiles near the viewport are realized, so on a grid taller than
    /// the window the current tile frequently has no widget. Everything that
    /// speaks for it then has nothing to speak about: no node carries
    /// `selected`, no tile id is in `tile_map` for `accessibility` to nominate
    /// as the `active_descendant`, and a screen reader taking focus here is
    /// told nothing at all. The first arrow press steps *past* that tile as
    /// well, because the cursor was somewhere the user was never shown.
    ///
    /// `ScrollAnchor::Auto` (`scroll_delta_to_reveal` returns 0 for a tile
    /// already fully visible, `grid_view/layout/strategy.rs:194-202`) rather
    /// than a forced anchor: a tile already on screen must not jump under
    /// somebody who can see it. `Center` would, and by a lot: a fully visible
    /// tile on the fifth row of a 300px viewport gets dragged 107px to reach
    /// the middle. It is also the anchor arrow navigation already scrolls with
    /// (`grid_view/keyboard.rs:348-355`), so taking focus and then stepping
    /// move the viewport by the same rule.
    ///
    /// The cursor is `focused_index` else the first selected tile, the same
    /// one the keyboard steps from (`grid_view/keyboard.rs:113-121`) and the
    /// same one the context-menu key targets, so focus reveals the tile the
    /// next keystroke will act on.
    ///
    /// Index to offset is asked of the layout strategy rather than computed
    /// here, because a grid wraps and the wrap point is not this widget's to
    /// know: `UniformGrid::tile_rect` (`grid_view/layout/uniform.rs:87-99`)
    /// puts item `i` on row `i / column_count(viewport_width)` at
    /// `inset.top + row * row_step()`, so the offset depends on the width the
    /// last layout settled on, and a waterfall strategy has no row formula at
    /// all, its items dropping into whichever column is shortest.
    /// `viewport_width` is the body width `place_children` published
    /// (`grid_view.rs:1789`) and asked the strategy for its column count
    /// (`:1791`), the scrollbar column already subtracted, so the reveal and
    /// the layout wrap at the same place.
    ///
    /// The handles are cloned into the effect rather than reaching through
    /// `self`, which the closure cannot borrow. `strategy` comes from the
    /// caller because `ensure_strategy` has just built it there and takes
    /// `&mut self`.
    fn reveal_focused_tile_on_focus(
        &self,
        ctx: &mut BuildContext,
        strategy: Rc<dyn GridLayoutStrategy>,
    ) {
        // Keyed on this grid's own id, not on the enclosing scope: a grid
        // nested inside another data view's rows would otherwise read that
        // view's focus, since `view_focus_active` prefers whatever scope is
        // open on the build stack (`build_context.rs:576-585`). Begin/end
        // around nothing leaves the stack as it was
        // (`widget_tree/focus_impl.rs:751-760`).
        let view_focused = ctx.begin_view_focus();
        ctx.end_view_focus();

        let scroll_y = self.scroll_y.clone();
        let max_scroll_y = self.max_scroll_y.clone();
        let viewport_height = self.viewport_height.clone();
        let viewport_width = self.viewport_width.clone();
        let focused_index = self.focused_index.clone();
        let selection = self.selection.clone();

        ctx.effect(&view_focused, move |focused| {
            if !*focused {
                return;
            }
            let Some(index) = focused_index.get().or_else(|| {
                selection
                    .as_ref()
                    .and_then(|s| s.selected_indices().first().copied())
            }) else {
                return;
            };
            if let Some(target) = scroll_for_ensure_visible(
                strategy.as_ref(),
                index,
                scroll_y.get(),
                viewport_height.get(),
                viewport_width.get(),
                max_scroll_y.get(),
                ScrollAnchor::Auto,
            ) {
                scroll_y.set(target);
            }
        });
    }

    /// Keep an anchor on the disclosed tile, so a reset that moves it can
    /// find it again (`follow_the_disclosed_tile`). Re-anchored on every
    /// write, wherever it comes from; the anchor is built at the write,
    /// against the data the index refers to.
    fn track_the_disclosed_tile(&self, ctx: &mut BuildContext, detail: &detail::DetailState) {
        let anchor_of = self.source.anchor_fn.clone();
        let slot = self.detail_anchor.clone();
        *slot.borrow_mut() = detail.expanded.get().map(|i| anchor_of(i));
        ctx.effect(&detail.expanded, move |expanded| {
            *slot.borrow_mut() = expanded.map(|i| anchor_of(i));
        });
    }

    // ── Accessibility / empty state ─────────────────────────────────────

    // ── Sections ────────────────────────────────────────────────────────

    /// Group the flat model into sections, rendering a header above each
    /// section's tile band. Sections compose with the uniform tile layout.
    pub fn sections<P: SectionProvider>(mut self, provider: P) -> Self {
        let provider = Rc::new(provider);
        let counts_provider = provider.clone();
        let title_provider = provider.clone();
        self.section_data = Some(SectionData {
            counts_fn: Rc::new(move || counts_provider.section_counts()),
            title_fn: Rc::new(move |s| title_provider.section_title(s)),
        });
        self
    }

    /// Custom section-header widget builder `(section_index, title)`. Without
    /// it a default bold-text header is used.
    pub fn section_header_delegate(
        mut self,
        f: impl Fn(usize, &str) -> Box<dyn Widget> + 'static,
    ) -> Self {
        self.header_delegate = Some(Rc::new(f));
        self
    }

    /// Height of each section header row (default 28).
    pub fn section_header_height(mut self, height: f32) -> Self {
        self.header_height = height.max(0.0);
        self
    }

    /// Keep the current section's header pinned to the top while scrolling
    /// through it (SwiftUI `pinnedViews:[.sectionHeaders]`).
    pub fn pinned_section_headers(mut self, enabled: bool) -> Self {
        self.pinned_section_headers = enabled;
        self
    }

    /// Accessible label for the grid container.
    pub fn a11y_label(mut self, label: impl Into<String>) -> Self {
        self.a11y_label = Some(label.into());
        self
    }

    /// Per-call Tier-3 decoration style override (focus ring, marquee,
    /// insertion bar, pinned-header surface). Precedence: this override →
    /// `theme.style_slots.grid_view` → the stock `RecipeGridViewStyle`.
    pub fn style(mut self, style: impl GridViewStyle) -> Self {
        self.style = Some(Rc::new(style));
        self
    }

    /// Build the header-widget factory (section → widget) shared by the body
    /// pane and the pinned slot, falling back to a default bold-text header.
    #[allow(clippy::type_complexity)]
    fn header_factory(&self) -> Option<Rc<dyn Fn(usize) -> Box<dyn Widget>>> {
        let data = self.section_data.as_ref()?;
        let title_fn = data.title_fn.clone();
        let delegate = self.header_delegate.clone();
        Some(Rc::new(move |section| {
            let title = title_fn(section);
            match &delegate {
                Some(d) => d(section, &title),
                None => Box::new(TextWidget::new(teksilo_i18n::lit!(title))) as Box<dyn Widget>,
            }
        }))
    }

    /// Widget shown when the model is empty.
    pub fn empty_view(mut self, f: impl Fn() -> Box<dyn Widget> + 'static) -> Self {
        self.empty_view = Some(Rc::new(f));
        self
    }

    /// Widget overlaid while `is_loading` reads `true`.
    pub fn loading_view(mut self, f: impl Fn() -> Box<dyn Widget> + 'static) -> Self {
        self.loading_view = Some(Rc::new(f));
        self
    }

    /// Reactive loading flag; when `true` the [`loading_view`](Self::loading_view)
    /// is shown above the grid.
    pub fn is_loading(mut self, flag: impl Into<Prop<bool>>) -> Self {
        self.is_loading = Some(flag.into());
        self
    }

    // ── Drag-to-reorder ─────────────────────────────────────────────────

    /// Enable intra-grid drag reordering (and keyboard Alt+Arrow). The move is
    /// routed through the source's `accept_drop` (a built-in `ListModel`
    /// reorders via `move_item`; an external source applies its own command).
    pub fn reorderable(mut self, enabled: bool) -> Self {
        self.reorderable = enabled;
        self
    }

    /// Make tiles **droppable outside this view** — on a
    /// [`DropTarget`](crate::DropTarget), another data view, or the OS.
    ///
    /// A dragged tile (or the whole selection, when the pressed tile is part of
    /// a multi-selection) carries clones of its items in a public
    /// [`RowDragData<T>`](crate::RowDragData), so a foreign receiver can pull
    /// them out with `payload.get_typed::<RowDragData<T>>()` /
    /// `DropTarget::on_drop_typed::<RowDragData<T>>()` — no serialization. This
    /// also makes tiles a drag source even without [`reorderable`](Self::reorderable).
    ///
    /// `mode` chooses what happens to the origin rows once a *foreign* target
    /// accepts them: [`DragTransferMode::Move`] removes them (via the source's
    /// `on_drag_out`, or [`on_rows_transferred_out`](Self::on_rows_transferred_out)),
    /// [`DragTransferMode::Copy`] leaves them. A same-view reorder is never a
    /// transfer, so `mode` never affects it. Requires `T: Clone`.
    pub fn exportable(mut self, mode: DragTransferMode) -> Self
    where
        T: Clone,
    {
        self.export.set_exportable(mode);
        self
    }

    /// Additionally advertise the dragged tiles as MIME data so they can be
    /// dropped on a [`DropZone`](crate::DropZone) or exported to another
    /// application / window via the OS. `f` maps the dragged items to
    /// `(mime_type, bytes)` pairs (e.g. `text/plain`, `text/uri-list`, an
    /// app-specific `application/x-…`). Implies [`exportable`](Self::exportable)
    /// (defaulting to [`DragTransferMode::Move`] if not already set). Requires
    /// `T: Clone`.
    pub fn export_external(mut self, f: impl Fn(&[T]) -> Vec<(String, Vec<u8>)> + 'static) -> Self
    where
        T: Clone,
    {
        self.export.set_export_external(f);
        self
    }

    /// Override how rows moved out to a foreign target are removed from this
    /// view. Receives the dragged rows' indices (descending-safe) and the live
    /// context. Without this, an [`exportable`](Self::exportable)
    /// [`Move`](DragTransferMode::Move) drag removes them through the source's
    /// `on_drag_out` (works out of the box for a `ListModel`).
    pub fn on_rows_transferred_out(
        mut self,
        f: impl Fn(&[usize], &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.export.set_on_rows_transferred_out(f);
        self
    }

    /// Accept exported rows dropped from a **different** view or source without
    /// writing a custom `ListDataSource`. Pair with
    /// [`on_rows_received`](Self::on_rows_received), which is handed the dropped
    /// items and the insertion index. (Same-view reorder is
    /// [`reorderable`](Self::reorderable); a custom `ListDataSource` can still
    /// accept foreign drops through its `can_accept`/`accept_drop` instead.)
    pub fn accept_foreign_rows(mut self, accept: bool) -> Self {
        self.export.accept_foreign_rows = accept;
        self
    }

    /// Handler for rows accepted via [`accept_foreign_rows`](Self::accept_foreign_rows):
    /// `(items, insertion_index, ctx)`. Insert them into your model at the
    /// index.
    pub fn on_rows_received(
        mut self,
        f: impl Fn(Vec<T>, usize, &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.export.set_on_rows_received(f);
        self
    }

    /// Accept external drops at a flat insertion index. Returns `true` when
    /// the drop is accepted.
    pub fn on_item_drop(
        mut self,
        f: impl Fn(
            teksilo_core::drag_payload::DragPayload,
            usize,
            &mut teksilo_core::widget::EventContext,
        ) -> bool
        + 'static,
    ) -> Self {
        self.on_item_drop = Some(Rc::new(f));
        self
    }

    // ── Activation / context menu / type-ahead / loading ────────────────

    /// Called when a tile is activated (a click per [`activate_on`](Self::activate_on),
    /// or Enter on the focused tile) — the "open / default action", distinct
    /// from selection.
    pub fn on_tile_activate(
        mut self,
        f: impl Fn(usize, &mut teksilo_core::widget::EventContext) + 'static,
    ) -> Self {
        self.on_tile_activate = Some(Rc::new(f));
        self
    }

    /// Choose single- vs double-click tile activation (default
    /// [`ActivateOn::DoubleClick`](crate::ActivateOn)). Enter activates in either
    /// mode.
    pub fn activate_on(mut self, mode: crate::data_views::ActivateOn) -> Self {
        self.activate_on = mode;
        self
    }

    /// Per-tile context-menu factory: `(index, pointer_position, ctx)` →
    /// optional menu widget.
    pub fn tile_context_menu(
        mut self,
        f: impl Fn(usize, Point, &mut teksilo_core::widget::EventContext) -> Option<Box<dyn Widget>>
        + 'static,
    ) -> Self {
        self.tile_context_menu = Some(Rc::new(f));
        self
    }

    /// Supply a per-item label for type-ahead navigation (typing letters
    /// jumps to the first matching item). Required to enable type-ahead.
    pub fn type_ahead_label(mut self, f: impl Fn(usize) -> String + 'static) -> Self {
        self.type_ahead_label = Some(Rc::new(f));
        self
    }

    /// Supply a per-item accessible name applied to each tile's `GridCell`
    /// (`Node::label`), so a screen reader announces a concise item name in
    /// addition to the row/column position. Without it, the cell's name is left
    /// to its contents.
    pub fn tile_a11y_label(mut self, f: impl Fn(usize) -> String + 'static) -> Self {
        self.tile_a11y_label = Some(Rc::new(f));
        self
    }

    /// Type-ahead reset timeout (default 500 ms; `ZERO` disables).
    pub fn type_ahead_timeout(mut self, timeout: std::time::Duration) -> Self {
        self.type_ahead_timeout = timeout;
        self
    }

    // ── Detail band ─────────────────────────────────────────────────────

    /// The disclosed tile: `Some(index)` opens a full-width band under the
    /// row holding tile `index` (see [`detail_row`](Self::detail_row)),
    /// `None` closes it. The grid writes it when a tile is activated (not for
    /// a tile with nothing to disclose), and follows writes made from
    /// outside. Without this the grid keeps its own signal.
    pub fn expanded_index(mut self, expanded: Signal<Option<usize>>) -> Self {
        self.expanded = expanded;
        self
    }

    /// The content of the detail band: the "album expansion" of a music
    /// library, a full-width band opened directly under the row that holds
    /// the activated tile.
    ///
    /// `f` receives the disclosed tile's [`TileContext`], the same one the
    /// tile delegate gets, and returns the band's content, or `None` when the
    /// tile has nothing to disclose. It is also asked when a tile is
    /// activated, to learn whether it has anything, and its answer dropped,
    /// so it should be cheap and have no side effects. The band pushes the
    /// following rows down, and stays under its tile when a resize changes
    /// the column count.
    ///
    /// With a band, activating a tile (a click per
    /// [`activate_on`](Self::activate_on), or Enter) opens it and scrolls it
    /// into view, and activating the open tile closes it;
    /// [`on_tile_activate`](Self::on_tile_activate) still fires. A tile with
    /// nothing to disclose opens nothing. In a single selection, Enter also
    /// selects the tile whose band it opens, unless the application has an
    /// activation of its own; a multiple selection is left as it is. Space on
    /// the open tile closes it. ↓ from the open tile
    /// moves focus to the first focusable control in the band, scrolling it
    /// into view, and ↑ from there, when the control does not use it, returns
    /// to the tile. A band that closes with focus inside it hands focus back
    /// to the grid, on its tile. Arrows between tiles step over the band, and
    /// the rubber band selects no band.
    ///
    /// The band follows its tile when the tile moves. A source with item keys
    /// is followed through a sort or a filter (a reset); a source without
    /// them is followed through inserts, removals and moves, and closes the
    /// band on a reset. A [`ListModel`]'s keys are its positions, which
    /// identify no item across a reset, so it counts as a source without
    /// keys here, through [`from_source`](Self::from_source) as through
    /// [`new`](Self::new). The band closes when its tile is removed.
    ///
    /// The band is measured height-for-width at the content width, or sized
    /// by [`detail_row_height`](Self::detail_row_height). It works with the
    /// uniform grid, [`variable_row_heights`](Self::variable_row_heights) and
    /// [`sections`](Self::sections). A [`waterfall`](Self::waterfall) has no
    /// rows to put it under and ignores it. A band that opens, closes or
    /// moves above the viewport leaves the visible tiles where they are. Its
    /// content is rebuilt when the band moves to another tile, when its own
    /// tile's item arrives from a lazy source, and when the grid's rows
    /// change (an insert, a removal, a move, an update, a reset); a lazy
    /// source loading other windows leaves it as it is.
    ///
    /// Accessibility: the band is a `Role::Group`, read after its tile's
    /// row, named after its tile's [`tile_a11y_label`](Self::tile_a11y_label),
    /// or labelled by the tile, or, with the tile outside the realized
    /// window, "Details of item N" in the user's language. A tile carries an
    /// `expanded` state, `Expand` / `Collapse` actions and, while open, a
    /// `controls` relation to the band. Without
    /// [`detail_row_when`](Self::detail_row_when) every tile does, one with
    /// nothing to disclose included, since knowing otherwise means building
    /// its band, and that one stays collapsed. The grid's row and column
    /// counts and the tiles' positions do not count the band.
    pub fn detail_row(
        mut self,
        f: impl Fn(&TileContext<'_, T>) -> Option<Box<dyn Widget>> + 'static,
    ) -> Self {
        self.detail_row = Some(Rc::new(f));
        self
    }

    /// Which tiles have a detail band, answered without building one: `f`
    /// receives the tile's [`TileContext`], as
    /// [`detail_row`](Self::detail_row) does, and returns `false` for a tile
    /// with nothing to disclose.
    ///
    /// Such a tile is not a disclosure. Assistive technology hears no
    /// expanded state on it and is offered no `Expand` or `Collapse`, which it
    /// would be otherwise. Activating it opens nothing, `detail_row` is not
    /// asked for it, and [`expanded_index`](Self::expanded_index) naming it
    /// opens no band.
    ///
    /// `f` is asked as each tile is built: when it comes into the realized
    /// window, after a change to the data, and when its selectedness flips.
    /// Answer from the item, cheaply and with no side effects, and agree with
    /// `detail_row`: a tile `f` accepts and `detail_row` gives nothing for is
    /// offered as expandable, and opens nothing. A tile of a lazy source
    /// whose item has not arrived is offered until it does. Without
    /// `detail_row`, this does nothing.
    pub fn detail_row_when(mut self, f: impl Fn(&TileContext<'_, T>) -> bool + 'static) -> Self {
        self.detail_row_when = Some(Rc::new(f));
        self
    }

    /// The detail band's height for the tile at `index`, instead of measuring
    /// it. See [`detail_row`](Self::detail_row).
    pub fn detail_row_height(mut self, f: impl Fn(usize) -> f32 + 'static) -> Self {
        self.detail_row_height = Some(Rc::new(f));
        self
    }

    // ── Internals ───────────────────────────────────────────────────────

    /// The detail band's shared state, when a band is in force: a
    /// `detail_row` was given and the layout has rows. Built once.
    fn ensure_detail(&mut self) -> Option<Rc<detail::DetailState>> {
        self.detail_row.as_ref()?;
        let has_rows = self.section_data.is_some()
            || !matches!(self.strategy_kind, StrategyKind::Waterfall { .. });
        if !has_rows {
            return None;
        }
        Some(
            self.detail
                .get_or_insert_with(|| {
                    Rc::new(detail::DetailState::new(
                        self.expanded.clone(),
                        self.detail_row_height.clone(),
                    ))
                })
                .clone(),
        )
    }

    /// Build (once) and return the layout strategy. Cached so variable
    /// strategies keep their measurement caches across rebuilds.
    fn ensure_strategy(&mut self) -> Rc<dyn GridLayoutStrategy> {
        if let Some(s) = &self.strategy {
            return s.clone();
        }
        // Sections override the strategy kind (uniform tiles + headers).
        let sizing = self.sizing;
        let options = self.column_options;
        let inner: Rc<dyn GridLayoutStrategy> = if let Some(ref data) = self.section_data {
            Rc::new(
                SectionedGrid::new(
                    self.sizing,
                    self.col_gap,
                    self.row_gap,
                    self.inset,
                    self.header_height,
                    data.counts_fn.clone(),
                )
                .with_columns(sizing, options),
            )
        } else {
            match self.strategy_kind {
                StrategyKind::Uniform => Rc::new(
                    UniformGrid::new(self.sizing, self.col_gap, self.row_gap, self.inset)
                        .with_columns(sizing, options),
                ),
                StrategyKind::VariableRow { estimated } => Rc::new(
                    VariableRowGrid::new(
                        self.sizing,
                        self.col_gap,
                        self.row_gap,
                        self.inset,
                        estimated,
                        self.exact_item_height.clone(),
                    )
                    .with_columns(sizing, options),
                ),
                StrategyKind::Waterfall { estimated } => Rc::new(
                    VirtualizedMasonry::new(
                        self.sizing,
                        self.col_gap,
                        self.row_gap,
                        self.inset,
                        estimated,
                        self.exact_item_height.clone(),
                    )
                    .with_columns(sizing, options),
                ),
            }
        };
        let s: Rc<dyn GridLayoutStrategy> = match self.ensure_detail() {
            Some(state) => {
                let wrapped = Rc::new(detail::DetailRowStrategy::new(
                    inner,
                    state,
                    self.source.len_fn.clone(),
                    self.row_gap,
                    self.inset,
                ));
                self.detail_layout = Some(wrapped.clone());
                wrapped
            }
            None => inner,
        };
        self.strategy = Some(s.clone());
        s
    }
}

impl<T: 'static> std::fmt::Debug for GridView<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("GridView")
            .field("items", &self.source.len())
            .field("scroll_bar_style", &self.scroll_bar_style)
            .field("scroll_y", &self.scroll_y.get())
            .finish()
    }
}

/// The grid's erasure of `source`.
///
/// A [`ListModel`] goes through the erasure [`GridView::new`] uses. Its keys
/// are its positions (`ListModel::key_at(i)` is `i`), and a reset keeps a
/// position for whatever item lands there, so they identify no tile: erased
/// as a keyed source, they reported an anchor that tracks its tile, and a
/// `replace_all` left the detail band open over another item. Every other
/// source's keys are taken as identities.
fn erase_source<T: 'static, S: teksilo_data::ListDataSource<Item = T>>(
    source: Rc<S>,
) -> ListSource<T> {
    match (source.as_ref() as &dyn std::any::Any).downcast_ref::<ListModel<T>>() {
        Some(model) => ListSource::from_model(model.clone()),
        None => ListSource::from_data_source_rc(source),
    }
}

/// In a single selection, move a cursor that is off the selection onto the
/// selected tile. A grid with no cursor, or a selection on no tile this grid
/// shows, leaves the cursor where it is. See
/// `GridView::follow_the_selection_in_single_mode`.
fn put_the_cursor_on_the_selection(
    focused_index: &Signal<Option<usize>>,
    selection: &RowSelection,
) {
    if selection.mode() != SelectionMode::Single {
        return;
    }
    if let Some(cursor) = focused_index.get()
        && !selection.is_selected(cursor)
        && let Some(&tile) = selection.selected_indices().first()
    {
        focused_index.set(Some(tile));
    }
}

/// Keep the detail band on its tile after a change to the data, or close it.
///
/// A change that says where rows went (an insert, a removal, a move) is
/// followed by position, for any source: it is exact, and it closes the band
/// when its tile is the one removed. A reset says nothing about where
/// anything went; the tile is found again by its key when the source has
/// keys (a sort or a filter of a `SortFilterListModel`), and the band closes
/// when it has none (a `ListModel`'s positions count as none, see
/// `erase_source`), or when the tile is gone.
fn follow_the_disclosed_tile(
    detail: &detail::DetailState,
    anchor: Option<&crate::data_views::RowAnchor>,
    change: &DataChange,
    len: usize,
) {
    let Some(open) = detail.expanded.get() else {
        return;
    };
    let next = match change {
        DataChange::Reset => anchor
            .filter(|a| a.tracks_identity())
            .and_then(|a| a.index()),
        _ => teksilo_data::data_change::adjust_single_index_for_change(open, change),
    }
    .filter(|&i| i < len);
    if next != Some(open) {
        detail.expanded.set(next);
    }
}

/// Hands `f` the [`TileContext`] of a tile, as the band's builder and
/// [`GridView::detail_row_when`] receive it, and returns whether the tile's
/// item was resident; `f` is not called when it was not.
type TileContextReader<T> = Rc<dyn Fn(usize, &mut dyn FnMut(&TileContext<'_, T>)) -> bool>;

/// The [`TileContextReader`] the detail band asks through.
///
/// Reads the tile's row and column from the wrapped strategy rather than the
/// band's wrapper, which holds the state this is kept in.
fn tile_context_reader<T: 'static>(
    read_item_fn: body_pane::ReadItemFn<T>,
    strategy: Rc<dyn GridLayoutStrategy>,
    viewport_width: Rc<Cell<f32>>,
    selection: Option<RowSelection>,
    focused_index: Signal<Option<usize>>,
) -> TileContextReader<T> {
    Rc::new(move |index, f| {
        let (row, col) = strategy.tile_row_col(index, viewport_width.get());
        let is_selected = selection.as_ref().is_some_and(|s| s.is_selected(index));
        let is_focused = focused_index.get() == Some(index);
        (read_item_fn)(index, &mut |item| {
            f(&TileContext {
                index,
                row,
                col,
                item,
                is_selected,
                is_focused,
            })
        })
    })
}

/// Whether a tile has a band, as the tiles ask it: the application's
/// [`GridView::detail_row_when`] over the tile's [`TileContext`], or `None`
/// for a tile of a lazy source whose item has not arrived.
fn band_when<T: 'static>(
    when: detail::DetailWhen<T>,
    read_tile: TileContextReader<T>,
) -> detail::BandWhenFn {
    Rc::new(move |index| {
        let mut answer = false;
        read_tile(index, &mut |tc| answer = when(tc)).then_some(answer)
    })
}

/// The detail band's content for a tile, as the band and activation ask for
/// it: the application's builder over the tile's item and its
/// [`TileContext`], or a placeholder for a tile of a lazy source whose item
/// has not arrived.
fn band_content<T: 'static>(
    builder: detail::DetailBuilder<T>,
    read_tile: TileContextReader<T>,
    row_state_fn: Rc<dyn Fn(usize) -> teksilo_data::RowState>,
) -> detail::BandContentFn {
    Rc::new(move |index| {
        let mut content = None;
        let resident = read_tile(index, &mut |tc| content = builder(tc));
        if resident {
            (content, true)
        } else {
            // Hold the band's place, as a tile does, rather than collapse it.
            let placeholder = ((row_state_fn)(index) == teksilo_data::RowState::Loading)
                .then(crate::data_views::default_placeholder);
            (placeholder, false)
        }
    })
}

/// Scroll `target`, in window coordinates, into a viewport whose top edge is
/// at `viewport_top`, the way `ScrollArea` answers
/// `WidgetEvent::ScrollIntoView`: the least scroll that shows it, or the pin
/// `align` asks for, gliding over `glide` when given. Returns how far the
/// content scrolled.
#[allow(clippy::too_many_arguments)]
fn reveal_in_viewport(
    target: Rect,
    margin: f32,
    align: teksilo_core::event::ScrollAlign,
    glide: Option<Duration>,
    scroll_y: &Signal<f32>,
    max_scroll_y: &Signal<f32>,
    viewport_top: f32,
    viewport_height: f32,
) -> f32 {
    let current = scroll_y.get();
    // In content coordinates: an edge at the viewport's top is at `current`.
    let top = target.y - viewport_top + current;
    let new_y = match align {
        // A pin names an exact place, so the margin does not pad it.
        teksilo_core::event::ScrollAlign::Fraction(f) => {
            top - (viewport_height - target.height) * f
        }
        teksilo_core::event::ScrollAlign::Minimal => {
            let (top, bottom) = (top - margin, top + target.height + margin);
            if top <= current && bottom >= current + viewport_height {
                // As visible as it can be: larger than the viewport.
                current
            } else if top < current {
                top
            } else if bottom > current + viewport_height {
                bottom - viewport_height
            } else {
                current
            }
        }
    }
    .clamp(0.0, max_scroll_y.get());
    if (new_y - current).abs() <= 0.001 {
        return 0.0;
    }
    match glide {
        Some(duration) => scroll_y.animate_to(new_y, duration, teksilo_tokens::Easing::EaseOut),
        None => scroll_y.set(new_y),
    }
    new_y - current
}

/// The scroll offset that brings tile `index` into view per `anchor`, or
/// `None` when the offset already satisfies it.
///
/// Split out of [`GridView::ensure_index_visible`] so the reveal-on-focus
/// effect runs the same arithmetic as the public scroll-into-view API rather
/// than a second copy of it: the effect outlives any borrow of `self` and
/// holds cloned handles instead of the widget, so it cannot call the method.
/// Takes the geometry by value for the same reason. The keyboard has its own
/// call into `scroll_delta_to_reveal` (`grid_view/keyboard.rs:496-502`, in
/// `reveal_tile`), because it applies the delta to an enclosing scroll area as
/// well.
fn scroll_for_ensure_visible(
    strategy: &dyn GridLayoutStrategy,
    index: usize,
    scroll_y: f32,
    viewport_height: f32,
    viewport_width: f32,
    max_scroll_y: f32,
    anchor: ScrollAnchor,
) -> Option<f32> {
    let delta =
        strategy.scroll_delta_to_reveal(index, scroll_y, viewport_height, viewport_width, anchor);
    if delta.abs() <= 0.01 {
        return None;
    }
    Some((scroll_y + delta).clamp(0.0, max_scroll_y))
}

/// The scroll offset a [`handle::RevealRequest`] asks for, or `None` when the
/// offset already satisfies it or the grid has no such tile.
///
/// The one arithmetic behind [`GridView::scroll_to_index`] and
/// [`GridView::ensure_index_visible`], applied at call time, and behind a
/// [`GridViewHandle`]'s requests, applied by `place_children`. A band
/// request reveals the span from the top of the tile's row to the bottom of
/// its band, the row first when the two do not fit, as the grid does for a
/// band a user opens; with that tile's band not open it reveals the tile.
#[allow(clippy::too_many_arguments)]
fn scroll_for_request(
    strategy: &dyn GridLayoutStrategy,
    detail_layout: Option<&detail::DetailRowStrategy>,
    request: handle::RevealRequest,
    len: usize,
    scroll_y: f32,
    viewport_height: f32,
    viewport_width: f32,
    max_scroll_y: f32,
) -> Option<f32> {
    let index = request.index();
    if index >= len {
        return None;
    }
    let reveal = |anchor| {
        scroll_for_ensure_visible(
            strategy,
            index,
            scroll_y,
            viewport_height,
            viewport_width,
            max_scroll_y,
            anchor,
        )
    };
    match request {
        handle::RevealRequest::ScrollTo { anchor, .. } => reveal(anchor),
        handle::RevealRequest::Ensure { anchor, .. } => {
            // Fully visible is what `Auto` leaves alone.
            reveal(ScrollAnchor::Auto)?;
            reveal(anchor)
        }
        handle::RevealRequest::Band(_) => {
            let Some((top, bottom)) =
                detail_layout.and_then(|layout| layout.reveal_span(index, viewport_width))
            else {
                return reveal(ScrollAnchor::Auto);
            };
            let y = reveal_span_offset(top, bottom, scroll_y, viewport_height, max_scroll_y);
            ((y - scroll_y).abs() > 0.001).then_some(y)
        }
    }
}

/// The least scroll from `scroll_y` that shows the content span
/// `top..bottom`, its top first when it is taller than the viewport, clamped
/// to `0..=max_scroll_y`.
fn reveal_span_offset(
    top: f32,
    bottom: f32,
    scroll_y: f32,
    viewport_height: f32,
    max_scroll_y: f32,
) -> f32 {
    let mut y = scroll_y;
    if bottom > y + viewport_height {
        y = bottom - viewport_height;
    }
    if top < y {
        y = top;
    }
    y.clamp(0.0, max_scroll_y)
}

/// The part of a band at content rect `band` on screen at `scroll_y`, in
/// band-local coordinates; `None` when none of it is.
fn band_visible_span(
    band: TileRect,
    scroll_y: f32,
    viewport_height: f32,
) -> Option<std::ops::Range<f32>> {
    let start = (scroll_y - band.y).max(0.0);
    let end = (scroll_y + viewport_height - band.y).min(band.height);
    (end > start).then_some(start..end)
}

impl<T: 'static> Widget for GridView<T> {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        let self_id = ctx.self_id();
        ctx.enabled_when(self_id, self.enabled.clone());

        // Reactive tile sizing (the card-size slider): observe the bound signal
        // at Rebuild, and when its value changes, drop the cached strategy so
        // `ensure_strategy` rebuilds it with the new sizing and the grid reflows.
        // Done before `ensure_strategy` so this build already uses the new value.
        if let Some(ref sig) = self.sizing_signal {
            sig.bind_to(self_id, ctx.binding_registry(), BindingLevel::Rebuild);
            let next = sig.get();
            if self.sizing != next {
                self.sizing = next;
                self.strategy = None;
            }
        }

        let strategy = self.ensure_strategy();

        // Rebuild trigger (data changes, empty/non-empty transition).
        let version = ctx.signal(0_u64);
        version.bind_to(ctx.self_id(), ctx.binding_registry(), BindingLevel::Rebuild);

        // scroll_y at Relayout so place_children re-writes max_scroll/ratio.
        self.scroll_y.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::Relayout,
        );
        ctx.register_animated_signal(&self.scroll_y);
        // A handle's request relays the grid out; `place_children` applies it.
        self.reveal.relayout_signal().bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::Relayout,
        );

        // Re-walk container a11y when selection / focus changes, and repaint
        // the overlay's container ring. Never a rebuild: each tile watches
        // its own selectedness (`TileA11y`). A counter rather than the model's
        // own signal, because the facade hides which of the two models it is.
        let selection_changed = ctx.signal(0_u64);
        if let Some(ref sel) = self.selection {
            selection_changed.bind_to(
                ctx.self_id(),
                ctx.binding_registry(),
                BindingLevel::AccessibilityOnly,
            );
            let changed = selection_changed.clone();
            let handle = sel.observe_for_rebuild(move || changed.set(changed.get() + 1));
            ctx.own_handle(handle);
        }
        self.focused_index.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::AccessibilityOnly,
        );

        self.follow_the_selection_in_single_mode(ctx);
        // Taking focus scrolls the current tile into the realized window,
        // which is what gives `accessibility` a tile id to nominate.
        self.reveal_focused_tile_on_focus(ctx, strategy.clone());

        // The detail band, when one is in force. Opening and closing it moves
        // the rows after it, which is a relayout here and nothing more: the
        // band rebuilds its own content, and no tile is rebuilt.
        let detail = self.detail_layout.as_ref().and(self.detail.clone());
        if let Some(ref d) = detail {
            d.expanded.bind_to(
                ctx.self_id(),
                ctx.binding_registry(),
                BindingLevel::Relayout,
            );
            // The band rebuilt alone, around content that arrived: its height
            // is measured here.
            d.version.bind_to(
                ctx.self_id(),
                ctx.binding_registry(),
                BindingLevel::Relayout,
            );
            self.track_the_disclosed_tile(ctx, d);
            if let (Some(layout), Some(builder)) = (&self.detail_layout, &self.detail_row) {
                let read_tile = tile_context_reader(
                    self.source.read_item_fn.clone(),
                    layout.inner(),
                    self.viewport_width.clone(),
                    self.selection.clone(),
                    self.focused_index.clone(),
                );
                if let Some(when) = &self.detail_row_when {
                    d.set_when(band_when(when.clone(), read_tile.clone()));
                }
                d.set_content(band_content(
                    builder.clone(),
                    read_tile,
                    self.source.dnd.row_state_fn.clone(),
                ));
            }
        }
        // The body pane's rebuild trigger, made here so the model observer
        // below can rebuild the pane alone when a window loads.
        let pane_version = Signal::new(0_u64);

        // Observe model changes.
        {
            let v = version.clone();
            let counter = Rc::new(Cell::new(0_u64));
            let strategy_obs = strategy.clone();
            let selection_obs = self.selection.clone();
            let len_fn = self.source.len_fn.clone();
            let scroll_reset = self.scroll_y.clone();
            let focused_obs = self.focused_index.clone();
            let detail_obs = detail.clone();
            let anchor_obs = self.detail_anchor.clone();
            let pane_v = pane_version.clone();
            let handle = (self.source.observe_fn)(Box::new(move |change| {
                // Keep the keyboard-focus anchor in step too — otherwise it
                // silently points at the wrong tile after an insert / remove
                // / move (reachable not just from local edits but from a
                // live watcher pushing in a peer process's write), and the
                // next Enter/Space acts on the wrong item. Mirrors
                // `ListView`'s `focused_index` adjustment.
                //
                // Before the selection is adjusted, not after: in a single
                // selection the selection's own observer puts the cursor on
                // the selected tile (`follow_the_selection_in_single_mode`),
                // and a cursor shifted after that would move twice.
                let had_cursor = focused_obs.get().is_some();
                if let Some(current) = focused_obs.get() {
                    focused_obs.set(teksilo_data::data_change::adjust_single_index_for_change(
                        current, change,
                    ));
                }
                match change {
                    DataChange::ItemsInserted { range } => {
                        strategy_obs.invalidate_rows(range.start..usize::MAX);
                        strategy_obs.resize((len_fn)());
                    }
                    DataChange::ItemsRemoved { range } => {
                        strategy_obs.invalidate_rows(range.start..usize::MAX);
                        strategy_obs.resize((len_fn)());
                    }
                    DataChange::ItemsMoved { .. } => {
                        strategy_obs.invalidate_rows(0..usize::MAX);
                    }
                    DataChange::ItemUpdated { index } => {
                        strategy_obs.invalidate_rows(*index..index + 1);
                    }
                    DataChange::WindowLoaded { range } => {
                        strategy_obs.invalidate_rows(range.start..range.end);
                    }
                    DataChange::Reset => {
                        strategy_obs.invalidate_rows(0..usize::MAX);
                        strategy_obs.resize(0);
                        scroll_reset.set(0.0);
                    }
                }
                // Index-shift (index model: insert / remove / move, cleared
                // on a reset) or prune the keys that left the source (keyed
                // model, which needs nothing else to follow its items).
                if let Some(ref s) = selection_obs {
                    s.on_data_change(change);
                    // A keyed selection follows its tile through a sort
                    // without being written, so no selection observer hears
                    // it, while the sort's reset has dropped the cursor. In a
                    // single selection the cursor goes back onto the tile, or
                    // the grid would name no tile as its active descendant.
                    if had_cursor
                        && focused_obs.get().is_none()
                        && s.mode() == SelectionMode::Single
                        && let Some(&tile) = s.selected_indices().first()
                    {
                        focused_obs.set(Some(tile));
                    }
                }
                if let Some(ref d) = detail_obs {
                    // Cloned out: moving the band re-anchors it, through an
                    // observer that writes this slot.
                    let anchor = anchor_obs.borrow().clone();
                    follow_the_disclosed_tile(d, anchor.as_ref(), change, (len_fn)());
                    if !matches!(change, DataChange::WindowLoaded { .. }) {
                        d.forget_placement();
                    }
                }
                if let DataChange::WindowLoaded { range } = change {
                    // Items arrived for tiles the pane drew as placeholders.
                    // Nothing else this root builds shows them, so the pane
                    // is rebuilt alone: rebuilding the root threw the band's
                    // content away, its focus and scroll offset with it,
                    // every time a lazy source slid its window. The band is
                    // built again only when it was waiting for this window.
                    pane_v.set(pane_v.get() + 1);
                    if let Some(ref d) = detail_obs
                        && d.awaiting_item.get()
                        && d.expanded.get().is_some_and(|i| range.contains(&i))
                    {
                        d.version.set(d.version.get().wrapping_add(1));
                    }
                    return;
                }
                let next = counter.get() + 1;
                counter.set(next);
                v.set(next);
            }));
            ctx.own_handle(handle);
        }

        // Fire on_selection_changed on every selection change (interactive
        // or programmatic). The framework's reactive observers don't carry
        // an EventContext, so the callback receives only the selection set.
        if let (Some(sel), Some(cb)) = (&self.selection, &self.on_selection_changed) {
            let cb = cb.clone();
            let live = sel.clone();
            let handle = sel.observe_for_rebuild(move || {
                let set: BTreeSet<usize> = live.selected_indices().into_iter().collect();
                cb(&set);
            });
            ctx.own_handle(handle);
        }

        // Rebuild when the loading flag toggles (shows/hides the overlay).
        if let Some(flag) = &self.is_loading {
            let v = version.clone();
            let c = Rc::new(Cell::new(0_u64));
            ctx.effect(&flag.as_signal(), move |_| {
                c.set(c.get() + 1);
                v.set(c.get());
            });
        }

        // Self handlers: scroll wheel + keyboard.
        let mut handlers = HandlerSet::new().clips_children(true).focusable(true);
        {
            // The wheel arithmetic, the pan and the claim that puts this node
            // on a finger's claimant chain all come from `common::scrollable`.
            // A wheel still takes the path it always did —
            // `handle_scroll_event` branches on the scroll *source*, not the
            // phase.
            //
            // The notch size is snapshotted from the strategy in force at
            // build, which is what the hand-rolled handler did: a strategy
            // swapped after mount keeps the notch it was built with until the
            // next rebuild.
            let behavior = crate::common::scrollable::ScrollableBehavior::new(
                crate::common::scrollable::ScrollableAxes::vertical(
                    self.scroll_y.clone(),
                    self.max_scroll_y.clone(),
                ),
            )
            .with_scroller(self.scroller.clone())
            // Vertical only: this view owns no horizontal offset, so a
            // horizontal pan is declined and chains outward.
            .axes(PanAxes::Y)
            .overscroll(self.overscroll_behavior)
            .smooth(self.smooth_scrolling)
            .smooth_duration(self.smooth_scroll_duration)
            .line_height(strategy.estimated_row_height().max(1.0))
            .reduced_motion(ctx.prefers_reduced_motion())
            .physics(ctx.theme().input.scroll_physics)
            .before({
                // The framework's reveal walk asks every clipping scroll
                // container above a widget that takes focus to bring it into
                // view. This grid ignored the question, so a control in the
                // detail band could take focus below the viewport, clipped.
                let scroll_y = self.scroll_y.clone();
                let max_scroll_y = self.max_scroll_y.clone();
                let viewport_height = self.viewport_height.clone();
                let viewport_origin = self.viewport_origin.clone();
                let glide = (self.smooth_scrolling && !ctx.prefers_reduced_motion())
                    .then_some(self.smooth_scroll_duration);
                move |event, _ctx| {
                    let WidgetEvent::ScrollIntoView {
                        target_bounds,
                        margin,
                        align,
                        motion,
                        applied_scroll,
                    } = event
                    else {
                        return None;
                    };
                    let Some(origin) = viewport_origin.get() else {
                        return Some(EventResponse::Ignored);
                    };
                    let glide =
                        glide.filter(|_| *motion == teksilo_core::event::ScrollMotion::Smooth);
                    let delta = reveal_in_viewport(
                        *target_bounds,
                        *margin,
                        *align,
                        glide,
                        &scroll_y,
                        &max_scroll_y,
                        origin.y,
                        viewport_height.get(),
                    );
                    if let Some(cell) = applied_scroll
                        && let Ok(mut applied) = cell.lock()
                    {
                        *applied = Point::new(0.0, delta);
                    }
                    Some(EventResponse::Handled)
                }
            });
            handlers = behavior.install(handlers);
        }
        // --- The non-drag reorder, all four routes at once ---
        //
        // SC 2.5.7 wants the tile drag reachable without a drag. One closure
        // performs the move; the chord below, the tile's context menu and the
        // tile's AccessKit custom actions all call it, so the routes cannot
        // reach different end states. The move travels the source's own
        // drop-accept path — see `common::ordered_move`.
        #[allow(clippy::type_complexity)]
        let reorder_perform: Option<
            Rc<dyn Fn(usize, usize, &mut teksilo_core::widget::EventContext)>,
        > = self.reorderable.then(|| {
            let mover = Rc::new(crate::common::ordered_move::RowMover {
                len: self.source.len_fn.clone(),
                stash: self.source.dnd.stash_drag_keys_fn.clone(),
                payload: {
                    let model_id = self.model_id;
                    Rc::new(move |idx: usize| {
                        DragPayload::typed(RowDragData::<T> {
                            source: model_id,
                            rows: vec![idx],
                            items: None,
                        })
                    })
                },
                accept: self.source.dnd.accept_drop_fn.clone(),
                view: self.model_id,
                name: {
                    // The type-ahead label resolver, where the application
                    // gave one; routed through the source's string accessor
                    // so an unloaded row yields no name rather than a
                    // fabricated one.
                    let with_item_str = self.source.with_item_str_fn.clone();
                    let label = self.type_ahead_label.clone();
                    Rc::new(move |index: usize| {
                        let label = label.as_ref()?;
                        // `label` is index-keyed here (a grid's delegate
                        // is), but the read still goes through the source so
                        // an unloaded tile yields no name rather than one
                        // computed for an absent item.
                        (with_item_str)(index, &|_item: &T| label(index))
                    })
                },
            });
            let focused = self.focused_index.clone();
            let selection = self.selection.clone();
            let strategy = strategy.clone();
            let scroll_y = self.scroll_y.clone();
            let max_scroll_y = self.max_scroll_y.clone();
            let viewport_height = self.viewport_height.clone();
            let viewport_width = self.viewport_width.clone();
            let viewport_origin = self.viewport_origin.clone();
            Rc::new(
                move |from: usize,
                      destination: usize,
                      ctx: &mut teksilo_core::widget::EventContext| {
                    let Some((dest, utterance)) = mover.commit_to(from, destination) else {
                        return;
                    };
                    focused.set(Some(dest));
                    if let Some(ref sel) = selection {
                        sel.select(dest);
                    }
                    keyboard::reveal_tile(
                        &strategy,
                        &scroll_y,
                        &max_scroll_y,
                        &viewport_height,
                        &viewport_width,
                        &viewport_origin,
                        dest,
                        ctx,
                    );
                    ctx.announce(utterance);
                },
            ) as Rc<dyn Fn(usize, usize, &mut teksilo_core::widget::EventContext)>
        });

        // Every user action that can change how many tiles are selected runs
        // inside this, so the count is said once, by the action that changed
        // it. See `selection_count`.
        let count_voice = self.selection.clone().map(SelectionCountVoice::new);

        // Activating a tile by the pointer: open or close its detail band
        // first, so the application's own handler sees the state the
        // activation left. The keys do the same in `keyboard::activate_tile`,
        // which also decides what Enter does to the selection.
        #[allow(clippy::type_complexity)]
        let activate: Option<Rc<dyn Fn(usize, &mut teksilo_core::widget::EventContext)>> =
            match &detail {
                Some(d) => {
                    let d = d.clone();
                    let user = self.on_tile_activate.clone();
                    Some(Rc::new(move |index, ctx| {
                        d.activate(index);
                        if let Some(user) = &user {
                            user(index, ctx);
                        }
                    }))
                }
                None => self.on_tile_activate.clone(),
            };

        // Select all comes through the rebindable `edit.select_all`, inside
        // the same count voice as the keys.
        {
            let len = self.source.len_fn.clone();
            let selection = self.selection.clone();
            let detail = detail.clone();
            let voice = count_voice.clone();
            crate::common::standard_edit::register_standard_edit_action(
                ctx,
                teksilo_core::shortcut::StandardEdit::SelectAll,
                move |ctx| {
                    let run = |_ctx: &mut teksilo_core::widget::EventContext| {
                        keyboard::run_select_all((len)(), selection.as_ref(), detail.as_deref())
                    };
                    match &voice {
                        Some(voice) => voice.around(ctx, run),
                        None => run(ctx),
                    }
                },
            );
        }

        let mut on_key = build_grid_key_handler(GridKeyConfig {
            len_fn: self.source.len_fn.clone(),
            col_count: self.column_count.clone(),
            focused_index: self.focused_index.clone(),
            selection: self.selection.clone(),
            count_voice: count_voice.clone(),
            scroll_y: self.scroll_y.clone(),
            max_scroll_y: self.max_scroll_y.clone(),
            viewport_height: self.viewport_height.clone(),
            viewport_width: self.viewport_width.clone(),
            viewport_origin: self.viewport_origin.clone(),
            strategy: strategy.clone(),
            wrap_navigation: self.wrap_navigation,
            tab_traversal: self.tab_traversal,
            on_tile_activate: self.on_tile_activate.clone(),
            detail: detail.clone(),
            reorder_perform: reorder_perform.clone(),
            type_ahead_timeout: self.type_ahead_timeout,
            type_ahead: self.type_ahead.clone(),
            tile_map: self.tile_map.clone(),
            // Route through the source's string accessor so an unloaded
            // (lazy/windowed) row is skipped rather than searched with
            // whatever the app's index-only closure happens to compute for
            // it — mirrors `ListView::with_item_str_fn`. The public
            // `type_ahead_label(usize) -> String` API is unchanged; this
            // just gates it on row residency.
            type_ahead_label: self.type_ahead_label.as_ref().map(|label| {
                let label = label.clone();
                let with_item_str = self.source.with_item_str_fn.clone();
                Rc::new(move |i: usize| (with_item_str)(i, &|_item: &T| label(i)))
                    as Rc<dyn Fn(usize) -> Option<String>>
            }),
        });
        {
            let voice = count_voice.clone();
            handlers = handlers.on_key(move |event, ctx| match &voice {
                Some(voice) => voice.around(ctx, |ctx| on_key(event, ctx)),
                None => on_key(event, ctx),
            });
        }

        // Rubber-band marquee (Multi mode only). A container pointer handler
        // records the modifier state at press time for additive selection;
        // the drag handler sweeps the rectangle — from the `DragSurface` that
        // wraps the body pane, not from this root. See below.
        let mut marquee_drag: Option<_> = None;
        let marquee_on = self.marquee_selection
            && self
                .selection
                .as_ref()
                .map(|s| s.mode() == SelectionMode::Multi)
                .unwrap_or(false);
        if marquee_on {
            let additive_mods = Rc::new(Cell::new(false));
            {
                let mods = additive_mods.clone();
                handlers = handlers.on_pointer_event(move |event, _ctx| {
                    if let WidgetEvent::PointerDown { modifiers, .. } = event {
                        mods.set(modifiers.command() || modifiers.shift());
                    }
                    EventResponse::Ignored
                });
            }
            // The marquee's `on_drag` does NOT go on this root, and that is
            // load-bearing rather than tidy. This root is the `PanClaim`
            // holder, and a drag on the node that also captures the press
            // latches at `drag_slop` (18 dp) before a claim can win at
            // `pan_slop` (36) — the claim is then never evaluated at all, so a
            // `Multi`-selection grid did not scroll under a finger *and* did
            // not marquee (the drag declines a press that lands on a tile).
            // Hanging it on the `DragSurface` below instead makes it a strict
            // ancestor of whatever takes the press, which is the one shape the
            // tree arms `DragActivation` for: `Immediate` for a mouse (5 dp,
            // exactly as before), `AfterLongPress` for a finger.
            let mut sweep = build_marquee_handler(MarqueeConfig {
                marquee: self.marquee.clone(),
                selection: self.selection.clone().unwrap(),
                strategy: strategy.clone(),
                scroll_y: self.scroll_y.clone(),
                viewport_width: self.viewport_width.clone(),
                len_fn: self.source.len_fn.clone(),
                additive_mods,
            });
            let voice = count_voice.clone();
            marquee_drag = Some(
                move |phase: teksilo_core::gesture::DragPhase,
                      ctx: &mut teksilo_core::widget::EventContext| match &voice {
                    Some(voice) => voice.around(ctx, |ctx| sweep(phase, ctx)),
                    None => sweep(phase, ctx),
                },
            );

            // Viewport-edge auto-scroll while the marquee is active, so a
            // rubber-band selection can extend past the visible window —
            // matching `TabBar`/`TreeView`'s drag-tick edge-scroll. Those
            // ride `on_drag_tick`, which only fires for an `active_drag`
            // (a `DragPayload` session started via `start_drag`); the
            // marquee is a plain gesture-recognizer drag (`on_drag`) with
            // no such session, so it drives itself from the raw per-frame
            // handle instead — the same "owner-driven, non-visibility-
            // bound" path the rich-text editor's drag-select auto-scroll
            // uses. Not gated on reduced-motion: this is an interaction
            // (extending the selection), not decorative motion.
            let frame_request = ctx.frame_request_handle();
            let marquee_for_tick = self.marquee.clone();
            let scroll_for_tick = self.scroll_y.clone();
            let max_scroll_for_tick = self.max_scroll_y.clone();
            let viewport_h_for_tick = self.viewport_height.clone();
            ctx.effect(&ctx.frame_tick(), move |_delta| {
                let Some(st) = marquee_for_tick.get() else {
                    return;
                };
                let step = selection::marquee_auto_scroll_step(
                    st.current.y,
                    viewport_h_for_tick.get(),
                    st.kind,
                );
                if step != 0.0 {
                    let max = max_scroll_for_tick.get();
                    let new_y = (scroll_for_tick.get() + step).clamp(0.0, max);
                    scroll_for_tick.set(new_y);
                    // Still inside the edge band (or the marquee moved
                    // again next frame) — keep the chain alive so the
                    // pointer doesn't need to wiggle to keep scrolling.
                    frame_request.set(true);
                }
            });
        }

        // Drop target: intra-grid reorder + foreign-rows receive + external
        // drops, with an insertion indicator painted by the overlay.
        // Hover/drop are routed through the SOURCE's `can_accept` /
        // `accept_drop` (the pre-drop validation), so a same-view
        // `RowDragData<T>` reorders and a foreign payload is the source's
        // call — falling back to the zero-custom-source `accept_foreign_rows`
        // sugar, then the app-level `on_item_drop` escape hatch.
        if self.export.is_drop_target(self.reorderable) || self.on_item_drop.is_some() {
            let has_drop_cb = self.on_item_drop.is_some();
            let my_id = self.model_id;

            let strategy_h = strategy.clone();
            let scroll_h = self.scroll_y.clone();
            let vp_w_h = self.viewport_width.clone();
            let len_h = self.source.len_fn.clone();
            let can_accept_h = self.source.dnd.can_accept_fn.clone();
            let insertion_h = self.insertion.clone();
            let export_for_hover = self.export.clone();
            handlers = handlers.on_drag_hover(move |payload, position, _ctx| {
                let len = (len_h)();
                let idx = drag::insertion_index(
                    strategy_h.as_ref(),
                    position,
                    scroll_h.get(),
                    vp_w_h.get(),
                    len,
                );
                let allowed = drop_allowed::<T>(
                    &can_accept_h,
                    payload,
                    idx,
                    len,
                    my_id,
                    has_drop_cb,
                    &export_for_hover,
                );
                if allowed {
                    insertion_h.set(Some(idx));
                    // Engage (stops drop-target bubbling); the overlay paints
                    // the insertion bar, so no framework-drawn feedback.
                    teksilo_core::DropFeedback::Accept
                } else {
                    insertion_h.set(None);
                    teksilo_core::DropFeedback::NoFeedback
                }
            });

            let insertion_leave = self.insertion.clone();
            handlers = handlers.on_drag_leave(move |_ctx| {
                insertion_leave.set(None);
            });

            let strategy_d = strategy.clone();
            let scroll_d = self.scroll_y.clone();
            let vp_w_d = self.viewport_width.clone();
            let len_d = self.source.len_fn.clone();
            let accept_drop_d = self.source.dnd.accept_drop_fn.clone();
            let drop_cb = self.on_item_drop.clone();
            let insertion_d = self.insertion.clone();
            let export_for_drop = self.export.clone();
            let reorderable_for_drop = self.reorderable;
            handlers = handlers.on_drop(move |mut payload, position, ctx| {
                insertion_d.set(None);
                let len = (len_d)();
                let to = drag::insertion_index(
                    strategy_d.as_ref(),
                    position,
                    scroll_d.get(),
                    vp_w_d.get(),
                    len,
                );
                let is_same_view = payload
                    .get_typed::<RowDragData<T>>()
                    .is_some_and(|rd| rd.source == my_id);
                // (a) Same-view reorder + any source-handled drop go through
                // accept_drop first. A same-view drop only reorders when this
                // view is `reorderable` — otherwise it falls through and is
                // treated like a foreign payload (branches b/c).
                if (reorderable_for_drop || !is_same_view)
                    && let Some((target, position_kind)) = flat_insertion_target(to, len)
                    && (accept_drop_d)(&payload, target, position_kind, my_id)
                {
                    // Only suppress our OWN move-out for a genuine same-view
                    // drop.
                    if is_same_view {
                        export_for_drop.note_self_reorder();
                    }
                    return true;
                }
                // (b) Shared foreign-receive sugar: accept exported rows from
                // a different view/source without a custom ListDataSource.
                // Peeks before taking, so a payload that doesn't match
                // (same-view, or reorder-only) still reaches the raw escape
                // hatch (c) with its typed data intact.
                if export_for_drop.foreign_receive(&mut payload, my_id, to, ctx) {
                    return true;
                }
                // (c) Raw escape hatch for any other payload the app wants to
                // handle itself.
                if let Some(ref cb) = drop_cb {
                    return cb(payload, to, ctx);
                }
                false
            });
        }
        ctx.apply_self_handlers(handlers);

        // Children: body pane (or empty view), scrollbar, overlay.
        // (Incremental loading — `request_window` / `fetch_more` — lives in the
        // body pane's realize loop now, driven by the source's `can_fetch_more`
        // / `fetch_more` capabilities; it fires on each scroll-buffer exit.)
        self.body_pane_id = None;
        self.empty_id = None;
        self.scrollbar_id = None;
        self.overlay_id = None;
        self.pinned_header_id = None;
        self.band_id = None;

        let len = self.source.len();
        if len == 0 {
            self.tile_map.borrow_mut().clear();
            // No tiles, so no band: nothing may still point at the last one.
            if let Some(ref d) = detail {
                d.shown.set(None);
                d.band_id.set(None);
                d.enterable.set(false);
            }
            if let Some(ref ef) = self.empty_view {
                self.empty_id = Some(ctx.add_boxed(ef()));
            }
        } else {
            // The band before the pane: it records which tile it shows as it
            // builds, and the pane's realization window is read off that.
            if let Some(d) = &detail {
                let return_to_tile: detail::ReturnToTile = {
                    let grid = ctx.self_id();
                    let focused = self.focused_index.clone();
                    let strategy = strategy.clone();
                    let scroll_y = self.scroll_y.clone();
                    let max_scroll_y = self.max_scroll_y.clone();
                    let viewport_height = self.viewport_height.clone();
                    let viewport_width = self.viewport_width.clone();
                    let viewport_origin = self.viewport_origin.clone();
                    Rc::new(move |index, ctx| {
                        focused.set(Some(index));
                        ctx.request_focus(grid);
                        keyboard::reveal_tile(
                            &strategy,
                            &scroll_y,
                            &max_scroll_y,
                            &viewport_height,
                            &viewport_width,
                            &viewport_origin,
                            index,
                            ctx,
                        );
                    })
                };
                self.band_id = Some(ctx.add(detail::DetailBand {
                    state: d.clone(),
                    len_fn: self.source.len_fn.clone(),
                    focused_index: self.focused_index.clone(),
                    name_fn: self.tile_a11y_label.clone(),
                    tile_map: self.tile_map.clone(),
                    return_to_tile,
                    grid: ctx.self_id(),
                    child: None,
                }));
            }

            // Pane → root total refresh (measuring strategies): re-place
            // this root when the body pane's measurements changed the
            // content total, so `max_scroll_y` / the thumb ratio pick up
            // the corrected value next frame.
            let pane_total_refresh = ctx.signal(0_u64);
            pane_total_refresh.bind_to(
                ctx.self_id(),
                ctx.binding_registry(),
                teksilo_core::binding::BindingLevel::Relayout,
            );
            let pane = GridBodyPane {
                len_fn: self.source.len_fn.clone(),
                with_item_fn: self.source.with_item_fn.clone(),
                delegate: self.delegate.clone(),
                strategy: strategy.clone(),
                viewport_width: self.viewport_width.clone(),
                viewport_height: self.viewport_height.clone(),
                viewport_origin: self.viewport_origin.clone(),
                column_count: self.column_count.clone(),
                scroll_y: self.scroll_y.clone(),
                selection: self.selection.clone(),
                count_voice: count_voice.clone(),
                focused_index: self.focused_index.clone(),
                on_tile_activate: activate.clone(),
                detail: detail.clone(),
                activate_on: self.activate_on,
                reorder_perform: reorder_perform.clone(),
                tile_context_menu: self.tile_context_menu.clone(),
                tile_a11y_label: self.tile_a11y_label.clone(),
                reorderable: self.reorderable,
                model_id: self.model_id,
                scope_owner: ctx.self_id(),
                drag_fn: self.source.dnd.drag_fn.clone(),
                row_state_fn: self.source.dnd.row_state_fn.clone(),
                request_window_fn: self.source.dnd.request_window_fn.clone(),
                can_fetch_more_fn: self.source.dnd.can_fetch_more_fn.clone(),
                fetch_more_fn: self.source.dnd.fetch_more_fn.clone(),
                export: self.export.clone(),
                read_item_fn: self.source.read_item_fn.clone(),
                snapshot_out_fn: self.source.dnd.snapshot_out_fn.clone(),
                tile_map: self.tile_map.clone(),
                header_factory: self.header_factory(),
                header_title: self.section_data.as_ref().map(|d| d.title_fn.clone()),
                // Fresh per GridView rebuild; persists across the
                // pane's own (buffer-exit / re-check / window-load) rebuilds.
                version: pane_version.clone(),
                prev_built_start: Rc::new(Cell::new(0)),
                prev_built_end: Rc::new(Cell::new(0)),
                total_refresh: pane_total_refresh,
                tile_entries: Vec::new(),
                tile_roots: Vec::new(),
                header_entries: Vec::new(),
                in_place_children: Cell::new(false),
            };
            let pane_id = ctx.add(pane);
            // A no-op tap gives the pane its own gesture arena, so a press on
            // the background *between* tiles is captured inside the
            // `DragSurface` rather than by it. Without that the surface would be
            // the captor and its own drag would win the arbitration at 18 dp,
            // which is the bug the surface exists to fix. A press on a tile is
            // captured by the tile's own absorber, deeper still — which it must
            // be, or the release would be dispatched here and bubbled outward,
            // never reaching the tile that recorded the press.
            ctx.apply_handlers(pane_id, crate::data_views::press_absorber());
            let surface_id = ctx.add(crate::data_views::DragSurface::new(pane_id));
            if let Some(drag) = marquee_drag.take() {
                ctx.apply_handlers(surface_id, HandlerSet::new().on_drag(drag));
            }
            self.body_pane_id = Some(surface_id);

            let overlay = GridOverlay {
                focused_index: self.focused_index.clone(),
                // Grid root's inclusive focus signal (stack empty here → resolves
                // to this root) + input modality, so the ring is keyboard-only
                // and hides when the grid loses focus.
                view_focused: ctx.view_focus_active(),
                focus_visible: ctx.focus_visible(),
                band_focus: detail.as_ref().map(|d| d.focus_within.clone()),
                band_moved: detail.as_ref().map(|d| d.moved.clone()),
                selection: self.selection.clone(),
                selection_changed: selection_changed.clone(),
                scroll_y: self.scroll_y.clone(),
                strategy: strategy.clone(),
                viewport_width: self.viewport_width.clone(),
                marquee: self.marquee.clone(),
                insertion: self.insertion.clone(),
                style: self.style.clone(),
                len_fn: self.source.len_fn.clone(),
            };
            self.overlay_id = Some(ctx.add(overlay));

            // Sticky pinned header slot (reused widget showing the current
            // section's header at the viewport top). Skipped when the
            // provider declares zero sections — `PinnedHeader::build` would
            // otherwise unconditionally invoke the factory at
            // `current_section`'s default (0), and a hand-rolled provider
            // indexing directly into its own section list would panic.
            self.pinned_header_id = None;
            let section_count = self
                .section_data
                .as_ref()
                .map(|d| (d.counts_fn)().len())
                .unwrap_or(0);
            if self.pinned_section_headers && section_count > 0 {
                if let Some(factory) = self.header_factory() {
                    let ph = PinnedHeader {
                        current_section: self.current_section.clone(),
                        factory,
                        child: None,
                        style: self.style.clone(),
                    };
                    self.pinned_header_id = Some(ctx.add(ph));
                }
            }
        }

        if self.show_scrollbar {
            let sb = ScrollBar::new(
                ScrollBarOrientation::Vertical,
                self.scroll_y.clone(),
                self.max_scroll_y.clone(),
                self.viewport_ratio_y.clone(),
            )
            .visual(match self.scroll_bar_style {
                ScrollBarMode::Permanent => ScrollBarVisual::Permanent,
                ScrollBarMode::Overlay => ScrollBarVisual::Overlay,
                ScrollBarMode::Thin => ScrollBarVisual::Thin,
            });
            self.scrollbar_id = Some(ctx.add(sb));
        }

        // Loading overlay (on top of everything).
        self.loading_id = None;
        if let Some(flag) = &self.is_loading {
            if flag.get() {
                if let Some(ref lv) = self.loading_view {
                    self.loading_id = Some(ctx.add_boxed(lv()));
                }
            }
        }

        // Order = paint order. Overlay then loading paint last (on top).
        let mut children = Vec::new();
        if let Some(id) = self.body_pane_id {
            children.push(id);
        }
        if let Some(id) = self.band_id {
            children.push(id);
        }
        if let Some(id) = self.empty_id {
            children.push(id);
        }
        if let Some(id) = self.scrollbar_id {
            children.push(id);
        }
        if let Some(id) = self.overlay_id {
            children.push(id);
        }
        if let Some(id) = self.pinned_header_id {
            children.push(id);
        }
        if let Some(id) = self.loading_id {
            children.push(id);
        }
        children
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        _ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        // Only an allocation may seed the cached viewport (`common::viewport`);
        // the body pane shares these cells, and `build` sizes its realization
        // window — and the strategy its column count — from them.
        let size = crate::common::viewport::viewport_size(
            proposal,
            &self.viewport_height,
            Size::new(400.0, 400.0),
        );
        if proposal.width.is_some() {
            self.viewport_width.set(size.width);
        }
        size.into()
    }

    fn place_children(
        &self,
        bounds: Rect,
        _proposal: SizeProposal,
        children: &mut [WidgetPlacement],
        ctx: &LayoutContext,
    ) {
        let Some(ref strategy) = self.strategy else {
            return;
        };
        // Leading and trailing in `column_alignment` resolve against the
        // direction of this pass; every position read below and by the pane
        // (and, after layout, by paint, the marquee and the keys) follows.
        strategy.set_rtl(ctx.is_rtl());
        let len = self.source.len();
        let vp_h = bounds.height;
        // The rubber band's resistance is a fraction of the viewport. This
        // view does not band, but the scroller reads the extent either way and
        // this is the only pass that knows it.
        self.scroller
            .borrow_mut()
            .set_viewport(teksilo_canvas::Vec2::new(bounds.width, vp_h));

        // Query the strategy at a SINGLE, stable body width per frame (using
        // the previous frame's scrollbar decision). Querying at two widths
        // would flip a variable strategy's column count back and forth and
        // reset its measurement cache every frame. The scrollbar appearing /
        // disappearing settles in one frame.
        // Permanent reserves a column for the bar; Overlay / Thin float
        // over the content, so tiles span the full width.
        let reserves_bar = self.scroll_bar_style == ScrollBarMode::Permanent;
        let body_w = if self.last_needs_scrollbar.get() && reserves_bar {
            (bounds.width - SCROLLBAR_THICKNESS).max(0.0)
        } else {
            bounds.width
        };
        self.viewport_width.set(body_w);

        let cols = strategy.column_count(body_w).max(1);
        if self.column_count.get() != cols {
            self.column_count.set(cols);
        }

        // The detail band is measured before the total is asked for, so the
        // total, and the tiles the pane places after this, already include
        // its height. Height-for-width at the band's own width, which is the
        // content's: a band of text wraps there.
        if let Some(layout) = &self.detail_layout {
            if let (Some(band), Some(d)) = (self.band_id, &self.detail)
                && d.measures()
                && let Some((index, rect)) = layout.band_rect(body_w)
                && let Some(measured) = ctx.child_size(band, SizeProposal::with_width(rect.width))
            {
                layout.record_band_height(index, measured.height);
            }
            // Whatever the band did since the last pass (opened, closed,
            // moved, grew), the content under the viewport's top edge stays
            // put. Clamped with everything else below.
            let shift = layout.settle_placement(self.scroll_y.get(), body_w);
            if shift.abs() > 0.01 {
                self.scroll_y.set(self.scroll_y.get() + shift);
            }
        }

        let total = strategy.total_content_height(len, body_w);
        let needs_sb = self.show_scrollbar && total > vp_h + 0.5;
        if self.last_needs_scrollbar.get() != needs_sb {
            self.last_needs_scrollbar.set(needs_sb);
        }
        let max_y = (total - vp_h).max(0.0);
        self.max_scroll_y.set(max_y);

        // A band a user just opened is scrolled into view with its tile's
        // row, now that its height is known: the row first when the two do
        // not fit, so the band reads as the tile's.
        if let (Some(layout), Some(d)) = (&self.detail_layout, &self.detail)
            && let Some(index) = d.reveal.take()
            && let Some((top, bottom)) = layout.reveal_span(index, body_w)
        {
            let cur = self.scroll_y.get();
            let y = reveal_span_offset(top, bottom, cur, vp_h, max_y);
            if (y - cur).abs() > 0.001 {
                self.scroll_y.set(y);
            }
        }
        // A handle's request, at the same point and for the same reason: the
        // band is measured and the anchoring above has run, so the offset is
        // computed in the layout the tile will be shown in. An offset
        // written from outside before this pass would have been taken for
        // one of the old layout and moved by the anchoring. After the
        // grid's own reveal, which it replaces when both are pending: it was
        // asked for explicitly.
        if let Some(request) = self.reveal.take()
            && let Some(y) = scroll_for_request(
                strategy.as_ref(),
                self.detail_layout.as_deref(),
                request,
                len,
                self.scroll_y.get(),
                vp_h,
                body_w,
                max_y,
            )
        {
            self.scroll_y.set(y);
        }
        let ratio = if total > 0.0 {
            (vp_h / total).clamp(0.0, 1.0)
        } else {
            1.0
        };
        self.viewport_ratio_y.set(ratio);
        // Clamp scroll (matches ListView).
        let cur = self.scroll_y.get();
        let clamped = cur.clamp(0.0, max_y);
        if (clamped - cur).abs() > 0.001 {
            self.scroll_y.set(clamped);
        }

        // Sticky pinned header: track the current section and decide whether
        // the in-flow header has scrolled above the top.
        let pinned_rect = if self.pinned_header_id.is_some() {
            let cur = strategy.current_section(self.scroll_y.get(), body_w);
            if let Some(cur) = cur {
                if self.current_section.get() != cur {
                    self.current_section.set(cur);
                }
                // Show the pinned slot only once the real header is above top.
                strategy.header_rect(cur, body_w).map(|r| {
                    let screen_y = bounds.y + r.y - self.scroll_y.get();
                    let visible = screen_y < bounds.y - 0.5;
                    (visible, r.height)
                })
            } else {
                None
            }
        } else {
            None
        };

        let band_rect = self
            .detail_layout
            .as_ref()
            .and_then(|layout| layout.band_rect(body_w));
        // What of the band is on screen, now that the offset is final.
        self.detail_visible_span.set_if_changed(
            band_rect
                .filter(|(_, r)| r.height > 0.0)
                .and_then(|(_, r)| band_visible_span(r, self.scroll_y.get(), vp_h)),
        );

        let body_rect_origin = bounds.origin();
        let body_size = Size::new(body_w, vp_h);
        for child in children.iter_mut() {
            if Some(child.id) == self.band_id {
                // In content coordinates, like a tile: the pane fills the
                // same rect and places its tiles at `tile_rect - scroll`.
                match band_rect {
                    Some((_, r)) => {
                        child.origin =
                            Point::new(bounds.x + r.x, bounds.y + r.y - self.scroll_y.get());
                        child.size = Size::new(r.width, r.height);
                    }
                    None => {
                        child.origin = bounds.origin();
                        child.size = Size::ZERO;
                    }
                }
            } else if Some(child.id) == self.scrollbar_id {
                if needs_sb {
                    // Right edge in all modes — in Overlay / Thin `body_w`
                    // spans the full width, so anchor off `bounds.width`.
                    child.origin =
                        Point::new(bounds.x + bounds.width - SCROLLBAR_THICKNESS, bounds.y);
                    child.size = Size::new(SCROLLBAR_THICKNESS, vp_h);
                } else {
                    child.origin = bounds.origin();
                    child.size = Size::ZERO;
                }
            } else if Some(child.id) == self.pinned_header_id {
                match pinned_rect {
                    Some((true, h)) => {
                        child.origin = bounds.origin();
                        child.size = Size::new(body_w, h);
                    }
                    _ => {
                        child.origin = bounds.origin();
                        child.size = Size::ZERO;
                    }
                }
            } else {
                // body pane / empty view / overlay all fill the body rect.
                child.origin = body_rect_origin;
                child.size = body_size;
            }
        }
    }

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

        let total = self.source.len();
        let cols = self.column_count.get().max(1);
        let rows = total.div_ceil(cols);
        builder.set_row_count(rows);
        builder.set_column_count(cols);
        // The set size belongs on the container, not on each tile: AccessKit's
        // `size_of_set` differs from ARIA's per-item `aria-setsize`, and
        // `size_of_set_from_container` resolves an item's set size by walking
        // *up* from it. The logical item count, not the realized window.
        if total > 0 {
            builder.set_size_of_set(total);
        }

        if let Some(ref sel) = self.selection {
            if sel.mode() == SelectionMode::Multi {
                builder.set_multiselectable(true);
            }
            // The count as the grid's value, for a screen reader that reports
            // it with the grid. Not a live region: a `Grid` is named by its
            // label, so no platform announced the value, and every tile
            // inherited the setting and was announced as it scrolled into
            // view. The count is spoken by the action that changes it; see
            // `selection_count`.
            let count = sel.count();
            if count > 0 {
                builder.set_value(selection_count_words(count));
            }
        }

        // Roving focus: point active_descendant at the focused tile node.
        if let Some(idx) = self.focused_index.get() {
            let map = self.tile_map.borrow();
            if let Some((_, tile_id)) = map.iter().find(|(i, _)| *i == idx) {
                builder.set_active_descendant(widget_id_to_node_id(*tile_id));
            }
        }
    }

    /// The context-menu key opens the *focused tile's* menu, not the grid's.
    ///
    /// A `GridView` is focusable and its tiles are not — the container owns
    /// focus and `active_descendant` above is what points assistive technology
    /// at the current tile. So the dispatcher's default of "the focused widget"
    /// would open the grid's own menu.
    ///
    /// The tile the user means is the roving cursor, else the first selected
    /// tile. Only realized tiles have a widget, so a cursor scrolled outside
    /// the virtualization window resolves to nothing and the menu falls back to
    /// the grid — which is right, since there is no tile on screen for it to be
    /// about.
    fn context_menu_key_target(&self) -> Option<WidgetId> {
        let index = self.focused_index.get().or_else(|| {
            self.selection
                .as_ref()
                .and_then(|s| s.selected_indices().first().copied())
        })?;
        let map = self.tile_map.borrow();
        map.iter().find(|(i, _)| *i == index).map(|(_, id)| *id)
    }

    fn as_any(&self) -> Option<&dyn std::any::Any> {
        Some(self)
    }

    /// Every child but the detail band, which the body pane presents among
    /// the tiles, after its own row (`GridBodyPane::accessibility_children`).
    fn accessibility_children(&self) -> Option<Vec<WidgetId>> {
        let band = self.band_id?;
        Some(
            self.children()
                .into_iter()
                .filter(|&id| id != band)
                .collect(),
        )
    }

    fn children(&self) -> Vec<WidgetId> {
        let mut ids = Vec::new();
        if let Some(id) = self.body_pane_id {
            ids.push(id);
        }
        if let Some(id) = self.band_id {
            ids.push(id);
        }
        if let Some(id) = self.empty_id {
            ids.push(id);
        }
        if let Some(id) = self.scrollbar_id {
            ids.push(id);
        }
        if let Some(id) = self.overlay_id {
            ids.push(id);
        }
        if let Some(id) = self.pinned_header_id {
            ids.push(id);
        }
        if let Some(id) = self.loading_id {
            ids.push(id);
        }
        ids
    }

    fn clips_children(&self) -> bool {
        true
    }
}

/// A top-most, event-transparent leaf that paints the focus ring, the
/// marquee rectangle and the drag-insertion bar. Drawing
/// here rather than in the container sidesteps any parent-vs-child paint-order
/// ambiguity — a last sibling always paints over the tiles.
struct GridOverlay {
    focused_index: Signal<Option<usize>>,
    /// `true` while the grid (its root or a descendant) holds keyboard focus —
    /// the grid root's inclusive [`BuildContext::view_focus_active`] signal.
    /// Gates the focus ring so an unfocused grid shows none.
    view_focused: Signal<bool>,
    /// Input-modality `:focus-visible`. Gates the focus ring to keyboard
    /// navigation, never a mouse click.
    focus_visible: Signal<bool>,
    /// `true` while focus is inside the detail band, where the ring would
    /// point at a tile the keyboard is not on.
    band_focus: Option<Signal<bool>>,
    /// Bumped when the detail band's placement changes, which moves the
    /// tiles after it: the ring and the insertion bar move with them, though
    /// this widget's own bounds do not change.
    band_moved: Option<Signal<u64>>,
    /// The grid's selection, for the **container focus ring**: when the grid is
    /// keyboard-focused but has no current tile *and* nothing is selected, no
    /// tile chrome marks the focus, so the whole grid outlines itself instead.
    selection: Option<RowSelection>,
    /// Bumped on every selection change; repaints the container ring.
    selection_changed: Signal<u64>,
    scroll_y: Signal<f32>,
    strategy: Rc<dyn GridLayoutStrategy>,
    viewport_width: Rc<Cell<f32>>,
    marquee: Signal<Option<MarqueeState>>,
    insertion: Signal<Option<usize>>,
    style: Option<Rc<dyn GridViewStyle>>,
    /// Live item count — `focused_index` is adjusted on every model change,
    /// but paint reads a snapshot signal on a different binding level
    /// (`AccessibilityOnly` on the grid root vs `RepaintOnly` here), so a
    /// stale index can transiently outlive the adjustment. Bounds-check
    /// before drawing a ring at a tile that no longer exists.
    len_fn: Rc<dyn Fn() -> usize>,
}

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

impl GridOverlay {
    fn focus_recipe(&self, ctx: &PaintContext) -> teksilo_core::styles::GridFocusRingRecipe {
        resolve_grid_style(&self.style, ctx, |s| s.focus_ring())
    }
    fn marquee_recipe(&self, ctx: &PaintContext) -> teksilo_core::styles::GridMarqueeRecipe {
        resolve_grid_style(&self.style, ctx, |s| s.marquee())
    }
    fn insertion_recipe(&self, ctx: &PaintContext) -> teksilo_core::styles::GridInsertionRecipe {
        resolve_grid_style(&self.style, ctx, |s| s.insertion())
    }
}

/// Geometry of the drag-reorder insertion bar: `(bar_x, row_rect)`, where
/// `bar_x` is the bar's CENTER x and `row_rect` supplies its `y`/`height`.
/// When `ins < len` this is the LEADING edge of the target tile
/// `tile_rect(ins)` — using the target row (not the previous tile's row)
/// is what keeps the bar on the correct row at a row boundary, where
/// `ins` is the first index of a new row. When `ins >= len` (append) it's
/// the trailing edge of the last tile. `None` for an empty grid.
fn insertion_bar_geometry(
    strategy: &dyn GridLayoutStrategy,
    ins: usize,
    len: usize,
    viewport_width: f32,
) -> Option<(f32, TileRect)> {
    if len == 0 {
        return None;
    }
    if ins < len {
        let r = strategy.tile_rect(ins, viewport_width);
        Some((r.x, r))
    } else {
        let r = strategy.tile_rect(len - 1, viewport_width);
        Some((r.x + r.width, r))
    }
}

/// Resolve a decoration recipe from the per-call override → theme slot →
/// stock default.
fn resolve_grid_style<R: Default>(
    override_style: &Option<Rc<dyn GridViewStyle>>,
    ctx: &PaintContext,
    f: impl Fn(&dyn GridViewStyle) -> R,
) -> R {
    if let Some(s) = override_style {
        f(s.as_ref())
    } else if let Some(s) = ctx.theme.style_slots.grid_view.as_ref() {
        f(s.as_ref())
    } else {
        R::default()
    }
}

impl Widget for GridOverlay {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        // Repaint on focus / scroll / marquee / insertion change.
        self.scroll_y.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        self.focused_index.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        self.view_focused.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        self.focus_visible.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        self.selection_changed.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        if let Some(ref band_focus) = self.band_focus {
            band_focus.bind_to(
                ctx.self_id(),
                ctx.binding_registry(),
                BindingLevel::RepaintOnly,
            );
        }
        if let Some(ref band_moved) = self.band_moved {
            band_moved.bind_to(
                ctx.self_id(),
                ctx.binding_registry(),
                BindingLevel::RepaintOnly,
            );
        }
        self.marquee.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        self.insertion.bind_to(
            ctx.self_id(),
            ctx.binding_registry(),
            BindingLevel::RepaintOnly,
        );
        // Transparent to pointer events so the body beneath stays interactive.
        ctx.apply_self_handlers(HandlerSet::new().event_pass_through(true));
        Vec::new()
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        _ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        proposal.resolve(0.0, 0.0).into()
    }

    fn paint(&self, bounds: Rect, canvas: &mut teksilo_canvas::Canvas, ctx: &PaintContext) {
        // Marquee rectangle (in widget-local coords → offset by bounds origin).
        if let Some(m) = self.marquee.get() {
            let lr = m.local_rect(self.scroll_y.get());
            let rect = Rect::new(bounds.x + lr.x, bounds.y + lr.y, lr.width, lr.height);
            let recipe = self.marquee_recipe(ctx);
            let c = recipe.role.resolve(&ctx.theme.colors);
            let fill = teksilo_tokens::Color::new(c.r(), c.g(), c.b(), recipe.fill_alpha);
            canvas.fill_rect(rect, fill);
            canvas.stroke_rect(rect, c, recipe.stroke_width);
        }

        // Drag-reorder insertion bar: a vertical accent bar at the leading
        // edge of the target tile (or trailing edge of the last tile when
        // appending).
        if let Some(ins) = self.insertion.get()
            && let Some((bar_x, r)) =
                insertion_bar_geometry(self.strategy.as_ref(), ins, (self.len_fn)(), bounds.width)
        {
            let scroll_y = self.scroll_y.get();
            let y = bounds.y + r.y - scroll_y;
            let h = r.height;
            if y + h >= bounds.y && y <= bounds.bottom() {
                let recipe = self.insertion_recipe(ctx);
                let color = recipe.role.resolve(&ctx.theme.colors);
                let t = recipe.thickness;
                canvas.fill_rect(Rect::new(bounds.x + bar_x - t * 0.5, y, t, h), color);
            }
        }

        // Focus ring — keyboard-only (`:focus-visible`) and only while the grid
        // holds focus, so a mouse click never leaves a ring.
        if !self.view_focused.get()
            || !self.focus_visible.get()
            || self.band_focus.as_ref().is_some_and(|f| f.get())
        {
            return;
        }
        // A stale index (outlived by a not-yet-applied model-change
        // adjustment) can't draw a ring at a tile that no longer exists —
        // treat it the same as "no current tile".
        let idx = self.focused_index.get().filter(|&i| i < (self.len_fn)());
        let Some(idx) = idx else {
            // No current tile. If nothing is selected either, no tile chrome
            // marks the focus — outline the whole grid so a Tab-focused empty
            // grid still shows where focus landed (mirrors TreeView / ListView).
            let empty = self.selection.as_ref().is_none_or(|s| !s.has_selection());
            if empty {
                let inset = 1.0_f32;
                let rect = Rect::new(
                    bounds.x + inset,
                    bounds.y + inset,
                    (bounds.width - inset * 2.0).max(0.0),
                    (bounds.height - inset * 2.0).max(0.0),
                );
                let color = teksilo_tokens::BorderRole::Focused.resolve(&ctx.theme.colors);
                canvas.stroke_rect(rect, color, 1.5);
            }
            return;
        };
        let vp_w = bounds.width;
        let r = self.strategy.tile_rect(idx, vp_w);
        let scroll_y = self.scroll_y.get();
        let recipe = self.focus_recipe(ctx);
        let inset = recipe.inset;
        let stroke = recipe.thickness;
        let rx = bounds.x + r.x + inset;
        let ry = bounds.y + r.y - scroll_y + inset;
        let rw = (r.width - inset * 2.0).max(0.0);
        let rh = (r.height - inset * 2.0).max(0.0);
        // Cull if fully outside the viewport.
        if ry + rh < bounds.y || ry > bounds.bottom() {
            return;
        }
        let color = recipe.role.resolve(&ctx.theme.colors);
        canvas.fill_rect(Rect::new(rx, ry, rw, stroke), color); // top
        canvas.fill_rect(Rect::new(rx, ry + rh - stroke, rw, stroke), color); // bottom
        canvas.fill_rect(Rect::new(rx, ry, stroke, rh), color); // left
        canvas.fill_rect(Rect::new(rx + rw - stroke, ry, stroke, rh), color); // right
    }

    fn accessibility(&self, builder: &mut AccessNodeBuilder) {
        builder.set_hidden();
    }
}

/// The reused sticky-header slot: rebuilds its child from the section header
/// factory whenever the current section changes, and paints an opaque
/// background so tiles scrolling underneath don't show through.
struct PinnedHeader {
    current_section: Signal<usize>,
    #[allow(clippy::type_complexity)]
    factory: Rc<dyn Fn(usize) -> Box<dyn Widget>>,
    child: Option<WidgetId>,
    style: Option<Rc<dyn GridViewStyle>>,
}

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

impl Widget for PinnedHeader {
    fn build(&mut self, ctx: &mut BuildContext) -> Vec<WidgetId> {
        self.current_section
            .bind_to(ctx.self_id(), ctx.binding_registry(), BindingLevel::Rebuild);
        let section = self.current_section.get();
        let id = ctx.add_boxed((self.factory)(section));
        self.child = Some(id);
        vec![id]
    }

    fn layout_response(
        &self,
        proposal: SizeProposal,
        _ctx: &LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        proposal.resolve(0.0, 0.0).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();
        }
    }

    fn paint(&self, bounds: Rect, canvas: &mut teksilo_canvas::Canvas, ctx: &PaintContext) {
        if bounds.height > 0.5 {
            let surface = self
                .style
                .as_ref()
                .or(ctx.theme.style_slots.grid_view.as_ref())
                .map(|s| s.pinned_header_surface())
                .unwrap_or(SurfaceRole::Raised);
            canvas.fill_rect(bounds, surface.resolve(&ctx.theme.colors));
        }
    }

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

    fn clips_children(&self) -> bool {
        true
    }
}

#[cfg(test)]
mod focus_reveal_tests {
    //! Taking focus brings the current tile into the realized window.
    //!
    //! The other half of `active_descendant`: `GridView::accessibility` can
    //! only nominate a tile that has a widget, and virtualization means the
    //! current one usually has none until the grid is scrolled to it.

    use super::*;
    use teksilo_core::widget::LayoutContext;
    use teksilo_core::widget_tree::WidgetTree;

    #[derive(Debug)]
    struct FixedLeaf(f32, f32);
    impl Widget for FixedLeaf {
        fn layout_response(
            &self,
            _proposal: SizeProposal,
            _ctx: &LayoutContext,
        ) -> teksilo_core::widget::LayoutResponse {
            Size::new(self.0, self.1).into()
        }
    }

    /// A 300-item grid of 100x50 tiles carrying `selection`, laid out once at
    /// 400x300. That width holds three columns, so the items wrap into 100
    /// rows of 58px and the viewport shows about five of them.
    fn grid_with_selection(selection: &SelectionModel) -> (WidgetTree, WidgetId) {
        let model = ListModel::from_vec((0..300).collect::<Vec<usize>>());
        let mut tree = WidgetTree::new();
        let id = tree.add(
            GridView::new(model, |_tc| Box::new(FixedLeaf(100.0, 50.0)))
                .tile_size(100.0, 50.0)
                .selection(selection.clone()),
        );
        tree.layout(SizeProposal::exact(400.0, 300.0));
        (tree, id)
    }

    /// The flat index of every realized tile marked selected, read back off
    /// the accessibility tree, since that is what the failure was about: the
    /// tile has to be a node a platform can name.
    ///
    /// `position_in_set` reads 0-based here even though `TileA11y` writes the
    /// 1-based ARIA number (`grid_view/a11y.rs:88`):
    /// `AccessNodeBuilder::set_position_in_set`
    /// (`teksilo-core/src/accessibility.rs:726-729`) subtracts the 1 through
    /// `to_accesskit_ordinal` (`:359-366`), so the value in a snapshot is the
    /// flat index itself.
    fn selected_positions(tree: &WidgetTree) -> Vec<usize> {
        tree.accessibility_tree_snapshot()
            .nodes
            .iter()
            .filter(|(_, node)| node.is_selected() == Some(true))
            .filter_map(|(_, node)| node.position_in_set())
            .collect()
    }

    /// A selection made before the grid is ever looked at is off-window, so
    /// nothing carries it into the tree until focus scrolls to it.
    #[test]
    fn taking_focus_reveals_the_current_tile() {
        let selection = SelectionModel::new(SelectionMode::Single);
        selection.select(150);
        let (mut tree, id) = grid_with_selection(&selection);

        assert!(
            selected_positions(&tree).is_empty(),
            "tile 150 sits fifty rows below the realized window, which is the \
             case this is about"
        );

        tree.focus(id);
        tree.layout(SizeProposal::exact(400.0, 300.0));

        assert_eq!(
            selected_positions(&tree),
            vec![150],
            "taking focus has to bring the current tile into the realized \
             window, or nothing in the tree can be told about it"
        );
    }

    /// The window-space rect of a realized tile, read out of the same
    /// `tile_map` the body pane writes and `accessibility` nominates from
    /// (`grid_view.rs:1904-1910`). `None` for a tile outside the
    /// virtualization window, which has no widget and so no rect.
    fn tile_bounds(tree: &WidgetTree, grid: WidgetId, index: usize) -> Option<Rect> {
        let tile = tree
            .widget_as_any(grid)
            .and_then(|any| any.downcast_ref::<GridView<usize>>())
            .and_then(|g| {
                g.tile_map
                    .borrow()
                    .iter()
                    .find(|(i, _)| *i == index)
                    .map(|(_, id)| *id)
            })?;
        Some(tree.bounds(tile))
    }

    /// And a tile already on screen does not lurch when the grid is clicked
    /// into: `ScrollAnchor::Auto`, not a forced anchor.
    ///
    /// Tile 12 is the one that catches a forced anchor. Three columns of 58px
    /// row step put it on the fifth row, spanning y 232..282 of a 300px
    /// viewport: fully visible, and far enough down that `Center` would scroll
    /// by about 107px to drag it to the middle. A tile on the first row proves
    /// nothing here, because centering row 0 asks for a negative offset that
    /// the clamp to `0.0..=max_scroll_y` turns back into no movement at all.
    #[test]
    fn taking_focus_does_not_move_a_tile_already_in_view() {
        let selection = SelectionModel::new(SelectionMode::Single);
        selection.select(12);
        let (mut tree, id) = grid_with_selection(&selection);

        let scroll = tree
            .widget_as_any(id)
            .and_then(|any| any.downcast_ref::<GridView<usize>>())
            .map(|g| g.scroll_y_signal().clone())
            .expect("the grid is the widget at `id`");
        let before = scroll.get();

        let rect = tile_bounds(&tree, id, 12).expect("tile 12 is realized");
        assert!(
            rect.y >= 0.0 && rect.y + rect.height <= 300.0,
            "this case only means anything while tile 12 is fully on screen, \
             and it spans y {}..{} of a 300px viewport",
            rect.y,
            rect.y + rect.height
        );

        tree.focus(id);
        tree.layout(SizeProposal::exact(400.0, 300.0));

        assert_eq!(
            scroll.get(),
            before,
            "tile 12 is already fully visible, so taking focus must not scroll \
             the grid under somebody who can see it"
        );
    }
}