xonecas.io
70160
Ce

cel-tui / commit fa34bca

feat(core): implement visibleWidth with grapheme segmentation

- Fast ASCII path (width = string.length)
- East Asian width lookup via get-east-asian-width
- Emoji detection (RGI_Emoji regex with fast pre-filter)
- ANSI escape stripping (CSI, OSC, APC sequences)
- Zero-width character handling (control, marks, ignorables)
- LRU cache (512 entries) for non-ASCII results
- 23 tests covering ASCII, CJK, emoji, ANSI, mixed content

xonecas2026-04-03 fa34bcabb4475d74ed1c889f6e634529b75c4d2f parent ff91bdc

5 files changed

AGENTS.md+21−0
@@ -71,6 +71,27 @@ Use `bun test` (built-in test runner, no extra deps). Test files live next to so
7171 - Terminal I/O (assert emitted ANSI sequences against an in-memory buffer)
7272 - End-to-end pipeline (`cel.viewport` → rendered output)
7373
74+## Commit Format
75+
76+Use [Conventional Commits](https://www.conventionalcommits.org/):
77+
78+```
79+<type>(<scope>): <description>
80+```
81+
82+**Types:** `feat`, `fix`, `test`, `refactor`, `docs`, `chore`, `style`
83+
84+**Scopes:** `types`, `core`, `components`, `spec`, or omit for repo-wide changes.
85+
86+**Examples:**
87+
88+```
89+feat(core): implement visibleWidth with grapheme segmentation
90+test(core): add character width tests for CJK, emoji, ANSI
91+docs(spec): define Text primitive styling and wrapping
92+chore: scaffold monorepo with types, core, components packages
93+```
94+
7495 ## Conventions
7596
7697 - All code is TypeScript with strict mode
bun.lock+3−0
@@ -6,6 +6,7 @@
66 "name": "cel-tui",
77 "devDependencies": {
88 "@biomejs/biome": "^2.4.10",
9+ "get-east-asian-width": "^1.5.0",
910 "prettier": "^3.8.1",
1011 "typescript": "^6.0.2",
1112 },
@@ -55,6 +56,8 @@
5556
5657 "@cel-tui/types": ["@cel-tui/types@workspace:packages/types"],
5758
59+ "get-east-asian-width": ["get-east-asian-width@1.5.0", "", {}, "sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA=="],
60+
5861 "prettier": ["prettier@3.8.1", "", { "bin": { "prettier": "bin/prettier.cjs" } }, "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg=="],
5962
6063 "typescript": ["typescript@6.0.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ=="],
package.json+1−0
@@ -13,6 +13,7 @@
1313 },
1414 "devDependencies": {
1515 "@biomejs/biome": "^2.4.10",
16+ "get-east-asian-width": "^1.5.0",
1617 "prettier": "^3.8.1",
1718 "typescript": "^6.0.2"
1819 }
packages/core/src/width.test.ts+111−0
@@ -0,0 +1,111 @@
1+import { describe, expect, test } from "bun:test";
2+import { visibleWidth } from "./width.js";
3+
4+describe("visibleWidth", () => {
5+ describe("ASCII fast path", () => {
6+ test("empty string", () => {
7+ expect(visibleWidth("")).toBe(0);
8+ });
9+
10+ test("simple ASCII", () => {
11+ expect(visibleWidth("hello")).toBe(5);
12+ });
13+
14+ test("ASCII with spaces", () => {
15+ expect(visibleWidth("hello world")).toBe(11);
16+ });
17+
18+ test("ASCII punctuation", () => {
19+ expect(visibleWidth("a-b_c.d")).toBe(7);
20+ });
21+
22+ test("single character", () => {
23+ expect(visibleWidth("x")).toBe(1);
24+ });
25+ });
26+
27+ describe("East Asian wide characters", () => {
28+ test("CJK characters are width 2", () => {
29+ expect(visibleWidth("世界")).toBe(4);
30+ });
31+
32+ test("mixed ASCII and CJK", () => {
33+ expect(visibleWidth("hi世界")).toBe(6);
34+ });
35+
36+ test("fullwidth punctuation", () => {
37+ expect(visibleWidth("!")).toBe(2);
38+ });
39+ });
40+
41+ describe("emoji", () => {
42+ test("simple emoji is width 2", () => {
43+ expect(visibleWidth("😀")).toBe(2);
44+ });
45+
46+ test("emoji in text", () => {
47+ expect(visibleWidth("hi 😀 there")).toBe(11);
48+ });
49+
50+ test("ZWJ emoji sequence", () => {
51+ expect(visibleWidth("👨‍👩‍👧")).toBe(2);
52+ });
53+
54+ test("flag emoji", () => {
55+ expect(visibleWidth("🇺🇸")).toBe(2);
56+ });
57+
58+ test("emoji with skin tone", () => {
59+ expect(visibleWidth("👋🏽")).toBe(2);
60+ });
61+ });
62+
63+ describe("ANSI escape sequences", () => {
64+ test("CSI SGR codes are zero width", () => {
65+ expect(visibleWidth("\x1b[31mred\x1b[0m")).toBe(3);
66+ });
67+
68+ test("bold + color", () => {
69+ expect(visibleWidth("\x1b[1;34mblue\x1b[0m")).toBe(4);
70+ });
71+
72+ test("256 color", () => {
73+ expect(visibleWidth("\x1b[38;5;240mgray\x1b[0m")).toBe(4);
74+ });
75+
76+ test("RGB color", () => {
77+ expect(visibleWidth("\x1b[38;2;255;128;0morange\x1b[0m")).toBe(6);
78+ });
79+
80+ test("only ANSI codes, no visible content", () => {
81+ expect(visibleWidth("\x1b[31m\x1b[0m")).toBe(0);
82+ });
83+
84+ test("OSC hyperlink", () => {
85+ expect(
86+ visibleWidth("\x1b]8;;https://example.com\x07link\x1b]8;;\x07"),
87+ ).toBe(4);
88+ });
89+ });
90+
91+ describe("zero-width characters", () => {
92+ test("combining marks", () => {
93+ // e + combining acute accent = 1 grapheme, width 1
94+ expect(visibleWidth("e\u0301")).toBe(1);
95+ });
96+
97+ test("zero-width joiner", () => {
98+ expect(visibleWidth("\u200D")).toBe(0);
99+ });
100+ });
101+
102+ describe("mixed content", () => {
103+ test("CJK + ANSI + ASCII", () => {
104+ expect(visibleWidth("\x1b[1m世界\x1b[0m hello")).toBe(10);
105+ });
106+
107+ test("emoji + ANSI", () => {
108+ expect(visibleWidth("\x1b[32m😀\x1b[0m ok")).toBe(5);
109+ });
110+ });
111+});
packages/core/src/width.ts+174−0
@@ -0,0 +1,174 @@
1+import { eastAsianWidth } from "get-east-asian-width";
2+
3+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
4+
5+// --- ANSI escape extraction ---
6+
7+/**
8+ * Extract an ANSI escape sequence starting at `pos` in `str`.
9+ * Handles CSI (ESC [), OSC (ESC ]), and APC (ESC _) sequences.
10+ * Returns null if no escape sequence starts at `pos`.
11+ */
12+export function extractAnsiCode(
13+ str: string,
14+ pos: number,
15+): { code: string; length: number } | null {
16+ if (pos >= str.length || str[pos] !== "\x1b") return null;
17+
18+ const next = str[pos + 1];
19+
20+ // CSI: ESC [ ... <terminal byte>
21+ if (next === "[") {
22+ let j = pos + 2;
23+ while (j < str.length && !/[A-Za-z]/.test(str[j]!)) j++;
24+ if (j < str.length)
25+ return { code: str.substring(pos, j + 1), length: j + 1 - pos };
26+ return null;
27+ }
28+
29+ // OSC: ESC ] ... BEL or ESC ] ... ST
30+ if (next === "]") {
31+ let j = pos + 2;
32+ while (j < str.length) {
33+ if (str[j] === "\x07")
34+ return { code: str.substring(pos, j + 1), length: j + 1 - pos };
35+ if (str[j] === "\x1b" && str[j + 1] === "\\")
36+ return { code: str.substring(pos, j + 2), length: j + 2 - pos };
37+ j++;
38+ }
39+ return null;
40+ }
41+
42+ // APC: ESC _ ... BEL or ESC _ ... ST
43+ if (next === "_") {
44+ let j = pos + 2;
45+ while (j < str.length) {
46+ if (str[j] === "\x07")
47+ return { code: str.substring(pos, j + 1), length: j + 1 - pos };
48+ if (str[j] === "\x1b" && str[j + 1] === "\\")
49+ return { code: str.substring(pos, j + 2), length: j + 2 - pos };
50+ j++;
51+ }
52+ return null;
53+ }
54+
55+ return null;
56+}
57+
58+// --- Grapheme width ---
59+
60+const zeroWidthRegex =
61+ /^(?:\p{Default_Ignorable_Code_Point}|\p{Control}|\p{Mark}|\p{Surrogate})+$/v;
62+const leadingNonPrintingRegex =
63+ /^[\p{Default_Ignorable_Code_Point}\p{Control}\p{Format}\p{Mark}\p{Surrogate}]+/v;
64+const rgiEmojiRegex = /^\p{RGI_Emoji}$/v;
65+
66+function couldBeEmoji(segment: string): boolean {
67+ const cp = segment.codePointAt(0)!;
68+ return (
69+ (cp >= 0x1f000 && cp <= 0x1fbff) ||
70+ (cp >= 0x2300 && cp <= 0x23ff) ||
71+ (cp >= 0x2600 && cp <= 0x27bf) ||
72+ (cp >= 0x2b50 && cp <= 0x2b55) ||
73+ segment.includes("\uFE0F") ||
74+ segment.length > 2
75+ );
76+}
77+
78+/**
79+ * Calculate the terminal width of a single grapheme cluster.
80+ */
81+function graphemeWidth(segment: string): number {
82+ if (zeroWidthRegex.test(segment)) return 0;
83+
84+ if (couldBeEmoji(segment) && rgiEmojiRegex.test(segment)) return 2;
85+
86+ const base = segment.replace(leadingNonPrintingRegex, "");
87+ const cp = base.codePointAt(0);
88+ if (cp === undefined) return 0;
89+
90+ // Regional indicator symbols
91+ if (cp >= 0x1f1e6 && cp <= 0x1f1ff) return 2;
92+
93+ let width = eastAsianWidth(cp);
94+
95+ if (segment.length > 1) {
96+ for (const char of segment.slice(1)) {
97+ const c = char.codePointAt(0)!;
98+ if (c >= 0xff00 && c <= 0xffef) {
99+ width += eastAsianWidth(c);
100+ }
101+ }
102+ }
103+
104+ return width;
105+}
106+
107+// --- ASCII fast path ---
108+
109+function isPrintableAscii(str: string): boolean {
110+ for (let i = 0; i < str.length; i++) {
111+ const code = str.charCodeAt(i);
112+ if (code < 0x20 || code > 0x7e) return false;
113+ }
114+ return true;
115+}
116+
117+// --- Cache ---
118+
119+const WIDTH_CACHE_SIZE = 512;
120+const widthCache = new Map<string, number>();
121+
122+// --- Public API ---
123+
124+/**
125+ * Calculate the visible width of a string in terminal columns.
126+ *
127+ * Handles ASCII (fast path), East Asian wide characters, emoji,
128+ * ANSI escape sequences, and zero-width characters.
129+ *
130+ * @param str - The string to measure.
131+ * @returns Width in terminal columns.
132+ */
133+export function visibleWidth(str: string): number {
134+ if (str.length === 0) return 0;
135+
136+ // Fast path: pure printable ASCII
137+ if (isPrintableAscii(str)) return str.length;
138+
139+ // Check cache
140+ const cached = widthCache.get(str);
141+ if (cached !== undefined) return cached;
142+
143+ // Strip ANSI escapes
144+ let clean = str;
145+ if (clean.includes("\x1b")) {
146+ let stripped = "";
147+ let i = 0;
148+ while (i < clean.length) {
149+ const ansi = extractAnsiCode(clean, i);
150+ if (ansi) {
151+ i += ansi.length;
152+ continue;
153+ }
154+ stripped += clean[i];
155+ i++;
156+ }
157+ clean = stripped;
158+ }
159+
160+ // Sum grapheme widths
161+ let width = 0;
162+ for (const { segment } of segmenter.segment(clean)) {
163+ width += graphemeWidth(segment);
164+ }
165+
166+ // Cache
167+ if (widthCache.size >= WIDTH_CACHE_SIZE) {
168+ const firstKey = widthCache.keys().next().value;
169+ if (firstKey !== undefined) widthCache.delete(firstKey);
170+ }
171+ widthCache.set(str, width);
172+
173+ return width;
174+}