541 lines
16 KiB
Markdown
541 lines
16 KiB
Markdown
# TUI Orchestrator - Complete TUI Framework
|
|
|
|
## Overview
|
|
|
|
`tui_orchestrator` is a **ready-to-use TUI framework** that provides a complete runtime for building terminal user interfaces. Users define their pages, buttons, and logic—library handles everything else: input routing, focus management, page navigation, lifecycle hooks, and event orchestration.
|
|
|
|
### Key Philosophy
|
|
|
|
**"Register pages with buttons and logic—it just works."**
|
|
|
|
The library is a **complete application framework** where:
|
|
- User defines components (pages with focusable elements)
|
|
- Library orchestrates all runtime concerns
|
|
- Everything is optional—define what you need
|
|
- Fully extendable for complex apps like komp_ac
|
|
|
|
### Zero Boilerplate
|
|
|
|
Users write:
|
|
```rust
|
|
impl Component for LoginPage {
|
|
fn targets(&self) -> &[Focus];
|
|
fn handle(&mut self, focus: &Focus, action: Action) -> Result<Option<Event>> {
|
|
// What happens when button pressed
|
|
}
|
|
}
|
|
```
|
|
|
|
Library handles:
|
|
- Input processing
|
|
- Focus management
|
|
- Page navigation
|
|
- Lifecycle hooks
|
|
- Event routing
|
|
- Default keybindings
|
|
|
|
### Extension Model
|
|
|
|
komp_ac can use the library for 90% of functionality while extending:
|
|
- Mode resolution (dynamic Canvas-style modes)
|
|
- Overlay management (command palette, find file, search)
|
|
- Event routing (global vs page vs canvas actions)
|
|
- Custom behaviors (boundary detection, navigation rules)
|
|
|
|
**Defaults work, override what's different.**
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ User Code (What You Define) │
|
|
│ │
|
|
│ Component trait │
|
|
│ - Page structs/enums │
|
|
│ - Focus targets (buttons, fields) │
|
|
│ - Button logic (what happens on press) │
|
|
│ - Lifecycle hooks (optional) │
|
|
└─────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────┐
|
|
│ Orchestrator (Library Runtime) │
|
|
│ │
|
|
│ - ComponentRegistry │
|
|
│ - FocusManager │
|
|
│ - Bindings (default + custom) │
|
|
│ - Router + history │
|
|
│ - ModeStack │
|
|
│ - OverlayStack │
|
|
│ - EventBus │
|
|
└─────────────────────────────────────────────────┘
|
|
↓
|
|
┌─────────────────────────────────────────────────┐
|
|
│ Extension Points (For komp_ac) │
|
|
│ │
|
|
│ - ModeResolver (dynamic mode resolution) │
|
|
│ - OverlayManager (custom overlay types) │
|
|
│ - EventHandler (custom event routing) │
|
|
│ - FocusNavigation (boundary detection) │
|
|
└─────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Core Foundation ✅ COMPLETE
|
|
|
|
**Completed:**
|
|
- `src/input/` - Key types, bindings, sequence handling
|
|
- `src/focus/` - Focus manager, queries, traits
|
|
|
|
**What this provides:**
|
|
- Backend-agnostic key representation
|
|
- Key-to-action mappings
|
|
- Focus tracking with navigation
|
|
- Generic focus IDs (user-defined enums, `usize`, `String`, etc.)
|
|
|
|
---
|
|
|
|
### Phase 2: Component System (CURRENT)
|
|
|
|
**Goal:** Unified abstraction for pages/components.
|
|
|
|
**Files to create:**
|
|
- `src/component/mod.rs` - Component trait
|
|
- `src/component/action.rs` - Standard component actions
|
|
- `src/component/error.rs` - Component-specific errors
|
|
|
|
**Component Trait:**
|
|
|
|
```rust
|
|
pub trait Component {
|
|
type Focus: FocusId + Clone;
|
|
type Action: Action + Clone;
|
|
type Event: Clone + core::fmt::Debug;
|
|
|
|
fn targets(&self) -> &[Self::Focus];
|
|
fn handle(&mut self, focus: &Self::Focus, action: Self::Action) -> Result<Option<Self::Event>>;
|
|
|
|
fn on_enter(&mut self) -> Result<()> { Ok(()) }
|
|
fn on_exit(&mut self) -> Result<()> { Ok(()) }
|
|
fn on_focus(&mut self, focus: &Self::Focus) -> Result<()> { Ok(()) }
|
|
fn on_blur(&mut self, focus: &Self::Focus) -> Result<()> { Ok(()) }
|
|
fn handle_text(&mut self, focus: &Self::Focus, ch: char) -> Result<Option<Self::Event>> { Ok(None) }
|
|
fn can_navigate_forward(&self, focus: &Self::Focus) -> bool { true }
|
|
fn can_navigate_backward(&self, focus: &Self::Focus) -> bool { true }
|
|
}
|
|
```
|
|
|
|
**Standard Component Actions:**
|
|
|
|
```rust
|
|
pub enum ComponentAction {
|
|
Next, // Tab by default
|
|
Prev, // Shift+Tab by default
|
|
First,
|
|
Last,
|
|
Select, // Enter by default
|
|
Cancel, // Esc by default
|
|
TypeChar(char),
|
|
Backspace,
|
|
Delete,
|
|
Custom(usize), // User extension
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 3: Router & Lifecycle
|
|
|
|
**Goal:** Page navigation with automatic lifecycle hooks.
|
|
|
|
**Files to create:**
|
|
- `src/router/mod.rs` - Router trait and implementation
|
|
- `src/router/history.rs` - Navigation history
|
|
|
|
**Router API:**
|
|
|
|
```rust
|
|
pub struct Router<C: Component> {
|
|
pages: alloc::collections::HashMap<String, C>,
|
|
current: Option<String>,
|
|
history: alloc::vec::Vec<String>,
|
|
}
|
|
|
|
impl<C: Component> Router<C> {
|
|
pub fn new() -> Self;
|
|
pub fn navigate(&mut self, id: &str) -> Result<()>;
|
|
pub fn back(&mut self) -> Result<Option<()>>;
|
|
pub fn forward(&mut self) -> Result<Option<()>>;
|
|
pub fn current(&self) -> Option<&C>;
|
|
}
|
|
```
|
|
|
|
**Automatic behavior:**
|
|
- `navigate()` calls `old_page.on_exit()` → swaps page → calls `new_page.on_enter()`
|
|
- `back()`/`forward()` manage history stack
|
|
- Focus targets auto-updated from `targets()`
|
|
|
|
---
|
|
|
|
### Phase 4: Orchestrator (The Core Runtime)
|
|
|
|
**Goal:** Wire everything together into complete TUI runtime.
|
|
|
|
**Files to create:**
|
|
- `src/orchestrator/mod.rs` - Orchestrator struct
|
|
- `src/orchestrator/modes.rs` - Mode stack and resolution
|
|
- `src/orchestrator/overlays.rs` - Overlay stack
|
|
- `src/orchestrator/events.rs` - Event bus
|
|
- `src/orchestrator/bindings.rs` - Default + custom bindings
|
|
|
|
**Orchestrator API:**
|
|
|
|
```rust
|
|
pub struct Orchestrator<C: Component> {
|
|
registry: ComponentRegistry<C>,
|
|
focus: FocusManager<C::Focus>,
|
|
bindings: Bindings<ComponentAction>,
|
|
router: Router<C>,
|
|
modes: ModeStack<ModeName>,
|
|
overlays: OverlayStack<C::Event>,
|
|
events: EventBus<C::Event>,
|
|
}
|
|
|
|
impl<C: Component> Orchestrator<C> {
|
|
pub fn new() -> Self;
|
|
|
|
pub fn register_page(&mut self, id: &str, page: C) -> Result<()>;
|
|
pub fn navigate_to(&mut self, id: &str) -> Result<()>;
|
|
|
|
pub fn process_frame(&mut self, key: Key) -> Result<alloc::vec::Vec<C::Event>>;
|
|
pub fn run<I: InputSource>(&mut self, input: I) -> Result<()>;
|
|
|
|
// Extension points
|
|
pub fn set_mode_resolver<R: ModeResolver + 'static>(&mut self, resolver: R);
|
|
pub fn set_overlay_manager<O: OverlayManager + 'static>(&mut self, manager: O);
|
|
pub fn set_event_handler<H: EventHandler<C::Event> + 'static>(&mut self, handler: H);
|
|
}
|
|
```
|
|
|
|
**Process flow:**
|
|
1. Check overlay active → route to overlay
|
|
2. Get current mode + focus
|
|
3. Lookup binding → get action
|
|
4. Get current component
|
|
5. Call `component.handle(action, focus)`
|
|
6. Collect events returned
|
|
7. Handle internal events (focus changes, page nav)
|
|
8. Return external events to user
|
|
|
|
---
|
|
|
|
### Phase 5: Extension Traits
|
|
|
|
**Goal:** Provide extension points for komp_ac's custom behavior.
|
|
|
|
**Files to create:**
|
|
- `src/extension/mod.rs` - Extension traits
|
|
- `src/extension/mode.rs` - Mode resolver
|
|
- `src/extension/overlay.rs` - Overlay manager
|
|
- `src/extension/event.rs` - Event handler
|
|
|
|
**ModeResolver (for dynamic mode resolution):**
|
|
|
|
```rust
|
|
pub trait ModeResolver {
|
|
fn resolve(&self, focus: &dyn core::any::Any) -> alloc::vec::Vec<ModeName>;
|
|
}
|
|
|
|
pub struct DefaultModeResolver;
|
|
impl ModeResolver for DefaultModeResolver {
|
|
fn resolve(&self, _focus: &dyn core::any::Any) -> alloc::vec::Vec<ModeName> {
|
|
alloc::vec![ModeName::General]
|
|
}
|
|
}
|
|
```
|
|
|
|
**OverlayManager (for custom overlays):**
|
|
|
|
```rust
|
|
pub trait OverlayManager {
|
|
fn is_active(&self) -> bool;
|
|
fn handle_input(&mut self, key: Key) -> Option<OverlayResult>;
|
|
}
|
|
|
|
pub enum OverlayResult {
|
|
Dismissed,
|
|
Selected(OverlayData),
|
|
Continue,
|
|
}
|
|
```
|
|
|
|
**EventHandler (for custom event routing):**
|
|
|
|
```rust
|
|
pub trait EventHandler<E> {
|
|
fn handle(&mut self, event: E) -> Result<HandleResult>;
|
|
}
|
|
|
|
pub enum HandleResult {
|
|
Consumed,
|
|
Forward,
|
|
Navigate(String),
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 6: Builder & Defaults
|
|
|
|
**Goal:** Easy setup with sensible defaults.
|
|
|
|
**Files to create:**
|
|
- `src/builder/mod.rs` - Builder pattern
|
|
- `src/defaults/bindings.rs` - Preset keybindings
|
|
|
|
**Builder API:**
|
|
|
|
```rust
|
|
impl<C: Component> Orchestrator<C> {
|
|
pub fn builder() -> Builder<C> { Builder::new() }
|
|
}
|
|
|
|
pub struct Builder<C: Component> {
|
|
orchestrator: Orchestrator<C>,
|
|
}
|
|
|
|
impl<C: Component> Builder<C> {
|
|
pub fn with_page(mut self, id: &str, page: C) -> Result<Self>;
|
|
pub fn with_default_bindings(mut self) -> Self;
|
|
pub fn with_mode_resolver<R: ModeResolver + 'static>(mut self, resolver: R) -> Self;
|
|
pub fn with_overlay_manager<O: OverlayManager + 'static>(mut self, manager: O) -> Self;
|
|
pub fn build(self) -> Result<Orchestrator<C>>;
|
|
}
|
|
```
|
|
|
|
**Default bindings:**
|
|
|
|
```rust
|
|
pub fn default_bindings<A: Action>() -> Bindings<ComponentAction> {
|
|
let mut bindings = Bindings::new();
|
|
bindings.bind(Key::tab(), ComponentAction::Next);
|
|
bindings.bind(Key::shift_tab(), ComponentAction::Prev);
|
|
bindings.bind(Key::enter(), ComponentAction::Select);
|
|
bindings.bind(Key::esc(), ComponentAction::Cancel);
|
|
bindings.bind(Key::ctrl('c'), ComponentAction::Custom(0)); // Quit
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### Phase 7: Integration (Optional)
|
|
|
|
**Goal:** Seamless integration with komp_ac.
|
|
|
|
**Files to create:**
|
|
- `src/integration/mod.rs` - Integration helpers
|
|
- `src/integration/komp_ac.rs` - komp_ac-specific adapters
|
|
|
|
**Adapter pattern:**
|
|
|
|
```rust
|
|
impl Component for komp_ac::LoginPage {
|
|
type Focus = komp_ac::FocusTarget;
|
|
type Action = komp_ac::ResolvedAction;
|
|
type Event = komp_ac::AppEvent;
|
|
|
|
fn targets(&self) -> &[Self::Focus] { ... }
|
|
fn handle(&mut self, focus: &Self::Focus, action: Self::Action) -> Result<Option<Self::Event>> { ... }
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
```
|
|
src/
|
|
├── lib.rs # Routing only, re-exports
|
|
├── prelude.rs # Common imports
|
|
│
|
|
├── input/ # Phase 1 ✅
|
|
│ ├── mod.rs
|
|
│ ├── key.rs # KeyCode, KeyModifiers
|
|
│ ├── bindings.rs # Bindings
|
|
│ ├── handler.rs # InputHandler
|
|
│ ├── result.rs # MatchResult
|
|
│ └── action.rs # Action trait
|
|
│
|
|
├── focus/ # Phase 1 ✅
|
|
│ ├── mod.rs
|
|
│ ├── id.rs # FocusId trait
|
|
│ ├── manager.rs # FocusManager
|
|
│ ├── query.rs # FocusQuery
|
|
│ ├── error.rs # FocusError
|
|
│ └── traits.rs # Focusable
|
|
│
|
|
├── component/ # Phase 2
|
|
│ ├── mod.rs
|
|
│ ├── trait.rs # Component trait
|
|
│ ├── action.rs # ComponentAction
|
|
│ └── error.rs # ComponentError
|
|
│
|
|
├── router/ # Phase 3
|
|
│ ├── mod.rs
|
|
│ ├── router.rs # Router
|
|
│ └── history.rs # HistoryStack
|
|
│
|
|
├── orchestrator/ # Phase 4
|
|
│ ├── mod.rs
|
|
│ ├── core.rs # Orchestrator
|
|
│ ├── modes.rs # ModeStack, ModeResolver
|
|
│ ├── overlays.rs # OverlayStack
|
|
│ ├── bindings.rs # Component bindings
|
|
│ └── events.rs # EventBus
|
|
│
|
|
├── extension/ # Phase 5
|
|
│ ├── mod.rs
|
|
│ ├── mode.rs # ModeResolver trait
|
|
│ ├── overlay.rs # OverlayManager trait
|
|
│ └── event.rs # EventHandler trait
|
|
│
|
|
├── builder/ # Phase 6
|
|
│ ├── mod.rs
|
|
│ ├── builder.rs # Builder pattern
|
|
│ └── defaults.rs # Default bindings
|
|
│
|
|
└── integration/ # Phase 7
|
|
├── mod.rs
|
|
└── komp_ac.rs # komp_ac adapters
|
|
|
|
tests/ # Mirror src/ structure
|
|
├── input/
|
|
├── focus/
|
|
├── component/
|
|
├── router/
|
|
├── orchestrator/
|
|
└── integration/
|
|
```
|
|
|
|
---
|
|
|
|
## Design Principles
|
|
|
|
### From AGENTS.md
|
|
|
|
- **Feature-based tree structure**—group by domain
|
|
- **Each feature is self-contained**—handler, logic, types, tests
|
|
- **Functional programming style**—pure functions, stateless where possible
|
|
- **Use structs, traits, enums, impl, match** over if
|
|
- **No Arc/Mutex/RefCell**
|
|
- **Result<T, E> everywhere**
|
|
- **mod.rs is for routing only**
|
|
- **No comments unless necessary**
|
|
|
|
### Additional for Framework
|
|
|
|
- **Batteries included**—not just building blocks
|
|
- **Sensible defaults**—zero configuration works
|
|
- **Optional everything**—define only what you need
|
|
- **Extension points**—override defaults when needed
|
|
- **no_std compatible**—works on embedded, WASM
|
|
- **Backend-agnostic**—no crossterm/ratatui dependencies
|
|
- **User-focused**—"register page" not "register_chord"
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
### Core (no_std)
|
|
|
|
- `alloc` - For dynamic collections (Vec, HashMap)
|
|
|
|
### Optional Features
|
|
|
|
- `std` - Enable std library support
|
|
- `sequences` - Enable multi-key sequences
|
|
|
|
---
|
|
|
|
## User Experience
|
|
|
|
### Before (Building Blocks)
|
|
|
|
Users must manually wire everything:
|
|
- Create focus manager
|
|
- Create bindings
|
|
- Create router
|
|
- Set up components
|
|
- Write main loop
|
|
- Handle lifecycle manually
|
|
|
|
**Result:** Lots of boilerplate, easy to get wrong.
|
|
|
|
### After (Framework)
|
|
|
|
Users define components and run:
|
|
|
|
```rust
|
|
#[derive(Debug, Clone)]
|
|
struct LoginPage;
|
|
|
|
impl Component for LoginPage {
|
|
fn targets(&self) -> &[Focus] { ... }
|
|
fn handle(&mut self, focus: &Focus, action: Action) -> Result<Option<Event>> { ... }
|
|
}
|
|
|
|
fn main() -> Result<()> {
|
|
let mut orch = Orchestrator::new();
|
|
orch.register_page("login", LoginPage::new())?;
|
|
orch.run()?;
|
|
}
|
|
```
|
|
|
|
**Result:** Zero boilerplate, everything just works.
|
|
|
|
---
|
|
|
|
## Migration for komp_ac
|
|
|
|
### Before Integration
|
|
|
|
komp_ac has:
|
|
- Custom orchestrator
|
|
- Custom mode resolution (Canvas-style)
|
|
- Custom overlays (command bar, find file, search)
|
|
- Custom action routing (page vs canvas vs global)
|
|
|
|
### After Integration
|
|
|
|
komp_ac:
|
|
1. Implements `Component` trait for all pages
|
|
2. Uses library's `Orchestrator` as runtime
|
|
3. Extends with custom `ModeResolver`
|
|
4. Extends with custom `OverlayManager`
|
|
5. Extends with custom `EventHandler`
|
|
|
|
**Result:**
|
|
- Library handles 90% of runtime
|
|
- komp_ac keeps all custom behavior
|
|
- No code duplication
|
|
- Cleaner, more maintainable codebase
|
|
|
|
---
|
|
|
|
## Feature Checklist
|
|
|
|
- [x] Phase 1: Input handling (keys, bindings, focus)
|
|
- [ ] Phase 2: Component trait and actions
|
|
- [ ] Phase 3: Router with lifecycle
|
|
- [ ] Phase 4: Orchestrator runtime
|
|
- [ ] Phase 5: Extension traits
|
|
- [ ] Phase 6: Builder and defaults
|
|
- [ ] Phase 7: Integration with komp_ac
|
|
- [ ] Documentation updates
|
|
- [ ] Example applications
|
|
- [ ] Full test coverage
|