xonecas.io
70160
Ce

cel-tui / commit 6982c8f

docs: add demo gif, hello example, and TODO

- Demo gif in README (centered, from screencast)
- examples/hello.ts: stylish centered logo with color cycling and clock
- TODO.md: full gap analysis between spec and implementation with priority order

xonecas2026-04-03 6982c8f0eb9da7a72f97fa6663da15087dc586de parent b8e64c3

4 files changed

README.md+4−0
@@ -2,6 +2,10 @@
22
33 A TypeScript TUI framework built around a declarative functional API and ultra-fast rendering.
44
5+<p align="center">
6+ <img src="assets/demo.gif" alt="cel-tui demo" width="539" />
7+</p>
8+
59 ## Why "cel"?
610
711 A **cel** is the smallest unit of a terminal display — a single character cell. Start from the smallest meaningful unit and build up, with nothing wasted.
TODO.md+120−0
@@ -0,0 +1,120 @@
1+# cel-tui — TODO
2+
3+What's implemented, what's missing, and what needs hardening. Reference `spec.md` for full design.
4+
5+## Legend
6+
7+- ✅ Implemented and tested
8+- 🔧 Partially implemented (basic version exists, needs work)
9+- ❌ Not yet implemented
10+
11+---
12+
13+## Layout Engine
14+
15+- ✅ Fixed sizing (`width: 30, height: 10`)
16+- ✅ Intrinsic sizing (containers fit children, Text height from content)
17+- ✅ Flex distribution with largest remainder rounding
18+- ✅ Percentage sizing (`width: "50%"`)
19+- ✅ Constraints (`minWidth`, `maxWidth`, `minHeight`, `maxHeight`)
20+- ✅ Gap spacing between children
21+- ✅ Padding (`{ x, y }`)
22+- ❌ `justifyContent` — positions are computed but alignment offsets not applied (`"start"`, `"end"`, `"center"`, `"space-between"`)
23+- ❌ `alignItems` — cross-axis alignment not applied (`"start"`, `"end"`, `"center"`, `"stretch"`)
24+
25+## Rendering
26+
27+- ✅ Cell buffer (2D grid, get/set/fill/clear/resize/diff/isEmpty)
28+- ✅ ANSI emitter (SGR colors, bold/italic/underline, synchronized output CSI 2026)
29+- ✅ Reactive rendering (`cel.render()` batched via `process.nextTick`)
30+- ✅ Full render on first paint, cursor home positioning
31+- 🔧 Differential rendering — `CellBuffer.diff()` exists but `cel.ts` always does full redraws (doesn't use diff to skip unchanged cells)
32+- ❌ Full clear + re-render on terminal resize (currently re-renders but doesn't clear scrollback)
33+
34+## Painting
35+
36+- ✅ Text painting (content, newlines, styling)
37+- ✅ Text `repeat: "fill"` and `repeat: <number>`
38+- ✅ Text `wrap: "word"` (basic word-wrap)
39+- ✅ Hard clipping at rect boundaries
40+- ✅ TextInput painting (value, placeholder, cursor via color inversion)
41+- 🔧 Text wrapping and layout use `string.length` for width — should use `visibleWidth()` for correct CJK/emoji handling
42+- ❌ Overflow clipping (`overflow: "hidden"`) — children aren't clipped to parent bounds
43+- ❌ Scroll rendering (`overflow: "scroll"`) — content offset not applied during painting
44+- ❌ Scrollbar rendering (`scrollbar: true`)
45+
46+## Input
47+
48+- ✅ Key parsing (ASCII, control chars, CSI sequences, arrow keys, function keys)
49+- ✅ Key normalization (canonical modifier order)
50+- ✅ Mouse event parsing (SGR mode: click, scroll-up, scroll-down)
51+- ✅ Hit detection (point → deepest node path)
52+- ✅ Click routing (innermost `onClick` wins)
53+- ✅ Scroll routing (innermost scrollable, fires `onScroll`)
54+- ✅ Key routing to `onKeyPress` handlers
55+- ✅ TextInput key consumption (editing keys consumed, modifiers bubble)
56+- 🔧 `onKeyPress` bubbling — currently only checks the root container, should walk up from focused element through all ancestors
57+- ❌ Focus traversal (Tab/Shift+Tab cycling through focusable elements)
58+- ❌ Escape to unfocus
59+- ❌ Enter to activate focused clickable container
60+- ❌ Mouse click focusing (clicking a focusable element should fire `onFocus`)
61+- ❌ `onFocus`/`onBlur` callbacks not fired by framework
62+
63+## Layer Compositing
64+
65+- ✅ Multiple layers paint bottom-to-top
66+- ✅ Transparency (empty cells in upper layer show lower layer)
67+- ✅ Topmost layer receives input events first
68+- ✅ Conditional layers (show/hide via array inclusion)
69+
70+## TextInput
71+
72+- ✅ Text editing (insert, delete backward/forward)
73+- ✅ Cursor movement (left/right/up/down/home/end)
74+- ✅ Vertical navigation across lines
75+- ✅ `onChange` fires on edits
76+- ✅ `onSubmit` fires on `submitKey`
77+- ✅ Placeholder rendering
78+- ✅ Cursor display (inverted colors)
79+- 🔧 Cursor state uses `WeakMap` keyed on props — works for single render but may lose cursor position across re-renders since props objects are recreated each frame
80+- ❌ Framework-managed scroll (auto-scroll to keep cursor visible)
81+- ❌ Mouse wheel scroll inside TextInput
82+
83+## Terminal
84+
85+- ✅ `ProcessTerminal` (raw mode, SGR mouse, cursor hide/show)
86+- ✅ `MockTerminal` (captured output, simulated input/resize)
87+- ❌ Restore terminal state on crash/unhandled exception (cleanup handler)
88+- ❌ Bracketed paste mode support
89+- ❌ Kitty keyboard protocol detection
90+
91+## Pre-made Components
92+
93+- ✅ `Spacer` — `VStack({ flex: 1 }, [])`
94+- ✅ `Divider` — `Text(char, { repeat: "fill" })`
95+- ✅ `Button` — `HStack({ onClick }, [Text(label)])`
96+
97+## Developer Experience
98+
99+- ✅ JSDoc on all public types, interfaces, and functions
100+- ✅ TypeDoc generation (HTML + Markdown)
101+- ✅ Agent Skills file (`docs/skill/cel-tui/SKILL.md`)
102+- ✅ AGENTS.md for onboarding
103+- ❌ Example apps that fully work end-to-end (`examples/hello.ts` needs alignment)
104+
105+---
106+
107+## Priority Order
108+
109+Suggested order to tackle remaining work:
110+
111+1. **`justifyContent` + `alignItems`** — unblocks the hello example and any centered layout
112+2. **`visibleWidth` integration** — text measurement in layout + paint should use grapheme-aware width
113+3. **Overflow clipping** — parent bounds must clip children (`overflow: "hidden"`)
114+4. **Scroll rendering** — `overflow: "scroll"` offsets content, scrollbar indicator
115+5. **Differential rendering** — use `CellBuffer.diff()` to emit only changed cells
116+6. **Focus system** — Tab traversal, Escape unfocus, Enter activate, onFocus/onBlur
117+7. **`onKeyPress` full bubbling** — walk up from focused element, not just root
118+8. **TextInput cursor persistence** — stable identity across re-renders
119+9. **TextInput auto-scroll** — scroll to keep cursor visible
120+10. **Terminal hardening** — crash cleanup, bracketed paste, resize clear
assets/demo.gif+0−0
Binary file, not shown.
examples/hello.ts+99−0
@@ -0,0 +1,99 @@
1+/**
2+ * cel-tui: Hello World
3+ *
4+ * A stylish first impression — centered ASCII art logo with a
5+ * reactive clock and keyboard hints. Press any key to cycle
6+ * colors, Ctrl+Q to quit.
7+ *
8+ * Run: bun run examples/hello.ts
9+ */
10+
11+import { cel, VStack, HStack, Text, ProcessTerminal } from "@cel-tui/core";
12+
13+const logo = [
14+ " ╭─────────────────────╮",
15+ " │ ██████╗███████╗██╗ │",
16+ " │ ██╔════╝██╔════╝██║ │",
17+ " │ ██║ █████╗ ██║ │",
18+ " │ ██║ ██╔══╝ ██║ │",
19+ " │ ╚██████╗███████╗██║ │",
20+ " │ ╚═════╝╚══════╝╚═╝ │",
21+ " ╰─────────────────────╯",
22+];
23+
24+const palette: Array<"cyan" | "magenta" | "yellow" | "green" | "blue" | "red"> =
25+ ["cyan", "magenta", "yellow", "green", "blue", "red"];
26+
27+let colorIndex = 0;
28+let tick = 0;
29+
30+const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
31+
32+function clock(): string {
33+ const now = new Date();
34+ return now.toLocaleTimeString("en-US", { hour12: false });
35+}
36+
37+// Animate spinner
38+setInterval(() => {
39+ tick++;
40+ cel.render();
41+}, 80);
42+
43+cel.init(new ProcessTerminal());
44+cel.viewport(() => {
45+ const color = palette[colorIndex % palette.length]!;
46+ const spinner = spinnerFrames[tick % spinnerFrames.length]!;
47+
48+ return VStack(
49+ {
50+ height: "100%",
51+ justifyContent: "center",
52+ alignItems: "center",
53+ onKeyPress: (key) => {
54+ if (key === "ctrl+q" || key === "ctrl+c") {
55+ cel.stop();
56+ process.exit();
57+ }
58+ colorIndex++;
59+ cel.render();
60+ },
61+ },
62+ [
63+ // Logo
64+ ...logo.map((line) => Text(line, { fgColor: color, bold: true })),
65+
66+ // Tagline
67+ Text(""),
68+ Text(" terminal UIs, cell by cell", {
69+ italic: true,
70+ fgColor: "brightBlack",
71+ }),
72+
73+ // Divider
74+ Text(""),
75+ HStack({}, [
76+ Text(" "),
77+ Text("─", { repeat: 34, fgColor: color }),
78+ Text(" "),
79+ ]),
80+ Text(""),
81+
82+ // Live info row
83+ HStack({ gap: 2 }, [
84+ Text(` ${spinner}`, { fgColor: color, bold: true }),
85+ Text(clock(), { fgColor: "white" }),
86+ Text("│", { fgColor: "brightBlack" }),
87+ Text("press any key to change color", { fgColor: "brightBlack" }),
88+ ]),
89+
90+ // Quit hint
91+ Text(""),
92+ HStack({ gap: 1 }, [
93+ Text(" "),
94+ Text(" ctrl+q ", { bgColor: color, fgColor: "black", bold: true }),
95+ Text("quit", { fgColor: "brightBlack" }),
96+ ]),
97+ ],
98+ );
99+});