gridcn2.0.0
Contracts

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:

FunctionReturns
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 update or a delete finds its row by rowId. The stored index does not matter. If the row id is not in data, the engine skips the operation without an error.
  • An update puts its row in place of the stored row. It merges no cells.
  • With duplicate row ids, an operation uses the first row with that id.
  • A move applies as a delete plus an insert at to.
  • The index of a delete and the from of a move are positions before the whole change. They are not running positions.
  • The index of an insert and the to of a move are positions in the result. An insert index past the end puts the row last.
  • insert operations apply in ascending index order, whatever their order in ops.

invertChange

invertChange inverts each operation and reverses the order of the operations, so a change unwinds in the right order:

OperationInverse
updateAn update with row and prev swapped. The value and prev of each cell swap too
insertA delete of the same row
deleteAn insert of the same row
moveA 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.

On this page