@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/hooks/use-sheet-properties.js

@@ -0,0 +1,895 @@
+import { FormulaError } from "@rowsncolumns/fast-formula-parser";
+import { isCellWithinBounds } from "@rowsncolumns/grid";
+import { DEFAULT_COLUMN_COUNT, DEFAULT_COLUMN_WIDTH, DEFAULT_ROW_COUNT, DEFAULT_ROW_HEIGHT, isStyleReference, useCallbackRef, } from "@rowsncolumns/spreadsheet";
+import { cellToAddress, getCurrentLocale, getExtendedValueError, isNil, iterateCells, sortSheetsByIndex, } from "@rowsncolumns/utils";
+import { getCellEffectiveValue, getCellFormattedValue, getCellUserEnteredFormat, getCellUserEnteredValue, getExtendedValueBool, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, getStyleId, } from "@rowsncolumns/utils";
+import { useCallback, useMemo, useRef } from "react";
+import { useTokenizer } from "@rowsncolumns/spreadsheet";
+import { buildConditionalFormatExpression, isConditionalFormatFormulaRule, } from "../api/conditional-format";
+import { buildDataValidationExpression, isDataValidationFormulaRule, } from "../api/data-validation";
+import { formulaToRelativeReference } from "../api/formula";
+import { FormattedValueCache, FormulaFormatCache } from "../api/format-caches";
+import { deriveEffectiveNumberFormatFromPrecedents } from "../api/immer-utils";
+import { createFormattedValue, detectValueType } from "../api/datatype";
+import { LOADING_VALUE } from "../sheet-cell";
+import { getSharedStringRuns, getSharedStringText, } from "../types";
+/**
+ * Build a "format fingerprint" for the precedents of a formula cell — an
+ * array of effective `numberFormat` references, one per precedent. Used
+ * to invalidate the derived-format cache when a precedent's format
+ * changes (the precedent's value may stay the same, so value-only
+ * invalidation isn't enough).
+ *
+ * Uses a resolver to get the precedent's effective `numberFormat` —
+ * either `uf.numberFormat` (plain cell) or the recursively-derived
+ * format (formula cell). That way a change deep in the chain
+ * (`A1` → `B1=A1` → `C1=B1`) invalidates `C1`'s cache: `B1`'s derived
+ * format object identity changes, so `C1`'s fingerprint mismatches.
+ *
+ * Only the **anchor cell** is sampled for range references — matches
+ * Excel's first-cell inheritance behaviour and keeps cost O(1) per range
+ * (vs O(n) walking the whole range). Trade-off: changing a non-anchor
+ * cell's format inside a range won't invalidate the cache.
+ */
+const collectPrecedentFormatRefs = (precedents, defaultSheetId, resolveNumberFormat) => {
+    const refs = [];
+    for (const p of precedents) {
+        const position = p.position;
+        if (!position)
+            continue;
+        const sheetId = position.sheetId ?? defaultSheetId;
+        let row;
+        let col;
+        if ("rowIndex" in position) {
+            row = position.rowIndex;
+            col = position.columnIndex;
+        }
+        else if ("startRowIndex" in position) {
+            row = position.startRowIndex;
+            col = position.startColumnIndex;
+        }
+        else {
+            continue;
+        }
+        refs.push(resolveNumberFormat(sheetId, row, col));
+    }
+    return refs;
+};
+const shallowArrayRefEqual = (a, b) => {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (!Object.is(a[i], b[i]))
+            return false;
+    }
+    return true;
+};
+export const useSheetProperties = ({ conditionalFormats, sheetData, sheets, activeSheetId, dataValidations, protectFormulas, getEffectiveStructuredValue, cellXfs, cellXfsRegistry, cellStyles, sharedStrings, locale, use1904, lenientGrouping, getPrecedents, }) => {
+    /* Callback refs */
+    const getEffectiveStructuredValueRef = useCallbackRef(getEffectiveStructuredValue);
+    const tokenizer = useTokenizer();
+    /**
+     * Per-formula-cell number-format cache. Stores the value + precedent-uf
+     * fingerprint the format was derived from so we can invalidate cheaply
+     * when either changes (matches Excel's "format depends on result"
+     * semantics). Walking precedents is intensive — this avoids it on every
+     * render. LRU-bounded to keep memory predictable over long sessions.
+     */
+    const formulaNumberFormatCache = useRef(new FormulaFormatCache());
+    /**
+     * Two-level WeakMap cache for the (eff, der) → merged result.
+     * Keyed first by the user-entered format reference, then by the derived
+     * format reference. Both inputs already have stable identity per their
+     * own caches, so the same merged object is returned across renders unless
+     * one of the inputs actually changed. GC-friendly: when either input is
+     * replaced, the corresponding entry becomes unreachable and is collected.
+     */
+    const mergedFormatCache = useRef(new WeakMap());
+    /**
+     * Per-(locale, pattern, value) formatted-value cache. Shared across all
+     * formula cells — `createFormattedValue` is the expensive call we're
+     * memoising, and many cells share the same (value, pattern) tuple.
+     * LRU-bounded.
+     */
+    const formulaFormattedValueCache = useRef(new FormattedValueCache());
+    // Clear both formula caches on locale change. The fingerprints don't
+    // include locale (value + precedent refs are locale-agnostic), but
+    // the *output* depends on locale — synthesized DATE/TIME default
+    // patterns (`m/d/yyyy` vs `d/m/yyyy`), formatted-value strings, etc.
+    //
+    // Done **during render** (not via `useEffect`) because the cell
+    // renderer reads from these caches inside its `useMemo` in the same
+    // render pass. A `useEffect` fires *after* commit — by then the stale
+    // format has already painted, and nothing else triggers a follow-up
+    // render to correct it (the user reported `=TODAY()` staying on the
+    // old locale's pattern after switching). Comparing the previous
+    // locale against the current one in render lets the clear happen
+    // before any cache read in this pass. Mutating a ref during render
+    // is safe here: the work is idempotent (we guard on the ref so a
+    // single render only clears once) and there are no external side
+    // effects.
+    const prevLocaleRef = useRef(locale);
+    if (prevLocaleRef.current !== locale) {
+        formulaFormattedValueCache.current.clear();
+        formulaNumberFormatCache.current.clear();
+        prevLocaleRef.current = locale;
+    }
+    // Note: we deliberately do NOT clear `formulaNumberFormatCache` on
+    // row/column insert/delete. The cache fingerprint `(value,
+    // precedentUfRefs)` self-corrects on structural changes — after a shift
+    // the cell at a given `(sheetId, r, c)` is a different cell with
+    // different value/precedent refs, so the fingerprint mismatches and the
+    // entry is recomputed naturally. Stale entries that survive sit until
+    // LRU eviction; they're memory, not a correctness issue.
+    // Sheet property by id
+    const [sheetnameBySheetId, sheetIdByName, sheetPropertiesById, sheetMetaDataById,] = useMemo(() => {
+        const sheetnameById = new Map();
+        const sheetIdByName = new Map();
+        const sheetPropertiesById = new Map();
+        const sheetMetaDataById = new Map();
+        for (const sheet of sheets) {
+            if (sheet) {
+                const { sheetId, title, rowCount = DEFAULT_ROW_COUNT, columnCount = DEFAULT_COLUMN_COUNT, rowMetadata, columnMetadata, frozenRowCount, frozenColumnCount, } = sheet;
+                sheetnameById.set(sheetId, title);
+                sheetIdByName.set(title, sheetId);
+                sheetPropertiesById.set(sheetId, {
+                    rowCount: rowCount ?? DEFAULT_ROW_COUNT,
+                    columnCount: columnCount ?? DEFAULT_COLUMN_COUNT,
+                    frozenRowCount: frozenRowCount ?? 0,
+                    frozenColumnCount: frozenColumnCount ?? 0,
+                });
+                sheetMetaDataById.set(sheetId, {
+                    rowMetadata: rowMetadata,
+                    columnMetadata: columnMetadata,
+                });
+            }
+        }
+        return [
+            sheetnameById,
+            sheetIdByName,
+            sheetPropertiesById,
+            sheetMetaDataById,
+        ];
+    }, [sheets]);
+    // Get Conditional format formula value
+    const conditionalFormatById = useMemo(() => {
+        const map = new Map();
+        if (conditionalFormats) {
+            for (const rule of conditionalFormats) {
+                map.set(rule.id, rule);
+            }
+        }
+        return map;
+    }, [conditionalFormats]);
+    // By Id
+    const dataValidationsById = useMemo(() => {
+        const map = new Map();
+        for (const d of dataValidations ?? []) {
+            map.set(d.id, d);
+        }
+        return map;
+    }, [dataValidations]);
+    // Get conditional formatting
+    const getConditionalFormattingById = useCallback((id) => {
+        return conditionalFormatById.get(id);
+    }, [conditionalFormatById]);
+    // Get data validations
+    const getDataValidationById = useCallback((id) => {
+        return dataValidationsById.get(id);
+    }, [dataValidationsById]);
+    // Get column width
+    const getColumnWidth = useCallback((sheetId, columnIndex) => {
+        return (sheetMetaDataById.get(sheetId)?.columnMetadata?.[columnIndex]?.size ??
+            DEFAULT_COLUMN_WIDTH);
+    }, [sheetMetaDataById]);
+    // Check if a row is resized by user
+    const isRowResizedByUser = useCallback((sheetId, rowIndex) => sheetMetaDataById.get(sheetId)?.rowMetadata?.[rowIndex]?.resizedByUser, [sheetMetaDataById]);
+    // Get row height
+    const getRowHeight = useCallback((sheetId, rowIndex) => {
+        return (sheetMetaDataById.get(sheetId)?.rowMetadata?.[rowIndex]?.size ??
+            DEFAULT_ROW_HEIGHT);
+    }, [sheetMetaDataById]);
+    // Get row count
+    const getSheetRowCount = useCallback((sheetId) => {
+        return sheetPropertiesById.get(sheetId)?.rowCount ?? DEFAULT_ROW_COUNT;
+    }, [sheetPropertiesById]);
+    // Get column count
+    const getSheetColumnCount = useCallback((sheetId) => {
+        return (sheetPropertiesById.get(sheetId)?.columnCount ?? DEFAULT_COLUMN_COUNT);
+    }, [sheetPropertiesById]);
+    // Non blank rows
+    const getDataRowCount = useCallback((sheetId = activeSheetId) => sheetData?.[sheetId]?.length ?? undefined, [sheetData, activeSheetId]);
+    // Get non empty row count
+    const getNonEmptyRowCount = useCallback((sheetId) => sheetData?.[sheetId]?.length ?? undefined, [sheetData]);
+    // Number of columns that have data in a row
+    const getNonEmptyColumnCount = useCallback((sheetId, rowIndex) => {
+        return sheetData?.[sheetId]?.[rowIndex]?.values?.length ?? undefined;
+    }, [sheetData]);
+    // Get column count for a sheet
+    const getDataColumnCount = useCallback((sheetId) => {
+        let cur = 0;
+        const rowData = sheetData?.[sheetId];
+        if (!rowData) {
+            return 0;
+        }
+        for (const rowIndex in rowData) {
+            cur = Math.max(cur, (rowData?.[rowIndex]?.values?.length ?? 0) - 1);
+        }
+        return cur;
+    }, [sheetData]);
+    // Get non empty row count
+    const getActualRowCount = useCallback((sheetId) => sheetData?.[sheetId]?.length ?? 0, [sheetData]);
+    // Get frozen row count
+    const getFrozenRowCount = useCallback((sheetId) => sheetPropertiesById.get(sheetId)?.frozenRowCount ?? 0, [sheetPropertiesById]);
+    // Hidden row
+    const isHiddenRow = useCallback((sheetId, rowIndex) => {
+        const metaData = sheetMetaDataById.get(sheetId)?.rowMetadata?.[rowIndex];
+        return Boolean(metaData?.hiddenByUser || metaData?.hiddenByFilter);
+    }, [sheetMetaDataById]);
+    // Hidden by filter row
+    const isHiddenByFilterRow = useCallback((sheetId, rowIndex) => {
+        const metaData = sheetMetaDataById.get(sheetId)?.rowMetadata?.[rowIndex];
+        return Boolean(metaData?.hiddenByFilter);
+    }, [sheetMetaDataById]);
+    // Hidden column
+    const isColumnHidden = useCallback((sheetId, columnIndex) => {
+        const metaData = sheetMetaDataById.get(sheetId)?.columnMetadata?.[columnIndex];
+        return Boolean(metaData?.hiddenByUser || metaData?.hiddenByFilter);
+    }, [sheetMetaDataById]);
+    // Get sheet count. Used for formuls
+    const getSheetCount = useCallbackRef(useCallback(() => sheets.length, [sheets]));
+    // Get sheet name. Used for formuls
+    const getSheetName = useCallbackRef(useCallback((sheetId) => sheetnameBySheetId.get(sheetId), [sheetnameBySheetId]));
+    // Get sheet Id by sheet name
+    const getSheetId = useCallbackRef(useCallback((sheetname) => {
+        return sheetIdByName.get(sheetname);
+    }, [sheetIdByName]));
+    // Ordered sheets
+    const sheetIndexByName = useMemo(() => {
+        const orderedSheets = sortSheetsByIndex(sheets, true);
+        const map = new Map();
+        orderedSheets.forEach((sheet, index) => {
+            map.set(sheet.title, index + 1);
+        });
+        return map;
+    }, [sheets]);
+    // For calculator
+    const getSheetIndex = useCallbackRef(useCallback((sheetName) => {
+        const resolvedName = sheetName ?? sheetnameBySheetId.get(activeSheetId);
+        if (!resolvedName) {
+            return undefined;
+        }
+        return sheetIndexByName.get(resolvedName);
+    }, [sheetnameBySheetId, activeSheetId]));
+    // Get sheet Id by sheet name
+    const getSheetProperties = useCallbackRef(useCallback((sheetId) => {
+        return sheetPropertiesById.get(sheetId);
+    }, [sheetPropertiesById]));
+    // Get cell data of active sheet
+    const getCellData = useCallback((sheetId, rowIndex, columnIndex) => {
+        return sheetData?.[sheetId]?.[rowIndex]?.values?.[columnIndex];
+    }, [sheetData]);
+    /**
+     * Get mentions from a cell
+     */
+    const getMentionsFromCell = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        if (isNil(cellData?.ss) || !sharedStrings)
+            return undefined;
+        // Mentions ride along on the SharedStrings rich entry the cell
+        // points at, same as bold/italic runs.
+        const runs = getSharedStringRuns(sharedStrings.get(String(cellData.ss)));
+        return runs?.filter((run) => run.nodeType === "mention");
+    }, [getCellData, sharedStrings]);
+    /**
+     * Get textFormat runs from a cell
+     */
+    const getTextFormatRuns = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        if (isNil(cellData?.ss) || !sharedStrings)
+            return undefined;
+        // Rich-text runs are persisted on the SharedStrings entry the
+        // cell points at via `ss`. Returns `undefined` when the entry
+        // is plain or the cell isn't interned.
+        return getSharedStringRuns(sharedStrings.get(String(cellData.ss)));
+    }, [getCellData, sharedStrings]);
+    /**
+     * Get hyperlink runs from a cell
+     */
+    const getHyperLink = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        return cellData?.hyperlink;
+    }, [getCellData]);
+    const getHyperlinkText = useCallback((hyperlink) => {
+        if (!hyperlink) {
+            return undefined;
+        }
+        if (typeof hyperlink === "string") {
+            return hyperlink;
+        }
+        if (hyperlink.kind === "external") {
+            return hyperlink.url;
+        }
+        return hyperlink.location;
+    }, []);
+    const getSharedStringValue = useCallback((cellData) => {
+        if (cellData?.ss == null || !sharedStrings) {
+            return undefined;
+        }
+        // SharedStrings may hold a plain string OR a rich object
+        // (`{text, runs}`). Callers that need the displayed text get a
+        // string here; the runs are surfaced separately via
+        // `getTextFormatRuns`.
+        const value = sharedStrings.get(String(cellData.ss));
+        return getSharedStringText(value);
+    }, [sharedStrings]);
+    const getEffectiveValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        if (!cellData) {
+            return undefined;
+        }
+        // Check for shared strings
+        const sharedStringValue = getSharedStringValue(cellData);
+        if (!isNil(sharedStringValue)) {
+            return sharedStringValue;
+        }
+        const effectiveValue = getCellEffectiveValue(cellData);
+        if (!effectiveValue) {
+            return undefined;
+        }
+        return (getExtendedValueBool(effectiveValue) ??
+            getExtendedValueNumber(effectiveValue) ??
+            getExtendedValueString(effectiveValue));
+    }, [getCellData, getSharedStringValue]);
+    // For backwards compat
+    const getEffectiveExtendedValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        const effectiveValue = getCellEffectiveValue(cellData);
+        const errorValue = getExtendedValueError(effectiveValue);
+        if (errorValue) {
+            return effectiveValue;
+        }
+        const sharedStringValue = getSharedStringValue(cellData);
+        if (sharedStringValue !== undefined) {
+            return { sv: sharedStringValue };
+        }
+        return effectiveValue;
+    }, [getCellData, getSharedStringValue]);
+    // For backwards compat
+    const getUserEnteredExtendedValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        const sharedStringValue = getSharedStringValue(cellData);
+        if (sharedStringValue !== undefined) {
+            return { sv: sharedStringValue };
+        }
+        return getCellUserEnteredValue(cellData);
+    }, [getCellData, getSharedStringValue]);
+    /**
+     * Get error value of a cell
+     */
+    const getErrorValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        const effectiveValue = getCellEffectiveValue(cellData);
+        return getExtendedValueError(effectiveValue);
+    }, [getCellData]);
+    /**
+     * Return structured value for calculation
+     */
+    const getEffectiveValueForCalculation = useCallbackRef(useCallback((sheetId, rowIndex, columnIndex, property) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        // User us always accessing a structured value
+        if (property) {
+            return getEffectiveStructuredValueRef?.(getCellEffectiveValue(getCellData(sheetId, rowIndex, columnIndex))
+                ?.structuredValue, property);
+        }
+        // Check if error value - but skip validation errors (type: "Invalid")
+        // Validation errors are visual indicators only and should not affect formulas
+        const effectiveValue = getCellEffectiveValue(cellData);
+        const errorValue = getExtendedValueError(effectiveValue);
+        if (errorValue && errorValue.type !== "Invalid") {
+            return new FormulaError(errorValue.name, errorValue.message);
+        }
+        const hyperlink = getHyperlinkText(getHyperLink(sheetId, rowIndex, columnIndex));
+        return (hyperlink ??
+            getEffectiveValue(sheetId, rowIndex, columnIndex) ??
+            hyperlink ??
+            getEffectiveStructuredValueRef?.(effectiveValue?.structuredValue) ??
+            effectiveValue?.structuredValue);
+    }, [
+        getCellData,
+        getEffectiveValue,
+        getHyperLink,
+        getEffectiveStructuredValueRef,
+    ]));
+    /**
+     * Resolve a formula cell's derived number format. Returns `undefined`
+     * for non-formula cells, when `uf.numberFormat` is set, or when no
+     * derivation is possible.
+     *
+     * Single-pass derivation from **direct** precedents only — no
+     * recursion, no transitive walk. When a precedent is itself a formula
+     * cell, its derived format is read from the per-cell LRU cache
+     * populated during an earlier `getDerivedFormat` call. The cache
+     * fingerprint `(value, precedentUfRefs)` invalidates this cell
+     * automatically whenever a direct precedent's format object identity
+     * changes — so a chain like `C1 = B1 = A1 = TODAY()` settles via
+     * normal cache invalidation: A1 derives DATE → B1's fingerprint sees
+     * the new DATE ref → B1 re-derives DATE → C1's fingerprint sees B1's
+     * new ref → C1 re-derives DATE. The renderer's row-major iteration
+     * naturally visits precedents before dependents in the common case,
+     * so this converges in a single render.
+     */
+    const getDerivedFormat = useCallback((sheetId, rowIndex, columnIndex) => {
+        const rootCell = getCellData(sheetId, rowIndex, columnIndex);
+        if (!rootCell)
+            return undefined;
+        const rootFormula = getExtendedValueFormula(getCellUserEnteredValue(rootCell));
+        if (!rootFormula)
+            return undefined;
+        const resolveUf = (cell) => {
+            const uf = getCellUserEnteredFormat(cell);
+            return isStyleReference(uf)
+                ? cellXfs?.get(getStyleId(uf)) ?? undefined
+                : uf ?? undefined;
+        };
+        if (resolveUf(rootCell)?.numberFormat)
+            return undefined;
+        if (!getPrecedents || !sheetData)
+            return undefined;
+        // Look up a precedent's numberFormat without walking its chain.
+        // The LRU cache holds the last-rendered derived format for any
+        // formula cell we've previously processed; for plain cells (no
+        // formula) we read `uf.numberFormat` directly. If the cache entry
+        // is stale, the consumer's own fingerprint (built below) will
+        // detect it next render and re-derive.
+        const resolveNumberFormat = (psId, pr, pc) => {
+            const cached = formulaNumberFormatCache.current.get(psId, pr, pc);
+            if (cached)
+                return cached.numberFormat;
+            const pCell = sheetData?.[psId]?.[pr]?.values?.[pc];
+            if (!pCell)
+                return undefined;
+            return resolveUf(pCell)?.numberFormat ?? undefined;
+        };
+        const effectiveValue = getCellEffectiveValue(rootCell);
+        const currentValue = getExtendedValueNumber(effectiveValue) ??
+            getExtendedValueString(effectiveValue) ??
+            getExtendedValueBool(effectiveValue);
+        const directPrecedents = getPrecedents({
+            sheetId,
+            rowIndex,
+            columnIndex,
+        });
+        const currentPrecedentFormatRefs = collectPrecedentFormatRefs(directPrecedents, sheetId, resolveNumberFormat);
+        const cached = formulaNumberFormatCache.current.get(sheetId, rowIndex, columnIndex);
+        if (cached &&
+            Object.is(cached.value, currentValue) &&
+            shallowArrayRefEqual(cached.precedentUfRefs, currentPrecedentFormatRefs)) {
+            return cached.format;
+        }
+        const derivedNumberFormat = deriveEffectiveNumberFormatFromPrecedents(rootFormula, directPrecedents, sheetData, tokenizer, sheetId, rowIndex, columnIndex, locale, getSheetId, cellXfsRegistry, getDataValidationById, typeof currentValue === "number" ? currentValue : null, resolveNumberFormat);
+        const numberFormat = derivedNumberFormat ?? undefined;
+        const format = numberFormat
+            ? { numberFormat }
+            : undefined;
+        formulaNumberFormatCache.current.set(sheetId, rowIndex, columnIndex, {
+            value: currentValue,
+            precedentUfRefs: currentPrecedentFormatRefs,
+            numberFormat,
+            format,
+        });
+        return format;
+    }, [
+        getCellData,
+        cellXfs,
+        cellXfsRegistry,
+        getDataValidationById,
+        getPrecedents,
+        sheetData,
+        tokenizer,
+        locale,
+        getSheetId,
+    ]);
+    /**
+     * Resolve the rendered cell format: user-entered layer (style-ref-resolved
+     * via `cellXfs`) merged with the precedent-derived `numberFormat` for
+     * formula cells. Returns the user format alone for non-formula cells, or
+     * when an explicit `uf.numberFormat` already wins (`getDerivedFormat`
+     * short-circuits in that case).
+     *
+     * Plain `useCallback` — `libs/grid` invokes this via the cellRenderer
+     * **during** its `cells` useMemo (render phase). A `useCallbackRef`
+     * wrapper updates its internal ref in `useLayoutEffect` (post-commit),
+     * so during-render calls would read the previous render's closure — and
+     * miss fresh `sheetData`. That caused precedent-derived format updates
+     * (e.g. A1 → currency propagating to B1 = SUM(A1, 4)) to lag by a render.
+     * With `useCallback`, identity churns when `sheetData` / deps change,
+     * which is exactly the repaint signal the downstream memos need.
+     * Per-cell merged-result identity is still preserved by the (eff, der)
+     * WeakMap cache below.
+     */
+    const getEffectiveFormat = useCallback((sheetId, rowIndex, columnIndex) => {
+        let eff;
+        if (cellStyles) {
+            // Engine-authoritative styles: the map is the SOLE source of a cell's user format. A missing
+            // entry means "no format" (so an undo that clears the entry actually clears the cell) — we
+            // intentionally do NOT fall back to the cell's own `uf`/`cellXfs` here.
+            eff = cellStyles.get(`${sheetId}!${cellToAddress({ rowIndex, columnIndex }, false, false)}`);
+        }
+        else {
+            const cellData = getCellData(sheetId, rowIndex, columnIndex);
+            const userEnteredFormat = getCellUserEnteredFormat(cellData);
+            eff = isStyleReference(userEnteredFormat)
+                ? cellXfs?.get(getStyleId(userEnteredFormat))
+                : userEnteredFormat;
+        }
+        const der = getDerivedFormat(sheetId, rowIndex, columnIndex);
+        if (!der)
+            return eff;
+        if (!eff)
+            return der;
+        let inner = mergedFormatCache.current.get(eff);
+        if (!inner) {
+            inner = new WeakMap();
+            mergedFormatCache.current.set(eff, inner);
+        }
+        let merged = inner.get(der);
+        if (!merged) {
+            merged = { ...eff, ...der };
+            inner.set(der, merged);
+        }
+        return merged;
+    }, [getCellData, getDerivedFormat, cellStyles, cellXfs]);
+    /**
+     * Get formula value entered by user
+     */
+    const getFormulaValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        if (!cellData)
+            return undefined;
+        const userEnteredValue = getCellUserEnteredValue(cellData);
+        if (!userEnteredValue)
+            return undefined;
+        return getExtendedValueFormula(userEnteredValue);
+    }, [getCellData]);
+    /**
+     * Get formatted value.
+     *
+     * Non-formula cells: read persisted `fv` (set at write time).
+     * Formula cells with a structured value: read `effectiveValue.structuredValue`.
+     * Scalar formula cells: derive via `createFormattedValue(value, type, pattern, locale)`,
+     * memoised by `(locale, pattern, value)` since many formula cells share
+     * the same tuple.
+     */
+    const getFormattedValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        // Check for shared strings
+        const sharedStringValue = getSharedStringValue(cellData);
+        if (sharedStringValue !== undefined) {
+            // Excel display parity: a lone text-prefix apostrophe (`'`) renders
+            // as a blank cell — the `'` stays visible only in the formula bar.
+            return sharedStringValue === "'" ? "" : sharedStringValue;
+        }
+        const userEnteredValue = getCellUserEnteredValue(cellData);
+        const formula = getExtendedValueFormula(userEnteredValue);
+        if (!formula) {
+            // Excel display parity: a user-entered lone text-prefix apostrophe
+            // (`'`) renders as a blank cell (the formula bar still shows the `'`).
+            if (getExtendedValueString(userEnteredValue) === "'") {
+                return "";
+            }
+            return getCellFormattedValue(cellData);
+        }
+        // Formula cells normally derive their display string from
+        // effectiveValue + uf at render time, ignoring any persisted `fv`.
+        // While a recalc is in flight calc-begin pins `fv = "Loading..."`
+        // on the cellData; honor that placeholder here so the renderer
+        // surfaces the loading indicator instead of the stale ev value.
+        const persistedFormattedValue = getCellFormattedValue(cellData);
+        if (persistedFormattedValue === LOADING_VALUE) {
+            return persistedFormattedValue;
+        }
+        // Formula cells from this point on
+        const effectiveValue = getCellEffectiveValue(cellData);
+        const structured = effectiveValue
+            ?.structuredValue;
+        if (structured) {
+            switch (structured.kind) {
+                case "hyperlink":
+                    return structured.title ?? structured.url;
+                case "image":
+                    return "";
+                case "sparkline":
+                default:
+                    return structured.formattedValue;
+            }
+        }
+        const errorValue = getExtendedValueError(effectiveValue);
+        if (errorValue) {
+            return errorValue.name ?? "#ERROR!";
+        }
+        const value = getExtendedValueNumber(effectiveValue) ??
+            getExtendedValueString(effectiveValue) ??
+            getExtendedValueBool(effectiveValue);
+        if (isNil(value)) {
+            return undefined;
+        }
+        const uf = getEffectiveFormat(sheetId, rowIndex, columnIndex);
+        const pattern = uf?.numberFormat?.pattern ?? "General";
+        const valueType = detectValueType(value, locale, lenientGrouping) ?? "stringValue";
+        const cacheLocale = locale ?? getCurrentLocale();
+        const cached = formulaFormattedValueCache.current.get(cacheLocale, pattern, valueType, value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const formatted = createFormattedValue(value, valueType, pattern, locale);
+        if (formatted !== undefined) {
+            formulaFormattedValueCache.current.set(cacheLocale, pattern, valueType, value, formatted);
+        }
+        return formatted;
+    }, [
+        getCellData,
+        getSharedStringValue,
+        getEffectiveFormat,
+        locale,
+        lenientGrouping,
+    ]);
+    /**
+     * Get value entered by the user in a cell
+     */
+    const getUserEnteredValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        const sharedStringValue = getSharedStringValue(cellData);
+        if (sharedStringValue !== undefined) {
+            return { sv: sharedStringValue };
+        }
+        return getCellUserEnteredValue(cellData);
+    }, [getCellData, getSharedStringValue]);
+    // Get user entered value of a cell
+    // Remove useCallbackRef as its being in FloatingCellEditor
+    const getUserEnteredStringValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const formulaValue = getFormulaValue(sheetId, rowIndex, columnIndex);
+        if (formulaValue && !protectFormulas) {
+            return formulaValue;
+        }
+        const userEnteredValue = getUserEnteredValue(sheetId, rowIndex, columnIndex);
+        const stringValue = getExtendedValueString(userEnteredValue);
+        if (stringValue) {
+            return stringValue;
+        }
+        return undefined;
+    }, [getUserEnteredValue, protectFormulas, getFormulaValue]);
+    // Stable reference for calculator
+    const getUserEnteredValueStable = useCallbackRef(getUserEnteredStringValue);
+    // Get the conditional format formula value
+    const getConditionalFormatFormula = useCallbackRef(useCallback((sheetId, rowIndex, columnIndex, conditionalFormatId) => {
+        const rule = conditionalFormatById.get(conditionalFormatId);
+        if (!rule) {
+            return undefined;
+        }
+        const formulaValue = isConditionalFormatFormulaRule(rule)
+            ? buildConditionalFormatExpression(rule, cellToAddress({
+                rowIndex: rule?.ranges?.[0]?.startRowIndex ?? 1,
+                columnIndex: rule?.ranges?.[0]?.startColumnIndex ?? 1,
+            }, false, false) ?? "A1", locale)
+            : undefined;
+        if (rule.ranges.length && formulaValue) {
+            const masterCell = {
+                rowIndex: rule.ranges[0].startRowIndex,
+                columnIndex: rule.ranges[0].startColumnIndex,
+            };
+            const activeSheetName = getSheetName(sheetId) ?? "";
+            for (const range of rule.ranges) {
+                if (sheetId === range.sheetId &&
+                    isCellWithinBounds({ rowIndex, columnIndex }, range)) {
+                    const newFormula = formulaToRelativeReference(formulaValue, masterCell, { rowIndex, columnIndex }, activeSheetName, { ignoreCircular: true, preserveAbsolutes: true });
+                    return newFormula;
+                }
+            }
+        }
+    }, [conditionalFormatById, getSheetName]));
+    // Get getDataValidation formula value
+    const getDataValidationFormula = useCallbackRef(useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        // Check if its a
+        let dataValidation = cellData?.dataValidation;
+        if (typeof dataValidation === "string" ||
+            typeof dataValidation === "number") {
+            dataValidation = getDataValidationById(dataValidation);
+        }
+        const formulaValue = isDataValidationFormulaRule(dataValidation)
+            ? buildDataValidationExpression(dataValidation, cellToAddress({
+                rowIndex: dataValidation?.ranges?.[0]
+                    ?.startRowIndex ?? 1,
+                columnIndex: dataValidation?.ranges?.[0]
+                    ?.startColumnIndex ?? 1,
+            }, false, false) ?? "A1", locale)
+            : undefined;
+        if (formulaValue &&
+            dataValidation.ranges) {
+            const masterCell = {
+                rowIndex: dataValidation.ranges[0]
+                    .startRowIndex,
+                columnIndex: dataValidation.ranges[0]
+                    .startColumnIndex,
+            };
+            const activeSheetName = getSheetName(sheetId) ?? "";
+            return (formulaToRelativeReference(formulaValue, masterCell, { rowIndex, columnIndex }, activeSheetName, { ignoreCircular: true, preserveAbsolutes: true }) ?? "");
+        }
+        return formulaValue;
+    }, [getCellData, getDataValidationById, getSheetName]));
+    // Get getDataValidation
+    const getDataValidation = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        // Check if its a
+        let dataValidation = cellData?.dataValidation;
+        if (typeof dataValidation === "string" ||
+            typeof dataValidation === "number") {
+            dataValidation = getDataValidationById(dataValidation);
+        }
+        return dataValidation;
+    }, [getCellData, getDataValidationById]);
+    // Get current sheet Id
+    const getActiveSheetId = useCallbackRef(useCallback(() => activeSheetId, [activeSheetId]));
+    // User entered format
+    const getUserEnteredFormat = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cellData = getCellData(sheetId, rowIndex, columnIndex);
+        if (!cellData)
+            return undefined;
+        return getCellUserEnteredFormat(cellData);
+    }, [getCellData]);
+    // Useful for charts, get series data values
+    // Do not use useCallbackRef, so charts can update
+    // when columns and rows are hidden
+    const getSeriesValuesFromRange = useCallback((sheetRange, hiddenDimensionStategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const effectiveValues = [];
+        const { sheetId } = sheetRange;
+        const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = sheetRange;
+        for (const [rowIndex, columnIndex] of iterateCells(startRowIndex, endColumnIndex, endRowIndex, startColumnIndex)) {
+            if (hiddenDimensionStategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" &&
+                (isHiddenRow(sheetId, rowIndex) ||
+                    isColumnHidden(sheetId, columnIndex))) {
+                continue;
+            }
+            const effectiveValue = getEffectiveValue(sheetId, rowIndex, columnIndex);
+            effectiveValues.push(effectiveValue);
+        }
+        return effectiveValues;
+    }, [getEffectiveValue, isColumnHidden, isHiddenRow]);
+    // Useful for charts, get domain values
+    // Do not use useCallbackRef, so charts can update
+    // when columns and rows are hidden
+    const getDomainValuesFromRange = useCallback((sheetRange, hiddenDimensionStategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const formattedValues = [];
+        const { sheetId } = sheetRange;
+        const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = sheetRange;
+        for (const [rowIndex, columnIndex] of iterateCells(startRowIndex, endColumnIndex, endRowIndex, startColumnIndex)) {
+            if (hiddenDimensionStategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" &&
+                (isHiddenRow(sheetId, rowIndex) ||
+                    isColumnHidden(sheetId, columnIndex))) {
+                continue;
+            }
+            const formattedValue = getFormattedValue(sheetId, rowIndex, columnIndex);
+            formattedValues.push(formattedValue);
+        }
+        return formattedValues;
+    }, [isHiddenRow, isColumnHidden, getFormattedValue]);
+    // Get formatting information from a range
+    const getFormattingFromRange = useCallback((sheetRange, hiddenDimensionStategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const formattingValues = [];
+        const { sheetId } = sheetRange;
+        const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = sheetRange;
+        for (const [rowIndex, columnIndex] of iterateCells(startRowIndex, endColumnIndex, endRowIndex, startColumnIndex)) {
+            if (hiddenDimensionStategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" &&
+                (isHiddenRow(sheetId, rowIndex) ||
+                    isColumnHidden(sheetId, columnIndex))) {
+                continue;
+            }
+            // Return the rendered format consumers actually see (auto-derived
+            // bits, formula precedent format, CF overlay) — NOT raw `ef` which
+            // is no longer persisted on cellData.
+            const effectiveFormat = getEffectiveFormat(sheetId, rowIndex, columnIndex);
+            formattingValues.push(effectiveFormat);
+        }
+        return formattingValues;
+    }, [isHiddenRow, isColumnHidden, getEffectiveFormat]);
+    // Get user entered values from a range
+    const getUserEnteredValuesFromRange = useCallback((sheetRange, hiddenDimensionStategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const userEnteredValues = [];
+        const { sheetId } = sheetRange;
+        const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = sheetRange;
+        for (const [rowIndex, columnIndex] of iterateCells(startRowIndex, endColumnIndex, endRowIndex, startColumnIndex)) {
+            if (hiddenDimensionStategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" &&
+                (isHiddenRow(sheetId, rowIndex) ||
+                    isColumnHidden(sheetId, columnIndex))) {
+                continue;
+            }
+            const userEnteredValue = getUserEnteredStringValue(sheetId, rowIndex, columnIndex);
+            userEnteredValues.push(userEnteredValue);
+        }
+        return userEnteredValues;
+    }, [getUserEnteredStringValue, isColumnHidden, isHiddenRow]);
+    // Get user entered values from a range
+    const getFormulasFromRange = useCallback((sheetRange, hiddenDimensionStategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const formulas = [];
+        const { sheetId } = sheetRange;
+        const { startRowIndex, startColumnIndex, endRowIndex, endColumnIndex } = sheetRange;
+        for (const [rowIndex, columnIndex] of iterateCells(startRowIndex, endColumnIndex, endRowIndex, startColumnIndex)) {
+            if (hiddenDimensionStategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" &&
+                (isHiddenRow(sheetId, rowIndex) ||
+                    isColumnHidden(sheetId, columnIndex))) {
+                continue;
+            }
+            const formula = getFormulaValue(sheetId, rowIndex, columnIndex);
+            formulas.push(formula);
+        }
+        return formulas;
+    }, [getFormulaValue, isColumnHidden, isHiddenRow]);
+    // Get array of records from a given range
+    const getColumnarDataFromRange = useCallbackRef(useCallback((sheetRange) => {
+        const columnarData = {};
+        for (let columnIndex = sheetRange.startColumnIndex; columnIndex <= sheetRange.endColumnIndex; columnIndex++) {
+            const columnName = getFormattedValue(sheetRange.sheetId, sheetRange.startRowIndex, columnIndex);
+            if (!isNil(columnName)) {
+                columnarData[columnName] = [];
+            }
+            for (let rowIndex = sheetRange.startRowIndex; rowIndex <= sheetRange.endRowIndex; rowIndex++) {
+                if (rowIndex === sheetRange.startRowIndex) {
+                    continue;
+                }
+                const fieldValue = getEffectiveValue(sheetRange.sheetId, rowIndex, columnIndex) ??
+                    "";
+                if (!isNil(columnName)) {
+                    columnarData[columnName].push(fieldValue);
+                }
+            }
+        }
+        return columnarData;
+    }, [getEffectiveValue, getFormattedValue]));
+    return {
+        getDataRowCount,
+        getNonEmptyRowCount,
+        getNonEmptyColumnCount,
+        getSheetId,
+        getSheetName,
+        getSheetCount,
+        getSheetIndex,
+        getSheetProperties,
+        getCellData,
+        getMentionsFromCell,
+        getTextFormatRuns,
+        getUserEnteredValue: getUserEnteredStringValue,
+        getUserEnteredValueStable,
+        getConditionalFormatFormula,
+        getDataValidationFormula,
+        getErrorValue,
+        getEffectiveValue,
+        getEffectiveValueForCalculation,
+        getFormattedValue,
+        getEffectiveFormat,
+        getActiveSheetId,
+        getUserEnteredFormat,
+        getSeriesValuesFromRange,
+        getDomainValuesFromRange,
+        getColumnarDataFromRange,
+        getUserEnteredValuesFromRange,
+        getFormattingFromRange,
+        getFormulasFromRange,
+        isHiddenRow,
+        isHiddenByFilterRow,
+        getSheetRowCount,
+        getSheetColumnCount,
+        getColumnWidth,
+        getRowHeight,
+        isColumnHidden,
+        isRowResizedByUser,
+        getDataColumnCount,
+        getActualRowCount,
+        getFrozenRowCount,
+        getDataValidation,
+        getDataValidationById,
+        getConditionalFormattingById,
+        getEffectiveExtendedValue,
+        getUserEnteredExtendedValue,
+    };
+};