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`], [`MasterLayout`] for flexible UI layouts
11//! - **UI Components**: [`Button`], [`Dialog`], [`Toast`], [`Pane`] for common UI elements
12//! - **Widgets**: [`TreeView`], [`ClickableScrollbar`], [`FuzzyFinder`] for data display
13//! - **Navigation**: [`MenuBar`], [`HotkeyFooter`], [`StatusBar`] for navigation aids
14//! - **Rendering**: [`render_markdown`] for markdown to ratatui text conversion
15//! - **Terminal**: [`AlacTerm`], [`VT100Term`], [`TermTui`] for embedded terminal emulation
16//!
17//! ## Feature Flags
18//!
19//! The crate uses feature flags to minimize dependencies:
20//!
21//! | Feature | Default | Description |
22//! |---------|---------|-------------|
23//! | `markdown` | Yes | Markdown rendering support |
24//! | `tree` | Yes | Tree view widget |
25//! | `dialog` | Yes | Modal dialog components |
26//! | `toast` | Yes | Toast notification system |
27//! | `split` | Yes | Resizable split panels |
28//! | `menu` | Yes | Menu bar component |
29//! | `statusbar` | Yes | Status bar components |
30//! | `hotkey` | Yes | Hotkey footer and modal |
31//! | `terminal` | No | Terminal emulators (AlacTerm, VT100) |
32//! | `fuzzy` | No | Fuzzy finder component |
33//! | `master-layout` | No | Full application layout framework |
34//! | `file-tree` | No | File system tree with devicons |
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 button;
68pub mod clickable_scrollbar;
69pub mod pane;
70
71// Feature-gated components
72#[cfg(feature = "dialog")]
73#[cfg_attr(docsrs, doc(cfg(feature = "dialog")))]
74pub mod dialog;
75
76#[cfg(feature = "toast")]
77#[cfg_attr(docsrs, doc(cfg(feature = "toast")))]
78pub mod toast;
79
80#[cfg(feature = "split")]
81#[cfg_attr(docsrs, doc(cfg(feature = "split")))]
82pub mod resizable_split;
83
84#[cfg(feature = "tree")]
85#[cfg_attr(docsrs, doc(cfg(feature = "tree")))]
86pub mod tree_view;
87
88#[cfg(feature = "menu")]
89#[cfg_attr(docsrs, doc(cfg(feature = "menu")))]
90pub mod menu_bar;
91
92#[cfg(feature = "statusbar")]
93#[cfg_attr(docsrs, doc(cfg(feature = "statusbar")))]
94pub mod statusbar;
95
96#[cfg(feature = "statusbar")]
97#[cfg_attr(docsrs, doc(cfg(feature = "statusbar")))]
98pub mod statusline_stacked;
99
100#[cfg(feature = "hotkey")]
101#[cfg_attr(docsrs, doc(cfg(feature = "hotkey")))]
102pub mod hotkey_footer;
103
104#[cfg(feature = "hotkey")]
105#[cfg_attr(docsrs, doc(cfg(feature = "hotkey")))]
106pub mod hotkey_modal;
107
108#[cfg(feature = "markdown")]
109#[cfg_attr(docsrs, doc(cfg(feature = "markdown")))]
110pub mod markdown_renderer;
111
112#[cfg(feature = "terminal")]
113#[cfg_attr(docsrs, doc(cfg(feature = "terminal")))]
114pub mod alac_term;
115
116#[cfg(feature = "terminal")]
117#[cfg_attr(docsrs, doc(cfg(feature = "terminal")))]
118pub mod vt100_term;
119
120#[cfg(feature = "terminal")]
121#[cfg_attr(docsrs, doc(cfg(feature = "terminal")))]
122pub mod ai_chat;
123
124#[cfg(feature = "terminal")]
125#[cfg_attr(docsrs, doc(cfg(feature = "terminal")))]
126pub mod termtui;
127
128#[cfg(feature = "fuzzy")]
129#[cfg_attr(docsrs, doc(cfg(feature = "fuzzy")))]
130pub mod fuzzy_finder;
131
132#[cfg(feature = "file-tree")]
133#[cfg_attr(docsrs, doc(cfg(feature = "file-tree")))]
134pub mod file_system_tree;
135
136#[cfg(feature = "master-layout")]
137#[cfg_attr(docsrs, doc(cfg(feature = "master-layout")))]
138pub mod master_layout;
139
140// Re-export commonly used types - always available
141pub use button::{render_title_with_buttons, Button};
142pub use clickable_scrollbar::{ClickableScrollbar, ClickableScrollbarState, ScrollbarEvent};
143pub use pane::Pane;
144
145// Feature-gated re-exports
146#[cfg(feature = "dialog")]
147pub use dialog::{Dialog, DialogType, DialogWidget};
148
149#[cfg(feature = "toast")]
150pub use toast::{render_toasts, Toast, ToastLevel, ToastManager};
151
152#[cfg(feature = "split")]
153pub use resizable_split::{ResizableSplit, SplitDirection};
154
155#[cfg(feature = "tree")]
156pub use tree_view::{
157    get_visible_paths, NodeState, TreeKeyBindings, TreeNavigator, TreeNode, TreeView, TreeViewState,
158};
159
160#[cfg(feature = "menu")]
161pub use menu_bar::{MenuBar, MenuItem};
162
163#[cfg(feature = "statusbar")]
164pub use statusbar::{StatusBar, StatusItem};
165
166#[cfg(feature = "statusbar")]
167pub use statusline_stacked::{
168    OperationalMode, StatusLineStacked, StyledStatusLine, SLANT_BL_TR, SLANT_TL_BR,
169};
170
171#[cfg(feature = "hotkey")]
172pub use hotkey_footer::{HotkeyFooter, HotkeyFooterBuilder, HotkeyItem};
173
174#[cfg(feature = "hotkey")]
175pub use hotkey_modal::{render_hotkey_modal, Hotkey, HotkeyModalConfig, HotkeySection};
176
177#[cfg(feature = "markdown")]
178pub use markdown_renderer::{render_markdown, render_markdown_with_style, MarkdownStyle};
179
180#[cfg(feature = "terminal")]
181pub use alac_term::{AlacTerm, AlacTermKeyBindings, KeyBinding};
182
183#[cfg(feature = "terminal")]
184pub use vt100_term::{KeyBinding as VT100KeyBinding, VT100Term, VT100TermKeyBindings};
185
186#[cfg(feature = "terminal")]
187pub use ai_chat::AiChat;
188
189#[cfg(feature = "terminal")]
190pub use termtui::{TermTui, TermTuiKeyBindings};
191
192#[cfg(feature = "fuzzy")]
193pub use fuzzy_finder::FuzzyFinder;
194
195#[cfg(feature = "file-tree")]
196pub use file_system_tree::{FileSystemEntry, FileSystemTree, FileSystemTreeConfig};
197
198#[cfg(feature = "master-layout")]
199pub use master_layout::{
200    EventResult, InteractionMode, MasterLayout, NavigationBar, PaneContent, PaneId, PaneLayout,
201    Tab, TabButton,
202};
203
204/// Prelude module for convenient imports
205///
206/// # Example
207///
208/// ```rust
209/// use ratatui_toolkit::prelude::*;
210/// ```
211pub mod prelude {
212    // Core components
213    pub use crate::button::{render_title_with_buttons, Button};
214    pub use crate::clickable_scrollbar::{
215        ClickableScrollbar, ClickableScrollbarState, ScrollbarEvent,
216    };
217    pub use crate::pane::Pane;
218
219    // Feature-gated components
220    #[cfg(feature = "dialog")]
221    pub use crate::dialog::{Dialog, DialogType, DialogWidget};
222
223    #[cfg(feature = "toast")]
224    pub use crate::toast::{render_toasts, Toast, ToastLevel, ToastManager};
225
226    #[cfg(feature = "split")]
227    pub use crate::resizable_split::{ResizableSplit, SplitDirection};
228
229    #[cfg(feature = "tree")]
230    pub use crate::tree_view::{
231        get_visible_paths, NodeState, TreeKeyBindings, TreeNavigator, TreeNode, TreeView,
232        TreeViewState,
233    };
234
235    #[cfg(feature = "menu")]
236    pub use crate::menu_bar::{MenuBar, MenuItem};
237
238    #[cfg(feature = "statusbar")]
239    pub use crate::statusbar::{StatusBar, StatusItem};
240
241    #[cfg(feature = "statusbar")]
242    pub use crate::statusline_stacked::{
243        OperationalMode, StatusLineStacked, StyledStatusLine, SLANT_BL_TR, SLANT_TL_BR,
244    };
245
246    #[cfg(feature = "hotkey")]
247    pub use crate::hotkey_footer::{HotkeyFooter, HotkeyFooterBuilder, HotkeyItem};
248
249    #[cfg(feature = "hotkey")]
250    pub use crate::hotkey_modal::{render_hotkey_modal, Hotkey, HotkeyModalConfig, HotkeySection};
251
252    #[cfg(feature = "markdown")]
253    pub use crate::markdown_renderer::{
254        render_markdown, render_markdown_with_style, MarkdownStyle,
255    };
256
257    #[cfg(feature = "terminal")]
258    pub use crate::alac_term::{AlacTerm, AlacTermKeyBindings, KeyBinding};
259
260    #[cfg(feature = "terminal")]
261    pub use crate::vt100_term::{KeyBinding as VT100KeyBinding, VT100Term, VT100TermKeyBindings};
262
263    #[cfg(feature = "terminal")]
264    pub use crate::ai_chat::AiChat;
265
266    #[cfg(feature = "terminal")]
267    pub use crate::termtui::{TermTui, TermTuiKeyBindings};
268
269    #[cfg(feature = "fuzzy")]
270    pub use crate::fuzzy_finder::FuzzyFinder;
271
272    #[cfg(feature = "file-tree")]
273    pub use crate::file_system_tree::{FileSystemEntry, FileSystemTree, FileSystemTreeConfig};
274
275    #[cfg(feature = "master-layout")]
276    pub use crate::master_layout::{
277        EventResult, InteractionMode, MasterLayout, NavigationBar, PaneContent, PaneId, PaneLayout,
278        Tab, TabButton,
279    };
280}
281
282/// Error types for the crate
283#[derive(Debug, thiserror::Error)]
284pub enum Error {
285    /// IO error
286    #[error("IO error: {0}")]
287    Io(#[from] std::io::Error),
288
289    /// Terminal error
290    #[error("Terminal error: {0}")]
291    Terminal(String),
292
293    /// Parse error
294    #[error("Parse error: {0}")]
295    Parse(String),
296}
297
298/// Result type for the crate
299pub type Result<T> = std::result::Result<T, Error>;
ratatui_toolkit/lib.rs

ratatui_toolkit/
lib.rs
