kanban-tui

Terminal UI for the kanban workspace, built with ratatui and crossterm. Depends on kanban-service for all state management and persistence.

Module Structure

src/
├── app/            # Application state, AppMode, event dispatch
├── components/     # Reusable UI widgets (panels, lists, popups)
├── handlers/       # Keyboard event handlers per mode
├── keybindings/    # Keybinding definitions and context registry
├── ui/             # Ratatui rendering for each view
└── lib.rs          # Public API: run()

Application State

App

The root application state struct:

pub struct App {
    pub mode: AppMode,
    pub mode_stack: Vec<AppMode>,
    pub focus: FocusState,
    // boards, columns, cards, sprints, ... all via KanbanContext
}

AppMode

pub enum AppMode {
    Normal,
    CardDetail,
    BoardDetail,
    SprintDetail,
    Search,
    ArchivedCardsView,
    Settings,
    Help(Box<AppMode>),     // wraps the previous mode for help overlay
    ErrorLog,               // structured error log viewer
    Dialog(DialogMode),
}

DialogMode

All 29 dialog variants:

Focus System

pub struct FocusState {
    pub active: Focus,         // Which top-level panel is active
    pub card_focus: CardFocus, // Which panel in CardDetail is active
    pub board_focus: BoardFocus, // Which panel in BoardDetail is active
    pub settings_focus: SettingsFocus,
}

pub enum Focus {
    Boards,
    Cards,
}

pub enum CardFocus {
    Title,
    Metadata,
    Description,
    Parents,
    Children,
}

pub enum BoardFocus {
    Name,
    Description,
    Settings,
    Sprints,
    Columns,
}

Focus is switched via number keys (1–5) or h/l.

View Strategies

Three card list view modes, toggled with V:

The active mode is persisted per-session and defaults to Flat.

Event Loop

crossterm event
       │
       ▼
  App::handle_key(KeyEvent)
       │
       ├─ dispatch to handler for current AppMode
       │    e.g. handle_normal_mode / handle_card_detail_key / handle_dialog / ...
       │
       ├─ state mutation (App fields + KanbanContext)
       │
       └─ mark dirty → auto-save via KanbanContext::save()

  ratatui render tick
       │
       └─ ui::draw(frame, &app)
            └─ render each panel based on app.mode and app.focus

Key Bindings

Normal Mode — Boards Panel

Normal Mode — Cards Panel

Card Detail View

Board Detail View

Sprint Detail View

Archived Cards View

External Editor Integration

Descriptions are edited in an external editor:

1. Detect editor: $EDITOR → nvim → vim → nano → vi
2. Write current description to a temp file
3. Spawn editor as a subprocess; wait for it to exit
4. Read modified content from the temp file
5. Update card description in KanbanContext

Clipboard

• y in card detail or card list: copies the git branch name (KAN-42/fix-login-bug)
• Y in card detail: copies the full git checkout -b KAN-42/fix-login-bug command

On Linux, clipboard content requires a clipboard manager to persist after the app exits (Wayland: wl-clip-persist; X11: usually built into the DE).

Markdown Renderer

Card descriptions are rendered with basic markdown formatting in the description panel: **bold**, *italic*, `code`, - lists, # headings.

Components

Position in the workspace

Unlike kanban-cli/kanban-mcp, kanban-tui depends on the storage backends unconditionally rather than behind Cargo features — there's no "minimal TUI without JSON support" build today.

graph TD
    CORE[kanban-core]
    DOM[kanban-domain] --> CORE
    PER[kanban-persistence] --> CORE
    PER --> DOM
    BE[kanban-backend] --> PER
    BEMEM[kanban-backend-memory] --> BE
    JSON[kanban-persistence-json] --> BE
    SQL[kanban-persistence-sqlite] --> BE
    SVC[kanban-service] --> BE
    TUI[kanban-tui] --> CORE
    TUI --> DOM
    TUI --> PER
    TUI --> BE
    TUI --> BEMEM
    TUI --> JSON
    TUI --> SQL
    TUI --> SVC
    CLI[kanban-cli] -.->|feature: tui, default-on| TUI

All edges shown out of kanban-tui are normal ([dependencies]) edges — it registers all four backends (in-memory, JSON, SQLite, and — via kanban-backend — the abstraction an HTTP backend would plug into) at startup itself, mirroring kanban-cli/kanban-mcp/kanban-server (KAN-1027: the app crates, not kanban-service, compose the concrete backends). The one dotted arrow (kanban-cli -.-> kanban-tui) is kanban-cli's tui feature, default-on. See the root README for the full workspace dependency graph.

Dependencies

Related crates

Used by: kanban-cli (optional feature tui, default-on).