@jielga/tmdatagrid 0.2.0 → 0.5.0

package/src/tmdatagrid/components/TMDataGridHeaderCell.tsx

@@ -11,6 +11,7 @@ import {
 } from "../TMDataGridContext";
 import type { TMDataGridColumnLayout } from "./TMDataGridTable";
 import { getColumnCapabilities, getGridCapabilities } from "../core/capabilities";
+import { autosizeColumn } from "../core/autosize";
 import {
   getColumnRegion,
   getStepTargetColumn,
@@ -18,22 +19,32 @@ import {
   moveColumnByStep,
   type TMDataGridDropSide,
 } from "../core/columnOrdering";
-import { getColumnAlign, getColumnLabel } from "../core/columnUtils";
+import {
+  getColumnAlign,
+  getColumnLabel,
+  isControlColumn,
+} from "../core/columnUtils";
+import { resolveExpandAll } from "../core/expanding";
 import { isFilterActive } from "../core/filterOperators";
 import {
   ArrowDownIcon,
   ArrowUpIcon,
+  AutosizeIcon,
+  CollapseAllIcon,
   ColumnsIcon,
   DotsVerticalIcon,
+  ExpandAllIcon,
   EyeOffIcon,
   FilterIcon,
+  GroupIcon,
   MoveLeftIcon,
   MoveRightIcon,
   PinLeftIcon,
   PinOffIcon,
   PinRightIcon,
+  UngroupIcon,
 } from "./icons";
-import { SELECT_COLUMN_ID } from "./TMDataGridSelectColumn";
+import { GROUP_COLUMN_ID } from "./TMDataGridGroupColumn";
 import { type TMDataGridFeatures, openColumnFilter } from "../useTMDataGrid";
 
 export type TMDataGridHeader = Header<
@@ -50,9 +61,10 @@ export function TMDataGridHeaderCell({
   layout: TMDataGridColumnLayout;
 }) {
   const api = useTMDataGridContext();
-  const { table, features } = api;
+  const { table, features, labels } = api;
   const column = header.column;
   const [menuOpened, setMenuOpened] = useState(false);
+  const [contextMenuOpened, setContextMenuOpened] = useState(false);
   const [dropSide, setDropSide] = useState<TMDataGridDropSide | null>(null);
   const cellRef = useRef<HTMLDivElement>(null);
   // A resize drag ends with a click that bubbles to the header — without this
@@ -63,7 +75,7 @@ export function TMDataGridHeaderCell({
   // surrounding tree is memoized (React Compiler) or the table lives elsewhere.
   // `columnOrder` is in the list because the move menu items are derived from
   // the column's neighbours, which is exactly what an order change invalidates.
-  const { sorting, columnFilters, resizingColumnId, columnPinning } =
+  const { sorting, columnFilters, resizingColumnId, columnPinning, grouping } =
     useSelector(
       table.store,
       (state) => ({
@@ -72,6 +84,7 @@ export function TMDataGridHeaderCell({
         resizingColumnId: state.columnResizing.isResizingColumn,
         columnPinning: state.columnPinning,
         columnOrder: state.columnOrder,
+        grouping: state.grouping,
       }),
       { compare: shallow },
     );
@@ -82,6 +95,12 @@ export function TMDataGridHeaderCell({
   const align = getColumnAlign(column);
   const sortDirection = sorting.find((sort) => sort.id === column.id)?.desc;
   const isSorted = sortDirection !== undefined;
+  // 1-based position in a multi-sort, shown only while more than one column
+  // sorts — under a single sort the arrow already says everything.
+  const sortIndex =
+    isSorted && sorting.length > 1
+      ? sorting.findIndex((sort) => sort.id === column.id) + 1
+      : null;
   const isFiltered = columnFilters.some(
     (filter) => filter.id === column.id && isFilterActive(filter.value),
   );
@@ -97,9 +116,18 @@ export function TMDataGridHeaderCell({
   const canPin = isLeaf && capabilities.canPin;
   const canResize = capabilities.canResize;
   const canReorder = isLeaf && capabilities.canReorder;
+  const canGroup = isLeaf && capabilities.canGroup;
   const canManageColumns =
     isLeaf && getGridCapabilities(table, features).canHideAny;
 
+  // Read off the subscribed slice, not from `column.getIsGrouped()`: that is a
+  // call on a `column` whose identity survives a grouping change, so the React
+  // Compiler would cache the answer and the menu would keep offering to group
+  // a column that already is. Same reason the sort and filter flags above are
+  // derived from state rather than from `getIsSorted()`.
+  const isGrouped = grouping.includes(column.id);
+  const isGroupingActive = grouping.length > 0;
+
   // A column only moves inside its own pinned lane, so a header in another one
   // never lights up as a target. See TMDataGridColumnRegion.
   const isDragged = draggedColumnId === column.id;
@@ -154,6 +182,18 @@ export function TMDataGridHeaderCell({
     api.ui.actions.endColumnDrag();
   }
 
+  /**
+   * Sizes the column to its widest mounted content. The container is found
+   * from the cell rather than passed down — the header always renders inside
+   * the grid's scroll container, and that is the subtree autosize measures.
+   */
+  function autosize() {
+    const container = cellRef.current?.closest<HTMLElement>(
+      "[data-dg-scroll-container]",
+    );
+    if (container) autosizeColumn({ table, columnId: column.id, container });
+  }
+
   /**
    * Pinned columns are positioned with `getStart()` / `getAfter()`, which sum
    * `column.getSize()`. Fluid (`fr`) columns don't report their rendered width
@@ -181,14 +221,14 @@ export function TMDataGridHeaderCell({
         leftSection={<ArrowUpIcon size={16} stroke={1.6} />}
         onClick={() => column.toggleSorting(false)}
       >
-        Sort by ASC
+        {labels.sortAsc}
       </Menu.Item>,
       <Menu.Item
         key="sort-desc"
         leftSection={<ArrowDownIcon size={16} stroke={1.6} />}
         onClick={() => column.toggleSorting(true)}
       >
-        Sort by DESC
+        {labels.sortDesc}
       </Menu.Item>,
       <Menu.Divider key="sort-divider" />,
     );
@@ -200,11 +240,82 @@ export function TMDataGridHeaderCell({
         leftSection={<FilterIcon size={16} stroke={1.6} />}
         onClick={() => openColumnFilter(api, column.id)}
       >
-        Filter
+        {labels.filterMenuItem}
       </Menu.Item>,
       <Menu.Divider key="filter-divider" />,
     );
   }
+  if (canGroup) {
+    menuItems.push(
+      <Menu.Item
+        key="group"
+        className={isGrouped ? classes.menuItemActive : undefined}
+        leftSection={
+          isGrouped ? (
+            <UngroupIcon size={16} stroke={1.6} />
+          ) : (
+            <GroupIcon size={16} stroke={1.6} />
+          )
+        }
+        onClick={column.getToggleGroupingHandler()}
+      >
+        {isGrouped ? labels.ungroup(label) : labels.groupBy(label)}
+      </Menu.Item>,
+    );
+  }
+  if (isGroupingActive) {
+    // Under the default `groupedColumnMode: "remove"` a grouped column is taken
+    // out of the grid, so its own header — and the Ungroup item on it — is no
+    // longer reachable. The tree column that replaced it carries them instead,
+    // which is also where someone would look for them.
+    if (column.id === GROUP_COLUMN_ID) {
+      for (const groupedId of grouping) {
+        const groupedColumn = table.getColumn(groupedId);
+        if (!groupedColumn) continue;
+        menuItems.push(
+          <Menu.Item
+            key={`ungroup-${groupedId}`}
+            leftSection={<UngroupIcon size={16} stroke={1.6} />}
+            onClick={() => groupedColumn.toggleGrouping()}
+          >
+            {labels.ungroup(getColumnLabel(groupedColumn))}
+          </Menu.Item>,
+        );
+      }
+    }
+    // Groups only, though `expanded` also holds which rows have their detail
+    // panel open — `toggleAllRowsExpanded` would open every one of them from an
+    // item that says "groups". See resolveExpandAll.
+    const expandAllGroups = (expand: boolean) =>
+      table.setExpanded(
+        resolveExpandAll({
+          rows: table.getPrePaginatedRowModel().flatRows,
+          expanded: table.store.state.expanded,
+          target: "groups",
+          expand,
+        }),
+      );
+
+    menuItems.push(
+      <Menu.Item
+        key="expand-all"
+        leftSection={<ExpandAllIcon size={16} stroke={1.6} />}
+        onClick={() => expandAllGroups(true)}
+      >
+        {labels.expandAllGroups}
+      </Menu.Item>,
+      <Menu.Item
+        key="collapse-all"
+        leftSection={<CollapseAllIcon size={16} stroke={1.6} />}
+        onClick={() => expandAllGroups(false)}
+      >
+        {labels.collapseAllGroups}
+      </Menu.Item>,
+    );
+  }
+  if (canGroup || isGroupingActive) {
+    menuItems.push(<Menu.Divider key="group-divider" />);
+  }
   if (canPin) {
     menuItems.push(
       <Menu.Item
@@ -213,7 +324,7 @@ export function TMDataGridHeaderCell({
         leftSection={<PinLeftIcon size={16} stroke={1.6} />}
         onClick={() => setPinned(pinnedAt === "left" ? false : "left")}
       >
-        Pin to left
+        {labels.pinLeft}
       </Menu.Item>,
       <Menu.Item
         key="pin-right"
@@ -221,7 +332,7 @@ export function TMDataGridHeaderCell({
         leftSection={<PinRightIcon size={16} stroke={1.6} />}
         onClick={() => setPinned(pinnedAt === "right" ? false : "right")}
       >
-        Pin to right
+        {labels.pinRight}
       </Menu.Item>,
     );
     if (pinnedAt) {
@@ -231,7 +342,7 @@ export function TMDataGridHeaderCell({
           leftSection={<PinOffIcon size={16} stroke={1.6} />}
           onClick={() => setPinned(false)}
         >
-          Unpin
+          {labels.unpin}
         </Menu.Item>,
       );
     }
@@ -260,7 +371,7 @@ export function TMDataGridHeaderCell({
             moveColumnByStep({ table, columnId: column.id, direction: -1 })
           }
         >
-          Move left
+          {labels.moveLeft}
         </Menu.Item>,
         <Menu.Item
           key="move-right"
@@ -270,12 +381,24 @@ export function TMDataGridHeaderCell({
             moveColumnByStep({ table, columnId: column.id, direction: 1 })
           }
         >
-          Move right
+          {labels.moveRight}
         </Menu.Item>,
         <Menu.Divider key="move-divider" />,
       );
     }
   }
+  if (canResize && isLeaf) {
+    menuItems.push(
+      <Menu.Item
+        key="autosize"
+        leftSection={<AutosizeIcon size={16} stroke={1.6} />}
+        onClick={autosize}
+      >
+        {labels.autosizeColumn}
+      </Menu.Item>,
+      <Menu.Divider key="autosize-divider" />,
+    );
+  }
   if (canHide) {
     menuItems.push(
       <Menu.Item
@@ -283,7 +406,7 @@ export function TMDataGridHeaderCell({
         leftSection={<EyeOffIcon size={16} stroke={1.6} />}
         onClick={() => column.toggleVisibility(false)}
       >
-        Hide column
+        {labels.hideColumn}
       </Menu.Item>,
     );
   }
@@ -294,7 +417,7 @@ export function TMDataGridHeaderCell({
         leftSection={<ColumnsIcon size={16} stroke={1.6} />}
         onClick={() => api.ui.actions.setColumnsPanelOpen(true)}
       >
-        Manage columns
+        {labels.manageColumns}
       </Menu.Item>,
     );
   }
@@ -303,6 +426,12 @@ export function TMDataGridHeaderCell({
     menuItems.pop();
   }
 
+  // One gate for both ways into the menu — the button and the right-click —
+  // so the two can never disagree about which headers have one. A control
+  // lane's header is itself a control (select-all, expand-all), so it carries
+  // no column menu, and a right-click there falls through to the browser's.
+  const hasMenu = isLeaf && menuItems.length > 0 && !isControlColumn(column.id);
+
   const cellClass = [
     classes.headerCell,
     canSort ? classes.headerCellSortable : "",
@@ -315,13 +444,16 @@ export function TMDataGridHeaderCell({
     .filter(Boolean)
     .join(" ");
 
-  return (
+  const cell = (
     <div
       ref={cellRef}
       role="columnheader"
       data-testid={`dg-header-${column.id}`}
       data-active={isSorted || isFiltered}
       data-align={align}
+      // A control lane is a fixed track, so it cannot take the cell padding the
+      // scale grows for text. See isControlColumn.
+      data-control-column={isControlColumn(column.id)}
       // Only meaningful on a sortable column: "none" advertises that this
       // header sorts, which is a lie on one that doesn't.
       aria-sort={
@@ -347,8 +479,19 @@ export function TMDataGridHeaderCell({
         left: pinnedAt === "left" ? layout.offset : undefined,
         right: pinnedAt === "right" ? layout.offset : undefined,
         position: pinnedAt ? "sticky" : undefined,
-        zIndex: pinnedAt ? 4 : undefined,
+        // From the stacking ladder in TMDataGrid.module.css.
+        zIndex: pinnedAt ? "var(--dg-z-header-pinned-cell, 7)" : undefined,
       }}
+      // Shift+click is "add to sort", and the browser would smear a text
+      // selection across the headers it passes. Stopped at the one gesture,
+      // same as the body rows do for shift-select.
+      onMouseDown={
+        canSort
+          ? (event) => {
+              if (event.shiftKey) event.preventDefault();
+            }
+          : undefined
+      }
       onClick={
         canSort
           ? (event) => {
@@ -356,6 +499,8 @@ export function TMDataGridHeaderCell({
                 suppressSortRef.current = false;
                 return;
               }
+              // TanStack's handler reads the modifier itself: a plain click
+              // replaces the sort, Shift+click appends (`isMultiSortEvent`).
               column.getToggleSortingHandler()?.(event);
             }
           : undefined
@@ -363,7 +508,8 @@ export function TMDataGridHeaderCell({
     >
       {header.isPlaceholder ? null : (
         <Tooltip label={label} openDelay={600} withinPortal disabled={!isLeaf}>
-          <span className={classes.headerTitle}>
+          {/* `data-dg-header-title` is how autosize measures the title text. */}
+          <span className={classes.headerTitle} data-dg-header-title>
             {flexRender(column.columnDef.header, header.getContext())}
           </span>
         </Tooltip>
@@ -378,7 +524,7 @@ export function TMDataGridHeaderCell({
               variant="subtle"
               color="gray"
               size="xs"
-              aria-label={`Filter on ${label}`}
+              aria-label={labels.filterOn(label)}
               onClick={(event) => {
                 event.stopPropagation();
                 openColumnFilter(api, column.id);
@@ -395,7 +541,7 @@ export function TMDataGridHeaderCell({
               variant="subtle"
               color="gray"
               size="xs"
-              aria-label={`Sort ${label}`}
+              aria-label={labels.sortColumn(label)}
               onClick={column.getToggleSortingHandler()}
             >
               {sortDirection ? (
@@ -406,7 +552,16 @@ export function TMDataGridHeaderCell({
             </ActionIcon>
           )}
 
-          {menuItems.length > 0 && column.id !== SELECT_COLUMN_ID && (
+          {/* Shift+click adds a column to the sort (TanStack's own
+              `isMultiSortEvent`); the number is its priority. Outside the
+              hover-revealed action so an active multi-sort stays readable. */}
+          {sortIndex !== null && (
+            <span className={classes.sortIndex} data-testid="dg-sort-index">
+              {sortIndex}
+            </span>
+          )}
+
+          {hasMenu && (
             <Menu
               opened={menuOpened}
               onChange={setMenuOpened}
@@ -418,11 +573,14 @@ export function TMDataGridHeaderCell({
               <Menu.Target>
                 <ActionIcon
                   className={classes.headerAction}
-                  data-pinned-visible={menuOpened}
+                  // Held visible for the right-click menu too: that one opens at
+                  // the pointer and is portaled, so the hover that revealed the
+                  // actions is lost the moment the pointer enters the dropdown.
+                  data-pinned-visible={menuOpened || contextMenuOpened}
                   variant="subtle"
                   color="gray"
                   size="xs"
-                  aria-label={`${label} column menu`}
+                  aria-label={labels.columnMenu(label)}
                   onClick={(event) => {
                     event.stopPropagation();
                     setMenuOpened((opened) => !opened);
@@ -439,30 +597,77 @@ export function TMDataGridHeaderCell({
         </div>
       )}
 
-      <div
-        className={[
-          classes.columnSeparator,
-          canResize ? classes.columnSeparatorResizable : "",
-          isResizing ? classes.columnSeparatorActive : "",
-        ]
-          .filter(Boolean)
-          .join(" ")}
-        // Keeps a drag that starts on the separator from being picked up by the
-        // draggable header around it.
-        draggable={false}
-        onMouseDown={
-          canResize
-            ? (event) => {
-                suppressSortRef.current = true;
-                header.getResizeHandler()(event);
-              }
-            : undefined
-        }
-        onTouchStart={canResize ? header.getResizeHandler() : undefined}
-        onClick={(event) => event.stopPropagation()}
-      />
+      {/* A system lane has no separator at all: it cannot be resized, and the
+          hover line reads as a handle that does nothing — the one place the
+          separator stops being a divider and starts being a lie. */}
+      {!isControlColumn(column.id) && (
+        <div
+          className={[
+            classes.columnSeparator,
+            canResize ? classes.columnSeparatorResizable : "",
+            isResizing ? classes.columnSeparatorActive : "",
+          ]
+            .filter(Boolean)
+            .join(" ")}
+          // Keeps a drag that starts on the separator from being picked up by
+          // the draggable header around it.
+          draggable={false}
+          onMouseDown={
+            canResize
+              ? (event) => {
+                  suppressSortRef.current = true;
+                  header.getResizeHandler()(event);
+                }
+              : undefined
+          }
+          onTouchStart={canResize ? header.getResizeHandler() : undefined}
+          onClick={(event) => event.stopPropagation()}
+          // The spreadsheet gesture: double-click the divider, the column
+          // fits its content. Same measurement as the menu item.
+          onDoubleClick={
+            canResize
+              ? (event) => {
+                  event.stopPropagation();
+                  autosize();
+                }
+              : undefined
+          }
+        />
+      )}
     </div>
   );
+
+  if (!hasMenu) return cell;
+
+  // A second Menu for the same items, rather than one Menu serving both ways
+  // in: the button's dropdown hangs off the button, while a context menu
+  // belongs at the pointer, and a Mantine Menu has one target. `menuItems` is
+  // built once and rendered by whichever dropdown is open — never both — so
+  // the two can't drift apart.
+  //
+  // The per-header Popover this adds is not the cost the body pays for one per
+  // row (see TMDataGridBodyRowGroup): there are as many headers as columns, and
+  // they don't re-render on every scroll frame.
+  return (
+    <Menu
+      opened={contextMenuOpened}
+      onChange={(opened) => {
+        setContextMenuOpened(opened);
+        // Right-clicking a header whose button menu is still open would
+        // otherwise leave two dropdowns of the same items on screen.
+        if (opened) setMenuOpened(false);
+      }}
+      position="bottom-start"
+      shadow="md"
+      width={220}
+      withinPortal
+    >
+      <Menu.ContextMenu>{cell}</Menu.ContextMenu>
+      <Menu.Dropdown onClick={(event) => event.stopPropagation()}>
+        {menuItems}
+      </Menu.Dropdown>
+    </Menu>
+  );
 }
 
 function isDivider(node: ReactNode): boolean {

package/src/tmdatagrid/components/TMDataGridSearch.tsx

@@ -0,0 +1,122 @@
+import { ActionIcon, TextInput } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import { useEffect, useRef, useState } from "react";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import { getGridCapabilities } from "../core/capabilities";
+import { CloseIcon, SearchIcon } from "./icons";
+
+export type TMDataGridSearchProps = {
+  /** Defaults to `labels.searchPlaceholder`. */
+  placeholder?: string;
+  /**
+   * How long typing pauses before the filter is applied, in ms. Defaults to
+   * 250. `0` writes on every keystroke — what the tests use, and fine for
+   * small client-side data sets.
+   */
+  debounce?: number;
+  /** Width of the input. Defaults to 220. */
+  w?: number | string;
+};
+
+/**
+ * Quick search over every column — a debounced input writing the table's
+ * `globalFilter` state through the `"includesString"` filter the grid
+ * configures by default.
+ *
+ * ```tsx
+ * <TMDataGrid.Toolbar>
+ *   <TMDataGrid.Search />
+ *   <TMDataGrid.Spacer />
+ *   <TMDataGrid.FilterButton />
+ * </TMDataGrid.Toolbar>
+ * ```
+ *
+ * Renders nothing under `enableGlobalFilter: false`. Columns opt out with
+ * their own `enableGlobalFilter: false` — the generated lanes already do.
+ *
+ * The state is TanStack's `globalFilter`, so everything around it comes free:
+ * `manualFiltering` grids forward it to the server, and it is one of the
+ * persisted `data` slices. A grid that wants its own input entirely writes
+ * `table.setGlobalFilter` itself — this component is only the built-in one.
+ */
+export function TMDataGridSearch({
+  placeholder,
+  debounce = 250,
+  w = 220,
+}: TMDataGridSearchProps) {
+  const { table, features, labels, controlSize } = useTMDataGridContext();
+
+  // A consumer can put anything in `globalFilter`; the input only mirrors the
+  // string form and treats the rest as empty.
+  const globalFilter = useSelector(table.store, (state) =>
+    typeof state.globalFilter === "string" ? state.globalFilter : "",
+  );
+
+  const [draft, setDraft] = useState(globalFilter);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+    undefined,
+  );
+  // What this input last wrote, so an echo of its own write is not mistaken
+  // for an external change that should overwrite what is being typed.
+  const lastWrittenRef = useRef(globalFilter);
+
+  // External writes — a consumer's `setGlobalFilter`, a persistence restore —
+  // win over the draft; the input is a mirror, not an owner.
+  useEffect(() => {
+    if (globalFilter === lastWrittenRef.current) return;
+    lastWrittenRef.current = globalFilter;
+    setDraft(globalFilter);
+  }, [globalFilter]);
+
+  // An unmount mid-debounce drops the pending write rather than filtering a
+  // grid whose input no longer exists.
+  useEffect(() => () => clearTimeout(timeoutRef.current), []);
+
+  if (!getGridCapabilities(table, features).canSearch) return null;
+
+  const commit = (value: string) => {
+    lastWrittenRef.current = value;
+    // `undefined` rather than `""`: an empty filter is no filter, and this is
+    // what keeps the persisted slice and the funnel logic clean.
+    table.setGlobalFilter(value === "" ? undefined : value);
+  };
+
+  const handleChange = (value: string) => {
+    setDraft(value);
+    clearTimeout(timeoutRef.current);
+    if (debounce <= 0) {
+      commit(value);
+      return;
+    }
+    timeoutRef.current = setTimeout(() => commit(value), debounce);
+  };
+
+  return (
+    <TextInput
+      size={controlSize}
+      w={w}
+      value={draft}
+      onChange={(event) => handleChange(event.currentTarget.value)}
+      placeholder={placeholder ?? labels.searchPlaceholder}
+      aria-label={labels.searchLabel}
+      leftSection={<SearchIcon size={16} stroke={1.6} />}
+      rightSection={
+        draft !== "" ? (
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            size="sm"
+            aria-label={labels.clearSearch}
+            onClick={() => {
+              clearTimeout(timeoutRef.current);
+              setDraft("");
+              commit("");
+            }}
+          >
+            <CloseIcon size={14} stroke={1.6} />
+          </ActionIcon>
+        ) : undefined
+      }
+    />
+  );
+}