Events

grid.on(evt, fn) subscribes to a grid event and returns an off() function. Call it to unsubscribe.

const off = grid.on("change", ({ transaction, source, commitReason }) => {
  if (source === "local") console.log(commitReason, transaction.patches.length);
});
// later
off();

After a user types a value and presses Enter, the log shows edit-enter 1.

Event direction

change is the committed transaction stream. ChangeEvent.source is local for user or API output that a host may persist, and remote for already-persisted input that must not be enqueued again. Selection, search, renderer fallback, and other UI events remain observational.

Framework onGridChange / grid-change callbacks carry the same committed event. Adapter readiness is { grid, generation, reason }; reason distinguishes initial, input-reset, and renderer-reset. The imperative ref, exposed handle, or binding is assigned before readiness and cleared on replacement.

Grid events

commitReason is one of edit-blur, edit-enter, edit-tab, edit-programmatic, paste, cut, clear, fill, structure, style, replace, undo, redo or api.

Sync coordinator events

SyncCoordinator has its own event stream. sync.on(fn) returns an unsubscribe function:

const sync = new SyncCoordinator(grid, adapter, {
  documentId: "products",
  serverVersion: loadedSnapshot.version ?? 0,
});
const off = sync.on((event) => {
  if (event.type === "conflict") showConflict(event.response);
  if (event.type === "reload-required") requestFreshSnapshot();
});

saveButton.onclick = () => void sync.sendNext();
// later
off();
sync.destroy();

Edge cases and limits

• Persist only change events with source: "local". Remote input is observable but never belongs in outgoing local persistence.
• changes is empty for commits that only change metadata.
• Hydration from a snapshot and datasource pages emit no user change event.

See also

• Grid methods
• Persistence
• Error handling
• Generated GridEvents, ChangeEvent and SyncCoordinatorEvent contracts