xonecas.io
725
Ds

diff-scope / files

diff-scope / .agents / skills / cel-tui / references / api.md

11.7 KB
1# cel-tui API Reference
2
3## Framework lifecycle
4
5```ts
6cel.init(new ProcessTerminal(), { theme?: Theme });
7cel.viewport(() => tree); // or () => [layer1, layer2]
8cel.render();
9cel.setTitle("My App");
10cel.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
20All 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
58measureContentHeight(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
67const addedHeight = measureContentHeight(
68  VStack({}, olderMessages.map(renderMessage)),
69  { width: historyContentWidth },
70);
71
72scrollOffset += addedHeight;
73```
74
75Measure 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
79Scroll supports **uncontrolled** (default) and **controlled** modes, mirroring the focus model:
80
81```ts
82// Uncontrolled — framework manages scroll position. Mouse wheel just works.
83VStack({ overflow: "scroll", scrollbar: true }, [...items]);
84
85// Controlled — app owns scroll state.
86VStack(
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
109Text("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
120Colors: 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
125TextInput({
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
134Enter inserts a newline by default. Use `onKeyPress` to intercept keys before editing:
135
136```ts
137// Enter submits instead of inserting newline
138TextInput({
139  value: input,
140  onChange: handleChange,
141  onKeyPress: (key) => {
142    if (key === "enter") {
143      handleSend();
144      return false;
145    }
146  },
147});
148```
149
150When 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"` while still inserting `"A"`.
151
152## Sizing Strategies
153
154Containers accept 4 sizing strategies:
155
156```ts
157VStack({}, []); // Intrinsic — size to fit content (default)
158VStack({ width: 30, height: 10 }, []); // Fixed — exact cell count
159VStack({ flex: 1 }, []); // Flex — proportional to siblings
160VStack({ width: "50%", height: "100%" }, []); // Percentage — relative to parent
161```
162
163Constraints: `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
164
165Text has no sizing props — parent controls the box, height is intrinsic (content + wrapping).
166
167TextInput 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
171All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`, `"enter"`, `"alt+up"`, `"f1"`. Framework normalizes modifier order.
172
173cel-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
178import {
179  Spacer,
180  Divider,
181  Button,
182  Select,
183  VDivider,
184  Markdown,
185  SyntaxHighlight,
186} from "@cel-tui/components";
187
188Spacer(); // VStack({ flex: 1 }, [])
189Divider(); // Text("─", { repeat: "fill" })
190Divider({ char: "═", fgColor: "color08" });
191Button("[OK]", { onClick: handleOk });
192Button("✕", { 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
201Select 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
204const 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.
215cel.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
231mySelect.reset();
232```
233
234Rich items with separate display label, return value, and filter text:
235
236```ts
237const 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
256import { VDivider } from "@cel-tui/components";
257
258// Separate columns in an HStack
259HStack({ 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
266VDivider({ char: "║", fgColor: "color08" });
267```
268
269### Markdown (rendered markdown)
270
271Returns an array of nodes — spread into a container's children:
272
273````ts
274import { Markdown } from "@cel-tui/components";
275
276VStack(
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
282Custom theme for markdown styling:
283
284```ts
285Markdown(content, {
286  theme: {
287    heading1: { bold: true, fgColor: "color05" },
288    codeBlock: { bgColor: "color08" },
289    bold: { bold: true, fgColor: "color03" },
290  },
291});
292```
293
294Streaming works naturally — append chunks and call `cel.render()`. Unclosed blocks are handled gracefully.
295
296### SyntaxHighlight (rendered code)
297
298Returns a `VStack` — place it directly in a container's children:
299
300```ts
301import { SyntaxHighlight } from "@cel-tui/components";
302
303VStack({ flex: 1, overflow: "scroll", padding: { x: 1 } }, [
304  SyntaxHighlight(code, "typescript"),
305]);
306
307SyntaxHighlight(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
319The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to different ANSI indices or 24-bit hex:
320
321```ts
322import { cel, ProcessTerminal, type Theme } from "@cel-tui/core";
323
324const 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
343cel.init(new ProcessTerminal(), { theme: mocha });
344```
345
346App code uses `"color00"`–`"color15"` regardless of theme. The mapping is a rendering concern.