ratatui_toolkit/
lib.rs

1//! # ratatui-toolkit
2//!
3//! A comprehensive collection of reusable TUI components for [ratatui](https://ratatui.rs/),
4//! the Rust terminal UI library.
5//!
6//! ## Overview
7//!
8//! This crate provides production-ready, reusable widgets for building terminal user interfaces:
9//!
10//! - **Layout Components**: [`ResizableSplit`] for flexible UI layouts
11//! - **UI Components**: [`Button`], [`Dialog`], [`Toast`], [`Pane`] for common UI elements
12//! - **Widgets**: [`TreeView`] for data display
13//! - **Navigation**: [`MenuBar`], [`HotkeyFooter`] for navigation aids
14//! - **Rendering**: [`render_markdown`] for markdown to ratatui text conversion
15//! - **Terminal**: [`TermTui`] for embedded terminal emulation
16//! - **Theming**: [`theme`] module with 33 builtin themes and JSON loader
17//!
18//! ## Feature Flags
19//!
20//! The crate uses feature flags to minimize dependencies:
21//!
22//! | Feature | Default | Description |
23//! |---------|---------|-------------|
24//! | `markdown` | Yes | Markdown rendering support |
25//! | `tree` | Yes | Tree view widget |
26//! | `dialog` | Yes | Modal dialog components |
27//! | `toast` | Yes | Toast notification system |
28//! | `split` | Yes | Resizable split panels |
29//! | `menu` | Yes | Menu bar component |
30//! | `statusline` | Yes | Powerline-style statusline |
31//! | `hotkey` | Yes | Hotkey footer and modal |
32//! | `terminal` | No | Terminal emulator (TermTui) |
33//! | `file-tree` | No | File system tree with devicons |
34//! | `theme` | No | Theme system with 33 builtin themes |
35//! | `full` | No | Enable all features |
36//!
37//! ## Quick Start
38//!
39//! ```rust,no_run
40//! use ratatui::prelude::*;
41//! use ratatui_toolkit::prelude::*;
42//!
43//! // Create a resizable split
44//! let split = ResizableSplit::new(30); // 30% left, 70% right
45//!
46//! // Create a toast notification
47//! let mut manager = ToastManager::new();
48//! manager.success("File saved!");
49//!
50//! // Render markdown
51//! let text = render_markdown("# Hello\n\n**Bold** and *italic* text.", None);
52//! ```
53//!
54//! ## Examples
55//!
56//! See the `examples/` directory for runnable demos of each component:
57//!
58//! ```bash
59//! cargo run --example resizable_split_demo
60//! cargo run --example tree_view_demo --features tree
61//! cargo run --example toast_manager_demo --features toast
62//! ```
63
64#![cfg_attr(docsrs, feature(doc_cfg))]
65
66// Core components - always available
67pub mod primitives;
68
69pub mod widgets;
70
71// Services module - shared infrastructure
72pub mod services;
73
74// Re-export commonly used types - always available
75pub use primitives::button::render_title_with_buttons::render_title_with_buttons;
76pub use primitives::button::Button;
77pub use primitives::pane::Pane;
78pub use widgets::ai_chat::{AIChat, AIChatEvent, InputState, Message, MessageRole, MessageStore};
79pub use widgets::code_diff::{CodeDiff, DiffConfig, DiffHunk, DiffLine, DiffLineKind, DiffStyle};
80pub use widgets::split_layout::SplitLayoutWidget;
81pub use widgets::split_layout::SplitLayoutWidgetState;
82
83// Feature-gated re-exports
84#[cfg(feature = "dialog")]
85pub use primitives::dialog::widget::DialogWidget;
86#[cfg(feature = "dialog")]
87pub use primitives::dialog::{Dialog, DialogType};
88
89#[cfg(feature = "toast")]
90pub use primitives::toast::methods::render_toasts::render_toasts;
91#[cfg(feature = "toast")]
92pub use primitives::toast::{Toast, ToastLevel, ToastManager};
93
94#[cfg(feature = "split")]
95pub use primitives::resizable_split::{ResizableSplit, SplitDirection};
96#[cfg(feature = "split")]
97pub use primitives::split_layout::{PaneId, PaneLayout, SplitAxis, SplitLayout};
98
99#[cfg(feature = "tree")]
100pub use primitives::tree_view::{
101    get_visible_paths, matches_filter, NodeState, TreeKeyBindings, TreeNavigator, TreeNode,
102    TreeView, TreeViewRef, TreeViewState,
103};
104
105#[cfg(feature = "menu")]
106pub use primitives::menu_bar::{MenuBar, MenuItem};
107
108#[cfg(feature = "statusline")]
109pub use primitives::statusline::{
110    OperationalMode, StatusLineStacked, StyledStatusLine, SLANT_BL_TR, SLANT_TL_BR,
111};
112
113#[cfg(feature = "hotkey")]
114pub use widgets::hotkey_footer::{HotkeyFooter, HotkeyFooterBuilder, HotkeyItem};
115
116#[cfg(feature = "hotkey")]
117#[cfg(feature = "markdown")]
118pub use widgets::markdown_widget::{
119    render_markdown, render_markdown_with_style, CacheState, CodeBlockTheme, CollapseState,
120    DisplaySettings, DoubleClickState, ExpandableState, GitStats, GitStatsState,
121    MarkdownDoubleClickEvent, MarkdownEvent, MarkdownState, MarkdownStyle, MarkdownWidget,
122    MarkdownWidgetMode, ScrollState, SelectionPos, SelectionState, SourceState, VimState,
123};
124
125#[cfg(feature = "terminal")]
126pub use primitives::termtui::{TermTui, TermTuiKeyBindings};
127
128#[cfg(feature = "file-tree")]
129pub use widgets::file_system_tree::{FileSystemEntry, FileSystemTree, FileSystemTreeConfig};
130
131#[cfg(feature = "theme")]
132pub use services::theme::{AppTheme, DiffColors, MarkdownColors, SyntaxColors, ThemeVariant};
133
134// File watcher service - always available
135pub use services::file_watcher::{FileWatcher, WatchConfig, WatchMode};
136
137/// Prelude module for convenient imports
138///
139/// # Example
140///
141/// ```rust
142/// use ratatui_toolkit::prelude::*;
143/// ```
144pub mod prelude {
145    // Core components
146    pub use crate::primitives::button::render_title_with_buttons::render_title_with_buttons;
147    pub use crate::primitives::button::Button;
148    pub use crate::primitives::pane::Pane;
149    pub use crate::widgets::ai_chat::{
150        AIChat, AIChatEvent, InputState, Message, MessageRole, MessageStore,
151    };
152    pub use crate::widgets::code_diff::{
153        CodeDiff, DiffConfig, DiffHunk, DiffLine, DiffLineKind, DiffStyle,
154    };
155
156    // Feature-gated components
157    #[cfg(feature = "dialog")]
158    pub use crate::primitives::dialog::widget::DialogWidget;
159    #[cfg(feature = "dialog")]
160    pub use crate::primitives::dialog::{Dialog, DialogType};
161
162    #[cfg(feature = "toast")]
163    pub use crate::primitives::toast::methods::render_toasts::render_toasts;
164    #[cfg(feature = "toast")]
165    pub use crate::primitives::toast::{Toast, ToastLevel, ToastManager};
166
167    #[cfg(feature = "split")]
168    pub use crate::primitives::resizable_split::{ResizableSplit, SplitDirection};
169    #[cfg(feature = "split")]
170    pub use crate::primitives::split_layout::{PaneId, PaneLayout, SplitAxis, SplitLayout};
171    #[cfg(feature = "split")]
172    pub use crate::widgets::split_layout::{SplitLayoutWidget, SplitLayoutWidgetState};
173
174    #[cfg(feature = "tree")]
175    pub use crate::primitives::tree_view::{
176        get_visible_paths, matches_filter, NodeState, TreeKeyBindings, TreeNavigator, TreeNode,
177        TreeView, TreeViewRef, TreeViewState,
178    };
179
180    #[cfg(feature = "menu")]
181    pub use crate::primitives::menu_bar::{MenuBar, MenuItem};
182
183    #[cfg(feature = "statusline")]
184    pub use crate::primitives::statusline::{
185        OperationalMode, StatusLineStacked, StyledStatusLine, SLANT_BL_TR, SLANT_TL_BR,
186    };
187
188    #[cfg(feature = "hotkey")]
189    pub use crate::widgets::hotkey_footer::{HotkeyFooter, HotkeyFooterBuilder, HotkeyItem};
190
191    #[cfg(feature = "markdown")]
192    pub use crate::widgets::markdown_widget::{
193        render_markdown, render_markdown_with_style, CacheState, CollapseState, DisplaySettings,
194        DoubleClickState, ExpandableState, GitStatsState, MarkdownState, MarkdownStyle,
195        MarkdownWidget, ScrollState, SelectionState, SourceState, VimState,
196    };
197
198    #[cfg(feature = "terminal")]
199    pub use crate::primitives::termtui::{TermTui, TermTuiKeyBindings};
200
201    #[cfg(feature = "file-tree")]
202    pub use crate::widgets::file_system_tree::{
203        FileSystemEntry, FileSystemTree, FileSystemTreeConfig,
204    };
205
206    #[cfg(feature = "theme")]
207    pub use crate::services::theme::{
208        AppTheme, DiffColors, MarkdownColors, SyntaxColors, ThemeVariant,
209    };
210
211    // Services
212    pub use crate::services::file_watcher::{FileWatcher, WatchConfig, WatchMode};
213}
214
215/// Error types for the crate
216#[derive(Debug, thiserror::Error)]
217pub enum Error {
218    /// IO error
219    #[error("IO error: {0}")]
220    Io(#[from] std::io::Error),
221
222    /// Terminal error
223    #[error("Terminal error: {0}")]
224    Terminal(String),
225
226    /// Parse error
227    #[error("Parse error: {0}")]
228    Parse(String),
229}
230
231/// Result type for the crate
232pub type Result<T> = std::result::Result<T, Error>;
ratatui_toolkit/lib.rs

ratatui_toolkit/
lib.rs
