xonecas.io
70160
Ce

cel-tui / commit 4d22a4c

docs: add key forwarding TODO and component composition guide to skill

- TODO: onKeyPress bubbling through component boundaries — innermost
  handler swallows all keys, forcing manual forwarding in stateful
  components. Propose return-value convention for the framework.
- SKILL: add Select component usage examples (basic + rich items)
- SKILL: add Composing Components section with stateless (simple
  function) and stateful (factory pattern) patterns, including
  key forwarding guidance and cel.render() usage from components.

xonecas2026-04-04 4d22a4c020dd1d5e8f29beca8a8c34a8474a5862 parent 0c44ffa

2 files changed

TODO.md+2−0
@@ -18,6 +18,8 @@ Remaining work, known bugs, and planned improvements.
1818
1919 - ❌ **`VDivider` component** — Drawing a vertical divider requires `VStack({ width: 1, height: "100%" }, [Text("│", { repeat: "fill" })])`. A `VDivider({ char, fgColor })` component would match the existing horizontal `Divider` and reduce boilerplate.
2020
21+- ❌ **`onKeyPress` bubbling through component boundaries** — `findKeyPressHandler` returns the innermost handler and stops. Unhandled keys don't bubble to parent `onKeyPress` handlers. This means every stateful component with `onKeyPress` needs to manually forward unrecognized keys (e.g., `Select` accepts an `onKeyPress` prop and calls it for keys it doesn't consume). A framework-level fix — such as a "return false to keep bubbling" convention or a `consumed` return value from handlers — …
22+
2123 ## Not Yet Implemented
2224
2325 - ❌ Alt key combos (`alt+x`) — `parseKey` doesn't handle ESC-prefixed sequences as alt modifiers. The spec lists `"alt+up"` as a valid key format.
docs/skill/cel-tui/SKILL.md+159−1
@@ -328,7 +328,7 @@ All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`
328328 ## Pre-made Components
329329
330330 ```ts
331-import { Spacer, Divider, Button } from "@cel-tui/components";
331+import { Spacer, Divider, Button, Select } from "@cel-tui/components";
332332
333333 Spacer(); // VStack({ flex: 1 }, [])
334334 Divider(); // Text("─", { repeat: "fill" })
@@ -337,4 +337,162 @@ Button("[OK]", { onClick: handleOk });
337337 Button("✕", { onClick: handleClose, focusable: false });
338338 ```
339339
340+### Select (filterable list)
341+
342+```ts
343+import { Select } from "@cel-tui/components";
344+
345+const mySelect = Select({
346+ items: ["apple", "banana", "cherry"],
347+ onSelect: (value) => {
348+ chosen = value;
349+ cel.render();
350+ },
351+ placeholder: "search fruits...",
352+ maxVisible: 8,
353+ onKeyPress: (key) => {
354+ // Receives keys the Select doesn't handle (modifiers, etc.)
355+ if (key === "ctrl+q") {
356+ cel.stop();
357+ process.exit();
358+ }
359+ },
360+});
361+
362+// Inside cel.viewport — call each render to get the current node tree
363+cel.viewport(() =>
364+ VStack({ height: "100%" }, [Text("Pick a fruit:"), mySelect()]),
365+);
366+
367+// Reset state programmatically
368+mySelect.reset();
369+```
370+
371+Rich items with separate display label, return value, and filter text:
372+
373+```ts
374+const modelSelect = Select({
375+ items: [
376+ {
377+ label: "claude-sonnet-4 (free)",
378+ value: "anthropic/claude-sonnet-4",
379+ filterText: "claude-sonnet-4",
380+ },
381+ { label: "gpt-4o", value: "openai/gpt-4o", filterText: "gpt-4o" },
382+ ],
383+ onSelect: (value) => {
384+ model = value;
385+ cel.render();
386+ },
387+});
388+```
389+
390+## Composing Components
391+
392+cel-tui components are plain functions that return `Node` trees. There are two patterns depending on whether the component needs internal state.
393+
394+### Stateless components
395+
396+Stateless components are simple functions that take props and return a `Node`. They're called every render cycle inside `cel.viewport()`. All existing state is external — passed in as props.
397+
398+```ts
399+import type { ContainerNode } from "@cel-tui/types";
400+import { HStack, Text } from "@cel-tui/core";
401+
402+function StatusBar(left: string, right: string): ContainerNode {
403+ return HStack({ fgColor: "black", bgColor: "white" }, [
404+ Text(` ${left}`),
405+ VStack({ flex: 1 }, []), // spacer
406+ Text(`${right} `),
407+ ]);
408+}
409+
410+// Usage — called fresh each render
411+cel.viewport(() =>
412+ VStack({ height: "100%" }, [
413+ mainContent(),
414+ StatusBar(filename, `${lines} lines`),
415+ ]),
416+);
417+```
418+
419+This is the pattern used by `Button`, `Divider`, and `Spacer`. Prefer it whenever possible — it's simple, testable, and composable.
420+
421+### Stateful components (factory pattern)
422+
423+When a component needs internal state that persists across renders (e.g., a search query, cursor position, scroll offset), use a **factory function** that returns a callable instance. State lives in the closure. The user calls the instance each render to get a fresh `Node` tree.
424+
425+```ts
426+import type { ContainerNode, Color } from "@cel-tui/types";
427+import { cel, VStack, HStack, Text } from "@cel-tui/core";
428+
429+interface ToggleGroupProps {
430+ options: string[];
431+ onSelect: (value: string) => void;
432+ activeColor?: Color;
433+}
434+
435+interface ToggleGroupInstance {
436+ (): ContainerNode;
437+ reset(): void;
438+}
439+
440+function ToggleGroup(props: ToggleGroupProps): ToggleGroupInstance {
441+ const { options, onSelect, activeColor = "cyan" } = props;
442+ let activeIndex = 0;
443+
444+ function handleKey(key: string): void {
445+ if (key === "left" && activeIndex > 0) {
446+ activeIndex--;
447+ cel.render();
448+ } else if (key === "right" && activeIndex < options.length - 1) {
449+ activeIndex++;
450+ cel.render();
451+ } else if (key === "enter") {
452+ onSelect(options[activeIndex]!);
453+ }
454+ }
455+
456+ function render(): ContainerNode {
457+ return HStack(
458+ { focusable: true, onKeyPress: handleKey, gap: 1 },
459+ options.map((opt, i) =>
460+ Text(` ${opt} `, {
461+ fgColor: i === activeIndex ? "black" : undefined,
462+ bgColor: i === activeIndex ? activeColor : undefined,
463+ }),
464+ ),
465+ );
466+ }
467+
468+ render.reset = () => {
469+ activeIndex = 0;
470+ };
471+ return render as ToggleGroupInstance;
472+}
473+
474+// Usage — create once, call each render
475+const formatToggle = ToggleGroup({
476+ options: ["JSON", "YAML", "TOML"],
477+ onSelect: (fmt) => {
478+ format = fmt;
479+ cel.render();
480+ },
481+});
482+
483+cel.viewport(() =>
484+ VStack({ height: "100%" }, [Text("Output format:"), formatToggle()]),
485+);
486+```
487+
488+Key points:
489+
490+- **Create once** outside `cel.viewport()`. The closure captures mutable state.
491+- **Call each render** inside `cel.viewport()` — the function builds a fresh node tree from current state.
492+- **`cel.render()`** is importable from `@cel-tui/core` — stateful components call it after internal state changes to trigger re-renders.
493+- **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.
494+- **`.reset()`** or other methods — attach to the render function (functions are objects in JS) to expose imperative control.
495+
496+This is the pattern used by `Select` from `@cel-tui/components`.
497+
340498 For the full specification, see the [cel-tui spec](https://raw.githubusercontent.com/sacenox/cel-tui/main/spec.md).