tui_dispatch_core/
lib.rs

1//! Core traits and types for tui-dispatch
2//!
3//! This crate provides the foundational abstractions for building TUI applications
4//! with centralized state management, following a Redux/Elm-inspired architecture.
5//!
6//! # Core Concepts
7//!
8//! - **Action**: Events that describe state changes
9//! - **Store**: Centralized state container with reducer pattern
10//! - **Component**: Pure UI elements that render based on props
11//! - **EventBus**: Pub/sub system for event routing
12//! - **Keybindings**: Context-aware key mapping
13//!
14//! # Basic Example
15//!
16//! ```ignore
17//! use tui_dispatch_core::prelude::*;
18//!
19//! #[derive(Action, Clone, Debug)]
20//! enum MyAction {
21//!     Increment,
22//!     Decrement,
23//! }
24//!
25//! #[derive(Default)]
26//! struct AppState {
27//!     counter: i32,
28//! }
29//!
30//! fn reducer(state: &mut AppState, action: MyAction) -> bool {
31//!     match action {
32//!         MyAction::Increment => { state.counter += 1; true }
33//!         MyAction::Decrement => { state.counter -= 1; true }
34//!     }
35//! }
36//!
37//! let mut store = Store::new(AppState::default(), reducer);
38//! store.dispatch(MyAction::Increment);
39//! ```
40//!
41//! # Async Handler Pattern
42//!
43//! For applications with async operations (API calls, file I/O, etc.), use a two-phase
44//! action pattern:
45//!
46//! 1. **Intent actions** trigger async work (e.g., `FetchData`)
47//! 2. **Result actions** carry the outcome back (e.g., `DidFetchData`, `DidFetchError`)
48//!
49//! ```ignore
50//! use tokio::sync::mpsc;
51//!
52//! #[derive(Action, Clone, Debug)]
53//! #[action(infer_categories)]
54//! enum Action {
55//!     // Intent: triggers async fetch
56//!     DataFetch { id: String },
57//!     // Result: async operation completed
58//!     DataDidLoad { id: String, payload: Vec<u8> },
59//!     DataDidError { id: String, error: String },
60//! }
61//!
62//! // Async handler spawns a task and sends result back via channel
63//! fn handle_async(action: &Action, tx: mpsc::UnboundedSender<Action>) {
64//!     match action {
65//!         Action::DataFetch { id } => {
66//!             let id = id.clone();
67//!             let tx = tx.clone();
68//!             tokio::spawn(async move {
69//!                 match fetch_from_api(&id).await {
70//!                     Ok(payload) => tx.send(Action::DataDidLoad { id, payload }),
71//!                     Err(e) => tx.send(Action::DataDidError { id, error: e.to_string() }),
72//!                 }
73//!             });
74//!         }
75//!         _ => {}
76//!     }
77//! }
78//!
79//! // Main loop receives actions from both events and async completions
80//! loop {
81//!     tokio::select! {
82//!         Some(action) = action_rx.recv() => {
83//!             handle_async(&action, action_tx.clone());
84//!             store.dispatch(action);
85//!         }
86//!         // ... event handling
87//!     }
88//! }
89//! ```
90//!
91//! The `Did*` naming convention clearly identifies result actions. With `#[action(infer_categories)]`,
92//! these are automatically grouped (e.g., `DataFetch` and `DataDidLoad` both get category `"data"`).
93
94pub mod action;
95pub mod bus;
96pub mod component;
97pub mod debug;
98pub mod event;
99pub mod features;
100pub mod keybindings;
101pub mod store;
102pub mod testing;
103
104// Core trait exports
105pub use action::{Action, ActionCategory};
106pub use component::Component;
107pub use features::{DynamicFeatures, FeatureFlags};
108
109// Event system exports
110pub use bus::{process_raw_event, spawn_event_poller, EventBus, RawEvent};
111pub use event::{ComponentId, Event, EventContext, EventKind, EventType, NumericComponentId};
112
113// Keybindings exports
114pub use keybindings::{format_key_for_display, parse_key_string, BindingContext, Keybindings};
115
116// Store exports
117pub use store::{
118    ComposedMiddleware, LoggingMiddleware, Middleware, NoopMiddleware, Reducer, Store,
119    StoreWithMiddleware,
120};
121
122// Re-export ratatui types for convenience
123pub use ratatui::{
124    layout::Rect,
125    style::{Color, Modifier, Style},
126    text::{Line, Span, Text},
127    Frame,
128};
129
130// Testing exports
131pub use testing::{
132    alt_key, buffer_rect_to_string_plain, buffer_to_string, buffer_to_string_plain, char_key,
133    ctrl_key, into_event, key, key_event, key_events, keys, ActionAssertions, ActionAssertionsEq,
134    RenderHarness, TestHarness,
135};
136
137#[cfg(feature = "testing-time")]
138pub use testing::{advance_time, pause_time, resume_time};
139
140/// Prelude module for convenient imports
141pub mod prelude {
142    pub use crate::action::{Action, ActionCategory};
143    pub use crate::bus::{process_raw_event, spawn_event_poller, EventBus, RawEvent};
144    pub use crate::component::Component;
145    pub use crate::event::{
146        ComponentId, Event, EventContext, EventKind, EventType, NumericComponentId,
147    };
148    pub use crate::features::{DynamicFeatures, FeatureFlags};
149    pub use crate::keybindings::{
150        format_key_for_display, parse_key_string, BindingContext, Keybindings,
151    };
152    pub use crate::store::{
153        ComposedMiddleware, LoggingMiddleware, Middleware, NoopMiddleware, Reducer, Store,
154        StoreWithMiddleware,
155    };
156
157    // Re-export ratatui types
158    pub use ratatui::{
159        layout::Rect,
160        style::{Color, Modifier, Style},
161        text::{Line, Span, Text},
162        Frame,
163    };
164}
tui_dispatch_core/lib.rs

tui_dispatch_core/
lib.rs
