teksilo_widgets/

data_views.rs

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

//! Shared substrate for the data views' source-owned drag-and-drop + lazy
//! loading.
//!
//! Centralizes the vocabulary the four data views (`ListView` / `TreeView` /
//! `TableView` / `TreeTableView`) share, so DnD validation (`can_accept`) and
//! the lazy placeholder are wired one way everywhere:
//!
//! - [`RowDragData`] — the **public, generic** intra-app drag payload a row (or
//!   a whole selected set) emits. The receiving source distinguishes its OWN
//!   reorder (matching [`ViewId`]) from a foreign drop, and translates the
//!   origin's `rows` → its own key via `key_at`, so the source's `Key` type
//!   never leaks into the view. When the origin opted into export it also
//!   carries `items` (clones of the dragged `T`), so a foreign `DropTarget`,
//!   a different data view, or the OS can consume the drag.
//! - [`DropIndicator`] — what `paint` renders; `allowed == false` is the
//!   pre-commit forbidden affordance.
//! - [`flat_insertion_target`] — maps a flat insertion index to the
//!   `(target, position)` pair `can_accept` / `accept_drop` expect.
//! - [`default_placeholder`] — the skeleton for a `Loading` row.

use std::cell::{Cell, RefCell};
use std::rc::Rc;
use std::sync::atomic::{AtomicUsize, Ordering};

use teksilo_core::ObserverHandle;
use teksilo_core::build_context::BuildContext;
use teksilo_core::drag_payload::{DragPayload, DropOutcome};
use teksilo_core::widget::{EventContext, Widget};
use teksilo_core::widget_builder::HandlerSet;
use teksilo_core::widget_id::WidgetId;
use teksilo_data::{
    DataChange, DropPosition, ItemKey, KeyedSelectionModel, SelectionMode, SelectionModel,
};

/// How a data-view row/tile is *activated* (opened/committed) by pointer —
/// distinct from *selection*, which also moves on arrow-key navigation. Mirrors
/// the platform split other toolkits expose (Qt
/// `SH_ItemView_ActivateItemOnSingleClick`, GTK `activate-on-single-click`).
/// Enter/Space always activates regardless of this mode.
///
/// Pass to `ListView::activate_on`, `TreeView::activate_on`, etc.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum ActivateOn {
    /// One primary click activates the row (KDE / web / Scrivener convention).
    /// Selection and activation happen on the same click.
    SingleClick,
    /// A double primary click activates the row; the first click only selects
    /// it (Finder / Explorer / Qt and GTK default). This is the [`Default`].
    #[default]
    DoubleClick,
}

/// Which kind of data view minted a [`ViewId`]. Folded into the id so two
/// different widget kinds that happen to draw the same value from the shared
/// process counter can never be mistaken for one another — the reason a bare
/// `usize` id was a latent cross-widget hazard.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub(crate) enum ViewKind {
    List,
    Tree,
    Table,
    TreeTable,
    Grid,
}

/// Opaque, kind-tagged, process-unique identity of a drag-capable data-view
/// instance. Used to tell a view's OWN reorder (`SameView`) from a foreign drop
/// on the receive side. Apps only ever compare two `ViewId`s for equality (e.g.
/// out of a received [`RowDragData`]); there is no public constructor, and the
/// value is stable for a view instance's lifetime, so it is safe to compare
/// even across windows (each mint is globally unique).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ViewId(ViewKind, usize);

impl ViewId {
    /// Mint a fresh, globally-unique id for a view of the given kind.
    pub(crate) fn next(kind: ViewKind) -> Self {
        Self(kind, next_view_id())
    }
}

/// What the *origin* view does to its own rows once a drag is accepted by a
/// **foreign** target (a different `DropTarget` / view / the OS). Purely an
/// origin-side cleanup choice — the receiver is unaffected. A same-view reorder
/// is never a transfer, so this never applies to it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum DragTransferMode {
    /// Leave the origin rows in place (the dragged data is duplicated).
    Copy,
    /// Remove the dragged rows from the origin once accepted elsewhere
    /// (or exported as an OS move). This is the [`Default`].
    #[default]
    Move,
}

/// The public, generic drag payload every data-view row (or selected set)
/// emits. It occupies the single typed slot of a
/// [`teksilo_core::drag_payload::DragPayload`] and serves both audiences:
///
/// - the origin view's own erased classifier reads [`source`](Self::source) +
///   [`rows`](Self::rows) to recognise a same-view reorder;
/// - a **foreign** consumer (another view's custom `ListDataSource`, a
///   `DropTarget::accept_typed::<RowDragData<T>>()`, or `on_rows_received`)
///   reads [`items`](Self::items).
///
/// `items` is `Some` only when the origin view opted into export via
/// `.exportable(..)` (which requires `T: Clone`); a plain `.reorderable(true)`
/// drag carries `items == None` (nothing outside the origin could use it
/// anyway), so a reorder-only view is never accidentally droppable elsewhere.
#[derive(Debug)]
pub struct RowDragData<T: 'static> {
    /// Identity of the view that started the drag.
    pub source: ViewId,
    /// The dragged rows as the origin view's flat visible indices at
    /// drag-start, ascending. Informational (row count, app callbacks): the
    /// origin's accept path resolves the dragged rows' **stable keys** at
    /// drag-start and never re-reads these indices at hover/drop time — they
    /// go stale the moment the source reflows mid-drag (a spring-load
    /// auto-expand, a peer write). A foreign consumer should read
    /// [`items`](Self::items) instead.
    pub rows: Vec<usize>,
    /// Clones of the dragged items, `rows`-ordered. `None` for a reorder-only
    /// (non-exportable) drag.
    pub items: Option<Vec<T>>,
}

impl<T: 'static> RowDragData<T> {
    /// The dragged items, if this is an export drag (`.exportable(..)` was set
    /// on the origin). `None` for a reorder-only drag.
    pub fn items(&self) -> Option<&[T]> {
        self.items.as_deref()
    }

    /// Consume the payload for its items (avoids cloning on the receive side).
    pub fn into_items(self) -> Option<Vec<T>> {
        self.items
    }

    /// Whether this drag carries exportable items — i.e. the origin opted into
    /// `.exportable(..)`. A foreign receiver should gate on this (a reorder-only
    /// payload has the same Rust type but carries nothing usable).
    pub fn is_export(&self) -> bool {
        self.items.is_some()
    }

    /// Number of dragged rows.
    pub fn len(&self) -> usize {
        self.rows.len()
    }

    /// Whether no rows are carried (never true for a real drag).
    pub fn is_empty(&self) -> bool {
        self.rows.is_empty()
    }
}

/// A drop indicator the data views' `paint` renders. `allowed == false` paints a
/// muted line where an accepted-drop line would be — the pre-commit "you can't
/// drop here" affordance.
#[derive(Debug, Clone, Copy, PartialEq)]
pub(crate) struct DropIndicator {
    pub(crate) y: f32,
    pub(crate) width: f32,
    pub(crate) allowed: bool,
}

/// A process-unique id distinguishing data-view instances (for SameView drop
/// detection when several views share one source).
pub(crate) fn next_view_id() -> usize {
    static NEXT: AtomicUsize = AtomicUsize::new(1);
    NEXT.fetch_add(1, Ordering::Relaxed)
}

/// Map a flat insertion index (`0..=len`) to the `(target_index, position)` pair
/// a `ListDataSource::can_accept` / `accept_drop` understands. `None` for an
/// empty list. Insertion *before* row `i` is `(i, Before)`; insertion past the
/// end is `(len-1, After)`.
pub(crate) fn flat_insertion_target(insertion: usize, len: usize) -> Option<(usize, DropPosition)> {
    if len == 0 {
        None
    } else if insertion >= len {
        Some((len - 1, DropPosition::After))
    } else {
        Some((insertion, DropPosition::Before))
    }
}

/// The default skeleton for a `Loading` row — a muted inset bar. The row's
/// placement sizes it to the row's height and width.
/// One row's tooltip, already resolved from its item and awaiting a
/// `BuildContext` to attach it with.
pub(crate) enum ResolvedRowTooltip {
    Plain(teksilo_i18n::LocalizedString),
    Rich(crate::tooltip::RichTooltipSource),
    Composite(Box<dyn Widget>),
}

/// Per-row tooltip resolvers, shared by every data view that builds rows from
/// a delegate.
///
/// A data view's rows are not authored by the app as widgets it can hang a
/// `.tooltip(...)` on — they come out of a delegate, and the view owns the
/// resulting `WidgetId`. So the view takes the *resolvers* instead and does the
/// attaching itself, against the row it just built. Same shape as
/// [`TabDelegate`](crate::tab_widget::TabDelegate)'s per-tab tooltip callbacks,
/// and the same last-setter-wins matrix as the per-widget setters: each `set_*`
/// clears the other two, so a row can never mature two tips at once.
///
/// Placement is [`Side`](crate::tooltip::TooltipPlacement::Side) for every
/// view here — rows stack vertically, and a `Below` tip would cover the next
/// row, which is the one the user is most likely reading next.
///
/// Cost: the body is resolved and built for each **realized** row, i.e. the
/// virtualization window (visible + buffer), not the whole model — and again
/// whenever those rows rebuild. Keep resolvers cheap; defer anything expensive
/// (a backend read, a subtree walk) to the body's own first paint, which only
/// happens if the tip is actually shown.
pub(crate) struct RowTooltips<T: 'static> {
    plain: Option<Rc<dyn Fn(usize, &T) -> Option<teksilo_i18n::LocalizedString>>>,
    rich: Option<Rc<dyn Fn(usize, &T) -> Option<crate::tooltip::RichTooltipSource>>>,
    composite: Option<Rc<dyn Fn(usize, &T) -> Option<Box<dyn Widget>>>>,
    /// Whether a composite row tip offers dwell-to-sticky promotion.
    composite_sticky: bool,
}

impl<T: 'static> Default for RowTooltips<T> {
    fn default() -> Self {
        Self {
            plain: None,
            rich: None,
            composite: None,
            composite_sticky: true,
        }
    }
}

impl<T: 'static> Clone for RowTooltips<T> {
    fn clone(&self) -> Self {
        Self {
            plain: self.plain.clone(),
            rich: self.rich.clone(),
            composite: self.composite.clone(),
            composite_sticky: self.composite_sticky,
        }
    }
}

impl<T: 'static> std::fmt::Debug for RowTooltips<T> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RowTooltips")
            .field("plain", &self.plain.is_some())
            .field("rich", &self.rich.is_some())
            .field("composite", &self.composite.is_some())
            .finish()
    }
}

impl<T: 'static> RowTooltips<T> {
    /// Whether any resolver is set — lets a view skip the per-row work.
    pub(crate) fn is_set(&self) -> bool {
        self.plain.is_some() || self.rich.is_some() || self.composite.is_some()
    }

    pub(crate) fn set_plain(
        &mut self,
        f: impl Fn(usize, &T) -> Option<teksilo_i18n::LocalizedString> + 'static,
    ) {
        *self = Self {
            plain: Some(Rc::new(f)),
            rich: None,
            composite: None,
            composite_sticky: self.composite_sticky,
        };
    }

    pub(crate) fn set_rich(
        &mut self,
        f: impl Fn(usize, &T) -> Option<crate::tooltip::RichTooltipSource> + 'static,
    ) {
        *self = Self {
            plain: None,
            rich: Some(Rc::new(f)),
            composite: None,
            composite_sticky: self.composite_sticky,
        };
    }

    pub(crate) fn set_composite(
        &mut self,
        f: impl Fn(usize, &T) -> Option<Box<dyn Widget>> + 'static,
    ) {
        *self = Self {
            plain: None,
            rich: None,
            composite: Some(Rc::new(f)),
            composite_sticky: self.composite_sticky,
        };
    }

    /// Whether a composite row tip offers dwell promotion. Off suits a
    /// read-only card: nothing to reach into, so nothing to pin.
    pub(crate) fn set_composite_sticky(&mut self, on: bool) {
        self.composite_sticky = on;
    }

    /// Resolve this row's tooltip, if any.
    ///
    /// Split from [`attach_resolved`](Self::attach_resolved) because a view can
    /// only reach the item from inside the same borrow that builds the row
    /// widget, while attaching needs the `BuildContext` and the resulting
    /// `WidgetId` — which only exist after that borrow ends.
    pub(crate) fn resolve(&self, index: usize, item: &T) -> Option<ResolvedRowTooltip> {
        if let Some(f) = &self.composite {
            f(index, item).map(ResolvedRowTooltip::Composite)
        } else if let Some(f) = &self.rich {
            f(index, item).map(ResolvedRowTooltip::Rich)
        } else if let Some(f) = &self.plain {
            f(index, item).map(ResolvedRowTooltip::Plain)
        } else {
            None
        }
    }

    /// Attach a resolved tooltip to the row widget the view just built.
    pub(crate) fn attach_resolved(
        &self,
        ctx: &mut teksilo_core::build_context::BuildContext,
        row_id: teksilo_core::widget_id::WidgetId,
        resolved: ResolvedRowTooltip,
    ) {
        // Rows stack vertically, so a `Below` tip would cover the next row —
        // the one the user is most likely reading next.
        let placement = crate::tooltip::TooltipPlacement::Side;
        match resolved {
            ResolvedRowTooltip::Composite(body) => {
                let delay = ctx.theme().motion.tooltip_delay_heavy;
                crate::tooltip::attach_composite_tooltip_widget_with_placement(
                    ctx,
                    row_id,
                    crate::tooltip::CompositeTooltipWidget::new()
                        .content_boxed(body)
                        .sticky(self.composite_sticky),
                    delay,
                    placement,
                );
            }
            ResolvedRowTooltip::Rich(source) => {
                let delay = ctx.theme().motion.tooltip_delay;
                crate::tooltip::attach_rich_tooltip_source_with_placement(
                    ctx, row_id, source, delay, placement,
                );
            }
            ResolvedRowTooltip::Plain(text) => {
                let delay = ctx.theme().motion.tooltip_delay;
                crate::tooltip::attach_plain_tooltip_with_placement(
                    ctx, row_id, text, delay, placement,
                );
            }
        }
    }
}

pub(crate) fn default_placeholder() -> Box<dyn Widget> {
    use crate::primitives::{Padding, RectWidget};
    Box::new(
        Padding::uniform(6.0).child(
            RectWidget::new()
                .background(teksilo_tokens::SurfaceRole::Hover)
                .corner_radius(teksilo_tokens::CornerRadius::uniform(4.0)),
        ),
    )
}

/// Index-facing row-selection facade backing the four data views.
///
/// An app installs *either* the index-based [`SelectionModel`] (positions) or a
/// [`KeyedSelectionModel<K>`] (stable identities that survive reorder / filter /
/// window-slide / multi-view). The views' click / keyboard / rebuild / paint
/// paths all work in **indices**, so this facade erases the difference: the
/// keyed variant carries the view's index↔key mapping (`key_at` / `len` /
/// `contains_key`) and translates internally. The method surface deliberately
/// mirrors `SelectionModel` so call sites read identically (`rs.select(i)`,
/// `rs.is_selected(i)`, …).
#[derive(Clone)]
pub(crate) struct RowSelection {
    mode: SelectionMode,
    is_selected: Rc<dyn Fn(usize) -> bool>,
    select_fn: Rc<dyn Fn(usize)>,
    toggle_fn: Rc<dyn Fn(usize)>,
    extend_fn: Rc<dyn Fn(usize)>,
    /// Ctrl+Shift range extension: keeps whatever the previous gesture
    /// selected instead of replacing it, so a second disjoint range can be
    /// built without losing the first.
    extend_additive_fn: Rc<dyn Fn(usize)>,
    select_all_fn: Rc<dyn Fn(usize)>,
    selected_indices_fn: Rc<dyn Fn() -> Vec<usize>>,
    /// Cheap (O(selected count), never O(visible)) emptiness check for the
    /// container-focus-ring gate — paint runs every frame and only needs to
    /// know "is anything selected", not the set itself.
    has_selection_fn: Rc<dyn Fn() -> bool>,
    clear_fn: Rc<dyn Fn()>,
    observe_fn: Rc<dyn Fn(Box<dyn Fn()>) -> ObserverHandle>,
    on_change_fn: Rc<dyn Fn(&DataChange)>,
    /// Unconditional prune for the version-signal-driven tree views (which
    /// don't emit a `DataChange`): drop orphaned keys (keyed) or no-op (index).
    prune_fn: Rc<dyn Fn()>,
    /// Drop selected indices that no longer fit `0..count`, for the
    /// version-signal-driven tree views' index-selection path: an index has
    /// no identity to follow a moved row by (that's `focused_index`'s job,
    /// via `RowAnchor`), so a structural change can only clamp it — never
    /// re-land it on the row it used to point at. A no-op for the keyed
    /// model, which is already fully reconciled by `prune_fn`.
    prune_range_fn: Rc<dyn Fn(usize)>,
}

impl RowSelection {
    /// Back the facade with the index-based [`SelectionModel`]. Index ops pass
    /// straight through; `on_data_change` index-shifts (insert / remove) or
    /// clears (reset) the selection, matching the legacy inline behaviour.
    pub(crate) fn from_index(sel: SelectionModel) -> Self {
        let (s_is, s_sel, s_tog, s_ext, s_all, s_idx, s_has, s_clr, s_obs, s_chg, s_range) = (
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
            sel.clone(),
        );
        Self {
            mode: sel.mode(),
            is_selected: Rc::new(move |i| s_is.is_selected(i)),
            select_fn: Rc::new(move |i| s_sel.select(i)),
            toggle_fn: Rc::new(move |i| s_tog.toggle(i)),
            extend_fn: Rc::new(move |i| s_ext.extend_to(i)),
            extend_additive_fn: {
                let s = sel.clone();
                Rc::new(move |i| s.extend_to_additive(i))
            },
            select_all_fn: Rc::new(move |count| s_all.select_all(count)),
            selected_indices_fn: Rc::new(move || s_idx.selected_indices()),
            has_selection_fn: Rc::new(move || s_has.count() > 0),
            clear_fn: Rc::new(move || s_clr.clear()),
            observe_fn: Rc::new(move |cb| s_obs.selection_signal().observe(move |_| cb())),
            on_change_fn: Rc::new(move |change| match change {
                DataChange::ItemsInserted { range } => {
                    s_chg.adjust_for_insert(range.start, range.end - range.start);
                }
                DataChange::ItemsRemoved { range } => {
                    s_chg.adjust_for_remove(range.start, range.end - range.start);
                }
                DataChange::ItemsMoved { from, to, count } => {
                    s_chg.adjust_for_move(*from, *to, *count);
                }
                DataChange::Reset => s_chg.clear(),
                _ => {}
            }),
            // The index model has no stable identity to prune against on a
            // bare version bump — tree structural adjustments stay no-ops here
            // (the legacy behaviour).
            prune_fn: Rc::new(|| {}),
            prune_range_fn: Rc::new(move |count| {
                let kept: Vec<usize> = s_range
                    .selected_indices()
                    .into_iter()
                    .filter(|&i| i < count)
                    .collect();
                if kept.len() != s_range.count() {
                    s_range.select_indices(kept, false);
                }
            }),
        }
    }

    /// Back the facade with a [`KeyedSelectionModel<K>`] plus the view's
    /// index↔key mapping. `key_at(i)` is the key at visible index `i`, `len()`
    /// the visible count (for Shift-range ordering and `selected_indices`), and
    /// `contains_key(&k)` whether the *source* still holds the key (for
    /// prune-on-remove — a collapsed-but-present tree node must NOT be pruned,
    /// so this is supplied by the view, not derived from the visible window).
    pub(crate) fn from_keyed<K: ItemKey>(
        keyed: KeyedSelectionModel<K>,
        key_at: Rc<dyn Fn(usize) -> Option<K>>,
        len: Rc<dyn Fn() -> usize>,
        contains_key: Rc<dyn Fn(&K) -> bool>,
    ) -> Self {
        let mode = keyed.mode();
        Self {
            mode,
            is_selected: {
                let (k, ka) = (keyed.clone(), key_at.clone());
                Rc::new(move |i| ka(i).map(|key| k.is_selected(&key)).unwrap_or(false))
            },
            select_fn: {
                let (k, ka) = (keyed.clone(), key_at.clone());
                Rc::new(move |i| {
                    if let Some(key) = ka(i) {
                        k.select(key);
                    }
                })
            },
            toggle_fn: {
                let (k, ka) = (keyed.clone(), key_at.clone());
                Rc::new(move |i| {
                    if let Some(key) = ka(i) {
                        k.toggle(key);
                    }
                })
            },
            extend_fn: {
                // O(visible count) per Shift-click / Shift-arrow gesture:
                // builds the full visible key order every call rather than
                // just the `[anchor_index..=target_index]` span
                // `KeyedSelectionModel::extend_to` actually inserts.
                //
                // Narrowing this to the sub-range was considered and
                // rejected as not cleanly possible without touching
                // `teksilo-data`: `extend_to`'s "anchor scrolled out of
                // view / evicted" fallback (single-select `target`) is
                // detected by NOT finding `anchor` in the `ordered_keys`
                // slice it's given, and the anchor is a private field with
                // no public accessor (`KeyedSelectionModel::anchor` isn't
                // exposed, and there's no `index_of_key` on the view's
                // key↔index mapping this facade carries either). Without
                // that, this closure has no way to know the anchor's
                // current index — or whether it still HAS one — to bound a
                // sub-range with, and a shadow copy of the anchor tracked
                // here would drift from `KeyedSelectionModel`'s own
                // whenever something else drives `select`/`toggle`
                // (clearing or moving the anchor) — a duplicated-state
                // correctness risk for a micro-optimization on a
                // human-triggered, once-per-gesture path (not a hot loop).
                let (k, ka, l) = (keyed.clone(), key_at.clone(), len.clone());
                Rc::new(move |i| {
                    if let Some(target) = ka(i) {
                        let ordered: Vec<K> = (0..l()).filter_map(|j| ka(j)).collect();
                        k.extend_to(target, &ordered);
                    }
                })
            },
            extend_additive_fn: {
                // Same visible-order rebuild as `extend_fn` above, and the same
                // reasoning for why it is not narrowed to the anchor's span.
                let (k, ka, l) = (keyed.clone(), key_at.clone(), len.clone());
                Rc::new(move |i| {
                    if let Some(target) = ka(i) {
                        let ordered: Vec<K> = (0..l()).filter_map(|j| ka(j)).collect();
                        k.extend_to_additive(target, &ordered);
                    }
                })
            },
            select_all_fn: {
                let (k, ka) = (keyed.clone(), key_at.clone());
                Rc::new(move |count| {
                    let keys: Vec<K> = (0..count).filter_map(|i| ka(i)).collect();
                    k.select_keys(keys, false);
                })
            },
            selected_indices_fn: {
                let (k, ka, l) = (keyed.clone(), key_at.clone(), len.clone());
                Rc::new(move || {
                    (0..l())
                        .filter(|&i| ka(i).map(|key| k.is_selected(&key)).unwrap_or(false))
                        .collect()
                })
            },
            has_selection_fn: {
                let k = keyed.clone();
                Rc::new(move || k.count() > 0)
            },
            clear_fn: {
                let k = keyed.clone();
                Rc::new(move || k.clear())
            },
            observe_fn: {
                let k = keyed.clone();
                Rc::new(move |cb| k.selection_signal().observe(move |_| cb()))
            },
            on_change_fn: {
                let (k, c) = (keyed.clone(), contains_key.clone());
                Rc::new(move |change| match change {
                    // Keys are stable across inserts / moves; only removals and
                    // resets can orphan a selected key.
                    DataChange::ItemsRemoved { .. } | DataChange::Reset => {
                        k.prune_missing(|key| c(key));
                    }
                    _ => {}
                })
            },
            prune_fn: {
                let (k, c) = (keyed, contains_key);
                Rc::new(move || k.prune_missing(|key| c(key)))
            },
            // Keys already survive a version bump via `prune_fn` above —
            // there is no separate index range to clamp.
            prune_range_fn: Rc::new(|_count: usize| {}),
        }
    }

    pub(crate) fn mode(&self) -> SelectionMode {
        self.mode
    }
    pub(crate) fn is_selected(&self, index: usize) -> bool {
        (self.is_selected)(index)
    }
    pub(crate) fn select(&self, index: usize) {
        (self.select_fn)(index)
    }
    pub(crate) fn toggle(&self, index: usize) {
        (self.toggle_fn)(index)
    }
    pub(crate) fn extend_to(&self, index: usize) {
        (self.extend_fn)(index)
    }
    pub(crate) fn extend_to_additive(&self, index: usize) {
        (self.extend_additive_fn)(index)
    }
    pub(crate) fn select_all(&self, count: usize) {
        (self.select_all_fn)(count)
    }
    pub(crate) fn selected_indices(&self) -> Vec<usize> {
        (self.selected_indices_fn)()
    }
    /// Whether anything is selected. Prefer this over
    /// `!selected_indices().is_empty()` when only the emptiness matters (e.g.
    /// a per-frame paint gate) — it costs O(selected count), never
    /// O(visible), for both the index and keyed backings.
    pub(crate) fn has_selection(&self) -> bool {
        (self.has_selection_fn)()
    }
    pub(crate) fn clear(&self) {
        (self.clear_fn)()
    }
    /// Subscribe to selection changes (drives the view's rebuild). Owns the
    /// returned handle for the subscription's lifetime.
    pub(crate) fn observe_for_rebuild(&self, cb: impl Fn() + 'static) -> ObserverHandle {
        (self.observe_fn)(Box::new(cb))
    }
    /// React to a source data change (index-shift for the index model, prune
    /// for the keyed model).
    pub(crate) fn on_data_change(&self, change: &DataChange) {
        (self.on_change_fn)(change)
    }
    /// Prune orphaned keys (keyed model) — used by the tree views, which drive
    /// off a version signal rather than a `DataChange`. No-op for the index
    /// model.
    pub(crate) fn prune(&self) {
        (self.prune_fn)()
    }
    /// Drop selected indices `>= count` (index model) after a structural
    /// change with no delta to shift them by — a version-signal-driven tree
    /// view's only defence against a selection left pointing past the
    /// shrunk end (it cannot re-land on the row it used to point at; only
    /// `focused_index`'s `RowAnchor` tracks identity). No-op for the keyed
    /// model, already fully reconciled by `prune`.
    pub(crate) fn prune_out_of_range(&self, count: usize) {
        (self.prune_range_fn)(count)
    }
}

/// Resolves a set of the origin view's flat indices to a **removal thunk** at
/// drag-start. Invoked at completion, the thunk removes exactly those rows from
/// the source. Resolving eagerly (rather than re-reading flat indices at
/// completion) keeps a Move correct even if the origin's flat indices reshuffle
/// mid-drag — e.g. a `TreeView` spring-load auto-expand — since the stable keys
/// were already captured. The source erasure supplies it.
pub(crate) type SnapshotOutFn = Rc<dyn Fn(&[usize]) -> Box<dyn Fn()>>;

/// Active drag-drop feedback a tree data view paints itself: a between-rows
/// insertion line (Before/After) or a highlighted row (an into-container drop).
///
/// Shared by `TreeView` and `TreeTableView` so both render the same affordance
/// for the same source verdict.
/// A stable handle to a row in a data view.
///
/// Per-row event handlers (a chevron toggle, a click, an activation) are built
/// once and then live as long as the row widget does, so capturing the flat
/// index they were built at is fragile: expanding a branch above, applying a
/// filter, or sorting shifts every index below, and the stale handler would act
/// on whatever row moved into that slot.
///
/// A `RowAnchor` closes over the row's **source-owned identity** instead and
/// resolves the row's *current* position on demand. The key never surfaces in
/// the anchor's type — it is captured inside the resolver, so views stay
/// key-agnostic ([`TreeSource`](crate::tree_source::TreeSource) and
/// [`ListSource`](crate::list_source::ListSource) both erase it).
///
/// Sources without identity (a bare `ListModel`, or any source that leaves
/// `key_at` at its `None` default) get a fixed anchor that always reports the
/// index it was built with — no worse than capturing the index directly.
///
/// A bare `ListModel` has no identity to offer (a `Vec` row *is* its position),
/// so anchors over one are fixed. `SortFilterListModel` keys rows by their
/// **source index**, which no sort/filter reprojection renumbers — so anchors
/// over a projection do track their row across a filter change, which is the
/// flat fragility in practice. They can still mis-resolve inside the window
/// between an *upstream* insert/remove and the rebuild it schedules, since that
/// does renumber source indices; no worse than the captured index they replace.
/// The tree sources all carry real identity.
///
/// **Precondition: keys must be unique.** Resolution falls back to a lookup by
/// key, which returns the *first* match, so a source handing out duplicate keys
/// would silently redirect an anchor onto a different row — the very failure
/// this type exists to prevent.
#[derive(Clone)]
pub struct RowAnchor {
    resolve: Rc<dyn Fn() -> Option<usize>>,
}

impl RowAnchor {
    /// Build an identity-backed anchor from a resolver.
    pub(crate) fn new(resolve: Rc<dyn Fn() -> Option<usize>>) -> Self {
        Self { resolve }
    }

    /// An anchor for a source with no identity: always reports `index`.
    pub(crate) fn fixed(index: usize) -> Self {
        Self {
            resolve: Rc::new(move || Some(index)),
        }
    }

    /// The row's current flat index, or `None` if it no longer exists in the
    /// source (it was deleted, or filtered away).
    pub fn index(&self) -> Option<usize> {
        (self.resolve)()
    }

    /// Whether the row still exists.
    pub fn is_live(&self) -> bool {
        self.index().is_some()
    }
}

impl std::fmt::Debug for RowAnchor {
    /// Deliberately does NOT resolve: the resolver reads the source's
    /// interior-mutable state, so a `{:?}` from inside code already holding a
    /// borrow (a `set_source` closure, a reorder callback, a debugger's
    /// pretty-printer) would panic on a `RefCell` conflict.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("RowAnchor(..)")
    }
}

/// Keep an open cell editor pointing at the row it was opened on.
///
/// `editing_cell` is a `(row, col)` pair that outlives rebuilds, so rows
/// appearing or vanishing above an open editor would slide it onto a different
/// row. The anchor is captured the first time an open editor is seen and
/// re-resolved on every later rebuild: the row index is rewritten when it moved,
/// and the editor closes outright when its row is gone — better than silently
/// editing whoever took the slot.
///
/// Called from each body pane's `build`, which is the only place that sees both
/// an editing change and a data change. It can therefore write `editing_cell`
/// while that pane is building; the write is idempotent and converges in one
/// extra pass (the next reconcile finds `cur == row` and writes nothing), which
/// `an_editing_reconcile_converges_in_one_pass` pins.
pub(crate) fn reconcile_editing_row(
    editing_cell: &teksilo_core::signal::Signal<Option<(usize, usize)>>,
    slot: &Rc<std::cell::RefCell<Option<RowAnchor>>>,
    anchor_of: &dyn Fn(usize) -> RowAnchor,
) {
    let Some((row, col)) = editing_cell.get() else {
        *slot.borrow_mut() = None;
        return;
    };
    let existing = slot.borrow().clone();
    match existing {
        None => *slot.borrow_mut() = Some(anchor_of(row)),
        Some(anchor) => match anchor.index() {
            Some(cur) if cur != row => editing_cell.set(Some((cur, col))),
            Some(_) => {}
            None => {
                editing_cell.set(None);
                *slot.borrow_mut() = None;
            }
        },
    }
}

/// Tint for the "drop into this container" row highlight. Defined once so the
/// `DropFeedback` handed to the framework and the widget's own paint cannot
/// drift into two different colors on the same row.
pub(crate) fn drop_into_tint() -> teksilo_tokens::Color {
    teksilo_tokens::Color::from_rgba(0.25, 0.47, 0.85, 0.25)
}

#[derive(Clone, Copy, PartialEq, Debug)]
pub(crate) enum DropViz {
    /// Horizontal insertion line at `y`, spanning `width`, indented by
    /// `depth` tree levels — the level the dropped row lands at.
    Line { y: f32, width: f32, depth: usize },
    /// Highlighted target row `[top, top + height]`, spanning `width`,
    /// indented by the target's own `depth` — the "drop into this folder"
    /// affordance.
    Rect {
        top: f32,
        height: f32,
        width: f32,
        depth: usize,
    },
}

/// The reusable export / foreign-drop machinery shared by all five data views:
/// the config fields, the drag-start payload build (selection set already
/// resolved by the caller), the foreign-receive sugar, and the `on_drag_ended`
/// move-out completion. Each view holds ONE of these instead of duplicating the
/// logic five ways (the drift that a code review caught). See
/// [docs/drag-and-drop.md §12](https://github.com/ferntech-eu/teksilo/blob/main/docs/drag-and-drop.md).
pub(crate) struct RowExport<T: 'static> {
    /// `Some` once `.exportable(..)` was called; the transfer mode also drives
    /// the move-out completion.
    pub(crate) mode: Option<DragTransferMode>,
    /// Clones `&T` → `T` for the payload (set by `.exportable`/`.export_external`,
    /// each `where T: Clone`, so the view constructor stays unconstrained).
    #[allow(clippy::type_complexity)]
    pub(crate) clone_item_fn: Option<Rc<dyn Fn(&T) -> T>>,
    /// Builds MIME reps of the dragged items for OS / `DropZone` export.
    #[allow(clippy::type_complexity)]
    pub(crate) export_mime_fn: Option<Rc<dyn Fn(&[T]) -> Vec<(String, Vec<u8>)>>>,
    /// App override for removing rows moved out to a foreign target.
    #[allow(clippy::type_complexity)]
    pub(crate) on_rows_transferred_out: Option<Rc<dyn Fn(&[usize], &mut EventContext)>>,
    /// Accept exported rows from a different view/source (zero-custom-source).
    pub(crate) accept_foreign_rows: bool,
    /// Handler for rows accepted via `accept_foreign_rows`.
    #[allow(clippy::type_complexity)]
    pub(crate) on_rows_received: Option<Rc<dyn Fn(Vec<T>, usize, &mut EventContext)>>,
    /// Set by the view's own `on_drop` when it applied a same-view reorder, so
    /// the completion skips the move-out (already applied). The TabBar pattern.
    pub(crate) self_reorder_flag: Rc<Cell<bool>>,
    /// The rows carried by the in-flight drag (for the app move-out callback).
    dragged_rows: Rc<RefCell<Vec<usize>>>,
    /// Stable-key removal thunk for the default move-out, resolved at drag-start.
    #[allow(clippy::type_complexity)]
    removal: Rc<RefCell<Option<Box<dyn Fn()>>>>,
}

impl<T: 'static> Clone for RowExport<T> {
    // Hand-written (not derived) so cloning does NOT require `T: Clone` — every
    // field is an `Rc` / `Copy`, so a clone shares the same drag stash + flags,
    // which is exactly what the per-row drag closure needs.
    fn clone(&self) -> Self {
        Self {
            mode: self.mode,
            clone_item_fn: self.clone_item_fn.clone(),
            export_mime_fn: self.export_mime_fn.clone(),
            on_rows_transferred_out: self.on_rows_transferred_out.clone(),
            accept_foreign_rows: self.accept_foreign_rows,
            on_rows_received: self.on_rows_received.clone(),
            self_reorder_flag: self.self_reorder_flag.clone(),
            dragged_rows: self.dragged_rows.clone(),
            removal: self.removal.clone(),
        }
    }
}

impl<T: 'static> Default for RowExport<T> {
    fn default() -> Self {
        Self {
            mode: None,
            clone_item_fn: None,
            export_mime_fn: None,
            on_rows_transferred_out: None,
            accept_foreign_rows: false,
            on_rows_received: None,
            self_reorder_flag: Rc::new(Cell::new(false)),
            dragged_rows: Rc::new(RefCell::new(Vec::new())),
            removal: Rc::new(RefCell::new(None)),
        }
    }
}

impl<T: 'static> RowExport<T> {
    /// `.exportable(mode)` — carry item clones; `where T: Clone` at the call.
    pub(crate) fn set_exportable(&mut self, mode: DragTransferMode)
    where
        T: Clone,
    {
        self.mode = Some(mode);
        if self.clone_item_fn.is_none() {
            self.clone_item_fn = Some(Rc::new(|t: &T| t.clone()));
        }
    }

    /// `.export_external(f)` — attach MIME; implies exportable.
    pub(crate) fn set_export_external(
        &mut self,
        f: impl Fn(&[T]) -> Vec<(String, Vec<u8>)> + 'static,
    ) where
        T: Clone,
    {
        if self.clone_item_fn.is_none() {
            self.clone_item_fn = Some(Rc::new(|t: &T| t.clone()));
        }
        if self.mode.is_none() {
            self.mode = Some(DragTransferMode::default());
        }
        self.export_mime_fn = Some(Rc::new(f));
    }

    pub(crate) fn set_on_rows_transferred_out(
        &mut self,
        f: impl Fn(&[usize], &mut EventContext) + 'static,
    ) {
        self.on_rows_transferred_out = Some(Rc::new(f));
    }

    pub(crate) fn set_on_rows_received(
        &mut self,
        f: impl Fn(Vec<T>, usize, &mut EventContext) + 'static,
    ) {
        self.on_rows_received = Some(Rc::new(f));
    }

    /// Rows are a drag source when the view reorders OR exports.
    pub(crate) fn is_drag_source(&self, reorderable: bool) -> bool {
        reorderable || self.mode.is_some()
    }

    /// The view is a drop target when it reorders OR accepts foreign rows.
    pub(crate) fn is_drop_target(&self, reorderable: bool) -> bool {
        reorderable || self.accept_foreign_rows
    }

    /// Build the drag payload for the (already selection-resolved) `rows`. Drops
    /// any non-resident row (a lazy `Loading` row `read` can't serve) so `rows`
    /// and `items` stay index-aligned and a Move never deletes a row whose data
    /// wasn't transferred. Attaches MIME, and stashes the rows + a stable-key
    /// removal thunk for the completion.
    ///
    /// `None` when no row survives the residency filter (an all-`Loading`
    /// selection): the caller must refuse the drag rather than float an empty
    /// payload nothing can accept.
    pub(crate) fn build_payload(
        &self,
        source: ViewId,
        mut rows: Vec<usize>,
        read: &dyn Fn(usize, &mut dyn FnMut(&T)) -> bool,
        snapshot_out: &SnapshotOutFn,
    ) -> Option<DragPayload> {
        let items: Option<Vec<T>> = if let Some(cf) = self.clone_item_fn.as_ref() {
            let mut out = Vec::with_capacity(rows.len());
            rows.retain(|&r| {
                let mut got = None;
                read(r, &mut |t| got = Some(cf(t)));
                match got {
                    Some(v) => {
                        out.push(v);
                        true
                    }
                    None => false,
                }
            });
            Some(out)
        } else {
            None
        };
        if rows.is_empty() {
            return None;
        }
        let mime_pairs: Vec<(String, Vec<u8>)> =
            match (self.export_mime_fn.as_ref(), items.as_ref()) {
                (Some(mf), Some(its)) => mf(its),
                _ => Vec::new(),
            };
        let mut payload = DragPayload::typed(RowDragData::<T> {
            source,
            rows: rows.clone(),
            items,
        });
        let has_mime = !mime_pairs.is_empty();
        for (mime, bytes) in mime_pairs {
            payload = payload.with_mime(&mime, bytes);
        }
        if has_mime {
            payload.enrich_external_from_mime();
        }
        *self.removal.borrow_mut() = Some((snapshot_out)(&rows));
        *self.dragged_rows.borrow_mut() = rows;
        Some(payload)
    }

    /// Whether a **foreign** exported payload would be accepted here — for the
    /// hover affordance. (Same-view / reorder-only payloads return `false`.)
    pub(crate) fn accepts_foreign_export(&self, payload: &DragPayload, source: ViewId) -> bool {
        self.accept_foreign_rows
            && self.on_rows_received.is_some()
            && payload
                .get_typed::<RowDragData<T>>()
                .is_some_and(|rd| rd.source != source && rd.is_export())
    }

    /// Foreign-receive sugar for a view's `on_drop`. Peeks before taking, so a
    /// non-matching payload is left intact for any further fallback.
    pub(crate) fn foreign_receive(
        &self,
        payload: &mut DragPayload,
        source: ViewId,
        insertion: usize,
        ctx: &mut EventContext,
    ) -> bool {
        if self.accepts_foreign_export(payload, source)
            && let Some(cb) = self.on_rows_received.as_ref()
            && let Some(rd) = payload.take_typed::<RowDragData<T>>()
            && let Some(items) = rd.items
        {
            cb(items, insertion, ctx);
            return true;
        }
        false
    }

    /// The view's own `on_drop` calls this after applying a genuine SAME-VIEW
    /// reorder, so the completion knows the change was already applied.
    pub(crate) fn note_self_reorder(&self) {
        self.self_reorder_flag.set(true);
    }

    /// Install the `on_drag_ended` move-out completion. A same-view reorder set
    /// `self_reorder_flag` (skipped here); on `Move` + accepted-elsewhere the
    /// origin rows are removed via the app override (delivered **descending** so
    /// index-by-index removal stays valid) or the stable-key removal thunk.
    pub(crate) fn install_completion(&self, handlers: HandlerSet) -> HandlerSet {
        let Some(mode) = self.mode else {
            return handlers;
        };
        let flag = self.self_reorder_flag.clone();
        let dragged = self.dragged_rows.clone();
        let removal = self.removal.clone();
        let on_out = self.on_rows_transferred_out.clone();
        handlers.on_drag_ended(move |outcome, ctx| {
            let handled_by_us = flag.replace(false);
            let rows = std::mem::take(&mut *dragged.borrow_mut());
            let thunk = removal.borrow_mut().take();
            if handled_by_us {
                return;
            }
            let accepted_elsewhere = matches!(
                outcome,
                DropOutcome::InApp { accepted: true } | DropOutcome::OsMove
            );
            if mode != DragTransferMode::Move || !accepted_elsewhere || rows.is_empty() {
                return;
            }
            if let Some(cb) = on_out.as_ref() {
                let mut desc = rows;
                desc.sort_unstable();
                desc.reverse();
                cb(&desc, ctx);
            } else if let Some(thunk) = thunk {
                thunk();
            }
        })
    }
}

/// A layout- and accessibility-transparent wrapper whose only job is to own a
/// drag on a node that **strictly encloses** the node whose gesture arena takes
/// the press.
///
/// # Why the drag cannot live on the pressed node
///
/// [`DragActivation`](teksilo_tokens::DragActivation) — the policy that holds a
/// touch drag back until a long press so the scroll underneath can win first —
/// is read on two paths, and the node that *captures* the press is on neither
/// of them unless it is **already** the sequence's pan claimant:
///
/// * the **ancestor walk** of the tree's sequence enrolment, through
///   `PointerSequence::enrol_drag`;
/// * `PointerSequence::defer_own_drag`, the dual-role arm, which attaches the
///   activation to a member the node already holds — and which refuses anything
///   but a live `MemberRole::Pan`. A `SceneView` is such a node. A **row** is
///   not: the claim is the scrollable's, several levels out.
///
/// So a row that carries both its tap and its reorder `on_drag` is enrolled by
/// the captured branch's plain `enrol`, which consults no activation at all. It
/// latches that drag at `drag_slop` on the first sample past 18 dp, decides the
/// arbitration, and the scrollable's `PanClaim` — which needs 36 dp — is never
/// even evaluated. The view then neither scrolls nor reorders: the drag won and,
/// for a marquee that declines a press on a tile, did nothing. That is the
/// `list row · touch` row of `crates/teksilo-core/tests/arbitration_matrix.rs`,
/// read as a defect rather than as a rule.
///
/// Hanging the drag one level out fixes both halves at once, with no change to
/// the framework: the pressed node has no drag, so the walk reaches this
/// wrapper and enrols it *with* its activation. A precise pointer resolves
/// `Auto` to `Immediate` and latches at the same 5 dp it always did; a direct
/// pointer resolves it to `AfterLongPress` and the pan wins unless the contact
/// holds still.
///
/// # What must be true of the node inside
///
/// It must have a gesture arena of its own, or nothing captures the press and
/// the enrolment walk never starts — the drag would then compete by no path at
/// all. [`press_absorber`] is the no-op tap that guarantees one, for a row
/// whose application wired no activation. This is the `primitives::dead_zone`
/// precedent: a structural rule plus an absorber that makes the structure real.
///
/// Transparent in every other respect: it forwards the child's whole
/// [`LayoutResponse`](teksilo_core::widget::LayoutResponse) (grow weight,
/// shrink weight and compression floor, not
/// just the size), places the child at its own bounds, and emits no
/// accessibility properties, so the walker prunes it: a reorderable view's
/// accessibility tree has the same *shape* as the same view without the
/// wrapper, which is what
/// `a_reorderable_view_has_the_same_accessibility_shape` asserts.
pub(crate) struct DragSurface {
    child: Option<WidgetId>,
}

impl DragSurface {
    /// Wrap a pre-registered widget by id.
    pub(crate) fn new(child: WidgetId) -> Self {
        Self { child: Some(child) }
    }
}

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

impl Widget for DragSurface {
    fn build(&mut self, _ctx: &mut BuildContext) -> Vec<WidgetId> {
        self.child.into_iter().collect()
    }

    fn layout_response(
        &self,
        proposal: teksilo_canvas::SizeProposal,
        ctx: &teksilo_core::widget::LayoutContext,
    ) -> teksilo_core::widget::LayoutResponse {
        self.child
            .and_then(|id| ctx.child_layout_response(id, proposal))
            .unwrap_or_else(|| proposal.resolve(0.0, 0.0).into())
    }

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

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

/// The `HandlerSet` a row's or tile's [`DragSurface`] carries, before its own
/// `on_drag` is chained onto it: the declaration that **the hold inside this
/// wrapper belongs to that drag**.
///
/// A19's ruling is that where a row has both a reorder and a context menu the
/// reorder wins the hold, and the menu moves to an overflow affordance plus
/// Secondary / `Shift+F10` / the AccessKit `ShowContextMenu` action. The
/// framework enforces "one hold, one meaning" implicitly, from the deferral on
/// the drag member — but that rule is keyed on the **node**, because a deferred
/// grab on some enclosing container is not a claim on the holds of everything
/// inside it (a `SceneView` that marquees after a hold must not thereby take the
/// touch context menu away from every widget placed in it; a finger has no
/// secondary button, so the hold is the only route those have).
///
/// A [`DragSurface`] is the one place that implicit rule reads one node too far
/// out. The wrapper is not an enclosing container: it is layout-, hit- and
/// accessibility-transparent, its subtree is exactly one row, and the drag it
/// carries is that row's own. So it says so, with the explicit subtree-wide
/// declaration [`LongPressRole::DragHandle`](teksilo_core::LongPressRole::DragHandle),
/// which `WidgetTree::long_press_is_a_grab` walks from the pressed node to the
/// root.
///
/// **It takes a hold only from a direct pointer**, because a hold is a
/// drag-start route only where a drag waits for one — which is the finger and
/// the pen. A mouse latches this same reorder on travel, at `drag_slop`, with no
/// deadline in it, so its hold is spent on nothing and stays the application's:
/// a row's own `on_long_press` still fires under a mouse however this wrapper is
/// declared. That gate lives in `long_press_is_a_grab`, not here, so every
/// `DragHandle` declaration gets it.
///
/// Deliberately **not** applied to the body-pane `DragSurface` that hosts
/// `GridView`'s marquee. That one *is* an enclosing container — its subtree is
/// every tile in the grid — and declaring it there would take the touch context
/// menu away from all of them, which is the defect this distinction exists to
/// avoid.
pub(crate) fn row_grab_surface() -> HandlerSet {
    HandlerSet::new().long_press_role(teksilo_core::LongPressRole::DragHandle)
}

/// The no-op tap that guarantees a node its own gesture arena.
///
/// Merged onto every row, tile or body pane a [`DragSurface`] encloses. Without
/// an arena nothing captures the press, and the walk that enrols the surface's
/// drag never runs — so the drag would compete by no path at all.
///
/// `GridView` merges it onto every tile whether or not one encloses it, and for
/// a second reason: the grid's body pane carries an absorber too, so a tile with
/// no arena of its own leaves the pane holding the press — and a release
/// dispatched to the captor and bubbled target→root never reaches a tile
/// *beneath* it. A plain selectable grid lost both its finger tap and, on a
/// mouse, the release that collapses a multi-selection that way. The four row
/// views have no pane-level absorber, so a plain row there is merely arena-less,
/// which costs it nothing *so long as nothing above it competes for the press*.
/// An application that wraps such a view in anything tappable puts an arena
/// there itself, and the row loses its release the same way — see
/// `docs/data-view-touch.md`'s second known limit.
///
/// Applied unconditionally rather than only where the node would otherwise have
/// none: an extra no-op tap in an arena that already has one is inert (the
/// arena builds one `TapRecognizer` however many closures are installed), while
/// a condition enumerating the handlers a pane happens to attach today would
/// silently stop guaranteeing anything the next time one is added. It absorbs
/// nothing and answers nothing — the recognizer's existence is the whole point.
pub(crate) fn press_absorber() -> HandlerSet {
    HandlerSet::new().on_tap(|_tap, _ctx| {})
}

/// Whether the primary release being dispatched still completes the press it
/// began — the question every **release-time commitment** in a data view's row
/// body has to ask before committing.
///
/// A row body commits two things on release: the deferred collapse of a
/// multi-selection ([`deferred_select::on_up`]), and — in `TreeView` — the
/// expansion toggle of a branch row. Both are correct for a click and wrong for
/// a finger that was scrolling, so both are gated on this.
///
/// It answers `false` in the two ways a row loses the press without a cancel it
/// can see:
///
/// * **a peer claimed the contact.** The scrollable above the row won the
///   arbitration with its `PanClaim` and the press is now a scroll. The row
///   cannot rely on being told: it is enrolled as a sequence member only when
///   it carries a drag (`reorderable` / `exportable`), and even then the
///   loser's `CancelReason::PeerClaimed` is *member*-level — deliberately
///   leaving the pointer alive so its winner can finish — so the `PointerUp`
///   still arrives here either way. `WidgetTree::update_press` ends the press
///   record on that claim, which is the fact this reads.
/// * **the pointer left the press's tap boundary.** The same predicate that
///   fails the tap and fires `cancel_taps`, so a release-time commit is
///   abandoned exactly when the activation is.
///
/// It stays `true` through a press-feedback delay — a finger that lands and
/// lifts before the delay elapses has still clicked — because the delay
/// withholds the *visual*, not the press.
///
/// The older reasoning at these sites, that "an active drag consumes
/// `PointerUp`", covers only a **drag**: a won pan claim is not an
/// `active_drag`, so the release is not routed to `handle_drag_drop` and does
/// reach the row.
pub(crate) fn release_completes_the_press(ctx: &teksilo_core::widget::EventContext) -> bool {
    ctx.press_is_inside()
}

/// Shared selection-on-press/release logic for a data-view row, and the type
/// its two calls share.
///
/// # What a press decides, and when the decision is applied
///
/// A **precise** pointer (mouse) still selects on press, exactly as it always
/// has — that is the click convention on every desktop, and a press that never
/// becomes anything else is still a click. The one thing it defers is the
/// *collapse* of an existing multi-selection: pressing an already-selected row
/// keeps the whole set so it can be dragged, and collapses to the pressed row
/// only on a release that still belongs to it.
///
/// A **direct** pointer (a finger, a pen) defers the *whole* decision to the
/// release. A press from a finger is not yet a click: the same contact is the
/// opening sample of a scroll, and a scrolling finger must leave the selection
/// exactly as it found it. No release-time predicate can rescue a selection
/// already written on `PointerDown`, so the write itself moves to the release —
/// and a release the row has lost (a won `PanClaim`, a press that wandered out
/// of the tap boundary) is refused by
/// [`release_completes_the_press`], which is what makes a pan commit nothing.
///
/// The nav cursor travels with the selection rather than with the press, so the
/// arrow-key origin and the selection can never point at different rows: both
/// calls report whether the caller should move it *now*.
pub(crate) mod deferred_select {
    use std::cell::Cell;
    use std::rc::Rc;

    use teksilo_core::event::Modifiers;
    use teksilo_core::widget::EventContext;

    use super::RowSelection;

    /// The selection change a press decided but has not applied yet.
    ///
    /// `Collapse` is the one a mouse defers; a direct pointer defers whichever
    /// of the three its modifiers chose.
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    pub(crate) enum PendingSelect {
        /// Replace the selection with this row — a plain click, and the
        /// collapse of a multi-selection the press kept alive.
        Collapse,
        /// Accelerator-click: add or remove this row.
        Toggle,
        /// Shift-click: extend the range from the anchor.
        Extend,
    }

    /// The per-row cell the two calls share. One per realized row.
    pub(crate) type Pending = Rc<Cell<Option<PendingSelect>>>;

    /// A fresh, empty pending cell.
    pub(crate) fn pending_cell() -> Pending {
        Rc::new(Cell::new(None))
    }

    fn apply(sel: &RowSelection, index: usize, what: PendingSelect) {
        match what {
            PendingSelect::Collapse => sel.select(index),
            PendingSelect::Toggle => sel.toggle(index),
            PendingSelect::Extend => sel.extend_to(index),
        }
    }

    /// Handle a primary `PointerDown` on row `index`.
    ///
    /// Returns whether the caller should move its nav cursor to `index` now:
    /// `false` when an interactive child claimed the press (nothing happened
    /// here at all), and `false` for a direct pointer, whose decision — cursor
    /// included — belongs to the release.
    pub(crate) fn on_down(
        sel: &RowSelection,
        index: usize,
        modifiers: Modifiers,
        pending: &Pending,
        ctx: &mut EventContext,
    ) -> bool {
        if ctx.press_claimed_by_interactive_child() {
            pending.set(None);
            return false;
        }
        // The accelerator-click that adds one row to a discontiguous selection:
        // Ctrl+click on Windows and Linux, ⌘-click on macOS — where ⌃-click is
        // the secondary click and would open a context menu instead.
        let what = if modifiers.command() {
            PendingSelect::Toggle
        } else if modifiers.shift() {
            PendingSelect::Extend
        } else {
            PendingSelect::Collapse
        };
        if ctx.pointer_kind().is_direct() {
            // A finger's press is not yet a click — see the module header.
            pending.set(Some(what));
            return false;
        }
        if what == PendingSelect::Collapse && sel.is_selected(index) {
            // Grab-the-set-and-drag: keep the multi-selection alive for the
            // press, collapse it on a release without a drag.
            pending.set(Some(what));
        } else {
            apply(sel, index, what);
            pending.set(None);
        }
        true
    }

    /// Handle a primary `PointerUp` on row `index`, applying whatever the press
    /// deferred.
    ///
    /// Returns whether the caller should move its nav cursor to `index` now —
    /// true exactly when a deferred decision was applied.
    ///
    /// Refuses when the release belongs to an interactive child, and when the
    /// press it would complete is no longer this row's
    /// ([`release_completes_the_press`](super::release_completes_the_press)).
    pub(crate) fn on_up(
        sel: &RowSelection,
        index: usize,
        pending: &Pending,
        ctx: &mut EventContext,
    ) -> bool {
        if ctx.press_claimed_by_interactive_child() {
            return false;
        }
        if !super::release_completes_the_press(ctx) {
            // The deferred decision is abandoned, not postponed: clear the flag
            // so it cannot fire on some later release this row does own.
            pending.set(None);
            return false;
        }
        match pending.replace(None) {
            Some(what) => {
                apply(sel, index, what);
                true
            }
            None => false,
        }
    }
}

#[cfg(test)]
mod payload_tests {
    use super::*;

    fn noop_snapshot() -> SnapshotOutFn {
        Rc::new(|_: &[usize]| Box::new(|| {}) as Box<dyn Fn()>)
    }

    #[test]
    fn an_all_unresident_selection_refuses_the_drag() {
        // Every dragged row is still `Loading`: the residency filter empties
        // the set, and the drag must be refused outright — a floating payload
        // with no rows and no items would remove nothing on a Move and offer
        // nothing to a receiver.
        let mut export = RowExport::<u64>::default();
        export.set_exportable(DragTransferMode::Move);
        let read = |_: usize, _: &mut dyn FnMut(&u64)| false;
        let payload = export.build_payload(
            ViewId::next(ViewKind::List),
            vec![0, 1, 2],
            &read,
            &noop_snapshot(),
        );
        assert!(payload.is_none());
    }

    #[test]
    fn a_partially_resident_selection_carries_only_the_resident_rows() {
        let mut export = RowExport::<u64>::default();
        export.set_exportable(DragTransferMode::Copy);
        // Row 1 is unresident; rows 0 and 2 resolve.
        let read = |i: usize, f: &mut dyn FnMut(&u64)| {
            if i == 1 {
                return false;
            }
            f(&(i as u64 * 10));
            true
        };
        let payload = export
            .build_payload(
                ViewId::next(ViewKind::List),
                vec![0, 1, 2],
                &read,
                &noop_snapshot(),
            )
            .expect("two rows are resident");
        let rd = payload.get_typed::<RowDragData<u64>>().unwrap();
        assert_eq!(rd.rows, vec![0, 2]);
        assert_eq!(rd.items.as_deref(), Some(&[0, 20][..]));
    }
}

#[cfg(test)]
mod drag_surface_tests {
    use super::*;
    use crate::primitives::{FixedSize, HStack, Shrinkable};
    use teksilo_canvas::SizeProposal;
    use teksilo_core::widget_tree::WidgetTree;

    /// The wrapper's own doc says it forwards the child's *whole*
    /// `LayoutResponse`, not just the size. Flattening it to a bare `Size` makes
    /// the surface rigid, which over-constrains any tight container it sits in —
    /// the failure `primitives::dead_zone` was written to avoid and
    /// `primitives::touch_target::tests::the_wrapper_forwards_its_child_shrink_weight`
    /// already pins for the other wrapper of this shape. Shrink is the
    /// discriminating field: a rigid surface refuses to compress at all, so its
    /// width stays at the child's ideal instead of yielding to the deficit.
    #[test]
    fn the_drag_surface_forwards_its_child_shrink_weight() {
        let mut tree = WidgetTree::new();
        let inner = tree.add(
            Shrinkable::new()
                .min_width(20.0)
                .child(FixedSize::new().width(100.0).height(20.0)),
        );
        let slot = tree.add(DragSurface::new(inner));
        let rigid = tree.add(FixedSize::new().width(100.0).height(20.0));
        tree.add(HStack::new().child(rigid).child(slot));
        tree.layout(SizeProposal::exact(120.0, 20.0));
        let w = tree.bounds(slot).width;
        assert!(
            w < 100.0,
            "the DragSurface must forward the child's shrink weight (width was {w})"
        );
    }
}