@niicojs/excel 0.2.5 → 0.2.7

package/dist/index.cjs

@@ -1117,6 +1117,129 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
 }
 
+/**
+ * Excel built-in number format IDs (0-163 are reserved).
+ * These formats don't need to be defined in the numFmts element.
+ */ const BUILTIN_NUM_FMTS = new Map([
+    [
+        'General',
+        0
+    ],
+    [
+        '0',
+        1
+    ],
+    [
+        '0.00',
+        2
+    ],
+    [
+        '#,##0',
+        3
+    ],
+    [
+        '#,##0.00',
+        4
+    ],
+    [
+        '0%',
+        9
+    ],
+    [
+        '0.00%',
+        10
+    ],
+    [
+        '0.00E+00',
+        11
+    ],
+    [
+        '# ?/?',
+        12
+    ],
+    [
+        '# ??/??',
+        13
+    ],
+    [
+        'mm-dd-yy',
+        14
+    ],
+    [
+        'd-mmm-yy',
+        15
+    ],
+    [
+        'd-mmm',
+        16
+    ],
+    [
+        'mmm-yy',
+        17
+    ],
+    [
+        'h:mm AM/PM',
+        18
+    ],
+    [
+        'h:mm:ss AM/PM',
+        19
+    ],
+    [
+        'h:mm',
+        20
+    ],
+    [
+        'h:mm:ss',
+        21
+    ],
+    [
+        'm/d/yy h:mm',
+        22
+    ],
+    [
+        '#,##0 ;(#,##0)',
+        37
+    ],
+    [
+        '#,##0 ;[Red](#,##0)',
+        38
+    ],
+    [
+        '#,##0.00;(#,##0.00)',
+        39
+    ],
+    [
+        '#,##0.00;[Red](#,##0.00)',
+        40
+    ],
+    [
+        'mm:ss',
+        45
+    ],
+    [
+        '[h]:mm:ss',
+        46
+    ],
+    [
+        'mmss.0',
+        47
+    ],
+    [
+        '##0.0E+0',
+        48
+    ],
+    [
+        '@',
+        49
+    ]
+]);
+/**
+ * Reverse lookup: built-in format ID -> format code
+ */ const BUILTIN_NUM_FMT_CODES = new Map(Array.from(BUILTIN_NUM_FMTS.entries()).map(([code, id])=>[
+        id,
+        code
+    ]));
 /**
  * Normalize a color to ARGB format (8 hex chars).
  * Accepts: "#RGB", "#RRGGBB", "RGB", "RRGGBB", "AARRGGBB", "#AARRGGBB"
@@ -1307,7 +1430,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         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);
+        // Check custom formats first, then fall back to built-in format codes
+        const numFmt = this._numFmts.get(xf.numFmtId) ?? BUILTIN_NUM_FMT_CODES.get(xf.numFmtId);
         const style = {};
         if (font) {
             if (font.bold) style.bold = true;
@@ -1439,16 +1563,30 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         return this._borders.length - 1;
     }
     _findOrCreateNumFmt(format) {
-        // Check if already exists
+        // Check built-in formats first (IDs 0-163)
+        const builtinId = BUILTIN_NUM_FMTS.get(format);
+        if (builtinId !== undefined) {
+            return builtinId;
+        }
+        // Check if already exists in custom formats
         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;
+        // Create new custom format (IDs 164+)
+        const existingIds = Array.from(this._numFmts.keys());
+        const id = existingIds.length > 0 ? Math.max(...existingIds) + 1 : 164;
         this._numFmts.set(id, format);
         return id;
     }
     /**
+   * Get or create a number format ID for the given format string.
+   * Returns built-in IDs (0-163) for standard formats, or creates custom IDs (164+).
+   * @param format - The number format string (e.g., '0.00', '#,##0', '$#,##0.00')
+   */ getOrCreateNumFmtId(format) {
+        this._dirty = true;
+        return this._findOrCreateNumFmt(format);
+    }
+    /**
    * Check if styles have been modified
    */ get dirty() {
         return this._dirty;
@@ -1628,6 +1766,7 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._columnFields = [];
         this._valueFields = [];
         this._filterFields = [];
+        this._styles = null;
         this._name = name;
         this._cache = cache;
         this._targetSheet = targetSheet;
@@ -1662,6 +1801,13 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         return this._pivotTableIndex;
     }
     /**
+   * Set the styles reference for number format resolution
+   * @internal
+   */ setStyles(styles) {
+        this._styles = styles;
+        return this;
+    }
+    /**
    * Add a field to the row area
    * @param fieldName - Name of the source field (column header)
    */ addRowField(fieldName) {
@@ -1691,23 +1837,40 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         });
         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) {
+    addValueField(fieldNameOrConfig, aggregation = 'sum', displayName, numberFormat) {
+        // Normalize arguments to a common form
+        let fieldName;
+        let agg;
+        let name;
+        let format;
+        if (typeof fieldNameOrConfig === 'object') {
+            fieldName = fieldNameOrConfig.field;
+            agg = fieldNameOrConfig.aggregation ?? 'sum';
+            name = fieldNameOrConfig.name;
+            format = fieldNameOrConfig.numberFormat;
+        } else {
+            fieldName = fieldNameOrConfig;
+            agg = aggregation;
+            name = displayName;
+            format = numberFormat;
+        }
         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}`;
+        const defaultName = `${agg.charAt(0).toUpperCase() + agg.slice(1)} of ${fieldName}`;
+        // Resolve numFmtId immediately if format is provided and styles are available
+        let numFmtId;
+        if (format && this._styles) {
+            numFmtId = this._styles.getOrCreateNumFmtId(format);
+        }
         this._valueFields.push({
             fieldName,
             fieldIndex,
             axis: 'value',
-            aggregation,
-            displayName: displayName || defaultName
+            aggregation: agg,
+            displayName: name || defaultName,
+            numFmtId
         });
         return this;
     }
@@ -1830,17 +1993,26 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         // Data fields (values)
         if (this._valueFields.length > 0) {
-            const dataFieldNodes = this._valueFields.map((f)=>createElement('dataField', {
+            const dataFieldNodes = this._valueFields.map((f)=>{
+                const attrs = {
                     name: f.displayName || f.fieldName,
                     fld: String(f.fieldIndex),
                     baseField: '0',
                     baseItem: '0',
                     subtotal: f.aggregation || 'sum'
-                }, []));
+                };
+                // Add numFmtId if it was resolved during addValueField
+                if (f.numFmtId !== undefined) {
+                    attrs.numFmtId = String(f.numFmtId);
+                }
+                return createElement('dataField', attrs, []);
+            });
             children.push(createElement('dataFields', {
                 count: String(dataFieldNodes.length)
             }, dataFieldNodes));
         }
+        // Check if any value field has a number format
+        const hasNumberFormats = this._valueFields.some((f)=>f.numFmtId !== undefined);
         // Pivot table style
         children.push(createElement('pivotTableStyleInfo', {
             name: 'PivotStyleMedium9',
@@ -1855,7 +2027,7 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             'xmlns:r': 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
             name: this._name,
             cacheId: String(this._cache.cacheId),
-            applyNumberFormats: '0',
+            applyNumberFormats: hasNumberFormats ? '1' : '0',
             applyBorderFormats: '0',
             applyFontFormats: '0',
             applyPatternFormats: '0',
@@ -2789,6 +2961,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         // Create pivot table
         const pivotTableIndex = this._pivotTables.length + 1;
         const pivotTable = new PivotTable(config.name, cache, targetSheet, targetCell, targetAddr.row + 1, targetAddr.col, pivotTableIndex);
+        // Set styles reference for number format resolution
+        pivotTable.setStyles(this._styles);
         this._pivotTables.push(pivotTable);
         return pivotTable;
     }

package/dist/index.d.cts

@@ -89,10 +89,12 @@ type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
 interface PivotValueConfig {
     /** Source field name (column header) */
     field: string;
-    /** Aggregation function */
-    aggregation: AggregationType;
+    /** Aggregation function (default: 'sum') */
+    aggregation?: AggregationType;
     /** Display name (e.g., "Sum of Sales") */
     name?: string;
+    /** Number format (e.g., '$#,##0.00', '0.00%') */
+    numberFormat?: string;
 }
 /**
  * Configuration for creating a pivot table
@@ -521,6 +523,12 @@ declare class Styles {
     private _findOrCreateFill;
     private _findOrCreateBorder;
     private _findOrCreateNumFmt;
+    /**
+     * Get or create a number format ID for the given format string.
+     * Returns built-in IDs (0-163) for standard formats, or creates custom IDs (164+).
+     * @param format - The number format string (e.g., '0.00', '#,##0', '$#,##0.00')
+     */
+    getOrCreateNumFmtId(format: string): number;
     /**
      * Check if styles have been modified
      */
@@ -620,6 +628,7 @@ declare class PivotTable {
     private _valueFields;
     private _filterFields;
     private _pivotTableIndex;
+    private _styles;
     constructor(name: string, cache: PivotCache, targetSheet: string, targetCell: string, targetRow: number, targetCol: number, pivotTableIndex: number);
     /**
      * Get the pivot table name
@@ -641,6 +650,11 @@ declare class PivotTable {
      * Get the pivot table index (for file naming)
      */
     get index(): number;
+    /**
+     * Set the styles reference for number format resolution
+     * @internal
+     */
+    setStyles(styles: Styles): this;
     /**
      * Add a field to the row area
      * @param fieldName - Name of the source field (column header)
@@ -652,12 +666,21 @@ declare class PivotTable {
      */
     addColumnField(fieldName: string): 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")
+     * Add a field to the values area with aggregation.
+     *
+     * Supports two call signatures:
+     * - Positional: `addValueField(fieldName, aggregation?, displayName?, numberFormat?)`
+     * - Object: `addValueField({ field, aggregation?, name?, numberFormat? })`
+     *
+     * @example
+     * // Positional arguments
+     * pivot.addValueField('Sales', 'sum', 'Total Sales', '$#,##0.00');
+     *
+     * // Object form
+     * pivot.addValueField({ field: 'Sales', aggregation: 'sum', name: 'Total Sales', numberFormat: '$#,##0.00' });
      */
-    addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string): this;
+    addValueField(config: PivotValueConfig): this;
+    addValueField(fieldName: string, aggregation?: AggregationType, displayName?: string, numberFormat?: string): this;
     /**
      * Add a field to the filter (page) area
      * @param fieldName - Name of the source field (column header)