@jielga/tmdatagrid 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,592 @@
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+import { TableFeatures, RowData, Row, TableState, Column, Table, TableOptions, ColumnPinningState } from '@tanstack/react-table';
+import { MantineSize } from '@mantine/core';
+import * as _tanstack_table_core from '@tanstack/table-core';
+import { Store } from '@tanstack/store';
+
+/**
+ * The "Manage columns" surface. Reachable from every column header menu and
+ * from the grid's burger menu, so it lives on its own and is rendered by
+ * `TMDataGrid.ColumnsButton`.
+ */
+declare function TMDataGridColumnsPanel(): react.JSX.Element;
+
+/**
+ * The MUI-style filter surface: one row per active column filter, each row a
+ * column / operator / value triple. It only ever reads and writes the table's
+ * `columnFilters` state, so a `manualFiltering` grid gets the same panel for
+ * free — the state is forwarded to the server instead of a row model.
+ */
+declare function TMDataGridFilterPanel(): react.JSX.Element | null;
+
+type TMDataGridFooterProps = {
+    pageSizeOptions?: ReadonlyArray<number>;
+};
+/**
+ * MUI-style pager: "Rows per page · from–to of total · ‹ ›".
+ *
+ * Row totals come from `table.getRowCount()`, which prefers `options.rowCount`
+ * — so a server-paged grid shows the server's total without changes here.
+ */
+declare function TMDataGridFooter({ pageSizeOptions, }: TMDataGridFooterProps): react.JSX.Element;
+
+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>;
+
+/**
+ * The value shape stored in `columnFilters` for every TMDataGrid column.
+ *
+ * TanStack resolves `filterFn` statically per column, so the operator travels
+ * inside the filter *value* instead. That keeps the whole filter model plain,
+ * serialisable JSON — which is what makes it portable to a server-side
+ * `manualFiltering` table (just forward `columnFilters` to the API).
+ */
+type TMDataGridFilterValue = {
+    operator: TMDataGridFilterOperator;
+    value: string;
+};
+type TMDataGridColumnType = "string" | "number";
+type TMDataGridFilterOperator = "contains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "greaterThan" | "greaterThanOrEqual" | "lessThan" | "lessThanOrEqual" | "isEmpty" | "isNotEmpty";
+declare const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string>;
+/**
+ * A filter only narrows the row set once it has something to compare against.
+ * Half-typed filters stay in state (so the panel keeps rendering their row) but
+ * are treated as inactive for the funnel indicator and for row matching.
+ */
+declare function isFilterActive(value: unknown): boolean;
+/**
+ * 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
+ * "contains" / "does not equal" / "is empty" without redefining the column.
+ */
+declare function tmDataGridFilterFn<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData>, columnId: string, filterValue: unknown): boolean;
+
+type GridState = TableState<TMDataGridFeatures>;
+/**
+ * Persistence deliberately does not use Mantine's `useLocalStorage`.
+ *
+ * That hook owns a piece of state and returns `[value, setValue]`. Here the
+ * table already owns the state and storage only mirrors it, so routing writes
+ * through the hook would keep a second copy and trigger a React state update on
+ * every change, including every pointer move during a column resize. Its
+ * defaults also work against this use: `getInitialValueInEffect: true` delivers
+ * the stored value after mount, while `initialState` is only read on the first
+ * render, and `sync: true` would let two open tabs overwrite each other's
+ * column layout.
+ *
+ * The option vocabulary follows Mantine's: `StorageType` is its type, and
+ * `serialize` / `deserialize` behave as they do in `UseStorageOptions`.
+ */
+/**
+ * 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"];
+/**
+ * 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"];
+type TMDataGridDataSlice = (typeof DATA_STATE_SLICES)[number];
+type TMDataGridSettingsSlice = (typeof SETTINGS_STATE_SLICES)[number];
+/**
+ * A storage key, optionally narrowed to a subset of its group's slices.
+ *
+ * - `"employees.data"` — persists every slice in the group.
+ * - `["employees.data", ["sorting"]]` — persists only the listed slices.
+ */
+type TMDataGridPersistKey<TSlice extends string> = string | readonly [key: string, slices: readonly TSlice[]];
+/** Same values as Mantine's `StorageType`, which the package does not re-export. */
+type TMDataGridStorageMode = "localStorage" | "sessionStorage";
+type TMDataGridPersistence = {
+    /** Key for filters, global filter, sorting and pagination. */
+    dataKey?: TMDataGridPersistKey<TMDataGridDataSlice>;
+    /** Key for column visibility, sizing, order and pinning. */
+    settingsKey?: TMDataGridPersistKey<TMDataGridSettingsSlice>;
+    /** Which storage area to use. Defaults to `"localStorage"`. */
+    storageMode?: TMDataGridStorageMode;
+    /** Serializes a payload before it is stored. Defaults to `JSON.stringify`. */
+    serialize?: (value: Partial<GridState>) => string;
+    /** Parses a stored payload. Defaults to `JSON.parse`. */
+    deserialize?: (value: string) => unknown;
+};
+
+/**
+ * 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.
+ */
+type TMDataGridFeatureFlags = {
+    sorting: boolean;
+    filtering: boolean;
+    hiding: boolean;
+    pinning: boolean;
+    resizing: boolean;
+    ordering: boolean;
+    rowSelection: boolean;
+};
+declare function readFeatureFlags<TData extends RowData>(options: Pick<UseTMDataGridOptions<TData>, "enableSorting" | "enableColumnFilters" | "enableHiding" | "enableColumnPinning" | "enableColumnResizing" | "enableColumnOrdering" | "enableRowSelection">): TMDataGridFeatureFlags;
+/**
+ * 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` |
+ */
+type TMDataGridColumnCapabilities = {
+    canSort: boolean;
+    canFilter: boolean;
+    canHide: boolean;
+    canPin: boolean;
+    canResize: boolean;
+    canReorder: 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. */
+type TMDataGridCapabilities = {
+    canSortAny: boolean;
+    canFilterAny: boolean;
+    canHideAny: boolean;
+    canPinAny: boolean;
+    canReorderAny: boolean;
+    canSelectRows: boolean;
+};
+declare function getGridCapabilities(table: TMDataGridTable$1<TMDataGridRowData>, features: TMDataGridFeatureFlags): TMDataGridCapabilities;
+
+declare const SELECT_COLUMN_ID = "__select__";
+/** Per-column configuration the TMDataGrid chrome reads. */
+type TMDataGridColumnMeta = {
+    /** Name shown in menus and the column manager. Falls back to a string header. */
+    label?: string;
+    /** Drives which filter operators are offered. Defaults to `"string"`. */
+    type?: TMDataGridColumnType;
+    /** Share of the leftover width this column claims. Defaults to `1`. */
+    flex?: number;
+    align?: "left" | "right" | "center";
+    /**
+     * `false` keeps the column where it is: no header dragging, no move items.
+     * Column ordering is the one feature TanStack defines no column option for,
+     * so its switch lives here rather than on the column definition.
+     */
+    enableOrdering?: boolean;
+};
+/** Grid-wide configuration passed through `options.meta`. */
+type TMDataGridTableMeta = {
+    loading?: boolean;
+    noResultsLabel?: string;
+    /** Row height used by the virtualizer. Defaults to `52`. */
+    rowHeight?: number;
+    /**
+     * Unfiltered row total. Only needed for server-driven grids, where the client
+     * never holds the full data set — `TMDataGrid.SummaryCount` uses it as denominator.
+     */
+    totalRowCount?: number;
+};
+/**
+ * Every feature the TMDataGrid chrome can drive. Defined at module scope so the
+ * reference stays stable across renders (see the TanStack table-state skill).
+ */
+declare const tmDataGridFeatures: {
+    columnFilteringFeature: _tanstack_table_core.TableFeature;
+    globalFilteringFeature: _tanstack_table_core.TableFeature;
+    rowSortingFeature: _tanstack_table_core.TableFeature;
+    rowPaginationFeature: _tanstack_table_core.TableFeature;
+    rowSelectionFeature: _tanstack_table_core.TableFeature;
+    columnPinningFeature: _tanstack_table_core.TableFeature;
+    columnVisibilityFeature: _tanstack_table_core.TableFeature;
+    columnOrderingFeature: _tanstack_table_core.TableFeature;
+    columnSizingFeature: _tanstack_table_core.TableFeature;
+    columnResizingFeature: _tanstack_table_core.TableFeature;
+    columnFacetingFeature: _tanstack_table_core.TableFeature;
+    filteredRowModel: (table: Table<any, any>) => () => _tanstack_table_core.RowModel<any, any>;
+    sortedRowModel: (table: Table<any, any>) => () => _tanstack_table_core.RowModel<any, any>;
+    paginatedRowModel: (table: Table<any, any>) => () => _tanstack_table_core.RowModel<any, any>;
+    facetedRowModel: (table: Table<any, any>, columnId: string) => () => _tanstack_table_core.RowModel<any, any>;
+    facetedMinMaxValues: (table: Table<_tanstack_table_core.TableFeatures, any>, columnId: string) => () => undefined | [number, number];
+    facetedUniqueValues: (table: Table<_tanstack_table_core.TableFeatures, any>, columnId: string) => () => Map<any, number>;
+    filterFns: {
+        tmDataGrid: typeof tmDataGridFilterFn;
+        arrIncludes: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: Array<unknown>) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        arrIncludesAll: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: Array<unknown>) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        arrHas: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: Array<unknown>) => boolean;
+        arrIncludesSome: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: Array<unknown>) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        between: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValues: [unknown, unknown]) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        betweenInclusive: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValues: [unknown, unknown]) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        equals: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        equalsString: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        inNumberRange: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: [number, number]) => boolean) & {
+            resolveFilterValue: (val: [any, any]) => readonly [number, number];
+            autoRemove: (val: any) => boolean;
+        };
+        includesString: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        includesStringSensitive: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        weakEquals: (<TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+    };
+    sortFns: {
+        alphanumeric: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData>, rowB: _tanstack_table_core.Row<TFeatures, TData>, columnId: string) => number;
+        alphanumericCaseSensitive: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData>, rowB: _tanstack_table_core.Row<TFeatures, TData>, columnId: string) => number;
+        basic: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData>, rowB: _tanstack_table_core.Row<TFeatures, TData>, columnId: string) => 0 | 1 | -1;
+        datetime: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData>, rowB: _tanstack_table_core.Row<TFeatures, TData>, columnId: string) => 0 | 1 | -1;
+        text: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData>, rowB: _tanstack_table_core.Row<TFeatures, TData>, columnId: string) => 0 | 1 | -1;
+        textCaseSensitive: <TFeatures extends _tanstack_table_core.TableFeatures, TData extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData>, rowB: _tanstack_table_core.Row<TFeatures, TData>, columnId: string) => 0 | 1 | -1;
+    };
+    tableMeta: TMDataGridTableMeta;
+    columnMeta: TMDataGridColumnMeta;
+};
+type TMDataGridFeatures = typeof tmDataGridFeatures;
+type TMDataGridTable$1<TData extends RowData> = Table<TMDataGridFeatures, TData>;
+declare function createTMDataGridColumnHelper<TData extends RowData>(): _tanstack_table_core.ColumnHelper<{
+    columnFilteringFeature: _tanstack_table_core.TableFeature;
+    globalFilteringFeature: _tanstack_table_core.TableFeature;
+    rowSortingFeature: _tanstack_table_core.TableFeature;
+    rowPaginationFeature: _tanstack_table_core.TableFeature;
+    rowSelectionFeature: _tanstack_table_core.TableFeature;
+    columnPinningFeature: _tanstack_table_core.TableFeature;
+    columnVisibilityFeature: _tanstack_table_core.TableFeature;
+    columnOrderingFeature: _tanstack_table_core.TableFeature;
+    columnSizingFeature: _tanstack_table_core.TableFeature;
+    columnResizingFeature: _tanstack_table_core.TableFeature;
+    columnFacetingFeature: _tanstack_table_core.TableFeature;
+    filteredRowModel: (table: Table<any, any>) => () => _tanstack_table_core.RowModel<any, any>;
+    sortedRowModel: (table: Table<any, any>) => () => _tanstack_table_core.RowModel<any, any>;
+    paginatedRowModel: (table: Table<any, any>) => () => _tanstack_table_core.RowModel<any, any>;
+    facetedRowModel: (table: Table<any, any>, columnId: string) => () => _tanstack_table_core.RowModel<any, any>;
+    facetedMinMaxValues: (table: Table<_tanstack_table_core.TableFeatures, any>, columnId: string) => () => undefined | [number, number];
+    facetedUniqueValues: (table: Table<_tanstack_table_core.TableFeatures, any>, columnId: string) => () => Map<any, number>;
+    filterFns: {
+        tmDataGrid: typeof tmDataGridFilterFn;
+        arrIncludes: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: Array<unknown>) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        arrIncludesAll: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: Array<unknown>) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        arrHas: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: Array<unknown>) => boolean;
+        arrIncludesSome: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: Array<unknown>) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        between: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValues: [unknown, unknown]) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        betweenInclusive: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValues: [unknown, unknown]) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        equals: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        equalsString: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        inNumberRange: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: [number, number]) => boolean) & {
+            resolveFilterValue: (val: [any, any]) => readonly [number, number];
+            autoRemove: (val: any) => boolean;
+        };
+        includesString: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        includesStringSensitive: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+        weakEquals: (<TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(row: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string, filterValue: unknown) => boolean) & {
+            autoRemove: (val: any) => boolean;
+        };
+    };
+    sortFns: {
+        alphanumeric: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData_1>, rowB: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string) => number;
+        alphanumericCaseSensitive: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData_1>, rowB: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string) => number;
+        basic: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData_1>, rowB: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string) => 0 | 1 | -1;
+        datetime: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData_1>, rowB: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string) => 0 | 1 | -1;
+        text: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData_1>, rowB: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string) => 0 | 1 | -1;
+        textCaseSensitive: <TFeatures extends _tanstack_table_core.TableFeatures, TData_1 extends RowData>(rowA: _tanstack_table_core.Row<TFeatures, TData_1>, rowB: _tanstack_table_core.Row<TFeatures, TData_1>, columnId: string) => 0 | 1 | -1;
+    };
+    tableMeta: TMDataGridTableMeta;
+    columnMeta: TMDataGridColumnMeta;
+}, TData>;
+/**
+ * Chrome state that is *not* table state: which panels are open, and which
+ * column opened the filter panel. Kept in a TanStack Store so consumers can
+ * subscribe to it the same way they subscribe to `table.store`.
+ */
+type TMDataGridUiState = {
+    filterPanelOpen: boolean;
+    columnsPanelOpen: boolean;
+    /** Column whose filter row should be focused when the panel opens. */
+    filterPanelColumnId: string | null;
+    /**
+     * Column being dragged by its header, if any. Held here rather than read from
+     * `dataTransfer`, which browsers keep unreadable until the drop.
+     */
+    draggedColumnId: string | null;
+};
+type TMDataGridUiActions = {
+    openFilterPanel: (columnId?: string | null) => void;
+    closeFilterPanel: () => void;
+    setColumnsPanelOpen: (open: boolean) => void;
+    toggleColumnsPanel: () => void;
+    startColumnDrag: (columnId: string) => void;
+    endColumnDrag: () => void;
+};
+type TMDataGridUiStore = Store<TMDataGridUiState, TMDataGridUiActions>;
+/** What `useTMDataGrid` returns — spread straight onto `<TMDataGrid />`. */
+type TMDataGridApi<TData extends RowData> = {
+    table: TMDataGridTable$1<TData>;
+    ui: TMDataGridUiStore;
+    /** Table-level feature switches, re-read from options on every render. */
+    features: TMDataGridFeatureFlags;
+};
+type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridFeatures, TData>, "features"> & {
+    /**
+     * Restore and persist table state across mounts. Two keys, because the two
+     * kinds of state have different lifetimes — see {@link TMDataGridPersistence}.
+     *
+     * Keep the object referentially stable (module scope or `useMemo`); it is a
+     * dependency of the subscription that writes back.
+     */
+    persist?: TMDataGridPersistence;
+    /**
+     * Header drag-and-drop and the move items in the column menu. Defaults to
+     * `true`.
+     *
+     * The one feature switch the grid defines itself: TanStack's
+     * `columnOrderingFeature` ships state and APIs but no `enable` option, since
+     * reordering is entirely a matter of interface.
+     */
+    enableColumnOrdering?: boolean;
+};
+/**
+ * Builds a TMDataGrid table plus its chrome store.
+ *
+ * Every `TableOptions` field passes straight through, so a server-driven grid
+ * only needs `manualPagination` / `manualFiltering` / `manualSorting`,
+ * `rowCount` and the matching `onXChange` callbacks — the chrome reads
+ * `getRowCount()` / `getPageCount()` / `getPaginatedRowModel()`, all of which
+ * already respect manual mode.
+ */
+declare function useTMDataGrid<TData extends RowData>({ persist, enableColumnOrdering, ...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;
+
+/**
+ * Row shape the chrome components work against. They only ever touch columns,
+ * rows and cells generically, so the concrete row type is erased at the context
+ * boundary — the same trick Mantine uses for its compound components.
+ */
+type TMDataGridRowData = Record<string, unknown>;
+type TMDataGridContextValue = TMDataGridApi<TMDataGridRowData> & {
+    size: TMDataGridSize;
+    /** Row height in px, already resolved from `size` and `meta.rowHeight`. */
+    rowHeight: number;
+    /** Mantine control size that pairs with `size`. */
+    controlSize: TMDataGridSize;
+};
+declare function useTMDataGridContext(): TMDataGridContextValue;
+
+/** Where a column sits relative to the pinned regions, resolved once per render. */
+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;
+};
+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.
+ */
+declare function TMDataGridTable<TData extends RowData = TMDataGridRowData>({ onRowClick, }: TMDataGridTableProps<TData>): react.JSX.Element;
+
+/** Row above the grid. Compose it from the pieces below, or anything else. */
+declare function TMDataGridToolbar({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/** Pushes the following toolbar items to the right. */
+declare function TMDataGridToolbarSpacer(): react.JSX.Element;
+/**
+ * Visible rows over total rows. On a server-driven grid, set
+ * `meta.totalRowCount` for the denominator — the client never sees every row.
+ */
+declare function TMDataGridSummaryCount({ children }: {
+    children?: ReactNode;
+}): react.JSX.Element;
+/**
+ * Burger menu in the grid's top-right corner — opens "Manage columns".
+ * Renders nothing when no column can be hidden (`enableHiding: false`).
+ */
+declare function TMDataGridColumnsButton(): react.JSX.Element | null;
+/**
+ * Toggles the filter panel, seeding a filter row on the first filterable column.
+ * Renders nothing when no column can be filtered (`enableColumnFilters: false`).
+ */
+declare function TMDataGridFilterButton(): react.JSX.Element | null;
+
+type TMDataGridProps<TData extends RowData> = TMDataGridApi<TData> & {
+    children: ReactNode;
+    /**
+     * Mantine size scale. Drives row height, font size, cell padding and the
+     * size of the controls in the chrome. `meta.rowHeight` still wins if set.
+     */
+    size?: TMDataGridSize;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * Root of the grid. Takes the object returned by `useTMDataGrid` — spread it —
+ * and publishes it to the compound components below it:
+ *
+ * ```tsx
+ * const grid = useTMDataGrid({ data, columns });
+ *
+ * <TMDataGrid {...grid}>
+ *   <TMDataGrid.Toolbar>
+ *     <TMDataGrid.SummaryCount />
+ *     <TMDataGrid.Spacer />
+ *     <TMDataGrid.ColumnsButton />
+ *   </TMDataGrid.Toolbar>
+ *   <TMDataGrid.Table />
+ *   <TMDataGrid.Footer />
+ * </TMDataGrid>
+ * ```
+ */
+declare function TMDataGridRoot<TData extends RowData>({ table, ui, features, size, children, className, style, }: TMDataGridProps<TData>): react.JSX.Element;
+declare const TMDataGrid: typeof TMDataGridRoot & {
+    Toolbar: typeof TMDataGridToolbar;
+    Spacer: typeof TMDataGridToolbarSpacer;
+    SummaryCount: typeof TMDataGridSummaryCount;
+    ColumnsButton: typeof TMDataGridColumnsButton;
+    FilterButton: typeof TMDataGridFilterButton;
+    Table: typeof TMDataGridTable;
+    Footer: typeof TMDataGridFooter;
+    /** Rendered by `TMDataGrid.Table`; exported for custom layouts. */
+    FilterPanel: typeof TMDataGridFilterPanel;
+    /** Rendered by `TMDataGrid.ColumnsButton`; exported for custom layouts. */
+    ColumnsPanel: typeof TMDataGridColumnsPanel;
+};
+
+/**
+ * Structural shape of the column bits the chrome reads. Kept minimal so these
+ * helpers work with any `Column`/`Header` instance without dragging generics
+ * through every call site.
+ */
+type ColumnLike = {
+    id: string;
+    columnDef: {
+        header?: unknown;
+        meta?: TMDataGridColumnMeta;
+    };
+    /** Set on a leaf that sits inside a header group. */
+    parent?: unknown;
+};
+/** Menu- and panel-facing column name. */
+declare function getColumnLabel(column: ColumnLike): string;
+declare function getColumnType(column: ColumnLike): TMDataGridColumnType;
+/**
+ * Whether a column may be moved. Ordering is the one column feature TanStack
+ * has no column option for, so the switch lives in `meta.enableOrdering`.
+ *
+ * A leaf inside a header group is never movable: `columnOrder` sequences leaf
+ * columns, so moving one out of its group would leave the group header spanning
+ * columns that no longer belong to it.
+ */
+declare function isColumnReorderable(column: ColumnLike): boolean;
+
+type GridColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
+type GridTable = TMDataGridTable$1<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.
+ */
+type TMDataGridColumnRegion = "left" | "center" | "right";
+/** Which edge of the column under the pointer a dragged column lands on. */
+type TMDataGridDropSide = "before" | "after";
+declare function getColumnRegion(columnPinning: ColumnPinningState, columnId: string): TMDataGridColumnRegion;
+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.
+ */
+declare function moveColumn({ table, columnId, targetId, side, }: MoveColumnArgs): void;
+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.
+ */
+declare function getStepTargetColumn({ table, columnId, direction, }: ColumnStepArgs): GridColumn | null;
+/** Moves a column one position within its lane. Hidden columns are stepped over. */
+declare function moveColumnByStep({ table, columnId, direction, }: ColumnStepArgs): void;
+
+export { DATA_STATE_SLICES, DEFAULT_TMDATAGRID_SIZE, FILTER_OPERATOR_LABELS, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDataGrid, createTMDataGridColumnHelper, getColumnCapabilities, getColumnLabel, getColumnRegion, getColumnType, getGridCapabilities, getStepTargetColumn, isColumnReorderable, isFilterActive, moveColumn, moveColumnByStep, openColumnFilter, readFeatureFlags, tmDataGridFeatures, useTMDataGrid, useTMDataGridContext };
+export type { ColumnStepArgs, MoveColumnArgs, TMDataGridApi, TMDataGridCapabilities, TMDataGridColumnCapabilities, TMDataGridColumnLayout, TMDataGridColumnMeta, TMDataGridColumnRegion, TMDataGridColumnType, TMDataGridContextValue, TMDataGridDataSlice, TMDataGridDropSide, TMDataGridFeatureFlags, TMDataGridFeatures, TMDataGridFilterOperator, TMDataGridFilterValue, TMDataGridPersistKey, TMDataGridPersistence, TMDataGridProps, TMDataGridRowData, TMDataGridSettingsSlice, TMDataGridSize, TMDataGridStorageMode, TMDataGridTable$1 as TMDataGridTable, TMDataGridTableMeta, TMDataGridUiActions, TMDataGridUiState, TMDataGridUiStore, UseTMDataGridOptions };