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

package/src/tmdatagrid/core/labels.ts

@@ -111,12 +111,12 @@ export type TMDataGridLabels = {
   cancelRowEdit: string;
   /** Save tooltip when field errors block the row, with no row message. */
   editRowErrors: string;
-  /** `EditActions`' Save, with the count of rows in the draft store. */
+  /** `DraftActions`' Save, with the count of rows in the draft store. */
   saveAllEdits: (rows: number) => string;
-  /** `EditActions`' Discard. */
+  /** `DraftActions`' Discard. */
   discardAllEdits: string;
   /**
-   * `EditActions`' note about rows still open - edited but not committed, so
+   * `DraftActions`' 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;

package/src/tmdatagrid/core/summary.ts

@@ -18,6 +18,10 @@ export type TMDataGridAggregationName = keyof typeof aggregationFns;
  * Filtered rather than paginated rows, so the total covers everything the
  * filters left (all pages), and follows the filters as they change. Reuses
  * TanStack's registered aggregation functions; `fn` defaults to `"sum"`.
+ *
+ * Every data row counts once. Grouping builds its group rows from this model
+ * rather than into it, so a grouped grid totals its records, not its records
+ * plus their subtotals; a tree counts parents and children alike.
  */
 export function aggregateColumn<TData extends RowData>({
   table,
@@ -29,7 +33,11 @@ export function aggregateColumn<TData extends RowData>({
   fn?: TMDataGridAggregationName;
 }): unknown {
   const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
-  const rows = erased.getFilteredRowModel().rows;
-  // Leaf and child rows are the same set here: the filtered model is flat.
+  // `flatRows`, not `rows`: the filtered model nests under `getSubRows`, and
+  // the top-level array would total a tree's roots and drop every child.
+  // Grouping does not nest it - the group rows are built from this model, not
+  // held in it - so a grouped grid is unaffected either way.
+  const rows = erased.getFilteredRowModel().flatRows;
+  // Leaf and child rows are the same set here: this is already every row.
   return aggregationFns[fn](columnId, rows, rows);
 }

package/src/tmdatagrid/index.ts

@@ -67,13 +67,13 @@ export {
   type TMDataGridOptionsSource,
 } from "./core/columnOptions";
 export {
-  TMDataGridEditActions,
-  type TMDataGridEditActionsActions,
-  type TMDataGridEditActionsControls,
-  type TMDataGridEditActionsProps,
-  type TMDataGridEditActionsSlotArgs,
-  type TMDataGridEditActionsState,
-} from "./components/TMDataGridEditActions";
+  TMDataGridDraftActions,
+  type TMDataGridDraftActionsActions,
+  type TMDataGridDraftActionsControls,
+  type TMDataGridDraftActionsProps,
+  type TMDataGridDraftActionsSlotArgs,
+  type TMDataGridDraftActionsState,
+} from "./components/TMDataGridDraftActions";
 export {
   clearedValueForType,
   getEditFieldName,
@@ -101,6 +101,8 @@ export {
   type TMDataGridRowDeleteArgs,
   type TMDataGridRowEditForm,
   type TMDataGridRowValidators,
+  type TMDataGridTableValidateArgs,
+  type TMDataGridTableValidators,
 } from "./core/editEngine";
 export type {
   TMDataGridColumnFilterOptions,

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -59,6 +59,7 @@ import {
   type TMDataGridRowAddArgs,
   type TMDataGridRowDeleteArgs,
   type TMDataGridRowValidators,
+  type TMDataGridTableValidators,
 } from "./core/editEngine";
 import {
   emptyValueForOperator,
@@ -461,6 +462,27 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
    * Pathed issues land on the matching columns; pathless ones on the row.
    */
   rowValidators?: TMDataGridRowValidators;
+  /**
+   * Rules that need the other rows - no duplicate keys, no overlapping
+   * ranges, allocations summing to a total. Handed the committing row and
+   * `rows`, the collection as it would stand if the commit landed: every
+   * draft overlaid, entry rows appended, deletion-marked rows removed.
+   *
+   * ```tsx
+   * tableValidators: {
+   *   onSubmit: ({ value, rowId, rows }) =>
+   *     rows.some((r) => r.rowId !== rowId && r.value.code === value.code)
+   *       ? { fields: { code: "Duplicate code" } }
+   *       : undefined,
+   * }
+   * ```
+   *
+   * Runs at every commit, after the row's own validators, and again per
+   * parked row during `saveDrafts` - a draft another edit has invalidated
+   * blocks the save. Pathed issues land on the committing row's cells,
+   * pathless ones on the row.
+   */
+  tableValidators?: TMDataGridTableValidators<TData>;
   /** Rows the pencil skips - `false` keeps a row read-only in every mode. */
   isRowEditable?: (row: Row<TMDataGridFeatures, TData>) => boolean;
   /**
@@ -481,36 +503,44 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
    */
   newRowDefaults?: TData | (() => TData);
   /**
-   * Called when an entry row commits: `Enter` or the lane's ✓ under the
-   * immediate modes, `submitAll` under draft. Create the record and let it
-   * arrive back through `data`; the engine's `tempId` never leaves the grid.
+   * Called when an entry row commits: `Enter` or the lane's ✓, or
+   * `saveDrafts` under `editing.draft`. Create the record and let it arrive
+   * back through `data`; the engine's `tempId` never leaves the grid.
    */
   onRowAdd?: (args: TMDataGridRowAddArgs<TData>) => void | Promise<void>;
   /**
-   * Called by `edit.deleteRow` under the immediate modes - confirmation, if
-   * any, belongs in here. Under draft, deletions accumulate in
-   * `edit.state.deletedRowIds` instead and are reported by `submitAll`.
-   * Setting this also puts the trash can in the edit lane.
+   * Called by `edit.deleteRow` - confirmation, if any, belongs in here. Under
+   * `editing.draft` deletions accumulate in `edit.state.deletedRowIds`
+   * instead and are reported by `saveDrafts`. Setting this also puts the
+   * trash can in the edit lane.
    */
   onRowDelete?: (args: TMDataGridRowDeleteArgs<TData>) => void | Promise<void>;
 };
 
 /**
  * The `editing` option: one object that turns editing on and holds
- * everything about it. `mode` picks what counts as a commit and which
- * controls trigger it; the other members act within that mode.
+ * everything about it. Two axes, and they are independent: `mode` picks what
+ * counts as a commit, `draft` picks where that commit goes.
+ *
+ * | Mode | Commit | Cancel | Controls |
+ * | ---- | ------ | ------ | -------- |
+ * | `"cell"` | Enter, Tab, blur - Sheets | Escape | none |
+ * | `"cellConfirm"` | ✓ or Enter; Tab and blur keep the draft | ✕ or Escape | ✓ / ✕ beside the input |
+ * | `"row"` | Save in the edit lane, or Enter | Cancel, or Escape | generated edit lane |
+ *
+ * | `draft` | Where a commit goes |
+ * | ------- | ------------------- |
+ * | `false` (default) | Out as it happens - `onCommit`, `onRowAdd`, `onRowDelete` |
+ * | `true` | Into the grid's draft store; `edit.saveDrafts()` sends the lot |
  *
- * | Mode | Commit | Cancel |
- * | ---- | ------ | ------ |
- * | `"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.commit(rowId)` into the draft store, `edit.saveDrafts()` out | `edit.cancelAll()` |
+ * So `{ mode: "row", draft: true }` is "edit a row, the lane's ✓ parks it,
+ * the toolbar's Save sends every parked row at once", and
+ * `{ mode: "cell", draft: true }` is the same store filled cell by cell.
  *
  * Setting `editing` makes `getRowId` required - drafts are keyed by row id,
  * and the index fallback would name a different record after any sort - and
- * `onSaveDrafts` exists only under `mode: "draft"`, the one mode with a draft
- * store to save.
+ * `onSaveDrafts` exists only under `draft: true`, the one configuration 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.
@@ -522,12 +552,35 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * override the rest.
  */
 export type TMDataGridEditingOptions<TData extends RowData> =
-  TMDataGridEditingCallbacks<TData> &
-    (
+  TMDataGridEditingCallbacks<TData> & {
+    /** What counts as a commit. See the table above. */
+    mode: TMDataGridEditMode;
+    /**
+     * The column ids that take edits, by id. Unset - the default - every
+     * column mapping to a data path is editable, which is what a grid whose
+     * columns are mostly the record itself wants.
+     *
+     * Set it for the other shape: a grid of reference data with one or two
+     * columns the user maintains, where naming those is shorter and harder to
+     * get wrong than switching every other column off one by one.
+     *
+     * This gates before `meta.edit`, never past it: a column left out takes no
+     * edits whatever its own meta says, and a column listed here still answers
+     * to its `meta.edit.enabled`.
+     */
+    columns?: ReadonlyArray<string>;
+  } & (
       | {
-          mode: "draft";
           /**
-           * Draft mode's save: called once by `edit.saveDrafts()` with the
+           * Commits park in the grid's draft store instead of reaching the
+           * consumer, and leave together through `edit.saveDrafts()`. The
+           * edit lane gains the change markers and the per-row revert, the
+           * trash marks a row for deletion rather than deleting it, and
+           * `TMDataGrid.DraftActions` gets something to save.
+           */
+          draft: true;
+          /**
+           * The bulk 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
@@ -555,21 +608,22 @@ export type TMDataGridEditingOptions<TData extends RowData> =
             | TMDataGridSaveDraftsResult
             | Promise<void | TMDataGridSaveDraftsResult>;
           /**
-           * 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.
+           * Keep parked entry rows pinned in the sticky entry block until
+           * the draft store is saved. Off by default: a parked row joins the
+           * scrolling flow above the body rows instead - the block a row is
+           * *typed* into is always sticky, but parked rows scroll, so
+           * entering many cannot fill the viewport with sticky chrome.
            */
           newRowsSticky?: boolean;
         }
       | {
-          mode: Exclude<TMDataGridEditMode, "draft">;
-          /** Only `"draft"` has a draft store to save - see the other branch. */
+          /** Every commit reaches the consumer as it happens. The default. */
+          draft?: false;
+          /** Only `draft: true` has a store to save - see the other branch. */
           onSaveDrafts?: never;
           /** @deprecated See {@link onSaveDrafts}. */
           onCommitDrafts?: never;
-          /** Committed entry rows exist only under `"draft"` - see there. */
+          /** Parked entry rows exist only under `draft: true` - see there. */
           newRowsSticky?: never;
         }
     );
@@ -919,6 +973,7 @@ export function useTMDataGrid<TData extends RowData>({
   // The one place `editing` is unpacked - the engine and the flags keep their
   // own vocabulary (`editMode`, `onEditCommit`), so the mapping lives here.
   const editMode = editing?.mode;
+  const editDraft = editing?.draft === true;
 
   // Derived up here, rather than just before the return, because the rest of the
   // hook needs `selectColumn` - one place decides what each mode means.
@@ -949,14 +1004,12 @@ export function useTMDataGrid<TData extends RowData>({
   const detailsColumnEnabled = renderDetails !== undefined;
   // Row mode's Save sits at the end of the row - the lane is its chrome. It
   // also appears wherever the trash can has somewhere to report to, and
-  // always under draft mode, where it is the change marker and the per-row
-  // revert - with or without `onCommitDrafts`, since the per-row `submitAll`
-  // fallback is a first-class configuration.
+  // always under `draft`, where it is the change marker and the per-row
+  // revert - with or without `onSaveDrafts`, since the per-row fallback is a
+  // first-class configuration.
   const editColumnEnabled =
     editing !== undefined &&
-    (editing.mode === "row" ||
-      editing.mode === "draft" ||
-      editing.onRowDelete !== undefined);
+    (editing.mode === "row" || editDraft || editing.onRowDelete !== undefined);
 
   // The generated lanes bake `meta.label` into their definitions, so the memo
   // depends on the strings rather than on the labels object - a fresh
@@ -967,9 +1020,9 @@ export function useTMDataGrid<TData extends RowData>({
   const editColumnLabel = labels.editColumnLabel;
   const rowNumberColumnLabel = labels.rowNumberColumnLabel;
   const rowNumbersEnabled = features.rowNumbers;
-  // Draft mode's lane holds three controls (state icon, undo, trash) where
-  // the other modes hold two - it gets the wider track.
-  const editIsDraftMode = editing?.mode === "draft";
+  // A draft lane holds three controls (state icon, undo, trash) where the
+  // rest hold two - it gets the wider track.
+  const editWideLane = editDraft;
 
   const columns = useMemo(() => {
     const base = withTMDataGridDefaults<TData>(
@@ -1000,7 +1053,7 @@ export function useTMDataGrid<TData extends RowData>({
       ...base,
       // Last and pinned right - the row's Save belongs at the end of the row.
       ...(editColumnEnabled
-        ? [createEditColumn<TData>(editColumnLabel, editIsDraftMode)]
+        ? [createEditColumn<TData>(editColumnLabel, editWideLane)]
         : []),
     ];
   }, [
@@ -1010,7 +1063,7 @@ export function useTMDataGrid<TData extends RowData>({
     detailsColumnEnabled,
     groupColumnEnabled,
     editColumnEnabled,
-    editIsDraftMode,
+    editWideLane,
     rowNumberColumnLabel,
     selectColumnLabel,
     groupColumnLabel,
@@ -1186,7 +1239,11 @@ export function useTMDataGrid<TData extends RowData>({
   editContextRef.current = {
     table: table as unknown as TMDataGridTable<TMDataGridRowData>,
     editMode: editMode ?? "cell",
+    draft: editDraft,
     rowValidators: editing?.rowValidators,
+    tableValidators: editing?.tableValidators as
+      TMDataGridEditEngineContext["tableValidators"],
+    editableColumnIds: editing?.columns,
     isRowEditable:
       editing?.isRowEditable as TMDataGridEditEngineContext["isRowEditable"],
     onEditCommit:
@@ -1209,15 +1266,18 @@ export function useTMDataGrid<TData extends RowData>({
       ) as unknown as TMDataGridEditApi<TData>,
   );
 
-  // Switching modes mid-flight drops every draft: the policies disagree about
-  // what an open form means, and carrying one across is how a draft parked
-  // under "draft" silently commits under "cell".
-  const previousEditModeRef = useRef(editMode);
+  // Switching either axis mid-flight drops every draft: the policies disagree
+  // about what an open form means, and carrying one across is how a row
+  // parked for `saveDrafts` silently commits to the consumer instead.
+  const previousEditPolicyRef = useRef({ editMode, editDraft });
   useEffect(() => {
-    if (previousEditModeRef.current === editMode) return;
-    previousEditModeRef.current = editMode;
+    const previous = previousEditPolicyRef.current;
+    if (previous.editMode === editMode && previous.editDraft === editDraft) {
+      return;
+    }
+    previousEditPolicyRef.current = { editMode, editDraft };
     edit.cancelAll();
-  }, [editMode, edit]);
+  }, [editMode, editDraft, edit]);
 
   // Editing without stable ids points every draft at whatever record slides
   // into that index after a sort. Loud, once, in development.

package/src/tmdatagrid/components/TMDataGridEditActions.tsx

@@ -1,233 +0,0 @@
-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 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 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.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,
-  );
-}
-
-/*
- * Module scope, like the pagination controls and for the same reason: a
- * component defined inside the render body is a new type every render, so
- * React would remount the buttons underneath an interaction.
- */
-
-function EditSaveButton() {
-  const { edit, labels } = useTMDataGridContext();
-  const draftCount = useDraftCount();
-  const isSubmitting = useSelector(edit.store, (state) =>
-    state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
-  );
-
-  return (
-    <Button
-      size="compact-sm"
-      disabled={draftCount === 0}
-      loading={isSubmitting}
-      data-dg-part="save-all"
-      data-draft-count={draftCount}
-      onClick={() => void edit.saveDrafts()}
-    >
-      {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();
-  // Discard drops everything the grid is holding, open rows included, so it
-  // stays live while anything is uncommitted.
-  const pendingCount = useDraftCount() + useOpenCount();
-
-  return (
-    <Button
-      variant="subtle"
-      color="gray"
-      size="compact-sm"
-      disabled={pendingCount === 0}
-      data-dg-part="discard-all"
-      onClick={() => edit.cancelAll()}
-    >
-      {labels.discardAllEdits}
-    </Button>
-  );
-}
-
-const EDIT_ACTIONS_CONTROLS: TMDataGridEditActionsControls = {
-  Save: EditSaveButton,
-  Discard: EditDiscardButton,
-  OpenRowsNote: EditOpenRowsNote,
-};
-
-/** What the edit chrome is showing. */
-export type TMDataGridEditActionsState = {
-  /**
-   * 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;
-};
-
-/** What the edit chrome can do. */
-export type TMDataGridEditActionsActions = {
-  /** Saves the draft store. Open rows are left alone. */
-  save: () => Promise<boolean>;
-  /** 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 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. */
-export type TMDataGridEditActionsSlotArgs = {
-  state: TMDataGridEditActionsState;
-  actions: TMDataGridEditActionsActions;
-  Controls: TMDataGridEditActionsControls;
-};
-
-export type TMDataGridEditActionsProps = {
-  /**
-   * Replaces the built-in Save/Discard pair, and is handed the pieces of it.
-   *
-   * ```tsx
-   * <TMDataGrid.EditActions
-   *   renderActions={({ state, Controls }) => (
-   *     <Group>
-   *       {state.draftCount > 0 && <Badge>{state.draftCount}</Badge>}
-   *       <Controls.OpenRowsNote />
-   *       <Controls.Save />
-   *       <Controls.Discard />
-   *     </Group>
-   *   )}
-   * />
-   * ```
-   */
-  renderActions?: (args: TMDataGridEditActionsSlotArgs) => ReactNode;
-};
-
-/**
- * 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>
- *   <TMDataGrid.SummaryCount />
- *   <TMDataGrid.Spacer />
- *   <TMDataGrid.EditActions />
- * </TMDataGrid.Toolbar>
- * ```
- */
-export function TMDataGridEditActions({
-  renderActions,
-}: TMDataGridEditActionsProps = {}) {
-  const { edit, features } = useTMDataGridContext();
-  const draftCount = useDraftCount();
-  const openCount = useOpenCount();
-  const isSubmitting = useSelector(edit.store, (state) =>
-    state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
-  );
-
-  if (!features.editing) return null;
-
-  if (renderActions) {
-    return renderActions({
-      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>
-  );
-}