@jielga/tmdatagrid 0.2.0 → 0.3.0

package/src/tmdatagrid/components/TMDataGridTable.tsx

@@ -1,20 +1,33 @@
-import { Loader, Text } from "@mantine/core";
+import { Loader, Menu, type MenuProps, Text } from "@mantine/core";
 import {
   type Cell,
   flexRender,
   type Row,
   type RowData,
+  type Table,
 } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { useCallback, useEffect, useRef } from "react";
+import {
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
 import classes from "./TMDataGridTable.module.css";
 import sticky from "./sticky.module.css";
 import { type TMDataGridRowData, useTMDataGridContext } from "../TMDataGridContext";
 import { TMDataGridFilterPanel } from "./TMDataGridFilterPanel";
 import { TMDataGridHeaderCell } from "./TMDataGridHeaderCell";
 import { getColumnAlign } from "../core/columnUtils";
+import {
+  getDisplayedRows,
+  resolveRowSelectionClick,
+} from "../core/rowSelection";
 import { SearchIcon } from "./icons";
+import { SELECT_COLUMN_ID } from "./TMDataGridSelectColumn";
 import type { TMDataGridFeatures } from "../useTMDataGrid";
 
 /** Where a column sits relative to the pinned regions, resolved once per render. */
@@ -32,19 +45,61 @@ const UNPINNED_LAYOUT: TMDataGridColumnLayout = {
   isBoundary: false,
 };
 
+/**
+ * What a cell shows once grouping is in play.
+ *
+ * A group row carries a cell for every column, but only some of them have
+ * anything to say:
+ *
+ * | Cell | Renders |
+ * | ---- | ------- |
+ * | On a data row | the column's `cell`, as always |
+ * | Placeholder — a grouped column other than this row's own | nothing |
+ * | Aggregated, column declares `aggregatedCell` | that |
+ * | Aggregated, column declares an `aggregationFn` | the column's `cell`, over the aggregate |
+ * | Aggregated, column declares neither | nothing |
+ *
+ * That last row is the one worth spelling out. Without an aggregation function
+ * `getValue()` is `undefined` on a group row, so the column's own renderer
+ * would be handed nothing — and a renderer that formats what it gets
+ * (`value.toFixed(2)`) would throw. Blank is both the safe answer and the right
+ * one: a plain "group by" is a tree, not a summary, and a column only joins in
+ * once it has been told how.
+ */
+function renderCellContent(
+  cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>,
+) {
+  if (cell.getIsPlaceholder()) return null;
+  if (!cell.getIsAggregated()) {
+    return flexRender(cell.column.columnDef.cell, cell.getContext());
+  }
+  const { aggregatedCell, aggregationFn } = cell.column.columnDef;
+  if (aggregatedCell !== undefined) {
+    return flexRender(aggregatedCell, cell.getContext());
+  }
+  if (aggregationFn === undefined) return null;
+  return flexRender(cell.column.columnDef.cell, cell.getContext());
+}
+
 function TMDataGridBodyCell({
   cell,
   rowHeight,
   layout,
+  onContextMenu,
 }: {
   cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>;
   rowHeight: number;
   layout: TMDataGridColumnLayout;
+  onContextMenu?: (event: MouseEvent<HTMLDivElement>) => void;
 }) {
   return (
     <div
       role="cell"
       data-align={getColumnAlign(cell.column)}
+      // The checkbox lane is a fixed track, so it cannot take the cell padding
+      // the scale grows for text. See TMDataGridTable.module.css.
+      data-select-column={cell.column.id === SELECT_COLUMN_ID}
+      onContextMenu={onContextMenu}
       className={[
         classes.bodyCell,
         layout.isBoundary && layout.pinnedAt === "left" ? sticky.stickyLeft : "",
@@ -62,19 +117,135 @@ function TMDataGridBodyCell({
         zIndex: layout.pinnedAt ? 2 : undefined,
       }}
     >
-      <span className={classes.cellContent}>
-        {flexRender(cell.column.columnDef.cell, cell.getContext())}
-      </span>
+      <span className={classes.cellContent}>{renderCellContent(cell)}</span>
+    </div>
+  );
+}
+
+/**
+ * The virtualized body rows, wrapped in the single Menu that serves all of them
+ * when `rowContextMenu` is set.
+ *
+ * One instance for the whole body rather than one per row. A Mantine `Menu` is
+ * a `Popover`, and a closed Popover still runs its hooks on every render — and
+ * the body re-renders on every scroll frame, because that is how virtualization
+ * works. Wrapping each of ~20 mounted rows measured a fifth onto a body render;
+ * wrapping the group is the same behaviour for one instance.
+ *
+ * `display: contents` keeps the group out of the grid's layout while still
+ * taking the right-click, carrying `Menu.ContextMenu`'s handlers, and passing
+ * its inherited `user-select: none` down to the rows.
+ */
+function TMDataGridBodyRowGroup({
+  enabled,
+  menuContent,
+  menuProps,
+  onContextMenu,
+  onClose,
+  children,
+}: {
+  enabled: boolean;
+  menuContent: ReactNode;
+  menuProps?: Omit<MenuProps, "opened" | "onChange" | "children">;
+  onContextMenu: () => void;
+  onClose: () => void;
+  children: ReactNode;
+}) {
+  const rowGroup = (
+    <div
+      role="rowgroup"
+      style={{ display: "contents" }}
+      // Runs before Mantine's own handler, which `Menu.ContextMenu` composes on
+      // top of this one — so the row and cell are known by the time the
+      // dropdown is built and opened at the pointer.
+      onContextMenu={enabled ? onContextMenu : undefined}
+    >
+      {children}
     </div>
   );
+
+  if (!enabled) return rowGroup;
+
+  return (
+    <Menu
+      // Open only once the render prop has returned something: a row it answers
+      // `null` for never opens an empty dropdown.
+      opened={menuContent !== null}
+      onChange={(opened) => {
+        if (!opened) onClose();
+      }}
+      position="bottom-start"
+      shadow="md"
+      width={220}
+      {...menuProps}
+    >
+      <Menu.ContextMenu>{rowGroup}</Menu.ContextMenu>
+      <Menu.Dropdown>{menuContent}</Menu.Dropdown>
+    </Menu>
+  );
 }
 
+/** What a `rowContextMenu` render prop is handed for the right-clicked row. */
+export type TMDataGridRowContextMenuArgs<TData extends RowData> = {
+  table: Table<TMDataGridFeatures, TData>;
+  row: Row<TMDataGridFeatures, TData>;
+  /**
+   * The cell under the pointer. `null` only when the right-click landed on the
+   * row but on no cell — which a custom cell renderer that stops propagation
+   * can cause.
+   */
+  cell: Cell<TMDataGridFeatures, TData, unknown> | null;
+  /**
+   * Closes the menu. `Menu.Item` already closes on click (Mantine's
+   * `closeOnItemClick`), so this is for content that isn't a menu item.
+   */
+  close: () => void;
+};
+
+/**
+ * Builds the contents of a row's context menu — `Menu.Item`, `Menu.Label`,
+ * `Menu.Divider`, `Menu.Sub`, or any other node. The grid owns the `Menu` and
+ * its `Menu.Dropdown`; this fills the dropdown.
+ */
+export type TMDataGridRowContextMenu<TData extends RowData> = (
+  args: TMDataGridRowContextMenuArgs<TData>,
+) => ReactNode;
+
 export type TMDataGridTableProps<TData extends RowData> = {
   /**
    * Called when a body row is clicked. Runs in addition to row selection under
-   * `rowSelectionMode: "row"`, not instead of it.
+   * `selectionMode: "row"`, not instead of it.
    */
   onRowClick?: (row: Row<TMDataGridFeatures, TData>) => void;
+  /**
+   * Contents of the menu a right-click on a row opens, at the pointer. Return
+   * `null` to leave a row without one — the browser's own menu stays suppressed
+   * either way.
+   *
+   * ```tsx
+   * <TMDataGrid.Table<Employee>
+   *   rowContextMenu={({ row, close }) => (
+   *     <>
+   *       <Menu.Label>{row.original.firstName}</Menu.Label>
+   *       <Menu.Item onClick={() => open(row.original.id)}>Open</Menu.Item>
+   *       <Menu.Divider />
+   *       <Menu.Item color="red" onClick={() => remove(row.original.id)}>
+   *         Delete
+   *       </Menu.Item>
+   *     </>
+   *   )}
+   * />
+   * ```
+   *
+   * Called during render, and only for the row whose menu is open — so it stays
+   * a pure function of the row, and cost per row does not matter.
+   */
+  rowContextMenu?: TMDataGridRowContextMenu<TData>;
+  /**
+   * Passed to the Mantine `Menu` the grid wraps the row in — `width`, `shadow`,
+   * `position`, `transitionProps` and the rest. Its open state is the grid's.
+   */
+  rowContextMenuProps?: Omit<MenuProps, "opened" | "onChange" | "children">;
 };
 
 /**
@@ -85,12 +256,17 @@ export type TMDataGridTableProps<TData extends RowData> = {
  */
 export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   onRowClick,
+  rowContextMenu,
+  rowContextMenuProps,
 }: TMDataGridTableProps<TData>) {
-  const { table, features, rowHeight, controlSize } = useTMDataGridContext();
+  const { table, ui, features, rowHeight, controlSize } =
+    useTMDataGridContext();
 
   // The body depends on every state slice (sorting, filters, paging, sizing,
   // visibility, selection), so it subscribes to the whole table store.
   useSelector(table.store);
+  // The active row lives in the chrome store, so it needs its own subscription.
+  const highlightedRowId = useSelector(ui, (state) => state.highlightedRowId);
 
   const { loading, noResultsLabel = "No rows match your filters" } =
     table.options.meta ?? {};
@@ -99,9 +275,7 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   // Pagination off (the default): every filtered+sorted row, virtualized.
   // Pagination on: the current page; under `manualPagination` TanStack returns
   // the rows as delivered, so the same branch serves server paging.
-  const rows = features.pagination
-    ? table.getPaginatedRowModel().rows
-    : table.getPrePaginatedRowModel().rows;
+  const rows = getDisplayedRows(table, features);
 
   // A persisted pageIndex can outlive the data that produced it; TanStack only
   // auto-resets on live filter/sort/data changes, not on restored state. The
@@ -128,9 +302,15 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   const paddingBottom =
     virtualizer.getTotalSize() - (virtualItems.at(-1)?.end ?? 0);
 
-  const leftLeafColumns = table.getLeftLeafColumns();
-  const rightLeafColumns = table.getRightLeafColumns();
-  const centerLeafColumns = table.getCenterLeafColumns();
+  // The *Visible* variants throughout: `getLeftLeafColumns()` and friends
+  // include hidden columns, while the cells below come from
+  // `row.getLeftVisibleCells()`, which does not. Mixing the two would lay down
+  // a grid track for a column that renders no cell, shifting every column after
+  // it out of its header. The tree column is hidden exactly this way while
+  // nothing is grouped.
+  const leftLeafColumns = table.getLeftVisibleLeafColumns();
+  const rightLeafColumns = table.getRightVisibleLeafColumns();
+  const centerLeafColumns = table.getCenterVisibleLeafColumns();
 
   const orderedColumns = [
     ...leftLeafColumns,
@@ -221,20 +401,113 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
 
   const isEmpty = rows.length === 0;
 
-  // "row" mode: the row itself is the selection control — clicking it toggles
-  // that row and leaves the rest of the selection alone.
-  const selectsOnRowClick =
-    features.rowSelection && features.rowSelectionMode === "row";
-  const rowIsInteractive = selectsOnRowClick || onRowClick !== undefined;
+  // "row" mode: the row itself is the selection control, with the modifier
+  // conventions of any desktop list — see resolveRowSelectionClick.
+  const selectsOnRowClick = features.rowClickSelects;
+  const rowIsInteractive =
+    selectsOnRowClick || features.highlightRow || onRowClick !== undefined;
 
-  const handleRowActivate = (row: Row<TMDataGridFeatures, TMDataGridRowData>) => {
-    if (selectsOnRowClick && row.getCanSelect()) row.toggleSelected();
+  /**
+   * Group rows sit out every row-level gesture.
+   *
+   * Not squeamishness: TanStack builds a group row on top of its first leaf's
+   * record (`constructRow(table, id, leafRows[0].original, …)`), so an
+   * `onRowClick` firing here would hand a consumer a real-looking row that is
+   * the wrong one — a detail panel would open on an arbitrary child. The same
+   * goes for the highlight, which is what a detail panel follows.
+   *
+   * Selecting a group is still possible, through its checkbox, which resolves
+   * to the descendants rather than to the group itself. See
+   * getSelectableRowIds.
+   */
+  const rowGesturesFor = (row: Row<TMDataGridFeatures, TMDataGridRowData>) =>
+    row.getIsGrouped() ? false : rowIsInteractive;
+
+  const handleRowActivate = (
+    row: Row<TMDataGridFeatures, TMDataGridRowData>,
+    modifiers: { toggle: boolean; extend: boolean },
+  ) => {
+    if (selectsOnRowClick && row.getCanSelect()) {
+      const resolved = resolveRowSelectionClick({
+        rows,
+        rowId: row.id,
+        anchorRowId: ui.state.selectionAnchorRowId,
+        modifiers,
+        selection: table.store.state.rowSelection,
+        canReplaceSelection: true,
+      });
+      table.setRowSelection(resolved.selection);
+      ui.actions.setSelectionAnchor(resolved.anchorRowId);
+    }
+    // Set, never toggle: a second click on the highlighted row must not close
+    // the detail panel showing it. Clearing is
+    // `ui.actions.setHighlightedRow(null)`.
+    if (features.highlightRow) ui.actions.setHighlightedRow(row.id);
     onRowClick?.(row as unknown as Row<TMDataGridFeatures, TData>);
   };
 
+  // Which row's context menu is open, and which cell it was opened from.
+  const [contextMenuTarget, setContextMenuTarget] = useState<{
+    rowId: string;
+    columnId: string | null;
+  } | null>(null);
+  const closeContextMenu = () => setContextMenuTarget(null);
+
+  // Row and cell each record themselves on the way up, so that by the time the
+  // rowgroup's handler opens the menu it knows what was hit. Refs rather than
+  // state: written and read inside the same event, before the render it causes.
+  const contextMenuRowRef = useRef<string | null>(null);
+  const contextMenuColumnRef = useRef<string | null>(null);
+
+  const handleContextMenu = () => {
+    const rowId = contextMenuRowRef.current;
+    const columnId = contextMenuColumnRef.current;
+    contextMenuRowRef.current = null;
+    contextMenuColumnRef.current = null;
+    setContextMenuTarget(rowId === null ? null : { rowId, columnId });
+  };
+
+  const contextMenuRow =
+    contextMenuTarget === null
+      ? undefined
+      : rows.find((row) => row.id === contextMenuTarget.rowId);
+
+  /**
+   * Built for the open row only, so a consumer's render prop is called once per
+   * opened menu rather than once per mounted row. `null` back from it means
+   * this row has no menu, which is also how the menu stays shut.
+   *
+   * The casts put back the concrete row type the context boundary erased — the
+   * same crossing `onRowClick` makes.
+   */
+  const contextMenuContent =
+    rowContextMenu && contextMenuTarget && contextMenuRow
+      ? rowContextMenu({
+          table: table as unknown as Table<TMDataGridFeatures, TData>,
+          row: contextMenuRow as unknown as Row<TMDataGridFeatures, TData>,
+          cell: (contextMenuRow
+            .getAllCells()
+            .find((cell) => cell.column.id === contextMenuTarget.columnId) ??
+            null) as unknown as Cell<TMDataGridFeatures, TData, unknown> | null,
+          close: closeContextMenu,
+        }) ?? null
+      : null;
+
+  /**
+   * The dropdown is anchored to a fixed viewport point, so it does not travel
+   * with the row when the body scrolls — and under virtualization the row it
+   * belongs to may unmount entirely. Closing is the honest answer, and matches
+   * what every desktop context menu does.
+   */
+  const handleScroll = contextMenuTarget ? closeContextMenu : undefined;
+
   return (
     <div className={classes.tableWrapper}>
-      <div ref={scrollContainerRef} className={classes.scrollContainer}>
+      <div
+        ref={scrollContainerRef}
+        className={classes.scrollContainer}
+        onScroll={handleScroll}
+      >
         <div
           role="table"
           className={classes.grid}
@@ -268,43 +541,127 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
             <div aria-hidden style={{ gridColumn: "1/-1", height: paddingTop }} />
           )}
 
-          <div role="rowgroup" style={{ display: "contents" }}>
+          <TMDataGridBodyRowGroup
+            enabled={rowContextMenu !== undefined}
+            menuContent={contextMenuContent}
+            menuProps={rowContextMenuProps}
+            onContextMenu={handleContextMenu}
+            onClose={closeContextMenu}
+          >
             {virtualItems.map((virtualItem) => {
               const row = rows[virtualItem.index];
               if (!row) return null;
+              const isGroupRow = row.getIsGrouped();
+              const isInteractive = rowGesturesFor(row);
+              const takesKeyboard =
+                !isGroupRow && (selectsOnRowClick || features.highlightRow);
               return (
                 <div
                   key={virtualItem.key}
                   role="row"
                   aria-rowindex={virtualItem.index + headerGroups.length + 1}
                   data-testid={`dg-row-${row.id}`}
-                  data-selected={row.getIsSelected()}
-                  // Selection is state; the highlight is a display choice, so
+                  // The tree's own rows. `data-grouped` rather than a class, to
+                  // match how the rest of the row's state is published — and so
+                  // a consumer can restyle them without reaching into modules.
+                  data-grouped={isGroupRow}
+                  data-depth={row.depth}
+                  // Gated on the flag, not just on `getIsSelected()`: under
+                  // `"highlight"` there is no selection, but `rowSelection` may
+                  // still hold ids from before the mode changed — TanStack never
+                  // prunes it — and a row must not report itself selected in a
+                  // mode where selecting is not a thing.
+                  data-selected={features.rowSelection && row.getIsSelected()}
+                  // Being selected is state; painting it is a display choice, so
                   // the two are separate attributes.
+                  data-selected-bg={
+                    features.rowSelection &&
+                    features.showSelectedBackground &&
+                    row.getIsSelected()
+                  }
+                  // The highlighted row is its own concept, so its own attribute
+                  // pair — `data-highlighted` / `aria-current` against
+                  // `data-selected` / `aria-selected` for selection. Under
+                  // `"checkboxAndHighlight"` a row can carry both.
+                  //
+                  // Not `data-active`: header cells already use that for
+                  // sorted-or-filtered, and Mantine puts it on its own controls,
+                  // so a consumer styling or querying rows by it would cast far
+                  // wider than they meant to.
                   data-highlighted={
-                    features.highlightSelectedRows && row.getIsSelected()
+                    features.highlightRow && row.id === highlightedRowId
                   }
-                  data-selects-on-click={selectsOnRowClick}
+                  // The menu is anchored to the rowgroup, so Mantine's own
+                  // `data-expanded` lands there rather than on a row. This is
+                  // what says which row the open menu is about.
+                  data-context-menu={
+                    contextMenuContent !== null &&
+                    contextMenuTarget?.rowId === row.id
+                  }
+                  data-selects-on-click={selectsOnRowClick && !isGroupRow}
                   aria-selected={
                     features.rowSelection ? row.getIsSelected() : undefined
                   }
+                  aria-current={
+                    features.highlightRow && row.id === highlightedRowId
+                      ? true
+                      : undefined
+                  }
                   className={classes.bodyRow}
                   style={{
                     minHeight: rowHeight,
-                    cursor: rowIsInteractive ? "pointer" : undefined,
+                    cursor: isInteractive ? "pointer" : undefined,
                   }}
                   // Keyboard parity with the checkbox the row replaces.
-                  tabIndex={selectsOnRowClick ? 0 : undefined}
+                  tabIndex={takesKeyboard ? 0 : undefined}
+                  // Shift-click extends the browser's text selection across
+                  // every row it passes. `user-select: none` would fix it too,
+                  // but at the cost of ever copying a cell value, so the smear
+                  // is stopped at the one gesture that causes it.
+                  onMouseDown={
+                    selectsOnRowClick && !isGroupRow
+                      ? (event) => {
+                          if (event.shiftKey) event.preventDefault();
+                        }
+                      : undefined
+                  }
                   onClick={
-                    rowIsInteractive ? () => handleRowActivate(row) : undefined
+                    isInteractive
+                      ? (event) =>
+                          handleRowActivate(row, {
+                            toggle: event.ctrlKey || event.metaKey,
+                            extend: event.shiftKey,
+                          })
+                      : undefined
                   }
                   onKeyDown={
-                    selectsOnRowClick
+                    takesKeyboard
                       ? (event) => {
                           if (event.key !== " " && event.key !== "Enter") return;
                           if (event.target !== event.currentTarget) return;
                           event.preventDefault();
-                          handleRowActivate(row);
+                          // Space/Enter toggle rather than replace, so a
+                          // keyboard-only user can still build a selection.
+                          handleRowActivate(row, {
+                            toggle: true,
+                            extend: event.shiftKey,
+                          });
+                        }
+                      : undefined
+                  }
+                  // Bubbles to the rowgroup, where the menu opens — so the row
+                  // is recorded before the dropdown is built.
+                  //
+                  // Group rows record nothing, which leaves the ref null and the
+                  // menu shut. Same reason they sit out `onRowClick`: TanStack
+                  // builds a group row on its first child's record, so a render
+                  // prop reaching for `row.original` would be handed a real
+                  // employee that has nothing to do with the group. The browser
+                  // menu stays suppressed over them either way.
+                  onContextMenu={
+                    rowContextMenu && !isGroupRow
+                      ? () => {
+                          contextMenuRowRef.current = row.id;
                         }
                       : undefined
                   }
@@ -319,12 +676,19 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                       cell={cell}
                       rowHeight={rowHeight}
                       layout={layoutFor(cell.column.id)}
+                      onContextMenu={
+                        rowContextMenu
+                          ? () => {
+                              contextMenuColumnRef.current = cell.column.id;
+                            }
+                          : undefined
+                      }
                     />
                   ))}
                 </div>
               );
             })}
-          </div>
+          </TMDataGridBodyRowGroup>
 
           {isEmpty && loading === true && (
             <div role="row" className={classes.messageRow}>

package/src/tmdatagrid/components/TMDataGridToolbar.tsx

@@ -112,6 +112,9 @@ export function TMDataGridFilterButton() {
         color={activeCount > 0 ? undefined : "gray"}
         size={controlSize}
         aria-label="Filters"
+        // Marks this as the panel's own toggle, so the panel's click-away
+        // handler leaves it alone and the button stays a toggle.
+        data-dg-filter-toggle
         onClick={() => {
           if (opened) {
             ui.actions.closeFilterPanel();

package/src/tmdatagrid/components/icons.ts

@@ -10,12 +10,17 @@ export {
   IconArrowLeft as MoveLeftIcon,
   IconArrowRight as MoveRightIcon,
   IconArrowUp as ArrowUpIcon,
+  IconChevronDown as ChevronDownIcon,
   IconChevronLeft as ChevronLeftIcon,
   IconChevronRight as ChevronRightIcon,
   IconColumns3 as ColumnsIcon,
   IconDotsVertical as DotsVerticalIcon,
   IconEyeOff as EyeOffIcon,
   IconFilter as FilterIcon,
+  IconFoldDown as ExpandAllIcon,
+  IconFoldUp as CollapseAllIcon,
+  IconIndentDecrease as UngroupIcon,
+  IconIndentIncrease as GroupIcon,
   IconArrowBarToLeft as PinLeftIcon,
   IconArrowBarToRight as PinRightIcon,
   IconMenu2 as BurgerIcon,