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

package/src/components/TMDataGridDraftActions.tsx

@@ -0,0 +1,307 @@
+import { Button, Group, Text } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
+import type { ReactNode } from "react";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import { getOpenRowIds } from "../core/editEngine";
+import { getDisplayedRows } from "../core/rowSelection";
+import type {
+  TMDataGridScrollAlign,
+  TMDataGridScrollToRowArgs,
+} from "../useTMDataGrid";
+
+/**
+ * How many rows the draft store holds - parked edits, parked 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) => {
+    const deleted = new Set(state.deletedRowIds);
+    // An edited row that was then marked counts once: Save sends the
+    // deletion and leaves the edit behind.
+    const edited =
+      deleted.size === 0
+        ? state.committedRowIds.length
+        : state.committedRowIds.filter((rowId) => !deleted.has(rowId)).length;
+    return (
+      edited +
+      state.newRows.filter((newRow) => newRow.committed).length +
+      deleted.size
+    );
+  });
+}
+
+/**
+ * How many rows are still open - edited or entered but not parked, so not
+ * part of the save. Surfaced beside Save so an undecided row is visible
+ * rather than silently left behind.
+ */
+function useOpenCount(): number {
+  const { edit } = useTMDataGridContext();
+  return useSelector(edit.store, (state) => getOpenRowIds(state).length);
+}
+
+/**
+ * The ids behind {@link useOpenCount}. Shallow-compared: the array would
+ * otherwise be a new one on every edit-store publish, and it is handed to
+ * `renderActions`, where it may well end up in a dependency array.
+ */
+function useOpenRowIds(): ReadonlyArray<string> {
+  const { edit } = useTMDataGridContext();
+  return useSelector(edit.store, getOpenRowIds, { compare: shallow });
+}
+
+/*
+ * 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();
+  // Save sends the draft store, so its loading state is the save in flight,
+  // not an open row's submit.
+  const isSaving = useSelector(edit.store, (state) => state.isSaving);
+
+  return (
+    <Button
+      size="compact-sm"
+      disabled={draftCount === 0}
+      loading={isSaving}
+      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: TMDataGridDraftActionsControls = {
+  Save: EditSaveButton,
+  Discard: EditDiscardButton,
+  OpenRowsNote: EditOpenRowsNote,
+};
+
+/** What the edit chrome is showing. */
+export type TMDataGridDraftActionsState = {
+  /**
+   * 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;
+  /**
+   * The ids behind {@link openCount}, in the order the grid opened them - a
+   * sort, a filter or a page never moves this list. An entered row appears as
+   * its `tempId`.
+   *
+   * Narrower than `edit.state.openRowIds`, which is every row holding a form,
+   * the parked ones included. And note the ordering:
+   * {@link TMDataGridDraftActionsActions.scrollToFirstOpenRow} takes "first"
+   * in display order, so it need not be `openRowIds[0]`.
+   */
+  openRowIds: ReadonlyArray<string>;
+  /**
+   * @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 - any open row is submitting. */
+  isSubmitting: boolean;
+  /** `true` while `saveDrafts` is in flight. */
+  isSaving: boolean;
+};
+
+/** What the edit chrome can do. */
+export type TMDataGridDraftActionsActions = {
+  /** 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;
+  /**
+   * `grid.scrollToRow`, so a control in here can take the user to a row
+   * without the grid being threaded down to it.
+   */
+  scrollToRow: (args: TMDataGridScrollToRowArgs) => boolean;
+  /**
+   * Scrolls to the first row still open, taking "first" in display order: the
+   * topmost open row under the current sort, filter and page. That need not
+   * be {@link TMDataGridDraftActionsState.openRowIds}`[0]`, which is the
+   * order the grid opened them in.
+   *
+   * Answers whether an open row could be reached. `false` when nothing is
+   * open, and when every open row is filtered out, on another page or
+   * collapsed inside a group. An open entry row answers `true` without
+   * scrolling - it is sticky under the header, so it is on screen already -
+   * and so does an open row pinned to an edge. The scroll goes through
+   * `scrollToRow`, so before `TMDataGrid.Table` has mounted there is nothing
+   * to scroll and the answer is `false`.
+   */
+  scrollToFirstOpenRow: (align?: TMDataGridScrollAlign) => boolean;
+};
+
+/** The pre-bound pieces of the built-in edit chrome. */
+export type TMDataGridDraftActionsControls = {
+  /** 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 TMDataGridDraftActionsProps.renderActions} is handed. */
+export type TMDataGridDraftActionsSlotArgs = {
+  state: TMDataGridDraftActionsState;
+  actions: TMDataGridDraftActionsActions;
+  Controls: TMDataGridDraftActionsControls;
+};
+
+export type TMDataGridDraftActionsProps = {
+  /**
+   * Replaces the built-in Save/Discard pair, and is handed the pieces of it.
+   *
+   * ```tsx
+   * <TMDataGrid.DraftActions
+   *   renderActions={({ state, Controls }) => (
+   *     <Group>
+   *       {state.draftCount > 0 && <Badge>{state.draftCount}</Badge>}
+   *       <Controls.OpenRowsNote />
+   *       <Controls.Save />
+   *       <Controls.Discard />
+   *     </Group>
+   *   )}
+   * />
+   * ```
+   */
+  renderActions?: (args: TMDataGridDraftActionsSlotArgs) => ReactNode;
+};
+
+/**
+ * The draft store's toolbar chrome: Save with the store's count, Discard, and
+ * a note counting the rows still open. Save sends the store and leaves open
+ * rows alone, so it greys out while nothing is parked however much is being
+ * typed - the note is what makes those rows visible.
+ *
+ * Works under any `editing.mode`. The toolbar is declarative: the grid does
+ * not decide for you, so include this only when the grid runs a draft store -
+ * without `editing.draft` there is nothing to save and Save stays disabled.
+ *
+ * ```tsx
+ * <TMDataGrid.Toolbar>
+ *   <TMDataGrid.SummaryCount />
+ *   <TMDataGrid.Spacer />
+ *   <TMDataGrid.DraftActions />
+ * </TMDataGrid.Toolbar>
+ * ```
+ */
+export function TMDataGridDraftActions({
+  renderActions,
+}: TMDataGridDraftActionsProps = {}) {
+  const { edit, features, table, scrollToRow } = useTMDataGridContext();
+  const draftCount = useDraftCount();
+  const openRowIds = useOpenRowIds();
+  const isSubmitting = useSelector(edit.store, (state) =>
+    state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
+  );
+  const isSaving = useSelector(edit.store, (state) => state.isSaving);
+
+  if (!features.editing) return null;
+
+  if (renderActions) {
+    return renderActions({
+      state: {
+        draftCount,
+        openCount: openRowIds.length,
+        openRowIds,
+        pendingCount: draftCount + openRowIds.length,
+        isSubmitting,
+        isSaving,
+      },
+      actions: {
+        save: () => edit.saveDrafts(),
+        commitAll: () => edit.commitAll(),
+        discard: () => edit.cancelAll(),
+        scrollToRow,
+        scrollToFirstOpenRow: (align) => {
+          // Read through the store rather than closing over this render's
+          // arrays: display order is only decided here, at the click.
+          const state = edit.state;
+          const openIds = getOpenRowIds(state);
+          if (openIds.length === 0) return false;
+          const open = new Set(openIds);
+          const first = getDisplayedRows(table, features).find((row) =>
+            open.has(row.id),
+          );
+          if (first !== undefined) {
+            return scrollToRow({ rowId: first.id, align });
+          }
+          // Nothing left in the scrolling order, which does not mean nothing
+          // is visible: an entry row is sticky under the header, and a pinned
+          // row is parked at an edge - `scrollToRow` answers for that one.
+          return openIds.some(
+            (rowId) =>
+              state.newRows.some((newRow) => newRow.tempId === rowId) ||
+              scrollToRow({ rowId, align }),
+          );
+        },
+      },
+      Controls: EDIT_ACTIONS_CONTROLS,
+    });
+  }
+
+  return (
+    <Group gap="xs" wrap="nowrap">
+      <EditOpenRowsNote />
+      <EditSaveButton />
+      <EditDiscardButton />
+    </Group>
+  );
+}

package/src/{tmdatagrid/components → components}/TMDataGridEditColumn.tsx

@@ -3,11 +3,11 @@ import { useSelector } from "@tanstack/react-store";
 import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
 import classes from "./TMDataGridTable.module.css";
 import {
-  useCellControlTabIndex,
+  useBodyControlTabIndex,
   useTMDataGridContext,
 } from "../TMDataGridContext";
 import type { TMDataGridFeatures } from "../useTMDataGrid";
-import { firstErrorText } from "./editors/editorShared";
+import { firstErrorText } from "../core/editEngine";
 import {
   CheckIcon,
   CloseIcon,
@@ -20,10 +20,10 @@ import {
 export const EDIT_COLUMN_ID = "__edit__";
 
 /**
- * Draft mode's change marker in the lane - what kind of uncommitted change
- * the row carries. Non-interactive; the buttons beside it act. `data-state`
- * is the styling hook, `data-error` flips it red and puts the message in the
- * tooltip in place of the state's name.
+ * The draft store's change marker in the lane - what kind of change the row
+ * is holding for the save. Non-interactive; the buttons beside it act.
+ * `data-state` is the styling hook, `data-error` flips it red and puts the
+ * message in the tooltip in place of the state's name.
  */
 function RowStateIndicator({
   state,
@@ -56,13 +56,23 @@ function RowStateIndicator({
 }
 
 /**
- * One row's slot in the edit lane, driven off the edit store. Outside draft
- * mode: a pencil while idle, Save/Cancel while the row's form is open, a
- * loader while its commit is in flight; a row error turns the Save red with
- * the message in its tooltip - the pathless `.refine()` has nowhere else to
- * land. Under draft mode the lane is the change marker and the per-row
- * revert instead: a state icon (new/edited/deleted) beside undo, discard or
- * restore - never a per-row save, which the engine would only park anyway.
+ * One row's slot in the edit lane, driven off the edit store. Two things
+ * decide what it holds, and they are the two axes of `editing`:
+ *
+ * | Row is | Lane holds | From |
+ * | ------ | ---------- | ---- |
+ * | parked in the draft store | the change marker and the way back out - revert, discard or restore | `editing.draft` |
+ * | open | the mode's own controls: Save and Cancel | `editing.mode` |
+ * | neither | the pencil (row mode) and the trash | `editing.mode` |
+ *
+ * A row error turns the Save - or an entry row's ✓ - red with the message in
+ * its tooltip: a pathless `.refine()` has nowhere else to land, and a field
+ * error outlives the editor that found it. A parked row never offers a save:
+ * it has had its submit, and `TMDataGrid.DraftActions` is what sends it.
+ *
+ * The lane's controls take the tab index every body control does - see
+ * useBodyControlTabIndex. The open row's save and cancel are the exception,
+ * see where they are built.
  */
 function EditLaneCell<TData extends RowData>({
   row,
@@ -70,7 +80,7 @@ function EditLaneCell<TData extends RowData>({
   row: Row<TMDataGridFeatures, TData>;
 }) {
   const { edit, features, labels } = useTMDataGridContext();
-  const tabIndex = useCellControlTabIndex();
+  const tabIndex = useBodyControlTabIndex();
   const rowId = row.id;
   const isOpen = useSelector(edit.store, (state) =>
     state.openRowIds.includes(rowId),
@@ -82,21 +92,28 @@ 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,
   );
+  // Parked: the row passed its submit and is waiting for the save. A subset
+  // of the open rows, so it is asked about first - the two overlap.
+  const isCommitted = useSelector(edit.store, (state) =>
+    state.committedRowIds.includes(rowId),
+  );
   const isMarkedDeleted = useSelector(edit.store, (state) =>
     state.deletedRowIds.includes(rowId),
   );
 
   if (row.getIsGrouped()) return null;
 
-  const isDraftMode = features.editMode === "draft";
   const hasErrors =
     projection !== undefined &&
     (projection.hasRowError || projection.errorFields.length > 0);
+  // The row's own message first - a pathless issue is about the row - then
+  // the first field's, which is what a failed commit left behind.
   const rowError = hasErrors
     ? (firstErrorText(edit.getForm(rowId)?.state.errors ?? []) ??
+      projection.errorMessages[0]?.message ??
       labels.editRowErrors)
     : null;
 
@@ -120,9 +137,9 @@ function EditLaneCell<TData extends RowData>({
     </Tooltip>
   ) : null;
 
-  // An entry row: ✓ enters it - an add under the immediate modes, a parked
-  // confirm under draft - and ✕ discards the entry. A confirmed entry waits
-  // for Save all as a value row: marked new, re-openable, still discardable.
+  // An entry row: ✓ enters it - an add, or a park under `editing.draft` -
+  // and ✕ discards the entry. A parked entry waits for the save as a value
+  // row: marked new, re-openable, still discardable.
   if (isNew) {
     if (isConfirmedNew) {
       return (
@@ -169,10 +186,10 @@ function EditLaneCell<TData extends RowData>({
     }
     return (
       <Group gap={0} wrap="nowrap">
-        <Tooltip label={labels.confirmNewRow} withArrow>
+        <Tooltip label={rowError ?? labels.confirmNewRow} withArrow>
           <ActionIcon
             variant="subtle"
-            color="green"
+            color={hasErrors ? "red" : "green"}
             size="sm"
             tabIndex={tabIndex}
             aria-label={labels.confirmNewRow}
@@ -201,7 +218,7 @@ function EditLaneCell<TData extends RowData>({
     );
   }
 
-  // A draft-mode deletion mark is a draft like any other - restorable in place.
+  // A deletion mark is a draft like any other - restorable in place.
   if (isMarkedDeleted) {
     return (
       <Group gap={0} wrap="nowrap">
@@ -222,7 +239,7 @@ function EditLaneCell<TData extends RowData>({
             data-row-id={rowId}
             onClick={(event) => {
               event.stopPropagation();
-              edit.deleteRow(rowId);
+              edit.restoreRow(rowId);
             }}
           >
             <RestoreIcon size={16} stroke={1.6} />
@@ -235,16 +252,14 @@ function EditLaneCell<TData extends RowData>({
   // The pencil means "this row edits"; a row that does not gets nothing.
   if (!edit.canEditRow(row as never)) return null;
 
-  // Draft mode never offers a per-row save - the engine would only park it,
-  // and Save all is the commit. The lane is the state marker and the revert.
-  // No trash beside the revert: the two undo-shaped icons were too easy to
-  // mistake for one another, so a dirty row reverts first, then deletes.
-  if (isDraftMode) {
-    if (projection?.isSubmitting) {
-      return <Loader size="xs" aria-label={labels.loading} />;
-    }
-    const isDirty = (projection?.dirtyFields.length ?? 0) > 0;
-    if (!isDirty) return trash;
+  if (projection?.isSubmitting) {
+    return <Loader size="xs" aria-label={labels.loading} />;
+  }
+
+  // Parked in the draft store: the mark, and the way back out. No trash
+  // beside the revert - the two undo-shaped icons were too easy to mistake
+  // for one another, so a drafted row reverts first, then deletes.
+  if (isCommitted) {
     return (
       <Group gap={0} wrap="nowrap">
         <RowStateIndicator
@@ -301,16 +316,15 @@ function EditLaneCell<TData extends RowData>({
     );
   }
 
-  if (projection?.isSubmitting) {
-    return <Loader size="xs" aria-label={labels.loading} />;
-  }
-
+  // An open row is a form, and its save and cancel are the form's last two
+  // fields: Tab walks into them from the last editor. The closed lane's
+  // controls stay out of the tab order like every other control in a cell.
   const save = (
     <ActionIcon
       variant="subtle"
       color={hasErrors ? "red" : "green"}
       size="sm"
-      tabIndex={tabIndex}
+      tabIndex={0}
       aria-label={labels.saveRow}
       data-dg-part="save-row"
       data-row-id={rowId}
@@ -325,21 +339,15 @@ function EditLaneCell<TData extends RowData>({
 
   return (
     <Group gap={0} wrap="nowrap">
-      {rowError === null ? (
-        <Tooltip label={labels.saveRow} withArrow>
-          {save}
-        </Tooltip>
-      ) : (
-        <Tooltip label={rowError} withArrow>
-          {save}
-        </Tooltip>
-      )}
+      <Tooltip label={rowError ?? labels.saveRow} withArrow>
+        {save}
+      </Tooltip>
       <Tooltip label={labels.cancelRowEdit} withArrow>
         <ActionIcon
           variant="subtle"
           color="gray"
           size="sm"
-          tabIndex={tabIndex}
+          tabIndex={0}
           aria-label={labels.cancelRowEdit}
           data-dg-part="cancel-row"
           data-row-id={rowId}
@@ -358,11 +366,11 @@ function EditLaneCell<TData extends RowData>({
 /**
  * The generated edit lane, appended and pinned right - the row's Save at the
  * end of the row under `mode: "row"`, the state marker and revert under
- * `mode: "draft"`, mirroring the checkbox lane's build on the left.
+ * `editing.draft`, mirroring the checkbox lane's build on the left.
  */
 export function createEditColumn<TData extends RowData>(
   label = "Edit",
-  /** Draft mode holds three controls where the others hold two. */
+  /** A draft lane holds three controls where the rest hold two. */
   wide = false,
 ): ColumnDef<TMDataGridFeatures, TData, unknown> {
   const width = wide ? 88 : 64;