envision 0.16.0

//! A generic selectable list component with keyboard navigation.
//!
//! [`SelectableList<T>`] provides a scrollable list of items with selection
//! tracking and keyboard navigation (vim-style and arrow keys). State is
//! stored in [`SelectableListState<T>`], updated via [`SelectableListMessage`],
//! and produces [`SelectableListOutput`].
//!
//!
//! See also [`SearchableList`](super::SearchableList) for a filterable variant,
//! and [`LoadingList`](super::LoadingList) for lists with loading states.
//!
//! # Example
//!
//! ```rust
//! use envision::component::{Component, SelectableListMessage, SelectableList, SelectableListState};
//!
//! // Create a list of items
//! let mut state = SelectableList::<String>::init();
//! state.set_items(vec!["Item 1".into(), "Item 2".into(), "Item 3".into()]);
//!
//! // Navigate down
//! SelectableList::<String>::update(&mut state, SelectableListMessage::Down);
//! assert_eq!(state.selected_index(), Some(1));
//!
//! // Get selected item
//! assert_eq!(state.selected_item(), Some(&"Item 2".into()));
//! ```

use ratatui::widgets::{Block, Borders, List, ListItem, ListState};

use super::{Component, EventContext, RenderContext};
use crate::input::{Event, Key};
use crate::scroll::ScrollState;

/// Messages that can be sent to a SelectableList.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SelectableListMessage {
    /// Move selection up by one.
    Up,
    /// Move selection down by one.
    Down,
    /// Move selection to the first item.
    First,
    /// Move selection to the last item.
    Last,
    /// Move selection up by a page.
    PageUp(usize),
    /// Move selection down by a page.
    PageDown(usize),
    /// Select the current item (triggers output).
    Select,
    /// Set the filter text for searching items.
    SetFilter(String),
    /// Clear the filter text.
    ClearFilter,
}

/// Output messages from a SelectableList.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SelectableListOutput<T: Clone> {
    /// An item was selected (e.g., Enter pressed).
    Selected(T),
    /// The selection changed to a new index (original item index).
    SelectionChanged(usize),
    /// The filter text changed.
    FilterChanged(String),
}

/// State for a SelectableList component.
#[derive(Clone, Debug)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct SelectableListState<T: Clone> {
    items: Vec<T>,
    #[cfg_attr(feature = "serialization", serde(skip))]
    list_state: ListState,
    filter_text: String,
    filtered_indices: Vec<usize>,
    #[cfg_attr(feature = "serialization", serde(skip))]
    scroll: ScrollState,
}

impl<T: Clone + PartialEq> PartialEq for SelectableListState<T> {
    fn eq(&self, other: &Self) -> bool {
        self.items == other.items
            && self.list_state.selected() == other.list_state.selected()
            && self.filter_text == other.filter_text
    }
}

impl<T: Clone> Default for SelectableListState<T> {
    fn default() -> Self {
        Self {
            items: Vec::new(),
            list_state: ListState::default(),
            filter_text: String::new(),
            filtered_indices: Vec::new(),
            scroll: ScrollState::default(),
        }
    }
}

impl<T: Clone> SelectableListState<T> {
    /// Creates a new state with the given items.
    ///
    /// If the items list is non-empty, the first item is selected.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = SelectableListState::new(vec!["apple", "banana", "cherry"]);
    /// assert_eq!(state.selected_index(), Some(0));
    /// assert_eq!(state.len(), 3);
    /// ```
    pub fn new(items: Vec<T>) -> Self {
        Self::with_items(items)
    }

    /// Creates a new state with the given items.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = SelectableListState::with_items(vec![1, 2, 3]);
    /// assert_eq!(state.selected_item(), Some(&1));
    /// ```
    pub fn with_items(items: Vec<T>) -> Self {
        let filtered_indices: Vec<usize> = (0..items.len()).collect();
        let scroll = ScrollState::new(filtered_indices.len());
        let mut state = Self {
            items,
            list_state: ListState::default(),
            filter_text: String::new(),
            filtered_indices,
            scroll,
        };
        if !state.items.is_empty() {
            state.list_state.select(Some(0));
        }
        state
    }

    /// Sets the initially selected index (builder method).
    ///
    /// The index is clamped to the valid range. Has no effect on empty lists.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let state = SelectableListState::new(vec!["A", "B", "C"]).with_selected(1);
    /// assert_eq!(state.selected_index(), Some(1));
    /// assert_eq!(state.selected_item(), Some(&"B"));
    /// ```
    pub fn with_selected(mut self, index: usize) -> Self {
        if self.items.is_empty() {
            return self;
        }
        let clamped = index.min(self.items.len() - 1);
        if let Some(filtered_pos) = self.filtered_indices.iter().position(|&fi| fi == clamped) {
            self.list_state.select(Some(filtered_pos));
        }
        self
    }

    /// Returns a reference to the items.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = SelectableListState::new(vec!["a", "b", "c"]);
    /// assert_eq!(state.items(), &["a", "b", "c"]);
    /// ```
    pub fn items(&self) -> &[T] {
        &self.items
    }

    /// Sets the items, clearing any active filter and resetting selection.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let mut state = SelectableListState::new(vec!["old"]);
    /// state.set_items(vec!["new1", "new2"]);
    /// assert_eq!(state.items(), &["new1", "new2"]);
    /// assert_eq!(state.selected_index(), Some(0));
    /// ```
    pub fn set_items(&mut self, items: Vec<T>) {
        self.items = items;
        self.filter_text.clear();
        self.filtered_indices = (0..self.items.len()).collect();
        self.scroll.set_content_length(self.filtered_indices.len());
        if self.filtered_indices.is_empty() {
            self.list_state.select(None);
        } else {
            let current = self.list_state.selected().unwrap_or(0);
            let new_index = current.min(self.filtered_indices.len().saturating_sub(1));
            self.list_state.select(Some(new_index));
        }
    }

    /// Returns the currently selected index in the original items list.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = SelectableListState::new(vec!["a", "b", "c"]);
    /// assert_eq!(state.selected_index(), Some(0));
    ///
    /// let empty: SelectableListState<String> = SelectableListState::new(vec![]);
    /// assert_eq!(empty.selected_index(), None);
    /// ```
    pub fn selected_index(&self) -> Option<usize> {
        self.list_state
            .selected()
            .and_then(|i| self.filtered_indices.get(i).copied())
    }

    /// Alias for [`selected_index()`](Self::selected_index).
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let state = SelectableListState::new(vec!["a", "b", "c"]);
    /// assert_eq!(state.selected(), Some(0));
    /// ```
    pub fn selected(&self) -> Option<usize> {
        self.selected_index()
    }

    /// Returns a reference to the currently selected item.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = SelectableListState::new(vec!["a", "b", "c"]);
    /// assert_eq!(state.selected_item(), Some(&"a"));
    /// ```
    pub fn selected_item(&self) -> Option<&T> {
        self.selected_index().and_then(|i| self.items.get(i))
    }

    /// Selects the item at the given index in the original items list.
    ///
    /// If the item is filtered out, the selection is unchanged.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let mut state = SelectableListState::new(vec!["a", "b", "c"]);
    /// state.select(Some(2));
    /// assert_eq!(state.selected_index(), Some(2));
    /// assert_eq!(state.selected_item(), Some(&"c"));
    /// ```
    pub fn select(&mut self, index: Option<usize>) {
        match index {
            Some(i) if i < self.items.len() => {
                if let Some(filtered_pos) = self.filtered_indices.iter().position(|&fi| fi == i) {
                    self.list_state.select(Some(filtered_pos));
                }
            }
            Some(_) => {} // Index out of bounds, ignore
            None => self.list_state.select(None),
        }
    }

    /// Sets the selected index.
    ///
    /// Pass `Some(index)` to select an item (clamped to valid range), or
    /// `None` to clear the selection. Has no effect on empty lists when
    /// selecting.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let mut state = SelectableListState::new(vec!["a", "b", "c"]);
    /// state.set_selected(Some(2));
    /// assert_eq!(state.selected_index(), Some(2));
    /// assert_eq!(state.selected_item(), Some(&"c"));
    ///
    /// state.set_selected(None);
    /// assert_eq!(state.selected_index(), None);
    /// ```
    pub fn set_selected(&mut self, index: Option<usize>) {
        match index {
            Some(i) => {
                if self.items.is_empty() {
                    return;
                }
                let clamped = i.min(self.items.len() - 1);
                if let Some(filtered_pos) =
                    self.filtered_indices.iter().position(|&fi| fi == clamped)
                {
                    self.list_state.select(Some(filtered_pos));
                }
            }
            None => self.list_state.select(None),
        }
    }

    /// Returns true if the list is empty.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let empty: SelectableListState<i32> = SelectableListState::new(vec![]);
    /// assert!(empty.is_empty());
    ///
    /// let non_empty = SelectableListState::new(vec![1]);
    /// assert!(!non_empty.is_empty());
    /// ```
    pub fn is_empty(&self) -> bool {
        self.items.is_empty()
    }

    /// Returns the number of items in the list.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = SelectableListState::new(vec!["a", "b", "c"]);
    /// assert_eq!(state.len(), 3);
    /// ```
    pub fn len(&self) -> usize {
        self.items.len()
    }

    /// Returns the current filter text.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let state = SelectableListState::new(vec!["apple".to_string(), "banana".to_string()]);
    /// assert_eq!(state.filter_text(), "");
    /// ```
    pub fn filter_text(&self) -> &str {
        &self.filter_text
    }

    /// Returns the number of items visible after filtering.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let state = SelectableListState::new(vec!["apple".to_string(), "banana".to_string(), "cherry".to_string()]);
    /// assert_eq!(state.visible_count(), 3);
    /// ```
    pub fn visible_count(&self) -> usize {
        self.filtered_indices.len()
    }
}

impl<T: Clone + std::fmt::Display + 'static> SelectableListState<T> {
    /// Updates an item at the given index and re-applies the active filter.
    ///
    /// No-ops if the index is out of bounds. If a filter is active, the
    /// filter indices are recomputed after the mutation to ensure
    /// consistency.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let mut state = SelectableListState::new(vec!["apple".to_string(), "banana".to_string()]);
    /// state.update_item(0, |item| *item = "APPLE".to_string());
    /// assert_eq!(state.items()[0], "APPLE");
    /// ```
    pub fn update_item(&mut self, index: usize, f: impl FnOnce(&mut T)) {
        if let Some(item) = self.items.get_mut(index) {
            f(item);
            self.apply_filter();
        }
    }

    /// Pushes an item and updates filter indices.
    ///
    /// The new item is appended to the end of the list. If a filter is
    /// active, the item is checked against it and only added to the
    /// visible set if it matches.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let mut state = SelectableListState::new(vec!["apple".to_string()]);
    /// state.push_item("banana".to_string());
    /// assert_eq!(state.len(), 2);
    /// assert_eq!(state.items()[1], "banana");
    /// ```
    pub fn push_item(&mut self, item: T) {
        self.items.push(item);
        self.apply_filter();
    }

    /// Removes an item by index and updates filter indices and selection.
    ///
    /// Returns the removed item, or `None` if the index is out of bounds.
    /// Selection is adjusted to remain valid after removal.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let mut state = SelectableListState::new(vec![
    ///     "apple".to_string(), "banana".to_string(), "cherry".to_string(),
    /// ]);
    /// let removed = state.remove_item(1);
    /// assert_eq!(removed, Some("banana".to_string()));
    /// assert_eq!(state.len(), 2);
    /// assert_eq!(state.items(), &["apple".to_string(), "cherry".to_string()]);
    /// ```
    pub fn remove_item(&mut self, index: usize) -> Option<T> {
        if index >= self.items.len() {
            return None;
        }
        let item = self.items.remove(index);
        // Adjust selection if needed
        if let Some(sel) = self.list_state.selected() {
            if let Some(&orig_idx) = self.filtered_indices.get(sel) {
                if orig_idx >= self.items.len() {
                    // Selected item was at or past the end; will be fixed by apply_filter
                }
            }
        }
        self.apply_filter();
        Some(item)
    }

    /// Sets the filter text for case-insensitive substring matching.
    ///
    /// Items whose `Display` output contains the filter text (case-insensitive)
    /// are shown. Selection is preserved if the selected item remains visible,
    /// otherwise it moves to the first visible item.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let mut state = SelectableListState::new(vec!["apple".to_string(), "banana".to_string(), "cherry".to_string()]);
    /// state.set_filter_text("an");
    /// assert_eq!(state.visible_count(), 1); // only "banana" contains "an"
    /// assert_eq!(state.filter_text(), "an");
    /// ```
    pub fn set_filter_text(&mut self, text: &str) {
        self.filter_text = text.to_string();
        self.apply_filter();
    }

    /// Clears the filter, showing all items.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SelectableListState;
    ///
    /// let mut state = SelectableListState::new(vec!["apple".to_string(), "banana".to_string()]);
    /// state.set_filter_text("apple");
    /// assert_eq!(state.visible_count(), 1);
    /// state.clear_filter();
    /// assert_eq!(state.visible_count(), 2);
    /// ```
    pub fn clear_filter(&mut self) {
        self.filter_text.clear();
        self.apply_filter();
    }

    /// Recomputes filtered_indices based on the current filter_text.
    fn apply_filter(&mut self) {
        let previously_selected = self.selected_index();

        if self.filter_text.is_empty() {
            self.filtered_indices = (0..self.items.len()).collect();
        } else {
            let filter_lower = self.filter_text.to_lowercase();
            self.filtered_indices = self
                .items
                .iter()
                .enumerate()
                .filter(|(_, item)| format!("{}", item).to_lowercase().contains(&filter_lower))
                .map(|(i, _)| i)
                .collect();
        }

        self.scroll.set_content_length(self.filtered_indices.len());

        // Try to preserve the previously selected item
        if let Some(prev_idx) = previously_selected {
            if let Some(new_pos) = self.filtered_indices.iter().position(|&i| i == prev_idx) {
                self.list_state.select(Some(new_pos));
                return;
            }
        }

        // Otherwise, select first visible item or none
        if self.filtered_indices.is_empty() {
            self.list_state.select(None);
        } else {
            self.list_state.select(Some(0));
        }
    }

    /// Updates the selectable list state with a message, returning any output.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{SelectableListState, SelectableListMessage, SelectableListOutput};
    ///
    /// let mut state = SelectableListState::new(vec!["a".to_string(), "b".to_string()]);
    /// let output = state.update(SelectableListMessage::Down);
    /// assert_eq!(output, Some(SelectableListOutput::SelectionChanged(1)));
    /// ```
    pub fn update(&mut self, msg: SelectableListMessage) -> Option<SelectableListOutput<T>> {
        SelectableList::<T>::update(self, msg)
    }
}

/// A generic selectable list component.
///
/// This component provides a scrollable list with keyboard navigation.
/// It's generic over the item type `T`, which must be `Clone`.
///
/// # Navigation
///
/// - `Up` / `Down` - Move selection by one
/// - `First` / `Last` - Jump to beginning/end
/// - `PageUp` / `PageDown` - Move by page size
/// - `Select` - Emit the selected item
pub struct SelectableList<T: Clone>(std::marker::PhantomData<T>);

impl<T: Clone + std::fmt::Display + 'static> Component for SelectableList<T> {
    type State = SelectableListState<T>;
    type Message = SelectableListMessage;
    type Output = SelectableListOutput<T>;

    fn init() -> Self::State {
        SelectableListState::default()
    }

    fn handle_event(
        _state: &Self::State,
        event: &Event,
        ctx: &EventContext,
    ) -> Option<Self::Message> {
        if !ctx.focused || ctx.disabled {
            return None;
        }
        if let Some(key) = event.as_key() {
            match key.code {
                Key::Up | Key::Char('k') => Some(SelectableListMessage::Up),
                Key::Down | Key::Char('j') => Some(SelectableListMessage::Down),
                Key::Char('g') if key.modifiers.shift() => Some(SelectableListMessage::Last),
                Key::Home | Key::Char('g') => Some(SelectableListMessage::First),
                Key::End => Some(SelectableListMessage::Last),
                Key::Enter => Some(SelectableListMessage::Select),
                Key::PageUp => Some(SelectableListMessage::PageUp(10)),
                Key::PageDown => Some(SelectableListMessage::PageDown(10)),
                _ => None,
            }
        } else {
            None
        }
    }

    fn update(state: &mut Self::State, msg: Self::Message) -> Option<Self::Output> {
        match msg {
            SelectableListMessage::SetFilter(text) => {
                state.set_filter_text(&text);
                return Some(SelectableListOutput::FilterChanged(text));
            }
            SelectableListMessage::ClearFilter => {
                state.clear_filter();
                return Some(SelectableListOutput::FilterChanged(String::new()));
            }
            _ => {}
        }

        if state.filtered_indices.is_empty() {
            return None;
        }

        let len = state.filtered_indices.len();
        let current = state.list_state.selected().unwrap_or(0);

        match msg {
            SelectableListMessage::Up => {
                let new_index = current.saturating_sub(1);
                if new_index != current {
                    state.list_state.select(Some(new_index));
                    let orig = state.filtered_indices[new_index];
                    return Some(SelectableListOutput::SelectionChanged(orig));
                }
            }
            SelectableListMessage::Down => {
                let new_index = (current + 1).min(len - 1);
                if new_index != current {
                    state.list_state.select(Some(new_index));
                    let orig = state.filtered_indices[new_index];
                    return Some(SelectableListOutput::SelectionChanged(orig));
                }
            }
            SelectableListMessage::First => {
                if current != 0 {
                    state.list_state.select(Some(0));
                    let orig = state.filtered_indices[0];
                    return Some(SelectableListOutput::SelectionChanged(orig));
                }
            }
            SelectableListMessage::Last => {
                let last = len - 1;
                if current != last {
                    state.list_state.select(Some(last));
                    let orig = state.filtered_indices[last];
                    return Some(SelectableListOutput::SelectionChanged(orig));
                }
            }
            SelectableListMessage::PageUp(page_size) => {
                let new_index = current.saturating_sub(page_size);
                if new_index != current {
                    state.list_state.select(Some(new_index));
                    let orig = state.filtered_indices[new_index];
                    return Some(SelectableListOutput::SelectionChanged(orig));
                }
            }
            SelectableListMessage::PageDown(page_size) => {
                let new_index = (current + page_size).min(len - 1);
                if new_index != current {
                    state.list_state.select(Some(new_index));
                    let orig = state.filtered_indices[new_index];
                    return Some(SelectableListOutput::SelectionChanged(orig));
                }
            }
            SelectableListMessage::Select => {
                let orig = state.filtered_indices[current];
                if let Some(item) = state.items.get(orig).cloned() {
                    return Some(SelectableListOutput::Selected(item));
                }
            }
            SelectableListMessage::SetFilter(_) | SelectableListMessage::ClearFilter => {
                unreachable!("handled above")
            }
        }

        None
    }

    fn view(state: &Self::State, ctx: &mut RenderContext<'_, '_>) {
        crate::annotation::with_registry(|reg| {
            let mut ann = crate::annotation::Annotation::list("selectable_list")
                .with_focus(ctx.focused)
                .with_disabled(ctx.disabled);
            if let Some(idx) = state.selected_index() {
                ann = ann.with_selected(true).with_value(idx.to_string());
            }
            reg.register(ctx.area, ann);
        });

        let mut items = Vec::with_capacity(state.filtered_indices.len());
        for &idx in &state.filtered_indices {
            items.push(ListItem::new(state.items[idx].to_string()));
        }

        let highlight_style = if ctx.disabled {
            ctx.theme.disabled_style()
        } else {
            ctx.theme.selected_highlight_style(ctx.focused)
        };

        let block = Block::default().borders(Borders::ALL);
        let inner = block.inner(ctx.area);

        let list = List::new(items)
            .block(block)
            .highlight_style(highlight_style)
            .highlight_symbol("> ");

        // We need to clone the state for rendering since StatefulWidget needs &mut
        let mut list_state = state.list_state.clone();
        ctx.frame
            .render_stateful_widget(list, ctx.area, &mut list_state);

        // Render scrollbar when content exceeds viewport
        if state.filtered_indices.len() > inner.height as usize {
            let mut bar_scroll = ScrollState::new(state.filtered_indices.len());
            bar_scroll.set_viewport_height(inner.height as usize);
            bar_scroll.set_offset(list_state.offset());
            crate::scroll::render_scrollbar_inside_border(
                &bar_scroll,
                ctx.frame,
                ctx.area,
                ctx.theme,
            );
        }
    }
}

#[cfg(test)]
mod tests;