@jielga/tmdatagrid 0.5.0 → 1.0.0

package/src/tmdatagrid/components/TMDataGridCellEditor.tsx

@@ -0,0 +1,256 @@
+import { ActionIcon } from "@mantine/core";
+import { FieldApi } from "@tanstack/react-form";
+import type { Cell, Row } from "@tanstack/react-table";
+import {
+  type ComponentType,
+  type FocusEvent,
+  type KeyboardEvent,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import classes from "./TMDataGridTable.module.css";
+import { type TMDataGridRowData, useTMDataGridContext } from "../TMDataGridContext";
+import {
+  getEditFieldName,
+  normalizeFieldValidate,
+  type TMDataGridEditField,
+  type TMDataGridEditorArgs,
+} from "../core/editEngine";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+import { CheckIcon, CloseIcon } from "./icons";
+import { TMDataGridBooleanEditor } from "./editors/TMDataGridBooleanEditor";
+import { TMDataGridDateEditor } from "./editors/TMDataGridDateEditor";
+import { TMDataGridMultiSelectEditor } from "./editors/TMDataGridMultiSelectEditor";
+import { TMDataGridNumberEditor } from "./editors/TMDataGridNumberEditor";
+import { TMDataGridSelectEditor } from "./editors/TMDataGridSelectEditor";
+import { TMDataGridStringEditor } from "./editors/TMDataGridStringEditor";
+
+const BUILT_IN_EDITORS: Record<
+  string,
+  ComponentType<TMDataGridEditorArgs>
+> = {
+  string: TMDataGridStringEditor,
+  number: TMDataGridNumberEditor,
+  boolean: TMDataGridBooleanEditor,
+  date: TMDataGridDateEditor,
+  select: TMDataGridSelectEditor,
+  multiSelect: TMDataGridMultiSelectEditor,
+};
+
+/** How an editor closed, for the table to decide where the focus goes. */
+export type TMDataGridCellEditorClose =
+  | { committed: true; via: "enter" | "tab" | "shift-tab" | "pick" }
+  | { committed: false; via: "escape" }
+  /** Batch: the editor closed, the draft stays — Enter parks, Tab moves on. */
+  | { committed: false; via: "defer" | "defer-tab" | "defer-shift-tab" };
+
+/**
+ * The host an editing cell mounts — it owns the field, the keys and the blur
+ * policy; the editor inside it (a built-in picked by `meta.type`, or the
+ * column's `meta.editor`) owns the input.
+ *
+ * The form outlives this component by design: scrolling the row away
+ * unmounts the host, and the form in the engine's map keeps the draft.
+ */
+export function TMDataGridCellEditor({
+  cell,
+  row,
+  takeSeedText,
+  autoFocus = true,
+  onClose,
+}: {
+  cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>;
+  row: Row<TMDataGridFeatures, TMDataGridRowData>;
+  /** Consumes the pending type-to-edit seed, when typing opened this editor. */
+  takeSeedText: () => string | undefined;
+  /** In row mode only the first editable cell takes the focus. */
+  autoFocus?: boolean;
+  /** After the editor closed itself — the table moves the focus. */
+  onClose: (args: TMDataGridCellEditorClose) => void;
+}) {
+  const { table, edit, features, labels, controlSize } = useTMDataGridContext();
+  // Row mode mounts one host per editable cell of the row; every key that
+  // commits or cancels acts on the whole row's form either way, but Tab must
+  // stay the browser's (it walks the row's inputs) and blur must do nothing
+  // (focus moves between this row's own editors).
+  const isRowMode = features.editMode === "row";
+  const column = cell.column;
+  const form = edit.getForm(row.id);
+  const fieldName = getEditFieldName(column);
+  const [seedText] = useState(() => takeSeedText());
+
+  // One FieldApi per open editor, over the row's long-lived form. Created
+  // imperatively (the documented core usage) because the form was too.
+  const [field] = useState<TMDataGridEditField>(
+    () =>
+      new FieldApi({
+        form: form as never,
+        name: fieldName as never,
+        validators: normalizeFieldValidate(
+          column.columnDef.meta?.validate,
+        ) as never,
+      }) as unknown as TMDataGridEditField,
+  );
+  useEffect(() => field.mount(), [field]);
+
+  // Type-to-edit: the seed replaces the value, as it does in a spreadsheet.
+  // Only for the types where keystrokes are the input.
+  useEffect(() => {
+    if (seedText === undefined) return;
+    const type = column.columnDef.meta?.type ?? "string";
+    if (type === "string") {
+      field.handleChange(seedText as never);
+    } else if (type === "number") {
+      const seeded = Number(seedText);
+      if (Number.isFinite(seeded)) field.handleChange(seeded as never);
+    }
+    // Once, at open.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const closingRef = useRef(false);
+
+  const commitAndClose = async (
+    via: "enter" | "tab" | "shift-tab" | "pick",
+  ): Promise<boolean> => {
+    if (closingRef.current) return false;
+    const ok = await edit.commit(row.id);
+    if (ok && !closingRef.current) {
+      closingRef.current = true;
+      onClose({ committed: true, via });
+    }
+    return ok;
+  };
+
+  const cancelAndClose = () => {
+    if (closingRef.current) return;
+    closingRef.current = true;
+    edit.cancel(row.id);
+    onClose({ committed: false, via: "escape" });
+  };
+
+  /** Batch: the key closes the editor and leaves the draft for submitAll. */
+  const deferAndClose = (via: "defer" | "defer-tab" | "defer-shift-tab") => {
+    if (closingRef.current) return;
+    closingRef.current = true;
+    edit.deactivate();
+    onClose({ committed: false, via });
+  };
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    const isBatch = features.editMode === "batch";
+    if (event.key === "Enter") {
+      event.preventDefault();
+      event.stopPropagation();
+      // In row mode Enter (and Ctrl+Enter, the documented pair) saves the
+      // row; in batch nothing commits until submitAll, so Enter just parks
+      // the draft.
+      if (isBatch) deferAndClose("defer");
+      else void commitAndClose("enter");
+    } else if (event.key === "Escape") {
+      event.preventDefault();
+      event.stopPropagation();
+      cancelAndClose();
+    } else if (event.key === "Tab" && !isRowMode) {
+      event.preventDefault();
+      event.stopPropagation();
+      if (isBatch) {
+        deferAndClose(event.shiftKey ? "defer-shift-tab" : "defer-tab");
+      } else {
+        void commitAndClose(event.shiftKey ? "shift-tab" : "tab");
+      }
+    }
+  };
+
+  /**
+   * Focus left the editor entirely — a click somewhere else. Under `"cell"`
+   * that commits (Sheets); a commit blocked by validation keeps the form and
+   * its invalid marker, with the editor closed. The confirming modes keep
+   * the draft open-but-inactive, waiting for their explicit ✓.
+   */
+  const handleBlur = (event: FocusEvent<HTMLDivElement>) => {
+    if (closingRef.current) return;
+    // Row mode: the row's other editors are outside this host, and focus
+    // moving between them is not leaving the edit. Blur means nothing here;
+    // the lane's Save/Cancel and the keys end the edit.
+    if (isRowMode) return;
+    const next = event.relatedTarget;
+    if (next instanceof Node && event.currentTarget.contains(next)) return;
+    closingRef.current = true;
+    if (features.editMode === "cell") {
+      void edit.commit(row.id).then((ok) => {
+        if (!ok) edit.deactivate();
+      });
+    } else {
+      // cellConfirm: the draft stays, dirty-marked, waiting for its ✓.
+      edit.deactivate();
+    }
+  };
+
+  if (form === undefined || fieldName === null) return null;
+
+  const args: TMDataGridEditorArgs = {
+    field,
+    form,
+    cell,
+    row,
+    column,
+    table,
+    commit: () => commitAndClose("pick"),
+    cancel: cancelAndClose,
+    size: controlSize,
+    autoFocus,
+    seedText,
+  };
+
+  const Editor =
+    column.columnDef.meta?.editor ??
+    BUILT_IN_EDITORS[column.columnDef.meta?.type ?? "string"] ??
+    TMDataGridStringEditor;
+
+  return (
+    <div
+      className={classes.cellEditor}
+      data-dg-part="editor"
+      data-row-id={row.id}
+      data-column-id={column.id}
+      onKeyDown={handleKeyDown}
+      onBlur={handleBlur}
+      // The cell underneath listens for selection gestures; a click inside
+      // the editor is about the editor.
+      onMouseDown={(event) => event.stopPropagation()}
+      onDoubleClick={(event) => event.stopPropagation()}
+    >
+      <Editor {...args} />
+      {/* cellConfirm's chrome: the draft only commits through the ✓ (or
+          Enter), so the pair sits right beside the input. */}
+      {features.editMode === "cellConfirm" && (
+        <div className={classes.cellEditorActions}>
+          <ActionIcon
+            size="sm"
+            variant="subtle"
+            color="green"
+            aria-label={labels.confirmEdit}
+            data-dg-part="editor-confirm"
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={() => void commitAndClose("pick")}
+          >
+            <CheckIcon size={14} stroke={2} />
+          </ActionIcon>
+          <ActionIcon
+            size="sm"
+            variant="subtle"
+            color="gray"
+            aria-label={labels.cancelEdit}
+            data-dg-part="editor-cancel"
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={cancelAndClose}
+          >
+            <CloseIcon size={14} stroke={2} />
+          </ActionIcon>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/tmdatagrid/components/TMDataGridColumnsPanel.tsx

@@ -1,10 +1,18 @@
-import { Button, Checkbox, ScrollArea, Text, TextInput } from "@mantine/core";
+import {
+  Button,
+  Checkbox,
+  ScrollArea,
+  Text,
+  TextInput,
+  Tooltip,
+} from "@mantine/core";
 import { useSelector } from "@tanstack/react-store";
 import { useState } from "react";
 import classes from "./TMDataGridColumnsPanel.module.css";
 import { useTMDataGridContext } from "../TMDataGridContext";
 import { getColumnLabel } from "../core/columnUtils";
 import { GROUP_COLUMN_ID } from "./TMDataGridGroupColumn";
+import { ROW_NUMBER_COLUMN_ID } from "./TMDataGridRowNumberColumn";
 import { SearchIcon } from "./icons";
 
 /**
@@ -13,7 +21,7 @@ import { SearchIcon } from "./icons";
  * `TMDataGrid.ColumnsButton`.
  */
 export function TMDataGridColumnsPanel() {
-  const { table, labels, controlSize } = useTMDataGridContext();
+  const { table, labels, controlSize, resetSettings } = useTMDataGridContext();
   const [search, setSearch] = useState("");
 
   const columnVisibility = useSelector(
@@ -23,10 +31,14 @@ export function TMDataGridColumnsPanel() {
 
   // The tree column is left out rather than listed and disabled: its visibility
   // is not a setting at all, it follows the grouping state, so an unchecked box
-  // that cannot be ticked would only invite the question.
+  // that cannot be ticked would only invite the question. The row-number
+  // gutter follows `enableRowNumbers` the same way.
   const columns = table
     .getAllLeafColumns()
-    .filter((column) => column.id !== GROUP_COLUMN_ID);
+    .filter(
+      (column) =>
+        column.id !== GROUP_COLUMN_ID && column.id !== ROW_NUMBER_COLUMN_ID,
+    );
   const needle = search.trim().toLowerCase();
   const visibleInPanel = needle
     ? columns.filter((column) =>
@@ -40,7 +52,7 @@ export function TMDataGridColumnsPanel() {
   ).length;
 
   return (
-    <div className={classes.columnsPanel}>
+    <div data-dg-part="columns-panel" className={classes.columnsPanel}>
       <div className={classes.columnsPanelSearch}>
         <TextInput
           value={search}
@@ -48,6 +60,7 @@ export function TMDataGridColumnsPanel() {
           placeholder={labels.columnsSearchPlaceholder}
           leftSection={<SearchIcon size={16} stroke={1.6} />}
           size={controlSize}
+          data-dg-part="columns-search"
           data-autofocus
         />
       </div>
@@ -59,6 +72,8 @@ export function TMDataGridColumnsPanel() {
               key={column.id}
               size={controlSize}
               label={getColumnLabel(column)}
+              data-dg-part="columns-toggle"
+              data-column-id={column.id}
               disabled={!column.getCanHide()}
               checked={columnVisibility[column.id] !== false}
               onChange={(event) =>
@@ -78,19 +93,27 @@ export function TMDataGridColumnsPanel() {
         <Checkbox
           size={controlSize}
           label={labels.columnsShowHideAll}
+          data-dg-part="columns-toggle-all"
           checked={shownCount === hideableColumns.length}
           indeterminate={shownCount > 0 && shownCount < hideableColumns.length}
           onChange={(event) =>
             table.toggleAllColumnsVisible(event.currentTarget.checked)
           }
         />
-        <Button
-          variant="subtle"
-          size="compact-sm"
-          onClick={() => table.resetColumnVisibility()}
-        >
-          {labels.columnsReset}
-        </Button>
+        {/* The whole layout, not only visibility: one reset with an honest
+            scope, stated in the tooltip. `table.resetColumnVisibility()` would
+            also be wrong under persistence — it resets to `initialState`,
+            which the mount built *from* the persisted payload. */}
+        <Tooltip label={labels.columnsResetHint} withArrow>
+          <Button
+            variant="subtle"
+            size="compact-sm"
+            data-dg-part="columns-reset"
+            onClick={() => resetSettings()}
+          >
+            {labels.columnsReset}
+          </Button>
+        </Tooltip>
       </div>
     </div>
   );

package/src/tmdatagrid/components/TMDataGridDetailsColumn.tsx

@@ -42,6 +42,8 @@ function DetailsCell<TData extends RowData>({
       tabIndex={tabIndex}
       aria-expanded={expanded}
       aria-label={expanded ? labels.hideDetails : labels.showDetails}
+      data-dg-part="details-toggle"
+      data-row-id={row.id}
       // The row underneath may select or highlight on click; opening a panel is
       // its own gesture and must not also trigger those.
       onClick={(event) => {
@@ -90,6 +92,7 @@ function DetailsHeader<TData extends RowData>({
       aria-label={
         allExpanded ? labels.collapseAllDetails : labels.expandAllDetails
       }
+      data-dg-part="details-toggle-all"
       // Partly expanded opens the rest rather than closing what is already
       // open — the same reading as an indeterminate select-all box.
       onClick={() =>

package/src/tmdatagrid/components/TMDataGridEditActions.tsx

@@ -0,0 +1,62 @@
+import { Button, Group } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import { useTMDataGridContext } from "../TMDataGridContext";
+
+/**
+ * Batch 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 `editMode` — a
+ * cellConfirm grid accumulating drafts can offer the same pair — and renders
+ * nothing while editing is off.
+ *
+ * ```tsx
+ * <TMDataGrid.Toolbar>
+ *   <TMDataGrid.SummaryCount />
+ *   <TMDataGrid.Spacer />
+ *   <TMDataGrid.EditActions />
+ * </TMDataGrid.Toolbar>
+ * ```
+ */
+export function TMDataGridEditActions() {
+  const { edit, features, labels } = useTMDataGridContext();
+  // Everything pending counts: dirty edits, entry rows (an add is pending
+  // whether or not it was touched), and deletion marks.
+  const dirtyCount = 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,
+  );
+  const isSubmitting = useSelector(edit.store, (state) =>
+    state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
+  );
+
+  if (!features.editing) return null;
+
+  return (
+    <Group gap="xs" wrap="nowrap">
+      <Button
+        size="compact-sm"
+        disabled={dirtyCount === 0}
+        loading={isSubmitting}
+        data-dg-part="save-all"
+        onClick={() => void edit.submitAll()}
+      >
+        {labels.saveAllEdits(dirtyCount)}
+      </Button>
+      <Button
+        variant="subtle"
+        color="gray"
+        size="compact-sm"
+        disabled={dirtyCount === 0}
+        data-dg-part="discard-all"
+        onClick={() => edit.cancelAll()}
+      >
+        {labels.discardAllEdits}
+      </Button>
+    </Group>
+  );
+}

package/src/tmdatagrid/components/TMDataGridEditColumn.tsx

@@ -0,0 +1,237 @@
+import { ActionIcon, Group, Loader, Tooltip } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import {
+  useCellControlTabIndex,
+  useTMDataGridContext,
+} from "../TMDataGridContext";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+import { firstErrorText } from "./editors/editorShared";
+import {
+  CheckIcon,
+  CloseIcon,
+  PencilIcon,
+  RestoreIcon,
+  TrashIcon,
+} from "./icons";
+
+export const EDIT_COLUMN_ID = "__edit__";
+
+/**
+ * One row's slot in the edit lane. Three states, driven off the edit store:
+ * 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 and puts the
+ * message in its tooltip — the pathless `.refine()` has nowhere else to land.
+ */
+function EditLaneCell<TData extends RowData>({
+  row,
+}: {
+  row: Row<TMDataGridFeatures, TData>;
+}) {
+  const { edit, features, labels } = useTMDataGridContext();
+  const tabIndex = useCellControlTabIndex();
+  const rowId = row.id;
+  const isOpen = useSelector(edit.store, (state) =>
+    state.openRowIds.includes(rowId),
+  );
+  const projection = useSelector(edit.store, (state) => state.rows[rowId]);
+  const isNew = useSelector(edit.store, (state) =>
+    state.newRows.some((newRow) => newRow.tempId === rowId),
+  );
+  const isMarkedDeleted = useSelector(edit.store, (state) =>
+    state.deletedRowIds.includes(rowId),
+  );
+
+  if (row.getIsGrouped()) return null;
+
+  // An entry row: ✓ adds it (not under batch, where submitAll does), ✕
+  // discards the entry.
+  if (isNew) {
+    return (
+      <Group gap={0} wrap="nowrap">
+        {features.editMode !== "batch" && (
+          <ActionIcon
+            variant="subtle"
+            color="green"
+            size="sm"
+            tabIndex={tabIndex}
+            aria-label={labels.confirmNewRow}
+            data-dg-part="confirm-new-row"
+            data-row-id={rowId}
+            onClick={() => void edit.commit(rowId)}
+          >
+            <CheckIcon size={16} stroke={2} />
+          </ActionIcon>
+        )}
+        <ActionIcon
+          variant="subtle"
+          color="gray"
+          size="sm"
+          tabIndex={tabIndex}
+          aria-label={labels.discardNewRow}
+          data-dg-part="discard-new-row"
+          data-row-id={rowId}
+          onClick={() => edit.cancel(rowId)}
+        >
+          <CloseIcon size={16} stroke={1.6} />
+        </ActionIcon>
+      </Group>
+    );
+  }
+
+  // A batch deletion mark is a draft like any other — restorable in place.
+  if (isMarkedDeleted) {
+    return (
+      <ActionIcon
+        variant="subtle"
+        color="gray"
+        size="sm"
+        tabIndex={tabIndex}
+        aria-label={labels.restoreRow}
+        data-dg-part="restore-row"
+        data-row-id={rowId}
+        onClick={(event) => {
+          event.stopPropagation();
+          edit.deleteRow(rowId);
+        }}
+      >
+        <RestoreIcon size={16} stroke={1.6} />
+      </ActionIcon>
+    );
+  }
+
+  // The pencil means "this row edits"; a row that does not gets nothing.
+  if (!edit.canEditRow(row as never)) return null;
+
+  if (!isOpen) {
+    return (
+      <Group gap={0} wrap="nowrap">
+        {features.editMode === "row" && (
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            size="sm"
+            tabIndex={tabIndex}
+            aria-label={labels.editRow}
+            data-dg-part="edit-row"
+            data-row-id={rowId}
+            onClick={(event) => {
+              event.stopPropagation();
+              edit.begin({ rowId, columnId: null });
+            }}
+          >
+            <PencilIcon size={16} stroke={1.6} />
+          </ActionIcon>
+        )}
+        {edit.canDeleteRows() && (
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            size="sm"
+            tabIndex={tabIndex}
+            aria-label={labels.deleteRow}
+            data-dg-part="delete-row"
+            data-row-id={rowId}
+            onClick={(event) => {
+              event.stopPropagation();
+              edit.deleteRow(rowId);
+            }}
+          >
+            <TrashIcon size={16} stroke={1.6} />
+          </ActionIcon>
+        )}
+      </Group>
+    );
+  }
+
+  if (projection?.isSubmitting) {
+    return <Loader size="xs" aria-label={labels.loading} />;
+  }
+
+  const hasErrors =
+    projection !== undefined &&
+    (projection.hasRowError || projection.errorFields.length > 0);
+  const rowError = hasErrors
+    ? (firstErrorText(edit.getForm(rowId)?.state.errors ?? []) ??
+      labels.editRowErrors)
+    : null;
+
+  const save = (
+    <ActionIcon
+      variant="subtle"
+      color={hasErrors ? "red" : "green"}
+      size="sm"
+      tabIndex={tabIndex}
+      aria-label={labels.saveRow}
+      data-dg-part="save-row"
+      data-row-id={rowId}
+      onClick={(event) => {
+        event.stopPropagation();
+        void edit.commit(rowId);
+      }}
+    >
+      <CheckIcon size={16} stroke={2} />
+    </ActionIcon>
+  );
+
+  return (
+    <Group gap={0} wrap="nowrap">
+      {rowError === null ? (
+        save
+      ) : (
+        <Tooltip label={rowError} withArrow>
+          {save}
+        </Tooltip>
+      )}
+      <ActionIcon
+        variant="subtle"
+        color="gray"
+        size="sm"
+        tabIndex={tabIndex}
+        aria-label={labels.cancelRowEdit}
+        data-dg-part="cancel-row"
+        data-row-id={rowId}
+        onClick={(event) => {
+          event.stopPropagation();
+          edit.cancel(rowId);
+        }}
+      >
+        <CloseIcon size={16} stroke={1.6} />
+      </ActionIcon>
+    </Group>
+  );
+}
+
+/**
+ * The generated edit lane, appended and pinned right under
+ * `editMode: "row"` — the row's Save at the end of the row, mirroring the
+ * checkbox lane's build on the left.
+ */
+export function createEditColumn<TData extends RowData>(
+  label = "Edit",
+): ColumnDef<TMDataGridFeatures, TData, unknown> {
+  return {
+    id: EDIT_COLUMN_ID,
+    meta: {
+      label,
+      align: "center",
+      enableOrdering: false,
+    },
+    // Wide enough for the Save/Cancel pair it holds while editing.
+    size: 64,
+    minSize: 64,
+    maxSize: 64,
+    enableResizing: false,
+    enableSorting: false,
+    enableColumnFilter: false,
+    enableGlobalFilter: false,
+    // Structurally pinned to the right; not movable.
+    enablePinning: false,
+    header: () => null,
+    cell: ({ row }) => <EditLaneCell row={row} />,
+    // Group rows: same reasoning as the checkbox lane — without this the
+    // cell renders blank on aggregated rows, but here blank is also correct,
+    // so the aggregated cell renders the same (null for groups).
+    aggregatedCell: ({ row }) => <EditLaneCell row={row} />,
+  };
+}