pages-tui/PROGRESS.md

# TUI Orchestrator - Progress Summary

## Current Status

### Completed Features ✅

#### Phase 1: Core Foundation
- **Input handling** (`src/input/`)
  - Key types (KeyCode, KeyModifiers, Key)
  - Bindings (key → action mappings)
  - SequenceHandler (multi-key sequences, feature-gated)
  - MatchResult (action/pending/no-match)
  
- **Focus management** (`src/focus/`)
  - FocusId trait (generic focus identifiers)
  - FocusManager (focus tracking, navigation, overlays)
  - FocusQuery (read-only focus state for rendering)
  - Focusable trait (components declare focusable elements)
  - FocusError (error types)

#### Documentation ✅
- **PLAN.md** - Complete implementation plan for framework approach
- **REDESIGN.md** - Deep dive into framework architecture
- **INTEGRATION_GUIDE.md** - User guide for building TUI apps
- **README.md** - Project overview and quick start

#### Tests ✅
- Input tests: 12 tests passing
- Focus tests: 18 tests passing
- Total: 30 tests covering all core functionality

---

## Next Steps

### Phase 2: Component System

The foundation for the entire framework. This is the highest priority.

**Files to create:**
- `src/component/mod.rs` - Module routing
- `src/component/trait.rs` - Component trait definition
- `src/component/action.rs` - Standard component actions
- `src/component/error.rs` - Component-specific errors

**Component trait design:**
```rust
pub trait Component {
    type Focus: FocusId + Clone;
    type Action: Action + Clone;
    type Event: Clone + core::fmt::Debug;
    
    // REQUIRED
    fn targets(&self) -> &[Self::Focus];
    fn handle(&mut self, focus: &Self::Focus, action: Self::Action) -> Result<Option<Self::Event>>;
    
    // OPTIONAL (all with defaults)
    fn on_enter(&mut self) -> Result<()>;
    fn on_exit(&mut self) -> Result<()>;
    fn on_focus(&mut self, focus: &Self::Focus) -> Result<()>;
    fn on_blur(&mut self, focus: &Self::Focus) -> Result<()>;
    fn handle_text(&mut self, focus: &Self::Focus, ch: char) -> Result<Option<Self::Event>>;
    fn can_navigate_forward(&self, focus: &Self::Focus) -> bool;
    fn can_navigate_backward(&self, focus: &Self::Focus) -> bool;
}
```

**ComponentAction enum:**
```rust
pub enum ComponentAction {
    Next,           // Tab → move focus forward
    Prev,            // Shift+Tab → move focus backward
    First,           // Home → move to first
    Last,            // End → move to last
    Select,          // Enter → activate current focus
    Cancel,          // Esc → cancel/close
    TypeChar(char),  // Character → type text
    Backspace,       // Backspace → delete before cursor
    Delete,          // Delete → delete at cursor
    Custom(usize),   // User-defined action
}
```

**Priority:** HIGHEST - This enables all other functionality

---

### Phase 3: Router & Lifecycle

Page navigation with automatic lifecycle hook invocation.

**Files to create:**
- `src/router/mod.rs` - Module routing
- `src/router/router.rs` - Router 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>,
    future: alloc::vec::Vec<String>,  // For forward navigation
}

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 → calls `new_page.on_enter()`
- `back()`/`forward()` manage history stack

**Priority:** HIGH - Essential for multi-page apps

---

### Phase 4: Orchestrator Core

The complete runtime that wires everything together.

**Files to create:**
- `src/orchestrator/mod.rs` - Module routing
- `src/orchestrator/core.rs` - Main Orchestrator struct
- `src/orchestrator/bindings.rs` - Default + custom bindings
- `src/orchestrator/modes.rs` - Mode stack and resolution
- `src/orchestrator/overlays.rs` - Overlay stack
- `src/orchestrator/events.rs` - Event bus

**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
7. Handle internal events (focus changes, page nav)
8. Return external events

**Priority:** HIGH - This makes the framework "ready to use"

---

### Phase 5: Extension Traits

Extension points for komp_ac and other complex apps.

**Files to create:**
- `src/extension/mod.rs` - Module routing
- `src/extension/mode.rs` - ModeResolver trait
- `src/extension/overlay.rs` - OverlayManager trait
- `src/extension/event.rs` - EventHandler trait

**ModeResolver trait:**
```rust
pub trait ModeResolver {
    fn resolve(&self, focus: &dyn core::any::Any) -> alloc::vec::Vec<ModeName>;
}

pub struct DefaultModeResolver;
impl ModeResolver for DefaultModeResolver { ... }
```

**OverlayManager trait:**
```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 trait:**
```rust
pub trait EventHandler<E> {
    fn handle(&mut self, event: E) -> Result<HandleResult>;
}

pub enum HandleResult {
    Consumed,
    Forward,
    Navigate(String),
}
```

**Priority:** MEDIUM - Defaults work for most apps, komp_ac needs these

---

### Phase 6: Builder & Defaults

Easy setup pattern with sensible defaults.

**Files to create:**
- `src/builder/mod.rs` - Module routing
- `src/builder/builder.rs` - Builder pattern
- `src/builder/defaults.rs` - Preset keybindings

**Builder API:**
```rust
pub struct Builder<C: Component> {
    orchestrator: Orchestrator<C>,
}

impl<C: Component> Builder<C> {
    pub fn new() -> Self;
    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() -> 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)); // Common quit
}
```

**Priority:** MEDIUM - Improves developer experience

---

### Phase 7: Integration with komp_ac

Adapters and integration helpers for seamless komp_ac migration.

**Files to create:**
- `src/integration/mod.rs` - Module routing
- `src/integration/komp_ac.rs` - komp_ac-specific adapters

**Integration 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>> { ... }
}
```

**komp_ac setup:**
```rust
let mut orch = Orchestrator::new()
    .with_mode_resolver(CanvasModeResolver::new(app_state))
    .with_overlay_manager(KompAcOverlayManager::new())
    .with_event_handler(KompAcEventHandler::new(router, focus));
```

**Priority:** LOW - Not needed for general library users, but essential for komp_ac

---

## File Structure After All Phases

```
src/
├── lib.rs                    # Routing
├── prelude.rs                # Common imports
│
├── input/                    # Phase 1 ✅
│   ├── mod.rs
│   ├── key.rs
│   ├── bindings.rs
│   ├── handler.rs
│   ├── result.rs
│   └── action.rs
│
├── focus/                    # Phase 1 ✅
│   ├── mod.rs
│   ├── id.rs
│   ├── manager.rs
│   ├── query.rs
│   ├── error.rs
│   └── traits.rs
│
├── component/                 # Phase 2 (NEXT)
│   ├── mod.rs
│   ├── trait.rs
│   ├── action.rs
│   └── error.rs
│
├── router/                    # Phase 3
│   ├── mod.rs
│   ├── router.rs
│   └── history.rs
│
├── orchestrator/              # Phase 4
│   ├── mod.rs
│   ├── core.rs
│   ├── bindings.rs
│   ├── modes.rs
│   ├── overlays.rs
│   └── events.rs
│
├── extension/                 # Phase 5
│   ├── mod.rs
│   ├── mode.rs
│   ├── overlay.rs
│   └── event.rs
│
├── builder/                   # Phase 6
│   ├── mod.rs
│   ├── builder.rs
│   └── defaults.rs
│
└── integration/               # Phase 7
    ├── mod.rs
    └── komp_ac.rs

tests/
├── input/
├── focus/
├── component/
├── router/
├── orchestrator/
└── integration/
```

---

## Testing Strategy

For each phase:

1. **Write tests first** - Define expected behavior
2. **Implement to pass** - Code should make tests pass
3. **Run cargo test** - Verify all pass
4. **Run cargo clippy** - Ensure code quality
5. **Run cargo fmt** - Ensure formatting

**Target:** 100% test coverage for all public APIs

---

## Dependencies Update

### Cargo.toml (after Phase 4)

```toml
[package]
name = "tui_orchestrator"
version = "0.1.0"
edition = "2021"
license = "MIT OR Apache-2.0"

[features]
default = ["std"]
std = []
alloc = ["hashbrown"]
sequences = ["alloc"]

[dependencies]
hashbrown = { version = "0.15", optional = true }

[dev-dependencies]
```

---

## Next Action

**Implement Phase 2: Component System**

This is the foundation that enables:
- Page/component registration
- Button logic definition
- Lifecycle hooks
- Everything the framework needs

**Tasks:**
1. Create `src/component/mod.rs`
2. Create `src/component/trait.rs` with Component trait
3. Create `src/component/action.rs` with ComponentAction enum
4. Create `src/component/error.rs` with ComponentError enum
5. Write tests in `tests/component/`
6. Update `src/lib.rs` to export component module
7. Update `src/prelude.rs` to include Component types
8. Run `cargo test --all-features`
9. Run `cargo clippy --all-features`
10. Update documentation if needed

Ready to implement?