@niicojs/excel 0.2.5 → 0.2.7

package/dist/index.js

@@ -1115,6 +1115,129 @@ const builder = new 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"
@@ -1305,7 +1428,8 @@ const builder = new 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;
@@ -1437,16 +1561,30 @@ const builder = new 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;
@@ -1626,6 +1764,7 @@ const builder = new XMLBuilder(builderOptions);
         this._columnFields = [];
         this._valueFields = [];
         this._filterFields = [];
+        this._styles = null;
         this._name = name;
         this._cache = cache;
         this._targetSheet = targetSheet;
@@ -1660,6 +1799,13 @@ const builder = new 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) {
@@ -1689,23 +1835,40 @@ const builder = new 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;
     }
@@ -1828,17 +1991,26 @@ const builder = new 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',
@@ -1853,7 +2025,7 @@ const builder = new 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',
@@ -2787,6 +2959,8 @@ const builder = new 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niicojs/excel",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "typescript library to manipulate excel files",
   "homepage": "https://github.com/niicojs/excel#readme",
   "bugs": {

package/src/pivot-table.ts

@@ -1,4 +1,5 @@
-import type { AggregationType, PivotFieldAxis } from './types';
+import type { AggregationType, PivotFieldAxis, PivotValueConfig } from './types';
+import type { Styles } from './styles';
 import { PivotCache } from './pivot-cache';
 import { createElement, stringifyXml, XmlNode } from './utils/xml';
 
@@ -11,6 +12,7 @@ interface FieldAssignment {
   axis: PivotFieldAxis;
   aggregation?: AggregationType;
   displayName?: string;
+  numFmtId?: number;
 }
 
 /**
@@ -30,6 +32,7 @@ export class PivotTable {
   private _filterFields: FieldAssignment[] = [];
 
   private _pivotTableIndex: number;
+  private _styles: Styles | null = null;
 
   constructor(
     name: string,
@@ -84,6 +87,15 @@ export class PivotTable {
     return this._pivotTableIndex;
   }
 
+  /**
+   * Set the styles reference for number format resolution
+   * @internal
+   */
+  setStyles(styles: Styles): this {
+    this._styles = styles;
+    return this;
+  }
+
   /**
    * Add a field to the row area
    * @param fieldName - Name of the source field (column header)
@@ -123,25 +135,70 @@ export class PivotTable {
   }
 
   /**
-   * 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 = 'sum', displayName?: string): this {
+  addValueField(config: PivotValueConfig): this;
+  addValueField(
+    fieldName: string,
+    aggregation?: AggregationType,
+    displayName?: string,
+    numberFormat?: string,
+  ): this;
+  addValueField(
+    fieldNameOrConfig: string | PivotValueConfig,
+    aggregation: AggregationType = 'sum',
+    displayName?: string,
+    numberFormat?: string,
+  ): this {
+    // Normalize arguments to a common form
+    let fieldName: string;
+    let agg: AggregationType;
+    let name: string | undefined;
+    let format: string | undefined;
+
+    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: number | undefined;
+    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;
@@ -251,22 +308,28 @@ export class PivotTable {
 
     // 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',
-          },
-          [],
-        ),
-      );
+      const dataFieldNodes = this._valueFields.map((f) => {
+        const attrs: Record<string, string> = {
+          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(
@@ -290,7 +353,7 @@ export class PivotTable {
         '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',

package/src/styles.ts

@@ -1,6 +1,48 @@
 import type { CellStyle, BorderType } from './types';
 import { parseXml, findElement, getChildren, getAttr, XmlNode, stringifyXml, createElement } from './utils/xml';
 
+/**
+ * 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: Map<string, number> = 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: Map<number, string> = 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"
@@ -234,7 +276,8 @@ export class Styles {
     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: CellStyle = {};
 
@@ -403,17 +446,34 @@ export class Styles {
   }
 
   private _findOrCreateNumFmt(format: string): number {
-    // 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: string): number {
+    this._dirty = true;
+    return this._findOrCreateNumFmt(format);
+  }
+
   /**
    * Check if styles have been modified
    */

package/src/types.ts

@@ -119,10 +119,12 @@ export type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
 export 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;
 }
 
 /**

package/src/workbook.ts

@@ -493,6 +493,10 @@ export class Workbook {
       targetAddr.col,
       pivotTableIndex,
     );
+
+    // Set styles reference for number format resolution
+    pivotTable.setStyles(this._styles);
+
     this._pivotTables.push(pivotTable);
 
     return pivotTable;