xonecas.io
70160
Ce

cel-tui / commit 12de7e8

docs: align docs with current spec and implementation

- api.md: fix onScroll signature to include maxOffset parameter,
  add flexWrap to Container Props, add VDivider/Markdown/Theme docs,
  fix Button accepted props description
- SKILL.md: fix version to 0.1.1, fix onScroll example to include
  maxOffset, add flexWrap and theme mention to containers description,
  fix Button limitations gotcha (it does forward focusStyle)
- AGENTS.md: update Implementation Status for cross-axis constraints,
  grapheme-aware TextInput editing, cursor rendering, background fill;
  update text-edit.ts and paint.ts architecture notes
- README.md: add VDivider and Markdown to components table

xonecas2026-04-05 12de7e89a53eb9b1421abc9ab6266c99f1ca25e7 parent ac255bb

4 files changed

AGENTS.md+4−4
@@ -36,11 +36,11 @@ Dependency chain: `components → core → types`
3636
3737 All core systems from the spec are implemented and tested:
3838
39-- **Layout engine** — flexbox sizing (fixed, intrinsic, flex, percentage), constraints, gap, padding, justifyContent, alignItems, largest-remainder rounding
39+- **Layout engine** — flexbox sizing (fixed, intrinsic, flex, percentage), constraints (including cross-axis min/max), gap, padding, justifyContent, alignItems, flexWrap, largest-remainder rounding
4040 - **Rendering** — cell buffer, ANSI emitter with SGR styling, synchronized output (CSI 2026), differential rendering (emitDiff), full clear on resize
4141 - **Painting** — grapheme-aware text rendering (CJK/emoji via visibleWidth), overflow clipping via clip rect propagation, scroll content offsetting, scrollbar indicators, container bgColor fill, style inheritance, focusStyle overrides
4242 - **Input** — Kitty keyboard protocol (level 1, required), key parsing/normalization for CSI u / CSI letter / CSI tilde formats, SGR mouse events (with batched event support), hit detection, click/scroll routing, focus traversal (Tab/Shift+Tab/Escape/Enter) with uncontrolled and controlled modes, onKeyPress bubbling from focused element through ancestors
43-- **TextInput** — text editing, cursor movement, cursor persistence across re-renders (keyed on onChange), auto-scroll to keep cursor visible, placeholder rendering
43+- **TextInput** — grapheme-aware text editing (Intl.Segmenter for emoji/ZWJ), cursor movement, cursor persistence across re-renders (keyed on onChange, clamped on external value changes), auto-scroll to keep cursor visible, inverted-cell cursor with native terminal cursor positioning (blinking), background fill, placeholder rendering
4444 - **Layering** — multi-layer compositing, transparency, topmost-layer input priority
4545 - **Terminal** — Kitty keyboard protocol enable/disable, crash cleanup (SIGINT/SIGTERM/uncaughtException), resize clear
4646
@@ -205,11 +205,11 @@ chore: scaffold monorepo with types, core, components packages
205205
206206 - `cel.ts` — Framework entrypoint. Owns render loop, input dispatch, focus management. `cel.init(terminal, options?)` starts (accepts optional `{ theme }` for custom color themes), `cel.viewport(fn)` sets render function, `cel.render()` requests re-render, `cel.stop()` restores terminal. Mouse input handles batched SGR events (terminals often send multiple events in a single data chunk).
207207 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
208-- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets (clamped to max — apps can pass `Infinity` to mean "scroll to end"), scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state, container bgColor fill, style inheritance threading, focusStyle resolution.
208+- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets (clamped to max — apps can pass `Infinity` to mean "scroll to end"), scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state (with cursor screen position export for native cursor), TextInput background fill, container bgColor fill, style inheritance threading, focusStyle resolution.
209209 - `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both accept an optional `Theme` for color resolution and wrap in CSI 2026 synchronized output. Exports `defaultTheme` (ANSI 16 mapping).
210210 - `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
211211 - `keys.ts` — Kitty keyboard protocol parser. `parseKey(data)` handles CSI u sequences (special keys, modifier combos), CSI letter sequences (arrows, Home/End with modifiers), CSI tilde sequences (Delete, PageUp/Down, F-keys with modifiers), and raw printable bytes. Maps `" "` → `"space"`, `"+"` → `"plus"` as named keys. `isEditingKey()` identifies keys consumed by TextInput. `normalizeKey()` reorders modifiers to canonical `ctrl+alt+shift+<key>` order.
212-- `text-edit.ts` — Pure text editing functions (`insertChar`, `deleteBackward`, `deleteForward`, `moveCursor`). Operates on `EditState` (value + cursor position). Used by `cel.ts` to handle TextInput key events.
212+- `text-edit.ts` — Pure text editing functions (`insertChar`, `deleteBackward`, `deleteForward`, `moveCursor`). Operates on `EditState` (value + cursor position). Uses `Intl.Segmenter` with grapheme granularity for cursor movement and deletion (handles emoji, ZWJ sequences, combining marks). Used by `cel.ts` to handle TextInput key events.
213213 - `width.ts` — `visibleWidth(str)` measures terminal column width. Fast ASCII path, grapheme segmentation, East Asian width, ANSI stripping, LRU cache.
214214 - `terminal.ts` — `ProcessTerminal` (real I/O, raw mode, Kitty keyboard protocol level 1, SGR mouse, crash cleanup) and `MockTerminal` (testing).
215215
README.md+5−5
@@ -70,11 +70,11 @@ cel.viewport(() =>
7070
7171 ## Packages
7272
73-| Package | Description |
74-| --------------------- | ----------------------------------------------------- |
75-| `@cel-tui/types` | Shared type definitions |
76-| `@cel-tui/core` | Framework engine and primitives |
77-| `@cel-tui/components` | Pre-made components (Button, Spacer, Divider, Select) |
73+| Package | Description |
74+| --------------------- | ------------------------------------------------------------------------- |
75+| `@cel-tui/types` | Shared type definitions |
76+| `@cel-tui/core` | Framework engine and primitives |
77+| `@cel-tui/components` | Pre-made components (Button, Spacer, Divider, VDivider, Select, Markdown) |
7878
7979 ## Documentation
8080
docs/skill/cel-tui/SKILL.md+4−4
@@ -5,7 +5,7 @@ license: MIT
55 compatibility: Requires Bun runtime and a terminal with SGR mouse mode support.
66 metadata:
77 author: sacenox
8- version: "0.1.0"
8+ version: "0.1.1"
99 ---
1010
1111 # Building TUIs with cel-tui
@@ -75,7 +75,7 @@ The steps: `cel.init(terminal)` → `cel.viewport(() => tree)` → mutate state
7575 | `Text(content, props?)` | Leaf | Styled text, no children |
7676 | `TextInput(props)` | Container (no children) | Multi-line editable text |
7777
78-Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`), scroll (`overflow: "scroll"`, `scrollbar`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default.
78+Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to true color via `cel.init(terminal, { theme })`.
7979
8080 Read [references/api.md](references/api.md) for the full props listing, sizing strategies, text props, and component reference.
8181
@@ -113,7 +113,7 @@ VStack(
113113 overflow: "scroll",
114114 scrollbar: true,
115115 scrollOffset: offset,
116- onScroll: (newOffset) => {
116+ onScroll: (newOffset, maxOffset) => {
117117 offset = newOffset;
118118 cel.render();
119119 },
@@ -225,7 +225,7 @@ mySelect.reset(); // clear filter/highlight programmatically
225225 - **Crash cleanup** — terminal state is restored on SIGINT, SIGTERM, uncaughtException.
226226 - **Always call `cel.stop()` before `process.exit()`** — restores raw mode, mouse tracking, and alternate screen.
227227 - **Kitty keyboard protocol required** — the framework requires the Kitty keyboard protocol (level 1). All modifier combos (`alt+x`, `ctrl+plus`, `shift+enter`) are fully supported. The terminal must support this protocol (Kitty, WezTerm, Ghostty, foot, Alacritty, Windows Terminal). macOS Terminal.app and older xterm are not supported.
228-- **Button limitations** — `Button` from `@cel-tui/components` does not forward `focusStyle`, container sizing, or all style props. Use `HStack` + `Text` directly when you need full control.
228+- **Button limitations** — `Button` from `@cel-tui/components` does not forward container sizing props (`width`, `height`, `flex`, `minWidth`, etc.). It supports styling (`fgColor`, `bgColor`, `bold`, etc.), `focusStyle`, `focused`, `onFocus`, `onBlur`, `onKeyPress`, and `padding`. For full layout control, use `HStack` + `Text` directly.
229229
230230 ## Composing Components
231231
docs/skill/cel-tui/references/api.md+82−6
@@ -18,7 +18,8 @@ All props accepted by `VStack` and `HStack`:
1818 overflow, // "hidden" (default) | "scroll"
1919 scrollbar, // boolean
2020 scrollOffset, // number (controlled scroll)
21- onScroll, // (offset: number) => void
21+ onScroll, // (offset: number, maxOffset: number) => void
22+ flexWrap, // "nowrap" (default) | "wrap" (HStack only)
2223
2324 // Styling (inherited by descendants)
2425 bold, italic, underline,// boolean
@@ -49,7 +50,7 @@ VStack(
4950 overflow: "scroll",
5051 scrollbar: true,
5152 scrollOffset: offset,
52- onScroll: (newOffset) => {
53+ onScroll: (newOffset, maxOffset) => {
5354 offset = newOffset;
5455 cel.render();
5556 },
@@ -60,7 +61,7 @@ VStack(
6061
6162 - Scroll direction follows the container’s main axis: VStack → vertical, HStack → horizontal.
6263 - Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
63-- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset.
64+- 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).
6465
6566 ## Text Props
6667
@@ -122,9 +123,10 @@ Divider(); // Text("─", { repeat: "fill" })
122123 Divider({ char: "═", fgColor: "color08" });
123124 Button("[OK]", { onClick: handleOk });
124125 Button("✕", { onClick: handleClose, focusable: false });
125-// Button accepts: onClick, bold, fgColor, bgColor, focusable, focusStyle
126-// Note: Button does not forward container sizing props.
127-// For full control, use HStack + Text directly.
126+// Button accepts: onClick, focusable, focused, onFocus, onBlur, focusStyle,
127+// onKeyPress, padding, bold, fgColor, bgColor, italic, underline.
128+// Note: Button does not forward container sizing props (width, height, flex).
129+// For full layout control, use HStack + Text directly.
128130 ```
129131
130132 ### Select (filterable list)
@@ -180,3 +182,77 @@ const modelSelect = Select({
180182 },
181183 });
182184 ```
185+
186+### VDivider (vertical divider)
187+
188+```ts
189+import { VDivider } from "@cel-tui/components";
190+
191+// Separate columns in an HStack
192+HStack({ height: "100%" }, [
193+ VStack({ flex: 1 }, [Text("left pane")]),
194+ VDivider({ fgColor: "color08" }),
195+ VStack({ flex: 1 }, [Text("right pane")]),
196+]);
197+
198+// Custom character
199+VDivider({ char: "║", fgColor: "color08" });
200+```
201+
202+### Markdown (rendered markdown)
203+
204+Returns an array of nodes — spread into a container's children:
205+
206+````ts
207+import { Markdown } from "@cel-tui/components";
208+
209+VStack(
210+ { flex: 1, overflow: "scroll", padding: { x: 1 } },
211+ Markdown("# Hello\n\nSome **bold** text.\n\n```js\nconst x = 1;\n```"),
212+);
213+````
214+
215+Custom theme for markdown styling:
216+
217+```ts
218+Markdown(content, {
219+ theme: {
220+ heading1: { bold: true, fgColor: "color05" },
221+ codeBlock: { bgColor: "color08" },
222+ bold: { bold: true, fgColor: "color03" },
223+ },
224+});
225+```
226+
227+Streaming works naturally — append chunks and call `cel.render()`. Unclosed blocks are handled gracefully.
228+
229+## Theme
230+
231+The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to 256-color or 24-bit hex:
232+
233+```ts
234+import { cel, ProcessTerminal, type Theme } from "@cel-tui/core";
235+
236+const mocha: Theme = {
237+ color00: "#1e1e2e",
238+ color01: "#f38ba8",
239+ color02: "#a6e3a1",
240+ color03: "#f9e2af",
241+ color04: "#89b4fa",
242+ color05: "#cba6f7",
243+ color06: "#94e2d5",
244+ color07: "#cdd6f4",
245+ color08: "#45475a",
246+ color09: "#f38ba8",
247+ color10: "#a6e3a1",
248+ color11: "#f9e2af",
249+ color12: "#89b4fa",
250+ color13: "#cba6f7",
251+ color14: "#94e2d5",
252+ color15: "#bac2de",
253+};
254+
255+cel.init(new ProcessTerminal(), { theme: mocha });
256+```
257+
258+App code uses `"color00"`–`"color15"` regardless of theme. The mapping is a rendering concern.