tui-dispatch-core 0.7.0

//! Action trait for type-safe state mutations

use std::fmt::Debug;
use std::hash::Hash;

/// Marker trait for actions that can be dispatched to the store
///
/// Actions represent intents to change state. They should be:
/// - Clone: Actions may be logged, replayed, or sent to multiple handlers
/// - Debug: For debugging and logging
/// - Send + 'static: For async dispatch across threads
///
/// Use `#[derive(Action)]` from `tui-dispatch-macros` to auto-implement this trait.
pub trait Action: Clone + Debug + Send + 'static {
    /// Get the action name for logging and filtering
    fn name(&self) -> &'static str;
}

/// Extension trait for actions with category support
///
/// This trait is auto-implemented when using `#[derive(Action)]` with
/// `#[action(infer_categories)]`. It provides methods to query an action's
/// category for routing and filtering.
///
/// # Example
///
/// ```ignore
/// use tui_dispatch::ActionCategory;
///
/// #[derive(Action, Clone, Debug)]
/// #[action(infer_categories)]
/// enum MyAction {
///     SearchStart,
///     SearchClear,
///     ConnectionFormOpen,
/// }
///
/// let action = MyAction::SearchStart;
/// assert_eq!(action.category(), Some("search"));
/// assert!(matches!(action.category_enum(), MyActionCategory::Search));
/// ```
pub trait ActionCategory: Action {
    /// The category enum type generated by the derive macro
    type Category: Copy + Eq + Hash + Debug;

    /// Get the action's category as a string (if categorized)
    fn category(&self) -> Option<&'static str>;

    /// Get the action's category as an enum value
    fn category_enum(&self) -> Self::Category;
}

/// Trait for getting action parameters without the variant name.
///
/// Auto-implemented by `#[derive(Action)]`. Returns just the field values
/// as a string, suitable for display in action logs where the action name
/// is already shown separately.
///
/// # Example
///
/// ```ignore
/// #[derive(Action, Clone, Debug)]
/// enum MyAction {
///     SetFilter { query: String, limit: usize },
///     Tick,
/// }
///
/// let action = MyAction::SetFilter { query: "foo".into(), limit: 10 };
/// assert_eq!(action.name(), "SetFilter");
/// assert_eq!(action.params(), r#"{query: \"foo\", limit: 10}"#);
///
/// let tick = MyAction::Tick;
/// assert_eq!(tick.params(), "");
/// ```
pub trait ActionParams: Action {
    /// Get just the action parameters as a string (no variant name)
    fn params(&self) -> String;

    /// Get a multi-line, detailed representation of the parameters.
    fn params_pretty(&self) -> String {
        self.params()
    }
}

/// Trait for actions that provide a summary representation for logging
///
/// The default implementation uses the Debug representation. Override
/// `summary()` to provide concise summaries for actions with large payloads
/// (e.g., showing byte counts instead of full data).
///
/// # Example
///
/// ```ignore
/// impl ActionSummary for MyAction {
///     fn summary(&self) -> String {
///         match self {
///             MyAction::DidLoadData { data } => {
///                 format!("DidLoadData {{ bytes: {} }}", data.len())
///             }
///             _ => format!("{:?}", self)
///         }
///     }
/// }
/// ```
#[deprecated(since = "0.3.0", note = "use ActionParams::params() instead")]
pub trait ActionSummary: Action {
    /// Get a summary representation of this action for logging
    ///
    /// Should return a concise string, ideally one line, suitable for
    /// display in a scrolling action log. For actions with large data payloads,
    /// show size/count summaries instead of full content.
    ///
    /// Default implementation uses `Debug` formatting.
    fn summary(&self) -> String {
        format!("{:?}", self)
    }
}