@@ -0,0 +1,346 @@
1+# cel-tui API Reference
2+
3+## Framework lifecycle
4+
5+```ts
6+cel.init(new ProcessTerminal(), { theme?: Theme });
7+cel.viewport(() => tree); // or () => [layer1, layer2]
8+cel.render();
9+cel.setTitle("My App");
10+cel.stop();
11+```
12+
13+- `cel.viewport` sets the render function and triggers the first render.
14+- `cel.render()` requests a batched re-render after external state changes.
15+- `cel.setTitle(title)` writes a best-effort terminal title request. Control characters are stripped from `title`, and `cel.stop()` does not restore the previous title automatically.
16+- `cel.stop()` restores terminal state (raw mode, keyboard protocol, mouse tracking, alternate screen).
17+
18+## Container Props
19+
20+All props accepted by `VStack` and `HStack`:
21+
22+```ts
23+{
24+ // Sizing
25+ width, height, // SizeValue (number | "50%")
26+ flex, // number
27+ minWidth, maxWidth, // number
28+ minHeight, maxHeight, // number
29+ padding, // { x?: number, y?: number }
30+ gap, // number (cells between children)
31+ justifyContent, // "start" | "end" | "center" | "space-between"
32+ alignItems, // "start" | "end" | "center" | "stretch"
33+ overflow, // "hidden" (default) | "scroll"
34+ scrollbar, // boolean
35+ scrollStep, // number (mouse wheel step in cells; default adaptive)
36+ scrollOffset, // number (controlled scroll)
37+ onScroll, // (offset: number, maxOffset: number) => void
38+ flexWrap, // "nowrap" (default) | "wrap" (HStack only)
39+
40+ // Styling (inherited by descendants)
41+ bold, italic, underline,// boolean
42+ fgColor, bgColor, // Color ("color00"–"color15")
43+ focusStyle, // StyleProps — overrides when focused
44+
45+ // Interaction
46+ onClick, // () => void
47+ focusable, // boolean (default true if onClick set, or set true explicitly)
48+ focused, // boolean (controlled — omit for uncontrolled)
49+ onFocus, // () => void
50+ onBlur, // () => void
51+ onKeyPress, // (key: string) => boolean | void — normalized semantic key string; return false to keep bubbling
52+}
53+```
54+
55+## Measurement Helpers
56+
57+```ts
58+measureContentHeight(node, { width }); // number
59+```
60+
61+- Measures a node tree's **intrinsic content height** at the provided wrapping width.
62+- This is a content-measurement helper, not a viewport/clipping helper.
63+- The provided `width` is authoritative — use the actual width the subtree wraps at.
64+- Main use case: prepend-style scrollback, where older content is inserted above the current viewport and the app needs to preserve the viewport anchor.
65+
66+```ts
67+const addedHeight = measureContentHeight(
68+ VStack({}, olderMessages.map(renderMessage)),
69+ { width: historyContentWidth },
70+);
71+
72+scrollOffset += addedHeight;
73+```
74+
75+Measure the content subtree you are adding. If a wrapper's visible height is controlled by `height`, `flex`, or percentage sizing, measure the content inside that wrapper instead. For padded content, pass the outer width when measuring the padded container itself, or the inner content width when measuring its children directly.
76+
77+## Scroll
78+
79+Scroll supports **uncontrolled** (default) and **controlled** modes, mirroring the focus model:
80+
81+```ts
82+// Uncontrolled — framework manages scroll position. Mouse wheel just works.
83+VStack({ overflow: "scroll", scrollbar: true }, [...items]);
84+
85+// Controlled — app owns scroll state.
86+VStack(
87+ {
88+ overflow: "scroll",
89+ scrollbar: true,
90+ scrollOffset: offset,
91+ onScroll: (newOffset, maxOffset) => {
92+ offset = newOffset;
93+ cel.render();
94+ },
95+ },
96+ [...items],
97+);
98+```
99+
100+- Scroll direction follows the container’s main axis: VStack → vertical, HStack → horizontal.
101+- Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
102+- Mouse wheel scrolling uses an adaptive default step based on the scroll target's visible main-axis viewport size: `floor(viewportMainAxis / 3)`, clamped to `3..8`.
103+- Set `scrollStep` to override the mouse wheel step for a specific scrollable or `TextInput`.
104+- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset and the maximum offset (content size minus viewport size). Pass `Infinity` as `scrollOffset` to mean "scroll to end" (clamped during rendering). `scrollStep` affects mouse wheel input only.
105+
106+## Text Props
107+
108+```ts
109+Text("content", {
110+ repeat: "fill" | number, // Repeat to fill width or N times
111+ wrap: "none" | "word", // Default "none", hard-clips at edge
112+ bold,
113+ italic,
114+ underline, // boolean
115+ fgColor,
116+ bgColor, // Color ("color00"–"color15")
117+});
118+```
119+
120+Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to ANSI 16 by default; custom themes can remap to different ANSI indices or 24-bit true color. Omit a color prop for the terminal default.
121+
122+## TextInput Props
123+
124+```ts
125+TextInput({
126+ value, // string (controlled)
127+ onChange, // (value: string) => void
128+ onKeyPress, // (key: string) => boolean | void — normalized semantic key string; return false to prevent default editing action
129+ placeholder, // Text() node shown when empty
130+ // + all container props (sizing, styling, focus, scrollStep, etc.)
131+});
132+```
133+
134+Enter inserts a newline by default. Use `onKeyPress` to intercept keys before editing:
135+
136+```ts
137+// Enter submits instead of inserting newline
138+TextInput({
139+ value: input,
140+ onChange: handleChange,
141+ onKeyPress: (key) => {
142+ if (key === "enter") {
143+ handleSend();
144+ return false;
145+ }
146+ },
147+});
148+```
149+
150+When focused, TextInput consumes insertable text plus editing/navigation keys, including readline-style shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and deletion are whitespace-delimited, and `up` / `down` navigate visual wrapped lines. Other modifier combos and non-insertable control keys bubble. Key strings are semantic identifiers for handlers, not necessarily the exact inserted text — uppercase `A` normalizes to key `"a …
151+
152+## Sizing Strategies
153+
154+Containers accept 4 sizing strategies:
155+
156+```ts
157+VStack({}, []); // Intrinsic — size to fit content (default)
158+VStack({ width: 30, height: 10 }, []); // Fixed — exact cell count
159+VStack({ flex: 1 }, []); // Flex — proportional to siblings
160+VStack({ width: "50%", height: "100%" }, []); // Percentage — relative to parent
161+```
162+
163+Constraints: `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
164+
165+Text has no sizing props — parent controls the box, height is intrinsic (content + wrapping).
166+
167+TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.) plus container scroll props like `scrollStep` for mouse wheel behavior.
168+
169+## Key Format
170+
171+All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`, `"enter"`, `"alt+up"`, `"f1"`. Framework normalizes modifier order.
172+
173+cel-tui is **Kitty-first** and works well in `tmux` with `set -s extended-keys on`. Recoverable legacy forms normalize to the same key strings, but historically collapsed collisions (`ctrl+i` vs `tab`, `ctrl+m` vs `enter`, `ctrl+[` vs `escape`) remain limited by what the host terminal or multiplexer reports.
174+
175+## Pre-made Components
176+
177+```ts
178+import {
179+ Spacer,
180+ Divider,
181+ Button,
182+ Select,
183+ VDivider,
184+ Markdown,
185+ SyntaxHighlight,
186+} from "@cel-tui/components";
187+
188+Spacer(); // VStack({ flex: 1 }, [])
189+Divider(); // Text("─", { repeat: "fill" })
190+Divider({ char: "═", fgColor: "color08" });
191+Button("[OK]", { onClick: handleOk });
192+Button("✕", { onClick: handleClose, focusable: false });
193+// Button accepts: onClick, focusable, focused, onFocus, onBlur, focusStyle,
194+// onKeyPress, padding, bold, fgColor, bgColor, italic, underline.
195+// Note: Button does not forward container sizing props (width, height, flex).
196+// For full layout control, use HStack + Text directly.
197+```
198+
199+### Select (filterable list)
200+
201+Select props: `items`, `onSelect`, `placeholder` (default `"type to filter..."`), `maxVisible` (default `10`), `indicator` (default `"›"`), `highlightColor` (default `"color06"`), `onKeyPress` (composed with internal handler), plus container/style props: `width`, `height`, `flex`, `fgColor`, `bgColor`, `focused`, `focusable`, `onFocus`, `onBlur`, `focusStyle`.
202+
203+```ts
204+const mySelect = Select({
205+ items: ["apple", "banana", "cherry"],
206+ onSelect: (value) => {
207+ chosen = value;
208+ cel.render();
209+ },
210+ placeholder: "search fruits...",
211+ maxVisible: 8,
212+});
213+
214+// Select returns false for unrecognized keys, so they bubble to root.
215+cel.viewport(() =>
216+ VStack(
217+ {
218+ height: "100%",
219+ onKeyPress: (key) => {
220+ if (key === "ctrl+q") {
221+ cel.stop();
222+ process.exit();
223+ }
224+ },
225+ },
226+ [Text("Pick a fruit:"), mySelect()],
227+ ),
228+);
229+
230+// Reset state programmatically
231+mySelect.reset();
232+```
233+
234+Rich items with separate display label, return value, and filter text:
235+
236+```ts
237+const modelSelect = Select({
238+ items: [
239+ {
240+ label: "claude-sonnet-4 (free)",
241+ value: "anthropic/claude-sonnet-4",
242+ filterText: "claude-sonnet-4",
243+ },
244+ { label: "gpt-4o", value: "openai/gpt-4o", filterText: "gpt-4o" },
245+ ],
246+ onSelect: (value) => {
247+ model = value;
248+ cel.render();
249+ },
250+});
251+```
252+
253+### VDivider (vertical divider)
254+
255+```ts
256+import { VDivider } from "@cel-tui/components";
257+
258+// Separate columns in an HStack
259+HStack({ height: "100%" }, [
260+ VStack({ flex: 1 }, [Text("left pane")]),
261+ VDivider({ fgColor: "color08" }),
262+ VStack({ flex: 1 }, [Text("right pane")]),
263+]);
264+
265+// Custom character
266+VDivider({ char: "║", fgColor: "color08" });
267+```
268+
269+### Markdown (rendered markdown)
270+
271+Returns an array of nodes — spread into a container's children:
272+
273+````ts
274+import { Markdown } from "@cel-tui/components";
275+
276+VStack(
277+ { flex: 1, overflow: "scroll", padding: { x: 1 } },
278+ Markdown("# Hello\n\nSome **bold** text.\n\n```js\nconst x = 1;\n```"),
279+);
280+````
281+
282+Custom theme for markdown styling:
283+
284+```ts
285+Markdown(content, {
286+ theme: {
287+ heading1: { bold: true, fgColor: "color05" },
288+ codeBlock: { bgColor: "color08" },
289+ bold: { bold: true, fgColor: "color03" },
290+ },
291+});
292+```
293+
294+Streaming works naturally — append chunks and call `cel.render()`. Unclosed blocks are handled gracefully.
295+
296+### SyntaxHighlight (rendered code)
297+
298+Returns a `VStack` — place it directly in a container's children:
299+
300+```ts
301+import { SyntaxHighlight } from "@cel-tui/components";
302+
303+VStack({ flex: 1, overflow: "scroll", padding: { x: 1 } }, [
304+ SyntaxHighlight(code, "typescript"),
305+]);
306+
307+SyntaxHighlight(code, "javascript", { theme: "dark-plus" });
308+```
309+
310+- Signature: `SyntaxHighlight(content, language, props?)`
311+- `language` accepts registered lextide language ids and aliases
312+- `props.theme` accepts the built-in presets (`"default"`, `"dark-plus"`) or a best-effort token theme registration object
313+- Uses a terminal-friendly ANSI 16 fallback theme by default
314+- Highlighting is synchronous at the component boundary; unsupported languages render plain text
315+- Content changes re-highlight the full snippet so final output stays stable across streamed chunk boundaries
316+
317+## Theme
318+
319+The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to different ANSI indices or 24-bit hex:
320+
321+```ts
322+import { cel, ProcessTerminal, type Theme } from "@cel-tui/core";
323+
324+const mocha: Theme = {
325+ color00: "#1e1e2e",
326+ color01: "#f38ba8",
327+ color02: "#a6e3a1",
328+ color03: "#f9e2af",
329+ color04: "#89b4fa",
330+ color05: "#cba6f7",
331+ color06: "#94e2d5",
332+ color07: "#cdd6f4",
333+ color08: "#45475a",
334+ color09: "#f38ba8",
335+ color10: "#a6e3a1",
336+ color11: "#f9e2af",
337+ color12: "#89b4fa",
338+ color13: "#cba6f7",
339+ color14: "#94e2d5",
340+ color15: "#bac2de",
341+};
342+
343+cel.init(new ProcessTerminal(), { theme: mocha });
344+```
345+
346+App code uses `"color00"`–`"color15"` regardless of theme. The mapping is a rendering concern.