@devmm/puredocs-excel 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1016 @@
+declare class SharedStringManager {
+    #private;
+    /** Total number of unique strings. */
+    get count(): number;
+    /**
+     * Adds a string to the table (if not already present) and returns its index.
+     * O(1) average case.
+     */
+    addOrGet(value: string): number;
+    /**
+     * Returns the string at the given index.
+     * Throws if index is out of range.
+     */
+    getString(index: number): string;
+    /**
+     * Returns the string at index, or undefined if not found.
+     * Safe alternative to getString().
+     */
+    tryGetString(index: number): string | undefined;
+    /** Returns true if the string is already in the table. */
+    has(value: string): boolean;
+    /**
+     * Builds the xl/sharedStrings.xml string.
+     */
+    buildXml(): string;
+    /**
+     * Parses an existing xl/sharedStrings.xml and loads strings into the table.
+     */
+    loadFromXml(xml: string): void;
+}
+
+/**
+ * Represents a color for use in Excel styling (fonts, fills, borders).
+ * Supports hex, RGB, ARGB, theme, and indexed colors.
+ *
+ * Port of TVE.PureDocs.Excel.ExcelColor (C#)
+ *
+ * Key differences from C#:
+ *   - Constructor is private; use static factory methods
+ *   - Predefined colors use camelCase (ExcelColor.red vs ExcelColor.Red)
+ *   - toXmlAttrs() replaces ToOpenXmlColor() — returns plain object for XML serialisation
+ */
+interface ColorXmlAttrs {
+    rgb?: string;
+    theme?: number;
+    tint?: number;
+    indexed?: number;
+}
+declare class ExcelColor {
+    /** ARGB hex string e.g. "FFFF0000" for opaque red. */
+    readonly hex: string | undefined;
+    /** Theme color index. */
+    readonly theme: number | undefined;
+    /** Theme tint (-1.0 to 1.0). */
+    readonly tint: number | undefined;
+    /** Indexed color value. */
+    readonly indexed: number | undefined;
+    private constructor();
+    /**
+     * Creates a color from a hex string.
+     * Accepts "#RGB", "#RRGGBB", "RRGGBB", or "AARRGGBB" formats.
+     */
+    static fromHex(hex: string): ExcelColor;
+    /** Creates a color from RGB values (0–255). Alpha is set to 255 (opaque). */
+    static fromRgb(red: number, green: number, blue: number): ExcelColor;
+    /** Creates a color from ARGB values (0–255). */
+    static fromArgb(alpha: number, red: number, green: number, blue: number): ExcelColor;
+    /** Creates a theme color with optional tint value (-1.0 to 1.0). */
+    static fromTheme(themeIndex: number, tint?: number): ExcelColor;
+    /** Creates an indexed color. */
+    static fromIndexed(index: number): ExcelColor;
+    static readonly black: ExcelColor;
+    static readonly white: ExcelColor;
+    static readonly red: ExcelColor;
+    static readonly green: ExcelColor;
+    static readonly blue: ExcelColor;
+    static readonly yellow: ExcelColor;
+    static readonly magenta: ExcelColor;
+    static readonly cyan: ExcelColor;
+    static readonly orange: ExcelColor;
+    static readonly purple: ExcelColor;
+    static readonly darkRed: ExcelColor;
+    static readonly darkGreen: ExcelColor;
+    static readonly darkBlue: ExcelColor;
+    static readonly lightGray: ExcelColor;
+    static readonly darkGray: ExcelColor;
+    static readonly gray: ExcelColor;
+    static readonly lightBlue: ExcelColor;
+    static readonly lightGreen: ExcelColor;
+    static readonly lightYellow: ExcelColor;
+    static readonly lightPink: ExcelColor;
+    static readonly transparent: ExcelColor;
+    /** Returns XML attribute key-value pairs for embedding in OOXML elements. */
+    toXmlAttrs(): ColorXmlAttrs;
+    /** Builds an XML color element string for use inside other elements. */
+    toXmlElement(tagName: string): string;
+    /** Parses a color from OOXML XML attributes. Returns undefined if no color data. */
+    static fromXmlAttrs(attrs: Record<string, string | undefined>): ExcelColor | undefined;
+    toString(): string;
+}
+
+/**
+ * Font configuration for cell styling.
+ * Port of TVE.PureDocs.Excel.ExcelFont (C#)
+ */
+
+declare enum ExcelUnderline {
+    None = "none",
+    Single = "single",
+    Double = "double",
+    SingleAccounting = "singleAccounting",
+    DoubleAccounting = "doubleAccounting"
+}
+declare enum ExcelVerticalAlignRun {
+    Baseline = "baseline",
+    Superscript = "superscript",
+    Subscript = "subscript"
+}
+interface ExcelFontOptions {
+    name?: string;
+    size?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: ExcelUnderline;
+    strikethrough?: boolean;
+    color?: ExcelColor;
+    verticalAlign?: ExcelVerticalAlignRun;
+}
+declare class ExcelFont {
+    name?: string;
+    size?: number;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: ExcelUnderline;
+    strikethrough?: boolean;
+    color?: ExcelColor;
+    verticalAlign?: ExcelVerticalAlignRun;
+    constructor(opts?: ExcelFontOptions);
+    toXml(): string;
+    /** Parses font from parsed XML child elements. */
+    static fromXmlChildren(children: Array<{
+        tagName: string;
+        attributes: Record<string, string>;
+        textContent: string;
+    }>): ExcelFont;
+    /** Builds a canonical cache key for deduplication in StyleManager. */
+    cacheKey(): string;
+    clone(): ExcelFont;
+}
+
+/**
+ * Cell fill (background) configuration.
+ * Port of TVE.PureDocs.Excel.ExcelFill (C#)
+ */
+
+declare enum ExcelPatternType {
+    None = "none",
+    Solid = "solid",
+    DarkGray = "darkGray",
+    MediumGray = "mediumGray",
+    LightGray = "lightGray",
+    Gray125 = "gray125",
+    Gray0625 = "gray0625",
+    DarkHorizontal = "darkHorizontal",
+    DarkVertical = "darkVertical",
+    DarkDown = "darkDown",
+    DarkUp = "darkUp",
+    DarkGrid = "darkGrid",
+    DarkTrellis = "darkTrellis",
+    LightHorizontal = "lightHorizontal",
+    LightVertical = "lightVertical",
+    LightDown = "lightDown",
+    LightUp = "lightUp",
+    LightGrid = "lightGrid",
+    LightTrellis = "lightTrellis"
+}
+declare class ExcelFill {
+    patternType: ExcelPatternType;
+    /** Foreground/pattern color — for solid fills this IS the background color. */
+    foregroundColor?: ExcelColor;
+    /** Background color for pattern fills. */
+    backgroundColor?: ExcelColor;
+    constructor(patternType?: ExcelPatternType, foregroundColor?: ExcelColor, backgroundColor?: ExcelColor);
+    /**
+     * Creates a solid fill with the given color.
+     * Excel requires the magic indexed(64) background color for solid fills.
+     */
+    static solid(color: ExcelColor): ExcelFill;
+    /** Creates a pattern fill. */
+    static pattern(pattern: ExcelPatternType, foreground: ExcelColor, background?: ExcelColor): ExcelFill;
+    /** No fill (default). */
+    static readonly none: ExcelFill;
+    toXml(): string;
+    static fromXmlChildren(children: Array<{
+        tagName: string;
+        attributes: Record<string, string>;
+        children: Array<{
+            tagName: string;
+            attributes: Record<string, string>;
+        }>;
+    }>): ExcelFill;
+    cacheKey(): string;
+}
+
+/**
+ * Border configuration for cells.
+ * Port of TVE.PureDocs.Excel.ExcelBorder and ExcelBorderEdge (C#)
+ */
+
+declare enum ExcelBorderStyle {
+    None = "none",
+    Thin = "thin",
+    Medium = "medium",
+    Thick = "thick",
+    Dashed = "dashed",
+    Dotted = "dotted",
+    Double = "double",
+    Hair = "hair",
+    MediumDashed = "mediumDashed",
+    DashDot = "dashDot",
+    MediumDashDot = "mediumDashDot",
+    DashDotDot = "dashDotDot",
+    MediumDashDotDot = "mediumDashDotDot",
+    SlantDashDot = "slantDashDot"
+}
+declare class ExcelBorderEdge {
+    style: ExcelBorderStyle;
+    color?: ExcelColor;
+    constructor(style?: ExcelBorderStyle, color?: ExcelColor);
+    toXml(tag: string): string;
+    static fromXmlElement(el: {
+        attributes: Record<string, string>;
+        children: Array<{
+            tagName: string;
+            attributes: Record<string, string>;
+        }>;
+    }): ExcelBorderEdge;
+    cacheKey(): string;
+}
+declare class ExcelBorder {
+    left: ExcelBorderEdge;
+    right: ExcelBorderEdge;
+    top: ExcelBorderEdge;
+    bottom: ExcelBorderEdge;
+    diagonal: ExcelBorderEdge;
+    diagonalDown: boolean;
+    diagonalUp: boolean;
+    constructor();
+    /** Sets all four sides to the same style and color. */
+    static box(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
+    static bottomOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
+    static topOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
+    static leftOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
+    static rightOnly(style: ExcelBorderStyle, color?: ExcelColor): ExcelBorder;
+    static readonly none: ExcelBorder;
+    toXml(): string;
+    static fromXmlChildren(children: Array<{
+        tagName: string;
+        attributes: Record<string, string>;
+        children: Array<{
+            tagName: string;
+            attributes: Record<string, string>;
+        }>;
+    }>, borderAttrs: Record<string, string>): ExcelBorder;
+    cacheKey(): string;
+}
+
+/**
+ * Text alignment configuration for cells.
+ * Port of TVE.PureDocs.Excel.ExcelAlignment (C#)
+ */
+declare enum ExcelHorizontalAlignment {
+    General = "general",
+    Left = "left",
+    Center = "center",
+    Right = "right",
+    Fill = "fill",
+    Justify = "justify",
+    CenterContinuous = "centerContinuous",
+    Distributed = "distributed"
+}
+declare enum ExcelVerticalAlignment {
+    Top = "top",
+    Center = "center",
+    Bottom = "bottom",
+    Justify = "justify",
+    Distributed = "distributed"
+}
+declare enum ExcelReadingOrder {
+    ContextDependent = 0,
+    LeftToRight = 1,
+    RightToLeft = 2
+}
+declare class ExcelAlignment {
+    horizontal?: ExcelHorizontalAlignment;
+    vertical?: ExcelVerticalAlignment;
+    wrapText?: boolean;
+    shrinkToFit?: boolean;
+    textRotation?: number;
+    indent?: number;
+    readingOrder?: ExcelReadingOrder;
+    toXml(): string;
+    static fromXmlAttrs(attrs: Record<string, string>): ExcelAlignment;
+    cacheKey(): string;
+}
+
+/**
+ * Number format for cell display.
+ * Port of TVE.PureDocs.Excel.ExcelNumberFormat (C#)
+ *
+ * Built-in format IDs (per OOXML spec §18.8.30):
+ *   0  = General
+ *   1  = 0
+ *   2  = 0.00
+ *   3  = #,##0
+ *   4  = #,##0.00
+ *   9  = 0%
+ *   10 = 0.00%
+ *   11 = 0.00E+00
+ *   14 = mm-dd-yy  (date)
+ *   …
+ *   49 = @  (text)
+ * Custom formats start at ID 164.
+ */
+declare class ExcelNumberFormat {
+    readonly formatCode: string;
+    readonly formatId: number;
+    private constructor();
+    /** Creates a number format from a custom format code string. */
+    static custom(formatCode: string): ExcelNumberFormat;
+    /** Creates from format ID and optional custom formats map. */
+    static fromFormatId(formatId: number, customFormats?: Map<number, string>): ExcelNumberFormat;
+    static readonly general: ExcelNumberFormat;
+    static readonly integer: ExcelNumberFormat;
+    static readonly decimal2: ExcelNumberFormat;
+    static readonly thousandsSeparator: ExcelNumberFormat;
+    static readonly thousandsDecimal2: ExcelNumberFormat;
+    static readonly percentage: ExcelNumberFormat;
+    static readonly percentageDecimal2: ExcelNumberFormat;
+    static readonly scientific: ExcelNumberFormat;
+    static readonly fraction: ExcelNumberFormat;
+    static readonly fractionTwoDigits: ExcelNumberFormat;
+    static readonly shortDate: ExcelNumberFormat;
+    static readonly longDate: ExcelNumberFormat;
+    static readonly dayMonth: ExcelNumberFormat;
+    static readonly monthYear: ExcelNumberFormat;
+    static readonly time12h: ExcelNumberFormat;
+    static readonly time12hSeconds: ExcelNumberFormat;
+    static readonly time24h: ExcelNumberFormat;
+    static readonly time24hSeconds: ExcelNumberFormat;
+    static readonly dateTime: ExcelNumberFormat;
+    static readonly accounting: ExcelNumberFormat;
+    static readonly accountingRed: ExcelNumberFormat;
+    static readonly accountingDecimal2: ExcelNumberFormat;
+    static readonly text: ExcelNumberFormat;
+    static readonly currency: ExcelNumberFormat;
+    static readonly currencyNoDecimal: ExcelNumberFormat;
+    static readonly isoDate: ExcelNumberFormat;
+    static readonly isoDateTime: ExcelNumberFormat;
+    static readonly phoneNumber: ExcelNumberFormat;
+    static readonly zipCode: ExcelNumberFormat;
+    /** Returns true if this format code represents a date/time value. */
+    isDateFormat(): boolean;
+    toString(): string;
+}
+
+/**
+ * Complete cell style configuration with fluent builder API.
+ * Port of TVE.PureDocs.Excel.CellStyle (C#)
+ *
+ * Key difference from C#: method names are camelCase (setBold vs SetBold).
+ */
+
+declare class CellStyle {
+    #private;
+    font?: ExcelFont;
+    fill?: ExcelFill;
+    border?: ExcelBorder;
+    alignment?: ExcelAlignment;
+    numberFormat?: ExcelNumberFormat;
+    isLocked?: boolean;
+    isHidden?: boolean;
+    setFontName(name: string): this;
+    setFontSize(size: number): this;
+    setBold(bold?: boolean): this;
+    setItalic(italic?: boolean): this;
+    setUnderline(underline?: ExcelUnderline): this;
+    setStrikethrough(strikethrough?: boolean): this;
+    setFontColor(color: ExcelColor): this;
+    setFontColor(hex: string): this;
+    setVerticalAlign(align: ExcelVerticalAlignRun): this;
+    setBackgroundColor(color: ExcelColor): this;
+    setBackgroundColor(hex: string): this;
+    setPatternFill(pattern: ExcelPatternType, foreground: ExcelColor, background?: ExcelColor): this;
+    setAllBorders(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setBorder(border: ExcelBorder): this;
+    setLeftBorder(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setRightBorder(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setTopBorder(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setBottomBorder(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setHorizontalAlignment(alignment: ExcelHorizontalAlignment): this;
+    setVerticalAlignment(alignment: ExcelVerticalAlignment): this;
+    setWrapText(wrap?: boolean): this;
+    setShrinkToFit(shrink?: boolean): this;
+    setTextRotation(degrees: number): this;
+    setIndent(indent: number): this;
+    setNumberFormat(format: ExcelNumberFormat): this;
+    setNumberFormat(formatCode: string): this;
+    setLocked(locked?: boolean): this;
+    setFormulaHidden(hidden?: boolean): this;
+    /** Creates a deep copy of this style. */
+    clone(): CellStyle;
+}
+
+/**
+ * Manages the workbook stylesheet — fonts, fills, borders, number formats, cell formats.
+ * Handles deduplication and index management.
+ *
+ * Port of TVE.PureDocs.Excel.StyleManager (C#)
+ *
+ * Key differences:
+ *   - Works with parsed XmlElement trees instead of OpenXml SDK objects
+ *   - Serialises directly to XML strings
+ *   - No lazy save — isDirty flag still used, caller must call buildStylesXml()
+ */
+
+declare class StyleManager {
+    #private;
+    private fonts;
+    private fills;
+    private borders;
+    private numFmts;
+    private cellXfs;
+    private fontCache;
+    private fillCache;
+    private borderCache;
+    private numFmtCache;
+    private cellXfCache;
+    private nextCustomNumFmtId;
+    isDirty: boolean;
+    constructor();
+    /**
+     * Returns the cellXf index for the given CellStyle.
+     * Creates new font/fill/border entries as needed (with deduplication).
+     */
+    getOrCreateCellFormatIndex(style: CellStyle): number;
+    /**
+     * Reconstructs a CellStyle from a cellXf index.
+     * Used by Cell.style getter.
+     */
+    getCellStyle(styleIndex: number): CellStyle;
+    /** Builds the complete xl/styles.xml string. */
+    buildStylesXml(): string;
+    /** Loads an existing styles.xml, rebuilding all caches. */
+    loadFromXml(stylesXml: string): void;
+}
+
+/**
+ * Represents a single cell in a worksheet.
+ * Port of TVE.PureDocs.Excel.Cell (C#)
+ *
+ * Key differences from C#:
+ *   - All method names are camelCase
+ *   - No OpenXml SDK dependency — works with plain XML strings
+ *   - DateTime uses JavaScript Date
+ */
+
+/** Possible raw types stored in a cell. */
+type CellValue = string | number | boolean | Date | null;
+/** Internal cell data representation (mirrors what OOXML stores). */
+interface CellData {
+    reference: string;
+    /** 's' = sharedString, 'n' = number, 'b' = boolean, 'str' = inlineStr */
+    dataType?: 's' | 'n' | 'b' | 'str';
+    rawValue?: string;
+    formula?: string;
+    styleIndex: number;
+}
+declare class Cell {
+    #private;
+    /** @internal */
+    constructor(data: CellData, sharedStrings: SharedStringManager, styles: StyleManager);
+    /** Cell reference string e.g. "A1". */
+    get reference(): string;
+    /** 1-based row index. */
+    get row(): number;
+    /** 1-based column index. */
+    get column(): number;
+    /** Sets a string value. */
+    setValue(value: string): this;
+    /** Sets a numeric value. */
+    setValue(value: number): this;
+    /** Sets a boolean value. */
+    setValue(value: boolean): this;
+    /** Sets a Date value (stored as OADate number). */
+    setValue(value: Date): this;
+    /** Clears the cell value (sets to null). */
+    setValue(value: null): this;
+    /**
+     * Gets the typed cell value.
+     * Returns string | number | boolean | Date | null.
+     * Date detection is based on the cell's number format.
+     */
+    getValue(): CellValue;
+    /**
+     * Returns the display text of the cell value (always a string).
+     */
+    getText(): string;
+    /**
+     * Sets a formula. The leading '=' is optional.
+     * Clears any cached value.
+     */
+    setFormula(formula: string): this;
+    /** Returns the formula text (without leading '='), or null if no formula. */
+    getFormula(): string | null;
+    /** True if this cell contains a formula. */
+    get hasFormula(): boolean;
+    /** Gets the current CellStyle. Returns a new CellStyle if no style is set. */
+    get style(): CellStyle;
+    /** Replaces the entire cell style. */
+    set style(value: CellStyle);
+    /**
+     * Applies style changes via a callback on the current style.
+     * Returns this for chaining.
+     *
+     * @example
+     * cell.applyStyle(s => s.setBold(true).setFontColor(ExcelColor.red))
+     */
+    applyStyle(action: (style: CellStyle) => void): this;
+    setBold(bold?: boolean): this;
+    setItalic(italic?: boolean): this;
+    setFontSize(size: number): this;
+    setFontColor(color: ExcelColor | string): this;
+    setFontName(name: string): this;
+    setBackgroundColor(color: ExcelColor | string): this;
+    setWrapText(wrap?: boolean): this;
+    setHorizontalAlignment(a: ExcelHorizontalAlignment): this;
+    setVerticalAlignment(a: ExcelVerticalAlignment): this;
+    setAllBorders(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setNumberFormat(format: ExcelNumberFormat): this;
+    setNumberFormat(formatCode: string): this;
+    /** Clears the cell value and formula, preserving style. */
+    clear(): void;
+    /** Clears the cell value, formula, AND style. */
+    clearAll(): void;
+    /** @internal Builds the <c> XML element string for this cell. */
+    toXml(): string;
+    /** @internal Parses a <c> XML element into CellData. */
+    static fromXmlElement(el: {
+        attributes: Record<string, string>;
+        children: Array<{
+            tagName: string;
+            textContent: string;
+        }>;
+    }, ref: string): CellData;
+}
+
+/** A part that a drawing anchor references (e.g. `xl/charts/chart1.xml`). */
+interface DrawingDependentPart {
+    /** Package-relative path, no leading slash — e.g. `xl/charts/chart1.xml`. */
+    readonly path: string;
+    /** Full XML content of the part. */
+    readonly content: string;
+    /** Content type for the `[Content_Types].xml` Override entry. */
+    readonly contentType: string;
+    /** Relationship type used by the drawing → part relationship. */
+    readonly relType: string;
+}
+/**
+ * Contributes one anchored object (chart, image, …) to a worksheet's drawing.
+ * Implemented by satellite packages; consumed by the core save pipeline.
+ */
+interface DrawingProvider {
+    /**
+     * Builds the `<xdr:*Anchor>` fragment placed inside `<xdr:wsDr>`.
+     * @param relationshipId the id (e.g. `"rId1"`) the anchor must reference for
+     *   its embedded dependent part.
+     */
+    buildAnchorXml(relationshipId: string): string;
+    /**
+     * Builds the dependent part this drawing references.
+     * @param partIndex a workbook-unique 1-based index for building a unique path
+     *   (e.g. `xl/charts/chart{partIndex}.xml`).
+     */
+    buildPart(partIndex: number): DrawingDependentPart;
+}
+/** Relationship id used by a worksheet to reference its single drawing part. */
+declare const WORKSHEET_DRAWING_REL_ID = "rId1";
+/** Wraps anchor fragments into a complete `xl/drawings/drawingN.xml` part. */
+declare function buildDrawingXml(anchorsXml: string): string;
+/** Builds a generic `.rels` part from a list of `<Relationship .../>` strings. */
+declare function buildRelsXml(relationships: readonly string[]): string;
+
+/**
+ * Represents a rectangular range of cells for bulk operations.
+ * Port of TVE.PureDocs.Excel.Range (C#)
+ */
+
+declare class Range {
+    #private;
+    constructor(sheet: Worksheet, rangeReference: string);
+    /** The range address e.g. "A1:B10". */
+    get address(): string;
+    /** Number of rows in the range. */
+    get rowCount(): number;
+    /** Number of columns in the range. */
+    get columnCount(): number;
+    /**
+     * Sets values from a 2D array.
+     * Values that exceed the range boundary are silently ignored.
+     */
+    setValues(values: CellValue[][]): void;
+    /**
+     * Gets all cell values as a 2D array (row-major order).
+     */
+    getValues(): CellValue[][];
+    /** Clears all cells in the range (values only, preserves style). */
+    clear(): void;
+    /** Auto-fits all columns in the range. */
+    autoFit(): void;
+    /** Applies a CellStyle to all cells in the range. Returns this for chaining. */
+    setStyle(style: CellStyle): this;
+    /**
+     * Applies style changes to all cells in the range.
+     * @example range.applyStyle(s => s.setBold(true).setBackgroundColor(ExcelColor.lightGray))
+     */
+    applyStyle(action: (style: CellStyle) => void): this;
+    setBold(bold?: boolean): this;
+    setFontSize(size: number): this;
+    setFontColor(color: ExcelColor | string): this;
+    setFontName(name: string): this;
+    setBackgroundColor(color: ExcelColor | string): this;
+    setAllBorders(style: ExcelBorderStyle, color?: ExcelColor): this;
+    setHorizontalAlignment(alignment: ExcelHorizontalAlignment): this;
+    setVerticalAlignment(alignment: ExcelVerticalAlignment): this;
+    setWrapText(wrap?: boolean): this;
+    setNumberFormat(format: ExcelNumberFormat): this;
+    setNumberFormat(formatCode: string): this;
+}
+
+/**
+ * Represents a worksheet in an Excel workbook.
+ * Port of TVE.PureDocs.Excel.Worksheet (C#)
+ *
+ * Key differences from C#:
+ *   - All public methods camelCase
+ *   - XML parsed/serialised directly — no OpenXml SDK
+ *   - No CalcChain yet (added later via @devmm/puredocs-excel-formula)
+ */
+
+type SheetVisibility = 'visible' | 'hidden' | 'veryHidden';
+declare class Worksheet {
+    #private;
+    /** @internal */
+    constructor(name: string, sharedStrings: SharedStringManager, styles: StyleManager);
+    get name(): string;
+    set name(value: string);
+    /**
+     * Gets (or creates) a cell by reference string (e.g. "A1") or 1-based row/col.
+     * Creates the row/cell if it doesn't exist.
+     */
+    getCell(reference: string): Cell;
+    getCell(row: number, column: number): Cell;
+    /**
+     * Returns a Cell if it exists, or null if the row/cell has not been created.
+     * Does NOT create a new cell (read-only access).
+     */
+    tryGetCell(reference: string): Cell | null;
+    tryGetCell(row: number, column: number): Cell | null;
+    /** Shorthand indexer — sheet.cell("A1") or sheet.cell(1, 1). */
+    cell(reference: string): Cell;
+    cell(row: number, column: number): Cell;
+    /** Gets a Range object for bulk operations. */
+    getRange(rangeReference: string): Range;
+    /** Gets the raw value of a cell (for formula evaluation). */
+    getCellValue(reference: string): unknown;
+    /**
+     * 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
+     * sheet into a dense 2D array.
+     */
+    get usedBounds(): {
+        rowCount: number;
+        columnCount: number;
+    };
+    /** Sets the width of a column (1-based index). */
+    setColumnWidth(columnIndex: number, width: number): void;
+    /** Auto-fits column width based on content (approximate). */
+    autoFitColumn(columnIndex: number): void;
+    /** Sets the height of a row (1-based index). */
+    setRowHeight(rowIndex: number, height: number): void;
+    /** Merges cells in the given range (e.g. "A1:B2"). */
+    mergeCells(rangeReference: string): void;
+    /** Removes a merge for the given range reference. */
+    unmergeCells(rangeReference: string): void;
+    /**
+     * Freezes rows and/or columns.
+     * @param row    Number of rows to freeze (0 = none)
+     * @param column Number of columns to freeze (0 = none)
+     */
+    freezePanes(row: number, column: number): void;
+    /** Sets auto-filter on the given range. */
+    setAutoFilter(rangeReference: string): void;
+    /**
+     * Adds a dropdown data validation to a cell range.
+     * @param cellRange   Range to apply (e.g. "F2:F1000")
+     * @param listFormula Formula for the dropdown list (e.g. "'Sheet2'!$A$1:$A$10")
+     */
+    addDropdownValidation(cellRange: string, listFormula: string): void;
+    /** Sets the visibility state of this worksheet. */
+    setVisibility(state: SheetVisibility): void;
+    get visibility(): SheetVisibility;
+    /**
+     * Attaches a drawing provider (e.g. a chart) to this worksheet.
+     * Satellite packages such as `@devmm/puredocs-excel-charts` call this; the core
+     * save pipeline turns registered providers into valid OOXML drawing/chart parts.
+     */
+    addDrawingProvider(provider: DrawingProvider): void;
+    /** True when this worksheet has at least one drawing to serialise. */
+    get hasDrawings(): boolean;
+    /** @internal — drawing providers, consumed by the save pipeline. */
+    get drawingProviders(): readonly DrawingProvider[];
+    /** Builds the xl/worksheets/sheetN.xml string. */
+    buildXml(): string;
+    /** Parses xl/worksheets/sheetN.xml and loads cells into memory. */
+    loadFromXml(xml: string): void;
+}
+
+declare class Workbook {
+    #private;
+    private constructor();
+    /**
+     * Creates a new empty workbook.
+     * Mirrors Workbook.Create() in C#.
+     */
+    static create(): Workbook;
+    /**
+     * Opens an existing workbook from a binary buffer (ArrayBuffer or Uint8Array).
+     * Works in both browser and Node.js.
+     * Mirrors Workbook.Open(stream) in C#.
+     */
+    static fromBuffer(buffer: ArrayBuffer | Uint8Array): Workbook;
+    /**
+     * Opens an existing workbook from a file path (Node.js only).
+     * Mirrors Workbook.Open(filePath) in C#.
+     */
+    static fromFile(filePath: string): Promise<Workbook>;
+    /**
+     * Collection of worksheets (read-only array view).
+     * Access by index: workbook.worksheets[0]
+     * Access by name: workbook.worksheets.find(s => s.name === 'Sheet1')
+     */
+    get worksheets(): readonly Worksheet[];
+    /**
+     * Adds a new worksheet with the given name and returns it.
+     * Mirrors workbook.AddWorksheet(name) in C#.
+     */
+    addWorksheet(name: string): Worksheet;
+    /**
+     * Returns a worksheet by name. Throws if not found.
+     */
+    getWorksheet(name: string): Worksheet;
+    /**
+     * Serialises the workbook to a Uint8Array (xlsx binary).
+     * Mirrors workbook.SaveAs(stream) in C#.
+     * Works in browser and Node.js.
+     */
+    saveAsBuffer(): Uint8Array;
+    /**
+     * Saves the workbook to a file (Node.js only).
+     * Mirrors workbook.SaveAs(filePath) in C#.
+     */
+    saveToFile(filePath: string): Promise<void>;
+    /** Releases resources. The workbook should not be used after this call. */
+    close(): void;
+    /** Symbol.dispose support for `using` keyword (TypeScript 5.2+). */
+    [Symbol.dispose](): void;
+}
+
+/**
+ * Utility for converting between cell references (e.g. "A1") and
+ * 1-based row/column indices.
+ *
+ * Port of TVE.PureDocs.Excel.CellReference (C#)
+ */
+interface ParsedCellRef {
+    readonly row: number;
+    readonly column: number;
+}
+/**
+ * Parses a cell reference string into 1-based row and column indices.
+ *
+ * @example
+ * parseCellRef("A1")   // { row: 1, column: 1 }
+ * parseCellRef("B10")  // { row: 10, column: 2 }
+ * parseCellRef("AA1")  // { row: 1, column: 27 }
+ * parseCellRef("$B$2") // { row: 2, column: 2 } — $ stripped
+ */
+declare function parseCellRef(cellReference: string): ParsedCellRef;
+/**
+ * Converts 1-based row and column indices to a cell reference string.
+ *
+ * @example
+ * cellRefFromRowCol(1, 1)  // "A1"
+ * cellRefFromRowCol(10, 2) // "B10"
+ * cellRefFromRowCol(1, 27) // "AA1"
+ */
+declare function cellRefFromRowCol(row: number, column: number): string;
+/**
+ * Converts a 1-based column index to its letter representation.
+ *
+ * @example
+ * columnLetter(1)  // "A"
+ * columnLetter(26) // "Z"
+ * columnLetter(27) // "AA"
+ */
+declare function columnLetter(column: number): string;
+/**
+ * Converts a column letter string to a 1-based column number.
+ *
+ * @example
+ * columnNumber("A")  // 1
+ * columnNumber("Z")  // 26
+ * columnNumber("AA") // 27
+ */
+declare function columnNumber(letters: string): number;
+/**
+ * Parses a range reference string like "A1:B10" into start/end coordinates.
+ */
+declare function parseRangeRef(rangeReference: string): {
+    startRow: number;
+    startColumn: number;
+    endRow: number;
+    endColumn: number;
+};
+
+/**
+ * OLE Automation Date (OADate) helpers.
+ *
+ * Excel stores dates as floating-point numbers where:
+ *   - The integer part = number of days since Dec 30, 1899 (OADate epoch)
+ *   - The fractional part = time of day (0.5 = noon)
+ *
+ * Note: Excel has a known bug treating 1900 as a leap year (day 60 = Feb 29 1900),
+ * which never existed. This implementation matches Excel's behaviour exactly.
+ */
+/**
+ * Converts a JavaScript Date to an Excel OADate serial number.
+ *
+ * @example
+ * toOADate(new Date(1900, 0, 1))  // 1
+ * toOADate(new Date(2025, 0, 1))  // 45658
+ */
+declare function toOADate(date: Date): number;
+/**
+ * Converts an Excel OADate serial number to a JavaScript Date.
+ *
+ * @example
+ * fromOADate(1)     // Jan 1, 1900
+ * fromOADate(45658) // Jan 1, 2025
+ */
+declare function fromOADate(oaDate: number): Date;
+/**
+ * Returns true if the given number format ID represents a date/time value.
+ */
+declare function isDateFormatId(formatId: number): boolean;
+/**
+ * Returns true if the format code string contains date/time patterns.
+ */
+declare function isDateFormatCode(formatCode: string): boolean;
+
+/**
+ * Cross-platform XML parser.
+ *
+ * Uses the browser DOMParser when available; otherwise (Node.js, Deno, Bun without a
+ * DOM global) it uses a built-in char-scanning parser. The built-in parser handles the
+ * subset of XML that OOXML produces: nested/self-closing elements, attributes, text,
+ * CDATA sections, processing instructions and comments, plus standard entity decoding.
+ * It is deliberately not a general-purpose XML parser.
+ */
+type XmlElement = {
+    readonly tagName: string;
+    readonly attributes: Readonly<Record<string, string>>;
+    readonly children: XmlElement[];
+    readonly textContent: string;
+};
+/**
+ * Parses an XML string into a simple XmlElement tree.
+ */
+declare function parseXml(xmlString: string): XmlElement;
+/**
+ * Decodes a Uint8Array to a UTF-8 string.
+ */
+declare function decodeUtf8(bytes: Uint8Array): string;
+/**
+ * Encodes a string to UTF-8 bytes.
+ */
+declare function encodeUtf8(str: string): Uint8Array;
+/**
+ * Queries all descendant elements matching a local tag name.
+ * Handles namespace-prefixed tags (e.g. "a:t" matches tagName ending in ":t" or equal to "t").
+ */
+declare function getElementsByTagName(root: XmlElement, localName: string): XmlElement[];
+/**
+ * Gets a named attribute value, handling namespace prefixes.
+ * Tries exact match first, then suffix match (e.g. "r:id" → looks for "r:id" or "id").
+ */
+declare function getAttr(el: XmlElement, name: string): string | undefined;
+
+/**
+ * Lightweight XML builder for OOXML document parts.
+ * Produces well-formed XML strings without external dependencies.
+ */
+/** Escapes special XML characters in an attribute value or text content. */
+declare function escapeXml(value: string): string;
+type XmlAttrs = Record<string, string | number | boolean | undefined>;
+declare class XmlBuilder {
+    private readonly parts;
+    /** Appends the XML declaration header. */
+    xmlDeclaration(): this;
+    /** Opens a tag with optional attributes. */
+    open(tag: string, attrs?: XmlAttrs): this;
+    /** Closes a tag. */
+    close(tag: string): this;
+    /** Writes a self-closing tag. */
+    self(tag: string, attrs?: XmlAttrs): this;
+    /** Writes a tag with text content. */
+    text(tag: string, content: string, attrs?: XmlAttrs): this;
+    /** Writes raw (pre-escaped) XML — use with caution. */
+    raw(xml: string): this;
+    /** Returns the complete XML string. */
+    toString(): string;
+    /** Returns UTF-8 encoded bytes. */
+    toBytes(): Uint8Array;
+}
+/** Convenience factory. */
+declare function xml(): XmlBuilder;
+declare const NS: {
+    readonly spreadsheetml: "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+    readonly relationships: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    readonly relationshipsPackage: "http://schemas.openxmlformats.org/package/2006/relationships";
+    readonly drawingml: "http://schemas.openxmlformats.org/drawingml/2006/main";
+    readonly spreadsheetDrawing: "http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing";
+    readonly contentTypes: "http://schemas.openxmlformats.org/package/2006/content-types";
+    readonly coreProperties: "http://schemas.openxmlformats.org/package/2006/metadata/core-properties";
+};
+declare const REL_TYPES: {
+    readonly officeDocument: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+    readonly worksheet: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
+    readonly sharedStrings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings";
+    readonly styles: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+    readonly chart: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
+    readonly drawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
+    readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+};
+declare const CONTENT_TYPES: {
+    readonly workbook: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
+    readonly worksheet: "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml";
+    readonly sharedStrings: "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml";
+    readonly styles: "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml";
+    readonly drawing: "application/vnd.openxmlformats-officedocument.drawing+xml";
+    readonly chart: "application/vnd.openxmlformats-officedocument.drawingml.chart+xml";
+    readonly relationships: "application/vnd.openxmlformats-package.relationships+xml";
+    readonly coreProperties: "application/vnd.openxmlformats-package.core-properties+xml";
+};
+
+/**
+ * Represents the contents of an unzipped xlsx file.
+ * Keys are file paths within the archive (e.g. "xl/workbook.xml").
+ * Values are raw UTF-8 bytes.
+ */
+type ZipEntries = Map<string, Uint8Array>;
+/**
+ * Unzips an xlsx file buffer into a map of path → bytes.
+ *
+ * @param buffer - ArrayBuffer or Uint8Array of the xlsx file
+ * @returns Map of file paths to their raw bytes
+ */
+declare function unzipXlsx(buffer: ArrayBuffer | Uint8Array): ZipEntries;
+/**
+ * Reads and decodes a UTF-8 text entry from a zip archive.
+ * Returns undefined if the entry does not exist.
+ */
+declare function readXmlEntry(entries: ZipEntries, path: string): string | undefined;
+/**
+ * Reads and decodes a UTF-8 text entry, throwing if missing.
+ */
+declare function requireXmlEntry(entries: ZipEntries, path: string): string;
+/**
+ * Returns all entry paths that match the given prefix.
+ * Useful for listing worksheets: prefix = "xl/worksheets/".
+ */
+declare function listEntries(entries: ZipEntries, prefix: string): string[];
+
+/**
+ * Represents the file entries to be zipped.
+ * Keys are paths within the archive, values are either bytes or a UTF-8 string.
+ */
+type ZipInput = Map<string, Uint8Array | string>;
+/**
+ * Zips a collection of file entries into an xlsx-compatible buffer.
+ *
+ * @param entries - Map of path → content (string auto-encoded to UTF-8)
+ * @returns Uint8Array of the resulting ZIP file
+ */
+declare function zipXlsx(entries: ZipInput): Uint8Array;
+/**
+ * Helper to add or update a UTF-8 text entry.
+ */
+declare function setXmlEntry(entries: ZipInput, path: string, xml: string): void;
+/**
+ * Helper to add or update a binary entry.
+ */
+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 };