# ratkit
> Comprehensive Rust TUI component library built on ratatui 0.29, providing 21 feature-gated modules (primitives, widgets, services) for building rich terminal applications.
This file provides a complete reference for working with the ratkit codebase. The repository is organized as a single crate at the root level with feature-based modularity. Use this guide to understand component relationships, find APIs, and follow established patterns when implementing new features.
## Agent Operating Rules
1. **Single crate at root**: All code is in `src/` with 21 feature flags (e.g., `button`, `pane`, `markdown-preview`)
2. **Enable features explicitly**: No default features; add required features to Cargo.toml (e.g., `features = ["button", "dialog"]`)
3. **Cross-feature dependencies**: Some features auto-enable others (e.g., `tree-view` enables `widget-event`, `repo-watcher` enables `file-watcher` and `git-watcher`)
4. **Use `just` for all operations**: Build (`just build`), test (`just test`), check (`just check`), demos (`just demo`)
5. **Run examples with `--features` flag**: Examples require their specific features (e.g., `--features markdown-preview`)
6. **Import from crate root**: All public APIs are re-exported from `ratkit::` (e.g., `use ratkit::Button`)
7. **StatefulWidget pattern**: Complex widgets require separate state structs persisted in app state
8. **Event loop polling**: Services require regular `check_for_changes()` calls in the event loop
9. **Mouse capture required**: Enable crossterm mouse capture for interactive widgets
10. **Persist widget state**: Never create widget state in render loops - store in app struct
11. **Validate before commits**: Run `just check` (format + lint + test) before committing
12. **Verify feature flags**: Compilation errors often indicate missing feature flags in Cargo.toml
## Environment and Version Constraints
- Rust 1.70+ required (workspace.rust-version in Cargo.toml)
- ratatui 0.29 as the underlying rendering library
- crossterm 0.28 for terminal input/events
- tokio for async runtime
- Single crate at root with 21 feature flags (no workspace members)
- 23 examples in `examples/` (moved from `crates/ratkit/examples/`)
- Optional external deps: notify (file watching), reqwest (ai-chat), pulldown-cmark/syntect (markdown), similar (code-diff)
## Quick Task Playbooks
### Run an example
- **Where to edit**: N/A
- **Related files**: `examples/`
- **Validation**: `cargo run --example button_button_demo --features button`
### Run with just
- **Where to edit**: N/A
- **Related files**: `justfile`
- **Validation**: `just demo` (interactive picker) or `just demo-md`, `just demo-term`, etc.
### Build with specific features
- **Where to edit**: `Cargo.toml` (root level)
- **Related files**: Feature definitions
- **Validation**: `cargo build --features "button,pane,dialog"`
### Build all features
- **Where to edit**: N/A
- **Related files**: All source files
- **Validation**: `cargo build --all-features`
### Run full verification
- **Where to edit**: N/A
- **Related files**: All source files
- **Validation**: `just check` (runs fmt-check, lint, test)
## Getting Started
```toml
# Cargo.toml - enable specific features
[dependencies]
ratkit = { version = "0.2", features = ["button", "dialog", "pane"] }
```
```rust
use ratkit::prelude::*;
use ratatui::Frame;
struct MyApp;
impl CoordinatorApp for MyApp {
fn on_event(&mut self, event: CoordinatorEvent) -> LayoutResult<CoordinatorAction> {
match event {
CoordinatorEvent::Keyboard(keyboard) => {
if keyboard.is_escape() {
return Ok(CoordinatorAction::Quit);
}
}
_ => {}
}
Ok(CoordinatorAction::Continue)
}
fn on_draw(&mut self, frame: &mut Frame) {
// Render your UI here
}
}
fn main() -> std::io::Result<()> {
let app = MyApp;
run(app, RunnerConfig::default())
}
```
## Workspace Overview
The ratkit workspace contains a **single crate** with 21 feature-gated modules organized into:
- **Primitives** (11 modules): Core UI building blocks in `src/primitives/`
- button, pane, dialog, toast, statusline, scroll, menu_bar, resizable_grid, tree_view, widget_event, termtui
- **Widgets** (6 modules): Higher-level composite widgets in `src/widgets/`
- markdown_preview, code_diff, ai_chat, hotkey_footer, file_system_tree, theme_picker
- **Services** (4 modules): Background monitoring services in `src/services/`
- file_watcher, git_watcher, repo_watcher, hotkey_service
- **Core Runtime** (1 module): Application lifecycle in `src/core/`
All modules follow feature-gated compilation. Enable only what you need.
## Core Runtime
The core runtime provides the application lifecycle, event routing, and element management for terminal UI applications.
### Key Components
- **CoordinatorApp trait**: Applications implement this to receive events and render
- **run() / run_with_diagnostics()**: Entry points to start the event loop
- **Element trait**: Implement for custom widgets that integrate with the coordinator
- **RunnerConfig**: Configuration for tick rate, layout debounce, mouse capture
### Architecture
- Three-region layout: Top, Center, Bottom
- Focus management with stack and traversal
- Mouse routing with z-order hit testing
- Element registry with weak references
## UI Primitives
Core UI building blocks for TUI applications, located in `src/primitives/`.
### Feature Flags
Each primitive has an individual feature flag:
- `button`, `pane`, `dialog`, `toast`, `statusline`, `scroll`
- `menu-bar` (enables `widget-event`)
- `resizable-grid`
- `tree-view` (enables `widget-event`)
- `widget-event`
- `termtui`
### Common Patterns
- Builder pattern with `new()` and `with_*` methods
- StatefulWidget pattern for complex state
- Event emission via `WidgetEvent`
- Mouse/keyboard interaction support
## Complex Widgets
Higher-level composite widgets in `src/widgets/`.
### Feature Flags
- `markdown-preview` - Most complex (syntax highlighting, TOC, themes, selection)
- `code-diff` - VS Code-style diff viewer
- `ai-chat` - AI chat interface (requires reqwest, serde)
- `hotkey-footer` - Keyboard shortcut footer
- `file-system-tree` - File browser with devicons
- `theme-picker` - Theme selector with 25+ themes
### External Dependencies
| ai-chat | reqwest, serde, serde_json |
| markdown-preview | pulldown-cmark, syntect, syntect-tui, notify, arboard, dirs |
| code-diff | similar |
| file-system-tree | devicons |
## Services
Background monitoring services in `src/services/`.
### Feature Flags
- `file-watcher` - Watch files/directories for changes
- `git-watcher` - Monitor git repository state
- `repo-watcher` - Combined file + git watching (enables file-watcher and git-watcher)
- `hotkey-service` - Global hotkey registration and management
### Common Dependencies
All watcher services use the `notify` crate for filesystem events.
## Usage Cards
### CoordinatorApp
- **Use when**: Building any ratkit TUI application
- **Enable/Install**: Core runtime, no feature flag needed
- **Import/Invoke**: `use ratkit::prelude::*;`
- **Minimal flow**:
1. Define struct implementing `CoordinatorApp`
2. Implement `on_event()` to handle events
3. Implement `on_draw()` to render UI
4. Call `run(app, RunnerConfig::default())`
- **Key APIs**: `on_event()`, `on_draw()`, `on_layout_changed()`
- **Pitfalls**: Runner takes ownership; wrap shared state in `Arc<RwLock<>>`
- **Source**: `src/coordinator.rs`, `src/runner_helper.rs`
### run()
- **Use when**: Starting the main application event loop
- **Enable/Install**: Core runtime, no feature flag
- **Import/Invoke**: `use ratkit::{run, run_with_diagnostics};`
- **Minimal flow**:
1. Create app implementing `CoordinatorApp`
2. Create `RunnerConfig::default()` or custom
3. Call `run(app, config)` or `run_with_diagnostics(app, config)` for debug overlay
- **Key APIs**: `run()`, `run_with_diagnostics()`, `RunnerConfig`
- **Pitfalls**: Blocks until exit; handles terminal init/cleanup
- **Source**: `src/runner_helper.rs`
### Element
- **Use when**: Creating custom widgets that integrate with coordinator
- **Enable/Install**: Core runtime
- **Import/Invoke**: `use ratkit::Element;`
- **Minimal flow**:
1. Implement `Element` trait for your widget
2. Define `id()`, `on_render()`, `on_keyboard()`, `on_mouse()`
3. Register with `ElementMetadata` and region
- **Key APIs**: `id()`, `on_render()`, `on_keyboard()`, `on_mouse()`, `on_focus_gain()`, `on_focus_loss()`, `on_tick()`
- **Pitfalls**: Registry stores weak refs - keep strong refs in app state; return `true` when handling events
- **Source**: `src/registry.rs`
### Button
- **Use when**: Clickable button with hover states
- **Enable/Install**: `features = ["button"]`
- **Import/Invoke**: `use ratkit::Button;`
- **Minimal flow**:
1. Create `Button::new("Label")`
2. Call `update_hover(x, y)` on mouse move
3. Call `is_clicked(x, y)` on click
4. Render with `render_with_title()`
- **Key APIs**: `new()`, `normal_style()`, `hover_style()`, `update_hover()`, `is_clicked()`
- **Pitfalls**: State must persist in app struct
- **Source**: `src/primitives/button/widget.rs`
### Pane
- **Use when**: Styled panel container with title/icon/padding
- **Enable/Install**: `features = ["pane"]`
- **Import/Invoke**: `use ratkit::Pane;`
- **Minimal flow**:
1. Create `Pane::new("Title")`
2. Chain builder methods: `with_icon()`, `with_padding()`, `border_style()`
3. Render as widget
- **Key APIs**: `new()`, `with_icon()`, `with_padding()`, `with_uniform_padding()`, `border_style()`
- **Pitfalls**: Padding reduces inner content area
- **Source**: `src/primitives/pane/mod.rs`
### Dialog
- **Use when**: Modal dialogs for confirmation/information
- **Enable/Install**: `features = ["dialog"]`
- **Import/Invoke**: `use ratkit::{Dialog, DialogState, DialogType};`
- **Minimal flow**:
1. Create `Dialog::new(title, message)` or use builder (`Dialog::confirm()`)
2. Set buttons with `.buttons(vec!["Yes", "No"])`
3. Create `DialogState::new()` for button selection
4. Render with `DialogWidget`
- **Key APIs**: `new()`, `info()`, `warning()`, `error()`, `success()`, `confirm()`, `buttons()`
- **Pitfalls**: DialogState must persist; uses StatefulWidget pattern
- **Source**: `src/primitives/dialog/`
### Toast
- **Use when**: Auto-dismissing notifications
- **Enable/Install**: `features = ["toast"]`
- **Import/Invoke**: `use ratkit::{ToastManager, ToastLevel};`
- **Minimal flow**:
1. Create `ToastManager::new()` in app state
2. Add toasts via `.success()`, `.error()`, `.info()`, `.warning()`
3. Call `cleanup()` before render
4. Render with `render_toasts()`
- **Key APIs**: `ToastManager::new()`, `.add()`, `.success()`, `.error()`, `.cleanup()`
- **Pitfalls**: Must call `cleanup()` to remove expired; doesn't auto-expire
- **Source**: `src/primitives/toast/`
### TreeView
- **Use when**: Hierarchical data with expand/collapse/selection
- **Enable/Install**: `features = ["tree-view"]` (auto-enables widget-event)
- **Import/Invoke**: `use ratkit::{TreeNode, TreeView, TreeViewState, TreeNavigator};`
- **Minimal flow**:
1. Build `TreeNode` hierarchy
2. Create `TreeView::new(nodes)` with render_fn
3. Create `TreeViewState::new()` for selection/expansion
4. Use `TreeNavigator` for keyboard handling
- **Key APIs**: `TreeNode::new()`, `TreeView::new()`, `TreeViewState::new()`, `TreeNavigator::new()`
- **Pitfalls**: TreeViewState must persist; TreeNavigator handles all keyboard nav
- **Source**: `src/primitives/tree_view/`
### MarkdownWidget
- **Use when**: Rendering markdown with syntax highlighting, TOC, themes
- **Enable/Install**: `features = ["markdown-preview"]` (complex dependencies)
- **Import/Invoke**: `use ratkit::widgets::markdown_preview::{MarkdownWidget, ScrollState, SourceState, ...};`
- **Minimal flow**:
1. Create state structs (ScrollState, SourceState, etc.) in app state
2. Create `MarkdownWidget::new(content, scroll, source, ...)`
3. Handle keyboard with `handle_key()`
4. Render with ratatui
- **Key APIs**: `new()`, `handle_key()`, `handle_mouse()`, `.show_toc()`, `.show_scrollbar()`
- **Pitfalls**: Requires mouse capture enabled; state must persist across renders
- **Source**: `src/widgets/markdown_preview/widgets/markdown_widget/`
### FileWatcher
- **Use when**: Detecting file/directory changes
- **Enable/Install**: `features = ["file-watcher"]` (uses notify crate)
- **Import/Invoke**: `use ratkit::services::file_watcher::FileWatcher;`
- **Minimal flow**:
1. Create `FileWatcher::for_file()` or `FileWatcher::for_directory()`
2. Call `watch(path)`
3. Poll `check_for_changes()` in event loop
4. Get changes with `get_changed_paths()`
- **Key APIs**: `for_file()`, `for_directory()`, `watch()`, `check_for_changes()`, `get_changed_paths()`
- **Pitfalls**: Must poll regularly; `get_changed_paths()` clears queue; debounced (100ms/200ms)
- **Source**: `src/services/file_watcher/`
### HotkeyService
- **Use when**: Centralized hotkey management with scope filtering
- **Enable/Install**: `features = ["hotkey-service"]`
- **Import/Invoke**: `use ratkit::services::hotkey_service::{Hotkey, HotkeyRegistry, HotkeyScope};`
- **Minimal flow**:
1. Create `HotkeyRegistry::new()`
2. Register hotkeys with `Hotkey::new(key, description).scope(scope)`
3. Set active scope with `set_active_scope()`
4. Query with `lookup(key, scope)` in event loop
- **Key APIs**: `HotkeyRegistry::new()`, `register()`, `lookup()`, `set_active_scope()`
- **Pitfalls**: Uses `&'static str` for scopes; must handle crossterm events separately
- **Source**: `src/services/hotkey_service/`
## API Reference
### Core Runtime
| CoordinatorApp | `on_event()`, `on_draw()`, `on_layout_changed()` |
| run | `run()`, `run_with_diagnostics()` |
| Element | `id()`, `on_render()`, `on_keyboard()`, `on_mouse()`, `on_focus_gain()`, `on_focus_loss()`, `on_tick()` |
| RunnerConfig | `tick_rate`, `layout_debounce`, `mouse_router_config` |
### Primitives
| Button | `new()`, `normal_style()`, `hover_style()`, `update_hover()`, `is_clicked()` |
| Pane | `new()`, `with_icon()`, `with_padding()`, `with_uniform_padding()`, `border_style()` |
| Dialog | `new()`, `info()`, `warning()`, `error()`, `success()`, `confirm()`, `buttons()` |
| Toast | `ToastManager::new()`, `.add()`, `.success()`, `.error()`, `.cleanup()` |
| TreeView | `TreeNode::new()`, `TreeView::new()`, `TreeViewState::new()`, `TreeNavigator::new()` |
| Scroll | `calculate_scroll_offset()` |
### Services
| FileWatcher | `for_file()`, `for_directory()`, `watch()`, `check_for_changes()`, `get_changed_paths()` |
| GitWatcher | `new()`, `with_config()`, `watch()`, `check_for_changes()` |
| RepoWatcher | `new()`, `with_config()`, `watch()`, `check_for_changes()`, `get_change_set()` |
| HotkeyRegistry | `new()`, `register()`, `lookup()`, `set_active_scope()` |
## Common Pitfalls
### Feature Flags
1. **No default features**: Must explicitly enable every feature you use
2. **Cross-feature deps**: `tree-view` enables `widget-event`; `repo-watcher` enables `file-watcher` and `git-watcher`
3. **Missing feature errors**: "unresolved import" usually means missing feature flag
### State Management
1. **StatefulWidget pattern**: Complex widgets require persistent state in app struct
2. **Never create state in render**: Always store widget state in app struct
3. **Weak references**: Element registry stores weak refs - keep strong refs in app
### Event Handling
1. **Return values**: Return `true` when consuming events, `false` to propagate
2. **Mouse capture**: Must enable crossterm mouse capture for interactions
3. **Poll services**: Must call `check_for_changes()` regularly on watchers
### Examples
1. **Feature flags required**: Examples need their specific features: `--features markdown-preview`
2. **Just commands**: Use `just demo` for interactive picker or `just demo-*` for specific demos
## Optional
### Additional Resources
- **Examples**: 23 examples in `examples/`
- **Just commands**: Run `just help` for all available commands
- **Build**: `just build` or `cargo build -p ratkit --all-features`
- **Test**: `just test`
### Version
- Current: 0.2.5
- Rust: 1.70+