@jielga/tmdatagrid 2.0.0-beta.3 → 2.0.0-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/dist/index.d.ts +167 -88
  2. package/dist/index.js +2430 -2319
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
  5. package/skills/appearance/SKILL.md +1 -1
  6. package/skills/cell-selection/SKILL.md +1 -1
  7. package/skills/columns/SKILL.md +2 -2
  8. package/skills/data/SKILL.md +1 -1
  9. package/skills/editing/SKILL.md +58 -47
  10. package/skills/editing/references/common-mistakes.md +7 -6
  11. package/skills/editing/references/editing-api.md +30 -29
  12. package/skills/editing/references/editors-and-validation.md +1 -1
  13. package/skills/filtering/SKILL.md +1 -1
  14. package/skills/getting-started/SKILL.md +3 -3
  15. package/skills/grouping/SKILL.md +1 -1
  16. package/skills/options/SKILL.md +33 -3
  17. package/skills/rows/SKILL.md +1 -1
  18. package/skills/server-side/SKILL.md +1 -1
  19. package/skills/testing/SKILL.md +1 -1
  20. package/src/tmdatagrid/components/TMDataGrid.tsx +2 -2
  21. package/src/tmdatagrid/components/TMDataGridCellEditor.tsx +33 -34
  22. package/src/tmdatagrid/components/{TMDataGridEditActions.tsx → TMDataGridDraftActions.tsx} +28 -25
  23. package/src/tmdatagrid/components/TMDataGridEditColumn.tsx +40 -33
  24. package/src/tmdatagrid/components/TMDataGridEntryRows.tsx +6 -3
  25. package/src/tmdatagrid/components/TMDataGridTable.tsx +25 -5
  26. package/src/tmdatagrid/components/editors/editorShared.ts +1 -29
  27. package/src/tmdatagrid/core/capabilities.ts +14 -6
  28. package/src/tmdatagrid/core/controlledState.ts +179 -0
  29. package/src/tmdatagrid/core/editEngine.ts +247 -66
  30. package/src/tmdatagrid/core/labels.ts +3 -3
  31. package/src/tmdatagrid/index.ts +9 -7
  32. package/src/tmdatagrid/useTMDataGrid.tsx +183 -51
package/dist/index.d.ts CHANGED
@@ -12,9 +12,9 @@ import { RankingInfo } from "@tanstack/match-sorter-utils";
12
12
  */
13
13
  declare function TMDataGridColumnsPanel(): import("react").JSX.Element;
14
14
  //#endregion
15
- //#region .types-tmp/components/TMDataGridEditActions.d.ts
15
+ //#region .types-tmp/components/TMDataGridDraftActions.d.ts
16
16
  /** What the edit chrome is showing. */
17
- type TMDataGridEditActionsState = {
17
+ type TMDataGridDraftActionsState = {
18
18
  /**
19
19
  * Rows in the draft store, which is what Save sends: committed edits,
20
20
  * committed entry rows and deletion marks.
@@ -34,7 +34,7 @@ type TMDataGridEditActionsState = {
34
34
  isSubmitting: boolean;
35
35
  };
36
36
  /** What the edit chrome can do. */
37
- type TMDataGridEditActionsActions = {
37
+ type TMDataGridDraftActionsActions = {
38
38
  /** Saves the draft store. Open rows are left alone. */
39
39
  save: () => Promise<boolean>;
40
40
  /** Submits every open row, committing the ones that validate. */
@@ -43,7 +43,7 @@ type TMDataGridEditActionsActions = {
43
43
  discard: () => void;
44
44
  };
45
45
  /** The pre-bound pieces of the built-in edit chrome. */
46
- type TMDataGridEditActionsControls = {
46
+ type TMDataGridDraftActionsControls = {
47
47
  /** Save, with the draft count, disabled while the draft store is empty. */
48
48
  Save: () => ReactNode;
49
49
  /** Discard, disabled while nothing is pending. */
@@ -51,18 +51,18 @@ type TMDataGridEditActionsControls = {
51
51
  /** The "N rows still being edited" note, or nothing while there are none. */
52
52
  OpenRowsNote: () => ReactNode;
53
53
  };
54
- /** What {@link TMDataGridEditActionsProps.renderActions} is handed. */
55
- type TMDataGridEditActionsSlotArgs = {
56
- state: TMDataGridEditActionsState;
57
- actions: TMDataGridEditActionsActions;
58
- Controls: TMDataGridEditActionsControls;
54
+ /** What {@link TMDataGridDraftActionsProps.renderActions} is handed. */
55
+ type TMDataGridDraftActionsSlotArgs = {
56
+ state: TMDataGridDraftActionsState;
57
+ actions: TMDataGridDraftActionsActions;
58
+ Controls: TMDataGridDraftActionsControls;
59
59
  };
60
- type TMDataGridEditActionsProps = {
60
+ type TMDataGridDraftActionsProps = {
61
61
  /**
62
62
  * Replaces the built-in Save/Discard pair, and is handed the pieces of it.
63
63
  *
64
64
  * ```tsx
65
- * <TMDataGrid.EditActions
65
+ * <TMDataGrid.DraftActions
66
66
  * renderActions={({ state, Controls }) => (
67
67
  * <Group>
68
68
  * {state.draftCount > 0 && <Badge>{state.draftCount}</Badge>}
@@ -74,24 +74,27 @@ type TMDataGridEditActionsProps = {
74
74
  * />
75
75
  * ```
76
76
  */
77
- renderActions?: (args: TMDataGridEditActionsSlotArgs) => ReactNode;
77
+ renderActions?: (args: TMDataGridDraftActionsSlotArgs) => ReactNode;
78
78
  };
79
79
  /**
80
- * Draft mode's toolbar chrome: Save with the draft-store count, Discard, and
81
- * a note counting rows still open. Save sends the draft store and leaves open
82
- * rows alone, so it greys out while nothing is committed however much is
83
- * being typed - the note is what makes those rows visible. Works under any
84
- * `editing.mode` and renders nothing while editing is off.
80
+ * The draft store's toolbar chrome: Save with the store's count, Discard, and
81
+ * a note counting the rows still open. Save sends the store and leaves open
82
+ * rows alone, so it greys out while nothing is parked however much is being
83
+ * typed - the note is what makes those rows visible.
84
+ *
85
+ * Works under any `editing.mode`. The toolbar is declarative: the grid does
86
+ * not decide for you, so include this only when the grid runs a draft store -
87
+ * without `editing.draft` there is nothing to save and Save stays disabled.
85
88
  *
86
89
  * ```tsx
87
90
  * <TMDataGrid.Toolbar>
88
91
  * <TMDataGrid.SummaryCount />
89
92
  * <TMDataGrid.Spacer />
90
- * <TMDataGrid.EditActions />
93
+ * <TMDataGrid.DraftActions />
91
94
  * </TMDataGrid.Toolbar>
92
95
  * ```
93
96
  */
94
- declare function TMDataGridEditActions({ renderActions }?: TMDataGridEditActionsProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
97
+ declare function TMDataGridDraftActions({ renderActions }?: TMDataGridDraftActionsProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
95
98
  //#endregion
96
99
  //#region .types-tmp/components/TMDataGridFilterPanel.d.ts
97
100
  /**
@@ -277,10 +280,21 @@ declare function tmDataGridFilterFn<TFeatures extends TableFeatures, TData exten
277
280
  //#endregion
278
281
  //#region .types-tmp/core/editEngine.d.ts
279
282
  /**
280
- * How commits happen - one axis, each mode a thin policy over the same
281
- * engine. See `editMode` on `UseTMDataGridOptions`.
283
+ * What counts as a commit - one axis, each mode a thin policy over the same
284
+ * engine. Where a commit *goes* is the other axis, `editing.draft`: out to
285
+ * the consumer, or into the draft store. See `editing` on
286
+ * `UseTMDataGridOptions`.
287
+ *
288
+ * | Mode | Enter | Tab | Focus leaves | Escape |
289
+ * | ---- | ----- | --- | ------------ | ------ |
290
+ * | `"cell"` | commits | commits, caret moves on | commits | cancels |
291
+ * | `"cellConfirm"` | commits | keeps the draft, caret moves on | keeps the draft | cancels |
292
+ * | `"row"` | commits the row | the browser's, along the row | nothing | cancels the row |
293
+ *
294
+ * An entry row is row-shaped in every mode - every editable cell open at
295
+ * once, the browser's Tab between them, and an explicit ✓.
282
296
  */
283
- type TMDataGridEditMode = "cell" | "cellConfirm" | "row" | "draft";
297
+ type TMDataGridEditMode = "cell" | "cellConfirm" | "row";
284
298
  /**
285
299
  * One editing row's live form. TanStack Form's `FormApi`, not a wrapper: the
286
300
  * engine is a form library, and everything mid-edit - values, dirty state,
@@ -357,8 +371,20 @@ type TMDataGridEditCommitArgs<TData extends RowData> = {
357
371
  type TMDataGridEditRowProjection = {
358
372
  /** Field names whose value differs from the original. */
359
373
  dirtyFields: ReadonlyArray<string>;
360
- /** Field names carrying a validation error. */
374
+ /** Field names carrying a validation error, live or from a failed commit. */
361
375
  errorFields: ReadonlyArray<string>;
376
+ /**
377
+ * Those errors as text: what each cell editor is showing, plus what the
378
+ * row's last failed commit found. The second half is the reason this
379
+ * exists - Form clears a field's errors when its editor unmounts, so a row
380
+ * left invalid would go back to looking like an ordinary edited row. Such
381
+ * a message is dropped as soon as its field's value moves: the fix is what
382
+ * clears the mark.
383
+ */
384
+ errorMessages: ReadonlyArray<{
385
+ field: string;
386
+ message: string;
387
+ }>;
362
388
  /** A row-level error - a pathless `.refine()`, or a rejected commit. */
363
389
  hasRowError: boolean;
364
390
  isSubmitting: boolean;
@@ -398,22 +424,21 @@ type TMDataGridEditState = {
398
424
  * values stay in the row's form, this records which side of the line the
399
425
  * row is on. `begin` on one of these takes it back out, into form state.
400
426
  *
401
- * Only draft mode parks; the immediate modes send a commit straight to the
402
- * consumer and drop the form, so there this stays empty.
427
+ * Only `editing.draft` parks. Without it a commit goes straight to the
428
+ * consumer and the form is dropped, so this stays empty.
403
429
  */
404
430
  committedRowIds: ReadonlyArray<string>;
405
431
  /**
406
432
  * Rows being created, not yet in `data`. `committed` is the draft store's
407
433
  * add slice: the entry row passed its submit and renders as a value row
408
- * until `begin` re-opens it. Under the immediate modes a commit adds
409
- * through `onRowAdd` and the entry is dropped, so there it never turns
410
- * `true`.
434
+ * until `begin` re-opens it. Without `editing.draft` a commit adds through
435
+ * `onRowAdd` and the entry is dropped, so it never turns `true`.
411
436
  */
412
437
  newRows: ReadonlyArray<{
413
438
  tempId: string;
414
439
  committed: boolean;
415
440
  }>;
416
- /** The draft store's delete slice: rows marked deleted under draft mode. */
441
+ /** The draft store's delete slice: rows marked deleted, awaiting the save. */
417
442
  deletedRowIds: ReadonlyArray<string>;
418
443
  };
419
444
  type ErasedRow = Row<TMDataGridFeatures, TMDataGridRowData>;
@@ -523,7 +548,7 @@ type TMDataGridColumnEditOptions = {
523
548
  */
524
549
  mapValue?: TMDataGridEditValueMap;
525
550
  };
526
- /** A new row being committed - `onRowAdd`, and `submitAll`'s `added`. */
551
+ /** A new row being committed - `onRowAdd`, and `saveDrafts`'s `created`. */
527
552
  type TMDataGridRowAddArgs<TData extends RowData> = {
528
553
  /** The engine's placeholder id; the real id is the consumer's to mint. */
529
554
  tempId: string;
@@ -540,12 +565,39 @@ type TMDataGridRowDeleteArgs<TData extends RowData> = {
540
565
  * Rows still open (undecided form state) are not in here and stay open.
541
566
  */
542
567
  type TMDataGridSaveDraftsArgs<TData extends RowData> = {
543
- /** Every committed edit to an existing row. */
544
- rows: Array<TMDataGridEditCommitArgs<TData>>;
545
- /** Every committed new row from the entry block. */
546
- added: Array<TMDataGridRowAddArgs<TData>>;
568
+ /** Committed edits to existing rows; each entry carries its `rowId`. */
569
+ updated: Array<TMDataGridEditCommitArgs<TData>>;
570
+ /** Committed new rows from the entry block; each entry carries its `tempId`. */
571
+ created: Array<TMDataGridRowAddArgs<TData>>;
547
572
  /** Ids marked deleted while the drafts accumulated. */
548
573
  deleted: Array<string>;
574
+ /** @deprecated Renamed to {@link updated}. Removed in a later beta. */
575
+ rows: Array<TMDataGridEditCommitArgs<TData>>;
576
+ /** @deprecated Renamed to {@link created}. Removed in a later beta. */
577
+ added: Array<TMDataGridRowAddArgs<TData>>;
578
+ };
579
+ /**
580
+ * Which entries of one bucket saved. `true`, or an id the map does not name,
581
+ * saved and is dropped from the draft store; `false` failed and keeps its
582
+ * draft. A bare boolean answers for the whole bucket.
583
+ */
584
+ type TMDataGridSaveOutcomes = boolean | Record<string, boolean>;
585
+ /**
586
+ * What `onSaveDrafts` may return to save part of the store.
587
+ *
588
+ * Returning nothing saves everything, and throwing saves nothing. Between
589
+ * those, name the ids that failed: they keep their drafts, committed and
590
+ * ready for the next save, while the rest are dropped. The grid marks them
591
+ * with nothing beyond the state itself - a failed edit keeps `data-draft`,
592
+ * a failed deletion keeps `data-deleted` - so the display is the consumer's.
593
+ */
594
+ type TMDataGridSaveDraftsResult = {
595
+ /** Keyed by `rowId`. */
596
+ updated?: TMDataGridSaveOutcomes;
597
+ /** Keyed by `tempId`. */
598
+ created?: TMDataGridSaveOutcomes;
599
+ /** Keyed by `rowId`. */
600
+ deleted?: TMDataGridSaveOutcomes;
549
601
  };
550
602
  /**
551
603
  * @deprecated Renamed to {@link TMDataGridSaveDraftsArgs} - the payload is
@@ -638,10 +690,10 @@ type TMDataGridEditApi<TData extends RowData = TMDataGridRowData> = {
638
690
  cancelAll: () => void;
639
691
  /**
640
692
  * Submits every open row, as if each had been OK'd: a row that validates
641
- * commits (into the draft store under draft mode, straight to the consumer
642
- * under the immediate modes), a row that fails stays open with its errors.
643
- * `true` when every row committed. Sends nothing to the consumer by itself
644
- * under draft mode - that is `saveDrafts`.
693
+ * commits (into the draft store with `editing.draft` on, straight to the
694
+ * consumer without it), a row that fails stays open with its errors.
695
+ * `true` when every row committed. Under `editing.draft` it sends nothing
696
+ * to the consumer by itself - that is `saveDrafts`.
645
697
  */
646
698
  commitAll: () => Promise<boolean>;
647
699
  /**
@@ -665,8 +717,8 @@ type TMDataGridEditApi<TData extends RowData = TMDataGridRowData> = {
665
717
  * `newRowDefaults`. `values` overrides that seed key by key, so
666
718
  * `addRow()` opens a blank row and `addRow({ status: "draft" })` opens one
667
719
  * that starts filled in. Returns its temporary id - a form with no backing
668
- * row yet. Committing it calls `onRowAdd` (immediate modes) or joins
669
- * `submitAll`'s `added` (draft).
720
+ * row yet. Committing it calls `onRowAdd`, or parks it for `saveDrafts`
721
+ * under `editing.draft`.
670
722
  */
671
723
  addRow: (values?: Partial<TData>) => string;
672
724
  /**
@@ -675,17 +727,17 @@ type TMDataGridEditApi<TData extends RowData = TMDataGridRowData> = {
675
727
  * `newRowDefaults` exactly as `addRow` does.
676
728
  *
677
729
  * `commit: true` submits each row as it lands, which is what an import
678
- * wants: rows that validate commit (parked in the draft store under draft
679
- * mode, added through `onRowAdd` under the immediate modes - once per row),
730
+ * wants: rows that validate commit (parked in the draft store under
731
+ * `editing.draft`, added through `onRowAdd` without it - once per row),
680
732
  * and rows that fail stay open in the entry block carrying their errors,
681
733
  * for the user to fix. The result says which went which way.
682
734
  */
683
735
  addRows: (rows: ReadonlyArray<Partial<TData>>, options?: TMDataGridAddRowsOptions) => Promise<TMDataGridAddRowsResult>;
684
736
  /**
685
- * Deletes a row: `onRowDelete` straight away under the immediate modes;
686
- * under draft it toggles the id in `deletedRowIds` - the row renders
687
- * struck through until `submitAll` reports it. On an uncommitted entry
688
- * row it just discards the entry.
737
+ * Deletes a row: `onRowDelete` straight away, or under `editing.draft` a
738
+ * toggle of the id in `deletedRowIds` - the row renders struck through
739
+ * until `saveDrafts` reports it. On an uncommitted entry row it just
740
+ * discards the entry.
689
741
  */
690
742
  deleteRow: (rowId: string) => void;
691
743
  /** Whether delete chrome makes sense - the lane's trash gate. */
@@ -794,12 +846,12 @@ type TMDataGridLabels = {
794
846
  cancelRowEdit: string;
795
847
  /** Save tooltip when field errors block the row, with no row message. */
796
848
  editRowErrors: string;
797
- /** `EditActions`' Save, with the count of rows in the draft store. */
849
+ /** `DraftActions`' Save, with the count of rows in the draft store. */
798
850
  saveAllEdits: (rows: number) => string;
799
- /** `EditActions`' Discard. */
851
+ /** `DraftActions`' Discard. */
800
852
  discardAllEdits: string;
801
853
  /**
802
- * `EditActions`' note about rows still open - edited but not committed, so
854
+ * `DraftActions`' note about rows still open - edited but not committed, so
803
855
  * not part of the save. Shown only while there are any.
804
856
  */
805
857
  editRowsStillOpen: (rows: number) => string;
@@ -1101,13 +1153,20 @@ type TMDataGridFeatureFlags = {
1101
1153
  grouping: boolean;
1102
1154
  /** Whether cells can be edited at all - the `editing` option was set. */
1103
1155
  editing: boolean;
1104
- /** The commit policy, or `null` while editing is off. */
1156
+ /** What counts as a commit, or `null` while editing is off. */
1105
1157
  editMode: TMDataGridEditMode | null;
1106
1158
  /**
1107
- * Whether a confirmed entry row stays pinned in the sticky entry block
1108
- * until Save all - `editing.newRowsSticky`, draft mode only. Off by
1109
- * default: a confirmed row joins the scrolling flow instead, so entering
1110
- * many rows cannot fill the viewport with sticky chrome.
1159
+ * Where a commit goes - `editing.draft`. On, commits park in the grid's
1160
+ * draft store and leave through `edit.saveDrafts()`; off, each one reaches
1161
+ * the consumer as it happens.
1162
+ */
1163
+ editDraft: boolean;
1164
+ /**
1165
+ * Whether a parked entry row stays pinned in the sticky entry block until
1166
+ * the draft store is saved - `editing.newRowsSticky`, which needs
1167
+ * `editing.draft`. Off by default: a parked row joins the scrolling flow
1168
+ * instead, so entering many rows cannot fill the viewport with sticky
1169
+ * chrome.
1111
1170
  */
1112
1171
  editNewRowsSticky: boolean;
1113
1172
  /** The generated row-number gutter - `enableRowNumbers`. Off by default. */
@@ -1724,35 +1783,43 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
1724
1783
  */
1725
1784
  newRowDefaults?: TData | (() => TData);
1726
1785
  /**
1727
- * Called when an entry row commits: `Enter` or the lane's ✓ under the
1728
- * immediate modes, `submitAll` under draft. Create the record and let it
1729
- * arrive back through `data`; the engine's `tempId` never leaves the grid.
1786
+ * Called when an entry row commits: `Enter` or the lane's ✓, or
1787
+ * `saveDrafts` under `editing.draft`. Create the record and let it arrive
1788
+ * back through `data`; the engine's `tempId` never leaves the grid.
1730
1789
  */
1731
1790
  onRowAdd?: (args: TMDataGridRowAddArgs<TData>) => void | Promise<void>;
1732
1791
  /**
1733
- * Called by `edit.deleteRow` under the immediate modes - confirmation, if
1734
- * any, belongs in here. Under draft, deletions accumulate in
1735
- * `edit.state.deletedRowIds` instead and are reported by `submitAll`.
1736
- * Setting this also puts the trash can in the edit lane.
1792
+ * Called by `edit.deleteRow` - confirmation, if any, belongs in here. Under
1793
+ * `editing.draft` deletions accumulate in `edit.state.deletedRowIds`
1794
+ * instead and are reported by `saveDrafts`. Setting this also puts the
1795
+ * trash can in the edit lane.
1737
1796
  */
1738
1797
  onRowDelete?: (args: TMDataGridRowDeleteArgs<TData>) => void | Promise<void>;
1739
1798
  };
1740
1799
  /**
1741
1800
  * The `editing` option: one object that turns editing on and holds
1742
- * everything about it. `mode` picks what counts as a commit and which
1743
- * controls trigger it; the other members act within that mode.
1801
+ * everything about it. Two axes, and they are independent: `mode` picks what
1802
+ * counts as a commit, `draft` picks where that commit goes.
1803
+ *
1804
+ * | Mode | Commit | Cancel | Controls |
1805
+ * | ---- | ------ | ------ | -------- |
1806
+ * | `"cell"` | Enter, Tab, blur - Sheets | Escape | none |
1807
+ * | `"cellConfirm"` | ✓ or Enter; Tab and blur keep the draft | ✕ or Escape | ✓ / ✕ beside the input |
1808
+ * | `"row"` | Save in the edit lane, or Enter | Cancel, or Escape | generated edit lane |
1809
+ *
1810
+ * | `draft` | Where a commit goes |
1811
+ * | ------- | ------------------- |
1812
+ * | `false` (default) | Out as it happens - `onCommit`, `onRowAdd`, `onRowDelete` |
1813
+ * | `true` | Into the grid's draft store; `edit.saveDrafts()` sends the lot |
1744
1814
  *
1745
- * | Mode | Commit | Cancel |
1746
- * | ---- | ------ | ------ |
1747
- * | `"cell"` | Enter, Tab, blur - Sheets | Escape |
1748
- * | `"cellConfirm"` | ✓ or Enter only; blur keeps the draft | ✕ or Escape |
1749
- * | `"row"` | Save in the edit lane, or Ctrl+Enter | Cancel, or Escape |
1750
- * | `"draft"` | `edit.commit(rowId)` into the draft store, `edit.saveDrafts()` out | `edit.cancelAll()` |
1815
+ * So `{ mode: "row", draft: true }` is "edit a row, the lane's ✓ parks it,
1816
+ * the toolbar's Save sends every parked row at once", and
1817
+ * `{ mode: "cell", draft: true }` is the same store filled cell by cell.
1751
1818
  *
1752
1819
  * Setting `editing` makes `getRowId` required - drafts are keyed by row id,
1753
1820
  * and the index fallback would name a different record after any sort - and
1754
- * `onSaveDrafts` exists only under `mode: "draft"`, the one mode with a draft
1755
- * store to save.
1821
+ * `onSaveDrafts` exists only under `draft: true`, the one configuration with
1822
+ * a draft store to save.
1756
1823
  *
1757
1824
  * The object may be written inline: the callbacks are read through a ref
1758
1825
  * every render, so its identity does not matter.
@@ -1763,40 +1830,52 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
1763
1830
  * built-in editor, and `enabled`, `field`, `editor`, `validate` and `mapValue`
1764
1831
  * override the rest.
1765
1832
  */
1766
- type TMDataGridEditingOptions<TData extends RowData> = TMDataGridEditingCallbacks<TData> & ({
1767
- mode: "draft";
1833
+ type TMDataGridEditingOptions<TData extends RowData> = TMDataGridEditingCallbacks<TData> & {
1834
+ /** What counts as a commit. See the table above. */
1835
+ mode: TMDataGridEditMode;
1836
+ } & ({
1837
+ /**
1838
+ * Commits park in the grid's draft store instead of reaching the
1839
+ * consumer, and leave together through `edit.saveDrafts()`. The
1840
+ * edit lane gains the change markers and the per-row revert, the
1841
+ * trash marks a row for deletion rather than deleting it, and
1842
+ * `TMDataGrid.DraftActions` gets something to save.
1843
+ */
1844
+ draft: true;
1768
1845
  /**
1769
- * Draft mode's save: called once by `edit.saveDrafts()` with the
1846
+ * The bulk save: called once by `edit.saveDrafts()` with the
1770
1847
  * whole draft store - committed edits, added rows and deletion
1771
1848
  * marks - so a server can apply it as one transaction. Without it,
1772
1849
  * `saveDrafts` falls back to the per-row
1773
1850
  * {@link TMDataGridEditingCallbacks.onCommit} loop.
1774
1851
  *
1775
- * Rows still open are not in the payload and stay open; a rejection
1776
- * keeps every draft.
1852
+ * Rows still open are not in the payload and stay open. Returning
1853
+ * nothing saves the whole store and throwing saves none of it;
1854
+ * return a {@link TMDataGridSaveDraftsResult} to save part of it.
1777
1855
  */
1778
- onSaveDrafts?: (args: TMDataGridSaveDraftsArgs<TData>) => void | Promise<void>;
1856
+ onSaveDrafts?: (args: TMDataGridSaveDraftsArgs<TData>) => void | TMDataGridSaveDraftsResult | Promise<void | TMDataGridSaveDraftsResult>;
1779
1857
  /**
1780
1858
  * @deprecated Renamed to {@link onSaveDrafts} - it fires when the
1781
1859
  * draft store is saved, not when a row commits into it. Still
1782
1860
  * honoured; removed in a later beta.
1783
1861
  */
1784
- onCommitDrafts?: (args: TMDataGridSaveDraftsArgs<TData>) => void | Promise<void>;
1862
+ onCommitDrafts?: (args: TMDataGridSaveDraftsArgs<TData>) => void | TMDataGridSaveDraftsResult | Promise<void | TMDataGridSaveDraftsResult>;
1785
1863
  /**
1786
- * Keep committed entry rows pinned in the sticky entry block until
1787
- * the draft store is saved. Off by default: a committed row joins
1788
- * the scrolling flow above the body rows instead - the block a row
1789
- * is *typed* into is always sticky, but committed rows scroll, so
1790
- * committing many cannot fill the viewport with sticky chrome.
1864
+ * Keep parked entry rows pinned in the sticky entry block until
1865
+ * the draft store is saved. Off by default: a parked row joins the
1866
+ * scrolling flow above the body rows instead - the block a row is
1867
+ * *typed* into is always sticky, but parked rows scroll, so
1868
+ * entering many cannot fill the viewport with sticky chrome.
1791
1869
  */
1792
1870
  newRowsSticky?: boolean;
1793
1871
  } | {
1794
- mode: Exclude<TMDataGridEditMode, "draft">;
1795
- /** Only `"draft"` has a draft store to save - see the other branch. */
1872
+ /** Every commit reaches the consumer as it happens. The default. */
1873
+ draft?: false;
1874
+ /** Only `draft: true` has a store to save - see the other branch. */
1796
1875
  onSaveDrafts?: never;
1797
1876
  /** @deprecated See {@link onSaveDrafts}. */
1798
1877
  onCommitDrafts?: never;
1799
- /** Committed entry rows exist only under `"draft"` - see there. */
1878
+ /** Parked entry rows exist only under `draft: true` - see there. */
1800
1879
  newRowsSticky?: never;
1801
1880
  });
1802
1881
  type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridFeatures, TData>, "features"> & ({
@@ -2732,7 +2811,7 @@ declare const TMDataGrid: typeof TMDataGridRoot & {
2732
2811
  SummaryCount: typeof TMDataGridSummaryCount;
2733
2812
  LoadingIndicator: typeof TMDataGridLoadingIndicator;
2734
2813
  Search: typeof TMDataGridSearch;
2735
- EditActions: typeof TMDataGridEditActions;
2814
+ DraftActions: typeof TMDataGridDraftActions;
2736
2815
  ColumnsButton: typeof TMDataGridColumnsButton;
2737
2816
  FilterButton: typeof TMDataGridFilterButton;
2738
2817
  Table: typeof TMDataGridTable$1;
@@ -3215,4 +3294,4 @@ declare function getSelectableRowIds<TData extends RowData>(row: Row<TMDataGridF
3215
3294
  */
3216
3295
  declare function resolveRowSelectionClick<TData extends RowData>({ rows, rowId, anchorRowId, modifiers, selection, canReplaceSelection }: ResolveRowSelectionClickArgs<TData>): ResolvedRowSelection;
3217
3296
  //#endregion
3218
- export { type BuildCellMatrixArgs, type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_CELL_EXPORT_OPTIONS, DEFAULT_TMDATAGRID_SIZE, DETAILS_COLUMN_ID, DgAutocompleteFilter, DgDateRangeFilter, DgRangeSliderFilter, DgTriStateFilter, EDIT_COLUMN_ID, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, PERSIST_PAYLOAD_VERSION, ROW_NUMBER_COLUMN_ID, type ResolveCellMoveArgs, type ResolveRangeBoundsArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, TMDataGrid, type TMDataGridAddRowsOptions, type TMDataGridAddRowsResult, type TMDataGridAggregationName, type TMDataGridApi, TMDataGridBooleanEditor, type TMDataGridCapabilities, type TMDataGridCellCoords, type TMDataGridCellEventArgs, type TMDataGridCellExportOptions, type TMDataGridCellMatrix, type TMDataGridCellNav, type TMDataGridCellPosition, type TMDataGridCellRange, type TMDataGridCellSelectionMode, type TMDataGridColumnCapabilities, type TMDataGridColumnEditOptions, type TMDataGridColumnFilterOptions, type TMDataGridColumnLayout, type TMDataGridColumnMenuItemsArgs, type TMDataGridColumnMenuItemsRenderer, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnType, type TMDataGridContextValue, type TMDataGridDataSlice, TMDataGridDateEditor, type TMDataGridDetailsArgs, type TMDataGridDetailsRenderer, type TMDataGridDropSide, TMDataGridEditActions, type TMDataGridEditActionsActions, type TMDataGridEditActionsControls, type TMDataGridEditActionsProps, type TMDataGridEditActionsSlotArgs, type TMDataGridEditActionsState, type TMDataGridEditApi, type TMDataGridEditChange, type TMDataGridEditCommitArgs, type TMDataGridEditCommitDraftsArgs, type TMDataGridEditField, type TMDataGridEditMode, type TMDataGridEditRowProjection, type TMDataGridEditState, type TMDataGridEditValueMap, type TMDataGridEditValueMapArgs, type TMDataGridEditingOptions, type TMDataGridEditorArgs, type TMDataGridEditorComponent, type TMDataGridExpandAllArgs, type TMDataGridExpandTarget, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFieldValidate, type TMDataGridFilterControlArgs, type TMDataGridFilterControlComponent, type TMDataGridFilterOperator, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterValue, TMDataGridFilterValueInput, type TMDataGridFooterProps, type TMDataGridLabels, type TMDataGridLabelsOverride, TMDataGridMultiSelectEditor, TMDataGridNumberEditor, type TMDataGridOption, type TMDataGridOptionsArgs, type TMDataGridOptionsSource, type TMDataGridPaginationActions, type TMDataGridPaginationApi, type TMDataGridPaginationControls, type TMDataGridPaginationSlotArgs, type TMDataGridPaginationState, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridQuickSearchMode, type TMDataGridRangeBounds, type TMDataGridRowAddArgs, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenuArgs, type TMDataGridRowContextMenuRenderer, type TMDataGridRowData, type TMDataGridRowDeleteArgs, type TMDataGridRowEditForm, type TMDataGridRowStyle, type TMDataGridRowValidators, type TMDataGridSaveDraftsArgs, type TMDataGridScrollAlign, type TMDataGridScrollToRowArgs, TMDataGridSearch, type TMDataGridSearchProps, TMDataGridSelectEditor, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, TMDataGridStringEditor, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, aggregateColumn, areAllRowsExpanded, autosizeColumn, boundsCellCount, boundsEdges, buildCellMatrix, buildGridCellMatrix, clearedValueForType, createTMDataGridColumnHelper, downloadTextFile, emptyValueForOperator, exportGridToCsv, formatExportValue, formatFilterLabel, formatGroupValue, fuzzyGlobalFilterFn, getColumnCapabilities, getColumnDefaultOperator, getColumnFilterControl, getColumnLabel, getColumnRegion, getColumnType, getDefaultOperator, getDisplayedRows, getEditFieldName, getGridCapabilities, getGroupDataRows, getOperatorsForType, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, isColumnEditableForRow, isColumnReorderable, isControlColumn, isFilterActive, isGeneratedColumn, isPagingActive, isSameCell, isWithinBounds, keepGeneratedColumnsOutermost, measureColumnContentWidth, mergeLabels, moveColumn, moveColumnByStep, normalizeFieldValidate, openColumnFilter, operatorNeedsValue, operatorTakesArrayValue, operatorTakesRangeValue, optionsToComboboxData, readFeatureFlags, resolveCellMove, resolveColumnOptions, resolveExpandAll, resolveRangeBounds, resolveRowSelectionClick, tmDataGridFeatures, toClipboardText, toExcelCsv, useCellControlTabIndex, useTMDataGrid, useTMDataGridContext, writeClipboardText };
3297
+ export { type BuildCellMatrixArgs, type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_CELL_EXPORT_OPTIONS, DEFAULT_TMDATAGRID_SIZE, DETAILS_COLUMN_ID, DgAutocompleteFilter, DgDateRangeFilter, DgRangeSliderFilter, DgTriStateFilter, EDIT_COLUMN_ID, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, PERSIST_PAYLOAD_VERSION, ROW_NUMBER_COLUMN_ID, type ResolveCellMoveArgs, type ResolveRangeBoundsArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, TMDataGrid, type TMDataGridAddRowsOptions, type TMDataGridAddRowsResult, type TMDataGridAggregationName, type TMDataGridApi, TMDataGridBooleanEditor, type TMDataGridCapabilities, type TMDataGridCellCoords, type TMDataGridCellEventArgs, type TMDataGridCellExportOptions, type TMDataGridCellMatrix, type TMDataGridCellNav, type TMDataGridCellPosition, type TMDataGridCellRange, type TMDataGridCellSelectionMode, type TMDataGridColumnCapabilities, type TMDataGridColumnEditOptions, type TMDataGridColumnFilterOptions, type TMDataGridColumnLayout, type TMDataGridColumnMenuItemsArgs, type TMDataGridColumnMenuItemsRenderer, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnType, type TMDataGridContextValue, type TMDataGridDataSlice, TMDataGridDateEditor, type TMDataGridDetailsArgs, type TMDataGridDetailsRenderer, TMDataGridDraftActions, type TMDataGridDraftActionsActions, type TMDataGridDraftActionsControls, type TMDataGridDraftActionsProps, type TMDataGridDraftActionsSlotArgs, type TMDataGridDraftActionsState, type TMDataGridDropSide, type TMDataGridEditApi, type TMDataGridEditChange, type TMDataGridEditCommitArgs, type TMDataGridEditCommitDraftsArgs, type TMDataGridEditField, type TMDataGridEditMode, type TMDataGridEditRowProjection, type TMDataGridEditState, type TMDataGridEditValueMap, type TMDataGridEditValueMapArgs, type TMDataGridEditingOptions, type TMDataGridEditorArgs, type TMDataGridEditorComponent, type TMDataGridExpandAllArgs, type TMDataGridExpandTarget, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFieldValidate, type TMDataGridFilterControlArgs, type TMDataGridFilterControlComponent, type TMDataGridFilterOperator, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterValue, TMDataGridFilterValueInput, type TMDataGridFooterProps, type TMDataGridLabels, type TMDataGridLabelsOverride, TMDataGridMultiSelectEditor, TMDataGridNumberEditor, type TMDataGridOption, type TMDataGridOptionsArgs, type TMDataGridOptionsSource, type TMDataGridPaginationActions, type TMDataGridPaginationApi, type TMDataGridPaginationControls, type TMDataGridPaginationSlotArgs, type TMDataGridPaginationState, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridQuickSearchMode, type TMDataGridRangeBounds, type TMDataGridRowAddArgs, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenuArgs, type TMDataGridRowContextMenuRenderer, type TMDataGridRowData, type TMDataGridRowDeleteArgs, type TMDataGridRowEditForm, type TMDataGridRowStyle, type TMDataGridRowValidators, type TMDataGridSaveDraftsArgs, type TMDataGridSaveDraftsResult, type TMDataGridSaveOutcomes, type TMDataGridScrollAlign, type TMDataGridScrollToRowArgs, TMDataGridSearch, type TMDataGridSearchProps, TMDataGridSelectEditor, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, TMDataGridStringEditor, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, aggregateColumn, areAllRowsExpanded, autosizeColumn, boundsCellCount, boundsEdges, buildCellMatrix, buildGridCellMatrix, clearedValueForType, createTMDataGridColumnHelper, downloadTextFile, emptyValueForOperator, exportGridToCsv, formatExportValue, formatFilterLabel, formatGroupValue, fuzzyGlobalFilterFn, getColumnCapabilities, getColumnDefaultOperator, getColumnFilterControl, getColumnLabel, getColumnRegion, getColumnType, getDefaultOperator, getDisplayedRows, getEditFieldName, getGridCapabilities, getGroupDataRows, getOperatorsForType, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, isColumnEditableForRow, isColumnReorderable, isControlColumn, isFilterActive, isGeneratedColumn, isPagingActive, isSameCell, isWithinBounds, keepGeneratedColumnsOutermost, measureColumnContentWidth, mergeLabels, moveColumn, moveColumnByStep, normalizeFieldValidate, openColumnFilter, operatorNeedsValue, operatorTakesArrayValue, operatorTakesRangeValue, optionsToComboboxData, readFeatureFlags, resolveCellMove, resolveColumnOptions, resolveExpandAll, resolveRangeBounds, resolveRowSelectionClick, tmDataGridFeatures, toClipboardText, toExcelCsv, useCellControlTabIndex, useTMDataGrid, useTMDataGridContext, writeClipboardText };