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

package/src/tmdatagrid/components/TMDataGridEditActions.tsx

@@ -1,22 +1,43 @@
-import { Button, Group } from "@mantine/core";
+import { Button, Group, Text } from "@mantine/core";
 import { useSelector } from "@tanstack/react-store";
 import type { ReactNode } from "react";
 import { useTMDataGridContext } from "../TMDataGridContext";
 
 /**
- * How many rows are waiting to be saved: dirty edits, entry rows (an add is
- * pending whether or not it was touched), and deletion marks.
+ * How many rows the draft store holds - committed edits, committed entry
+ * rows and deletion marks. This is what Save sends, so it is what Save
+ * counts: a row the user is still typing into is not in here.
  */
-function usePendingCount(): number {
+function useDraftCount(): number {
+  const { edit } = useTMDataGridContext();
+  return useSelector(
+    edit.store,
+    (state) =>
+      state.committedRowIds.length +
+      state.newRows.filter((newRow) => newRow.committed).length +
+      state.deletedRowIds.length,
+  );
+}
+
+/**
+ * How many rows are still open - edited or entered but not committed, so not
+ * part of the save. Surfaced beside Save so an uncommitted row is visible
+ * rather than silently left behind.
+ */
+function useOpenCount(): number {
   const { edit } = useTMDataGridContext();
   return useSelector(
     edit.store,
     (state) =>
       state.openRowIds.filter(
         (rowId) =>
-          state.newRows.some((newRow) => newRow.tempId === rowId) ||
-          (state.rows[rowId]?.dirtyFields.length ?? 0) > 0,
-      ).length + state.deletedRowIds.length,
+          !state.committedRowIds.includes(rowId) &&
+          !state.newRows.some(
+            (newRow) => newRow.tempId === rowId && newRow.committed,
+          ) &&
+          (state.newRows.some((newRow) => newRow.tempId === rowId) ||
+            (state.rows[rowId]?.dirtyFields.length ?? 0) > 0),
+      ).length,
   );
 }
 
@@ -28,7 +49,7 @@ function usePendingCount(): number {
 
 function EditSaveButton() {
   const { edit, labels } = useTMDataGridContext();
-  const pendingCount = usePendingCount();
+  const draftCount = useDraftCount();
   const isSubmitting = useSelector(edit.store, (state) =>
     state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
   );
@@ -36,19 +57,39 @@ function EditSaveButton() {
   return (
     <Button
       size="compact-sm"
-      disabled={pendingCount === 0}
+      disabled={draftCount === 0}
       loading={isSubmitting}
       data-dg-part="save-all"
-      onClick={() => void edit.submitAll()}
+      data-draft-count={draftCount}
+      onClick={() => void edit.saveDrafts()}
     >
-      {labels.saveAllEdits(pendingCount)}
+      {labels.saveAllEdits(draftCount)}
     </Button>
   );
 }
 
+/** The count of rows left open, or nothing while every row is decided. */
+function EditOpenRowsNote() {
+  const { labels } = useTMDataGridContext();
+  const openCount = useOpenCount();
+  if (openCount === 0) return null;
+  return (
+    <Text
+      size="xs"
+      c="dimmed"
+      data-dg-part="open-rows-note"
+      data-open-count={openCount}
+    >
+      {labels.editRowsStillOpen(openCount)}
+    </Text>
+  );
+}
+
 function EditDiscardButton() {
   const { edit, labels } = useTMDataGridContext();
-  const pendingCount = usePendingCount();
+  // Discard drops everything the grid is holding, open rows included, so it
+  // stays live while anything is uncommitted.
+  const pendingCount = useDraftCount() + useOpenCount();
 
   return (
     <Button
@@ -67,11 +108,25 @@ function EditDiscardButton() {
 const EDIT_ACTIONS_CONTROLS: TMDataGridEditActionsControls = {
   Save: EditSaveButton,
   Discard: EditDiscardButton,
+  OpenRowsNote: EditOpenRowsNote,
 };
 
 /** What the edit chrome is showing. */
 export type TMDataGridEditActionsState = {
-  /** Rows with unsaved work: dirty edits, entry rows, and deletion marks. */
+  /**
+   * Rows in the draft store, which is what Save sends: committed edits,
+   * committed entry rows and deletion marks.
+   */
+  draftCount: number;
+  /**
+   * Rows still open - edited or entered but not committed, so not part of
+   * the save. They stay open across a save.
+   */
+  openCount: number;
+  /**
+   * @deprecated Was "everything uncommitted", which Save no longer sends.
+   * Reads as `draftCount + openCount`; use whichever you meant.
+   */
   pendingCount: number;
   /** Whether a submit is in flight. */
   isSubmitting: boolean;
@@ -79,18 +134,22 @@ export type TMDataGridEditActionsState = {
 
 /** What the edit chrome can do. */
 export type TMDataGridEditActionsActions = {
-  /** Commits every open row. Resolves `false` when a row stayed open. */
+  /** Saves the draft store. Open rows are left alone. */
   save: () => Promise<boolean>;
-  /** Drops every draft. */
+  /** Submits every open row, committing the ones that validate. */
+  commitAll: () => Promise<boolean>;
+  /** Drops everything - open form state and the draft store alike. */
   discard: () => void;
 };
 
 /** The pre-bound pieces of the built-in edit chrome. */
 export type TMDataGridEditActionsControls = {
-  /** Save, with the pending count, disabled while nothing is pending. */
+  /** Save, with the draft count, disabled while the draft store is empty. */
   Save: () => ReactNode;
   /** Discard, disabled while nothing is pending. */
   Discard: () => ReactNode;
+  /** The "N rows still being edited" note, or nothing while there are none. */
+  OpenRowsNote: () => ReactNode;
 };
 
 /** What {@link TMDataGridEditActionsProps.renderActions} is handed. */
@@ -108,7 +167,8 @@ export type TMDataGridEditActionsProps = {
    * <TMDataGrid.EditActions
    *   renderActions={({ state, Controls }) => (
    *     <Group>
-   *       {state.pendingCount > 0 && <Badge>{state.pendingCount}</Badge>}
+   *       {state.draftCount > 0 && <Badge>{state.draftCount}</Badge>}
+   *       <Controls.OpenRowsNote />
    *       <Controls.Save />
    *       <Controls.Discard />
    *     </Group>
@@ -120,11 +180,11 @@ export type TMDataGridEditActionsProps = {
 };
 
 /**
- * Draft mode's toolbar chrome: Save with the dirty-row count, and Discard.
- * Both read the edit store, so they grey out while nothing is dirty and the
- * Save spins while a submit is in flight. Works under any `editing.mode` - a
- * cellConfirm grid accumulating drafts can offer the same pair - and renders
- * nothing while editing is off.
+ * Draft mode's toolbar chrome: Save with the draft-store count, Discard, and
+ * a note counting rows still open. Save sends the draft store and leaves open
+ * rows alone, so it greys out while nothing is committed however much is
+ * being typed - the note is what makes those rows visible. Works under any
+ * `editing.mode` and renders nothing while editing is off.
  *
  * ```tsx
  * <TMDataGrid.Toolbar>
@@ -138,7 +198,8 @@ export function TMDataGridEditActions({
   renderActions,
 }: TMDataGridEditActionsProps = {}) {
   const { edit, features } = useTMDataGridContext();
-  const pendingCount = usePendingCount();
+  const draftCount = useDraftCount();
+  const openCount = useOpenCount();
   const isSubmitting = useSelector(edit.store, (state) =>
     state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
   );
@@ -147,14 +208,24 @@ export function TMDataGridEditActions({
 
   if (renderActions) {
     return renderActions({
-      state: { pendingCount, isSubmitting },
-      actions: { save: () => edit.submitAll(), discard: () => edit.cancelAll() },
+      state: {
+        draftCount,
+        openCount,
+        pendingCount: draftCount + openCount,
+        isSubmitting,
+      },
+      actions: {
+        save: () => edit.saveDrafts(),
+        commitAll: () => edit.commitAll(),
+        discard: () => edit.cancelAll(),
+      },
       Controls: EDIT_ACTIONS_CONTROLS,
     });
   }
 
   return (
     <Group gap="xs" wrap="nowrap">
+      <EditOpenRowsNote />
       <EditSaveButton />
       <EditDiscardButton />
     </Group>

package/src/tmdatagrid/components/TMDataGridEditColumn.tsx

@@ -82,7 +82,7 @@ function EditLaneCell<TData extends RowData>({
   const isConfirmedNew = useSelector(
     edit.store,
     (state) =>
-      state.newRows.find((newRow) => newRow.tempId === rowId)?.confirmed ===
+      state.newRows.find((newRow) => newRow.tempId === rowId)?.committed ===
       true,
   );
   const isMarkedDeleted = useSelector(edit.store, (state) =>

package/src/tmdatagrid/components/TMDataGridEntryRows.tsx

@@ -67,12 +67,12 @@ export function TMDataGridEntryRows({
 }) {
   const { table, edit, features } = useTMDataGridContext();
   const newRows = useSelector(edit.store, (state) => state.newRows);
-  // The reopen gesture: `begin` on a confirmed entry row flips it back to
+  // The reopen gesture: `begin` on a committed entry row flips it back to
   // editors and names the cell double-clicked - where the caret goes.
   const activeEntry = useSelector(edit.store, (state) =>
     state.active !== null &&
     state.newRows.some(
-      (newRow) => newRow.tempId === state.active?.rowId && !newRow.confirmed,
+      (newRow) => newRow.tempId === state.active?.rowId && !newRow.committed,
     )
       ? state.active
       : null,
@@ -109,7 +109,7 @@ export function TMDataGridEntryRows({
   });
 
   /**
-   * The caret for a reopen: `begin` on a confirmed row re-arms its editors
+   * The caret for a reopen: `begin` on a committed row re-arms its editors
    * and the double-clicked cell's editor should hold the caret, not the
    * row's first. Keyed separately from the add effect above - the row was
    * already focused once when it was added.
@@ -134,16 +134,16 @@ export function TMDataGridEntryRows({
     focusEditorContent(editor);
   });
 
-  // Unconfirmed rows keep the seed values frozen at addRow - the live values
+  // Open (uncommitted) rows keep the seed values frozen at addRow - the live values
   // belong to the forms, which the editors read directly, and this table only
-  // provides row and cell identity. A confirmed row's cells render values, so
+  // provides row and cell identity. A committed row's cells render values, so
   // there the draft itself is the row; the memo recomputes on every
-  // confirm/reopen because either flips `newRows`' identity.
+  // commit/reopen because either flips `newRows`' identity.
   const data = useMemo(
     () =>
       newRows.map(
-        ({ tempId, confirmed }) =>
-          ((confirmed
+        ({ tempId, committed }) =>
+          ((committed
             ? edit.getForm(tempId)?.state.values
             : edit.getForm(tempId)?.options.defaultValues) ??
             {}) as TMDataGridRowData,
@@ -161,20 +161,20 @@ export function TMDataGridEntryRows({
   if (newRows.length === 0) return null;
 
   const entryRows = entryTable.getCoreRowModel().rows;
-  const confirmedById = new Map(
-    newRows.map((newRow) => [newRow.tempId, newRow.confirmed]),
+  const committedById = new Map(
+    newRows.map((newRow) => [newRow.tempId, newRow.committed]),
   );
   // A row being *typed* into is always sticky - it exists nowhere else to
-  // scroll back to. A confirmed row joins the scrolling flow unless
+  // scroll back to. A committed row joins the scrolling flow unless
   // `newRowsSticky` keeps it pinned, so entering many rows cannot fill the
   // viewport with sticky chrome.
   const stickyRows = entryRows.filter(
     (entryRow) =>
-      features.editNewRowsSticky || confirmedById.get(entryRow.id) !== true,
+      features.editNewRowsSticky || committedById.get(entryRow.id) !== true,
   );
   const flowRows = features.editNewRowsSticky
     ? []
-    : entryRows.filter((entryRow) => confirmedById.get(entryRow.id) === true);
+    : entryRows.filter((entryRow) => committedById.get(entryRow.id) === true);
 
   const renderEntryRow = (
     entryRow: (typeof entryRows)[number],
@@ -183,7 +183,7 @@ export function TMDataGridEntryRows({
     const cellsById = new Map(
       entryRow.getAllCells().map((cell) => [cell.column.id, cell]),
     );
-    const confirmed = confirmedById.get(entryRow.id) === true;
+    const committed = committedById.get(entryRow.id) === true;
     return (
       <div
         key={entryRow.id}
@@ -191,7 +191,10 @@ export function TMDataGridEntryRows({
         data-dg-part="entry-row"
         data-row-id={entryRow.id}
         data-new
-        data-confirmed={confirmed}
+        data-committed={committed}
+        // The same marker body rows carry once committed, so one selector
+        // reaches everything parked in the draft store.
+        data-draft={committed}
         className={classes.entryRow}
       >
         {orderedColumns.map((column) => {
@@ -206,10 +209,10 @@ export function TMDataGridEntryRows({
               data-column-id={column.id}
               data-align={getColumnAlign(column)}
               data-control-column={isControlColumn(column.id)}
-              // A confirmed row re-opens where it is double-clicked, the
+              // A committed row re-opens where it is double-clicked, the
               // same gesture a body cell answers.
               onDoubleClick={
-                confirmed && !isControlColumn(column.id)
+                committed && !isControlColumn(column.id)
                   ? () =>
                       edit.begin({
                         rowId: entryRow.id,
@@ -239,7 +242,7 @@ export function TMDataGridEntryRows({
               {cell !== undefined && column.id === EDIT_COLUMN_ID ? (
                 // The lane's cell - the entry row's controls.
                 flexRender(cell.column.columnDef.cell, cell.getContext())
-              ) : confirmed && cell !== undefined ? (
+              ) : committed && cell !== undefined ? (
                 // Entered, awaiting Save all: a value row through the
                 // columns' own renderers, over the draft the memo above
                 // fed this table.

package/src/tmdatagrid/components/TMDataGridTable.tsx

@@ -750,6 +750,14 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
       (id) => (state.rows[id]?.dirtyFields.length ?? 0) > 0,
     ),
   );
+  // Rows parked in the draft store, waiting for Save. A separate marker from
+  // `data-dirty`, which covers any row being typed into: after a partial save
+  // these are what is left, so one selector highlights everything still
+  // pending.
+  const editDraftRowIds = useSelector(
+    edit.store,
+    (state) => state.committedRowIds,
+  );
 
   const { loading, noResultsLabel = labels.noResults } =
     table.options.meta ?? {};
@@ -2233,6 +2241,11 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                     editDirtyRowIds.length > 0 &&
                     editDirtyRowIds.includes(row.id)
                   }
+                  // Committed into the draft store, waiting for Save.
+                  data-draft={
+                    editDraftRowIds.length > 0 &&
+                    editDraftRowIds.includes(row.id)
+                  }
                   // The menu is anchored to the rowgroup, so Mantine's own
                   // `data-expanded` lands there rather than on a row. This is
                   // what says which row the open menu is about.

package/src/tmdatagrid/core/controlledState.ts

@@ -0,0 +1,179 @@
+import type { TableState } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+
+type GridState = TableState<TMDataGridFeatures>;
+
+/**
+ * Support for TanStack's `state` option (controlled state).
+ *
+ * table-core re-reads `options.state` on every render (`useTable` calls
+ * `setOptions` while rendering) and writes any slice whose value is not
+ * identical to the table's current value into the table's atom. The write
+ * publishes the store and re-renders the consumer, so a slice object built in
+ * the render body causes an infinite render loop.
+ *
+ * {@link stabilizeControlledState} prevents the loop by forwarding the
+ * previous render's value for a slice whose contents are unchanged.
+ * {@link findFrozenStateSlices} detects a controlled slice without its
+ * `onXChange` callback, which the grid cannot write to.
+ */
+
+/**
+ * The `onXChange` option that owns each controlled slice - every slice v9
+ * defines. `globalFilterFn` is not among them: in this beta it is a table
+ * option, not state.
+ */
+export const CONTROLLED_SLICE_HANDLERS = {
+  columnFilters: "onColumnFiltersChange",
+  columnOrder: "onColumnOrderChange",
+  columnPinning: "onColumnPinningChange",
+  columnResizing: "onColumnResizingChange",
+  columnSizing: "onColumnSizingChange",
+  columnVisibility: "onColumnVisibilityChange",
+  expanded: "onExpandedChange",
+  globalFilter: "onGlobalFilterChange",
+  grouping: "onGroupingChange",
+  pagination: "onPaginationChange",
+  rowPinning: "onRowPinningChange",
+  rowSelection: "onRowSelectionChange",
+  sorting: "onSortingChange",
+} as const satisfies Partial<Record<keyof GridState, string>>;
+
+export type TMDataGridControlledSlice = keyof typeof CONTROLLED_SLICE_HANDLERS;
+
+/** The options {@link findFrozenStateSlices} reads - a subset of `TableOptions`. */
+type ControlledOptions = {
+  state?: Partial<GridState>;
+  /**
+   * The v9 way of owning a slice: an atom the table writes through directly.
+   * It outranks `state`, so a slice backed by one is never frozen.
+   */
+  atoms?: Record<string, unknown>;
+} & Partial<
+  Record<(typeof CONTROLLED_SLICE_HANDLERS)[TMDataGridControlledSlice], unknown>
+>;
+
+const hasOwn = (value: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key);
+
+/**
+ * A plain data object: `Object.prototype` or null prototype. table-core builds
+ * its state maps with `Object.create(null)`, so null prototypes must compare
+ * as plain objects.
+ */
+function isDataObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Structural equality for state values.
+ *
+ * `Date`s compare by time; the built-in date filters hold them in filter
+ * values. `Map`s and class instances compare by identity, so a controlled
+ * slice containing one rebuilt each render reads as changed on every render
+ * and re-renders the table. Use primitives, plain objects, arrays or `Date`s
+ * in controlled state.
+ */
+export function sameStateValue(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (a instanceof Date || b instanceof Date) {
+    return (
+      a instanceof Date && b instanceof Date && a.getTime() === b.getTime()
+    );
+  }
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b)) return false;
+    return (
+      a.length === b.length &&
+      a.every((item, index) => sameStateValue(item, b[index]))
+    );
+  }
+  if (!isDataObject(a) || !isDataObject(b)) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  return keys.every((key) => hasOwn(b, key) && sameStateValue(a[key], b[key]));
+}
+
+/**
+ * Removes keys whose value is `undefined`, as in
+ * `state: { sorting: cond ? sorting : undefined }`.
+ *
+ * TanStack's sync writes every present key into the slice's atom, `undefined`
+ * included, which breaks everything that reads the slice. A key set to
+ * `undefined` is treated as not controlled: the key is removed and the slice
+ * falls back to the table's own state. Identity is preserved when there is
+ * nothing to remove; the stabilizer compares by it.
+ */
+export function withoutUndefinedSlices(
+  state: Partial<GridState> | undefined,
+): Partial<GridState> | undefined {
+  if (state === undefined) return state;
+  if (!Object.values(state).includes(undefined)) return state;
+  const compacted: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(state)) {
+    if (value !== undefined) compacted[key] = value;
+  }
+  return compacted as Partial<GridState>;
+}
+
+/**
+ * Returns `next` with every slice that structurally equals its counterpart in
+ * `previous` replaced by the previous object, so table-core's identity-based
+ * sync finds nothing to write. Returns `previous` when nothing changed.
+ */
+export function stabilizeControlledState(
+  next: Partial<GridState> | undefined,
+  previous: Partial<GridState> | undefined,
+): Partial<GridState> | undefined {
+  if (next === undefined || previous === undefined || next === previous) {
+    return next;
+  }
+
+  const keys = Object.keys(next);
+  const stabilized: Record<string, unknown> = {};
+  let changed = keys.length !== Object.keys(previous).length;
+
+  for (const key of keys) {
+    const nextValue = (next as Record<string, unknown>)[key];
+    const previousValue = (previous as Record<string, unknown>)[key];
+    if (hasOwn(previous, key) && sameStateValue(nextValue, previousValue)) {
+      // Unchanged contents: keep the object the table already holds.
+      stabilized[key] = previousValue;
+    } else {
+      stabilized[key] = nextValue;
+      changed = true;
+    }
+  }
+
+  return changed ? (stabilized as Partial<GridState>) : previous;
+}
+
+/**
+ * Controlled slices without a write path: `state.x` is set but no `onXChange`
+ * was passed and no external atom owns the slice. TanStack routes every write
+ * through the callback, so such a slice cannot change. Reported so the hook
+ * can warn in development; `initialState` is the option for a starting value.
+ */
+export function findFrozenStateSlices(
+  options: ControlledOptions,
+): Array<{ slice: TMDataGridControlledSlice; handler: string }> {
+  const state = options.state;
+  if (state === undefined) return [];
+
+  return (
+    Object.entries(CONTROLLED_SLICE_HANDLERS) as Array<
+      [TMDataGridControlledSlice, string]
+    >
+  )
+    .filter(
+      ([slice, handler]) =>
+        // Undefined-valued keys are removed before the table sees them; the
+        // slice is not controlled.
+        (state as Record<string, unknown>)[slice] !== undefined &&
+        (options as Record<string, unknown>)[handler] === undefined &&
+        options.atoms?.[slice] === undefined,
+    )
+    .map(([slice, handler]) => ({ slice, handler }));
+}