@jielga/tmdatagrid 0.2.0 → 0.5.0

package/src/tmdatagrid/components/TMDataGridFooter.tsx

@@ -1,10 +1,11 @@
-import { ActionIcon, Group, Select, Text } from "@mantine/core";
+import { ActionIcon, Group, Select, Text, Tooltip } from "@mantine/core";
 import type { RowData } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import type { ReactNode } from "react";
 import classes from "./TMDataGridFooter.module.css";
 import { useTMDataGridContext } from "../TMDataGridContext";
 import { getGridCapabilities } from "../core/capabilities";
+import { isPagingActive } from "../core/rowSelection";
 import { ChevronLeftIcon, ChevronRightIcon } from "./icons";
 import type { TMDataGridTable } from "../useTMDataGrid";
 
@@ -70,7 +71,7 @@ export function TMDataGridFooter({
   pageSizeOptions = [10, 25, 50, 100],
   pagination,
 }: TMDataGridFooterProps) {
-  const { table, features, controlSize } = useTMDataGridContext();
+  const { table, features, labels, controlSize } = useTMDataGridContext();
   useSelector(table.store);
 
   if (!getGridCapabilities(table, features).canPaginate) return null;
@@ -83,6 +84,10 @@ export function TMDataGridFooter({
     );
   }
 
+  // Grouping suspends paging — see isPagingActive. The pager is greyed out
+  // rather than dropped, so that a footer going quiet reads as a state the grid
+  // is in rather than as something that broke.
+  const paging = isPagingActive(table, features);
   const { pageIndex, pageSize } = table.store.state.pagination;
   const total = table.getRowCount();
   const from = total === 0 ? 0 : pageIndex * pageSize + 1;
@@ -95,49 +100,64 @@ export function TMDataGridFooter({
     : [...pageSizeOptions, pageSize].sort((a, b) => a - b);
 
   return (
-    <div className={classes.footer}>
-      <Group gap="xs" wrap="nowrap">
+    <Tooltip
+      label={labels.pagingSuspendedHint}
+      disabled={paging}
+      withArrow
+      multiline
+      w={260}
+      position="top"
+    >
+      <div className={classes.footer} data-paging-suspended={!paging}>
+        <Group gap="xs" wrap="nowrap">
+          <Text size={controlSize} c="dimmed">
+            {labels.rowsPerPage}
+          </Text>
+          <Select
+            size={controlSize}
+            w={78}
+            allowDeselect={false}
+            variant="unstyled"
+            disabled={!paging}
+            data={sizeOptions.map(String)}
+            value={String(pageSize)}
+            onChange={(value) => {
+              table.setPageSize(Number(value) || pageSizeOptions[0]);
+              table.setPageIndex(0);
+            }}
+          />
+        </Group>
+
         <Text size={controlSize} c="dimmed">
-          Rows per page:
+          {paging
+            ? labels.pageRange({ from, to, total })
+            : // Not a range: nothing is being sliced, so a range would be a lie.
+              // Counted before grouping too — `getRowCount()` would be counting
+              // the tree, so a collapsed grid would claim to hold eight rows.
+              labels.groupedAllRows(table.getFilteredRowModel().rows.length)}
         </Text>
-        <Select
-          size={controlSize}
-          w={78}
-          allowDeselect={false}
-          variant="unstyled"
-          data={sizeOptions.map(String)}
-          value={String(pageSize)}
-          onChange={(value) => {
-            table.setPageSize(Number(value) || pageSizeOptions[0]);
-            table.setPageIndex(0);
-          }}
-        />
-      </Group>
-
-      <Text size={controlSize} c="dimmed">
-        {from}–{to} of {total}
-      </Text>
 
-      <Group gap={4} wrap="nowrap">
-        <ActionIcon
-          variant="subtle"
-          color="gray"
-          aria-label="Previous page"
-          disabled={!table.getCanPreviousPage()}
-          onClick={() => table.previousPage()}
-        >
-          <ChevronLeftIcon size={18} stroke={1.6} />
-        </ActionIcon>
-        <ActionIcon
-          variant="subtle"
-          color="gray"
-          aria-label="Next page"
-          disabled={!table.getCanNextPage()}
-          onClick={() => table.nextPage()}
-        >
-          <ChevronRightIcon size={18} stroke={1.6} />
-        </ActionIcon>
-      </Group>
-    </div>
+        <Group gap={4} wrap="nowrap">
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label={labels.previousPage}
+            disabled={!paging || !table.getCanPreviousPage()}
+            onClick={() => table.previousPage()}
+          >
+            <ChevronLeftIcon size={18} stroke={1.6} />
+          </ActionIcon>
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label={labels.nextPage}
+            disabled={!paging || !table.getCanNextPage()}
+            onClick={() => table.nextPage()}
+          >
+            <ChevronRightIcon size={18} stroke={1.6} />
+          </ActionIcon>
+        </Group>
+      </div>
+    </Tooltip>
   );
 }

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

@@ -0,0 +1,48 @@
+/* The tree lane. Fills its cell so the whole indented width is a hit target,
+   which is what makes a deeply nested group as easy to click as a top-level
+   one. */
+.groupToggle {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  min-width: 0;
+  font-size: var(--dg-font-size);
+  color: inherit;
+}
+
+.chevron {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  color: var(--mantine-color-dimmed);
+  transition: transform 120ms ease;
+}
+
+.chevron[data-expanded="true"] {
+  transform: rotate(90deg);
+}
+
+/* One icon rotated rather than two swapped: the turn is what reads as the
+   expand, and a swap would jump. */
+@media (prefers-reduced-motion: reduce) {
+  .chevron {
+    transition: none;
+  }
+}
+
+.groupLabel {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-weight: 600;
+}
+
+/* Never squeezed out by a long group value — the count is the part that tells
+   you whether the group is worth opening. */
+.groupCount {
+  flex: 0 0 auto;
+  color: var(--mantine-color-dimmed);
+  font-variant-numeric: tabular-nums;
+}

package/src/tmdatagrid/components/TMDataGridGroupColumn.tsx

@@ -0,0 +1,159 @@
+import { UnstyledButton } from "@mantine/core";
+import {
+  useCellControlTabIndex,
+  useTMDataGridContext,
+} from "../TMDataGridContext";
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import { useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
+import classes from "./TMDataGridGroupColumn.module.css";
+import { ChevronRightIcon } from "./icons";
+import { getColumnLabel } from "../core/columnUtils";
+import { getGroupDataRows } from "../core/grouping";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+export const GROUP_COLUMN_ID = "__group__";
+
+/** Indent added per level of nesting, in px. */
+const INDENT_STEP = 16;
+
+/** Shown for a group whose value is empty — `String(null)` would read as "null". */
+const BLANK_GROUP_LABEL = "(Blank)";
+
+/**
+ * How a grouping value is written into the tree cell.
+ *
+ * Deliberately not the grouped column's own `cell` renderer: that renderer is
+ * written for a data row and is free to reach into `row.original`, which on a
+ * group row is the first leaf's record rather than anything about the group.
+ */
+export function formatGroupValue(
+  value: unknown,
+  blankLabel = BLANK_GROUP_LABEL,
+): string {
+  if (value === null || value === undefined || value === "") {
+    return blankLabel;
+  }
+  if (value instanceof Date) return value.toLocaleDateString();
+  return String(value);
+}
+
+/**
+ * The tree cell: chevron, group value and leaf count, indented by depth.
+ *
+ * Expansion is read through a subscription rather than from `row.getIsExpanded()`
+ * in the component body for the same reason the select checkbox does it — the
+ * `row` identity survives an expand, so the React Compiler would cache the call
+ * along with it and the chevron would never turn. See TMDataGridSelectColumn.
+ */
+function GroupCell<TData extends RowData>({
+  row,
+}: {
+  row: Row<TMDataGridFeatures, TData>;
+}) {
+  const { labels } = useTMDataGridContext();
+  const expanded = useSelector(row.table.store, () => row.getIsExpanded());
+  // See useCellControlTabIndex: reached by stepping into the cell, not by Tab.
+  const tabIndex = useCellControlTabIndex();
+
+  // Leaf rows keep the lane empty: their values are in the data columns, and
+  // the indent alone is what places them under their group.
+  if (!row.getIsGrouped()) return null;
+
+  const label = formatGroupValue(row.groupingValue, labels.blankGroupValue);
+
+  return (
+    <UnstyledButton
+      className={classes.groupToggle}
+      // Padding rather than margin, so the whole indented width stays clickable.
+      style={{ paddingInlineStart: row.depth * INDENT_STEP }}
+      tabIndex={tabIndex}
+      aria-expanded={expanded}
+      aria-label={
+        expanded ? labels.collapseGroup(label) : labels.expandGroup(label)
+      }
+      // The row underneath may select or highlight on click; expanding is its
+      // own gesture and must not also trigger those.
+      onClick={(event) => {
+        event.stopPropagation();
+        row.toggleExpanded();
+      }}
+    >
+      <span className={classes.chevron} data-expanded={expanded}>
+        <ChevronRightIcon size={16} stroke={1.6} />
+      </span>
+      <span className={classes.groupLabel}>{label}</span>
+      {/* Data rows, not direct children and not `getLeafRows()`: a nested group
+          counts the records under it, never the sub-groups in between. */}
+      <span className={classes.groupCount}>
+        ({getGroupDataRows(row).length})
+      </span>
+    </UnstyledButton>
+  );
+}
+
+/**
+ * Names the columns currently grouped on, so the lane says what it is showing
+ * rather than a static "Group".
+ */
+function GroupHeader<TData extends RowData>({
+  table,
+}: {
+  table: TMDataGridTable<TData>;
+}) {
+  const { labels } = useTMDataGridContext();
+  const grouping = useSelector(table.store, (state) => state.grouping, {
+    compare: shallow,
+  });
+
+  if (grouping.length === 0) return labels.groupColumnLabel;
+  return grouping
+    .map((columnId) => {
+      const column = table.getColumn(columnId);
+      return column ? getColumnLabel(column) : columnId;
+    })
+    .join(" / ");
+}
+
+/**
+ * The generated tree column, prepended whenever grouping is enabled and hidden
+ * again while `grouping` is empty — see the visibility effect in
+ * `useTMDataGrid`.
+ *
+ * It exists because TanStack ships no auto group column: `groupedColumnMode:
+ * "remove"` takes the grouped column out of the grid, so something has to hold
+ * the tree. Modelled on the checkbox column, which is generated the same way.
+ *
+ * Not groupable itself, and nothing had to be written to make that true —
+ * `column.getCanGroup()` requires an `accessorFn`, which a display column has
+ * no reason to have.
+ */
+export function createGroupColumn<TData extends RowData>(
+  label = "Group",
+): ColumnDef<TMDataGridFeatures, TData, unknown> {
+  return {
+    id: GROUP_COLUMN_ID,
+    meta: {
+      label,
+      // Structurally the first column after the checkbox lane.
+      enableOrdering: false,
+    },
+    size: 260,
+    minSize: 180,
+    enableSorting: false,
+    enableColumnFilter: false,
+    enableGlobalFilter: false,
+    // Keeps it out of the columns panel and out of the header menu: its
+    // visibility is not the user's to set, it follows the grouping state.
+    enableHiding: false,
+    // Structurally pinned to the left; users shouldn't be able to move it.
+    enablePinning: false,
+    cell: ({ row }) => <GroupCell row={row} />,
+    // A group row has subRows, so every cell on it that is not the grouped
+    // column reports `getIsAggregated()` — this lane included. Without an
+    // `aggregatedCell` the body would take that as "nothing to summarise" and
+    // render the tree lane blank on exactly the rows it exists for.
+    aggregatedCell: ({ row }) => <GroupCell row={row} />,
+    header: ({ table }) => <GroupHeader table={table} />,
+  };
+}

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

@@ -21,6 +21,13 @@
   justify-content: center;
 }
 
+/* Same as the body cells: a control lane's header — the select-all box, the
+   expand-all chevron — sits in a fixed 36px track, which the text padding would
+   squeeze it out of at the larger sizes. */
+.headerCell[data-control-column="true"] {
+  padding: 0;
+}
+
 /* Sorted or filtered columns read as active, like the MUI data grid. */
 .headerCell[data-active="true"] .headerTitle {
   color: var(--mantine-primary-color-filled);
@@ -78,6 +85,17 @@
   cursor: pointer;
 }
 
+/* Sort priority under multi-sort — "1", "2", … beside the arrow. Only rendered
+   while more than one column sorts, so a single sort stays as it always was. */
+.sortIndex {
+  font-size: 10px;
+  font-weight: 600;
+  line-height: 1;
+  color: var(--mantine-color-dimmed);
+  min-width: 10px;
+  text-align: center;
+}
+
 /* Column reordering. The dragged header stays in place and dims — the browser
    already carries a snapshot of it under the pointer — while the header being
    dragged over draws a bar on the edge the column will land against. */