xonecas.io
70160
Ce

cel-tui / commit 82efcf0

feat(core): integrate visibleWidth for CJK/emoji-aware layout and paint

Replace string.length with visibleWidth() throughout:

Layout (intrinsicMainSize):
- Text intrinsic width uses visibleWidth per line
- Word-wrap height computation uses visibleWidth

Paint:
- paintLineGraphemes: new grapheme-aware line painter that
  advances columns by each grapheme's visible width
- paintText and paintTextInput use grapheme-aware painting
- repeat fill computes repeats by visible width
- wrapLine breaks by grapheme instead of character
- offsetToWrappedPos uses visibleWidth for cursor mapping

Wide characters (CJK, emoji) now correctly occupy 2 terminal
cells in both layout sizing and rendering.

xonecas2026-04-03 82efcf074bd68b91e8c32d322a8f104e331b86f7 parent 6ec5bea

5 files changed

TODO.md+1−1
@@ -38,7 +38,7 @@ What's implemented, what's missing, and what needs hardening. Reference `spec.md
3838 - ✅ Text `wrap: "word"` (basic word-wrap)
3939 - ✅ Hard clipping at rect boundaries
4040 - ✅ TextInput painting (value, placeholder, cursor via color inversion)
41-- 🔧 Text wrapping and layout use `string.length` for width — should use `visibleWidth()` for correct CJK/emoji handling
41+- ✅ Text wrapping and layout use `visibleWidth()` for correct CJK/emoji handling
4242 - ❌ Overflow clipping (`overflow: "hidden"`) — children aren't clipped to parent bounds
4343 - ❌ Scroll rendering (`overflow: "scroll"`) — content offset not applied during painting
4444 - ❌ Scrollbar rendering (`scrollbar: true`)
packages/core/src/layout.test.ts+35−0
@@ -78,6 +78,41 @@ describe("layout", () => {
7878 });
7979 });
8080
81+ describe("visibleWidth-aware sizing", () => {
82+ test("CJK text intrinsic width counts double-width chars", () => {
83+ const node = HStack({ height: 10, alignItems: "start" }, [
84+ Text("世界"), // 2 chars, each width 2 = 4 columns
85+ ]);
86+ const result = layout(node, 80, 24);
87+ expect(childRects(result)[0]!.width).toBe(4);
88+ });
89+
90+ test("CJK text word-wrap height uses visible width", () => {
91+ // 6 CJK chars = 12 columns wide, wrap at width 5 → ceil(12/5) = 3 lines
92+ const node = VStack({ width: 5, height: 24 }, [
93+ Text("世界世界世界", { wrap: "word" }),
94+ ]);
95+ const result = layout(node, 80, 24);
96+ expect(childRects(result)[0]!.height).toBe(3);
97+ });
98+
99+ test("emoji text intrinsic width counts width 2", () => {
100+ const node = HStack({ height: 10, alignItems: "start" }, [
101+ Text("😀hi"), // emoji(2) + h(1) + i(1) = 4
102+ ]);
103+ const result = layout(node, 80, 24);
104+ expect(childRects(result)[0]!.width).toBe(4);
105+ });
106+
107+ test("mixed ASCII and CJK intrinsic width", () => {
108+ const node = HStack({ height: 10, alignItems: "start" }, [
109+ Text("hi世界"), // h(1) + i(1) + 世(2) + 界(2) = 6
110+ ]);
111+ const result = layout(node, 80, 24);
112+ expect(childRects(result)[0]!.width).toBe(6);
113+ });
114+ });
115+
81116 describe("flex sizing", () => {
82117 test("single flex child fills remaining space in VStack", () => {
83118 const node = VStack({ width: 80, height: 24 }, [
packages/core/src/layout.ts+11−3
@@ -1,4 +1,5 @@
11 import type { Node, ContainerProps, SizeValue } from "@cel-tui/types";
2+import { visibleWidth } from "./width.js";
23
34 /**
45 * A rectangle in absolute screen coordinates.
@@ -63,7 +64,10 @@ function intrinsicMainSize(
6364 if (node.props.wrap === "word") {
6465 let total = 0;
6566 for (const line of lines) {
66- total += Math.max(1, Math.ceil(line.length / Math.max(1, crossSize)));
67+ total += Math.max(
68+ 1,
69+ Math.ceil(visibleWidth(line) / Math.max(1, crossSize)),
70+ );
6771 }
6872 return total;
6973 }
@@ -74,7 +78,8 @@ function intrinsicMainSize(
7478 const lines = node.content.split("\n");
7579 let maxW = 0;
7680 for (const line of lines) {
77- if (line.length > maxW) maxW = line.length;
81+ const w = visibleWidth(line);
82+ if (w > maxW) maxW = w;
7883 }
7984 if (typeof node.props.repeat === "number") maxW *= node.props.repeat;
8085 return maxW;
@@ -87,7 +92,10 @@ function intrinsicMainSize(
8792 const lines = val.split("\n");
8893 let total = 0;
8994 for (const line of lines) {
90- total += Math.max(1, Math.ceil(line.length / Math.max(1, crossSize)));
95+ total += Math.max(
96+ 1,
97+ Math.ceil(visibleWidth(line) / Math.max(1, crossSize)),
98+ );
9199 }
92100 return total;
93101 }
packages/core/src/paint.test.ts+56−0
@@ -158,6 +158,62 @@ describe("paint", () => {
158158 });
159159 });
160160
161+ describe("wide character rendering", () => {
162+ test("CJK characters occupy 2 cells each", () => {
163+ const node = VStack({ width: 20, height: 1 }, [Text("\u4e16\u754c")]);
164+ const ln = layout(node, 20, 1);
165+ const buf = new CellBuffer(20, 1);
166+ paint(ln, buf);
167+ // \u4e16 at col 0 (wide), \u754c at col 2 (wide)
168+ expect(buf.get(0, 0).char).toBe("\u4e16");
169+ expect(buf.get(2, 0).char).toBe("\u754c");
170+ });
171+
172+ test("emoji occupies 2 cells", () => {
173+ const node = VStack({ width: 20, height: 1 }, [Text("\ud83d\ude00x")]);
174+ const ln = layout(node, 20, 1);
175+ const buf = new CellBuffer(20, 1);
176+ paint(ln, buf);
177+ // emoji at col 0 (wide), x at col 2
178+ expect(buf.get(0, 0).char).toBe("\ud83d\ude00");
179+ expect(buf.get(2, 0).char).toBe("x");
180+ });
181+
182+ test("repeat fill with CJK char fills by visible width", () => {
183+ const node = VStack({ width: 6, height: 1 }, [
184+ Text("\u4e16", { repeat: "fill" }), // width 2, fills 6 cols = 3 repeats
185+ ]);
186+ const ln = layout(node, 6, 1);
187+ const buf = new CellBuffer(6, 1);
188+ paint(ln, buf);
189+ expect(buf.get(0, 0).char).toBe("\u4e16");
190+ expect(buf.get(2, 0).char).toBe("\u4e16");
191+ expect(buf.get(4, 0).char).toBe("\u4e16");
192+ });
193+
194+ test("mixed ASCII and CJK paints at correct positions", () => {
195+ const node = VStack({ width: 20, height: 1 }, [Text("hi\u4e16\u754c")]);
196+ const ln = layout(node, 20, 1);
197+ const buf = new CellBuffer(20, 1);
198+ paint(ln, buf);
199+ expect(buf.get(0, 0).char).toBe("h");
200+ expect(buf.get(1, 0).char).toBe("i");
201+ expect(buf.get(2, 0).char).toBe("\u4e16");
202+ expect(buf.get(4, 0).char).toBe("\u754c");
203+ });
204+
205+ test("CJK text clips at rect boundary", () => {
206+ // \u4e16(2) + \u754c(2) = 4, but rect is 3 wide \u2192 clip \u754c
207+ const node = VStack({ width: 3, height: 1 }, [Text("\u4e16\u754c")]);
208+ const ln = layout(node, 3, 1);
209+ const buf = new CellBuffer(3, 1);
210+ paint(ln, buf);
211+ expect(buf.get(0, 0).char).toBe("\u4e16");
212+ // col 2 should be empty - \u754c doesn't fit (needs 2 cols, only 1 remains)
213+ expect(buf.get(2, 0).char).toBe(" ");
214+ });
215+ });
216+
161217 describe("nested layout", () => {
162218 test("editor-like layout paints correctly", () => {
163219 const node = HStack({ width: 30, height: 5 }, [
packages/core/src/paint.ts+80−21
@@ -2,6 +2,9 @@ import type { Color, TextInputProps } from "@cel-tui/types";
22 import type { Cell } from "./cell-buffer.js";
33 import { CellBuffer } from "./cell-buffer.js";
44 import type { LayoutNode, Rect } from "./layout.js";
5+import { visibleWidth } from "./width.js";
6+
7+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
58
69 /**
710 * Paint a laid-out tree into a cell buffer.
@@ -59,6 +62,35 @@ function makeCell(
5962 };
6063 }
6164
65+/**
66+ * Paint a single line of text into the buffer using grapheme segmentation.
67+ * Correctly handles wide characters (CJK, emoji) by advancing the column
68+ * by the grapheme's visible width.
69+ */
70+function paintLineGraphemes(
71+ line: string,
72+ x: number,
73+ y: number,
74+ maxWidth: number,
75+ props: {
76+ fgColor?: Color;
77+ bgColor?: Color;
78+ bold?: boolean;
79+ italic?: boolean;
80+ underline?: boolean;
81+ },
82+ buf: CellBuffer,
83+): void {
84+ let col = 0;
85+ for (const { segment } of segmenter.segment(line)) {
86+ const gw = visibleWidth(segment);
87+ if (gw === 0) continue;
88+ if (col + gw > maxWidth) break; // clip: grapheme doesn't fit
89+ buf.set(x + col, y, makeCell(segment, props));
90+ col += gw;
91+ }
92+}
93+
6294 function paintText(
6395 content: string,
6496 props: {
@@ -79,7 +111,10 @@ function paintText(
79111 // Resolve repeat
80112 let text = content;
81113 if (props.repeat === "fill" && content.length > 0) {
82- text = content.repeat(Math.ceil(w / content.length)).slice(0, w);
114+ const contentW = visibleWidth(content);
115+ if (contentW > 0) {
116+ text = content.repeat(Math.ceil(w / contentW));
117+ }
83118 } else if (typeof props.repeat === "number" && props.repeat > 0) {
84119 text = content.repeat(props.repeat);
85120 }
@@ -91,7 +126,7 @@ function paintText(
91126 const lines: string[] = [];
92127 if (props.wrap === "word") {
93128 for (const rawLine of rawLines) {
94- if (rawLine.length <= w) {
129+ if (visibleWidth(rawLine) <= w) {
95130 lines.push(rawLine);
96131 } else {
97132 wrapLine(rawLine, w, lines);
@@ -101,12 +136,10 @@ function paintText(
101136 lines.push(...rawLines);
102137 }
103138
104- // Paint lines, clipped to rect
139+ // Paint lines, clipped to rect (grapheme-aware)
105140 for (let row = 0; row < lines.length && row < h; row++) {
106141 const line = lines[row]!;
107- for (let col = 0; col < line.length && col < w; col++) {
108- buf.set(x + col, y + row, makeCell(line[col]!, props));
109- }
142+ paintLineGraphemes(line, x, y + row, w, props, buf);
110143 }
111144 }
112145
@@ -130,7 +163,7 @@ function paintTextInput(
130163 // Word-wrap value (always on for TextInput)
131164 const lines: string[] = [];
132165 for (const rawLine of value.split("\n")) {
133- if (rawLine.length <= w) {
166+ if (visibleWidth(rawLine) <= w) {
134167 lines.push(rawLine);
135168 } else {
136169 wrapLine(rawLine, w, lines);
@@ -140,14 +173,12 @@ function paintTextInput(
140173 // Framework-managed scroll: use stored scroll offset
141174 const scrollOffset = getTextInputScroll(props);
142175
143- // Paint visible lines
176+ // Paint visible lines (grapheme-aware)
144177 for (let row = 0; row < h; row++) {
145178 const lineIdx = scrollOffset + row;
146179 if (lineIdx >= lines.length) break;
147180 const line = lines[lineIdx]!;
148- for (let col = 0; col < line.length && col < w; col++) {
149- buf.set(x + col, y + row, makeCell(line[col]!, props));
150- }
181+ paintLineGraphemes(line, x, y + row, w, props, buf);
151182 }
152183
153184 // Paint cursor if focused
@@ -188,14 +219,18 @@ function offsetToWrappedPos(
188219 // Cursor is in this raw line
189220 const colInRaw = cursor - offset;
190221 if (width <= 0) return { line: wrappedLine, col: colInRaw };
191- const extraLines = Math.floor(colInRaw / width);
192- return { line: wrappedLine + extraLines, col: colInRaw % width };
222+ // Compute visible width of text before cursor
223+ const textBeforeCursor = rawLine.slice(0, colInRaw);
224+ const vw = visibleWidth(textBeforeCursor);
225+ const extraLines = Math.floor(vw / width);
226+ return { line: wrappedLine + extraLines, col: vw % width };
193227 }
194228 // Count wrapped lines for this raw line
195- if (rawLine.length <= width || width <= 0) {
229+ const lineVW = visibleWidth(rawLine);
230+ if (lineVW <= width || width <= 0) {
196231 wrappedLine += 1;
197232 } else {
198- wrappedLine += Math.ceil(rawLine.length / width);
233+ wrappedLine += Math.ceil(lineVW / width);
199234 }
200235 offset += rawLine.length + 1; // +1 for \n
201236 }
@@ -241,22 +276,46 @@ function wrapLine(line: string, width: number, out: string[]): void {
241276 if (width <= 0) return;
242277
243278 let current = "";
279+ let currentW = 0;
244280 const words = line.split(" ");
245281
246282 for (const word of words) {
247- if (current.length === 0) {
283+ const wordW = visibleWidth(word);
284+ if (currentW === 0) {
248285 current = word;
249- } else if (current.length + 1 + word.length <= width) {
286+ currentW = wordW;
287+ } else if (currentW + 1 + wordW <= width) {
250288 current += " " + word;
289+ currentW += 1 + wordW;
251290 } else {
252291 out.push(current);
253292 current = word;
293+ currentW = wordW;
254294 }
255295
256- // Handle words longer than width (break by character)
257- while (current.length > width) {
258- out.push(current.slice(0, width));
259- current = current.slice(width);
296+ // Handle words longer than width (break by grapheme)
297+ while (currentW > width) {
298+ let taken = "";
299+ let takenW = 0;
300+ let rest = "";
301+ let inRest = false;
302+ for (const { segment } of segmenter.segment(current)) {
303+ if (inRest) {
304+ rest += segment;
305+ continue;
306+ }
307+ const gw = visibleWidth(segment);
308+ if (takenW + gw > width) {
309+ rest += segment;
310+ inRest = true;
311+ } else {
312+ taken += segment;
313+ takenW += gw;
314+ }
315+ }
316+ out.push(taken);
317+ current = rest;
318+ currentW = visibleWidth(rest);
260319 }
261320 }