@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/excel/xlsx/xform/book/defined-name-xform.js

@@ -1,4 +1,3 @@
-import { colCache } from "../../../utils/col-cache.js";
 import { BaseXform } from "../base-xform.js";
 class DefinedNamesXform extends BaseXform {
     constructor() {
@@ -7,14 +6,21 @@ class DefinedNamesXform extends BaseXform {
     }
     render(xmlStream, model) {
         // <definedNames>
-        //   <definedName name="name">name.ranges.join(',')</definedName>
-        //   <definedName name="_xlnm.Print_Area" localSheetId="0">name.ranges.join(',')</definedName>
+        //   <definedName name="name">text</definedName>
+        //   <definedName name="_xlnm.Print_Area" localSheetId="0">text</definedName>
         // </definedNames>
         xmlStream.openNode("definedName", {
             name: model.name,
             localSheetId: model.localSheetId
         });
-        xmlStream.writeText(model.ranges.join(","));
+        // For opaque names, write the rawText verbatim to preserve round-trip fidelity.
+        // For reference/formula names, join the ranges array as before.
+        if (model.kind === "opaque" && model.rawText) {
+            xmlStream.writeText(model.rawText);
+        }
+        else {
+            xmlStream.writeText(model.ranges.join(","));
+        }
         xmlStream.closeNode();
     }
     parseOpen(node) {
@@ -31,94 +37,23 @@ class DefinedNamesXform extends BaseXform {
     parseText(text) {
         this._parsedText.push(text);
     }
+    /**
+     * Stage 1 of the two-phase defined name design: the XLSX layer only
+     * preserves the raw XML text.  Semantic classification (reference vs
+     * formula vs opaque) is deferred to `DefinedNames.set model()`.
+     */
     parseClose() {
-        this.model = {
+        const rawText = this._parsedText.join("");
+        const model = {
             name: this._parsedName,
-            ranges: extractRanges(this._parsedText.join(""))
+            ranges: [],
+            rawText: rawText.trim() || undefined
         };
         if (this._parsedLocalSheetId !== undefined) {
-            this.model.localSheetId = parseInt(this._parsedLocalSheetId, 10);
-        }
-        return false;
-    }
-}
-// Regex to validate cell range format:
-// - Cell: $A$1 or A1
-// - Range: $A$1:$B$10 or A1:B10
-// - Row range: $1:$2 (for print titles)
-// - Column range: $A:$B (for print titles)
-const cellRangeRegexp = /^[$]?[A-Za-z]{1,3}[$]?\d+(:[$]?[A-Za-z]{1,3}[$]?\d+)?$/;
-const rowRangeRegexp = /^[$]?\d+:[$]?\d+$/;
-const colRangeRegexp = /^[$]?[A-Za-z]{1,3}:[$]?[A-Za-z]{1,3}$/;
-function isValidRange(range) {
-    // Skip array constants wrapped in {} - these are not valid cell ranges
-    // e.g., {"'Sheet1'!$A$1:$B$10"} or {#N/A,#N/A,FALSE,"text"}
-    if (range.startsWith("{") || range.endsWith("}")) {
-        return false;
-    }
-    // Extract the cell reference part (after the sheet name if present)
-    const cellRef = range.split("!").pop() ?? "";
-    // Must match one of the valid patterns
-    if (!cellRangeRegexp.test(cellRef) &&
-        !rowRangeRegexp.test(cellRef) &&
-        !colRangeRegexp.test(cellRef)) {
-        return false;
-    }
-    try {
-        const decoded = colCache.decodeEx(range);
-        // For cell ranges: row/col or top/bottom/left/right should be valid numbers
-        // For row ranges ($1:$2): top/bottom are numbers, left/right are null
-        // For column ranges ($A:$B): left/right are numbers, top/bottom are null
-        if (("row" in decoded && typeof decoded.row === "number") ||
-            ("top" in decoded && typeof decoded.top === "number") ||
-            ("left" in decoded && typeof decoded.left === "number")) {
-            return true;
+            model.localSheetId = parseInt(this._parsedLocalSheetId, 10);
         }
+        this.model = model;
         return false;
     }
-    catch {
-        return false;
-    }
-}
-function extractRanges(parsedText) {
-    // Skip if the entire text is wrapped in {} (array constant)
-    const trimmed = parsedText.trim();
-    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
-        return [];
-    }
-    const ranges = [];
-    let quotesOpened = false;
-    let last = "";
-    parsedText.split(",").forEach(item => {
-        if (!item) {
-            return;
-        }
-        const quotes = (item.match(/'/g) ?? []).length;
-        if (!quotes) {
-            if (quotesOpened) {
-                last += `${item},`;
-            }
-            else if (isValidRange(item)) {
-                ranges.push(item);
-            }
-            return;
-        }
-        const quotesEven = quotes % 2 === 0;
-        if (!quotesOpened && quotesEven && isValidRange(item)) {
-            ranges.push(item);
-        }
-        else if (quotesOpened && !quotesEven) {
-            quotesOpened = false;
-            if (isValidRange(last + item)) {
-                ranges.push(last + item);
-            }
-            last = "";
-        }
-        else {
-            quotesOpened = true;
-            last += `${item},`;
-        }
-    });
-    return ranges;
 }
 export { DefinedNamesXform };

package/dist/esm/modules/excel/xlsx/xform/book/external-link-xform.js

@@ -0,0 +1,330 @@
+/**
+ * ExternalLinkXform — read and write `xl/externalLinks/externalLinkN.xml`.
+ *
+ * This part describes one external workbook referenced by the current file:
+ * the list of sheets inside the foreign workbook, plus an optional cache of
+ * the primitive values at each referenced address. The `r:id` attribute on
+ * `<externalBook>` points (via the neighbouring `_rels/externalLinkN.xml.rels`)
+ * at the actual file; that resolution is handled by the writer/reader in
+ * `xlsx.browser.ts`, not here.
+ *
+ * Schema shape:
+ *
+ *   <externalLink xmlns=".../spreadsheetml/2006/main"
+ *                 xmlns:r=".../relationships">
+ *     <externalBook r:id="rId1">
+ *       <sheetNames>
+ *         <sheetName val="Sheet1"/>
+ *         <sheetName val="Sheet2"/>
+ *       </sheetNames>
+ *       <sheetDataSet>
+ *         <sheetData sheetId="0">                (0-based index into sheetNames)
+ *           <row r="1">
+ *             <cell r="A1" t="n"><v>123</v></cell>
+ *             <cell r="B1" t="str"><v>hello</v></cell>
+ *           </row>
+ *           <row r="2">
+ *             <cell r="A2" t="b"><v>1</v></cell>
+ *           </row>
+ *         </sheetData>
+ *         <sheetData sheetId="1" refreshError="1"/>   (no cached values)
+ *       </sheetDataSet>
+ *     </externalBook>
+ *   </externalLink>
+ *
+ * The `t` attribute on `<cell>` mirrors the inline-value types used inside a
+ * worksheet's `<c>` element: "n" (number, default), "str" (string), "b"
+ * (boolean), "e" (error). We don't emit shared-string indices here because
+ * the externalLink part is self-contained — each cached string is serialised
+ * inline as plain text inside `<v>`.
+ *
+ * Parser state machine:
+ *   externalLink → externalBook → sheetNames → sheetName  (stores names in order)
+ *                            \→ sheetDataSet → sheetData → row → cell → v  (values)
+ *
+ * The parser tolerates missing cache data (Excel's `refreshError="1"` mode);
+ * sheets without a matching `<sheetData>` simply have no entry in
+ * `cachedValues`.
+ */
+import { BaseXform } from "../base-xform.js";
+import { StdDocAttributes } from "../../../../xml/writer.js";
+const NAMESPACE = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+const R_NAMESPACE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/** Pretty attribute constant used on the root element. */
+const ROOT_ATTRIBUTES = { xmlns: NAMESPACE, "xmlns:r": R_NAMESPACE };
+class ExternalLinkXform extends BaseXform {
+    constructor() {
+        super(...arguments);
+        /** Sheet name indexed by sheetId (0-based) — filled during parse. */
+        this.sheetNamesByIndex = [];
+        /** Current sheet's accumulated cached cells. */
+        this.currentSheetCells = null;
+        /** Current sheet's name (looked up from sheetId). */
+        this.currentSheetName = null;
+        /** Current cell being parsed: address + type. */
+        this.currentCellAddress = null;
+        this.currentCellType = "n";
+        /** Accumulated text content of the current <v> element. */
+        this.currentCellValue = null;
+        /** Which element we're currently inside. */
+        this.inV = false;
+    }
+    get tag() {
+        return "externalLink";
+    }
+    reset() {
+        super.reset();
+        this.sheetNamesByIndex = [];
+        this.currentSheetCells = null;
+        this.currentSheetName = null;
+        this.currentCellAddress = null;
+        this.currentCellType = "n";
+        this.currentCellValue = null;
+        this.inV = false;
+    }
+    // ==========================================================================
+    // Rendering
+    // ==========================================================================
+    render(xmlStream, model) {
+        xmlStream.openXml(StdDocAttributes);
+        xmlStream.openNode("externalLink", ROOT_ATTRIBUTES);
+        // We always use "rId1" for the externalBook ref — the externalLinkN.rels
+        // file only ever has a single relationship (the externalLinkPath one).
+        xmlStream.openNode("externalBook", { "r:id": "rId1" });
+        if (model.sheetNames.length > 0) {
+            xmlStream.openNode("sheetNames");
+            for (const name of model.sheetNames) {
+                xmlStream.leafNode("sheetName", { val: name });
+            }
+            xmlStream.closeNode();
+        }
+        // Emit cached values when supplied. We must always emit <sheetDataSet>
+        // if any sheet has cached values — it's fine to omit when none do.
+        const cache = model.cachedValues ?? {};
+        const hasAnyCache = Object.keys(cache).some(name => {
+            const sheet = cache[name];
+            return sheet && Object.keys(sheet).length > 0;
+        });
+        if (hasAnyCache) {
+            xmlStream.openNode("sheetDataSet");
+            // Iterate in sheetNames order so sheetId indices are stable.
+            for (let i = 0; i < model.sheetNames.length; i++) {
+                const sheetName = model.sheetNames[i];
+                const cells = cache[sheetName];
+                if (!cells || Object.keys(cells).length === 0) {
+                    continue;
+                }
+                renderSheetData(xmlStream, i, cells);
+            }
+            xmlStream.closeNode();
+        }
+        xmlStream.closeNode(); // </externalBook>
+        xmlStream.closeNode(); // </externalLink>
+    }
+    // ==========================================================================
+    // Parsing
+    // ==========================================================================
+    parseOpen(node) {
+        const name = node.name;
+        switch (name) {
+            case "externalLink":
+                this.model = {
+                    externalBookRId: "",
+                    sheetNames: [],
+                    cachedValues: {}
+                };
+                this.sheetNamesByIndex = [];
+                return true;
+            case "externalBook":
+                if (this.model) {
+                    this.model.externalBookRId = node.attributes["r:id"] ?? "";
+                }
+                return true;
+            case "sheetName":
+                if (this.model) {
+                    const val = node.attributes.val ?? "";
+                    this.model.sheetNames.push(val);
+                    this.sheetNamesByIndex.push(val);
+                }
+                return true;
+            case "sheetData": {
+                const sheetIdRaw = node.attributes.sheetId;
+                const sheetId = sheetIdRaw !== undefined ? parseInt(sheetIdRaw, 10) : NaN;
+                this.currentSheetName = Number.isFinite(sheetId)
+                    ? (this.sheetNamesByIndex[sheetId] ?? null)
+                    : null;
+                this.currentSheetCells = this.currentSheetName ? {} : null;
+                return true;
+            }
+            case "cell":
+                this.currentCellAddress = node.attributes.r ?? null;
+                this.currentCellType = node.attributes.t ?? "n";
+                this.currentCellValue = null;
+                return true;
+            case "v":
+                this.inV = true;
+                this.currentCellValue = "";
+                return true;
+            default:
+                return false;
+        }
+    }
+    parseText(text) {
+        if (this.inV) {
+            this.currentCellValue = (this.currentCellValue ?? "") + text;
+        }
+    }
+    parseClose(name) {
+        switch (name) {
+            case "v":
+                this.inV = false;
+                return true;
+            case "cell":
+                if (this.model && this.currentSheetCells && this.currentCellAddress) {
+                    this.currentSheetCells[this.currentCellAddress.toUpperCase()] = decodePrimitive(this.currentCellType, this.currentCellValue);
+                }
+                this.currentCellAddress = null;
+                this.currentCellType = "n";
+                this.currentCellValue = null;
+                return true;
+            case "sheetData":
+                if (this.model &&
+                    this.currentSheetName &&
+                    this.currentSheetCells &&
+                    Object.keys(this.currentSheetCells).length > 0) {
+                    this.model.cachedValues[this.currentSheetName] = this.currentSheetCells;
+                }
+                this.currentSheetName = null;
+                this.currentSheetCells = null;
+                return true;
+            case "externalLink":
+                // Document root closed — stop parsing
+                return false;
+            default:
+                return true;
+        }
+    }
+}
+// ==========================================================================
+// Serialisation helpers
+// ==========================================================================
+function renderSheetData(xmlStream, sheetIdx, cells) {
+    // Group cells by row so the XML tree is well-formed. Excel tolerates any
+    // ordering, but grouping by row matches the schema contract and keeps the
+    // output stable for diffing.
+    const rows = groupByRow(cells);
+    xmlStream.openNode("sheetData", { sheetId: sheetIdx });
+    for (const row of rows) {
+        xmlStream.openNode("row", { r: row.rowNum });
+        for (const { address, value } of row.cells) {
+            renderCell(xmlStream, address, value);
+        }
+        xmlStream.closeNode();
+    }
+    xmlStream.closeNode();
+}
+function groupByRow(cells) {
+    const byRow = new Map();
+    for (const rawAddress of Object.keys(cells)) {
+        const address = rawAddress.toUpperCase();
+        const rowNum = extractRowNumber(address);
+        if (rowNum === undefined) {
+            // Addresses that don't match the A1 shape are skipped rather than
+            // corrupting the file. An address like "A1" or "$B$12" yields a valid
+            // row number; anything else would produce malformed XML.
+            continue;
+        }
+        let bucket = byRow.get(rowNum);
+        if (!bucket) {
+            bucket = { rowNum, cells: [] };
+            byRow.set(rowNum, bucket);
+        }
+        bucket.cells.push({ address: stripAbsoluteMarkers(address), value: cells[rawAddress] });
+    }
+    return [...byRow.values()].sort((a, b) => a.rowNum - b.rowNum);
+}
+function extractRowNumber(address) {
+    // Strip leading $ and column letters, keep trailing digits.
+    const match = /^\$?[A-Z]+\$?(\d+)$/.exec(address);
+    return match ? parseInt(match[1], 10) : undefined;
+}
+function stripAbsoluteMarkers(address) {
+    return address.replace(/\$/g, "");
+}
+function renderCell(xmlStream, address, value) {
+    if (value === null || value === undefined) {
+        // An explicit blank — emit the address with no type/value so Excel shows
+        // an empty cell when displaying cached values.
+        xmlStream.leafNode("cell", { r: address });
+        return;
+    }
+    if (typeof value === "number") {
+        xmlStream.openNode("cell", { r: address });
+        xmlStream.leafNode("v", undefined, String(value));
+        xmlStream.closeNode();
+        return;
+    }
+    if (typeof value === "boolean") {
+        xmlStream.openNode("cell", { r: address, t: "b" });
+        xmlStream.leafNode("v", undefined, value ? "1" : "0");
+        xmlStream.closeNode();
+        return;
+    }
+    // Error values like "#DIV/0!", "#REF!", "#N/A" etc. are stored as t="e".
+    // Detect them so the round-trip preserves the type correctly (otherwise
+    // Excel would display the error literal as a plain string).
+    if (isErrorLiteral(value)) {
+        xmlStream.openNode("cell", { r: address, t: "e" });
+        xmlStream.leafNode("v", undefined, value);
+        xmlStream.closeNode();
+        return;
+    }
+    // String — emit t="str" with the text inside <v>.
+    xmlStream.openNode("cell", { r: address, t: "str" });
+    xmlStream.leafNode("v", undefined, value);
+    xmlStream.closeNode();
+}
+// ==========================================================================
+// Deserialisation helpers
+// ==========================================================================
+/** Excel error literals that should be written with `t="e"`. */
+const ERROR_LITERALS = new Set([
+    "#NULL!",
+    "#DIV/0!",
+    "#VALUE!",
+    "#REF!",
+    "#NAME?",
+    "#NUM!",
+    "#N/A",
+    "#GETTING_DATA",
+    "#SPILL!",
+    "#CALC!",
+    "#CONNECT!",
+    "#BLOCKED!",
+    "#UNKNOWN!",
+    "#FIELD!",
+    "#PYTHON!"
+]);
+function isErrorLiteral(value) {
+    return ERROR_LITERALS.has(value);
+}
+function decodePrimitive(type, raw) {
+    if (raw === null || raw === "") {
+        return null;
+    }
+    switch (type) {
+        case "b":
+            return raw !== "0" && raw.toLowerCase() !== "false";
+        case "e":
+            // Preserve the error literal as a string — consumers can match on it.
+            return raw;
+        case "str":
+            return raw;
+        case "n":
+        default: {
+            const n = Number(raw);
+            return Number.isFinite(n) ? n : raw;
+        }
+    }
+}
+export { ExternalLinkXform };

package/dist/esm/modules/excel/xlsx/xform/book/external-reference-xform.js

@@ -0,0 +1,24 @@
+/**
+ * Xform for a single `<externalReference r:id="..."/>` element inside
+ * `<externalReferences>` in `xl/workbook.xml`. Each `<externalReference>`
+ * maps positionally (in document order, 1-based) to an `[N]Sheet!Ref`
+ * prefix in formula strings.
+ */
+import { BaseXform } from "../base-xform.js";
+class ExternalReferenceXform extends BaseXform {
+    render(xmlStream, model) {
+        xmlStream.leafNode("externalReference", { "r:id": model.rId });
+    }
+    parseOpen(node) {
+        if (node.name === "externalReference") {
+            this.model = { rId: node.attributes["r:id"] ?? "" };
+            return true;
+        }
+        return false;
+    }
+    parseText() { }
+    parseClose() {
+        return false;
+    }
+}
+export { ExternalReferenceXform };

package/dist/esm/modules/excel/xlsx/xform/book/workbook-calc-properties-xform.js

@@ -3,12 +3,21 @@ class WorkbookCalcPropertiesXform extends BaseXform {
     render(xmlStream, model) {
         xmlStream.leafNode("calcPr", {
             calcId: 171027,
-            fullCalcOnLoad: model.fullCalcOnLoad ? 1 : undefined
+            fullCalcOnLoad: model.fullCalcOnLoad ? 1 : undefined,
+            iterate: model.iterate ? 1 : undefined,
+            iterateCount: model.iterateCount !== undefined ? model.iterateCount : undefined,
+            iterateDelta: model.iterateDelta !== undefined ? model.iterateDelta : undefined
         });
     }
     parseOpen(node) {
         if (node.name === "calcPr") {
-            this.model = {};
+            const attrs = node.attributes ?? {};
+            this.model = {
+                fullCalcOnLoad: attrs.fullCalcOnLoad === "1",
+                iterate: attrs.iterate === "1" ? true : undefined,
+                iterateCount: attrs.iterateCount !== undefined ? parseInt(attrs.iterateCount, 10) : undefined,
+                iterateDelta: attrs.iterateDelta !== undefined ? parseFloat(attrs.iterateDelta) : undefined
+            };
             return true;
         }
         return false;

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

@@ -0,0 +1,66 @@
+import { BaseXform } from "../base-xform.js";
+class WorkbookProtectionXform extends BaseXform {
+    get tag() {
+        return "workbookProtection";
+    }
+    render(xmlStream, model) {
+        if (!model) {
+            return;
+        }
+        const attributes = {};
+        if (model.lockStructure) {
+            attributes.lockStructure = "1";
+        }
+        if (model.lockWindows) {
+            attributes.lockWindows = "1";
+        }
+        if (model.lockRevision) {
+            attributes.lockRevision = "1";
+        }
+        if (model.workbookPassword) {
+            attributes.workbookPassword = model.workbookPassword;
+        }
+        if (model.revisionsPassword) {
+            attributes.revisionsPassword = model.revisionsPassword;
+        }
+        if (model.algorithmName) {
+            attributes.workbookAlgorithmName = model.algorithmName;
+            attributes.workbookHashValue = model.hashValue;
+            attributes.workbookSaltValue = model.saltValue;
+            attributes.workbookSpinCount = model.spinCount?.toString();
+        }
+        if (Object.values(attributes).some(v => v !== undefined)) {
+            xmlStream.leafNode(this.tag, attributes);
+        }
+    }
+    parseOpen(node) {
+        switch (node.name) {
+            case this.tag: {
+                const a = node.attributes;
+                this.model = {
+                    lockStructure: a.lockStructure === "1" || undefined,
+                    lockWindows: a.lockWindows === "1" || undefined,
+                    lockRevision: a.lockRevision === "1" || undefined,
+                    workbookPassword: a.workbookPassword || undefined,
+                    revisionsPassword: a.revisionsPassword || undefined
+                };
+                if (a.workbookAlgorithmName) {
+                    this.model.algorithmName = a.workbookAlgorithmName;
+                    this.model.hashValue = a.workbookHashValue;
+                    this.model.saltValue = a.workbookSaltValue;
+                    this.model.spinCount = a.workbookSpinCount
+                        ? parseInt(a.workbookSpinCount, 10)
+                        : undefined;
+                }
+                return true;
+            }
+            default:
+                return false;
+        }
+    }
+    parseText() { }
+    parseClose() {
+        return false;
+    }
+}
+export { WorkbookProtectionXform };