envision 0.16.0

//! A horizontal menu bar component.
//!
//! [`Menu`] provides a horizontal menu bar for application commands and navigation.
//! It supports keyboard navigation, item activation, and disabled states. State is
//! stored in [`MenuState`], updated via [`MenuMessage`], and produces [`MenuOutput`].
//! Items are configured with [`MenuItem`].
//!
//!
//! # Example
//!
//! ```rust
//! use envision::component::{Menu, MenuMessage, MenuOutput, MenuState, MenuItem, Component};
//!
//! // Create a menu
//! let mut state = MenuState::new(vec![
//!     MenuItem::new("File"),
//!     MenuItem::new("Edit"),
//!     MenuItem::new("View"),
//! ]);
//!
//! // Activate
//! let output = Menu::update(&mut state, MenuMessage::Select);
//! assert_eq!(output, Some(MenuOutput::Selected(0)));
//! ```

use ratatui::widgets::Paragraph;

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

/// A menu item.
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct MenuItem {
    label: String,
    enabled: bool,
}

impl MenuItem {
    /// Returns the item label.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::MenuItem;
    ///
    /// let item = MenuItem::new("Edit");
    /// assert_eq!(item.label(), "Edit");
    /// ```
    pub fn label(&self) -> &str {
        &self.label
    }

    /// Returns whether the item is enabled.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::MenuItem;
    ///
    /// let enabled = MenuItem::new("File");
    /// assert!(enabled.is_enabled());
    ///
    /// let disabled = MenuItem::disabled("Save");
    /// assert!(!disabled.is_enabled());
    /// ```
    pub fn is_enabled(&self) -> bool {
        self.enabled
    }

    /// Sets the item label.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::MenuItem;
    ///
    /// let mut item = MenuItem::new("File");
    /// item.set_label("Edit");
    /// assert_eq!(item.label(), "Edit");
    /// ```
    pub fn set_label(&mut self, label: impl Into<String>) {
        self.label = label.into();
    }

    /// Creates a new enabled menu item.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::MenuItem;
    ///
    /// let item = MenuItem::new("File");
    /// assert_eq!(item.label(), "File");
    /// assert!(item.is_enabled());
    /// ```
    pub fn new(label: impl Into<String>) -> Self {
        Self {
            label: label.into(),
            enabled: true,
        }
    }

    /// Creates a new disabled menu item.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::MenuItem;
    ///
    /// let item = MenuItem::disabled("Save");
    /// assert!(!item.is_enabled());
    /// ```
    pub fn disabled(label: impl Into<String>) -> Self {
        Self {
            label: label.into(),
            enabled: false,
        }
    }

    /// Sets whether this item is enabled.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::MenuItem;
    ///
    /// let mut item = MenuItem::new("Save");
    /// item.set_enabled(false);
    /// assert!(!item.is_enabled());
    /// ```
    pub fn set_enabled(&mut self, enabled: bool) {
        self.enabled = enabled;
    }
}

/// Messages that can be sent to a Menu.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum MenuMessage {
    /// Move to the next (right) menu item.
    Right,
    /// Move to the previous (left) menu item.
    Left,
    /// Select the currently highlighted item.
    Select,
    /// Select a specific item by index.
    SelectIndex(usize),
}

/// Output messages from a Menu.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum MenuOutput {
    /// A menu item was selected (contains the item index).
    Selected(usize),
    /// The selection changed during navigation (contains the new item index).
    SelectionChanged(usize),
}

/// State for a Menu component.
#[derive(Clone, Debug, Default, PartialEq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct MenuState {
    /// Menu items.
    items: Vec<MenuItem>,
    /// Currently selected item index, or `None` if no items.
    selected_index: Option<usize>,
}

impl MenuState {
    /// Creates a new menu with the given items.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuState, MenuItem};
    ///
    /// let state = MenuState::new(vec![
    ///     MenuItem::new("File"),
    ///     MenuItem::new("Edit"),
    /// ]);
    /// assert_eq!(state.items().len(), 2);
    /// ```
    pub fn new(items: Vec<MenuItem>) -> Self {
        let selected_index = if items.is_empty() { None } else { Some(0) };
        Self {
            items,
            selected_index,
        }
    }

    /// Returns the menu items.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = MenuState::new(vec![
    ///     MenuItem::new("File"),
    ///     MenuItem::new("Edit"),
    /// ]);
    /// assert_eq!(state.items().len(), 2);
    /// assert_eq!(state.items()[0].label(), "File");
    /// ```
    pub fn items(&self) -> &[MenuItem] {
        &self.items
    }

    /// Sets the menu items.
    ///
    /// Resets selection to the first item if the current selection is out of bounds.
    /// Sets selection to `None` if the new items list is empty.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuState, MenuItem};
    ///
    /// let mut state = MenuState::new(vec![MenuItem::new("File")]);
    /// state.set_items(vec![MenuItem::new("A"), MenuItem::new("B"), MenuItem::new("C")]);
    /// assert_eq!(state.items().len(), 3);
    /// ```
    pub fn set_items(&mut self, items: Vec<MenuItem>) {
        self.items = items;
        if self.items.is_empty() {
            self.selected_index = None;
        } else if self.selected_index.is_none_or(|i| i >= self.items.len()) {
            self.selected_index = Some(0);
        }
    }

    /// Adds a menu item.
    ///
    /// If this is the first item, it becomes selected.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuState, MenuItem};
    ///
    /// let mut state = MenuState::new(vec![MenuItem::new("File")]);
    /// state.add_item(MenuItem::new("Edit"));
    /// assert_eq!(state.items().len(), 2);
    /// ```
    pub fn add_item(&mut self, item: MenuItem) {
        self.items.push(item);
        if self.selected_index.is_none() {
            self.selected_index = Some(0);
        }
    }

    /// Removes a menu item by index.
    ///
    /// If the index is out of bounds, this is a no-op.
    /// Adjusts the selection after removal:
    /// - If the removed item was the selected item, selects the previous item
    ///   (or the first if at the beginning).
    /// - If the menu becomes empty, selection becomes `None`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuState, MenuItem};
    ///
    /// let mut state = MenuState::new(vec![
    ///     MenuItem::new("File"),
    ///     MenuItem::new("Edit"),
    ///     MenuItem::new("View"),
    /// ]);
    /// state.remove_item(1);
    /// assert_eq!(state.items().len(), 2);
    /// ```
    pub fn remove_item(&mut self, index: usize) {
        if index >= self.items.len() {
            return;
        }
        self.items.remove(index);
        if self.items.is_empty() {
            self.selected_index = None;
        } else if let Some(selected) = self.selected_index {
            if selected >= self.items.len() {
                self.selected_index = Some(self.items.len() - 1);
            }
        }
    }

    /// Returns the currently selected item index.
    ///
    /// Returns `None` if the menu is empty.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = MenuState::new(vec![MenuItem::new("File"), MenuItem::new("Edit")]);
    /// assert_eq!(state.selected_index(), Some(0));
    ///
    /// let empty = MenuState::new(vec![]);
    /// assert_eq!(empty.selected_index(), None);
    /// ```
    pub fn selected_index(&self) -> Option<usize> {
        self.selected_index
    }

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

    /// Sets the selected item index.
    ///
    /// Pass `Some(index)` to select an item (clamped to valid range), or
    /// `None` to clear the selection. Has no effect on an empty menu when
    /// selecting.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuState, MenuItem};
    ///
    /// let mut state = MenuState::new(vec![
    ///     MenuItem::new("File"),
    ///     MenuItem::new("Edit"),
    ///     MenuItem::new("View"),
    /// ]);
    /// 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.items.is_empty() {
                    self.selected_index = Some(i.min(self.items.len() - 1));
                }
            }
            None => self.selected_index = None,
        }
    }

    /// Sets the selected item index (builder method).
    ///
    /// If the index is out of bounds, it will be clamped to the valid range.
    /// Has no effect on an empty menu.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuState, MenuItem};
    ///
    /// let state = MenuState::new(vec![
    ///     MenuItem::new("File"),
    ///     MenuItem::new("Edit"),
    ///     MenuItem::new("View"),
    /// ]).with_selected(1);
    /// assert_eq!(state.selected_index(), Some(1));
    /// ```
    pub fn with_selected(mut self, index: usize) -> Self {
        self.set_selected(Some(index));
        self
    }

    /// Returns the currently selected item.
    ///
    /// # Examples
    ///
    /// ```
    /// use envision::prelude::*;
    ///
    /// let state = MenuState::new(vec![MenuItem::new("File"), MenuItem::new("Edit")]);
    /// assert_eq!(state.selected_item().unwrap().label(), "File");
    /// ```
    pub fn selected_item(&self) -> Option<&MenuItem> {
        self.items.get(self.selected_index?)
    }

    /// Updates the menu state with a message, returning any output.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{MenuMessage, MenuOutput, MenuState, MenuItem};
    ///
    /// let mut state = MenuState::new(vec![
    ///     MenuItem::new("File"),
    ///     MenuItem::new("Edit"),
    /// ]);
    /// let output = state.update(MenuMessage::Right);
    /// assert_eq!(output, Some(MenuOutput::SelectionChanged(1)));
    /// ```
    pub fn update(&mut self, msg: MenuMessage) -> Option<MenuOutput> {
        Menu::update(self, msg)
    }
}

/// A horizontal menu bar component.
///
/// This component provides a horizontal menu bar for application commands
/// and navigation. Items can be navigated with Left/Right arrows and
/// activated with Enter.
///
/// # Keyboard Navigation
///
/// The menu itself doesn't handle keyboard events directly. Your application
/// should map:
/// - Right arrow to [`MenuMessage::Right`]
/// - Left arrow to [`MenuMessage::Left`]
/// - Enter to [`MenuMessage::Select`]
///
/// # Visual Layout
///
/// ```text
/// File  Edit  View  Help
/// ^^^^
/// └── Selected item (highlighted)
/// ```
///
/// # Example
///
/// ```rust
/// use envision::component::{Menu, MenuMessage, MenuOutput, MenuState, MenuItem, Component};
///
/// let mut state = MenuState::new(vec![
///     MenuItem::new("New"),
///     MenuItem::new("Open"),
///     MenuItem::disabled("Save"),
/// ]);
///
/// // Navigate
/// Menu::update(&mut state, MenuMessage::Right);
///
/// // Select
/// let output = Menu::update(&mut state, MenuMessage::Select);
/// assert_eq!(output, Some(MenuOutput::Selected(1)));
/// ```
pub struct Menu;

impl Component for Menu {
    type State = MenuState;
    type Message = MenuMessage;
    type Output = MenuOutput;

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

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

        let selected = state.selected_index?;

        match msg {
            MenuMessage::Right => {
                // Move to next item, wrapping around
                let new_index = (selected + 1) % state.items.len();
                state.selected_index = Some(new_index);
                Some(MenuOutput::SelectionChanged(new_index))
            }
            MenuMessage::Left => {
                // Move to previous item, wrapping around
                let new_index = if selected == 0 {
                    state.items.len() - 1
                } else {
                    selected - 1
                };
                state.selected_index = Some(new_index);
                Some(MenuOutput::SelectionChanged(new_index))
            }
            MenuMessage::Select => {
                // Activate only if item is enabled
                if let Some(item) = state.items.get(selected) {
                    if item.is_enabled() {
                        Some(MenuOutput::Selected(selected))
                    } else {
                        None
                    }
                } else {
                    None
                }
            }
            MenuMessage::SelectIndex(index) => {
                if index < state.items.len() && state.selected_index != Some(index) {
                    state.selected_index = Some(index);
                    Some(MenuOutput::SelectionChanged(index))
                } else {
                    None
                }
            }
        }
    }

    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 => Some(MenuMessage::Left),
                Key::Right => Some(MenuMessage::Right),
                Key::Enter => Some(MenuMessage::Select),
                _ => None,
            }
        } else {
            None
        }
    }

    fn view(state: &Self::State, ctx: &mut RenderContext<'_, '_>) {
        let mut menu_text = String::new();

        for (idx, item) in state.items.iter().enumerate() {
            if idx > 0 {
                menu_text.push_str("  ");
            }

            let item_text = if Some(idx) == state.selected_index && ctx.focused {
                format!("[{}]", item.label())
            } else {
                item.label().to_string()
            };

            menu_text.push_str(&item_text);
        }

        // Determine style based on state
        let style = if ctx.disabled {
            ctx.theme.disabled_style()
        } else if ctx.focused {
            ctx.theme.focused_style()
        } else {
            ctx.theme.normal_style()
        };

        let paragraph = Paragraph::new(menu_text).style(style);

        let annotation = crate::annotation::Annotation::new(crate::annotation::WidgetType::Menu)
            .with_id("menu")
            .with_focus(ctx.focused)
            .with_disabled(ctx.disabled);
        let annotated = crate::annotation::Annotate::new(paragraph, annotation);
        ctx.frame.render_widget(annotated, ctx.area);
    }
}

#[cfg(test)]
mod tests;