@@ -0,0 +1,308 @@
1+---
2+name: cel-tui
3+description: Build terminal user interfaces with cel-tui, a TypeScript TUI framework. Use when the user wants to create a TUI app, build a terminal UI, render text in the terminal, create a CLI with interactive elements, build a chat interface, text editor, or any interactive terminal application. Triggers include "build a TUI", "terminal UI", "interactive CLI", "text-based interface", "render to terminal", or any task requiring a programmatic terminal user interface.
4+license: MIT
5+compatibility: Requires Bun runtime and a terminal with SGR mouse mode support.
6+metadata:
7+ author: sacenox
8+ version: "0.0.1"
9+---
10+
11+# Building TUIs with cel-tui
12+
13+cel-tui is a TypeScript TUI framework with a declarative functional API, flexbox layout, and cell-buffer rendering. It has 4 primitives and external state management.
14+
15+## Install
16+
17+```bash
18+bun add @cel-tui/core
19+# Optional pre-made components
20+bun add @cel-tui/components
21+```
22+
23+## Core Pattern
24+
25+Every cel-tui app follows this pattern:
26+
27+1. Import primitives and `ProcessTerminal`
28+2. Initialize with `cel.init(new ProcessTerminal())`
29+3. Define state as plain variables (or any state approach)
30+4. Set render function with `cel.viewport(() => tree)`
31+5. Call `cel.render()` after state changes
32+
33+```ts
34+import {
35+ cel,
36+ VStack,
37+ HStack,
38+ Text,
39+ TextInput,
40+ ProcessTerminal,
41+} from "@cel-tui/core";
42+
43+let value = "";
44+
45+cel.init(new ProcessTerminal());
46+cel.viewport(() =>
47+ VStack(
48+ {
49+ height: "100%",
50+ onKeyPress: (key) => {
51+ if (key === "ctrl+q") {
52+ cel.stop();
53+ process.exit();
54+ }
55+ },
56+ },
57+ [
58+ Text("My App", { bold: true, fgColor: "cyan" }),
59+ Text("─", { repeat: "fill" }),
60+ TextInput({
61+ flex: 1,
62+ value,
63+ focused: true,
64+ onChange: (v) => {
65+ value = v;
66+ cel.render();
67+ },
68+ }),
69+ ],
70+ ),
71+);
72+```
73+
74+## 4 Primitives
75+
76+| Primitive | Type | Description |
77+| ------------------------- | ----------------------- | ---------------------------------------------- |
78+| `VStack(props, children)` | Container | Vertical stack — children top to bottom |
79+| `HStack(props, children)` | Container | Horizontal stack — children left to right |
80+| `Text(content, props?)` | Leaf | Styled text, no children, fills parent width |
81+| `TextInput(props)` | Container (no children) | Multi-line editable text, accepts sizing props |
82+
83+## Sizing
84+
85+Containers accept 4 sizing strategies:
86+
87+```ts
88+VStack({}, []); // Intrinsic — size to fit content (default)
89+VStack({ width: 30, height: 10 }, []); // Fixed — exact cell count
90+VStack({ flex: 1 }, []); // Flex — proportional to siblings
91+VStack({ width: "50%", height: "100%" }, []); // Percentage — relative to parent
92+```
93+
94+Constraints: `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
95+
96+Text has no sizing props — parent controls the box, height is intrinsic (content + wrapping).
97+
98+TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.).
99+
100+## Container Props
101+
102+```ts
103+{
104+ width, height, // SizeValue (number | "50%")
105+ flex, // number
106+ minWidth, maxWidth, // number
107+ minHeight, maxHeight, // number
108+ padding, // { x?: number, y?: number }
109+ gap, // number (cells between children)
110+ justifyContent, // "start" | "end" | "center" | "space-between"
111+ alignItems, // "start" | "end" | "center" | "stretch"
112+ overflow, // "hidden" (default) | "scroll"
113+ scrollbar, // boolean
114+ scrollOffset, // number (controlled scroll)
115+ onScroll, // (offset: number) => void
116+ onClick, // () => void
117+ focusable, // boolean (default true if onClick set)
118+ focused, // boolean (controlled)
119+ onFocus, // () => void
120+ onBlur, // () => void
121+ onKeyPress, // (key: string) => void
122+}
123+```
124+
125+## Text Props
126+
127+```ts
128+Text("content", {
129+ repeat: "fill" | number, // Repeat to fill width or N times
130+ wrap: "none" | "word", // Default "none", hard-clips at edge
131+ bold,
132+ italic,
133+ underline, // boolean
134+ fgColor,
135+ bgColor, // ANSI 16 Color
136+});
137+```
138+
139+Colors: `"black"`, `"red"`, `"green"`, `"yellow"`, `"blue"`, `"magenta"`, `"cyan"`, `"white"`, and bright variants (`"brightRed"`, etc.).
140+
141+## TextInput Props
142+
143+```ts
144+TextInput({
145+ value, // string (controlled)
146+ onChange, // (value: string) => void
147+ onSubmit, // () => void
148+ submitKey, // string (default "enter")
149+ placeholder, // Text() node shown when empty
150+ focused, // boolean (controlled)
151+ onFocus,
152+ onBlur, // () => void
153+ // + all container sizing props
154+ // + all styling props (bold, fgColor, etc.)
155+});
156+```
157+
158+## Common Patterns
159+
160+### Spacer (push items apart)
161+
162+```ts
163+HStack({ height: 1 }, [
164+ Text("left"),
165+ VStack({ flex: 1 }, []), // spacer
166+ Text("right"),
167+]);
168+```
169+
170+### Horizontal divider
171+
172+```ts
173+Text("─", { repeat: "fill", fgColor: "brightBlack" });
174+```
175+
176+### Button
177+
178+```ts
179+HStack({ onClick: handleClick }, [
180+ Text("[Send]", { bold: true, fgColor: "cyan" }),
181+]);
182+```
183+
184+### Growing text input (caps at maxHeight, then scrolls)
185+
186+```ts
187+TextInput({
188+ flex: 1,
189+ maxHeight: 10,
190+ value,
191+ onChange: (v) => {
192+ value = v;
193+ cel.render();
194+ },
195+ submitKey: "ctrl+enter",
196+});
197+```
198+
199+### Scrollable list
200+
201+```ts
202+// Uncontrolled (framework manages scroll)
203+VStack({ overflow: "scroll", scrollbar: true }, [...items]);
204+
205+// Controlled (app manages scroll)
206+VStack(
207+ {
208+ overflow: "scroll",
209+ scrollOffset: offset,
210+ onScroll: (o) => {
211+ offset = o;
212+ cel.render();
213+ },
214+ },
215+ [...items],
216+);
217+```
218+
219+### Layers (modals)
220+
221+Return an array from the render function. Layers composite bottom-to-top:
222+
223+```ts
224+cel.viewport(() => [
225+ VStack({ height: "100%" }, [...mainUI]),
226+ ...(showModal
227+ ? [
228+ VStack(
229+ {
230+ height: "100%",
231+ justifyContent: "center",
232+ alignItems: "center",
233+ onClick: () => {
234+ showModal = false;
235+ cel.render();
236+ },
237+ },
238+ [VStack({ width: 40, height: 10 }, [...modalContent])],
239+ ),
240+ ]
241+ : []),
242+]);
243+```
244+
245+### Global key bindings
246+
247+Put `onKeyPress` on the root container — it catches all keys not consumed by focused elements:
248+
249+```ts
250+VStack({
251+ height: "100%",
252+ onKeyPress: (key) => {
253+ if (key === "ctrl+q") { cel.stop(); process.exit(); }
254+ if (key === "ctrl+s") saveFile();
255+ },
256+}, [...])
257+```
258+
259+### Focus (controlled)
260+
261+```ts
262+TextInput({
263+ value: text,
264+ onChange: handleChange,
265+ focused: isFocused,
266+ onFocus: () => {
267+ isFocused = true;
268+ cel.render();
269+ },
270+ onBlur: () => {
271+ isFocused = false;
272+ cel.render();
273+ },
274+});
275+```
276+
277+## Key Format
278+
279+All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`, `"enter"`, `"alt+up"`, `"f1"`. Framework normalizes modifier order.
280+
281+## Key Rules
282+
283+- **State is external** — framework has no state. Call `cel.render()` after changes.
284+- **Text is a leaf** — no sizing props, no children. Parent controls the box.
285+- **TextInput is a container** — accepts sizing props but no children.
286+- **No style inheritance** — every node sets its own styles explicitly.
287+- **Escape unfocuses** the current element.
288+- **Tab/Shift+Tab** traverses focusable elements in document order (wraps around).
289+- **Enter** activates a focused clickable container (fires onClick).
290+- **TextInput consumes editing keys** when focused (printable chars, arrows, backspace, delete). Modifier combos (ctrl+s) bubble up through ancestors via onKeyPress.
291+- **Mouse click** on a focusable element fires onFocus (and onBlur on previous).
292+- **Innermost wins** — for click, scroll, and key handlers.
293+- **Differential rendering** — only changed cells are emitted after the first render.
294+- **Crash cleanup** — terminal state is restored on SIGINT, SIGTERM, uncaughtException.
295+
296+## Pre-made Components
297+
298+```ts
299+import { Spacer, Divider, Button } from "@cel-tui/components";
300+
301+Spacer(); // VStack({ flex: 1 }, [])
302+Divider(); // Text("─", { repeat: "fill" })
303+Divider({ char: "═", fgColor: "brightBlack" });
304+Button("[OK]", { onClick: handleOk });
305+Button("✕", { onClick: handleClose, focusable: false });
306+```
307+
308+For the full specification, see the [cel-tui spec](https://raw.githubusercontent.com/sacenox/cel-tui/main/spec.md).