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.