@jielga/tmdatagrid 0.1.0

package/src/tmdatagrid/TMDataGridTable.tsx

@@ -0,0 +1,297 @@
+import { Loader, Text } from "@mantine/core";
+import {
+  type Cell,
+  flexRender,
+  type Row,
+  type RowData,
+} from "@tanstack/react-table";
+import { useSelector } from "@tanstack/react-store";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { useCallback, useRef } from "react";
+import classes from "./TMDataGrid.module.css";
+import { type TMDataGridRowData, useTMDataGridContext } from "./TMDataGridContext";
+import { TMDataGridFilterPanel } from "./TMDataGridFilterPanel";
+import { TMDataGridHeaderCell } from "./TMDataGridHeaderCell";
+import { getColumnAlign } from "./columnUtils";
+import { SearchIcon } from "./icons";
+import type { TMDataGridFeatures } from "./useTMDataGrid";
+
+/** Where a column sits relative to the pinned regions, resolved once per render. */
+export type TMDataGridColumnLayout = {
+  pinnedAt: "left" | "right" | false;
+  /** Distance in px from the grid's left or right edge. */
+  offset: number;
+  /** Last left-pinned / first right-pinned column — the one that casts the edge. */
+  isBoundary: boolean;
+};
+
+const UNPINNED_LAYOUT: TMDataGridColumnLayout = {
+  pinnedAt: false,
+  offset: 0,
+  isBoundary: false,
+};
+
+function TMDataGridBodyCell({
+  cell,
+  rowHeight,
+  layout,
+}: {
+  cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>;
+  rowHeight: number;
+  layout: TMDataGridColumnLayout;
+}) {
+  return (
+    <div
+      role="cell"
+      data-align={getColumnAlign(cell.column)}
+      className={[
+        classes.bodyCell,
+        layout.isBoundary && layout.pinnedAt === "left" ? classes.stickyLeft : "",
+        layout.isBoundary && layout.pinnedAt === "right"
+          ? classes.stickyRight
+          : "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      style={{
+        minHeight: rowHeight,
+        left: layout.pinnedAt === "left" ? layout.offset : undefined,
+        right: layout.pinnedAt === "right" ? layout.offset : undefined,
+        position: layout.pinnedAt ? "sticky" : undefined,
+        zIndex: layout.pinnedAt ? 2 : undefined,
+      }}
+    >
+      <span className={classes.cellContent}>
+        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+      </span>
+    </div>
+  );
+}
+
+export type TMDataGridTableProps<TData extends RowData> = {
+  /** Called when a body row is clicked. */
+  onRowClick?: (row: Row<TMDataGridFeatures, TData>) => void;
+};
+
+/**
+ * The scrollable grid surface. Always virtualized: only the rows inside the
+ * viewport (plus overscan) are mounted, regardless of page size.
+ */
+export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
+  onRowClick,
+}: TMDataGridTableProps<TData>) {
+  const { table, 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);
+
+  const { loading, noResultsLabel = "No rows match your filters" } =
+    table.options.meta ?? {};
+
+  const scrollContainerRef = useRef<HTMLDivElement>(null);
+  // Respects `manualPagination`: server-paged grids get the rows as delivered.
+  const rows = table.getPaginatedRowModel().rows;
+
+  const virtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollContainerRef.current,
+    estimateSize: useCallback(() => rowHeight, [rowHeight]),
+    getItemKey: useCallback((index: number) => rows[index]?.id ?? index, [rows]),
+    overscan: 6,
+    initialRect: { height: 600, width: 1200 },
+  });
+
+  const virtualItems = virtualizer.getVirtualItems();
+  const paddingTop = virtualItems[0]?.start ?? 0;
+  const paddingBottom =
+    virtualizer.getTotalSize() - (virtualItems.at(-1)?.end ?? 0);
+
+  const leftLeafColumns = table.getLeftLeafColumns();
+  const rightLeafColumns = table.getRightLeafColumns();
+  const centerLeafColumns = table.getCenterLeafColumns();
+
+  const orderedColumns = [
+    ...leftLeafColumns,
+    ...centerLeafColumns,
+    ...rightLeafColumns,
+  ];
+
+  // Headers and cells must follow the same left → center → right order as the
+  // column tracks, otherwise pinning a column would shuffle it out of its lane.
+  const centerHeaderGroups = table.getCenterHeaderGroups();
+  const leftHeaderGroups = table.getLeftHeaderGroups();
+  const rightHeaderGroups = table.getRightHeaderGroups();
+  const headerGroups = centerHeaderGroups.map((group, index) => ({
+    id: group.id,
+    headers: [
+      ...(leftHeaderGroups[index]?.headers ?? []),
+      ...group.headers,
+      ...(rightHeaderGroups[index]?.headers ?? []),
+    ],
+  }));
+  // Unresized columns stay fluid (`minmax(min, flex fr)`) so the grid fills the
+  // viewport; dragging a resize handle pins that column to an exact pixel width.
+  // minWidth is the sum of those floors — anything wider and the grid would
+  // force a horizontal scrollbar it doesn't need.
+  //
+  // Pinned columns are always exact: their sticky offsets come from
+  // `getStart()` / `getAfter()`, which sum `getSize()` and cannot see an `fr`.
+  const columnSizing = table.store.state.columnSizing;
+  const columnTracks = orderedColumns.map((column) => {
+    const isFixed = column.columnDef.minSize === column.columnDef.maxSize;
+    const isResized = column.id in columnSizing;
+    const isPinned = column.getIsPinned() !== false;
+    const minWidth = column.columnDef.minSize ?? 80;
+    if (isFixed || isResized || isPinned) {
+      return { track: `${column.getSize()}px`, minWidth: column.getSize() };
+    }
+    return {
+      track: `minmax(${minWidth}px, ${column.columnDef.meta?.flex ?? 1}fr)`,
+      minWidth,
+    };
+  });
+  const gridTemplateColumns = columnTracks.map((c) => c.track).join(" ");
+  const gridMinWidth = columnTracks.reduce((sum, c) => sum + c.minWidth, 0);
+
+  /**
+   * Sticky offsets are derived here, from state this component subscribes to,
+   * and handed down as props.
+   *
+   * Deriving them inside the cell via `column.getIsPinned()` /
+   * `column.getStart()` looks equivalent but isn't: those are plain calls on a
+   * `column` object whose identity survives a pin, so the React Compiler caches
+   * the result and the cell keeps rendering with stale pinning. Building the
+   * offsets from the same widths as the grid tracks also guarantees the two
+   * agree to the pixel.
+   */
+  const columnLayout = new Map<string, TMDataGridColumnLayout>();
+  const widthOf = (columnId: string) =>
+    columnTracks[orderedColumns.findIndex((c) => c.id === columnId)]?.minWidth ??
+    0;
+
+  let leftOffset = 0;
+  for (const column of leftLeafColumns) {
+    columnLayout.set(column.id, {
+      pinnedAt: "left",
+      offset: leftOffset,
+      isBoundary: column.id === leftLeafColumns.at(-1)?.id,
+    });
+    leftOffset += widthOf(column.id);
+  }
+  let rightOffset = 0;
+  for (const column of [...rightLeafColumns].reverse()) {
+    columnLayout.set(column.id, {
+      pinnedAt: "right",
+      offset: rightOffset,
+      isBoundary: column.id === rightLeafColumns[0]?.id,
+    });
+    rightOffset += widthOf(column.id);
+  }
+  for (const column of centerLeafColumns) {
+    columnLayout.set(column.id, {
+      pinnedAt: false,
+      offset: 0,
+      isBoundary: false,
+    });
+  }
+  const layoutFor = (columnId: string) =>
+    columnLayout.get(columnId) ?? UNPINNED_LAYOUT;
+
+  const isEmpty = rows.length === 0;
+
+  return (
+    <div className={classes.tableWrapper}>
+      <div ref={scrollContainerRef} className={classes.scrollContainer}>
+        <div
+          role="table"
+          className={classes.grid}
+          style={{ gridTemplateColumns, minWidth: gridMinWidth }}
+        >
+          <div role="rowgroup" style={{ display: "contents" }}>
+            {headerGroups.map((headerGroup) => (
+              <div key={headerGroup.id} role="row" className={classes.headerRow}>
+                {headerGroup.headers.map((header) => (
+                  <TMDataGridHeaderCell
+                    key={header.id}
+                    header={header}
+                    layout={layoutFor(header.column.id)}
+                  />
+                ))}
+              </div>
+            ))}
+          </div>
+
+          {paddingTop > 0 && (
+            <div aria-hidden style={{ gridColumn: "1/-1", height: paddingTop }} />
+          )}
+
+          <div role="rowgroup" style={{ display: "contents" }}>
+            {virtualItems.map((virtualItem) => {
+              const row = rows[virtualItem.index];
+              if (!row) return null;
+              return (
+                <div
+                  key={virtualItem.key}
+                  role="row"
+                  data-testid={`dg-row-${row.id}`}
+                  data-selected={row.getIsSelected()}
+                  className={classes.bodyRow}
+                  style={{
+                    minHeight: rowHeight,
+                    cursor: onRowClick ? "pointer" : undefined,
+                  }}
+                  onClick={
+                    onRowClick
+                      ? () =>
+                          onRowClick(
+                            row as unknown as Row<TMDataGridFeatures, TData>,
+                          )
+                      : undefined
+                  }
+                >
+                  {[
+                    ...row.getLeftVisibleCells(),
+                    ...row.getCenterVisibleCells(),
+                    ...row.getRightVisibleCells(),
+                  ].map((cell) => (
+                    <TMDataGridBodyCell
+                      key={cell.id}
+                      cell={cell}
+                      rowHeight={rowHeight}
+                      layout={layoutFor(cell.column.id)}
+                    />
+                  ))}
+                </div>
+              );
+            })}
+          </div>
+
+          {isEmpty && loading === true && (
+            <div role="row" className={classes.messageRow}>
+              <Loader size="lg" />
+            </div>
+          )}
+
+          {isEmpty && loading !== true && (
+            <div role="row" className={classes.messageRow}>
+              <SearchIcon size={40} stroke={1.4} opacity={0.4} />
+              <Text size={controlSize} c="dimmed">
+                {noResultsLabel}
+              </Text>
+            </div>
+          )}
+
+          {paddingBottom > 0 && (
+            <div
+              aria-hidden
+              style={{ gridColumn: "1/-1", height: paddingBottom }}
+            />
+          )}
+        </div>
+      </div>
+
+      <TMDataGridFilterPanel />
+    </div>
+  );
+}

package/src/tmdatagrid/TMDataGridToolbar.tsx

@@ -0,0 +1,131 @@
+import { ActionIcon, Popover, Text, Tooltip } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import type { ReactNode } from "react";
+import classes from "./TMDataGrid.module.css";
+import { TMDataGridColumnsPanel } from "./TMDataGridColumnsPanel";
+import { useTMDataGridContext } from "./TMDataGridContext";
+import { getGridCapabilities } from "./capabilities";
+import { isFilterActive } from "./filterOperators";
+import { BurgerIcon, FilterIcon } from "./icons";
+import { openColumnFilter } from "./useTMDataGrid";
+
+/** Row above the grid. Compose it from the pieces below, or anything else. */
+export function TMDataGridToolbar({ children }: { children?: ReactNode }) {
+  return <div className={classes.toolbar}>{children}</div>;
+}
+
+/** Pushes the following toolbar items to the right. */
+export function TMDataGridToolbarSpacer() {
+  return <div className={classes.toolbarSpacer} />;
+}
+
+/**
+ * Visible rows over total rows. On a server-driven grid, set
+ * `meta.totalRowCount` for the denominator — the client never sees every row.
+ */
+export function TMDataGridSummaryCount({ children }: { children?: ReactNode }) {
+  const { table, controlSize } = useTMDataGridContext();
+  useSelector(table.store);
+
+  if (children !== undefined) {
+    return (
+      <Text size={controlSize} c="dimmed">
+        {children}
+      </Text>
+    );
+  }
+
+  const shown = table.getRowCount();
+  const total =
+    table.options.meta?.totalRowCount ??
+    table.getPreFilteredRowModel().rows.length;
+
+  return (
+    <Text size={controlSize} c="dimmed">
+      {shown} / {total}
+    </Text>
+  );
+}
+
+/**
+ * Burger menu in the grid's top-right corner — opens "Manage columns".
+ * Renders nothing when no column can be hidden (`enableHiding: false`).
+ */
+export function TMDataGridColumnsButton() {
+  const { table, ui, features, controlSize } = useTMDataGridContext();
+  const opened = useSelector(ui, (state) => state.columnsPanelOpen);
+
+  if (!getGridCapabilities(table, features).canHideAny) return null;
+
+  return (
+    <Popover
+      opened={opened}
+      onChange={ui.actions.setColumnsPanelOpen}
+      position="bottom-end"
+      shadow="md"
+      radius="md"
+      withinPortal
+      trapFocus
+    >
+      <Popover.Target>
+        <Tooltip label="Manage columns" openDelay={400}>
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            size={controlSize}
+            aria-label="Manage columns"
+            onClick={ui.actions.toggleColumnsPanel}
+          >
+            <BurgerIcon size={18} stroke={1.6} />
+          </ActionIcon>
+        </Tooltip>
+      </Popover.Target>
+      <Popover.Dropdown p={0}>
+        <TMDataGridColumnsPanel />
+      </Popover.Dropdown>
+    </Popover>
+  );
+}
+
+/**
+ * Toggles the filter panel, seeding a filter row on the first filterable column.
+ * Renders nothing when no column can be filtered (`enableColumnFilters: false`).
+ */
+export function TMDataGridFilterButton() {
+  const api = useTMDataGridContext();
+  const { table, ui, features, controlSize } = api;
+  const opened = useSelector(ui, (state) => state.filterPanelOpen);
+  const columnFilters = useSelector(
+    table.store,
+    (state) => state.columnFilters,
+  );
+  const activeCount = columnFilters.filter((filter) =>
+    isFilterActive(filter.value),
+  ).length;
+
+  if (!getGridCapabilities(table, features).canFilterAny) return null;
+
+  return (
+    <Tooltip label="Filters" openDelay={400}>
+      <ActionIcon
+        variant={opened || activeCount > 0 ? "light" : "subtle"}
+        color={activeCount > 0 ? undefined : "gray"}
+        size={controlSize}
+        aria-label="Filters"
+        onClick={() => {
+          if (opened) {
+            ui.actions.closeFilterPanel();
+            return;
+          }
+          const firstFilterable = table
+            .getAllLeafColumns()
+            .find((column) => column.getCanFilter());
+          if (firstFilterable) openColumnFilter(api, firstFilterable.id);
+          else ui.actions.openFilterPanel();
+        }}
+      >
+        <FilterIcon size={16} stroke={1.6} />
+      </ActionIcon>
+    </Tooltip>
+  );
+}

package/src/tmdatagrid/capabilities.ts

@@ -0,0 +1,117 @@
+import type { Column, RowData } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "./TMDataGridContext";
+import { isColumnReorderable } from "./columnUtils";
+import type {
+  TMDataGridFeatures,
+  TMDataGridTable,
+  UseTMDataGridOptions,
+} from "./useTMDataGrid";
+
+/**
+ * Table-level feature switches, read straight off the options object.
+ *
+ * Why not just call `column.getCanSort()` everywhere? Because that is a method
+ * call on a `column` whose identity survives an options change, so the React
+ * Compiler caches the result and the chrome keeps rendering for a feature that
+ * was switched off. Reading the options into a fresh object each render gives
+ * every derived value something that actually changes to invalidate on.
+ *
+ * TanStack still decides: these flags are combined with `getCanX()`, which is
+ * what applies the per-column overrides.
+ */
+export type TMDataGridFeatureFlags = {
+  sorting: boolean;
+  filtering: boolean;
+  hiding: boolean;
+  pinning: boolean;
+  resizing: boolean;
+  ordering: boolean;
+  rowSelection: boolean;
+};
+
+export function readFeatureFlags<TData extends RowData>(
+  options: Pick<
+    UseTMDataGridOptions<TData>,
+    | "enableSorting"
+    | "enableColumnFilters"
+    | "enableHiding"
+    | "enableColumnPinning"
+    | "enableColumnResizing"
+    | "enableColumnOrdering"
+    | "enableRowSelection"
+  >,
+): TMDataGridFeatureFlags {
+  return {
+    sorting: options.enableSorting !== false,
+    filtering: options.enableColumnFilters !== false,
+    hiding: options.enableHiding !== false,
+    pinning: options.enableColumnPinning !== false,
+    resizing: options.enableColumnResizing !== false,
+    ordering: options.enableColumnOrdering !== false,
+    rowSelection: options.enableRowSelection !== false,
+  };
+}
+
+/**
+ * What one column's header may offer.
+ *
+ * | Affordance | Turned off by |
+ * | ---------- | ------------- |
+ * | Sort arrow, Sort ASC/DESC | `enableSorting` (table or column) |
+ * | Filter item, panel entry  | `enableColumnFilters` / `enableColumnFilter` |
+ * | Hide column               | `enableHiding` (table or column) |
+ * | Pin to left / right       | `enableColumnPinning` / `enablePinning` |
+ * | Resize dragging           | `enableColumnResizing` / `enableResizing` |
+ * | Header dragging, Move left / right | `enableColumnOrdering` / `meta.enableOrdering` |
+ */
+export type TMDataGridColumnCapabilities = {
+  canSort: boolean;
+  canFilter: boolean;
+  canHide: boolean;
+  canPin: boolean;
+  canResize: boolean;
+  canReorder: boolean;
+};
+
+export function getColumnCapabilities(
+  column: Column<TMDataGridFeatures, TMDataGridRowData, unknown>,
+  features: TMDataGridFeatureFlags,
+): TMDataGridColumnCapabilities {
+  return {
+    canSort: features.sorting && column.getCanSort(),
+    canFilter: features.filtering && column.getCanFilter(),
+    canHide: features.hiding && column.getCanHide(),
+    canPin: features.pinning && column.getCanPin(),
+    canResize: features.resizing && column.getCanResize(),
+    // Ordering has no TanStack capability method — see isColumnReorderable.
+    canReorder: features.ordering && isColumnReorderable(column),
+  };
+}
+
+/** The same questions, asked of the whole grid — used to hide toolbar buttons. */
+export type TMDataGridCapabilities = {
+  canSortAny: boolean;
+  canFilterAny: boolean;
+  canHideAny: boolean;
+  canPinAny: boolean;
+  canReorderAny: boolean;
+  canSelectRows: boolean;
+};
+
+export function getGridCapabilities(
+  table: TMDataGridTable<TMDataGridRowData>,
+  features: TMDataGridFeatureFlags,
+): TMDataGridCapabilities {
+  const columns = table.getAllLeafColumns();
+  const any = (predicate: (capabilities: TMDataGridColumnCapabilities) => boolean) =>
+    columns.some((column) => predicate(getColumnCapabilities(column, features)));
+
+  return {
+    canSortAny: any((c) => c.canSort),
+    canFilterAny: any((c) => c.canFilter),
+    canHideAny: any((c) => c.canHide),
+    canPinAny: any((c) => c.canPin),
+    canReorderAny: any((c) => c.canReorder),
+    canSelectRows: features.rowSelection,
+  };
+}

package/src/tmdatagrid/columnOrdering.ts

@@ -0,0 +1,140 @@
+import type { Column, ColumnPinningState } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "./TMDataGridContext";
+import { isColumnReorderable } from "./columnUtils";
+import type { TMDataGridFeatures, TMDataGridTable } from "./useTMDataGrid";
+
+type GridColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
+type GridTable = TMDataGridTable<TMDataGridRowData>;
+
+/**
+ * The lane a column renders in.
+ *
+ * Pinning splits the grid into three, and TanStack sequences them from two
+ * different state slices: `columnPinning.left` / `.right` order the pinned
+ * lanes, `columnOrder` orders the centre. A move therefore always stays inside
+ * one lane — moving a column into another one would be a pin, not a reorder.
+ */
+export type TMDataGridColumnRegion = "left" | "center" | "right";
+
+/** Which edge of the column under the pointer a dragged column lands on. */
+export type TMDataGridDropSide = "before" | "after";
+
+export function getColumnRegion(
+  columnPinning: ColumnPinningState,
+  columnId: string,
+): TMDataGridColumnRegion {
+  if (columnPinning.left.includes(columnId)) return "left";
+  if (columnPinning.right.includes(columnId)) return "right";
+  return "center";
+}
+
+/** Moves one id next to another, leaving every other id in place. */
+function moveInList(
+  ids: ReadonlyArray<string>,
+  movedId: string,
+  targetId: string,
+  side: TMDataGridDropSide,
+): Array<string> {
+  const remaining = ids.filter((id) => id !== movedId);
+  const targetIndex = remaining.indexOf(targetId);
+  if (targetIndex === -1) return [...ids];
+  remaining.splice(side === "before" ? targetIndex : targetIndex + 1, 0, movedId);
+  return remaining;
+}
+
+export type MoveColumnArgs = {
+  table: GridTable;
+  /** Column being moved. */
+  columnId: string;
+  /** Column it was dropped on. */
+  targetId: string;
+  side: TMDataGridDropSide;
+};
+
+/**
+ * Moves a column next to another one. A no-op when the two are in different
+ * pinned regions, or when either id is unknown.
+ *
+ * `columnOrder` is always written as the full leaf order, including hidden and
+ * pinned columns, so a column keeps its place when it is later shown or
+ * unpinned. Pinned lanes are read from `columnPinning`, so a move inside one
+ * updates that array as well.
+ */
+export function moveColumn({
+  table,
+  columnId,
+  targetId,
+  side,
+}: MoveColumnArgs): void {
+  if (columnId === targetId) return;
+
+  const columnPinning = table.store.state.columnPinning;
+  const region = getColumnRegion(columnPinning, columnId);
+  if (region !== getColumnRegion(columnPinning, targetId)) return;
+
+  const leafIds = table.getAllLeafColumns().map((column) => column.id);
+  table.setColumnOrder(moveInList(leafIds, columnId, targetId, side));
+
+  if (region !== "center") {
+    table.setColumnPinning((previous) => ({
+      ...previous,
+      [region]: moveInList(previous[region], columnId, targetId, side),
+    }));
+  }
+}
+
+/** Visible leaf columns of one lane, in the order they render. */
+function getRegionColumns(
+  table: GridTable,
+  region: TMDataGridColumnRegion,
+): Array<GridColumn> {
+  if (region === "left") return table.getLeftVisibleLeafColumns();
+  if (region === "right") return table.getRightVisibleLeafColumns();
+  return table.getCenterVisibleLeafColumns();
+}
+
+export type ColumnStepArgs = {
+  table: GridTable;
+  columnId: string;
+  /** `-1` moves towards the start of the lane, `1` towards its end. */
+  direction: -1 | 1;
+};
+
+/**
+ * The column a single step would swap with, or `null` when there is none.
+ *
+ * A neighbour that cannot be reordered acts as a wall rather than being skipped
+ * — that is what keeps the checkbox column anchored at the start of the left
+ * lane. Use it to enable or disable a "move" control.
+ */
+export function getStepTargetColumn({
+  table,
+  columnId,
+  direction,
+}: ColumnStepArgs): GridColumn | null {
+  const region = getColumnRegion(table.store.state.columnPinning, columnId);
+  const columns = getRegionColumns(table, region);
+  const index = columns.findIndex((column) => column.id === columnId);
+  if (index === -1) return null;
+
+  const target = columns[index + direction];
+  if (!target || !isColumnReorderable(target)) return null;
+  return target;
+}
+
+/** Moves a column one position within its lane. Hidden columns are stepped over. */
+export function moveColumnByStep({
+  table,
+  columnId,
+  direction,
+}: ColumnStepArgs): void {
+  const target = getStepTargetColumn({ table, columnId, direction });
+  if (!target) return;
+
+  moveColumn({
+    table,
+    columnId,
+    targetId: target.id,
+    side: direction === -1 ? "before" : "after",
+  });
+}