@jielga/tmdatagrid 0.2.0 → 0.3.0

package/src/tmdatagrid/core/capabilities.ts

@@ -20,9 +20,23 @@ 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";
 
 export type TMDataGridFeatureFlags = {
   sorting: boolean;
@@ -31,17 +45,49 @@ export type TMDataGridFeatureFlags = {
   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;
   /**
    * 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>(
@@ -54,12 +100,21 @@ export function readFeatureFlags<TData extends RowData>(
     | "enableColumnResizing"
     | "enableColumnOrdering"
     | "enableRowSelection"
-    | "rowSelectionMode"
-    | "highlightSelectedRows"
+    | "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,
@@ -67,14 +122,22 @@ export function readFeatureFlags<TData extends RowData>(
     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",
     pagination:
       options.enablePagination === true || options.manualPagination === true,
+    grouping: options.enableGrouping ?? options.manualPagination !== true,
   };
 }
 
@@ -89,6 +152,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 +161,7 @@ export type TMDataGridColumnCapabilities = {
   canPin: boolean;
   canResize: boolean;
   canReorder: boolean;
+  canGroup: boolean;
 };
 
 export function getColumnCapabilities(
@@ -111,6 +176,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,6 +189,7 @@ export type TMDataGridCapabilities = {
   canHideAny: boolean;
   canPinAny: boolean;
   canReorderAny: boolean;
+  canGroupAny: boolean;
   canSelectRows: boolean;
   canPaginate: boolean;
 };
@@ -139,6 +208,7 @@ 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,
   };

package/src/tmdatagrid/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/core/persistence.ts

@@ -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];
@@ -162,6 +170,9 @@ const SLICE_GUARDS: Record<
       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),
@@ -169,6 +180,7 @@ const SLICE_GUARDS: Record<
   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 {

package/src/tmdatagrid/core/rowSelection.ts

@@ -0,0 +1,202 @@
+import type { Row, RowData, RowSelectionState } from "@tanstack/react-table";
+import type { TMDataGridFeatureFlags } from "./capabilities";
+import { getGroupDataRows } from "./grouping";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+/**
+ * Rows in the order they are displayed, which is the order a shift-click range
+ * is measured over — so a range follows the active sort and skips filtered-out
+ * rows. Under pagination it is the current page, so a range cannot cross a page
+ * boundary.
+ *
+ * Once a column is grouped this includes the group rows, and only the leaves of
+ * groups that are open — and paging is suspended, so it is the whole tree. That
+ * is the right list for a range: it is what the user can see, and a range that
+ * swept collapsed rows would select things off screen. What a group row in the
+ * range contributes is decided by {@link getSelectableRowIds}.
+ */
+export function getDisplayedRows<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  features: TMDataGridFeatureFlags,
+): Array<Row<TMDataGridFeatures, TData>> {
+  return isPagingActive(table, features)
+    ? table.getPaginatedRowModel().rows
+    : table.getPrePaginatedRowModel().rows;
+}
+
+/**
+ * Whether the built-in pager is actually slicing anything.
+ *
+ * Grouping suspends it. A page can only count one kind of thing, and once the
+ * rows are a tree neither answer works: counting every row splits a group
+ * across a page boundary and strands the rest of the tree on pages the user has
+ * to go looking for, and counting only the top-level rows quietly redefines
+ * "rows per page" as groups per page, so a page of 25 can hold thousands of
+ * rows. Rather than pick, the grid renders the whole tree and leans on the
+ * virtualizer — which is its default mode anyway, pagination being opt-in.
+ *
+ * `TMDataGrid.Footer` reads this too, and greys the pager out rather than
+ * hiding it, so the pager going quiet is visible instead of mysterious.
+ */
+export function isPagingActive<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  features: TMDataGridFeatureFlags,
+): boolean {
+  return features.pagination && table.store.state.grouping.length === 0;
+}
+
+/**
+ * Which modifiers were held. Named for what they mean rather than for the keys,
+ * because the keys differ per platform — `toggle` is Ctrl on Windows/Linux and
+ * Cmd on macOS.
+ */
+export type TMDataGridRowClickModifiers = {
+  toggle: boolean;
+  extend: boolean;
+};
+
+export type ResolveRowSelectionClickArgs<TData extends RowData> = {
+  /** Displayed order — see {@link getDisplayedRows}. */
+  rows: ReadonlyArray<Row<TMDataGridFeatures, TData>>;
+  rowId: string;
+  /** The pivot a shift-click extends from. */
+  anchorRowId: string | null;
+  modifiers: TMDataGridRowClickModifiers;
+  selection: RowSelectionState;
+  /**
+   * Whether this gesture is allowed to clear rows it did not touch.
+   *
+   * `true` for a bare row click, where replacing is the whole point. `false` for
+   * a checkbox, which is only ever additive — ticking one box has never cleared
+   * the others, and shift-clicking one adds the range rather than becoming it.
+   */
+  canReplaceSelection: boolean;
+};
+
+export type ResolvedRowSelection = {
+  selection: RowSelectionState;
+  anchorRowId: string | null;
+};
+
+/**
+ * The row ids one gesture on this row selects.
+ *
+ * A group row is never selected itself: it holds no record, and TanStack
+ * derives its checked state from its descendants. So ticking a group means
+ * ticking every selectable leaf under it, which is also what makes the group's
+ * own box light up.
+ *
+ * Leaves rather than direct children, so one click on a top-level group takes
+ * the whole subtree however deeply it nests.
+ */
+export function getSelectableRowIds<TData extends RowData>(
+  row: Row<TMDataGridFeatures, TData>,
+): Array<string> {
+  return getGroupDataRows(row)
+    .filter((dataRow) => dataRow.getCanSelect())
+    .map((dataRow) => dataRow.id);
+}
+
+/**
+ * Turns one click into the next selection, following the convention every
+ * desktop list uses:
+ *
+ * | Gesture | Effect |
+ * | ------- | ------ |
+ * | Click | selection becomes only this row |
+ * | Ctrl/Cmd + click | toggle this row, leave the rest |
+ * | Shift + click | selection becomes the range anchor → this row |
+ * | Ctrl/Cmd + Shift + click | add that range to the selection |
+ *
+ * The anchor is a *pivot*, not "the last row touched": only a plain or
+ * Ctrl-click moves it, which is what lets a run of shift-clicks grow and shrink
+ * the same range from a fixed point.
+ *
+ * Selection state is rebuilt here and handed to `setRowSelection` wholesale
+ * rather than going through `row.toggleSelected()` per row, which would publish
+ * one state update each. That skips TanStack's sub-row cascade, so the cascade
+ * is done here instead: every row in the gesture is expanded through
+ * {@link getSelectableRowIds} before it reaches the map. Under grouping that is
+ * what makes one tick on a group select all of it.
+ */
+export function resolveRowSelectionClick<TData extends RowData>({
+  rows,
+  rowId,
+  anchorRowId,
+  modifiers,
+  selection,
+  canReplaceSelection,
+}: ResolveRowSelectionClickArgs<TData>): ResolvedRowSelection {
+  const index = rows.findIndex((row) => row.id === rowId);
+  const clickedRow = rows[index];
+  // Clicked row is not in the displayed set — nothing sensible to resolve.
+  if (index === -1 || clickedRow === undefined) return { selection, anchorRowId };
+
+  const targets = getSelectableRowIds(clickedRow);
+  // Nothing selectable under this gesture: a row the predicate refuses, or a
+  // group whose every leaf refuses.
+  if (targets.length === 0) return { selection, anchorRowId };
+
+  // `enableMultiRowSelection: false`, or the per-row predicate saying no: one
+  // row at a time, so the modifiers have nothing to build on and every gesture
+  // collapses to a single id.
+  //
+  // This has to be enforced here. Rebuilding the map and handing it to
+  // `setRowSelection` skips `mutateRowIsSelected`, which is where TanStack
+  // clears the other rows — so without this, Ctrl and Shift would quietly
+  // produce the multi-selection the option ruled out.
+  if (!clickedRow.getCanMultiSelect()) {
+    // A group stands for several rows, which single-select cannot express. The
+    // checkbox column drops the box on those rows for the same reason.
+    const only = targets.length === 1 ? targets[0] : undefined;
+    if (only === undefined) return { selection, anchorRowId };
+    // A checkbox must still be able to untick the one selected row; a row click
+    // only ever sets, so re-clicking it cannot empty the selection.
+    const untick = !canReplaceSelection && selection[only] === true;
+    return {
+      selection: untick ? {} : { [only]: true },
+      anchorRowId: rowId,
+    };
+  }
+
+  const anchorIndex =
+    anchorRowId === null
+      ? -1
+      : rows.findIndex((row) => row.id === anchorRowId);
+
+  // A range needs a pivot that is still on screen. When the anchor has been
+  // filtered or paged away, fall through and treat this as a fresh click.
+  if (modifiers.extend && anchorIndex !== -1) {
+    const from = Math.min(anchorIndex, index);
+    const to = Math.max(anchorIndex, index);
+    // Ctrl+Shift adds to what is already selected; Shift alone becomes the
+    // range — unless the gesture may not replace, in which case it also adds.
+    const next: RowSelectionState =
+      modifiers.toggle || !canReplaceSelection ? { ...selection } : {};
+    for (const row of rows.slice(from, to + 1)) {
+      // A group row inside the range brings its whole subtree, including leaves
+      // that are collapsed out of `rows` — sweeping past a closed group selects
+      // it entire, which is the only reading that matches what it displays.
+      for (const id of getSelectableRowIds(row)) next[id] = true;
+    }
+    // The pivot deliberately stays put.
+    return { selection: next, anchorRowId };
+  }
+
+  if (modifiers.toggle || !canReplaceSelection) {
+    const next: RowSelectionState = { ...selection };
+    // Asked of the targets rather than of `rowId`: a group row carries no id in
+    // the map, so it counts as selected exactly when all of its leaves do —
+    // which is also when its checkbox shows a tick rather than a dash.
+    const allSelected = targets.every((id) => selection[id] === true);
+    for (const id of targets) {
+      if (allSelected) delete next[id];
+      else next[id] = true;
+    }
+    return { selection: next, anchorRowId: rowId };
+  }
+
+  const next: RowSelectionState = {};
+  for (const id of targets) next[id] = true;
+  return { selection: next, anchorRowId: rowId };
+}

package/src/tmdatagrid/index.ts

@@ -5,6 +5,10 @@ export {
   type TMDataGridRowData,
 } from "./TMDataGridContext";
 export { SELECT_COLUMN_ID } from "./components/TMDataGridSelectColumn";
+export {
+  formatGroupValue,
+  GROUP_COLUMN_ID,
+} from "./components/TMDataGridGroupColumn";
 export {
   createTMDataGridColumnHelper,
   openColumnFilter,
@@ -20,11 +24,16 @@ export {
   useTMDataGrid,
   type UseTMDataGridOptions,
 } from "./useTMDataGrid";
+export {
+  TMDataGridFilterPills,
+  type TMDataGridFilterPillsProps,
+} from "./components/TMDataGridFilterPills";
 export {
   type TMDataGridColumnType,
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
   FILTER_OPERATOR_LABELS,
+  formatFilterLabel,
   isFilterActive,
 } from "./core/filterOperators";
 export {
@@ -32,6 +41,7 @@ export {
   getColumnType,
   isColumnReorderable,
 } from "./core/columnUtils";
+export { getGroupDataRows } from "./core/grouping";
 export {
   getColumnRegion,
   getStepTargetColumn,
@@ -49,8 +59,17 @@ export {
   type TMDataGridCapabilities,
   type TMDataGridColumnCapabilities,
   type TMDataGridFeatureFlags,
-  type TMDataGridRowSelectionMode,
+  type TMDataGridSelectionMode,
 } from "./core/capabilities";
+export {
+  getDisplayedRows,
+  getSelectableRowIds,
+  isPagingActive,
+  resolveRowSelectionClick,
+  type ResolvedRowSelection,
+  type ResolveRowSelectionClickArgs,
+  type TMDataGridRowClickModifiers,
+} from "./core/rowSelection";
 export {
   DEFAULT_TMDATAGRID_SIZE,
   SIZE_CONTROL_SIZE,
@@ -66,7 +85,12 @@ export {
   type TMDataGridSettingsSlice,
   type TMDataGridStorageMode,
 } from "./core/persistence";
-export type { TMDataGridColumnLayout } from "./components/TMDataGridTable";
+export type {
+  TMDataGridColumnLayout,
+  TMDataGridRowContextMenu,
+  TMDataGridRowContextMenuArgs,
+  TMDataGridTableProps,
+} from "./components/TMDataGridTable";
 export {
   getTMDataGridPaginationApi,
   type TMDataGridFooterProps,