Introduction - tui-pages

## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# tui-pages

You want to build a complex, keyboard-driven TUI app? So you start wiring key handlers to functions, those mutate some shared state, and a few hundred lines later you have a god object that every part of the app reaches into. Adding a page means touching everything. Thats why this crate was created.

`tui-pages` is the way out of that. It owns the boring, error-prone coordination — input, focus, navigation, panes — and leaves you with your own types and your own rendering. You describe what should happen ("move focus to the next thing", "go to the Settings page"); the library runs the state machine that makes it happen.

## The deal: who owns what

You own | tui-pages owns
--- | ---
Your `Action` enum | Turning key presses into your actions
Your `View`/page enum | Resolving typed commands (`:quit`) into actions
Your application state | Which element has focus, and moving it
All rendering | Buffer history, panes, splits
The actual side effects of an action | Multi-key chord sequences, modes

The library ships no rendering. You draw your state with ratatui (or anything else). The one exception is the optional `dialog` feature — an opt-in modal you can drop in. (It fits every big app, so I included it)

## The one idea to take away

Your code never reaches in and mutates focus, or pushes onto the buffer history, or splits a pane. You can't, really — those live inside the runtime. Instead your action handler returns a value describing what it wants:

    #![allow(unused)]
    fn main() {
    // "the user pressed Tab — move focus forward"
    ActionOutcome::effect(TuiEffect::Focus(FocusIntent::Next))

    // "the user picked the Settings button — go there"
    ActionOutcome::effect(TuiEffect::Navigate(View::Settings))
    }

The runtime applies that effect. That's the whole model. Once it clicks, every page in this book is just a catalogue of effects you can return and targets you can declare.

## Where to go next

- Installation — add the crate.
- Getting Started — a complete, runnable app in one file.
- Core Concepts — the types, `PageSpec`, and effects.
- The rest of the book drills into focus, navigation, commands, and dialogs.

There are also four runnable examples in the repo (`examples/`). They are the real source of truth — every snippet here is lifted from them.