xonecas.io
70160
Ce

cel-tui / commit 85f87ef

docs: add uncontrolled scroll documentation to SKILL.md and api.md

The scrollable list pattern in SKILL.md now shows both uncontrolled
(default, framework-managed) and controlled (app-owned) modes.

api.md gains a new Scroll section explaining both modes, scroll
direction, pointer-driven behavior, and controlled mode semantics.

Removes the documentation gap entry from TODO.md.

xonecas2026-04-04 85f87efce4e9ebe285766a648f8cb62b4cce117b parent 645d1ca

3 files changed

TODO.md+0βˆ’6
@@ -33,9 +33,3 @@ Remaining work, known bugs, and planned improvements.
3333 - πŸ’‘ Additional example apps (chat UI, text editor from spec reference examples)
3434 - πŸ’‘ `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)
3535 - πŸ’‘ Higher Kitty protocol levels β€” key-release events (level 2), associated text (level 3), and full event types (level 4) for advanced input patterns (games, physical key layout awareness)
36-
37----
38-
39-## Documentation Gaps
40-
41-- ❌ **No docs for uncontrolled scroll** β€” All examples/docs use controlled scroll (`scrollOffset` + `onScroll`). The spec's uncontrolled pattern should be shown in SKILL.md and api.md.
docs/skill/cel-tui/SKILL.md+23βˆ’0
@@ -95,10 +95,33 @@ HStack(
9595
9696 ### Scrollable list
9797
98+Scroll is **uncontrolled by default** β€” the framework manages scroll position internally. Mouse wheel just works:
99+
98100 ```ts
99101 VStack({ overflow: "scroll", scrollbar: true }, [...items]);
100102 ```
101103
104+Provide `scrollOffset` + `onScroll` to opt into **controlled mode** β€” you own the state:
105+
106+```ts
107+let offset = 0;
108+
109+VStack(
110+ {
111+ overflow: "scroll",
112+ scrollbar: true,
113+ scrollOffset: offset,
114+ onScroll: (newOffset) => {
115+ offset = newOffset;
116+ cel.render();
117+ },
118+ },
119+ [...items],
120+);
121+```
122+
123+Controlled mode enables patterns like auto-scroll to bottom on new content.
124+
102125 ### Layers (modals)
103126
104127 Return an array from the render function β€” layers composite bottom-to-top:
docs/skill/cel-tui/references/api.md+27βˆ’0
@@ -35,6 +35,33 @@ All props accepted by `VStack` and `HStack`:
3535 }
3636 ```
3737
38+## Scroll
39+
40+Scroll supports **uncontrolled** (default) and **controlled** modes, mirroring the focus model:
41+
42+```ts
43+// Uncontrolled β€” framework manages scroll position. Mouse wheel just works.
44+VStack({ overflow: "scroll", scrollbar: true }, [...items]);
45+
46+// Controlled β€” app owns scroll state.
47+VStack(
48+ {
49+ overflow: "scroll",
50+ scrollbar: true,
51+ scrollOffset: offset,
52+ onScroll: (newOffset) => {
53+ offset = newOffset;
54+ cel.render();
55+ },
56+ },
57+ [...items],
58+);
59+```
60+
61+- Scroll direction follows the container’s main axis: VStack β†’ vertical, HStack β†’ horizontal.
62+- Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
63+- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset.
64+
3865 ## Text Props
3966
4067 ```ts