@cj-tech-master/excelts 1.5.0 → 1.6.1

package/dist/esm/doc/pivot-table.js

@@ -1,23 +1,114 @@
-import { objectFromProps, range, toSortedArray } from "../utils/utils.js";
+import { range, toSortedArray } from "../utils/utils.js";
+import { colCache } from "../utils/col-cache.js";
 // TK(2023-10-10): turn this into a class constructor.
+/**
+ * Creates a PivotTableSource adapter from a Table object.
+ * This allows Tables to be used as pivot table data sources with the same interface as Worksheets.
+ */
+function createTableSourceAdapter(table) {
+    const tableModel = table.model;
+    // Validate that table has headerRow enabled (required for pivot table column names)
+    if (tableModel.headerRow === false) {
+        throw new Error("Cannot create pivot table from a table without headers. Set headerRow: true on the table.");
+    }
+    // Validate table has data rows
+    if (!tableModel.rows || tableModel.rows.length === 0) {
+        throw new Error("Cannot create pivot table from an empty table. Add data rows to the table.");
+    }
+    const columnNames = tableModel.columns.map(col => col.name);
+    // Check for duplicate column names
+    const nameSet = new Set();
+    for (const name of columnNames) {
+        if (nameSet.has(name)) {
+            throw new Error(`Duplicate column name "${name}" found in table. Pivot tables require unique column names.`);
+        }
+        nameSet.add(name);
+    }
+    // Build the full data array: headers + rows
+    const headerRow = [undefined, ...columnNames]; // sparse array starting at index 1
+    const dataRows = tableModel.rows.map(row => [undefined, ...row]); // sparse array starting at index 1
+    // Calculate the range reference for the table
+    const tl = tableModel.tl;
+    const startRow = tl.row;
+    const startCol = tl.col;
+    const endRow = startRow + tableModel.rows.length; // header row + data rows
+    const endCol = startCol + columnNames.length - 1;
+    const shortRange = colCache.encode(startRow, startCol, endRow, endCol);
+    return {
+        name: tableModel.name,
+        getRow(rowNumber) {
+            if (rowNumber === 1) {
+                return { values: headerRow };
+            }
+            const dataIndex = rowNumber - 2; // rowNumber 2 maps to index 0
+            if (dataIndex >= 0 && dataIndex < dataRows.length) {
+                return { values: dataRows[dataIndex] };
+            }
+            return { values: [] };
+        },
+        getColumn(columnNumber) {
+            // Validate column number is within bounds
+            if (columnNumber < 1 || columnNumber > columnNames.length) {
+                return { values: [] };
+            }
+            // Values should be sparse array with header at index 1, data starting at index 2
+            const values = [];
+            values[1] = columnNames[columnNumber - 1];
+            for (let i = 0; i < tableModel.rows.length; i++) {
+                values[i + 2] = tableModel.rows[i][columnNumber - 1];
+            }
+            return { values };
+        },
+        getSheetValues() {
+            // Return sparse array where index 1 is header row, and subsequent indices are data rows
+            const result = [];
+            result[1] = headerRow;
+            for (let i = 0; i < dataRows.length; i++) {
+                result[i + 2] = dataRows[i];
+            }
+            return result;
+        },
+        dimensions: { shortRange }
+    };
+}
+/**
+ * Resolves the data source from the model, supporting both sourceSheet and sourceTable.
+ */
+function resolveSource(model) {
+    if (model.sourceTable) {
+        return createTableSourceAdapter(model.sourceTable);
+    }
+    // For sourceSheet, it already implements the required interface
+    return model.sourceSheet;
+}
 function makePivotTable(worksheet, model) {
     // Example `model`:
     // {
-    //   // Source of data: the entire sheet range is taken,
-    //   // akin to `worksheet1.getSheetValues()`.
-    //   sourceSheet: worksheet1,
+    //   // Source of data (either sourceSheet OR sourceTable):
+    //   sourceSheet: worksheet1,  // Use entire sheet range
+    //   // OR
+    //   sourceTable: table,       // Use table data
     //
     //   // Pivot table fields: values indicate field names;
-    //   // they come from the first row in `worksheet1`.
+    //   // they come from the first row in `worksheet1` or table column names.
     //   rows: ['A', 'B'],
     //   columns: ['C'],
     //   values: ['E'], // only 1 item possible for now
     //   metric: 'sum', // only 'sum' possible for now
     // }
-    validate(worksheet, model);
-    const { sourceSheet } = model;
-    const { rows, columns, values } = model;
-    const cacheFields = makeCacheFields(sourceSheet, [...rows, ...columns]);
+    // Validate source exists before trying to resolve it
+    if (!model.sourceSheet && !model.sourceTable) {
+        throw new Error("Either sourceSheet or sourceTable must be provided.");
+    }
+    if (model.sourceSheet && model.sourceTable) {
+        throw new Error("Cannot specify both sourceSheet and sourceTable. Choose one.");
+    }
+    // Resolve source first to avoid creating adapter multiple times
+    const source = resolveSource(model);
+    validate(worksheet, model, source);
+    const { rows, values } = model;
+    const columns = model.columns ?? [];
+    const cacheFields = makeCacheFields(source, [...rows, ...columns]);
     const nameToIndex = cacheFields.reduce((result, cacheField, index) => {
         result[cacheField.name] = index;
         return result;
@@ -25,82 +116,79 @@ function makePivotTable(worksheet, model) {
     const rowIndices = rows.map(row => nameToIndex[row]);
     const columnIndices = columns.map(column => nameToIndex[column]);
     const valueIndices = values.map(value => nameToIndex[value]);
+    // Calculate tableNumber based on existing pivot tables (1-indexed)
+    const tableNumber = worksheet.workbook.pivotTables.length + 1;
+    // Base cache ID starts at 10 (Excel convention), each subsequent table increments
+    const BASE_CACHE_ID = 10;
     // form pivot table object
     return {
-        sourceSheet,
+        source,
         rows: rowIndices,
         columns: columnIndices,
         values: valueIndices,
-        metric: "sum",
+        metric: model.metric ?? "sum",
         cacheFields,
-        // defined in <pivotTableDefinition> of xl/pivotTables/pivotTable1.xml;
-        // also used in xl/workbook.xml
-        cacheId: "10"
+        // Dynamic cacheId: 10 for first table, 11 for second, etc.
+        // Used in <pivotTableDefinition> and xl/workbook.xml
+        cacheId: String(BASE_CACHE_ID + tableNumber - 1),
+        // Control whether pivot table style overrides worksheet column widths
+        // '0' = preserve worksheet column widths (useful for custom sizing)
+        // '1' = apply pivot table style width/height (default Excel behavior)
+        applyWidthHeightFormats: model.applyWidthHeightFormats ?? "1",
+        // Table number for file naming (pivotTable1.xml, pivotTable2.xml, etc.)
+        tableNumber
     };
 }
-function validate(worksheet, model) {
-    if (worksheet.workbook.pivotTables.length === 1) {
-        throw new Error("A pivot table was already added. At this time, ExcelTS supports at most one pivot table per file.");
+function validate(_worksheet, model, source) {
+    if (model.metric && model.metric !== "sum" && model.metric !== "count") {
+        throw new Error('Only the "sum" and "count" metrics are supported at this time.');
     }
-    if (model.metric && model.metric !== "sum") {
-        throw new Error('Only the "sum" metric is supported at this time.');
-    }
-    const headerNames = model.sourceSheet.getRow(1).values.slice(1);
-    const isInHeaderNames = objectFromProps(headerNames, true);
-    for (const name of [...model.rows, ...model.columns, ...model.values]) {
-        if (!isInHeaderNames[name]) {
-            throw new Error(`The header name "${name}" was not found in ${model.sourceSheet.name}.`);
+    const columns = model.columns ?? [];
+    // Get header names from source (already resolved)
+    const headerNames = source.getRow(1).values.slice(1);
+    // Use Set for O(1) lookup
+    const headerNameSet = new Set(headerNames);
+    for (const name of [...model.rows, ...columns, ...model.values]) {
+        if (!headerNameSet.has(name)) {
+            throw new Error(`The header name "${name}" was not found in ${source.name}.`);
         }
     }
     if (!model.rows.length) {
         throw new Error("No pivot table rows specified.");
     }
-    if (!model.columns.length) {
-        throw new Error("No pivot table columns specified.");
+    // Allow empty columns - Excel will use "Values" as column field
+    // But can't have multiple values with columns specified
+    if (model.values.length < 1) {
+        throw new Error("Must have at least one value.");
     }
-    if (model.values.length !== 1) {
-        throw new Error("Exactly 1 value needs to be specified at this time.");
+    if (model.values.length > 1 && columns.length > 0) {
+        throw new Error("It is currently not possible to have multiple values when columns are specified. Please either supply an empty array for columns or a single value.");
     }
 }
-function makeCacheFields(worksheet, fieldNamesWithSharedItems) {
+function makeCacheFields(source, fieldNamesWithSharedItems) {
     // Cache fields are used in pivot tables to reference source data.
-    //
-    // Example
-    // -------
-    // Turn
-    //
-    //  `worksheet` sheet values [
-    //    ['A', 'B', 'C', 'D', 'E'],
-    //    ['a1', 'b1', 'c1', 4, 5],
-    //    ['a1', 'b2', 'c1', 4, 5],
-    //    ['a2', 'b1', 'c2', 14, 24],
-    //    ['a2', 'b2', 'c2', 24, 35],
-    //    ['a3', 'b1', 'c3', 34, 45],
-    //    ['a3', 'b2', 'c3', 44, 45]
-    //  ];
-    //  fieldNamesWithSharedItems = ['A', 'B', 'C'];
-    //
-    // into
-    //
-    //  [
-    //    { name: 'A', sharedItems: ['a1', 'a2', 'a3'] },
-    //    { name: 'B', sharedItems: ['b1', 'b2'] },
-    //    { name: 'C', sharedItems: ['c1', 'c2', 'c3'] },
-    //    { name: 'D', sharedItems: null },
-    //    { name: 'E', sharedItems: null }
-    //  ]
-    const names = worksheet.getRow(1).values;
-    const nameToHasSharedItems = objectFromProps(fieldNamesWithSharedItems, true);
+    // Fields in fieldNamesWithSharedItems get their unique values extracted as sharedItems.
+    // Other fields (typically numeric) have sharedItems = null.
+    const names = source.getRow(1).values;
+    // Use Set for O(1) lookup instead of object
+    const sharedItemsFields = new Set(fieldNamesWithSharedItems);
     const aggregate = (columnIndex) => {
-        const columnValues = worksheet.getColumn(columnIndex).values.splice(2);
-        const columnValuesAsSet = new Set(columnValues);
-        return toSortedArray(columnValuesAsSet);
+        const columnValues = source.getColumn(columnIndex).values;
+        // Build unique values set directly, skipping header (index 0,1) and null/undefined
+        const uniqueValues = new Set();
+        for (let i = 2; i < columnValues.length; i++) {
+            const v = columnValues[i];
+            if (v !== null && v !== undefined) {
+                uniqueValues.add(v);
+            }
+        }
+        return toSortedArray(uniqueValues);
     };
-    // make result
+    // Build result array
     const result = [];
     for (const columnIndex of range(1, names.length)) {
         const name = names[columnIndex];
-        const sharedItems = nameToHasSharedItems[name] ? aggregate(columnIndex) : null;
+        const sharedItems = sharedItemsFields.has(name) ? aggregate(columnIndex) : null;
         result.push({ name, sharedItems });
     }
     return result;

package/dist/esm/doc/workbook.js

@@ -196,7 +196,9 @@ class Workbook {
         this.views = value.views;
         this._themes = value.themes;
         this.media = value.media || [];
-        this.pivotTables = value.pivotTables || [];
+        // Handle pivot tables - either newly created or loaded from file
+        // Loaded pivot tables come from loadedPivotTables after reconciliation
+        this.pivotTables = value.pivotTables || value.loadedPivotTables || [];
     }
 }
 export { Workbook };

package/dist/esm/doc/worksheet.js

@@ -830,8 +830,6 @@ class Worksheet {
     // =========================================================================
     // Pivot Tables
     addPivotTable(model) {
-        console.warn(`Warning: Pivot Table support is experimental. 
-Please leave feedback at https://github.com/excelts/excelts/discussions/2575`);
         const pivotTable = makePivotTable(this, model);
         this.pivotTables.push(pivotTable);
         this.workbook.pivotTables.push(pivotTable);

package/dist/esm/stream/xlsx/worksheet-writer.js

@@ -180,6 +180,7 @@ class WorksheetWriter {
             this._writeOpenSheetData();
         }
         this._writeCloseSheetData();
+        this._writeSheetProtection(); // Note: must be after sheetData and before autoFilter
         this._writeAutoFilter();
         this._writeMergeCells();
         // for some reason, Excel can't handle dimensions at the bottom of the file
@@ -187,7 +188,6 @@ class WorksheetWriter {
         this._writeHyperlinks();
         this._writeConditionalFormatting();
         this._writeDataValidations();
-        this._writeSheetProtection();
         this._writePageMargins();
         this._writePageSetup();
         this._writeBackground();

package/dist/esm/utils/unzip/zip-parser.js

@@ -175,7 +175,7 @@ export function parseZipEntries(data, options = {}) {
     reader.skip(2); // disk where central dir starts
     reader.skip(2); // entries on this disk
     let totalEntries = reader.readUint16(); // total entries
-    let centralDirSize = reader.readUint32();
+    reader.skip(4); // central directory size (unused)
     let centralDirOffset = reader.readUint32();
     // Check for ZIP64
     const zip64LocatorOffset = findZip64EOCDLocator(data, eocdOffset);
@@ -194,15 +194,12 @@ export function parseZipEntries(data, options = {}) {
             zip64Reader.skip(4); // disk number
             zip64Reader.skip(4); // disk with central dir
             const zip64TotalEntries = Number(zip64Reader.readBigUint64());
-            const zip64CentralDirSize = Number(zip64Reader.readBigUint64());
+            zip64Reader.skip(8); // central directory size (unused)
             const zip64CentralDirOffset = Number(zip64Reader.readBigUint64());
             // Use ZIP64 values if standard values are maxed out
             if (totalEntries === 0xffff) {
                 totalEntries = zip64TotalEntries;
             }
-            if (centralDirSize === 0xffffffff) {
-                centralDirSize = zip64CentralDirSize;
-            }
             if (centralDirOffset === 0xffffffff) {
                 centralDirOffset = zip64CentralDirOffset;
             }

package/dist/esm/xlsx/xform/book/workbook-xform.js

@@ -130,6 +130,9 @@ class WorkbookXform extends BaseXform {
                 if (this.map.definedNames.model) {
                     this.model.definedNames = this.map.definedNames.model;
                 }
+                if (this.map.pivotCaches.model && this.map.pivotCaches.model.length > 0) {
+                    this.model.pivotCaches = this.map.pivotCaches.model;
+                }
                 return false;
             default:
                 // not quite sure how we get here!

package/dist/esm/xlsx/xform/core/content-types-xform.js

@@ -28,26 +28,31 @@ class ContentTypesXform extends BaseXform {
             PartName: "/xl/workbook.xml",
             ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"
         });
-        model.worksheets.forEach((worksheet) => {
-            const name = `/xl/worksheets/sheet${worksheet.id}.xml`;
+        model.worksheets.forEach((worksheet, index) => {
+            // Use fileIndex if set, otherwise use sequential index (1-based)
+            const fileIndex = worksheet.fileIndex || index + 1;
+            const name = `/xl/worksheets/sheet${fileIndex}.xml`;
             xmlStream.leafNode("Override", {
                 PartName: name,
                 ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
             });
         });
         if ((model.pivotTables || []).length) {
-            // Note(2023-10-06): assuming at most one pivot table for now.
-            xmlStream.leafNode("Override", {
-                PartName: "/xl/pivotCache/pivotCacheDefinition1.xml",
-                ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"
-            });
-            xmlStream.leafNode("Override", {
-                PartName: "/xl/pivotCache/pivotCacheRecords1.xml",
-                ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"
-            });
-            xmlStream.leafNode("Override", {
-                PartName: "/xl/pivotTables/pivotTable1.xml",
-                ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"
+            // Add content types for each pivot table
+            (model.pivotTables || []).forEach((pivotTable) => {
+                const n = pivotTable.tableNumber;
+                xmlStream.leafNode("Override", {
+                    PartName: `/xl/pivotCache/pivotCacheDefinition${n}.xml`,
+                    ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"
+                });
+                xmlStream.leafNode("Override", {
+                    PartName: `/xl/pivotCache/pivotCacheRecords${n}.xml`,
+                    ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"
+                });
+                xmlStream.leafNode("Override", {
+                    PartName: `/xl/pivotTables/pivotTable${n}.xml`,
+                    ContentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"
+                });
             });
         }
         xmlStream.leafNode("Override", {

package/dist/esm/xlsx/xform/pivot-table/cache-field-xform.js

@@ -0,0 +1,132 @@
+import { BaseXform } from "../base-xform.js";
+import { xmlDecode } from "../../../utils/utils.js";
+/**
+ * Xform for parsing individual <cacheField> elements within a pivot cache definition.
+ *
+ * Example XML:
+ * ```xml
+ * <cacheField name="Category" numFmtId="0">
+ *   <sharedItems count="3">
+ *     <s v="A" />
+ *     <s v="B" />
+ *     <s v="C" />
+ *   </sharedItems>
+ * </cacheField>
+ *
+ * <cacheField name="Value" numFmtId="0">
+ *   <sharedItems containsSemiMixedTypes="0" containsString="0"
+ *                containsNumber="1" containsInteger="1" minValue="5" maxValue="45" />
+ * </cacheField>
+ * ```
+ */
+class CacheFieldXform extends BaseXform {
+    constructor() {
+        super();
+        this.model = null;
+        this.inSharedItems = false;
+    }
+    get tag() {
+        return "cacheField";
+    }
+    reset() {
+        this.model = null;
+        this.inSharedItems = false;
+    }
+    parseOpen(node) {
+        const { name, attributes } = node;
+        switch (name) {
+            case "cacheField":
+                // Initialize the model with field name
+                this.model = {
+                    name: xmlDecode(attributes.name || ""),
+                    sharedItems: null
+                };
+                break;
+            case "sharedItems":
+                this.inSharedItems = true;
+                // Check if this is a numeric field (no string items)
+                if (attributes.containsNumber === "1" || attributes.containsInteger === "1") {
+                    if (this.model) {
+                        this.model.containsNumber = attributes.containsNumber === "1";
+                        this.model.containsInteger = attributes.containsInteger === "1";
+                        if (attributes.minValue !== undefined) {
+                            this.model.minValue = parseFloat(attributes.minValue);
+                        }
+                        if (attributes.maxValue !== undefined) {
+                            this.model.maxValue = parseFloat(attributes.maxValue);
+                        }
+                        // Numeric fields have sharedItems = null
+                        this.model.sharedItems = null;
+                    }
+                }
+                else {
+                    // String field - initialize sharedItems array if count > 0
+                    if (this.model) {
+                        const count = parseInt(attributes.count || "0", 10);
+                        if (count > 0) {
+                            this.model.sharedItems = [];
+                        }
+                    }
+                }
+                break;
+            case "s":
+                // String value in sharedItems
+                if (this.inSharedItems && this.model?.sharedItems !== null) {
+                    // Decode XML entities in the value
+                    const value = xmlDecode(attributes.v || "");
+                    this.model.sharedItems.push(value);
+                }
+                break;
+            case "n":
+                // Numeric value in sharedItems (less common, but possible)
+                if (this.inSharedItems && this.model?.sharedItems !== null) {
+                    const value = parseFloat(attributes.v || "0");
+                    this.model.sharedItems.push(value);
+                }
+                break;
+            case "b":
+                // Boolean value in sharedItems
+                if (this.inSharedItems && this.model?.sharedItems !== null) {
+                    const value = attributes.v === "1";
+                    this.model.sharedItems.push(value);
+                }
+                break;
+            case "e":
+                // Error value in sharedItems
+                if (this.inSharedItems && this.model?.sharedItems !== null) {
+                    const value = `#${attributes.v || "ERROR!"}`;
+                    this.model.sharedItems.push(value);
+                }
+                break;
+            case "m":
+                // Missing/null value in sharedItems
+                if (this.inSharedItems && this.model?.sharedItems !== null) {
+                    this.model.sharedItems.push(null);
+                }
+                break;
+            case "d":
+                // Date value in sharedItems
+                if (this.inSharedItems && this.model?.sharedItems !== null) {
+                    const value = new Date(attributes.v || "");
+                    this.model.sharedItems.push(value);
+                }
+                break;
+        }
+        return true;
+    }
+    parseText(_text) {
+        // No text content in cacheField elements
+    }
+    parseClose(name) {
+        switch (name) {
+            case "cacheField":
+                // End of this cacheField element
+                return false;
+            case "sharedItems":
+                this.inSharedItems = false;
+                break;
+        }
+        return true;
+    }
+}
+export { CacheFieldXform };

package/dist/esm/xlsx/xform/pivot-table/cache-field.js

@@ -1,3 +1,4 @@
+import { xmlEncode } from "../../../utils/utils.js";
 class CacheField {
     constructor({ name, sharedItems }) {
         // string type
@@ -21,17 +22,19 @@ class CacheField {
     render() {
         // PivotCache Field: http://www.datypic.com/sc/ooxml/e-ssml_cacheField-1.html
         // Shared Items: http://www.datypic.com/sc/ooxml/e-ssml_sharedItems-1.html
+        // Escape XML special characters in name attribute
+        const escapedName = xmlEncode(this.name);
         // integer types
         if (this.sharedItems === null) {
             // TK(2023-07-18): left out attributes... minValue="5" maxValue="45"
-            return `<cacheField name="${this.name}" numFmtId="0">
+            return `<cacheField name="${escapedName}" numFmtId="0">
       <sharedItems containsSemiMixedTypes="0" containsString="0" containsNumber="1" containsInteger="1" />
     </cacheField>`;
         }
-        // string types
-        return `<cacheField name="${this.name}" numFmtId="0">
+        // string types - escape XML special characters in each shared item value
+        return `<cacheField name="${escapedName}" numFmtId="0">
       <sharedItems count="${this.sharedItems.length}">
-        ${this.sharedItems.map(item => `<s v="${item}" />`).join("")}
+        ${this.sharedItems.map(item => `<s v="${xmlEncode(String(item))}" />`).join("")}
       </sharedItems>
     </cacheField>`;
     }