tui_world/lib.rs
1//! # tui-world
2//!
3//! A state and event management library for TUIs built with [ratatui](https://github.com/ratatui/ratatui).
4//!
5//! ## Core Concepts
6//!
7//! - [`World`] - A container that holds application state
8//! - [`Keybindings`] - Key binding registry with built-in help display
9//! - [`Focus`] - Tracks which widget currently has keyboard focus
10//! - [`Pointer`] - Tracks widget areas and handles mouse click/drag/up events
11//! - [`InputEvent`] - Unified input event handling for keyboard and mouse
12//!
13//! ## Example
14//!
15//! ```ignore
16//! use tui_world::prelude::*;
17//! use crossterm::event::KeyCode;
18//!
19//! const WIDGET_ID: WidgetId = WidgetId("MyWidget");
20//!
21//! let mut world = World::default();
22//!
23//! // Store state in world
24//! world.insert(MyAppState::default());
25//!
26//! // Register keybindings
27//! world.get_mut::<Keybindings>().bind(WIDGET_ID, KeyCode::Enter, "Select", |world| {
28//! world.get_mut::<MyAppState>().select();
29//! });
30//!
31//! // Check focus
32//! if world.get::<Focus>().is_focused(WIDGET_ID) {
33//! // widget has focus
34//! }
35//!
36//! // Handle key events
37//! InputEvent::Key(key).handle(&mut world, &[WIDGET_ID]);
38//! ```
39
40mod focus;
41mod input_event;
42mod keybindings;
43mod pointer;
44mod world;
45
46pub use focus::Focus;
47pub use input_event::InputEvent;
48pub use keybindings::{DisplayInfo, KeyBinding, Keybindings, Keys};
49pub use pointer::{Area, Pointer};
50pub use world::World;
51
52/// A unique identifier for a widget in the application.
53///
54/// `WidgetId` is used to associate keybindings, focus state, and pointer areas
55/// with specific widgets. It wraps a static string slice for efficient comparison
56/// and hashing.
57///
58/// # Example
59/// ```ignore
60/// const MY_WIDGET: WidgetId = WidgetId("my_widget");
61/// ```
62#[derive(Debug, PartialOrd, Ord, Clone, Copy, PartialEq, Eq, Hash, Default)]
63pub struct WidgetId(pub &'static str);
64
65pub mod prelude {
66 pub use crate::Area;
67 pub use crate::DisplayInfo;
68 pub use crate::Focus;
69 pub use crate::InputEvent;
70 pub use crate::KeyBinding;
71 pub use crate::Keybindings;
72 pub use crate::Pointer;
73 pub use crate::WidgetId;
74 pub use crate::World;
75}