@devmm/puredocs-excel 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -474,6 +474,8 @@ interface CellData {
     dataType?: 's' | 'n' | 'b' | 'str';
     rawValue?: string;
     formula?: string;
+    /** Spill range for a dynamic-array formula anchor, e.g. "A1:A3". */
+    arrayRef?: string;
     styleIndex: number;
 }
 declare class Cell {
@@ -511,6 +513,24 @@ declare class Cell {
      * Clears any cached value.
      */
     setFormula(formula: string): 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: string | null): this;
+    /** The dynamic-array spill range, or null if this is not an array anchor. */
+    getArrayRef(): string | 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: CellValue): this;
     /** Returns the formula text (without leading '='), or null if no formula. */
     getFormula(): string | null;
     /** True if this cell contains a formula. */
@@ -551,6 +571,7 @@ declare class Cell {
         children: Array<{
             tagName: string;
             textContent: string;
+            attributes?: Record<string, string>;
         }>;
     }, ref: string): CellData;
 }
@@ -674,6 +695,10 @@ declare class Worksheet {
     getRange(rangeReference: string): Range;
     /** Gets the raw value of a cell (for formula evaluation). */
     getCellValue(reference: string): unknown;
+    /** Formula text (without leading '=') of a cell, or null if it has none. */
+    getCellFormula(reference: string): string | null;
+    /** Spill range (e.g. "A1:A3") of a dynamic-array anchor, or null. Supports A1#. */
+    getSpillRange(reference: string): string | 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
@@ -689,6 +714,10 @@ declare class Worksheet {
     autoFitColumn(columnIndex: number): void;
     /** Sets the height of a row (1-based index). */
     setRowHeight(rowIndex: number, height: number): void;
+    /** Shows or hides a row (1-based index). Hidden rows affect SUBTOTAL(101-111). */
+    setRowHidden(rowIndex: number, hidden?: boolean): void;
+    /** True if the given 1-based row is hidden. */
+    isRowHidden(rowIndex: number): boolean;
     /** Merges cells in the given range (e.g. "A1:B2"). */
     mergeCells(rangeReference: string): void;
     /** Removes a merge for the given range reference. */
@@ -726,6 +755,56 @@ declare class Worksheet {
     loadFromXml(xml: string): void;
 }
 
+/**
+ * Defined names (named ranges) for a workbook.
+ *
+ * A defined name maps an identifier (e.g. "TaxRate", "SalesData") to a
+ * refers-to expression (e.g. "Sheet1!$A$1", "Sheet1!$A$1:$B$10", "0.2*100").
+ * Names may be workbook-global or scoped to a single worksheet.
+ *
+ * This module only models and stores the data (and serialises it to OOXML).
+ * Resolution/evaluation of the refers-to expression is the responsibility of
+ * the formula engine (@devmm/puredocs-excel-formula), which reads names through
+ * Workbook.getDefinedName().
+ */
+/** A single defined name. */
+interface DefinedName {
+    /** The name identifier. Case-insensitive when resolved. */
+    readonly name: string;
+    /** The refers-to expression, WITHOUT a leading '='. */
+    readonly refersTo: string;
+    /**
+     * Worksheet name this name is scoped to, or undefined for a workbook-global
+     * name. Excel resolves a sheet-scoped name ahead of a global name of the
+     * same identifier when a formula on that sheet references it.
+     */
+    readonly scope?: string;
+}
+/**
+ * In-memory store for a workbook's defined names, with Excel scoping semantics.
+ * Kept separate from Workbook so the storage rules live in one place.
+ */
+declare class DefinedNameManager {
+    #private;
+    /** All defined names, in insertion order. */
+    get all(): readonly DefinedName[];
+    get size(): number;
+    /**
+     * 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: string, refersTo: string, scope?: string): void;
+    /** Removes a defined name by identifier and scope. Returns true if removed. */
+    remove(name: string, scope?: string): boolean;
+    /**
+     * 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: string, sheetName?: string): string | undefined;
+}
+
 declare class Workbook {
     #private;
     private constructor();
@@ -760,6 +839,30 @@ declare class Workbook {
      * Returns a worksheet by name. Throws if not found.
      */
     getWorksheet(name: string): Worksheet;
+    /**
+     * 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: string, refersTo: string, options?: {
+        scope?: string;
+    }): void;
+    /**
+     * 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: string, sheetName?: string): string | undefined;
+    /** Removes a defined name. Returns true if a matching name was removed. */
+    removeName(name: string, scope?: string): boolean;
+    /** All defined names in the workbook, in insertion order. */
+    get definedNames(): readonly DefinedName[];
     /**
      * Serialises the workbook to a Uint8Array (xlsx binary).
      * Mirrors workbook.SaveAs(stream) in C#.
@@ -1013,4 +1116,4 @@ declare function setXmlEntry(entries: ZipInput, path: string, xml: string): void
  */
 declare function setBinaryEntry(entries: ZipInput, path: string, bytes: Uint8Array): void;
 
-export { CONTENT_TYPES, Cell, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DrawingDependentPart, type DrawingProvider, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, NS, type ParsedCellRef, REL_TYPES, Range, type SheetVisibility, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, encodeUtf8, escapeXml, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, toOADate, unzipXlsx, xml, zipXlsx };
+export { CONTENT_TYPES, Cell, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DefinedName, DefinedNameManager, type DrawingDependentPart, type DrawingProvider, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, NS, type ParsedCellRef, REL_TYPES, Range, type SheetVisibility, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, encodeUtf8, escapeXml, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, toOADate, unzipXlsx, xml, zipXlsx };

package/dist/index.d.ts

@@ -474,6 +474,8 @@ interface CellData {
     dataType?: 's' | 'n' | 'b' | 'str';
     rawValue?: string;
     formula?: string;
+    /** Spill range for a dynamic-array formula anchor, e.g. "A1:A3". */
+    arrayRef?: string;
     styleIndex: number;
 }
 declare class Cell {
@@ -511,6 +513,24 @@ declare class Cell {
      * Clears any cached value.
      */
     setFormula(formula: string): 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: string | null): this;
+    /** The dynamic-array spill range, or null if this is not an array anchor. */
+    getArrayRef(): string | 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: CellValue): this;
     /** Returns the formula text (without leading '='), or null if no formula. */
     getFormula(): string | null;
     /** True if this cell contains a formula. */
@@ -551,6 +571,7 @@ declare class Cell {
         children: Array<{
             tagName: string;
             textContent: string;
+            attributes?: Record<string, string>;
         }>;
     }, ref: string): CellData;
 }
@@ -674,6 +695,10 @@ declare class Worksheet {
     getRange(rangeReference: string): Range;
     /** Gets the raw value of a cell (for formula evaluation). */
     getCellValue(reference: string): unknown;
+    /** Formula text (without leading '=') of a cell, or null if it has none. */
+    getCellFormula(reference: string): string | null;
+    /** Spill range (e.g. "A1:A3") of a dynamic-array anchor, or null. Supports A1#. */
+    getSpillRange(reference: string): string | 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
@@ -689,6 +714,10 @@ declare class Worksheet {
     autoFitColumn(columnIndex: number): void;
     /** Sets the height of a row (1-based index). */
     setRowHeight(rowIndex: number, height: number): void;
+    /** Shows or hides a row (1-based index). Hidden rows affect SUBTOTAL(101-111). */
+    setRowHidden(rowIndex: number, hidden?: boolean): void;
+    /** True if the given 1-based row is hidden. */
+    isRowHidden(rowIndex: number): boolean;
     /** Merges cells in the given range (e.g. "A1:B2"). */
     mergeCells(rangeReference: string): void;
     /** Removes a merge for the given range reference. */
@@ -726,6 +755,56 @@ declare class Worksheet {
     loadFromXml(xml: string): void;
 }
 
+/**
+ * Defined names (named ranges) for a workbook.
+ *
+ * A defined name maps an identifier (e.g. "TaxRate", "SalesData") to a
+ * refers-to expression (e.g. "Sheet1!$A$1", "Sheet1!$A$1:$B$10", "0.2*100").
+ * Names may be workbook-global or scoped to a single worksheet.
+ *
+ * This module only models and stores the data (and serialises it to OOXML).
+ * Resolution/evaluation of the refers-to expression is the responsibility of
+ * the formula engine (@devmm/puredocs-excel-formula), which reads names through
+ * Workbook.getDefinedName().
+ */
+/** A single defined name. */
+interface DefinedName {
+    /** The name identifier. Case-insensitive when resolved. */
+    readonly name: string;
+    /** The refers-to expression, WITHOUT a leading '='. */
+    readonly refersTo: string;
+    /**
+     * Worksheet name this name is scoped to, or undefined for a workbook-global
+     * name. Excel resolves a sheet-scoped name ahead of a global name of the
+     * same identifier when a formula on that sheet references it.
+     */
+    readonly scope?: string;
+}
+/**
+ * In-memory store for a workbook's defined names, with Excel scoping semantics.
+ * Kept separate from Workbook so the storage rules live in one place.
+ */
+declare class DefinedNameManager {
+    #private;
+    /** All defined names, in insertion order. */
+    get all(): readonly DefinedName[];
+    get size(): number;
+    /**
+     * 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: string, refersTo: string, scope?: string): void;
+    /** Removes a defined name by identifier and scope. Returns true if removed. */
+    remove(name: string, scope?: string): boolean;
+    /**
+     * 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: string, sheetName?: string): string | undefined;
+}
+
 declare class Workbook {
     #private;
     private constructor();
@@ -760,6 +839,30 @@ declare class Workbook {
      * Returns a worksheet by name. Throws if not found.
      */
     getWorksheet(name: string): Worksheet;
+    /**
+     * 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: string, refersTo: string, options?: {
+        scope?: string;
+    }): void;
+    /**
+     * 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: string, sheetName?: string): string | undefined;
+    /** Removes a defined name. Returns true if a matching name was removed. */
+    removeName(name: string, scope?: string): boolean;
+    /** All defined names in the workbook, in insertion order. */
+    get definedNames(): readonly DefinedName[];
     /**
      * Serialises the workbook to a Uint8Array (xlsx binary).
      * Mirrors workbook.SaveAs(stream) in C#.
@@ -1013,4 +1116,4 @@ declare function setXmlEntry(entries: ZipInput, path: string, xml: string): void
  */
 declare function setBinaryEntry(entries: ZipInput, path: string, bytes: Uint8Array): void;
 
-export { CONTENT_TYPES, Cell, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DrawingDependentPart, type DrawingProvider, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, NS, type ParsedCellRef, REL_TYPES, Range, type SheetVisibility, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, encodeUtf8, escapeXml, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, toOADate, unzipXlsx, xml, zipXlsx };
+export { CONTENT_TYPES, Cell, type CellData, CellStyle, type CellValue, type ColorXmlAttrs, type DefinedName, DefinedNameManager, type DrawingDependentPart, type DrawingProvider, ExcelAlignment, ExcelBorder, ExcelBorderEdge, ExcelBorderStyle, ExcelColor, ExcelFill, ExcelFont, type ExcelFontOptions, ExcelHorizontalAlignment, ExcelNumberFormat, ExcelPatternType, ExcelReadingOrder, ExcelUnderline, ExcelVerticalAlignRun, ExcelVerticalAlignment, NS, type ParsedCellRef, REL_TYPES, Range, type SheetVisibility, StyleManager, WORKSHEET_DRAWING_REL_ID, Workbook, Worksheet, type XmlAttrs, XmlBuilder, type XmlElement, type ZipEntries, type ZipInput, buildDrawingXml, buildRelsXml, cellRefFromRowCol, columnLetter, columnNumber, decodeUtf8, encodeUtf8, escapeXml, fromOADate, getAttr, getElementsByTagName, isDateFormatCode, isDateFormatId, listEntries, parseCellRef, parseRangeRef, parseXml, readXmlEntry, requireXmlEntry, setBinaryEntry, setXmlEntry, toOADate, unzipXlsx, xml, zipXlsx };