zubin-grid 0.4.13 → 0.42.13

package/dist/core/grid.js

@@ -1,6 +1,6 @@
-import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
 import { cell } from "./cell.js";
-import { createGridPersistController, defaultGridPersistAdapter, } from "./gridPersist.js";
+import { assertGridId, createGridIdKey, formatGridId } from "./grid-id.js";
+import { createGridPersistController, defaultGridPersistAdapter } from "./persist.js";
 import { assertHeadId, createHeadCellMap, createHeadOrderIndex, getHeadCell, getOrderedHeads, } from "./head.js";
 import { createTailCellMap, getTailCell, setTailCellResult } from "./tail.js";
 export function grid(input, options) {
@@ -13,12 +13,277 @@ export function grid(input, options) {
     const stateAdapter = createSchemaStateAdapter(rowCellKey, columnCellKey);
     return createGridStore(normalizedRowHeads, normalizedColumnHeads, createGridInitialCellsFromState(initialState.cells, stateAdapter), stateAdapter, schemaOptions.persist);
 }
-export function createSubGrid(parentGrid, cellsOrOptionsOrPersist, persist) {
-    const { initialCells, persistOption } = resolveCreateSubGridArgs(cellsOrOptionsOrPersist, persist);
+export function createDimensionGrid(parentGrid, initialCells, dimension, options) {
+    const readBoundIds = () => (dimension === "rows"
+        ? parentGrid.rowHeaders
+        : parentGrid.colHeaders);
+    const emptyRowHeaders = [];
+    const emptyColumnHeaders = [];
+    const dimensionSubscribers = new Set();
+    const resolvedPersistOption = createDimensionGridPersistOption(parentGrid, dimension, options?.persist);
+    let isApplyingState = false;
+    let boundIds = [...readBoundIds()];
+    const cellsById = new Map(boundIds.map((boundId, index) => [
+        createGridIdKey(boundId),
+        cell(initialCells[index]),
+    ]));
+    const dirtyBoundIdKeys = new Set();
+    const persistedCellValuesById = new Map(boundIds.map((boundId, index) => [createGridIdKey(boundId), initialCells[index]]));
+    let dimensionGridApi;
+    const resetPersistedDimensionCells = () => {
+        persistedCellValuesById.clear();
+        boundIds.forEach((boundId) => {
+            const idKey = createGridIdKey(boundId);
+            persistedCellValuesById.set(idKey, cellsById.get(idKey)?.get());
+        });
+        dirtyBoundIdKeys.clear();
+    };
+    const syncDimensionCellDirty = (boundId) => {
+        const idKey = createGridIdKey(boundId);
+        const currentValue = cellsById.get(idKey)?.get();
+        if (!persistedCellValuesById.has(idKey)) {
+            if (currentValue === undefined)
+                dirtyBoundIdKeys.delete(idKey);
+            else
+                dirtyBoundIdKeys.add(idKey);
+            return;
+        }
+        if (haveSameRuntimeValue(currentValue, persistedCellValuesById.get(idKey))) {
+            dirtyBoundIdKeys.delete(idKey);
+            return;
+        }
+        dirtyBoundIdKeys.add(idKey);
+    };
+    const getCellAtIndex = (index) => {
+        if (!Number.isInteger(index) || index < 0 || index >= boundIds.length) {
+            throw new Error(`Dimension grid ${dimension} index ${index} is out of range. ${describeIndexRange(boundIds.length, index)}`);
+        }
+        const boundId = boundIds[index];
+        const currentCell = cellsById.get(createGridIdKey(boundId));
+        if (!currentCell) {
+            throw new Error(`Missing dimension cell for ${dimension} index ${index}.`);
+        }
+        return currentCell;
+    };
+    const readCellAtIndex = (index) => {
+        const currentCell = getCellAtIndex(index);
+        const boundId = boundIds[index];
+        return {
+            value: currentCell.get(),
+            meta: {
+                existsInDb: currentCell.get() !== undefined,
+                isDirty: dirtyBoundIdKeys.has(createGridIdKey(boundId)),
+            },
+        };
+    };
+    const getState = () => ({
+        dimension,
+        cells: boundIds.map((boundId) => {
+            const currentCell = cellsById.get(createGridIdKey(boundId));
+            if (!currentCell) {
+                throw new Error(`Missing dimension cell for ${dimension} id "${formatGridId(boundId)}".`);
+            }
+            return currentCell.get();
+        }),
+    });
+    const applyDimensionCells = (nextCells, mode) => {
+        const changedIndices = [];
+        const limit = mode === "update" ? Math.min(nextCells.length, boundIds.length) : boundIds.length;
+        isApplyingState = true;
+        try {
+            for (let index = 0; index < limit; index += 1) {
+                const currentCell = getCellAtIndex(index);
+                const nextValue = nextCells[index];
+                if (Object.is(currentCell.get(), nextValue)) {
+                    continue;
+                }
+                currentCell.set(nextValue);
+                changedIndices.push(index);
+            }
+            if (mode === "replace") {
+                for (let index = nextCells.length; index < boundIds.length; index += 1) {
+                    const currentCell = getCellAtIndex(index);
+                    if (Object.is(currentCell.get(), undefined)) {
+                        continue;
+                    }
+                    currentCell.set(undefined);
+                    changedIndices.push(index);
+                }
+            }
+        }
+        finally {
+            isApplyingState = false;
+        }
+        changedIndices.forEach((index) => {
+            const boundId = boundIds[index];
+            if (boundId !== undefined) {
+                syncDimensionCellDirty(boundId);
+            }
+        });
+        return changedIndices;
+    };
+    const { hydrate, markStateChanged } = createGridPersistController(resolvedPersistOption, {
+        getState,
+        replaceState: (nextState) => {
+            applyDimensionCells(normalizeDimensionGridStateInput(nextState, dimension).cells, "replace");
+        },
+        isApplyingState: () => isApplyingState,
+        onHydratedStateApplied: resetPersistedDimensionCells,
+        onPersistedStateApplied: resetPersistedDimensionCells,
+    });
+    const emitDimensionGridUpdate = (diff, persistStateChanged = false) => {
+        if (persistStateChanged) {
+            markStateChanged();
+        }
+        [...dimensionSubscribers].forEach((callback) => {
+            callback(dimensionGridApi, diff);
+        });
+    };
+    const syncDimensionFromParent = () => {
+        const nextBoundIds = [...readBoundIds()];
+        if (haveSameItems(boundIds, nextBoundIds)) {
+            return;
+        }
+        const nextCellsById = new Map(nextBoundIds.map((boundId) => [
+            createGridIdKey(boundId),
+            cellsById.get(createGridIdKey(boundId)) ?? cell(undefined),
+        ]));
+        const previousSize = boundIds.length;
+        boundIds = nextBoundIds;
+        cellsById.clear();
+        nextCellsById.forEach((currentCell, boundIdKey) => {
+            cellsById.set(boundIdKey, currentCell);
+        });
+        const nextIdKeys = new Set(nextBoundIds.map((boundId) => createGridIdKey(boundId)));
+        [...persistedCellValuesById.keys()].forEach((idKey) => {
+            if (nextIdKeys.has(idKey))
+                return;
+            persistedCellValuesById.delete(idKey);
+            dirtyBoundIdKeys.delete(idKey);
+        });
+        nextBoundIds.forEach((boundId) => {
+            const idKey = createGridIdKey(boundId);
+            if (!persistedCellValuesById.has(idKey)) {
+                persistedCellValuesById.set(idKey, undefined);
+            }
+            syncDimensionCellDirty(boundId);
+        });
+        emitDimensionGridUpdate({
+            type: "dimension",
+            action: previousSize === nextBoundIds.length ? "update" : "resize",
+            source: "parent",
+            dimension,
+            size: nextBoundIds.length,
+            previousSize,
+        }, true);
+    };
+    const setGrid = (nextState, mode = "replace") => {
+        const changedIndices = applyDimensionCells(normalizeDimensionGridStateInput(nextState, dimension).cells, mode);
+        if (changedIndices.length === 0) {
+            return;
+        }
+        emitDimensionGridUpdate({
+            type: "cells",
+            action: mode === "update" ? "update" : "replace",
+            source: "setGrid",
+            dimension,
+            size: boundIds.length,
+            indices: changedIndices,
+        }, true);
+    };
+    const clearGrid = () => {
+        const changedIndices = applyDimensionCells([], "replace");
+        if (changedIndices.length === 0) {
+            return;
+        }
+        emitDimensionGridUpdate({
+            type: "cells",
+            action: "clear",
+            source: "clearGrid",
+            dimension,
+            size: boundIds.length,
+            indices: changedIndices,
+        }, true);
+    };
+    dimensionGridApi = {
+        dimension,
+        get size() {
+            return boundIds.length;
+        },
+        get rowHeaders() {
+            return dimension === "rows" ? parentGrid.rowHeaders : emptyRowHeaders;
+        },
+        get colHeaders() {
+            return dimension === "columns" ? parentGrid.colHeaders : emptyColumnHeaders;
+        },
+        getState,
+        setGrid,
+        readCell: readCellAtIndex,
+        setCell: (index, nextValue) => {
+            const boundId = boundIds[index];
+            const currentCell = getCellAtIndex(index);
+            const resolvedNextValue = resolveUpdater(nextValue, currentCell.get());
+            if (Object.is(currentCell.get(), resolvedNextValue)) {
+                return;
+            }
+            isApplyingState = true;
+            try {
+                currentCell.set(resolvedNextValue);
+            }
+            finally {
+                isApplyingState = false;
+            }
+            if (boundId !== undefined) {
+                syncDimensionCellDirty(boundId);
+            }
+            emitDimensionGridUpdate({
+                type: "cells",
+                action: resolvedNextValue === undefined ? "clear" : "update",
+                source: "setCell",
+                dimension,
+                size: boundIds.length,
+                indices: [index],
+            }, true);
+        },
+        getCell: getCellAtIndex,
+        getValue: (index) => getCellAtIndex(index).get(),
+        hasCell: (index) => Number.isInteger(index) && index >= 0 && index < boundIds.length,
+        clearGrid,
+        subscribeGrid: (callback) => {
+            dimensionSubscribers.add(callback);
+            return () => {
+                dimensionSubscribers.delete(callback);
+            };
+        },
+    };
+    Object.defineProperty(dimensionGridApi, "__persistOption", {
+        value: resolvedPersistOption,
+        enumerable: false,
+        configurable: true,
+    });
+    hydrate();
+    void parentGrid.subscribeGrid((_currentParentGrid, diff) => {
+        if (dimension === "rows") {
+            if (diff.type === "rows" ||
+                diff.type === "row-head" ||
+                (diff.type === "grid" && didGridDiffAffectAxes(diff))) {
+                syncDimensionFromParent();
+            }
+            return;
+        }
+        if (diff.type === "columns" ||
+            diff.type === "column-head" ||
+            (diff.type === "grid" && didGridDiffAffectAxes(diff))) {
+            syncDimensionFromParent();
+        }
+    });
+    return dimensionGridApi;
+}
+export function createSubGrid(parentGrid, initialCells = [], options) {
     const parentState = parentGrid.getState();
     const stateAdapter = createGridStateCellAdapter();
     const resolvedInitialCells = assertGridStateCellsWithinAxes(initialCells, parentState.rows, parentState.columns, "Sub grid cells");
-    const subGridStore = createGridStore(parentState.rows, parentState.columns, createGridInitialCellsFromState(resolvedInitialCells, stateAdapter), stateAdapter, createSubGridPersistOption(parentGrid, persistOption));
+    const subGridStore = createGridStore(parentState.rows, parentState.columns, createGridInitialCellsFromState(resolvedInitialCells, stateAdapter), stateAdapter, createSubGridPersistOption(parentGrid, options?.persist));
     const getSubGridState = () => {
         const nextParentState = parentGrid.getState();
         return createSubGridState(nextParentState.rows, nextParentState.columns, subGridStore.getState().cells);
@@ -146,7 +411,12 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
     const columnTailUpdaters = new Map();
     const cellsMap = new Map();
     const cellSubscriptions = new Map();
+    const dirtyCellKeys = new Set();
     const gridSubscribers = new Set();
+    let persistedCellValues = new Map(initialCells.map(({ rowId, columnId, cell: currentCell }) => [
+        createGridKey(rowId, columnId),
+        currentCell.get(),
+    ]));
     let nextRowFallbackOrder = initialRows.length;
     let nextColumnFallbackOrder = initialColumns.length;
     let isApplyingState = false;
@@ -173,14 +443,52 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
     const normalizeCellValue = (rowId, columnId, value) => {
         return stateAdapter.deserializeCell(stateAdapter.serializeCell(rowId, columnId, value)).value;
     };
+    const assertCellAxesExist = (rowId, columnId) => {
+        if (!rowHeadCells.has(createGridIdKey(rowId))) {
+            throw new Error(`Missing row header "${formatGridId(rowId)}".`);
+        }
+        if (!columnHeadCells.has(createGridIdKey(columnId))) {
+            throw new Error(`Missing column header "${formatGridId(columnId)}".`);
+        }
+    };
+    const syncDirtyCellKey = (gridKey) => {
+        const currentCell = cellsMap.get(gridKey);
+        if (!persistedCellValues.has(gridKey)) {
+            if (!currentCell)
+                dirtyCellKeys.delete(gridKey);
+            else
+                dirtyCellKeys.add(gridKey);
+            return;
+        }
+        if (currentCell &&
+            haveSameRuntimeValue(currentCell.get(), persistedCellValues.get(gridKey))) {
+            dirtyCellKeys.delete(gridKey);
+            return;
+        }
+        dirtyCellKeys.add(gridKey);
+    };
+    const refreshDirtyCellKeys = () => {
+        const nextGridKeys = new Set([...persistedCellValues.keys(), ...cellsMap.keys()]);
+        dirtyCellKeys.clear();
+        nextGridKeys.forEach((gridKey) => {
+            syncDirtyCellKey(gridKey);
+        });
+    };
+    const resetPersistedCellState = () => {
+        persistedCellValues = new Map([...cellsMap.entries()].map(([gridKey, currentCell]) => [
+            gridKey,
+            currentCell.get(),
+        ]));
+        dirtyCellKeys.clear();
+    };
     const recomputeRowTailInternal = (rowId) => {
-        const onRowUpdate = rowTailUpdaters.get(rowId);
+        const onRowUpdate = rowTailUpdaters.get(createGridIdKey(rowId));
         if (!onRowUpdate)
             return false;
         return setTailCellResult(getTailCell(rowTailCells, rowId, "row"), onRowUpdate(getRowCells(rowId)));
     };
     const recomputeColumnTailInternal = (columnId) => {
-        const onColumnUpdate = columnTailUpdaters.get(columnId);
+        const onColumnUpdate = columnTailUpdaters.get(createGridIdKey(columnId));
         if (!onColumnUpdate)
             return false;
         return setTailCellResult(getTailCell(columnTailCells, columnId, "column"), onColumnUpdate(getColumnCells(columnId)));
@@ -209,13 +517,11 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         cellsMap.delete(gridKey);
     };
     const attachCell = (rowId, columnId, currentCell) => {
-        if (!rowHeadCells.has(rowId))
-            throw new Error(`Missing row header "${rowId}".`);
-        if (!columnHeadCells.has(columnId))
-            throw new Error(`Missing column header "${columnId}".`);
+        assertCellAxesExist(rowId, columnId);
         const gridKey = createGridKey(rowId, columnId);
-        if (cellsMap.has(gridKey))
-            throw new Error(`Duplicate cell for row "${rowId}" and column "${columnId}".`);
+        if (cellsMap.has(gridKey)) {
+            throw new Error(`Duplicate cell for row "${formatGridId(rowId)}" and column "${formatGridId(columnId)}".`);
+        }
         cellsMap.set(gridKey, currentCell);
         let previousValue = currentCell.get();
         const unsubscribe = currentCell.subscribe(() => {
@@ -224,6 +530,7 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
                 previousValue = nextValue;
                 return;
             }
+            syncDirtyCellKey(gridKey);
             const rowTailIds = recomputeRowTailInternal(rowId) ? [rowId] : [];
             const columnTailIds = recomputeColumnTailInternal(columnId) ? [columnId] : [];
             emitGridUpdate({
@@ -243,11 +550,25 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         cellSubscriptions.set(gridKey, unsubscribe);
     };
     const getCell = (rowId, columnId) => {
+        assertCellAxesExist(rowId, columnId);
         const currentCell = cellsMap.get(createGridKey(rowId, columnId));
-        if (!currentCell)
-            throw new Error(`Missing cell for row "${rowId}" and column "${columnId}".`);
+        if (!currentCell) {
+            throw new Error(`Missing cell for row "${formatGridId(rowId)}" and column "${formatGridId(columnId)}".`);
+        }
         return currentCell;
     };
+    const readCell = (rowId, columnId) => {
+        assertCellAxesExist(rowId, columnId);
+        const gridKey = createGridKey(rowId, columnId);
+        const currentCell = cellsMap.get(gridKey);
+        return {
+            value: currentCell?.get(),
+            meta: {
+                existsInDb: currentCell !== undefined,
+                isDirty: dirtyCellKeys.has(gridKey),
+            },
+        };
+    };
     const createAxisCellSnapshot = (rowId, columnId) => {
         const currentCell = getCell(rowId, columnId);
         return {
@@ -272,15 +593,16 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         assertUniqueHeadIds(nextHeads, axis);
         const nextIds = new Set();
         nextHeads.forEach((nextHead, index) => {
-            nextIds.add(nextHead.id);
-            const currentHeadCell = headCells.get(nextHead.id);
+            const idKey = createGridIdKey(nextHead.id);
+            nextIds.add(idKey);
+            const currentHeadCell = headCells.get(idKey);
             if (currentHeadCell)
                 currentHeadCell.set(nextHead);
             else
-                headCells.set(nextHead.id, cell(nextHead));
-            if (!tailCells.has(nextHead.id))
-                tailCells.set(nextHead.id, cell(createEmptyTailState()));
-            headOrder.set(nextHead.id, index);
+                headCells.set(idKey, cell(nextHead));
+            if (!tailCells.has(idKey))
+                tailCells.set(idKey, cell(createEmptyTailState()));
+            headOrder.set(idKey, index);
         });
         [...headCells.keys()].forEach((id) => {
             if (nextIds.has(id))
@@ -294,24 +616,24 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
     const replaceState = (nextState) => {
         isApplyingState = true;
         try {
-            syncAxisHeads(nextState.rows, "row", rowHeadCells, rowTailCells, rowHeadOrder, (id) => {
-                rowTailUpdaters.delete(id);
+            syncAxisHeads(nextState.rows, "row", rowHeadCells, rowTailCells, rowHeadOrder, (idKey) => {
+                rowTailUpdaters.delete(idKey);
             });
-            syncAxisHeads(nextState.columns, "column", columnHeadCells, columnTailCells, columnHeadOrder, (id) => {
-                columnTailUpdaters.delete(id);
+            syncAxisHeads(nextState.columns, "column", columnHeadCells, columnTailCells, columnHeadOrder, (idKey) => {
+                columnTailUpdaters.delete(idKey);
             });
             const nextCells = new Map();
             nextState.cells.forEach((nextStateCell) => {
                 const { rowId, columnId, value } = stateAdapter.deserializeCell(nextStateCell);
-                if (!rowHeadCells.has(rowId)) {
-                    throw new Error(`Missing row header "${rowId}".`);
+                if (!rowHeadCells.has(createGridIdKey(rowId))) {
+                    throw new Error(`Missing row header "${formatGridId(rowId)}".`);
                 }
-                if (!columnHeadCells.has(columnId)) {
-                    throw new Error(`Missing column header "${columnId}".`);
+                if (!columnHeadCells.has(createGridIdKey(columnId))) {
+                    throw new Error(`Missing column header "${formatGridId(columnId)}".`);
                 }
                 const gridKey = createGridKey(rowId, columnId);
                 if (nextCells.has(gridKey)) {
-                    throw new Error(`Duplicate cell for row "${rowId}" and column "${columnId}".`);
+                    throw new Error(`Duplicate cell for row "${formatGridId(rowId)}" and column "${formatGridId(columnId)}".`);
                 }
                 nextCells.set(gridKey, {
                     rowId,
@@ -342,6 +664,7 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         const rowTailIds = recomputeAllRowTails();
         const columnTailIds = recomputeAllColumnTails();
         refreshAxisIdsSnapshot();
+        refreshDirtyCellKeys();
         return {
             rowTailIds,
             columnTailIds,
@@ -351,6 +674,8 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         getState,
         replaceState,
         isApplyingState: () => isApplyingState,
+        onHydratedStateApplied: resetPersistedCellState,
+        onPersistedStateApplied: resetPersistedCellState,
     });
     const emitGridUpdate = (diff, persistStateChanged = false) => {
         refreshAxisIdsSnapshot();
@@ -365,8 +690,8 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         if (nextCells.length === 0) {
             return null;
         }
-        const touchedRowIds = new Set();
-        const touchedColumnIds = new Set();
+        const touchedRowIds = new Map();
+        const touchedColumnIds = new Map();
         const normalizedCells = [];
         const previousCells = [];
         const cellKeys = [];
@@ -374,10 +699,12 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         try {
             nextCells.forEach((nextStateCell) => {
                 const { rowId, columnId, value } = stateAdapter.deserializeCell(nextStateCell);
-                if (!rowHeadCells.has(rowId))
-                    throw new Error(`Missing row header "${rowId}".`);
-                if (!columnHeadCells.has(columnId))
-                    throw new Error(`Missing column header "${columnId}".`);
+                if (!rowHeadCells.has(createGridIdKey(rowId))) {
+                    throw new Error(`Missing row header "${formatGridId(rowId)}".`);
+                }
+                if (!columnHeadCells.has(createGridIdKey(columnId))) {
+                    throw new Error(`Missing column header "${formatGridId(columnId)}".`);
+                }
                 const normalizedValue = normalizeCellValue(rowId, columnId, value);
                 const gridKey = createGridKey(rowId, columnId);
                 const currentCell = cellsMap.get(gridKey);
@@ -389,16 +716,19 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
                     attachCell(rowId, columnId, cell(normalizedValue));
                 }
                 normalizedCells.push(stateAdapter.serializeCell(rowId, columnId, normalizedValue));
-                touchedRowIds.add(rowId);
-                touchedColumnIds.add(columnId);
+                touchedRowIds.set(createGridIdKey(rowId), rowId);
+                touchedColumnIds.set(createGridIdKey(columnId), columnId);
                 cellKeys.push(gridKey);
             });
         }
         finally {
             isApplyingState = false;
         }
-        const rowIds = [...touchedRowIds];
-        const columnIds = [...touchedColumnIds];
+        cellKeys.forEach((gridKey) => {
+            syncDirtyCellKey(gridKey);
+        });
+        const rowIds = [...touchedRowIds.values()];
+        const columnIds = [...touchedColumnIds.values()];
         return {
             rowIds,
             columnIds,
@@ -431,35 +761,34 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         if (nextRowHeads.length === 0) {
             return null;
         }
-        const rowIds = new Set();
+        const rowIds = new Map();
         const rows = [];
         const previousRows = [];
         let shouldRecomputeColumns = false;
         nextRowHeads.forEach((nextRowHead) => {
             const rowHeadLike = nextRowHead;
-            if (typeof rowHeadLike.id !== "string") {
-                throw new Error("Row header upserts must include a string id.");
-            }
-            const currentHeadCell = rowHeadCells.get(rowHeadLike.id);
+            const rowIdKey = createGridIdKey(rowHeadLike.id);
+            assertGridId(rowHeadLike.id, "Row header upserts");
+            const currentHeadCell = rowHeadCells.get(rowIdKey);
             const currentHead = currentHeadCell?.get();
             const resolvedHead = normalizeUpsertHead(rowHeadLike, currentHead, nextRowFallbackOrder);
             if (currentHeadCell) {
                 currentHeadCell.set(resolvedHead);
             }
             else {
-                rowHeadCells.set(resolvedHead.id, cell(resolvedHead));
-                rowTailCells.set(resolvedHead.id, cell(createEmptyTailState()));
-                rowHeadOrder.set(resolvedHead.id, nextRowFallbackOrder);
+                rowHeadCells.set(rowIdKey, cell(resolvedHead));
+                rowTailCells.set(rowIdKey, cell(createEmptyTailState()));
+                rowHeadOrder.set(rowIdKey, nextRowFallbackOrder);
                 nextRowFallbackOrder += 1;
             }
             rows.push(resolvedHead);
             if (currentHead) {
                 previousRows.push(currentHead);
             }
-            rowIds.add(resolvedHead.id);
+            rowIds.set(rowIdKey, resolvedHead.id);
             shouldRecomputeColumns ||= !currentHead || currentHead.order !== resolvedHead.order;
         });
-        const resolvedRowIds = [...rowIds];
+        const resolvedRowIds = [...rowIds.values()];
         return {
             rows,
             previousRows,
@@ -488,35 +817,34 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         if (nextColumnHeads.length === 0) {
             return null;
         }
-        const columnIds = new Set();
+        const columnIds = new Map();
         const columns = [];
         const previousColumns = [];
         let shouldRecomputeRows = false;
         nextColumnHeads.forEach((nextColumnHead) => {
             const columnHeadLike = nextColumnHead;
-            if (typeof columnHeadLike.id !== "string") {
-                throw new Error("Column header upserts must include a string id.");
-            }
-            const currentHeadCell = columnHeadCells.get(columnHeadLike.id);
+            const columnIdKey = createGridIdKey(columnHeadLike.id);
+            assertGridId(columnHeadLike.id, "Column header upserts");
+            const currentHeadCell = columnHeadCells.get(columnIdKey);
             const currentHead = currentHeadCell?.get();
             const resolvedHead = normalizeUpsertHead(columnHeadLike, currentHead, nextColumnFallbackOrder);
             if (currentHeadCell) {
                 currentHeadCell.set(resolvedHead);
             }
             else {
-                columnHeadCells.set(resolvedHead.id, cell(resolvedHead));
-                columnTailCells.set(resolvedHead.id, cell(createEmptyTailState()));
-                columnHeadOrder.set(resolvedHead.id, nextColumnFallbackOrder);
+                columnHeadCells.set(columnIdKey, cell(resolvedHead));
+                columnTailCells.set(columnIdKey, cell(createEmptyTailState()));
+                columnHeadOrder.set(columnIdKey, nextColumnFallbackOrder);
                 nextColumnFallbackOrder += 1;
             }
             columns.push(resolvedHead);
             if (currentHead) {
                 previousColumns.push(currentHead);
             }
-            columnIds.add(resolvedHead.id);
+            columnIds.set(columnIdKey, resolvedHead.id);
             shouldRecomputeRows ||= !currentHead || currentHead.order !== resolvedHead.order;
         });
-        const resolvedColumnIds = [...columnIds];
+        const resolvedColumnIds = [...columnIds.values()];
         return {
             columns,
             previousColumns,
@@ -597,6 +925,66 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
     const upsertCell = (nextCell) => {
         emitCellUpsert("upsertCell", [nextCell]);
     };
+    const setCell = (rowId, columnId, nextValue) => {
+        assertCellAxesExist(rowId, columnId);
+        const gridKey = createGridKey(rowId, columnId);
+        const currentCell = cellsMap.get(gridKey);
+        const currentValue = currentCell?.get();
+        const resolvedNextValue = resolveUpdater(nextValue, currentValue);
+        if (resolvedNextValue === undefined) {
+            if (!currentCell) {
+                return;
+            }
+            detachCell(gridKey);
+            syncDirtyCellKey(gridKey);
+            const rowTailIds = recomputeRowTailInternal(rowId) ? [rowId] : [];
+            const columnTailIds = recomputeColumnTailInternal(columnId) ? [columnId] : [];
+            emitGridUpdate({
+                type: "cells",
+                action: "clear",
+                source: "setCell",
+                rowIds: [rowId],
+                columnIds: [columnId],
+                rowTailIds: toOptionalArray(rowTailIds),
+                columnTailIds: toOptionalArray(columnTailIds),
+                cellKeys: [gridKey],
+                previousCells: [
+                    stateAdapter.serializeCell(rowId, columnId, currentValue),
+                ],
+            }, true);
+            return;
+        }
+        const normalizedValue = normalizeCellValue(rowId, columnId, resolvedNextValue);
+        isApplyingState = true;
+        try {
+            if (currentCell) {
+                currentCell.set(normalizedValue);
+            }
+            else {
+                attachCell(rowId, columnId, cell(normalizedValue));
+            }
+        }
+        finally {
+            isApplyingState = false;
+        }
+        syncDirtyCellKey(gridKey);
+        const rowTailIds = recomputeRowTailInternal(rowId) ? [rowId] : [];
+        const columnTailIds = recomputeColumnTailInternal(columnId) ? [columnId] : [];
+        emitGridUpdate({
+            type: "cells",
+            action: currentCell ? "update" : "upsert",
+            source: "setCell",
+            rowIds: [rowId],
+            columnIds: [columnId],
+            rowTailIds: toOptionalArray(rowTailIds),
+            columnTailIds: toOptionalArray(columnTailIds),
+            cellKeys: [gridKey],
+            cells: [stateAdapter.serializeCell(rowId, columnId, normalizedValue)],
+            previousCells: currentCell
+                ? [stateAdapter.serializeCell(rowId, columnId, currentValue)]
+                : undefined,
+        }, true);
+    };
     function getState() {
         const rows = getOrderedRowHeads();
         const columns = getOrderedColumnHeads();
@@ -644,23 +1032,25 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         });
     };
     function registerRowTail(rowId, onRowUpdate) {
-        rowTailUpdaters.set(rowId, onRowUpdate);
+        const rowIdKey = createGridIdKey(rowId);
+        rowTailUpdaters.set(rowIdKey, onRowUpdate);
         recomputeRowTailInternal(rowId);
         return () => {
-            if (rowTailUpdaters.get(rowId) !== onRowUpdate) {
+            if (rowTailUpdaters.get(rowIdKey) !== onRowUpdate) {
                 return;
             }
-            rowTailUpdaters.delete(rowId);
+            rowTailUpdaters.delete(rowIdKey);
         };
     }
     function registerColumnTail(columnId, onColumnUpdate) {
-        columnTailUpdaters.set(columnId, onColumnUpdate);
+        const columnIdKey = createGridIdKey(columnId);
+        columnTailUpdaters.set(columnIdKey, onColumnUpdate);
         recomputeColumnTailInternal(columnId);
         return () => {
-            if (columnTailUpdaters.get(columnId) !== onColumnUpdate) {
+            if (columnTailUpdaters.get(columnIdKey) !== onColumnUpdate) {
                 return;
             }
-            columnTailUpdaters.delete(columnId);
+            columnTailUpdaters.delete(columnIdKey);
         };
     }
     const setGrid = (nextState, mode = "replace") => {
@@ -804,31 +1194,10 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         },
         getState,
         setGrid,
+        readCell,
+        setCell,
         getCell,
         getValue: (rowId, columnId) => getCell(rowId, columnId).get(),
-        __setCellValue: (rowId, columnId, newValue) => {
-            const currentCell = getCell(rowId, columnId);
-            isApplyingState = true;
-            try {
-                currentCell.set(normalizeCellValue(rowId, columnId, newValue));
-            }
-            finally {
-                isApplyingState = false;
-            }
-            const rowTailIds = recomputeRowTailInternal(rowId) ? [rowId] : [];
-            const columnTailIds = recomputeColumnTailInternal(columnId) ? [columnId] : [];
-            emitGridUpdate({
-                type: "cells",
-                action: "update",
-                source: "cell.set",
-                rowIds: [rowId],
-                columnIds: [columnId],
-                rowTailIds: toOptionalArray(rowTailIds),
-                columnTailIds: toOptionalArray(columnTailIds),
-                cellKeys: [createGridKey(rowId, columnId)],
-                cells: [stateAdapter.serializeCell(rowId, columnId, currentCell.get())],
-            }, true);
-        },
         hasCell: (rowId, columnId) => cellsMap.has(createGridKey(rowId, columnId)),
         getRowHead: (rowId) => getHeadCell(rowHeadCells, rowId, "row").get(),
         getColumnHead: (columnId) => getHeadCell(columnHeadCells, columnId, "column").get(),
@@ -871,6 +1240,11 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         recomputeRowTail,
         recomputeColumnTail,
     };
+    Object.defineProperty(gridApi, "__persistOption", {
+        value: persist,
+        enumerable: false,
+        configurable: true,
+    });
     return gridApi;
 }
 function resolveUpdater(nextValue, currentValue) {
@@ -879,45 +1253,49 @@ function resolveUpdater(nextValue, currentValue) {
         : nextValue;
 }
 export function createGridKey(rowId, columnId) {
-    return `${rowId}:${columnId}`;
-}
-export function useGrid(currentGrid, options) {
-    const snapshotRef = useRef({
-        rows: currentGrid.rowHeaders,
-        cols: currentGrid.colHeaders,
-    });
-    const onGridUpdateRef = useRef(options?.onGridUpdate);
-    useEffect(() => {
-        onGridUpdateRef.current = options?.onGridUpdate;
-    }, [options?.onGridUpdate]);
-    useEffect(() => {
-        return currentGrid.subscribeGrid((updatedGrid, diff) => {
-            onGridUpdateRef.current?.(updatedGrid, diff);
-        });
-    }, [currentGrid]);
-    const subscribe = useCallback((callback) => currentGrid.subscribeGrid(() => callback()), [currentGrid]);
-    const getSnapshot = useCallback(() => {
-        const nextRows = currentGrid.rowHeaders;
-        const nextCols = currentGrid.colHeaders;
-        const currentSnapshot = snapshotRef.current;
-        if (currentSnapshot.rows === nextRows && currentSnapshot.cols === nextCols) {
-            return currentSnapshot;
-        }
-        const nextSnapshot = {
-            rows: nextRows,
-            cols: nextCols,
-        };
-        snapshotRef.current = nextSnapshot;
-        return nextSnapshot;
-    }, [currentGrid]);
-    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    return `row=${createGridIdKey(rowId)}|col=${createGridIdKey(columnId)}`;
 }
 function toOptionalArray(values) {
     return values.length === 0 ? undefined : values;
 }
+function describeIndexRange(size, index) {
+    if (size === 0) {
+        return `The grid currently has no items, so index ${index} cannot be selected.`;
+    }
+    return `Expected an index between 0 and ${size - 1} (${size} total items).`;
+}
+function haveSameRuntimeValue(leftValue, rightValue) {
+    if (Object.is(leftValue, rightValue)) {
+        return true;
+    }
+    if (leftValue instanceof Date && rightValue instanceof Date) {
+        return leftValue.getTime() === rightValue.getTime();
+    }
+    if (Array.isArray(leftValue) && Array.isArray(rightValue)) {
+        return (leftValue.length === rightValue.length &&
+            leftValue.every((currentValue, index) => haveSameRuntimeValue(currentValue, rightValue[index])));
+    }
+    if (!isPlainObject(leftValue) || !isPlainObject(rightValue)) {
+        return false;
+    }
+    const leftKeys = Object.keys(leftValue);
+    const rightKeys = Object.keys(rightValue);
+    if (leftKeys.length !== rightKeys.length) {
+        return false;
+    }
+    return leftKeys.every((key) => {
+        if (!(key in rightValue)) {
+            return false;
+        }
+        return haveSameRuntimeValue(leftValue[key], rightValue[key]);
+    });
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function haveSameItems(left, right) {
     return (left.length === right.length &&
-        left.every((currentValue, index) => Object.is(currentValue, right[index])));
+        left.every((currentValue, index) => createGridIdKey(currentValue) === createGridIdKey(right[index])));
 }
 function normalizeGridStateInput(value) {
     if (!value || typeof value !== "object") {
@@ -969,16 +1347,16 @@ function mergeHeadStates(currentHeads, nextHeads) {
     const currentIds = new Set();
     const nextHeadsById = new Map();
     currentHeads.forEach((currentHead) => {
-        currentIds.add(currentHead.id);
+        currentIds.add(createGridIdKey(currentHead.id));
     });
     nextHeads.forEach((nextHead) => {
-        nextHeadsById.set(nextHead.id, nextHead);
+        nextHeadsById.set(createGridIdKey(nextHead.id), nextHead);
     });
     const resolvedHeads = currentHeads.map((currentHead) => {
-        return nextHeadsById.get(currentHead.id) ?? currentHead;
+        return nextHeadsById.get(createGridIdKey(currentHead.id)) ?? currentHead;
     });
     nextHeads.forEach((nextHead) => {
-        if (currentIds.has(nextHead.id)) {
+        if (currentIds.has(createGridIdKey(nextHead.id))) {
             return;
         }
         resolvedHeads.push(nextHead);
@@ -1013,7 +1391,7 @@ function normalizeGridState(value) {
         throw new Error("Grid state initializer must return an object.");
     }
     if (Array.isArray(value)) {
-        throw new Error("Legacy matrix grid input has been removed. Pass a schema object with rows, columns, and cells instead.");
+        throw new Error("Grid state initializer must be a schema object with rows, columns, and cells.");
     }
     const partialState = value;
     const { cells = [], rows = [], columns = [] } = partialState;
@@ -1029,9 +1407,7 @@ function normalizeGridState(value) {
 function normalizeRecordHeads(heads, idKey) {
     return heads.map((head, index) => {
         const id = head[idKey];
-        if (typeof id !== "string") {
-            throw new Error(`Grid header key "${String(idKey)}" must resolve to a string id.`);
-        }
+        assertGridId(id, `Grid header key "${String(idKey)}"`);
         return {
             ...head,
             id,
@@ -1047,7 +1423,7 @@ function createGridInitialCellsFromState(stateCells, stateAdapter) {
         const { rowId, columnId, value } = stateAdapter.deserializeCell(stateCell);
         const gridKey = createGridKey(rowId, columnId);
         if (seenKeys.has(gridKey)) {
-            throw new Error(`Duplicate cell for row "${rowId}" and column "${columnId}".`);
+            throw new Error(`Duplicate cell for row "${formatGridId(rowId)}" and column "${formatGridId(columnId)}".`);
         }
         seenKeys.add(gridKey);
         initialCells.push({
@@ -1063,9 +1439,8 @@ function createSchemaStateAdapter(rowCellKey, columnCellKey) {
         deserializeCell: (stateCell) => {
             const rowId = stateCell[rowCellKey];
             const columnId = stateCell[columnCellKey];
-            if (typeof rowId !== "string" || typeof columnId !== "string") {
-                throw new Error(`Grid cell keys "${String(rowCellKey)}" and "${String(columnCellKey)}" must resolve to string ids.`);
-            }
+            assertGridId(rowId, `Grid cell key "${String(rowCellKey)}"`);
+            assertGridId(columnId, `Grid cell key "${String(columnCellKey)}"`);
             return {
                 rowId: rowId,
                 columnId: columnId,
@@ -1104,10 +1479,11 @@ function normalizeUpsertHead(nextHead, currentHead, fallbackOrder) {
 function assertUniqueHeadIds(heads, axis) {
     const seenIds = new Set();
     heads.forEach((head) => {
-        if (seenIds.has(head.id)) {
-            throw new Error(`Duplicate ${axis} header "${head.id}".`);
+        const idKey = createGridIdKey(head.id);
+        if (seenIds.has(idKey)) {
+            throw new Error(`Duplicate ${axis} header "${formatGridId(head.id)}".`);
         }
-        seenIds.add(head.id);
+        seenIds.add(idKey);
     });
 }
 function createEmptyTailState() {
@@ -1125,54 +1501,7 @@ function readGridHeadLabel(head, id) {
     if (typeof name === "string") {
         return name;
     }
-    return id;
-}
-function resolveCreateSubGridArgs(cellsOrOptionsOrPersist, persist) {
-    if (persist) {
-        return {
-            initialCells: readCreateSubGridCells(cellsOrOptionsOrPersist),
-            persistOption: persist,
-        };
-    }
-    if (!cellsOrOptionsOrPersist) {
-        return {
-            initialCells: [],
-            persistOption: undefined,
-        };
-    }
-    if (isCreateSubGridOptions(cellsOrOptionsOrPersist)) {
-        const subGridOptions = cellsOrOptionsOrPersist;
-        return {
-            initialCells: subGridOptions.cells ?? [],
-            persistOption: subGridOptions.persist,
-        };
-    }
-    if (isGridPersistOption(cellsOrOptionsOrPersist)) {
-        return {
-            initialCells: [],
-            persistOption: cellsOrOptionsOrPersist,
-        };
-    }
-    return {
-        initialCells: cellsOrOptionsOrPersist,
-        persistOption: undefined,
-    };
-}
-function readCreateSubGridCells(value) {
-    if (!value || isGridPersistOption(value)) {
-        return [];
-    }
-    if (isCreateSubGridOptions(value)) {
-        return (value
-            .cells ?? []);
-    }
-    return value;
-}
-function isCreateSubGridOptions(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isGridPersistOption(value) {
-    return Array.isArray(value) && value.length > 0 && typeof value[0] === "string";
+    return formatGridId(id);
 }
 function createGridStateCellAdapter() {
     return {
@@ -1189,12 +1518,13 @@ function createGridStateCellAdapter() {
     };
 }
 function createSubGridPersistOption(parentGrid, persist) {
-    if (!persist) {
+    const resolvedPersist = resolveDependentGridPersistOption(parentGrid, persist, "sub-grid");
+    if (!resolvedPersist) {
         return undefined;
     }
-    const [storageKey, adapter] = persist;
-    const resolvedAdapter = adapter ??
-        defaultGridPersistAdapter;
+    const [storageKey, adapter] = resolvedPersist;
+    const resolvedAdapter = (adapter ??
+        defaultGridPersistAdapter);
     return [
         storageKey,
         {
@@ -1220,6 +1550,73 @@ function createSubGridPersistOption(parentGrid, persist) {
         },
     ];
 }
+function createDimensionGridPersistOption(parentGrid, dimension, persist) {
+    const resolvedPersist = resolveDependentGridPersistOption(parentGrid, persist, `dimension-grid:${dimension}`);
+    if (!resolvedPersist) {
+        return undefined;
+    }
+    const [storageKey, adapter] = resolvedPersist;
+    const resolvedAdapter = (adapter ?? defaultGridPersistAdapter);
+    return [
+        storageKey,
+        {
+            get: async (nextStorageKey) => {
+                const persistedState = await Promise.resolve(resolvedAdapter.get(nextStorageKey));
+                if (persistedState === null) {
+                    return null;
+                }
+                try {
+                    return normalizeDimensionGridStateInput(persistedState, dimension);
+                }
+                catch {
+                    return null;
+                }
+            },
+            set: (nextStorageKey, nextState) => {
+                return resolvedAdapter.set(nextStorageKey, normalizeDimensionGridStateInput(nextState, dimension));
+            },
+            remove: (nextStorageKey) => resolvedAdapter.remove(nextStorageKey),
+        },
+    ];
+}
+function normalizeDimensionGridStateInput(value, dimension) {
+    if (Array.isArray(value)) {
+        return {
+            dimension,
+            cells: value,
+        };
+    }
+    if (!value || typeof value !== "object") {
+        throw new Error("Dimension grid state updates must be arrays or objects.");
+    }
+    const nextState = value;
+    if (nextState.dimension !== undefined && nextState.dimension !== dimension) {
+        throw new Error(`Dimension grid state must use the "${dimension}" dimension when updating this grid.`);
+    }
+    if (!Array.isArray(nextState.cells)) {
+        throw new Error("Dimension grid state updates must provide a cells array.");
+    }
+    return {
+        dimension,
+        cells: nextState.cells,
+    };
+}
+function resolveDependentGridPersistOption(parentGrid, persist, suffix) {
+    if (persist === false) {
+        return undefined;
+    }
+    if (persist) {
+        return persist;
+    }
+    const inheritedPersist = parentGrid.__persistOption;
+    if (!inheritedPersist) {
+        return undefined;
+    }
+    return [
+        `${inheritedPersist[0]}:${suffix}`,
+        inheritedPersist[1],
+    ];
+}
 function createSubGridState(rows, columns, cells) {
     return {
         rows,
@@ -1228,22 +1625,23 @@ function createSubGridState(rows, columns, cells) {
     };
 }
 function assertGridStateCellsWithinAxes(cells, rows, columns, contextLabel) {
-    const rowIds = new Set(rows.map((rowHead) => rowHead.id));
-    const columnIds = new Set(columns.map((columnHead) => columnHead.id));
+    const rowIds = new Set(rows.map((rowHead) => createGridIdKey(rowHead.id)));
+    const columnIds = new Set(columns.map((columnHead) => createGridIdKey(columnHead.id)));
     cells.forEach((currentCell) => {
-        if (!rowIds.has(currentCell.rowId)) {
-            throw new Error(`${contextLabel} must reference an existing parent row header. Missing row "${currentCell.rowId}".`);
+        if (!rowIds.has(createGridIdKey(currentCell.rowId))) {
+            throw new Error(`${contextLabel} must reference an existing parent row header. Missing row "${formatGridId(currentCell.rowId)}".`);
         }
-        if (!columnIds.has(currentCell.columnId)) {
-            throw new Error(`${contextLabel} must reference an existing parent column header. Missing column "${currentCell.columnId}".`);
+        if (!columnIds.has(createGridIdKey(currentCell.columnId))) {
+            throw new Error(`${contextLabel} must reference an existing parent column header. Missing column "${formatGridId(currentCell.columnId)}".`);
         }
     });
     return cells;
 }
 function filterGridStateCellsToAxes(cells, rows, columns) {
-    const rowIds = new Set(rows.map((rowHead) => rowHead.id));
-    const columnIds = new Set(columns.map((columnHead) => columnHead.id));
-    return cells.filter((currentCell) => rowIds.has(currentCell.rowId) && columnIds.has(currentCell.columnId));
+    const rowIds = new Set(rows.map((rowHead) => createGridIdKey(rowHead.id)));
+    const columnIds = new Set(columns.map((columnHead) => createGridIdKey(columnHead.id)));
+    return cells.filter((currentCell) => rowIds.has(createGridIdKey(currentCell.rowId)) &&
+        columnIds.has(createGridIdKey(currentCell.columnId)));
 }
 function didGridDiffAffectAxes(diff) {
     return (!haveSameHeadSnapshots(diff.rows, diff.previousRows) ||
@@ -1277,7 +1675,18 @@ function haveSameShallowRecord(leftRecord, rightRecord) {
         if (!(key in rightRecord)) {
             return false;
         }
-        return Object.is(leftRecord[key], rightRecord[key]);
+        const leftValue = leftRecord[key];
+        const rightValue = rightRecord[key];
+        if (isGridIdValue(leftValue) && isGridIdValue(rightValue)) {
+            return createGridIdKey(leftValue) === createGridIdKey(rightValue);
+        }
+        return Object.is(leftValue, rightValue);
     });
 }
+function isGridIdValue(value) {
+    return (typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        value instanceof Date);
+}
 //# sourceMappingURL=grid.js.map