zubin-grid 0.4.13 → 0.41.13

package/dist/core/grid.js

@@ -1,6 +1,7 @@
 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 +14,212 @@ 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]),
+    ]));
+    let dimensionGridApi;
+    const getCellAtIndex = (index) => {
+        if (!Number.isInteger(index) || index < 0 || index >= boundIds.length) {
+            throw new Error(`Dimension grid ${dimension} index ${index} is out of bounds.`);
+        }
+        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 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;
+        }
+        return changedIndices;
+    };
+    const { hydrate, markStateChanged } = createGridPersistController(resolvedPersistOption, {
+        getState,
+        replaceState: (nextState) => {
+            applyDimensionCells(normalizeDimensionGridStateInput(nextState, dimension).cells, "replace");
+        },
+        isApplyingState: () => isApplyingState,
+    });
+    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);
+        });
+        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,
+        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);
+            };
+        },
+        __setCellValue: (index, newValue) => {
+            const currentCell = getCellAtIndex(index);
+            if (Object.is(currentCell.get(), newValue)) {
+                return;
+            }
+            isApplyingState = true;
+            try {
+                currentCell.set(newValue);
+            }
+            finally {
+                isApplyingState = false;
+            }
+            emitDimensionGridUpdate({
+                type: "cells",
+                action: "update",
+                source: "cell.set",
+                dimension,
+                size: boundIds.length,
+                indices: [index],
+            }, true);
+        },
+    };
+    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);
@@ -174,13 +375,13 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
         return stateAdapter.deserializeCell(stateAdapter.serializeCell(rowId, columnId, value)).value;
     };
     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 +410,16 @@ 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}".`);
+        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 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(() => {
@@ -244,8 +448,9 @@ function createGridStore(initialRows, initialColumns, initialCells, stateAdapter
     };
     const getCell = (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 createAxisCellSnapshot = (rowId, columnId) => {
@@ -272,15 +477,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 +500,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,
@@ -365,8 +571,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 +580,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 +597,16 @@ 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];
+        const rowIds = [...touchedRowIds.values()];
+        const columnIds = [...touchedColumnIds.values()];
         return {
             rowIds,
             columnIds,
@@ -431,35 +639,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 +695,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,
@@ -644,23 +850,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") => {
@@ -871,6 +1079,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,7 +1092,7 @@ function resolveUpdater(nextValue, currentValue) {
         : nextValue;
 }
 export function createGridKey(rowId, columnId) {
-    return `${rowId}:${columnId}`;
+    return `row=${createGridIdKey(rowId)}|col=${createGridIdKey(columnId)}`;
 }
 export function useGrid(currentGrid, options) {
     const snapshotRef = useRef({
@@ -917,7 +1130,7 @@ function toOptionalArray(values) {
 }
 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 +1182,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 +1226,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 +1242,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 +1258,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 +1274,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 +1314,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 +1336,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 +1353,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 +1385,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 +1460,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 +1510,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