# 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](https://ratatui.rs/) (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:

```rust
// "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](./installation.md)** — add the crate.
- **[Getting Started](./getting-started.md)** — a complete, runnable app in one file.
- **[Core Concepts](./core-concepts.md)** — 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.
