@jielga/tmdatagrid 0.1.0 → 0.3.0

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

@@ -0,0 +1,12 @@
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: var(--mantine-spacing-xs);
+  padding: 6px var(--mantine-spacing-xs);
+  min-height: 42px;
+  flex-shrink: 0;
+}
+
+.toolbarSpacer {
+  flex: 1;
+}

package/src/tmdatagrid/{TMDataGridToolbar.tsx → components/TMDataGridToolbar.tsx}

@@ -1,13 +1,13 @@
 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 classes from "./TMDataGridToolbar.module.css";
 import { TMDataGridColumnsPanel } from "./TMDataGridColumnsPanel";
-import { useTMDataGridContext } from "./TMDataGridContext";
-import { getGridCapabilities } from "./capabilities";
-import { isFilterActive } from "./filterOperators";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import { getGridCapabilities } from "../core/capabilities";
+import { isFilterActive } from "../core/filterOperators";
 import { BurgerIcon, FilterIcon } from "./icons";
-import { openColumnFilter } from "./useTMDataGrid";
+import { openColumnFilter } from "../useTMDataGrid";
 
 /** Row above the grid. Compose it from the pieces below, or anything else. */
 export function TMDataGridToolbar({ children }: { children?: ReactNode }) {
@@ -112,6 +112,9 @@ export function TMDataGridFilterButton() {
         color={activeCount > 0 ? undefined : "gray"}
         size={controlSize}
         aria-label="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/{icons.ts → components/icons.ts}

@@ -10,12 +10,17 @@ export {
   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

@@ -0,0 +1,45 @@
+/* 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.
+
+   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);
+}
+
+.stickyLeft::after,
+.stickyRight::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 4px;
+  pointer-events: none;
+}
+
+.stickyLeft::after {
+  left: 100%;
+  background: linear-gradient(
+    to right,
+    light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.28)),
+    transparent
+  );
+}
+
+.stickyRight::after {
+  right: 100%;
+  background: linear-gradient(
+    to left,
+    light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.28)),
+    transparent
+  );
+}

package/src/tmdatagrid/core/capabilities.ts

@@ -0,0 +1,215 @@
+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.
+ */
+/**
+ * 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 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";
+
+export type TMDataGridFeatureFlags = {
+  sorting: boolean;
+  filtering: boolean;
+  hiding: boolean;
+  pinning: boolean;
+  resizing: boolean;
+  ordering: boolean;
+  /** Whether any row selection is possible. Off outright under `"highlight"`. */
+  rowSelection: boolean;
+  /** 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. */
+  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;
+  /**
+   * 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>(
+  options: Pick<
+    UseTMDataGridOptions<TData>,
+    | "enableSorting"
+    | "enableColumnFilters"
+    | "enableHiding"
+    | "enableColumnPinning"
+    | "enableColumnResizing"
+    | "enableColumnOrdering"
+    | "enableRowSelection"
+    | "enableMultiRowSelection"
+    | "selectionMode"
+    | "showSelectedBackground"
+    | "enablePagination"
+    | "manualPagination"
+    | "enableGrouping"
+  >,
+): TMDataGridFeatureFlags {
+  const selectionMode = options.selectionMode ?? "checkbox";
+  // `"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,
+    hiding: options.enableHiding !== false,
+    pinning: options.enableColumnPinning !== false,
+    resizing: options.enableColumnResizing !== false,
+    ordering: options.enableColumnOrdering !== false,
+    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.
+    showSelectedBackground:
+      options.showSelectedBackground ?? selectionMode === "row",
+    highlightRow:
+      selectionMode === "checkboxAndHighlight" || selectionMode === "highlight",
+    pagination:
+      options.enablePagination === true || options.manualPagination === true,
+    grouping: options.enableGrouping ?? options.manualPagination !== true,
+  };
+}
+
+/**
+ * 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` |
+ * | Group by / Ungroup        | `enableGrouping` (table or column) |
+ */
+export type TMDataGridColumnCapabilities = {
+  canSort: boolean;
+  canFilter: boolean;
+  canHide: boolean;
+  canPin: boolean;
+  canResize: boolean;
+  canReorder: boolean;
+  canGroup: 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),
+    // `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(),
+  };
+}
+
+/** 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;
+  canGroupAny: boolean;
+  canSelectRows: boolean;
+  canPaginate: 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),
+    canGroupAny: any((c) => c.canGroup),
+    canSelectRows: features.rowSelection,
+    canPaginate: features.pagination,
+  };
+}

package/src/tmdatagrid/{columnOrdering.ts → core/columnOrdering.ts}

@@ -1,7 +1,7 @@
 import type { Column, ColumnPinningState } from "@tanstack/react-table";
-import type { TMDataGridRowData } from "./TMDataGridContext";
+import type { TMDataGridRowData } from "../TMDataGridContext";
 import { isColumnReorderable } from "./columnUtils";
-import type { TMDataGridFeatures, TMDataGridTable } from "./useTMDataGrid";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
 type GridColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
 type GridTable = TMDataGridTable<TMDataGridRowData>;

package/src/tmdatagrid/{columnUtils.ts → core/columnUtils.ts}

@@ -1,5 +1,5 @@
 import type { TMDataGridColumnType } from "./filterOperators";
-import type { TMDataGridColumnMeta } from "./useTMDataGrid";
+import type { TMDataGridColumnMeta } from "../useTMDataGrid";
 
 /**
  * Structural shape of the column bits the chrome reads. Kept minimal so these

package/src/tmdatagrid/{filterOperators.ts → core/filterOperators.ts}

@@ -106,6 +106,31 @@ export function isFilterActive(value: unknown): boolean {
   return !operatorNeedsValue(value.operator) || value.value.trim() !== "";
 }
 
+/**
+ * One-line description of a single filter, as shown on a filter pill.
+ *
+ * The type's default operator is left implicit — "First name: Sofia" reads the
+ * way a person would say it — while any other operator is spelled out, since
+ * that is the part a reader cannot guess.
+ */
+export function formatFilterLabel({
+  label,
+  type,
+  filter,
+}: {
+  label: string;
+  type: TMDataGridColumnType;
+  filter: TMDataGridFilterValue;
+}): string {
+  const { operator, value } = filter;
+  if (!operatorNeedsValue(operator)) {
+    return `${label} ${FILTER_OPERATOR_LABELS[operator]}`;
+  }
+  const text = value.trim();
+  if (operator === getDefaultOperator(type)) return `${label}: ${text}`;
+  return `${label} ${FILTER_OPERATOR_LABELS[operator]} ${text}`;
+}
+
 export function matchesFilter(
   cellValue: unknown,
   { operator, value }: TMDataGridFilterValue,

package/src/tmdatagrid/core/grouping.ts

@@ -0,0 +1,21 @@
+import type { Row, RowData } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+
+/**
+ * The data rows under a group row, at any depth.
+ *
+ * Not `row.getLeafRows()`, despite the name: that flattens the whole subtree
+ * and keeps the branches, so a group nested two deep reports its sub-groups
+ * alongside the records. Grouping `city` then `name` would have Stockholm
+ * counting four rows and three names as seven, and one tick on it selecting
+ * ids that hold no record.
+ *
+ * A row with no subRows is a data row, which also makes this the identity on an
+ * ungrouped grid.
+ */
+export function getGroupDataRows<TData extends RowData>(
+  row: Row<TMDataGridFeatures, TData>,
+): Array<Row<TMDataGridFeatures, TData>> {
+  if (row.subRows.length === 0) return [row];
+  return row.getLeafRows().filter((leaf) => leaf.subRows.length === 0);
+}

package/src/tmdatagrid/{persistence.ts → core/persistence.ts}

@@ -1,5 +1,5 @@
 import type { TableState } from "@tanstack/react-table";
-import type { TMDataGridFeatures } from "./useTMDataGrid";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
 
 type GridState = TableState<TMDataGridFeatures>;
 
@@ -28,6 +28,10 @@ export const DATA_STATE_SLICES = [
   "globalFilter",
   "sorting",
   "pagination",
+  // Which groups are open. Keyed by group ids built from the values themselves
+  // (`department:Design`), so a restored entry for a group the data no longer
+  // produces is simply never looked up.
+  "expanded",
 ] as const satisfies ReadonlyArray<keyof GridState>;
 
 /**
@@ -39,6 +43,10 @@ export const SETTINGS_STATE_SLICES = [
   "columnSizing",
   "columnOrder",
   "columnPinning",
+  // Which columns the rows are grouped by. A settings slice rather than a data
+  // one: it names columns, not values, so it survives the data changing under
+  // it the way the column layout does.
+  "grouping",
 ] as const satisfies ReadonlyArray<keyof GridState>;
 
 export type TMDataGridDataSlice = (typeof DATA_STATE_SLICES)[number];
@@ -100,6 +108,86 @@ function resolveStorage(
   }
 }
 
+/**
+ * Shape guards for restored state.
+ *
+ * A stored payload outlives the code that wrote it: a slice can change shape
+ * between releases, and nothing stops anyone from editing storage by hand. The
+ * value goes straight into `initialState`, where a wrong shape surfaces as a
+ * crash inside TanStack rather than as a bad read here. A slice that fails its
+ * guard is dropped; the rest still restore.
+ */
+function prop(value: unknown, key: string): unknown {
+  return typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+const isString = (value: unknown): value is string => typeof value === "string";
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+function isArrayOf(
+  value: unknown,
+  isItem: (item: unknown) => boolean,
+): boolean {
+  return Array.isArray(value) && value.every(isItem);
+}
+
+function isRecordOf(
+  value: unknown,
+  isItem: (item: unknown) => boolean,
+): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.values(value).every(isItem);
+}
+
+const hasStringId = (entry: unknown): boolean => isString(prop(entry, "id"));
+
+const SLICE_GUARDS: Record<
+  TMDataGridDataSlice | TMDataGridSettingsSlice,
+  (value: unknown) => boolean
+> = {
+  columnFilters: (value) => isArrayOf(value, hasStringId),
+  // TanStack leaves the global filter value untyped — the grid's own default
+  // filters on a string, but a consumer may store anything here.
+  globalFilter: () => true,
+  sorting: (value) =>
+    isArrayOf(
+      value,
+      (entry) => hasStringId(entry) && typeof prop(entry, "desc") === "boolean",
+    ),
+  pagination: (value) => {
+    const pageIndex = prop(value, "pageIndex");
+    const pageSize = prop(value, "pageSize");
+    return (
+      isFiniteNumber(pageIndex) &&
+      pageIndex >= 0 &&
+      isFiniteNumber(pageSize) &&
+      pageSize > 0
+    );
+  },
+  // `true` is a legal ExpandedState of its own, meaning every row is open.
+  expanded: (value) =>
+    value === true || isRecordOf(value, (entry) => typeof entry === "boolean"),
+  columnVisibility: (value) =>
+    isRecordOf(value, (entry) => typeof entry === "boolean"),
+  columnSizing: (value) => isRecordOf(value, isFiniteNumber),
+  columnOrder: (value) => isArrayOf(value, isString),
+  columnPinning: (value) =>
+    isArrayOf(prop(value, "left"), isString) &&
+    isArrayOf(prop(value, "right"), isString),
+  grouping: (value) => isArrayOf(value, isString),
+};
+
+function isValidSlice(slice: keyof GridState, value: unknown): boolean {
+  const guard = SLICE_GUARDS[slice as keyof typeof SLICE_GUARDS];
+  return guard === undefined || guard(value);
+}
+
 function readSlices(
   storage: Storage | null,
   resolved: ResolvedKey | null,
@@ -117,7 +205,9 @@ function readSlices(
     // Only copy the selected slices. A payload written before the selection was
     // narrowed cannot reintroduce slices the caller has since opted out of.
     for (const slice of resolved.slices) {
-      if (slice in record) restored[slice] = record[slice];
+      if (!(slice in record)) continue;
+      if (!isValidSlice(slice, record[slice])) continue;
+      restored[slice] = record[slice];
     }
     return restored as Partial<GridState>;
   } catch {