@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.4

package/src/tmdatagrid/core/labels.ts

@@ -111,10 +111,15 @@ export type TMDataGridLabels = {
   cancelRowEdit: string;
   /** Save tooltip when field errors block the row, with no row message. */
   editRowErrors: string;
-  /** `EditActions`' Save, with the dirty-row count. */
+  /** `EditActions`' Save, with the count of rows in the draft store. */
   saveAllEdits: (rows: number) => string;
   /** `EditActions`' Discard. */
   discardAllEdits: string;
+  /**
+   * `EditActions`' note about rows still open - edited but not committed, so
+   * not part of the save. Shown only while there are any.
+   */
+  editRowsStillOpen: (rows: number) => string;
   /** The entry row's ✓ - commit the add. */
   confirmNewRow: string;
   /** The entry row's ✕ - drop the entry. */
@@ -243,6 +248,8 @@ export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
   editRowErrors: "Fix the marked cells",
   saveAllEdits: (rows) => (rows === 1 ? "Save 1 row" : `Save ${rows} rows`),
   discardAllEdits: "Discard",
+  editRowsStillOpen: (rows) =>
+    rows === 1 ? "1 row still being edited" : `${rows} rows still being edited`,
   confirmNewRow: "Add row",
   discardNewRow: "Discard new row",
   deleteRow: "Delete row",

package/src/tmdatagrid/core/labelsSv.ts

@@ -103,6 +103,8 @@ export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
   editRowErrors: "Åtgärda de markerade cellerna",
   saveAllEdits: (rows) => (rows === 1 ? "Spara 1 rad" : `Spara ${rows} rader`),
   discardAllEdits: "Förkasta",
+  editRowsStillOpen: (rows) =>
+    rows === 1 ? "1 rad redigeras fortfarande" : `${rows} rader redigeras fortfarande`,
   confirmNewRow: "Lägg till rad",
   discardNewRow: "Släng ny rad",
   deleteRow: "Ta bort rad",

package/src/tmdatagrid/index.ts

@@ -82,7 +82,12 @@ export {
   type TMDataGridEditApi,
   type TMDataGridEditChange,
   type TMDataGridEditCommitArgs,
+  type TMDataGridSaveDraftsArgs,
+  type TMDataGridSaveDraftsResult,
+  type TMDataGridSaveOutcomes,
   type TMDataGridEditCommitDraftsArgs,
+  type TMDataGridAddRowsOptions,
+  type TMDataGridAddRowsResult,
   type TMDataGridEditField,
   type TMDataGridEditMode,
   type TMDataGridEditorArgs,

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -51,7 +51,8 @@ import {
   createEditEngine,
   type TMDataGridEditApi,
   type TMDataGridEditCommitArgs,
-  type TMDataGridEditCommitDraftsArgs,
+  type TMDataGridSaveDraftsArgs,
+  type TMDataGridSaveDraftsResult,
   type TMDataGridEditEngineContext,
   type TMDataGridColumnEditOptions,
   type TMDataGridEditMode,
@@ -93,6 +94,11 @@ import {
   isSameCell,
   type TMDataGridCellPosition,
 } from "./core/cellNavigation";
+import {
+  findFrozenStateSlices,
+  stabilizeControlledState,
+  withoutUndefinedSlices,
+} from "./core/controlledState";
 import type { TMDataGridCellRange } from "./core/cellRange";
 import {
   createSelectColumn,
@@ -390,7 +396,7 @@ export type TMDataGridApi<TData extends RowData> = {
    * 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.
    */
-  edit: TMDataGridEditApi;
+  edit: TMDataGridEditApi<TData>;
   /** Table-level feature switches, re-read from options on every render. */
   features: TMDataGridFeatureFlags;
   /** Every string the chrome renders, `labels` merged over the English defaults. */
@@ -471,6 +477,7 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
   /**
    * Seed values for `edit.addRow()` - the entry row's starting point. A
    * function is called per added row (fresh timestamps, empty arrays).
+   * `edit.addRow(values)` overrides this key by key for that one row.
    */
   newRowDefaults?: TData | (() => TData);
   /**
@@ -498,12 +505,12 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * | `"cell"` | Enter, Tab, blur - Sheets | Escape |
  * | `"cellConfirm"` | ✓ or Enter only; blur keeps the draft | ✕ or Escape |
  * | `"row"` | Save in the edit lane, or Ctrl+Enter | Cancel, or Escape |
- * | `"draft"` | `edit.submitAll()` | `edit.cancelAll()` |
+ * | `"draft"` | `edit.commit(rowId)` into the draft store, `edit.saveDrafts()` out | `edit.cancelAll()` |
  *
  * Setting `editing` makes `getRowId` required - drafts are keyed by row id,
  * and the index fallback would name a different record after any sort - and
- * `onCommitDrafts` exists only under `mode: "draft"`, the one mode whose
- * `submitAll` calls it.
+ * `onSaveDrafts` exists only under `mode: "draft"`, the one mode with a draft
+ * store to save.
  *
  * The object may be written inline: the callbacks are read through a ref
  * every render, so its identity does not matter.
@@ -520,28 +527,49 @@ export type TMDataGridEditingOptions<TData extends RowData> =
       | {
           mode: "draft";
           /**
-           * Draft mode's save, called once by `edit.submitAll()` with every
-           * valid dirty row. Without it, `submitAll` falls back to the per-row
-           * {@link TMDataGridEditingCallbacks.onCommit} loop. Rows failing
-           * validation stay open either way; a rejection keeps every draft.
+           * Draft mode's save: called once by `edit.saveDrafts()` with the
+           * whole draft store - committed edits, added rows and deletion
+           * marks - so a server can apply it as one transaction. Without it,
+           * `saveDrafts` falls back to the per-row
+           * {@link TMDataGridEditingCallbacks.onCommit} loop.
+           *
+           * Rows still open are not in the payload and stay open. Returning
+           * nothing saves the whole store and throwing saves none of it;
+           * return a {@link TMDataGridSaveDraftsResult} to save part of it.
+           */
+          onSaveDrafts?: (
+            args: TMDataGridSaveDraftsArgs<TData>,
+          ) =>
+            | void
+            | TMDataGridSaveDraftsResult
+            | Promise<void | TMDataGridSaveDraftsResult>;
+          /**
+           * @deprecated Renamed to {@link onSaveDrafts} - it fires when the
+           * draft store is saved, not when a row commits into it. Still
+           * honoured; removed in a later beta.
            */
           onCommitDrafts?: (
-            args: TMDataGridEditCommitDraftsArgs<TData>,
-          ) => void | Promise<void>;
+            args: TMDataGridSaveDraftsArgs<TData>,
+          ) =>
+            | void
+            | TMDataGridSaveDraftsResult
+            | Promise<void | TMDataGridSaveDraftsResult>;
           /**
-           * Keep confirmed entry rows pinned in the sticky entry block until
-           * Save all. Off by default: a confirmed row joins the scrolling
-           * flow above the body rows instead - the block a row is *typed*
-           * into is always sticky, but entered rows scroll, so entering many
-           * cannot fill the viewport with sticky chrome.
+           * Keep committed entry rows pinned in the sticky entry block until
+           * the draft store is saved. Off by default: a committed row joins
+           * the scrolling flow above the body rows instead - the block a row
+           * is *typed* into is always sticky, but committed rows scroll, so
+           * committing many cannot fill the viewport with sticky chrome.
            */
           newRowsSticky?: boolean;
         }
       | {
           mode: Exclude<TMDataGridEditMode, "draft">;
-          /** Only `"draft"`'s `submitAll` ever calls it - see the other branch. */
+          /** Only `"draft"` has a draft store to save - see the other branch. */
+          onSaveDrafts?: never;
+          /** @deprecated See {@link onSaveDrafts}. */
           onCommitDrafts?: never;
-          /** Confirmed entry rows exist only under `"draft"` - see there. */
+          /** Committed entry rows exist only under `"draft"` - see there. */
           newRowsSticky?: never;
         }
     );
@@ -1004,6 +1032,58 @@ export function useTMDataGrid<TData extends RowData>({
   const initialGrouping =
     persistedState.grouping ?? options.initialState?.grouping ?? [];
 
+  // Current grouping state, feeding the tree column's entry in a controlled
+  // `columnVisibility` (below). A ref, not state: it is only read while
+  // building the options, and the store change that updates it re-renders the
+  // hook anyway. A controlled `grouping` takes precedence over the persisted
+  // one; grouping held in an external atom is not readable here and is
+  // corrected by the effect below with one extra write on mount.
+  const groupingActiveRef = useRef(
+    (options.state?.grouping ?? initialGrouping).length > 0,
+  );
+
+  // Removes keys set to `undefined` before TanStack writes them into the
+  // slice atoms; such a key means the slice is not controlled.
+  const consumerState = withoutUndefinedSlices(options.state);
+
+  // A controlled `columnVisibility` replaces the whole map on every options
+  // sync, including the grid's own entries, so the tree column's entry must be
+  // re-applied here. Entries for the control columns are removed, as they are
+  // for `initialState`: their visibility follows the feature options, not the
+  // visibility map.
+  const controlledColumnVisibility = consumerState?.columnVisibility;
+  const requestedState =
+    consumerState !== undefined && controlledColumnVisibility !== undefined
+      ? {
+          ...consumerState,
+          columnVisibility: {
+            ...withoutControlColumnVisibility(controlledColumnVisibility),
+            ...(groupColumnEnabled
+              ? { [GROUP_COLUMN_ID]: groupingActiveRef.current }
+              : {}),
+          },
+        }
+      : consumerState;
+
+  // Controlled state is synced to the table on every render and compared by
+  // identity, so a `state` object built in the consumer's render body would
+  // cause an infinite render loop. Unchanged slices are forwarded with the
+  // previous render's identity instead - see controlledState.ts.
+  const controlledStateRef = useRef<Partial<TableState<TMDataGridFeatures>>>(
+    undefined,
+  );
+  // Exception: the grouping workaround below republishes `columnOrder` and
+  // `columnVisibility` with unchanged contents and a new identity to repair
+  // table-core's missing memo deps - the exact write stabilization cancels.
+  // After it runs, one render forwards the controlled state unstabilized so
+  // the new identities reach the atoms. A single render cannot loop.
+  const republishControlledStateRef = useRef(false);
+  const controlledState = republishControlledStateRef.current
+    ? requestedState
+    : stabilizeControlledState(requestedState, controlledStateRef.current);
+  republishControlledStateRef.current = false;
+  controlledStateRef.current = controlledState;
+
   const table = useTable({
     columnResizeMode: "onChange",
     enableSorting: true,
@@ -1042,6 +1122,8 @@ export function useTMDataGrid<TData extends RowData>({
         : options.enableRowPinning === true),
     features: tmDataGridFeatures,
     columns: columns as TableOptions<TMDataGridFeatures, TData>["columns"],
+    // The stabilized controlled state; `undefined` when nothing is controlled.
+    state: controlledState,
     initialState: {
       ...options.initialState,
       ...persistedState,
@@ -1109,16 +1191,22 @@ export function useTMDataGrid<TData extends RowData>({
       editing?.isRowEditable as TMDataGridEditEngineContext["isRowEditable"],
     onEditCommit:
       editing?.onCommit as TMDataGridEditEngineContext["onEditCommit"],
-    onEditCommitDrafts:
-      editing?.onCommitDrafts as TMDataGridEditEngineContext["onEditCommitDrafts"],
+    // The deprecated name still works; the new one wins if both are set.
+    onSaveDrafts: (editing?.onSaveDrafts ??
+      editing?.onCommitDrafts) as TMDataGridEditEngineContext["onSaveDrafts"],
     newRowDefaults:
       editing?.newRowDefaults as TMDataGridEditEngineContext["newRowDefaults"],
     onRowAdd: editing?.onRowAdd as TMDataGridEditEngineContext["onRowAdd"],
     onRowDelete:
       editing?.onRowDelete as TMDataGridEditEngineContext["onRowDelete"],
   };
-  const [edit] = useState(() =>
-    createEditEngine(() => editContextRef.current),
+  // The engine is erased; the row type comes back on the way out, which is
+  // what makes `edit.addRow(values)` check against `TData`.
+  const [edit] = useState(
+    () =>
+      createEditEngine(
+        () => editContextRef.current,
+      ) as unknown as TMDataGridEditApi<TData>,
   );
 
   // Switching modes mid-flight drops every draft: the policies disagree about
@@ -1143,6 +1231,20 @@ export function useTMDataGrid<TData extends RowData>({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // A controlled slice without its `onXChange` cannot change: TanStack routes
+  // every write through the callback, and the next options sync restores the
+  // consumer's value. Warned once in development; `initialState` is the option
+  // for a starting value.
+  useEffect(() => {
+    for (const { slice, handler } of findFrozenStateSlices(options)) {
+      console.warn(
+        `TMDataGrid: state.${slice} is controlled but no ${handler} was passed - the slice cannot change. Add ${handler}, or use initialState.${slice} for a starting value.`,
+      );
+    }
+    // A mount-time contract, like the check above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // Two things have to happen whenever `grouping` changes.
   //
   // One: the tree column appears with the first grouped column and goes away
@@ -1182,10 +1284,40 @@ export function useTMDataGrid<TData extends RowData>({
   useEffect(() => {
     if (!groupColumnEnabled) return;
     let previousGrouping = table.store.state.grouping;
+    // Update the ref before any write: it feeds the visibility injection
+    // above, and a write below re-renders the hook. With a stale ref the
+    // injection would restore the old value on every render. This also
+    // corrects the mount value when an external atom owns `grouping`, which
+    // the ref's initializer cannot read.
+    groupingActiveRef.current = previousGrouping.length > 0;
+
+    // The tree column's entry in `initialState` only reaches a slice the
+    // table owns. With `columnVisibility` in an external atom the entry is
+    // missing, and a missing entry means visible: the tree column would
+    // render in an ungrouped grid. The entry is seeded here through the table
+    // API instead, so the write reaches whichever store owns the slice. No-op
+    // when the entry is already correct. `?.`: an external atom can hold
+    // `undefined`.
+    if (
+      table.store.state.columnVisibility?.[GROUP_COLUMN_ID] !==
+      (previousGrouping.length > 0)
+    ) {
+      table.setColumnVisibility((old) => ({
+        ...old,
+        [GROUP_COLUMN_ID]: previousGrouping.length > 0,
+      }));
+    }
 
     const subscription = table.store.subscribe((state) => {
       if (state.grouping === previousGrouping) return;
       previousGrouping = state.grouping;
+      // Keeps the entry injected into a controlled `columnVisibility` (see
+      // requestedState) in sync with grouping.
+      groupingActiveRef.current = state.grouping.length > 0;
+      // On a controlled slice the writes below round-trip through the
+      // consumer's handler; the next render must forward them unstabilized.
+      // See republishControlledStateRef.
+      republishControlledStateRef.current = true;
 
       table.setColumnVisibility((old) => ({
         ...old,