@jielga/tmdatagrid 0.2.0 → 0.5.0

package/src/tmdatagrid/components/TMDataGridToolbar.tsx

@@ -1,4 +1,4 @@
-import { ActionIcon, Popover, Text, Tooltip } from "@mantine/core";
+import { ActionIcon, Loader, Popover, Text, Tooltip } from "@mantine/core";
 import { useSelector } from "@tanstack/react-store";
 import type { ReactNode } from "react";
 import classes from "./TMDataGridToolbar.module.css";
@@ -19,6 +19,29 @@ export function TMDataGridToolbarSpacer() {
   return <div className={classes.toolbarSpacer} />;
 }
 
+/**
+ * A small spinner shown while `meta.loading` is true, and nothing otherwise.
+ *
+ * The body only shows its loading state while the grid is *empty* — a
+ * server-driven grid refetching with rows on screen keeps showing them, which
+ * is right, but leaves nothing saying a fetch is running. This is that signal,
+ * and the consumer decides where it sits by placing it in the toolbar:
+ *
+ * ```tsx
+ * <TMDataGrid.Toolbar>
+ *   <TMDataGrid.SummaryCount />
+ *   <TMDataGrid.Spacer />
+ *   <TMDataGrid.LoadingIndicator />
+ *   <TMDataGrid.FilterButton />
+ * </TMDataGrid.Toolbar>
+ * ```
+ */
+export function TMDataGridLoadingIndicator() {
+  const { table, labels } = useTMDataGridContext();
+  if (table.options.meta?.loading !== true) return null;
+  return <Loader size="xs" aria-label={labels.loading} />;
+}
+
 /**
  * Visible rows over total rows. On a server-driven grid, set
  * `meta.totalRowCount` for the denominator — the client never sees every row.
@@ -52,7 +75,7 @@ export function TMDataGridSummaryCount({ children }: { children?: ReactNode }) {
  * Renders nothing when no column can be hidden (`enableHiding: false`).
  */
 export function TMDataGridColumnsButton() {
-  const { table, ui, features, controlSize } = useTMDataGridContext();
+  const { table, ui, features, labels, controlSize } = useTMDataGridContext();
   const opened = useSelector(ui, (state) => state.columnsPanelOpen);
 
   if (!getGridCapabilities(table, features).canHideAny) return null;
@@ -68,12 +91,12 @@ export function TMDataGridColumnsButton() {
       trapFocus
     >
       <Popover.Target>
-        <Tooltip label="Manage columns" openDelay={400}>
+        <Tooltip label={labels.manageColumns} openDelay={400}>
           <ActionIcon
             variant="subtle"
             color="gray"
             size={controlSize}
-            aria-label="Manage columns"
+            aria-label={labels.manageColumns}
             onClick={ui.actions.toggleColumnsPanel}
           >
             <BurgerIcon size={18} stroke={1.6} />
@@ -93,7 +116,7 @@ export function TMDataGridColumnsButton() {
  */
 export function TMDataGridFilterButton() {
   const api = useTMDataGridContext();
-  const { table, ui, features, controlSize } = api;
+  const { table, ui, features, labels, controlSize } = api;
   const opened = useSelector(ui, (state) => state.filterPanelOpen);
   const columnFilters = useSelector(
     table.store,
@@ -106,12 +129,15 @@ export function TMDataGridFilterButton() {
   if (!getGridCapabilities(table, features).canFilterAny) return null;
 
   return (
-    <Tooltip label="Filters" openDelay={400}>
+    <Tooltip label={labels.filters} openDelay={400}>
       <ActionIcon
         variant={opened || activeCount > 0 ? "light" : "subtle"}
         color={activeCount > 0 ? undefined : "gray"}
         size={controlSize}
-        aria-label="Filters"
+        aria-label={labels.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

@@ -6,16 +6,22 @@
  * `sideEffects: false`, so only the icons re-exported here reach the bundle.
  */
 export {
+  IconArrowAutofitWidth as AutosizeIcon,
   IconArrowDown as ArrowDownIcon,
   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,

package/src/tmdatagrid/components/sticky.module.css

@@ -1,36 +1,38 @@
 /* Boundary of a pinned column group. Shared, because the edge is cast by both
-   the header cell and every body cell in the same column — the two have to
-   draw an identical band or the seam shows at the header.
+   the header cell and every body cell in the same column — the two have to draw
+   an identical band or the seam shows at the header.
 
    A box-shadow is drawn per cell, and its blur fades in at each cell's own top
    and bottom edge — stacked down a column that reads as banding at every row
-   seam. Instead: a crisp 1px border for the hard edge, plus a gradient pseudo
-   element pinned to `top: 0; bottom: 0` so consecutive cells butt together into
-   one unbroken band. Mantine sets `color-scheme` on the root, so light-dark()
-   resolves without a second selector. */
-.stickyLeft {
-  border-right: 1px solid var(--mantine-color-default-border);
-}
-
-.stickyRight {
-  border-left: 1px solid var(--mantine-color-default-border);
-}
+   seam. Instead: a gradient pseudo element pinned to `top: 0; bottom: 0` so
+   consecutive cells butt together into one unbroken band. Mantine sets
+   `color-scheme` on the root, so light-dark() resolves without a second
+   selector.
 
+   No border. A 1px line the colour of the grid's own borders drew a hard rule
+   between the pinned lanes and the data, so the pinned columns read as a
+   separate table rather than as part of this one — and at the system lanes,
+   which are only a control wide, it framed them like a sidebar. */
 .stickyLeft::after,
 .stickyRight::after {
   content: "";
   position: absolute;
   top: 0;
   bottom: 0;
-  width: 4px;
+  width: 8px;
   pointer-events: none;
 }
 
+/* Three stops rather than two. A straight linear ramp to `transparent` fades
+   fastest at the start, so its own outer edge stays visible as a faint line —
+   the sharpness a hard border was blamed for. Front-loading the falloff puts
+   the density against the pinned cell and lets the tail reach zero unnoticed. */
 .stickyLeft::after {
   left: 100%;
   background: linear-gradient(
     to right,
-    light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.28)),
+    light-dark(rgba(0, 0, 0, 0.07), rgba(0, 0, 0, 0.26)),
+    light-dark(rgba(0, 0, 0, 0.025), rgba(0, 0, 0, 0.09)) 45%,
     transparent
   );
 }
@@ -39,7 +41,66 @@
   right: 100%;
   background: linear-gradient(
     to left,
-    light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.28)),
+    light-dark(rgba(0, 0, 0, 0.07), rgba(0, 0, 0, 0.26)),
+    light-dark(rgba(0, 0, 0, 0.025), rgba(0, 0, 0, 0.09)) 45%,
     transparent
   );
 }
+
+/* The band says "there is more table under this lane". So it should only be
+   there while that is true: nothing is hidden at either end of the scroll, and
+   nothing at all is hidden by a grid narrow enough not to scroll.
+
+   Driven by the scroll position itself rather than by a listener writing a
+   class. A scroll-driven animation is evaluated on the compositor, so the band
+   tracks the scroll frame for frame without a single React render — and the
+   body re-renders on every scroll frame already, from virtualization.
+
+   `scroll(nearest inline)` resolves to `.scrollContainer`, the one horizontal
+   scroller above these cells. An inactive timeline — which is what a container
+   with nothing to scroll gives — leaves the base style in place, so `opacity:
+   0` inside this block is also the answer for a grid that does not scroll. */
+@supports (animation-timeline: scroll()) {
+  .stickyLeft::after,
+  .stickyRight::after {
+    /* Distance over which the band arrives. Short enough to read as an edge
+       appearing under the lane rather than as a fade. */
+    --dg-sticky-edge-range: 20px;
+    opacity: 0;
+    animation-timeline: scroll(nearest inline);
+    animation-timing-function: linear;
+    animation-fill-mode: both;
+  }
+
+  .stickyLeft::after {
+    animation-name: stickyEdgeIn;
+    animation-range: 0 var(--dg-sticky-edge-range);
+  }
+
+  /* The mirror: on at rest, gone as the last column arrives. The range is
+     measured from the end, and `both` holds the first value everywhere before
+     it — so the band stays fully on until the scroller is within 20px of home.
+   */
+  .stickyRight::after {
+    animation-name: stickyEdgeOut;
+    animation-range: calc(100% - var(--dg-sticky-edge-range)) 100%;
+  }
+}
+
+@keyframes stickyEdgeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes stickyEdgeOut {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}

package/src/tmdatagrid/core/autosize.ts

@@ -0,0 +1,125 @@
+import type { RowData } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridTable } from "../useTMDataGrid";
+
+/**
+ * Room the header keeps for its hover-revealed actions (sort arrow, menu) and
+ * the resize divider, which measure zero while idle. Without it a column sized
+ * exactly to its header text puts the actions on top of the title.
+ */
+const HEADER_ACTIONS_ALLOWANCE = 30;
+
+/** Breathing room so the widest value does not touch the next divider. */
+const CONTENT_ALLOWANCE = 2;
+
+/**
+ * What the content inside one cell actually spans, in px.
+ *
+ * A Range over the children rather than the span's `scrollWidth`, because the
+ * two disagree in opposite directions: a left-aligned cell stretches its
+ * content span to fill the cell (`flex: 1 1 auto`), so `scrollWidth` reports
+ * the stretched box and autosize could never *shrink* a column — while for
+ * clipped content both see past the `overflow: hidden`. The Range measures
+ * the laid-out text and elements themselves, whatever box they sit in.
+ *
+ * `scrollWidth` stays as the fallback for environments whose Ranges do not
+ * measure (jsdom reports 0 there).
+ */
+function contentSpanWidth(content: HTMLElement): number {
+  const range = document.createRange();
+  range.selectNodeContents(content);
+  // jsdom's Range has no getBoundingClientRect at all, hence the guard
+  // rather than a zero-check alone.
+  const width =
+    typeof range.getBoundingClientRect === "function"
+      ? range.getBoundingClientRect().width
+      : 0;
+  return width > 0 ? width : content.scrollWidth;
+}
+
+/**
+ * Widest rendered content of one column, in px, measured from the DOM.
+ *
+ * Mounted cells only: under virtualization the unmounted rows do not exist to
+ * be measured, so this reads the visible window plus overscan — the same
+ * trade AG Grid's autosize makes by default.
+ */
+export function measureColumnContentWidth({
+  container,
+  columnId,
+}: {
+  /** The grid's scroll container — anything enclosing the column's cells. */
+  container: HTMLElement;
+  columnId: string;
+}): number {
+  let widest = 0;
+
+  const cells = container.querySelectorAll<HTMLElement>(
+    `[role="cell"][data-column-id="${CSS.escape(columnId)}"],` +
+      `[role="gridcell"][data-column-id="${CSS.escape(columnId)}"]`,
+  );
+  for (const cell of cells) {
+    const content = cell.firstElementChild;
+    if (!(content instanceof HTMLElement)) continue;
+    const styles = getComputedStyle(cell);
+    const padding =
+      (Number.parseFloat(styles.paddingLeft) || 0) +
+      (Number.parseFloat(styles.paddingRight) || 0);
+    widest = Math.max(
+      widest,
+      contentSpanWidth(content) + padding + CONTENT_ALLOWANCE,
+    );
+  }
+
+  const title = container.querySelector<HTMLElement>(
+    `[data-testid="dg-header-${CSS.escape(columnId)}"] [data-dg-header-title]`,
+  );
+  if (title) {
+    const header = title.closest<HTMLElement>('[role="columnheader"]');
+    const styles = header ? getComputedStyle(header) : null;
+    const padding = styles
+      ? (Number.parseFloat(styles.paddingLeft) || 0) +
+        (Number.parseFloat(styles.paddingRight) || 0)
+      : 0;
+    widest = Math.max(
+      widest,
+      contentSpanWidth(title) + padding + HEADER_ACTIONS_ALLOWANCE,
+    );
+  }
+
+  return widest;
+}
+
+/**
+ * Sizes a column to its widest mounted content — what double-clicking the
+ * resize divider does, exported so a menu item or consumer code can trigger
+ * the same thing.
+ *
+ * The width lands in `columnSizing`, so it persists with the other widths and
+ * a later resize drag takes over from it. Clamped to the column's
+ * `minSize`/`maxSize`; a no-op (returning `false`) for a column that cannot
+ * be resized or has nothing mounted to measure.
+ */
+export function autosizeColumn<TData extends RowData>({
+  table,
+  columnId,
+  container,
+}: {
+  table: TMDataGridTable<TData>;
+  columnId: string;
+  container: HTMLElement;
+}): boolean {
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
+  const column = erased.getColumn(columnId);
+  if (!column || !column.getCanResize()) return false;
+
+  const measured = measureColumnContentWidth({ container, columnId });
+  if (measured <= 0) return false;
+
+  const minSize = column.columnDef.minSize ?? 80;
+  const maxSize = column.columnDef.maxSize ?? Number.POSITIVE_INFINITY;
+  const width = Math.round(Math.min(Math.max(measured, minSize), maxSize));
+
+  erased.setColumnSizing((previous) => ({ ...previous, [columnId]: width }));
+  return true;
+}

package/src/tmdatagrid/core/capabilities.ts

@@ -20,28 +20,103 @@ import type {
  * what applies the per-column overrides.
  */
 /**
- * How rows are selected — see `rowSelectionMode` on {@link UseTMDataGridOptions}.
+ * How rows are selected — see `selectionMode` on {@link UseTMDataGridOptions}.
+ *
+ * One axis, because the two things a config could set independently — which
+ * chrome selects, and what a bare row click does — cannot both be free: a click
+ * can either toggle a multi-selection or move the highlight, never both. Folding
+ * them into one value makes that conflict unrepresentable rather than something
+ * to warn about.
  */
-export type TMDataGridRowSelectionMode = "checkbox" | "row";
+export type TMDataGridSelectionMode =
+  /** Checkbox column, multi-select. Clicking a row elsewhere does nothing. */
+  | "checkbox"
+  /** No checkbox column; row click multi-selects, with Ctrl/Shift modifiers. */
+  | "row"
+  /** Checkbox column multi-selects, and a row click highlights one row. */
+  | "checkboxAndHighlight"
+  /** No selection at all — a row click only highlights. Master-detail. */
+  | "highlight";
+
+/**
+ * How cells are selected — see `cellSelection` on {@link UseTMDataGridOptions}.
+ *
+ * A mode rather than a pair of booleans, for the reason
+ * {@link TMDataGridSelectionMode} is one: "cells can be selected" and "more
+ * than one at a time" are not independent, and a range that cannot be anchored
+ * anywhere is not a state worth being able to write down.
+ */
+export type TMDataGridCellSelectionMode =
+  /** No cell cursor at all. The body's tab stop stays on the row. */
+  | "none"
+  /** One cell takes the focus and the arrow keys move it. */
+  | "single"
+  /** As `"single"`, plus a rectangle: drag, Shift+click, Shift+arrows, Ctrl+C. */
+  | "range";
 
 export type TMDataGridFeatureFlags = {
   sorting: boolean;
   filtering: boolean;
+  /** Whether the quick search may filter — `enableGlobalFilter`. */
+  globalFiltering: boolean;
   hiding: boolean;
   pinning: boolean;
   resizing: boolean;
   ordering: boolean;
+  /** Whether any row selection is possible. Off outright under `"highlight"`. */
   rowSelection: boolean;
-  /** Only meaningful while `rowSelection` is on. Defaults to `"checkbox"`. */
-  rowSelectionMode: TMDataGridRowSelectionMode;
+  /** Defaults to `"checkbox"`. */
+  selectionMode: TMDataGridSelectionMode;
+  /** Whether the generated checkbox column is prepended. */
+  selectColumn: boolean;
+  /** Whether a bare row click toggles the selection. Only under `"row"`. */
+  rowClickSelects: boolean;
+  /**
+   * Whether more than one row can be selected at once — TanStack's
+   * `enableMultiRowSelection`. Off, the grid drops the select-all header
+   * checkbox: TanStack's `toggleAllRowsSelected` only consults `getCanSelect`,
+   * so that control would select every row and walk straight past the limit.
+   *
+   * A per-row predicate counts as on, since some rows may still multi-select.
+   */
+  multiRowSelection: boolean;
   /** Whether a selected row takes the highlight colour. Follows the mode. */
-  highlightSelectedRows: boolean;
+  showSelectedBackground: boolean;
+  /**
+   * The single highlighted row — clicking a row highlights it, for a detail
+   * panel to follow. State of its own, not a slice of `rowSelection`, which is
+   * what lets it coexist with a checkbox multi-selection.
+   */
+  highlightRow: boolean;
+  /**
+   * Whether cells can be selected at all. Off unless `cellSelection` asks for
+   * it — it takes the body's tab stop off the row and puts it on a cell, and
+   * reports the grid to assistive technology as a `grid` rather than a `table`,
+   * which is a different promise about what the keyboard does.
+   */
+  cellSelection: boolean;
+  /** Defaults to `"none"`. */
+  cellSelectionMode: TMDataGridCellSelectionMode;
+  /** Whether a rectangle of cells can be selected. Only under `"range"`. */
+  cellRangeSelection: boolean;
   /**
    * The one default-off flag: pagination must be asked for, either with the
    * grid's `enablePagination` or implicitly by declaring `manualPagination`.
    * Off, the grid renders every filtered row and relies on virtualization.
    */
   pagination: boolean;
+  /**
+   * Row grouping: the "Group by" items in the header menu and the generated
+   * tree column. On unless `enableGrouping: false`, since an ungrouped grid
+   * looks and behaves exactly as it did before — `grouping` starts empty, and
+   * an empty grouping state passes straight through the row model.
+   *
+   * The exception is `manualPagination`, where the client holds one page rather
+   * than the whole set: grouping that page would build groups out of an
+   * arbitrary slice and quietly show wrong counts. A server-side grid that does
+   * its own grouping can still say `enableGrouping: true` to override.
+   */
+  grouping: boolean;
 };
 
 export function readFeatureFlags<TData extends RowData>(
@@ -49,32 +124,56 @@ export function readFeatureFlags<TData extends RowData>(
     UseTMDataGridOptions<TData>,
     | "enableSorting"
     | "enableColumnFilters"
+    | "enableGlobalFilter"
     | "enableHiding"
     | "enableColumnPinning"
     | "enableColumnResizing"
     | "enableColumnOrdering"
     | "enableRowSelection"
-    | "rowSelectionMode"
-    | "highlightSelectedRows"
+    | "enableMultiRowSelection"
+    | "selectionMode"
+    | "showSelectedBackground"
+    | "cellSelection"
     | "enablePagination"
     | "manualPagination"
+    | "enableGrouping"
   >,
 ): TMDataGridFeatureFlags {
+  const selectionMode = options.selectionMode ?? "checkbox";
+  const cellSelectionMode = options.cellSelection ?? "none";
+  // `"highlight"` is the master-detail mode: no selection to speak of, so the
+  // checkbox column and the click-to-select behaviour both fall away. Otherwise
+  // `enableRowSelection` still has the final say, including its predicate form.
+  const rowSelection =
+    selectionMode !== "highlight" && options.enableRowSelection !== false;
+
   return {
     sorting: options.enableSorting !== false,
     filtering: options.enableColumnFilters !== false,
+    globalFiltering: options.enableGlobalFilter !== false,
     hiding: options.enableHiding !== false,
     pinning: options.enableColumnPinning !== false,
     resizing: options.enableColumnResizing !== false,
     ordering: options.enableColumnOrdering !== false,
-    rowSelection: options.enableRowSelection !== false,
-    rowSelectionMode: options.rowSelectionMode ?? "checkbox",
+    rowSelection,
+    selectionMode,
+    selectColumn:
+      rowSelection &&
+      (selectionMode === "checkbox" || selectionMode === "checkboxAndHighlight"),
+    rowClickSelects: rowSelection && selectionMode === "row",
+    multiRowSelection: options.enableMultiRowSelection !== false,
     // In "row" mode the highlight *is* the feedback for a click, so it is on.
     // With checkboxes the box already says it, so it is off unless asked for.
-    highlightSelectedRows:
-      options.highlightSelectedRows ?? options.rowSelectionMode === "row",
+    showSelectedBackground:
+      options.showSelectedBackground ?? selectionMode === "row",
+    highlightRow:
+      selectionMode === "checkboxAndHighlight" || selectionMode === "highlight",
+    cellSelection: cellSelectionMode !== "none",
+    cellSelectionMode,
+    cellRangeSelection: cellSelectionMode === "range",
     pagination:
       options.enablePagination === true || options.manualPagination === true,
+    grouping: options.enableGrouping ?? options.manualPagination !== true,
   };
 }
 
@@ -89,6 +188,7 @@ export function readFeatureFlags<TData extends RowData>(
  * | Pin to left / right       | `enableColumnPinning` / `enablePinning` |
  * | Resize dragging           | `enableColumnResizing` / `enableResizing` |
  * | Header dragging, Move left / right | `enableColumnOrdering` / `meta.enableOrdering` |
+ * | Group by / Ungroup        | `enableGrouping` (table or column) |
  */
 export type TMDataGridColumnCapabilities = {
   canSort: boolean;
@@ -97,6 +197,7 @@ export type TMDataGridColumnCapabilities = {
   canPin: boolean;
   canResize: boolean;
   canReorder: boolean;
+  canGroup: boolean;
 };
 
 export function getColumnCapabilities(
@@ -111,6 +212,9 @@ export function getColumnCapabilities(
     canResize: features.resizing && column.getCanResize(),
     // Ordering has no TanStack capability method — see isColumnReorderable.
     canReorder: features.ordering && isColumnReorderable(column),
+    // `getCanGroup()` also insists on an accessor, which is what keeps the
+    // generated checkbox and tree columns from offering to group on themselves.
+    canGroup: features.grouping && column.getCanGroup(),
   };
 }
 
@@ -121,8 +225,11 @@ export type TMDataGridCapabilities = {
   canHideAny: boolean;
   canPinAny: boolean;
   canReorderAny: boolean;
+  canGroupAny: boolean;
   canSelectRows: boolean;
   canPaginate: boolean;
+  /** At least one leaf column takes part in the global quick search. */
+  canSearch: boolean;
 };
 
 export function getGridCapabilities(
@@ -139,7 +246,11 @@ export function getGridCapabilities(
     canHideAny: any((c) => c.canHide),
     canPinAny: any((c) => c.canPin),
     canReorderAny: any((c) => c.canReorder),
+    canGroupAny: any((c) => c.canGroup),
     canSelectRows: features.rowSelection,
     canPaginate: features.pagination,
+    canSearch:
+      features.globalFiltering &&
+      columns.some((column) => column.getCanGlobalFilter()),
   };
 }