@jielga/tmdatagrid 0.1.0 → 0.3.0

package/src/tmdatagrid/components/TMDataGridFooter.tsx

@@ -0,0 +1,171 @@
+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";
+
+/** Shown on the greyed-out pager, and the reason it is greyed out. */
+const PAGING_SUSPENDED_HINT =
+  "Paging is off while the rows are grouped: the whole tree is rendered and virtualized. Ungroup to page again.";
+
+/** Distilled pagination state and actions for building a custom pager. */
+export type TMDataGridPaginationApi = {
+  pageIndex: number;
+  pageSize: number;
+  /** `-1` when a manual grid declares `pageCount: -1` (unknown total). */
+  pageCount: number;
+  rowCount: number;
+  canPreviousPage: boolean;
+  canNextPage: boolean;
+  setPageIndex: (pageIndex: number) => void;
+  setPageSize: (pageSize: number) => void;
+  previousPage: () => void;
+  nextPage: () => void;
+  firstPage: () => void;
+  lastPage: () => void;
+};
+
+/**
+ * Reads {@link TMDataGridPaginationApi} off a table. The Footer feeds it to the
+ * `pagination` render prop; a pager living outside the Footer can call it with
+ * the table from `useTMDataGrid` directly.
+ */
+export function getTMDataGridPaginationApi<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+): TMDataGridPaginationApi {
+  const { pageIndex, pageSize } = table.store.state.pagination;
+  return {
+    pageIndex,
+    pageSize,
+    pageCount: table.getPageCount(),
+    rowCount: table.getRowCount(),
+    canPreviousPage: table.getCanPreviousPage(),
+    canNextPage: table.getCanNextPage(),
+    setPageIndex: (index) => table.setPageIndex(index),
+    setPageSize: (size) => table.setPageSize(size),
+    previousPage: () => table.previousPage(),
+    nextPage: () => table.nextPage(),
+    firstPage: () => table.firstPage(),
+    lastPage: () => table.lastPage(),
+  };
+}
+
+export type TMDataGridFooterProps = {
+  pageSizeOptions?: ReadonlyArray<number>;
+  /** Replaces the built-in pager. Receives the distilled pagination API. */
+  pagination?: (api: TMDataGridPaginationApi) => ReactNode;
+};
+
+/**
+ * MUI-style pager: "Rows per page · from–to of total · ‹ ›".
+ *
+ * Renders nothing unless pagination is enabled (`enablePagination` or
+ * `manualPagination`) — the footer is a pager; extra footer content belongs in
+ * your own layout.
+ *
+ * Row totals come from `table.getRowCount()`, which prefers `options.rowCount`
+ * — so a server-paged grid shows the server's total without changes here.
+ */
+export function TMDataGridFooter({
+  pageSizeOptions = [10, 25, 50, 100],
+  pagination,
+}: TMDataGridFooterProps) {
+  const { table, features, controlSize } = useTMDataGridContext();
+  useSelector(table.store);
+
+  if (!getGridCapabilities(table, features).canPaginate) return null;
+
+  if (pagination) {
+    return (
+      <div className={classes.footer}>
+        {pagination(getTMDataGridPaginationApi(table))}
+      </div>
+    );
+  }
+
+  // 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;
+  const to = Math.min(total, (pageIndex + 1) * pageSize);
+  // A page size restored from storage, or set through `initialState`, need not
+  // be one of the offered sizes. Without it in the list the Select renders
+  // blank, so the current size is folded in rather than shown as nothing.
+  const sizeOptions = pageSizeOptions.includes(pageSize)
+    ? pageSizeOptions
+    : [...pageSizeOptions, pageSize].sort((a, b) => a - b);
+
+  return (
+    <Tooltip
+      label={PAGING_SUSPENDED_HINT}
+      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">
+            Rows per page:
+          </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">
+          {paging ? (
+            <>
+              {from}–{to} of {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.
+            <>Grouped · all {table.getFilteredRowModel().rows.length} rows</>
+          )}
+        </Text>
+
+        <Group gap={4} wrap="nowrap">
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label="Previous page"
+            disabled={!paging || !table.getCanPreviousPage()}
+            onClick={() => table.previousPage()}
+          >
+            <ChevronLeftIcon size={18} stroke={1.6} />
+          </ActionIcon>
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label="Next page"
+            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,147 @@
+import { UnstyledButton } from "@mantine/core";
+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): string {
+  if (value === null || value === undefined || value === "") {
+    return BLANK_GROUP_LABEL;
+  }
+  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 expanded = useSelector(row.table.store, () => row.getIsExpanded());
+
+  // 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);
+
+  return (
+    <UnstyledButton
+      className={classes.groupToggle}
+      // Padding rather than margin, so the whole indented width stays clickable.
+      style={{ paddingInlineStart: row.depth * INDENT_STEP }}
+      aria-expanded={expanded}
+      aria-label={`${expanded ? "Collapse" : "Expand"} ${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 grouping = useSelector(table.store, (state) => state.grouping, {
+    compare: shallow,
+  });
+
+  if (grouping.length === 0) return "Group";
+  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>(): ColumnDef<
+  TMDataGridFeatures,
+  TData,
+  unknown
+> {
+  return {
+    id: GROUP_COLUMN_ID,
+    meta: {
+      label: "Group",
+      // 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

@@ -0,0 +1,159 @@
+.headerCell {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 0 var(--dg-padding);
+  min-width: 0;
+  min-height: var(--dg-header-height);
+  font-weight: 600;
+  font-size: var(--dg-font-size);
+  background-color: var(--mantine-color-body);
+  border-bottom: 1px solid var(--mantine-color-default-border);
+  user-select: none;
+}
+
+.headerCell[data-align="right"] {
+  justify-content: flex-end;
+}
+
+.headerCell[data-align="center"] {
+  justify-content: center;
+}
+
+/* Same as the body cells: the select-all box sits in a fixed 48px track, which
+   the text padding would squeeze it out of at the larger sizes. */
+.headerCell[data-select-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);
+}
+
+.headerTitle {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Right-aligned headers stay text so the ellipsis still works; centered ones
+   hold a control (the select-all checkbox), so they become a flex box. */
+.headerCell[data-align="right"] .headerTitle {
+  text-align: right;
+}
+
+.headerCell[data-align="center"] .headerTitle {
+  display: flex;
+  justify-content: center;
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: 0;
+  flex-shrink: 0;
+  margin-left: auto;
+}
+
+/* Actions always reserve their width. On right-aligned columns they move to the
+   leading edge so the header text stays flush with the cell values below it. */
+.headerCell[data-align="right"] .headerActions {
+  order: -1;
+  margin-left: 0;
+  margin-right: auto;
+}
+
+/* Idle actions are removed from layout, not just faded — reserving their width
+   would truncate header text that otherwise fits. Indicators that must stay
+   visible (active sort, active filter, open menu) set data-pinned-visible. */
+.headerAction {
+  display: none;
+}
+
+.headerCell:hover .headerAction,
+.headerCell:focus-within .headerAction,
+.headerAction[data-pinned-visible="true"] {
+  display: flex;
+}
+
+.headerCellSortable {
+  cursor: pointer;
+}
+
+/* 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. */
+.headerCellDragging {
+  opacity: 0.4;
+}
+
+.headerCellDropBefore::before,
+.headerCellDropAfter::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background-color: var(--mantine-primary-color-filled);
+  z-index: 5;
+  pointer-events: none;
+}
+
+.headerCellDropBefore::before {
+  left: 0;
+}
+
+.headerCellDropAfter::before {
+  right: 0;
+}
+
+/* Doubles as the column divider seen between every header cell. */
+.columnSeparator {
+  position: absolute;
+  top: 25%;
+  right: 0;
+  height: 50%;
+  width: 10px;
+  transform: translateX(50%);
+  display: flex;
+  justify-content: center;
+  z-index: 1;
+}
+
+.columnSeparatorResizable {
+  cursor: col-resize;
+  touch-action: none;
+}
+
+/* The divider is a hover affordance, not permanent chrome — it only appears on
+   the header cell you are pointing at, or on the column being resized. */
+.columnSeparator::after {
+  content: "";
+  width: 1px;
+  height: 100%;
+  background-color: transparent;
+  transition:
+    background-color 120ms ease,
+    width 120ms ease;
+}
+
+.headerCell:hover .columnSeparator::after,
+.headerCell:focus-within .columnSeparator::after {
+  background-color: var(--mantine-color-default-border);
+}
+
+.columnSeparatorResizable:hover::after,
+.columnSeparatorActive::after {
+  width: 2px;
+  background-color: var(--mantine-primary-color-filled);
+}
+
+/* Marks the pin position a column is currently in. */
+.menuItemActive {
+  background-color: var(--mantine-color-default-hover);
+  font-weight: 600;
+}