guise/data/tableview/

state.rs

//! Pure sort and selection logic for [`TableView`](super::TableView).
//!
//! Sorting produces a *display order* — a stable permutation of source-row
//! indices — so the source data is never reordered. Selection is a set of
//! source indices, which is why it survives resorting unchanged.
//!
//! ```ignore
//! let order = sorted_order(&rows, SortDir::Asc, &|a, b| a.name.cmp(&b.name));
//! let mut sel = SelectionState::default();
//! sel.click(SelectionMode::Multi, &order, 0, false, false);
//! sel.click(SelectionMode::Multi, &order, 3, false, true); // shift: rows 0..=3
//! ```

use std::cmp::Ordering;
use std::collections::BTreeSet;

/// Sort direction of a table column.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SortDir {
    Asc,
    Desc,
}

/// How rows respond to clicks and arrow keys.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SelectionMode {
    /// Rows are not selectable.
    #[default]
    None,
    /// At most one row selected at a time.
    Single,
    /// Many rows: cmd-click toggles, shift-click selects a range.
    Multi,
}

/// Header-click cycling: none → asc → desc → none on the same column; a click
/// on a different column starts fresh at ascending.
pub fn cycle_sort(current: Option<(usize, SortDir)>, column: usize) -> Option<(usize, SortDir)> {
    match current {
        Some((col, SortDir::Asc)) if col == column => Some((column, SortDir::Desc)),
        Some((col, SortDir::Desc)) if col == column => None,
        _ => Some((column, SortDir::Asc)),
    }
}

/// The unsorted display order: `0..len`.
pub fn identity_order(len: usize) -> Vec<usize> {
    (0..len).collect()
}

/// A stable sort of row indices by `cmp`; the source slice is never mutated.
/// `Desc` flips the comparator arguments (rather than reversing the result),
/// so equal rows keep their source order in both directions.
pub fn sorted_order<T>(rows: &[T], dir: SortDir, cmp: &dyn Fn(&T, &T) -> Ordering) -> Vec<usize> {
    let mut order = identity_order(rows.len());
    order.sort_by(|&a, &b| match dir {
        SortDir::Asc => cmp(&rows[a], &rows[b]),
        SortDir::Desc => cmp(&rows[b], &rows[a]),
    });
    order
}

/// Where `source` currently sits in the display order.
fn position_of(order: &[usize], source: usize) -> Option<usize> {
    order.iter().position(|&s| s == source)
}

/// Row selection over **source** indices. The shift anchor and keyboard cursor
/// are also source indices, mapped through the display order at use, so all
/// three survive resorting.
#[derive(Debug, Clone, Default)]
pub struct SelectionState {
    selected: BTreeSet<usize>,
    anchor: Option<usize>,
    cursor: Option<usize>,
}

impl SelectionState {
    /// The selected source indices, ascending.
    pub fn selected(&self) -> Vec<usize> {
        self.selected.iter().copied().collect()
    }

    pub fn is_selected(&self, source: usize) -> bool {
        self.selected.contains(&source)
    }

    /// The keyboard cursor (a source index), if any.
    pub fn cursor(&self) -> Option<usize> {
        self.cursor
    }

    /// Drop everything. Returns whether the selected set changed.
    pub fn clear(&mut self) -> bool {
        self.anchor = None;
        self.cursor = None;
        if self.selected.is_empty() {
            return false;
        }
        self.selected.clear();
        true
    }

    /// Prune indices that fell off the end after a row-count change. Returns
    /// whether the selected set changed.
    pub fn retain_below(&mut self, len: usize) -> bool {
        let before = self.selected.len();
        self.selected.retain(|&s| s < len);
        self.anchor = self.anchor.filter(|&s| s < len);
        self.cursor = self.cursor.filter(|&s| s < len);
        self.selected.len() != before
    }

    /// A mouse click on the row at `display` position. `toggle` is cmd-click,
    /// `range` is shift-click (range wins when both are held).
    pub fn click(
        &mut self,
        mode: SelectionMode,
        order: &[usize],
        display: usize,
        toggle: bool,
        range: bool,
    ) {
        let Some(&source) = order.get(display) else {
            return;
        };
        match mode {
            SelectionMode::None => {}
            SelectionMode::Single => {
                if toggle && self.selected.contains(&source) {
                    self.selected.clear();
                } else {
                    self.selected.clear();
                    self.selected.insert(source);
                }
                self.anchor = Some(source);
                self.cursor = Some(source);
            }
            SelectionMode::Multi => {
                if range {
                    let from = match self.anchor.and_then(|a| position_of(order, a)) {
                        Some(pos) => pos,
                        // No live anchor (first interaction, or its row is
                        // gone): this click starts and anchors the range.
                        None => {
                            self.anchor = Some(source);
                            display
                        }
                    };
                    self.select_span(order, from, display);
                } else if toggle {
                    if !self.selected.remove(&source) {
                        self.selected.insert(source);
                    }
                    self.anchor = Some(source);
                } else {
                    self.selected.clear();
                    self.selected.insert(source);
                    self.anchor = Some(source);
                }
                self.cursor = Some(source);
            }
        }
    }

    /// Move the cursor by `delta` display positions (arrow keys), selecting
    /// the row it lands on. `extend` (shift) grows the range from the anchor
    /// in `Multi` mode. Returns the new cursor's display position so the
    /// caller can scroll it into view.
    pub fn step(
        &mut self,
        mode: SelectionMode,
        order: &[usize],
        delta: isize,
        extend: bool,
    ) -> Option<usize> {
        if matches!(mode, SelectionMode::None) || order.is_empty() {
            return None;
        }
        let last = order.len() - 1;
        let display = match self.cursor.and_then(|c| position_of(order, c)) {
            Some(pos) => (pos as isize + delta).clamp(0, last as isize) as usize,
            // Nothing focused yet: Down enters at the top, Up at the bottom.
            None if delta < 0 => last,
            None => 0,
        };
        let source = order[display];
        if extend && matches!(mode, SelectionMode::Multi) {
            let from = match self.anchor.and_then(|a| position_of(order, a)) {
                Some(pos) => pos,
                // No live anchor yet: the row this step lands on anchors the
                // range, so further shift-steps grow from it.
                None => {
                    self.anchor = Some(source);
                    display
                }
            };
            self.select_span(order, from, display);
        } else {
            self.selected.clear();
            self.selected.insert(source);
            self.anchor = Some(source);
        }
        self.cursor = Some(source);
        Some(display)
    }

    /// Select exactly the display range `a..=b` (either direction).
    fn select_span(&mut self, order: &[usize], a: usize, b: usize) {
        let (lo, hi) = if a <= b { (a, b) } else { (b, a) };
        self.selected.clear();
        self.selected.extend(order[lo..=hi].iter().copied());
    }
}

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

    #[test]
    fn sort_cycles_asc_desc_none() {
        let s1 = cycle_sort(None, 2);
        assert_eq!(s1, Some((2, SortDir::Asc)));
        let s2 = cycle_sort(s1, 2);
        assert_eq!(s2, Some((2, SortDir::Desc)));
        assert_eq!(cycle_sort(s2, 2), None);
    }

    #[test]
    fn sort_switching_column_restarts_ascending() {
        let current = Some((0, SortDir::Desc));
        assert_eq!(cycle_sort(current, 1), Some((1, SortDir::Asc)));
    }

    #[test]
    fn sorted_order_never_touches_the_source() {
        let rows = vec![3, 1, 2];
        let order = sorted_order(&rows, SortDir::Asc, &|a, b| a.cmp(b));
        assert_eq!(order, vec![1, 2, 0]);
        assert_eq!(rows, vec![3, 1, 2]);
    }

    #[test]
    fn sorted_order_is_stable_in_both_directions() {
        // Equal keys (by first tuple field) must keep source order.
        let rows = vec![(1, "a"), (0, "b"), (1, "c"), (0, "d")];
        let cmp = |a: &(i32, &str), b: &(i32, &str)| a.0.cmp(&b.0);
        assert_eq!(sorted_order(&rows, SortDir::Asc, &cmp), vec![1, 3, 0, 2]);
        assert_eq!(sorted_order(&rows, SortDir::Desc, &cmp), vec![0, 2, 1, 3]);
    }

    #[test]
    fn single_mode_holds_one_row_and_cmd_click_deselects() {
        let order = identity_order(4);
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::Single, &order, 1, false, false);
        assert_eq!(sel.selected(), vec![1]);
        sel.click(SelectionMode::Single, &order, 3, false, false);
        assert_eq!(sel.selected(), vec![3]);
        sel.click(SelectionMode::Single, &order, 3, true, false);
        assert_eq!(sel.selected(), Vec::<usize>::new());
    }

    #[test]
    fn none_mode_ignores_clicks_and_steps() {
        let order = identity_order(3);
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::None, &order, 0, false, false);
        assert!(sel.selected().is_empty());
        assert_eq!(sel.step(SelectionMode::None, &order, 1, false), None);
    }

    #[test]
    fn multi_mode_cmd_click_toggles() {
        let order = identity_order(4);
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::Multi, &order, 0, false, false);
        sel.click(SelectionMode::Multi, &order, 2, true, false);
        assert_eq!(sel.selected(), vec![0, 2]);
        sel.click(SelectionMode::Multi, &order, 0, true, false);
        assert_eq!(sel.selected(), vec![2]);
    }

    #[test]
    fn multi_mode_shift_click_selects_a_range_from_the_anchor() {
        let order = identity_order(6);
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::Multi, &order, 1, false, false);
        sel.click(SelectionMode::Multi, &order, 4, false, true);
        assert_eq!(sel.selected(), vec![1, 2, 3, 4]);
        // Shift again re-ranges from the same anchor, upward this time.
        sel.click(SelectionMode::Multi, &order, 0, false, true);
        assert_eq!(sel.selected(), vec![0, 1]);
    }

    #[test]
    fn shift_click_first_establishes_the_anchor() {
        let order = identity_order(6);
        let mut sel = SelectionState::default();
        // Fresh table: a shift-click anchors at the clicked row...
        sel.click(SelectionMode::Multi, &order, 2, false, true);
        assert_eq!(sel.selected(), vec![2]);
        // ...so the next shift-click grows a range from it.
        sel.click(SelectionMode::Multi, &order, 5, false, true);
        assert_eq!(sel.selected(), vec![2, 3, 4, 5]);
    }

    #[test]
    fn shift_step_first_extends_from_the_entry_row() {
        let order = identity_order(4);
        let mut sel = SelectionState::default();
        // Fresh table: shift+down enters at the top and anchors there...
        assert_eq!(sel.step(SelectionMode::Multi, &order, 1, true), Some(0));
        assert_eq!(sel.selected(), vec![0]);
        // ...so the next shift+down extends instead of moving the selection.
        assert_eq!(sel.step(SelectionMode::Multi, &order, 1, true), Some(1));
        assert_eq!(sel.selected(), vec![0, 1]);
    }

    #[test]
    fn shift_range_follows_display_order_but_stores_source_indices() {
        // Display order reversed: display 0 shows source 3, etc.
        let order = vec![3, 2, 1, 0];
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::Multi, &order, 0, false, false);
        assert_eq!(sel.selected(), vec![3]);
        sel.click(SelectionMode::Multi, &order, 2, false, true);
        assert_eq!(sel.selected(), vec![1, 2, 3]);
    }

    #[test]
    fn selection_survives_resorting() {
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::Single, &identity_order(4), 2, false, false);
        assert_eq!(sel.selected(), vec![2]);
        // Order flips; source 2 is still the selected row.
        assert!(sel.is_selected(2));
        // Stepping down from it moves through the *new* display order.
        let order = vec![3, 2, 1, 0]; // source 2 is at display 1
        let display = sel.step(SelectionMode::Single, &order, 1, false);
        assert_eq!(display, Some(2));
        assert_eq!(sel.selected(), vec![1]);
    }

    #[test]
    fn step_enters_at_the_edges_and_clamps() {
        let order = identity_order(3);
        let mut sel = SelectionState::default();
        assert_eq!(sel.step(SelectionMode::Single, &order, 1, false), Some(0));
        assert_eq!(sel.step(SelectionMode::Single, &order, -1, false), Some(0));
        assert_eq!(sel.selected(), vec![0]);

        let mut sel = SelectionState::default();
        assert_eq!(sel.step(SelectionMode::Single, &order, -1, false), Some(2));
        assert_eq!(sel.selected(), vec![2]);
    }

    #[test]
    fn shift_step_extends_from_the_anchor() {
        let order = identity_order(5);
        let mut sel = SelectionState::default();
        sel.click(SelectionMode::Multi, &order, 2, false, false);
        sel.step(SelectionMode::Multi, &order, 1, true);
        sel.step(SelectionMode::Multi, &order, 1, true);
        assert_eq!(sel.selected(), vec![2, 3, 4]);
        // Un-extending walks the range back.
        sel.step(SelectionMode::Multi, &order, -1, true);
        assert_eq!(sel.selected(), vec![2, 3]);
    }

    #[test]
    fn clear_and_retain_report_changes() {
        let order = identity_order(4);
        let mut sel = SelectionState::default();
        assert!(!sel.clear());
        sel.click(SelectionMode::Multi, &order, 1, false, false);
        sel.click(SelectionMode::Multi, &order, 3, true, false);
        assert!(sel.retain_below(2)); // drops source 3
        assert_eq!(sel.selected(), vec![1]);
        assert!(!sel.retain_below(2));
        assert!(sel.clear());
        assert_eq!(sel.cursor(), None);
    }
}