@jielga/tmdatagrid 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { Column, ColumnPinningState, Row, RowData, Table, TableFeatures, TableOptions, TableState } from "@tanstack/react-table";
+import { Cell, Column, ColumnPinningState, Row, RowData, RowSelectionState, Table, TableFeatures, TableOptions, TableState } from "@tanstack/react-table";
 import { CSSProperties, ReactNode } from "react";
+import { MantineSize, MenuProps } from "@mantine/core";
 import { Store } from "@tanstack/store";
-import { MantineSize } from "@mantine/core";
 //#region .types-tmp/components/TMDataGridColumnsPanel.d.ts
 /**
  * The "Manage columns" surface. Reachable from every column header menu and
@@ -19,6 +19,20 @@ declare function TMDataGridColumnsPanel(): import("react").JSX.Element;
  */
 declare function TMDataGridFilterPanel(): import("react").JSX.Element | null;
 //#endregion
+//#region .types-tmp/core/sizes.d.ts
+type TMDataGridSize = MantineSize;
+declare const DEFAULT_TMDATAGRID_SIZE: TMDataGridSize;
+/**
+ * Row height per size, in px.
+ *
+ * The virtualizer needs this as a number — it cannot read the CSS variable —
+ * so the scale lives here and `TMDataGrid.module.css` mirrors it. `meta.rowHeight`
+ * overrides it when a grid needs a height the scale doesn't offer.
+ */
+declare const SIZE_ROW_HEIGHT: Record<TMDataGridSize, number>;
+/** Size of the Mantine controls rendered inside the grid chrome. */
+declare const SIZE_CONTROL_SIZE: Record<TMDataGridSize, MantineSize>;
+//#endregion
 //#region .types-tmp/core/filterOperators.d.ts
 /**
  * The value shape stored in `columnFilters` for every TMDataGrid column.
@@ -41,6 +55,18 @@ declare const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string>;
  * are treated as inactive for the funnel indicator and for row matching.
  */
 declare function isFilterActive(value: unknown): boolean;
+/**
+ * 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.
+ */
+declare function formatFilterLabel({ label, type, filter }: {
+  label: string;
+  type: TMDataGridColumnType;
+  filter: TMDataGridFilterValue;
+}): string;
 /**
  * The single filter function every TMDataGrid column uses. It dispatches on the
  * operator carried by the filter value, which is what lets one column offer
@@ -69,12 +95,12 @@ type GridState = TableState<TMDataGridFeatures>;
  * State slices describing what the user is looking at. Derived from the data,
  * so they can go stale as it changes.
  */
-declare const DATA_STATE_SLICES: readonly ["columnFilters", "globalFilter", "sorting", "pagination"];
+declare const DATA_STATE_SLICES: readonly ["columnFilters", "globalFilter", "sorting", "pagination", "expanded"];
 /**
  * State slices describing how the user configured the grid. Independent of the
  * data, and the ones users notice losing.
  */
-declare const SETTINGS_STATE_SLICES: readonly ["columnVisibility", "columnSizing", "columnOrder", "columnPinning"];
+declare const SETTINGS_STATE_SLICES: readonly ["columnVisibility", "columnSizing", "columnOrder", "columnPinning", "grouping"];
 type TMDataGridDataSlice = (typeof DATA_STATE_SLICES)[number];
 type TMDataGridSettingsSlice = (typeof SETTINGS_STATE_SLICES)[number];
 /**
@@ -99,20 +125,6 @@ type TMDataGridPersistence = {
   deserialize?: (value: string) => unknown;
 };
 //#endregion
-//#region .types-tmp/core/sizes.d.ts
-type TMDataGridSize = MantineSize;
-declare const DEFAULT_TMDATAGRID_SIZE: TMDataGridSize;
-/**
- * Row height per size, in px.
- *
- * The virtualizer needs this as a number — it cannot read the CSS variable —
- * so the scale lives here and `TMDataGrid.module.css` mirrors it. `meta.rowHeight`
- * overrides it when a grid needs a height the scale doesn't offer.
- */
-declare const SIZE_ROW_HEIGHT: Record<TMDataGridSize, number>;
-/** Size of the Mantine controls rendered inside the grid chrome. */
-declare const SIZE_CONTROL_SIZE: Record<TMDataGridSize, MantineSize>;
-//#endregion
 //#region .types-tmp/TMDataGridContext.d.ts
 /**
  * Row shape the chrome components work against. They only ever touch columns,
@@ -143,9 +155,23 @@ declare function useTMDataGridContext(): TMDataGridContextValue;
  * 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.
  */
-type TMDataGridRowSelectionMode = "checkbox" | "row";
+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";
 type TMDataGridFeatureFlags = {
   sorting: boolean;
   filtering: boolean;
@@ -153,19 +179,51 @@ 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;
 };
-declare function readFeatureFlags<TData extends RowData>(options: Pick<UseTMDataGridOptions<TData>, "enableSorting" | "enableColumnFilters" | "enableHiding" | "enableColumnPinning" | "enableColumnResizing" | "enableColumnOrdering" | "enableRowSelection" | "rowSelectionMode" | "highlightSelectedRows" | "enablePagination" | "manualPagination">): TMDataGridFeatureFlags;
+declare function readFeatureFlags<TData extends RowData>(options: Pick<UseTMDataGridOptions<TData>, "enableSorting" | "enableColumnFilters" | "enableHiding" | "enableColumnPinning" | "enableColumnResizing" | "enableColumnOrdering" | "enableRowSelection" | "enableMultiRowSelection" | "selectionMode" | "showSelectedBackground" | "enablePagination" | "manualPagination" | "enableGrouping">): TMDataGridFeatureFlags;
 /**
  * What one column's header may offer.
  *
@@ -177,6 +235,7 @@ declare function readFeatureFlags<TData extends RowData>(options: Pick<UseTMData
  * | 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) |
  */
 type TMDataGridColumnCapabilities = {
   canSort: boolean;
@@ -185,6 +244,7 @@ type TMDataGridColumnCapabilities = {
   canPin: boolean;
   canResize: boolean;
   canReorder: boolean;
+  canGroup: boolean;
 };
 declare function getColumnCapabilities(column: Column<TMDataGridFeatures, TMDataGridRowData, unknown>, features: TMDataGridFeatureFlags): TMDataGridColumnCapabilities;
 /** The same questions, asked of the whole grid — used to hide toolbar buttons. */
@@ -194,6 +254,7 @@ type TMDataGridCapabilities = {
   canHideAny: boolean;
   canPinAny: boolean;
   canReorderAny: boolean;
+  canGroupAny: boolean;
   canSelectRows: boolean;
   canPaginate: boolean;
 };
@@ -244,8 +305,12 @@ declare const tmDataGridFeatures: {
   columnSizingFeature: import("@tanstack/table-core").TableFeature;
   columnResizingFeature: import("@tanstack/table-core").TableFeature;
   columnFacetingFeature: import("@tanstack/table-core").TableFeature;
+  columnGroupingFeature: import("@tanstack/table-core").TableFeature;
+  rowExpandingFeature: import("@tanstack/table-core").TableFeature;
   filteredRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  groupedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
   sortedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  expandedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
   paginatedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
   facetedRowModel: (table: Table<any, any>, columnId: string) => () => import("@tanstack/table-core").RowModel<any, any>;
   facetedMinMaxValues: (table: Table<import("@tanstack/table-core").TableFeatures, any>, columnId: string) => () => undefined | [number, number];
@@ -296,6 +361,17 @@ declare const tmDataGridFeatures: {
     text: <TFeatures extends import("@tanstack/table-core").TableFeatures, TData extends RowData>(rowA: import("@tanstack/table-core").Row<TFeatures, TData>, rowB: import("@tanstack/table-core").Row<TFeatures, TData>, columnId: string) => 0 | 1 | -1;
     textCaseSensitive: <TFeatures extends import("@tanstack/table-core").TableFeatures, TData extends RowData>(rowA: import("@tanstack/table-core").Row<TFeatures, TData>, rowB: import("@tanstack/table-core").Row<TFeatures, TData>, columnId: string) => 0 | 1 | -1;
   };
+  aggregationFns: {
+    sum: typeof import("@tanstack/table-core").aggregationFn_sum;
+    min: typeof import("@tanstack/table-core").aggregationFn_min;
+    max: typeof import("@tanstack/table-core").aggregationFn_max;
+    extent: typeof import("@tanstack/table-core").aggregationFn_extent;
+    mean: typeof import("@tanstack/table-core").aggregationFn_mean;
+    median: typeof import("@tanstack/table-core").aggregationFn_median;
+    unique: typeof import("@tanstack/table-core").aggregationFn_unique;
+    uniqueCount: typeof import("@tanstack/table-core").aggregationFn_uniqueCount;
+    count: typeof import("@tanstack/table-core").aggregationFn_count;
+  };
   tableMeta: TMDataGridTableMeta;
   columnMeta: TMDataGridColumnMeta;
 };
@@ -313,8 +389,12 @@ declare function createTMDataGridColumnHelper<TData extends RowData>(): import("
   columnSizingFeature: import("@tanstack/table-core").TableFeature;
   columnResizingFeature: import("@tanstack/table-core").TableFeature;
   columnFacetingFeature: import("@tanstack/table-core").TableFeature;
+  columnGroupingFeature: import("@tanstack/table-core").TableFeature;
+  rowExpandingFeature: import("@tanstack/table-core").TableFeature;
   filteredRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  groupedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
   sortedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
+  expandedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
   paginatedRowModel: (table: Table<any, any>) => () => import("@tanstack/table-core").RowModel<any, any>;
   facetedRowModel: (table: Table<any, any>, columnId: string) => () => import("@tanstack/table-core").RowModel<any, any>;
   facetedMinMaxValues: (table: Table<import("@tanstack/table-core").TableFeatures, any>, columnId: string) => () => undefined | [number, number];
@@ -365,6 +445,17 @@ declare function createTMDataGridColumnHelper<TData extends RowData>(): import("
     text: <TFeatures extends import("@tanstack/table-core").TableFeatures, TData_1 extends RowData>(rowA: import("@tanstack/table-core").Row<TFeatures, TData_1>, rowB: import("@tanstack/table-core").Row<TFeatures, TData_1>, columnId: string) => 0 | 1 | -1;
     textCaseSensitive: <TFeatures extends import("@tanstack/table-core").TableFeatures, TData_1 extends RowData>(rowA: import("@tanstack/table-core").Row<TFeatures, TData_1>, rowB: import("@tanstack/table-core").Row<TFeatures, TData_1>, columnId: string) => 0 | 1 | -1;
   };
+  aggregationFns: {
+    sum: typeof import("@tanstack/table-core").aggregationFn_sum;
+    min: typeof import("@tanstack/table-core").aggregationFn_min;
+    max: typeof import("@tanstack/table-core").aggregationFn_max;
+    extent: typeof import("@tanstack/table-core").aggregationFn_extent;
+    mean: typeof import("@tanstack/table-core").aggregationFn_mean;
+    median: typeof import("@tanstack/table-core").aggregationFn_median;
+    unique: typeof import("@tanstack/table-core").aggregationFn_unique;
+    uniqueCount: typeof import("@tanstack/table-core").aggregationFn_uniqueCount;
+    count: typeof import("@tanstack/table-core").aggregationFn_count;
+  };
   tableMeta: TMDataGridTableMeta;
   columnMeta: TMDataGridColumnMeta;
 }, TData>;
@@ -383,6 +474,20 @@ type TMDataGridUiState = {
    * `dataTransfer`, which browsers keep unreadable until the drop.
    */
   draggedColumnId: string | null;
+  /**
+   * The single highlighted row — the one a detail panel would be showing. Its
+   * own concept, not a slice of `rowSelection`: under
+   * `selectionMode: "checkboxAndHighlight"` the two coexist, and TanStack's one
+   * selection map cannot hold both.
+   *
+   * Not pruned when the row is filtered out, paged away or dropped from `data`,
+   * matching how TanStack treats `rowSelection` — nothing there resets it
+   * either. The row simply renders unhighlighted, and highlights again if it
+   * comes back.
+   */
+  highlightedRowId: string | null;
+  /** The pivot a shift-click extends from. See resolveRowSelectionClick. */
+  selectionAnchorRowId: string | null;
 };
 type TMDataGridUiActions = {
   openFilterPanel: (columnId?: string | null) => void;
@@ -391,6 +496,12 @@ type TMDataGridUiActions = {
   toggleColumnsPanel: () => void;
   startColumnDrag: (columnId: string) => void;
   endColumnDrag: () => void;
+  /**
+   * Moves the active row, or clears it with `null` — which is how a consumer
+   * closing its detail panel puts the grid back in step.
+   */
+  setHighlightedRow: (rowId: string | null) => void;
+  setSelectionAnchor: (rowId: string | null) => void;
 };
 type TMDataGridUiStore = Store<TMDataGridUiState, TMDataGridUiActions>;
 /** What `useTMDataGrid` returns — spread straight onto `<TMDataGrid />`. */
@@ -431,18 +542,29 @@ type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridF
   /**
    * How rows are selected. Defaults to `"checkbox"`.
    *
-   * - `"checkbox"` — the generated checkbox column selects; clicking a row
-   *   elsewhere does not.
-   * - `"row"` — no checkbox column; clicking a row toggles it. Other rows keep
-   *   their state, so a click never clears the rest of the selection.
+   * | Mode | Checkbox column | Row click |
+   * | ---- | --------------- | --------- |
+   * | `"checkbox"` | yes, multi-select | nothing |
+   * | `"row"` | no | multi-selects, Ctrl/Shift modifiers |
+   * | `"checkboxAndHighlight"` | yes, multi-select | highlights one row |
+   * | `"highlight"` | no | highlights one row, no selection at all |
    *
-   * Ignored when `enableRowSelection` is `false`. Both modes write to the same
-   * `rowSelection` state.
+   * One option rather than two, so the combination that cannot work — a click
+   * that both toggles a multi-selection and moves the highlight — is not
+   * expressible.
+   *
+   * The first two write to TanStack's `rowSelection`. The highlight is separate
+   * state, which is what lets `"checkboxAndHighlight"` run both at once: tick
+   * rows for a bulk action, click one to open its detail panel. See
+   * `defaultHighlightedRowId` / `onHighlightedRowChange`.
+   *
+   * `enableRowSelection` still gates the selection half, predicate form
+   * included; under `"highlight"` there is nothing for it to gate.
    */
-  rowSelectionMode?: TMDataGridRowSelectionMode;
+  selectionMode?: TMDataGridSelectionMode;
   /**
    * Give selected rows the highlight background. Defaults to `true` under
-   * `rowSelectionMode: "row"`, where the highlight is the only feedback a click
+   * `selectionMode: "row"`, where the highlight is the only feedback a click
    * gives, and `false` under `"checkbox"`, where the box already shows it.
    *
    * The colour is the `--dg-row-selected-bg` CSS variable, so it can be changed
@@ -455,7 +577,31 @@ type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridF
    * />
    * ```
    */
-  highlightSelectedRows?: boolean;
+  showSelectedBackground?: boolean;
+  /**
+   * The row that starts out highlighted, under a `selectionMode` that has a
+   * highlight. Read once on mount, like `initialState`.
+   *
+   * The grid never persists the highlighted row. Pair this with
+   * {@link onHighlightedRowChange} and keep it wherever it belongs — for a
+   * detail panel that is usually the route, which gets you a shareable link and
+   * a working back button as well as surviving a reload:
+   *
+   * ```tsx
+   * const { rowId } = useParams();
+   * useTMDataGrid({
+   *   selectionMode: "highlight",
+   *   defaultHighlightedRowId: rowId,
+   *   onHighlightedRowChange: (id) => navigate(id ? `/employees/${id}` : "/employees"),
+   * });
+   * ```
+   */
+  defaultHighlightedRowId?: string | null;
+  /**
+   * Called with the newly highlighted row id, or `null` when it is cleared.
+   * Fires for `ui.actions.setHighlightedRow` too, not only for clicks.
+   */
+  onHighlightedRowChange?: (rowId: string | null) => void;
 };
 /**
  * Builds a TMDataGrid table plus its chrome store.
@@ -468,13 +614,50 @@ type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridF
  * flag on, so `<TMDataGrid.Footer />` renders its pager without further
  * options.
  */
-declare function useTMDataGrid<TData extends RowData>({ persist, enableColumnOrdering, enablePagination, rowSelectionMode, highlightSelectedRows, ...options }: UseTMDataGridOptions<TData>): TMDataGridApi<TData>;
+declare function useTMDataGrid<TData extends RowData>({ persist, enableColumnOrdering, enablePagination, selectionMode, showSelectedBackground, defaultHighlightedRowId, onHighlightedRowChange, ...options }: UseTMDataGridOptions<TData>): TMDataGridApi<TData>;
 /**
  * Opens the filter panel for a column, seeding an empty filter row when the
  * column has none yet — mirrors "Filter" in the column header menu.
  */
 declare function openColumnFilter<TData extends RowData>(api: TMDataGridApi<TData>, columnId: string): void;
 //#endregion
+//#region .types-tmp/components/TMDataGridFilterPills.d.ts
+type TMDataGridFilterPillsProps<TData extends RowData> = {
+  /** The object returned by `useTMDataGrid`. */
+  api: TMDataGridApi<TData>;
+  /** Mantine size of the pills. Defaults to `"sm"`. */
+  size?: TMDataGridSize;
+  /** "Clear all" button, shown once two filters are active. Defaults to `true`. */
+  showClearAll?: boolean;
+  /**
+   * Replaces what a click on a pill's label does. The default opens the grid's
+   * filter panel on that column.
+   */
+  onPillClick?: (columnId: string) => void;
+  className?: string;
+};
+/**
+ * One pill per active filter — `First name: Sofia ✕` — with the ✕ clearing that
+ * filter and a click on the label opening the filter panel on its column.
+ *
+ * The one grid component that takes the api as a prop instead of reading
+ * context, so it can live anywhere: a page header, a card title, a breadcrumb
+ * row. Renders nothing while no filter is active.
+ *
+ * ```tsx
+ * const grid = useTMDataGrid({ data, columns });
+ *
+ * <Group>
+ *   <Title order={3}>Employees</Title>
+ *   <TMDataGridFilterPills api={grid} />
+ * </Group>
+ * ```
+ *
+ * Half-typed filters are left out: a filter that is not narrowing the rows yet
+ * has nothing to report, which is the same rule the funnel indicator uses.
+ */
+declare function TMDataGridFilterPills<TData extends RowData>({ api, size, showClearAll, onPillClick, className }: TMDataGridFilterPillsProps<TData>): import("react").JSX.Element | null;
+//#endregion
 //#region .types-tmp/components/TMDataGridFooter.d.ts
 /** Distilled pagination state and actions for building a custom pager. */
 type TMDataGridPaginationApi = {
@@ -524,12 +707,63 @@ type TMDataGridColumnLayout = {
   /** Last left-pinned / first right-pinned column — the one that casts the edge. */
   isBoundary: boolean;
 };
+/** What a `rowContextMenu` render prop is handed for the right-clicked row. */
+type TMDataGridRowContextMenuArgs<TData extends RowData> = {
+  table: Table<TMDataGridFeatures, TData>;
+  row: Row<TMDataGridFeatures, TData>;
+  /**
+   * The cell under the pointer. `null` only when the right-click landed on the
+   * row but on no cell — which a custom cell renderer that stops propagation
+   * can cause.
+   */
+  cell: Cell<TMDataGridFeatures, TData, unknown> | null;
+  /**
+   * Closes the menu. `Menu.Item` already closes on click (Mantine's
+   * `closeOnItemClick`), so this is for content that isn't a menu item.
+   */
+  close: () => void;
+};
+/**
+ * Builds the contents of a row's context menu — `Menu.Item`, `Menu.Label`,
+ * `Menu.Divider`, `Menu.Sub`, or any other node. The grid owns the `Menu` and
+ * its `Menu.Dropdown`; this fills the dropdown.
+ */
+type TMDataGridRowContextMenu<TData extends RowData> = (args: TMDataGridRowContextMenuArgs<TData>) => ReactNode;
 type TMDataGridTableProps<TData extends RowData> = {
   /**
    * Called when a body row is clicked. Runs in addition to row selection under
-   * `rowSelectionMode: "row"`, not instead of it.
+   * `selectionMode: "row"`, not instead of it.
    */
   onRowClick?: (row: Row<TMDataGridFeatures, TData>) => void;
+  /**
+   * Contents of the menu a right-click on a row opens, at the pointer. Return
+   * `null` to leave a row without one — the browser's own menu stays suppressed
+   * either way.
+   *
+   * ```tsx
+   * <TMDataGrid.Table<Employee>
+   *   rowContextMenu={({ row, close }) => (
+   *     <>
+   *       <Menu.Label>{row.original.firstName}</Menu.Label>
+   *       <Menu.Item onClick={() => open(row.original.id)}>Open</Menu.Item>
+   *       <Menu.Divider />
+   *       <Menu.Item color="red" onClick={() => remove(row.original.id)}>
+   *         Delete
+   *       </Menu.Item>
+   *     </>
+   *   )}
+   * />
+   * ```
+   *
+   * Called during render, and only for the row whose menu is open — so it stays
+   * a pure function of the row, and cost per row does not matter.
+   */
+  rowContextMenu?: TMDataGridRowContextMenu<TData>;
+  /**
+   * Passed to the Mantine `Menu` the grid wraps the row in — `width`, `shadow`,
+   * `position`, `transitionProps` and the rest. Its open state is the grid's.
+   */
+  rowContextMenuProps?: Omit<MenuProps, "opened" | "onChange" | "children">;
 };
 /**
  * The scrollable grid surface. Always virtualized: only the rows inside the
@@ -537,7 +771,7 @@ type TMDataGridTableProps<TData extends RowData> = {
  * no-pagination mode viable at any row count. Pagination is opt-in via
  * `enablePagination` (or implied by `manualPagination`).
  */
-declare function TMDataGridTable$1<TData extends RowData = TMDataGridRowData>({ onRowClick }: TMDataGridTableProps<TData>): import("react").JSX.Element;
+declare function TMDataGridTable$1<TData extends RowData = TMDataGridRowData>({ onRowClick, rowContextMenu, rowContextMenuProps }: TMDataGridTableProps<TData>): import("react").JSX.Element;
 //#endregion
 //#region .types-tmp/components/TMDataGridToolbar.d.ts
 /** Row above the grid. Compose it from the pieces below, or anything else. */
@@ -609,6 +843,11 @@ declare const TMDataGrid: typeof TMDataGridRoot & {
   Footer: typeof TMDataGridFooter;
   /** Rendered by `TMDataGrid.Table`; exported for custom layouts. */
   FilterPanel: typeof TMDataGridFilterPanel;
+  /**
+   * Takes the grid as an `api` prop rather than from context, so it can be
+   * rendered outside `<TMDataGrid>` — a page header, for instance.
+   */
+  FilterPills: typeof TMDataGridFilterPills;
   /** Rendered by `TMDataGrid.ColumnsButton`; exported for custom layouts. */
   ColumnsPanel: typeof TMDataGridColumnsPanel;
 };
@@ -616,6 +855,17 @@ declare const TMDataGrid: typeof TMDataGridRoot & {
 //#region .types-tmp/components/TMDataGridSelectColumn.d.ts
 declare const SELECT_COLUMN_ID = "__select__";
 //#endregion
+//#region .types-tmp/components/TMDataGridGroupColumn.d.ts
+declare const GROUP_COLUMN_ID = "__group__";
+/**
+ * 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.
+ */
+declare function formatGroupValue(value: unknown): string;
+//#endregion
 //#region .types-tmp/core/columnUtils.d.ts
 /**
  * Structural shape of the column bits the chrome reads. Kept minimal so these
@@ -644,6 +894,21 @@ declare function getColumnType(column: ColumnLike): TMDataGridColumnType;
  */
 declare function isColumnReorderable(column: ColumnLike): boolean;
 //#endregion
+//#region .types-tmp/core/grouping.d.ts
+/**
+ * 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.
+ */
+declare function getGroupDataRows<TData extends RowData>(row: Row<TMDataGridFeatures, TData>): Array<Row<TMDataGridFeatures, TData>>;
+//#endregion
 //#region .types-tmp/core/columnOrdering.d.ts
 type GridColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
 type GridTable = TMDataGridTable<TMDataGridRowData>;
@@ -694,4 +959,99 @@ declare function getStepTargetColumn({ table, columnId, direction }: ColumnStepA
 /** Moves a column one position within its lane. Hidden columns are stepped over. */
 declare function moveColumnByStep({ table, columnId, direction }: ColumnStepArgs): void;
 //#endregion
-export { type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_TMDATAGRID_SIZE, FILTER_OPERATOR_LABELS, type MoveColumnArgs, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDataGrid, type TMDataGridApi, type TMDataGridCapabilities, type TMDataGridColumnCapabilities, type TMDataGridColumnLayout, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnType, type TMDataGridContextValue, type TMDataGridDataSlice, type TMDataGridDropSide, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFilterOperator, type TMDataGridFilterValue, type TMDataGridFooterProps, type TMDataGridPaginationApi, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridRowData, type TMDataGridRowSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, createTMDataGridColumnHelper, getColumnCapabilities, getColumnLabel, getColumnRegion, getColumnType, getGridCapabilities, getStepTargetColumn, getTMDataGridPaginationApi, isColumnReorderable, isFilterActive, moveColumn, moveColumnByStep, openColumnFilter, readFeatureFlags, tmDataGridFeatures, useTMDataGrid, useTMDataGridContext };
+//#region .types-tmp/core/rowSelection.d.ts
+/**
+ * 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}.
+ */
+declare function getDisplayedRows<TData extends RowData>(table: TMDataGridTable<TData>, features: TMDataGridFeatureFlags): Array<Row<TMDataGridFeatures, TData>>;
+/**
+ * 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.
+ */
+declare function isPagingActive<TData extends RowData>(table: TMDataGridTable<TData>, features: TMDataGridFeatureFlags): boolean;
+/**
+ * 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.
+ */
+type TMDataGridRowClickModifiers = {
+  toggle: boolean;
+  extend: boolean;
+};
+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;
+};
+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.
+ */
+declare function getSelectableRowIds<TData extends RowData>(row: Row<TMDataGridFeatures, TData>): Array<string>;
+/**
+ * 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.
+ */
+declare function resolveRowSelectionClick<TData extends RowData>({ rows, rowId, anchorRowId, modifiers, selection, canReplaceSelection }: ResolveRowSelectionClickArgs<TData>): ResolvedRowSelection;
+//#endregion
+export { type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_TMDATAGRID_SIZE, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDataGrid, type TMDataGridApi, type TMDataGridCapabilities, type TMDataGridColumnCapabilities, type TMDataGridColumnLayout, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnType, type TMDataGridContextValue, type TMDataGridDataSlice, type TMDataGridDropSide, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFilterOperator, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterValue, type TMDataGridFooterProps, type TMDataGridPaginationApi, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenu, type TMDataGridRowContextMenuArgs, type TMDataGridRowData, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, createTMDataGridColumnHelper, formatFilterLabel, formatGroupValue, getColumnCapabilities, getColumnLabel, getColumnRegion, getColumnType, getDisplayedRows, getGridCapabilities, getGroupDataRows, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, isColumnReorderable, isFilterActive, isPagingActive, moveColumn, moveColumnByStep, openColumnFilter, readFeatureFlags, resolveRowSelectionClick, tmDataGridFeatures, useTMDataGrid, useTMDataGridContext };