@niicojs/excel 0.2.6 → 0.2.7

package/dist/index.cjs

@@ -1837,25 +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")
-   * @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;
     }
@@ -1986,9 +2001,9 @@ const builder = new fastXmlParser.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, []);
             });
@@ -1997,7 +2012,7 @@ const builder = new fastXmlParser.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/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
@@ -664,12 +666,20 @@ 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")
-     * @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;
     /**
      * Add a field to the filter (page) area