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`] 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 = "fuzzy")]
125#[cfg_attr(docsrs, doc(cfg(feature = "fuzzy")))]
126pub mod fuzzy_finder;
127
128#[cfg(feature = "file-tree")]
129#[cfg_attr(docsrs, doc(cfg(feature = "file-tree")))]
130pub mod file_system_tree;
131
132#[cfg(feature = "master-layout")]
133#[cfg_attr(docsrs, doc(cfg(feature = "master-layout")))]
134pub mod master_layout;
135
136// Re-export commonly used types - always available
137pub use button::{render_title_with_buttons, Button};
138pub use clickable_scrollbar::{ClickableScrollbar, ClickableScrollbarState, ScrollbarEvent};
139pub use pane::Pane;
140
141// Feature-gated re-exports
142#[cfg(feature = "dialog")]
143pub use dialog::{Dialog, DialogType, DialogWidget};
144
145#[cfg(feature = "toast")]
146pub use toast::{render_toasts, Toast, ToastLevel, ToastManager};
147
148#[cfg(feature = "split")]
149pub use resizable_split::{ResizableSplit, SplitDirection};
150
151#[cfg(feature = "tree")]
152pub use tree_view::{
153    get_visible_paths, NodeState, TreeKeyBindings, TreeNavigator, TreeNode, TreeView, TreeViewState,
154};
155
156#[cfg(feature = "menu")]
157pub use menu_bar::{MenuBar, MenuItem};
158
159#[cfg(feature = "statusbar")]
160pub use statusbar::{StatusBar, StatusItem};
161
162#[cfg(feature = "statusbar")]
163pub use statusline_stacked::{
164    OperationalMode, StatusLineStacked, StyledStatusLine, SLANT_BL_TR, SLANT_TL_BR,
165};
166
167#[cfg(feature = "hotkey")]
168pub use hotkey_footer::{HotkeyFooter, HotkeyFooterBuilder, HotkeyItem};
169
170#[cfg(feature = "hotkey")]
171pub use hotkey_modal::{render_hotkey_modal, Hotkey, HotkeyModalConfig, HotkeySection};
172
173#[cfg(feature = "markdown")]
174pub use markdown_renderer::{render_markdown, render_markdown_with_style, MarkdownStyle};
175
176#[cfg(feature = "terminal")]
177pub use alac_term::AlacTerm;
178
179#[cfg(feature = "terminal")]
180pub use vt100_term::VT100Term;
181
182#[cfg(feature = "terminal")]
183pub use ai_chat::AiChat;
184
185#[cfg(feature = "fuzzy")]
186pub use fuzzy_finder::FuzzyFinder;
187
188#[cfg(feature = "file-tree")]
189pub use file_system_tree::{FileSystemEntry, FileSystemTree, FileSystemTreeConfig};
190
191#[cfg(feature = "master-layout")]
192pub use master_layout::{
193    EventResult, InteractionMode, MasterLayout, NavigationBar, PaneContent, PaneId, PaneLayout,
194    Tab, TabButton,
195};
196
197/// Prelude module for convenient imports
198///
199/// # Example
200///
201/// ```rust
202/// use ratatui_toolkit::prelude::*;
203/// ```
204pub mod prelude {
205    // Core components
206    pub use crate::button::{render_title_with_buttons, Button};
207    pub use crate::clickable_scrollbar::{
208        ClickableScrollbar, ClickableScrollbarState, ScrollbarEvent,
209    };
210    pub use crate::pane::Pane;
211
212    // Feature-gated components
213    #[cfg(feature = "dialog")]
214    pub use crate::dialog::{Dialog, DialogType, DialogWidget};
215
216    #[cfg(feature = "toast")]
217    pub use crate::toast::{render_toasts, Toast, ToastLevel, ToastManager};
218
219    #[cfg(feature = "split")]
220    pub use crate::resizable_split::{ResizableSplit, SplitDirection};
221
222    #[cfg(feature = "tree")]
223    pub use crate::tree_view::{
224        get_visible_paths, NodeState, TreeKeyBindings, TreeNavigator, TreeNode, TreeView,
225        TreeViewState,
226    };
227
228    #[cfg(feature = "menu")]
229    pub use crate::menu_bar::{MenuBar, MenuItem};
230
231    #[cfg(feature = "statusbar")]
232    pub use crate::statusbar::{StatusBar, StatusItem};
233
234    #[cfg(feature = "statusbar")]
235    pub use crate::statusline_stacked::{
236        OperationalMode, StatusLineStacked, StyledStatusLine, SLANT_BL_TR, SLANT_TL_BR,
237    };
238
239    #[cfg(feature = "hotkey")]
240    pub use crate::hotkey_footer::{HotkeyFooter, HotkeyFooterBuilder, HotkeyItem};
241
242    #[cfg(feature = "hotkey")]
243    pub use crate::hotkey_modal::{render_hotkey_modal, Hotkey, HotkeyModalConfig, HotkeySection};
244
245    #[cfg(feature = "markdown")]
246    pub use crate::markdown_renderer::{
247        render_markdown, render_markdown_with_style, MarkdownStyle,
248    };
249
250    #[cfg(feature = "terminal")]
251    pub use crate::alac_term::AlacTerm;
252
253    #[cfg(feature = "terminal")]
254    pub use crate::vt100_term::VT100Term;
255
256    #[cfg(feature = "terminal")]
257    pub use crate::ai_chat::AiChat;
258
259    #[cfg(feature = "fuzzy")]
260    pub use crate::fuzzy_finder::FuzzyFinder;
261
262    #[cfg(feature = "file-tree")]
263    pub use crate::file_system_tree::{FileSystemEntry, FileSystemTree, FileSystemTreeConfig};
264
265    #[cfg(feature = "master-layout")]
266    pub use crate::master_layout::{
267        EventResult, InteractionMode, MasterLayout, NavigationBar, PaneContent, PaneId, PaneLayout,
268        Tab, TabButton,
269    };
270}
271
272/// Error types for the crate
273#[derive(Debug, thiserror::Error)]
274pub enum Error {
275    /// IO error
276    #[error("IO error: {0}")]
277    Io(#[from] std::io::Error),
278
279    /// Terminal error
280    #[error("Terminal error: {0}")]
281    Terminal(String),
282
283    /// Parse error
284    #[error("Parse error: {0}")]
285    Parse(String),
286}
287
288/// Result type for the crate
289pub type Result<T> = std::result::Result<T, Error>;
ratatui_toolkit/lib.rs

ratatui_toolkit/
lib.rs
