@cj-tech-master/excelts 9.2.1 → 9.3.0

package/dist/esm/modules/excel/defined-names.js

@@ -1,10 +1,226 @@
 import { Range } from "./range.js";
 import { CellMatrix } from "./utils/cell-matrix.js";
 import { colCache } from "./utils/col-cache.js";
+import { getDefaultSyntaxProbe } from "../formula/default-syntax-probe.js";
 const rangeRegexp = /[$](\w+)[$](\d+)(:[$](\w+)[$](\d+))?/;
+// ============================================================================
+// Range validation helpers (moved from defined-name-xform.ts)
+// ============================================================================
+// 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
+    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);
+        if (("row" in decoded && typeof decoded.row === "number") ||
+            ("top" in decoded && typeof decoded.top === "number") ||
+            ("left" in decoded && typeof decoded.left === "number")) {
+            return true;
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Extract valid cell/range references from a raw defined name text string.
+ * Handles comma-separated ranges and quoted sheet names that may contain commas.
+ */
+function extractRanges(parsedText) {
+    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;
+}
+// ============================================================================
+// Classifier — Stage 2 of the two-phase defined name design
+// ============================================================================
+/**
+ * Check whether a string contains a '(' character outside of single-quoted
+ * sheet name segments. Sheet names in cell references use single quotes:
+ * e.g. `'Sheet (1)'!$A$1` — the '(' is inside quotes and does NOT indicate
+ * a function call. A genuine formula like `OFFSET(Sheet1!$A$1,0,0,3,1)`
+ * has '(' outside of any quotes.
+ */
+function hasUnquotedParen(s) {
+    let inQuote = false;
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        if (ch === "'") {
+            inQuote = !inQuote;
+        }
+        else if (ch === "(" && !inQuote) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Classify a raw defined name text into one of three categories:
+ * 1. **reference** — pure cell/range union (goes into matrixMap)
+ * 2. **formula** — parseable expression (goes into formulaMap)
+ * 3. **opaque** — unrecognised content preserved for round-trip
+ *
+ * Classification order matters:
+ * - If the text contains an unquoted `(`, it is likely a formula — try the
+ *   formula parser first (this prevents `extractRanges` from misinterpreting
+ *   function arguments as partial range references).
+ * - Otherwise try to extract ranges (pure cell references).
+ * - If neither works, fall back to opaque.
+ *
+ * **Probe semantics:** `probe` is the formula tokenizer+parser oracle. It
+ * is the *only* authority for deciding whether a non-range, non-wrapper
+ * string is a formula. When `probe` is `null` (no formula engine
+ * installed and no probe injected), any such string is classified as
+ * **opaque** — we have no evidence it is a formula, and leaving it
+ * opaque preserves round-trip bytes via `rawText`.
+ *
+ * This function is pure: the classification of a given input depends
+ * entirely on (rawText, ranges, probe) and no global state. Two calls
+ * with the same arguments always produce the same result.
+ */
+function classifyDefinedName(rawText, ranges, probe) {
+    // If rawText is missing, fall back to existing ranges (programmatic API path)
+    if (rawText === undefined) {
+        if (ranges.length > 0) {
+            return { kind: "reference", ranges };
+        }
+        return { kind: "opaque", ranges: [] };
+    }
+    const trimmed = rawText.trim();
+    if (trimmed.length === 0) {
+        return { kind: "opaque", ranges: [] };
+    }
+    // Opaque-looking wrappers — array constants, string literals, error
+    // values — are preserved verbatim and never routed through formula
+    // parsing. Detect them once, up front.
+    const isArrayConst = trimmed.startsWith("{") && trimmed.endsWith("}");
+    const isStringLit = trimmed.startsWith('"') && trimmed.endsWith('"');
+    const isErrorVal = trimmed.startsWith("#");
+    const isOpaqueWrapper = isArrayConst || isStringLit || isErrorVal;
+    const hasParen = hasUnquotedParen(trimmed);
+    // If the text contains an unquoted parenthesis (e.g. OFFSET(...),
+    // LAMBDA(...)), it is either a formula or a malformed expression —
+    // never a cell-range union. `extractRanges` is not safe to call on
+    // such text because it splits on commas and can mis-identify
+    // `OFFSET(Sheet1` as a partial range reference.
+    //
+    // With a probe: confirm the expression parses before classifying as
+    // formula; if the probe rejects it, fall through to opaque.
+    // Without a probe: we cannot confirm it parses, so preserve the text
+    // verbatim as opaque. This is deliberately strict — the alternative
+    // (silently promoting unverified text to `formula`) produced
+    // classification results that depended on global install state.
+    if (hasParen && !isOpaqueWrapper) {
+        if (probe && probe(trimmed)) {
+            return { kind: "formula", ranges: [trimmed], formulaExpression: trimmed };
+        }
+        return { kind: "opaque", ranges: [] };
+    }
+    // Try to extract cell/range references (handles comma-separated
+    // multi-area names). Safe to call only after the paren check above,
+    // because `extractRanges` splits on commas.
+    const extracted = extractRanges(rawText);
+    if (extracted.length > 0) {
+        return { kind: "reference", ranges: extracted };
+    }
+    // Opaque wrappers that didn't pass as a formula above classify
+    // straight to opaque — we preserve them verbatim without calculating.
+    if (isOpaqueWrapper) {
+        return { kind: "opaque", ranges: [] };
+    }
+    // No parens and not a range — could still be a parseable constant
+    // expression or a reference to another defined name. Only classify as
+    // formula if a probe can confirm it parses; otherwise stay opaque so
+    // round-trip text is preserved without silently promoting unparseable
+    // content to the formula bucket.
+    if (probe && probe(trimmed)) {
+        return { kind: "formula", ranges: [trimmed], formulaExpression: trimmed };
+    }
+    // Nothing worked — opaque
+    return { kind: "opaque", ranges: [] };
+}
+// ============================================================================
+// Internal Key — disambiguates same-name entries with different scopes
+// ============================================================================
+/**
+ * Build the internal storage key for a defined name entry.
+ * Workbook-scoped: just the bare name.
+ * Sheet-scoped: `"name\0sheetId"` (null char separator avoids collisions).
+ */
+function storageKey(name, localSheetId) {
+    return localSheetId !== undefined ? `${name}\0${localSheetId}` : name;
+}
+// ============================================================================
+// DefinedNames class
+// ============================================================================
 class DefinedNames {
-    constructor() {
+    /**
+     * @param probe Optional formula-syntax probe used when classifying
+     *   defined-name text. Injecting a probe here makes classification
+     *   deterministic for this instance regardless of process-global
+     *   `installFormulaEngine()` state. When omitted, the instance defers
+     *   to the default probe at classification time (see `set model`).
+     */
+    constructor(probe) {
         this.matrixMap = {};
+        this.formulaMap = {};
+        this.localSheetIdMap = {};
+        this.opaqueMap = {};
+        this.nameForKey = {};
+        this._explicitProbe = probe ?? null;
     }
     getMatrix(name) {
         const matrix = this.matrixMap[name] || (this.matrixMap[name] = new CellMatrix());
@@ -16,6 +232,11 @@ class DefinedNames {
         if ("error" in location) {
             return; // Invalid reference, skip
         }
+        // A name is either cell-reference or formula — clear any formula/opaque binding
+        // (programmatic API always operates on workbook-scoped names)
+        delete this.formulaMap[name];
+        delete this.opaqueMap[name];
+        this.nameForKey[name] = name;
         this.addEx(location, name);
     }
     addEx(location, name) {
@@ -39,6 +260,24 @@ class DefinedNames {
             matrix.addCellEx(location);
         }
     }
+    /**
+     * Register a formula-based defined name.
+     *
+     * Unlike `add()` which binds a name to a cell/range reference, this binds
+     * a name to an arbitrary formula expression that will be evaluated at
+     * calculation time.
+     *
+     * @param name - The defined name (e.g. "MyArray")
+     * @param expression - The formula expression (e.g. "{1,2;3,4}", "LAMBDA(x,y,x+y)")
+     */
+    addFormula(name, expression) {
+        // A name is either formula or cell-reference — clear any cell-reference/opaque binding
+        // (programmatic API always operates on workbook-scoped names)
+        delete this.matrixMap[name];
+        delete this.opaqueMap[name];
+        this.nameForKey[name] = name;
+        this.formulaMap[name] = expression;
+    }
     remove(locStr, name) {
         const location = colCache.decodeEx(locStr);
         if ("error" in location) {
@@ -86,9 +325,10 @@ class DefinedNames {
         });
     }
     forEach(callback) {
-        Object.entries(this.matrixMap).forEach(([name, matrix]) => {
+        Object.entries(this.matrixMap).forEach(([sKey, matrix]) => {
+            const bareName = this.nameForKey[sKey] ?? sKey;
             matrix.forEach((cell) => {
-                callback(name, cell);
+                callback(bareName, cell);
             });
         });
     }
@@ -102,20 +342,73 @@ class DefinedNames {
     }
     getNamesEx(address) {
         return Object.entries(this.matrixMap)
-            .map(([name, matrix]) => matrix.findCellEx(address, false) && name)
+            .map(([sKey, matrix]) => matrix.findCellEx(address, false) && (this.nameForKey[sKey] ?? sKey))
             .filter((name) => Boolean(name));
     }
+    /**
+     * Return all defined name entries in this collection, including scope info.
+     * Each entry has the bare name and optional localSheetId.
+     * Same bare name may appear multiple times with different scopes.
+     */
+    getAllNames() {
+        return this.getAllEntries().map(e => e.localSheetId !== undefined
+            ? { name: e.name, localSheetId: e.localSheetId }
+            : { name: e.name });
+    }
+    /**
+     * Return all defined name entries with full details (name, ranges, scope).
+     *
+     * This is the primary enumeration API. Each entry is self-contained —
+     * no second lookup is needed. Same bare name may appear multiple times
+     * with different scopes.
+     */
+    getAllEntries() {
+        const result = [];
+        const seen = new Set();
+        for (const sKey of Object.keys(this.matrixMap)) {
+            if (seen.has(sKey)) {
+                continue;
+            }
+            seen.add(sKey);
+            const model = this.getRanges(sKey);
+            const localSheetId = this.localSheetIdMap[sKey];
+            result.push(localSheetId !== undefined ? { ...model, localSheetId } : model);
+        }
+        for (const sKey of Object.keys(this.formulaMap)) {
+            if (seen.has(sKey)) {
+                continue;
+            }
+            seen.add(sKey);
+            const model = this.getRanges(sKey);
+            const localSheetId = this.localSheetIdMap[sKey];
+            result.push(localSheetId !== undefined ? { ...model, localSheetId } : model);
+        }
+        for (const sKey of Object.keys(this.opaqueMap)) {
+            if (seen.has(sKey)) {
+                continue;
+            }
+            seen.add(sKey);
+            const bareName = this.nameForKey[sKey] ?? sKey;
+            const entry = this.opaqueMap[sKey];
+            result.push({
+                name: bareName,
+                ranges: [],
+                rawText: entry.rawText,
+                localSheetId: entry.localSheetId,
+                kind: "opaque"
+            });
+        }
+        return result;
+    }
     _explore(matrix, cell) {
         cell.mark = false;
-        const sheetName = cell.sheetName; // Always set for cells in defined names
+        const sheetName = cell.sheetName;
         const range = new Range(cell.row, cell.col, cell.row, cell.col, sheetName);
         let x;
         let y;
-        // Helper to get cell with proper type
         const getCell = (row, col) => {
             return matrix.findCellAt(sheetName, row, col);
         };
-        // grow vertical - only one col to worry about
         function vGrow(yy, edge) {
             const c = getCell(yy, cell.col);
             if (!c || !c.mark) {
@@ -131,7 +424,6 @@ class DefinedNames {
         for (y = cell.row + 1; vGrow(y, "bottom"); y++) {
             /* advance */
         }
-        // grow horizontal - ensure all rows can grow
         function hGrow(xx, edge) {
             const cells = [];
             for (y = range.top; y <= range.bottom; y++) {
@@ -157,10 +449,28 @@ class DefinedNames {
         }
         return range;
     }
+    /**
+     * Get ranges for a specific scoped entry.
+     *
+     * Unlike `getRanges(name)` which uses the bare name (and may hit the
+     * wrong scope when the same name exists both globally and locally),
+     * this method uses the internal `storageKey` to look up the exact entry.
+     */
+    getRangesScoped(name, localSheetId) {
+        const sKey = storageKey(name, localSheetId);
+        return this.getRanges(sKey);
+    }
     getRanges(name, matrix) {
+        // `name` can be a bare name (backward compat) or a storageKey.
+        // Try storageKey first, then bare name (workbook-scoped).
+        const formula = this.formulaMap[name];
         matrix = matrix || this.matrixMap[name];
+        const bareName = this.nameForKey[name] ?? name;
         if (!matrix) {
-            return { name, ranges: [] };
+            if (formula) {
+                return { name: bareName, ranges: [formula], formulaExpression: formula };
+            }
+            return { name: bareName, ranges: [] };
         }
         // mark and sweep!
         matrix.forEach((cell) => {
@@ -171,7 +481,7 @@ class DefinedNames {
             .filter((range) => Boolean(range))
             .map((range) => range.$shortRange);
         return {
-            name,
+            name: bareName,
             ranges
         };
     }
@@ -201,22 +511,102 @@ class DefinedNames {
         });
     }
     get model() {
-        // To get names per cell - just iterate over all names finding cells if they exist
-        return Object.entries(this.matrixMap)
-            .map(([name, matrix]) => this.getRanges(name, matrix))
+        // Cell-reference based names from matrixMap
+        const cellNames = Object.entries(this.matrixMap)
+            .map(([sKey, matrix]) => {
+            const result = this.getRanges(sKey, matrix);
+            const localSheetId = this.localSheetIdMap[sKey];
+            if (localSheetId !== undefined) {
+                return { ...result, localSheetId };
+            }
+            return result;
+        })
             .filter((definedName) => definedName.ranges.length);
+        // Formula-based names from formulaMap (only include names not already in matrixMap)
+        const formulaNames = Object.entries(this.formulaMap)
+            .filter(([sKey]) => !this.matrixMap[sKey])
+            .map(([sKey, expression]) => {
+            const bareName = this.nameForKey[sKey] ?? sKey;
+            const result = {
+                name: bareName,
+                ranges: [expression],
+                formulaExpression: expression
+            };
+            const localSheetId = this.localSheetIdMap[sKey];
+            if (localSheetId !== undefined) {
+                return { ...result, localSheetId };
+            }
+            return result;
+        });
+        // Opaque names — rawText preserved for round-trip
+        const opaqueNames = Object.entries(this.opaqueMap).map(([sKey, entry]) => {
+            const bareName = this.nameForKey[sKey] ?? sKey;
+            return {
+                name: bareName,
+                ranges: [],
+                rawText: entry.rawText,
+                localSheetId: entry.localSheetId,
+                kind: "opaque"
+            };
+        });
+        return [...cellNames, ...formulaNames, ...opaqueNames];
     }
+    /**
+     * Deserialise an array of `DefinedNameModel` entries (typically from XLSX parsing).
+     *
+     * Stage 2 of the two-phase design: each entry's `rawText` is classified
+     * into reference / formula / opaque by `classifyDefinedName()`.  Entries
+     * that arrive without `rawText` (programmatic API) fall back to inspecting
+     * the existing `ranges` and `formulaExpression` fields for compatibility.
+     */
     set model(value) {
-        // value is [ { name, ranges }, ... ]
         const matrixMap = (this.matrixMap = {});
-        value.forEach(definedName => {
-            const matrix = (matrixMap[definedName.name] = new CellMatrix());
-            definedName.ranges.forEach(rangeStr => {
-                if (rangeRegexp.test(rangeStr.split("!").pop() ?? "")) {
-                    matrix.addCell(rangeStr);
+        const formulaMap = (this.formulaMap = {});
+        const localSheetIdMap = (this.localSheetIdMap = {});
+        const opaqueMap = (this.opaqueMap = {});
+        const nameForKeyMap = (this.nameForKey = {});
+        // Resolve probe lazily: a caller may have constructed the Workbook
+        // before `installFormulaEngine()` but load XLSX data afterwards. We
+        // want whichever probe is registered at *load* time, not construct
+        // time. An explicit per-instance probe always wins when provided.
+        const probe = this._explicitProbe ?? getDefaultSyntaxProbe();
+        for (const definedName of value) {
+            const sKey = storageKey(definedName.name, definedName.localSheetId);
+            nameForKeyMap[sKey] = definedName.name;
+            // Track localSheetId for all name kinds
+            if (definedName.localSheetId !== undefined) {
+                localSheetIdMap[sKey] = definedName.localSheetId;
+            }
+            // Programmatic API path: formulaExpression already set and no rawText
+            if (definedName.formulaExpression && definedName.rawText === undefined) {
+                formulaMap[sKey] = definedName.formulaExpression;
+                continue;
+            }
+            // XLSX parse path (rawText present) or programmatic path with ranges only
+            const classified = classifyDefinedName(definedName.rawText, definedName.ranges, probe);
+            switch (classified.kind) {
+                case "reference": {
+                    const matrix = (matrixMap[sKey] = new CellMatrix());
+                    for (const rangeStr of classified.ranges) {
+                        if (rangeRegexp.test(rangeStr.split("!").pop() ?? "")) {
+                            matrix.addCell(rangeStr);
+                        }
+                    }
+                    break;
                 }
-            });
-        });
+                case "formula":
+                    formulaMap[sKey] = classified.formulaExpression;
+                    break;
+                case "opaque":
+                    if (definedName.rawText) {
+                        opaqueMap[sKey] = {
+                            rawText: definedName.rawText,
+                            localSheetId: definedName.localSheetId
+                        };
+                    }
+                    break;
+            }
+        }
     }
 }
 export { DefinedNames };

package/dist/esm/modules/excel/image.js

@@ -34,6 +34,19 @@ class Image {
                 if (!range) {
                     throw new ImageError("Image has no range");
                 }
+                // Absolute positioning — no cell anchors
+                if (range.pos) {
+                    return {
+                        type: this.type,
+                        imageId: this.imageId ?? "",
+                        hyperlinks: range.hyperlinks,
+                        range: {
+                            tl: { nativeCol: 0, nativeColOff: 0, nativeRow: 0, nativeRowOff: 0 },
+                            ext: range.ext,
+                            pos: range.pos
+                        }
+                    };
+                }
                 return {
                     type: this.type,
                     imageId: this.imageId ?? "",
@@ -69,6 +82,15 @@ class Image {
                     };
                 }
             }
+            else if (range && "pos" in range && range.pos) {
+                // Absolute positioning — preserve pos/ext, use dummy tl anchor
+                this.range = {
+                    tl: new Anchor(this.worksheet, null, 0),
+                    ext: range.ext,
+                    hyperlinks: hyperlinks || ("hyperlinks" in range ? range.hyperlinks : undefined),
+                    pos: range.pos
+                };
+            }
             else if (range) {
                 this.range = {
                     tl: new Anchor(this.worksheet, range.tl, 0),
@@ -95,7 +117,8 @@ class Image {
                 br: this.range.br ? this.range.br.clone(target) : undefined,
                 ext: this.range.ext ? { ...this.range.ext } : undefined,
                 editAs: this.range.editAs,
-                hyperlinks: this.range.hyperlinks ? { ...this.range.hyperlinks } : undefined
+                hyperlinks: this.range.hyperlinks ? { ...this.range.hyperlinks } : undefined,
+                pos: this.range.pos ? { ...this.range.pos } : undefined
             };
         }
         return cloned;

package/dist/esm/modules/excel/stream/workbook-reader.browser.js

@@ -15,6 +15,7 @@ import { WorksheetReader } from "./worksheet-reader.js";
 import { iterateStream } from "../utils/iterate-stream.js";
 import { getWorksheetNoFromWorksheetPath, getWorksheetNoFromWorksheetRelsPath, normalizeZipPath, OOXML_PATHS, worksheetRelTarget } from "../utils/ooxml-paths.js";
 import { WorkbookXform } from "../xlsx/xform/book/workbook-xform.js";
+import { MetadataXform } from "../xlsx/xform/core/metadata-xform.js";
 import { RelationshipsXform } from "../xlsx/xform/core/relationships-xform.js";
 import { StylesXform } from "../xlsx/xform/style/styles-xform.js";
 import { Readable } from "../../stream/index.js";
@@ -36,6 +37,8 @@ export class WorkbookReaderBase extends EventEmitter {
     }
     constructor(input, options, WorksheetReaderClass, HyperlinkReaderClass) {
         super();
+        /** Whether xl/metadata.xml contains XLDAPR dynamic array metadata */
+        this.hasDynamicArrayMetadata = false;
         /** Running total of bytes buffered for waiting worksheets. */
         this._totalBufferedBytes = 0;
         this.input = input;
@@ -443,6 +446,14 @@ export class WorkbookReaderBase extends EventEmitter {
             await this.styles.parseStream(iterateStream(entry));
         }
     }
+    async _parseMetadata(entry) {
+        const xform = new MetadataXform();
+        const result = await xform.parseStream(iterateStream(entry));
+        if (result) {
+            this.hasDynamicArrayMetadata = !!result.hasDynamicArrays;
+            this.dynamicArrayCmIndices = result.dynamicArrayCmIndices;
+        }
+    }
     *_parseWorksheet(iterator, sheetNo) {
         this._emitEntry({ type: "worksheet", id: sheetNo });
         const sheetNoNumber = parseInt(sheetNo, 10);
@@ -511,6 +522,9 @@ export class WorkbookReaderBase extends EventEmitter {
                 case OOXML_PATHS.xlStyles:
                     await this._parseStyles(entry);
                     break;
+                case OOXML_PATHS.xlMetadata:
+                    await this._parseMetadata(entry);
+                    break;
                 default:
                     sheetNo = getWorksheetNoFromWorksheetPath(normalizedPath)?.toString();
                     if (sheetNo) {