@niicojs/excel 0.2.6 → 0.2.7

package/dist/index.js

@@ -1835,25 +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")
-   * @param numberFormat - Optional number format (e.g., '$#,##0.00', '0.00%')
-   */ addValueField(fieldName, aggregation = 'sum', displayName, numberFormat) {
+    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,
-            numberFormat
+            aggregation: agg,
+            displayName: name || defaultName,
+            numFmtId
         });
         return this;
     }
@@ -1984,9 +1999,9 @@ const builder = new XMLBuilder(builderOptions);
                     baseItem: '0',
                     subtotal: f.aggregation || 'sum'
                 };
-                // Add numFmtId if format specified and styles available
-                if (f.numberFormat && this._styles) {
-                    attrs.numFmtId = String(this._styles.getOrCreateNumFmtId(f.numberFormat));
+                // Add numFmtId if it was resolved during addValueField
+                if (f.numFmtId !== undefined) {
+                    attrs.numFmtId = String(f.numFmtId);
                 }
                 return createElement('dataField', attrs, []);
             });
@@ -1995,7 +2010,7 @@ const builder = new XMLBuilder(builderOptions);
             }, dataFieldNodes));
         }
         // Check if any value field has a number format
-        const hasNumberFormats = this._valueFields.some((f)=>f.numberFormat);
+        const hasNumberFormats = this._valueFields.some((f)=>f.numFmtId !== undefined);
         // Pivot table style
         children.push(createElement('pivotTableStyleInfo', {
             name: 'PivotStyleMedium9',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niicojs/excel",
-  "version": "0.2.6",
+  "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,4 @@
-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';
@@ -12,7 +12,7 @@ interface FieldAssignment {
   axis: PivotFieldAxis;
   aggregation?: AggregationType;
   displayName?: string;
-  numberFormat?: string;
+  numFmtId?: number;
 }
 
 /**
@@ -135,32 +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")
-   * @param numberFormat - Optional number format (e.g., '$#,##0.00', '0.00%')
+   * 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(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,
-      numberFormat,
+      aggregation: agg,
+      displayName: name || defaultName,
+      numFmtId,
     });
 
     return this;
@@ -279,9 +317,9 @@ export class PivotTable {
           subtotal: f.aggregation || 'sum',
         };
 
-        // Add numFmtId if format specified and styles available
-        if (f.numberFormat && this._styles) {
-          attrs.numFmtId = String(this._styles.getOrCreateNumFmtId(f.numberFormat));
+        // Add numFmtId if it was resolved during addValueField
+        if (f.numFmtId !== undefined) {
+          attrs.numFmtId = String(f.numFmtId);
         }
 
         return createElement('dataField', attrs, []);
@@ -290,7 +328,7 @@ export class PivotTable {
     }
 
     // Check if any value field has a number format
-    const hasNumberFormats = this._valueFields.some((f) => f.numberFormat);
+    const hasNumberFormats = this._valueFields.some((f) => f.numFmtId !== undefined);
 
     // Pivot table style
     children.push(

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;
 }
 
 /**