teksilo_widgets/

tree_view.rs

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

//! TreeView — a virtualized, expandable/collapsible hierarchical list widget.
//!
//! Displays a [`TreeModel<T>`](teksilo_data::TreeModel) as an indented tree.
//! Internally each view owns a [`TreeSlice`] for independent
//! expand state, so two `TreeView`s on the same model can be open at different
//! depths simultaneously. Only rows in the visible viewport + a small buffer have
//! live widgets — rows outside the buffer are dormant, matching `ListView`'s
//! virtualization model. An external [`TreeDataSource`]
//! is also accepted via [`TreeView::from_source`] when the data lives outside a
//! `TreeModel`.
//!
//! Row heights come in three modes: uniform (`item_height`, default fast path),
//! exact per-flat-index callback (`item_height_fn`), and auto-measured
//! (`auto_item_height` — height-for-width per row, scroll-anchored).
//!
//! ## Scrolling to a row
//!
//! [`handle`](TreeView::handle) returns a [`TreeViewHandle`], a cheap `Clone`
//! taken before the view is added and usable from any handler afterwards. Its
//! [`scroll_to_index`](TreeViewHandle::scroll_to_index) and
//! [`ensure_index_visible`](TreeViewHandle::ensure_index_visible) take a flat
//! visible row index and are applied at the next layout pass, after row
//! measurement and scroll anchoring, so they may follow an expansion in the
//! same turn, or be called before mount:
//!
//! ```rust
//! # use teksilo_widgets::TreeView;
//! # use teksilo_widgets::primitives::TextWidget;
//! # use teksilo_data::TreeModel;
//! # use teksilo_i18n::lit;
//! # let model: TreeModel<String> = TreeModel::new();
//! let tree = TreeView::new(model, |item, _entry, _selected| {
//!     Box::new(TextWidget::new(lit!(item)))
//! });
//! let handle = tree.handle();
//! // … `ctx.add(tree)`; then, from a handler, after expanding the row's
//! // ancestors in the same turn:
//! handle.ensure_index_visible(42);
//! ```
//!
//! ## The keyboard cursor
//!
//! The tree has one current row, its keyboard cursor: the row the arrow keys
//! step from and the one it names to assistive technology as its active
//! descendant while it holds keyboard focus. The same [`TreeViewHandle`]
//! reads and moves it, in flat visible indices:
//! [`cursor`](TreeViewHandle::cursor),
//! [`set_cursor`](TreeViewHandle::set_cursor) (clamped to the last visible
//! row; keyboard focus, the selection and the scroll offset are left alone)
//! and [`cursor_signal`](TreeViewHandle::cursor_signal), for an application
//! to observe. The cursor follows its row through an expansion or a collapse
//! above it, whoever set it. A cursor set before mount is there at the first
//! build.
//!
//! In a single selection the cursor follows the selection. In a multiple
//! selection the two are **separate**: `Ctrl+↓` moves the cursor and leaves
//! the selection, and a selection written from outside leaves the cursor
//! where it was. Read the cursor, not the first selected row, for "the row
//! the user is on".
//!
//! ## 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. Vertical only: this view owns no horizontal offset, so a
//! horizontal pan is declined and chains outward. A pan that starts on a row
//! scrolls rather than activating it, toggling its chevron, or collapsing a
//! multi-selection onto it — the three things a *release* on that row commits.
//! Activation is a gesture, so the arbitration cancels it; the chevron and the
//! deferred collapse are raw `PointerUp` arms the arbitration cannot reach, so
//! each asks `data_views::release_completes_the_press` whether the release still
//! belongs to the row.
//!
//! ## Keyboard
//!
//! Arrows move the cursor; `Home` / `End` reach the first and last **visible**
//! row and `PageUp` / `PageDown` a viewport of them, each moving the selection
//! unless the accelerator is held, which moves the cursor alone — in a
//! multiple selection only: a single selection always moves with the cursor,
//! a selection the application sets moves the cursor onto it, and a
//! structural change carries the selection along with its row. `Shift`
//! extends a range from the anchor and `Ctrl+Shift` extends it additively.
//!
//! `→` opens a closed node and, on one already open, moves into its first
//! child; `←` closes an open node and, on a leaf or a closed one, ascends to
//! the parent. Both mirror under RTL. `*` expands the whole subtree, `+` and
//! `-` one level. `Space` selects or toggles, `Enter` activates, `Ctrl+A` and
//! `Ctrl+Shift+A` select and deselect everything, and `Ctrl+Arrow` with
//! `Ctrl+Space` build a disjoint selection. On macOS `⌘↓` opens a row, `⌘↑`
//! ascends, and `⌥→`/`⌥←` expand or collapse a subtree.
//!
//! The full table, and why some of it is platform-specific, is in
//! [docs/data-view-keyboard.md](https://github.com/ferntech-eu/teksilo/blob/main/docs/data-view-keyboard.md).
//!
//! ## Example
//!
//! ```rust
//! # use teksilo_widgets::TreeView;
//! # use teksilo_widgets::primitives::{HStack, Padding, TextWidget};
//! # use teksilo_data::TreeModel;
//! # use teksilo_i18n::lit;
//! # struct Item { title: String }
//! # let tree_model: TreeModel<Item> = TreeModel::new();
//! let _w = TreeView::new(tree_model, |item, entry, _selected| {
//!     let indent = entry.depth as f32 * 20.0;
//!     Box::new(HStack::new()
//!         .child(Padding::new(0.0, 0.0, 0.0, indent))
//!         .child(TextWidget::new(lit!(&item.title))))
//! })
//! .item_height(28.0);
//! ```

use std::cell::{Cell, RefCell};
use std::rc::Rc;
use std::time::Duration;

use teksilo_canvas::{Point, Rect, Size, SizeProposal};
use teksilo_tokens::{BorderRole, InputTokens, OverscrollStyle, TargetRole};

use teksilo_core::DropFeedback;
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::binding::BindingLevel;
use teksilo_core::kinetic::KineticScroller;
use teksilo_core::pointer::touch_action::PanAxes;
use teksilo_core::signal::{Prop, Signal};
use teksilo_core::widget::{LayoutContext, Widget, WidgetPlacement};
use teksilo_core::widget_builder::HandlerSet;
use teksilo_core::widget_id::WidgetId;

use teksilo_data::selection_model::SelectionModel;
use teksilo_data::tree_slice::{TreeSlice, TreeSliceHandle};
use teksilo_data::{
    DropPosition, DropResponse, FlatEntry, ItemKey, KeyedSelectionModel, NodeId, TreeDataSource,
    TreeModel,
};

use crate::common::row_metrics::{HeightSource, RowMetrics, SharedRowMetrics};
use crate::common::row_reveal::{RevealAlign, RowReveal, SharedRowReveal};
use crate::common::scroll::OverscrollBehavior;
use crate::data_views::{DragTransferMode, RowDragData, RowSelection, ViewId, ViewKind};
use crate::scroll_area::ScrollBarMode;
use crate::scroll_bar::{ScrollBar, ScrollBarOrientation, ScrollBarVisual};
use crate::tree_source::{TreeRow, TreeRowMeta, TreeSource};

const BUFFER_ITEMS: usize = 5;
const DEFAULT_ITEM_HEIGHT: f32 = 28.0;

/// [`DEFAULT_ITEM_HEIGHT`] raised to the density's `target_size`
/// (24 / 32 / 44 dp). The identity at Compact.
fn default_item_height(tokens: &InputTokens) -> f32 {
    dp(DEFAULT_ITEM_HEIGHT, TargetRole::Target, tokens)
}
const SCROLLBAR_THICKNESS: f32 = 12.0;

/// Per-row context passed to a 4-arg TreeView delegate. Carries a
/// reference to the slice handle and the row's `NodeId` so the
/// delegate can wire chevron toggles and other tree-aware behavior
/// without manually cloning state outside the closure.
///
/// Created internally by [`TreeView::new_with_context`]. Not
/// constructed directly by user code.
pub struct TreeRowContext<'a, T: 'static> {
    slice: &'a TreeSliceHandle<T>,
    node_id: teksilo_data::NodeId,
}

impl<'a, T: 'static> TreeRowContext<'a, T> {
    /// Toggle callback for this row's chevron. Wires in one line:
    /// `.on_chevron_toggle_rc(ctx.toggle_callback())`.
    pub fn toggle_callback(&self) -> std::rc::Rc<dyn Fn(&mut teksilo_core::widget::EventContext)> {
        let slice = self.slice.clone();
        let node = self.node_id;
        std::rc::Rc::new(move |_ctx| slice.toggle_expand(node))
    }

    /// Cloned handle to the slice — call `.toggle_expand(node)`,
    /// `.expand(node)`, `.collapse(node)` directly.
    pub fn slice_handle(&self) -> TreeSliceHandle<T> {
        self.slice.clone()
    }

    /// The `NodeId` of this row in the backing `TreeModel`.
    pub fn node_id(&self) -> teksilo_data::NodeId {
        self.node_id
    }
}

/// Delegate type for the built-in `TreeModel` path: takes the inputs the 3-arg
/// form gets plus the optional `TreeRowContext`. Both the 3-arg `new` and the
/// 4-arg `new_with_context` produce a closure of this shape.
type TreeDelegate<T> = dyn Fn(&T, &FlatEntry, bool, &TreeRowContext<'_, T>) -> Box<dyn Widget>;

/// Delegate type for the generic [`TreeView::from_source`] path: key-erased, so
/// it receives a [`TreeRow`] (flat metadata + a chevron toggle) instead of the
/// `NodeId`-typed `FlatEntry` / `TreeRowContext`.
type SourceTreeDelegate<T> = dyn Fn(&T, &TreeRow, bool) -> Box<dyn Widget>;

/// Internal, uniform per-row builder both constructors lower to:
/// `(visible_index, &item, &meta, selected) -> row widget`. The built-in
/// wrapper rebuilds the `NodeId` `TreeRowContext` from the index; the generic
/// wrapper builds a key-erased `TreeRow`.
type RowDelegate<T> = dyn Fn(usize, &T, &TreeRowMeta, bool) -> Box<dyn Widget>;

/// A virtualized hierarchical tree widget backed by a `TreeModel<T>`.
///
/// ```rust
/// # use teksilo_widgets::{TreeView};
/// # use teksilo_widgets::primitives::{HStack, Padding, TextWidget};
/// # use teksilo_data::TreeModel;
/// # use teksilo_i18n::lit;
/// # struct Item { title: String }
/// # let tree_model: TreeModel<Item> = TreeModel::new();
/// let _w = TreeView::new(tree_model, |item, entry, _selected| {
///     let indent = entry.depth as f32 * 20.0;
///     Box::new(HStack::new()
///         .child(Padding::new(0.0, 0.0, 0.0, indent))
///         .child(TextWidget::new(lit!(&item.title))))
/// })
/// .item_height(28.0);
/// ```
use crate::data_views::DropViz;
use teksilo_core::styles::density::dp;

pub struct TreeView<T: 'static> {
    /// Index-keyed erased backing — the built-in `TreeSlice` or an external
    /// `TreeDataSource`. All virtualization / DnD / keyboard work goes through
    /// this in flat indices.
    source: Rc<TreeSource<T>>,
    /// Present only for the built-in `TreeModel` path; backs the `NodeId`-typed
    /// public expand API + [`tree_slice`](Self::tree_slice). `None` for
    /// [`from_source`](Self::from_source).
    slice: Option<Rc<TreeSlice<T>>>,
    /// Uniform per-row builder produced by whichever constructor was used.
    row_delegate: Rc<RowDelegate<T>>,
    item_height: f32,
    /// Height-mode selection (uniform / exact callback / auto-measure).
    height_source: HeightSource,
    /// Row geometry — all virtualization consumers go through this.
    metrics: SharedRowMetrics,
    /// Row selection — index-based `SelectionModel` or keyed
    /// `KeyedSelectionModel<NodeId>`, unified behind the index-facing facade.
    row_selection: Option<RowSelection>,

    /// The keyboard cursor, a flat visible index: the row the arrow keys
    /// step from and the view names as its active descendant. A signal,
    /// bound `AccessibilityOnly` by the root, so a write from anywhere (the
    /// keys, a click, a [`TreeViewHandle`]) re-walks the AT tree; shared with
    /// every handle.
    focused_index: Signal<Option<usize>>,
    /// The row identity `focused_index` currently points at, refreshed
    /// alongside every write to `focused_index`. A tree's structural changes
    /// (insert/remove/reorder, and — unlike a flat list — expand/collapse)
    /// surface as a bare version bump with no `DataChange` delta to shift the
    /// cursor by, so it is reconciled by identity instead: resolved against
    /// the source on every version bump and used to rewrite `focused_index`
    /// to wherever the row landed (or drop it if the row is gone). See
    /// `crate::data_views::RowAnchor` and `reconcile_editing_row`, which
    /// plays the same role for `TableView`'s `editing_cell`.
    focused_anchor: Rc<RefCell<Option<crate::data_views::RowAnchor>>>,
    /// The realized `(flat index -> row wrapper id)` map, filled by the body
    /// pane each build. Lets this widget's `&self` methods resolve a row index
    /// to a widget without reaching into the pane. Mirrors `ListView::row_map`.
    row_map: Rc<RefCell<Vec<(usize, WidgetId)>>>,

    /// Type-ahead ("type to jump") label extractor — opt-in via
    /// [`type_ahead_label`](Self::type_ahead_label).
    /// Per-row tooltip resolvers. The view attaches these itself, against the
    /// row widget the delegate produced — an app cannot reach that widget to
    /// hang a `.tooltip(...)` on it. Shared with `ListView`; see
    /// [`RowTooltips`](crate::data_views::RowTooltips).
    row_tooltips: crate::data_views::RowTooltips<T>,
    type_ahead_label: Option<Rc<dyn Fn(&T) -> String>>,
    /// Reset window for the type-ahead search term.
    type_ahead_timeout: Duration,
    /// Persistent type-ahead buffer (survives the per-keystroke rebuild).
    type_ahead: Rc<crate::common::type_ahead::TypeAheadState>,

    /// Enable intra-widget drag reordering.
    reorderable: bool,

    /// 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>,

    /// Whether a row-body PointerUp on a branch row auto-toggles its
    /// expansion. Defaults to `true` (legacy behavior — convenient
    /// for hand-built delegates without an explicit chevron). Set to
    /// `false` when the delegate provides its own chevron tap target
    /// (e.g. `StandardTreeItem`) to avoid the auto-toggle firing in
    /// addition to the chevron's own click and cancelling out.
    row_click_expands: bool,

    /// Active drop feedback (set by on_drag_hover, cleared by on_drag_leave,
    /// read by paint). Reactive Signal — bound at `RepaintOnly` so any
    /// `set(...)` call dirties the TreeView for repaint automatically.
    drop_feedback: Signal<Option<DropViz>>, // insertion line OR folder highlight

    /// Optional row-activation callback (a click on the row body per
    /// `activate_on`, or Enter/Space on the focused row) — distinct from
    /// *selection*, which also moves on arrow navigation. Lets a view
    /// open/commit a row without firing on every navigation step.
    on_activate: Option<Rc<dyn Fn(usize, &mut teksilo_core::widget::EventContext)>>,
    /// Whether activation is a single or double click (default `DoubleClick`).
    activate_on: crate::data_views::ActivateOn,

    /// `true` while this view (root or descendant) holds keyboard focus — the
    /// root's inclusive [`BuildContext::view_focus_active`](teksilo_core::BuildContext::view_focus_active) signal, bound
    /// `RepaintOnly`. With [`focus_visible`](Self::focus_visible) it drives the
    /// **container focus ring**: when the view is Tab-focused but nothing is
    /// selected, no row ring shows, so the whole view outlines itself instead —
    /// the user can see where keyboard focus landed before they arrow.
    view_focused: Signal<bool>,
    /// Input-modality `:focus-visible`. Gates the container ring (and row rings)
    /// to keyboard navigation, never a mouse click. Bound `RepaintOnly`.
    focus_visible: Signal<bool>,

    // Persistent scroll state
    scroll_y: Signal<f32>,
    max_scroll_y: Signal<f32>,
    /// Scroll-chaining behavior at the boundary (default `Chain`).
    overscroll_behavior: OverscrollBehavior,
    viewport_ratio_y: Signal<f32>,

    /// Animate wheel scrolling instead of snapping to the new offset.
    /// Enabled by default — mirrors `ScrollArea`. Without it, each wheel
    /// notch jumps by `item_height` per delivered line (typically 3),
    /// which reads as a coarse multi-row jump rather than a smooth glide.
    smooth_scrolling: bool,
    /// Duration of the smooth scroll animation.
    smooth_scroll_duration: Duration,

    /// How the scroll bar is displayed. Defaults to `Permanent` — a
    /// layout sibling that reserves its own width. `Overlay` / `Thin`
    /// float over the content instead, like `ScrollArea`.
    scroll_bar_style: ScrollBarMode,

    /// Root-level **relayout** trigger. The root's `place_children` owns the
    /// scrollbar totals (`max_scroll_y`, thumb ratio) and the content-width
    /// decision, none of which its `build` output depends on — so a source
    /// change, or a pane measurement that moves the content total, needs a
    /// re-place here rather than a rebuild. Bumped by the source-version
    /// observer and by [`body_pane::TreeViewBodyPane::total_refresh`].
    layout_refresh: Signal<u64>,
    /// Root-level **repaint** trigger for the container focus ring, which is
    /// suppressed as soon as anything is selected. Selection changes rebuild
    /// the pane (the delegate's `selected` argument) but must not rebuild the
    /// root — they only change what the root paints.
    paint_refresh: Signal<u64>,

    /// Pane-local rebuild trigger, owned here so it survives pane rebuilds.
    pane_version: Signal<u64>,
    /// Buffered row range materialized by the pane's latest build.
    pane_built_start: Rc<Cell<usize>>,
    pane_built_end: Rc<Cell<usize>>,

    // Set during build
    body_pane_id: Option<WidgetId>,
    scrollbar_id: Option<WidgetId>,
    viewport_height: Rc<Cell<f32>>,
    /// The TreeView's own absolute (window) bounds, cached from
    /// `place_children` so the keyboard handler can chase the selected row
    /// into enclosing scroll areas via
    /// [`EventContext::ensure_visible`](teksilo_core::widget::EventContext::ensure_visible).
    /// Rows are not distinct focusable nodes, so the focus-driven follow never
    /// reveals the selected row in an outer scroller — this closes that gap.
    viewport_bounds: Rc<Cell<Rect>>,
    /// 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>>,
    /// Content width (updated during `place_children`, used by drag
    /// feedback so the insertion line / into-folder highlight spans the
    /// row's actual width instead of a guess). Mirrors `ListView`.
    placed_content_width: Rc<Cell<f32>>,
    tree_id: ViewId,

    /// 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>,
    /// The reveal a [`TreeViewHandle`] asked for, applied by the body pane
    /// after its measure pass. Created with the view so a handle taken before
    /// mount reaches every pane the view builds.
    reveal: SharedRowReveal,
}

mod body_pane;
mod builder;
mod widget_impl;

// std::fmt::Debug for the (non-Debug) generic fields.
impl<T: 'static> std::fmt::Debug for TreeView<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("TreeView")
            .field("visible_count", &self.source.visible_count())
            .field("item_height", &self.item_height)
            .field("scroll_bar_style", &self.scroll_bar_style)
            .field("scroll_y", &self.scroll_y.get())
            .finish()
    }
}

impl<T: 'static> TreeView<T> {
    /// A handle that scrolls this tree once it is mounted.
    ///
    /// Take it while describing the tree, before the view is handed to
    /// `ctx.add(...)`; it stays attached to the view across rebuilds. See
    /// [`TreeViewHandle`].
    pub fn handle(&self) -> TreeViewHandle {
        let count = self.source.clone();
        let anchor = self.source.clone();
        TreeViewHandle {
            reveal: self.reveal.clone(),
            cursor: self.focused_index.clone(),
            cursor_anchor: self.focused_anchor.clone(),
            len: Rc::new(move || count.visible_count()),
            anchor_at: Rc::new(move |index| anchor.anchor(index)),
        }
    }
}

/// A handle on a mounted [`TreeView`], to scroll it to a row from outside the
/// widget — a view-model revealing the node a search found, say.
///
/// Rows are addressed by their **flat visible index**: the position of the row
/// among the rows currently shown, counting the children of expanded nodes and
/// skipping those of collapsed ones (the index the delegate's selection and the
/// keyboard use).
///
/// Cheap to clone, valid before the view is mounted, and it survives the
/// view's rebuilds. Its methods never compute an offset when they are called:
/// they record the request and ask for a layout pass, and the view applies it
/// there, after row measurement and scroll anchoring have settled. So a
/// structural change made in the same turn (a node expanded above the target,
/// say) is accounted for, a request made before mount is applied at the first
/// layout, and a later request replaces an earlier pending one. A request on
/// an empty tree is dropped; an index past the end reveals the last row.
///
/// The handle also reads and moves the tree's **keyboard cursor**, the row the
/// arrow keys step from and assistive technology is told is current:
/// [`cursor`](Self::cursor), [`set_cursor`](Self::set_cursor) and
/// [`cursor_signal`](Self::cursor_signal), in the same flat visible indices.
/// In a multiple selection the cursor and the selection are separate: the
/// accelerator with an arrow moves the cursor alone, and a selection written
/// from outside leaves the cursor where it was.
///
/// ```rust
/// # use teksilo_widgets::TreeView;
/// # use teksilo_widgets::primitives::TextWidget;
/// # use teksilo_data::TreeModel;
/// # use teksilo_i18n::lit;
/// # let model: TreeModel<String> = TreeModel::new();
/// let tree = TreeView::new(model, |item, _entry, _selected| {
///     Box::new(TextWidget::new(lit!(item)))
/// });
/// let handle = tree.handle();
/// // … `ctx.add(tree)`; later, after expanding the node's ancestors:
/// handle.ensure_index_visible(42);
/// ```
#[derive(Clone)]
pub struct TreeViewHandle {
    reveal: SharedRowReveal,
    /// The tree's `focused_index`, the same signal the keyboard writes.
    cursor: Signal<Option<usize>>,
    /// The tree's `focused_anchor`: the row identity the cursor follows
    /// through a structural change, written with every write of the cursor.
    cursor_anchor: Rc<RefCell<Option<crate::data_views::RowAnchor>>>,
    /// The tree's visible row count, to clamp a cursor written from here.
    len: Rc<dyn Fn() -> usize>,
    /// The identity of the row at a flat index, for `cursor_anchor`.
    anchor_at: Rc<dyn Fn(usize) -> crate::data_views::RowAnchor>,
}

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

impl TreeViewHandle {
    /// Scroll so the row at the given flat visible index is aligned to the
    /// top of the viewport, as far as the scroll range allows, at the next
    /// layout pass.
    pub fn scroll_to_index(&self, index: usize) {
        self.reveal.request(index, RevealAlign::Top);
    }

    /// Scroll the minimum distance that brings the row at the given flat
    /// visible index fully into view, at the next layout pass; no scroll
    /// when it already is.
    pub fn ensure_index_visible(&self, index: usize) {
        self.reveal.request(index, RevealAlign::Nearest);
    }

    /// The flat visible index the keyboard cursor is on, or `None` while the
    /// tree has no cursor: it has not been navigated, clicked or given one by
    /// [`set_cursor`](Self::set_cursor). With no cursor the keys start from
    /// the first selected row, and from the first or last row when nothing is
    /// selected.
    ///
    /// The cursor follows its row: an expansion or a collapse above it, or an
    /// insertion, moves the index with the row, and a row that leaves the
    /// visible rows takes the cursor with it. In a single selection
    /// the cursor follows the selection: the keys move them together, and a
    /// selection written from outside moves the cursor onto it. In a multiple
    /// selection they are separate: the accelerator with an arrow
    /// (`Ctrl+Arrow`) moves the cursor alone, and a selection written from
    /// outside leaves the cursor where it was.
    pub fn cursor(&self) -> Option<usize> {
        self.cursor.get()
    }

    /// Move the keyboard cursor to the row at flat visible index `index`, or
    /// remove it with `None`.
    ///
    /// An index past the last visible row is clamped to that row; on an empty
    /// tree the cursor is removed. While the tree holds keyboard focus it
    /// names the row as its active descendant at the next accessibility
    /// update, when the row is realized; the next arrow key steps from it,
    /// and the cursor follows that row through later structural changes.
    ///
    /// Keyboard focus and the selection are left alone, and the tree does not
    /// scroll: pair it with
    /// [`ensure_index_visible`](Self::ensure_index_visible) to bring the row
    /// into view. Usable before the tree is mounted and across its rebuilds;
    /// in a single selection the tree seats the cursor on the selected row
    /// when it is built and whenever the selection changes.
    pub fn set_cursor(&self, index: Option<usize>) {
        let len = (self.len)();
        let index = index.and_then(|i| len.checked_sub(1).map(|last| i.min(last)));
        // The anchor first: an observer of the cursor reads a consistent pair.
        *self.cursor_anchor.borrow_mut() = index.map(|i| (self.anchor_at)(i));
        self.cursor.set(index);
    }

    /// A read-only signal of the cursor, as [`cursor`](Self::cursor) reports
    /// it, for an application to observe or bind: a status line naming the
    /// current row, actions enabled for it. It changes with every write of
    /// the cursor, by the keys, a click, a structural change moving it or
    /// [`set_cursor`](Self::set_cursor).
    pub fn cursor_signal(&self) -> Signal<Option<usize>> {
        self.cursor.map(|index| *index)
    }
}

#[cfg(test)]
mod tests;

#[cfg(test)]
mod handle_tests;

#[cfg(test)]
mod cursor_tests;