xonecas.io
70160
Ce

cel-tui / commit 7d5bdfa

docs: update examples to use Button/VDivider, document tmux gotchas

- pet.ts: replace 5 manual HStack+Text button patterns with Button,
  replace manual VStack+Text vertical divider with VDivider
- simple-scroll.ts: use Divider and Spacer components
- TODO: document controlled-focus TextInput Tab-trapping bug
  (pet.ts create screen — user can never Tab past the TextInput)
- AGENTS.md: document that SGR mouse events via tmux send-keys -H
  are unreliable; add capture-pane color limitations

xonecas2026-04-04 7d5bdfab43a73073d6e052c42a9a8fe2e733d388 parent e551c70

4 files changed

AGENTS.md+22−1
@@ -129,10 +129,31 @@ send_key "ctrl+s" # Modifier combo
129129 send_key "shift+tab" # Reverse focus traversal
130130 ```
131131
132-**Limitations:** The helper lowercases all input, so uppercase letters aren't testable this way. Mouse events (SGR format) are unaffected — use `send-keys -H` with raw SGR hex as before.
132+**Limitations:** The helper lowercases all input, so uppercase letters aren't testable this way.
133133
134134 **Caveat:** tmux `send-keys -H` injects raw bytes one event at a time, but real terminals batch multiple mouse events into a single stdin chunk. Always verify mouse/scroll behavior in a real terminal, not just tmux.
135135
136+### Mouse Events Don't Work in tmux
137+
138+SGR mouse events (click, scroll) sent via `tmux send-keys -H` are **unreliable** and should not be used for testing. Even with correctly-formatted SGR press/release byte sequences and `mouse off` in tmux config, the injected bytes may not reach the application's stdin in a form the parser recognizes. This is a known tmux limitation with raw byte injection for mouse protocols.
139+
140+**Do not test mouse interactions (click, scroll) through tmux.** Use tmux only for:
141+
142+- Keyboard-driven testing via `send_key` helper
143+- Visual inspection of rendered output via `tmux capture-pane -p`
144+- Verifying layout, alignment, and text content
145+
146+Mouse and scroll behavior must be verified in a real interactive terminal.
147+
148+### tmux capture-pane Limitations
149+
150+`tmux capture-pane -p` captures **plain text only** — no colors or style attributes. This means:
151+
152+- You can verify text content, alignment, and layout structure
153+- You **cannot** verify `fgColor`, `bgColor`, `bold`, `focusStyle` changes, or any visual styling
154+
155+To inspect colors, use `tmux capture-pane -e -p` (includes escape sequences) or verify styling through unit tests against the cell buffer.
156+
136157 ## Spec
137158
138159 The `spec.md` file is the source of truth for all API design decisions. Always read it before making changes to core framework behavior.
TODO.md+2−0
@@ -14,6 +14,8 @@ Remaining work, known bugs, and planned improvements.
1414
1515 - 🔧 **TextInput cursor movement doesn't handle multi-codepoint graphemes** — `deleteBackward`/`deleteForward` in `text-edit.ts` operate on single string indices. For multi-codepoint characters (emoji ZWJ sequences, combining marks), this leaves the cursor mid-grapheme. `moveCursor` has the same issue.
1616
17+- 🔧 **Controlled-focus TextInput traps Tab traversal** — When a controlled-focus TextInput (`focused` prop provided) is the first focusable element, Tab from unfocused state always focuses it. Once focused, Tab is consumed as an editing key. Escape unfocuses it, but the next Tab re-focuses it again — the user can never Tab past it to reach subsequent focusable elements. Visible in `examples/pet.ts` on the create screen: the name TextInput prevents keyboard access to the Create Pet button. …
18+
1719 ---
1820
1921 ## API Improvements
examples/pet.ts+34−46
@@ -21,7 +21,7 @@ import {
2121 TextInput,
2222 ProcessTerminal,
2323 } from "@cel-tui/core";
24-import { Button, Divider, Spacer } from "@cel-tui/components";
24+import { Button, Divider, Spacer, VDivider } from "@cel-tui/components";
2525
2626 // ─── Pet Definitions ────────────────────────────────────────────
2727
@@ -536,14 +536,12 @@ function createView() {
536536
537537 // Create button — uncontrolled focus + focusStyle
538538 HStack({ justifyContent: "center" }, [
539- HStack(
540- {
541- onClick: startGame,
542- fgColor: "green",
543- focusStyle: { bgColor: "green", fgColor: "black" },
544- },
545- [Text(" Create Pet! ", { bold: true })],
546- ),
539+ Button(" Create Pet! ", {
540+ onClick: startGame,
541+ fgColor: "green",
542+ bold: true,
543+ focusStyle: { bgColor: "green", fgColor: "black" },
544+ }),
547545 ]),
548546
549547 // Hints
@@ -602,22 +600,18 @@ function mainView() {
602600 ),
603601 Text(""),
604602 HStack({ gap: 3 }, [
605- HStack(
606- {
607- onClick: feed,
608- fgColor: "yellow",
609- focusStyle: { bgColor: "yellow", fgColor: "black" },
610- },
611- [Text(" Feed ", { bold: true })],
612- ),
613- HStack(
614- {
615- onClick: petIt,
616- fgColor: "magenta",
617- focusStyle: { bgColor: "magenta", fgColor: "black" },
618- },
619- [Text(" Pet ", { bold: true })],
620- ),
603+ Button(" Feed ", {
604+ onClick: feed,
605+ fgColor: "yellow",
606+ bold: true,
607+ focusStyle: { bgColor: "yellow", fgColor: "black" },
608+ }),
609+ Button(" Pet ", {
610+ onClick: petIt,
611+ fgColor: "magenta",
612+ bold: true,
613+ focusStyle: { bgColor: "magenta", fgColor: "black" },
614+ }),
621615 ]),
622616 ],
623617 );
@@ -663,9 +657,7 @@ function mainView() {
663657 // Wide: sidebar | pet side-by-side
664658 HStack({ flex: 1 }, [
665659 statsPanel,
666- VStack({ width: 1, height: "100%" }, [
667- Text("│", { repeat: "fill", fgColor: "brightBlack" }),
668- ]),
660+ VDivider({ fgColor: "brightBlack" }),
669661 petPane,
670662 ]),
671663 ]),
@@ -811,25 +803,21 @@ function deadView() {
811803 }),
812804 Text(""),
813805 HStack({ gap: 3 }, [
814- HStack(
815- {
816- onClick: restart,
817- fgColor: "green",
818- focusStyle: { bgColor: "green", fgColor: "black" },
819- },
820- [Text(" New Pet ", { bold: true })],
821- ),
822- HStack(
823- {
824- onClick: () => {
825- showLog = !showLog;
826- cel.render();
827- },
828- fgColor: "cyan",
829- focusStyle: { bgColor: "cyan", fgColor: "black" },
806+ Button(" New Pet ", {
807+ onClick: restart,
808+ fgColor: "green",
809+ bold: true,
810+ focusStyle: { bgColor: "green", fgColor: "black" },
811+ }),
812+ Button(" View Log ", {
813+ onClick: () => {
814+ showLog = !showLog;
815+ cel.render();
830816 },
831- [Text(" View Log ", { bold: true })],
832- ),
817+ fgColor: "cyan",
818+ bold: true,
819+ focusStyle: { bgColor: "cyan", fgColor: "black" },
820+ }),
833821 ]),
834822 HStack({}, [
835823 Text("Ctrl+Q", { fgColor: "brightBlack", bold: true }),
examples/simple-scroll.ts+4−3
@@ -8,6 +8,7 @@
88 * Run: bun run examples/simple-scroll.ts
99 */
1010 import { cel, VStack, HStack, Text, ProcessTerminal } from "@cel-tui/core";
11+import { Divider, Spacer } from "@cel-tui/components";
1112
1213 const MIN_COLS = 30;
1314 const MIN_ROWS = 8;
@@ -88,10 +89,10 @@ cel.viewport(() => {
8889 [
8990 HStack({ padding: { x: 1 } }, [
9091 Text("Scroll Test", { bold: true, fgColor: "cyan" }),
91- VStack({ flex: 1 }, []),
92+ Spacer(),
9293 Text("uncontrolled", { fgColor: "brightBlack" }),
9394 ]),
94- Text("─", { repeat: "fill", fgColor: "brightBlack" }),
95+ Divider({ fgColor: "brightBlack" }),
9596
9697 VStack(
9798 { flex: 1, overflow: "scroll", scrollbar: true },
@@ -103,7 +104,7 @@ cel.viewport(() => {
103104 ),
104105 ),
105106
106- Text("─", { repeat: "fill", fgColor: "brightBlack" }),
107+ Divider({ fgColor: "brightBlack" }),
107108 HStack({ padding: { x: 1 } }, [
108109 Text("Mouse wheel to scroll · Ctrl+Q quit", {
109110 fgColor: "brightBlack",