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

Dependencies