xonecas.io
70160
Ce

cel-tui / commit 02425a6

feat: add return false to propagate scroll events

xonecas2026-04-26 02425a60e9ac132c5c7c2a461053e569b400c450 parent 700e738

9 files changed

AGENTS.md+1−1
@@ -31,7 +31,7 @@ Dependency graph: `core → types`, `components → core`, `components → types
3131 - **Reactive rendering:** `cel.render()` batches via `process.nextTick()`. No fixed FPS.
3232 - **Layers:** `cel.viewport(() => [layer1, layer2])` — array of independent viewport-sized trees, composited bottom-to-top. Conditional inclusion = show/hide.
3333 - **Key bubbling:** Unconsumed keys bubble up from focused element through ancestors. Root `onKeyPress` = global handler. Escape blur is a fallback default action after bubbling — consuming `escape` prevents blur.
34-- **Hit detection:** Topmost layer first, deepest node at (x,y), walk up to find handler. Innermost wins for scroll, click, keys.
34+- **Hit detection:** Topmost layer first, deepest node at (x,y), walk up to find handler. Scroll targets propagate innermost-first when a container `onScroll` returns exactly `false`; TextInput consumes wheel input directly. Click uses the nearest handler; key bubbling is focused-element based.
3535
3636 ## Implementation Status
3737
docs/skill/cel-tui/SKILL.md+1−1
@@ -273,7 +273,7 @@ SyntaxHighlight(source, "javascript", { theme: "dark-plus" });
273273 - **Escape unfocuses** the current element. Tab/Shift+Tab traverses focusable elements (wraps around). After Escape, traversal continues from where focus was lost.
274274 - **Enter activates** a focused container's `onClick`. If no `onClick`, Enter reaches `onKeyPress`.
275275 - **`focusable: true`** without `onClick` makes a container keyboard-focusable (receives `onKeyPress` events via Tab). Used by stateful components like `Select`.
276-- **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.
276+- **Innermost handler wins** — for `onClick`. For `onScroll`, scrollable containers are tried innermost-first; return exactly `false` to continue to the next scrollable ancestor, while `void`/`undefined` consumes the scroll. TextInput consumes wheel input directly. 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.
277277 - **Mouse wheel step is adaptive by default** — scrollable containers and `TextInput` use `floor(viewportMainAxis / 3)`, clamped to `3..8`. Set `scrollStep` to override it for a specific view.
278278 - **Container `bgColor`** fills the rect with opaque background before painting children. Always pair `bgColor` with `fgColor` for contrast — terminal default fg is designed for the terminal default bg, not for arbitrary palette backgrounds.
279279 - **Colors are numbered slots** (`"color00"`–`"color15"`), not names. The default theme maps to ANSI 16. Omit `fgColor`/`bgColor` for terminal defaults (guaranteed readable across themes).
docs/skill/cel-tui/references/api.md+2−2
@@ -34,7 +34,7 @@ All props accepted by `VStack` and `HStack`:
3434 scrollbar, // boolean
3535 scrollStep, // number (mouse wheel step in cells; default adaptive)
3636 scrollOffset, // number (controlled scroll)
37- onScroll, // (offset: number, maxOffset: number) => void
37+ onScroll, // ScrollHandler; return false to keep bubbling
3838 flexWrap, // "nowrap" (default) | "wrap" (HStack only)
3939
4040 // Styling (inherited by descendants)
@@ -101,7 +101,7 @@ VStack(
101101 - Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
102102 - Mouse wheel scrolling uses an adaptive default step based on the scroll target's visible main-axis viewport size: `floor(viewportMainAxis / 3)`, clamped to `3..8`.
103103 - Set `scrollStep` to override the mouse wheel step for a specific scrollable or `TextInput`.
104-- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset and the maximum offset (content size minus viewport size). Pass `Infinity` as `scrollOffset` to mean "scroll to end" (clamped during rendering and hit testing). `scrollStep` affects mouse wheel input only.
104+- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset and the maximum offset (content size minus viewport size). Return exactly `false` to decline handling and continue to the next scrollable ancestor; any other return value consumes the scroll. Pass `Infinity` as `scrollOffset` to mean "scroll to end" (clamped during rendering and hit testing). `scrollStep` affects mouse wheel input only.
105105
106106 ## Text Props
107107
packages/core/src/cel.test.ts+131−0
@@ -324,6 +324,137 @@ describe("cel end-to-end", () => {
324324 expect(scrollOffset).toBe(12);
325325 });
326326
327+ test("inner onScroll returning false propagates wheel input to parent", async () => {
328+ const term = setup(20, 12);
329+ let outerOffset = 0;
330+ const innerOffsets: number[] = [];
331+ const outerOffsets: number[] = [];
332+
333+ cel.viewport(() =>
334+ VStack(
335+ {
336+ width: 20,
337+ height: 12,
338+ overflow: "scroll",
339+ scrollOffset: outerOffset,
340+ onScroll: (offset) => {
341+ outerOffset = offset;
342+ outerOffsets.push(offset);
343+ },
344+ },
345+ [
346+ VStack(
347+ {
348+ height: 6,
349+ overflow: "scroll",
350+ scrollOffset: 0,
351+ onScroll: (offset) => {
352+ innerOffsets.push(offset);
353+ return false;
354+ },
355+ },
356+ Array.from({ length: 10 }, (_, i) => Text(`inner ${i + 1}`)),
357+ ),
358+ ...Array.from({ length: 20 }, (_, i) => Text(`outer ${i + 1}`)),
359+ ],
360+ ),
361+ );
362+ await waitForRender();
363+
364+ term.sendInput("\x1b[<65;4;3M");
365+ await waitForRender();
366+
367+ expect(innerOffsets).toEqual([3]);
368+ expect(outerOffsets).toEqual([4]);
369+ expect(outerOffset).toBe(4);
370+ });
371+
372+ test("void inner onScroll consumes wheel input and does not notify parent", async () => {
373+ const term = setup(20, 12);
374+ let innerOffset = 0;
375+ let parentCalled = false;
376+
377+ cel.viewport(() =>
378+ VStack(
379+ {
380+ width: 20,
381+ height: 12,
382+ overflow: "scroll",
383+ scrollOffset: 0,
384+ onScroll: () => {
385+ parentCalled = true;
386+ },
387+ },
388+ [
389+ VStack(
390+ {
391+ height: 6,
392+ overflow: "scroll",
393+ scrollOffset: innerOffset,
394+ onScroll: (offset) => {
395+ innerOffset = offset;
396+ },
397+ },
398+ Array.from({ length: 10 }, (_, i) => Text(`inner ${i + 1}`)),
399+ ),
400+ ...Array.from({ length: 20 }, (_, i) => Text(`outer ${i + 1}`)),
401+ ],
402+ ),
403+ );
404+ await waitForRender();
405+
406+ term.sendInput("\x1b[<65;4;3M");
407+ await waitForRender();
408+
409+ expect(innerOffset).toBe(3);
410+ expect(parentCalled).toBe(false);
411+ });
412+
413+ test("batched propagated scrolls skip the declined inner accumulator", async () => {
414+ const term = setup(20, 12);
415+ let outerOffset = 0;
416+ const innerOffsets: number[] = [];
417+ const outerOffsets: number[] = [];
418+
419+ cel.viewport(() =>
420+ VStack(
421+ {
422+ width: 20,
423+ height: 12,
424+ overflow: "scroll",
425+ scrollOffset: outerOffset,
426+ onScroll: (offset) => {
427+ outerOffset = offset;
428+ outerOffsets.push(offset);
429+ },
430+ },
431+ [
432+ VStack(
433+ {
434+ height: 6,
435+ overflow: "scroll",
436+ scrollOffset: 0,
437+ onScroll: (offset) => {
438+ innerOffsets.push(offset);
439+ return false;
440+ },
441+ },
442+ Array.from({ length: 10 }, (_, i) => Text(`inner ${i + 1}`)),
443+ ),
444+ ...Array.from({ length: 20 }, (_, i) => Text(`outer ${i + 1}`)),
445+ ],
446+ ),
447+ );
448+ await waitForRender();
449+
450+ term.sendInput("\x1b[<65;4;3M\x1b[<65;4;3M");
451+ await waitForRender();
452+
453+ expect(innerOffsets).toEqual([3, 3]);
454+ expect(outerOffsets).toEqual([4, 8]);
455+ expect(outerOffset).toBe(8);
456+ });
457+
327458 test("scroll clamps at max offset (no blank space past content)", async () => {
328459 const term = setup(20, 5);
329460 let scrollOffset = 0;
packages/core/src/cel.ts+37−37
@@ -10,8 +10,8 @@ import { defaultTheme, emitBuffer, emitDiff } from "./emitter.js";
1010 import {
1111 collectFocusable,
1212 collectKeyPressHandlers,
13+ collectScrollTargets,
1314 findClickHandler,
14- findScrollTarget,
1515 hitTest,
1616 } from "./hit-test.js";
1717 import { decodeKeyEvents, isEditingKey, type KeyInput } from "./keys.js";
@@ -725,55 +725,55 @@ function handleMouseEvent(event: MouseEvent): void {
725725 }
726726
727727 if (event.type === "scroll-up" || event.type === "scroll-down") {
728- const target = findScrollTarget(path);
729- if (target) {
728+ const targets = collectScrollTargets(path);
729+ for (const target of targets) {
730730 const step = getScrollStep(target);
731731 const delta = event.type === "scroll-up" ? -step : step;
732732 const maxOffset = getMaxScrollOffset(target);
733733
734734 if (target.node.type === "textinput") {
735- // TextInput scroll is always framework-managed
735+ // TextInput scroll is always framework-managed and consumes wheel input.
736736 const tiProps = target.node.props;
737737 const current = getTextInputScroll(tiProps);
738738 const clamped = Math.max(0, Math.min(maxOffset, current + delta));
739739 setTextInputScroll(tiProps, clamped);
740740 cel.render();
741- } else if (
742- target.node.type === "vstack" ||
743- target.node.type === "hstack"
744- ) {
741+ return;
742+ }
743+
744+ if (target.node.type === "vstack" || target.node.type === "hstack") {
745745 const props = target.node.props;
746- if (props.overflow === "scroll") {
747- if (props.onScroll) {
748- // Controlled scroll: notify app.
749- // Use batch accumulator if available (multiple events in one chunk),
750- // otherwise read from props. Clamp to maxOffset first so that
751- // Infinity (sticky-bottom) resolves to a finite value before
752- // applying the delta — otherwise Infinity + (-1) = Infinity
753- // and scrolling up never unsticks.
754- const rawBase =
755- batchScrollOffsets?.get(props) ?? props.scrollOffset ?? 0;
756- const baseOffset = Math.min(rawBase, maxOffset);
757- const newOffset = Math.max(
758- 0,
759- Math.min(maxOffset, baseOffset + delta),
760- );
761- batchScrollOffsets?.set(props, newOffset);
762- props.onScroll(newOffset, maxOffset);
763- } else {
764- // Uncontrolled scroll: framework manages state via path key
765- const pathKey = getScrollPathKey(target);
766- if (pathKey !== null) {
767- const current = uncontrolledScrollOffsets.get(pathKey) ?? 0;
768- const clamped = Math.max(
769- 0,
770- Math.min(maxOffset, current + delta),
771- );
772- uncontrolledScrollOffsets.set(pathKey, clamped);
773- }
746+ if (props.overflow !== "scroll") continue;
747+
748+ if (props.onScroll) {
749+ // Controlled scroll: notify app.
750+ // Use batch accumulator if available (multiple events in one chunk),
751+ // otherwise read from props. Clamp to maxOffset first so that
752+ // Infinity (sticky-bottom) resolves to a finite value before
753+ // applying the delta — otherwise Infinity + (-1) = Infinity
754+ // and scrolling up never unsticks.
755+ const rawBase =
756+ batchScrollOffsets?.get(props) ?? props.scrollOffset ?? 0;
757+ const baseOffset = Math.min(rawBase, maxOffset);
758+ const newOffset = Math.max(
759+ 0,
760+ Math.min(maxOffset, baseOffset + delta),
761+ );
762+ const result = props.onScroll(newOffset, maxOffset);
763+ if (result === false) continue;
764+ batchScrollOffsets?.set(props, newOffset);
765+ } else {
766+ // Uncontrolled scroll: framework manages state via path key and consumes.
767+ const pathKey = getScrollPathKey(target);
768+ if (pathKey !== null) {
769+ const current = uncontrolledScrollOffsets.get(pathKey) ?? 0;
770+ const clamped = Math.max(0, Math.min(maxOffset, current + delta));
771+ uncontrolledScrollOffsets.set(pathKey, clamped);
774772 }
775- cel.render();
776773 }
774+
775+ cel.render();
776+ return;
777777 }
778778 }
779779 return;
packages/core/src/hit-test.test.ts+27−1
@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
22 import {
33 collectFocusable,
44 collectKeyPressHandlers,
5+ collectScrollTargets,
56 findClickHandler,
67 findScrollTarget,
78 hitTest,
@@ -230,7 +231,7 @@ describe("findScrollTarget", () => {
230231 expect(findScrollTarget(path)).toBeNull();
231232 });
232233
233- test("innermost scrollable wins", () => {
234+ test("findScrollTarget returns the innermost scrollable", () => {
234235 const node = VStack({ width: 20, height: 10, overflow: "scroll" }, [
235236 VStack({ height: 5, overflow: "scroll" }, [Text("inner")]),
236237 ]);
@@ -245,6 +246,31 @@ describe("findScrollTarget", () => {
245246 });
246247 });
247248
249+describe("collectScrollTargets", () => {
250+ test("collects scrollable ancestors from innermost to outermost", () => {
251+ const node = VStack({ width: 20, height: 10, overflow: "scroll" }, [
252+ VStack({ height: 6 }, [
253+ VStack({ height: 4, overflow: "scroll" }, [Text("inner")]),
254+ ]),
255+ ]);
256+ const ln = layout(node, 20, 10);
257+ const path = hitTest(ln, 3, 0);
258+ const targets = collectScrollTargets(path);
259+
260+ expect(targets).toHaveLength(2);
261+ const inner = item(targets, 0);
262+ const outer = item(targets, 1);
263+ expect(inner.node.type).toBe("vstack");
264+ expect(outer.node.type).toBe("vstack");
265+ if (inner.node.type === "vstack") {
266+ expect(inner.node.props.height).toBe(4);
267+ }
268+ if (outer.node.type === "vstack") {
269+ expect(outer.node.props.height).toBe(10);
270+ }
271+ });
272+});
273+
248274 describe("collectKeyPressHandlers", () => {
249275 test("collects handlers from deepest to root", () => {
250276 const rootHandler = (_key: string) => {};
packages/core/src/hit-test.ts+23−6
@@ -136,21 +136,38 @@ export function findClickHandler(
136136 }
137137
138138 /**
139- * Find the nearest scrollable ancestor (innermost wins).
139+ * Collect scrollable ancestors in bubbling order (innermost first).
140140 * Matches containers with `overflow: "scroll"` or TextInput nodes.
141141 *
142142 * @param path - Hit test path (root to deepest).
143- * @returns The scrollable layout node, or null.
143+ * @returns Scrollable layout nodes ordered deepest to root.
144144 */
145-export function findScrollTarget(path: LayoutNode[]): LayoutNode | null {
145+export function collectScrollTargets(path: LayoutNode[]): LayoutNode[] {
146+ const targets: LayoutNode[] = [];
146147 for (let i = path.length - 1; i >= 0; i--) {
147148 const layoutNode = requiredAt(path, i, "hit path node");
148149 const node = layoutNode.node;
149- if (node.type === "textinput") return layoutNode;
150+ if (node.type === "textinput") {
151+ targets.push(layoutNode);
152+ continue;
153+ }
150154 const props = getProps(layoutNode);
151- if (props?.overflow === "scroll") return layoutNode;
155+ if (props?.overflow === "scroll") targets.push(layoutNode);
152156 }
153- return null;
157+ return targets;
158+}
159+
160+/**
161+ * Find the nearest scrollable ancestor.
162+ *
163+ * For full scroll dispatch, prefer {@link collectScrollTargets} so container
164+ * handlers can propagate by returning `false`. TextInput consumes directly.
165+ *
166+ * @param path - Hit test path (root to deepest).
167+ * @returns The innermost scrollable layout node, or null.
168+ */
169+export function findScrollTarget(path: LayoutNode[]): LayoutNode | null {
170+ return collectScrollTargets(path)[0] ?? null;
154171 }
155172
156173 /**
packages/types/src/index.ts+22−1
@@ -100,6 +100,22 @@ export type SizeValue = number | `${number}%`;
100100 // biome-ignore lint/suspicious/noConfusingVoidType: public callback contract intentionally accepts void-returning handlers.
101101 export type KeyPressHandler = (key: string) => boolean | void;
102102
103+/**
104+ * Scroll notification callback for controlled scroll containers.
105+ *
106+ * Return exactly `false` to decline handling and continue scroll propagation
107+ * to the next scrollable ancestor. Any other return value, including
108+ * `undefined`, consumes the scroll event.
109+ *
110+ * This is a union of `void`-returning and `boolean`-returning callback
111+ * signatures instead of a single `boolean | void` return type so legacy
112+ * expression-bodied void handlers remain source-compatible even when they
113+ * incidentally return another value.
114+ */
115+export type ScrollHandler =
116+ | ((offset: number, maxOffset: number) => void)
117+ | ((offset: number, maxOffset: number) => boolean);
118+
103119 /** Why a focus change callback fired. */
104120 export type FocusChangeReason = "tab" | "shift+tab" | "click" | "escape";
105121
@@ -216,10 +232,15 @@ export interface ContainerProps extends StyleProps {
216232 * In controlled mode, update {@link scrollOffset} with the new value
217233 * to move the scroll position.
218234 *
235+ * Return `false` to decline handling and continue scroll propagation
236+ * to the next scrollable ancestor. Any other return value consumes the
237+ * scroll event and stops propagation.
238+ *
219239 * @param offset - The new scroll offset in cells.
220240 * @param maxOffset - The maximum scroll offset (content size minus viewport size).
241+ * @returns `false` to keep bubbling, anything else to consume.
221242 */
222- onScroll?: (offset: number, maxOffset: number) => void;
243+ onScroll?: ScrollHandler;
223244
224245 /**
225246 * Called on mouse click or Enter key when this container is focused.
spec.md+42−36
@@ -61,14 +61,14 @@ This helper is for **content subtrees** whose height is not externally constrain
6161
6262 ### Systems
6363
64-| System | Description |
65-| -------------------------- | --------------------------------------------------------- |
66-| Flexbox layout engine | Sizing, alignment, gap |
67-| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar |
68-| Layering | Multiple viewport layers, composited bottom-to-top |
69-| Mouse/scroll hit detection | Pointer-driven, topmost layer first, innermost node wins |
70-| Focus management | Keyboard-driven, for `TextInput` and clickable containers |
71-| Keyboard input | Kitty-first input with tmux/legacy compatibility |
64+| System | Description |
65+| -------------------------- | ------------------------------------------------------------ |
66+| Flexbox layout engine | Sizing, alignment, gap |
67+| Overflow & scrolling | `overflow: "hidden" \| "scroll"`, scrollbar |
68+| Layering | Multiple viewport layers, composited bottom-to-top |
69+| Mouse/scroll hit detection | Pointer-driven, topmost layer first, innermost-first routing |
70+| Focus management | Keyboard-driven, for `TextInput` and clickable containers |
71+| Keyboard input | Kitty-first input with tmux/legacy compatibility |
7272
7373 ---
7474
@@ -94,32 +94,34 @@ HStack(props, children);
9494
9595 Shared by both VStack and HStack. Containers also accept styling props (see [Styling](#styling)).
9696
97-| Prop | Type | Description |
98-| ---------------- | -------------------------------------------------------------------------- | --------------------------------------------------- |
99-| `width` | `number \| string` | Fixed cells or percentage (`"50%"`) |
100-| `height` | `number \| string` | Fixed cells or percentage (`"100%"`) |
101-| `flex` | `number` | Flex grow factor, proportional to siblings |
102-| `minWidth` | `number` | Minimum width constraint |
103-| `maxWidth` | `number` | Maximum width constraint |
104-| `minHeight` | `number` | Minimum height constraint |
105-| `maxHeight` | `number` | Maximum height constraint |
106-| `padding` | `{ x?: number, y?: number }` | Internal padding (cells) |
107-| `gap` | `number` | Spacing between children (cells) |
108-| `justifyContent` | `string` | Distribute children along the main axis |
109-| `alignItems` | `string` | Align children along the cross axis |
110-| `flexWrap` | `"nowrap" \| "wrap"` | Wrap children to next line (HStack only) |
111-| `overflow` | `"hidden" \| "scroll"` | Content overflow behavior (default: `"hidden"`) |
112-| `scrollbar` | `boolean` | Show scrollbar indicator |
113-| `scrollStep` | `number` | Mouse wheel step in cells (default: adaptive) |
114-| `scrollOffset` | `number` | Scroll position in cells (controlled) |
115-| `onScroll` | `(offset: number, maxOffset: number) => void` | Called on scroll input |
116-| `onClick` | `() => void` | Called on mouse click or Enter when focused |
117-| `focusable` | `boolean` | Opt out of focus (default: `true` if `onClick`) |
118-| `focused` | `boolean` | Whether this element is focused (controlled) |
119-| `onFocus` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element receives focus |
120-| `onBlur` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element loses focus |
121-| `focusStyle` | `StyleProps` | Style overrides applied when focused |
122-| `onKeyPress` | `(key: string) => boolean \| void` | Key event handler. Return `false` to keep bubbling. |
97+| Prop | Type | Description |
98+| ---------------- | -------------------------------------------------------------------------- | -------------------------------------------------------- |
99+| `width` | `number \| string` | Fixed cells or percentage (`"50%"`) |
100+| `height` | `number \| string` | Fixed cells or percentage (`"100%"`) |
101+| `flex` | `number` | Flex grow factor, proportional to siblings |
102+| `minWidth` | `number` | Minimum width constraint |
103+| `maxWidth` | `number` | Maximum width constraint |
104+| `minHeight` | `number` | Minimum height constraint |
105+| `maxHeight` | `number` | Maximum height constraint |
106+| `padding` | `{ x?: number, y?: number }` | Internal padding (cells) |
107+| `gap` | `number` | Spacing between children (cells) |
108+| `justifyContent` | `string` | Distribute children along the main axis |
109+| `alignItems` | `string` | Align children along the cross axis |
110+| `flexWrap` | `"nowrap" \| "wrap"` | Wrap children to next line (HStack only) |
111+| `overflow` | `"hidden" \| "scroll"` | Content overflow behavior (default: `"hidden"`) |
112+| `scrollbar` | `boolean` | Show scrollbar indicator |
113+| `scrollStep` | `number` | Mouse wheel step in cells (default: adaptive) |
114+| `scrollOffset` | `number` | Scroll position in cells (controlled) |
115+| `onScroll` | `ScrollHandler` | Called on scroll input. Return `false` to keep bubbling. |
116+| `onClick` | `() => void` | Called on mouse click or Enter when focused |
117+| `focusable` | `boolean` | Opt out of focus (default: `true` if `onClick`) |
118+| `focused` | `boolean` | Whether this element is focused (controlled) |
119+| `onFocus` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element receives focus |
120+| `onBlur` | `(event: { reason: "tab" \| "shift+tab" \| "click" \| "escape" }) => void` | Called when element loses focus |
121+| `focusStyle` | `StyleProps` | Style overrides applied when focused |
122+| `onKeyPress` | `(key: string) => boolean \| void` | Key event handler. Return `false` to keep bubbling. |
123+
124+`ScrollHandler` is `((offset: number, maxOffset: number) => void) | ((offset: number, maxOffset: number) => boolean)`. Only an exact `false` return continues propagation to the next scrollable ancestor; any other return value consumes the scroll event. The union preserves source compatibility for legacy void callbacks whose expression bodies incidentally return another value.
123125
124126 ### Sizing
125127
@@ -260,6 +262,8 @@ VStack({
260262
261263 In controlled mode, mouse wheel events fire `onScroll` with the new offset and maximum offset (total content size minus viewport size); the UI only moves when the app passes the updated `scrollOffset` back.
262264
265+For containers, `onScroll` may return `false` to decline handling and continue scroll propagation to the next scrollable ancestor. Any other return value (`undefined`, `true`, or no return) consumes the scroll event and stops propagation, preserving backward compatibility with existing void handlers.
266+
263267 ### Scroll Step
264268
265269 Mouse wheel scrolling moves by a configurable **step size** measured in cells along the container's main axis.
@@ -319,12 +323,14 @@ Scroll is **pointer-driven**, not focus-driven. Mouse wheel events are routed sp
319323 1. Terminal reports mouse position via SGR mouse mode
320324 2. Starting from the **topmost layer**, find the deepest node at `(x, y)`
321325 3. If the layer has a node at that position, it handles the event. Otherwise, try the next layer down.
322-4. For scroll: walk up the ancestor chain to find the nearest scrollable node (container with `overflow: "scroll"`, or TextInput)
326+4. For scroll: walk up the ancestor chain from the deepest hit node, considering scrollable nodes innermost-first (containers with `overflow: "scroll"`, or TextInput)
323327 5. For click: walk up to find the nearest container with `onClick`
324328
325329 ### Nested Scrollable Containers
326330
327-**Innermost scrollable wins.** The deepest scrollable ancestor of the hit target handles the event.
331+Wheel events start at the deepest scrollable ancestor of the hit target. For scrollable containers, if the container's `onScroll` returns `false`, the event continues to the next scrollable ancestor. Otherwise, that first target handles the event and propagation stops. Existing void `onScroll` handlers preserve current behavior because `undefined` consumes the event.
332+
333+TextInput participates as a scrollable target with framework-managed scroll, but it does not expose `onScroll`; once a TextInput is the scroll target, it handles wheel input directly.
328334
329335 ### Architecture Requirements