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

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -51,7 +51,7 @@ import {
   createEditEngine,
   type TMDataGridEditApi,
   type TMDataGridEditCommitArgs,
-  type TMDataGridEditCommitBatchArgs,
+  type TMDataGridEditCommitDraftsArgs,
   type TMDataGridEditEngineContext,
   type TMDataGridColumnEditOptions,
   type TMDataGridEditMode,
@@ -64,7 +64,7 @@ import {
   type TMDataGridColumnType,
   tmDataGridFilterFn,
 } from "./core/filterOperators";
-import { getColumnDefaultOperator } from "./core/columnUtils";
+import { getColumnDefaultOperator, isControlColumn } from "./core/columnUtils";
 import type { TMDataGridColumnFilterOptions } from "./core/filterControls";
 import {
   createFuzzyRankedSortedRowModel,
@@ -123,14 +123,14 @@ import {
 const PERSIST_DEBOUNCE_MS = 200;
 
 /**
- * Per-column configuration the TMDataGrid chrome reads.
+ * Per-column configuration the grid's own components read.
  *
- * A stage that owns behaviour gets a namespace - `filter` and `edit`, each
+ * The filter and edit stages each get a namespace, `filter` and `edit`,
  * mirroring the feature's runtime API. What the column *is* stays flat:
  * `label`, `type`, `options`, `align`, `flex`, `autoSize`, `enableOrdering`.
- * `type` and `options` in particular are shared ground - one declaration of
- * each feeds the filter panel and the cell editor alike, which is why they sit
- * outside both namespaces.
+ * `type` and `options` are read by both stages, so one declaration of each
+ * feeds the filter panel and the cell editor, which is why they sit outside
+ * both namespaces.
  */
 export type TMDataGridColumnMeta = {
   /** Name shown in menus and the column manager. Falls back to a string header. */
@@ -388,7 +388,7 @@ export type TMDataGridApi<TData extends RowData> = {
    * The edit engine - open forms, dirty/error projections, and the verbs
    * (`begin`, `commit`, `cancel`, `submitAll`). `edit.getForm(rowId)` hands
    * out the same TanStack Form the inline editors write through, so a drawer
-   * or detail panel can share a row's draft. Inert until `editMode` is set.
+   * or detail panel can share a row's draft. Inert until `editing` is set.
    */
   edit: TMDataGridEditApi;
   /** Table-level feature switches, re-read from options on every render. */
@@ -431,20 +431,14 @@ export type TMDataGridApi<TData extends RowData> = {
    */
   scrollToRow: (args: TMDataGridScrollToRowArgs) => boolean;
   /**
-   * @internal Wiring for `TMDataGrid.Table`, which owns the virtualizer and
-   * fills this in. Not part of the supported surface.
+   * @internal Wiring for `TMDataGrid.Table`, which holds the virtualizer and
+   * fills this in. Not part of the public API.
    */
   scrollerRef: MutableRefObject<TMDataGridScroller>;
 };
 
-/** The editing callbacks every mode shares. See {@link TMDataGridEditingOptions}. */
+/** The editing members every mode shares. See {@link TMDataGridEditingOptions}. */
 type TMDataGridEditingCallbacks<TData extends RowData> = {
-  /**
-   * `getRowId` stops being optional once editing is on: the forms are keyed
-   * by row id and live outside the DOM, and the index fallback points at a
-   * different record after any sort.
-   */
-  getRowId: NonNullable<TableOptions<TMDataGridFeatures, TData>["getRowId"]>;
   /**
    * Form-level validators for the whole editing row - where cross-field
    * rules live. TanStack Form's own vocabulary, Standard Schema included:
@@ -470,12 +464,10 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
    * draft visible with a busy marker - and a rejection keeps the form open
    * with the error on the row.
    *
-   * `changes` is the per-field diff (one entry in cell mode) for consumers
-   * who PATCH; `value` is the whole edited row for those who save records.
+   * `changes` is the per-field diff (one entry in cell mode), for a PATCH.
+   * `value` is the entire edited row, for saving a record.
    */
-  onEditCommit?: (
-    args: TMDataGridEditCommitArgs<TData>,
-  ) => void | Promise<void>;
+  onCommit?: (args: TMDataGridEditCommitArgs<TData>) => void | Promise<void>;
   /**
    * Seed values for `edit.addRow()` - the entry row's starting point. A
    * function is called per added row (fresh timestamps, empty arrays).
@@ -483,13 +475,13 @@ 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 batch. Create the record and let it
+   * immediate modes, `submitAll` under 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 batch, deletions accumulate in
+   * 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.
    */
@@ -497,21 +489,24 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
 };
 
 /**
- * The editing options travel together, and the type states it: without
- * `editMode` none of them has anything to act on, so passing one is a
- * compile error rather than a dead option; with it, `getRowId` becomes
- * required; and `onEditCommitBatch` exists only under `"batch"` - the one
- * mode whose `submitAll` calls it.
- *
- * `editMode` itself turns cell editing on and picks how commits happen. Off
- * by default.
+ * 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.
  *
  * | 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 |
- * | `"batch"` | `edit.submitAll()` | `edit.cancelAll()` |
+ * | `"draft"` | `edit.submitAll()` | `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.
+ *
+ * The object may be written inline: the callbacks are read through a ref
+ * every render, so its identity does not matter.
  *
  * One TanStack Form per editing row; drafts survive scrolling because the
  * forms live outside the DOM, keyed by row id. Which columns edit, and with
@@ -520,39 +515,56 @@ type TMDataGridEditingCallbacks<TData extends RowData> = {
  * override the rest.
  */
 export type TMDataGridEditingOptions<TData extends RowData> =
-  | (TMDataGridEditingCallbacks<TData> & {
-      editMode: "batch";
-      /**
-       * Batch mode's save, called once by `edit.submitAll()` with every
-       * valid dirty row. Without it, `submitAll` falls back to the per-row
-       * {@link TMDataGridEditingCallbacks.onEditCommit} loop. Rows failing
-       * validation stay open either way; a rejection keeps every draft.
-       */
-      onEditCommitBatch?: (
-        args: TMDataGridEditCommitBatchArgs<TData>,
-      ) => void | Promise<void>;
-    })
-  | (TMDataGridEditingCallbacks<TData> & {
-      editMode: Exclude<TMDataGridEditMode, "batch">;
-      /** Only `"batch"`'s `submitAll` ever calls it - see the other branch. */
-      onEditCommitBatch?: never;
-    })
-  | {
-      editMode?: never;
-      rowValidators?: never;
-      isRowEditable?: never;
-      onEditCommit?: never;
-      onEditCommitBatch?: never;
-      newRowDefaults?: never;
-      onRowAdd?: never;
-      onRowDelete?: never;
-    };
+  TMDataGridEditingCallbacks<TData> &
+    (
+      | {
+          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.
+           */
+          onCommitDrafts?: (
+            args: TMDataGridEditCommitDraftsArgs<TData>,
+          ) => void | Promise<void>;
+          /**
+           * 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.
+           */
+          newRowsSticky?: boolean;
+        }
+      | {
+          mode: Exclude<TMDataGridEditMode, "draft">;
+          /** Only `"draft"`'s `submitAll` ever calls it - see the other branch. */
+          onCommitDrafts?: never;
+          /** Confirmed entry rows exist only under `"draft"` - see there. */
+          newRowsSticky?: never;
+        }
+    );
 
 export type UseTMDataGridOptions<TData extends RowData> = Omit<
   TableOptions<TMDataGridFeatures, TData>,
   "features"
 > &
-  TMDataGridEditingOptions<TData> & {
+  (
+    | { editing?: undefined }
+    | {
+        /** Turns editing on. See {@link TMDataGridEditingOptions}. */
+        editing: TMDataGridEditingOptions<TData>;
+        /**
+         * Required once `editing` is set: the forms are keyed by row id and
+         * live outside the DOM, and the index fallback points at a different
+         * record after any sort.
+         */
+        getRowId: NonNullable<
+          TableOptions<TMDataGridFeatures, TData>["getRowId"]
+        >;
+      }
+  ) & {
   /**
    * Restore and persist table state across mounts. Two keys, because the two
    * kinds of state have different lifetimes - see {@link TMDataGridPersistence}.
@@ -772,9 +784,9 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
    * Defaults to 160.
    *
    * An estimate, not a height: every mounted row is measured, so the real one
-   * takes over as soon as the panel is on screen. It keeps the scrollbar honest
-   * for panels that open off screen (restored `expanded` state, say), and being
-   * roughly right is enough.
+   * takes over as soon as the panel is on screen. It keeps the scrollbar
+   * accurate for panels that open off screen, such as restored `expanded`
+   * state. An approximate value is enough.
    */
   renderDetailsEstHeight?: number;
   /**
@@ -807,6 +819,26 @@ type TMDataGridColumnDef<TData extends RowData> = ColumnDef<
  * request for one. Cleared here, so a grouped grid is a tree until a column
  * says otherwise - `aggregationFn: "sum"` on the column that wants it.
  */
+/**
+ * Drops the control lanes' entries from a visibility map.
+ *
+ * They are all `enableHiding: false`, but TanStack applies `columnVisibility`
+ * regardless - the option only gates `toggleVisibility` - so a stale `false`
+ * would hide a lane nothing in the grid can bring back: restored from storage
+ * written before 2.1 (when the checkbox lane was still hideable), or passed in
+ * `initialState`. The tree column is not scrubbed; its entry is the grid's own,
+ * written after this.
+ */
+function withoutControlColumnVisibility(
+  visibility: Record<string, boolean>,
+): Record<string, boolean> {
+  const scrubbed = { ...visibility };
+  for (const id of Object.keys(scrubbed)) {
+    if (isControlColumn(id)) delete scrubbed[id];
+  }
+  return scrubbed;
+}
+
 function withTMDataGridDefaults<TData extends RowData>(
   columns: ReadonlyArray<TMDataGridColumnDef<TData>>,
 ): Array<TMDataGridColumnDef<TData>> {
@@ -850,19 +882,16 @@ export function useTMDataGrid<TData extends RowData>({
   onHighlightedRowChange,
   cellSelection,
   onFocusedCellChange,
-  editMode,
-  rowValidators,
-  isRowEditable,
-  onEditCommit,
-  onEditCommitBatch,
-  newRowDefaults,
-  onRowAdd,
-  onRowDelete,
+  editing,
   renderDetails,
   renderDetailsEstHeight = DEFAULT_DETAILS_EST_HEIGHT,
   overscan = DEFAULT_OVERSCAN,
   ...options
 }: UseTMDataGridOptions<TData>): TMDataGridApi<TData> {
+  // 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;
+
   // Derived up here, rather than just before the return, because the rest of the
   // hook needs `selectColumn` - one place decides what each mode means.
   //
@@ -877,7 +906,7 @@ export function useTMDataGrid<TData extends RowData>({
     selectionMode,
     showSelectedBackground,
     cellSelection,
-    editMode,
+    editing,
   });
 
   // Resolved on the override's identity, so a module-scope dictionary costs one
@@ -891,12 +920,15 @@ export function useTMDataGrid<TData extends RowData>({
   // `renderDetails` has nothing for it to open.
   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.
+  // 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.
   const editColumnEnabled =
-    editMode !== undefined &&
-    (editMode === "row" ||
-      onRowDelete !== undefined ||
-      (editMode === "batch" && onEditCommitBatch !== undefined));
+    editing !== undefined &&
+    (editing.mode === "row" ||
+      editing.mode === "draft" ||
+      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
@@ -907,6 +939,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";
 
   const columns = useMemo(() => {
     const base = withTMDataGridDefaults<TData>(
@@ -936,7 +971,9 @@ 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)] : []),
+      ...(editColumnEnabled
+        ? [createEditColumn<TData>(editColumnLabel, editIsDraftMode)]
+        : []),
     ];
   }, [
     options.columns,
@@ -945,6 +982,7 @@ export function useTMDataGrid<TData extends RowData>({
     detailsColumnEnabled,
     groupColumnEnabled,
     editColumnEnabled,
+    editIsDraftMode,
     rowNumberColumnLabel,
     selectColumnLabel,
     groupColumnLabel,
@@ -1008,8 +1046,10 @@ export function useTMDataGrid<TData extends RowData>({
       ...options.initialState,
       ...persistedState,
       columnVisibility: {
-        ...options.initialState?.columnVisibility,
-        ...persistedState.columnVisibility,
+        ...withoutControlColumnVisibility({
+          ...options.initialState?.columnVisibility,
+          ...persistedState.columnVisibility,
+        }),
         // Last word, because the tree column's visibility is not a user setting
         // - it tracks the grouping state. See the effect below.
         ...(groupColumnEnabled
@@ -1064,24 +1104,26 @@ export function useTMDataGrid<TData extends RowData>({
   editContextRef.current = {
     table: table as unknown as TMDataGridTable<TMDataGridRowData>,
     editMode: editMode ?? "cell",
-    rowValidators,
-    isRowEditable: isRowEditable as TMDataGridEditEngineContext["isRowEditable"],
+    rowValidators: editing?.rowValidators,
+    isRowEditable:
+      editing?.isRowEditable as TMDataGridEditEngineContext["isRowEditable"],
     onEditCommit:
-      onEditCommit as TMDataGridEditEngineContext["onEditCommit"],
-    onEditCommitBatch:
-      onEditCommitBatch as TMDataGridEditEngineContext["onEditCommitBatch"],
+      editing?.onCommit as TMDataGridEditEngineContext["onEditCommit"],
+    onEditCommitDrafts:
+      editing?.onCommitDrafts as TMDataGridEditEngineContext["onEditCommitDrafts"],
     newRowDefaults:
-      newRowDefaults as TMDataGridEditEngineContext["newRowDefaults"],
-    onRowAdd: onRowAdd as TMDataGridEditEngineContext["onRowAdd"],
-    onRowDelete: onRowDelete as TMDataGridEditEngineContext["onRowDelete"],
+      editing?.newRowDefaults as TMDataGridEditEngineContext["newRowDefaults"],
+    onRowAdd: editing?.onRowAdd as TMDataGridEditEngineContext["onRowAdd"],
+    onRowDelete:
+      editing?.onRowDelete as TMDataGridEditEngineContext["onRowDelete"],
   };
   const [edit] = useState(() =>
     createEditEngine(() => editContextRef.current),
   );
 
   // Switching modes mid-flight drops every draft: the policies disagree about
-  // what an open form means, and carrying one across is how a "batch" draft
-  // silently commits under "cell".
+  // what an open form means, and carrying one across is how a draft parked
+  // under "draft" silently commits under "cell".
   const previousEditModeRef = useRef(editMode);
   useEffect(() => {
     if (previousEditModeRef.current === editMode) return;
@@ -1092,9 +1134,9 @@ export function useTMDataGrid<TData extends RowData>({
   // Editing without stable ids points every draft at whatever record slides
   // into that index after a sort. Loud, once, in development.
   useEffect(() => {
-    if (editMode !== undefined && options.getRowId === undefined) {
+    if (editing !== undefined && options.getRowId === undefined) {
       console.error(
-        "TMDataGrid: editMode requires getRowId - drafts are keyed by row id, and the index fallback names a different record after any sort or filter.",
+        "TMDataGrid: editing requires getRowId - drafts are keyed by row id, and the index fallback names a different record after any sort or filter.",
       );
     }
     // The check is a mount-time contract, not something to re-run per render.
@@ -1240,9 +1282,9 @@ export function useTMDataGrid<TData extends RowData>({
         ),
       setCellRange: (range) =>
         setState((prev) =>
-          // Same guard as above, and it earns more here: a drag publishes a new
-          // corner on every mouse move, and most of those land on the cell the
-          // range already ends at.
+          // Same guard as above, and it matters more here: a drag publishes a
+          // new corner on every mouse move, and most of those land on the cell
+          // the range already ends at.
           isSameCell(prev.cellRange?.anchor ?? null, range?.anchor ?? null) &&
           isSameCell(prev.cellRange?.focus ?? null, range?.focus ?? null)
             ? prev
@@ -1302,7 +1344,7 @@ export function useTMDataGrid<TData extends RowData>({
     const grouping = [...(initial?.grouping ?? [])];
     table.setGrouping(grouping);
     table.setColumnVisibility({
-      ...initial?.columnVisibility,
+      ...withoutControlColumnVisibility({ ...initial?.columnVisibility }),
       // The tree lane's visibility tracks the grouping, never the user.
       ...(groupColumnEnabled ? { [GROUP_COLUMN_ID]: grouping.length > 0 } : {}),
     });
@@ -1333,8 +1375,8 @@ export function useTMDataGrid<TData extends RowData>({
   const resetSettings = useCallback(() => resetSettingsRef.current(), []);
 
   // Filled in by `TMDataGrid.Table` on every render, because only the body
-  // holds the virtualizer and the current view. Answers `false` until one is
-  // mounted, which is the honest answer: there is nothing to scroll yet.
+  // holds the virtualizer and the current view. Returns `false` until one is
+  // mounted, since there is nothing to scroll before then.
   const scrollerRef = useRef<TMDataGridScroller>(() => false);
   const scrollToRow = useCallback(
     (args: TMDataGridScrollToRowArgs) => scrollerRef.current(args),