@niicojs/excel 0.3.1 → 0.3.2

package/dist/index.cjs

@@ -4,10 +4,10 @@ var promises = require('fs/promises');
 var fastXmlParser = require('fast-xml-parser');
 var fflate = require('fflate');
 
-/**
- * Converts a column index (0-based) to Excel column letters (A, B, ..., Z, AA, AB, ...)
- * @param col - 0-based column index
- * @returns Column letter(s)
+/**
+ * Converts a column index (0-based) to Excel column letters (A, B, ..., Z, AA, AB, ...)
+ * @param col - 0-based column index
+ * @returns Column letter(s)
  */ const colToLetter = (col)=>{
     let result = '';
     let n = col;
@@ -17,10 +17,10 @@ var fflate = require('fflate');
     }
     return result;
 };
-/**
- * Converts Excel column letters to a 0-based column index
- * @param letters - Column letter(s) like 'A', 'B', 'AA'
- * @returns 0-based column index
+/**
+ * Converts Excel column letters to a 0-based column index
+ * @param letters - Column letter(s) like 'A', 'B', 'AA'
+ * @returns 0-based column index
  */ const letterToCol = (letters)=>{
     const upper = letters.toUpperCase();
     let col = 0;
@@ -29,10 +29,10 @@ var fflate = require('fflate');
     }
     return col - 1;
 };
-/**
- * Parses an Excel cell address (e.g., 'A1', '$B$2') to row/col indices
- * @param address - Cell address string
- * @returns CellAddress with 0-based row and col
+/**
+ * Parses an Excel cell address (e.g., 'A1', '$B$2') to row/col indices
+ * @param address - Cell address string
+ * @returns CellAddress with 0-based row and col
  */ const parseAddress = (address)=>{
     // Remove $ signs for absolute references
     const clean = address.replace(/\$/g, '');
@@ -49,18 +49,18 @@ var fflate = require('fflate');
         col
     };
 };
-/**
- * Converts row/col indices to an Excel cell address
- * @param row - 0-based row index
- * @param col - 0-based column index
- * @returns Cell address string like 'A1'
+/**
+ * Converts row/col indices to an Excel cell address
+ * @param row - 0-based row index
+ * @param col - 0-based column index
+ * @returns Cell address string like 'A1'
  */ const toAddress = (row, col)=>{
     return `${colToLetter(col)}${row + 1}`;
 };
-/**
- * Parses an Excel range (e.g., 'A1:B10') to start/end addresses
- * @param range - Range string
- * @returns RangeAddress with start and end
+/**
+ * Parses an Excel range (e.g., 'A1:B10') to start/end addresses
+ * @param range - Range string
+ * @returns RangeAddress with start and end
  */ const parseRange = (range)=>{
     const parts = range.split(':');
     if (parts.length === 1) {
@@ -79,10 +79,10 @@ var fflate = require('fflate');
         end: parseAddress(parts[1])
     };
 };
-/**
- * Converts a RangeAddress to a range string
- * @param range - RangeAddress object
- * @returns Range string like 'A1:B10'
+/**
+ * Converts a RangeAddress to a range string
+ * @param range - RangeAddress object
+ * @returns Range string like 'A1:B10'
  */ const toRange = (range)=>{
     const start = toAddress(range.start.row, range.start.col);
     const end = toAddress(range.end.row, range.end.col);
@@ -91,8 +91,8 @@ var fflate = require('fflate');
     }
     return `${start}:${end}`;
 };
-/**
- * Normalizes a range so start is always top-left and end is bottom-right
+/**
+ * Normalizes a range so start is always top-left and end is bottom-right
  */ const normalizeRange = (range)=>{
     return {
         start: {
@@ -106,6 +106,334 @@ var fflate = require('fflate');
     };
 };
 
+const DEFAULT_LOCALE = 'fr-FR';
+const formatPartsCache = new Map();
+const getLocaleNumberInfo = (locale)=>{
+    const cacheKey = `num-info:${locale}`;
+    const cached = formatPartsCache.get(cacheKey);
+    if (cached) {
+        const decimal = cached.find((p)=>p.type === 'decimal')?.value ?? ',';
+        const group = cached.find((p)=>p.type === 'group')?.value ?? ' ';
+        return {
+            decimal,
+            group
+        };
+    }
+    const parts = new Intl.NumberFormat(locale).formatToParts(12345.6);
+    formatPartsCache.set(cacheKey, parts);
+    const decimal = parts.find((p)=>p.type === 'decimal')?.value ?? ',';
+    const group = parts.find((p)=>p.type === 'group')?.value ?? ' ';
+    return {
+        decimal,
+        group
+    };
+};
+const normalizeSpaces = (value)=>{
+    return value.replace(/[\u00a0\u202f]/g, ' ');
+};
+const splitFormatSections = (format)=>{
+    const sections = [];
+    let current = '';
+    let inQuote = false;
+    for(let i = 0; i < format.length; i++){
+        const ch = format[i];
+        if (ch === '"') {
+            inQuote = !inQuote;
+            current += ch;
+            continue;
+        }
+        if (ch === ';' && !inQuote) {
+            sections.push(current);
+            current = '';
+            continue;
+        }
+        current += ch;
+    }
+    sections.push(current);
+    return sections;
+};
+const extractFormatLiterals = (format)=>{
+    let prefix = '';
+    let suffix = '';
+    let cleaned = '';
+    let inQuote = false;
+    let sawPlaceholder = false;
+    for(let i = 0; i < format.length; i++){
+        const ch = format[i];
+        if (ch === '"') {
+            inQuote = !inQuote;
+            continue;
+        }
+        if (inQuote) {
+            if (!sawPlaceholder) {
+                prefix += ch;
+            } else {
+                suffix += ch;
+            }
+            continue;
+        }
+        if (ch === '\\' && i + 1 < format.length) {
+            const escaped = format[i + 1];
+            if (!sawPlaceholder) {
+                prefix += escaped;
+            } else {
+                suffix += escaped;
+            }
+            i++;
+            continue;
+        }
+        if (ch === '_' || ch === '*') {
+            if (i + 1 < format.length) {
+                i++;
+            }
+            continue;
+        }
+        if (ch === '[') {
+            const end = format.indexOf(']', i + 1);
+            if (end !== -1) {
+                const content = format.slice(i + 1, end);
+                const currencyMatch = content.match(/[$€]/);
+                if (currencyMatch) {
+                    if (!sawPlaceholder) {
+                        prefix += currencyMatch[0];
+                    } else {
+                        suffix += currencyMatch[0];
+                    }
+                }
+                i = end;
+                continue;
+            }
+        }
+        if (ch === '%') {
+            if (!sawPlaceholder) {
+                prefix += ch;
+            } else {
+                suffix += ch;
+            }
+            continue;
+        }
+        if (ch === '0' || ch === '#' || ch === '?' || ch === '.' || ch === ',') {
+            sawPlaceholder = true;
+            cleaned += ch;
+            continue;
+        }
+        if (!sawPlaceholder) {
+            prefix += ch;
+        } else {
+            suffix += ch;
+        }
+    }
+    return {
+        cleaned,
+        prefix,
+        suffix
+    };
+};
+const parseNumberFormat = (format)=>{
+    const trimmed = format.trim();
+    if (!trimmed) return null;
+    const { cleaned, prefix, suffix } = extractFormatLiterals(trimmed);
+    const lower = cleaned.toLowerCase();
+    if (!/[0#?]/.test(lower)) return null;
+    const percent = /%/.test(trimmed);
+    const section = lower;
+    const lastDot = section.lastIndexOf('.');
+    const lastComma = section.lastIndexOf(',');
+    let decimalSeparator = null;
+    if (lastDot >= 0 && lastComma >= 0) {
+        decimalSeparator = lastDot > lastComma ? '.' : ',';
+    } else if (lastDot >= 0 || lastComma >= 0) {
+        const candidate = lastDot >= 0 ? '.' : ',';
+        const index = lastDot >= 0 ? lastDot : lastComma;
+        const fractionSection = section.slice(index + 1);
+        const fractionDigitsCandidate = fractionSection.replace(/[^0#?]/g, '').length;
+        if (fractionDigitsCandidate > 0) {
+            if (fractionDigitsCandidate === 3) {
+                decimalSeparator = null;
+            } else {
+                decimalSeparator = candidate;
+            }
+        }
+    }
+    let decimalIndex = decimalSeparator === '.' ? lastDot : decimalSeparator === ',' ? lastComma : -1;
+    if (decimalIndex >= 0) {
+        const fractionSection = section.slice(decimalIndex + 1);
+        if (!/[0#?]/.test(fractionSection)) {
+            decimalIndex = -1;
+        }
+    }
+    const decimalSection = decimalIndex >= 0 ? section.slice(decimalIndex + 1) : '';
+    const fractionDigits = decimalSection.replace(/[^0#?]/g, '').length;
+    const integerSection = decimalIndex >= 0 ? section.slice(0, decimalIndex) : section;
+    const useGrouping = /[,.\s\u00a0\u202f]/.test(integerSection) && integerSection.length > 0;
+    return {
+        fractionDigits,
+        percent,
+        useGrouping,
+        literalPrefix: prefix || undefined,
+        literalSuffix: suffix || undefined
+    };
+};
+const formatNumber = (value, info, locale)=>{
+    const adjusted = info.percent ? value * 100 : value;
+    const { decimal, group } = getLocaleNumberInfo(locale);
+    const absValue = Math.abs(adjusted);
+    const fixed = absValue.toFixed(info.fractionDigits);
+    const [integerPart, fractionPart] = fixed.split('.');
+    const grouped = info.useGrouping ? integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, group) : integerPart;
+    const fraction = info.fractionDigits > 0 ? `${decimal}${fractionPart}` : '';
+    const signed = adjusted < 0 ? '-' : '';
+    let result = `${signed}${grouped}${fraction}`;
+    if (info.literalPrefix) {
+        result = `${info.literalPrefix}${result}`;
+    }
+    if (info.literalSuffix) {
+        result = `${result}${info.literalSuffix}`;
+    }
+    return normalizeSpaces(result);
+};
+const padNumber = (value, length)=>{
+    const str = String(value);
+    return str.length >= length ? str : `${'0'.repeat(length - str.length)}${str}`;
+};
+const formatDatePart = (value, token, locale)=>{
+    switch(token){
+        case 'yyyy':
+            return String(value.getFullYear());
+        case 'yy':
+            return padNumber(value.getFullYear() % 100, 2);
+        case 'mmmm':
+            return value.toLocaleString(locale, {
+                month: 'long'
+            });
+        case 'mmm':
+            return value.toLocaleString(locale, {
+                month: 'short'
+            });
+        case 'mm':
+            return padNumber(value.getMonth() + 1, 2);
+        case 'm':
+            return String(value.getMonth() + 1);
+        case 'dd':
+            return padNumber(value.getDate(), 2);
+        case 'd':
+            return String(value.getDate());
+        case 'hh':
+            {
+                const hours = value.getHours();
+                return padNumber(hours, 2);
+            }
+        case 'h':
+            return String(value.getHours());
+        case 'min2':
+            return padNumber(value.getMinutes(), 2);
+        case 'min1':
+            return String(value.getMinutes());
+        case 'ss':
+            return padNumber(value.getSeconds(), 2);
+        case 's':
+            return String(value.getSeconds());
+        default:
+            return token;
+    }
+};
+const tokenizeDateFormat = (format)=>{
+    const tokens = [];
+    let i = 0;
+    while(i < format.length){
+        const ch = format[i];
+        if (ch === '"') {
+            let literal = '';
+            i++;
+            while(i < format.length && format[i] !== '"'){
+                literal += format[i];
+                i++;
+            }
+            i++;
+            if (literal) tokens.push(literal);
+            continue;
+        }
+        if (ch === '\\' && i + 1 < format.length) {
+            tokens.push(format[i + 1]);
+            i += 2;
+            continue;
+        }
+        if (ch === '[') {
+            const end = format.indexOf(']', i + 1);
+            if (end !== -1) {
+                i = end + 1;
+                continue;
+            }
+        }
+        const lower = format.slice(i).toLowerCase();
+        const match = [
+            'yyyy',
+            'yy',
+            'mmmm',
+            'mmm',
+            'mm',
+            'm',
+            'dd',
+            'd',
+            'hh',
+            'h',
+            'ss',
+            's'
+        ].find((t)=>lower.startsWith(t));
+        if (match) {
+            if (match === 'm' || match === 'mm') {
+                let j = i - 1;
+                let previousChar = '';
+                while(j >= 0 && previousChar === ''){
+                    const candidate = format[j];
+                    if (candidate && candidate !== ' ') {
+                        previousChar = candidate;
+                    }
+                    j--;
+                }
+                const isMinute = previousChar === 'h' || previousChar === 'H' || previousChar === ':';
+                if (isMinute) {
+                    tokens.push(match === 'mm' ? 'min2' : 'min1');
+                    i += match.length;
+                    continue;
+                }
+            }
+            tokens.push(match);
+            i += match.length;
+            continue;
+        }
+        tokens.push(ch);
+        i++;
+    }
+    return tokens;
+};
+const isDateFormat = (format)=>{
+    const lowered = format.toLowerCase();
+    return /[ymdhss]/.test(lowered);
+};
+const formatDate = (value, format, locale)=>{
+    const tokens = tokenizeDateFormat(format);
+    return tokens.map((token)=>formatDatePart(value, token, locale)).join('');
+};
+const formatCellValue = (value, style, locale)=>{
+    const numberFormat = style?.numberFormat;
+    if (!numberFormat) return null;
+    const normalizedLocale = locale || DEFAULT_LOCALE;
+    const sections = splitFormatSections(numberFormat);
+    const hasNegativeSection = sections.length > 1;
+    const section = value instanceof Date ? sections[0] : value < 0 ? sections[1] ?? sections[0] : sections[0];
+    if (value instanceof Date && isDateFormat(section)) {
+        return formatDate(value, section, normalizedLocale);
+    }
+    if (typeof value === 'number') {
+        const info = parseNumberFormat(section);
+        if (!info) return null;
+        const numericValue = value < 0 && hasNegativeSection ? Math.abs(value) : value;
+        return formatNumber(numericValue, info, normalizedLocale);
+    }
+    return null;
+};
+
 // Excel epoch: December 30, 1899 (accounting for the 1900 leap year bug)
 const EXCEL_EPOCH = new Date(Date.UTC(1899, 11, 30));
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
@@ -306,12 +634,21 @@ const ERROR_TYPES = new Set([
     /**
    * Get the formatted text (as displayed in Excel)
    */ get text() {
+        return this.textWithLocale();
+    }
+    /**
+   * Get the formatted text using a specific locale
+   */ textWithLocale(locale) {
         if (this._data.w) {
             return this._data.w;
         }
         const val = this.value;
         if (val === null) return '';
         if (typeof val === 'object' && 'error' in val) return val.error;
+        if (val instanceof Date || typeof val === 'number') {
+            const formatted = formatCellValue(val, this.style, locale ?? this._worksheet.workbook.locale);
+            if (formatted !== null) return formatted;
+        }
         if (val instanceof Date) return val.toISOString().split('T')[0];
         return String(val);
     }
@@ -409,38 +746,38 @@ const ERROR_TYPES = new Set([
 
 var _computedKey;
 _computedKey = Symbol.iterator;
-/**
- * Represents a range of cells in a worksheet
+/**
+ * Represents a range of cells in a worksheet
  */ class Range {
     constructor(worksheet, range){
         this._worksheet = worksheet;
         this._range = normalizeRange(range);
     }
-    /**
-   * Get the range address as a string
+    /**
+   * Get the range address as a string
    */ get address() {
         const start = toAddress(this._range.start.row, this._range.start.col);
         const end = toAddress(this._range.end.row, this._range.end.col);
         if (start === end) return start;
         return `${start}:${end}`;
     }
-    /**
-   * Get the number of rows in the range
+    /**
+   * Get the number of rows in the range
    */ get rowCount() {
         return this._range.end.row - this._range.start.row + 1;
     }
-    /**
-   * Get the number of columns in the range
+    /**
+   * Get the number of columns in the range
    */ get colCount() {
         return this._range.end.col - this._range.start.col + 1;
     }
-    /**
-   * Get all values in the range as a 2D array
+    /**
+   * Get all values in the range as a 2D array
    */ get values() {
         return this.getValues();
     }
-    /**
-   * Get all values in the range as a 2D array with options
+    /**
+   * Get all values in the range as a 2D array with options
    */ getValues(options = {}) {
         const { createMissing = true } = options;
         const result = [];
@@ -459,8 +796,8 @@ _computedKey = Symbol.iterator;
         }
         return result;
     }
-    /**
-   * Set values in the range from a 2D array
+    /**
+   * Set values in the range from a 2D array
    */ set values(data) {
         for(let r = 0; r < data.length && r < this.rowCount; r++){
             const row = data[r];
@@ -470,8 +807,8 @@ _computedKey = Symbol.iterator;
             }
         }
     }
-    /**
-   * Get all formulas in the range as a 2D array
+    /**
+   * Get all formulas in the range as a 2D array
    */ get formulas() {
         const result = [];
         for(let r = this._range.start.row; r <= this._range.end.row; r++){
@@ -484,8 +821,8 @@ _computedKey = Symbol.iterator;
         }
         return result;
     }
-    /**
-   * Set formulas in the range from a 2D array
+    /**
+   * Set formulas in the range from a 2D array
    */ set formulas(data) {
         for(let r = 0; r < data.length && r < this.rowCount; r++){
             const row = data[r];
@@ -495,13 +832,13 @@ _computedKey = Symbol.iterator;
             }
         }
     }
-    /**
-   * Get the style of the top-left cell
+    /**
+   * Get the style of the top-left cell
    */ get style() {
         return this._worksheet.cell(this._range.start.row, this._range.start.col).style;
     }
-    /**
-   * Set style for all cells in the range
+    /**
+   * Set style for all cells in the range
    */ set style(style) {
         for(let r = this._range.start.row; r <= this._range.end.row; r++){
             for(let c = this._range.start.col; c <= this._range.end.col; c++){
@@ -510,8 +847,8 @@ _computedKey = Symbol.iterator;
             }
         }
     }
-    /**
-   * Iterate over all cells in the range
+    /**
+   * Iterate over all cells in the range
    */ *[_computedKey]() {
         for(let r = this._range.start.row; r <= this._range.end.row; r++){
             for(let c = this._range.start.col; c <= this._range.end.col; c++){
@@ -519,8 +856,8 @@ _computedKey = Symbol.iterator;
             }
         }
     }
-    /**
-   * Iterate over cells row by row
+    /**
+   * Iterate over cells row by row
    */ *rows() {
         for(let r = this._range.start.row; r <= this._range.end.row; r++){
             const row = [];
@@ -558,19 +895,19 @@ const builderOptions = {
 };
 const parser = new fastXmlParser.XMLParser(parserOptions);
 const builder = new fastXmlParser.XMLBuilder(builderOptions);
-/**
- * Parses an XML string into a JavaScript object
- * Preserves element order and attributes for round-trip compatibility
+/**
+ * Parses an XML string into a JavaScript object
+ * Preserves element order and attributes for round-trip compatibility
  */ const parseXml = (xml)=>{
     return parser.parse(xml);
 };
-/**
- * Converts a JavaScript object back to an XML string
+/**
+ * Converts a JavaScript object back to an XML string
  */ const stringifyXml = (obj)=>{
     return builder.build(obj);
 };
-/**
- * Finds the first element with the given tag name in the XML tree
+/**
+ * Finds the first element with the given tag name in the XML tree
  */ const findElement = (nodes, tagName)=>{
     for (const node of nodes){
         if (tagName in node) {
@@ -579,8 +916,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
     return undefined;
 };
-/**
- * Gets the children of an element
+/**
+ * Gets the children of an element
  */ const getChildren = (node, tagName)=>{
     const children = node[tagName];
     if (Array.isArray(children)) {
@@ -588,14 +925,14 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
     return [];
 };
-/**
- * Gets an attribute value from a node
+/**
+ * Gets an attribute value from a node
  */ const getAttr = (node, name)=>{
     const attrs = node[':@'];
     return attrs?.[`@_${name}`];
 };
-/**
- * Creates a new XML element
+/**
+ * Creates a new XML element
  */ const createElement = (tagName, attrs, children)=>{
     const node = {
         [tagName]: children || []
@@ -609,17 +946,17 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
     return node;
 };
-/**
- * Creates a text node
+/**
+ * Creates a text node
  */ const createText = (text)=>{
     return {
         '#text': text
     };
 };
 
-/**
- * Maps table total function names to SUBTOTAL function numbers
- * SUBTOTAL uses 101-111 for functions that ignore hidden values
+/**
+ * Maps table total function names to SUBTOTAL function numbers
+ * SUBTOTAL uses 101-111 for functions that ignore hidden values
  */ const TOTAL_FUNCTION_NUMBERS = {
     average: 101,
     count: 102,
@@ -631,8 +968,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     var: 110,
     none: 0
 };
-/**
- * Maps table total function names to XML attribute values
+/**
+ * Maps table total function names to XML attribute values
  */ const TOTAL_FUNCTION_NAMES = {
     average: 'average',
     count: 'count',
@@ -644,8 +981,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     var: 'var',
     none: 'none'
 };
-/**
- * Represents an Excel Table (ListObject) with auto-filter, banded styling, and total row.
+/**
+ * Represents an Excel Table (ListObject) with auto-filter, banded styling, and total row.
  */ class Table {
     constructor(worksheet, config, tableId){
         this._columns = [];
@@ -681,80 +1018,80 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         // Extract column names from worksheet headers
         this._extractColumns();
     }
-    /**
-   * Get the table name
+    /**
+   * Get the table name
    */ get name() {
         return this._name;
     }
-    /**
-   * Get the table display name
+    /**
+   * Get the table display name
    */ get displayName() {
         return this._displayName;
     }
-    /**
-   * Get the table ID
+    /**
+   * Get the table ID
    */ get id() {
         return this._id;
     }
-    /**
-   * Get the worksheet this table belongs to
+    /**
+   * Get the worksheet this table belongs to
    */ get worksheet() {
         return this._worksheet;
     }
-    /**
-   * Get the table range address string
+    /**
+   * Get the table range address string
    */ get range() {
         return toRange(this._range);
     }
-    /**
-   * Get the base range excluding total row
+    /**
+   * Get the base range excluding total row
    */ get baseRange() {
         return toRange(this._baseRange);
     }
-    /**
-   * Get the table range as RangeAddress
+    /**
+   * Get the table range as RangeAddress
    */ get rangeAddress() {
         return {
             ...this._range
         };
     }
-    /**
-   * Get column names
+    /**
+   * Get column names
    */ get columns() {
         return this._columns.map((c)=>c.name);
     }
-    /**
-   * Check if table has a total row
+    /**
+   * Check if table has a total row
    */ get hasTotalRow() {
         return this._totalRow;
     }
-    /**
-   * Check if table has a header row
+    /**
+   * Check if table has a header row
    */ get hasHeaderRow() {
         return this._headerRow;
     }
-    /**
-   * Check if table has auto-filter enabled
+    /**
+   * Check if table has auto-filter enabled
    */ get hasAutoFilter() {
         return this._autoFilter;
     }
-    /**
-   * Get the current style configuration
+    /**
+   * Get the current style configuration
    */ get style() {
         return {
             ...this._style
         };
     }
-    /**
-   * Check if the table has been modified
+    /**
+   * Check if the table has been modified
    */ get dirty() {
         return this._dirty;
     }
-    /**
-   * Set a total function for a column
-   * @param columnName - Name of the column (header text)
-   * @param fn - Aggregation function to use
-   * @returns this for method chaining
+    /**
+   * Set a total function for a column
+   * @param columnName - Name of the column (header text)
+   * @param fn - Aggregation function to use
+   * @returns this for method chaining
    */ setTotalFunction(columnName, fn) {
         if (!this._totalRow) {
             throw new Error('Cannot set total function: table does not have a total row enabled');
@@ -769,25 +1106,25 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._writeTotalRowFormula(column);
         return this;
     }
-    /**
-   * Get total function for a column if set
+    /**
+   * Get total function for a column if set
    */ getTotalFunction(columnName) {
         const column = this._columns.find((c)=>c.name === columnName);
         return column?.totalFunction;
     }
-    /**
-   * Enable or disable auto-filter
-   * @param enabled - Whether auto-filter should be enabled
-   * @returns this for method chaining
+    /**
+   * Enable or disable auto-filter
+   * @param enabled - Whether auto-filter should be enabled
+   * @returns this for method chaining
    */ setAutoFilter(enabled) {
         this._autoFilter = enabled;
         this._dirty = true;
         return this;
     }
-    /**
-   * Update table style configuration
-   * @param style - Style options to apply
-   * @returns this for method chaining
+    /**
+   * Update table style configuration
+   * @param style - Style options to apply
+   * @returns this for method chaining
    */ setStyle(style) {
         if (style.name !== undefined) this._style.name = style.name;
         if (style.showRowStripes !== undefined) this._style.showRowStripes = style.showRowStripes;
@@ -797,10 +1134,10 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._dirty = true;
         return this;
     }
-    /**
-   * Enable or disable the total row
-   * @param enabled - Whether total row should be shown
-   * @returns this for method chaining
+    /**
+   * Enable or disable the total row
+   * @param enabled - Whether total row should be shown
+   * @returns this for method chaining
    */ setTotalRow(enabled) {
         if (this._totalRow === enabled) return this;
         this._totalRow = enabled;
@@ -830,8 +1167,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return this;
     }
-    /**
-   * Extract column names from the header row of the worksheet
+    /**
+   * Extract column names from the header row of the worksheet
    */ _extractColumns() {
         const headerRow = this._range.start.row;
         const startCol = this._range.start.col;
@@ -847,8 +1184,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             });
         }
     }
-    /**
-   * Write the SUBTOTAL formula to a total row cell
+    /**
+   * Write the SUBTOTAL formula to a total row cell
    */ _writeTotalRowFormula(column) {
         if (!this._totalRow || !column.totalFunction || column.totalFunction === 'none') {
             return;
@@ -861,8 +1198,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         const formula = `SUBTOTAL(${funcNum},[${column.name}])`;
         cell.formula = formula;
     }
-    /**
-   * Get the auto-filter range (excludes total row if present)
+    /**
+   * Get the auto-filter range (excludes total row if present)
    */ _getAutoFilterRange() {
         const start = toAddress(this._range.start.row, this._range.start.col);
         // Auto-filter excludes the total row
@@ -873,8 +1210,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         const end = toAddress(endRow, this._range.end.col);
         return `${start}:${end}`;
     }
-    /**
-   * Generate the table definition XML
+    /**
+   * Generate the table definition XML
    */ toXml() {
         const children = [];
         // Auto-filter element
@@ -1354,12 +1691,12 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         return table;
     }
     /**
-   * Convert sheet data to an array of JSON objects.
-   *
-   * @param config - Configuration options
-   * @returns Array of objects where keys are field names and values are cell values
+   * Convert sheet data to an array of JSON objects.
    *
-   * @example
+   * @param config - Configuration options
+   * @returns Array of objects where keys are field names and values are cell values
+   *
+   * @example
    * ```typescript
    * // Using first row as headers
    * const data = sheet.toJson();
@@ -1368,10 +1705,10 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
    * const data = sheet.toJson({ fields: ['name', 'age', 'city'] });
    *
    * // Starting from a specific row/column
-   * const data = sheet.toJson({ startRow: 2, startCol: 1 });
-   * ```
+   * const data = sheet.toJson({ startRow: 2, startCol: 1 });
+   * ```
    */ toJson(config = {}) {
-        const { fields, startRow = 0, startCol = 0, endRow, endCol, stopOnEmptyRow = true, dateHandling = this._workbook.dateHandling, asText = false } = config;
+        const { fields, startRow = 0, startCol = 0, endRow, endCol, stopOnEmptyRow = true, dateHandling = this._workbook.dateHandling, asText = false, locale } = config;
         // Get the bounds of data in the sheet
         const bounds = this._getDataBounds();
         if (!bounds) {
@@ -1407,7 +1744,7 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
                 let value;
                 if (asText) {
                     // Return formatted text instead of raw value
-                    value = cell?.text ?? '';
+                    value = cell?.textWithLocale(locale) ?? '';
                     if (value !== '') {
                         hasData = true;
                     }
@@ -1748,12 +2085,12 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
 }
 
-/**
- * Manages the shared strings table from xl/sharedStrings.xml
- * Excel stores strings in a shared table to reduce file size
+/**
+ * Manages the shared strings table from xl/sharedStrings.xml
+ * Excel stores strings in a shared table to reduce file size
  */ class SharedStrings {
-    /**
-   * Parse shared strings from XML content
+    /**
+   * Parse shared strings from XML content
    */ static parse(xml) {
         const ss = new SharedStrings();
         const parsed = parseXml(xml);
@@ -1783,9 +2120,9 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return ss;
     }
-    /**
-   * Extract text from a string item (si element)
-   * Handles both simple <t> elements and rich text <r> elements
+    /**
+   * Extract text from a string item (si element)
+   * Handles both simple <t> elements and rich text <r> elements
    */ extractText(nodes) {
         let text = '';
         for (const node of nodes){
@@ -1814,14 +2151,14 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return text;
     }
-    /**
-   * Get a string by index
+    /**
+   * Get a string by index
    */ getString(index) {
         return this.entries[index]?.text;
     }
-    /**
-   * Add a string and return its index
-   * If the string already exists, returns the existing index
+    /**
+   * Add a string and return its index
+   * If the string already exists, returns the existing index
    */ addString(str) {
         const existing = this.stringToIndex.get(str);
         if (existing !== undefined) {
@@ -1847,23 +2184,23 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._dirty = true;
         return index;
     }
-    /**
-   * Check if the shared strings table has been modified
+    /**
+   * Check if the shared strings table has been modified
    */ get dirty() {
         return this._dirty;
     }
-    /**
-   * Get the count of strings
+    /**
+   * Get the count of strings
    */ get count() {
         return this.entries.length;
     }
-    /**
-   * Get total usage count of shared strings
+    /**
+   * Get total usage count of shared strings
    */ get totalCount() {
         return Math.max(this._totalCount, this.entries.length);
     }
-    /**
-   * Generate XML for the shared strings table
+    /**
+   * Generate XML for the shared strings table
    */ toXml() {
         const siElements = [];
         for (const entry of this.entries){
@@ -1900,9 +2237,9 @@ 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.
+/**
+ * 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',
@@ -2017,15 +2354,15 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         49
     ]
 ]);
-/**
- * Reverse lookup: built-in format ID -> format code
+/**
+ * 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"
+/**
+ * Normalize a color to ARGB format (8 hex chars).
+ * Accepts: "#RGB", "#RRGGBB", "RGB", "RRGGBB", "AARRGGBB", "#AARRGGBB"
  */ const normalizeColor = (color)=>{
     let c = color.replace(/^#/, '').toUpperCase();
     // Handle shorthand 3-char format (e.g., "FFF" -> "FFFFFF")
@@ -2038,14 +2375,14 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
     return c;
 };
-/**
- * Manages the styles (xl/styles.xml)
+/**
+ * Manages the styles (xl/styles.xml)
  */ class Styles {
-    /**
-   * Generate a deterministic cache key for a style object.
-   * More efficient than JSON.stringify as it avoids the overhead of
-   * full JSON serialization and produces a consistent key regardless
-   * of property order.
+    /**
+   * Generate a deterministic cache key for a style object.
+   * More efficient than JSON.stringify as it avoids the overhead of
+   * full JSON serialization and produces a consistent key regardless
+   * of property order.
    */ _getStyleKey(style) {
         // Use a delimiter that won't appear in values
         const SEP = '\x00';
@@ -2085,8 +2422,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return parts.join(SEP);
     }
-    /**
-   * Parse styles from XML content
+    /**
+   * Parse styles from XML content
    */ static parse(xml) {
         const styles = new Styles();
         styles._xmlNodes = parseXml(xml);
@@ -2142,8 +2479,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return styles;
     }
-    /**
-   * Create an empty styles object with defaults
+    /**
+   * Create an empty styles object with defaults
    */ static createDefault() {
         const styles = new Styles();
         // Default font (Calibri 11)
@@ -2282,8 +2619,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             textRotation: parseInt(getAttr(alignNode, 'textRotation') || '0', 10)
         };
     }
-    /**
-   * Get a style by index
+    /**
+   * Get a style by index
    */ getStyle(index) {
         const cached = this._styleObjectCache.get(index);
         if (cached) return {
@@ -2347,9 +2684,9 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         });
         return style;
     }
-    /**
-   * Create a style and return its index
-   * Uses caching to deduplicate identical styles
+    /**
+   * Create a style and return its index
+   * Uses caching to deduplicate identical styles
    */ createStyle(style) {
         const key = this._getStyleKey(style);
         const cached = this._styleCache.get(key);
@@ -2388,8 +2725,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         });
         return index;
     }
-    /**
-   * Clone an existing style by index, optionally overriding fields.
+    /**
+   * Clone an existing style by index, optionally overriding fields.
    */ cloneStyle(index, overrides = {}) {
         const baseStyle = this.getStyle(index);
         return this.createStyle({
@@ -2473,21 +2810,21 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         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')
+    /**
+   * 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
+    /**
+   * Check if styles have been modified
    */ get dirty() {
         return this._dirty;
     }
-    /**
-   * Generate XML for styles
+    /**
+   * Generate XML for styles
    */ toXml() {
         const children = [];
         // Number formats
@@ -2687,8 +3024,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
 }
 
-/**
- * Represents an Excel pivot table with a fluent API for configuration.
+/**
+ * Represents an Excel pivot table with a fluent API for configuration.
  */ class PivotTable {
     constructor(name, cache, targetSheet, targetCell, targetRow, targetCol, pivotTableIndex, cacheFileIndex){
         this._rowFields = [];
@@ -2706,47 +3043,47 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._pivotTableIndex = pivotTableIndex;
         this._cacheFileIndex = cacheFileIndex;
     }
-    /**
-   * Get the pivot table name
+    /**
+   * Get the pivot table name
    */ get name() {
         return this._name;
     }
-    /**
-   * Get the target sheet name
+    /**
+   * Get the target sheet name
    */ get targetSheet() {
         return this._targetSheet;
     }
-    /**
-   * Get the target cell address
+    /**
+   * Get the target cell address
    */ get targetCell() {
         return this._targetCell;
     }
-    /**
-   * Get the pivot cache
+    /**
+   * Get the pivot cache
    */ get cache() {
         return this._cache;
     }
-    /**
-   * Get the pivot table index (for file naming)
+    /**
+   * Get the pivot table index (for file naming)
    */ get index() {
         return this._pivotTableIndex;
     }
-    /**
-   * Get the pivot cache file index used for rels.
-   * @internal
+    /**
+   * Get the pivot cache file index used for rels.
+   * @internal
    */ get cacheFileIndex() {
         return this._cacheFileIndex;
     }
-    /**
-   * Set the styles reference for number format resolution
-   * @internal
+    /**
+   * 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)
+    /**
+   * Add a field to the row area
+   * @param fieldName - Name of the source field (column header)
    */ addRowField(fieldName) {
         const fieldIndex = this._cache.getFieldIndex(fieldName);
         if (fieldIndex < 0) {
@@ -2761,9 +3098,9 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._fieldAssignments.set(fieldIndex, assignment);
         return this;
     }
-    /**
-   * Add a field to the column area
-   * @param fieldName - Name of the source field (column header)
+    /**
+   * Add a field to the column area
+   * @param fieldName - Name of the source field (column header)
    */ addColumnField(fieldName) {
         const fieldIndex = this._cache.getFieldIndex(fieldName);
         if (fieldIndex < 0) {
@@ -2817,9 +3154,9 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._fieldAssignments.set(fieldIndex, assignment);
         return this;
     }
-    /**
-   * Add a field to the filter (page) area
-   * @param fieldName - Name of the source field (column header)
+    /**
+   * Add a field to the filter (page) area
+   * @param fieldName - Name of the source field (column header)
    */ addFilterField(fieldName) {
         const fieldIndex = this._cache.getFieldIndex(fieldName);
         if (fieldIndex < 0) {
@@ -2834,10 +3171,10 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._fieldAssignments.set(fieldIndex, assignment);
         return this;
     }
-    /**
-   * Set a sort order for a row or column field
-   * @param fieldName - Name of the field to sort
-   * @param order - Sort order ('asc' or 'desc')
+    /**
+   * Set a sort order for a row or column field
+   * @param fieldName - Name of the field to sort
+   * @param order - Sort order ('asc' or 'desc')
    */ sortField(fieldName, order) {
         const fieldIndex = this._cache.getFieldIndex(fieldName);
         if (fieldIndex < 0) {
@@ -2853,10 +3190,10 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         assignment.sortOrder = order;
         return this;
     }
-    /**
-   * Filter items for a row, column, or filter field
-   * @param fieldName - Name of the field to filter
-   * @param filter - Filter configuration with include or exclude list
+    /**
+   * Filter items for a row, column, or filter field
+   * @param fieldName - Name of the field to filter
+   * @param filter - Filter configuration with include or exclude list
    */ filterField(fieldName, filter) {
         const fieldIndex = this._cache.getFieldIndex(fieldName);
         if (fieldIndex < 0) {
@@ -2872,8 +3209,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         assignment.filter = filter;
         return this;
     }
-    /**
-   * Generate the pivotTableDefinition XML
+    /**
+   * Generate the pivotTableDefinition XML
    */ toXml() {
         const children = [];
         // Calculate location (estimate based on fields)
@@ -3033,8 +3370,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             pivotTableNode
         ])}`;
     }
-    /**
-   * Build a pivotField node for a given field index
+    /**
+   * Build a pivotField node for a given field index
    */ _buildPivotFieldNode(fieldIndex) {
         const attrs = {};
         const children = [];
@@ -3092,8 +3429,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return createElement('pivotField', attrs, children);
     }
-    /**
-   * Build item nodes for a pivot field, with optional filtering
+    /**
+   * Build item nodes for a pivot field, with optional filtering
    */ _buildItemNodes(sharedItems, filter) {
         const itemNodes = [];
         for(let i = 0; i < sharedItems.length; i++){
@@ -3121,8 +3458,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }, []));
         return itemNodes;
     }
-    /**
-   * Build row items based on unique values in row fields
+    /**
+   * Build row items based on unique values in row fields
    */ _buildRowItems() {
         const items = [];
         if (this._rowFields.length === 0) return items;
@@ -3146,8 +3483,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         ]));
         return items;
     }
-    /**
-   * Build column items based on unique values in column fields
+    /**
+   * Build column items based on unique values in column fields
    */ _buildColItems() {
         const items = [];
         if (this._columnFields.length === 0) return items;
@@ -3204,8 +3541,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return items;
     }
-    /**
-   * Calculate the location reference for the pivot table output
+    /**
+   * Calculate the location reference for the pivot table output
    */ _calculateLocationRef() {
         // Estimate output size based on fields
         const numRows = this._estimateRowCount();
@@ -3216,8 +3553,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         const endCol = startCol + numCols - 1;
         return `${this._colToLetter(startCol)}${startRow}:${this._colToLetter(endCol)}${endRow}`;
     }
-    /**
-   * Estimate number of rows in pivot table output
+    /**
+   * Estimate number of rows in pivot table output
    */ _estimateRowCount() {
         let count = 1; // Header row
         // Add filter area rows
@@ -3232,8 +3569,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return Math.max(count, 3);
     }
-    /**
-   * Estimate number of columns in pivot table output
+    /**
+   * Estimate number of columns in pivot table output
    */ _estimateColCount() {
         let count = 0;
         // Row label columns
@@ -3249,8 +3586,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return Math.max(count, 2);
     }
-    /**
-   * Convert 0-based column index to letter (A, B, ..., Z, AA, etc.)
+    /**
+   * Convert 0-based column index to letter (A, B, ..., Z, AA, etc.)
    */ _colToLetter(col) {
         let result = '';
         let n = col;
@@ -3262,9 +3599,9 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     }
 }
 
-/**
- * Manages the pivot cache (definition and records) for a pivot table.
- * The cache stores source data metadata and cached values.
+/**
+ * Manages the pivot cache (definition and records) for a pivot table.
+ * The cache stores source data metadata and cached values.
  */ class PivotCache {
     constructor(cacheId, sourceSheet, sourceRange, fileIndex){
         this._fields = [];
@@ -3278,55 +3615,55 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._sourceSheet = sourceSheet;
         this._sourceRange = sourceRange;
     }
-    /**
-   * Get the cache ID
+    /**
+   * Get the cache ID
    */ get cacheId() {
         return this._cacheId;
     }
-    /**
-   * Get the file index for this cache (used for file naming).
+    /**
+   * Get the file index for this cache (used for file naming).
    */ get fileIndex() {
         return this._fileIndex;
     }
-    /**
-   * Set refreshOnLoad option
+    /**
+   * Set refreshOnLoad option
    */ set refreshOnLoad(value) {
         this._refreshOnLoad = value;
     }
-    /**
-   * Get refreshOnLoad option
+    /**
+   * Get refreshOnLoad option
    */ get refreshOnLoad() {
         return this._refreshOnLoad;
     }
-    /**
-   * Get the source sheet name
+    /**
+   * Get the source sheet name
    */ get sourceSheet() {
         return this._sourceSheet;
     }
-    /**
-   * Get the source range
+    /**
+   * Get the source range
    */ get sourceRange() {
         return this._sourceRange;
     }
-    /**
-   * Get the full source reference (Sheet!Range)
+    /**
+   * Get the full source reference (Sheet!Range)
    */ get sourceRef() {
         return `${this._sourceSheet}!${this._sourceRange}`;
     }
-    /**
-   * Get the fields in this cache
+    /**
+   * Get the fields in this cache
    */ get fields() {
         return this._fields;
     }
-    /**
-   * Get the number of data records
+    /**
+   * Get the number of data records
    */ get recordCount() {
         return this._recordCount;
     }
-    /**
-   * Build the cache from source data.
-   * @param headers - Array of column header names
-   * @param data - 2D array of data rows (excluding headers)
+    /**
+   * Build the cache from source data.
+   * @param headers - Array of column header names
+   * @param data - 2D array of data rows (excluding headers)
    */ buildFromData(headers, data) {
         this._recordCount = data.length;
         // Initialize fields from headers
@@ -3387,19 +3724,19 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         // Store records
         this._records = data;
     }
-    /**
-   * Get field by name
+    /**
+   * Get field by name
    */ getField(name) {
         return this._fields.find((f)=>f.name === name);
     }
-    /**
-   * Get field index by name
+    /**
+   * Get field index by name
    */ getFieldIndex(name) {
         const field = this._fields.find((f)=>f.name === name);
         return field ? field.index : -1;
     }
-    /**
-   * Generate the pivotCacheDefinition XML
+    /**
+   * Generate the pivotCacheDefinition XML
    */ toDefinitionXml(recordsRelId) {
         const cacheFieldNodes = this._fields.map((field)=>{
             const sharedItemsAttrs = {};
@@ -3471,8 +3808,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             definitionNode
         ])}`;
     }
-    /**
-   * Generate the pivotCacheRecords XML
+    /**
+   * Generate the pivotCacheRecords XML
    */ toRecordsXml() {
         const recordNodes = [];
         for (const row of this._records){
@@ -3577,8 +3914,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
     files.set(path, fflate.strToU8(content));
 };
 
-/**
- * Represents an Excel workbook (.xlsx file)
+/**
+ * Represents an Excel workbook (.xlsx file)
  */ class Workbook {
     constructor(){
         this._files = new Map();
@@ -3595,17 +3932,18 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._nextTableId = 1;
         // Date serialization handling
         this._dateHandling = 'jsDate';
+        this._locale = 'fr-FR';
         this._sharedStrings = new SharedStrings();
         this._styles = Styles.createDefault();
     }
-    /**
-   * Load a workbook from a file path
+    /**
+   * Load a workbook from a file path
    */ static async fromFile(path) {
         const data = await promises.readFile(path);
         return Workbook.fromBuffer(new Uint8Array(data));
     }
-    /**
-   * Load a workbook from a buffer
+    /**
+   * Load a workbook from a buffer
    */ static async fromBuffer(data) {
         const workbook = new Workbook();
         workbook._files = await readZip(data);
@@ -3631,52 +3969,62 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return workbook;
     }
-    /**
-   * Create a new empty workbook
+    /**
+   * Create a new empty workbook
    */ static create() {
         const workbook = new Workbook();
         workbook._dirty = true;
         return workbook;
     }
-    /**
-   * Get sheet names
+    /**
+   * Get sheet names
    */ get sheetNames() {
         return this._sheetDefs.map((s)=>s.name);
     }
-    /**
-   * Get number of sheets
+    /**
+   * Get number of sheets
    */ get sheetCount() {
         return this._sheetDefs.length;
     }
-    /**
-   * Get shared strings table
+    /**
+   * Get shared strings table
    */ get sharedStrings() {
         return this._sharedStrings;
     }
-    /**
-   * Get styles
+    /**
+   * Get styles
    */ get styles() {
         return this._styles;
     }
-    /**
-   * Get the workbook date handling strategy.
+    /**
+   * Get the workbook date handling strategy.
    */ get dateHandling() {
         return this._dateHandling;
     }
-    /**
-   * Set the workbook date handling strategy.
+    /**
+   * Set the workbook date handling strategy.
    */ set dateHandling(value) {
         this._dateHandling = value;
     }
-    /**
-   * Get the next unique table ID for this workbook.
-   * Table IDs must be unique across all worksheets.
-   * @internal
+    /**
+   * Get the workbook locale for formatting.
+   */ get locale() {
+        return this._locale;
+    }
+    /**
+   * Set the workbook locale for formatting.
+   */ set locale(value) {
+        this._locale = value;
+    }
+    /**
+   * Get the next unique table ID for this workbook.
+   * Table IDs must be unique across all worksheets.
+   * @internal
    */ getNextTableId() {
         return this._nextTableId++;
     }
-    /**
-   * Get a worksheet by name or index
+    /**
+   * Get a worksheet by name or index
    */ sheet(nameOrIndex) {
         let def;
         if (typeof nameOrIndex === 'number') {
@@ -3705,8 +4053,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._sheets.set(def.name, worksheet);
         return worksheet;
     }
-    /**
-   * Add a new worksheet
+    /**
+   * Add a new worksheet
    */ addSheet(name, index) {
         // Check for duplicate name
         if (this._sheetDefs.some((s)=>s.name === name)) {
@@ -3738,8 +4086,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._sheets.set(name, worksheet);
         return worksheet;
     }
-    /**
-   * Delete a worksheet by name or index
+    /**
+   * Delete a worksheet by name or index
    */ deleteSheet(nameOrIndex) {
         let index;
         if (typeof nameOrIndex === 'number') {
@@ -3768,8 +4116,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             this._relationships.splice(relIndex, 1);
         }
     }
-    /**
-   * Rename a worksheet
+    /**
+   * Rename a worksheet
    */ renameSheet(oldName, newName) {
         const def = this._sheetDefs.find((s)=>s.name === oldName);
         if (!def) {
@@ -3788,8 +4136,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         def.name = newName;
     }
-    /**
-   * Copy a worksheet
+    /**
+   * Copy a worksheet
    */ copySheet(sourceName, newName) {
         const source = this.sheet(sourceName);
         const copy = this.addSheet(newName);
@@ -3874,49 +4222,49 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return false;
     }
-    /**
-   * Create a new worksheet from an array of objects.
-   *
-   * The first row contains headers (object keys or custom column headers),
-   * and subsequent rows contain the object values.
-   *
-   * @param config - Configuration for the sheet creation
-   * @returns The created Worksheet
-   *
-   * @example
-   * ```typescript
-   * const data = [
-   *   { name: 'Alice', age: 30, city: 'Paris' },
-   *   { name: 'Bob', age: 25, city: 'London' },
-   *   { name: 'Charlie', age: 35, city: 'Berlin' },
-   * ];
-   *
-   * // Simple usage - all object keys become columns
-   * const sheet = wb.addSheetFromData({
-   *   name: 'People',
-   *   data: data,
-   * });
-   *
-   * // With custom column configuration
-   * const sheet2 = wb.addSheetFromData({
-   *   name: 'People Custom',
-   *   data: data,
-   *   columns: [
-   *     { key: 'name', header: 'Full Name' },
-   *     { key: 'age', header: 'Age (years)' },
-   *   ],
-   * });
-   *
-   * // With rich cell values (value, formula, style)
-   * const dataWithFormulas = [
-   *   { product: 'Widget', price: 10, qty: 5, total: { formula: 'B2*C2', style: { bold: true } } },
-   *   { product: 'Gadget', price: 20, qty: 3, total: { formula: 'B3*C3', style: { bold: true } } },
-   * ];
-   * const sheet3 = wb.addSheetFromData({
-   *   name: 'With Formulas',
-   *   data: dataWithFormulas,
-   * });
-   * ```
+    /**
+   * Create a new worksheet from an array of objects.
+   *
+   * The first row contains headers (object keys or custom column headers),
+   * and subsequent rows contain the object values.
+   *
+   * @param config - Configuration for the sheet creation
+   * @returns The created Worksheet
+   *
+   * @example
+   * ```typescript
+   * const data = [
+   *   { name: 'Alice', age: 30, city: 'Paris' },
+   *   { name: 'Bob', age: 25, city: 'London' },
+   *   { name: 'Charlie', age: 35, city: 'Berlin' },
+   * ];
+   *
+   * // Simple usage - all object keys become columns
+   * const sheet = wb.addSheetFromData({
+   *   name: 'People',
+   *   data: data,
+   * });
+   *
+   * // With custom column configuration
+   * const sheet2 = wb.addSheetFromData({
+   *   name: 'People Custom',
+   *   data: data,
+   *   columns: [
+   *     { key: 'name', header: 'Full Name' },
+   *     { key: 'age', header: 'Age (years)' },
+   *   ],
+   * });
+   *
+   * // With rich cell values (value, formula, style)
+   * const dataWithFormulas = [
+   *   { product: 'Widget', price: 10, qty: 5, total: { formula: 'B2*C2', style: { bold: true } } },
+   *   { product: 'Gadget', price: 20, qty: 3, total: { formula: 'B3*C3', style: { bold: true } } },
+   * ];
+   * const sheet3 = wb.addSheetFromData({
+   *   name: 'With Formulas',
+   *   data: dataWithFormulas,
+   * });
+   * ```
    */ addSheetFromData(config) {
         const { name, data, columns, headerStyle = true, startCell = 'A1' } = config;
         if (!data?.length) return this.addSheet(name);
@@ -3971,8 +4319,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         }
         return sheet;
     }
-    /**
-   * Check if a value is a rich cell value object with value, formula, or style fields
+    /**
+   * Check if a value is a rich cell value object with value, formula, or style fields
    */ _isRichCellValue(value) {
         if (value === null || value === undefined) {
             return false;
@@ -3984,15 +4332,15 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         const obj = value;
         return 'value' in obj || 'formula' in obj || 'style' in obj;
     }
-    /**
-   * Infer column configuration from the first data object
+    /**
+   * Infer column configuration from the first data object
    */ _inferColumns(sample) {
         return Object.keys(sample).map((key)=>({
                 key
             }));
     }
-    /**
-   * Convert an unknown value to a CellValue
+    /**
+   * Convert an unknown value to a CellValue
    */ _toCellValue(value) {
         if (value === null || value === undefined) {
             return null;
@@ -4009,25 +4357,25 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         // Convert other types to string
         return String(value);
     }
-    /**
-   * Create a pivot table from source data.
-   *
-   * @param config - Pivot table configuration
-   * @returns PivotTable instance for fluent configuration
-   *
-   * @example
-   * ```typescript
-   * const pivot = wb.createPivotTable({
-   *   name: 'SalesPivot',
-   *   source: 'DataSheet!A1:D100',
-   *   target: 'PivotSheet!A3',
-   * });
-   *
-   * pivot
-   *   .addRowField('Region')
-   *   .addColumnField('Product')
-   *   .addValueField('Sales', 'sum', 'Total Sales');
-   * ```
+    /**
+   * Create a pivot table from source data.
+   *
+   * @param config - Pivot table configuration
+   * @returns PivotTable instance for fluent configuration
+   *
+   * @example
+   * ```typescript
+   * const pivot = wb.createPivotTable({
+   *   name: 'SalesPivot',
+   *   source: 'DataSheet!A1:D100',
+   *   target: 'PivotSheet!A3',
+   * });
+   *
+   * pivot
+   *   .addRowField('Region')
+   *   .addColumnField('Product')
+   *   .addValueField('Sales', 'sum', 'Total Sales');
+   * ```
    */ createPivotTable(config) {
         this._dirty = true;
         // Parse source reference (Sheet!Range)
@@ -4061,8 +4409,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
         this._pivotTables.push(pivotTable);
         return pivotTable;
     }
-    /**
-   * Parse a sheet reference like "Sheet1!A1:D100" into sheet name and range
+    /**
+   * Parse a sheet reference like "Sheet1!A1:D100" into sheet name and range
    */ _parseSheetRef(ref) {
         const match = ref.match(/^(.+?)!(.+)$/);
         if (!match) {
@@ -4073,8 +4421,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             range: match[2]
         };
     }
-    /**
-   * Extract headers and data from a source range
+    /**
+   * Extract headers and data from a source range
    */ _extractSourceData(sheet, rangeStr) {
         const range = parseRange(rangeStr);
         const headers = [];
@@ -4098,14 +4446,14 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             data
         };
     }
-    /**
-   * Save the workbook to a file
+    /**
+   * Save the workbook to a file
    */ async toFile(path) {
         const buffer = await this.toBuffer();
         await promises.writeFile(path, buffer);
     }
-    /**
-   * Save the workbook to a buffer
+    /**
+   * Save the workbook to a buffer
    */ async toBuffer() {
         // Update files map with modified content
         this._updateFiles();
@@ -4419,8 +4767,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             ])}`);
         }
     }
-    /**
-   * Generate all pivot table related files
+    /**
+   * Generate all pivot table related files
    */ _updatePivotTableFiles() {
         // Track which sheets have pivot tables for their .rels files
         const sheetPivotTables = new Map();
@@ -4538,8 +4886,8 @@ const builder = new fastXmlParser.XMLBuilder(builderOptions);
             ])}`);
         }
     }
-    /**
-   * Generate all table related files
+    /**
+   * Generate all table related files
    */ _updateTableFiles() {
         // Collect all tables with their global indices
         let globalTableIndex = 1;