xonecas.io
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