@jielga/tmdatagrid 1.0.2 → 1.1.1

package/skills/rows/SKILL.md

@@ -6,17 +6,18 @@ description: >
   highlight as state of its own with defaultHighlightedRowId and
   onHighlightedRowChange, showSelectedBackground and --dg-row-selected-bg,
   reading a selection through the table store, onRowClick / onCellClick /
-  onCellDoubleClick / onCellContextMenu, the rowContextMenu render prop and
-  rowContextMenuProps, per-row styling with rowStyle, rowClassName, striped and
-  the --row-bg rule, the row details panel through renderDetails and
-  DETAILS_COLUMN_ID, row pinning with enableRowPinning and row.pin, and the
-  row-number gutter through enableRowNumbers. Load when selecting rows, reacting
-  to a click, opening a detail panel, colouring rows by their data, pinning rows
-  to an edge, or numbering them.
+  onCellDoubleClick / onCellContextMenu, the renderRowContextMenu slot with its
+  internalItems handback, renderColumnMenuItems and rowContextMenuProps, per-row
+  styling with rowStyle, rowClassName, striped and the --row-bg rule, the row
+  details panel through renderDetails and DETAILS_COLUMN_ID, row pinning with
+  enableRowPinning and row.pin, and the row-number gutter through
+  enableRowNumbers. Load when selecting rows, reacting to a click, opening a
+  detail panel, colouring rows by their data, pinning rows to an edge, or
+  numbering them.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.0.2'
+  library_version: '1.1.1'
 sources:
   - 'Jielga/TMDataGrid:src/docs/row-selection.md'
   - 'Jielga/TMDataGrid:src/docs/row-interaction.md'
@@ -117,7 +118,7 @@ not replace selection or the highlight; yours runs in addition.
 | `onRowClick` | `row` | Rows show a pointer cursor when set |
 | `onCellClick` | `{ cell, row, column, event }` | The cell cursor still moves |
 | `onCellDoubleClick` | same | A double-click that opens an editor still does |
-| `onCellContextMenu` | same | `rowContextMenu` still opens |
+| `onCellContextMenu` | same | `renderRowContextMenu` still opens |
 
 ```tsx
 <TMDataGrid.Table<Employee> onRowClick={(row) => open(row.original.id)} />
@@ -127,13 +128,13 @@ Pass the row type, as above, and `row.original` is typed. Group rows sit out all
 four: TanStack builds a group row on top of its first child's record, so a
 handler would receive a real-looking row that is the wrong one.
 
-`rowContextMenu` is a render prop saying what goes inside the menu. The grid
+`renderRowContextMenu` is a slot saying what goes inside the menu. The grid
 owns the Mantine `Menu`, opening it at the pointer and closing it on Escape, an
 outside click, a body scroll and after an item is picked.
 
 ```tsx
 <TMDataGrid.Table<Employee>
-  rowContextMenu={({ table, row, cell }) => (
+  renderRowContextMenu={({ table, row, cell }) => (
     <>
       <Menu.Label>{row.original.firstName}</Menu.Label>
       <Menu.Item onClick={() => open(row.original.id)}>Open</Menu.Item>
@@ -156,6 +157,35 @@ a pure function of its arguments and do the work in the item handlers. Return
 the row with `data-context-menu` while its menu is open, so an action meant for
 a multi-selection reads `table` and falls back to the clicked row.
 
+Under `cellSelection: "range"` the grid has its own items for this menu - copy,
+export, include headers. `internalItems` is those items, and **reading it hands
+the composition over**: place it and the menu is exactly what you returned;
+never mention it and the grid keeps its half above a divider and yours below.
+
+```tsx
+renderRowContextMenu={({ row, internalItems }) => (
+  <>
+    <Menu.Item onClick={() => open(row.id)}>Open</Menu.Item>
+    <Menu.Divider />
+    {internalItems}
+  </>
+)}
+```
+
+`renderColumnMenuItems` is the same idea for a column's menu, and returns an
+array rather than a node:
+
+```tsx
+<TMDataGrid.Table
+  renderColumnMenuItems={({ column, internalItems }) => [
+    ...internalItems,
+    <Menu.Item key="stats" onClick={() => showStats(column.id)}>Stats</Menu.Item>,
+  ]}
+/>
+```
+
+Returning an empty list leaves the column with no menu button at all.
+
 ## Row styling
 
 ```tsx
@@ -219,10 +249,15 @@ const grid = useTMDataGrid({
 });
 ```
 
-There is no built-in pin gesture - pin from wherever suits, most naturally the
-row context menu, through TanStack's own `row.pin("top" | "bottom" | false)`,
-`row.getIsPinned()` and `row.getCanPin()`. Pinned rows leave the scrolling order
-and render in sticky blocks: top under the header, bottom above the summary row.
+There is no built-in pin gesture and no pin icon - build one from TanStack's own
+`row.pin("top" | "bottom" | false)`, `row.getIsPinned()` and `row.getCanPin()`,
+either as a display column whose cell is a pin button or in the row context
+menu. Read the pinned state through a subscription
+(`useSelector(row.table.store, () => row.getIsPinned())`) rather than calling it
+in a component body: the `row` identity survives a pin, so the React Compiler
+would cache the call and the icon would never change. Whichever gesture you
+build, put unpin in it too. Pinned rows leave the scrolling order and render in
+sticky blocks: top under the header, bottom above the summary row.
 
 Pinned rows are still body rows - selection, editing, details, the context menu
 and per-row styling all behave normally. What they sit out are the statements

package/skills/rows/references/rows-api.md

@@ -31,11 +31,12 @@ All are props of `TMDataGrid.Table`, not hook options.
 | `onCellClick` | `(args) => void` | Cell click. `args` is `TMDataGridCellEventArgs`. |
 | `onCellDoubleClick` | `(args) => void` | Cell double-click. |
 | `onCellContextMenu` | `(args) => void` | Cell right-click. |
-| `rowContextMenu` | `({ table, row, cell, close }) => ReactNode` | Contents of the row's context menu. `null` for no menu. |
+| `renderRowContextMenu` | `({ table, row, cell, close, internalItems }) => ReactNode` | Contents of the row's context menu. `null` for no menu. Reading `internalItems` hands the composition over. |
+| `renderColumnMenuItems` | `({ column, table, internalItems }) => ReactNode[]` | Contents of a column's menu. An empty list removes the button. |
 | `rowContextMenuProps` | `MenuProps` | Passed to the Mantine `Menu` untouched apart from its open state. |
 
 `TMDataGridCellEventArgs` is `{ cell, row, column, event }`. The context-menu
-render prop's `cell` is `null` only when a custom cell renderer stopped the
+slot's `cell` is `null` only when a custom cell renderer stopped the
 event. One `Menu` serves the whole body: a closed Mantine `Popover` still runs
 its hooks on every render, and the virtualized body re-renders every scroll
 frame.

package/skills/server-side/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.0.2'
+  library_version: '1.1.1'
 sources:
   - 'Jielga/TMDataGrid:src/docs/server-side.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'

package/skills/testing/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '1.0.2'
+  library_version: '1.1.1'
 sources:
   - 'Jielga/TMDataGrid:src/docs/testing.md'
   - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGrid.tsx'

package/src/tmdatagrid/components/TMDataGridCellEditor.tsx

@@ -64,7 +64,7 @@ export function TMDataGridCellEditor({
   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. */
+  /** @deprecated The grid places the caret; see `TMDataGridEditorArgs`. */
   autoFocus?: boolean;
   /** After the editor closed itself - the table moves the focus. */
   onClose: (args: TMDataGridCellEditorClose) => void;

package/src/tmdatagrid/components/TMDataGridEditActions.tsx

@@ -1,7 +1,124 @@
 import { Button, Group } 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.
+ */
+function usePendingCount(): 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,
+  );
+}
+
+/*
+ * 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 pendingCount = usePendingCount();
+  const isSubmitting = useSelector(edit.store, (state) =>
+    state.openRowIds.some((rowId) => state.rows[rowId]?.isSubmitting === true),
+  );
+
+  return (
+    <Button
+      size="compact-sm"
+      disabled={pendingCount === 0}
+      loading={isSubmitting}
+      data-dg-part="save-all"
+      onClick={() => void edit.submitAll()}
+    >
+      {labels.saveAllEdits(pendingCount)}
+    </Button>
+  );
+}
+
+function EditDiscardButton() {
+  const { edit, labels } = useTMDataGridContext();
+  const pendingCount = usePendingCount();
+
+  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,
+};
+
+/** What the edit chrome is showing. */
+export type TMDataGridEditActionsState = {
+  /** Rows with unsaved work: dirty edits, entry rows, and deletion marks. */
+  pendingCount: number;
+  /** Whether a submit is in flight. */
+  isSubmitting: boolean;
+};
+
+/** What the edit chrome can do. */
+export type TMDataGridEditActionsActions = {
+  /** Commits every open row. Resolves `false` when a row stayed open. */
+  save: () => Promise<boolean>;
+  /** Drops every draft. */
+  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: () => ReactNode;
+  /** Discard, disabled while nothing is pending. */
+  Discard: () => 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.pendingCount > 0 && <Badge>{state.pendingCount}</Badge>}
+   *       <Controls.Save />
+   *       <Controls.Discard />
+   *     </Group>
+   *   )}
+   * />
+   * ```
+   */
+  renderActions?: (args: TMDataGridEditActionsSlotArgs) => ReactNode;
+};
+
 /**
  * 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
@@ -17,46 +134,29 @@ import { useTMDataGridContext } from "../TMDataGridContext";
  * </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,
-  );
+export function TMDataGridEditActions({
+  renderActions,
+}: TMDataGridEditActionsProps = {}) {
+  const { edit, features } = useTMDataGridContext();
+  const pendingCount = usePendingCount();
   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: { pendingCount, isSubmitting },
+      actions: { save: () => edit.submitAll(), discard: () => edit.cancelAll() },
+      Controls: EDIT_ACTIONS_CONTROLS,
+    });
+  }
+
   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>
+      <EditSaveButton />
+      <EditDiscardButton />
     </Group>
   );
 }