70160
Ce
cel-tui / files
cel-tui / README.md
7.0 KB
1# cel-tui 2 3A TypeScript TUI framework built around a declarative functional API, ultra-fast rendering, and Kitty-first keyboard input that also works well in tmux. 4 5<p align="center"> 6 <picture> 7 <img src="assets/demo.gif" alt="cel-tui demo" width="539" style="border-radius: 8px; box-shadow: 0 4px 16px rgba(0,0,0,0.3);" /> 8 </picture> 9</p> 10 11## Why "cel"? 12 13A **cel** is the smallest unit of a terminal display — a single character cell. Start from the smallest meaningful unit and build up, with nothing wasted. 14 15## Quick Example 16 17```ts 18import { cel, VStack, Text, TextInput, ProcessTerminal } from "@cel-tui/core"; 19 20let input = ""; 21 22cel.init(new ProcessTerminal()); 23cel.viewport(() => 24 VStack( 25 { 26 height: "100%", 27 onKeyPress: (key) => { 28 if (key === "ctrl+q") { 29 cel.stop(); 30 process.exit(); 31 } 32 }, 33 }, 34 [ 35 Text("Hello, cel-tui!", { bold: true, fgColor: "color06" }), 36 Text("─", { repeat: "fill", fgColor: "color08" }), 37 TextInput({ 38 flex: 1, 39 value: input, 40 onChange: (v) => { 41 input = v; 42 cel.render(); 43 }, 44 }), 45 ], 46 ), 47); 48``` 49 50## Primitives 51 52| Primitive | Description | 53| ------------------------- | ---------------------------------- | 54| `VStack(props, children)` | Vertical stack — top to bottom | 55| `HStack(props, children)` | Horizontal stack — left to right | 56| `Text(content, props?)` | Styled text leaf | 57| `TextInput(props)` | Multi-line editable text container | 58 59## Key Concepts 60 61- **State is external** — the framework renders what you give it. Use any state approach. 62- **`cel.viewport(() => tree)`** sets the render function, **`cel.render()`** triggers re-renders. 63- **Explicit invalidation** — `cel.redraw()` repairs externally corrupted screens; `cel.setTheme(theme)` replaces the runtime palette and redraws automatically. 64- **Flexbox layout** — fixed, flex, percentage, and intrinsic sizing with gap, padding, alignment. 65- **Layers** — return an array for multi-layer compositing (modals, overlays). 66- **Uncontrolled by default** — focus and scroll just work. Opt into controlled mode when needed. 67- **Stable state identity** — `stateKey` keeps focus, scroll, and TextInput state attached through reordering; `autoFocus` seeds the active layer once. 68- **Controlled caret when needed** — TextInput `cursor` / `onCursorChange` enables grapheme-safe completion and range-replacement workflows. 69- **Cursor shape control** — TextInput `cursorStyle` keeps block, bar, or underline painted/native cursors aligned. 70- **Adaptive wheel scrolling** — scrollables and TextInput use an adaptive mouse-wheel step by default; override it with `scrollStep` when needed. 71- **Content measurement helper** — `measureContentHeight(node, { width })` lets apps preserve scroll anchors when prepending intrinsically sized content. 72- **Bounded long lists** — callable `VirtualList()` instances measure variable-height keyed rows, window by cell offset with overscan, preserve scroll anchors, and support controlled or sticky-bottom scrolling. 73- **Terminal title helper** — `cel.setTitle("My App")` updates the window/tab title when the host honors OSC titles. 74- **Style inheritance** — containers propagate styles to descendants. `bgColor` fills the rect. 75- **Custom scrollbars** — `scrollbarStyle` controls thumb/track characters and terminal styles. 76- **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to different ANSI indices or 24-bit true color. 77- **Cell buffer rendering** — styled cells, differential updates, synchronized output. 78- **Opt-in managed animation** — `Spinner()` and `createTicker()` cap render cadence and expose explicit start/stop/dispose lifecycles; the default renderer remains timer-free. 79- **Kitty-first keyboard input** — baseline disambiguation is enabled by default; optional `kittyKeyboard` flags expose repeat/release phases, alternate-layout keys, all-key events, and associated text. Mixed tmux/legacy input remains supported. 80- **TextInput editing shortcuts** — focused inputs support familiar readline-style editing (`ctrl+a/e`, `alt+b/f`, `ctrl+left/right`, `ctrl+w`, `alt+d`), and `up` / `down` follow visual wrapped lines. 81- **TextInput-backed Select** — filterable lists share exact text, grapheme-safe cursor editing, and bracketed paste behavior with TextInput, with optional controlled query/highlight models for async overlays. 82 83## Terminal Compatibility 84 85- **First-class:** Kitty-compatible terminals such as Kitty, WezTerm, Ghostty, foot, Alacritty, and Windows Terminal 1.25+ 86- **First-class:** `tmux` with `set -s extended-keys on` 87- **Best effort:** legacy terminals or multiplexers that collapse some modifier distinctions 88 89Some historical legacy collisions remain impossible to recover once a host has already collapsed them — for example `ctrl+i` vs `tab`, `ctrl+m` vs `enter`, and `ctrl+[` vs `escape`. 90 91## Packages 92 93| Package | Description | 94| --------------------- | ---------------------------------------------------------------------------------------------------------------- | 95| `@cel-tui/types` | Shared type definitions | 96| `@cel-tui/core` | Framework engine and primitives | 97| `@cel-tui/clew` | Stream-first syntax tokenization library | 98| `@cel-tui/components` | Pre-made components (Button, Spacer, Divider, VDivider, Select, VirtualList, Spinner, Markdown, SyntaxHighlight) | 99 100## Documentation 101 102- **[API Reference](https://sacenox.github.io/cel-tui/)** — full TypeDoc-generated docs on GitHub Pages 103- **[0.9 Migration Guide](MIGRATION.md)** — changes required when upgrading from 0.8.x 104- **[Specification](spec.md)** — complete design spec covering layout, rendering, input, and focus 105- **[Agent Skill](docs/skill/cel-tui/SKILL.md)** — structured guide for AI coding agents to build apps with cel-tui 106 107## Performance 108 109cel-tui ships a benchmark suite covering every pipeline stage (layout, paint, cell buffer, ANSI emission, hit testing, key parsing). See [benchmarks/RESULTS.md](benchmarks/RESULTS.md) for historical measurements and the benchmark methodology. For before/after work, compare repeated runs on the same machine, Bun version, and power profile. 110 111```bash 112bun run bench # detailed exploratory suite 113bun run bench:regression # fixed-work JSON for before/after comparisons 114``` 115 116## Development 117 118```bash 119bun install # install dependencies 120bun test # run tests 121bun run bench # run benchmarks 122bun run check # biome lint 123bun run format # prettier check 124bun run typecheck # tsc --noEmit 125bun run docs # generate API docs 126``` 127 128## License 129 130MIT