@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/api/immer-utils.js

@@ -0,0 +1,1552 @@
+import { isStaticNode } from "@rowsncolumns/dag";
+import { isCellCoordinate } from "@rowsncolumns/dag";
+import { tokenVocabulary } from "@rowsncolumns/fast-formula-parser";
+import { addressToCell, desanitizeSheetName, getDefaultDateFormat, getDefaultDateTimeFormat, getDefaultTimeFormat, isNil, } from "@rowsncolumns/utils";
+import { defaultCellCoords, SheetCell } from "../sheet-cell";
+import { changeDecimals, getCurrentDecimalCountInPattern, getDecimalPlaces, } from "./decimals";
+export const createSheetDraft = (draft, sheetId, rowIndex) => {
+    // Get sheet reference once
+    let sheet = draft[sheetId];
+    if (!sheet) {
+        sheet = draft[sheetId] = [];
+    }
+    if (!isNil(rowIndex)) {
+        // Direct assignment, single proxy access
+        if (!sheet[rowIndex]?.values) {
+            sheet[rowIndex] = { values: [] };
+        }
+    }
+    return sheet;
+};
+// Clone entire row
+export const cloneRowWithFormatting = (rowData) => {
+    if (!rowData) {
+        return { values: [] };
+    }
+    const sheetCell = new SheetCell();
+    const values = rowData?.values?.map((cellData) => {
+        sheetCell.assign(1, defaultCellCoords, cellData);
+        return sheetCell.cloneWithFormatting().getCellData();
+    });
+    return {
+        values,
+    };
+};
+// Clone cell
+export const cloneCellWithFormatting = (celLData) => {
+    const sheetCell = new SheetCell(1, defaultCellCoords, celLData);
+    return sheetCell.cloneWithFormatting().getCellData();
+};
+/**
+ * "Generic" precedent types — these don't carry styling intent so a
+ * later, more specific format can override them. Used by the
+ * first-specific-wins merging rule in `processPrecedentCell`.
+ */
+const isGenericNumberFormatType = (type) => !type || type === "NUMBER" || type === "GENERAL";
+/**
+ * Date-family types — when the derived (resolved) type is one of these
+ * and the precedent's type is also in this set, we preserve the
+ * precedent's exact custom pattern instead of synthesizing a locale
+ * default. Mirrors Excel's behaviour for date-arithmetic functions
+ * (EDATE, EOMONTH, …) where `=EDATE(A1, 1)` keeps A1's custom pattern.
+ */
+const isDateFamilyType = (type) => type === "DATE" || type === "TIME" || type === "DATE_TIME";
+const customNumberFormatMap = {
+    COUNT: "NUMBER",
+};
+const formatDerivationRules = {
+    SUMIFS: { type: "fixed_index", index: 0 },
+    AVERAGEIFS: { type: "fixed_index", index: 0 },
+    MINIFS: { type: "fixed_index", index: 0 },
+    MAXIFS: { type: "fixed_index", index: 0 },
+    FILTER: { type: "fixed_index", index: 0 },
+    XLOOKUP: { type: "fixed_index", index: 2 },
+    INDEX: { type: "fixed_index", index: 0 },
+    SORT: { type: "fixed_index", index: 0 },
+    SORTBY: { type: "fixed_index", index: 0 },
+    UNIQUE: { type: "fixed_index", index: 0 },
+    TAKE: { type: "fixed_index", index: 0 },
+    DROP: { type: "fixed_index", index: 0 },
+    TOCOL: { type: "fixed_index", index: 0 },
+    TOROW: { type: "fixed_index", index: 0 },
+    WRAPROWS: { type: "fixed_index", index: 0 },
+    WRAPCOLS: { type: "fixed_index", index: 0 },
+    CHOOSECOLS: { type: "fixed_index", index: 0 },
+    CHOOSEROWS: { type: "fixed_index", index: 0 },
+    TRANSPOSE: { type: "fixed_index", index: 0 },
+    SUMIF: {
+        type: "conditional_index",
+        getIndex: (count) => (count >= 3 ? 2 : 0),
+    },
+    AVERAGEIF: {
+        type: "conditional_index",
+        getIndex: (count) => (count >= 3 ? 2 : 0),
+    },
+    VLOOKUP: { type: "vlookup", tableIndex: 1, colIndexArg: 2 },
+    HLOOKUP: { type: "hlookup", tableIndex: 1, rowIndexArg: 2 },
+    // Statistical functions that inherit format from their data array.
+    // Excel renders `MEDIAN(currency_range)` etc. with the data's
+    // format. All take the data array as the first arg.
+    MEDIAN: { type: "fixed_index", index: 0 },
+    MODE: { type: "fixed_index", index: 0 },
+    "MODE.SNGL": { type: "fixed_index", index: 0 },
+    "MODE.MULT": { type: "fixed_index", index: 0 },
+    PERCENTILE: { type: "fixed_index", index: 0 },
+    "PERCENTILE.INC": { type: "fixed_index", index: 0 },
+    "PERCENTILE.EXC": { type: "fixed_index", index: 0 },
+    QUARTILE: { type: "fixed_index", index: 0 },
+    "QUARTILE.INC": { type: "fixed_index", index: 0 },
+    "QUARTILE.EXC": { type: "fixed_index", index: 0 },
+    LARGE: { type: "fixed_index", index: 0 },
+    SMALL: { type: "fixed_index", index: 0 },
+    TRIMMEAN: { type: "fixed_index", index: 0 },
+    GEOMEAN: { type: "fixed_index", index: 0 },
+    HARMEAN: { type: "fixed_index", index: 0 },
+    AVERAGEA: { type: "fixed_index", index: 0 },
+    MINA: { type: "fixed_index", index: 0 },
+    MAXA: { type: "fixed_index", index: 0 },
+    // VAR and STDEV: Excel keeps the data format on display (units are a
+    // formatting concern, not a value-unit concern). VAR is technically
+    // squared, but spreadsheets don't track units — match Excel.
+    VAR: { type: "fixed_index", index: 0 },
+    "VAR.S": { type: "fixed_index", index: 0 },
+    "VAR.P": { type: "fixed_index", index: 0 },
+    VARA: { type: "fixed_index", index: 0 },
+    VARPA: { type: "fixed_index", index: 0 },
+    STDEV: { type: "fixed_index", index: 0 },
+    "STDEV.S": { type: "fixed_index", index: 0 },
+    "STDEV.P": { type: "fixed_index", index: 0 },
+    STDEVA: { type: "fixed_index", index: 0 },
+    STDEVPA: { type: "fixed_index", index: 0 },
+    // FORECAST(x, known_ys, known_xs) — inherits from y values (index 1).
+    FORECAST: { type: "fixed_index", index: 1 },
+    "FORECAST.LINEAR": { type: "fixed_index", index: 1 },
+    "FORECAST.ETS": { type: "fixed_index", index: 1 },
+    // Financial functions — inherit CURRENCY from the principal arg
+    // (matches Excel's behaviour where `=PMT(rate, n, pv)` on a currency
+    // principal renders as currency). Arg positions reference the
+    // standard Excel signatures.
+    PMT: { type: "fixed_index", index: 2 }, // PMT(rate, nper, pv, [fv], [type])
+    PV: { type: "fixed_index", index: 2 }, // PV(rate, nper, pmt, [fv], [type])
+    FV: { type: "fixed_index", index: 2 }, // FV(rate, nper, pmt, [pv], [type])
+    NPV: { type: "fixed_index", index: 1 }, // NPV(rate, value1, ...)
+    XNPV: { type: "fixed_index", index: 1 }, // XNPV(rate, values, dates)
+    IPMT: { type: "fixed_index", index: 3 }, // IPMT(rate, per, nper, pv, [fv], [type])
+    PPMT: { type: "fixed_index", index: 3 }, // PPMT(rate, per, nper, pv, [fv], [type])
+    CUMIPMT: { type: "fixed_index", index: 2 }, // CUMIPMT(rate, nper, pv, start, end, type)
+    CUMPRINC: { type: "fixed_index", index: 2 }, // CUMPRINC(rate, nper, pv, start, end, type)
+    DDB: { type: "fixed_index", index: 0 }, // DDB(cost, salvage, life, period, [factor])
+    SLN: { type: "fixed_index", index: 0 }, // SLN(cost, salvage, life)
+    SYD: { type: "fixed_index", index: 0 }, // SYD(cost, salvage, life, per)
+    DB: { type: "fixed_index", index: 0 }, // DB(cost, salvage, life, period, [month])
+};
+const functionReturnTypes = {
+    // ─── Date/time — extractors (return scalar numbers) ────────────────
+    MONTH: "NUMBER",
+    YEAR: "NUMBER",
+    DAY: "NUMBER",
+    DAYS: "NUMBER",
+    HOUR: "NUMBER",
+    MINUTE: "NUMBER",
+    SECOND: "NUMBER",
+    WEEKDAY: "NUMBER",
+    WEEKNUM: "NUMBER",
+    ISOWEEKNUM: "NUMBER",
+    YEARFRAC: "NUMBER",
+    DATEDIF: "NUMBER",
+    DATEVALUE: "NUMBER",
+    TIMEVALUE: "NUMBER",
+    NETWORKDAYS: "NUMBER",
+    "NETWORKDAYS.INTL": "NUMBER",
+    DAYS360: "NUMBER",
+    // ─── Date/time — date producers (must render as DATE/TIME/DATE_TIME) ─
+    NOW: "DATE_TIME",
+    TODAY: "DATE",
+    DATE: "DATE",
+    TIME: "TIME",
+    EDATE: "DATE",
+    EOMONTH: "DATE",
+    // WORKDAY returns a date serial number — must render as DATE, not
+    // raw NUMBER (was a bug: cells showed e.g. "45292" instead of the
+    // calendar date).
+    WORKDAY: "DATE",
+    "WORKDAY.INTL": "DATE",
+    // ─── Aggregation / rounding (return NUMBER; CURRENCY precedent
+    //     preserved via the "expectedOutputType === NUMBER + numFormat
+    //     CURRENCY → keep numFormat" branch) ──────────────────────────
+    SUM: "NUMBER",
+    SUMPRODUCT: "NUMBER",
+    SUMSQ: "NUMBER",
+    ROUND: "NUMBER",
+    ROUNDUP: "NUMBER",
+    ROUNDDOWN: "NUMBER",
+    TRUNC: "NUMBER",
+    QUOTIENT: "NUMBER",
+    CEILING: "NUMBER",
+    FLOOR: "NUMBER",
+    MROUND: "NUMBER",
+    INT: "NUMBER",
+    MOD: "NUMBER",
+    // ─── Math/trig (return scalar NUMBER) ──────────────────────────────
+    POWER: "NUMBER",
+    SQRT: "NUMBER",
+    EXP: "NUMBER",
+    LN: "NUMBER",
+    LOG: "NUMBER",
+    LOG10: "NUMBER",
+    SIGN: "NUMBER",
+    SIN: "NUMBER",
+    COS: "NUMBER",
+    TAN: "NUMBER",
+    ASIN: "NUMBER",
+    ACOS: "NUMBER",
+    ATAN: "NUMBER",
+    ATAN2: "NUMBER",
+    SINH: "NUMBER",
+    COSH: "NUMBER",
+    TANH: "NUMBER",
+    ASINH: "NUMBER",
+    ACOSH: "NUMBER",
+    ATANH: "NUMBER",
+    DEGREES: "NUMBER",
+    RADIANS: "NUMBER",
+    PI: "NUMBER",
+    FACT: "NUMBER",
+    FACTDOUBLE: "NUMBER",
+    COMBIN: "NUMBER",
+    COMBINA: "NUMBER",
+    PERMUT: "NUMBER",
+    PERMUTATIONA: "NUMBER",
+    GCD: "NUMBER",
+    LCM: "NUMBER",
+    // ─── Random/value conversion ───────────────────────────────────────
+    RAND: "NUMBER",
+    RANDBETWEEN: "NUMBER",
+    VALUE: "NUMBER",
+    N: "NUMBER",
+    // ─── Statistical — scalar results (NUMBER) ─────────────────────────
+    AVEDEV: "NUMBER",
+    DEVSQ: "NUMBER",
+    KURT: "NUMBER",
+    SKEW: "NUMBER",
+    "SKEW.P": "NUMBER",
+    COVAR: "NUMBER",
+    "COVARIANCE.S": "NUMBER",
+    "COVARIANCE.P": "NUMBER",
+    CORREL: "NUMBER",
+    RSQ: "NUMBER",
+    SLOPE: "NUMBER",
+    INTERCEPT: "NUMBER",
+    STEYX: "NUMBER",
+    PEARSON: "NUMBER",
+    // ─── Financial — rate/period scalars (NUMBER); CURRENCY-returning
+    //     financial functions live in `formatDerivationRules` instead ──
+    XIRR: "NUMBER",
+    IRR: "NUMBER",
+    MIRR: "NUMBER",
+    RATE: "NUMBER",
+    NPER: "NUMBER",
+    EFFECT: "NUMBER",
+    NOMINAL: "NUMBER",
+    // ─── Counts & positions (COUNT, displays as NUMBER) ────────────────
+    MATCH: "COUNT",
+    XMATCH: "COUNT",
+    COUNT: "COUNT",
+    COUNTA: "COUNT",
+    COUNTBLANK: "COUNT",
+    COUNTIF: "COUNT",
+    COUNTIFS: "COUNT",
+    ROW: "COUNT",
+    ROWS: "COUNT",
+    COLUMN: "COUNT",
+    COLUMNS: "COUNT",
+    RANK: "COUNT",
+    "RANK.EQ": "COUNT",
+    "RANK.AVG": "COUNT",
+    FREQUENCY: "COUNT",
+    LEN: "COUNT",
+    SEARCH: "COUNT",
+    SEARCHB: "COUNT",
+    FIND: "COUNT",
+    FINDB: "COUNT",
+    // ─── Text producers ─────────────────────────────────────────────────
+    TEXT: "TEXT",
+    LEFT: "TEXT",
+    LEFTB: "TEXT",
+    RIGHT: "TEXT",
+    RIGHTB: "TEXT",
+    MID: "TEXT",
+    MIDB: "TEXT",
+    LOWER: "TEXT",
+    UPPER: "TEXT",
+    PROPER: "TEXT",
+    TRIM: "TEXT",
+    CLEAN: "TEXT",
+    SUBSTITUTE: "TEXT",
+    REPLACE: "TEXT",
+    REPLACEB: "TEXT",
+    REPT: "TEXT",
+    CONCAT: "TEXT",
+    CONCATENATE: "TEXT",
+    TEXTJOIN: "TEXT",
+    ADDRESS: "TEXT",
+    CHAR: "TEXT",
+    UNICHAR: "TEXT",
+    T: "TEXT",
+    DOLLAR: "TEXT",
+    FIXED: "TEXT",
+    BAHTTEXT: "TEXT",
+    // ─── Aggregation with formatDerivationRules entries (NUMBER base —
+    //     specific-arg inheritance is in `formatDerivationRules`) ──────
+    SUMIFS: "NUMBER",
+    SUMIF: "NUMBER",
+    AVERAGEIFS: "NUMBER",
+    AVERAGEIF: "NUMBER",
+    MINIFS: "NUMBER",
+    MAXIFS: "NUMBER",
+};
+const currencyDecimalAdjustmentFunctions = new Set([
+    "ROUND",
+    "ROUNDUP",
+    "ROUNDDOWN",
+    "TRUNC",
+    "INT",
+    "MROUND",
+    "CEILING",
+    "FLOOR",
+    "QUOTIENT",
+]);
+// Get all function names from formula
+const functionRegex = /([A-Za-z0-9_]+)\s*\(/g;
+export const getFunctionNamesFromFormula = (formula) => {
+    let match;
+    const matches = [];
+    while ((match = functionRegex.exec(formula))) {
+        const [_, functionName] = match;
+        if (functionName) {
+            matches.push(functionName);
+        }
+    }
+    return matches;
+};
+const getSheetNameFromToken = (token) => {
+    if (!token)
+        return undefined;
+    if (token.tokenType.name === tokenVocabulary.Sheet.name) {
+        return token.image.slice(0, -1);
+    }
+    if (token.tokenType.name === tokenVocabulary.SheetQuoted.name) {
+        const cleanSheetName = desanitizeSheetName(token.image);
+        return cleanSheetName ? cleanSheetName.slice(0, -1) : undefined;
+    }
+    return undefined;
+};
+const getDirectReferenceBounds = (formula, tokenizer, sheetId, getSheetId) => {
+    if (!formula)
+        return [];
+    const trimmed = formula.trim();
+    if (!trimmed.startsWith("="))
+        return [];
+    const tokens = tokenizer(trimmed.slice(1));
+    const bounds = [];
+    let pendingSheetId;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        const tokenSheetName = getSheetNameFromToken(token);
+        if (tokenSheetName) {
+            pendingSheetId = getSheetId(tokenSheetName);
+            continue;
+        }
+        if (token.tokenType.name !== tokenVocabulary.Cell.name) {
+            continue;
+        }
+        const refSheetId = token.sheetName
+            ? getSheetId(token.sheetName)
+            : pendingSheetId ?? sheetId;
+        pendingSheetId = undefined;
+        const startCell = addressToCell(token.image);
+        if (!startCell)
+            continue;
+        if (tokens[i + 1]?.tokenType.name === tokenVocabulary.Colon.name &&
+            tokens[i + 2]?.tokenType.name === tokenVocabulary.Cell.name) {
+            const endCell = addressToCell(tokens[i + 2]?.image);
+            if (endCell) {
+                bounds.push({
+                    sheetId: refSheetId,
+                    minRow: Math.min(startCell.rowIndex, endCell.rowIndex),
+                    maxRow: Math.max(startCell.rowIndex, endCell.rowIndex),
+                    minCol: Math.min(startCell.columnIndex, endCell.columnIndex),
+                    maxCol: Math.max(startCell.columnIndex, endCell.columnIndex),
+                });
+                i += 2;
+                continue;
+            }
+        }
+        bounds.push({
+            sheetId: refSheetId,
+            minRow: startCell.rowIndex,
+            maxRow: startCell.rowIndex,
+            minCol: startCell.columnIndex,
+            maxCol: startCell.columnIndex,
+        });
+    }
+    return bounds;
+};
+const filterPrecedentsByBounds = (precedents, bounds) => {
+    if (bounds.length === 0)
+        return precedents;
+    const intersects = (b, row, col) => row >= b.minRow && row <= b.maxRow && col >= b.minCol && col <= b.maxCol;
+    const rangeIntersects = (b, startRow, startCol, endRow, endCol) => !(startRow > b.maxRow ||
+        endRow < b.minRow ||
+        startCol > b.maxCol ||
+        endCol < b.minCol);
+    const filtered = precedents.filter((p) => {
+        if (isStaticNode(p))
+            return true;
+        for (const b of bounds) {
+            if (p.position.sheetId !== b.sheetId) {
+                continue;
+            }
+            if (isCellCoordinate(p.position)) {
+                if (intersects(b, p.position.rowIndex, p.position.columnIndex)) {
+                    return true;
+                }
+            }
+            else if (rangeIntersects(b, p.position.startRowIndex, p.position.startColumnIndex, p.position.endRowIndex, p.position.endColumnIndex)) {
+                return true;
+            }
+        }
+        return false;
+    });
+    return filtered.length > 0 ? filtered : precedents;
+};
+const sheetCell = new SheetCell();
+export const deriveEffectiveNumberFormatFromPrecedents = (formula = "", precedents, draft, tokenizer, sheetId, rowIndex, columnIndex, locale, getSheetId, cellXfsRegistry, getDataValidationById, calculatedValue, 
+/**
+ * Optional resolver for a precedent's effective `numberFormat`. When a
+ * precedent is itself a formula cell with no `uf.numberFormat`, its
+ * format is derived (not persisted on cellData), so reading
+ * `sheetCell.getNumberFormat()` would miss it. The resolver lets the
+ * caller recurse through formula chains so `C1 = B1 = A1` inherits A1's
+ * format. When omitted, only the precedent's persisted
+ * `uf.numberFormat` is consulted.
+ */
+resolvePrecedentNumberFormat) => {
+    // Assign sheet cell
+    sheetCell.assign(sheetId, defaultCellCoords, draft?.[sheetId]?.[rowIndex]?.values?.[columnIndex], {
+        locale,
+        cellXfsRegistry,
+        getDataValidationById,
+    });
+    // Check if has user entered format
+    // User entered format always has precedence over
+    // format derived from precedents
+    if (sheetCell.userEnteredFormat?.numberFormat) {
+        return sheetCell.userEnteredFormat.numberFormat;
+    }
+    if (shouldSkipPrecedentFormatInheritance(formula)) {
+        return undefined;
+    }
+    // Priority
+    // NUMBER -> PERCENTAGE -> CURRENCY
+    let numFormat = undefined;
+    // Expected return type from function
+    let expectedOutputType = undefined;
+    let shouldAdjustCurrencyDecimals = false;
+    let maxDecimals = 0;
+    let match;
+    const isIndirectReference = formula
+        .trim()
+        .toUpperCase()
+        .startsWith("=INDIRECT(");
+    functionRegex.lastIndex = 0;
+    while ((match = functionRegex.exec(formula))) {
+        const [_, functionName] = match;
+        const functionDefault = isIndirectReference
+            ? undefined
+            : functionReturnTypes[functionName.toUpperCase()];
+        if (currencyDecimalAdjustmentFunctions.has(functionName.toUpperCase())) {
+            shouldAdjustCurrencyDecimals = true;
+        }
+        if (!expectedOutputType) {
+            expectedOutputType = functionDefault;
+        }
+        else if (functionDefault === "NUMBER" && expectedOutputType === "DATE") {
+            // if the function returns a number but the expected type is a date,
+            // assume the output is a date
+            expectedOutputType = "DATE";
+        }
+    }
+    // Set effective format
+    let effectivePrecedents = precedents;
+    const indirectCurrentRowAddressMatch = formula
+        .trim()
+        .match(/^=INDIRECT\(\s*ADDRESS\(\s*ROW\(\)\s*,\s*(\d+)\s*\)\s*\)$/i);
+    if (indirectCurrentRowAddressMatch) {
+        effectivePrecedents = [
+            {
+                position: {
+                    sheetId,
+                    rowIndex,
+                    columnIndex: Number(indirectCurrentRowAddressMatch[1]),
+                },
+            },
+        ];
+    }
+    let topLevelFunctionName;
+    const directBounds = getDirectReferenceBounds(formula, tokenizer, sheetId, getSheetId);
+    effectivePrecedents = filterPrecedentsByBounds(effectivePrecedents, directBounds);
+    const upperFormula = formula?.trim().toUpperCase();
+    if (upperFormula) {
+        const functionNameMatch = upperFormula.match(/^=([A-Z0-9_]+)\(/);
+        topLevelFunctionName = functionNameMatch ? functionNameMatch[1] : undefined;
+        const rule = topLevelFunctionName
+            ? formatDerivationRules[topLevelFunctionName]
+            : undefined;
+        if (rule) {
+            const args = extractTopLevelArgs(formula, upperFormula.split("(")[0]);
+            if (rule.type === "fixed_index" || rule.type === "conditional_index") {
+                const targetIndex = rule.type === "fixed_index"
+                    ? rule.index
+                    : rule.getIndex(args.length);
+                if (targetIndex >= 0 && targetIndex < args.length) {
+                    effectivePrecedents = filterPrecedentsByAddress(precedents, args[targetIndex], sheetId, getSheetId);
+                }
+            }
+            else if (rule.type === "vlookup" || rule.type === "hlookup") {
+                // VLOOKUP / HLOOKUP: Excel returns the format of the matched cell
+                // in the literal-numbered column/row of the table range. Restrict
+                // derivation to that single column/row so a currency-formatted
+                // unrelated column in the table doesn't leak its format into the
+                // result.
+                const tableArg = args[rule.tableIndex];
+                const indexArg = args[rule.type === "vlookup" ? rule.colIndexArg : rule.rowIndexArg];
+                const offset = parseLiteralInt(indexArg);
+                if (tableArg && offset && offset >= 1) {
+                    effectivePrecedents = filterPrecedentsByTableOffset(precedents, tableArg, offset, rule.type === "vlookup" ? "column" : "row", sheetId, getSheetId);
+                }
+                else if (tableArg) {
+                    // Fallback: literal index unreadable (e.g. formula expression).
+                    // Filter to the whole table — still better than walking every
+                    // precedent.
+                    effectivePrecedents = filterPrecedentsByAddress(precedents, tableArg, sheetId, getSheetId);
+                }
+            }
+        }
+    }
+    const processPrecedentCell = (precedentSheetId, precedentRowIndex, precedentColumnIndex) => {
+        sheetCell.assign(precedentSheetId, {
+            rowIndex: precedentRowIndex,
+            columnIndex: precedentColumnIndex,
+        }, draft?.[precedentSheetId]?.[precedentRowIndex]?.values?.[precedentColumnIndex], {
+            locale,
+            cellXfsRegistry,
+            getDataValidationById,
+        });
+        // Prefer the resolver: it returns `uf.numberFormat` for plain cells
+        // and the recursively-derived format for formula cells, so chains
+        // like `C1 = B1 = A1` propagate A1's format through B1 to C1.
+        // Falls back to the precedent's persisted `uf.numberFormat` when no
+        // resolver is wired (callers without a derive-graph, e.g. exporters).
+        const curNumFormat = resolvePrecedentNumberFormat?.(precedentSheetId, precedentRowIndex, precedentColumnIndex) ?? sheetCell.getNumberFormat();
+        const currentValue = sheetCell.getEffectiveValue();
+        if (typeof currentValue === "number") {
+            maxDecimals = Math.max(maxDecimals, getDecimalPlaces(currentValue, locale));
+        }
+        if (curNumFormat) {
+            maxDecimals = Math.max(maxDecimals, getCurrentDecimalCountInPattern(curNumFormat.pattern));
+            if (curNumFormat.type === "TEXT" &&
+                numFormat &&
+                numFormat.type &&
+                numFormat.type !== "TEXT") {
+                return;
+            }
+            // Excel's rule: the **first** non-generic precedent format wins.
+            // Generic = NUMBER/GENERAL/COUNT (no specific styling intent), so a
+            // later CURRENCY/PERCENT/DATE/etc. can upgrade it; but once a
+            // specific format is locked in we don't let a different specific
+            // format override it (e.g. PERCENT then CURRENCY → keep PERCENT,
+            // matching Excel; previously priority-based merging picked the
+            // higher-priority one regardless of position).
+            if (!numFormat || isGenericNumberFormatType(numFormat.type)) {
+                numFormat = curNumFormat;
+            }
+        }
+    };
+    for (const precedent of effectivePrecedents) {
+        // Ignore static node
+        if (isStaticNode(precedent)) {
+            continue;
+        }
+        const precedentSheetId = precedent.position.sheetId;
+        if (isCellCoordinate(precedent.position)) {
+            processPrecedentCell(precedentSheetId, precedent.position.rowIndex, precedent.position.columnIndex);
+            continue;
+        }
+        // Anchor-only derivation: Excel inherits a range's number format from
+        // its first cell (top-left). This makes derivation O(1) per range and
+        // keeps it consistent with the anchor-only cache fingerprint so a
+        // non-anchor format change doesn't leak a different result than what
+        // the cache would return.
+        processPrecedentCell(precedentSheetId, precedent.position.startRowIndex, precedent.position.startColumnIndex);
+    }
+    // Get decimal places from the calculated value
+    // This respects ROUND's output - if ROUND(x, 0) gives 456, it has 0 decimals
+    const calculatedDecimals = typeof calculatedValue === "number"
+        ? getDecimalPlaces(calculatedValue, locale)
+        : undefined;
+    if (typeof calculatedValue === "number") {
+        maxDecimals = Math.max(maxDecimals, calculatedDecimals ?? 0);
+    }
+    if (!numFormat && maxDecimals > 0) {
+        numFormat = { type: "NUMBER" };
+    }
+    const applyDecimalHeuristic = (format) => {
+        // `#` is the implicit integer pattern inferred from plain numeric cells,
+        // but it suppresses zero. Formula results should still display a derived
+        // zero; an explicitly formatted formula cell returned above remains
+        // untouched.
+        if (calculatedValue === 0 &&
+            format?.type === "NUMBER" &&
+            format.pattern === "#") {
+            return { ...format, pattern: "0" };
+        }
+        // For CURRENCY type, use the calculated value's decimal places
+        // This ensures ROUND(SUM(F9), 0) shows 0 decimals even if precedent has 2
+        if (format?.type === "CURRENCY" &&
+            shouldAdjustCurrencyDecimals &&
+            calculatedDecimals !== undefined &&
+            format.pattern) {
+            const patternDecimals = getCurrentDecimalCountInPattern(format.pattern);
+            // Only adjust if calculated value has fewer decimals than the pattern
+            // (respects ROUND's intent to reduce decimals)
+            if (calculatedDecimals < patternDecimals) {
+                return {
+                    ...format,
+                    pattern: changeDecimals(format.pattern, calculatedDecimals, false),
+                };
+            }
+        }
+        // Original heuristic for NUMBER type
+        if (format?.type === "NUMBER" && maxDecimals > 0) {
+            const basePattern = format.pattern ?? "0";
+            return {
+                ...format,
+                pattern: changeDecimals(basePattern, Math.min(maxDecimals, 3), false),
+            };
+        }
+        return format;
+    };
+    // Useful for Percentages
+    // 20% x 50 => number
+    if (numFormat) {
+        // Does not support structured references as of now
+        const astDerivedNumberFormat = getNumberFormatFromFormulaAst(formula, numFormat, draft, tokenizer, sheetId, getSheetId, cellXfsRegistry, getDataValidationById, locale);
+        if (astDerivedNumberFormat) {
+            return applyDecimalHeuristic(astDerivedNumberFormat);
+        }
+    }
+    // If we could not derive from function
+    if (expectedOutputType === undefined) {
+        return applyDecimalHeuristic(numFormat);
+    }
+    // Number variations
+    if (expectedOutputType === "NUMBER" &&
+        (numFormat?.type === "CURRENCY" ||
+            numFormat?.type === "PERCENT" ||
+            numFormat?.type === "SCIENTIFIC")) {
+        return numFormat;
+    }
+    // Date variations
+    if (expectedOutputType === "DATE" && numFormat?.type === "DATE_TIME") {
+        return numFormat;
+    }
+    if (expectedOutputType !== numFormat?.type) {
+        const resolvedType = expectedOutputType in customNumberFormatMap
+            ? customNumberFormatMap[expectedOutputType]
+            : expectedOutputType;
+        const resolvedNumberFormat = {
+            type: resolvedType,
+        };
+        // Date/time types need a concrete pattern — without one the renderer
+        // falls back to "General" and shows the serial number (the
+        // =TODAY() bug). When the precedent itself is a date-family format
+        // with a pattern, inherit that pattern (e.g. `=EDATE(A1, 1)` keeps
+        // A1's custom `yyyy-mm-dd` instead of falling back to the locale
+        // default). Otherwise mirror the format toolbar's default for the
+        // type.
+        if (isDateFamilyType(resolvedNumberFormat.type) &&
+            isDateFamilyType(numFormat?.type) &&
+            numFormat?.pattern) {
+            resolvedNumberFormat.pattern = numFormat.pattern;
+        }
+        else if (resolvedNumberFormat.type === "DATE_TIME") {
+            resolvedNumberFormat.pattern = getDefaultDateTimeFormat(locale);
+        }
+        else if (resolvedNumberFormat.type === "DATE") {
+            resolvedNumberFormat.pattern = getDefaultDateFormat(locale);
+        }
+        else if (resolvedNumberFormat.type === "TIME") {
+            resolvedNumberFormat.pattern = getDefaultTimeFormat(locale);
+        }
+        // Preserve pattern from precedent cells for CURRENCY type
+        // This ensures currency symbols (€, $, etc.) are preserved
+        if (resolvedNumberFormat.type === "CURRENCY" &&
+            numFormat?.type === "CURRENCY" &&
+            numFormat.pattern) {
+            resolvedNumberFormat.pattern = numFormat.pattern;
+        }
+        return applyDecimalHeuristic(resolvedNumberFormat);
+    }
+    return applyDecimalHeuristic(numFormat);
+};
+/**
+ * Like `deriveEffectiveNumberFormatFromPrecedents` but synthesizes the
+ * `precedents` array from the formula's direct cell/range references —
+ * used by the XLSX/ODS/CSV exporters which don't have a calc graph.
+ *
+ * Internally calls `deriveEffectiveNumberFormatFromPrecedents`, so all the
+ * function-specific rules (FILTER source range, ROUND decimals, IFERROR,
+ * function return types, etc.) are honored — render and export produce
+ * the same format for the same formula.
+ */
+export const deriveEffectiveNumberFormatFromFormula = (formula, sheetId, rowIndex, columnIndex, draft, tokenizer, getSheetId, locale, cellXfsRegistry, getDataValidationById, calculatedValue) => {
+    if (!formula || !formula.trim().startsWith("="))
+        return undefined;
+    const bounds = getDirectReferenceBounds(formula, tokenizer, sheetId, getSheetId);
+    // Synthesize precedents — one CellNode per cell in each bound. The
+    // existing implementation re-filters precedents by the same bounds, so
+    // this produces identical input.
+    const precedents = [];
+    for (const bound of bounds) {
+        for (let r = bound.minRow; r <= bound.maxRow; r++) {
+            for (let c = bound.minCol; c <= bound.maxCol; c++) {
+                precedents.push({
+                    position: {
+                        sheetId: bound.sheetId,
+                        rowIndex: r,
+                        columnIndex: c,
+                    },
+                });
+            }
+        }
+    }
+    return deriveEffectiveNumberFormatFromPrecedents(formula, precedents, draft, tokenizer, sheetId, rowIndex, columnIndex, locale, getSheetId, cellXfsRegistry, getDataValidationById, calculatedValue);
+};
+const resolveResultsType = (type) => {
+    if (!type)
+        return undefined;
+    if (type in customNumberFormatMap) {
+        return customNumberFormatMap[type];
+    }
+    return type;
+};
+const parseNumberFormatAst = (formula, tokenizer, sheetId, getSheetId) => {
+    if (!formula.startsWith("=")) {
+        return undefined;
+    }
+    const tokens = tokenizer(formula.slice(1));
+    let index = 0;
+    const emptyStopTokens = new Set();
+    const peek = () => tokens[index];
+    const next = () => tokens[index++];
+    const shouldStop = (stopTokens) => !!peek() && stopTokens.has(peek().tokenType.name);
+    const parseCellOrRange = (cellToken, explicitSheetId) => {
+        const startCell = addressToCell(cellToken.image);
+        if (!startCell)
+            return undefined;
+        const resolvedSheetId = cellToken.sheetName
+            ? getSheetId(cellToken.sheetName)
+            : explicitSheetId ?? sheetId;
+        if (peek()?.tokenType.name === tokenVocabulary.Colon.name &&
+            tokens[index + 1]?.tokenType.name === tokenVocabulary.Cell.name) {
+            next();
+            const endCellToken = next();
+            const endCell = addressToCell(endCellToken.image);
+            if (!endCell) {
+                return {
+                    kind: "cell_reference",
+                    sheetId: resolvedSheetId,
+                    rowIndex: startCell.rowIndex,
+                    columnIndex: startCell.columnIndex,
+                };
+            }
+            return {
+                kind: "range_reference",
+                sheetId: resolvedSheetId,
+                startRowIndex: startCell.rowIndex,
+                startColumnIndex: startCell.columnIndex,
+                endRowIndex: endCell.rowIndex,
+                endColumnIndex: endCell.columnIndex,
+            };
+        }
+        return {
+            kind: "cell_reference",
+            sheetId: resolvedSheetId,
+            rowIndex: startCell.rowIndex,
+            columnIndex: startCell.columnIndex,
+        };
+    };
+    const parseExpression = (stopTokens) => parseComparison(stopTokens);
+    const parseComparison = (stopTokens) => {
+        let left = parseConcat(stopTokens);
+        while (left && !shouldStop(stopTokens)) {
+            const name = peek()?.tokenType.name;
+            if (name === tokenVocabulary.EqOp.name ||
+                name === tokenVocabulary.NeqOp.name ||
+                name === tokenVocabulary.GtOp.name ||
+                name === tokenVocabulary.GteOp.name ||
+                name === tokenVocabulary.LtOp.name ||
+                name === tokenVocabulary.LteOp.name) {
+                next();
+                const right = parseConcat(stopTokens);
+                if (!right)
+                    break;
+                left = { kind: "binary", op: "COMPARE", left, right };
+                continue;
+            }
+            break;
+        }
+        return left;
+    };
+    const parseConcat = (stopTokens) => {
+        let left = parseAddSub(stopTokens);
+        while (left && !shouldStop(stopTokens)) {
+            if (peek()?.tokenType.name === tokenVocabulary.ConcatOp.name) {
+                next();
+                const right = parseAddSub(stopTokens);
+                if (!right)
+                    break;
+                left = { kind: "binary", op: "CONCAT", left, right };
+                continue;
+            }
+            break;
+        }
+        return left;
+    };
+    const parseAddSub = (stopTokens) => {
+        let left = parseMulDiv(stopTokens);
+        while (left && !shouldStop(stopTokens)) {
+            const name = peek()?.tokenType.name;
+            if (name === tokenVocabulary.PlusOp.name ||
+                name === tokenVocabulary.MinOp.name) {
+                next();
+                const right = parseMulDiv(stopTokens);
+                if (!right)
+                    break;
+                left = {
+                    kind: "binary",
+                    op: name === tokenVocabulary.PlusOp.name ? "ADD" : "SUB",
+                    left,
+                    right,
+                };
+                continue;
+            }
+            break;
+        }
+        return left;
+    };
+    const parseMulDiv = (stopTokens) => {
+        let left = parsePower(stopTokens);
+        while (left && !shouldStop(stopTokens)) {
+            const name = peek()?.tokenType.name;
+            if (name === tokenVocabulary.MulOp.name ||
+                name === tokenVocabulary.DivOp.name) {
+                next();
+                const right = parsePower(stopTokens);
+                if (!right)
+                    break;
+                left = {
+                    kind: "binary",
+                    op: name === tokenVocabulary.MulOp.name ? "MUL" : "DIV",
+                    left,
+                    right,
+                };
+                continue;
+            }
+            break;
+        }
+        return left;
+    };
+    const parsePower = (stopTokens) => {
+        let left = parseUnary(stopTokens);
+        while (left && !shouldStop(stopTokens)) {
+            if (peek()?.tokenType.name === tokenVocabulary.ExOp.name) {
+                next();
+                const right = parseUnary(stopTokens);
+                if (!right)
+                    break;
+                left = { kind: "binary", op: "EXP", left, right };
+                continue;
+            }
+            break;
+        }
+        return left;
+    };
+    const parseUnary = (stopTokens) => {
+        const name = peek()?.tokenType.name;
+        if (name === tokenVocabulary.PlusOp.name ||
+            name === tokenVocabulary.MinOp.name) {
+            next();
+            const operand = parseUnary(stopTokens);
+            if (!operand)
+                return undefined;
+            return {
+                kind: "unary",
+                op: name === tokenVocabulary.PlusOp.name ? "PLUS" : "MINUS",
+                operand,
+            };
+        }
+        return parsePostfix(stopTokens);
+    };
+    const parsePostfix = (stopTokens) => {
+        let left = parsePrimary(stopTokens);
+        while (left && !shouldStop(stopTokens)) {
+            if (peek()?.tokenType.name === tokenVocabulary.PercentOp.name) {
+                next();
+                left = { kind: "postfix_percent", operand: left };
+                continue;
+            }
+            break;
+        }
+        return left;
+    };
+    const parseFunction = () => {
+        const token = next();
+        const functionName = token.image.slice(0, -1).toUpperCase();
+        const argStopTokens = new Set([
+            tokenVocabulary.Comma.name,
+            tokenVocabulary.CloseParen.name,
+        ]);
+        const args = [];
+        while (index < tokens.length) {
+            if (peek()?.tokenType.name === tokenVocabulary.CloseParen.name) {
+                next();
+                break;
+            }
+            const parsedArg = parseExpression(argStopTokens);
+            args.push(parsedArg ?? { kind: "unknown" });
+            const nextName = peek()?.tokenType.name;
+            if (nextName === tokenVocabulary.Comma.name) {
+                next();
+                continue;
+            }
+            if (nextName === tokenVocabulary.CloseParen.name) {
+                next();
+                break;
+            }
+            if (nextName === undefined) {
+                break;
+            }
+            next();
+        }
+        return {
+            kind: "function_call",
+            name: functionName,
+            args,
+        };
+    };
+    const parsePrimary = (stopTokens) => {
+        if (shouldStop(stopTokens)) {
+            return undefined;
+        }
+        const token = peek();
+        if (!token)
+            return undefined;
+        const name = token.tokenType.name;
+        if (name === tokenVocabulary.Number.name) {
+            next();
+            return { kind: "number_literal" };
+        }
+        if (name === tokenVocabulary.String.name) {
+            next();
+            return { kind: "string_literal" };
+        }
+        if (name === tokenVocabulary.Boolean.name) {
+            next();
+            return { kind: "boolean_literal" };
+        }
+        if (name === tokenVocabulary.Cell.name) {
+            const cellToken = next();
+            return parseCellOrRange(cellToken);
+        }
+        if (name === tokenVocabulary.Sheet.name ||
+            name === tokenVocabulary.SheetQuoted.name) {
+            const sheetToken = next();
+            const parsedSheetName = getSheetNameFromToken(sheetToken);
+            const explicitSheetId = parsedSheetName
+                ? getSheetId(parsedSheetName)
+                : sheetId;
+            const cellToken = peek();
+            if (cellToken?.tokenType.name !== tokenVocabulary.Cell.name) {
+                return { kind: "unknown" };
+            }
+            next();
+            return parseCellOrRange(cellToken, explicitSheetId);
+        }
+        if (name === tokenVocabulary.Function.name) {
+            return parseFunction();
+        }
+        if (name === tokenVocabulary.OpenParen.name) {
+            next();
+            const node = parseExpression(new Set([tokenVocabulary.CloseParen.name]));
+            if (peek()?.tokenType.name === tokenVocabulary.CloseParen.name) {
+                next();
+            }
+            return node;
+        }
+        next();
+        return { kind: "unknown" };
+    };
+    return parseExpression(emptyStopTokens);
+};
+const deriveNumberFormatTypeFromAst = (ast, derivedNumberFormat, draft, getDataValidationById, cellXfsRegistry) => {
+    const getCellFormatType = (targetSheetId, rowIndex, columnIndex) => {
+        sheetCell.assign(targetSheetId, { rowIndex, columnIndex }, draft?.[targetSheetId]?.[rowIndex]?.values?.[columnIndex], { cellXfsRegistry, getDataValidationById });
+        return sheetCell.getNumberFormat()?.type;
+    };
+    const isDateLike = (type) => type === "DATE" || type === "DATE_TIME" || type === "TIME";
+    const isCurrencyLike = (type) => type === "CURRENCY" || type === "ACCOUNTING";
+    const isPercentLike = (type) => type === "PERCENT";
+    const isNumericLike = (type) => type === "NUMBER" ||
+        type === "GENERAL" ||
+        type === "SCIENTIFIC" ||
+        type === "FRACTION" ||
+        type === "SPECIAL" ||
+        isCurrencyLike(type) ||
+        isPercentLike(type);
+    const mergeValueTypes = (types) => {
+        const filtered = types.filter((type) => !!type);
+        if (filtered.length === 0)
+            return undefined;
+        if (filtered.every((type) => type === filtered[0])) {
+            return filtered[0];
+        }
+        if (filtered.some(isCurrencyLike)) {
+            return filtered.find(isCurrencyLike) ?? filtered[0];
+        }
+        if (filtered.every(isPercentLike)) {
+            return "PERCENT";
+        }
+        if (filtered.some(isPercentLike)) {
+            return "NUMBER";
+        }
+        if (filtered.every(isDateLike)) {
+            return filtered[0];
+        }
+        return filtered[0];
+    };
+    const deriveAggregateType = (functionName, argTypes) => {
+        const filtered = argTypes.filter((type) => !!type);
+        if (filtered.length === 0)
+            return undefined;
+        const hasCurrency = filtered.some(isCurrencyLike);
+        const allPercent = filtered.every(isPercentLike);
+        const hasPercent = filtered.some(isPercentLike);
+        const allDate = filtered.every(isDateLike);
+        if (functionName === "MIN" || functionName === "MAX") {
+            if (allDate)
+                return filtered[0];
+            if (hasCurrency)
+                return filtered.find(isCurrencyLike) ?? "NUMBER";
+            if (allPercent)
+                return "PERCENT";
+            if (hasPercent)
+                return "NUMBER";
+            return filtered[0] ?? "NUMBER";
+        }
+        if (functionName === "SUM" || functionName === "AVERAGE") {
+            if (hasCurrency)
+                return filtered.find(isCurrencyLike) ?? "NUMBER";
+            if (allPercent)
+                return "PERCENT";
+            if (hasPercent)
+                return "NUMBER";
+            if (allDate)
+                return "NUMBER";
+            return filtered[0] ?? "NUMBER";
+        }
+        return filtered[0];
+    };
+    const preferNumericType = (left, right) => {
+        if (isCurrencyLike(left))
+            return left;
+        if (isCurrencyLike(right))
+            return right;
+        if (isPercentLike(left) && isPercentLike(right))
+            return "PERCENT";
+        if (isPercentLike(left))
+            return right ?? "NUMBER";
+        if (isPercentLike(right))
+            return left ?? "NUMBER";
+        return left ?? right;
+    };
+    const combineTypes = (op, left, right) => {
+        if (op === "CONCAT")
+            return "TEXT";
+        if (op === "COMPARE")
+            return "GENERAL";
+        if (op === "ADD" || op === "SUB") {
+            if (isDateLike(left) && isDateLike(right))
+                return "NUMBER";
+            if (isDateLike(left) && isNumericLike(right))
+                return left;
+            if (isDateLike(right) && isNumericLike(left))
+                return right;
+            return preferNumericType(left, right);
+        }
+        if (op === "MUL") {
+            if (isPercentLike(left) && isPercentLike(right))
+                return "NUMBER";
+            if (isPercentLike(left) && isNumericLike(right))
+                return right;
+            if (isPercentLike(right) && isNumericLike(left))
+                return left;
+            if (isDateLike(left) || isDateLike(right))
+                return "NUMBER";
+            if (isCurrencyLike(left) && isCurrencyLike(right))
+                return "NUMBER";
+            if (isCurrencyLike(left) && isNumericLike(right))
+                return left;
+            if (isCurrencyLike(right) && isNumericLike(left))
+                return right;
+            return preferNumericType(left, right);
+        }
+        if (op === "DIV") {
+            if (isDateLike(left) || isDateLike(right))
+                return "NUMBER";
+            if (isCurrencyLike(left) && isCurrencyLike(right))
+                return "NUMBER";
+            if (isCurrencyLike(left) && isNumericLike(right))
+                return left;
+            if (isCurrencyLike(right) && isNumericLike(left))
+                return "NUMBER";
+            if (isPercentLike(left) && isPercentLike(right))
+                return "NUMBER";
+            if (isPercentLike(left) && isNumericLike(right))
+                return right;
+            if (isPercentLike(right) && isNumericLike(left))
+                return left;
+            return preferNumericType(left, right);
+        }
+        if (op === "EXP")
+            return "NUMBER";
+        return left ?? right;
+    };
+    const inferNodeType = (node) => {
+        if (!node)
+            return undefined;
+        switch (node.kind) {
+            case "number_literal":
+                return "NUMBER";
+            case "string_literal":
+                return "TEXT";
+            case "boolean_literal":
+                return "NUMBER";
+            case "cell_reference":
+                return (getCellFormatType(node.sheetId, node.rowIndex, node.columnIndex) ??
+                    derivedNumberFormat.type);
+            case "range_reference":
+                return (getCellFormatType(node.sheetId, node.startRowIndex, node.startColumnIndex) ?? derivedNumberFormat.type);
+            case "unary":
+                return inferNodeType(node.operand);
+            case "postfix_percent":
+                return "PERCENT";
+            case "binary":
+                return combineTypes(node.op, inferNodeType(node.left), inferNodeType(node.right));
+            case "function_call": {
+                const args = node.args.map((arg) => inferNodeType(arg));
+                const functionName = node.name;
+                if (functionName === "IF") {
+                    const trueType = args[1];
+                    const falseType = args[2];
+                    return (mergeValueTypes([trueType, falseType]) ?? derivedNumberFormat.type);
+                }
+                if (functionName === "IFS") {
+                    const valueTypes = [];
+                    for (let i = 1; i < args.length; i += 2) {
+                        valueTypes.push(args[i]);
+                    }
+                    return mergeValueTypes(valueTypes) ?? derivedNumberFormat.type;
+                }
+                if (functionName === "IFERROR" || functionName === "IFNA") {
+                    return (mergeValueTypes([args[0], args[1]]) ?? derivedNumberFormat.type);
+                }
+                if (functionName === "CHOOSE") {
+                    // CHOOSE(index, choice1, choice2, …) — result is one of the
+                    // choices, so merge their types like IF/IFS.
+                    return (mergeValueTypes(args.slice(1)) ?? derivedNumberFormat.type);
+                }
+                if (functionName === "SWITCH") {
+                    // SWITCH(expression, val1, result1, [val2, result2, …], [default]).
+                    // Results sit at indices 2, 4, … and an even total arg count
+                    // means there's a trailing default at the last position.
+                    const valueTypes = [];
+                    for (let i = 2; i < args.length; i += 2) {
+                        valueTypes.push(args[i]);
+                    }
+                    if (args.length % 2 === 0) {
+                        valueTypes.push(args[args.length - 1]);
+                    }
+                    return mergeValueTypes(valueTypes) ?? derivedNumberFormat.type;
+                }
+                if (functionName === "ROUND" ||
+                    functionName === "ROUNDUP" ||
+                    functionName === "ROUNDDOWN" ||
+                    functionName === "ABS" ||
+                    functionName === "INT") {
+                    return args[0] ?? derivedNumberFormat.type;
+                }
+                if (functionName === "MOD" || functionName === "POWER") {
+                    return "NUMBER";
+                }
+                if (functionName === "SUMPRODUCT") {
+                    const filtered = args.filter((type) => !!type);
+                    if (filtered.some(isCurrencyLike)) {
+                        return filtered.find(isCurrencyLike) ?? "NUMBER";
+                    }
+                    return "NUMBER";
+                }
+                if (functionName === "SUM" ||
+                    functionName === "AVERAGE" ||
+                    functionName === "MIN" ||
+                    functionName === "MAX") {
+                    return (deriveAggregateType(functionName, args) ?? derivedNumberFormat.type);
+                }
+                const rule = formatDerivationRules[functionName];
+                if (rule) {
+                    let targetIndex;
+                    if (rule.type === "fixed_index") {
+                        targetIndex = rule.index;
+                    }
+                    else if (rule.type === "conditional_index") {
+                        targetIndex = rule.getIndex(args.length);
+                    }
+                    if (targetIndex !== undefined && args[targetIndex]) {
+                        return args[targetIndex];
+                    }
+                }
+                const defaultType = functionReturnTypes[functionName];
+                if (defaultType === "NUMBER") {
+                    if (derivedNumberFormat.type === "PERCENT" ||
+                        derivedNumberFormat.type === "CURRENCY" ||
+                        derivedNumberFormat.type === "ACCOUNTING" ||
+                        derivedNumberFormat.type === "SCIENTIFIC") {
+                        return derivedNumberFormat.type;
+                    }
+                }
+                return resolveResultsType(defaultType) ?? derivedNumberFormat.type;
+            }
+            case "unknown":
+                return undefined;
+        }
+    };
+    return inferNodeType(ast);
+};
+/**
+ * Two phase inference:
+ * 1) parse formula tokens into AST
+ * 2) derive number format type from the AST semantics
+ */
+export const getNumberFormatTypeFromFormula = (formula, derivedNumberFormat, draft, tokenizer, sheetId, getSheetId, cellXfsRegistry, getDataValidationById) => {
+    const ast = parseNumberFormatAst(formula, tokenizer, sheetId, getSheetId);
+    if (!ast) {
+        return undefined;
+    }
+    return deriveNumberFormatTypeFromAst(ast, derivedNumberFormat, draft, getDataValidationById, cellXfsRegistry);
+};
+/**
+ * AST-based format derivation from formula semantics.
+ * Uses the parser-backed type analysis and preserves source pattern when
+ * the resolved type is unchanged.
+ */
+export const getNumberFormatFromFormulaAst = (formula, derivedNumberFormat, draft, tokenizer, sheetId, getSheetId, cellXfsRegistry, getDataValidationById, locale) => {
+    const resolvedType = getNumberFormatTypeFromFormula(formula, derivedNumberFormat, draft, tokenizer, sheetId, getSheetId, cellXfsRegistry, getDataValidationById);
+    if (!resolvedType) {
+        return undefined;
+    }
+    // Keep the exact source pattern for passthrough/same-type formulas
+    // (or when the source is a date-family pattern and the resolved type
+    // is also date-family — keeps `yyyy-mm-dd` etc. through date math).
+    if (resolvedType === derivedNumberFormat.type) {
+        return {
+            type: resolvedType,
+            ...(derivedNumberFormat.pattern
+                ? { pattern: derivedNumberFormat.pattern }
+                : {}),
+        };
+    }
+    if (isDateFamilyType(resolvedType) &&
+        isDateFamilyType(derivedNumberFormat.type) &&
+        derivedNumberFormat.pattern) {
+        return { type: resolvedType, pattern: derivedNumberFormat.pattern };
+    }
+    // Date-family resolved types without an inheritable pattern need a
+    // concrete default — otherwise the renderer falls back to "General"
+    // and surfaces the serial number (`=NOW()` showed `45000.5` instead
+    // of a date-time string when the calculated-decimals heuristic above
+    // set `numFormat = { type: "NUMBER" }` and the AST then resolved to
+    // DATE_TIME, dropping the pattern).
+    if (resolvedType === "DATE_TIME") {
+        return { type: resolvedType, pattern: getDefaultDateTimeFormat(locale) };
+    }
+    if (resolvedType === "DATE") {
+        return { type: resolvedType, pattern: getDefaultDateFormat(locale) };
+    }
+    if (resolvedType === "TIME") {
+        return { type: resolvedType, pattern: getDefaultTimeFormat(locale) };
+    }
+    return { type: resolvedType };
+};
+// Seems hacky ony for percentage
+export const isPercentageType = (token, sheetId, draft, cellXfsRegistry, getDataValidationById) => {
+    const cell = token ? addressToCell(token.image) : undefined;
+    if (cell) {
+        const sheetCell = new SheetCell(sheetId, cell, draft?.[sheetId]?.[cell.rowIndex]?.values?.[cell.columnIndex], { cellXfsRegistry, getDataValidationById });
+        const curNumFormat = sheetCell.getNumberFormat();
+        return curNumFormat?.type === "PERCENT";
+    }
+    return false;
+};
+// Seems hacky ony for percentage
+export const isDateType = (token, sheetId, draft, cellXfsRegistry, getDataValidationById) => {
+    const cell = token ? addressToCell(token.image) : undefined;
+    if (cell) {
+        const sheetCell = new SheetCell(sheetId, cell, draft?.[sheetId]?.[cell.rowIndex]?.values?.[cell.columnIndex], { cellXfsRegistry, getDataValidationById });
+        const curNumFormat = sheetCell.getNumberFormat();
+        return curNumFormat?.type === "DATE" || curNumFormat?.type === "DATE_TIME";
+    }
+    return false;
+};
+const numericLiteralRegex = /^[-+]?(?:\d+(\.\d*)?|\.\d+)$/;
+const shouldSkipPrecedentFormatInheritance = (formula) => {
+    if (!formula) {
+        return false;
+    }
+    const trimmed = formula.trim();
+    const upper = trimmed.toUpperCase();
+    if (upper.startsWith("=IF(")) {
+        const args = extractTopLevelArgs(trimmed, "=IF");
+        if (args.length < 3) {
+            return false;
+        }
+        const [, trueArg, falseArg] = args;
+        return (numericLiteralRegex.test(trueArg.trim()) &&
+            numericLiteralRegex.test(falseArg.trim()));
+    }
+    if (upper.startsWith("=CHOOSE(")) {
+        const args = extractTopLevelArgs(trimmed, "=CHOOSE");
+        if (args.length < 2) {
+            return false;
+        }
+        const options = args.slice(1);
+        return options.every((option) => numericLiteralRegex.test(option.trim()));
+    }
+    return false;
+};
+const extractTopLevelArgs = (formula, prefix) => {
+    const upper = formula.toUpperCase();
+    const startIndex = upper.indexOf(prefix);
+    if (startIndex === -1) {
+        return [];
+    }
+    let parenIndex = startIndex + prefix.length;
+    if (formula[parenIndex] !== "(") {
+        return [];
+    }
+    parenIndex += 1;
+    const args = [];
+    let depth = 0;
+    let current = "";
+    let inString = false;
+    for (let i = parenIndex; i < formula.length; i++) {
+        const char = formula[i];
+        if (char === '"' && formula[i - 1] !== "\\") {
+            inString = !inString;
+        }
+        if (!inString) {
+            if (char === "(") {
+                depth++;
+            }
+            else if (char === ")") {
+                if (depth === 0) {
+                    args.push(current);
+                    break;
+                }
+                depth--;
+            }
+            else if (char === "," && depth === 0) {
+                args.push(current);
+                current = "";
+                continue;
+            }
+        }
+        current += char;
+    }
+    return args.map((arg) => arg.trim());
+};
+/**
+ * Peek an iterable
+ * @param iterator
+ * @returns
+ */
+export const peekIterable = (iterator) => {
+    const items = Array.from(iterator); // Consume entire iterator
+    const peeked = items.length > 0
+        ? { done: false, value: items[0] }
+        : { done: true, value: undefined };
+    const rebuiltIterator = function* () {
+        yield* items;
+    };
+    return { peeked, rebuiltIterator };
+};
+export const deriveCellFromPrecedents = (formula = "", precedents, draft, sheetId, locale, cellXfsRegistry) => {
+    const trimmedFormula = formula?.trim() ?? "";
+    const directRefRegex = /^=\s*('?[^'!]+?'!)?\$?[A-Z]+\$?\d+$/i;
+    if (!directRefRegex.test(trimmedFormula)) {
+        return undefined;
+    }
+    const sheetCell = new SheetCell(sheetId, defaultCellCoords);
+    for (const precedent of precedents) {
+        // Ignore static node
+        if (isStaticNode(precedent)) {
+            continue;
+        }
+        let rowIndex;
+        let columnIndex;
+        const sheetId = precedent.position.sheetId;
+        // Get the first cell from a range
+        if (isCellCoordinate(precedent.position)) {
+            rowIndex = precedent.position.rowIndex;
+            columnIndex = precedent.position.columnIndex;
+        }
+        else {
+            rowIndex = precedent.position.startRowIndex;
+            columnIndex = precedent.position.startColumnIndex;
+        }
+        sheetCell.assign(sheetId, {
+            rowIndex,
+            columnIndex,
+        }, draft?.[sheetId]?.[rowIndex]?.values?.[columnIndex], {
+            locale,
+            cellXfsRegistry,
+        });
+        return sheetCell.getCellData();
+    }
+};
+/**
+ * Parse a literal integer from a VLOOKUP/HLOOKUP col/row-index argument.
+ * Returns undefined for non-literal expressions so the caller can fall
+ * back to a coarser filter.
+ */
+const parseLiteralInt = (raw) => {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!/^-?\d+$/.test(trimmed))
+        return undefined;
+    const n = Number(trimmed);
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * Filter precedents to a single anchor cell inside a table range, used by
+ * VLOOKUP (`column`) and HLOOKUP (`row`). The anchor is the cell at the
+ * table's start row + selected column (vlookup), or start column +
+ * selected row (hlookup) — matching Excel's first-cell format inheritance
+ * for the looked-up column/row. `offset` is 1-based.
+ */
+const filterPrecedentsByTableOffset = (precedents, tableAddress, offset, axis, currentSheetId, getSheetId) => {
+    let targetSheetId = currentSheetId;
+    let rangeStr = tableAddress;
+    if (tableAddress.includes("!")) {
+        const lastBang = tableAddress.lastIndexOf("!");
+        const sheetName = tableAddress
+            .substring(0, lastBang)
+            .replace(/^'|'$/g, "");
+        rangeStr = tableAddress.substring(lastBang + 1);
+        targetSheetId = getSheetId(sheetName);
+    }
+    const parts = rangeStr.split(":");
+    const start = parts.length === 2 ? addressToCell(parts[0]) : addressToCell(rangeStr);
+    const end = parts.length === 2 ? addressToCell(parts[1]) : start;
+    if (!start || !end)
+        return precedents;
+    const minRow = Math.min(start.rowIndex, end.rowIndex);
+    const maxRow = Math.max(start.rowIndex, end.rowIndex);
+    const minCol = Math.min(start.columnIndex, end.columnIndex);
+    const maxCol = Math.max(start.columnIndex, end.columnIndex);
+    // Anchor cell: table-start row × (start col + col_index - 1) for VLOOKUP,
+    // (start row + row_index - 1) × table-start col for HLOOKUP.
+    const anchorRow = axis === "row" ? minRow + (offset - 1) : minRow;
+    const anchorCol = axis === "column" ? minCol + (offset - 1) : minCol;
+    // Out-of-bounds offset → can't form an anchor; fall back to the whole
+    // table so derivation still has something to work with.
+    if (anchorRow < minRow || anchorRow > maxRow || anchorCol < minCol || anchorCol > maxCol) {
+        return filterPrecedentsByAddress(precedents, tableAddress, currentSheetId, getSheetId);
+    }
+    return precedents.filter((p) => {
+        if (isStaticNode(p))
+            return true;
+        if (p.position.sheetId !== targetSheetId)
+            return false;
+        if (isCellCoordinate(p.position)) {
+            return (p.position.rowIndex === anchorRow &&
+                p.position.columnIndex === anchorCol);
+        }
+        const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = p.position;
+        return (startRowIndex <= anchorRow &&
+            endRowIndex >= anchorRow &&
+            startColumnIndex <= anchorCol &&
+            endColumnIndex >= anchorCol);
+    });
+};
+const filterPrecedentsByAddress = (precedents, address, currentSheetId, getSheetId) => {
+    let targetSheetId = currentSheetId;
+    let rangeStr = address;
+    if (address.includes("!")) {
+        const lastBang = address.lastIndexOf("!");
+        const sheetName = address.substring(0, lastBang).replace(/^'|'$/g, "");
+        rangeStr = address.substring(lastBang + 1);
+        targetSheetId = getSheetId(sheetName);
+    }
+    const parts = rangeStr.split(":");
+    let start;
+    let end;
+    if (parts.length === 2) {
+        start = addressToCell(parts[0]);
+        end = addressToCell(parts[1]);
+    }
+    else {
+        start = addressToCell(rangeStr);
+        end = start;
+    }
+    if (!start || !end)
+        return precedents;
+    const bounds = {
+        minRow: Math.min(start.rowIndex, end.rowIndex),
+        maxRow: Math.max(start.rowIndex, end.rowIndex),
+        minCol: Math.min(start.columnIndex, end.columnIndex),
+        maxCol: Math.max(start.columnIndex, end.columnIndex),
+    };
+    const filtered = precedents.filter((p) => {
+        if (isStaticNode(p))
+            return true;
+        if (p.position.sheetId !== targetSheetId)
+            return false;
+        if (isCellCoordinate(p.position)) {
+            const { rowIndex, columnIndex } = p.position;
+            return (rowIndex >= bounds.minRow &&
+                rowIndex <= bounds.maxRow &&
+                columnIndex >= bounds.minCol &&
+                columnIndex <= bounds.maxCol);
+        }
+        else {
+            const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = p.position;
+            return !(startRowIndex > bounds.maxRow ||
+                endRowIndex < bounds.minRow ||
+                startColumnIndex > bounds.maxCol ||
+                endColumnIndex < bounds.minCol);
+        }
+    });
+    return filtered.length > 0 ? filtered : precedents;
+};