envision 0.16.0

//! A horizontal tab navigation component.
//!
//! [`Tabs<T>`] provides a horizontal tab bar for switching between views or panels.
//! It supports keyboard navigation with Left/Right keys and generic tab types.
//! State is stored in [`TabsState<T>`], updated via [`TabsMessage`], and produces
//! [`TabsOutput`].
//!
//! See also [`TabBar`](super::TabBar) for a richer variant with closable tabs,
//! modified indicators, and horizontal scrolling.
//!
//! # Example
//!
//! ```rust
//! use envision::component::{Component, Tabs, TabsState, TabsMessage, TabsOutput};
//!
//! // Create tabs with string labels
//! let mut state = TabsState::new(vec!["Home", "Settings", "Help"]);
//!
//! assert_eq!(state.selected_index(), Some(0));
//! assert_eq!(state.selected_item(), Some(&"Home"));
//!
//! // Navigate right
//! let output = Tabs::<&str>::update(&mut state, TabsMessage::Right);
//! assert_eq!(output, Some(TabsOutput::SelectionChanged(1)));
//! assert_eq!(state.selected_index(), Some(1));
//! ```

use std::fmt::Display;
use std::marker::PhantomData;

use ratatui::prelude::*;
use ratatui::widgets::{Block, Borders};

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

/// Messages that can be sent to a Tabs component.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TabsMessage {
    /// Navigate to the previous (left) tab.
    Left,
    /// Navigate to the next (right) tab.
    Right,
    /// Jump to a specific tab by index.
    Select(usize),
    /// Go to the first tab.
    First,
    /// Go to the last tab.
    Last,
    /// Confirm the current selection.
    Confirm,
}

/// Output messages from a Tabs component.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TabsOutput<T: Clone> {
    /// The selected tab changed.
    Selected(T),
    /// The current selection was confirmed.
    Confirmed(T),
    /// The selection changed during navigation (contains the new index).
    SelectionChanged(usize),
}

/// State for a Tabs component.
///
/// The state tracks the available tabs, the currently selected tab,
/// and focus/disabled states.
#[derive(Clone, Debug)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct TabsState<T: Clone> {
    /// The available tabs.
    tabs: Vec<T>,
    /// Currently selected tab index, or `None` if empty.
    selected: Option<usize>,
}

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

impl<T: Clone> Default for TabsState<T> {
    fn default() -> Self {
        Self {
            tabs: Vec::new(),
            selected: None,
        }
    }
}

impl<T: Clone> TabsState<T> {
    /// Creates a new tabs state with the first tab selected.
    ///
    /// If tabs are empty, the selection is `None`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::new(vec!["Tab1", "Tab2", "Tab3"]);
    /// assert_eq!(state.selected_index(), Some(0));
    /// assert_eq!(state.len(), 3);
    /// ```
    pub fn new(tabs: Vec<T>) -> Self {
        let selected = if tabs.is_empty() { None } else { Some(0) };
        Self { tabs, selected }
    }

    /// Creates a tabs state with a specific tab selected.
    ///
    /// The index is clamped to the valid range. Returns `None` selection
    /// for empty tabs.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::with_selected(vec!["A", "B", "C"], 1);
    /// assert_eq!(state.selected_index(), Some(1));
    /// assert_eq!(state.selected_item(), Some(&"B"));
    /// ```
    pub fn with_selected(tabs: Vec<T>, selected: usize) -> Self {
        let selected = if tabs.is_empty() {
            None
        } else {
            Some(selected.min(tabs.len() - 1))
        };
        Self { tabs, selected }
    }

    /// Returns the currently selected index.
    ///
    /// Returns `None` if there are no tabs.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::new(vec!["Home", "Settings"]);
    /// assert_eq!(state.selected_index(), Some(0));
    /// ```
    pub fn selected_index(&self) -> Option<usize> {
        self.selected
    }

    /// Alias for [`selected_index()`](Self::selected_index).
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::with_selected(vec!["A", "B", "C"], 2);
    /// assert_eq!(state.selected(), Some(2));
    /// ```
    pub fn selected(&self) -> Option<usize> {
        self.selected_index()
    }

    /// Returns the currently selected item.
    ///
    /// Returns `None` if there are no tabs or no selection.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::with_selected(vec!["Home", "Settings", "Help"], 1);
    /// assert_eq!(state.selected_item(), Some(&"Settings"));
    /// ```
    pub fn selected_item(&self) -> Option<&T> {
        self.tabs.get(self.selected?)
    }

    /// Sets the selected tab by index.
    ///
    /// Pass `Some(index)` to select a tab (clamped to valid range), or
    /// `None` to clear the selection.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let mut state = TabsState::new(vec!["A", "B", "C"]);
    /// state.set_selected(Some(2));
    /// assert_eq!(state.selected_index(), Some(2));
    /// ```
    pub fn set_selected(&mut self, index: Option<usize>) {
        match index {
            Some(i) => {
                if self.tabs.is_empty() {
                    self.selected = None;
                } else {
                    self.selected = Some(i.min(self.tabs.len() - 1));
                }
            }
            None => self.selected = None,
        }
    }

    /// Returns all tabs.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::new(vec!["Home", "Settings", "Help"]);
    /// assert_eq!(state.tabs(), &["Home", "Settings", "Help"]);
    /// ```
    pub fn tabs(&self) -> &[T] {
        &self.tabs
    }

    /// Sets the available tabs.
    ///
    /// If the current selected index would be out of bounds for the new tabs,
    /// it is clamped to the last valid index. If the new tabs are empty,
    /// the selection is set to `None`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let mut state = TabsState::new(vec!["Home", "Settings", "Help"]);
    /// assert_eq!(state.selected_index(), Some(0));
    ///
    /// state.set_tabs(vec!["Tab A", "Tab B"]);
    /// assert_eq!(state.tabs(), &["Tab A", "Tab B"]);
    /// assert_eq!(state.selected_index(), Some(0));
    /// ```
    pub fn set_tabs(&mut self, tabs: Vec<T>) {
        self.tabs = tabs;

        if self.tabs.is_empty() {
            self.selected = None;
        } else if let Some(idx) = self.selected {
            if idx >= self.tabs.len() {
                self.selected = Some(self.tabs.len() - 1);
            }
        }
    }

    /// Returns the number of tabs.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let state = TabsState::new(vec!["Tab1", "Tab2", "Tab3"]);
    /// assert_eq!(state.len(), 3);
    /// ```
    pub fn len(&self) -> usize {
        self.tabs.len()
    }

    /// Returns true if there are no tabs.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::TabsState;
    ///
    /// let empty: TabsState<&str> = TabsState::default();
    /// assert!(empty.is_empty());
    ///
    /// let state = TabsState::new(vec!["Tab1"]);
    /// assert!(!state.is_empty());
    /// ```
    pub fn is_empty(&self) -> bool {
        self.tabs.is_empty()
    }

    /// Move selection to the left (previous tab).
    ///
    /// Returns true if the selection changed.
    fn move_left(&mut self) -> bool {
        match self.selected {
            Some(idx) if idx > 0 => {
                self.selected = Some(idx - 1);
                true
            }
            _ => false,
        }
    }

    /// Move selection to the right (next tab).
    ///
    /// Returns true if the selection changed.
    fn move_right(&mut self) -> bool {
        match self.selected {
            Some(idx) if idx < self.tabs.len().saturating_sub(1) => {
                self.selected = Some(idx + 1);
                true
            }
            _ => false,
        }
    }
}

impl<T: Clone + std::fmt::Display + 'static> TabsState<T> {
    /// Updates the tabs state with a message, returning any output.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{TabsState, TabsMessage, TabsOutput};
    ///
    /// let mut state = TabsState::new(vec!["Home", "Settings"]);
    /// let output = state.update(TabsMessage::Right);
    /// assert_eq!(output, Some(TabsOutput::SelectionChanged(1)));
    /// ```
    pub fn update(&mut self, msg: TabsMessage) -> Option<TabsOutput<T>> {
        Tabs::update(self, msg)
    }
}

/// A horizontal tab navigation component.
///
/// `Tabs` provides a horizontal tab bar for switching between different views
/// or panels. Navigation is done with Left/Right keys, and the component
/// supports generic tab types that implement `Clone` and `Display`.
///
/// # Type Parameters
///
/// - `T`: The type of tab labels. Must implement `Clone` and `Display`.
///
/// # Navigation
///
/// - `Left` - Move to the previous tab
/// - `Right` - Move to the next tab
/// - `First` - Jump to the first tab
/// - `Last` - Jump to the last tab
/// - `Select(index)` - Jump to a specific tab
/// - `Confirm` - Confirm the current selection
///
/// # Output
///
/// - `SelectionChanged(usize)` - Emitted when navigation changes the selection (contains the new index)
/// - `Confirmed(T)` - Emitted when the user confirms their selection
///
/// # Example
///
/// ```rust
/// use envision::component::{Component, Tabs, TabsState, TabsMessage, TabsOutput};
///
/// // Using with string slices
/// let mut state = TabsState::new(vec!["Home", "Settings", "Help"]);
///
/// // Using with an enum
/// #[derive(Clone, Debug, PartialEq)]
/// enum Page { Home, Settings, Help }
///
/// impl std::fmt::Display for Page {
///     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
///         match self {
///             Page::Home => write!(f, "Home"),
///             Page::Settings => write!(f, "Settings"),
///             Page::Help => write!(f, "Help"),
///         }
///     }
/// }
///
/// let mut state = TabsState::new(vec![Page::Home, Page::Settings, Page::Help]);
/// let output = Tabs::<Page>::update(&mut state, TabsMessage::Right);
/// assert_eq!(output, Some(TabsOutput::SelectionChanged(1)));
/// ```
pub struct Tabs<T: Clone>(PhantomData<T>);

impl<T: Clone + Display + 'static> Component for Tabs<T> {
    type State = TabsState<T>;
    type Message = TabsMessage;
    type Output = TabsOutput<T>;

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

    fn update(state: &mut Self::State, msg: Self::Message) -> Option<Self::Output> {
        if state.tabs.is_empty() {
            return None;
        }

        let selected = state.selected?;

        match msg {
            TabsMessage::Left => {
                if state.move_left() {
                    state.selected.map(TabsOutput::SelectionChanged)
                } else {
                    None
                }
            }
            TabsMessage::Right => {
                if state.move_right() {
                    state.selected.map(TabsOutput::SelectionChanged)
                } else {
                    None
                }
            }
            TabsMessage::Select(index) => {
                let clamped = index.min(state.tabs.len().saturating_sub(1));
                if clamped != selected {
                    state.selected = Some(clamped);
                    Some(TabsOutput::SelectionChanged(clamped))
                } else {
                    None
                }
            }
            TabsMessage::First => {
                if selected != 0 {
                    state.selected = Some(0);
                    Some(TabsOutput::SelectionChanged(0))
                } else {
                    None
                }
            }
            TabsMessage::Last => {
                let last = state.tabs.len().saturating_sub(1);
                if selected != last {
                    state.selected = Some(last);
                    Some(TabsOutput::SelectionChanged(last))
                } else {
                    None
                }
            }
            TabsMessage::Confirm => state.selected_item().cloned().map(TabsOutput::Confirmed),
        }
    }

    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::Left | Key::Char('h') => Some(TabsMessage::Left),
                Key::Right | Key::Char('l') => Some(TabsMessage::Right),
                Key::Home => Some(TabsMessage::First),
                Key::End => Some(TabsMessage::Last),
                Key::Enter => Some(TabsMessage::Confirm),
                _ => None,
            }
        } else {
            None
        }
    }

    fn view(state: &Self::State, ctx: &mut RenderContext<'_, '_>) {
        let selected_idx = state.selected.unwrap_or(0);

        let titles: Vec<Line> = state
            .tabs
            .iter()
            .enumerate()
            .map(|(i, tab)| {
                let style = if ctx.disabled {
                    ctx.theme.disabled_style()
                } else if i == selected_idx {
                    ctx.theme.selected_style(ctx.focused)
                } else {
                    ctx.theme.normal_style()
                };
                Line::from(Span::styled(format!(" {} ", tab), style))
            })
            .collect();

        let border_style = if ctx.focused && !ctx.disabled {
            ctx.theme.focused_border_style()
        } else {
            ctx.theme.border_style()
        };

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

        let tabs_widget = ratatui::widgets::Tabs::new(titles)
            .block(
                Block::default()
                    .borders(Borders::ALL)
                    .border_style(border_style),
            )
            .select(selected_idx)
            .highlight_style(highlight_style);

        let annotation = crate::annotation::Annotation::new(crate::annotation::WidgetType::TabBar)
            .with_id("tabs")
            .with_focus(ctx.focused)
            .with_disabled(ctx.disabled)
            .with_selected(true)
            .with_value(selected_idx.to_string());
        let annotated = crate::annotation::Annotate::new(tabs_widget, annotation);
        ctx.frame.render_widget(annotated, ctx.area);
    }
}

#[cfg(test)]
mod tests;