47 lines
2.2 KiB
Markdown
47 lines
2.2 KiB
Markdown
# The TUI — working map
|
|
|
|
Read this before touching `internal/tui/`. The generic side — how a Go CLI/TUI project is built,
|
|
tested and reviewed — belongs to the pipeline that started you.
|
|
|
|
## Build and test
|
|
|
|
```sh
|
|
go build ./...
|
|
go test ./internal/tui # fast (~2-4 s); the whole tree is ~1 min
|
|
go vet ./...
|
|
```
|
|
|
|
No device, no capture, no network: a TUI change is verified by unit tests plus a rendered frame.
|
|
|
|
## How the TUI is put together
|
|
|
|
- `model.go` — the `Model`, the key map (`keys`), and `Update`/`View` dispatch. Key bindings are
|
|
declared in one place; a new binding goes there, not inline.
|
|
- `dashboard.go`, `pipeline.go`, `runs.go`, `run_detail.go` — the screens. A run's detail is built
|
|
from sections, and a section can open as its own pane in the sliding stack.
|
|
- `context_footer.go` — the footer for the current mode. A modal's footer replaces the page's; never
|
|
inherit shortcuts that the modal does not honour.
|
|
- `theme.go` / `style.go` — colours and text styles. Status colour comes from one vocabulary so a
|
|
state looks the same in every screen.
|
|
- `linetext.go`, `graph.go` — line building and the stage graph rendering.
|
|
- Human decision stages are answered in the TUI: `↑/↓ choose · Tab feedback · Enter decide · Esc
|
|
cancel`.
|
|
|
|
## Reviewing a TUI change without a terminal
|
|
|
|
The pinned frames in `internal/harness/tmp/ui-review/render/` (`empty-catalog-*`, `filter-no-match-*`,
|
|
`narrow-long-model-*`, `plain-nocolor-*`, `wide-focused-*`, in dark and light) are the reference
|
|
renders. Compare against them when a change alters layout, spacing, colour or the footer, and add a
|
|
frame when you introduce a new state worth pinning. A change that alters a pinned frame and does not
|
|
say why is a review finding.
|
|
|
|
## Conventions and traps
|
|
|
|
- No polling: state arrives from the server; do not add a ticker to look busy.
|
|
- The footer and the pane stack are shared surfaces — a change there affects every screen, so say what
|
|
you checked.
|
|
- Terminal width matters: verify at a narrow width as well as a wide one, and never assume colour
|
|
support (`plain-nocolor-*` exists for a reason).
|
|
- Do not restart the deployed server, the lanes or ntfy to test a TUI change: run the binary against a
|
|
scratch server or use the fixtures.
|