xonecas.io
70160
Ce

cel-tui / commit 36bc1c0

docs: update all docs for onKeyPress bubbling changes

- AGENTS.md: rename findKeyPressHandler → collectKeyPressHandlers
- SKILL.md: fix gotcha about innermost handler — keys now bubble
  via return false convention. Update Select example to show
  root-level onKeyPress instead of manual forwarding.
- api.md: fix onKeyPress type to boolean | void. Update Select
  docs and example to show bubbling pattern.
- composing-components.md: replace manual forwarding guidance with
  return false bubbling pattern. Update ToggleGroup example.

xonecas2026-04-04 36bc1c0d95bf893a03a3fb38bfd5172318744c2a parent f5280a2

4 files changed

AGENTS.md+1−1
@@ -146,7 +146,7 @@ chore: scaffold monorepo with types, core, components packages
146146 - `layout.ts` — Flexbox engine. `layout(root, width, height)` → `LayoutNode` tree with absolute screen rects.
147147 - `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.
148148 - `emitter.ts` — `emitBuffer()` for full renders, `emitDiff()` for differential. Both wrap in CSI 2026 synchronized output.
149-- `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `findKeyPressHandler`, `collectFocusable` walk paths.
149+- `hit-test.ts` — `hitTest(root, x, y)` → path from root to deepest node. `findClickHandler`, `findScrollTarget`, `collectKeyPressHandlers`, `collectFocusable` walk paths.
150150 - `keys.ts` — `parseKey(data)` normalizes terminal input to canonical key strings. `isEditingKey()` identifies keys consumed by TextInput. `normalizeKey()` reorders modifiers to canonical `ctrl+alt+shift+<key>` order.
151151 - `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.
152152 - `width.ts` — `visibleWidth(str)` measures terminal column width. Fast ASCII path, grapheme segmentation, East Asian width, ANSI stripping, LRU cache.
docs/skill/cel-tui/SKILL.md+17−8
@@ -163,15 +163,24 @@ const mySelect = Select({
163163 chosen = value;
164164 cel.render();
165165 },
166- onKeyPress: (key) => {
167- if (key === "ctrl+q") {
168- cel.stop();
169- process.exit();
170- }
171- },
172166 });
173167
174-cel.viewport(() => VStack({ height: "100%" }, [mySelect()]));
168+// ctrl+q lives on the root — Select returns false for unrecognized
169+// keys, so they bubble up automatically.
170+cel.viewport(() =>
171+ VStack(
172+ {
173+ height: "100%",
174+ onKeyPress: (key) => {
175+ if (key === "ctrl+q") {
176+ cel.stop();
177+ process.exit();
178+ }
179+ },
180+ },
181+ [mySelect()],
182+ ),
183+);
175184 mySelect.reset(); // clear filter/highlight programmatically
176185 ```
177186
@@ -183,7 +192,7 @@ mySelect.reset(); // clear filter/highlight programmatically
183192 - **Escape unfocuses** the current element. Tab/Shift+Tab traverses focusable elements (wraps around). After Escape, traversal continues from where focus was lost.
184193 - **Enter activates** a focused container's `onClick`. If no `onClick`, Enter reaches `onKeyPress`.
185194 - **`focusable: true`** without `onClick` makes a container keyboard-focusable (receives `onKeyPress` events via Tab). Used by stateful components like `Select`.
186-- **Innermost handler wins** — for `onClick`, `onScroll`, and `onKeyPress`. Unhandled keys in a component's `onKeyPress` don't automatically bubble to parent handlers — forward them manually via an `onKeyPress` prop.
195+- **Innermost handler wins** — for `onClick` and `onScroll`. For `onKeyPress`, keys **bubble up** through ancestors: return `false` from a handler to let the key continue to the next ancestor. Returning `void`/`undefined` consumes the key (stops bubbling). This is backward-compatible.
187196 - **Container `bgColor`** fills the rect with opaque background before painting children.
188197 - **`repeat: "fill"` in HStack** gets width 0 (intrinsic width is 0). Workaround: wrap in `VStack({ flex: 1 }, [Text(" ", { repeat: "fill" })])`.
189198 - **Crash cleanup** — terminal state is restored on SIGINT, SIGTERM, uncaughtException.
docs/skill/cel-tui/references/api.md+15−11
@@ -31,7 +31,7 @@ All props accepted by `VStack` and `HStack`:
3131 focused, // boolean (controlled — omit for uncontrolled)
3232 onFocus, // () => void
3333 onBlur, // () => void
34- onKeyPress, // (key: string) => void
34+ onKeyPress, // (key: string) => boolean | void — return false to keep bubbling
3535 }
3636 ```
3737
@@ -102,7 +102,7 @@ Button("✕", { onClick: handleClose, focusable: false });
102102
103103 ### Select (filterable list)
104104
105-Select props: `items`, `onSelect`, `placeholder` (default `"type to filter..."`), `maxVisible` (default `10`), `indicator` (default `"›"`), `highlightColor` (default `"cyan"`), `onKeyPress` (receives unhandled keys), plus container/style props: `width`, `height`, `flex`, `fgColor`, `bgColor`, `focused`, `focusable`, `onFocus`, `onBlur`, `focusStyle`.
105+Select props: `items`, `onSelect`, `placeholder` (default `"type to filter..."`), `maxVisible` (default `10`), `indicator` (default `"›"`), `highlightColor` (default `"cyan"`), `onKeyPress` (composed with internal handler), plus container/style props: `width`, `height`, `flex`, `fgColor`, `bgColor`, `focused`, `focusable`, `onFocus`, `onBlur`, `focusStyle`.
106106
107107 ```ts
108108 const mySelect = Select({
@@ -113,18 +113,22 @@ const mySelect = Select({
113113 },
114114 placeholder: "search fruits...",
115115 maxVisible: 8,
116- onKeyPress: (key) => {
117- // Receives keys the Select doesn't handle (modifiers, etc.)
118- if (key === "ctrl+q") {
119- cel.stop();
120- process.exit();
121- }
122- },
123116 });
124117
125-// Inside cel.viewport — call each render to get the current node tree
118+// Select returns false for unrecognized keys, so they bubble to root.
126119 cel.viewport(() =>
127- VStack({ height: "100%" }, [Text("Pick a fruit:"), mySelect()]),
120+ VStack(
121+ {
122+ height: "100%",
123+ onKeyPress: (key) => {
124+ if (key === "ctrl+q") {
125+ cel.stop();
126+ process.exit();
127+ }
128+ },
129+ },
130+ [Text("Pick a fruit:"), mySelect()],
131+ ),
128132 );
129133
130134 // Reset state programmatically
docs/skill/cel-tui/references/composing-components.md+4−2
@@ -52,7 +52,7 @@ function ToggleGroup(props: ToggleGroupProps): ToggleGroupInstance {
5252 const { options, onSelect, activeColor = "cyan" } = props;
5353 let activeIndex = 0;
5454
55- function handleKey(key: string): void {
55+ function handleKey(key: string): boolean | void {
5656 if (key === "left" && activeIndex > 0) {
5757 activeIndex--;
5858 cel.render();
@@ -61,6 +61,8 @@ function ToggleGroup(props: ToggleGroupProps): ToggleGroupInstance {
6161 cel.render();
6262 } else if (key === "enter") {
6363 onSelect(options[activeIndex]!);
64+ } else {
65+ return false; // unrecognized key — let it bubble to ancestors
6466 }
6567 }
6668
@@ -101,7 +103,7 @@ cel.viewport(() =>
101103 - **Create once** outside `cel.viewport()`. The closure captures mutable state.
102104 - **Call each render** inside `cel.viewport()` — the function builds a fresh node tree from current state.
103105 - **`cel.render()`** is importable from `@cel-tui/core` — stateful components call it after internal state changes to trigger re-renders.
104-- **Key forwarding** — `findKeyPressHandler` returns the innermost handler and stops. If your component uses `onKeyPress`, accept an `onKeyPress` prop from the user and call it for keys you don't handle, so parent shortcuts still work.
106+- **Key bubbling** — `onKeyPress` handlers bubble from innermost to root. Return `false` from a handler to signal the key was not consumed and let it continue to the next ancestor. Return `void`/`undefined` to consume (backward-compatible). Components like `Select` return `false` for unrecognized keys, so app-level shortcuts on parent containers work automatically.
105107 - **`.reset()`** or other methods — attach to the render function (functions are objects in JS) to expose imperative control.
106108
107109 This is the pattern used by `Select` from `@cel-tui/components`.