xonecas.io
70160
Ce

cel-tui / commit a70a559

docs: update TODO, AGENTS, README, and SKILL for 0.1.0 API changes

- TODO: mark bgColor, uncontrolled focus, and style inheritance as done.
  Update Button component TODO for new focusStyle/style props.
  Remove style context TODO (superseded by style inheritance).

- AGENTS: replace 'No style inheritance' with inheritance description.
  Replace controlled-by-default with uncontrolled-by-default. Add
  focusStyle. Update implementation status and architecture notes.

- README: update Quick Example to use uncontrolled focus and inherited
  fgColor. Update Key Concepts (style inheritance, uncontrolled default).

- SKILL: update version to 0.1.0. Add style inheritance, focusStyle,
  uncontrolled focus patterns. Update Container Props, TextInput Props,
  Button example, modal example, focus section, and key rules.

xonecas2026-04-04 a70a55904e7f7455d8862df7e5a65500ba5f1bdc parent ac77a43

4 files changed

AGENTS.md+7−7
@@ -21,11 +21,11 @@ Dependency chain: `components → core → types`
2121
2222 - **4 primitives only:** VStack, HStack (layout), Text (content leaf), TextInput (editable container)
2323 - **State is external:** The framework has no state management. `cel.viewport(() => tree)` sets a render function, `cel.render()` requests re-evaluation. Apps use whatever state approach they want.
24-- **Controlled props pattern:** Focus (`focused`/`onFocus`/`onBlur`), scroll (`scrollOffset`/`onScroll`), and value (`value`/`onChange`) are app-controlled. The app owns the state, the framework renders it.
25-- **Uncontrolled scroll default:** `overflow: "scroll"` without `scrollOffset` is framework-managed. Adding `scrollOffset` makes it controlled.
24+- **Uncontrolled by default, controlled opt-in:** Focus and scroll are framework-managed by default. Providing `focused` or `scrollOffset` explicitly switches to controlled mode (app owns the state). Value (`value`/`onChange`) on TextInput is always controlled.
25+- **Style inheritance:** Containers propagate style props (fgColor, bgColor, bold, italic, underline) to descendants. Explicit props on a node always override inherited values. Container `bgColor` fills the rect with opaque background before painting children.
26+- **focusStyle:** Containers accept `focusStyle: StyleProps` — style overrides applied when focused, participating in inheritance.
2627 - **TextInput is a container:** Accepts sizing props (flex, width, height, padding, min/max constraints) but has no children — its content is the `value` prop. Scroll is always framework-managed (follows cursor + responds to mouse wheel).
2728 - **Text is a pure leaf:** No sizing props, no children. Parent controls the box. Height is intrinsic (from content + wrapping).
28-- **No style inheritance:** Every Text/TextInput sets its own styles explicitly. No cascading. Verbose but predictable.
2929 - **Cell buffer rendering:** Layout writes to a 2D grid of styled cells, not raw strings. Clipping and layer compositing are cell writes. Diff against previous buffer for minimal terminal output.
3030 - **Reactive rendering:** `cel.render()` batches via `process.nextTick()`. No fixed FPS.
3131 - **Layers:** `cel.viewport(() => [layer1, layer2])` — array of independent viewport-sized trees, composited bottom-to-top. Conditional inclusion = show/hide.
@@ -38,8 +38,8 @@ All core systems from the spec are implemented and tested:
3838
3939 - **Layout engine** — flexbox sizing (fixed, intrinsic, flex, percentage), constraints, gap, padding, justifyContent, alignItems, largest-remainder rounding
4040 - **Rendering** — cell buffer, ANSI emitter with SGR styling, synchronized output (CSI 2026), differential rendering (emitDiff), full clear on resize
41-- **Painting** — grapheme-aware text rendering (CJK/emoji via visibleWidth), overflow clipping via clip rect propagation, scroll content offsetting, scrollbar indicators
42-- **Input** — key parsing/normalization, SGR mouse events (with batched event support), hit detection, click/scroll routing, focus traversal (Tab/Shift+Tab/Escape/Enter), onKeyPress bubbling from focused element through ancestors
41+- **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
42+- **Input** — key parsing/normalization, 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
4343 - **TextInput** — text editing, cursor movement, cursor persistence across re-renders (keyed on onChange), auto-scroll to keep cursor visible, placeholder rendering
4444 - **Layering** — multi-layer compositing, transparency, topmost-layer input priority
4545 - **Terminal** — crash cleanup (SIGINT/SIGTERM/uncaughtException), resize clear
@@ -94,7 +94,7 @@ This lets you see exactly what the user sees — rendered cells, alignment, clip
9494
9595 ## Spec
9696
97-The `spec.md` file is the source of truth for all API design decisions. Always read it before making changes to core framework behavior. The open questions at the bottom track what's been decided vs. still in progress.
97+The `spec.md` file is the source of truth for all API design decisions. Always read it before making changes to core framework behavior.
9898
9999 ## Testing Strategy
100100
@@ -143,7 +143,7 @@ chore: scaffold monorepo with types, core, components packages
143143
144144 - `cel.ts` — Framework entrypoint. Owns render loop, input dispatch, focus management. `cel.init(terminal)` starts, `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).
145145 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
146-- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets, scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state.
146+- `paint.ts` — Paints `LayoutNode` tree into `CellBuffer`. Handles clip rects, scroll offsets, scrollbars, grapheme-aware text rendering, TextInput cursor/scroll state, container bgColor fill, style inheritance threading, focusStyle resolution.
147147 - `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both wrap in CSI 2026 synchronized output.
148148 - `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `findKeyPressHandler`, `collectFocusable` walk paths.
149149 - `keys.ts` — `parseKey(data)` normalizes terminal input to canonical key strings. `isEditingKey()` identifies keys consumed by TextInput.
README.md+3−2
@@ -24,6 +24,7 @@ cel.viewport(() =>
2424 VStack(
2525 {
2626 height: "100%",
27+ fgColor: "white",
2728 onKeyPress: (key) => {
2829 if (key === "ctrl+q") process.exit();
2930 },
@@ -34,7 +35,6 @@ cel.viewport(() =>
3435 TextInput({
3536 flex: 1,
3637 value: input,
37- focused: true,
3838 onChange: (v) => {
3939 input = v;
4040 cel.render();
@@ -60,7 +60,8 @@ cel.viewport(() =>
6060 - **`cel.viewport(() => tree)`** sets the render function, **`cel.render()`** triggers re-renders.
6161 - **Flexbox layout** — fixed, flex, percentage, and intrinsic sizing with gap, padding, alignment.
6262 - **Layers** — return an array for multi-layer compositing (modals, overlays).
63-- **Controlled props** — focus, scroll, and text value are app-owned.
63+- **Uncontrolled by default** — focus and scroll just work. Opt into controlled mode when needed.
64+- **Style inheritance** — containers propagate styles to descendants. `bgColor` fills the rect.
6465 - **Cell buffer rendering** — styled cells, differential updates, synchronized output.
6566
6667 ## Packages
TODO.md+1−6
@@ -12,11 +12,7 @@ Remaining work, known bugs, and planned improvements.
1212
1313 ## API Improvements
1414
15-- ❌ **`bgColor` on containers** — Containers (VStack/HStack) have no background color. This forces manual per-row fills with `HStack({}, [Text(...), VStack({ flex: 1 }, [Text(" ", { repeat: "fill", bgColor })])])` to create solid panels, modals, or sidebars. Fix: add `bgColor` to `ContainerProps`. Paint should fill the container rect with bgColor before painting children. Single biggest DX win from the pet example.
16-
17-- ❌ **Upgrade `Button` component with focus support** — `Button` from `@cel-tui/components` only passes `onClick` and `focusable` to the underlying HStack. It doesn't support `focused`/`onFocus`/`onBlur`, making it useless for keyboard navigation. Every focusable button in the pet example required 5 inline props. Fix: add `focused`, `onFocus`, `onBlur`, and a `name` prop to `ButtonProps`, and forward them to the HStack.
18-
19-- ❌ **Uncontrolled focus option** — Focus is always controlled (app owns the state via `focused`/`onFocus`/`onBlur`). This creates significant boilerplate — every focusable element needs a state variable, an onFocus setter, an onBlur guard, and a `cel.render()` call. The framework should support uncontrolled focus by default (framework tracks focus internally, Tab/Shift+Tab/Escape just work), with controlled as an opt-in when `focused` is explicitly provided. Mirrors the uncontrolled/contr …
15+- ❌ **Upgrade `Button` component** — `Button` from `@cel-tui/components` doesn't forward `focusStyle`, `fgColor`, `bgColor`, or other container/style props to the underlying HStack. With uncontrolled focus and focusStyle now available, Button should accept these to be useful for keyboard navigation without inline HStack wrappers.
2016
2117 - ❌ **`repeat: "fill"` should claim flex space in HStack** — `Text(" ", { repeat: "fill" })` inside an HStack gets width 0 because its intrinsic width is 0 and no flex distributes remaining space. The workaround is `VStack({ flex: 1 }, [Text(" ", { repeat: "fill" })])`, which is non-obvious. Fix: either make `repeat: "fill"` imply flex behavior in the layout engine, or document the workaround prominently. The former is preferred.
2218
@@ -31,6 +27,5 @@ Remaining work, known bugs, and planned improvements.
3127
3228 ## Future Enhancements
3329
34-- 💡 Style context / theming — a way to set default styles for a subtree without inheritance. Deferred until the core is more battle-tested.
3530 - 💡 Additional example apps (chat UI, text editor from spec reference examples)
3631 - 💡 `overflow: "hidden"` as explicit prop (currently all containers clip by default, which matches the spec's default behavior, but the prop value is not checked)
docs/skill/cel-tui/SKILL.md+49−17
@@ -5,12 +5,12 @@ license: MIT
55 compatibility: Requires Bun runtime and a terminal with SGR mouse mode support.
66 metadata:
77 author: sacenox
8- version: "0.0.1"
8+ version: "0.1.0"
99 ---
1010
1111 # Building TUIs with cel-tui
1212
13-cel-tui is a TypeScript TUI framework with a declarative functional API, flexbox layout, and cell-buffer rendering. It has 4 primitives and external state management.
13+cel-tui is a TypeScript TUI framework with a declarative functional API, flexbox layout, cell-buffer rendering, and style inheritance. It has 4 primitives and external state management.
1414
1515 ## Install
1616
@@ -47,6 +47,7 @@ cel.viewport(() =>
4747 VStack(
4848 {
4949 height: "100%",
50+ fgColor: "white",
5051 onKeyPress: (key) => {
5152 if (key === "ctrl+q") {
5253 cel.stop();
@@ -60,7 +61,6 @@ cel.viewport(() =>
6061 TextInput({
6162 flex: 1,
6263 value,
63- focused: true,
6464 onChange: (v) => {
6565 value = v;
6666 cel.render();
@@ -101,6 +101,7 @@ TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`,
101101
102102 ```ts
103103 {
104+ // Sizing
104105 width, height, // SizeValue (number | "50%")
105106 flex, // number
106107 minWidth, maxWidth, // number
@@ -113,9 +114,16 @@ TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`,
113114 scrollbar, // boolean
114115 scrollOffset, // number (controlled scroll)
115116 onScroll, // (offset: number) => void
117+
118+ // Styling (inherited by descendants)
119+ bold, italic, underline,// boolean
120+ fgColor, bgColor, // Color (ANSI 16)
121+ focusStyle, // StyleProps — overrides when focused
122+
123+ // Interaction
116124 onClick, // () => void
117125 focusable, // boolean (default true if onClick set)
118- focused, // boolean (controlled)
126+ focused, // boolean (controlled — omit for uncontrolled)
119127 onFocus, // () => void
120128 onBlur, // () => void
121129 onKeyPress, // (key: string) => void
@@ -147,11 +155,7 @@ TextInput({
147155 onSubmit, // () => void
148156 submitKey, // string (default "enter")
149157 placeholder, // Text() node shown when empty
150- focused, // boolean (controlled)
151- onFocus,
152- onBlur, // () => void
153- // + all container sizing props
154- // + all styling props (bold, fgColor, etc.)
158+ // + all container props (sizing, styling, focus, etc.)
155159 });
156160 ```
157161
@@ -173,12 +177,17 @@ HStack({ height: 1 }, [
173177 Text("─", { repeat: "fill", fgColor: "brightBlack" });
174178 ```
175179
176-### Button
180+### Button with focus style
177181
178182 ```ts
179-HStack({ onClick: handleClick }, [
180- Text("[Send]", { bold: true, fgColor: "cyan" }),
181-]);
183+HStack(
184+ {
185+ onClick: handleClick,
186+ fgColor: "cyan",
187+ focusStyle: { bgColor: "cyan", fgColor: "black" },
188+ },
189+ [Text(" Send ", { bold: true })],
190+);
182191 ```
183192
184193 ### Growing text input (caps at maxHeight, then scrolls)
@@ -218,7 +227,7 @@ VStack(
218227
219228 ### Layers (modals)
220229
221-Return an array from the render function. Layers composite bottom-to-top:
230+Return an array from the render function. Layers composite bottom-to-top. Use `bgColor` for opaque modal backgrounds:
222231
223232 ```ts
224233 cel.viewport(() => [
@@ -235,7 +244,11 @@ cel.viewport(() => [
235244 cel.render();
236245 },
237246 },
238- [VStack({ width: 40, height: 10 }, [...modalContent])],
247+ [
248+ VStack({ width: 40, height: 10, bgColor: "black" }, [
249+ ...modalContent,
250+ ]),
251+ ],
239252 ),
240253 ]
241254 : []),
@@ -256,9 +269,15 @@ VStack({
256269 }, [...])
257270 ```
258271
259-### Focus (controlled)
272+### Focus
273+
274+Focus is **uncontrolled by default** — Tab/Shift+Tab/Escape/click just work:
260275
261276 ```ts
277+// Uncontrolled (default) — framework manages focus
278+HStack({ onClick: handleAction }, [Text("[ OK ]")]);
279+
280+// Controlled — app owns focus state (provide `focused` prop)
262281 TextInput({
263282 value: text,
264283 onChange: handleChange,
@@ -274,6 +293,17 @@ TextInput({
274293 });
275294 ```
276295
296+### Style inheritance
297+
298+Containers propagate styles to descendants. Explicit props always win:
299+
300+```ts
301+VStack({ fgColor: "white", bgColor: "blue" }, [
302+ Text("inherits white on blue"),
303+ Text("explicit green on blue", { fgColor: "green" }),
304+]);
305+```
306+
277307 ## Key Format
278308
279309 All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`, `"enter"`, `"alt+up"`, `"f1"`. Framework normalizes modifier order.
@@ -283,7 +313,9 @@ All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`
283313 - **State is external** — framework has no state. Call `cel.render()` after changes.
284314 - **Text is a leaf** — no sizing props, no children. Parent controls the box.
285315 - **TextInput is a container** — accepts sizing props but no children.
286-- **No style inheritance** — every node sets its own styles explicitly.
316+- **Style inheritance** — containers propagate styles (fgColor, bgColor, bold, etc.) to descendants. Explicit props on a node always override. Container `bgColor` fills the rect with opaque background.
317+- **focusStyle** — `focusStyle: { bgColor, fgColor, ... }` on containers overrides styles when focused. Participates in inheritance.
318+- **Uncontrolled focus by default** — Tab/Shift+Tab/Escape/click just work. Provide `focused` prop to opt into controlled mode.
287319 - **Escape unfocuses** the current element.
288320 - **Tab/Shift+Tab** traverses focusable elements in document order (wraps around). After Escape, traversal continues from the element that lost focus (not from the start).
289321 - **Enter** activates a focused clickable container (fires onClick).