xonecas.io
70160
Ce

cel-tui / commit acc374e

feat(core): implement overflow clipping via clip rect propagation

Paint now tracks a clip rect through the tree. Each container
intersects its rect with the parent's clip rect, so children are
always clipped to their nearest ancestor's bounds.

- intersectRect() helper computes rect intersection
- paintLayoutNode() passes clip rect to children
- paintLineGraphemes() skips graphemes outside clip rect
- paintText/paintTextInput accept and forward clip rect

This handles overflow: hidden behavior — content that extends
beyond a container's bounds is not rendered.

xonecas2026-04-03 acc374e3eb119438c13953415505516a34ce1c98 parent 82efcf0

3 files changed

TODO.md+1−1
@@ -39,7 +39,7 @@ What's implemented, what's missing, and what needs hardening. Reference `spec.md
3939 - ✅ Hard clipping at rect boundaries
4040 - ✅ TextInput painting (value, placeholder, cursor via color inversion)
4141 - ✅ Text wrapping and layout use `visibleWidth()` for correct CJK/emoji handling
42-- ❌ Overflow clipping (`overflow: "hidden"`) — children aren't clipped to parent bounds
42+- ✅ Overflow clipping — children clipped to parent bounds via clip rect propagation
4343 - ❌ Scroll rendering (`overflow: "scroll"`) — content offset not applied during painting
4444 - ❌ Scrollbar rendering (`scrollbar: true`)
4545
packages/core/src/paint.test.ts+68−0
@@ -214,6 +214,74 @@ describe("paint", () => {
214214 });
215215 });
216216
217+ describe("overflow clipping", () => {
218+ test("text extending beyond container width is clipped", () => {
219+ // Container is 5 wide, child text is longer
220+ const node = VStack({ width: 5, height: 3 }, [
221+ VStack({ width: 5, height: 1 }, [Text("HelloWorld")]),
222+ ]);
223+ const ln = layout(node, 10, 3);
224+ const buf = new CellBuffer(10, 3);
225+ paint(ln, buf);
226+ // Only "Hello" should appear, "World" clipped by container
227+ expect(readRow(buf, 0)).toBe("Hello");
228+ });
229+
230+ test("child positioned outside parent bounds is clipped", () => {
231+ // Parent is 10 wide, 3 tall. Two children each 2 tall = 4 total.
232+ // Second child overflows vertically.
233+ const node = VStack({ width: 10, height: 3 }, [
234+ VStack({ height: 2 }, [Text("AA")]),
235+ VStack({ height: 2 }, [Text("BB")]),
236+ ]);
237+ const ln = layout(node, 10, 3);
238+ const buf = new CellBuffer(10, 5);
239+ paint(ln, buf);
240+ expect(readRow(buf, 0)).toBe("AA");
241+ expect(readRow(buf, 2)).toBe("BB");
242+ // Row 3 is outside the parent (height=3), second line of "BB" child
243+ // would be at y=3 but should be clipped
244+ expect(readRow(buf, 3)).toBe("");
245+ });
246+
247+ test("nested containers clip to innermost parent", () => {
248+ // Outer 10x3, inner 5x2 at position (0,0)
249+ // Text inside inner is long
250+ const node = VStack({ width: 10, height: 3 }, [
251+ VStack({ width: 5, height: 2 }, [Text("LongTextHere")]),
252+ ]);
253+ const ln = layout(node, 10, 3);
254+ const buf = new CellBuffer(10, 3);
255+ paint(ln, buf);
256+ // Clipped to inner container width of 5
257+ expect(readRow(buf, 0)).toBe("LongT");
258+ });
259+
260+ test("HStack children clipped horizontally by parent", () => {
261+ const node = HStack({ width: 8, height: 1 }, [
262+ VStack({ width: 5 }, [Text("AAAAA")]),
263+ VStack({ width: 5 }, [Text("BBBBB")]),
264+ ]);
265+ const ln = layout(node, 10, 1);
266+ const buf = new CellBuffer(10, 1);
267+ paint(ln, buf);
268+ // First child fills 0-4 ("AAAAA"), second starts at 5
269+ // But parent is only 8 wide, so second child clipped at col 8
270+ expect(readRow(buf, 0)).toBe("AAAAABBB");
271+ });
272+
273+ test("deeply nested clipping", () => {
274+ const node = VStack({ width: 6, height: 2 }, [
275+ HStack({}, [VStack({ width: 10 }, [Text("TooWide!!!")])]),
276+ ]);
277+ const ln = layout(node, 10, 2);
278+ const buf = new CellBuffer(10, 2);
279+ paint(ln, buf);
280+ // Should be clipped to outermost container width of 6
281+ expect(readRow(buf, 0)).toBe("TooWid");
282+ });
283+ });
284+
217285 describe("nested layout", () => {
218286 test("editor-like layout paints correctly", () => {
219287 const node = HStack({ width: 30, height: 5 }, [
packages/core/src/paint.ts+58−11
@@ -17,18 +17,42 @@ const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
1717 * @param buf - Target cell buffer.
1818 */
1919 export function paint(root: LayoutNode, buf: CellBuffer): void {
20- paintLayoutNode(root, buf);
20+ paintLayoutNode(root, buf, root.rect);
2121 }
2222
23-function paintLayoutNode(ln: LayoutNode, buf: CellBuffer): void {
23+/**
24+ * Intersect two rectangles. Returns a rect with zero area if they don't overlap.
25+ */
26+function intersectRect(a: Rect, b: Rect): Rect {
27+ const x = Math.max(a.x, b.x);
28+ const y = Math.max(a.y, b.y);
29+ const right = Math.min(a.x + a.width, b.x + b.width);
30+ const bottom = Math.min(a.y + a.height, b.y + b.height);
31+ return {
32+ x,
33+ y,
34+ width: Math.max(0, right - x),
35+ height: Math.max(0, bottom - y),
36+ };
37+}
38+
39+function paintLayoutNode(
40+ ln: LayoutNode,
41+ buf: CellBuffer,
42+ clipRect: Rect,
43+): void {
2444 const { node, rect } = ln;
2545
46+ // Clip this node's rect against the parent clip rect
47+ const clipped = intersectRect(rect, clipRect);
48+ if (clipped.width <= 0 || clipped.height <= 0) return;
49+
2650 switch (node.type) {
2751 case "text":
28- paintText(node.content, node.props, rect, buf);
52+ paintText(node.content, node.props, rect, clipped, buf);
2953 break;
3054 case "textinput":
31- paintTextInput(node.props, rect, buf);
55+ paintTextInput(node.props, rect, clipped, buf);
3256 break;
3357 case "vstack":
3458 case "hstack":
@@ -36,9 +60,9 @@ function paintLayoutNode(ln: LayoutNode, buf: CellBuffer): void {
3660 break;
3761 }
3862
39- // Recurse into children
63+ // Recurse into children, using this node's clipped rect as the clip for children
4064 for (const child of ln.children) {
41- paintLayoutNode(child, buf);
65+ paintLayoutNode(child, buf, clipped);
4266 }
4367 }
4468
@@ -67,11 +91,17 @@ function makeCell(
6791 * Correctly handles wide characters (CJK, emoji) by advancing the column
6892 * by the grapheme's visible width.
6993 */
94+/**
95+ * Paint a single line of text into the buffer using grapheme segmentation.
96+ * Correctly handles wide characters (CJK, emoji) by advancing the column
97+ * by the grapheme's visible width. Respects the clip rect.
98+ */
7099 function paintLineGraphemes(
71100 line: string,
72101 x: number,
73102 y: number,
74103 maxWidth: number,
104+ clipRect: Rect,
75105 props: {
76106 fgColor?: Color;
77107 bgColor?: Color;
@@ -81,12 +111,21 @@ function paintLineGraphemes(
81111 },
82112 buf: CellBuffer,
83113 ): void {
114+ if (y < clipRect.y || y >= clipRect.y + clipRect.height) return;
115+ const clipLeft = clipRect.x;
116+ const clipRight = clipRect.x + clipRect.width;
117+
84118 let col = 0;
85119 for (const { segment } of segmenter.segment(line)) {
86120 const gw = visibleWidth(segment);
87121 if (gw === 0) continue;
88- if (col + gw > maxWidth) break; // clip: grapheme doesn't fit
89- buf.set(x + col, y, makeCell(segment, props));
122+ if (col + gw > maxWidth) break; // clip: grapheme doesn't fit in rect
123+ const absX = x + col;
124+ if (absX >= clipRight) break; // past clip right edge
125+ if (absX + gw > clipLeft) {
126+ // At least partially visible in clip rect
127+ buf.set(absX, y, makeCell(segment, props));
128+ }
90129 col += gw;
91130 }
92131 }
@@ -103,6 +142,7 @@ function paintText(
103142 underline?: boolean;
104143 },
105144 rect: Rect,
145+ clipRect: Rect,
106146 buf: CellBuffer,
107147 ): void {
108148 const { x, y, width: w, height: h } = rect;
@@ -139,13 +179,14 @@ function paintText(
139179 // Paint lines, clipped to rect (grapheme-aware)
140180 for (let row = 0; row < lines.length && row < h; row++) {
141181 const line = lines[row]!;
142- paintLineGraphemes(line, x, y + row, w, props, buf);
182+ paintLineGraphemes(line, x, y + row, w, clipRect, props, buf);
143183 }
144184 }
145185
146186 function paintTextInput(
147187 props: TextInputProps,
148188 rect: Rect,
189+ clipRect: Rect,
149190 buf: CellBuffer,
150191 ): void {
151192 const { x, y, width: w, height: h } = rect;
@@ -156,7 +197,13 @@ function paintTextInput(
156197
157198 if (showPlaceholder && props.placeholder) {
158199 // Paint placeholder text
159- paintText(props.placeholder.content, props.placeholder.props, rect, buf);
200+ paintText(
201+ props.placeholder.content,
202+ props.placeholder.props,
203+ rect,
204+ clipRect,
205+ buf,
206+ );
160207 return;
161208 }
162209
@@ -178,7 +225,7 @@ function paintTextInput(
178225 const lineIdx = scrollOffset + row;
179226 if (lineIdx >= lines.length) break;
180227 const line = lines[lineIdx]!;
181- paintLineGraphemes(line, x, y + row, w, props, buf);
228+ paintLineGraphemes(line, x, y + row, w, clipRect, props, buf);
182229 }
183230
184231 // Paint cursor if focused