xonecas.io
70160
Ce

cel-tui / commit c477b71

feat(core): implement scroll rendering and scrollbar indicators

Scroll rendering for overflow: scroll containers:
- shiftLayoutNode() offsets children by -scrollOffset along the
  main axis (vertical for VStack, horizontal for HStack)
- Content is clipped to the container bounds (via existing clip rect)
- Supports both controlled (scrollOffset prop) and uncontrolled
  (framework-managed via WeakMap) scroll modes

Scrollbar indicators (scrollbar: true):
- Vertical scrollbar: ┃ for thumb, │ for track, in last column
- Horizontal scrollbar: ━ for thumb, ─ for track, in last row
- Thumb size and position proportional to content/viewport ratio

Uncontrolled scroll in cel.ts:
- When no onScroll handler, framework manages scroll state internally
- Mouse wheel events update the framework-managed offset directly

xonecas2026-04-03 c477b712979dfd78234d0e90e43625e238625431 parent acc374e

4 files changed

TODO.md+2−2
@@ -40,8 +40,8 @@ What's implemented, what's missing, and what needs hardening. Reference `spec.md
4040 - ✅ TextInput painting (value, placeholder, cursor via color inversion)
4141 - ✅ Text wrapping and layout use `visibleWidth()` for correct CJK/emoji handling
4242 - ✅ Overflow clipping — children clipped to parent bounds via clip rect propagation
43-- ❌ Scroll rendering (`overflow: "scroll"`) — content offset not applied during painting
44-- ❌ Scrollbar rendering (`scrollbar: true`)
43+- ✅ Scroll rendering (`overflow: "scroll"`) — content offset applied during painting
44+- ✅ Scrollbar rendering (`scrollbar: true`) — vertical and horizontal indicators
4545
4646 ## Input
4747
packages/core/src/cel.ts+12−3
@@ -15,6 +15,8 @@ import {
1515 getTextInputCursor,
1616 setTextInputCursor,
1717 setTextInputScroll,
18+ getContainerScroll,
19+ setContainerScroll,
1820 } from "./paint.js";
1921 import {
2022 insertChar,
@@ -130,10 +132,17 @@ function handleMouseEvent(event: MouseEvent): void {
130132 const target = findScrollTarget(path);
131133 if (target) {
132134 const props = target.node.type !== "text" ? target.node.props : null;
133- if (props && "onScroll" in props && props.onScroll) {
134- const offset = (props as any).scrollOffset ?? 0;
135+ if (props && "onScroll" in props) {
135136 const delta = event.type === "scroll-up" ? -1 : 1;
136- props.onScroll(offset + delta);
137+ if (props.onScroll) {
138+ // Controlled scroll: notify app
139+ const offset = (props as any).scrollOffset ?? 0;
140+ props.onScroll(Math.max(0, offset + delta));
141+ } else {
142+ // Uncontrolled scroll: framework manages state
143+ const current = getContainerScroll(props);
144+ setContainerScroll(props, Math.max(0, current + delta));
145+ }
137146 cel.render();
138147 }
139148 }
packages/core/src/paint.test.ts+99−0
@@ -282,6 +282,105 @@ describe("paint", () => {
282282 });
283283 });
284284
285+ describe("scroll rendering", () => {
286+ test("VStack with overflow scroll and scrollOffset offsets children vertically", () => {
287+ const node = VStack(
288+ { width: 10, height: 3, overflow: "scroll", scrollOffset: 1 },
289+ [
290+ Text("line0"),
291+ Text("line1"),
292+ Text("line2"),
293+ Text("line3"),
294+ Text("line4"),
295+ ],
296+ );
297+ const ln = layout(node, 10, 3);
298+ const buf = new CellBuffer(10, 5);
299+ paint(ln, buf);
300+ // scrollOffset=1 means first visible line is line1
301+ expect(readRow(buf, 0)).toBe("line1");
302+ expect(readRow(buf, 1)).toBe("line2");
303+ expect(readRow(buf, 2)).toBe("line3");
304+ // Row 3 should be empty (outside container)
305+ expect(readRow(buf, 3)).toBe("");
306+ });
307+
308+ test("scrollOffset 0 shows from the top", () => {
309+ const node = VStack(
310+ { width: 10, height: 2, overflow: "scroll", scrollOffset: 0 },
311+ [Text("first"), Text("second"), Text("third")],
312+ );
313+ const ln = layout(node, 10, 2);
314+ const buf = new CellBuffer(10, 3);
315+ paint(ln, buf);
316+ expect(readRow(buf, 0)).toBe("first");
317+ expect(readRow(buf, 1)).toBe("second");
318+ expect(readRow(buf, 2)).toBe("");
319+ });
320+
321+ test("HStack with overflow scroll and scrollOffset offsets children horizontally", () => {
322+ const node = HStack(
323+ { width: 5, height: 1, overflow: "scroll", scrollOffset: 3 },
324+ [
325+ VStack({ width: 4 }, [Text("AAAA")]),
326+ VStack({ width: 4 }, [Text("BBBB")]),
327+ VStack({ width: 4 }, [Text("CCCC")]),
328+ ],
329+ );
330+ const ln = layout(node, 10, 1);
331+ const buf = new CellBuffer(10, 1);
332+ paint(ln, buf);
333+ // Total content width = 12, scrollOffset=3, viewport=5
334+ // Visible: cols 3-7 of content = "A" + "BBBB" → "ABBBB" but clipped to 5
335+ expect(readRow(buf, 0)).toBe("ABBBB");
336+ });
337+
338+ test("scroll with scrollbar shows indicator", () => {
339+ const node = VStack(
340+ {
341+ width: 10,
342+ height: 4,
343+ overflow: "scroll",
344+ scrollOffset: 0,
345+ scrollbar: true,
346+ },
347+ [
348+ Text("line0"),
349+ Text("line1"),
350+ Text("line2"),
351+ Text("line3"),
352+ Text("line4"),
353+ Text("line5"),
354+ Text("line6"),
355+ Text("line7"),
356+ ],
357+ );
358+ const ln = layout(node, 10, 4);
359+ const buf = new CellBuffer(10, 4);
360+ paint(ln, buf);
361+ // Scrollbar should be in the last column (col 9)
362+ // Content height = 8, viewport = 4, scrollOffset = 0
363+ // Scrollbar thumb should be at top rows
364+ const lastCol = Array.from({ length: 4 }, (_, y) => buf.get(9, y).char);
365+ // At least one cell should have the scrollbar character
366+ expect(lastCol.some((c) => c !== " ")).toBe(true);
367+ });
368+
369+ test("scroll clamps content — no painting above container", () => {
370+ const node = VStack(
371+ { width: 10, height: 3, overflow: "scroll", scrollOffset: 2 },
372+ [Text("line0"), Text("line1"), Text("line2"), Text("line3")],
373+ );
374+ const ln = layout(node, 10, 5);
375+ const buf = new CellBuffer(10, 5);
376+ paint(ln, buf);
377+ // With scrollOffset=2, line2 and line3 visible
378+ expect(readRow(buf, 0)).toBe("line2");
379+ expect(readRow(buf, 1)).toBe("line3");
380+ expect(readRow(buf, 2)).toBe("");
381+ });
382+ });
383+
285384 describe("nested layout", () => {
286385 test("editor-like layout paints correctly", () => {
287386 const node = HStack({ width: 30, height: 5 }, [
packages/core/src/paint.ts+147−2
@@ -60,9 +60,137 @@ function paintLayoutNode(
6060 break;
6161 }
6262
63+ // Determine scroll offset for scrollable containers
64+ const isContainer = node.type === "vstack" || node.type === "hstack";
65+ const containerProps = isContainer ? node.props : null;
66+ const isScrollable = containerProps?.overflow === "scroll";
67+ const scrollOffset = isScrollable
68+ ? (containerProps.scrollOffset ?? getContainerScroll(containerProps))
69+ : 0;
70+ const isVertical = node.type === "vstack";
71+
6372 // Recurse into children, using this node's clipped rect as the clip for children
6473 for (const child of ln.children) {
65- paintLayoutNode(child, buf, clipped);
74+ if (isScrollable && scrollOffset !== 0) {
75+ // Paint child with shifted position
76+ const shifted = shiftLayoutNode(child, isVertical, -scrollOffset);
77+ paintLayoutNode(shifted, buf, clipped);
78+ } else {
79+ paintLayoutNode(child, buf, clipped);
80+ }
81+ }
82+
83+ // Paint scrollbar if enabled
84+ if (isScrollable && containerProps.scrollbar) {
85+ paintScrollbar(ln, scrollOffset, buf, clipped);
86+ }
87+}
88+
89+/**
90+ * Create a copy of a layout node (and all descendants) with positions
91+ * shifted along the given axis.
92+ */
93+function shiftLayoutNode(
94+ ln: LayoutNode,
95+ isVertical: boolean,
96+ offset: number,
97+): LayoutNode {
98+ const newRect: Rect = {
99+ x: ln.rect.x + (isVertical ? 0 : offset),
100+ y: ln.rect.y + (isVertical ? offset : 0),
101+ width: ln.rect.width,
102+ height: ln.rect.height,
103+ };
104+ return {
105+ node: ln.node,
106+ rect: newRect,
107+ children: ln.children.map((c) => shiftLayoutNode(c, isVertical, offset)),
108+ };
109+}
110+
111+/**
112+ * Paint a scrollbar indicator for a scrollable container.
113+ */
114+function paintScrollbar(
115+ ln: LayoutNode,
116+ scrollOffset: number,
117+ buf: CellBuffer,
118+ clipRect: Rect,
119+): void {
120+ const { rect, children } = ln;
121+ const isVertical = ln.node.type === "vstack";
122+
123+ if (isVertical) {
124+ // Compute total content height from children
125+ let contentHeight = 0;
126+ for (const child of children) {
127+ const childBottom = child.rect.y + child.rect.height - rect.y;
128+ if (childBottom > contentHeight) contentHeight = childBottom;
129+ }
130+ const viewportH = rect.height;
131+ if (contentHeight <= viewportH) return; // no scrollbar needed
132+
133+ // Thumb size and position
134+ const thumbSize = Math.max(
135+ 1,
136+ Math.round((viewportH / contentHeight) * viewportH),
137+ );
138+ const maxOffset = contentHeight - viewportH;
139+ const thumbPos =
140+ maxOffset > 0
141+ ? Math.round((scrollOffset / maxOffset) * (viewportH - thumbSize))
142+ : 0;
143+
144+ const barX = rect.x + rect.width - 1;
145+ for (let row = 0; row < viewportH; row++) {
146+ const absY = rect.y + row;
147+ if (absY < clipRect.y || absY >= clipRect.y + clipRect.height) continue;
148+ if (barX < clipRect.x || barX >= clipRect.x + clipRect.width) continue;
149+ const isThumb = row >= thumbPos && row < thumbPos + thumbSize;
150+ buf.set(barX, absY, {
151+ char: isThumb ? "┃" : "│",
152+ fgColor: isThumb ? "white" : "brightBlack",
153+ bgColor: null,
154+ bold: false,
155+ italic: false,
156+ underline: false,
157+ });
158+ }
159+ } else {
160+ // Horizontal scrollbar
161+ let contentWidth = 0;
162+ for (const child of children) {
163+ const childRight = child.rect.x + child.rect.width - rect.x;
164+ if (childRight > contentWidth) contentWidth = childRight;
165+ }
166+ const viewportW = rect.width;
167+ if (contentWidth <= viewportW) return;
168+
169+ const thumbSize = Math.max(
170+ 1,
171+ Math.round((viewportW / contentWidth) * viewportW),
172+ );
173+ const maxOffset = contentWidth - viewportW;
174+ const thumbPos =
175+ maxOffset > 0
176+ ? Math.round((scrollOffset / maxOffset) * (viewportW - thumbSize))
177+ : 0;
178+
179+ const barY = rect.y + rect.height - 1;
180+ for (let col = 0; col < viewportW; col++) {
181+ const absX = rect.x + col;
182+ if (absX < clipRect.x || absX >= clipRect.x + clipRect.width) continue;
183+ if (barY < clipRect.y || barY >= clipRect.y + clipRect.height) continue;
184+ const isThumb = col >= thumbPos && col < thumbPos + thumbSize;
185+ buf.set(absX, barY, {
186+ char: isThumb ? "━" : "─",
187+ fgColor: isThumb ? "white" : "brightBlack",
188+ bgColor: null,
189+ bold: false,
190+ italic: false,
191+ underline: false,
192+ });
193+ }
66194 }
67195 }
68196
@@ -285,7 +413,24 @@ function offsetToWrappedPos(
285413 return { line: wrappedLine, col: 0 };
286414 }
287415
288-// --- TextInput framework-managed state ---
416+// --- Framework-managed state ---
417+
418+import type { ContainerProps } from "@cel-tui/types";
419+
420+const containerScrolls = new WeakMap<ContainerProps, number>();
421+
422+/** Get the scroll offset for an uncontrolled scrollable container. */
423+export function getContainerScroll(props: ContainerProps): number {
424+ return containerScrolls.get(props) ?? 0;
425+}
426+
427+/** Set the scroll offset for an uncontrolled scrollable container. */
428+export function setContainerScroll(
429+ props: ContainerProps,
430+ scroll: number,
431+): void {
432+ containerScrolls.set(props, scroll);
433+}
289434
290435 const textInputCursors = new WeakMap<TextInputProps, number>();
291436 const textInputScrolls = new WeakMap<TextInputProps, number>();