@cj-tech-master/excelts 9.5.8 → 9.5.9

package/dist/cjs/modules/excel/xlsx/xform/book/workbook-xform.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkbookXform = void 0;
+const errors_1 = require("../../../errors.js");
 const col_cache_1 = require("../../../utils/col-cache.js");
 const ooxml_paths_1 = require("../../../utils/ooxml-paths.js");
 const base_xform_1 = require("../base-xform.js");
@@ -92,43 +93,70 @@ class WorkbookXform extends base_xform_1.BaseXform {
             model.sheets = withIndex.map(entry => entry.sheet);
         }
         // collate all the print areas from all of the sheets and add them to the defined names
+        //
+        // OOXML (ECMA-376 §18.2.5) requires that the (name, localSheetId) pair
+        // is unique within `<definedNames>` — so multiple print areas on the
+        // same sheet must collapse into a *single* `<definedName>` whose text
+        // is a comma-separated list of ranges (the format Excel itself emits).
+        // The `printArea` field uses `&&` as the multi-range separator (a
+        // historical convention preserved for backwards compatibility); we
+        // also accept commas so users can paste Excel's native format.
+        //
+        // Both `printArea` and the `printTitlesRow`/`printTitlesColumn` fields
+        // are normalised through `parsePrintReference` before being emitted.
+        // This means the writer accepts any of the forms Excel itself accepts
+        // — `A1`, `A1:B5`, `$A$1:$B$5`, `a1:b5`, ` A1 : B5 `, `Sheet!A1:B5`,
+        // `'Q,F'!A1:B5`, whole-row `1:5`, whole-column `A:C` — and always
+        // emits the canonical `$col$row[:$col$row]` shape that Excel
+        // round-trips faithfully. Without normalisation, the previous
+        // string-concatenation path produced `$$A$1` for a `$A$1` input
+        // (corrupt), `$a1` for a `a1` input (Excel rejects), and
+        // `$A1:$B5` row-relative (semantically wrong for a print area).
         const printAreas = [];
         let index = 0; // sheets is sparse array - calc index manually
         model.sheets.forEach((sheet) => {
             if (sheet.pageSetup && sheet.pageSetup.printArea) {
-                sheet.pageSetup.printArea.split("&&").forEach((printArea) => {
-                    const printAreaComponents = printArea.split(":");
-                    const start = printAreaComponents[0];
-                    const end = printAreaComponents[1] ?? start;
-                    const definedName = {
+                const ranges = [];
+                // Split on either `&&` (legacy excelts separator) or `,` (Excel's
+                // native separator) at the *top level* — commas / `&&` inside a
+                // quoted sheet name (`'Q1, Forecast'!A1:B5`) must NOT be treated
+                // as separators. A naive `split(/&&|,/)` shreds such inputs.
+                for (const segment of splitPrintAreaInput(sheet.pageSetup.printArea)) {
+                    const normalised = normalisePrintAreaRange(segment, sheet.name);
+                    if (normalised) {
+                        ranges.push(normalised);
+                    }
+                }
+                if (ranges.length > 0) {
+                    printAreas.push({
                         name: "_xlnm.Print_Area",
-                        ranges: [`'${sheet.name}'!$${start}:$${end}`],
+                        ranges,
                         localSheetId: index
-                    };
-                    printAreas.push(definedName);
-                });
+                    });
+                }
             }
             if (sheet.pageSetup &&
                 (sheet.pageSetup.printTitlesRow || sheet.pageSetup.printTitlesColumn)) {
                 const ranges = [];
                 if (sheet.pageSetup.printTitlesColumn) {
-                    const titlesColumns = sheet.pageSetup.printTitlesColumn.split(":");
-                    const start = titlesColumns[0];
-                    const end = titlesColumns[1] ?? start;
-                    ranges.push(`'${sheet.name}'!$${start}:$${end}`);
+                    const normalised = normalisePrintTitlesAxis(sheet.pageSetup.printTitlesColumn, sheet.name);
+                    if (normalised) {
+                        ranges.push(normalised);
+                    }
                 }
                 if (sheet.pageSetup.printTitlesRow) {
-                    const titlesRows = sheet.pageSetup.printTitlesRow.split(":");
-                    const start = titlesRows[0];
-                    const end = titlesRows[1] ?? start;
-                    ranges.push(`'${sheet.name}'!$${start}:$${end}`);
+                    const normalised = normalisePrintTitlesAxis(sheet.pageSetup.printTitlesRow, sheet.name);
+                    if (normalised) {
+                        ranges.push(normalised);
+                    }
+                }
+                if (ranges.length > 0) {
+                    printAreas.push({
+                        name: "_xlnm.Print_Titles",
+                        ranges,
+                        localSheetId: index
+                    });
                 }
-                const definedName = {
-                    name: "_xlnm.Print_Titles",
-                    ranges,
-                    localSheetId: index
-                };
-                printAreas.push(definedName);
             }
             index++;
         });
@@ -334,10 +362,14 @@ class WorkbookXform extends base_xform_1.BaseXform {
             model.definedNames.forEach((definedName) => {
                 // For print area/titles, use rawText to extract ranges since the xform
                 // layer no longer pre-classifies content (two-phase design).
+                // When falling back to rawText we must split on top-level commas
+                // (commas inside a quoted sheet name like `'Q1, Forecast'!$A$1` do
+                // *not* delimit ranges), so a naive `rawText.split(",")` is wrong
+                // and would mis-split sheet names with embedded commas.
                 const effectiveRanges = definedName.ranges?.length > 0
                     ? definedName.ranges
                     : definedName.rawText
-                        ? [definedName.rawText]
+                        ? splitPrintAreaInput(definedName.rawText)
                         : [];
                 if (definedName.name === "_xlnm.Print_Area") {
                     worksheet = worksheets[definedName.localSheetId];
@@ -345,10 +377,52 @@ class WorkbookXform extends base_xform_1.BaseXform {
                         if (!worksheet.pageSetup) {
                             worksheet.pageSetup = {};
                         }
-                        const range = col_cache_1.colCache.decodeEx(effectiveRanges[0]);
-                        worksheet.pageSetup.printArea = worksheet.pageSetup.printArea
-                            ? `${worksheet.pageSetup.printArea}&&${range.dimensions}`
-                            : range.dimensions;
+                        // A print-area `<definedName>` may carry multiple ranges as a
+                        // comma-separated list (Excel's native format) — read every
+                        // range, not just the first. Rejoin with `&&` so the
+                        // worksheet-level `printArea` field uses the legacy excelts
+                        // separator (preserved for backwards compatibility on the
+                        // public API; both `&&` and `,` are accepted on write).
+                        //
+                        // Route through the same `parsePrintReference` the writer
+                        // uses so every legitimate Excel reference shape (cell,
+                        // range, whole-row, whole-column) round-trips. The previous
+                        // implementation called `colCache.decodeEx` directly, which
+                        // returns a `NaN`-laced result for whole-row/column inputs
+                        // (those are not cell addresses) — those legitimate shapes
+                        // came back as `"NaN:NaN"` on the worksheet model.
+                        const decoded = [];
+                        for (const rangeStr of effectiveRanges) {
+                            // Wrap in try/catch: `parsePrintReference` throws
+                            // `ColumnOutOfBoundsError` (column past XFD) or
+                            // `RowOutOfBoundsError` (row 0 or row past 1048576) for
+                            // out-of-range refs. On the *write* side that throw
+                            // surfaces a user error, but on this *read* side a
+                            // malformed file (or one authored by another tool) must
+                            // not blow up the whole load — drop the bad range and
+                            // continue.
+                            let ref;
+                            try {
+                                ref = parsePrintReference(rangeStr);
+                            }
+                            catch {
+                                ref = undefined;
+                            }
+                            if (!ref) {
+                                continue;
+                            }
+                            // Promote a bare cell to a degenerate range so the
+                            // worksheet `printArea` field is always a range string —
+                            // that's the documented API contract and matches what
+                            // Excel itself emits for single-cell print areas.
+                            decoded.push(ref.kind === "cell" ? `${ref.dimensions}:${ref.dimensions}` : ref.dimensions);
+                        }
+                        if (decoded.length > 0) {
+                            const joined = decoded.join("&&");
+                            worksheet.pageSetup.printArea = worksheet.pageSetup.printArea
+                                ? `${worksheet.pageSetup.printArea}&&${joined}`
+                                : joined;
+                        }
                     }
                 }
                 else if (definedName.name === "_xlnm.Print_Titles") {
@@ -406,3 +480,306 @@ WorkbookXform.STATIC_XFORMS = {
         $: { appName: "xl", lastEdited: 5, lowestEdited: 5, rupBuild: 9303 }
     })
 };
+/**
+ * Split a print-area string on its multi-range separators while honouring
+ * single-quoted sheet name segments.
+ *
+ * Used by both the writer (parsing user-supplied `printArea` values) and
+ * the reader (parsing the body of an OOXML `<definedName>` when the
+ * defined-name layer hands us the raw text). Recognises both:
+ *   - `,` — the OOXML / Excel-native separator
+ *   - `&&` — the legacy excelts convention preserved on the public API
+ *
+ * Quoted sheet names (`'Q1, Forecast'!A1:B5`) are skipped over: any `,`,
+ * `&`, or `'` inside a quoted name is preserved verbatim. A doubled
+ * apostrophe inside a quoted segment (`''`) is the OOXML escape for a
+ * literal apostrophe and does not terminate the quote.
+ *
+ * Empty / whitespace-only segments are dropped; the caller normalises
+ * each surviving segment further with `parsePrintReference`.
+ */
+function splitPrintAreaInput(input) {
+    const result = [];
+    let current = "";
+    let inQuote = false;
+    for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === "'") {
+            // Doubled apostrophe inside a quoted segment is an escaped literal.
+            if (inQuote && input[i + 1] === "'") {
+                current += "''";
+                i++;
+                continue;
+            }
+            inQuote = !inQuote;
+            current += ch;
+            continue;
+        }
+        if (!inQuote) {
+            if (ch === ",") {
+                if (current.trim()) {
+                    result.push(current);
+                }
+                current = "";
+                continue;
+            }
+            if (ch === "&" && input[i + 1] === "&") {
+                if (current.trim()) {
+                    result.push(current);
+                }
+                current = "";
+                i++; // skip the second `&`
+                continue;
+            }
+        }
+        current += ch;
+    }
+    if (current.trim()) {
+        result.push(current);
+    }
+    return result;
+}
+/**
+ * Quote a sheet name for inclusion in an OOXML defined-name reference.
+ *
+ * Per ECMA-376 §18.17 sheet names that contain spaces or any character
+ * outside `[A-Za-z0-9_]` MUST be wrapped in single quotes; a literal
+ * apostrophe inside the name is doubled. We always quote — over-quoting
+ * is harmless (Excel parses both forms) and keeps the writer trivial.
+ */
+function quoteSheetName(sheetName) {
+    return `'${sheetName.replace(/'/g, "''")}'`;
+}
+/**
+ * Find the index of the first `!` that lies outside any single-quoted
+ * sheet-name segment, or `-1` if no unquoted `!` is present.
+ *
+ * Sheet names quoted with `'` may contain unbalanced characters, so we
+ * walk the string honouring quote toggles before declaring a `!` to be
+ * the sheet/address separator. Doubled apostrophes (`''`) inside a
+ * quoted name are treated as a literal apostrophe per OOXML.
+ */
+function findUnquotedExclamation(value) {
+    let inQuote = false;
+    for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (ch === "'") {
+            if (inQuote && value[i + 1] === "'") {
+                i++;
+                continue;
+            }
+            inQuote = !inQuote;
+        }
+        else if (ch === "!" && !inQuote) {
+            return i;
+        }
+    }
+    return -1;
+}
+// Excel 2007+ row limit. Print-area / print-titles references emitted
+// to OOXML must respect this — Excel rejects definitions that point
+// past the addressable sheet, so the writer normalises every row
+// through `parseRowToken` (which throws `RowOutOfBoundsError` on
+// overflow). The rest of the codebase tolerates higher row numbers in
+// transient API calls (`getCell("A99999999")`) because those never
+// reach the file format; print references do.
+const EXCEL_MAX_ROW = 1048576;
+/**
+ * Parse a row token (the digits portion of a cell reference, or a
+ * whole-row number) into a canonical integer string.
+ *
+ * Rejects:
+ *   - row 0 (Excel rows are 1-indexed; `$A$0` is never a valid Excel ref)
+ *   - rows beyond `EXCEL_MAX_ROW` (Excel hard limit)
+ *
+ * Normalises:
+ *   - leading zeros (`001` → `1`) — OOXML expects bare integers, and
+ *     `Number(...)` collapses any padding the user typed.
+ */
+function parseRowToken(token) {
+    // The caller has already matched the token against `\d+`, so `Number`
+    // is safe (no NaN). We re-emit the canonical decimal form to drop
+    // leading zeros the user typed.
+    const n = Number(token);
+    if (n < 1) {
+        throw new errors_1.RowOutOfBoundsError(n, `Excel rows are 1-indexed; row ${token} is invalid`);
+    }
+    if (n > EXCEL_MAX_ROW) {
+        throw new errors_1.RowOutOfBoundsError(n, `Excel supports rows from 1 to ${EXCEL_MAX_ROW}`);
+    }
+    return String(n);
+}
+/**
+ * Parse a single user- or OOXML-supplied print reference into one of
+ * Excel's four valid shapes (cell / range / row / column), discarding
+ * any sheet prefix the input carries. Both the writer and the reader
+ * route through this single parser so the two sides agree on what is
+ * accepted and how it is canonicalised.
+ *
+ * Accepts every form Excel itself accepts on input, regardless of which
+ * side calls it:
+ *   - cell: `A1`, `$A$1`, `Sheet1!$A$1`, `'Q,F'!$A$1`, `a1`
+ *   - range: `A1:B5`, `$A$1:$B$5`, `Sheet!A1:B5`, ` A1 : B5 `, `a1:b5`,
+ *     mixed `$A1:$B$5`, reversed `B5:A1` (canonicalised to `A1:B5`)
+ *   - whole row: `1:5`, `$1:$5`, `Sheet!$1:$5`, `5` (single row),
+ *     reversed `5:1` (canonicalised to `1:5`), padded `001:005`
+ *   - whole column: `A:C`, `$A:$C`, `Sheet!$A:$C`, `C` (single column),
+ *     `a:c`, reversed `C:A` (canonicalised to `A:C`)
+ *
+ * Returns `undefined` for inputs that do not match one of the four
+ * shapes — callers drop the entry rather than emit corrupt XML.
+ *
+ * **Throws**:
+ *   - `ColumnOutOfBoundsError` when the input parses as a valid shape
+ *     but references a column letter beyond Excel's XFD (16384) limit.
+ *   - `RowOutOfBoundsError` for row 0 (Excel rows are 1-indexed) or
+ *     rows beyond Excel's `1048576` limit.
+ *
+ * Both errors match what `getCell` and `colCache.l2n` already throw for
+ * the same inputs; surfacing them here means a user who hand-authors a
+ * malformed `printArea` finds out at write time rather than producing
+ * a workbook Excel silently rejects.
+ *
+ * Why a hand-rolled parser instead of `colCache.decodeEx`? `decodeEx`
+ * was designed for cell addresses and produces `NaN`-laced output for
+ * whole-row (`$1:$5`) and whole-column (`$A:$C`) references. Print
+ * areas and print titles legitimately use both, so we need a parser
+ * that recognises all four shapes uniformly *and* canonicalises
+ * reversed endpoints (which `decodeEx` does for cells but not for
+ * row/column references).
+ */
+function parsePrintReference(input) {
+    if (typeof input !== "string") {
+        return undefined;
+    }
+    const trimmed = input.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    // Strip the sheet prefix if present (we anchor by `localSheetId`,
+    // never by the prefix). Any prefix the caller supplies is discarded.
+    const exclamation = findUnquotedExclamation(trimmed);
+    const body = exclamation === -1 ? trimmed : trimmed.slice(exclamation + 1);
+    // Strip every `$`, every whitespace, and upper-case the remaining
+    // letters in one pass. This subsumes mixed/redundant `$` signs
+    // (`$A1:$B$5` → `A1:B5`), surrounding/internal whitespace
+    // (`A1 : B5` → `A1:B5`), and lowercase columns (`a1:b5` → `A1:B5`).
+    const cleaned = body.replace(/[\s$]+/g, "").toUpperCase();
+    if (!cleaned) {
+        return undefined;
+    }
+    const parts = cleaned.split(":");
+    if (parts.length > 2) {
+        return undefined;
+    }
+    const startRaw = parts[0];
+    const endRaw = parts.length === 2 ? parts[1] : startRaw;
+    // Cell shape: both endpoints are full `<col><row>` addresses.
+    const cellRe = /^([A-Z]+)(\d+)$/;
+    const startCell = cellRe.exec(startRaw);
+    const endCell = cellRe.exec(endRaw);
+    if (startCell && endCell) {
+        // Validate column letters against Excel's XFD (16384) limit and
+        // rows against the `1..1048576` band. `l2n` and `parseRowToken`
+        // throw the project-standard errors here so the caller (and end
+        // user) sees a familiar diagnosis when they hand-author a bad ref.
+        // We keep the column numbers around to canonicalise reversed
+        // endpoints below without a second lookup.
+        const startColNum = col_cache_1.colCache.l2n(startCell[1]);
+        const endColNum = col_cache_1.colCache.l2n(endCell[1]);
+        const startRow = Number(parseRowToken(startCell[2]));
+        const endRow = Number(parseRowToken(endCell[2]));
+        // Canonicalise reversed endpoints. Excel's UI never produces
+        // `B5:A1`, but a hand-authored input might; downstream consumers
+        // (PDF layout, the OOXML reader's sort comparators) assume
+        // top-left → bottom-right ordering, so we sort here once.
+        const tlCol = startColNum <= endColNum ? startCell[1] : endCell[1];
+        const brCol = startColNum <= endColNum ? endCell[1] : startCell[1];
+        const tlRow = startRow <= endRow ? startRow : endRow;
+        const brRow = startRow <= endRow ? endRow : startRow;
+        // A bare cell (no `:` in the input) is the only true `cell` shape.
+        // `A1:A1` — a `:`-bearing range whose endpoints happen to coincide —
+        // is reported as `range`, matching the user's typed intent and
+        // avoiding the question of whether `parts.length === 2 && tl === br`
+        // should round-trip as a cell or a degenerate range.
+        if (parts.length === 1) {
+            return {
+                kind: "cell",
+                ooxml: `$${tlCol}$${tlRow}`,
+                dimensions: `${tlCol}${tlRow}`
+            };
+        }
+        return {
+            kind: "range",
+            ooxml: `$${tlCol}$${tlRow}:$${brCol}$${brRow}`,
+            dimensions: `${tlCol}${tlRow}:${brCol}${brRow}`
+        };
+    }
+    // Whole-row shape: both endpoints are bare row numbers.
+    if (/^\d+$/.test(startRaw) && /^\d+$/.test(endRaw)) {
+        const startRow = Number(parseRowToken(startRaw));
+        const endRow = Number(parseRowToken(endRaw));
+        const tl = Math.min(startRow, endRow);
+        const br = Math.max(startRow, endRow);
+        return {
+            kind: "row",
+            ooxml: `$${tl}:$${br}`,
+            dimensions: `${tl}:${br}`
+        };
+    }
+    // Whole-column shape: both endpoints are bare column letters. We
+    // reuse `l2n`'s already-validated index to canonicalise reversed
+    // endpoints — `colCache.l2n` is the project-wide source of truth for
+    // column ordering.
+    if (/^[A-Z]+$/.test(startRaw) && /^[A-Z]+$/.test(endRaw)) {
+        const startNum = col_cache_1.colCache.l2n(startRaw);
+        const endNum = col_cache_1.colCache.l2n(endRaw);
+        const tl = startNum <= endNum ? startRaw : endRaw;
+        const br = startNum <= endNum ? endRaw : startRaw;
+        return {
+            kind: "col",
+            ooxml: `$${tl}:$${br}`,
+            dimensions: `${tl}:${br}`
+        };
+    }
+    return undefined;
+}
+/**
+ * Normalise a user-supplied `printArea` value into the canonical OOXML
+ * `'Sheet'!<ref>` form. Returns `undefined` for malformed input so the
+ * caller drops the entry instead of emitting corrupt XML.
+ *
+ * `printArea` accepts cell, range, whole-row, and whole-column shapes —
+ * Excel itself supports all four (e.g. selecting entire columns A:C as
+ * the print area is a common UI gesture). Bare cell inputs are promoted
+ * to a degenerate range `$A$1:$A$1` because that is what Excel itself
+ * emits for a single-cell print area, and the worksheet API exposes
+ * `printArea` as a range string (single-cell entries surface as `A1:A1`).
+ */
+function normalisePrintAreaRange(input, sheetName) {
+    const ref = parsePrintReference(input);
+    if (!ref) {
+        return undefined;
+    }
+    const ooxml = ref.kind === "cell" ? `${ref.ooxml}:${ref.ooxml}` : ref.ooxml;
+    return `${quoteSheetName(sheetName)}!${ooxml}`;
+}
+/**
+ * Normalise a user-supplied print-titles row or column expression into
+ * the canonical OOXML form `'Sheet'!$N:$N` (rows) or `'Sheet'!$L:$L`
+ * (columns).
+ *
+ * Long-standing excelts behaviour lets users put a column expression on
+ * `printTitlesRow` (and vice versa) — the OOXML reader has always
+ * re-classified the value onto the correct field on round-trip — so we
+ * honour that by letting the parser infer the actual axis from the
+ * input shape. Strict enforcement would silently drop print titles
+ * users have set successfully for years.
+ */
+function normalisePrintTitlesAxis(input, sheetName) {
+    const ref = parsePrintReference(input);
+    if (!ref || (ref.kind !== "row" && ref.kind !== "col")) {
+        return undefined;
+    }
+    return `${quoteSheetName(sheetName)}!${ref.ooxml}`;
+}

package/dist/esm/modules/excel/utils/col-cache.js

@@ -51,7 +51,15 @@ const colCache = {
         let l3;
         let n = 1;
         if (level >= 4) {
-            throw new ColumnOutOfBoundsError(level, "Excel supports columns from 1 to 16384");
+            // Defensive invariant: Excel's column space (XFD = 16,384) caps at
+            // three letters, so neither `l2n` nor `n2l` should ever ask for a
+            // higher level. Both callers validate before reaching here; if
+            // this branch fires it indicates a programming error in a future
+            // caller, not a user input problem — surface that clearly rather
+            // than reusing `ColumnOutOfBoundsError` (which would lie about
+            // the offending column, since `level` is a letter-count, not a
+            // column number).
+            throw new Error(`colCache._fill: invariant violated — level ${level} exceeds the 3-letter cap; callers must validate before invoking _fill`);
         }
         if (this._l2nFill < 1 && level >= 1) {
             while (n <= 26) {
@@ -92,6 +100,16 @@ const colCache = {
     },
     l2n(l) {
         if (!this._l2n[l]) {
+            // Excel's column space stops at XFD (16,384) — three letters is
+            // the maximum width any valid column letter can have. Reject
+            // longer inputs explicitly here, BEFORE handing the length to
+            // `_fill`, so the thrown error carries the actual offending
+            // letter (`AAAA`) rather than the level integer (`4`) — matching
+            // what the equivalent `n2l(n > 16384)` and `decodeAddress` paths
+            // already report.
+            if (l.length > 3) {
+                throw new ColumnOutOfBoundsError(l, "Excel supports columns from 1 to 16384");
+            }
             this._fill(l.length);
         }
         if (!this._l2n[l]) {