From 15f8238f83c266dd4d37ca01c4cdbe18ee22c2a7 Mon Sep 17 00:00:00 2001 From: Afzal Ahmad Date: Tue, 17 Nov 2026 16:37:59 +0100 Subject: [PATCH] JSE-F5: sheet names count code points, as Excel does Excel for Mac accepts a sheet name of 30 x's and an emoji: 31 code points, 32 UTF-16 units (conformance check, 2026-11-17). The validator counted UTF-16 units (name.length > 31), so the writer rejected names Excel accepts. - validateSheetName (and so the writer) counts code points. - sanitizeSheetName cuts to 31 code points, never splitting a surrogate pair, and still drops an apostrophe the cut leaves at the end. - History stays reserved in any case; sanitize turns it into "Sheet", which react-data-export's legacy components rely on. - Tests: 30 x + emoji accepted, 31 x + emoji rejected, 31 and 32 emoji, truncation, the writer end to end. --- .changeset/sheet-names-code-points.md | 5 ++++ docs/api.md | 4 ++-- packages/javascript-excel/src/sheet-names.ts | 23 +++++++++++------- .../test/write/writer-features.test.ts | 24 ++++++++++++++++++- 4 files changed, 44 insertions(+), 12 deletions(-) create mode 100644 .changeset/sheet-names-code-points.md diff --git a/.changeset/sheet-names-code-points.md b/.changeset/sheet-names-code-points.md new file mode 100644 index 0000000..fd551f1 --- /dev/null +++ b/.changeset/sheet-names-code-points.md @@ -0,0 +1,5 @@ +--- +"javascript-excel": patch +--- + +Sheet names are limited to 31 code points, as in Excel, instead of 31 UTF-16 units. `validateSheetName`, the writer and `sanitizeSheetName` now accept a name such as 30 letters plus an emoji (Excel for Mac accepts it), and `sanitizeSheetName` cuts long names to 31 code points without splitting a surrogate pair. `History` stays reserved in any case (Excel refuses it), and `sanitizeSheetName` turns it into `Sheet`. diff --git a/docs/api.md b/docs/api.md index dd90f1f..2a404d1 100644 --- a/docs/api.md +++ b/docs/api.md @@ -227,7 +227,7 @@ export type ColumnWidth = number | { wch: number } | { wpx: number } | 'auto'; **Sheet names.** The writer throws `INVALID_SHEET_NAME` unless the name: -- is 1 to 31 characters long. Excel counts code points: it accepts 30 x's and ๐Ÿ˜€, which is 31 code points and 32 UTF-16 units *(confirmed in Excel for Mac, 2026-11-17; conformance.md, 17-workbook)*. The writer still counts UTF-16 units (`name.length`), so it rejects such a name although Excel accepts it; +- is 1 to 31 characters long. Excel counts code points: it accepts 30 x's and ๐Ÿ˜€, which is 31 code points and 32 UTF-16 units *(confirmed in Excel for Mac, 2026-11-17; conformance.md, 17-workbook)*. `validateSheetName`, the writer and `sanitizeSheetName` count code points too (from 2.0.0-beta.1; before, they counted UTF-16 units and rejected such names); - contains none of `\ / ? * [ ] :`; - does not start or end with an apostrophe `'`; - is not `History`, which Excel reserves: renaming a tab to it gives "History is a reserve word" *(confirmed in Excel for Mac, 2026-11-17; conformance.md, 17-workbook)*. The check ignores case (`history`, `HISTORY`); only `History` itself was tried in Excel. @@ -724,7 +724,7 @@ export function serialToDate(serial: number, opts?: { date1904?: boolean; dateZo ### 4.6 Names ```ts -/** Replaces forbidden characters with '_', trims apostrophes, truncates to 31, falls back to 'Sheet'. */ +/** Replaces forbidden characters with '_', trims apostrophes, truncates to 31 code points (never splitting a surrogate pair), falls back to 'Sheet' (also for 'History'). */ export function sanitizeSheetName(name: string): string; /** Returns null when valid, or the reason. */ export function validateSheetName(name: string): null | 'empty' | 'too-long' | 'forbidden-char' | 'apostrophe' | 'reserved'; diff --git a/packages/javascript-excel/src/sheet-names.ts b/packages/javascript-excel/src/sheet-names.ts index 179a43d..d3e3a9f 100644 --- a/packages/javascript-excel/src/sheet-names.ts +++ b/packages/javascript-excel/src/sheet-names.ts @@ -1,7 +1,8 @@ /** * Sheet-name rules (docs/api.md ยง3.3, ยง4.6). * - * Excel rejects names that are empty, longer than 31 characters, contain any + * Excel rejects names that are empty, longer than 31 characters (code points, + * not UTF-16 units: 30 x's and an emoji are accepted), contain any * of \ / ? * [ ] :, or start or end with an apostrophe. It reserves 'History' * (Excel for Mac: "History is a reserve word"); the check here ignores case. * Names are unique case-insensitively (checked by the writer). @@ -12,11 +13,19 @@ export type SheetNameProblem = "empty" | "too-long" | "forbidden-char" | "apostr const FORBIDDEN = /[\\/?*[\]:]/; const FORBIDDEN_ALL = /[\\/?*[\]:]/g; +const MAX_LENGTH = 31; + +/** Length in code points, as Excel counts sheet names (a surrogate pair is one). */ +function codePoints(s: string): number { + let n = 0; + for (const _ of s) n++; + return n; +} /** Returns null when `name` is a valid sheet name, or the reason it is not. */ export function validateSheetName(name: string): SheetNameProblem | null { if (typeof name !== "string" || name.length === 0) return "empty"; - if (name.length > 31) return "too-long"; + if (codePoints(name) > MAX_LENGTH) return "too-long"; if (FORBIDDEN.test(name)) return "forbidden-char"; if (name.startsWith("'") || name.endsWith("'")) return "apostrophe"; if (name.toLowerCase() === "history") return "reserved"; @@ -26,15 +35,11 @@ export function validateSheetName(name: string): SheetNameProblem | null { /** * Makes any string a valid sheet name: forbidden characters become '_', * leading and trailing apostrophes are removed, the result is cut to 31 - * characters (without splitting a surrogate pair), and an empty or reserved - * result becomes 'Sheet'. Uniqueness is the caller's job. + * code points (never splitting a surrogate pair), and an empty or reserved + * result ('History' in any case) becomes 'Sheet'. Uniqueness is the caller's job. */ export function sanitizeSheetName(name: string): string { let s = String(name ?? "").replace(FORBIDDEN_ALL, "_").replace(/^'+|'+$/g, ""); - if (s.length > 31) { - s = s.slice(0, 31); - if (/[\uD800-\uDBFF]$/.test(s)) s = s.slice(0, 30); - s = s.replace(/'+$/, ""); - } + if (codePoints(s) > MAX_LENGTH) s = Array.from(s).slice(0, MAX_LENGTH).join("").replace(/'+$/, ""); return s.length === 0 || s.toLowerCase() === "history" ? "Sheet" : s; } diff --git a/packages/javascript-excel/test/write/writer-features.test.ts b/packages/javascript-excel/test/write/writer-features.test.ts index 4f83021..9cde110 100644 --- a/packages/javascript-excel/test/write/writer-features.test.ts +++ b/packages/javascript-excel/test/write/writer-features.test.ts @@ -292,7 +292,29 @@ describe("sheet names (ยง4.6)", () => { expect(out[1]).toBe("quoted"); expect([out[2], out[3], out[6]]).toEqual(["Sheet", "Sheet", "Sheet"]); expect(out[4]).toHaveLength(31); - expect(out[5]).toBe("x".repeat(30)); // a surrogate pair is never split + expect(out[5]).toBe(`${"x".repeat(30)}๐Ÿ˜€`); // 31 code points: already valid for (const name of out) expect(validateSheetName(name)).toBeNull(); }); + + it("counts code points, as Excel does: 30 x's and an emoji fit, 31 x's and an emoji don't", () => { + expect(validateSheetName(`${"x".repeat(30)}๐Ÿ˜€`)).toBeNull(); // 31 code points, 32 UTF-16 units + expect(validateSheetName(`${"x".repeat(31)}๐Ÿ˜€`)).toBe("too-long"); + expect(validateSheetName("๐Ÿ˜€".repeat(31))).toBeNull(); + expect(validateSheetName("๐Ÿ˜€".repeat(32))).toBe("too-long"); + }); + + it("sanitizeSheetName cuts to 31 code points without splitting a surrogate pair", () => { + expect(sanitizeSheetName(`${"x".repeat(31)}๐Ÿ˜€`)).toBe("x".repeat(31)); + expect(sanitizeSheetName(`${"x".repeat(30)}๐Ÿ˜€๐Ÿ˜€`)).toBe(`${"x".repeat(30)}๐Ÿ˜€`); + expect(sanitizeSheetName("๐Ÿ˜€".repeat(40))).toBe("๐Ÿ˜€".repeat(31)); + expect(sanitizeSheetName(`${"x".repeat(30)}'y`)).toBe("x".repeat(30)); // the cut leaves a trailing apostrophe, which goes + for (const name of ["History", "HISTORY", "history"]) expect(sanitizeSheetName(name)).toBe("Sheet"); + }); + + it("the writer accepts a 31-code-point name with an emoji", async () => { + const name = `${"x".repeat(30)}๐Ÿ˜€`; + const bytes = await toUint8Array({ sheets: [{ name, rows: [["a"]] }] }); + expect(bytes.length).toBeGreaterThan(0); + await expect(toUint8Array({ sheets: [{ name: `${name}x`, rows: [] }] })).rejects.toMatchObject({ code: "INVALID_SHEET_NAME" }); + }); });