xonecas.io
70160
Ce

cel-tui / commit 69a6fb8

feat(core): add adaptive mouse wheel scrollStep

xonecas2026-04-07 69a6fb86706cb94d3f5379ce2e5ec349ab491bc0 parent d7fde7d

10 files changed

README.md+1−0
@@ -63,6 +63,7 @@ cel.viewport(() =>
6363 - **Flexbox layout** — fixed, flex, percentage, and intrinsic sizing with gap, padding, alignment.
6464 - **Layers** — return an array for multi-layer compositing (modals, overlays).
6565 - **Uncontrolled by default** — focus and scroll just work. Opt into controlled mode when needed.
66+- **Adaptive wheel scrolling** — scrollables and TextInput use an adaptive mouse-wheel step by default; override it with `scrollStep` when needed.
6667 - **Style inheritance** — containers propagate styles to descendants. `bgColor` fills the rect.
6768 - **16-color palette** — numbered slots (`"color00"`–`"color15"`) mapped to ANSI 16 by default. Custom themes can remap to different ANSI indices or 24-bit true color.
6869 - **Cell buffer rendering** — styled cells, differential updates, synchronized output.
TODO.md+0−4
@@ -12,14 +12,10 @@ Remaining work, known bugs, and planned improvements.
1212
1313 ## Bugs / Spec Violations
1414
15-- 🔧 **Mouse wheel scrolling is too slow for scrollable containers** — high priority. Scroll handling in `cel.ts` applies a hardcoded `delta` of `±1` cell per wheel event for both controlled and uncontrolled scrollables. That makes long logs and transcripts tedious to navigate, and apps using the documented sticky-bottom chat pattern inherit the sluggish behavior unchanged. Fix: introduce a larger default wheel step and/or a configurable scroll-step API, then add tests covering multi-line m …
16-
1715 - 🔧 **Streaming wrapped Markdown with inline formatting can corrupt until rendering settles** — high priority. The risky behavior is in `packages/components/src/markdown.ts`: plain paragraphs render as a single `Text(..., { wrap: "word" })`, but formatted paragraphs/list items/blockquote content render as `HStack({ flexWrap: "wrap" })` trees built from split inline spans. During streaming, partial markdown can change shape across renders (for example plain text becoming a formatted span onc …
1816
1917 - 🔧 **Scrollbar thumb position ignores padding** — `paintScrollbar` in `paint.ts` computes `maxOffset = contentHeight - rect.height` without accounting for container padding, while the scroll clamping logic uses `contentHeight + padY - rect.height`. For padded scrollable containers the thumb position is slightly off.
2018
21-- 🔧 **Duplicate max scroll offset calculation** — `getMaxScrollOffset` in `cel.ts` and `computeMaxScrollOffset` in `paint.ts` implement the same logic. Should be extracted to a shared function.
22-
2319 - 🔧 **Key events leak through layers** — When no element is focused and the topmost layer's root has no `onKeyPress`, `handleKeyEvent` falls through to lower layers. Mouse input stops at the topmost layer with a node at the event position, but keyboard input doesn't follow the same rule. A modal overlay without its own root `onKeyPress` would leak keys to the base layer, breaking the "events target the topmost layer" principle.
2420
2521 - 🔧 **`space-between` + `gap` double-spaces children** — When both `justifyContent: "space-between"` and `gap` are set, children get `gap` spacing plus the distributed remaining space on top. The remaining-space calculation subtracts `totalGap` first, then `space-between` distributes what's left as extra gap — so the effective gap is `gap + betweenGaps[i]`. CSS flex doesn't stack `space-between` on top of `gap` this way. The spec doesn't define this interaction.
docs/skill/cel-tui/SKILL.md+14−2
@@ -75,7 +75,7 @@ The steps: `cel.init(terminal)` → `cel.viewport(() => tree)` → mutate state
7575 | `Text(content, props?)` | Leaf | Styled text, no children |
7676 | `TextInput(props)` | Container (no children) | Multi-line editable text |
7777
78-Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to different ANSI indices or 24-bit true color via `cel …
78+Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`, `scrollStep`, `scrollOffset`, `onScroll`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to different …
7979
8080 Read [references/api.md](references/api.md) for the full props listing, sizing strategies, text props, and component reference.
8181
@@ -103,6 +103,17 @@ Scroll is **uncontrolled by default** — the framework manages scroll position
103103 VStack({ overflow: "scroll", scrollbar: true }, [...items]);
104104 ```
105105
106+Mouse wheel scrolling uses an **adaptive step** by default based on the scroll target's visible main-axis viewport size:
107+
108+- `floor(viewportMainAxis / 3)`
109+- clamped to `3..8`
110+
111+Override it with `scrollStep` when a view should scroll faster or slower:
112+
113+```ts
114+VStack({ overflow: "scroll", scrollbar: true, scrollStep: 6 }, [...items]);
115+```
116+
106117 Provide `scrollOffset` + `onScroll` to opt into **controlled mode** — you own the state:
107118
108119 ```ts
@@ -122,7 +133,7 @@ VStack(
122133 );
123134 ```
124135
125-Controlled mode enables patterns like auto-scroll to bottom on new content.
136+Controlled mode enables patterns like auto-scroll to bottom on new content. `scrollStep` affects mouse wheel input only — not programmatic `scrollOffset` updates.
126137
127138 ### Layers (modals)
128139
@@ -219,6 +230,7 @@ mySelect.reset(); // clear filter/highlight programmatically
219230 - **Enter activates** a focused container's `onClick`. If no `onClick`, Enter reaches `onKeyPress`.
220231 - **`focusable: true`** without `onClick` makes a container keyboard-focusable (receives `onKeyPress` events via Tab). Used by stateful components like `Select`.
221232 - **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.
233+- **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.
222234 - **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.
223235 - **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).
224236 - **`repeat: "fill"` in HStack** gets width 0 (intrinsic width is 0). Workaround: wrap in `VStack({ flex: 1 }, [Text(" ", { repeat: "fill" })])`.
docs/skill/cel-tui/references/api.md+6−3
@@ -17,6 +17,7 @@ All props accepted by `VStack` and `HStack`:
1717 alignItems, // "start" | "end" | "center" | "stretch"
1818 overflow, // "hidden" (default) | "scroll"
1919 scrollbar, // boolean
20+ scrollStep, // number (mouse wheel step in cells; default adaptive)
2021 scrollOffset, // number (controlled scroll)
2122 onScroll, // (offset: number, maxOffset: number) => void
2223 flexWrap, // "nowrap" (default) | "wrap" (HStack only)
@@ -61,7 +62,9 @@ VStack(
6162
6263 - Scroll direction follows the container’s main axis: VStack → vertical, HStack → horizontal.
6364 - Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
64-- 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).
65+- 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`.
66+- Set `scrollStep` to override the mouse wheel step for a specific scrollable or `TextInput`.
67+- 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). `scrollStep` affects mouse wheel input only.
6568
6669 ## Text Props
6770
@@ -87,7 +90,7 @@ TextInput({
8790 onChange, // (value: string) => void
8891 onKeyPress, // (key: string) => boolean | void — return false to prevent default editing action
8992 placeholder, // Text() node shown when empty
90- // + all container props (sizing, styling, focus, etc.)
93+ // + all container props (sizing, styling, focus, scrollStep, etc.)
9194 });
9295 ```
9396
@@ -122,7 +125,7 @@ Constraints: `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
122125
123126 Text has no sizing props — parent controls the box, height is intrinsic (content + wrapping).
124127
125-TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.).
128+TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.) plus container scroll props like `scrollStep` for mouse wheel behavior.
126129
127130 ## Key Format
128131
packages/core/src/cel.test.ts+66−48
@@ -186,66 +186,57 @@ describe("cel end-to-end", () => {
186186 expect(receivedKey).toBe("ctrl+s");
187187 });
188188
189- test("onScroll fires on mouse wheel", async () => {
190- const term = setup(20, 5);
189+ test("onScroll fires on mouse wheel using the adaptive default step", async () => {
190+ const term = setup(20, 12);
191191 let scrollOffset = 0;
192192 cel.viewport(() =>
193193 VStack(
194194 {
195195 width: 20,
196- height: 5,
196+ height: 12,
197197 overflow: "scroll",
198198 scrollOffset: scrollOffset,
199199 onScroll: (offset) => {
200200 scrollOffset = offset;
201201 },
202202 },
203- // Enough content to exceed viewport (5 rows)
204- Array.from({ length: 10 }, (_, i) => Text(`line ${i + 1}`)),
203+ // 12-row viewport → adaptive wheel step = floor(12 / 3) = 4
204+ Array.from({ length: 20 }, (_, i) => Text(`line ${i + 1}`)),
205205 ),
206206 );
207207 await waitForRender();
208208
209- // SGR scroll down at (3, 2): ESC [ < 65 ; 4 ; 3 M
210209 term.sendInput("\x1b[<65;4;3M");
211210 await waitForRender();
212211
213- expect(scrollOffset).toBe(1);
212+ expect(scrollOffset).toBe(4);
214213 });
215214
216215 test("batched mouse scroll events are all processed", async () => {
217- const term = setup(20, 5);
216+ const term = setup(20, 12);
218217 let scrollOffset = 0;
219218 cel.viewport(() =>
220219 VStack(
221220 {
222221 width: 20,
223- height: 5,
222+ height: 12,
224223 overflow: "scroll",
225224 scrollOffset: scrollOffset,
226225 onScroll: (offset) => {
227226 scrollOffset = offset;
228227 },
229228 },
230- [
231- Text("line1"),
232- Text("line2"),
233- Text("line3"),
234- Text("line4"),
235- Text("line5"),
236- Text("line6"),
237- Text("line7"),
238- Text("line8"),
239- ],
229+ Array.from({ length: 30 }, (_, i) => Text(`line${i + 1}`)),
240230 ),
241231 );
242232 await waitForRender();
243233
244234 // 3 scroll-down events batched in one data chunk (as real terminals do)
235+ // 12-row viewport → adaptive wheel step = 4, so total = 12
245236 term.sendInput("\x1b[<65;4;3M\x1b[<65;4;3M\x1b[<65;4;3M");
246237 await waitForRender();
247238
248- expect(scrollOffset).toBe(3);
239+ expect(scrollOffset).toBe(12);
249240 });
250241
251242 test("scroll clamps at max offset (no blank space past content)", async () => {
@@ -278,14 +269,14 @@ describe("cel end-to-end", () => {
278269 });
279270
280271 test("onScroll receives maxOffset", async () => {
281- const term = setup(20, 5);
272+ const term = setup(20, 12);
282273 let scrollOffset = 0;
283274 let receivedMax = -1;
284275 cel.viewport(() =>
285276 VStack(
286277 {
287278 width: 20,
288- height: 5,
279+ height: 12,
289280 overflow: "scroll",
290281 scrollOffset: scrollOffset,
291282 onScroll: (offset, maxOffset) => {
@@ -293,8 +284,8 @@ describe("cel end-to-end", () => {
293284 receivedMax = maxOffset;
294285 },
295286 },
296- // 8 items in 5-row viewport → max offset = 3
297- Array.from({ length: 8 }, (_, i) => Text(`item ${i + 1}`)),
287+ // 20 items in 12-row viewport → max offset = 8
288+ Array.from({ length: 20 }, (_, i) => Text(`item ${i + 1}`)),
298289 ),
299290 );
300291 await waitForRender();
@@ -302,20 +293,46 @@ describe("cel end-to-end", () => {
302293 term.sendInput("\x1b[<65;4;3M");
303294 await waitForRender();
304295
305- expect(scrollOffset).toBe(1);
306- expect(receivedMax).toBe(3);
296+ expect(scrollOffset).toBe(4);
297+ expect(receivedMax).toBe(8);
298+ });
299+
300+ test("scrollStep overrides the adaptive default", async () => {
301+ const term = setup(20, 12);
302+ let scrollOffset = 0;
303+ cel.viewport(() =>
304+ VStack(
305+ {
306+ width: 20,
307+ height: 12,
308+ overflow: "scroll",
309+ scrollStep: 6,
310+ scrollOffset: scrollOffset,
311+ onScroll: (offset) => {
312+ scrollOffset = offset;
313+ },
314+ },
315+ Array.from({ length: 30 }, (_, i) => Text(`line ${i + 1}`)),
316+ ),
317+ );
318+ await waitForRender();
319+
320+ term.sendInput("\x1b[<65;4;3M");
321+ await waitForRender();
322+
323+ expect(scrollOffset).toBe(6);
307324 });
308325
309326 test("uncontrolled scroll works without onScroll", async () => {
310- const term = setup(20, 5);
327+ const term = setup(20, 12);
311328 cel.viewport(() =>
312329 VStack(
313330 {
314331 width: 20,
315- height: 5,
332+ height: 12,
316333 overflow: "scroll",
317334 },
318- Array.from({ length: 10 }, (_, i) => Text(`line ${i + 1}`)),
335+ Array.from({ length: 20 }, (_, i) => Text(`line ${i + 1}`)),
319336 ),
320337 );
321338 await waitForRender();
@@ -324,16 +341,14 @@ describe("cel end-to-end", () => {
324341 const buf1 = cel._getBuffer()!;
325342 expect(buf1.get(0, 0).char).toBe("l"); // "line 1"
326343
327- // SGR scroll down at (3, 2): ESC [ < 65 ; 4 ; 3 M
328344 term.sendInput("\x1b[<65;4;3M");
329345 await waitForRender();
330346
331- // After scroll by 1, line 2 should now be at row 0
347+ // After scrolling by the adaptive step (4), line 5 should now be at row 0
332348 const buf2 = cel._getBuffer()!;
333- // Read first 6 chars of row 0
334349 let row0 = "";
335350 for (let x = 0; x < 6; x++) row0 += buf2.get(x, 0).char;
336- expect(row0).toBe("line 2");
351+ expect(row0).toBe("line 5");
337352 });
338353
339354 test("uncontrolled scroll clamps at max offset", async () => {
@@ -417,7 +432,7 @@ describe("cel end-to-end", () => {
417432 cel.render();
418433 },
419434 },
420- // 10 items in 5-row viewport → max offset = 5
435+ // 10 items in 5-row viewport → max offset = 5, adaptive wheel step = 3
421436 Array.from({ length: 10 }, (_, i) => Text(`line ${i + 1}`)),
422437 ),
423438 );
@@ -431,7 +446,7 @@ describe("cel end-to-end", () => {
431446 await waitForRender();
432447
433448 expect(stickToBottom).toBe(false);
434- expect(scrollOffset).toBe(4); // maxOffset(5) - 1 = 4
449+ expect(scrollOffset).toBe(2); // maxOffset(5) - 3 = 2
435450 });
436451 });
437452
@@ -1251,18 +1266,20 @@ describe("cel end-to-end", () => {
12511266
12521267 describe("TextInput mouse wheel scroll", () => {
12531268 test("mouse wheel scrolls TextInput content", async () => {
1254- const term = setup(20, 3);
1255- let value = "line1\nline2\nline3\nline4\nline5";
1269+ const term = setup(20, 12);
1270+ let value = Array.from({ length: 20 }, (_, i) => `line${i + 1}`).join(
1271+ "\n",
1272+ );
12561273 // Stable onChange ref so TextInput scroll state persists across re-renders
12571274 const onChange = (v: string) => {
12581275 value = v;
12591276 };
12601277
12611278 cel.viewport(() =>
1262- VStack({ width: 20, height: 3 }, [
1279+ VStack({ width: 20, height: 12 }, [
12631280 TextInput({
12641281 value,
1265- height: 3,
1282+ height: 12,
12661283 onChange,
12671284 }),
12681285 ]),
@@ -1275,15 +1292,14 @@ describe("cel end-to-end", () => {
12751292 for (let x = 0; x < 5; x++) row0 += buf1.get(x, 0).char;
12761293 expect(row0).toBe("line1");
12771294
1278- // Scroll down at (5, 1)
1295+ // 12-row viewport → adaptive wheel step = 4
12791296 term.sendInput("\x1b[<65;6;2M");
12801297 await waitForRender();
12811298
1282- // After scrolling down, line1 should no longer be at row 0
12831299 const buf2 = cel._getBuffer()!;
12841300 let row0After = "";
12851301 for (let x = 0; x < 5; x++) row0After += buf2.get(x, 0).char;
1286- expect(row0After).toBe("line2");
1302+ expect(row0After).toBe("line5");
12871303 });
12881304
12891305 test("mouse wheel scroll up clamps at 0", async () => {
@@ -1316,9 +1332,11 @@ describe("cel end-to-end", () => {
13161332 });
13171333
13181334 test("mouse wheel prefers innermost TextInput over outer scrollable", async () => {
1319- const term = setup(20, 3);
1335+ const term = setup(20, 12);
13201336 let outerScrolled = false;
1321- let value = "line1\nline2\nline3\nline4";
1337+ let value = Array.from({ length: 20 }, (_, i) => `line${i + 1}`).join(
1338+ "\n",
1339+ );
13221340 const onChange = (v: string) => {
13231341 value = v;
13241342 };
@@ -1327,7 +1345,7 @@ describe("cel end-to-end", () => {
13271345 VStack(
13281346 {
13291347 width: 20,
1330- height: 3,
1348+ height: 12,
13311349 overflow: "scroll",
13321350 scrollOffset: 0,
13331351 onScroll: () => {
@@ -1337,7 +1355,7 @@ describe("cel end-to-end", () => {
13371355 [
13381356 TextInput({
13391357 value,
1340- height: 3,
1358+ height: 12,
13411359 onChange,
13421360 }),
13431361 ],
@@ -1351,11 +1369,11 @@ describe("cel end-to-end", () => {
13511369
13521370 expect(outerScrolled).toBe(false);
13531371
1354- // Verify TextInput scrolled
1372+ // Verify TextInput scrolled by the adaptive step (4)
13551373 const buf = cel._getBuffer()!;
13561374 let row0 = "";
13571375 for (let x = 0; x < 5; x++) row0 += buf.get(x, 0).char;
1358- expect(row0).toBe("line2");
1376+ expect(row0).toBe("line5");
13591377 });
13601378 });
13611379
packages/core/src/cel.ts+3−2
@@ -26,7 +26,7 @@ import {
2626 type EditState,
2727 } from "./text-edit.js";
2828 import type { Terminal } from "./terminal.js";
29-import { getMaxScrollOffset } from "./scroll.js";
29+import { getMaxScrollOffset, getScrollStep } from "./scroll.js";
3030
3131 type RenderFn = () => Node | Node[];
3232
@@ -502,7 +502,8 @@ function handleMouseEvent(event: MouseEvent): void {
502502 if (event.type === "scroll-up" || event.type === "scroll-down") {
503503 const target = findScrollTarget(path);
504504 if (target) {
505- const delta = event.type === "scroll-up" ? -1 : 1;
505+ const step = getScrollStep(target);
506+ const delta = event.type === "scroll-up" ? -step : step;
506507 const maxOffset = getMaxScrollOffset(target);
507508
508509 if (target.node.type === "textinput") {
packages/core/src/scroll.test.ts+50−2
@@ -1,9 +1,9 @@
11 import { describe, expect, test } from "bun:test";
22 import { layout } from "./layout.js";
3-import { VStack } from "./primitives/stacks.js";
3+import { HStack, VStack } from "./primitives/stacks.js";
44 import { Text } from "./primitives/text.js";
55 import { TextInput } from "./primitives/text-input.js";
6-import { getMaxScrollOffset } from "./scroll.js";
6+import { getMaxScrollOffset, getScrollStep } from "./scroll.js";
77
88 describe("scroll", () => {
99 test("TextInput max scroll offset uses visual wrapping and padding", () => {
@@ -38,4 +38,52 @@ describe("scroll", () => {
3838
3939 expect(getMaxScrollOffset(root)).toBe(1);
4040 });
41+
42+ test("adaptive scroll step uses the scroll target viewport and clamps to 3..8", () => {
43+ const small = layout(
44+ VStack({ width: 10, height: 2, overflow: "scroll" }, [Text("x")]),
45+ 10,
46+ 2,
47+ );
48+ const medium = layout(
49+ VStack({ width: 10, height: 12, overflow: "scroll" }, [Text("x")]),
50+ 10,
51+ 12,
52+ );
53+ const large = layout(
54+ HStack({ width: 30, height: 3, overflow: "scroll" }, [Text("x")]),
55+ 30,
56+ 3,
57+ );
58+
59+ expect(getScrollStep(small)).toBe(3);
60+ expect(getScrollStep(medium)).toBe(4);
61+ expect(getScrollStep(large)).toBe(8);
62+ });
63+
64+ test("scrollStep prop overrides the adaptive default", () => {
65+ const scrollable = layout(
66+ VStack({ width: 10, height: 12, overflow: "scroll", scrollStep: 6 }, [
67+ Text("x"),
68+ ]),
69+ 10,
70+ 12,
71+ );
72+ const textInputRoot = layout(
73+ VStack({ width: 8, height: 4 }, [
74+ TextInput({
75+ width: 8,
76+ height: 4,
77+ scrollStep: 5,
78+ value: "line1\nline2\nline3\nline4\nline5\nline6",
79+ onChange: () => {},
80+ }),
81+ ]),
82+ 8,
83+ 4,
84+ );
85+
86+ expect(getScrollStep(scrollable)).toBe(6);
87+ expect(getScrollStep(textInputRoot.children[0]!)).toBe(5);
88+ });
4189 });
packages/core/src/scroll.ts+33−0
@@ -1,6 +1,39 @@
11 import type { LayoutNode } from "./layout.js";
22 import { layoutText } from "./text-layout.js";
33
4+function isVerticalScrollTarget(target: LayoutNode): boolean {
5+ return target.node.type === "vstack" || target.node.type === "textinput";
6+}
7+
8+function getScrollTargetProps(target: LayoutNode): Record<string, any> {
9+ return target.node.props as Record<string, any>;
10+}
11+
12+function getScrollViewportMainAxisSize(target: LayoutNode): number {
13+ const props = getScrollTargetProps(target);
14+ const isVertical = isVerticalScrollTarget(target);
15+ const mainAxisSize = isVertical ? target.rect.height : target.rect.width;
16+ const mainAxisPadding = isVertical
17+ ? (props.padding?.y ?? 0) * 2
18+ : (props.padding?.x ?? 0) * 2;
19+ return Math.max(1, mainAxisSize - mainAxisPadding);
20+}
21+
22+/**
23+ * Resolve the mouse wheel scroll step for a scrollable layout node.
24+ * Uses the explicit `scrollStep` prop when provided, otherwise an
25+ * adaptive default based on the visible main-axis viewport size.
26+ */
27+export function getScrollStep(target: LayoutNode): number {
28+ const rawStep = getScrollTargetProps(target).scrollStep;
29+ if (Number.isFinite(rawStep) && rawStep > 0) {
30+ return Math.max(1, Math.floor(rawStep));
31+ }
32+
33+ const viewport = getScrollViewportMainAxisSize(target);
34+ return Math.max(3, Math.min(8, Math.floor(viewport / 3)));
35+}
36+
437 /**
538 * Compute the maximum scroll offset for a scrollable layout node.
639 * Returns 0 if content fits within the viewport.
packages/types/src/index.ts+11−0
@@ -178,6 +178,17 @@ export interface ContainerProps extends StyleProps {
178178 /** Show a scrollbar indicator when `overflow` is `"scroll"`. */
179179 scrollbar?: boolean;
180180
181+ /**
182+ * Mouse wheel step size in cells along the container's main axis.
183+ * When omitted, the framework uses an adaptive default based on the
184+ * scroll target's viewport size: `floor(viewportMainAxis / 3)`,
185+ * clamped to the range `3..8`.
186+ *
187+ * Affects mouse wheel input only — not programmatic {@link scrollOffset}
188+ * updates or TextInput cursor-follow behavior.
189+ */
190+ scrollStep?: number;
191+
181192 /**
182193 * Controlled scroll position in cells. When provided, the app owns
183194 * scroll state and must update this value via {@link onScroll}.
spec.md+19−1
@@ -81,6 +81,7 @@ Shared by both VStack and HStack. Containers also accept styling props (see [Sty
8181 | `flexWrap` | `"nowrap" \| "wrap"` | Wrap children to next line (HStack only) |
8282 | `overflow` | `"hidden" \| "scroll"` | Content overflow behavior (default: `"hidden"`) |
8383 | `scrollbar` | `boolean` | Show scrollbar indicator |
84+| `scrollStep` | `number` | Mouse wheel step in cells (default: adaptive) |
8485 | `scrollOffset` | `number` | Scroll position in cells (controlled) |
8586 | `onScroll` | `(offset: number, maxOffset: number) => void` | Called on scroll input |
8687 | `onClick` | `() => void` | Called on mouse click or Enter when focused |
@@ -230,6 +231,23 @@ VStack({
230231
231232 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.
232233
234+### Scroll Step
235+
236+Mouse wheel scrolling moves by a configurable **step size** measured in cells along the container's main axis.
237+
238+- `scrollStep` sets the step explicitly.
239+- When omitted, the framework uses an adaptive default based on the viewport size of the scroll target:
240+ - `floor(viewportMainAxis / 3)`
241+ - clamped to the range `3..8`
242+
243+Examples:
244+
245+- height `3` viewport → step `3`
246+- height `12` viewport → step `4`
247+- height `30` viewport → step `8`
248+
249+This applies to both controlled and uncontrolled scrollable containers, and to `TextInput` mouse wheel scrolling. It affects **mouse wheel input only** — not programmatic `scrollOffset` updates or TextInput cursor-follow behavior.
250+
233251 Values exceeding the maximum scroll offset are clamped during rendering — passing `Infinity` means "scroll to the end". This enables patterns like sticky-bottom scroll:
234252
235253 ```ts
@@ -550,7 +568,7 @@ TextInput(props: TextInputProps)
550568
551569 #### Props
552570
553-Container sizing props (`width`, `height`, `flex`, `min*`, `max*`, `padding`), focus props (`focused`, `onFocus`, `onBlur`, `focusStyle`), styling props, and:
571+Container sizing props (`width`, `height`, `flex`, `min*`, `max*`, `padding`), focus props (`focused`, `onFocus`, `onBlur`, `focusStyle`), styling props, wheel scroll prop (`scrollStep`), and:
554572
555573 | Prop | Type | Description |
556574 | ------------- | ---------------------------------- | ---------------------------------------------------------------------------------------- |