SuperLightTUI

# SuperLightTUI

> Immediate-mode TUI library for Rust. One closure runs every frame; the library handles layout, diffing, and rendering. Designed for fast iteration and AI-assisted TUI code generation.

## Reading order for coding agents

- [Complete reference (single-file)](reference/complete-reference.md): condensed full API. Start here for most tasks.
- [Quick start](guide/01-quick-start.md): install, first app, closure mental model, mouse opt-in, shortcut ordering
- [AI guide](reference/ai-guide.md): common questions agents get wrong, implementation rules
- [Widgets](reference/widgets.md): categorized API catalog (50+ widgets, state types, runtime methods)
- [Patterns](guide/03-patterns.md): composition patterns, state ownership, screens, forms
- [Examples guide](reference/examples.md): the 29 runnable `cargo run --example` targets (8 tours + entry, feature, tool, and report binaries) and which source files each tour uses
- [Architecture](internals/architecture.md): module map, frame lifecycle, layout pipeline
- [Design principles](internals/design-principles.md): API philosophy, immediate-mode rationale

## Core concepts

- The mouse is on by default in fullscreen runs: `MouseMode::Drag` locally (clicks, wheel, drags), `MouseMode::Click` over SSH/mosh; inline/static runs default to `MouseMode::Off`. Hover, tooltips and `group_hover_*` need `slt::run_with(slt::RunConfig::default().mouse_mode(slt::MouseMode::Hover), |ui| { ... })`. Focused buttons also activate with Enter / Space.
- Check global shortcuts (`ui.key('q')`) after rendering widgets: `key*` sees events not consumed so far, so a check placed before a focused `text_input` fires while the user types into it.

- [Run loop](internals/architecture.md#frame-lifecycle): 8-stage per-frame pipeline
- [Immediate mode](internals/design-principles.md): no App trait, no Model/Update/View
- [Previous-frame feedback](guide/02-state.md#the-previous-frame-rule): why Response.rect is valid from frame 2
- [State ownership](guide/03-patterns.md): app state vs hooks vs widget state

## API surface

- [Crate root re-exports](../src/lib.rs): authoritative public API
- [Context runtime methods](../src/context/runtime.rs): use_state, use_memo, focus, interaction, error_boundary

### Component / state APIs

- `ui.provide(value, |ui| { ... })` — context injection, scoped to the closure body
- `ui.use_context::<T>()` — read provided context (panics if no `T` is in scope)
- `ui.try_use_context::<T>()` — read provided context, returns `Option<&T>` (safe form)
- `ui.use_state_keyed(id, init)` / `ui.use_state_keyed_default::<T>(id)` — id-keyed local state, safe inside conditionals and loops (`use_state_named` is a deprecated alias sharing the same slot)

- `.with_if(cond, modifier)` / `.with(modifier)` — fluent conditional styling on text and `ContainerBuilder`

### Current (v0.26) highlights

- Mouse on by default: `RunConfig::default()` resolves to `MouseMode::Drag` locally and `MouseMode::Click` over SSH/mosh; hover, tooltips and `group_hover_*` need `RunConfig::default().mouse_mode(MouseMode::Hover)`. Inline and static runs keep the mouse off
- Option builders: `ui.button(l).variant(v).colors(&c)`, `ui.badge(l).color(c)`, `ui.slider(l, &mut v, range).step(s)`, ... deref to `Response`; `.show()` returns an owned `Response`. `ui.text(..)` returns a scoped `Text<'_>` builder; `use slt::prelude::*;`
- Focus follows the widget (`register_focusable_keyed`), keys a focused text field edits with never reach `ui.key(..)`, `ui.shortcut(code, mods)` matches modifiers exactly, `ui.raw_key(c)` ignores text focus, and `ui.modal(f)` traps focus
- Text selection, Ctrl+C / Ctrl+X copy and undo in `text_input` / `textarea`; `ui.disabled(cond, |ui| ..)`; `hover_bg` / `focus_bg` / `focus_within_bg` / `active_bg` on containers; `ui.popover`, `ui.context_menu`, `ui.menu_bar`
- New widgets and modes: `ui.code_editor(&mut CodeEditorState)`, `ui.diff(&mut DiffState)`, the opt-in `ratatui` feature (`ContainerBuilder::ratatui_widget`), accessible output with `SLT_ACCESSIBLE=1` / `RunConfig::accessible(true)`
- Multi-step tests: `tb.step(events, &mut f).press(KeyCode::Tab, &mut f).type_text("x", &mut f)`; `run_with_events` keeps focus
- Upgrading from 0.25: [Migration](reference/migration.md). `slt-wasm` is deferred in 0.26 (latest published: 0.25.0)

### v0.25 additions

- Scroll containers follow keyboard focus (nested axes, modal forms, resize); opt out per container with the public `ScrollState::follow_focus` field (default `true`)
- `ui.form_field_response(&mut field)` returns `FormFieldResponse`; `ui.focused_layout_rect()` / `ui.measured_layout_rect(name)` expose full [previous-frame](guide/02-state.md#the-previous-frame-rule) geometry
- Input typed after a Tab in the same batch is queued for the next frame; custom loops can check `AppState::has_pending_input()` / `TestBackend::has_pending_input()`
- Quick transitions: `ui.animate_bool(id, on)` / `ui.animate_value(id, target, ticks)` — see [Animation](guide/07-animation.md)

### Longer-standing helpers

- `NO_COLOR` env var support (auto-disables color output when set)
- `scroll_col` — vertical scroll container helper
- `container().draw_with(data, |buf, rect, data| { ... })` — raw draw with owned data
- `Buffer::try_get(x, y) -> Option<&Cell>` — fallible buffer cell accessor for `draw(|buf, rect| ...)` raw-draw closures

### Builder widgets

- `ui.breadcrumb(segments).separator(...).show()` — returns `BreadcrumbResponse` with the standard interaction signals and `clicked_segment`
- `ui.button(label).variant(ButtonVariant::Danger).colors(&c)`, `ui.badge(l).color(c)`, `ui.stat(l, v).color(c)`, `ui.help(b).key_color(c)`, `ui.separator().color(c)`, `ui.progress(r).color(c)`, `ui.slider(l, &mut v, range).step(s)`, `ui.line_chart(d, w, h).color(c)` — option builders that deref to `Response`; `.show()` returns an owned `Response` when you store it across other `ui.` calls. Bind `let c = ui.theme().x;` before the call: builder arguments cannot borrow `ui`
- `use slt::prelude::*;` — one-line import of the run entry points, `Context`, builders, style types, `State` / `StateHandle` and the common widget states

- `mx(n)` / `my(n)` — horizontal / vertical margin shorthands

## Specialized topics

- [Theming](guide/06-theming.md): 10 preset themes, ThemeColor semantic tokens, WidgetColors overrides, Tailwind palette
- [Animation](guide/07-animation.md): animate_bool / animate_value quick transitions; Tween, Spring, Keyframes, Sequence, Stagger
- [Backends](guide/09-runtime-modes.md): custom backends, Backend trait, AppState, frame()
- [Testing](guide/08-testing.md): TestBackend, EventBuilder
- [Debugging](reference/debugging.md): F12 overlay, clipping issues, focus surprises
- [Features](reference/features.md): feature flags (crossterm, async, serde, image, qrcode, syntax)

## Examples

Runnable targets (`cargo run --example <name>`; `autoexamples = false`, so other file names in `examples/` are not runnable):

- `hello` ([source](../examples/hello.rs)): smallest app
- `counter` ([source](../examples/counter.rs)): state plus keyboard
- `demo` ([source](../examples/demo.rs)): broad widget tour
- `cookbook_tour` ([source](../examples/cookbook_tour.rs)): the COOKBOOK recipes as tabs
- `interaction_tour` ([source](../examples/interaction_tour.rs)): click / double-click / scroll `Response` signals, `KeyMap`, focus traversal
- `showcase_tour` ([source](../examples/showcase_tour.rs)): dashboard, infoviz, website, spreadsheet, trading screens
- `text_tour` ([source](../examples/text_tour.rs)): CJK, IME, CLI-style text
- `system_tour --features async` ([source](../examples/system_tour.rs)): error boundary, overlay anchor, async / inline modes
- `widgets_tour` ([source](../examples/widgets_tour.rs)): hooks, theming, modal focus traps, layout helpers as tabs
- `inline` ([source](../examples/inline.rs)): `run_inline` below the shell prompt
- `async_demo --features async` ([source](../examples/async_demo.rs)): `run_async` with a tokio producer

Source modules shown inside tours (read them, run the tour):

- [examples/demo_dashboard.rs](../examples/demo_dashboard.rs): dashboard composition — `showcase_tour`
- [examples/demo_infoviz.rs](../examples/demo_infoviz.rs): charts and visualizations — `showcase_tour`
- [examples/demo_website.rs](../examples/demo_website.rs): canonical `provide` / `use_context` composition — `showcase_tour`
- [examples/demo_cli.rs](../examples/demo_cli.rs): CLI-style layout — `text_tour`
- [examples/demo_cjk.rs](../examples/demo_cjk.rs): CJK / wide-character rendering, title clamp, mouse hover — `text_tour`