@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/helpers/iterative-calculation.js

@@ -0,0 +1,44 @@
+const areFormulaArraysEqual = (left, right) => {
+    if (left.length !== right.length) {
+        return false;
+    }
+    for (let rowIndex = 0; rowIndex < left.length; rowIndex++) {
+        const leftRow = left[rowIndex];
+        const rightRow = right[rowIndex];
+        if (!leftRow || !rightRow || leftRow.length !== rightRow.length) {
+            return false;
+        }
+        for (let colIndex = 0; colIndex < leftRow.length; colIndex++) {
+            const leftValue = leftRow[colIndex];
+            const rightValue = rightRow[colIndex];
+            if (leftValue instanceof Date && rightValue instanceof Date) {
+                if (leftValue.getTime() !== rightValue.getTime()) {
+                    return false;
+                }
+                continue;
+            }
+            if (leftValue !== rightValue) {
+                return false;
+            }
+        }
+    }
+    return true;
+};
+export const computeDelta = (prev, next) => {
+    if (prev === next) {
+        return 0;
+    }
+    if (typeof prev === "number" &&
+        typeof next === "number" &&
+        Number.isFinite(prev) &&
+        Number.isFinite(next)) {
+        return Math.abs(next - prev);
+    }
+    if (prev instanceof Date && next instanceof Date) {
+        return Math.abs(next.getTime() - prev.getTime());
+    }
+    if (Array.isArray(prev) && Array.isArray(next)) {
+        return areFormulaArraysEqual(prev, next) ? 0 : Number.POSITIVE_INFINITY;
+    }
+    return Number.POSITIVE_INFINITY;
+};

package/dist/esm/helpers/sheet-title.d.ts

@@ -0,0 +1,5 @@
+import type { Sheet } from "@rowsncolumns/spreadsheet";
+export declare const MAX_SHEET_TITLE_LENGTH = 32;
+export declare const truncateSheetTitle: (title: string) => string;
+export declare const sanitizeSheetSpecTitle: <S extends Sheet>(sheetSpec: Partial<S>) => Partial<S>;
+//# sourceMappingURL=sheet-title.d.ts.map

package/dist/esm/helpers/sheet-title.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sheet-title.d.ts","sourceRoot":"","sources":["../../../helpers/sheet-title.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAEvD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAElD,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,KAAK,EACpD,WAAW,OAAO,CAAC,CAAC,CAAC,KACpB,OAAO,CAAC,CAAC,CASX,CAAC"}

package/dist/esm/helpers/sheet-title.js

@@ -0,0 +1,13 @@
+export const MAX_SHEET_TITLE_LENGTH = 32;
+export const truncateSheetTitle = (title) => {
+    return title.slice(0, MAX_SHEET_TITLE_LENGTH);
+};
+export const sanitizeSheetSpecTitle = (sheetSpec) => {
+    if (typeof sheetSpec.title !== "string") {
+        return sheetSpec;
+    }
+    return {
+        ...sheetSpec,
+        title: truncateSheetTitle(sheetSpec.title),
+    };
+};

package/dist/esm/helpers.d.ts

@@ -0,0 +1,45 @@
+import type { RowData } from "@rowsncolumns/common-types";
+import type { CellCoords, CellRange } from "@rowsncolumns/fast-formula-parser";
+import type { CellData, Column, TableView } from "@rowsncolumns/spreadsheet";
+import type { GeneratedNames } from "./generated-names";
+/**
+ * Convert
+ * @param rows
+ * @param sheetId
+ * @param startCell
+ * @returns
+ */
+export declare const createRowDataFromArray: <T extends CellData>(rows: (string | number | Date | boolean | undefined | null | T)[][], sheetId?: number) => RowData<T>[];
+/**
+ * Check if coords is cellRange
+ * @param coords
+ * @returns
+ */
+export declare const isCellRange: (coords: CellCoords | CellRange) => coords is CellRange;
+/**
+ * Combine multiple iterators
+ * @param mapIterators
+ * @returns
+ */
+export declare function combineMapIterators<K, V>(...mapIterators: IterableIterator<[K, V]>[]): IterableIterator<[K, V]>;
+/**
+ * Combine multiple iterators with optional formatting
+ * @param mapIterators
+ * @returns
+ */
+export declare function combineMapIteratorsWithFormatting<K, V, F>(...mapIterators: IterableIterator<[K, V, formatting?: F]>[]): IterableIterator<[K, V, formatting?: F]>;
+/**
+ * Get unique table column name
+ * @param columns
+ * @returns
+ */
+export declare const getNextTableColumnName: (columns?: Column[] | null, generatedNames?: GeneratedNames) => string;
+export declare const getConfictingTable: (tables: TableView[] | undefined, activeTable: TableView) => TableView | undefined;
+/**
+ * Hashes and object and returns a number
+ * @param obj
+ * @returns
+ */
+export declare const hashObject: (obj: object | null | undefined) => number;
+export declare const AWAITING_CALCULATION = "Paused";
+//# sourceMappingURL=helpers.d.ts.map

package/dist/esm/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE7E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAKxD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,CAAC,SAAS,QAAQ,EACvD,MAAM,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,EAAE,EAAE,EACnE,gBAAwB,KACvB,OAAO,CAAC,CAAC,CAAC,EAeZ,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,UAAU,GAAG,SAAS,KAC7B,MAAM,IAAI,SAEZ,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,CAAC,EACtC,GAAG,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAC1C,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAkB1B;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EACvD,GAAG,YAAY,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAC1D,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAkB1C;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,UAAU,MAAM,EAAE,GAAG,IAAI,EACzB,iBAAiB,cAAc,WAYhC,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,EAAE,GAAG,SAAS,EAC/B,aAAa,SAAS,0BAsBvB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,WA6BxD,CAAC;AAEF,eAAO,MAAM,oBAAoB,WAAW,CAAC"}

package/dist/esm/helpers.js

@@ -0,0 +1,143 @@
+import { getGeneratedTableColumnName } from "./generated-names";
+import { defaultCellCoords, defaultSheetId, SheetCell } from "./sheet-cell";
+/**
+ * Convert
+ * @param rows
+ * @param sheetId
+ * @param startCell
+ * @returns
+ */
+export const createRowDataFromArray = (rows, sheetId = defaultSheetId) => {
+    return rows.map((row) => {
+        return {
+            values: row.map((value) => {
+                const sheetCell = new SheetCell();
+                if (typeof value === "object" && !(value instanceof Date)) {
+                    sheetCell.assign(sheetId, defaultCellCoords, value);
+                }
+                else {
+                    sheetCell.setUserEnteredValue(value);
+                }
+                return sheetCell.getCellData();
+            }),
+        };
+    });
+};
+/**
+ * Check if coords is cellRange
+ * @param coords
+ * @returns
+ */
+export const isCellRange = (coords) => {
+    return !!coords.from;
+};
+/**
+ * Combine multiple iterators
+ * @param mapIterators
+ * @returns
+ */
+export function combineMapIterators(...mapIterators) {
+    let currentIteratorIndex = 0;
+    return {
+        [Symbol.iterator]() {
+            return this;
+        },
+        next() {
+            while (currentIteratorIndex < mapIterators.length) {
+                const result = mapIterators[currentIteratorIndex].next();
+                if (!result.done) {
+                    return result;
+                }
+                currentIteratorIndex++;
+            }
+            return { done: true, value: undefined };
+        },
+    };
+}
+/**
+ * Combine multiple iterators with optional formatting
+ * @param mapIterators
+ * @returns
+ */
+export function combineMapIteratorsWithFormatting(...mapIterators) {
+    let currentIteratorIndex = 0;
+    return {
+        [Symbol.iterator]() {
+            return this;
+        },
+        next() {
+            while (currentIteratorIndex < mapIterators.length) {
+                const result = mapIterators[currentIteratorIndex].next();
+                if (!result.done) {
+                    return result;
+                }
+                currentIteratorIndex++;
+            }
+            return { done: true, value: undefined };
+        },
+    };
+}
+/**
+ * Get unique table column name
+ * @param columns
+ * @returns
+ */
+export const getNextTableColumnName = (columns, generatedNames) => {
+    let i = 1;
+    while (columns &&
+        columns.find((col) => col.name === getGeneratedTableColumnName(i, generatedNames))) {
+        i++;
+    }
+    return getGeneratedTableColumnName(i, generatedNames);
+};
+// When inserting or deleting a table
+// column. Make sure we are not moving a partial table
+export const getConfictingTable = (tables, activeTable) => {
+    return tables?.find((table) => {
+        if (table.sheetId === activeTable.sheetId && table.id !== activeTable.id) {
+            const isTableInside = table.range.startRowIndex >= activeTable.range.startRowIndex &&
+                table.range.endRowIndex <= activeTable.range.endRowIndex;
+            const isTableOutside = table.range.startRowIndex > activeTable.range.endRowIndex ||
+                table.range.endRowIndex < activeTable.range.startRowIndex ||
+                table.range.endColumnIndex <= activeTable.range.startColumnIndex;
+            if (isTableInside || isTableOutside) {
+                return false;
+            }
+            return true;
+        }
+        return false;
+    });
+};
+/**
+ * Hashes and object and returns a number
+ * @param obj
+ * @returns
+ */
+export const hashObject = (obj) => {
+    // Handle null/undefined
+    if (obj === null || obj === undefined) {
+        return 0;
+    }
+    // Create a more detailed string representation of the object
+    const str = JSON.stringify(obj, (_key, value) => {
+        // Ensure consistent ordering of object keys
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            return Object.keys(value)
+                .sort()
+                .reduce((sorted, key) => {
+                sorted[key] = value[key];
+                return sorted;
+            }, {});
+        }
+        return value;
+    });
+    // Generate hash from the string
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32bit integer
+    }
+    return Math.abs(hash);
+};
+export const AWAITING_CALCULATION = "Paused";

package/dist/esm/hooks/use-async-datasource.d.ts

@@ -0,0 +1,57 @@
+import type { ViewPortProps } from "@rowsncolumns/grid";
+import type { CellData } from "@rowsncolumns/spreadsheet";
+import type { RowData, UseSpreadsheetProps } from "./use-spreadsheet-state";
+export type RowDataSlice = [start: number, end: number];
+type UseAsyncDatasourceProps<T extends CellData> = {
+    sheetId: number;
+    locale: string;
+    bufferPages?: number;
+    maxCachedPages?: number;
+    pageSize?: number;
+    frozenRowCount?: number;
+    rowCount?: number;
+    getRowData(sheetId: number, slice: RowDataSlice): Promise<(RowData<T | null> | null)[] | undefined>;
+    onChangeSheetData: UseSpreadsheetProps<T>["onChangeSheetData"];
+};
+/**
+ * Infinite loader for Spreadsheet
+ *
+ * Usage:
+ *
+ *  const { onViewPortChange, isLoading } = useAsyncDatasource<CellData>({
+      sheetId: activeSheetId,
+      locale,
+      onChangeSheetData,
+      getRowData: useCallback(
+        async (sheetId, [rowStartIndex, rowStopIndex]) => {
+          console.log("fetching page", sheetId, [rowStartIndex, rowStopIndex]);
+          await new Promise((res) => setTimeout(res, 1000));
+          return [
+            null,
+            {
+              values: [
+                null,
+                {
+                  userEnteredValue: {
+                    formulaValue: "=SUM(E11,4)",
+                  },
+                },
+              ],
+            },
+          ];
+        },
+        []
+      ),
+    });
+ * @param param0
+ * @returns
+ */
+export declare const useAsyncDatasource: <T extends CellData>({ sheetId, locale, bufferPages, maxCachedPages, pageSize, frozenRowCount, rowCount, getRowData, onChangeSheetData, }: UseAsyncDatasourceProps<T>) => {
+    onViewPortChange: (props: ViewPortProps) => void;
+    isLoading: boolean;
+    invalidate: (sheetId: number, rowIndex: number) => void;
+    invalidateAll: (targetSheetId: number) => void;
+    loadPage: (sheetId: number, page: number) => Promise<void>;
+};
+export {};
+//# sourceMappingURL=use-async-datasource.d.ts.map

package/dist/esm/hooks/use-async-datasource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-async-datasource.d.ts","sourceRoot":"","sources":["../../../hooks/use-async-datasource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAa1D,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE5E,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;AAExD,KAAK,uBAAuB,CAAC,CAAC,SAAS,QAAQ,IAAI;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CACR,OAAO,EAAE,MAAM,EAEf,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,CAAC,CAAC;IACrD,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;CAChE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,QAAQ,EAAE,sHAUpD,uBAAuB,CAAC,CAAC,CAAC;8BA0MjB,aAAa;;0BAoCX,MAAM,YAAY,MAAM;mCAuClB,MAAM;wBA/QN,MAAM,QAAQ,MAAM;CA8SvC,CAAC"}

package/dist/esm/hooks/use-async-datasource.js

@@ -0,0 +1,276 @@
+import { log } from "@rowsncolumns/utils";
+import { produce } from "immer";
+import { startTransition, useCallback, useEffect, useRef, useState, } from "react";
+import { createSheetDraft } from "../api/immer-utils";
+import { SheetCell } from "../sheet-cell";
+/**
+ * Infinite loader for Spreadsheet
+ *
+ * Usage:
+ *
+ *  const { onViewPortChange, isLoading } = useAsyncDatasource<CellData>({
+      sheetId: activeSheetId,
+      locale,
+      onChangeSheetData,
+      getRowData: useCallback(
+        async (sheetId, [rowStartIndex, rowStopIndex]) => {
+          console.log("fetching page", sheetId, [rowStartIndex, rowStopIndex]);
+          await new Promise((res) => setTimeout(res, 1000));
+          return [
+            null,
+            {
+              values: [
+                null,
+                {
+                  userEnteredValue: {
+                    formulaValue: "=SUM(E11,4)",
+                  },
+                },
+              ],
+            },
+          ];
+        },
+        []
+      ),
+    });
+ * @param param0
+ * @returns
+ */
+export const useAsyncDatasource = ({ sheetId, locale, bufferPages = 5, // Default to 5 pages
+maxCachedPages, pageSize = 100, // Optional fixed batch size
+frozenRowCount = 0, rowCount, getRowData, onChangeSheetData, }) => {
+    const loadingRef = useRef(new Set());
+    const loadedPagesRef = useRef(new Map()); // Track loaded pages
+    const [isLoading, setIsLoading] = useState(false);
+    const loadPage = useCallback(async (sheetId, page) => {
+        // Don't skip if loadingRef has it, because multiple sheets can have same page index
+        // We rely on caller to check loadingRef with sheetId scope
+        log("Loading page", sheetId, page);
+        if (pageSize === 0)
+            return; // Should not happen if batchSize is set or initialized
+        const rowStartIndex = page * pageSize;
+        const rowStopIndex = (page + 1) * pageSize;
+        // Ensure we don't fetch beyond rowCount if provided
+        if (rowCount !== undefined && rowStartIndex >= rowCount) {
+            return;
+        }
+        // Add to cache AFTER check
+        loadingRef.current.add(`${sheetId}:${page}`);
+        // Set loading
+        setIsLoading(true);
+        const data = await getRowData(sheetId, [rowStartIndex, rowStopIndex]);
+        // Optimization: Abort if the user has scrolled away from this page
+        if (lastViewportRef.current) {
+            const { rowStartIndex: currentStart } = lastViewportRef.current;
+            const currentMinPage = Math.max(0, Math.floor(currentStart / pageSize));
+            if (page < currentMinPage - bufferPages ||
+                page > currentMinPage + bufferPages + 2) {
+                log("Aborting outdated page load", sheetId, page);
+                loadingRef.current.delete(`${sheetId}:${page}`);
+                setIsLoading(false);
+                return;
+            }
+        }
+        // Create a sheet cell placeholder
+        const sheetCell = new SheetCell();
+        // Update sheet data
+        // Calculate eviction outside produce to avoid side effects in reducer
+        const pagesToRemove = [];
+        if (pageSize > 0) {
+            if (!loadedPagesRef.current.has(sheetId)) {
+                loadedPagesRef.current.set(sheetId, new Set());
+            }
+            const loadedPages = loadedPagesRef.current.get(sheetId);
+            loadedPages.add(page);
+            let currentMinPage = Math.max(0, page - bufferPages);
+            let currentMaxPage = page + bufferPages;
+            let viewportStartPage = page;
+            let viewportEndPage = page;
+            if (lastViewportRef.current) {
+                viewportStartPage = Math.floor(lastViewportRef.current.rowStartIndex / pageSize);
+                viewportEndPage = Math.ceil(lastViewportRef.current.rowStopIndex / pageSize);
+                currentMinPage = Math.max(0, viewportStartPage - bufferPages);
+                currentMaxPage = viewportEndPage + bufferPages;
+            }
+            // Ensure page 0 is kept if there are frozen rows
+            const keepPage0 = frozenRowCount > 0;
+            for (const loadedPage of loadedPages) {
+                // If loadedPage contains frozen rows (page 0), keep it
+                if (keepPage0 && loadedPage === 0)
+                    continue;
+                if (loadedPage < currentMinPage || loadedPage > currentMaxPage) {
+                    pagesToRemove.push(loadedPage);
+                }
+            }
+            if (maxCachedPages && maxCachedPages > 0) {
+                const pagesToRemoveSet = new Set(pagesToRemove);
+                const protectedPages = new Set();
+                for (let p = viewportStartPage; p <= viewportEndPage; p++) {
+                    protectedPages.add(p);
+                }
+                protectedPages.add(page);
+                if (keepPage0) {
+                    protectedPages.add(0);
+                }
+                const remainingPages = Array.from(loadedPages).filter((p) => !pagesToRemoveSet.has(p));
+                const remainingCount = remainingPages.length;
+                const excess = remainingCount - maxCachedPages;
+                if (excess > 0) {
+                    const distanceFromViewport = (p) => {
+                        if (p < viewportStartPage)
+                            return viewportStartPage - p;
+                        if (p > viewportEndPage)
+                            return p - viewportEndPage;
+                        return 0;
+                    };
+                    const evictionCandidates = remainingPages
+                        .filter((p) => !protectedPages.has(p))
+                        .sort((a, b) => {
+                        const distanceDelta = distanceFromViewport(b) - distanceFromViewport(a);
+                        if (distanceDelta !== 0)
+                            return distanceDelta;
+                        return b - a;
+                    });
+                    for (let i = 0; i < evictionCandidates.length && i < excess; i++) {
+                        pagesToRemoveSet.add(evictionCandidates[i]);
+                    }
+                }
+                pagesToRemove.length = 0;
+                pagesToRemove.push(...pagesToRemoveSet);
+            }
+            // Update Refs immediately (side effects belong here, not in reducer)
+            for (const p of pagesToRemove) {
+                loadedPages.delete(p);
+                loadingRef.current.delete(`${sheetId}:${p}`);
+            }
+        }
+        console.log("pagesToRemove", pagesToRemove);
+        startTransition(() => {
+            onChangeSheetData?.((prevSheetData) => {
+                const nextState = produce(prevSheetData, (draft) => {
+                    // 1. Eviction Logic
+                    for (const p of pagesToRemove) {
+                        const removeStart = p * pageSize;
+                        const removeEnd = (p + 1) * pageSize;
+                        const sheet = draft[sheetId];
+                        if (sheet) {
+                            for (let r = removeStart; r < removeEnd; r++) {
+                                delete sheet[r];
+                            }
+                        }
+                    }
+                    // 2. Insert New Data
+                    for (let rowIndex = 0; rowIndex < (data?.length ?? 0); rowIndex++) {
+                        const dataRowIndex = rowStartIndex + rowIndex;
+                        const currentSheet = createSheetDraft(draft, sheetId, dataRowIndex);
+                        for (let columnIndex = 1; columnIndex < (data?.[rowIndex]?.values?.length ?? 0); columnIndex++) {
+                            const cellData = data?.[rowIndex]?.values?.[columnIndex];
+                            sheetCell.assign(sheetId, { rowIndex: dataRowIndex, columnIndex }, cellData, { locale });
+                            // Set cell data
+                            currentSheet[dataRowIndex].values[columnIndex] =
+                                sheetCell.getCellData();
+                        }
+                    }
+                });
+                return nextState;
+            });
+        });
+        // Reset
+        setIsLoading(false);
+    }, [
+        onChangeSheetData,
+        getRowData,
+        pageSize,
+        locale,
+        frozenRowCount,
+        rowCount,
+        bufferPages,
+        maxCachedPages,
+    ]);
+    const lastViewportRef = useRef(null);
+    const onViewPortChange = useCallback((props) => {
+        const { rowStartIndex, rowStopIndex } = props;
+        lastViewportRef.current = props;
+        if (pageSize <= 0)
+            return;
+        const firstPage = Math.max(0, Math.floor(rowStartIndex / pageSize));
+        const lastPage = Math.ceil(rowStopIndex / pageSize);
+        // Fetch pages in the viewport + buffer
+        const bufferStart = Math.max(0, firstPage - bufferPages);
+        const bufferEnd = lastPage + bufferPages;
+        for (let page = bufferStart; page < bufferEnd; page++) {
+            if (rowCount !== undefined && page * pageSize >= rowCount) {
+                continue;
+            }
+            if (loadingRef.current.has(`${sheetId}:${page}`)) {
+                continue;
+            }
+            loadPage(sheetId, page);
+        }
+    }, [loadPage, sheetId, pageSize, rowCount, bufferPages]);
+    // Trigger load when sheetId changes by re-using the last known viewport
+    useEffect(() => {
+        lastViewportRef.current = null;
+        loadPage(sheetId, 0);
+    }, [sheetId]);
+    /**
+     * Invalidate cache for a specific row and force re-fetch if it's currently loaded.
+     * Useful when background sync updates the underlying datasource.
+     */
+    const invalidate = useCallback((sheetId, rowIndex) => {
+        if (pageSize <= 0)
+            return;
+        const page = Math.floor(rowIndex / pageSize);
+        // Only re-fetch if we have tracked it as loaded or loading
+        // (If it's not loaded, it will be fetched when scrolled into view anyway)
+        if (loadingRef.current.has(`${sheetId}:${page}`)) {
+            log("Invalidating page", sheetId, page);
+            // Remove from cache tracking to allow re-fetch
+            loadingRef.current.delete(`${sheetId}:${page}`);
+            loadedPagesRef.current.get(sheetId)?.delete(page);
+            // Clear the page data from state to ensure deletions are reflected
+            // onChangeSheetData?.((prevSheetData) => {
+            //   return produce(prevSheetData, (draft) => {
+            //     const sheet = draft[sheetId];
+            //     if (sheet) {
+            //       const start = page * pageSize;
+            //       const end = (page + 1) * pageSize;
+            //       for (let r = start; r < end; r++) {
+            //         delete sheet[r];
+            //       }
+            //     }
+            //   });
+            // });
+            // Trigger reload
+            loadPage(sheetId, page);
+        }
+    }, [pageSize, loadPage]);
+    /**
+     * Clears all cache and reloads the current viewport
+     */
+    const invalidateAll = useCallback((targetSheetId) => {
+        const id = targetSheetId;
+        // Clear loading refs for this sheet
+        const prefix = `${id}:`;
+        for (const key of loadingRef.current) {
+            if (key.startsWith(prefix)) {
+                loadingRef.current.delete(key);
+            }
+        }
+        // Clear loaded pages for this sheet
+        loadedPagesRef.current.delete(id);
+        // Clear state
+        onChangeSheetData?.((prev) => {
+            return produce(prev, (draft) => {
+                delete draft[id];
+            });
+        });
+    }, [onChangeSheetData]);
+    return {
+        onViewPortChange,
+        isLoading,
+        invalidate,
+        invalidateAll,
+        loadPage,
+    };
+};

package/dist/esm/hooks/use-calculation-initialize.d.ts

@@ -0,0 +1,61 @@
+import type { IterativeCalculationOptions } from "@rowsncolumns/common-types";
+import type { CellCoordinate } from "@rowsncolumns/dag";
+import type { CellData, ConditionalFormatRule, DataValidationRuleRecord, NamedRange } from "@rowsncolumns/spreadsheet";
+import { type CalculationOperation } from "./use-calculation";
+import type { useSheetProperties } from "./use-sheet-properties";
+import type { SheetData } from "./use-spreadsheet-state";
+/**
+ * Viewport information for viewport-based conditional format evaluation.
+ * Compatible with ViewPortProps from @rowsncolumns/grid.
+ */
+export type ViewportInfo = {
+    visibleRowStartIndex: number;
+    visibleRowStopIndex: number;
+    visibleColumnStartIndex: number;
+    visibleColumnStopIndex: number;
+};
+export type UseCalculationInitializeProps<T extends CellData> = {
+    sheetData?: SheetData<T>;
+    recalculateOnOpen?: boolean;
+    conditionalFormats?: ConditionalFormatRule[];
+    dataValidations?: DataValidationRuleRecord[];
+    activeSheetId?: number;
+    iterativeCalculation?: IterativeCalculationOptions;
+    getDataValidationById: ReturnType<typeof useSheetProperties>["getDataValidationById"];
+    enqueueCalculation(operation: CalculationOperation): void;
+    enqueueGraphOperation(operation: CalculationOperation): void;
+    onResetCalculator?(): void;
+    /** Get current viewport for viewport-based CF/DV evaluation */
+    getViewPort?(): ViewportInfo | undefined;
+    /**
+     * Phase 9 — workbook's named ranges. Passed through to
+     * `applyNamedRanges` at the top of each calculate sweep so the
+     * calculator's named-range registrations match the latest list
+     * before any cell formula is parsed. Without this, cells
+     * referencing a named range would be parsed as `#NAME?` and no
+     * DAG edge would form to the named-range static node.
+     */
+    namedRanges?: NamedRange[];
+    /**
+     * Phase 9 — registers `namedRanges` with the calculator. Excel
+     * applies defined names workbook-wide before any cell evaluates;
+     * this hook gives us the same ordering guarantee. Invoked at the
+     * top of `calculate()` with the current `namedRanges` prop.
+     */
+    applyNamedRanges?(list: NamedRange[] | undefined): void;
+};
+export type CalculateNowOptions = {
+    shouldResetCellDependencyGraph?: boolean;
+    disableEvaluation?: boolean;
+};
+export declare const useCalculationInitialize: <T extends CellData>({ sheetData, conditionalFormats: initialConditionalFormats, dataValidations: initialDataValidations, recalculateOnOpen, activeSheetId, iterativeCalculation, getDataValidationById, enqueueCalculation, enqueueGraphOperation, onResetCalculator, getViewPort, namedRanges, applyNamedRanges, }: UseCalculationInitializeProps<T>) => {
+    calculateNow: (options?: CalculateNowOptions) => Promise<void>;
+    evaluateConditionalFormatting: (conditionalFormats?: ConditionalFormatRule[], viewport?: ViewportInfo, disableEvaluation?: boolean) => void;
+    evaluateDataValidations: (dataValidations?: DataValidationRuleRecord[], viewport?: ViewportInfo, disableEvaluation?: boolean) => void;
+    evaluateConditionalFormattingForViewport: (viewport: ViewportInfo, conditionalFormats?: ConditionalFormatRule[]) => void;
+    evaluateDataValidationsForViewport: (viewport: ViewportInfo, dataValidations?: DataValidationRuleRecord[]) => void;
+    clearEvaluatedCellsCache: () => void;
+    onViewPortChange: (viewport: ViewportInfo) => void;
+    reevaluateDerivationsForCells: (cells: Array<Pick<CellCoordinate, "sheetId" | "rowIndex" | "columnIndex">>) => void;
+};
+//# sourceMappingURL=use-calculation-initialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-calculation-initialize.d.ts","sourceRoot":"","sources":["../../../hooks/use-calculation-initialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAE5B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EACV,QAAQ,EACR,qBAAqB,EACrB,wBAAwB,EACxB,UAAU,EACX,MAAM,2BAA2B,CAAC;AAkBnC,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,6BAA6B,CAAC,CAAC,SAAS,QAAQ,IAAI;IAC9D,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAC7C,eAAe,CAAC,EAAE,wBAAwB,EAAE,CAAC;IAC7C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oBAAoB,CAAC,EAAE,2BAA2B,CAAC;IACnD,qBAAqB,EAAE,UAAU,CAC/B,OAAO,kBAAkB,CAC1B,CAAC,uBAAuB,CAAC,CAAC;IAC3B,kBAAkB,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC1D,qBAAqB,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7D,iBAAiB,CAAC,IAAI,IAAI,CAAC;IAC3B,+DAA+D;IAC/D,WAAW,CAAC,IAAI,YAAY,GAAG,SAAS,CAAC;IACzC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,gBAAgB,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC;CACzD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B,CAAC;AAkJF,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,QAAQ,EAAE,iSAc1D,6BAA6B,CAAC,CAAC,CAAC;6BAmGrB,mBAAmB,KAAQ,OAAO,CAAC,IAAI,CAAC;yDA4C3B,qBAAqB,EAAE,aACjC,YAAY,sBACH,OAAO;gDA+DT,wBAAwB,EAAE,aACjC,YAAY,sBACH,OAAO;yDAiNlB,YAAY,uBAAuB,qBAAqB,EAAE;mDAuD1D,YAAY,oBAAoB,wBAAwB,EAAE;;iCAsHxD,YAAY;2CAvDd,KAAK,CACV,IAAI,CAAC,cAAc,EAAE,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC,CAC7D;CAmHR,CAAC"}