@niicojs/excel 0.1.0

package/dist/index.js

@@ -0,0 +1,2881 @@
+import { readFile, writeFile } from 'fs/promises';
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+import { unzip, strFromU8, zip, strToU8 } from 'fflate';
+
+/**
+ * Converts a column index (0-based) to Excel column letters (A, B, ..., Z, AA, AB, ...)
+ * @param col - 0-based column index
+ * @returns Column letter(s)
+ */ const colToLetter = (col)=>{
+    let result = '';
+    let n = col;
+    while(n >= 0){
+        result = String.fromCharCode(n % 26 + 65) + result;
+        n = Math.floor(n / 26) - 1;
+    }
+    return result;
+};
+/**
+ * Converts Excel column letters to a 0-based column index
+ * @param letters - Column letter(s) like 'A', 'B', 'AA'
+ * @returns 0-based column index
+ */ const letterToCol = (letters)=>{
+    const upper = letters.toUpperCase();
+    let col = 0;
+    for(let i = 0; i < upper.length; i++){
+        col = col * 26 + (upper.charCodeAt(i) - 64);
+    }
+    return col - 1;
+};
+/**
+ * Parses an Excel cell address (e.g., 'A1', '$B$2') to row/col indices
+ * @param address - Cell address string
+ * @returns CellAddress with 0-based row and col
+ */ const parseAddress = (address)=>{
+    // Remove $ signs for absolute references
+    const clean = address.replace(/\$/g, '');
+    const match = clean.match(/^([A-Z]+)(\d+)$/i);
+    if (!match) {
+        throw new Error(`Invalid cell address: ${address}`);
+    }
+    const col = letterToCol(match[1].toUpperCase());
+    const row = parseInt(match[2], 10) - 1; // Convert to 0-based
+    return {
+        row,
+        col
+    };
+};
+/**
+ * Converts row/col indices to an Excel cell address
+ * @param row - 0-based row index
+ * @param col - 0-based column index
+ * @returns Cell address string like 'A1'
+ */ const toAddress = (row, col)=>{
+    return `${colToLetter(col)}${row + 1}`;
+};
+/**
+ * Parses an Excel range (e.g., 'A1:B10') to start/end addresses
+ * @param range - Range string
+ * @returns RangeAddress with start and end
+ */ const parseRange = (range)=>{
+    const parts = range.split(':');
+    if (parts.length === 1) {
+        // Single cell range
+        const addr = parseAddress(parts[0]);
+        return {
+            start: addr,
+            end: addr
+        };
+    }
+    if (parts.length !== 2) {
+        throw new Error(`Invalid range: ${range}`);
+    }
+    return {
+        start: parseAddress(parts[0]),
+        end: parseAddress(parts[1])
+    };
+};
+/**
+ * Converts a RangeAddress to a range string
+ * @param range - RangeAddress object
+ * @returns Range string like 'A1:B10'
+ */ const toRange = (range)=>{
+    const start = toAddress(range.start.row, range.start.col);
+    const end = toAddress(range.end.row, range.end.col);
+    if (start === end) {
+        return start;
+    }
+    return `${start}:${end}`;
+};
+/**
+ * Normalizes a range so start is always top-left and end is bottom-right
+ */ const normalizeRange = (range)=>{
+    return {
+        start: {
+            row: Math.min(range.start.row, range.end.row),
+            col: Math.min(range.start.col, range.end.col)
+        },
+        end: {
+            row: Math.max(range.start.row, range.end.row),
+            col: Math.max(range.start.col, range.end.col)
+        }
+    };
+};
+
+// Excel epoch: December 30, 1899 (accounting for the 1900 leap year bug)
+const EXCEL_EPOCH = new Date(Date.UTC(1899, 11, 30));
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+// Excel error types
+const ERROR_TYPES = new Set([
+    '#NULL!',
+    '#DIV/0!',
+    '#VALUE!',
+    '#REF!',
+    '#NAME?',
+    '#NUM!',
+    '#N/A',
+    '#GETTING_DATA'
+]);
+/**
+ * Represents a single cell in a worksheet
+ */ class Cell {
+    constructor(worksheet, row, col, data){
+        this._dirty = false;
+        this._worksheet = worksheet;
+        this._row = row;
+        this._col = col;
+        this._data = data || {};
+    }
+    /**
+   * Get the cell address (e.g., 'A1')
+   */ get address() {
+        return toAddress(this._row, this._col);
+    }
+    /**
+   * Get the 0-based row index
+   */ get row() {
+        return this._row;
+    }
+    /**
+   * Get the 0-based column index
+   */ get col() {
+        return this._col;
+    }
+    /**
+   * Get the cell type
+   */ get type() {
+        const t = this._data.t;
+        if (!t && this._data.v === undefined && !this._data.f) {
+            return 'empty';
+        }
+        switch(t){
+            case 'n':
+                return 'number';
+            case 's':
+            case 'str':
+                return 'string';
+            case 'b':
+                return 'boolean';
+            case 'e':
+                return 'error';
+            case 'd':
+                return 'date';
+            default:
+                // If no type but has value, infer from value
+                if (typeof this._data.v === 'number') return 'number';
+                if (typeof this._data.v === 'string') return 'string';
+                if (typeof this._data.v === 'boolean') return 'boolean';
+                return 'empty';
+        }
+    }
+    /**
+   * Get the cell value
+   */ get value() {
+        const t = this._data.t;
+        const v = this._data.v;
+        if (v === undefined && !this._data.f) {
+            return null;
+        }
+        switch(t){
+            case 'n':
+                return typeof v === 'number' ? v : parseFloat(String(v));
+            case 's':
+                // Shared string reference
+                if (typeof v === 'number') {
+                    return this._worksheet.workbook.sharedStrings.getString(v) ?? '';
+                }
+                return String(v);
+            case 'str':
+                // Inline string
+                return String(v);
+            case 'b':
+                return v === 1 || v === '1' || v === true;
+            case 'e':
+                return {
+                    error: String(v)
+                };
+            case 'd':
+                // ISO 8601 date string
+                return new Date(String(v));
+            default:
+                // No type specified - try to infer
+                if (typeof v === 'number') {
+                    // Check if this might be a date based on number format
+                    if (this._isDateFormat()) {
+                        return this._excelDateToJs(v);
+                    }
+                    return v;
+                }
+                if (typeof v === 'string') {
+                    if (ERROR_TYPES.has(v)) {
+                        return {
+                            error: v
+                        };
+                    }
+                    return v;
+                }
+                if (typeof v === 'boolean') return v;
+                return null;
+        }
+    }
+    /**
+   * Set the cell value
+   */ set value(val) {
+        this._dirty = true;
+        if (val === null || val === undefined) {
+            this._data.v = undefined;
+            this._data.t = undefined;
+            this._data.f = undefined;
+            return;
+        }
+        if (typeof val === 'number') {
+            this._data.v = val;
+            this._data.t = 'n';
+        } else if (typeof val === 'string') {
+            // Store as shared string
+            const index = this._worksheet.workbook.sharedStrings.addString(val);
+            this._data.v = index;
+            this._data.t = 's';
+        } else if (typeof val === 'boolean') {
+            this._data.v = val ? 1 : 0;
+            this._data.t = 'b';
+        } else if (val instanceof Date) {
+            // Store as ISO date string with 'd' type
+            this._data.v = val.toISOString();
+            this._data.t = 'd';
+        } else if ('error' in val) {
+            this._data.v = val.error;
+            this._data.t = 'e';
+        }
+        // Clear formula when setting value directly
+        this._data.f = undefined;
+    }
+    /**
+   * Write a 2D array of values starting at this cell
+   */ set values(data) {
+        for(let r = 0; r < data.length; r++){
+            const row = data[r];
+            for(let c = 0; c < row.length; c++){
+                const cell = this._worksheet.cell(this._row + r, this._col + c);
+                cell.value = row[c];
+            }
+        }
+    }
+    /**
+   * Get the formula (without leading '=')
+   */ get formula() {
+        return this._data.f;
+    }
+    /**
+   * Set the formula (without leading '=')
+   */ set formula(f) {
+        this._dirty = true;
+        if (f === undefined) {
+            this._data.f = undefined;
+        } else {
+            // Remove leading '=' if present
+            this._data.f = f.startsWith('=') ? f.slice(1) : f;
+        }
+    }
+    /**
+   * Get the formatted text (as displayed in Excel)
+   */ get text() {
+        if (this._data.w) {
+            return this._data.w;
+        }
+        const val = this.value;
+        if (val === null) return '';
+        if (typeof val === 'object' && 'error' in val) return val.error;
+        if (val instanceof Date) return val.toISOString().split('T')[0];
+        return String(val);
+    }
+    /**
+   * Get the style index
+   */ get styleIndex() {
+        return this._data.s;
+    }
+    /**
+   * Set the style index
+   */ set styleIndex(index) {
+        this._dirty = true;
+        this._data.s = index;
+    }
+    /**
+   * Get the cell style
+   */ get style() {
+        if (this._data.s === undefined) {
+            return {};
+        }
+        return this._worksheet.workbook.styles.getStyle(this._data.s);
+    }
+    /**
+   * Set the cell style (merges with existing)
+   */ set style(style) {
+        this._dirty = true;
+        const currentStyle = this.style;
+        const merged = {
+            ...currentStyle,
+            ...style
+        };
+        this._data.s = this._worksheet.workbook.styles.createStyle(merged);
+    }
+    /**
+   * Check if cell has been modified
+   */ get dirty() {
+        return this._dirty;
+    }
+    /**
+   * Get internal cell data
+   */ get data() {
+        return this._data;
+    }
+    /**
+   * Check if this cell has a date number format
+   */ _isDateFormat() {
+        // TODO: Check actual number format from styles
+        // For now, return false - dates should be explicitly typed
+        return false;
+    }
+    /**
+   * Convert Excel serial date to JavaScript Date
+   * Used when reading dates stored as numbers with date formats
+   */ _excelDateToJs(serial) {
+        // Excel incorrectly considers 1900 a leap year
+        // Dates after Feb 28, 1900 need adjustment
+        const adjusted = serial > 60 ? serial - 1 : serial;
+        const ms = Math.round((adjusted - 1) * MS_PER_DAY);
+        return new Date(EXCEL_EPOCH.getTime() + ms);
+    }
+    /**
+   * Convert JavaScript Date to Excel serial date
+   * Used when writing dates as numbers for Excel compatibility
+   */ _jsDateToExcel(date) {
+        const ms = date.getTime() - EXCEL_EPOCH.getTime();
+        let serial = ms / MS_PER_DAY + 1;
+        // Account for Excel's 1900 leap year bug
+        if (serial > 60) {
+            serial += 1;
+        }
+        return serial;
+    }
+}
+/**
+ * Parse a cell address or row/col to get row and col indices
+ */ const parseCellRef = (rowOrAddress, col)=>{
+    if (typeof rowOrAddress === 'string') {
+        return parseAddress(rowOrAddress);
+    }
+    if (col === undefined) {
+        throw new Error('Column must be provided when row is a number');
+    }
+    return {
+        row: rowOrAddress,
+        col
+    };
+};
+
+var _computedKey;
+_computedKey = Symbol.iterator;
+/**
+ * Represents a range of cells in a worksheet
+ */ class Range {
+    constructor(worksheet, range){
+        this._worksheet = worksheet;
+        this._range = normalizeRange(range);
+    }
+    /**
+   * Get the range address as a string
+   */ get address() {
+        const start = toAddress(this._range.start.row, this._range.start.col);
+        const end = toAddress(this._range.end.row, this._range.end.col);
+        if (start === end) return start;
+        return `${start}:${end}`;
+    }
+    /**
+   * Get the number of rows in the range
+   */ get rowCount() {
+        return this._range.end.row - this._range.start.row + 1;
+    }
+    /**
+   * Get the number of columns in the range
+   */ get colCount() {
+        return this._range.end.col - this._range.start.col + 1;
+    }
+    /**
+   * Get all values in the range as a 2D array
+   */ get values() {
+        const result = [];
+        for(let r = this._range.start.row; r <= this._range.end.row; r++){
+            const row = [];
+            for(let c = this._range.start.col; c <= this._range.end.col; c++){
+                const cell = this._worksheet.cell(r, c);
+                row.push(cell.value);
+            }
+            result.push(row);
+        }
+        return result;
+    }
+    /**
+   * Set values in the range from a 2D array
+   */ set values(data) {
+        for(let r = 0; r < data.length && r < this.rowCount; r++){
+            const row = data[r];
+            for(let c = 0; c < row.length && c < this.colCount; c++){
+                const cell = this._worksheet.cell(this._range.start.row + r, this._range.start.col + c);
+                cell.value = row[c];
+            }
+        }
+    }
+    /**
+   * Get all formulas in the range as a 2D array
+   */ get formulas() {
+        const result = [];
+        for(let r = this._range.start.row; r <= this._range.end.row; r++){
+            const row = [];
+            for(let c = this._range.start.col; c <= this._range.end.col; c++){
+                const cell = this._worksheet.cell(r, c);
+                row.push(cell.formula);
+            }
+            result.push(row);
+        }
+        return result;
+    }
+    /**
+   * Set formulas in the range from a 2D array
+   */ set formulas(data) {
+        for(let r = 0; r < data.length && r < this.rowCount; r++){
+            const row = data[r];
+            for(let c = 0; c < row.length && c < this.colCount; c++){
+                const cell = this._worksheet.cell(this._range.start.row + r, this._range.start.col + c);
+                cell.formula = row[c];
+            }
+        }
+    }
+    /**
+   * Get the style of the top-left cell
+   */ get style() {
+        return this._worksheet.cell(this._range.start.row, this._range.start.col).style;
+    }
+    /**
+   * Set style for all cells in the range
+   */ set style(style) {
+        for(let r = this._range.start.row; r <= this._range.end.row; r++){
+            for(let c = this._range.start.col; c <= this._range.end.col; c++){
+                const cell = this._worksheet.cell(r, c);
+                cell.style = style;
+            }
+        }
+    }
+    /**
+   * Iterate over all cells in the range
+   */ *[_computedKey]() {
+        for(let r = this._range.start.row; r <= this._range.end.row; r++){
+            for(let c = this._range.start.col; c <= this._range.end.col; c++){
+                yield this._worksheet.cell(r, c);
+            }
+        }
+    }
+    /**
+   * Iterate over cells row by row
+   */ *rows() {
+        for(let r = this._range.start.row; r <= this._range.end.row; r++){
+            const row = [];
+            for(let c = this._range.start.col; c <= this._range.end.col; c++){
+                row.push(this._worksheet.cell(r, c));
+            }
+            yield row;
+        }
+    }
+}
+
+// Parser options that preserve structure and attributes
+const parserOptions = {
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    textNodeName: '#text',
+    preserveOrder: true,
+    commentPropName: '#comment',
+    cdataPropName: '#cdata',
+    trimValues: false,
+    parseTagValue: false,
+    parseAttributeValue: false
+};
+// Builder options matching parser for round-trip compatibility
+const builderOptions = {
+    ignoreAttributes: false,
+    attributeNamePrefix: '@_',
+    textNodeName: '#text',
+    preserveOrder: true,
+    commentPropName: '#comment',
+    cdataPropName: '#cdata',
+    format: false,
+    suppressEmptyNode: false,
+    suppressBooleanAttributes: false
+};
+const parser = new XMLParser(parserOptions);
+const builder = new XMLBuilder(builderOptions);
+/**
+ * Parses an XML string into a JavaScript object
+ * Preserves element order and attributes for round-trip compatibility
+ */ const parseXml = (xml)=>{
+    return parser.parse(xml);
+};
+/**
+ * Converts a JavaScript object back to an XML string
+ */ const stringifyXml = (obj)=>{
+    return builder.build(obj);
+};
+/**
+ * Finds the first element with the given tag name in the XML tree
+ */ const findElement = (nodes, tagName)=>{
+    for (const node of nodes){
+        if (tagName in node) {
+            return node;
+        }
+    }
+    return undefined;
+};
+/**
+ * Gets the children of an element
+ */ const getChildren = (node, tagName)=>{
+    const children = node[tagName];
+    if (Array.isArray(children)) {
+        return children;
+    }
+    return [];
+};
+/**
+ * Gets an attribute value from a node
+ */ const getAttr = (node, name)=>{
+    const attrs = node[':@'];
+    return attrs?.[`@_${name}`];
+};
+/**
+ * Creates a new XML element
+ */ const createElement = (tagName, attrs, children)=>{
+    const node = {
+        [tagName]: children || []
+    };
+    if (attrs && Object.keys(attrs).length > 0) {
+        const attrObj = {};
+        for (const [key, value] of Object.entries(attrs)){
+            attrObj[`@_${key}`] = value;
+        }
+        node[':@'] = attrObj;
+    }
+    return node;
+};
+/**
+ * Creates a text node
+ */ const createText = (text)=>{
+    return {
+        '#text': text
+    };
+};
+
+/**
+ * Represents a worksheet in a workbook
+ */ class Worksheet {
+    constructor(workbook, name){
+        this._cells = new Map();
+        this._xmlNodes = null;
+        this._dirty = false;
+        this._mergedCells = new Set();
+        this._sheetData = [];
+        this._workbook = workbook;
+        this._name = name;
+    }
+    /**
+   * Get the workbook this sheet belongs to
+   */ get workbook() {
+        return this._workbook;
+    }
+    /**
+   * Get the sheet name
+   */ get name() {
+        return this._name;
+    }
+    /**
+   * Set the sheet name
+   */ set name(value) {
+        this._name = value;
+        this._dirty = true;
+    }
+    /**
+   * Parse worksheet XML content
+   */ parse(xml) {
+        this._xmlNodes = parseXml(xml);
+        const worksheet = findElement(this._xmlNodes, 'worksheet');
+        if (!worksheet) return;
+        const worksheetChildren = getChildren(worksheet, 'worksheet');
+        // Parse sheet data (cells)
+        const sheetData = findElement(worksheetChildren, 'sheetData');
+        if (sheetData) {
+            this._sheetData = getChildren(sheetData, 'sheetData');
+            this._parseSheetData(this._sheetData);
+        }
+        // Parse merged cells
+        const mergeCells = findElement(worksheetChildren, 'mergeCells');
+        if (mergeCells) {
+            const mergeChildren = getChildren(mergeCells, 'mergeCells');
+            for (const mergeCell of mergeChildren){
+                if ('mergeCell' in mergeCell) {
+                    const ref = getAttr(mergeCell, 'ref');
+                    if (ref) {
+                        this._mergedCells.add(ref);
+                    }
+                }
+            }
+        }
+    }
+    /**
+   * Parse the sheetData element to extract cells
+   */ _parseSheetData(rows) {
+        for (const rowNode of rows){
+            if (!('row' in rowNode)) continue;
+            const rowChildren = getChildren(rowNode, 'row');
+            for (const cellNode of rowChildren){
+                if (!('c' in cellNode)) continue;
+                const ref = getAttr(cellNode, 'r');
+                if (!ref) continue;
+                const { row, col } = parseAddress(ref);
+                const cellData = this._parseCellNode(cellNode);
+                const cell = new Cell(this, row, col, cellData);
+                this._cells.set(ref, cell);
+            }
+        }
+    }
+    /**
+   * Parse a cell XML node to CellData
+   */ _parseCellNode(node) {
+        const data = {};
+        // Type attribute
+        const t = getAttr(node, 't');
+        if (t) {
+            data.t = t;
+        }
+        // Style attribute
+        const s = getAttr(node, 's');
+        if (s) {
+            data.s = parseInt(s, 10);
+        }
+        const children = getChildren(node, 'c');
+        // Value element
+        const vNode = findElement(children, 'v');
+        if (vNode) {
+            const vChildren = getChildren(vNode, 'v');
+            for (const child of vChildren){
+                if ('#text' in child) {
+                    const text = child['#text'];
+                    // Parse based on type
+                    if (data.t === 's') {
+                        data.v = parseInt(text, 10); // Shared string index
+                    } else if (data.t === 'b') {
+                        data.v = text === '1' ? 1 : 0;
+                    } else if (data.t === 'e' || data.t === 'str') {
+                        data.v = text;
+                    } else {
+                        // Number or default
+                        data.v = parseFloat(text);
+                    }
+                    break;
+                }
+            }
+        }
+        // Formula element
+        const fNode = findElement(children, 'f');
+        if (fNode) {
+            const fChildren = getChildren(fNode, 'f');
+            for (const child of fChildren){
+                if ('#text' in child) {
+                    data.f = child['#text'];
+                    break;
+                }
+            }
+            // Check for shared formula
+            const si = getAttr(fNode, 'si');
+            if (si) {
+                data.si = parseInt(si, 10);
+            }
+            // Check for array formula range
+            const ref = getAttr(fNode, 'ref');
+            if (ref) {
+                data.F = ref;
+            }
+        }
+        // Inline string (is element)
+        const isNode = findElement(children, 'is');
+        if (isNode) {
+            data.t = 'str';
+            const isChildren = getChildren(isNode, 'is');
+            const tNode = findElement(isChildren, 't');
+            if (tNode) {
+                const tChildren = getChildren(tNode, 't');
+                for (const child of tChildren){
+                    if ('#text' in child) {
+                        data.v = child['#text'];
+                        break;
+                    }
+                }
+            }
+        }
+        return data;
+    }
+    /**
+   * Get a cell by address or row/col
+   */ cell(rowOrAddress, col) {
+        const { row, col: c } = parseCellRef(rowOrAddress, col);
+        const address = toAddress(row, c);
+        let cell = this._cells.get(address);
+        if (!cell) {
+            cell = new Cell(this, row, c);
+            this._cells.set(address, cell);
+        }
+        return cell;
+    }
+    range(startRowOrRange, startCol, endRow, endCol) {
+        let rangeAddr;
+        if (typeof startRowOrRange === 'string') {
+            rangeAddr = parseRange(startRowOrRange);
+        } else {
+            if (startCol === undefined || endRow === undefined || endCol === undefined) {
+                throw new Error('All range parameters must be provided');
+            }
+            rangeAddr = {
+                start: {
+                    row: startRowOrRange,
+                    col: startCol
+                },
+                end: {
+                    row: endRow,
+                    col: endCol
+                }
+            };
+        }
+        return new Range(this, rangeAddr);
+    }
+    /**
+   * Merge cells in the given range
+   */ mergeCells(rangeOrStart, end) {
+        let rangeStr;
+        if (end) {
+            rangeStr = `${rangeOrStart}:${end}`;
+        } else {
+            rangeStr = rangeOrStart;
+        }
+        this._mergedCells.add(rangeStr);
+        this._dirty = true;
+    }
+    /**
+   * Unmerge cells in the given range
+   */ unmergeCells(rangeStr) {
+        this._mergedCells.delete(rangeStr);
+        this._dirty = true;
+    }
+    /**
+   * Get all merged cell ranges
+   */ get mergedCells() {
+        return Array.from(this._mergedCells);
+    }
+    /**
+   * Check if the worksheet has been modified
+   */ get dirty() {
+        if (this._dirty) return true;
+        for (const cell of this._cells.values()){
+            if (cell.dirty) return true;
+        }
+        return false;
+    }
+    /**
+   * Get all cells in the worksheet
+   */ get cells() {
+        return this._cells;
+    }
+    /**
+   * Generate XML for this worksheet
+   */ toXml() {
+        // Build sheetData from cells
+        const rowMap = new Map();
+        for (const cell of this._cells.values()){
+            const row = cell.row;
+            if (!rowMap.has(row)) {
+                rowMap.set(row, []);
+            }
+            rowMap.get(row).push(cell);
+        }
+        // Sort rows and cells
+        const sortedRows = Array.from(rowMap.entries()).sort((a, b)=>a[0] - b[0]);
+        const rowNodes = [];
+        for (const [rowIdx, cells] of sortedRows){
+            cells.sort((a, b)=>a.col - b.col);
+            const cellNodes = [];
+            for (const cell of cells){
+                const cellNode = this._buildCellNode(cell);
+                cellNodes.push(cellNode);
+            }
+            const rowNode = createElement('row', {
+                r: String(rowIdx + 1)
+            }, cellNodes);
+            rowNodes.push(rowNode);
+        }
+        const sheetDataNode = createElement('sheetData', {}, rowNodes);
+        // Build worksheet structure
+        const worksheetChildren = [
+            sheetDataNode
+        ];
+        // Add merged cells if any
+        if (this._mergedCells.size > 0) {
+            const mergeCellNodes = [];
+            for (const ref of this._mergedCells){
+                mergeCellNodes.push(createElement('mergeCell', {
+                    ref
+                }, []));
+            }
+            const mergeCellsNode = createElement('mergeCells', {
+                count: String(this._mergedCells.size)
+            }, mergeCellNodes);
+            worksheetChildren.push(mergeCellsNode);
+        }
+        const worksheetNode = createElement('worksheet', {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+            'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+        }, worksheetChildren);
+        return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            worksheetNode
+        ])}`;
+    }
+    /**
+   * Build a cell XML node from a Cell object
+   */ _buildCellNode(cell) {
+        const data = cell.data;
+        const attrs = {
+            r: cell.address
+        };
+        if (data.t && data.t !== 'n') {
+            attrs.t = data.t;
+        }
+        if (data.s !== undefined) {
+            attrs.s = String(data.s);
+        }
+        const children = [];
+        // Formula
+        if (data.f) {
+            const fAttrs = {};
+            if (data.F) fAttrs.ref = data.F;
+            if (data.si !== undefined) fAttrs.si = String(data.si);
+            children.push(createElement('f', fAttrs, [
+                createText(data.f)
+            ]));
+        }
+        // Value
+        if (data.v !== undefined) {
+            children.push(createElement('v', {}, [
+                createText(String(data.v))
+            ]));
+        }
+        return createElement('c', attrs, children);
+    }
+}
+
+/**
+ * Manages the shared strings table from xl/sharedStrings.xml
+ * Excel stores strings in a shared table to reduce file size
+ */ class SharedStrings {
+    /**
+   * Parse shared strings from XML content
+   */ static parse(xml) {
+        const ss = new SharedStrings();
+        const parsed = parseXml(xml);
+        const sst = findElement(parsed, 'sst');
+        if (!sst) return ss;
+        const children = getChildren(sst, 'sst');
+        for (const child of children){
+            if ('si' in child) {
+                const siChildren = getChildren(child, 'si');
+                const text = ss.extractText(siChildren);
+                ss.strings.push(text);
+                ss.stringToIndex.set(text, ss.strings.length - 1);
+            }
+        }
+        return ss;
+    }
+    /**
+   * Extract text from a string item (si element)
+   * Handles both simple <t> elements and rich text <r> elements
+   */ extractText(nodes) {
+        let text = '';
+        for (const node of nodes){
+            if ('t' in node) {
+                // Simple text: <t>value</t>
+                const tChildren = getChildren(node, 't');
+                for (const child of tChildren){
+                    if ('#text' in child) {
+                        text += child['#text'];
+                    }
+                }
+            } else if ('r' in node) {
+                // Rich text: <r><t>value</t></r>
+                const rChildren = getChildren(node, 'r');
+                for (const rChild of rChildren){
+                    if ('t' in rChild) {
+                        const tChildren = getChildren(rChild, 't');
+                        for (const child of tChildren){
+                            if ('#text' in child) {
+                                text += child['#text'];
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        return text;
+    }
+    /**
+   * Get a string by index
+   */ getString(index) {
+        return this.strings[index];
+    }
+    /**
+   * Add a string and return its index
+   * If the string already exists, returns the existing index
+   */ addString(str) {
+        const existing = this.stringToIndex.get(str);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const index = this.strings.length;
+        this.strings.push(str);
+        this.stringToIndex.set(str, index);
+        this._dirty = true;
+        return index;
+    }
+    /**
+   * Check if the shared strings table has been modified
+   */ get dirty() {
+        return this._dirty;
+    }
+    /**
+   * Get the count of strings
+   */ get count() {
+        return this.strings.length;
+    }
+    /**
+   * Generate XML for the shared strings table
+   */ toXml() {
+        const siElements = [];
+        for (const str of this.strings){
+            const tElement = createElement('t', str.startsWith(' ') || str.endsWith(' ') ? {
+                'xml:space': 'preserve'
+            } : {}, [
+                createText(str)
+            ]);
+            const siElement = createElement('si', {}, [
+                tElement
+            ]);
+            siElements.push(siElement);
+        }
+        const sst = createElement('sst', {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+            count: String(this.strings.length),
+            uniqueCount: String(this.strings.length)
+        }, siElements);
+        return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            sst
+        ])}`;
+    }
+    constructor(){
+        this.strings = [];
+        this.stringToIndex = new Map();
+        this._dirty = false;
+    }
+}
+
+/**
+ * Normalize a color to ARGB format (8 hex chars).
+ * Accepts: "#RGB", "#RRGGBB", "RGB", "RRGGBB", "AARRGGBB", "#AARRGGBB"
+ */ const normalizeColor = (color)=>{
+    let c = color.replace(/^#/, '').toUpperCase();
+    // Handle shorthand 3-char format (e.g., "FFF" -> "FFFFFF")
+    if (c.length === 3) {
+        c = c[0] + c[0] + c[1] + c[1] + c[2] + c[2];
+    }
+    // Add alpha channel if not present (6 chars -> 8 chars)
+    if (c.length === 6) {
+        c = 'FF' + c;
+    }
+    return c;
+};
+/**
+ * Manages the styles (xl/styles.xml)
+ */ class Styles {
+    /**
+   * Parse styles from XML content
+   */ static parse(xml) {
+        const styles = new Styles();
+        styles._xmlNodes = parseXml(xml);
+        const styleSheet = findElement(styles._xmlNodes, 'styleSheet');
+        if (!styleSheet) return styles;
+        const children = getChildren(styleSheet, 'styleSheet');
+        // Parse number formats
+        const numFmts = findElement(children, 'numFmts');
+        if (numFmts) {
+            for (const child of getChildren(numFmts, 'numFmts')){
+                if ('numFmt' in child) {
+                    const id = parseInt(getAttr(child, 'numFmtId') || '0', 10);
+                    const code = getAttr(child, 'formatCode') || '';
+                    styles._numFmts.set(id, code);
+                }
+            }
+        }
+        // Parse fonts
+        const fonts = findElement(children, 'fonts');
+        if (fonts) {
+            for (const child of getChildren(fonts, 'fonts')){
+                if ('font' in child) {
+                    styles._fonts.push(styles._parseFont(child));
+                }
+            }
+        }
+        // Parse fills
+        const fills = findElement(children, 'fills');
+        if (fills) {
+            for (const child of getChildren(fills, 'fills')){
+                if ('fill' in child) {
+                    styles._fills.push(styles._parseFill(child));
+                }
+            }
+        }
+        // Parse borders
+        const borders = findElement(children, 'borders');
+        if (borders) {
+            for (const child of getChildren(borders, 'borders')){
+                if ('border' in child) {
+                    styles._borders.push(styles._parseBorder(child));
+                }
+            }
+        }
+        // Parse cellXfs (cell formats)
+        const cellXfs = findElement(children, 'cellXfs');
+        if (cellXfs) {
+            for (const child of getChildren(cellXfs, 'cellXfs')){
+                if ('xf' in child) {
+                    styles._cellXfs.push(styles._parseCellXf(child));
+                }
+            }
+        }
+        return styles;
+    }
+    /**
+   * Create an empty styles object with defaults
+   */ static createDefault() {
+        const styles = new Styles();
+        // Default font (Calibri 11)
+        styles._fonts.push({
+            bold: false,
+            italic: false,
+            underline: false,
+            strike: false,
+            size: 11,
+            name: 'Calibri',
+            color: undefined
+        });
+        // Default fills (none and gray125 pattern are required)
+        styles._fills.push({
+            type: 'none'
+        });
+        styles._fills.push({
+            type: 'gray125'
+        });
+        // Default border (none)
+        styles._borders.push({});
+        // Default cell format
+        styles._cellXfs.push({
+            fontId: 0,
+            fillId: 0,
+            borderId: 0,
+            numFmtId: 0
+        });
+        return styles;
+    }
+    _parseFont(node) {
+        const font = {
+            bold: false,
+            italic: false,
+            underline: false,
+            strike: false
+        };
+        const children = getChildren(node, 'font');
+        for (const child of children){
+            if ('b' in child) font.bold = true;
+            if ('i' in child) font.italic = true;
+            if ('u' in child) font.underline = true;
+            if ('strike' in child) font.strike = true;
+            if ('sz' in child) font.size = parseFloat(getAttr(child, 'val') || '11');
+            if ('name' in child) font.name = getAttr(child, 'val');
+            if ('color' in child) {
+                font.color = getAttr(child, 'rgb') || getAttr(child, 'theme');
+            }
+        }
+        return font;
+    }
+    _parseFill(node) {
+        const fill = {
+            type: 'none'
+        };
+        const children = getChildren(node, 'fill');
+        for (const child of children){
+            if ('patternFill' in child) {
+                const pattern = getAttr(child, 'patternType');
+                fill.type = pattern || 'none';
+                const pfChildren = getChildren(child, 'patternFill');
+                for (const pfChild of pfChildren){
+                    if ('fgColor' in pfChild) {
+                        fill.fgColor = getAttr(pfChild, 'rgb') || getAttr(pfChild, 'theme');
+                    }
+                    if ('bgColor' in pfChild) {
+                        fill.bgColor = getAttr(pfChild, 'rgb') || getAttr(pfChild, 'theme');
+                    }
+                }
+            }
+        }
+        return fill;
+    }
+    _parseBorder(node) {
+        const border = {};
+        const children = getChildren(node, 'border');
+        for (const child of children){
+            const style = getAttr(child, 'style');
+            if ('left' in child && style) border.left = style;
+            if ('right' in child && style) border.right = style;
+            if ('top' in child && style) border.top = style;
+            if ('bottom' in child && style) border.bottom = style;
+        }
+        return border;
+    }
+    _parseCellXf(node) {
+        return {
+            fontId: parseInt(getAttr(node, 'fontId') || '0', 10),
+            fillId: parseInt(getAttr(node, 'fillId') || '0', 10),
+            borderId: parseInt(getAttr(node, 'borderId') || '0', 10),
+            numFmtId: parseInt(getAttr(node, 'numFmtId') || '0', 10),
+            alignment: this._parseAlignment(node)
+        };
+    }
+    _parseAlignment(node) {
+        const children = getChildren(node, 'xf');
+        const alignNode = findElement(children, 'alignment');
+        if (!alignNode) return undefined;
+        return {
+            horizontal: getAttr(alignNode, 'horizontal'),
+            vertical: getAttr(alignNode, 'vertical'),
+            wrapText: getAttr(alignNode, 'wrapText') === '1',
+            textRotation: parseInt(getAttr(alignNode, 'textRotation') || '0', 10)
+        };
+    }
+    /**
+   * Get a style by index
+   */ getStyle(index) {
+        const xf = this._cellXfs[index];
+        if (!xf) return {};
+        const font = this._fonts[xf.fontId];
+        const fill = this._fills[xf.fillId];
+        const border = this._borders[xf.borderId];
+        const numFmt = this._numFmts.get(xf.numFmtId);
+        const style = {};
+        if (font) {
+            if (font.bold) style.bold = true;
+            if (font.italic) style.italic = true;
+            if (font.underline) style.underline = true;
+            if (font.strike) style.strike = true;
+            if (font.size) style.fontSize = font.size;
+            if (font.name) style.fontName = font.name;
+            if (font.color) style.fontColor = font.color;
+        }
+        if (fill && fill.fgColor) {
+            style.fill = fill.fgColor;
+        }
+        if (border) {
+            if (border.top || border.bottom || border.left || border.right) {
+                style.border = {
+                    top: border.top,
+                    bottom: border.bottom,
+                    left: border.left,
+                    right: border.right
+                };
+            }
+        }
+        if (numFmt) {
+            style.numberFormat = numFmt;
+        }
+        if (xf.alignment) {
+            style.alignment = {
+                horizontal: xf.alignment.horizontal,
+                vertical: xf.alignment.vertical,
+                wrapText: xf.alignment.wrapText,
+                textRotation: xf.alignment.textRotation
+            };
+        }
+        return style;
+    }
+    /**
+   * Create a style and return its index
+   * Uses caching to deduplicate identical styles
+   */ createStyle(style) {
+        const key = JSON.stringify(style);
+        const cached = this._styleCache.get(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        this._dirty = true;
+        // Create or find font
+        const fontId = this._findOrCreateFont(style);
+        // Create or find fill
+        const fillId = this._findOrCreateFill(style);
+        // Create or find border
+        const borderId = this._findOrCreateBorder(style);
+        // Create or find number format
+        const numFmtId = style.numberFormat ? this._findOrCreateNumFmt(style.numberFormat) : 0;
+        // Create cell format
+        const xf = {
+            fontId,
+            fillId,
+            borderId,
+            numFmtId
+        };
+        if (style.alignment) {
+            xf.alignment = {
+                horizontal: style.alignment.horizontal,
+                vertical: style.alignment.vertical,
+                wrapText: style.alignment.wrapText,
+                textRotation: style.alignment.textRotation
+            };
+        }
+        const index = this._cellXfs.length;
+        this._cellXfs.push(xf);
+        this._styleCache.set(key, index);
+        return index;
+    }
+    _findOrCreateFont(style) {
+        const font = {
+            bold: style.bold || false,
+            italic: style.italic || false,
+            underline: style.underline === true || style.underline === 'single' || style.underline === 'double',
+            strike: style.strike || false,
+            size: style.fontSize,
+            name: style.fontName,
+            color: style.fontColor
+        };
+        // Try to find existing font
+        for(let i = 0; i < this._fonts.length; i++){
+            const f = this._fonts[i];
+            if (f.bold === font.bold && f.italic === font.italic && f.underline === font.underline && f.strike === font.strike && f.size === font.size && f.name === font.name && f.color === font.color) {
+                return i;
+            }
+        }
+        // Create new font
+        this._fonts.push(font);
+        return this._fonts.length - 1;
+    }
+    _findOrCreateFill(style) {
+        if (!style.fill) return 0;
+        // Try to find existing fill
+        for(let i = 0; i < this._fills.length; i++){
+            const f = this._fills[i];
+            if (f.fgColor === style.fill) {
+                return i;
+            }
+        }
+        // Create new fill
+        this._fills.push({
+            type: 'solid',
+            fgColor: style.fill
+        });
+        return this._fills.length - 1;
+    }
+    _findOrCreateBorder(style) {
+        if (!style.border) return 0;
+        const border = {
+            top: style.border.top,
+            bottom: style.border.bottom,
+            left: style.border.left,
+            right: style.border.right
+        };
+        // Try to find existing border
+        for(let i = 0; i < this._borders.length; i++){
+            const b = this._borders[i];
+            if (b.top === border.top && b.bottom === border.bottom && b.left === border.left && b.right === border.right) {
+                return i;
+            }
+        }
+        // Create new border
+        this._borders.push(border);
+        return this._borders.length - 1;
+    }
+    _findOrCreateNumFmt(format) {
+        // Check if already exists
+        for (const [id, code] of this._numFmts){
+            if (code === format) return id;
+        }
+        // Create new (custom formats start at 164)
+        const id = Math.max(164, ...Array.from(this._numFmts.keys())) + 1;
+        this._numFmts.set(id, format);
+        return id;
+    }
+    /**
+   * Check if styles have been modified
+   */ get dirty() {
+        return this._dirty;
+    }
+    /**
+   * Generate XML for styles
+   */ toXml() {
+        const children = [];
+        // Number formats
+        if (this._numFmts.size > 0) {
+            const numFmtNodes = [];
+            for (const [id, code] of this._numFmts){
+                numFmtNodes.push(createElement('numFmt', {
+                    numFmtId: String(id),
+                    formatCode: code
+                }, []));
+            }
+            children.push(createElement('numFmts', {
+                count: String(numFmtNodes.length)
+            }, numFmtNodes));
+        }
+        // Fonts
+        const fontNodes = this._fonts.map((font)=>this._buildFontNode(font));
+        children.push(createElement('fonts', {
+            count: String(fontNodes.length)
+        }, fontNodes));
+        // Fills
+        const fillNodes = this._fills.map((fill)=>this._buildFillNode(fill));
+        children.push(createElement('fills', {
+            count: String(fillNodes.length)
+        }, fillNodes));
+        // Borders
+        const borderNodes = this._borders.map((border)=>this._buildBorderNode(border));
+        children.push(createElement('borders', {
+            count: String(borderNodes.length)
+        }, borderNodes));
+        // Cell style xfs (required but we just add a default)
+        children.push(createElement('cellStyleXfs', {
+            count: '1'
+        }, [
+            createElement('xf', {
+                numFmtId: '0',
+                fontId: '0',
+                fillId: '0',
+                borderId: '0'
+            }, [])
+        ]));
+        // Cell xfs
+        const xfNodes = this._cellXfs.map((xf)=>this._buildXfNode(xf));
+        children.push(createElement('cellXfs', {
+            count: String(xfNodes.length)
+        }, xfNodes));
+        // Cell styles (required)
+        children.push(createElement('cellStyles', {
+            count: '1'
+        }, [
+            createElement('cellStyle', {
+                name: 'Normal',
+                xfId: '0',
+                builtinId: '0'
+            }, [])
+        ]));
+        const styleSheet = createElement('styleSheet', {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'
+        }, children);
+        return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            styleSheet
+        ])}`;
+    }
+    _buildFontNode(font) {
+        const children = [];
+        if (font.bold) children.push(createElement('b', {}, []));
+        if (font.italic) children.push(createElement('i', {}, []));
+        if (font.underline) children.push(createElement('u', {}, []));
+        if (font.strike) children.push(createElement('strike', {}, []));
+        if (font.size) children.push(createElement('sz', {
+            val: String(font.size)
+        }, []));
+        if (font.color) children.push(createElement('color', {
+            rgb: normalizeColor(font.color)
+        }, []));
+        if (font.name) children.push(createElement('name', {
+            val: font.name
+        }, []));
+        return createElement('font', {}, children);
+    }
+    _buildFillNode(fill) {
+        const patternChildren = [];
+        if (fill.fgColor) {
+            const rgb = normalizeColor(fill.fgColor);
+            patternChildren.push(createElement('fgColor', {
+                rgb
+            }, []));
+            // For solid fills, bgColor is required (indexed 64 = system background)
+            if (fill.type === 'solid') {
+                patternChildren.push(createElement('bgColor', {
+                    indexed: '64'
+                }, []));
+            }
+        }
+        if (fill.bgColor && fill.type !== 'solid') {
+            const rgb = normalizeColor(fill.bgColor);
+            patternChildren.push(createElement('bgColor', {
+                rgb
+            }, []));
+        }
+        const patternFill = createElement('patternFill', {
+            patternType: fill.type || 'none'
+        }, patternChildren);
+        return createElement('fill', {}, [
+            patternFill
+        ]);
+    }
+    _buildBorderNode(border) {
+        const children = [];
+        if (border.left) children.push(createElement('left', {
+            style: border.left
+        }, []));
+        if (border.right) children.push(createElement('right', {
+            style: border.right
+        }, []));
+        if (border.top) children.push(createElement('top', {
+            style: border.top
+        }, []));
+        if (border.bottom) children.push(createElement('bottom', {
+            style: border.bottom
+        }, []));
+        // Add empty elements if not present (required by Excel)
+        if (!border.left) children.push(createElement('left', {}, []));
+        if (!border.right) children.push(createElement('right', {}, []));
+        if (!border.top) children.push(createElement('top', {}, []));
+        if (!border.bottom) children.push(createElement('bottom', {}, []));
+        children.push(createElement('diagonal', {}, []));
+        return createElement('border', {}, children);
+    }
+    _buildXfNode(xf) {
+        const attrs = {
+            numFmtId: String(xf.numFmtId),
+            fontId: String(xf.fontId),
+            fillId: String(xf.fillId),
+            borderId: String(xf.borderId)
+        };
+        if (xf.fontId > 0) attrs.applyFont = '1';
+        if (xf.fillId > 0) attrs.applyFill = '1';
+        if (xf.borderId > 0) attrs.applyBorder = '1';
+        if (xf.numFmtId > 0) attrs.applyNumberFormat = '1';
+        const children = [];
+        if (xf.alignment) {
+            const alignAttrs = {};
+            if (xf.alignment.horizontal) alignAttrs.horizontal = xf.alignment.horizontal;
+            if (xf.alignment.vertical) alignAttrs.vertical = xf.alignment.vertical;
+            if (xf.alignment.wrapText) alignAttrs.wrapText = '1';
+            if (xf.alignment.textRotation) alignAttrs.textRotation = String(xf.alignment.textRotation);
+            children.push(createElement('alignment', alignAttrs, []));
+            attrs.applyAlignment = '1';
+        }
+        return createElement('xf', attrs, children);
+    }
+    constructor(){
+        this._numFmts = new Map();
+        this._fonts = [];
+        this._fills = [];
+        this._borders = [];
+        this._cellXfs = []; // Cell formats (combined style index)
+        this._xmlNodes = null;
+        this._dirty = false;
+        // Cache for style deduplication
+        this._styleCache = new Map();
+    }
+}
+
+/**
+ * Represents an Excel pivot table with a fluent API for configuration.
+ */ class PivotTable {
+    constructor(name, cache, targetSheet, targetCell, targetRow, targetCol, pivotTableIndex){
+        this._rowFields = [];
+        this._columnFields = [];
+        this._valueFields = [];
+        this._filterFields = [];
+        this._name = name;
+        this._cache = cache;
+        this._targetSheet = targetSheet;
+        this._targetCell = targetCell;
+        this._targetRow = targetRow;
+        this._targetCol = targetCol;
+        this._pivotTableIndex = pivotTableIndex;
+    }
+    /**
+   * Get the pivot table name
+   */ get name() {
+        return this._name;
+    }
+    /**
+   * Get the target sheet name
+   */ get targetSheet() {
+        return this._targetSheet;
+    }
+    /**
+   * Get the target cell address
+   */ get targetCell() {
+        return this._targetCell;
+    }
+    /**
+   * Get the pivot cache
+   */ get cache() {
+        return this._cache;
+    }
+    /**
+   * Get the pivot table index (for file naming)
+   */ get index() {
+        return this._pivotTableIndex;
+    }
+    /**
+   * Add a field to the row area
+   * @param fieldName - Name of the source field (column header)
+   */ addRowField(fieldName) {
+        const fieldIndex = this._cache.getFieldIndex(fieldName);
+        if (fieldIndex < 0) {
+            throw new Error(`Field not found in source data: ${fieldName}`);
+        }
+        this._rowFields.push({
+            fieldName,
+            fieldIndex,
+            axis: 'row'
+        });
+        return this;
+    }
+    /**
+   * Add a field to the column area
+   * @param fieldName - Name of the source field (column header)
+   */ addColumnField(fieldName) {
+        const fieldIndex = this._cache.getFieldIndex(fieldName);
+        if (fieldIndex < 0) {
+            throw new Error(`Field not found in source data: ${fieldName}`);
+        }
+        this._columnFields.push({
+            fieldName,
+            fieldIndex,
+            axis: 'column'
+        });
+        return this;
+    }
+    /**
+   * Add a field to the values area with aggregation
+   * @param fieldName - Name of the source field (column header)
+   * @param aggregation - Aggregation function (sum, count, average, min, max)
+   * @param displayName - Optional display name (defaults to "Sum of FieldName")
+   */ addValueField(fieldName, aggregation = 'sum', displayName) {
+        const fieldIndex = this._cache.getFieldIndex(fieldName);
+        if (fieldIndex < 0) {
+            throw new Error(`Field not found in source data: ${fieldName}`);
+        }
+        const defaultName = `${aggregation.charAt(0).toUpperCase() + aggregation.slice(1)} of ${fieldName}`;
+        this._valueFields.push({
+            fieldName,
+            fieldIndex,
+            axis: 'value',
+            aggregation,
+            displayName: displayName || defaultName
+        });
+        return this;
+    }
+    /**
+   * Add a field to the filter (page) area
+   * @param fieldName - Name of the source field (column header)
+   */ addFilterField(fieldName) {
+        const fieldIndex = this._cache.getFieldIndex(fieldName);
+        if (fieldIndex < 0) {
+            throw new Error(`Field not found in source data: ${fieldName}`);
+        }
+        this._filterFields.push({
+            fieldName,
+            fieldIndex,
+            axis: 'filter'
+        });
+        return this;
+    }
+    /**
+   * Generate the pivotTableDefinition XML
+   */ toXml() {
+        const children = [];
+        // Calculate location (estimate based on fields)
+        const locationRef = this._calculateLocationRef();
+        // Calculate first data row/col offsets (1-based, relative to pivot table)
+        // firstHeaderRow: row offset of column headers (usually 1)
+        // firstDataRow: row offset where data starts (after filters and column headers)
+        // firstDataCol: column offset where data starts (after row labels)
+        const filterRowCount = this._filterFields.length > 0 ? this._filterFields.length + 1 : 0;
+        const headerRows = this._columnFields.length > 0 ? 1 : 0;
+        const firstDataRow = filterRowCount + headerRows + 1;
+        const firstDataCol = this._rowFields.length > 0 ? this._rowFields.length : 1;
+        const locationNode = createElement('location', {
+            ref: locationRef,
+            firstHeaderRow: String(filterRowCount + 1),
+            firstDataRow: String(firstDataRow),
+            firstDataCol: String(firstDataCol)
+        }, []);
+        children.push(locationNode);
+        // Build pivotFields (one per source field)
+        const pivotFieldNodes = [];
+        for (const cacheField of this._cache.fields){
+            const fieldNode = this._buildPivotFieldNode(cacheField.index);
+            pivotFieldNodes.push(fieldNode);
+        }
+        children.push(createElement('pivotFields', {
+            count: String(pivotFieldNodes.length)
+        }, pivotFieldNodes));
+        // Row fields
+        if (this._rowFields.length > 0) {
+            const rowFieldNodes = this._rowFields.map((f)=>createElement('field', {
+                    x: String(f.fieldIndex)
+                }, []));
+            children.push(createElement('rowFields', {
+                count: String(rowFieldNodes.length)
+            }, rowFieldNodes));
+            // Row items
+            const rowItemNodes = this._buildRowItems();
+            children.push(createElement('rowItems', {
+                count: String(rowItemNodes.length)
+            }, rowItemNodes));
+        }
+        // Column fields
+        if (this._columnFields.length > 0) {
+            const colFieldNodes = this._columnFields.map((f)=>createElement('field', {
+                    x: String(f.fieldIndex)
+                }, []));
+            // If we have multiple value fields, add -2 to indicate where "Values" header goes
+            if (this._valueFields.length > 1) {
+                colFieldNodes.push(createElement('field', {
+                    x: '-2'
+                }, []));
+            }
+            children.push(createElement('colFields', {
+                count: String(colFieldNodes.length)
+            }, colFieldNodes));
+            // Column items - need to account for multiple value fields
+            const colItemNodes = this._buildColItems();
+            children.push(createElement('colItems', {
+                count: String(colItemNodes.length)
+            }, colItemNodes));
+        } else if (this._valueFields.length > 1) {
+            // If no column fields but we have multiple values, need colFields with -2 (data field indicator)
+            children.push(createElement('colFields', {
+                count: '1'
+            }, [
+                createElement('field', {
+                    x: '-2'
+                }, [])
+            ]));
+            // Column items for each value field
+            const colItemNodes = [];
+            for(let i = 0; i < this._valueFields.length; i++){
+                colItemNodes.push(createElement('i', {}, [
+                    createElement('x', i === 0 ? {} : {
+                        v: String(i)
+                    }, [])
+                ]));
+            }
+            children.push(createElement('colItems', {
+                count: String(colItemNodes.length)
+            }, colItemNodes));
+        } else if (this._valueFields.length === 1) {
+            // Single value field - just add a single column item
+            children.push(createElement('colItems', {
+                count: '1'
+            }, [
+                createElement('i', {}, [])
+            ]));
+        }
+        // Page (filter) fields
+        if (this._filterFields.length > 0) {
+            const pageFieldNodes = this._filterFields.map((f)=>createElement('pageField', {
+                    fld: String(f.fieldIndex),
+                    hier: '-1'
+                }, []));
+            children.push(createElement('pageFields', {
+                count: String(pageFieldNodes.length)
+            }, pageFieldNodes));
+        }
+        // Data fields (values)
+        if (this._valueFields.length > 0) {
+            const dataFieldNodes = this._valueFields.map((f)=>createElement('dataField', {
+                    name: f.displayName || f.fieldName,
+                    fld: String(f.fieldIndex),
+                    baseField: '0',
+                    baseItem: '0',
+                    subtotal: f.aggregation || 'sum'
+                }, []));
+            children.push(createElement('dataFields', {
+                count: String(dataFieldNodes.length)
+            }, dataFieldNodes));
+        }
+        // Pivot table style
+        children.push(createElement('pivotTableStyleInfo', {
+            name: 'PivotStyleMedium9',
+            showRowHeaders: '1',
+            showColHeaders: '1',
+            showRowStripes: '0',
+            showColStripes: '0',
+            showLastColumn: '1'
+        }, []));
+        const pivotTableNode = createElement('pivotTableDefinition', {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+            'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+            name: this._name,
+            cacheId: String(this._cache.cacheId),
+            applyNumberFormats: '0',
+            applyBorderFormats: '0',
+            applyFontFormats: '0',
+            applyPatternFormats: '0',
+            applyAlignmentFormats: '0',
+            applyWidthHeightFormats: '1',
+            dataCaption: 'Values',
+            updatedVersion: '8',
+            minRefreshableVersion: '3',
+            useAutoFormatting: '1',
+            rowGrandTotals: '1',
+            colGrandTotals: '1',
+            itemPrintTitles: '1',
+            createdVersion: '8',
+            indent: '0',
+            outline: '1',
+            outlineData: '1',
+            multipleFieldFilters: '0'
+        }, children);
+        return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            pivotTableNode
+        ])}`;
+    }
+    /**
+   * Build a pivotField node for a given field index
+   */ _buildPivotFieldNode(fieldIndex) {
+        const attrs = {};
+        const children = [];
+        // Check if this field is assigned to an axis
+        const rowField = this._rowFields.find((f)=>f.fieldIndex === fieldIndex);
+        const colField = this._columnFields.find((f)=>f.fieldIndex === fieldIndex);
+        const filterField = this._filterFields.find((f)=>f.fieldIndex === fieldIndex);
+        const valueField = this._valueFields.find((f)=>f.fieldIndex === fieldIndex);
+        if (rowField) {
+            attrs.axis = 'axisRow';
+            attrs.showAll = '0';
+            // Add items for shared values
+            const cacheField = this._cache.fields[fieldIndex];
+            if (cacheField && cacheField.sharedItems.length > 0) {
+                const itemNodes = [];
+                for(let i = 0; i < cacheField.sharedItems.length; i++){
+                    itemNodes.push(createElement('item', {
+                        x: String(i)
+                    }, []));
+                }
+                // Add default subtotal item
+                itemNodes.push(createElement('item', {
+                    t: 'default'
+                }, []));
+                children.push(createElement('items', {
+                    count: String(itemNodes.length)
+                }, itemNodes));
+            }
+        } else if (colField) {
+            attrs.axis = 'axisCol';
+            attrs.showAll = '0';
+            const cacheField = this._cache.fields[fieldIndex];
+            if (cacheField && cacheField.sharedItems.length > 0) {
+                const itemNodes = [];
+                for(let i = 0; i < cacheField.sharedItems.length; i++){
+                    itemNodes.push(createElement('item', {
+                        x: String(i)
+                    }, []));
+                }
+                itemNodes.push(createElement('item', {
+                    t: 'default'
+                }, []));
+                children.push(createElement('items', {
+                    count: String(itemNodes.length)
+                }, itemNodes));
+            }
+        } else if (filterField) {
+            attrs.axis = 'axisPage';
+            attrs.showAll = '0';
+            const cacheField = this._cache.fields[fieldIndex];
+            if (cacheField && cacheField.sharedItems.length > 0) {
+                const itemNodes = [];
+                for(let i = 0; i < cacheField.sharedItems.length; i++){
+                    itemNodes.push(createElement('item', {
+                        x: String(i)
+                    }, []));
+                }
+                itemNodes.push(createElement('item', {
+                    t: 'default'
+                }, []));
+                children.push(createElement('items', {
+                    count: String(itemNodes.length)
+                }, itemNodes));
+            }
+        } else if (valueField) {
+            attrs.dataField = '1';
+            attrs.showAll = '0';
+        } else {
+            attrs.showAll = '0';
+        }
+        return createElement('pivotField', attrs, children);
+    }
+    /**
+   * Build row items based on unique values in row fields
+   */ _buildRowItems() {
+        const items = [];
+        if (this._rowFields.length === 0) return items;
+        // Get unique values from first row field
+        const firstRowField = this._rowFields[0];
+        const cacheField = this._cache.fields[firstRowField.fieldIndex];
+        if (cacheField && cacheField.sharedItems.length > 0) {
+            for(let i = 0; i < cacheField.sharedItems.length; i++){
+                items.push(createElement('i', {}, [
+                    createElement('x', i === 0 ? {} : {
+                        v: String(i)
+                    }, [])
+                ]));
+            }
+        }
+        // Add grand total row
+        items.push(createElement('i', {
+            t: 'grand'
+        }, [
+            createElement('x', {}, [])
+        ]));
+        return items;
+    }
+    /**
+   * Build column items based on unique values in column fields
+   */ _buildColItems() {
+        const items = [];
+        if (this._columnFields.length === 0) return items;
+        // Get unique values from first column field
+        const firstColField = this._columnFields[0];
+        const cacheField = this._cache.fields[firstColField.fieldIndex];
+        if (cacheField && cacheField.sharedItems.length > 0) {
+            if (this._valueFields.length > 1) {
+                // Multiple value fields - need nested items for each column value + value field combination
+                for(let colIdx = 0; colIdx < cacheField.sharedItems.length; colIdx++){
+                    for(let valIdx = 0; valIdx < this._valueFields.length; valIdx++){
+                        const xNodes = [
+                            createElement('x', colIdx === 0 ? {} : {
+                                v: String(colIdx)
+                            }, []),
+                            createElement('x', valIdx === 0 ? {} : {
+                                v: String(valIdx)
+                            }, [])
+                        ];
+                        items.push(createElement('i', {}, xNodes));
+                    }
+                }
+            } else {
+                // Single value field - simple column items
+                for(let i = 0; i < cacheField.sharedItems.length; i++){
+                    items.push(createElement('i', {}, [
+                        createElement('x', i === 0 ? {} : {
+                            v: String(i)
+                        }, [])
+                    ]));
+                }
+            }
+        }
+        // Add grand total column(s)
+        if (this._valueFields.length > 1) {
+            // Grand total for each value field
+            for(let valIdx = 0; valIdx < this._valueFields.length; valIdx++){
+                const xNodes = [
+                    createElement('x', {}, []),
+                    createElement('x', valIdx === 0 ? {} : {
+                        v: String(valIdx)
+                    }, [])
+                ];
+                items.push(createElement('i', {
+                    t: 'grand'
+                }, xNodes));
+            }
+        } else {
+            items.push(createElement('i', {
+                t: 'grand'
+            }, [
+                createElement('x', {}, [])
+            ]));
+        }
+        return items;
+    }
+    /**
+   * Calculate the location reference for the pivot table output
+   */ _calculateLocationRef() {
+        // Estimate output size based on fields
+        const numRows = this._estimateRowCount();
+        const numCols = this._estimateColCount();
+        const startRow = this._targetRow;
+        const startCol = this._targetCol;
+        const endRow = startRow + numRows - 1;
+        const endCol = startCol + numCols - 1;
+        return `${this._colToLetter(startCol)}${startRow}:${this._colToLetter(endCol)}${endRow}`;
+    }
+    /**
+   * Estimate number of rows in pivot table output
+   */ _estimateRowCount() {
+        let count = 1; // Header row
+        // Add filter area rows
+        count += this._filterFields.length;
+        // Add row labels (unique values in row fields)
+        if (this._rowFields.length > 0) {
+            const firstRowField = this._rowFields[0];
+            const cacheField = this._cache.fields[firstRowField.fieldIndex];
+            count += (cacheField?.sharedItems.length || 1) + 1; // +1 for grand total
+        } else {
+            count += 1; // At least one data row
+        }
+        return Math.max(count, 3);
+    }
+    /**
+   * Estimate number of columns in pivot table output
+   */ _estimateColCount() {
+        let count = 0;
+        // Row label columns
+        count += Math.max(this._rowFields.length, 1);
+        // Column labels (unique values in column fields)
+        if (this._columnFields.length > 0) {
+            const firstColField = this._columnFields[0];
+            const cacheField = this._cache.fields[firstColField.fieldIndex];
+            count += (cacheField?.sharedItems.length || 1) + 1; // +1 for grand total
+        } else {
+            // Value columns
+            count += Math.max(this._valueFields.length, 1);
+        }
+        return Math.max(count, 2);
+    }
+    /**
+   * Convert 0-based column index to letter (A, B, ..., Z, AA, etc.)
+   */ _colToLetter(col) {
+        let result = '';
+        let n = col;
+        while(n >= 0){
+            result = String.fromCharCode(n % 26 + 65) + result;
+            n = Math.floor(n / 26) - 1;
+        }
+        return result;
+    }
+}
+
+/**
+ * Manages the pivot cache (definition and records) for a pivot table.
+ * The cache stores source data metadata and cached values.
+ */ class PivotCache {
+    constructor(cacheId, sourceSheet, sourceRange){
+        this._fields = [];
+        this._records = [];
+        this._recordCount = 0;
+        this._refreshOnLoad = true; // Default to true
+        this._cacheId = cacheId;
+        this._sourceSheet = sourceSheet;
+        this._sourceRange = sourceRange;
+    }
+    /**
+   * Get the cache ID
+   */ get cacheId() {
+        return this._cacheId;
+    }
+    /**
+   * Set refreshOnLoad option
+   */ set refreshOnLoad(value) {
+        this._refreshOnLoad = value;
+    }
+    /**
+   * Get refreshOnLoad option
+   */ get refreshOnLoad() {
+        return this._refreshOnLoad;
+    }
+    /**
+   * Get the source sheet name
+   */ get sourceSheet() {
+        return this._sourceSheet;
+    }
+    /**
+   * Get the source range
+   */ get sourceRange() {
+        return this._sourceRange;
+    }
+    /**
+   * Get the full source reference (Sheet!Range)
+   */ get sourceRef() {
+        return `${this._sourceSheet}!${this._sourceRange}`;
+    }
+    /**
+   * Get the fields in this cache
+   */ get fields() {
+        return this._fields;
+    }
+    /**
+   * Get the number of data records
+   */ get recordCount() {
+        return this._recordCount;
+    }
+    /**
+   * Build the cache from source data.
+   * @param headers - Array of column header names
+   * @param data - 2D array of data rows (excluding headers)
+   */ buildFromData(headers, data) {
+        this._recordCount = data.length;
+        // Initialize fields from headers
+        this._fields = headers.map((name, index)=>({
+                name,
+                index,
+                isNumeric: true,
+                isDate: false,
+                sharedItems: [],
+                minValue: undefined,
+                maxValue: undefined
+            }));
+        // Analyze data to determine field types and collect unique values
+        for (const row of data){
+            for(let colIdx = 0; colIdx < row.length && colIdx < this._fields.length; colIdx++){
+                const value = row[colIdx];
+                const field = this._fields[colIdx];
+                if (value === null || value === undefined) {
+                    continue;
+                }
+                if (typeof value === 'string') {
+                    field.isNumeric = false;
+                    if (!field.sharedItems.includes(value)) {
+                        field.sharedItems.push(value);
+                    }
+                } else if (typeof value === 'number') {
+                    if (field.minValue === undefined || value < field.minValue) {
+                        field.minValue = value;
+                    }
+                    if (field.maxValue === undefined || value > field.maxValue) {
+                        field.maxValue = value;
+                    }
+                } else if (value instanceof Date) {
+                    field.isDate = true;
+                    field.isNumeric = false;
+                } else if (typeof value === 'boolean') {
+                    field.isNumeric = false;
+                }
+            }
+        }
+        // Store records
+        this._records = data;
+    }
+    /**
+   * Get field by name
+   */ getField(name) {
+        return this._fields.find((f)=>f.name === name);
+    }
+    /**
+   * Get field index by name
+   */ getFieldIndex(name) {
+        const field = this._fields.find((f)=>f.name === name);
+        return field ? field.index : -1;
+    }
+    /**
+   * Generate the pivotCacheDefinition XML
+   */ toDefinitionXml(recordsRelId) {
+        const cacheFieldNodes = this._fields.map((field)=>{
+            const sharedItemsAttrs = {};
+            const sharedItemChildren = [];
+            if (field.sharedItems.length > 0) {
+                // String field with shared items - Excel just uses count attribute
+                sharedItemsAttrs.count = String(field.sharedItems.length);
+                for (const item of field.sharedItems){
+                    sharedItemChildren.push(createElement('s', {
+                        v: item
+                    }, []));
+                }
+            } else if (field.isNumeric) {
+                // Numeric field - use "0"/"1" for boolean attributes as Excel expects
+                sharedItemsAttrs.containsSemiMixedTypes = '0';
+                sharedItemsAttrs.containsString = '0';
+                sharedItemsAttrs.containsNumber = '1';
+                // Check if all values are integers
+                if (field.minValue !== undefined && field.maxValue !== undefined) {
+                    const isInteger = Number.isInteger(field.minValue) && Number.isInteger(field.maxValue);
+                    if (isInteger) {
+                        sharedItemsAttrs.containsInteger = '1';
+                    }
+                    sharedItemsAttrs.minValue = String(field.minValue);
+                    sharedItemsAttrs.maxValue = String(field.maxValue);
+                }
+            }
+            const sharedItemsNode = createElement('sharedItems', sharedItemsAttrs, sharedItemChildren);
+            return createElement('cacheField', {
+                name: field.name,
+                numFmtId: '0'
+            }, [
+                sharedItemsNode
+            ]);
+        });
+        const cacheFieldsNode = createElement('cacheFields', {
+            count: String(this._fields.length)
+        }, cacheFieldNodes);
+        const worksheetSourceNode = createElement('worksheetSource', {
+            ref: this._sourceRange,
+            sheet: this._sourceSheet
+        }, []);
+        const cacheSourceNode = createElement('cacheSource', {
+            type: 'worksheet'
+        }, [
+            worksheetSourceNode
+        ]);
+        // Build attributes - refreshOnLoad should come early per OOXML schema
+        const definitionAttrs = {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+            'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+            'r:id': recordsRelId
+        };
+        // Add refreshOnLoad early in attributes (default is true)
+        if (this._refreshOnLoad) {
+            definitionAttrs.refreshOnLoad = '1';
+        }
+        // Continue with remaining attributes
+        definitionAttrs.refreshedBy = 'User';
+        definitionAttrs.refreshedVersion = '8';
+        definitionAttrs.minRefreshableVersion = '3';
+        definitionAttrs.createdVersion = '8';
+        definitionAttrs.recordCount = String(this._recordCount);
+        const definitionNode = createElement('pivotCacheDefinition', definitionAttrs, [
+            cacheSourceNode,
+            cacheFieldsNode
+        ]);
+        return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            definitionNode
+        ])}`;
+    }
+    /**
+   * Generate the pivotCacheRecords XML
+   */ toRecordsXml() {
+        const recordNodes = [];
+        for (const row of this._records){
+            const fieldNodes = [];
+            for(let colIdx = 0; colIdx < this._fields.length; colIdx++){
+                const field = this._fields[colIdx];
+                const value = colIdx < row.length ? row[colIdx] : null;
+                if (value === null || value === undefined) {
+                    // Missing value
+                    fieldNodes.push(createElement('m', {}, []));
+                } else if (typeof value === 'string') {
+                    // String value - use index into sharedItems
+                    const idx = field.sharedItems.indexOf(value);
+                    if (idx >= 0) {
+                        fieldNodes.push(createElement('x', {
+                            v: String(idx)
+                        }, []));
+                    } else {
+                        // Direct string value (shouldn't happen if cache is built correctly)
+                        fieldNodes.push(createElement('s', {
+                            v: value
+                        }, []));
+                    }
+                } else if (typeof value === 'number') {
+                    fieldNodes.push(createElement('n', {
+                        v: String(value)
+                    }, []));
+                } else if (typeof value === 'boolean') {
+                    fieldNodes.push(createElement('b', {
+                        v: value ? '1' : '0'
+                    }, []));
+                } else if (value instanceof Date) {
+                    fieldNodes.push(createElement('d', {
+                        v: value.toISOString()
+                    }, []));
+                } else {
+                    // Unknown type, treat as missing
+                    fieldNodes.push(createElement('m', {}, []));
+                }
+            }
+            recordNodes.push(createElement('r', {}, fieldNodes));
+        }
+        const recordsNode = createElement('pivotCacheRecords', {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+            'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+            count: String(this._recordCount)
+        }, recordNodes);
+        return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            recordsNode
+        ])}`;
+    }
+}
+
+/**
+ * Reads a ZIP file and returns a map of path -> content
+ * @param data - ZIP file as Uint8Array
+ * @returns Promise resolving to a map of file paths to contents
+ */ const readZip = (data)=>{
+    return new Promise((resolve, reject)=>{
+        unzip(data, (err, result)=>{
+            if (err) {
+                reject(err);
+                return;
+            }
+            const files = new Map();
+            for (const [path, content] of Object.entries(result)){
+                files.set(path, content);
+            }
+            resolve(files);
+        });
+    });
+};
+/**
+ * Creates a ZIP file from a map of path -> content
+ * @param files - Map of file paths to contents
+ * @returns Promise resolving to ZIP file as Uint8Array
+ */ const writeZip = (files)=>{
+    return new Promise((resolve, reject)=>{
+        const zipData = {};
+        for (const [path, content] of files){
+            zipData[path] = content;
+        }
+        zip(zipData, (err, result)=>{
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve(result);
+        });
+    });
+};
+/**
+ * Reads a file from the ZIP as a UTF-8 string
+ */ const readZipText = (files, path)=>{
+    const data = files.get(path);
+    if (!data) return undefined;
+    return strFromU8(data);
+};
+/**
+ * Writes a UTF-8 string to the ZIP files map
+ */ const writeZipText = (files, path, content)=>{
+    files.set(path, strToU8(content));
+};
+
+/**
+ * Represents an Excel workbook (.xlsx file)
+ */ class Workbook {
+    constructor(){
+        this._files = new Map();
+        this._sheets = new Map();
+        this._sheetDefs = [];
+        this._relationships = [];
+        this._dirty = false;
+        // Pivot table support
+        this._pivotTables = [];
+        this._pivotCaches = [];
+        this._nextCacheId = 0;
+        this._sharedStrings = new SharedStrings();
+        this._styles = Styles.createDefault();
+    }
+    /**
+   * Load a workbook from a file path
+   */ static async fromFile(path) {
+        const data = await readFile(path);
+        return Workbook.fromBuffer(new Uint8Array(data));
+    }
+    /**
+   * Load a workbook from a buffer
+   */ static async fromBuffer(data) {
+        const workbook = new Workbook();
+        workbook._files = await readZip(data);
+        // Parse workbook.xml for sheet definitions
+        const workbookXml = readZipText(workbook._files, 'xl/workbook.xml');
+        if (workbookXml) {
+            workbook._parseWorkbook(workbookXml);
+        }
+        // Parse relationships
+        const relsXml = readZipText(workbook._files, 'xl/_rels/workbook.xml.rels');
+        if (relsXml) {
+            workbook._parseRelationships(relsXml);
+        }
+        // Parse shared strings
+        const sharedStringsXml = readZipText(workbook._files, 'xl/sharedStrings.xml');
+        if (sharedStringsXml) {
+            workbook._sharedStrings = SharedStrings.parse(sharedStringsXml);
+        }
+        // Parse styles
+        const stylesXml = readZipText(workbook._files, 'xl/styles.xml');
+        if (stylesXml) {
+            workbook._styles = Styles.parse(stylesXml);
+        }
+        return workbook;
+    }
+    /**
+   * Create a new empty workbook
+   */ static create() {
+        const workbook = new Workbook();
+        workbook._dirty = true;
+        // Add default sheet
+        workbook.addSheet('Sheet1');
+        return workbook;
+    }
+    /**
+   * Get sheet names
+   */ get sheetNames() {
+        return this._sheetDefs.map((s)=>s.name);
+    }
+    /**
+   * Get number of sheets
+   */ get sheetCount() {
+        return this._sheetDefs.length;
+    }
+    /**
+   * Get shared strings table
+   */ get sharedStrings() {
+        return this._sharedStrings;
+    }
+    /**
+   * Get styles
+   */ get styles() {
+        return this._styles;
+    }
+    /**
+   * Get a worksheet by name or index
+   */ sheet(nameOrIndex) {
+        let def;
+        if (typeof nameOrIndex === 'number') {
+            def = this._sheetDefs[nameOrIndex];
+        } else {
+            def = this._sheetDefs.find((s)=>s.name === nameOrIndex);
+        }
+        if (!def) {
+            throw new Error(`Sheet not found: ${nameOrIndex}`);
+        }
+        // Return cached worksheet if available
+        if (this._sheets.has(def.name)) {
+            return this._sheets.get(def.name);
+        }
+        // Load worksheet
+        const worksheet = new Worksheet(this, def.name);
+        // Find the relationship to get the file path
+        const rel = this._relationships.find((r)=>r.id === def.rId);
+        if (rel) {
+            const sheetPath = `xl/${rel.target}`;
+            const sheetXml = readZipText(this._files, sheetPath);
+            if (sheetXml) {
+                worksheet.parse(sheetXml);
+            }
+        }
+        this._sheets.set(def.name, worksheet);
+        return worksheet;
+    }
+    /**
+   * Add a new worksheet
+   */ addSheet(name, index) {
+        // Check for duplicate name
+        if (this._sheetDefs.some((s)=>s.name === name)) {
+            throw new Error(`Sheet already exists: ${name}`);
+        }
+        this._dirty = true;
+        // Generate new sheet ID and relationship ID
+        const sheetId = Math.max(0, ...this._sheetDefs.map((s)=>s.sheetId)) + 1;
+        const rId = `rId${Math.max(0, ...this._relationships.map((r)=>parseInt(r.id.replace('rId', ''), 10) || 0)) + 1}`;
+        const def = {
+            name,
+            sheetId,
+            rId
+        };
+        // Add relationship
+        this._relationships.push({
+            id: rId,
+            type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet',
+            target: `worksheets/sheet${sheetId}.xml`
+        });
+        // Insert at index or append
+        if (index !== undefined && index >= 0 && index < this._sheetDefs.length) {
+            this._sheetDefs.splice(index, 0, def);
+        } else {
+            this._sheetDefs.push(def);
+        }
+        // Create worksheet
+        const worksheet = new Worksheet(this, name);
+        this._sheets.set(name, worksheet);
+        return worksheet;
+    }
+    /**
+   * Delete a worksheet by name or index
+   */ deleteSheet(nameOrIndex) {
+        let index;
+        if (typeof nameOrIndex === 'number') {
+            index = nameOrIndex;
+        } else {
+            index = this._sheetDefs.findIndex((s)=>s.name === nameOrIndex);
+        }
+        if (index < 0 || index >= this._sheetDefs.length) {
+            throw new Error(`Sheet not found: ${nameOrIndex}`);
+        }
+        if (this._sheetDefs.length === 1) {
+            throw new Error('Cannot delete the last sheet');
+        }
+        this._dirty = true;
+        const def = this._sheetDefs[index];
+        this._sheetDefs.splice(index, 1);
+        this._sheets.delete(def.name);
+        // Remove relationship
+        const relIndex = this._relationships.findIndex((r)=>r.id === def.rId);
+        if (relIndex >= 0) {
+            this._relationships.splice(relIndex, 1);
+        }
+    }
+    /**
+   * Rename a worksheet
+   */ renameSheet(oldName, newName) {
+        const def = this._sheetDefs.find((s)=>s.name === oldName);
+        if (!def) {
+            throw new Error(`Sheet not found: ${oldName}`);
+        }
+        if (this._sheetDefs.some((s)=>s.name === newName)) {
+            throw new Error(`Sheet already exists: ${newName}`);
+        }
+        this._dirty = true;
+        // Update cached worksheet
+        const worksheet = this._sheets.get(oldName);
+        if (worksheet) {
+            worksheet.name = newName;
+            this._sheets.delete(oldName);
+            this._sheets.set(newName, worksheet);
+        }
+        def.name = newName;
+    }
+    /**
+   * Copy a worksheet
+   */ copySheet(sourceName, newName) {
+        const source = this.sheet(sourceName);
+        const copy = this.addSheet(newName);
+        // Copy all cells
+        for (const [address, cell] of source.cells){
+            const newCell = copy.cell(address);
+            newCell.value = cell.value;
+            if (cell.formula) {
+                newCell.formula = cell.formula;
+            }
+            if (cell.styleIndex !== undefined) {
+                newCell.styleIndex = cell.styleIndex;
+            }
+        }
+        // Copy merged cells
+        for (const mergedRange of source.mergedCells){
+            copy.mergeCells(mergedRange);
+        }
+        return copy;
+    }
+    /**
+   * Create a pivot table from source data.
+   *
+   * @param config - Pivot table configuration
+   * @returns PivotTable instance for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * const pivot = wb.createPivotTable({
+   *   name: 'SalesPivot',
+   *   source: 'DataSheet!A1:D100',
+   *   target: 'PivotSheet!A3',
+   * });
+   *
+   * pivot
+   *   .addRowField('Region')
+   *   .addColumnField('Product')
+   *   .addValueField('Sales', 'sum', 'Total Sales');
+   * ```
+   */ createPivotTable(config) {
+        this._dirty = true;
+        // Parse source reference (Sheet!Range)
+        const { sheetName: sourceSheet, range: sourceRange } = this._parseSheetRef(config.source);
+        // Parse target reference
+        const { sheetName: targetSheet, range: targetCell } = this._parseSheetRef(config.target);
+        // Ensure target sheet exists
+        if (!this._sheetDefs.some((s)=>s.name === targetSheet)) {
+            this.addSheet(targetSheet);
+        }
+        // Parse target cell address
+        const targetAddr = parseAddress(targetCell);
+        // Get source worksheet and extract data
+        const sourceWs = this.sheet(sourceSheet);
+        const { headers, data } = this._extractSourceData(sourceWs, sourceRange);
+        // Create pivot cache
+        const cacheId = this._nextCacheId++;
+        const cache = new PivotCache(cacheId, sourceSheet, sourceRange);
+        cache.buildFromData(headers, data);
+        // refreshOnLoad defaults to true; only disable if explicitly set to false
+        if (config.refreshOnLoad === false) {
+            cache.refreshOnLoad = false;
+        }
+        this._pivotCaches.push(cache);
+        // Create pivot table
+        const pivotTableIndex = this._pivotTables.length + 1;
+        const pivotTable = new PivotTable(config.name, cache, targetSheet, targetCell, targetAddr.row + 1, targetAddr.col, pivotTableIndex);
+        this._pivotTables.push(pivotTable);
+        return pivotTable;
+    }
+    /**
+   * Parse a sheet reference like "Sheet1!A1:D100" into sheet name and range
+   */ _parseSheetRef(ref) {
+        const match = ref.match(/^(.+?)!(.+)$/);
+        if (!match) {
+            throw new Error(`Invalid reference format: ${ref}. Expected "SheetName!Range"`);
+        }
+        return {
+            sheetName: match[1],
+            range: match[2]
+        };
+    }
+    /**
+   * Extract headers and data from a source range
+   */ _extractSourceData(sheet, rangeStr) {
+        const range = parseRange(rangeStr);
+        const headers = [];
+        const data = [];
+        // First row is headers
+        for(let col = range.start.col; col <= range.end.col; col++){
+            const cell = sheet.cell(toAddress(range.start.row, col));
+            headers.push(String(cell.value ?? `Column${col + 1}`));
+        }
+        // Remaining rows are data
+        for(let row = range.start.row + 1; row <= range.end.row; row++){
+            const rowData = [];
+            for(let col = range.start.col; col <= range.end.col; col++){
+                const cell = sheet.cell(toAddress(row, col));
+                rowData.push(cell.value);
+            }
+            data.push(rowData);
+        }
+        return {
+            headers,
+            data
+        };
+    }
+    /**
+   * Save the workbook to a file
+   */ async toFile(path) {
+        const buffer = await this.toBuffer();
+        await writeFile(path, buffer);
+    }
+    /**
+   * Save the workbook to a buffer
+   */ async toBuffer() {
+        // Update files map with modified content
+        this._updateFiles();
+        // Write ZIP
+        return writeZip(this._files);
+    }
+    _parseWorkbook(xml) {
+        const parsed = parseXml(xml);
+        const workbook = findElement(parsed, 'workbook');
+        if (!workbook) return;
+        const children = getChildren(workbook, 'workbook');
+        const sheets = findElement(children, 'sheets');
+        if (!sheets) return;
+        for (const child of getChildren(sheets, 'sheets')){
+            if ('sheet' in child) {
+                const name = getAttr(child, 'name');
+                const sheetId = getAttr(child, 'sheetId');
+                const rId = getAttr(child, 'r:id');
+                if (name && sheetId && rId) {
+                    this._sheetDefs.push({
+                        name,
+                        sheetId: parseInt(sheetId, 10),
+                        rId
+                    });
+                }
+            }
+        }
+    }
+    _parseRelationships(xml) {
+        const parsed = parseXml(xml);
+        const rels = findElement(parsed, 'Relationships');
+        if (!rels) return;
+        for (const child of getChildren(rels, 'Relationships')){
+            if ('Relationship' in child) {
+                const id = getAttr(child, 'Id');
+                const type = getAttr(child, 'Type');
+                const target = getAttr(child, 'Target');
+                if (id && type && target) {
+                    this._relationships.push({
+                        id,
+                        type,
+                        target
+                    });
+                }
+            }
+        }
+    }
+    _updateFiles() {
+        // Update workbook.xml
+        this._updateWorkbookXml();
+        // Update relationships
+        this._updateRelationshipsXml();
+        // Update content types
+        this._updateContentTypes();
+        // Update shared strings if modified
+        if (this._sharedStrings.dirty || this._sharedStrings.count > 0) {
+            writeZipText(this._files, 'xl/sharedStrings.xml', this._sharedStrings.toXml());
+        }
+        // Update styles if modified or if file doesn't exist yet
+        if (this._styles.dirty || this._dirty || !this._files.has('xl/styles.xml')) {
+            writeZipText(this._files, 'xl/styles.xml', this._styles.toXml());
+        }
+        // Update worksheets
+        for (const [name, worksheet] of this._sheets){
+            if (worksheet.dirty || this._dirty) {
+                const def = this._sheetDefs.find((s)=>s.name === name);
+                if (def) {
+                    const rel = this._relationships.find((r)=>r.id === def.rId);
+                    if (rel) {
+                        const sheetPath = `xl/${rel.target}`;
+                        writeZipText(this._files, sheetPath, worksheet.toXml());
+                    }
+                }
+            }
+        }
+        // Update pivot tables
+        if (this._pivotTables.length > 0) {
+            this._updatePivotTableFiles();
+        }
+    }
+    _updateWorkbookXml() {
+        const sheetNodes = this._sheetDefs.map((def)=>createElement('sheet', {
+                name: def.name,
+                sheetId: String(def.sheetId),
+                'r:id': def.rId
+            }, []));
+        const sheetsNode = createElement('sheets', {}, sheetNodes);
+        const children = [
+            sheetsNode
+        ];
+        // Add pivot caches if any
+        if (this._pivotCaches.length > 0) {
+            const pivotCacheNodes = this._pivotCaches.map((cache, idx)=>{
+                // Cache relationship ID is after sheets, sharedStrings, and styles
+                const cacheRelId = `rId${this._relationships.length + 3 + idx}`;
+                return createElement('pivotCache', {
+                    cacheId: String(cache.cacheId),
+                    'r:id': cacheRelId
+                }, []);
+            });
+            children.push(createElement('pivotCaches', {}, pivotCacheNodes));
+        }
+        const workbookNode = createElement('workbook', {
+            xmlns: 'http://schemas.openxmlformats.org/spreadsheetml/2006/main',
+            'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+        }, children);
+        const xml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            workbookNode
+        ])}`;
+        writeZipText(this._files, 'xl/workbook.xml', xml);
+    }
+    _updateRelationshipsXml() {
+        const relNodes = this._relationships.map((rel)=>createElement('Relationship', {
+                Id: rel.id,
+                Type: rel.type,
+                Target: rel.target
+            }, []));
+        let nextRelId = this._relationships.length + 1;
+        // Add shared strings relationship if needed
+        if (this._sharedStrings.count > 0) {
+            const hasSharedStrings = this._relationships.some((r)=>r.type === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings');
+            if (!hasSharedStrings) {
+                relNodes.push(createElement('Relationship', {
+                    Id: `rId${nextRelId++}`,
+                    Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings',
+                    Target: 'sharedStrings.xml'
+                }, []));
+            }
+        }
+        // Add styles relationship if needed
+        const hasStyles = this._relationships.some((r)=>r.type === 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles');
+        if (!hasStyles) {
+            relNodes.push(createElement('Relationship', {
+                Id: `rId${nextRelId++}`,
+                Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles',
+                Target: 'styles.xml'
+            }, []));
+        }
+        // Add pivot cache relationships
+        for(let i = 0; i < this._pivotCaches.length; i++){
+            relNodes.push(createElement('Relationship', {
+                Id: `rId${nextRelId++}`,
+                Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition',
+                Target: `pivotCache/pivotCacheDefinition${i + 1}.xml`
+            }, []));
+        }
+        const relsNode = createElement('Relationships', {
+            xmlns: 'http://schemas.openxmlformats.org/package/2006/relationships'
+        }, relNodes);
+        const xml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            relsNode
+        ])}`;
+        writeZipText(this._files, 'xl/_rels/workbook.xml.rels', xml);
+    }
+    _updateContentTypes() {
+        const types = [
+            createElement('Default', {
+                Extension: 'rels',
+                ContentType: 'application/vnd.openxmlformats-package.relationships+xml'
+            }, []),
+            createElement('Default', {
+                Extension: 'xml',
+                ContentType: 'application/xml'
+            }, []),
+            createElement('Override', {
+                PartName: '/xl/workbook.xml',
+                ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml'
+            }, []),
+            createElement('Override', {
+                PartName: '/xl/styles.xml',
+                ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml'
+            }, [])
+        ];
+        // Add shared strings if present
+        if (this._sharedStrings.count > 0) {
+            types.push(createElement('Override', {
+                PartName: '/xl/sharedStrings.xml',
+                ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml'
+            }, []));
+        }
+        // Add worksheets
+        for (const def of this._sheetDefs){
+            const rel = this._relationships.find((r)=>r.id === def.rId);
+            if (rel) {
+                types.push(createElement('Override', {
+                    PartName: `/xl/${rel.target}`,
+                    ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml'
+                }, []));
+            }
+        }
+        // Add pivot cache definitions and records
+        for(let i = 0; i < this._pivotCaches.length; i++){
+            types.push(createElement('Override', {
+                PartName: `/xl/pivotCache/pivotCacheDefinition${i + 1}.xml`,
+                ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml'
+            }, []));
+            types.push(createElement('Override', {
+                PartName: `/xl/pivotCache/pivotCacheRecords${i + 1}.xml`,
+                ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml'
+            }, []));
+        }
+        // Add pivot tables
+        for(let i = 0; i < this._pivotTables.length; i++){
+            types.push(createElement('Override', {
+                PartName: `/xl/pivotTables/pivotTable${i + 1}.xml`,
+                ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml'
+            }, []));
+        }
+        const typesNode = createElement('Types', {
+            xmlns: 'http://schemas.openxmlformats.org/package/2006/content-types'
+        }, types);
+        const xml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+            typesNode
+        ])}`;
+        writeZipText(this._files, '[Content_Types].xml', xml);
+        // Also ensure _rels/.rels exists
+        const rootRelsXml = readZipText(this._files, '_rels/.rels');
+        if (!rootRelsXml) {
+            const rootRels = createElement('Relationships', {
+                xmlns: 'http://schemas.openxmlformats.org/package/2006/relationships'
+            }, [
+                createElement('Relationship', {
+                    Id: 'rId1',
+                    Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument',
+                    Target: 'xl/workbook.xml'
+                }, [])
+            ]);
+            writeZipText(this._files, '_rels/.rels', `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+                rootRels
+            ])}`);
+        }
+    }
+    /**
+   * Generate all pivot table related files
+   */ _updatePivotTableFiles() {
+        // Track which sheets have pivot tables for their .rels files
+        const sheetPivotTables = new Map();
+        for (const pivotTable of this._pivotTables){
+            const sheetName = pivotTable.targetSheet;
+            if (!sheetPivotTables.has(sheetName)) {
+                sheetPivotTables.set(sheetName, []);
+            }
+            sheetPivotTables.get(sheetName).push(pivotTable);
+        }
+        // Generate pivot cache files
+        for(let i = 0; i < this._pivotCaches.length; i++){
+            const cache = this._pivotCaches[i];
+            const cacheIdx = i + 1;
+            // Pivot cache definition
+            const definitionPath = `xl/pivotCache/pivotCacheDefinition${cacheIdx}.xml`;
+            writeZipText(this._files, definitionPath, cache.toDefinitionXml('rId1'));
+            // Pivot cache records
+            const recordsPath = `xl/pivotCache/pivotCacheRecords${cacheIdx}.xml`;
+            writeZipText(this._files, recordsPath, cache.toRecordsXml());
+            // Pivot cache definition relationships (link to records)
+            const cacheRelsPath = `xl/pivotCache/_rels/pivotCacheDefinition${cacheIdx}.xml.rels`;
+            const cacheRels = createElement('Relationships', {
+                xmlns: 'http://schemas.openxmlformats.org/package/2006/relationships'
+            }, [
+                createElement('Relationship', {
+                    Id: 'rId1',
+                    Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheRecords',
+                    Target: `pivotCacheRecords${cacheIdx}.xml`
+                }, [])
+            ]);
+            writeZipText(this._files, cacheRelsPath, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+                cacheRels
+            ])}`);
+        }
+        // Generate pivot table files
+        for(let i = 0; i < this._pivotTables.length; i++){
+            const pivotTable = this._pivotTables[i];
+            const ptIdx = i + 1;
+            // Pivot table definition
+            const ptPath = `xl/pivotTables/pivotTable${ptIdx}.xml`;
+            writeZipText(this._files, ptPath, pivotTable.toXml());
+            // Pivot table relationships (link to cache definition)
+            const cacheIdx = this._pivotCaches.indexOf(pivotTable.cache) + 1;
+            const ptRelsPath = `xl/pivotTables/_rels/pivotTable${ptIdx}.xml.rels`;
+            const ptRels = createElement('Relationships', {
+                xmlns: 'http://schemas.openxmlformats.org/package/2006/relationships'
+            }, [
+                createElement('Relationship', {
+                    Id: 'rId1',
+                    Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition',
+                    Target: `../pivotCache/pivotCacheDefinition${cacheIdx}.xml`
+                }, [])
+            ]);
+            writeZipText(this._files, ptRelsPath, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+                ptRels
+            ])}`);
+        }
+        // Generate worksheet relationships for pivot tables
+        for (const [sheetName, pivotTables] of sheetPivotTables){
+            const def = this._sheetDefs.find((s)=>s.name === sheetName);
+            if (!def) continue;
+            const rel = this._relationships.find((r)=>r.id === def.rId);
+            if (!rel) continue;
+            // Extract sheet file name from target path
+            const sheetFileName = rel.target.split('/').pop();
+            const sheetRelsPath = `xl/worksheets/_rels/${sheetFileName}.rels`;
+            const relNodes = [];
+            for(let i = 0; i < pivotTables.length; i++){
+                const pt = pivotTables[i];
+                relNodes.push(createElement('Relationship', {
+                    Id: `rId${i + 1}`,
+                    Type: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable',
+                    Target: `../pivotTables/pivotTable${pt.index}.xml`
+                }, []));
+            }
+            const sheetRels = createElement('Relationships', {
+                xmlns: 'http://schemas.openxmlformats.org/package/2006/relationships'
+            }, relNodes);
+            writeZipText(this._files, sheetRelsPath, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${stringifyXml([
+                sheetRels
+            ])}`);
+        }
+    }
+}
+
+export { Cell, PivotCache, PivotTable, Range, SharedStrings, Styles, Workbook, Worksheet, parseAddress, parseRange, toAddress, toRange };