knoopx pi-tui — Component-Based Terminal UI
Component-based TUI framework with differential rendering and synchronized output for flicker-free terminals.
Core Setup
import { TUI, ProcessTerminal } from "@mariozechner/pi-tui";
const tui = new TUI(new ProcessTerminal());
tui.addChild(component); // any Component
tui.start(); // starts rendering loop
tui.stop(); // stops and drains input
Built-in Components (13 total)
| Component | Purpose | Key Methods |
|---|---|---|
Container |
Holds child components | addChild(), removeChild(), clear() |
Text / TruncatedText |
Plain text display | setText() |
Input |
Single-line text input | getValue(), setValue() |
Editor |
Multi-line text editor | setText(), getText(), getCursor() |
Markdown |
Render markdown text | setText() |
SelectList |
Selectable list with filtering | setFilter(), onSelect, onCancel |
SettingsList |
Key-value settings editor | updateValue() |
Box |
Container with background | setBgFn() |
Spacer |
Vertical spacing | setLines() |
Loader / CancellableLoader |
Loading spinner | start(), stop(), setMessage() |
Image |
Render images (base64) | getImageId() |
Each component is its own file — import directly from the package, no barrel re-exports.
Rendering Rules
Every render(width) line must not exceed width visible columns. Use truncateToWidth(), wrapTextWithAnsi(), or visibleWidth() to enforce this. Each rendered line gets a full SGR reset appended — styles do not carry across lines.
Focusable Components
Input, Editor implement Focusable. Custom components with cursors must also implement Focusable and emit CURSOR_MARKER in render output when focused. When a container wraps an Input/Editor, propagate focus to the child for correct IME candidate window positioning.
Keybindings & Key Detection
Use matchesKey() for raw detection: matchesKey(data, Key.enter), Key.ctrl("c"), Key.shift("tab"). For user-customizable bindings, use the global KeybindingsManager via getKeybindings() — components like Editor, Input, SelectList, and SettingsList route input through named bindings.
Overlays
tui.showOverlay(component, options); // Position: absolute > percentage > anchor
handle.hide(); // Permanent
handle.setHidden(); // Temporary
Overlays support nonCapturing mode (no keyboard focus steal) and stack with z-ordering by focusOrder.
Custom Components
Each custom component lives in its own file implementing Component. For caching, store cachedLines and cachedWidth, reset in invalidate().
See references/ for complete API reference, custom component patterns, autocomplete providers, terminal image APIs, best practices, and anti-patterns.