@jielga/tmdatagrid 2.0.0-beta.17 → 2.0.0-beta.18

package/dist/index.d.ts

@@ -188,8 +188,9 @@ type TMDataGridTableValidateArgs<TData extends RowData = TMDataGridRowData> = {
 /**
  * `editing.tableValidators` - rules that need the other rows: no duplicate
  * keys, no overlapping ranges, allocations summing to a total. Run at every
- * commit, after the row's own validators, and again per parked row during
- * `saveDrafts` - so a draft invalidated by a later edit blocks the save.
+ * commit, after the row's own validators, and again per committed row during
+ * `saveDrafts`, the only rules that run there - a committed row a later edit
+ * invalidated is reopened with the error and the save resolves `false`.
  *
  * Return nothing to pass, a message, or Form's `{ form, fields }` shape;
  * pathed issues land on the committing row's cells, pathless ones on the row.
@@ -265,20 +266,22 @@ type TMDataGridEditState = {
     columnId: string | null;
   } | null;
   /**
-   * Rows with a live form, committed or not - every row the grid is holding
-   * work for. A row is *open* (undecided form state) when it is in here and
-   * not in {@link committedRowIds}.
+   * Every row the grid is holding work for: open rows, whose form is still
+   * undecided, and committed rows, whose values wait in the draft store. In
+   * the order the rows first entered; a reopen keeps a row's place. A row is
+   * *open* when it is in here and not in {@link committedRowIds}, or, for an
+   * entry row, not flagged `committed` in {@link newRows}.
    */
   openRowIds: ReadonlyArray<string>;
   rows: Record<string, TMDataGridEditRowProjection>;
   /**
-   * The draft store's edit slice: existing rows whose form passed its submit
-   * and is parked, waiting for `saveDrafts`. A subset of `openRowIds` - the
-   * values stay in the row's form, this records which side of the line the
-   * row is on. `begin` on one of these takes it back out, into form state.
+   * The draft store's edit slice: existing rows that passed their commit and
+   * wait for `saveDrafts`. A committed row is data, not a form: its values
+   * are in {@link committedValues}, and `begin` on one of these builds a
+   * fresh form from them and takes the row back out.
    *
-   * Only `editing.draft` parks. Without it a commit goes straight to the
-   * consumer and the form is dropped, so this stays empty.
+   * Only `editing.draft` commits into the store. Without it a commit goes
+   * straight to the consumer, so this stays empty.
    */
   committedRowIds: ReadonlyArray<string>;
   /**
@@ -294,8 +297,9 @@ type TMDataGridEditState = {
   /**
    * Rows being created, not yet in `data`. `committed` is the draft store's
    * add slice: the entry row passed its submit and renders as a value row
-   * until `begin` re-opens it. Without `editing.draft` a commit adds through
-   * `onRowAdd` and the entry is dropped, so it never turns `true`.
+   * from {@link committedValues} until `begin` re-opens it. Without
+   * `editing.draft` a commit adds through `onRowAdd` and the entry is
+   * dropped, so it never turns `true`.
    */
   newRows: ReadonlyArray<{
     tempId: string;
@@ -520,22 +524,28 @@ type TMDataGridEditRowSnapshot<TData extends RowData = TMDataGridRowData> = {
 /**
  * The engine plus its store - `api.edit`.
  *
- * "One row, one form": `getForm` hands out the same `FormApi` the inline
- * editors write through, so a consumer can render it in a drawer or a detail
- * panel and share values, dirty state and errors with the cells.
+ * "One row, one form" while a row is open: `getForm` hands out the same
+ * `FormApi` the inline editors write through, so a consumer can render it in
+ * a drawer or a detail panel and share values, dirty state and errors with
+ * the cells. A committed row has no form - it is data in the draft store -
+ * so `getForm` returns `undefined` for it until `begin` reopens it.
  */
 type TMDataGridEditApi<TData extends RowData = TMDataGridRowData> = {
   /** The projection store - subscribe with `useSelector(edit.store, …)`. */
   store: Store<TMDataGridEditState>;
   /** Current snapshot, for reads outside React. */
   readonly state: TMDataGridEditState;
-  /** rowId → live form. The source of truth for everything mid-edit. */
+  /**
+   * rowId → the open row's live form, the source of truth for everything
+   * mid-edit. `undefined` for a row that is not open, a committed row
+   * included; `begin` reopens one.
+   */
   getForm: (rowId: string) => TMDataGridRowEditForm | undefined;
   /**
-   * The row as shown: its draft values where a form holds one - open or
-   * parked in the draft store - else what `data` says. `undefined` when no
-   * such row exists. A deletion mark does not change the answer; check
-   * `state.deletedRowIds` for that.
+   * The row as shown: its draft values where the grid holds any - an open
+   * form's, or the committed values in the draft store - else what `data`
+   * says. `undefined` when no such row exists. A deletion mark does not
+   * change the answer; check `state.deletedRowIds` for that.
    */
   getRowValues: (rowId: string) => TData | undefined;
   /**
@@ -2123,8 +2133,10 @@ type TMDataGridApi<TData extends RowData> = {
   /**
    * The edit engine - open forms, dirty/error projections, and the verbs
    * (`begin`, `commit`, `cancel`, `submitAll`). `edit.getForm(rowId)` hands
-   * out the same TanStack Form the inline editors write through, so a drawer
-   * or detail panel can share a row's draft. Inert until `editing` is set.
+   * out the same TanStack Form the inline editors write through while a row
+   * is open, so a drawer or detail panel can share a row's draft; a
+   * committed row has no form until `begin` reopens it. Inert until
+   * `editing` is set.
    */
   edit: TMDataGridEditApi<TData>;
   /** Table-level feature switches, re-read from options on every render. */