@devmm/puredocs-excel 1.0.0 → 1.0.2

package/dist/index.cjs

@@ -346,11 +346,22 @@ ${sheetRels}
   <Relationship Id="rId${sharedId}" Type="${REL_TYPES.sharedStrings}" Target="sharedStrings.xml"/>
 </Relationships>`;
 }
-function buildWorkbookXml(sheets) {
+function buildWorkbookXml(sheets, definedNames = []) {
   const sheetElems = sheets.map(({ name, sheetId, relationshipId, state }) => {
     const stateAttr = state && state !== "visible" ? ` state="${state}"` : "";
     return `    <sheet name="${escapeAttr(name)}" sheetId="${sheetId}" r:id="${relationshipId}"${stateAttr}/>`;
   }).join("\n");
+  let definedNamesBlock = "";
+  if (definedNames.length > 0) {
+    const items = definedNames.map(({ name, refersTo, localSheetId }) => {
+      const local = localSheetId !== void 0 ? ` localSheetId="${localSheetId}"` : "";
+      return `    <definedName name="${escapeAttr(name)}"${local}>${escapeContent(refersTo)}</definedName>`;
+    }).join("\n");
+    definedNamesBlock = `
+  <definedNames>
+${items}
+  </definedNames>`;
+  }
   return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main"
           xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">
@@ -361,7 +372,7 @@ function buildWorkbookXml(sheets) {
   </bookViews>
   <sheets>
 ${sheetElems}
-  </sheets>
+  </sheets>${definedNamesBlock}
   <calcPr calcId="191028" fullCalcOnLoad="1"/>
 </workbook>`;
 }
@@ -373,6 +384,9 @@ var EMPTY_WORKSHEET_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"
 function escapeAttr(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
+function escapeContent(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
 
 // src/io/drawing-part.ts
 var WORKSHEET_DRAWING_REL_ID = "rId1";
@@ -1752,6 +1766,54 @@ var Cell = class {
     __privateGet(this, _data).formula = formula.startsWith("=") ? formula.slice(1) : formula;
     __privateGet(this, _data).rawValue = void 0;
     __privateGet(this, _data).dataType = void 0;
+    __privateGet(this, _data).arrayRef = void 0;
+    return this;
+  }
+  /**
+   * Marks (or unmarks) this cell as a dynamic-array formula anchor. `spillRef`
+   * is the block the array spills over (e.g. "A1:C2"); pass null to revert to a
+   * plain scalar formula. Serialises as `<f t="array" ref="…">`.
+   */
+  setArrayRef(spillRef) {
+    __privateGet(this, _data).arrayRef = spillRef ?? void 0;
+    return this;
+  }
+  /** The dynamic-array spill range, or null if this is not an array anchor. */
+  getArrayRef() {
+    return __privateGet(this, _data).arrayRef ?? null;
+  }
+  /**
+   * Sets the cached/computed result of this cell WITHOUT touching its formula.
+   *
+   * This is what a recalculation engine calls after evaluating the formula: it
+   * stores the value that XLSX serialises into `<v>` alongside the `<f>`. Unlike
+   * setValue(), it does NOT clear the formula, and strings are stored inline
+   * (t="str") the way Excel stores calculated string results — they are not
+   * added to the shared-string table.
+   */
+  setComputedValue(value) {
+    if (value === null || value === void 0) {
+      __privateGet(this, _data).dataType = void 0;
+      __privateGet(this, _data).rawValue = void 0;
+      return this;
+    }
+    if (typeof value === "string") {
+      __privateGet(this, _data).dataType = "str";
+      __privateGet(this, _data).rawValue = value;
+      return this;
+    }
+    if (typeof value === "boolean") {
+      __privateGet(this, _data).dataType = "b";
+      __privateGet(this, _data).rawValue = value ? "1" : "0";
+      return this;
+    }
+    if (value instanceof Date) {
+      __privateGet(this, _data).dataType = "n";
+      __privateGet(this, _data).rawValue = String(toOADate(value));
+      return this;
+    }
+    __privateGet(this, _data).dataType = "n";
+    __privateGet(this, _data).rawValue = String(value);
     return this;
   }
   /** Returns the formula text (without leading '='), or null if no formula. */
@@ -1824,6 +1886,7 @@ var Cell = class {
     __privateGet(this, _data).rawValue = void 0;
     __privateGet(this, _data).dataType = void 0;
     __privateGet(this, _data).formula = void 0;
+    __privateGet(this, _data).arrayRef = void 0;
   }
   /** Clears the cell value, formula, AND style. */
   clearAll() {
@@ -1836,7 +1899,7 @@ var Cell = class {
     const ref = __privateGet(this, _data).reference;
     const style = __privateGet(this, _data).styleIndex > 0 ? ` s="${__privateGet(this, _data).styleIndex}"` : "";
     const type = __privateGet(this, _data).dataType ? ` t="${__privateGet(this, _data).dataType}"` : "";
-    const formulaXml = __privateGet(this, _data).formula ? `<f>${escXml(__privateGet(this, _data).formula)}</f>` : "";
+    const formulaXml = __privateGet(this, _data).formula ? __privateGet(this, _data).arrayRef ? `<f t="array" ref="${__privateGet(this, _data).arrayRef}" aca="1" ca="1">${escXml(__privateGet(this, _data).formula)}</f>` : `<f>${escXml(__privateGet(this, _data).formula)}</f>` : "";
     const valueXml = __privateGet(this, _data).rawValue !== void 0 && __privateGet(this, _data).rawValue !== "" ? `<v>${escXml(__privateGet(this, _data).rawValue)}</v>` : "";
     if (!formulaXml && !valueXml && __privateGet(this, _data).styleIndex === 0) return "";
     return `<c r="${ref}"${style}${type}>${formulaXml}${valueXml}</c>`;
@@ -1847,12 +1910,18 @@ var Cell = class {
     const styleIndex = parseInt(el.attributes["s"] ?? "0", 10);
     let rawValue;
     let formula;
+    let arrayRef;
     for (const child of el.children) {
       const tag = child.tagName.replace(/^.*:/, "");
       if (tag === "v") rawValue = child.textContent;
-      if (tag === "f") formula = child.textContent;
+      if (tag === "f") {
+        formula = child.textContent;
+        if (child.attributes && child.attributes["t"] === "array" && child.attributes["ref"]) {
+          arrayRef = child.attributes["ref"];
+        }
+      }
     }
-    return { reference: ref, dataType, rawValue, formula, styleIndex };
+    return { reference: ref, dataType, rawValue, formula, arrayRef, styleIndex };
   }
 };
 _data = new WeakMap();
@@ -2075,6 +2144,14 @@ var Worksheet = class {
   getCellValue(reference) {
     return this.tryGetCell(reference)?.getValue() ?? null;
   }
+  /** Formula text (without leading '=') of a cell, or null if it has none. */
+  getCellFormula(reference) {
+    return this.tryGetCell(reference)?.getFormula() ?? null;
+  }
+  /** Spill range (e.g. "A1:A3") of a dynamic-array anchor, or null. Supports A1#. */
+  getSpillRange(reference) {
+    return this.tryGetCell(reference)?.getArrayRef() ?? null;
+  }
   /**
    * Returns the 1-based extent of populated cells (largest row and column that
    * contain data). Returns zeros for an empty sheet. Useful for snapshotting a
@@ -2125,6 +2202,15 @@ var Worksheet = class {
     row.height = height;
     row.customHeight = true;
   }
+  /** Shows or hides a row (1-based index). Hidden rows affect SUBTOTAL(101-111). */
+  setRowHidden(rowIndex, hidden = true) {
+    if (rowIndex < 1) throw new RangeError("Row index must be >= 1.");
+    __privateMethod(this, _Worksheet_instances, getOrCreateRow_fn).call(this, rowIndex).hidden = hidden;
+  }
+  /** True if the given 1-based row is hidden. */
+  isRowHidden(rowIndex) {
+    return __privateGet(this, _rows).get(rowIndex)?.hidden === true;
+  }
   /** Merges cells in the given range (e.g. "A1:B2"). */
   mergeCells(rangeReference) {
     if (!rangeReference) throw new Error("Range reference cannot be empty.");
@@ -2224,6 +2310,7 @@ ${colsXml}${sheetDataXml}${filterXml}${mergeXml}${validXml}${drawingXml}
         rowData.height = parseFloat(ht);
         rowData.customHeight = true;
       }
+      if (getAttr(rowEl, "hidden") === "1") rowData.hidden = true;
       for (const cellEl of rowEl.children) {
         const tag = cellEl.tagName.replace(/^.*:/, "");
         if (tag !== "c") continue;
@@ -2289,14 +2376,15 @@ buildSheetDataXml_fn = function() {
   if (sortedRows.length === 0) return "<sheetData/>";
   const rowsXml = sortedRows.map((row) => {
     const ht = row.height !== void 0 && row.customHeight ? ` ht="${row.height}" customHeight="1"` : "";
+    const hidden = row.hidden ? ' hidden="1"' : "";
     const sortedCells = [...row.cells.values()].sort((a, b) => {
       const ra = parseCellRef(a.reference);
       const rb = parseCellRef(b.reference);
       return ra.column - rb.column;
     });
     const cellsXml = sortedCells.map((cd) => new Cell(cd, __privateGet(this, _sharedStrings2), __privateGet(this, _styles2)).toXml()).filter(Boolean).join("");
-    if (!cellsXml && !ht) return "";
-    return `<row r="${row.rowIndex}"${ht}>${cellsXml}</row>`;
+    if (!cellsXml && !ht && !hidden) return "";
+    return `<row r="${row.rowIndex}"${ht}${hidden}>${cellsXml}</row>`;
   }).filter(Boolean).join("");
   return `<sheetData>${rowsXml}</sheetData>`;
 };
@@ -2335,14 +2423,77 @@ function escXml2(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 
+// src/model/defined-name.ts
+var _names, _DefinedNameManager_instances, indexOf_fn;
+var DefinedNameManager = class {
+  constructor() {
+    __privateAdd(this, _DefinedNameManager_instances);
+    __privateAdd(this, _names, []);
+  }
+  /** All defined names, in insertion order. */
+  get all() {
+    return __privateGet(this, _names);
+  }
+  get size() {
+    return __privateGet(this, _names).length;
+  }
+  /**
+   * Adds or replaces a defined name. A name is uniquely identified by the pair
+   * (identifier, scope): the same identifier may exist once globally and once
+   * per worksheet. The leading '=' of refersTo is stripped.
+   */
+  define(name, refersTo, scope) {
+    if (!name) throw new Error("Defined name cannot be empty.");
+    if (!refersTo) throw new Error("Defined name refersTo cannot be empty.");
+    const cleaned = refersTo.startsWith("=") ? refersTo.slice(1) : refersTo;
+    const idx = __privateMethod(this, _DefinedNameManager_instances, indexOf_fn).call(this, name, scope);
+    const entry = { name, refersTo: cleaned, scope };
+    if (idx >= 0) __privateGet(this, _names)[idx] = entry;
+    else __privateGet(this, _names).push(entry);
+  }
+  /** Removes a defined name by identifier and scope. Returns true if removed. */
+  remove(name, scope) {
+    const idx = __privateMethod(this, _DefinedNameManager_instances, indexOf_fn).call(this, name, scope);
+    if (idx < 0) return false;
+    __privateGet(this, _names).splice(idx, 1);
+    return true;
+  }
+  /**
+   * Resolves a name to its refers-to expression following Excel scoping:
+   * a name scoped to `sheetName` takes precedence over the workbook-global
+   * name of the same identifier. Returns undefined if no name matches.
+   */
+  resolve(name, sheetName) {
+    const key = name.toUpperCase();
+    if (sheetName) {
+      const local = __privateGet(this, _names).find(
+        (n) => n.name.toUpperCase() === key && n.scope?.toUpperCase() === sheetName.toUpperCase()
+      );
+      if (local) return local.refersTo;
+    }
+    const global = __privateGet(this, _names).find((n) => n.name.toUpperCase() === key && n.scope === void 0);
+    return global?.refersTo;
+  }
+};
+_names = new WeakMap();
+_DefinedNameManager_instances = new WeakSet();
+indexOf_fn = function(name, scope) {
+  const key = name.toUpperCase();
+  const scopeKey = scope?.toUpperCase();
+  return __privateGet(this, _names).findIndex(
+    (n) => n.name.toUpperCase() === key && n.scope?.toUpperCase() === scopeKey
+  );
+};
+
 // src/model/workbook.ts
-var _sharedStrings3, _styles3, _sheets, _closed, _Workbook_instances, assertOpen_fn, buildZipEntries_fn;
+var _sharedStrings3, _styles3, _sheets, _definedNames, _closed, _Workbook_instances, assertOpen_fn, buildZipEntries_fn;
 var _Workbook = class _Workbook {
   constructor(sharedStrings, styles) {
     __privateAdd(this, _Workbook_instances);
     __privateAdd(this, _sharedStrings3);
     __privateAdd(this, _styles3);
     __privateAdd(this, _sheets, []);
+    __privateAdd(this, _definedNames, new DefinedNameManager());
     __privateAdd(this, _closed, false);
     __privateSet(this, _sharedStrings3, sharedStrings);
     __privateSet(this, _styles3, styles);
@@ -2386,6 +2537,19 @@ var _Workbook = class _Workbook {
       ws.loadFromXml(wsXml);
       __privateGet(wb, _sheets).push({ worksheet: ws, sheetId, relId });
     }
+    for (const dn of getElementsByTagName(wbRoot, "definedName")) {
+      const name = getAttr(dn, "name");
+      if (!name) continue;
+      const refersTo = dn.textContent.trim();
+      if (!refersTo) continue;
+      const localSheetId = getAttr(dn, "localSheetId");
+      let scope;
+      if (localSheetId !== void 0) {
+        const idx = parseInt(localSheetId, 10);
+        scope = __privateGet(wb, _sheets)[idx]?.worksheet.name;
+      }
+      __privateGet(wb, _definedNames).define(name, refersTo, scope);
+    }
     return wb;
   }
   /**
@@ -2430,6 +2594,43 @@ var _Workbook = class _Workbook {
     if (!entry) throw new Error(`Worksheet "${name}" not found.`);
     return entry.worksheet;
   }
+  // ── Defined names (named ranges) ─────────────────────────────────────────────
+  /**
+   * Defines (or replaces) a named range.
+   *
+   * @param name     The name identifier (case-insensitive when resolved).
+   * @param refersTo The refers-to expression, e.g. "Sheet1!$A$1:$B$10". A
+   *                 leading '=' is optional and stripped.
+   * @param options  `scope` restricts the name to a single worksheet; omit for
+   *                 a workbook-global name.
+   */
+  defineName(name, refersTo, options) {
+    __privateMethod(this, _Workbook_instances, assertOpen_fn).call(this);
+    const scope = options?.scope;
+    if (scope !== void 0 && !__privateGet(this, _sheets).some((e) => e.worksheet.name === scope)) {
+      throw new Error(`Cannot scope defined name "${name}" to unknown worksheet "${scope}".`);
+    }
+    __privateGet(this, _definedNames).define(name, refersTo, scope);
+  }
+  /**
+   * Resolves a defined name to its refers-to expression (without leading '=').
+   * Follows Excel scoping: a name scoped to `sheetName` wins over the global
+   * name of the same identifier. Returns undefined if no name matches.
+   *
+   * This is the seam the formula engine calls to resolve NamedRangeNode.
+   */
+  getDefinedName(name, sheetName) {
+    return __privateGet(this, _definedNames).resolve(name, sheetName);
+  }
+  /** Removes a defined name. Returns true if a matching name was removed. */
+  removeName(name, scope) {
+    __privateMethod(this, _Workbook_instances, assertOpen_fn).call(this);
+    return __privateGet(this, _definedNames).remove(name, scope);
+  }
+  /** All defined names in the workbook, in insertion order. */
+  get definedNames() {
+    return __privateGet(this, _definedNames).all;
+  }
   // ── Serialisation ──────────────────────────────────────────────────────────
   /**
    * Serialises the workbook to a Uint8Array (xlsx binary).
@@ -2467,6 +2668,7 @@ var _Workbook = class _Workbook {
 _sharedStrings3 = new WeakMap();
 _styles3 = new WeakMap();
 _sheets = new WeakMap();
+_definedNames = new WeakMap();
 _closed = new WeakMap();
 _Workbook_instances = new WeakSet();
 // ── Private helpers ────────────────────────────────────────────────────────
@@ -2483,7 +2685,15 @@ buildZipEntries_fn = function() {
     relationshipId: e.relId,
     state: e.worksheet.visibility !== "visible" ? e.worksheet.visibility : void 0
   }));
-  entries.set("xl/workbook.xml", buildWorkbookXml(sheetMetas));
+  const definedNameMetas = __privateGet(this, _definedNames).all.map((dn) => {
+    let localSheetId;
+    if (dn.scope !== void 0) {
+      const idx = __privateGet(this, _sheets).findIndex((e) => e.worksheet.name === dn.scope);
+      if (idx >= 0) localSheetId = idx;
+    }
+    return { name: dn.name, refersTo: dn.refersTo, localSheetId };
+  });
+  entries.set("xl/workbook.xml", buildWorkbookXml(sheetMetas, definedNameMetas));
   entries.set("xl/_rels/workbook.xml.rels", buildWorkbookRels(sheetCount));
   entries.set("xl/styles.xml", __privateGet(this, _styles3).buildStylesXml());
   entries.set("xl/sharedStrings.xml", __privateGet(this, _sharedStrings3).buildXml());
@@ -2544,6 +2754,7 @@ function resolveWorksheetPath(relsXml, relId) {
 exports.CONTENT_TYPES = CONTENT_TYPES;
 exports.Cell = Cell;
 exports.CellStyle = CellStyle;
+exports.DefinedNameManager = DefinedNameManager;
 exports.ExcelAlignment = ExcelAlignment;
 exports.ExcelBorder = ExcelBorder;
 exports.ExcelBorderEdge = ExcelBorderEdge;