@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/hooks/use-calculation-initialize.js

@@ -0,0 +1,603 @@
+import { useCallbackRef } from "@rowsncolumns/spreadsheet";
+import { useIsomorphicLayoutEffect, usePrevious, } from "@rowsncolumns/spreadsheet";
+import { addressToSelection, isNil, iterateCellsInRange, } from "@rowsncolumns/utils";
+import { useCallback, useRef } from "react";
+import { isConditionalFormatFormulaRule } from "../api/conditional-format";
+import { isDataValidationFormulaRule } from "../api/data-validation";
+import { createSheetCellIdentifier } from "../api/formula";
+import { getFunctionNamesFromFormula } from "../api/immer-utils";
+import { SheetCell } from "../sheet-cell";
+// For calc
+const CALC_EPHEMERAL_FUNCTIONS = new Set(["NOW", "TODAY"]);
+// Functions that aren't volatile but still need their effective value
+// materialized to be useful — `SPARKLINE` builds the `structuredValue`
+// the chart renderer reads, so a DAG-only seed would leave the cell
+// holding raw formula text. Keep this distinct from the volatile set
+// so the "force eval" predicate stays readable when more render-payload
+// functions land here (e.g. `HYPERLINK`, `IMAGE`).
+const CALC_REQUIRES_EVAL_FUNCTIONS = new Set(["SPARKLINE"]);
+/**
+ * Maximum number of cells to evaluate for conditional formatting/data validation
+ * Prevents performance issues with massive ranges like row 2 to 1048576
+ */
+const MAX_RANGE_CELLS_FOR_EVALUATION = 10000;
+/** Buffer rows/columns around viewport for smooth scrolling */
+const VIEWPORT_BUFFER_ROWS = 50;
+const VIEWPORT_BUFFER_COLUMNS = 20;
+/**
+ * Clamps a range to viewport + buffer zone.
+ * Returns undefined if range doesn't intersect with viewport.
+ */
+const clampRangeToViewport = (range, viewport) => {
+    // Calculate buffered viewport bounds
+    const viewportStartRow = Math.max(0, viewport.visibleRowStartIndex - VIEWPORT_BUFFER_ROWS);
+    const viewportEndRow = viewport.visibleRowStopIndex + VIEWPORT_BUFFER_ROWS;
+    const viewportStartCol = Math.max(0, viewport.visibleColumnStartIndex - VIEWPORT_BUFFER_COLUMNS);
+    const viewportEndCol = viewport.visibleColumnStopIndex + VIEWPORT_BUFFER_COLUMNS;
+    // Check if range intersects with buffered viewport
+    const hasIntersection = range.startRowIndex <= viewportEndRow &&
+        range.endRowIndex >= viewportStartRow &&
+        range.startColumnIndex <= viewportEndCol &&
+        range.endColumnIndex >= viewportStartCol;
+    if (!hasIntersection) {
+        return undefined;
+    }
+    // Clamp range to buffered viewport
+    return {
+        ...range,
+        startRowIndex: Math.max(range.startRowIndex, viewportStartRow),
+        endRowIndex: Math.min(range.endRowIndex, viewportEndRow),
+        startColumnIndex: Math.max(range.startColumnIndex, viewportStartCol),
+        endColumnIndex: Math.min(range.endColumnIndex, viewportEndCol),
+    };
+};
+/**
+ * Caps a range to a maximum number of cells to prevent performance issues
+ * with large ranges (e.g., entire columns in Excel format).
+ * Prioritizes keeping rows over columns since most data is row-oriented.
+ */
+const capRangeForEvaluation = (range, viewport, maxCells = MAX_RANGE_CELLS_FOR_EVALUATION) => {
+    // If viewport is provided, use viewport-based clamping
+    if (viewport) {
+        return clampRangeToViewport(range, viewport);
+    }
+    // Otherwise, cap to max cells (for initial load without viewport)
+    const rowCount = range.endRowIndex - range.startRowIndex + 1;
+    const colCount = range.endColumnIndex - range.startColumnIndex + 1;
+    const totalCells = rowCount * colCount;
+    if (totalCells <= maxCells) {
+        return range;
+    }
+    // Calculate how many rows we can afford with the given columns
+    const maxRows = Math.floor(maxCells / colCount);
+    return {
+        ...range,
+        endRowIndex: range.startRowIndex + Math.max(0, maxRows - 1),
+    };
+};
+/**
+ * Rules whose formula predicate has not yet been seeded into the
+ * calculator for `sheetId`. Shared between CF and DV rules — both carry
+ * `id` + `ranges`; CF rules additionally carry `enabled`.
+ */
+const filterUnseededRulesForSheet = (rules, seeded, sheetId, isFormulaRule) => (rules ?? []).filter((rule) => rule.enabled !== false &&
+    !seeded.get(rule.id)?.has(sheetId) &&
+    rule.ranges.some((range) => range.sheetId === sheetId) &&
+    isFormulaRule(rule));
+/**
+ * Forget seeded state for rules that no longer exist, so a re-added
+ * rule (undo of a delete, a replaced hydration snapshot) seeds again
+ * instead of being skipped.
+ */
+const pruneSeededRules = (seeded, rules) => {
+    if (!seeded.size)
+        return;
+    const liveIds = new Set((rules ?? []).map((rule) => rule.id));
+    for (const id of seeded.keys()) {
+        if (!liveIds.has(id)) {
+            seeded.delete(id);
+        }
+    }
+};
+export const useCalculationInitialize = ({ sheetData, conditionalFormats: initialConditionalFormats, dataValidations: initialDataValidations, recalculateOnOpen = true, activeSheetId, iterativeCalculation, getDataValidationById, enqueueCalculation, enqueueGraphOperation, onResetCalculator, getViewPort, namedRanges, applyNamedRanges, }) => {
+    const previousIterativeModeEnabled = usePrevious(iterativeCalculation?.enabled);
+    // Start calculating
+    const calculate = useCallbackRef(useCallback((disableEvaluation = true) => {
+        const defaultEnqueue = disableEvaluation
+            ? enqueueGraphOperation
+            : enqueueCalculation;
+        // Phase 9 — register named ranges with the calculator
+        // BEFORE walking cells. The dep parser inside `addFormula`
+        // consults the calculator's registered named-range set to
+        // decide whether to emit a `nr:<name>` StaticReference dep.
+        // If we walked cells first, every named-range reference
+        // would be `#NAME?` and no DAG edge would form. Pass the
+        // current namedRanges so registration matches the host's
+        // latest state.
+        applyNamedRanges?.(namedRanges);
+        // Recalc all cells
+        const sheetCell = new SheetCell();
+        for (const sheetIdKey in sheetData) {
+            const sheetId = Number(sheetIdKey);
+            for (const [rowIndex, value] of sheetData[sheetId]?.entries() ?? []) {
+                for (const [columnIndex, cellData] of value?.values?.entries() ??
+                    []) {
+                    if (!cellData) {
+                        continue;
+                    }
+                    sheetCell.assign(sheetId, { rowIndex, columnIndex }, cellData, {
+                        getDataValidationById,
+                    });
+                    if (sheetCell.formula) {
+                        const formulaValue = sheetCell.formula.startsWith("=")
+                            ? sheetCell.formula.slice(1)
+                            : sheetCell.formula;
+                        const fnNames = getFunctionNamesFromFormula(formulaValue);
+                        const isEphemeral = fnNames.some((fn) => CALC_EPHEMERAL_FUNCTIONS.has(fn.toUpperCase()));
+                        const requiresEval = fnNames.some((fn) => CALC_REQUIRES_EVAL_FUNCTIONS.has(fn.toUpperCase()));
+                        const shouldForceEvaluation = sheetCell.error
+                            ? true
+                            : disableEvaluation && (isEphemeral || requiresEval);
+                        const enqueueFn = shouldForceEvaluation
+                            ? enqueueCalculation
+                            : defaultEnqueue;
+                        // Persisted spill range (set by use-on-calculation-success
+                        // on the anchor cell of array formulas). Pass it through so
+                        // the calculator can seed its array range map for the spill
+                        // rectangle without re-evaluating the formula.
+                        const spillRange = sheetCell.arrayFormulaRef
+                            ? addressToSelection(sheetCell.arrayFormulaRef)?.range
+                            : undefined;
+                        enqueueFn({
+                            type: "add",
+                            position: {
+                                rowIndex,
+                                columnIndex,
+                                sheetId: Number(sheetId),
+                            },
+                            spillRange,
+                        });
+                    }
+                    // DV formula DAG seeding happens lazily in
+                    // `evaluateDataValidations` (mount effect, activeSheetId
+                    // effect, onViewPortChange) — keyed by `rule.id` and
+                    // filtered to activeSheetId. Walking every cell on every
+                    // sheet here just to enqueue inactive-sheet DV nodes is
+                    // wasted work; DV doesn't mutate cell values so the
+                    // inactive sheet's DAG can wait until that sheet activates.
+                }
+            }
+        }
+    }, [
+        sheetData,
+        getDataValidationById,
+        enqueueCalculation,
+        enqueueGraphOperation,
+        namedRanges,
+        applyNamedRanges,
+    ]));
+    // Add calculate now to trigger calculation in the
+    // next animation frame
+    const calcScheduledRef = useRef(undefined);
+    const calculateNow = useCallback((options = {}) => {
+        if (options.shouldResetCellDependencyGraph) {
+            onResetCalculator?.();
+        }
+        if (calcScheduledRef.current) {
+            cancelAnimationFrame(calcScheduledRef.current);
+        }
+        return new Promise((resolve) => {
+            calcScheduledRef.current = requestAnimationFrame(() => {
+                calculate(options.disableEvaluation);
+                resolve();
+            });
+        });
+    }, [calculate, onResetCalculator]);
+    /**
+     * Evaluate conditional formatting
+     *
+     * Seeded (rule, sheet) pairs — replaces the previous per-sheet
+     * "evaluated" flag. Per-rule tracking matters because rules can
+     * arrive after a sheet was already active (async hydration,
+     * collaborative peers, host-side import pipelines writing straight
+     * into state): a sheet-level flag set while the rules array was
+     * still empty permanently blocked those late rules from seeding,
+     * leaving imported rules visible in the UI but never evaluated
+     * until the user re-saved them.
+     */
+    const seededConditionalRulesRef = useRef(new Map());
+    const seededDataValidationRulesRef = useRef(new Map());
+    // Mirror `activeSheetId` into a ref so the evaluate* callbacks read the
+    // latest sheet on invocation rather than the value captured at
+    // useCallback construction time. Without this, long-lived flows (Excel
+    // import's PARSE_EXCEL_COMPLETE handler, scheduled callbacks, async
+    // subscribers) call into a stale closure and scope DV/CF seeding to the
+    // wrong sheet — typically seeding nothing when the host auto-activated
+    // the imported workbook's first sheet during the import.
+    const activeSheetIdRef = useRef(activeSheetId);
+    activeSheetIdRef.current = activeSheetId;
+    const evaluateConditionalFormatting = useCallback((conditionalFormats, viewport, disableEvaluation) => {
+        const currentActiveSheetId = activeSheetIdRef.current;
+        const restrictToActiveSheet = typeof currentActiveSheetId === "number";
+        const enqueueFn = disableEvaluation
+            ? enqueueGraphOperation
+            : enqueueCalculation;
+        for (const rule of conditionalFormats ?? []) {
+            if (rule.enabled === false) {
+                continue;
+            }
+            // Formula-backed rules (support legacy custom-formula values too)
+            if (isConditionalFormatFormulaRule(rule)) {
+                for (const range of rule.ranges) {
+                    if (restrictToActiveSheet &&
+                        range.sheetId !== currentActiveSheetId) {
+                        continue;
+                    }
+                    // Only mark as seeded when we actually evaluated; DAG-only
+                    // seeding must still allow the activeSheet / rules-change /
+                    // viewport handlers to fire evaluation later. Marked even when
+                    // the range is off-viewport — the viewport handlers own
+                    // scrolled-into cells.
+                    if (!disableEvaluation) {
+                        const seededSheets = seededConditionalRulesRef.current.get(rule.id) ??
+                            new Set();
+                        seededSheets.add(range.sheetId);
+                        seededConditionalRulesRef.current.set(rule.id, seededSheets);
+                    }
+                    // DAG-only mode seeds the full range; evaluation mode caps to viewport + buffer
+                    const targetRange = disableEvaluation
+                        ? range
+                        : capRangeForEvaluation(range, viewport);
+                    if (!targetRange) {
+                        continue; // Range doesn't intersect with viewport
+                    }
+                    for (const [rowIndex, columnIndex] of iterateCellsInRange(targetRange)) {
+                        enqueueFn({
+                            position: {
+                                rowIndex,
+                                columnIndex,
+                                sheetId: range.sheetId,
+                                conditionalFormatId: rule.id,
+                            },
+                            type: "add",
+                        });
+                    }
+                }
+            }
+        }
+    }, [enqueueCalculation, enqueueGraphOperation]);
+    /**
+     * Evaluate data validations
+     */
+    const evaluateDataValidations = useCallback((dataValidations, viewport, disableEvaluation) => {
+        const currentActiveSheetId = activeSheetIdRef.current;
+        const restrictToActiveSheet = typeof currentActiveSheetId === "number";
+        const enqueueFn = disableEvaluation
+            ? enqueueGraphOperation
+            : enqueueCalculation;
+        for (const rule of dataValidations ?? []) {
+            if (isDataValidationFormulaRule(rule)) {
+                for (const range of rule.ranges) {
+                    if (restrictToActiveSheet &&
+                        range.sheetId !== currentActiveSheetId) {
+                        continue;
+                    }
+                    if (!disableEvaluation) {
+                        const seededSheets = seededDataValidationRulesRef.current.get(rule.id) ??
+                            new Set();
+                        seededSheets.add(range.sheetId);
+                        seededDataValidationRulesRef.current.set(rule.id, seededSheets);
+                    }
+                    // DAG-only mode seeds the full range; evaluation mode caps to viewport + buffer
+                    const targetRange = disableEvaluation
+                        ? range
+                        : capRangeForEvaluation(range, viewport);
+                    if (!targetRange) {
+                        continue; // Range doesn't intersect with viewport
+                    }
+                    for (const [rowIndex, columnIndex] of iterateCellsInRange(targetRange)) {
+                        enqueueFn({
+                            position: {
+                                rowIndex,
+                                columnIndex,
+                                sheetId: range.sheetId,
+                                dataValidationId: rule.id,
+                            },
+                            type: "add",
+                        });
+                    }
+                }
+            }
+        }
+    }, [enqueueCalculation, enqueueGraphOperation]);
+    const dataValidationsRef = useRef(initialDataValidations);
+    const cfRulesRef = useRef(initialConditionalFormats);
+    const hasMountedRef = useRef(false);
+    dataValidationsRef.current = initialDataValidations;
+    cfRulesRef.current = initialConditionalFormats;
+    useIsomorphicLayoutEffect(() => {
+        // Check if any cf rule is queued
+        if (isNil(activeSheetId)) {
+            return;
+        }
+        // Defer on first mounted
+        if (!hasMountedRef.current) {
+            hasMountedRef.current = true;
+            return;
+        }
+        // Process deferred (capped to viewport + buffer). Per-rule seeding
+        // records mean revisiting a sheet only evaluates rules that never
+        // seeded there (e.g. rules that hydrated while another sheet was
+        // active), not the whole rule list again.
+        const viewport = getViewPort?.();
+        const pendingDataValidations = filterUnseededRulesForSheet(dataValidationsRef.current, seededDataValidationRulesRef.current, activeSheetId, isDataValidationFormulaRule);
+        if (pendingDataValidations.length) {
+            evaluateDataValidations(pendingDataValidations, viewport);
+        }
+        const pendingConditionalFormats = filterUnseededRulesForSheet(cfRulesRef.current, seededConditionalRulesRef.current, activeSheetId, isConditionalFormatFormulaRule);
+        if (pendingConditionalFormats.length) {
+            evaluateConditionalFormatting(pendingConditionalFormats, viewport);
+        }
+    }, [activeSheetId]);
+    /**
+     * Recalculate when iterative calculation is toggled after mount.
+     */
+    useIsomorphicLayoutEffect(() => {
+        if (previousIterativeModeEnabled === undefined) {
+            return;
+        }
+        if (previousIterativeModeEnabled !== iterativeCalculation?.enabled) {
+            // Skip first time
+            if (!previousIterativeModeEnabled && !iterativeCalculation?.enabled) {
+                return;
+            }
+            const disableEvaluation = !iterativeCalculation?.enabled;
+            calculateNow({ disableEvaluation });
+        }
+    }, [calculate, previousIterativeModeEnabled, iterativeCalculation?.enabled]);
+    /**
+     * The first calculation that is triggered when spreadsheet is open
+     * 1. Builds Cell dependency graphs (Unless user has restored)
+     * 2. Trigger computation of each formula
+     *
+     * 1) is always required to build a DAG, but 2) is optional, since we want to keep the
+     * calculated values inside a cell
+     */
+    useIsomorphicLayoutEffect(() => {
+        const disableEvaluation = recalculateOnOpen === false;
+        // Update graph if evaluation is disabled
+        calculate(disableEvaluation);
+        // Always seed DAG for CF/DV on the active sheet; in eval mode we cap to
+        // viewport + buffer, in DAG-only mode we seed the full range per-cell so
+        // the graph is correct before any lazy/scroll-driven evaluation runs.
+        const viewport = getViewPort?.();
+        evaluateDataValidations(initialDataValidations, viewport, disableEvaluation);
+        evaluateConditionalFormatting(initialConditionalFormats, viewport, disableEvaluation);
+    }, [recalculateOnOpen]);
+    /**
+     * Seed rules that arrive after mount. Hosts that hydrate
+     * `conditionalFormats`/`dataValidations` asynchronously (collaborative
+     * doc sync, server-side import pipelines writing straight into state)
+     * update the props without going through the onCreate/import
+     * handlers, so no other path enqueues their cells — the rule would
+     * render in the sidebar but never evaluate until the user re-saved it
+     * or scrolled far enough to trigger the viewport handlers.
+     *
+     * Known limitation: an existing rule edited in place (same id, new
+     * ranges/condition) arriving via props is treated as already seeded;
+     * only UI edits (which enqueue directly) re-evaluate it.
+     */
+    const hasSeenInitialRulesRef = useRef(false);
+    useIsomorphicLayoutEffect(() => {
+        pruneSeededRules(seededConditionalRulesRef.current, initialConditionalFormats);
+        pruneSeededRules(seededDataValidationRulesRef.current, initialDataValidations);
+        // The mount effect above owns the initial seed (and respects
+        // recalculateOnOpen's DAG-only mode); only react to later changes.
+        if (!hasSeenInitialRulesRef.current) {
+            hasSeenInitialRulesRef.current = true;
+            return;
+        }
+        const currentActiveSheetId = activeSheetIdRef.current;
+        if (isNil(currentActiveSheetId)) {
+            return;
+        }
+        const viewport = getViewPort?.();
+        const pendingConditionalFormats = filterUnseededRulesForSheet(initialConditionalFormats, seededConditionalRulesRef.current, currentActiveSheetId, isConditionalFormatFormulaRule);
+        if (pendingConditionalFormats.length) {
+            evaluateConditionalFormatting(pendingConditionalFormats, viewport);
+        }
+        const pendingDataValidations = filterUnseededRulesForSheet(initialDataValidations, seededDataValidationRulesRef.current, currentActiveSheetId, isDataValidationFormulaRule);
+        if (pendingDataValidations.length) {
+            evaluateDataValidations(pendingDataValidations, viewport);
+        }
+    }, [initialConditionalFormats, initialDataValidations]);
+    /**
+     * Track evaluated cells to avoid re-evaluation during scroll
+     * Key format: `${sheetId}_${rowIndex}_${columnIndex}_${ruleId}`
+     */
+    const evaluatedCellsRef = useRef(new Set());
+    /**
+     * Evaluate conditional formatting for a specific viewport.
+     * Call this when the user scrolls to evaluate newly visible cells.
+     * Uses caching to avoid re-evaluating cells that have already been processed.
+     */
+    const evaluateConditionalFormattingForViewport = useCallback((viewport, conditionalFormats) => {
+        const rules = conditionalFormats ?? cfRulesRef.current;
+        const currentActiveSheetId = activeSheetIdRef.current;
+        if (!rules || isNil(currentActiveSheetId)) {
+            return;
+        }
+        for (const rule of rules) {
+            if (rule.enabled === false) {
+                continue;
+            }
+            if (isConditionalFormatFormulaRule(rule)) {
+                for (const range of rule.ranges) {
+                    if (range.sheetId !== currentActiveSheetId) {
+                        continue;
+                    }
+                    // Clamp to viewport + buffer
+                    const clampedRange = clampRangeToViewport(range, viewport);
+                    if (!clampedRange) {
+                        continue;
+                    }
+                    for (const [rowIndex, columnIndex] of iterateCellsInRange(clampedRange)) {
+                        const cellKey = `${createSheetCellIdentifier(range.sheetId, rowIndex, columnIndex)}_cf_${rule.id}`;
+                        if (evaluatedCellsRef.current.has(cellKey)) {
+                            continue; // Already evaluated
+                        }
+                        evaluatedCellsRef.current.add(cellKey);
+                        enqueueCalculation({
+                            position: {
+                                rowIndex,
+                                columnIndex,
+                                sheetId: range.sheetId,
+                                conditionalFormatId: rule.id,
+                            },
+                            type: "add",
+                        });
+                    }
+                }
+            }
+        }
+    }, [enqueueCalculation]);
+    /**
+     * Evaluate data validations for a specific viewport.
+     * Call this when the user scrolls to evaluate newly visible cells.
+     */
+    const evaluateDataValidationsForViewport = useCallback((viewport, dataValidations) => {
+        const rules = dataValidations ?? dataValidationsRef.current;
+        const currentActiveSheetId = activeSheetIdRef.current;
+        if (!rules || isNil(currentActiveSheetId)) {
+            return;
+        }
+        for (const rule of rules) {
+            if (isDataValidationFormulaRule(rule)) {
+                for (const range of rule.ranges) {
+                    if (range.sheetId !== currentActiveSheetId) {
+                        continue;
+                    }
+                    // Clamp to viewport + buffer
+                    const clampedRange = clampRangeToViewport(range, viewport);
+                    if (!clampedRange) {
+                        continue;
+                    }
+                    for (const [rowIndex, columnIndex] of iterateCellsInRange(clampedRange)) {
+                        const cellKey = `${createSheetCellIdentifier(range.sheetId, rowIndex, columnIndex)}_dv_${rule.id}`;
+                        if (evaluatedCellsRef.current.has(cellKey)) {
+                            continue; // Already evaluated
+                        }
+                        evaluatedCellsRef.current.add(cellKey);
+                        enqueueCalculation({
+                            position: {
+                                rowIndex,
+                                columnIndex,
+                                sheetId: range.sheetId,
+                                dataValidationId: rule.id,
+                            },
+                            type: "add",
+                        });
+                    }
+                }
+            }
+        }
+    }, [enqueueCalculation]);
+    /**
+     * Clear evaluated cells cache. Call when rules change or sheet changes.
+     */
+    const clearEvaluatedCellsCache = useCallback(() => {
+        evaluatedCellsRef.current.clear();
+    }, []);
+    /**
+     * Re-derive formula-backed CF/DV results for cells whose VALUE changed
+     * outside the calculator — agent/backend recalc patches carry pre-computed
+     * values and only update the dependency graph, so without this the covered
+     * cells' conditional formatting stays stale until the user re-saves a rule
+     * in the dialog. One calculation op per (cell, covering rule).
+     */
+    const reevaluateDerivationsForCells = useCallbackRef(useCallback((cells) => {
+        const coversCell = (ranges, cell) => ranges.some((range) => range.sheetId === cell.sheetId &&
+            cell.rowIndex >= range.startRowIndex &&
+            cell.rowIndex <= range.endRowIndex &&
+            cell.columnIndex >= range.startColumnIndex &&
+            cell.columnIndex <= range.endColumnIndex);
+        for (const cell of cells) {
+            for (const rule of cfRulesRef.current ?? []) {
+                if (rule.enabled !== false &&
+                    isConditionalFormatFormulaRule(rule) &&
+                    coversCell(rule.ranges, cell)) {
+                    enqueueCalculation({
+                        position: { ...cell, conditionalFormatId: rule.id },
+                        type: "add",
+                    });
+                }
+            }
+            for (const rule of dataValidationsRef.current ?? []) {
+                if (isDataValidationFormulaRule(rule) && coversCell(rule.ranges, cell)) {
+                    enqueueCalculation({
+                        position: { ...cell, dataValidationId: rule.id },
+                        type: "add",
+                    });
+                }
+            }
+        }
+    }, [enqueueCalculation]));
+    /**
+     * Non-blocking viewport change handler.
+     * Uses requestIdleCallback to evaluate CF/DV without blocking the UI.
+     * Falls back to setTimeout for browsers that don't support requestIdleCallback.
+     */
+    const viewportChangeIdleRef = useRef(undefined);
+    const lastViewportRef = useRef(undefined);
+    const onViewPortChange = useCallbackRef(useCallback((viewport) => {
+        // Skip if viewport hasn't meaningfully changed (within buffer zone)
+        const last = lastViewportRef.current;
+        if (last &&
+            Math.abs(viewport.visibleRowStartIndex - last.visibleRowStartIndex) <
+                10 &&
+            Math.abs(viewport.visibleRowStopIndex - last.visibleRowStopIndex) <
+                10 &&
+            Math.abs(viewport.visibleColumnStartIndex - last.visibleColumnStartIndex) < 5 &&
+            Math.abs(viewport.visibleColumnStopIndex - last.visibleColumnStopIndex) < 5) {
+            return;
+        }
+        lastViewportRef.current = viewport;
+        // Cancel any pending idle callback
+        if (viewportChangeIdleRef.current !== undefined) {
+            if (typeof cancelIdleCallback !== "undefined") {
+                cancelIdleCallback(viewportChangeIdleRef.current);
+            }
+            else {
+                clearTimeout(viewportChangeIdleRef.current);
+            }
+        }
+        // Schedule evaluation during idle time
+        const evaluate = () => {
+            evaluateConditionalFormattingForViewport(viewport);
+            evaluateDataValidationsForViewport(viewport);
+            viewportChangeIdleRef.current = undefined;
+        };
+        if (typeof requestIdleCallback !== "undefined") {
+            viewportChangeIdleRef.current = requestIdleCallback(evaluate, {
+                timeout: 100, // Max 100ms delay
+            });
+        }
+        else {
+            // Fallback for browsers without requestIdleCallback
+            viewportChangeIdleRef.current = setTimeout(evaluate, 16);
+        }
+    }, [
+        evaluateConditionalFormattingForViewport,
+        evaluateDataValidationsForViewport,
+    ]));
+    return {
+        calculateNow,
+        evaluateConditionalFormatting,
+        evaluateDataValidations,
+        evaluateConditionalFormattingForViewport,
+        evaluateDataValidationsForViewport,
+        clearEvaluatedCellsCache,
+        onViewPortChange,
+        reevaluateDerivationsForCells,
+    };
+};

package/dist/esm/hooks/use-calculation-process-array.d.ts

@@ -0,0 +1,20 @@
+import type { Calculator } from "@rowsncolumns/calculator";
+import type { CellCoordinate, CellNode, StaticNode } from "@rowsncolumns/dag";
+import type { FormulaResultArray } from "@rowsncolumns/fast-formula-parser";
+import type { CellData, CellFormat, ErrorValue } from "@rowsncolumns/spreadsheet";
+import type { CalculationOperation, CalculationResult, UseCalculationProps } from "./use-calculation";
+type ProcessArrayProps = {
+    locale?: string;
+    getCalculator(): Calculator;
+    getUserEnteredValue: UseCalculationProps["getUserEnteredValue"];
+    getCellData: UseCalculationProps["getCellData"];
+    getSheetId: UseCalculationProps["getSheetId"];
+    getComputationCache(): Map<string, CalculationResult | ErrorValue>;
+};
+export declare const useCalculationProcessArray: <T extends CellData>({ locale, getCalculator, getUserEnteredValue, getCellData, getSheetId, getComputationCache, }: ProcessArrayProps) => readonly [(result: FormulaResultArray, position: CellCoordinate, results: Map<string, [CellCoordinate, CalculationResult, formatting?: CellFormat]>, getDependents: (position: CellCoordinate) => (CellNode | StaticNode)[]) => readonly [boolean, CalculationOperation[]], ({ position, shouldRemoveArrayReference, getDependents, }: {
+    position: CellCoordinate;
+    shouldRemoveArrayReference?: boolean;
+    getDependents: (position: CellCoordinate) => (CellNode | StaticNode)[];
+}) => Map<string, [CellCoordinate, CalculationResult, formatting?: CellFormat | undefined]>, (position: CellCoordinate) => readonly [Map<string, [CellCoordinate, CalculationResult, formatting?: CellFormat | undefined]>, CalculationOperation[]]];
+export {};
+//# sourceMappingURL=use-calculation-process-array.d.ts.map

package/dist/esm/hooks/use-calculation-process-array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-calculation-process-array.d.ts","sourceRoot":"","sources":["../../../hooks/use-calculation-process-array.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,UAAU,EACX,MAAM,2BAA2B,CAAC;AAcnC,OAAO,KAAK,EACV,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAE3B,KAAK,iBAAiB,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,IAAI,UAAU,CAAC;IAC5B,mBAAmB,EAAE,mBAAmB,CAAC,qBAAqB,CAAC,CAAC;IAChE,WAAW,EAAE,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAChD,UAAU,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;IAC9C,mBAAmB,IAAI,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,UAAU,CAAC,CAAC;CACpE,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,CAAC,SAAS,QAAQ,EAAE,+FAO5D,iBAAiB,wBA+CN,kBAAkB,YAChB,cAAc,WACf,GAAG,CACV,MAAM,EACN,CAAC,cAAc,EAAE,iBAAiB,EAAE,UAAU,CAAC,EAAE,UAAU,CAAC,CAC7D,iBACc,CAAC,QAAQ,EAAE,cAAc,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAC,EAAE,4GAgMrE;IACD,QAAQ,EAAE,cAAc,CAAC;IACzB,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,aAAa,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,CAAC,QAAQ,GAAG,UAAU,CAAC,EAAE,CAAC;CACxE,uGA2GU,cAAc,8HA+C5B,CAAC"}