Operation engine contract
Apply and invert a DataChange against your own copy of the rows with applyChange and invertChange.
Every write to the rows is a DataChange: a list of operations addressed by row id. The grid applies each change through one engine.
Operation engine
The data-grid entry exports two functions of the engine:
| Function | Returns |
|---|---|
applyChange(data, change, getRowId?) | A new row array with the change applied |
invertChange(change, source?) | The change that undoes change |
applyChange
applyChange never edits data. It returns a new array and keeps the object of every row that no operation touched. It runs in O(n + k log(n + k)) for n rows and k operations. This sample applies and undoes a change on your own copy of the rows:
import {
applyChange,
invertChange,
type DataChange,
} from "@/components/data-grid/data-grid";
type Row = { id: string; name: string };
export function applyToCache(cache: Row[], change: DataChange<Row>) {
return applyChange(cache, change);
}
export function undoOnCache(cache: Row[], change: DataChange<Row>) {
return applyChange(cache, invertChange(change));
}getRowId defaults to the id field of each row, as in the grid. Pass it when your rows use another key.
These rules apply:
- An
updateor adeletefinds its row byrowId. The storedindexdoes not matter. If the row id is not indata, the engine skips the operation without an error. - An
updateputs itsrowin place of the stored row. It merges no cells. - With duplicate row ids, an operation uses the first row with that id.
- A
moveapplies as a delete plus an insert atto. - The
indexof adeleteand thefromof amoveare positions before the whole change. They are not running positions. - The
indexof aninsertand thetoof amoveare positions in the result. An insertindexpast the end puts the row last. insertoperations apply in ascendingindexorder, whatever their order inops.
invertChange
invertChange inverts each operation and reverses the order of the operations, so a change unwinds in the right order:
| Operation | Inverse |
|---|---|
update | An update with row and prev swapped. The value and prev of each cell swap too |
insert | A delete of the same row |
delete | An insert of the same row |
move | A move with from and to swapped |
The result keeps label. Its source is "history" by default. Pass "rollback" to tag the revert of a failed save, so that an onDataChange handler can tell it from an undo.
commitChange
actions.commitChange(change) applies a whole change to the grid through applyChange. It writes once and fires onDataChange once, so the change lands on the undo stack as one entry. It does nothing on a readOnly grid, except for a change with source: "stream". If no operation applies, it writes and fires nothing.
commitChange clears the errors of the cells it writes, and the active cell and the checked rows follow their records. It does not run the column validate. It runs validateRow for the rows it inserts or updates, except for a change with source: "stream". A change with source: "history" or "rollback" is never recorded in the undo stack.
The history add-on inverts with invertChange. It re-targets each update that has cells onto the current row, so it writes only those cells. It applies the result with commitChange. Its rollback reverts a cell only while the cell still holds the change's value.