Current section

Files

Jump to
ex_ratatui usage-rules.md
Raw

usage-rules.md

# ExRatatui Usage Rules

ExRatatui is Elixir bindings for the Rust [ratatui](https://ratatui.rs) terminal UI library, via Rustler NIFs. It builds rich terminal UIs that run on the BEAM's DirtyIo scheduler, so rendering never blocks application processes.

It is **not** the Rust ratatui API and **not** bubbletea. Widgets are plain Elixir structs (pure view descriptors), assembled each frame and handed to a draw/render function. There are no stateful widget objects that update in place.

## Choosing a runtime

Pick the runtime before writing any code — this is the single most important decision and the easiest to get wrong.

| Use | When | Shape |
|-----|------|-------|
| `ExRatatui.run/2` | Scripts, one-shots, examples, throwaway demos | A closure that draws and polls events itself |
| `use ExRatatui.App` | Supervised interactive apps (the default) | LiveView-style `mount/1`, `render/2`, `handle_event/2`, `handle_info/2` |
| `use ExRatatui.App, runtime: :reducer` | Apps wanting pure transitions, declarative timers, and managed side effects | `init/1`, `update/2`, `render/2`, `subscriptions/1` + `Command`/`Subscription` |

- The callback runtime is the default and fits most apps. Reach for the reducer runtime when modeling the app as `(msg, state) -> state` with `Command`-driven effects and `Subscription`-driven timers is worth the structure.
- Both `App` runtimes are supervised: add `{MyApp.TUI, opts}` to a supervision tree. Never hand-roll the loop with `run/2` for a long-lived interactive app.
- Erlang and Gleam modules can't call `use`: they export the `ExRatatui.App` callbacks and start with `ExRatatui.App.start_link/2` or `child_spec/2`. Widgets and nested values are built with `'Elixir.ExRatatui.Style':'__struct__'(#{...})`, never plain maps. Install steps and the reducer style are in the [Erlang and Gleam guide](https://hexdocs.pm/ex_ratatui/erlang_and_gleam.html).

## Core API shape

Canonical entry points for a raw `run/2` loop — match these signatures exactly, do not invent Rust- or bubbletea-shaped calls:

```elixir
# fun receives a terminal reference; terminal is restored on exit, even on raise
ExRatatui.run(fn terminal ->
  {width, height} = ExRatatui.terminal_size()

  # draw/2 takes a LIST of {widget_struct, %Rect{}} tuples — a bare widget draws nothing
  ExRatatui.draw(terminal, [
    {%ExRatatui.Widgets.Paragraph{text: "hi"},
     %ExRatatui.Layout.Rect{x: 0, y: 0, width: width, height: height}}
  ])

  ExRatatui.poll_event(60_000)
end, mouse_capture: false, focus_events: false)
```

- `run/2` — `run(fun, opts \\ [])`. `fun` is arity-1, receiving a terminal reference. Opts: `:mouse_capture`, `:focus_events` and `:keyboard_enhancement`, all **default `false`** on the local transport — opt in explicitly when needed.
- `draw/2` — `draw(terminal, [{widget, %Rect{}}, ...])`. The rect, in absolute 0-based cell coordinates, says where to paint.
- `poll_event/1` — `poll_event(timeout_ms \\ 250)`. Returns an `ExRatatui.Event.*` struct, `nil` on timeout, or `{:error, reason}`.
- `terminal_size/0` — returns `{width, height}` (a tuple, not a `Rect`).
- `Layout.split/4` — `split(area, direction, constraints, opts \\ [])`. Returns a list of `%Rect{}` (one per constraint). Direction is `:horizontal | :vertical`; constraints are `{:percentage, n}`, `{:length, n}`, `{:min, n}`, `{:max, n}`, `{:ratio, num, den}`, `{:fill, weight}`.
- `%ExRatatui.Layout.Rect{x: 0, y: 0, width: 0, height: 0}` — placement is explicit; widgets do not auto-resize to the terminal.

In an `App`, `render/2` receives `(state, %ExRatatui.Frame{width:, height:})` and returns the **full** `[{widget, %Rect{}}]` list for the whole screen — describe the entire frame every time, never a partial delta. The runtime diffs cells.

## Widget index

All widgets are structs under `ExRatatui.Widgets.*` (a few have a companion data module under `ExRatatui.*`). Knowing what exists prevents reinventing it.

**Text and containers**
- `Paragraph` — wrapped/aligned text with an optional block frame
- `Block` — borders, titles (top/bottom, per-title alignment via `Block.Title`)
- `Clear` — clears a region (use under popups/overlays)

**Lists and tables**
- `List` — selectable item list
- `Table` — rows, columns, header, selection
- `WidgetList` — vertically stacked, scrollable list of primitive widgets

**Progress and activity**
- `Gauge` — ratio bar with label
- `LineGauge` — single-line ratio bar
- `Sparkline` — compact inline trend line
- `Throbber` — animated spinner

**Charts and drawing**
- `BarChart` — bars (`Bar`, `BarGroup` data modules)
- `Chart` — line/scatter datasets (`Chart.Axis`, `Chart.Dataset`)
- `Canvas` — freeform drawing (`Circle`, `Label`, `Line`, `Map`, `Points`, `Rectangle`)

**Navigation and selection**
- `Tabs` — horizontal tab bar
- `Scrollbar` — scroll position indicator
- `Calendar` — month grid
- `Checkbox` — toggle
- `Popup` — modal/overlay container
- `SlashCommands` — command palette (`SlashCommands.Command`)

**Input (stateful — NIF-backed)**
- `TextInput` — single-line editor; drive via `ExRatatui.text_input_*` helpers
- `Textarea` — multi-line editor; drive via `ExRatatui.textarea_*` helpers

**Rich / special**
- `Markdown` — rendered Markdown
- `Image` — image rendering (`ExRatatui.Image` decodes; Kitty/Sixel/iTerm2/halfblocks). Resizing uses `filter: :catmull_rom` by default; pass `filter: :nearest` only for pixel art, since it breaks thin text strokes in screenshots
- `BigText` — oversized 8x8 pixel text (`ExRatatui.BigText`)
- `CodeBlock` — syntax-highlighted code (`ExRatatui.CodeBlock`)

**App-level helpers (not widgets)**
- `ExRatatui.Focus` — focus ring for multi-panel apps. `handle_key/2` consumes Tab/Shift+Tab and returns `{focus, key_or_nil}` (`nil` = consumed); register rects to get click-to-focus via `handle_mouse/2`; style with `focused?/2`. Pure data, no process — do not hand-roll focus tracking.
- `ExRatatui.Theme` — semantic color palette (eleven slots) with `default/0` / `light/0` constructors and `border_style/2` / `text_style/2` / `selection_style/1` helpers. Pure data threaded through render code — no globals, no automatic widget injection.
- `ExRatatui.CellSession` — render to a cell buffer instead of ANSI bytes (Phoenix LiveView, screenshots, custom surfaces); reach for it before parsing ANSI out of a `Session`. For pixel displays such as e-ink panels or Linux framebuffers, use [raster_ex_ratatui](https://hexdocs.pm/raster_ex_ratatui) rather than rasterising cells by hand. Pixel regions are in the [CellSession guide](https://hexdocs.pm/ex_ratatui/cell_session.html), and rotating and packing them in the [framebuffer guide](https://hexdocs.pm/ex_ratatui/framebuffer_surfaces.html).

Compose custom composite widgets in pure Elixir via the `ExRatatui.Widget` protocol — no Rust required. See the Custom Widgets guide.

## Anti-patterns and gotchas

Highest-value rules. The guides hold the full set; these are the ones agents get wrong most.

- **Key event fields are lowercase strings, never atoms — wrong values compile and silently never match.** The shape is `%Event.Key{code: "up", kind: "press", modifiers: ["ctrl"]}`. Character keys are their string value (`"a"`, `"1"`, `" "`); special keys include `"enter"`, `"esc"`, `"tab"`, `"back_tab"`, `"backspace"`, `"up"` / `"down"` / `"left"` / `"right"`, `"page_up"` / `"page_down"`, `"f1"`..`"f12"` — full table in `ExRatatui.Event.Key`. `kind` is always `"press"` unless the app is started with `keyboard_enhancement: true` (`:local` / `run/2`), which adds `"repeat"` (autorepeat) and `"release"` on terminals with the kitty keyboard protocol — handlers that should keep firing while a key is held must match `"repeat"` too. Mouse events use string `kind` / `button` the same way (`%Event.Mouse{kind: "down", button: "left", x: 0, y: 0}`).
- **Never call `draw/2` with a bare widget — pass `[{widget, %Rect{}}, ...]`.** A widget without a rect paints nothing.
- **Never treat a widget as stateful — rebuild the struct each frame.** Widgets are immutable view descriptors, not objects that mutate in place.
- **Never return a partial scene from `render/2` — return the whole screen.** The runtime diffs cells; the job is to describe the full frame.
- **Never create `TextInput`/`Textarea` state in `render/2` — create it once in `mount/1`/`init/1` and keep the ref in state.** Recreating it each render drops cursor position and typed text.
- **Never do I/O, HTTP, sorting, or large allocations in `render/2`.** It runs up to ~60fps; derive once in the transition callback and store the result in state.
- **Never make a blocking call in `handle_event/2`/`update/2`.** Use `ExRatatui.Command.async/2` (reducer) or `Task.Supervisor.async_nolink/2` (callback). A blocking call freezes the whole UI.
- **Never hand-roll a render throttle to survive message bursts — the runtime already merges them.** A transition that finds more messages queued defers its render, so a burst renders once with the final state; an idle message renders immediately. Don't count renders per message in tests either: drive input with `Runtime.inject_event/2`, which renders synchronously.
- **A `[:ex_ratatui, :runtime, :mailbox]` event or "messages queued" warning means the callbacks can't keep up — fix the source, don't raise the threshold.** Make the slow callback cheap, sample or batch the noisy subscription, and return `render?: false` where nothing visible changed. `:mailbox_warn_threshold` (default `10_000`, `false` disables) is a start option; over `:ssh`/`:distributed` it goes inside `:app_opts`.
- **Always include a catch-all `handle_event(_event, state)` / `update(_msg, state)` returning `{:noreply, state}`.** Unmatched events otherwise crash the app.
- **Never `IO.inspect`/`IO.puts`/`dbg` to stdout while in raw mode** — it garbles the display. Log to a file via `Logger`, or use `Runtime.snapshot/1`.
- **Reducer `update/2` receives `{:event, event}` and `{:info, msg}`, never bare structs.** All input is routed through one `update/2`.
- **`commands:` and `render?:` runtime opts are designed for the reducer runtime.** They execute under the callback runtime too (command results land in `handle_info/2`), but idiomatic callback apps use `Process.send_after/3` or a supervised Task.
- **Never serve a TUI to remote users over the `:local` transport — use `transport: :ssh` or `:distributed`.** `:local` grabs the host tty and fails with `terminal_init_failed` where there is no TTY.
- **From an IEx session over SSH (`nerves_ssh`) or `iex --remsh`, open a TUI with `ExRatatui.IODevice.run(MyApp.TUI, opts)`, not `start_link/1`.** `:local` would draw on the node's own console instead of the shell; `ExRatatui.IODevice.io_device?/0` tells the two apart for an IEx helper.
- **Never background or pipe stdin into a `mix run`/`iex` TUI example.** With no TTY it exits immediately or raises `terminal_init_failed`; run it in a real terminal emulator.
- **In tests, always pass `test_mode: {w, h}` and `name: nil`, and drive input with `ExRatatui.Runtime.inject_event/2`.** `test_mode` disables live TTY polling so `async: true` tests do not race; named apps collide across parallel tests.

## Going deeper

Full walkthroughs and the complete gotcha set live in the guides on hexdocs, grouped as in the docs sidebar:

- **Introduction:** [Getting started](https://hexdocs.pm/ex_ratatui/getting_started.html), [Installation](https://hexdocs.pm/ex_ratatui/installation.html), [Examples](https://hexdocs.pm/ex_ratatui/examples.html)
- **Building UIs:** [Building UIs](https://hexdocs.pm/ex_ratatui/building_uis.html), [Custom widgets](https://hexdocs.pm/ex_ratatui/custom_widgets.html), [Images](https://hexdocs.pm/ex_ratatui/images.html), [3D rendering](https://hexdocs.pm/ex_ratatui/3d.html), [Paste and clipboard](https://hexdocs.pm/ex_ratatui/paste_and_clipboard.html)
- **Runtimes:** [Callback runtime](https://hexdocs.pm/ex_ratatui/callback_runtime.html), [Reducer runtime](https://hexdocs.pm/ex_ratatui/reducer_runtime.html), [State machine patterns](https://hexdocs.pm/ex_ratatui/state_machines.html), [Erlang and Gleam](https://hexdocs.pm/ex_ratatui/erlang_and_gleam.html)
- **Transports:** [Transports](https://hexdocs.pm/ex_ratatui/transports.html), [SSH](https://hexdocs.pm/ex_ratatui/ssh_transport.html), [Remote IEx shell](https://hexdocs.pm/ex_ratatui/iex_shell_transport.html), [Erlang distribution](https://hexdocs.pm/ex_ratatui/distributed_transport.html), [Custom transports](https://hexdocs.pm/ex_ratatui/custom_transports.html), [CellSession](https://hexdocs.pm/ex_ratatui/cell_session.html), [Framebuffers](https://hexdocs.pm/ex_ratatui/framebuffer_surfaces.html)
- **Going deeper:** [Architecture](https://hexdocs.pm/ex_ratatui/architecture.html), [Testing](https://hexdocs.pm/ex_ratatui/testing.html), [Debugging](https://hexdocs.pm/ex_ratatui/debugging.html), [Performance](https://hexdocs.pm/ex_ratatui/performance.html), [Telemetry](https://hexdocs.pm/ex_ratatui/telemetry.html)
- **Packaging:** [Burrito](https://hexdocs.pm/ex_ratatui/packaging_with_burrito.html)
- **Cheatsheets:** [Widgets](https://hexdocs.pm/ex_ratatui/widgets.html)