Data Grid — change tracking & persistence

1"use client"
2 
3/**
4 * niko-table — created by Semir N. (Semkoo, https://github.com/Semkoo) with AI assistance.
5 *
6 * Before reporting anything: please check the changelog first.
7 *  - In-repo: ./CHANGELOG.md
8 *  - Docs site: https://niko-table.com/changelog
9 *
10 * Found a bug or have a fix? Open an issue or PR on GitHub so other
11 * users (and future LLMs reading this code) benefit:
12 * https://github.com/Semkoo/niko-table-registry
13 */
14/**
15 * niko-table grid — change tracking & persistence (opt-in).
16 *
17 * The engine (`useDataGrid`) is UNCONTROLLED — it owns the rows. This hook
18 * OBSERVES it (via the `lastCommit` signal) and turns local edits into a CRUD
19 * change-set, so a consumer can stage, autosave, or do full create/update/delete
20 * against a backend. Install/import it ONLY on a grid that persists; grids that
21 * don't pay nothing. Plain React, no dependency.
22 *
23 * Three patterns, one hook:
24 *  - Staging:  edit → on Save read `getChangeSet().created` → one bulk mutation
25 *              → `reconcile({ succeededIds, failedIds })` → highlight failures.
26 *  - Autosave: `useEffect([dirtyRowIds])` + debounce → `getChangeSet()`
27 *              → batch upsert → `reconcile`.
28 *  - Full CRUD: create/update/delete all fall out of the change-set.
29 */
30import * as React from "react"
31 
32import type { UseDataGrid } from "./use-data-grid"
33import type { GridRow } from "../types/grid-cell"
34 
35export interface UseGridChangesOptions<TRow extends GridRow> {
36  /**
37   * The server/pre-existing baseline. These rows' ids are "existing" (edits to
38   * them are UPDATEs; removing them is a DELETE). Omit / pass `[]` for a fresh
39   * import where everything the user enters is a CREATE. For a live-edit surface,
40   * pass the SAME loaded rows you seeded `useDataGrid({ initialRows })` with.
41   */
42  initialRows?: readonly TRow[]
43  /** Row identity. Default `(r) => r.id`. */
44  getRowId?: (row: TRow) => string
45  /**
46   * Compare a current row to its baseline snapshot to filter reverts out of
47   * `getChangeSet().updated` (a row edited back to its original value isn't a
48   * real update). Default: reference equality — pair it with the engine's
49   * structural sharing (unchanged rows keep their reference).
50   */
51  isEqual?: (current: TRow, baseline: TRow) => boolean
52}
53 
54/** The precise CRUD delta to send to a backend. */
55export interface GridChangeSet<TRow extends GridRow> {
56  /** New rows (not in the baseline). */
57  created: TRow[]
58// … truncated