envision 0.15.1

//! A component for displaying keyboard shortcuts.
//!
//! [`KeyHints`] provides a bar displaying keyboard shortcuts with their actions,
//! commonly used at the bottom of TUI applications to show available commands.
//! State is stored in [`KeyHintsState`] and updated via [`KeyHintsMessage`].
//!
//! # Example
//!
//! ```rust
//! use envision::component::{KeyHints, KeyHint, KeyHintsState, KeyHintsLayout, Component};
//!
//! // Create hints using builder pattern
//! let state = KeyHintsState::new()
//!     .hint("Enter", "Select")
//!     .hint("q", "Quit")
//!     .hint("?", "Help");
//!
//! // Or create with a vector
//! let hints = vec![
//!     KeyHint::new("↑/k", "Up"),
//!     KeyHint::new("↓/j", "Down"),
//!     KeyHint::new("Enter", "Select"),
//! ];
//! let state = KeyHintsState::with_hints(hints);
//! ```

use ratatui::prelude::*;
use ratatui::widgets::Paragraph;

use super::{Component, RenderContext};

/// Layout style for key hints display.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub enum KeyHintsLayout {
    /// Hints are displayed with even spacing.
    #[default]
    Spaced,
    /// Hints are displayed inline with minimal spacing.
    Inline,
}

/// A single keyboard hint entry.
///
/// Represents a key-action pair that tells the user what a key does.
///
/// # Example
///
/// ```rust
/// use envision::component::KeyHint;
///
/// let hint = KeyHint::new("Ctrl+S", "Save")
///     .with_priority(1)
///     .with_enabled(true);
/// ```
#[derive(Clone, Debug, PartialEq, Eq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct KeyHint {
    /// The key or key combination.
    key: String,
    /// The action description.
    action: String,
    /// Whether this hint is enabled/visible.
    enabled: bool,
    /// Priority for responsive hiding (lower = more important, shown first).
    priority: u8,
}

impl KeyHint {
    /// Creates a new key hint.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("Enter", "Select");
    /// assert_eq!(hint.key(), "Enter");
    /// assert_eq!(hint.action(), "Select");
    /// ```
    pub fn new(key: impl Into<String>, action: impl Into<String>) -> Self {
        Self {
            key: key.into(),
            action: action.into(),
            enabled: true,
            priority: 100,
        }
    }

    /// Sets the priority for responsive hiding.
    ///
    /// Lower priority values are more important and will be shown first
    /// when space is limited.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("q", "Quit").with_priority(1);
    /// assert_eq!(hint.priority(), 1);
    /// ```
    pub fn with_priority(mut self, priority: u8) -> Self {
        self.priority = priority;
        self
    }

    /// Sets whether the hint is enabled.
    ///
    /// Disabled hints are not displayed.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("Delete", "Remove").with_enabled(false);
    /// assert!(!hint.is_enabled());
    /// ```
    pub fn with_enabled(mut self, enabled: bool) -> Self {
        self.enabled = enabled;
        self
    }

    /// Returns the key string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("Ctrl+S", "Save");
    /// assert_eq!(hint.key(), "Ctrl+S");
    /// ```
    pub fn key(&self) -> &str {
        &self.key
    }

    /// Returns the action description.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("Enter", "Select");
    /// assert_eq!(hint.action(), "Select");
    /// ```
    pub fn action(&self) -> &str {
        &self.action
    }

    /// Returns whether the hint is enabled.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("q", "Quit");
    /// assert!(hint.is_enabled()); // enabled by default
    /// ```
    pub fn is_enabled(&self) -> bool {
        self.enabled
    }

    /// Returns the priority value.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let hint = KeyHint::new("q", "Quit").with_priority(5);
    /// assert_eq!(hint.priority(), 5);
    /// ```
    pub fn priority(&self) -> u8 {
        self.priority
    }

    /// Sets the key string.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let mut hint = KeyHint::new("Enter", "Select");
    /// hint.set_key("Return");
    /// assert_eq!(hint.key(), "Return");
    /// ```
    pub fn set_key(&mut self, key: impl Into<String>) {
        self.key = key.into();
    }

    /// Sets the action description.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let mut hint = KeyHint::new("q", "Quit");
    /// hint.set_action("Exit");
    /// assert_eq!(hint.action(), "Exit");
    /// ```
    pub fn set_action(&mut self, action: impl Into<String>) {
        self.action = action.into();
    }

    /// Sets whether the hint is enabled.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let mut hint = KeyHint::new("Delete", "Remove");
    /// hint.set_enabled(false);
    /// assert!(!hint.is_enabled());
    /// ```
    pub fn set_enabled(&mut self, enabled: bool) {
        self.enabled = enabled;
    }

    /// Sets the priority.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHint;
    ///
    /// let mut hint = KeyHint::new("q", "Quit");
    /// hint.set_priority(5);
    /// assert_eq!(hint.priority(), 5);
    /// ```
    pub fn set_priority(&mut self, priority: u8) {
        self.priority = priority;
    }
}

/// Messages that can be sent to a KeyHints component.
#[derive(Clone, Debug, PartialEq)]
pub enum KeyHintsMessage {
    /// Set all hints at once.
    SetHints(Vec<KeyHint>),
    /// Add a single hint.
    AddHint(KeyHint),
    /// Remove a hint by key.
    RemoveHint(String),
    /// Enable a hint by key.
    EnableHint(String),
    /// Disable a hint by key.
    DisableHint(String),
    /// Set the layout style.
    SetLayout(KeyHintsLayout),
    /// Clear all hints.
    Clear,
}

/// State for a KeyHints component.
///
/// Contains all hints and display configuration.
///
/// # Example
///
/// ```rust
/// use envision::component::{KeyHintsState, KeyHintsLayout};
///
/// let state = KeyHintsState::new()
///     .with_layout(KeyHintsLayout::Inline)
///     .hint("Enter", "Select")
///     .hint("Esc", "Cancel");
/// ```
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct KeyHintsState {
    /// All key hints.
    hints: Vec<KeyHint>,
    /// Layout style.
    layout: KeyHintsLayout,
    /// Separator between key and action (default: " ").
    key_action_separator: String,
    /// Separator between hints (default: "  ").
    hint_separator: String,
    /// Key style.
    key_style: Style,
    /// Action style.
    action_style: Style,
    /// Whether the component is disabled.
    disabled: bool,
}

impl Default for KeyHintsState {
    fn default() -> Self {
        Self {
            hints: Vec::new(),
            layout: KeyHintsLayout::default(),
            key_action_separator: " ".to_string(),
            hint_separator: "  ".to_string(),
            key_style: Style::default().fg(Color::Green),
            action_style: Style::default(),
            disabled: false,
        }
    }
}

impl KeyHintsState {
    /// Creates a new empty KeyHints state.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new();
    /// assert!(state.is_empty());
    /// ```
    pub fn new() -> Self {
        Self::default()
    }

    /// Creates a new state with the given hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHint};
    ///
    /// let hints = vec![KeyHint::new("q", "Quit")];
    /// let state = KeyHintsState::with_hints(hints);
    /// assert_eq!(state.len(), 1);
    /// ```
    pub fn with_hints(hints: Vec<KeyHint>) -> Self {
        Self {
            hints,
            ..Self::default()
        }
    }

    /// Sets the layout style.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHintsLayout};
    ///
    /// let state = KeyHintsState::new().with_layout(KeyHintsLayout::Inline);
    /// assert_eq!(state.layout(), KeyHintsLayout::Inline);
    /// ```
    pub fn with_layout(mut self, layout: KeyHintsLayout) -> Self {
        self.layout = layout;
        self
    }

    /// Sets the separator between key and action.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new()
    ///     .with_key_action_separator(": ")
    ///     .hint("Enter", "Select");
    /// assert_eq!(state.len(), 1);
    /// ```
    pub fn with_key_action_separator(mut self, sep: impl Into<String>) -> Self {
        self.key_action_separator = sep.into();
        self
    }

    /// Sets the separator between hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new()
    ///     .with_hint_separator(" | ")
    ///     .hint("q", "Quit")
    ///     .hint("Enter", "Select");
    /// assert_eq!(state.len(), 2);
    /// ```
    pub fn with_hint_separator(mut self, sep: impl Into<String>) -> Self {
        self.hint_separator = sep.into();
        self
    }

    /// Sets the style for keys.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    /// use ratatui::style::{Style, Color};
    ///
    /// let state = KeyHintsState::new().with_key_style(Style::default().fg(Color::Yellow));
    /// assert_eq!(state.key_style(), Style::default().fg(Color::Yellow));
    /// ```
    pub fn with_key_style(mut self, style: Style) -> Self {
        self.key_style = style;
        self
    }

    /// Sets the style for actions.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    /// use ratatui::style::{Style, Color};
    ///
    /// let state = KeyHintsState::new().with_action_style(Style::default().fg(Color::White));
    /// assert_eq!(state.action_style(), Style::default().fg(Color::White));
    /// ```
    pub fn with_action_style(mut self, style: Style) -> Self {
        self.action_style = style;
        self
    }

    /// Adds a hint using builder pattern.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new()
    ///     .hint("Enter", "Select")
    ///     .hint("Esc", "Cancel")
    ///     .hint("q", "Quit");
    ///
    /// assert_eq!(state.len(), 3);
    /// ```
    pub fn hint(mut self, key: impl Into<String>, action: impl Into<String>) -> Self {
        self.hints.push(KeyHint::new(key, action));
        self
    }

    /// Adds a hint with priority using builder pattern.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new()
    ///     .hint_with_priority("q", "Quit", 1)
    ///     .hint_with_priority("Enter", "Select", 10);
    /// assert_eq!(state.visible_hints()[0].key(), "q");
    /// ```
    pub fn hint_with_priority(
        mut self,
        key: impl Into<String>,
        action: impl Into<String>,
        priority: u8,
    ) -> Self {
        self.hints
            .push(KeyHint::new(key, action).with_priority(priority));
        self
    }

    /// Returns all hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new().hint("q", "Quit").hint("Enter", "Select");
    /// assert_eq!(state.hints().len(), 2);
    /// ```
    pub fn hints(&self) -> &[KeyHint] {
        &self.hints
    }

    /// Returns only enabled hints, sorted by priority.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new()
    ///     .hint("q", "Quit")
    ///     .hint("Delete", "Remove")
    ///     .with_disabled(false);
    /// assert_eq!(state.visible_hints().len(), 2);
    /// ```
    pub fn visible_hints(&self) -> Vec<&KeyHint> {
        let mut visible: Vec<_> = self.hints.iter().filter(|h| h.enabled).collect();
        visible.sort_by_key(|h| h.priority);
        visible
    }

    /// Returns the layout style.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHintsLayout};
    ///
    /// let state = KeyHintsState::new().with_layout(KeyHintsLayout::Spaced);
    /// assert_eq!(state.layout(), KeyHintsLayout::Spaced);
    /// ```
    pub fn layout(&self) -> KeyHintsLayout {
        self.layout
    }

    /// Returns the number of hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new().hint("q", "Quit").hint("Enter", "Select");
    /// assert_eq!(state.len(), 2);
    /// ```
    pub fn len(&self) -> usize {
        self.hints.len()
    }

    /// Returns true if there are no hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new();
    /// assert!(state.is_empty());
    /// ```
    pub fn is_empty(&self) -> bool {
        self.hints.is_empty()
    }

    /// Sets the hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHint};
    ///
    /// let mut state = KeyHintsState::new().hint("q", "Quit");
    /// state.set_hints(vec![KeyHint::new("Enter", "Select"), KeyHint::new("Esc", "Cancel")]);
    /// assert_eq!(state.len(), 2);
    /// ```
    pub fn set_hints(&mut self, hints: Vec<KeyHint>) {
        self.hints = hints;
    }

    /// Adds a hint.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHint};
    ///
    /// let mut state = KeyHintsState::new();
    /// state.add_hint(KeyHint::new("q", "Quit"));
    /// assert_eq!(state.len(), 1);
    /// ```
    pub fn add_hint(&mut self, hint: KeyHint) {
        self.hints.push(hint);
    }

    /// Removes a hint by key.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let mut state = KeyHintsState::new().hint("q", "Quit").hint("Enter", "Select");
    /// state.remove_hint("q");
    /// assert_eq!(state.len(), 1);
    /// assert_eq!(state.hints()[0].key(), "Enter");
    /// ```
    pub fn remove_hint(&mut self, key: &str) {
        self.hints.retain(|h| h.key != key);
    }

    /// Enables a hint by key.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHint};
    ///
    /// let mut state = KeyHintsState::new()
    ///     .hint("Delete", "Remove");
    /// state.disable_hint("Delete");
    /// state.enable_hint("Delete");
    /// assert!(state.hints()[0].is_enabled());
    /// ```
    pub fn enable_hint(&mut self, key: &str) {
        if let Some(hint) = self.hints.iter_mut().find(|h| h.key == key) {
            hint.enabled = true;
        }
    }

    /// Disables a hint by key.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let mut state = KeyHintsState::new().hint("Delete", "Remove");
    /// state.disable_hint("Delete");
    /// assert!(!state.hints()[0].is_enabled());
    /// ```
    pub fn disable_hint(&mut self, key: &str) {
        if let Some(hint) = self.hints.iter_mut().find(|h| h.key == key) {
            hint.enabled = false;
        }
    }

    /// Sets the layout.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::{KeyHintsState, KeyHintsLayout};
    ///
    /// let mut state = KeyHintsState::new();
    /// state.set_layout(KeyHintsLayout::Inline);
    /// assert_eq!(state.layout(), KeyHintsLayout::Inline);
    /// ```
    pub fn set_layout(&mut self, layout: KeyHintsLayout) {
        self.layout = layout;
    }

    /// Clears all hints.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let mut state = KeyHintsState::new().hint("q", "Quit").hint("Enter", "Select");
    /// state.clear();
    /// assert!(state.is_empty());
    /// ```
    pub fn clear(&mut self) {
        self.hints.clear();
    }

    /// Returns the key style.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    /// use ratatui::style::{Style, Color};
    ///
    /// let state = KeyHintsState::new().with_key_style(Style::default().fg(Color::Blue));
    /// assert_eq!(state.key_style(), Style::default().fg(Color::Blue));
    /// ```
    pub fn key_style(&self) -> Style {
        self.key_style
    }

    /// Returns the action style.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    /// use ratatui::style::Style;
    ///
    /// let state = KeyHintsState::new();
    /// assert_eq!(state.action_style(), Style::default());
    /// ```
    pub fn action_style(&self) -> Style {
        self.action_style
    }

    /// Sets the key style.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    /// use ratatui::style::{Style, Color};
    ///
    /// let mut state = KeyHintsState::new();
    /// state.set_key_style(Style::default().fg(Color::Cyan));
    /// assert_eq!(state.key_style(), Style::default().fg(Color::Cyan));
    /// ```
    pub fn set_key_style(&mut self, style: Style) {
        self.key_style = style;
    }

    /// Sets the action style.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    /// use ratatui::style::{Style, Color};
    ///
    /// let mut state = KeyHintsState::new();
    /// state.set_action_style(Style::default().fg(Color::Gray));
    /// assert_eq!(state.action_style(), Style::default().fg(Color::Gray));
    /// ```
    pub fn set_action_style(&mut self, style: Style) {
        self.action_style = style;
    }

    /// Returns true if the key hints are disabled.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new();
    /// assert!(!state.is_disabled());
    /// ```
    pub fn is_disabled(&self) -> bool {
        self.disabled
    }

    /// Sets the disabled state.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let mut state = KeyHintsState::new();
    /// state.set_disabled(true);
    /// assert!(state.is_disabled());
    /// ```
    pub fn set_disabled(&mut self, disabled: bool) {
        self.disabled = disabled;
    }

    /// Sets the disabled state using builder pattern.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::KeyHintsState;
    ///
    /// let state = KeyHintsState::new()
    ///     .with_disabled(true);
    /// assert!(state.is_disabled());
    /// ```
    pub fn with_disabled(mut self, disabled: bool) -> Self {
        self.disabled = disabled;
        self
    }
}

/// A component for displaying keyboard shortcuts.
///
/// `KeyHints` displays a row of key-action pairs, typically shown at the
/// bottom of a TUI to inform users of available commands.
///
/// # Visual Format
///
/// ```text
/// Spaced:  Enter Select    Esc Cancel    q Quit
/// Inline:  Enter Select  Esc Cancel  q Quit
/// ```
///
/// # Example
///
/// ```rust
/// use envision::component::{KeyHints, KeyHintsState, KeyHintsMessage, Component};
///
/// let mut state = KeyHintsState::new()
///     .hint("Enter", "Select")
///     .hint("q", "Quit");
///
/// // Disable a hint dynamically
/// KeyHints::update(&mut state, KeyHintsMessage::DisableHint("q".to_string()));
/// ```
pub struct KeyHints;

impl Component for KeyHints {
    type State = KeyHintsState;
    type Message = KeyHintsMessage;
    type Output = ();

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

    fn update(state: &mut Self::State, msg: Self::Message) -> Option<Self::Output> {
        match msg {
            KeyHintsMessage::SetHints(hints) => {
                state.hints = hints;
            }
            KeyHintsMessage::AddHint(hint) => {
                state.hints.push(hint);
            }
            KeyHintsMessage::RemoveHint(key) => {
                state.hints.retain(|h| h.key != key);
            }
            KeyHintsMessage::EnableHint(key) => {
                if let Some(hint) = state.hints.iter_mut().find(|h| h.key == key) {
                    hint.enabled = true;
                }
            }
            KeyHintsMessage::DisableHint(key) => {
                if let Some(hint) = state.hints.iter_mut().find(|h| h.key == key) {
                    hint.enabled = false;
                }
            }
            KeyHintsMessage::SetLayout(layout) => {
                state.layout = layout;
            }
            KeyHintsMessage::Clear => {
                state.hints.clear();
            }
        }
        None // Display-only, no output
    }

    fn view(state: &Self::State, ctx: &mut RenderContext<'_, '_>) {
        if state.hints.is_empty() || ctx.area.width == 0 || ctx.area.height == 0 {
            return;
        }

        let visible = state.visible_hints();
        if visible.is_empty() {
            return;
        }

        let mut spans = Vec::new();

        // Use ctx.theme for key style (focused/success color for keys)
        let key_style = if state.key_style == Style::default().fg(Color::Green) {
            ctx.theme.success_style()
        } else {
            state.key_style
        };

        for (i, hint) in visible.iter().enumerate() {
            if i > 0 {
                spans.push(Span::raw(&state.hint_separator));
            }

            spans.push(Span::styled(&hint.key, key_style));
            spans.push(Span::raw(&state.key_action_separator));
            spans.push(Span::styled(&hint.action, state.action_style));
        }

        let line = Line::from(spans);
        let alignment = match state.layout {
            KeyHintsLayout::Spaced => Alignment::Center,
            KeyHintsLayout::Inline => Alignment::Left,
        };

        let paragraph = Paragraph::new(line).alignment(alignment);

        let annotation =
            crate::annotation::Annotation::new(crate::annotation::WidgetType::KeyHints)
                .with_id("key_hints");
        let annotated = crate::annotation::Annotate::new(paragraph, annotation);
        ctx.frame.render_widget(annotated, ctx.area);
    }
}

#[cfg(test)]
mod tests;