envision 0.17.0

//! Types for the table component.

use ratatui::layout::Constraint;

use crate::component::cell::{Cell, RowStatus};

/// Trait for types that can be displayed as table rows.
///
/// Implement this trait for your data types to use them with `Table`.
///
/// # Example
///
/// ```rust
/// use envision::component::TableRow;
/// use envision::component::cell::Cell;
///
/// #[derive(Clone)]
/// struct Product {
///     name: String,
///     price: f64,
///     quantity: u32,
/// }
///
/// impl TableRow for Product {
///     fn cells(&self) -> Vec<Cell> {
///         vec![
///             Cell::new(&self.name),
///             Cell::new(format!("${:.2}", self.price)),
///             Cell::uint(self.quantity as u64),
///         ]
///     }
/// }
/// ```
pub trait TableRow: Clone {
    /// Returns the cells for this row, one per column.
    ///
    /// The order of cells should match the order of columns
    /// defined in the table.
    fn cells(&self) -> Vec<Cell>;

    /// Optional row-level status indicator. Default: `RowStatus::None` —
    /// no status column rendered. If any row in the table returns non-None,
    /// the status column is rendered for all rows.
    fn status(&self) -> RowStatus {
        RowStatus::None
    }
}

/// Column definition for a table.
///
/// Columns define the header text, width, and whether the column
/// is sortable.
///
/// # Example
///
/// ```rust
/// use envision::component::Column;
/// use ratatui::layout::Constraint;
///
/// let col = Column::new("Name", Constraint::Length(20)).sortable();
/// assert_eq!(col.header(), "Name");
/// assert!(col.is_sortable());
/// ```
#[derive(Clone, Debug, PartialEq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct Column {
    header: String,
    #[cfg_attr(feature = "serialization", serde(skip))]
    width: Constraint,
    sortable: bool,
    editable: bool,
    visible: bool,
    default_sort: SortDirection,
}

impl Column {
    /// Creates a new column with the given header and width.
    ///
    /// # Width semantics
    ///
    /// `Column::new` takes any `ratatui::layout::Constraint`. The most
    /// common patterns:
    ///
    /// - [`Constraint::Length`] `(n)` — a hard request for exactly `n` cells.
    /// - [`Constraint::Min`] `(n)` — a minimum of `n` cells, growing to fill
    ///   available space. Typical choice for one "flexible" column.
    /// - [`Constraint::Percentage`] `(n)` — `n%` of the resolved area,
    ///   partitioned left-to-right with the other constraints.
    ///
    /// `Length` and `Min` both declare an absolute floor. When the
    /// resolved area is narrower than the declared floor — a `Length(n)`
    /// column that got `<n` cells, or a `Min(n)` column that got `<n`
    /// cells — the column emits a warning (see "Clipping diagnostics").
    /// `Percentage` is a share of the resolved area and has no absolute
    /// floor, so it is never flagged.
    ///
    /// For these three idioms the shorthand constructors
    /// [`Column::fixed`], [`Column::min`], and [`Column::percent`] read
    /// more directly than `Column::new`.
    ///
    /// The column is not sortable by default.
    ///
    /// # Example
    ///
    /// Three-column layout: fixed ID, fixed price, flexible description.
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let cols = vec![
    ///     Column::new("ID",          Constraint::Length(8)),
    ///     Column::new("Price",       Constraint::Length(10)),
    ///     Column::new("Description", Constraint::Min(20)),
    /// ];
    /// assert_eq!(cols.len(), 3);
    /// assert_eq!(cols[0].width(), Constraint::Length(8));
    /// assert_eq!(cols[2].width(), Constraint::Min(20));
    /// ```
    ///
    /// # Clipping diagnostics
    ///
    /// When a `Length(n)` or `Min(n)` column resolves to fewer than `n`
    /// cells, the column emits a `tracing::warn!` once. Dedup is per
    /// `(column index, area width)`: the warning re-arms when the
    /// terminal is resized. This is best-effort observability — the
    /// table still renders. Enable with the `tracing` feature.
    pub fn new(header: impl Into<String>, width: Constraint) -> Self {
        Self {
            header: header.into(),
            width,
            sortable: false,
            editable: true,
            visible: true,
            default_sort: SortDirection::Ascending,
        }
    }

    /// Makes this column sortable.
    ///
    /// Sortable columns can be sorted by clicking/selecting the header
    /// or using `TableMessage::SortAsc` / `SortDesc` / `SortToggle`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Name", Constraint::Length(20)).sortable();
    /// assert!(col.is_sortable());
    /// ```
    pub fn sortable(mut self) -> Self {
        self.sortable = true;
        self
    }

    /// Returns the column header text.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Name", Constraint::Length(20));
    /// assert_eq!(col.header(), "Name");
    /// ```
    pub fn header(&self) -> &str {
        &self.header
    }

    /// Returns the column width constraint.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Price", Constraint::Length(10));
    /// assert_eq!(col.width(), Constraint::Length(10));
    /// ```
    pub fn width(&self) -> Constraint {
        self.width
    }

    /// Creates a column with a fixed width.
    ///
    /// This is a shorthand for `Column::new(header, Constraint::Length(width))`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    ///
    /// let col = Column::fixed("Name", 20);
    /// assert_eq!(col.header(), "Name");
    /// ```
    pub fn fixed(header: impl Into<String>, width: u16) -> Self {
        Self::new(header, Constraint::Length(width))
    }

    /// Creates a column with a minimum width.
    ///
    /// This is a shorthand for `Column::new(header, Constraint::Min(width))`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    ///
    /// let col = Column::min("Description", 10);
    /// ```
    pub fn min(header: impl Into<String>, width: u16) -> Self {
        Self::new(header, Constraint::Min(width))
    }

    /// Creates a column that takes a percentage of available width.
    ///
    /// This is a shorthand for `Column::new(header, Constraint::Percentage(percent))`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    ///
    /// let col = Column::percent("Status", 25);
    /// ```
    pub fn percent(header: impl Into<String>, percent: u16) -> Self {
        Self::new(header, Constraint::Percentage(percent))
    }

    /// Returns whether this column is sortable.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Name", Constraint::Length(20));
    /// assert!(!col.is_sortable());
    ///
    /// let sortable = col.sortable();
    /// assert!(sortable.is_sortable());
    /// ```
    pub fn is_sortable(&self) -> bool {
        self.sortable
    }

    /// Sets whether this column is editable (builder pattern).
    ///
    /// Columns are editable by default. Set to `false` to make a column
    /// read-only in a `DataGrid`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("ID", Constraint::Length(10)).with_editable(false);
    /// assert!(!col.is_editable());
    /// ```
    pub fn with_editable(mut self, editable: bool) -> Self {
        self.editable = editable;
        self
    }

    /// Returns whether this column is editable.
    ///
    /// Defaults to `true`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Name", Constraint::Length(10));
    /// assert!(col.is_editable());
    ///
    /// let read_only = col.with_editable(false);
    /// assert!(!read_only.is_editable());
    /// ```
    pub fn is_editable(&self) -> bool {
        self.editable
    }

    /// Sets whether this column is visible (builder pattern).
    ///
    /// Columns are visible by default. Set to `false` to hide a column
    /// from rendering while preserving its data.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Internal", Constraint::Length(10)).with_visible(false);
    /// assert!(!col.is_visible());
    /// ```
    pub fn with_visible(mut self, visible: bool) -> Self {
        self.visible = visible;
        self
    }

    /// Returns whether this column is visible.
    ///
    /// Defaults to `true`.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let col = Column::new("Name", Constraint::Length(10));
    /// assert!(col.is_visible());
    ///
    /// let hidden = col.with_visible(false);
    /// assert!(!hidden.is_visible());
    /// ```
    pub fn is_visible(&self) -> bool {
        self.visible
    }

    /// Sets column visibility.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let mut col = Column::new("Internal", Constraint::Length(10));
    /// assert!(col.is_visible());
    /// col.set_visible(false);
    /// assert!(!col.is_visible());
    /// ```
    pub fn set_visible(&mut self, visible: bool) {
        self.visible = visible;
    }

    /// Sets whether this column is editable.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let mut col = Column::new("Name", Constraint::Length(10));
    /// assert!(col.is_editable());
    /// col.set_editable(false);
    /// assert!(!col.is_editable());
    /// ```
    pub fn set_editable(&mut self, editable: bool) {
        self.editable = editable;
    }

    /// Declares this column's natural sort direction. `SortToggle` and
    /// `AddSortToggle` use this when activating the column for the first
    /// time. Default: `Ascending`.
    ///
    /// Use `Descending` for columns where bigger-is-worse (latency,
    /// regression delta, error count).
    ///
    /// # Example
    ///
    /// ```
    /// use envision::component::{Column, SortDirection};
    /// use ratatui::layout::Constraint;
    ///
    /// let c = Column::new("delta", Constraint::Length(10))
    ///     .with_default_sort(SortDirection::Descending);
    /// assert_eq!(c.default_sort(), SortDirection::Descending);
    /// ```
    pub fn with_default_sort(mut self, dir: SortDirection) -> Self {
        self.default_sort = dir;
        self
    }

    /// Returns the column's natural sort direction.
    ///
    /// Defaults to [`SortDirection::Ascending`] for newly constructed
    /// columns; override with [`Column::with_default_sort`] when a column
    /// reads more naturally in descending order (timestamps, percentages,
    /// load counters, etc.).
    ///
    /// # Example
    ///
    /// ```
    /// use envision::component::{Column, SortDirection};
    /// use ratatui::layout::Constraint;
    ///
    /// let asc = Column::new("name", Constraint::Length(10));
    /// assert_eq!(asc.default_sort(), SortDirection::Ascending);
    ///
    /// let desc = Column::new("age", Constraint::Length(8))
    ///     .with_default_sort(SortDirection::Descending);
    /// assert_eq!(desc.default_sort(), SortDirection::Descending);
    /// ```
    pub fn default_sort(&self) -> SortDirection {
        self.default_sort
    }

    /// Sets the width of this column (builder method).
    ///
    /// This is useful for column resizing operations.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::Column;
    /// use ratatui::layout::Constraint;
    ///
    /// let mut col = Column::fixed("Name", 10);
    /// assert_eq!(col.width(), Constraint::Length(10));
    /// col.set_width(Constraint::Length(20));
    /// assert_eq!(col.width(), Constraint::Length(20));
    /// ```
    pub fn set_width(&mut self, width: Constraint) {
        self.width = width;
    }
}

/// Sort direction for table columns.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub enum SortDirection {
    /// Sort in ascending order (A-Z, 0-9).
    #[default]
    Ascending,
    /// Sort in descending order (Z-A, 9-0).
    Descending,
}

impl SortDirection {
    /// Returns the opposite sort direction.
    ///
    /// # Example
    ///
    /// ```rust
    /// use envision::component::SortDirection;
    ///
    /// assert_eq!(SortDirection::Ascending.toggle(), SortDirection::Descending);
    /// assert_eq!(SortDirection::Descending.toggle(), SortDirection::Ascending);
    /// ```
    pub fn toggle(self) -> Self {
        match self {
            SortDirection::Ascending => SortDirection::Descending,
            SortDirection::Descending => SortDirection::Ascending,
        }
    }
}

/// Pair of (column index, direction) for declarative initial sort.
///
/// Used with `TableState::with_initial_sorts` to bootstrap the table
/// into a sorted state on frame 1.
///
/// # Example
///
/// ```
/// use envision::component::{InitialSort, SortDirection};
/// let s = InitialSort { column: 4, direction: SortDirection::Descending };
/// assert_eq!(s.column, 4);
/// ```
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
#[cfg_attr(
    feature = "serialization",
    derive(serde::Serialize, serde::Deserialize)
)]
pub struct InitialSort {
    /// Index of the column to sort by.
    pub column: usize,
    /// Sort direction to apply.
    pub direction: SortDirection,
}

/// Messages that can be sent to a Table component.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TableMessage {
    /// Move selection up by one row.
    Up,
    /// Move selection down by one row.
    Down,
    /// Move selection to the first row.
    First,
    /// Move selection to the last row.
    Last,
    /// Move selection up by a page.
    PageUp(usize),
    /// Move selection down by a page.
    PageDown(usize),
    /// Confirm the current selection.
    Select,

    /// Set the primary sort to this column, ascending. Replaces the entire
    /// sort stack with just this entry.
    #[allow(dead_code)] // Handler lands in Phase 2; allow until then.
    SortAsc(usize),

    /// Set the primary sort to this column, descending. Replaces the entire
    /// sort stack with just this entry.
    #[allow(dead_code)]
    SortDesc(usize),

    /// 2-cycle toggle. Never clears.
    /// - If this column is already the primary sort: flip Asc <-> Desc.
    /// - If this column is not currently in the sort stack: activate it
    ///   using `Column::default_sort()`. Default fallback: `Ascending`.
    #[allow(dead_code)]
    SortToggle(usize),

    /// Drop the primary sort and any tiebreakers. Returns to load order.
    /// (Renamed from `ClearSort` for naming consistency with the rest of
    /// the family. The old `ClearSort` is removed in Phase 2 Task 16.)
    #[allow(dead_code)]
    SortClear,

    /// Drop just one column from the multi-sort stack. The remaining
    /// columns keep their relative order. If the dropped column was
    /// primary, the next tiebreaker is promoted.
    #[allow(dead_code)]
    RemoveSort(usize),

    // ----- NEW tiebreaker family -----
    /// Add this column to the sort stack as a lowest-priority Asc
    /// tiebreaker. If the column is already in the stack, replace its
    /// direction in place -- do not reorder.
    #[allow(dead_code)]
    AddSortAsc(usize),

    /// Add this column to the sort stack as a lowest-priority Desc
    /// tiebreaker. If already in the stack, replace direction in place.
    #[allow(dead_code)]
    AddSortDesc(usize),

    /// Toggle this column's tiebreaker direction. If not in the stack,
    /// add it using `Column::default_sort()`.
    #[allow(dead_code)]
    AddSortToggle(usize),

    /// Increase the width of the column at the given index.
    IncreaseColumnWidth(usize),
    /// Decrease the width of the column at the given index.
    ///
    /// The width will not go below the minimum of 3 characters.
    DecreaseColumnWidth(usize),
    /// Set the filter text for searching rows.
    SetFilter(String),
    /// Clear the filter text.
    ClearFilter,
}

/// Output messages from a Table component.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum TableOutput<T: Clone> {
    /// A row was selected (e.g., Enter pressed).
    Selected(T),
    /// The selection changed to a new row index.
    SelectionChanged(usize),
    /// The sort changed.
    Sorted {
        /// The column being sorted by.
        column: usize,
        /// The sort direction.
        direction: SortDirection,
    },
    /// Sort was cleared.
    SortCleared,
    /// The filter text changed.
    FilterChanged(String),
    /// A column was resized.
    ColumnResized {
        /// The column that was resized.
        column: usize,
        /// The new width of the column.
        width: u16,
    },
}