@cj-tech-master/excelts 9.2.1 → 9.3.0

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

@@ -15,12 +15,14 @@ import { filterDrawingAnchors } from "../utils/drawing-utils.js";
 import { drawingPath, drawingRelsPath, mediaPath, OOXML_PATHS, OOXML_REL_TARGETS, worksheetRelTarget } from "../utils/ooxml-paths.js";
 import { SharedStrings } from "../utils/shared-strings.js";
 import { StreamBuf } from "../utils/stream-buf.js";
+import { buildWorkbookProtection } from "../utils/workbook-protection.js";
 import { RelType } from "../xlsx/rel-type.js";
 import { WorkbookXform } from "../xlsx/xform/book/workbook-xform.js";
 import { AppXform } from "../xlsx/xform/core/app-xform.js";
 import { ContentTypesXform } from "../xlsx/xform/core/content-types-xform.js";
 import { CoreXform } from "../xlsx/xform/core/core-xform.js";
 import { FeaturePropertyBagXform } from "../xlsx/xform/core/feature-property-bag-xform.js";
+import { MetadataXform } from "../xlsx/xform/core/metadata-xform.js";
 import { RelationshipsXform } from "../xlsx/xform/core/relationships-xform.js";
 import { DrawingXform } from "../xlsx/xform/drawing/drawing-xform.js";
 import { SharedStringsXform } from "../xlsx/xform/strings/shared-strings-xform.js";
@@ -53,6 +55,7 @@ export class WorkbookWriterBase {
         this.compressionLevel = Math.max(0, Math.min(9, level));
         this.media = [];
         this.commentRefs = [];
+        this.dynamicArrayCount = 0;
         this._trueStreaming = options.trueStreaming ?? false;
         // Create Zip instance
         this.zip = new Zip((err, data, final) => {
@@ -87,6 +90,18 @@ export class WorkbookWriterBase {
     get definedNames() {
         return this._definedNames;
     }
+    /**
+     * The default font for the workbook (fontId=0 / "Normal" style).
+     * Must be set before any worksheet rows are committed.
+     */
+    get defaultFont() {
+        return this.styles.defaultFont;
+    }
+    set defaultFont(font) {
+        if (this.styles.setDefaultFont) {
+            this.styles.setDefaultFont(font);
+        }
+    }
     /** @internal */
     _openStream(path) {
         const stream = new StreamBuf({
@@ -147,6 +162,7 @@ export class WorkbookWriterBase {
             this.addSharedStrings(),
             this.addStyles(),
             this.addFeaturePropertyBag(),
+            this.addMetadata(),
             this.addWorkbookRels()
         ]);
         await this.addWorkbook();
@@ -173,6 +189,19 @@ export class WorkbookWriterBase {
     getImage(id) {
         return this.media[id];
     }
+    /**
+     * Protect the workbook structure with an optional password.
+     * Prevents users from adding, deleting, renaming, moving, or copying worksheets.
+     */
+    async protect(password, options) {
+        this.protection = await buildWorkbookProtection(password, options);
+    }
+    /**
+     * Remove workbook structure protection.
+     */
+    unprotect() {
+        this.protection = undefined;
+    }
     addWorksheet(name, options) {
         const opts = options || {};
         const useSharedStrings = opts.useSharedStrings !== undefined ? opts.useSharedStrings : this.useSharedStrings;
@@ -250,7 +279,8 @@ export class WorkbookWriterBase {
                 commentRefs: this.commentRefs,
                 media: this.media,
                 drawings,
-                hasCheckboxes: this.styles.hasCheckboxes
+                hasCheckboxes: this.styles.hasCheckboxes,
+                hasDynamicArrayFormulas: this.dynamicArrayCount > 0
             };
             const xform = new ContentTypesXform();
             this._addFile(xform.toXml(model), OOXML_PATHS.contentTypes);
@@ -336,6 +366,14 @@ export class WorkbookWriterBase {
         }
         return Promise.resolve();
     }
+    addMetadata() {
+        if (this.dynamicArrayCount <= 0) {
+            return Promise.resolve();
+        }
+        const xform = new MetadataXform();
+        this._addFile(xform.toXml({ dynamicArrayCount: this.dynamicArrayCount }), OOXML_PATHS.xlMetadata);
+        return Promise.resolve();
+    }
     addWorkbookRels() {
         let count = 1;
         const relationships = [
@@ -357,6 +395,14 @@ export class WorkbookWriterBase {
                 Target: OOXML_REL_TARGETS.workbookFeaturePropertyBag
             });
         }
+        // Add metadata relationship for dynamic array formulas
+        if (this.dynamicArrayCount > 0) {
+            relationships.push({
+                Id: `rId${count++}`,
+                Type: RelType.SheetMetadata,
+                Target: OOXML_REL_TARGETS.workbookMetadata
+            });
+        }
         this._worksheets.forEach(ws => {
             if (ws) {
                 ws.rId = `rId${count++}`;
@@ -379,6 +425,7 @@ export class WorkbookWriterBase {
             definedNames: this._definedNames.model,
             views: this.views,
             properties: {},
+            protection: this.protection,
             calcProperties: {}
         };
         return new Promise(resolve => {

package/dist/esm/modules/excel/stream/worksheet-reader.js

@@ -187,10 +187,12 @@ class WorksheetReader extends EventEmitter {
                     case "c":
                         if (row) {
                             const styleAttr = node.attributes.s;
+                            const cmAttr = node.attributes.cm;
                             c = {
                                 ref: node.attributes.r,
                                 s: styleAttr !== undefined ? parseInt(styleAttr, 10) : undefined,
-                                t: node.attributes.t
+                                t: node.attributes.t,
+                                cm: cmAttr !== undefined ? parseInt(cmAttr, 10) : undefined
                             };
                         }
                         break;
@@ -295,6 +297,20 @@ class WorksheetReader extends EventEmitter {
                                         cellValue.result = parseFloat(c.v.text);
                                     }
                                 }
+                                // Check if this cell is a dynamic array formula via cm → metadata mapping.
+                                // Uses the precise dynamicArrayCmIndices set from WorkbookReaderBase,
+                                // falling back to the coarser hasDynamicArrayMetadata boolean.
+                                if (c.cm !== undefined) {
+                                    const { workbook: wb } = this;
+                                    if (wb.dynamicArrayCmIndices) {
+                                        if (wb.dynamicArrayCmIndices.has(c.cm)) {
+                                            cellValue.isDynamicArray = true;
+                                        }
+                                    }
+                                    else if (wb.hasDynamicArrayMetadata) {
+                                        cellValue.isDynamicArray = true;
+                                    }
+                                }
                                 cell.value = cellValue;
                             }
                             else if (c.v) {

package/dist/esm/modules/excel/stream/worksheet-writer.js

@@ -26,6 +26,7 @@ import { DrawingXform as DrawingPartXform } from "../xlsx/xform/sheet/drawing-xf
 import { ExtLstXform } from "../xlsx/xform/sheet/ext-lst-xform.js";
 import { HeaderFooterXform } from "../xlsx/xform/sheet/header-footer-xform.js";
 import { HyperlinkXform } from "../xlsx/xform/sheet/hyperlink-xform.js";
+import { IgnoredErrorsXform } from "../xlsx/xform/sheet/ignored-errors-xform.js";
 import { PageMarginsXform } from "../xlsx/xform/sheet/page-margins-xform.js";
 import { PageSetupXform } from "../xlsx/xform/sheet/page-setup-xform.js";
 import { PictureXform } from "../xlsx/xform/sheet/picture-xform.js";
@@ -60,6 +61,7 @@ const xform = {
     drawing: new DrawingPartXform(),
     conditionalFormattings: new ConditionalFormattingsXform(),
     extLst: new ExtLstXform(),
+    ignoredErrors: new IgnoredErrorsXform(),
     headerFooter: new HeaderFooterXform(),
     rowBreaks: new RowBreaksXform(),
     colBreaks: new ColBreaksXform()
@@ -100,6 +102,8 @@ class WorksheetWriter {
         this._siFormulae = 0;
         // keep a record of conditionalFormattings
         this.conditionalFormatting = [];
+        // ignored errors (suppress green triangles in Excel)
+        this.ignoredErrors = [];
         // keep a record of all row and column pageBreaks
         this.rowBreaks = [];
         this.colBreaks = [];
@@ -212,6 +216,8 @@ class WorksheetWriter {
         this._writeBackground(); // Note: must be after drawing
         // Legacy Data tag for comments
         this._writeLegacyData();
+        // ignoredErrors must be before extLst
+        this._writeIgnoredErrors();
         // extLst must be the last child element before </worksheet>
         this._writeExtLst();
         this._writeCloseWorksheet();
@@ -529,18 +535,33 @@ class WorksheetWriter {
             }
             throw new Error(`Invalid image range: "${range}". Expected a range like "A1:C3".`);
         }
-        const tl = new Anchor(this, range.tl, 0).model;
-        const br = range.br ? new Anchor(this, range.br, 0).model : undefined;
+        // Absolute positioning (pos + ext, no cell anchors)
+        if ("pos" in range && range.pos) {
+            return {
+                type: "image",
+                imageId,
+                range: {
+                    tl: { nativeCol: 0, nativeColOff: 0, nativeRow: 0, nativeRowOff: 0 },
+                    ext: range.ext,
+                    pos: range.pos
+                },
+                hyperlinks: range.hyperlinks
+            };
+        }
+        // Cell-based positioning (tl/br anchors)
+        const cellRange = range;
+        const tl = new Anchor(this, cellRange.tl, 0).model;
+        const br = cellRange.br ? new Anchor(this, cellRange.br, 0).model : undefined;
         return {
             type: "image",
             imageId,
             range: {
                 tl,
                 br,
-                ext: range.ext,
-                editAs: range.editAs
+                ext: cellRange.ext,
+                editAs: cellRange.editAs
             },
-            hyperlinks: range.hyperlinks
+            hyperlinks: cellRange.hyperlinks
         };
     }
     // =========================================================================
@@ -617,6 +638,9 @@ class WorksheetWriter {
         }
         if (row.hasValues || row.height != null) {
             const { model } = row;
+            if (!model) {
+                return;
+            }
             const options = {
                 styles: this._workbook.styles,
                 sharedStrings: this.useSharedStrings ? this._workbook.sharedStrings : undefined,
@@ -628,6 +652,14 @@ class WorksheetWriter {
             };
             xform.row.prepare(model, options);
             this.stream.write(xform.row.toXml(model));
+            // Count dynamic array formula cells for metadata generation
+            if (model.cells) {
+                for (const cell of model.cells) {
+                    if (cell && cell.isDynamicArray) {
+                        this._workbook.dynamicArrayCount++;
+                    }
+                }
+            }
             if (options.comments.length) {
                 this.hasComments = true;
                 this._sheetCommentsWriter.addComments(options.comments);
@@ -680,6 +712,11 @@ class WorksheetWriter {
         const model = { conditionalFormattings: this.conditionalFormatting };
         this.stream.write(xform.extLst.toXml(model));
     }
+    _writeIgnoredErrors() {
+        if (this.ignoredErrors.length > 0) {
+            this.stream.write(xform.ignoredErrors.toXml(this.ignoredErrors));
+        }
+    }
     _writeRowBreaks() {
         this.stream.write(xform.rowBreaks.toXml(this.rowBreaks));
     }
@@ -753,6 +790,9 @@ class WorksheetWriter {
         if (this._background) {
             if (this._background.imageId !== undefined) {
                 const image = this._workbook.getImage(this._background.imageId);
+                if (!image) {
+                    return;
+                }
                 const pictureId = this._sheetRelsWriter.addMedia({
                     Target: mediaRelTargetFromRels(image.name),
                     Type: RelType.Image

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

@@ -535,14 +535,27 @@ class Table {
         this._ensureStyle().showColumnStripes = value;
     }
 }
+// SUBTOTAL function codes per OOXML/Excel:
+//   1/101=AVERAGE, 2/102=COUNT, 3/103=COUNTA, 4/104=MAX, 5/105=MIN,
+//   6/106=PRODUCT, 7/107=STDEV, 8/108=STDEVP, 9/109=SUM, 10/110=VAR, 11/111=VARP.
+// The 1xx variants also ignore manually hidden rows — Excel always uses
+// these for totals-row injection. OOXML totalsRowFunction names map to:
+//   average → 1 (AVERAGE)
+//   countNums → 2 (COUNT, numeric-only)
+//   count → 3 (COUNTA)
+//   max → 4
+//   min → 5
+//   stdDev → 7 (sample std dev, per Excel's totals UI)
+//   var → 10  (sample variance, per Excel's totals UI)
+//   sum → 9
 Table.SUBTOTAL_FUNCTIONS = {
     average: 101,
     countNums: 102,
     count: 103,
     max: 104,
     min: 105,
-    stdDev: 106,
-    var: 107,
+    stdDev: 107,
+    var: 110,
     sum: 109
 };
 export { Table, sanitizeTableName };

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

@@ -299,6 +299,21 @@ const colCache = {
                 throw new InvalidAddressError(String(args.length), "Can only encode with 2 or 4 arguments");
         }
     },
+    /**
+     * Compare two cell addresses by column then row (numeric order).
+     *
+     * Returns a negative number if `a` should come before `b`,
+     * a positive number if `a` should come after `b`, or zero if equal.
+     *
+     * This avoids the pitfalls of `localeCompare` which treats addresses
+     * as strings (e.g. "C10" < "C2") instead of comparing their numeric
+     * column and row components.
+     */
+    compareAddress(a, b) {
+        const addrA = colCache.decodeAddress(a);
+        const addrB = colCache.decodeAddress(b);
+        return addrA.col - addrB.col || addrA.row - addrB.row;
+    },
     // return true if address is contained within range
     inRange(range, address) {
         const [left, top, , right, bottom] = range;

package/dist/esm/modules/excel/utils/drawing-utils.js

@@ -101,6 +101,10 @@ export function filterDrawingAnchors(anchors) {
         if (a == null) {
             return false;
         }
+        // Absolute anchors need a valid picture
+        if (a.range?.pos !== undefined) {
+            return !!a.picture;
+        }
         // Form controls have range.br and shape properties
         if (a.range?.br && a.shape) {
             return true;

package/dist/esm/modules/excel/utils/external-link-formula.js

@@ -0,0 +1,208 @@
+/**
+ * Utilities for manipulating the external-workbook prefix in formula strings.
+ *
+ * Excel formula strings containing external workbook references have the
+ * shape `[<workbook>]Sheet!Ref` where `<workbook>` is either
+ *
+ *   - a 1-based numeric index  — `[1]Sheet1!A1`  (the canonical on-disk form
+ *     stored inside `<f>` elements of worksheet XML), or
+ *   - a filename / relative path — `[测试.xlsx]Sheet1!A1`  (what Excel
+ *     displays in the formula bar; not part of the OOXML storage contract,
+ *     but produced by hand-written formulas and some older tools).
+ *
+ * When writing, excelts always emits the numeric form — indices map
+ * positionally into the workbook's `<externalReferences>` list. When a
+ * formula arrives with the filename form, the writer assigns (or reuses) an
+ * ExternalLinkModel with that filename as its `target` and rewrites the
+ * formula to the numeric form. This matches how Excel itself stores formulas
+ * and makes them round-trippable.
+ *
+ * The quoted variant `'[file.xlsx]Sheet with space'!A1` is handled too — Excel
+ * wraps the `[name]Sheet` segment in single quotes when the sheet name needs
+ * quoting. The matching logic here recognises both the unquoted and quoted
+ * forms, rewriting inside the quotes when needed.
+ *
+ * Edge cases we explicitly *do not* treat as external refs:
+ *   - `[@Column]`, `[#Headers]`, `[Column Name]` — table structured refs
+ *     (no `]Sheet!` tail). The regex requires the `]<sheet>!` follow-up,
+ *     which structured refs never have.
+ *   - Array literals `{1,2;3,4}` use `{}`, not `[]`.
+ *   - String literals `"[Book]Sheet!A1"` — handled by scanning only outside
+ *     string literal regions.
+ */
+// Matches an external-ref prefix in a formula:
+//   Group 1 captures the workbook token inside [...], which is either
+//   digits-only (numeric form) or a filename that may include path separators
+//   when the whole prefix is single-quoted.
+//
+// Two variants:
+//   1. Unquoted: [Book]Sheet!A1       — Windows-filename-safe chars only in
+//      workbook token, then identifier sheet name, then !
+//   2. Quoted:   '[path/to/Book]Sheet name'!A1    — quoted segment allows
+//      paths / spaces / most punctuation inside the brackets; the sheet
+//      name inside the quotes can contain anything except `'` (escaped as '')
+//
+// The regex matches through and including the trailing `!` so callers don't
+// have to re-parse the A1/range part.
+// Unquoted form: workbook token must not contain characters that would
+// make the formula string ambiguous ( ] / \ space). This matches what Excel
+// itself writes for the bare-filename case — anything more exotic is
+// written in the quoted form by Excel.
+const UNQUOTED_EXTERNAL_REF = /\[([^\]\\/:*?"<>|\s]+)\]([A-Za-z_\u00A1-\uFFFF][A-Za-z0-9_\u00A1-\uFFFF.]*)!/g;
+// Quoted form: everything inside [] is permissive (any char except `]`),
+// since the outer `'..'` quotes absorb the surrounding formula
+// delimiters. Sheet name inside quotes is likewise permissive (any char
+// except `'`, with `''` representing an escaped quote).
+const QUOTED_EXTERNAL_REF = /'\[([^\]]+)\]((?:''|[^'])+)'!/g;
+/**
+ * Scan a formula string for all external-workbook references. String
+ * literals (inside `"..."`) are skipped so that a string value like
+ * `"[Book]Sheet!A1"` is not misidentified as a ref.
+ *
+ * The returned matches are in source order. If a formula contains no
+ * external refs, the array is empty.
+ */
+export function findExternalRefs(formula) {
+    // Fast-fail: external refs always include a `[`. Skipping the
+    // string-literal scan + two regex passes for plain cell refs (A1+B1,
+    // SUM(A1:A5), 99% of real workbooks) saves noticeable time on large
+    // sheets with thousands of formulas.
+    if (formula.indexOf("[") === -1) {
+        return [];
+    }
+    const matches = [];
+    const safeRegions = stringLiteralRegions(formula);
+    const addMatch = (start, end, workbook, sheet, quoted, match) => {
+        if (insideAnyRegion(start, safeRegions)) {
+            return;
+        }
+        const numeric = /^\d+$/.test(workbook);
+        matches.push({
+            match,
+            workbook,
+            numeric,
+            index: numeric ? parseInt(workbook, 10) : null,
+            sheet: unquoteSheetName(sheet),
+            quoted,
+            start,
+            end
+        });
+    };
+    UNQUOTED_EXTERNAL_REF.lastIndex = 0;
+    let m;
+    while ((m = UNQUOTED_EXTERNAL_REF.exec(formula)) !== null) {
+        addMatch(m.index, m.index + m[0].length, m[1], m[2], false, m[0]);
+    }
+    QUOTED_EXTERNAL_REF.lastIndex = 0;
+    while ((m = QUOTED_EXTERNAL_REF.exec(formula)) !== null) {
+        addMatch(m.index, m.index + m[0].length, m[1], m[2], true, m[0]);
+    }
+    // Sort matches by start offset so callers can process them in source
+    // order (needed when rewriting with offset bookkeeping).
+    matches.sort((a, b) => a.start - b.start);
+    // Deduplicate overlapping matches (the unquoted regex can technically
+    // match a prefix of a quoted sheet name in pathological inputs). Take
+    // the first of any overlap.
+    const out = [];
+    let lastEnd = -1;
+    for (const ref of matches) {
+        if (ref.start >= lastEnd) {
+            out.push(ref);
+            lastEnd = ref.end;
+        }
+    }
+    return out;
+}
+/**
+ * Replace every external-workbook token in `formula` using the supplied
+ * resolver. The resolver is called once per match and returns the numeric
+ * index to substitute; returning `null` leaves the match unchanged (useful
+ * when the caller cannot resolve a particular filename).
+ *
+ * Returns the rewritten formula. Offsets inside the original formula are
+ * adjusted correctly even when multiple rewrites change the total length.
+ */
+export function rewriteExternalRefs(formula, resolve) {
+    const refs = findExternalRefs(formula);
+    if (refs.length === 0) {
+        return formula;
+    }
+    let out = "";
+    let cursor = 0;
+    for (const ref of refs) {
+        const index = resolve(ref);
+        if (index === null) {
+            continue; // leave this ref alone; cursor stays put
+        }
+        out += formula.slice(cursor, ref.start);
+        // Construct the replacement: keep the quoted/unquoted shape, swap the
+        // workbook token for [N], preserve the sheet segment exactly.
+        if (ref.quoted) {
+            // The quoted variant surrounds `[Book]Sheet` with single quotes,
+            // followed by `!`. We swap the [Book] part for [N] and keep the
+            // rest (including the closing `'!`) unchanged so sheet-name
+            // quoting is preserved exactly.
+            const inner = formula.slice(ref.start + 1, ref.end - 2); // between quotes, excluding trailing '!
+            out += "'" + inner.replace(/^\[[^\]]*\]/, `[${index}]`) + "'!";
+        }
+        else {
+            out += `[${index}]${ref.match.slice(ref.match.indexOf("]") + 1)}`;
+        }
+        cursor = ref.end;
+    }
+    out += formula.slice(cursor);
+    return out;
+}
+// ===========================================================================
+// Internal helpers
+// ===========================================================================
+/**
+ * Return the spans of string literal regions in a formula, as half-open
+ * [start, end) intervals (exclusive of the surrounding quotes themselves).
+ * Used to skip external-ref matches that fall inside a string value.
+ */
+function stringLiteralRegions(formula) {
+    // Fast-fail when the formula has no double-quote at all — very common
+    // for pure arithmetic / reference formulas.
+    if (formula.indexOf('"') === -1) {
+        return [];
+    }
+    const regions = [];
+    const len = formula.length;
+    let i = 0;
+    while (i < len) {
+        if (formula[i] === '"') {
+            const start = i;
+            i++;
+            while (i < len) {
+                if (formula[i] === '"') {
+                    if (i + 1 < len && formula[i + 1] === '"') {
+                        i += 2; // escaped quote inside string — keep scanning
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            regions.push([start, i]);
+        }
+        else {
+            i++;
+        }
+    }
+    return regions;
+}
+function insideAnyRegion(pos, regions) {
+    for (const [a, b] of regions) {
+        if (pos >= a && pos < b) {
+            return true;
+        }
+    }
+    return false;
+}
+function unquoteSheetName(sheet) {
+    // The quoted form captured inside `'..'` may have doubled single quotes
+    // that represent a single quote in the logical sheet name.
+    return sheet.replace(/''/g, "'");
+}

package/dist/esm/modules/excel/utils/iterate-stream.js

@@ -39,7 +39,9 @@ async function* iterateStream(stream) {
             else {
                 stream.pause();
                 const data = contents.shift();
-                yield data;
+                if (data !== undefined) {
+                    yield data;
+                }
             }
             if (error) {
                 throw toError(error);

package/dist/esm/modules/excel/utils/ooxml-paths.js

@@ -8,7 +8,8 @@ export const OOXML_PATHS = {
     xlSharedStrings: "xl/sharedStrings.xml",
     xlStyles: "xl/styles.xml",
     xlTheme1: "xl/theme/theme1.xml",
-    xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml"
+    xlFeaturePropertyBag: "xl/featurePropertyBag/featurePropertyBag.xml",
+    xlMetadata: "xl/metadata.xml"
 };
 const worksheetXmlRegex = /^xl\/worksheets\/sheet(\d+)[.]xml$/;
 const worksheetRelsXmlRegex = /^xl\/worksheets\/_rels\/sheet(\d+)[.]xml[.]rels$/;
@@ -25,6 +26,9 @@ const pivotTableRelsXmlRegex = /^xl\/pivotTables\/_rels\/(pivotTable\d+)[.]xml[.
 const pivotCacheDefinitionXmlRegex = /^xl\/pivotCache\/(pivotCacheDefinition\d+)[.]xml$/;
 const pivotCacheDefinitionRelsXmlRegex = /^xl\/pivotCache\/_rels\/(pivotCacheDefinition\d+)[.]xml[.]rels$/;
 const pivotCacheRecordsXmlRegex = /^xl\/pivotCache\/(pivotCacheRecords\d+)[.]xml$/;
+// External workbook links (xl/externalLinks/externalLink{n}.xml and its rels)
+const externalLinkXmlRegex = /^xl\/externalLinks\/externalLink(\d+)[.]xml$/;
+const externalLinkRelsXmlRegex = /^xl\/externalLinks\/_rels\/externalLink(\d+)[.]xml[.]rels$/;
 export function normalizeZipPath(path) {
     return path.startsWith("/") ? path.slice(1) : path;
 }
@@ -105,6 +109,22 @@ export function getPivotCacheRecordsNameFromPath(path) {
     const match = pivotCacheRecordsXmlRegex.exec(path);
     return match ? match[1] : undefined;
 }
+/**
+ * Extract the 1-based index `N` from `xl/externalLinks/externalLink{N}.xml`.
+ * Returns the raw integer (e.g. `1` for externalLink1.xml) or undefined.
+ */
+export function getExternalLinkIndexFromPath(path) {
+    const match = externalLinkXmlRegex.exec(path);
+    return match ? parseInt(match[1], 10) : undefined;
+}
+/**
+ * Extract the 1-based index `N` from
+ * `xl/externalLinks/_rels/externalLink{N}.xml.rels`.
+ */
+export function getExternalLinkIndexFromRelsPath(path) {
+    const match = externalLinkRelsXmlRegex.exec(path);
+    return match ? parseInt(match[1], 10) : undefined;
+}
 export function toContentTypesPartName(zipPath) {
     // ContentTypes uses leading slash PartName (e.g. "/xl/workbook.xml").
     return zipPath.startsWith("/") ? zipPath : `/${zipPath}`;
@@ -167,6 +187,20 @@ export function pivotTablePath(n) {
 export function pivotTableRelsPath(n) {
     return `xl/pivotTables/_rels/pivotTable${n}.xml.rels`;
 }
+// -------- External links --------
+export function externalLinkPath(n) {
+    return `xl/externalLinks/externalLink${n}.xml`;
+}
+export function externalLinkRelsPath(n) {
+    return `xl/externalLinks/_rels/externalLink${n}.xml.rels`;
+}
+/**
+ * Build the `Target` value for an externalLink relationship inside
+ * `xl/_rels/workbook.xml.rels` (base: `xl/`).
+ */
+export function externalLinkRelTargetFromWorkbook(n) {
+    return `externalLinks/externalLink${n}.xml`;
+}
 export function pivotCacheDefinitionRelTargetFromPivotTable(n) {
     return `../pivotCache/pivotCacheDefinition${n}.xml`;
 }
@@ -175,7 +209,8 @@ export const OOXML_REL_TARGETS = {
     workbookStyles: "styles.xml",
     workbookSharedStrings: "sharedStrings.xml",
     workbookTheme1: "theme/theme1.xml",
-    workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml"
+    workbookFeaturePropertyBag: "featurePropertyBag/featurePropertyBag.xml",
+    workbookMetadata: "metadata.xml"
 };
 export function pivotCacheDefinitionRelTargetFromWorkbook(n) {
     // Target inside xl/_rels/workbook.xml.rels (base: xl/)

package/dist/esm/modules/excel/utils/shared-strings.js

@@ -1,3 +1,21 @@
+/**
+ * Canonical JSON serializer with sorted object keys.
+ *
+ * Used to derive an insertion-order-independent dedupe key for rich-text
+ * shared-string entries. Two semantically identical run/font objects must
+ * map to the same key regardless of the order their properties were assigned.
+ */
+function canonicalStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalStringify).join(",")}]`;
+    }
+    const keys = Object.keys(value).sort();
+    const obj = value;
+    return `{${keys.map(k => `${JSON.stringify(k)}:${canonicalStringify(obj[k])}`).join(",")}}`;
+}
 class SharedStrings {
     constructor() {
         this._values = [];
@@ -17,9 +35,10 @@ class SharedStrings {
         return this._values[index];
     }
     add(value) {
-        let index = this._hash[value];
+        const key = typeof value === "string" ? `s:${value}` : `r:${canonicalStringify(value.richText)}`;
+        let index = this._hash[key];
         if (index === undefined) {
-            index = this._hash[value] = this._values.length;
+            index = this._hash[key] = this._values.length;
             this._values.push(value);
         }
         this._totalRefs++;