@niicojs/excel 0.2.2 → 0.2.4

package/dist/index.js

@@ -38,8 +38,10 @@ import { unzip, strFromU8, zip, strToU8 } from 'fflate';
     if (!match) {
         throw new Error(`Invalid cell address: ${address}`);
     }
+    const rowNumber = +match[2];
+    if (rowNumber <= 0) throw new Error(`Invalid cell address: ${address}`);
     const col = letterToCol(match[1].toUpperCase());
-    const row = parseInt(match[2], 10) - 1; // Convert to 0-based
+    const row = rowNumber - 1; // Convert to 0-based
     return {
         row,
         col
@@ -101,6 +103,12 @@ import { unzip, strFromU8, zip, strToU8 } from 'fflate';
         }
     };
 };
+/**
+ * Checks if an address is within a range
+ */ const isInRange = (addr, range)=>{
+    const norm = normalizeRange(range);
+    return addr.row >= norm.start.row && addr.row <= norm.end.row && addr.col >= norm.start.col && addr.col <= norm.end.col;
+};
 
 // Excel epoch: December 30, 1899 (accounting for the 1900 leap year bug)
 const EXCEL_EPOCH = new Date(Date.UTC(1899, 11, 30));
@@ -433,12 +441,23 @@ _computedKey = Symbol.iterator;
     /**
    * Get all values in the range as a 2D array
    */ get values() {
+        return this.getValues();
+    }
+    /**
+   * Get all values in the range as a 2D array with options
+   */ getValues(options = {}) {
+        const { createMissing = true } = options;
         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);
+                if (createMissing) {
+                    const cell = this._worksheet.cell(r, c);
+                    row.push(cell.value);
+                } else {
+                    const cell = this._worksheet.getCellIfExists(r, c);
+                    row.push(cell?.value ?? null);
+                }
             }
             result.push(row);
         }
@@ -611,6 +630,11 @@ const builder = new XMLBuilder(builderOptions);
         this._dirty = false;
         this._mergedCells = new Set();
         this._sheetData = [];
+        this._columnWidths = new Map();
+        this._rowHeights = new Map();
+        this._frozenPane = null;
+        this._dataBoundsCache = null;
+        this._boundsDirty = true;
         this._workbook = workbook;
         this._name = name;
     }
@@ -637,12 +661,49 @@ const builder = new XMLBuilder(builderOptions);
         const worksheet = findElement(this._xmlNodes, 'worksheet');
         if (!worksheet) return;
         const worksheetChildren = getChildren(worksheet, 'worksheet');
+        // Parse sheet views (freeze panes)
+        const sheetViews = findElement(worksheetChildren, 'sheetViews');
+        if (sheetViews) {
+            const viewChildren = getChildren(sheetViews, 'sheetViews');
+            const sheetView = findElement(viewChildren, 'sheetView');
+            if (sheetView) {
+                const sheetViewChildren = getChildren(sheetView, 'sheetView');
+                const pane = findElement(sheetViewChildren, 'pane');
+                if (pane && getAttr(pane, 'state') === 'frozen') {
+                    const xSplit = parseInt(getAttr(pane, 'xSplit') || '0', 10);
+                    const ySplit = parseInt(getAttr(pane, 'ySplit') || '0', 10);
+                    if (xSplit > 0 || ySplit > 0) {
+                        this._frozenPane = {
+                            row: ySplit,
+                            col: xSplit
+                        };
+                    }
+                }
+            }
+        }
         // Parse sheet data (cells)
         const sheetData = findElement(worksheetChildren, 'sheetData');
         if (sheetData) {
             this._sheetData = getChildren(sheetData, 'sheetData');
             this._parseSheetData(this._sheetData);
         }
+        // Parse column widths
+        const cols = findElement(worksheetChildren, 'cols');
+        if (cols) {
+            const colChildren = getChildren(cols, 'cols');
+            for (const col of colChildren){
+                if (!('col' in col)) continue;
+                const min = parseInt(getAttr(col, 'min') || '0', 10);
+                const max = parseInt(getAttr(col, 'max') || '0', 10);
+                const width = parseFloat(getAttr(col, 'width') || '0');
+                if (!Number.isFinite(width) || width <= 0) continue;
+                if (min > 0 && max > 0) {
+                    for(let idx = min; idx <= max; idx++){
+                        this._columnWidths.set(idx - 1, width);
+                    }
+                }
+            }
+        }
         // Parse merged cells
         const mergeCells = findElement(worksheetChildren, 'mergeCells');
         if (mergeCells) {
@@ -662,6 +723,11 @@ const builder = new XMLBuilder(builderOptions);
    */ _parseSheetData(rows) {
         for (const rowNode of rows){
             if (!('row' in rowNode)) continue;
+            const rowIndex = parseInt(getAttr(rowNode, 'r') || '0', 10) - 1;
+            const rowHeight = parseFloat(getAttr(rowNode, 'ht') || '0');
+            if (rowIndex >= 0 && Number.isFinite(rowHeight) && rowHeight > 0) {
+                this._rowHeights.set(rowIndex, rowHeight);
+            }
             const rowChildren = getChildren(rowNode, 'row');
             for (const cellNode of rowChildren){
                 if (!('c' in cellNode)) continue;
@@ -673,6 +739,7 @@ const builder = new XMLBuilder(builderOptions);
                 this._cells.set(ref, cell);
             }
         }
+        this._boundsDirty = true;
     }
     /**
    * Parse a cell XML node to CellData
@@ -759,9 +826,17 @@ const builder = new XMLBuilder(builderOptions);
         if (!cell) {
             cell = new Cell(this, row, c);
             this._cells.set(address, cell);
+            this._boundsDirty = true;
         }
         return cell;
     }
+    /**
+   * Get an existing cell without creating it.
+   */ getCellIfExists(rowOrAddress, col) {
+        const { row, col: c } = parseCellRef(rowOrAddress, col);
+        const address = toAddress(row, c);
+        return this._cells.get(address);
+    }
     range(startRowOrRange, startCol, endRow, endCol) {
         let rangeAddr;
         if (typeof startRowOrRange === 'string') {
@@ -821,6 +896,182 @@ const builder = new XMLBuilder(builderOptions);
         return this._cells;
     }
     /**
+   * Set a column width (0-based index or column letter)
+   */ setColumnWidth(col, width) {
+        if (!Number.isFinite(width) || width <= 0) {
+            throw new Error('Column width must be a positive number');
+        }
+        const colIndex = typeof col === 'number' ? col : letterToCol(col);
+        if (colIndex < 0) {
+            throw new Error(`Invalid column: ${col}`);
+        }
+        this._columnWidths.set(colIndex, width);
+        this._dirty = true;
+    }
+    /**
+   * Get a column width if set
+   */ getColumnWidth(col) {
+        const colIndex = typeof col === 'number' ? col : letterToCol(col);
+        return this._columnWidths.get(colIndex);
+    }
+    /**
+   * Set a row height (0-based index)
+   */ setRowHeight(row, height) {
+        if (!Number.isFinite(height) || height <= 0) {
+            throw new Error('Row height must be a positive number');
+        }
+        if (row < 0) {
+            throw new Error('Row index must be >= 0');
+        }
+        this._rowHeights.set(row, height);
+        this._dirty = true;
+    }
+    /**
+   * Get a row height if set
+   */ getRowHeight(row) {
+        return this._rowHeights.get(row);
+    }
+    /**
+   * Freeze panes at a given row/column split (counts from top-left)
+   */ freezePane(rowSplit, colSplit) {
+        if (rowSplit < 0 || colSplit < 0) {
+            throw new Error('Freeze pane splits must be >= 0');
+        }
+        if (rowSplit === 0 && colSplit === 0) {
+            this._frozenPane = null;
+        } else {
+            this._frozenPane = {
+                row: rowSplit,
+                col: colSplit
+            };
+        }
+        this._dirty = true;
+    }
+    /**
+   * Get current frozen pane configuration
+   */ getFrozenPane() {
+        return this._frozenPane ? {
+            ...this._frozenPane
+        } : null;
+    }
+    /**
+   * Convert sheet data to an array of JSON objects.
+   *
+   * @param config - Configuration options
+   * @returns Array of objects where keys are field names and values are cell values
+   *
+   * @example
+   * ```typescript
+   * // Using first row as headers
+   * const data = sheet.toJson();
+   *
+   * // Using custom field names
+   * const data = sheet.toJson({ fields: ['name', 'age', 'city'] });
+   *
+   * // Starting from a specific row/column
+   * const data = sheet.toJson({ startRow: 2, startCol: 1 });
+   * ```
+   */ toJson(config = {}) {
+        const { fields, startRow = 0, startCol = 0, endRow, endCol, stopOnEmptyRow = true, dateHandling = this._workbook.dateHandling } = config;
+        // Get the bounds of data in the sheet
+        const bounds = this._getDataBounds();
+        if (!bounds) {
+            return [];
+        }
+        const effectiveEndRow = endRow ?? bounds.maxRow;
+        const effectiveEndCol = endCol ?? bounds.maxCol;
+        // Determine field names
+        let fieldNames;
+        let dataStartRow;
+        if (fields) {
+            // Use provided field names, data starts at startRow
+            fieldNames = fields;
+            dataStartRow = startRow;
+        } else {
+            // Use first row as headers
+            fieldNames = [];
+            for(let col = startCol; col <= effectiveEndCol; col++){
+                const cell = this._cells.get(toAddress(startRow, col));
+                const value = cell?.value;
+                fieldNames.push(value != null ? String(value) : `column${col}`);
+            }
+            dataStartRow = startRow + 1;
+        }
+        // Read data rows
+        const result = [];
+        for(let row = dataStartRow; row <= effectiveEndRow; row++){
+            const obj = {};
+            let hasData = false;
+            for(let colOffset = 0; colOffset < fieldNames.length; colOffset++){
+                const col = startCol + colOffset;
+                const cell = this._cells.get(toAddress(row, col));
+                let value = cell?.value ?? null;
+                if (value instanceof Date) {
+                    value = this._serializeDate(value, dateHandling, cell);
+                }
+                if (value !== null) {
+                    hasData = true;
+                }
+                const fieldName = fieldNames[colOffset];
+                if (fieldName) {
+                    obj[fieldName] = value;
+                }
+            }
+            // Stop on empty row if configured
+            if (stopOnEmptyRow && !hasData) {
+                break;
+            }
+            result.push(obj);
+        }
+        return result;
+    }
+    _serializeDate(value, dateHandling, cell) {
+        if (dateHandling === 'excelSerial') {
+            return cell?._jsDateToExcel(value) ?? value;
+        }
+        if (dateHandling === 'isoString') {
+            return value.toISOString();
+        }
+        return value;
+    }
+    /**
+   * Get the bounds of data in the sheet (min/max row and column with data)
+   */ _getDataBounds() {
+        if (!this._boundsDirty && this._dataBoundsCache) {
+            return this._dataBoundsCache;
+        }
+        if (this._cells.size === 0) {
+            this._dataBoundsCache = null;
+            this._boundsDirty = false;
+            return null;
+        }
+        let minRow = Infinity;
+        let maxRow = -Infinity;
+        let minCol = Infinity;
+        let maxCol = -Infinity;
+        for (const cell of this._cells.values()){
+            if (cell.value !== null) {
+                minRow = Math.min(minRow, cell.row);
+                maxRow = Math.max(maxRow, cell.row);
+                minCol = Math.min(minCol, cell.col);
+                maxCol = Math.max(maxCol, cell.col);
+            }
+        }
+        if (minRow === Infinity) {
+            this._dataBoundsCache = null;
+            this._boundsDirty = false;
+            return null;
+        }
+        this._dataBoundsCache = {
+            minRow,
+            maxRow,
+            minCol,
+            maxCol
+        };
+        this._boundsDirty = false;
+        return this._dataBoundsCache;
+    }
+    /**
    * Generate XML for this worksheet
    */ toXml() {
         // Build sheetData from cells
@@ -832,6 +1083,11 @@ const builder = new XMLBuilder(builderOptions);
             }
             rowMap.get(row).push(cell);
         }
+        for (const rowIdx of this._rowHeights.keys()){
+            if (!rowMap.has(rowIdx)) {
+                rowMap.set(rowIdx, []);
+            }
+        }
         // Sort rows and cells
         const sortedRows = Array.from(rowMap.entries()).sort((a, b)=>a[0] - b[0]);
         const rowNodes = [];
@@ -842,16 +1098,71 @@ const builder = new XMLBuilder(builderOptions);
                 const cellNode = this._buildCellNode(cell);
                 cellNodes.push(cellNode);
             }
-            const rowNode = createElement('row', {
+            const rowAttrs = {
                 r: String(rowIdx + 1)
-            }, cellNodes);
+            };
+            const rowHeight = this._rowHeights.get(rowIdx);
+            if (rowHeight !== undefined) {
+                rowAttrs.ht = String(rowHeight);
+                rowAttrs.customHeight = '1';
+            }
+            const rowNode = createElement('row', rowAttrs, cellNodes);
             rowNodes.push(rowNode);
         }
         const sheetDataNode = createElement('sheetData', {}, rowNodes);
         // Build worksheet structure
-        const worksheetChildren = [
-            sheetDataNode
-        ];
+        const worksheetChildren = [];
+        // Sheet views (freeze panes)
+        if (this._frozenPane) {
+            const paneAttrs = {
+                state: 'frozen'
+            };
+            const topLeftCell = toAddress(this._frozenPane.row, this._frozenPane.col);
+            paneAttrs.topLeftCell = topLeftCell;
+            if (this._frozenPane.col > 0) {
+                paneAttrs.xSplit = String(this._frozenPane.col);
+            }
+            if (this._frozenPane.row > 0) {
+                paneAttrs.ySplit = String(this._frozenPane.row);
+            }
+            let activePane = 'bottomRight';
+            if (this._frozenPane.row > 0 && this._frozenPane.col === 0) {
+                activePane = 'bottomLeft';
+            } else if (this._frozenPane.row === 0 && this._frozenPane.col > 0) {
+                activePane = 'topRight';
+            }
+            paneAttrs.activePane = activePane;
+            const paneNode = createElement('pane', paneAttrs, []);
+            const selectionNode = createElement('selection', {
+                pane: activePane,
+                activeCell: topLeftCell,
+                sqref: topLeftCell
+            }, []);
+            const sheetViewNode = createElement('sheetView', {
+                workbookViewId: '0'
+            }, [
+                paneNode,
+                selectionNode
+            ]);
+            worksheetChildren.push(createElement('sheetViews', {}, [
+                sheetViewNode
+            ]));
+        }
+        // Column widths
+        if (this._columnWidths.size > 0) {
+            const colNodes = [];
+            const entries = Array.from(this._columnWidths.entries()).sort((a, b)=>a[0] - b[0]);
+            for (const [colIndex, width] of entries){
+                colNodes.push(createElement('col', {
+                    min: String(colIndex + 1),
+                    max: String(colIndex + 1),
+                    width: String(width),
+                    customWidth: '1'
+                }, []));
+            }
+            worksheetChildren.push(createElement('cols', {}, colNodes));
+        }
+        worksheetChildren.push(sheetDataNode);
         // Add merged cells if any
         if (this._mergedCells.size > 0) {
             const mergeCellNodes = [];
@@ -1038,6 +1349,40 @@ const builder = new XMLBuilder(builderOptions);
  * Manages the styles (xl/styles.xml)
  */ class Styles {
     /**
+   * Generate a deterministic cache key for a style object.
+   * More efficient than JSON.stringify as it avoids the overhead of
+   * full JSON serialization and produces a consistent key regardless
+   * of property order.
+   */ _getStyleKey(style) {
+        // Use a delimiter that won't appear in values
+        const SEP = '\x00';
+        // Build key from all style properties in a fixed order
+        const parts = [
+            style.bold ? '1' : '0',
+            style.italic ? '1' : '0',
+            style.underline === true ? '1' : style.underline === 'single' ? 's' : style.underline === 'double' ? 'd' : '0',
+            style.strike ? '1' : '0',
+            style.fontSize?.toString() ?? '',
+            style.fontName ?? '',
+            style.fontColor ?? '',
+            style.fill ?? '',
+            style.numberFormat ?? ''
+        ];
+        // Border properties
+        if (style.border) {
+            parts.push(style.border.top ?? '', style.border.bottom ?? '', style.border.left ?? '', style.border.right ?? '');
+        } else {
+            parts.push('', '', '', '');
+        }
+        // Alignment properties
+        if (style.alignment) {
+            parts.push(style.alignment.horizontal ?? '', style.alignment.vertical ?? '', style.alignment.wrapText ? '1' : '0', style.alignment.textRotation?.toString() ?? '');
+        } else {
+            parts.push('', '', '0', '');
+        }
+        return parts.join(SEP);
+    }
+    /**
    * Parse styles from XML content
    */ static parse(xml) {
         const styles = new Styles();
@@ -1204,6 +1549,10 @@ const builder = new XMLBuilder(builderOptions);
     /**
    * Get a style by index
    */ getStyle(index) {
+        const cached = this._styleObjectCache.get(index);
+        if (cached) return {
+            ...cached
+        };
         const xf = this._cellXfs[index];
         if (!xf) return {};
         const font = this._fonts[xf.fontId];
@@ -1244,13 +1593,16 @@ const builder = new XMLBuilder(builderOptions);
                 textRotation: xf.alignment.textRotation
             };
         }
+        this._styleObjectCache.set(index, {
+            ...style
+        });
         return style;
     }
     /**
    * Create a style and return its index
    * Uses caching to deduplicate identical styles
    */ createStyle(style) {
-        const key = JSON.stringify(style);
+        const key = this._getStyleKey(style);
         const cached = this._styleCache.get(key);
         if (cached !== undefined) {
             return cached;
@@ -1282,8 +1634,20 @@ const builder = new XMLBuilder(builderOptions);
         const index = this._cellXfs.length;
         this._cellXfs.push(xf);
         this._styleCache.set(key, index);
+        this._styleObjectCache.set(index, {
+            ...style
+        });
         return index;
     }
+    /**
+   * Clone an existing style by index, optionally overriding fields.
+   */ cloneStyle(index, overrides = {}) {
+        const baseStyle = this.getStyle(index);
+        return this.createStyle({
+            ...baseStyle,
+            ...overrides
+        });
+    }
     _findOrCreateFont(style) {
         const font = {
             bold: style.bold || false,
@@ -1519,6 +1883,7 @@ const builder = new XMLBuilder(builderOptions);
         this._dirty = false;
         // Cache for style deduplication
         this._styleCache = new Map();
+        this._styleObjectCache = new Map();
     }
 }
 
@@ -1530,6 +1895,7 @@ const builder = new XMLBuilder(builderOptions);
         this._columnFields = [];
         this._valueFields = [];
         this._filterFields = [];
+        this._fieldAssignments = new Map();
         this._name = name;
         this._cache = cache;
         this._targetSheet = targetSheet;
@@ -1571,11 +1937,13 @@ const builder = new XMLBuilder(builderOptions);
         if (fieldIndex < 0) {
             throw new Error(`Field not found in source data: ${fieldName}`);
         }
-        this._rowFields.push({
+        const assignment = {
             fieldName,
             fieldIndex,
             axis: 'row'
-        });
+        };
+        this._rowFields.push(assignment);
+        this._fieldAssignments.set(fieldIndex, assignment);
         return this;
     }
     /**
@@ -1586,11 +1954,13 @@ const builder = new XMLBuilder(builderOptions);
         if (fieldIndex < 0) {
             throw new Error(`Field not found in source data: ${fieldName}`);
         }
-        this._columnFields.push({
+        const assignment = {
             fieldName,
             fieldIndex,
             axis: 'column'
-        });
+        };
+        this._columnFields.push(assignment);
+        this._fieldAssignments.set(fieldIndex, assignment);
         return this;
     }
     /**
@@ -1604,13 +1974,15 @@ const builder = new XMLBuilder(builderOptions);
             throw new Error(`Field not found in source data: ${fieldName}`);
         }
         const defaultName = `${aggregation.charAt(0).toUpperCase() + aggregation.slice(1)} of ${fieldName}`;
-        this._valueFields.push({
+        const assignment = {
             fieldName,
             fieldIndex,
             axis: 'value',
             aggregation,
             displayName: displayName || defaultName
-        });
+        };
+        this._valueFields.push(assignment);
+        this._fieldAssignments.set(fieldIndex, assignment);
         return this;
     }
     /**
@@ -1621,11 +1993,44 @@ const builder = new XMLBuilder(builderOptions);
         if (fieldIndex < 0) {
             throw new Error(`Field not found in source data: ${fieldName}`);
         }
-        this._filterFields.push({
+        const assignment = {
             fieldName,
             fieldIndex,
             axis: 'filter'
-        });
+        };
+        this._filterFields.push(assignment);
+        this._fieldAssignments.set(fieldIndex, assignment);
+        return this;
+    }
+    /**
+   * Set a sort order for a row/column field
+   */ sortField(fieldName, order) {
+        const fieldIndex = this._cache.getFieldIndex(fieldName);
+        if (fieldIndex < 0) {
+            throw new Error(`Field not found in source data: ${fieldName}`);
+        }
+        const assignment = this._fieldAssignments.get(fieldIndex);
+        if (!assignment || assignment.axis !== 'row' && assignment.axis !== 'column') {
+            throw new Error(`Field is not assigned to row or column axis: ${fieldName}`);
+        }
+        assignment.sortOrder = order;
+        return this;
+    }
+    /**
+   * Filter items for a field (include or exclude list)
+   */ filterField(fieldName, filter) {
+        const fieldIndex = this._cache.getFieldIndex(fieldName);
+        if (fieldIndex < 0) {
+            throw new Error(`Field not found in source data: ${fieldName}`);
+        }
+        const assignment = this._fieldAssignments.get(fieldIndex);
+        if (!assignment) {
+            throw new Error(`Field is not assigned to pivot table: ${fieldName}`);
+        }
+        if (filter.include && filter.exclude) {
+            throw new Error('Pivot field filter cannot use both include and exclude');
+        }
+        assignment.filter = filter;
         return this;
     }
     /**
@@ -1790,17 +2195,28 @@ const builder = new XMLBuilder(builderOptions);
         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);
+        const assignment = this._fieldAssignments.get(fieldIndex);
         if (rowField) {
             attrs.axis = 'axisRow';
             attrs.showAll = '0';
+            if (assignment?.sortOrder) {
+                attrs.sortType = 'ascending';
+                attrs.sortOrder = assignment.sortOrder === 'asc' ? 'ascending' : 'descending';
+            }
             // Add items for shared values
             const cacheField = this._cache.fields[fieldIndex];
             if (cacheField && cacheField.sharedItems.length > 0) {
                 const itemNodes = [];
+                const allowedIndexes = this._resolveItemFilter(cacheField.sharedItems, assignment?.filter);
                 for(let i = 0; i < cacheField.sharedItems.length; i++){
-                    itemNodes.push(createElement('item', {
+                    const shouldInclude = allowedIndexes.has(i);
+                    const itemAttrs = {
                         x: String(i)
-                    }, []));
+                    };
+                    if (!shouldInclude) {
+                        itemAttrs.h = '1';
+                    }
+                    itemNodes.push(createElement('item', itemAttrs, []));
                 }
                 // Add default subtotal item
                 itemNodes.push(createElement('item', {
@@ -1813,13 +2229,23 @@ const builder = new XMLBuilder(builderOptions);
         } else if (colField) {
             attrs.axis = 'axisCol';
             attrs.showAll = '0';
+            if (assignment?.sortOrder) {
+                attrs.sortType = 'ascending';
+                attrs.sortOrder = assignment.sortOrder === 'asc' ? 'ascending' : 'descending';
+            }
             const cacheField = this._cache.fields[fieldIndex];
             if (cacheField && cacheField.sharedItems.length > 0) {
                 const itemNodes = [];
+                const allowedIndexes = this._resolveItemFilter(cacheField.sharedItems, assignment?.filter);
                 for(let i = 0; i < cacheField.sharedItems.length; i++){
-                    itemNodes.push(createElement('item', {
+                    const shouldInclude = allowedIndexes.has(i);
+                    const itemAttrs = {
                         x: String(i)
-                    }, []));
+                    };
+                    if (!shouldInclude) {
+                        itemAttrs.h = '1';
+                    }
+                    itemNodes.push(createElement('item', itemAttrs, []));
                 }
                 itemNodes.push(createElement('item', {
                     t: 'default'
@@ -1834,10 +2260,16 @@ const builder = new XMLBuilder(builderOptions);
             const cacheField = this._cache.fields[fieldIndex];
             if (cacheField && cacheField.sharedItems.length > 0) {
                 const itemNodes = [];
+                const allowedIndexes = this._resolveItemFilter(cacheField.sharedItems, assignment?.filter);
                 for(let i = 0; i < cacheField.sharedItems.length; i++){
-                    itemNodes.push(createElement('item', {
+                    const shouldInclude = allowedIndexes.has(i);
+                    const itemAttrs = {
                         x: String(i)
-                    }, []));
+                    };
+                    if (!shouldInclude) {
+                        itemAttrs.h = '1';
+                    }
+                    itemNodes.push(createElement('item', itemAttrs, []));
                 }
                 itemNodes.push(createElement('item', {
                     t: 'default'
@@ -1854,6 +2286,31 @@ const builder = new XMLBuilder(builderOptions);
         }
         return createElement('pivotField', attrs, children);
     }
+    _resolveItemFilter(items, filter) {
+        const allowed = new Set();
+        if (!filter || !filter.include && !filter.exclude) {
+            for(let i = 0; i < items.length; i++){
+                allowed.add(i);
+            }
+            return allowed;
+        }
+        if (filter.include) {
+            for(let i = 0; i < items.length; i++){
+                if (filter.include.includes(items[i])) {
+                    allowed.add(i);
+                }
+            }
+            return allowed;
+        }
+        if (filter.exclude) {
+            for(let i = 0; i < items.length; i++){
+                if (!filter.exclude.includes(items[i])) {
+                    allowed.add(i);
+                }
+            }
+        }
+        return allowed;
+    }
     /**
    * Build row items based on unique values in row fields
    */ _buildRowItems() {
@@ -2004,6 +2461,7 @@ const builder = new XMLBuilder(builderOptions);
         this._records = [];
         this._recordCount = 0;
         this._refreshOnLoad = true; // Default to true
+        this._dateGrouping = false;
         this._cacheId = cacheId;
         this._sourceSheet = sourceSheet;
         this._sourceRange = sourceRange;
@@ -2092,6 +2550,8 @@ const builder = new XMLBuilder(builderOptions);
                 }
             }
         }
+        // Enable date grouping flag if any date field exists
+        this._dateGrouping = this._fields.some((field)=>field.isDate);
         // Store records
         this._records = data;
     }
@@ -2120,6 +2580,8 @@ const builder = new XMLBuilder(builderOptions);
                         v: item
                     }, []));
                 }
+            } else if (field.isDate) {
+                sharedItemsAttrs.containsDate = '1';
             } else if (field.isNumeric) {
                 // Numeric field - use "0"/"1" for boolean attributes as Excel expects
                 sharedItemsAttrs.containsSemiMixedTypes = '0';
@@ -2150,9 +2612,13 @@ const builder = new XMLBuilder(builderOptions);
             ref: this._sourceRange,
             sheet: this._sourceSheet
         }, []);
-        const cacheSourceNode = createElement('cacheSource', {
+        const cacheSourceAttrs = {
             type: 'worksheet'
-        }, [
+        };
+        if (this._dateGrouping) {
+            cacheSourceAttrs.grouping = '1';
+        }
+        const cacheSourceNode = createElement('cacheSource', cacheSourceAttrs, [
             worksheetSourceNode
         ]);
         // Build attributes - refreshOnLoad should come early per OOXML schema
@@ -2298,6 +2764,8 @@ const builder = new XMLBuilder(builderOptions);
         this._pivotTables = [];
         this._pivotCaches = [];
         this._nextCacheId = 0;
+        // Date serialization handling
+        this._dateHandling = 'jsDate';
         this._sharedStrings = new SharedStrings();
         this._styles = Styles.createDefault();
     }
@@ -2362,6 +2830,16 @@ const builder = new XMLBuilder(builderOptions);
         return this._styles;
     }
     /**
+   * Get the workbook date handling strategy.
+   */ get dateHandling() {
+        return this._dateHandling;
+    }
+    /**
+   * Set the workbook date handling strategy.
+   */ set dateHandling(value) {
+        this._dateHandling = value;
+    }
+    /**
    * Get a worksheet by name or index
    */ sheet(nameOrIndex) {
         let def;
@@ -3041,4 +3519,4 @@ const builder = new XMLBuilder(builderOptions);
     }
 }
 
-export { Cell, PivotCache, PivotTable, Range, SharedStrings, Styles, Workbook, Worksheet, parseAddress, parseRange, toAddress, toRange };
+export { Cell, PivotCache, PivotTable, Range, SharedStrings, Styles, Workbook, Worksheet, colToLetter, isInRange, letterToCol, normalizeRange, parseAddress, parseRange, toAddress, toRange };