@jielga/tmdatagrid 2.1.4 → 2.2.0

package/skills/data/SKILL.md

@@ -8,7 +8,7 @@ description: >
   canPaginate, always-on virtualization with overscan and meta.rowHeight,
   scrollToRow, the edge callbacks onScrollToBottom / onScrollToRight and why
   onReachEnd is better for loading more, the header and pinned-lane depth
-  shadows, and the four empty states in precedence order with meta.loading,
+  shadows, and the five empty states in precedence order with meta.loading,
   renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator and
   TMDataGrid.SummaryCount, and export: TMDataGrid.Menu.Export and
   Menu.ExportSelected, useTMDataGridExport, exportGrid, exportOptions, the
@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.2.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/pagination.md'
   - 'Jielga/react:packages/tmdatagrid/docs/scrolling.md'
@@ -56,8 +56,14 @@ const grid = useTMDataGrid({
 ```
 
 Initial page size is 25, through `initialState.pagination`. `enablePagination`
-is defined by the grid rather than by TanStack, and is the only grid option that
-defaults to off.
+is defined by the grid rather than by TanStack.
+
+The Footer renders a rows-per-page select, the range (`1–25 of 300`, from
+`table.getRowCount()`) and previous and next buttons; there are no numbered page
+buttons. The select offers `pageSizeOptions`, by default `[10, 25, 50, 100]`,
+with the current size folded in when it is not in the list. Pass a module-scope
+array: the select is memoized on it, and an inline literal remounts it on every
+render.
 
 `TMDataGrid.Footer` takes a `renderPagination` slot handed three things: the
 `state` the pager shows, the `actions` it can take, and `Controls`, the built-in
@@ -82,22 +88,26 @@ pieces, already wired.
 
 `Controls.PageSize`, `Controls.Range` and `Controls.Pager` are what the default
 footer renders, in that order, so a custom layout can keep the parts it wants
-instead of rebuilding them. They behave exactly as before, including greying out
-under a suspended pager. `Controls.PageNumber` - the "Page 3 of 200" label a
-server-paged grid usually shows in place of a row range - is a fourth control,
-not in the default footer; put it in through the slot rather than writing it by
-hand.
+instead of rebuilding them. They behave as in the default footer, including
+greying out while paging is suspended. `Controls.PageNumber` renders
+"Page 3 of 200", the label a server-paged grid usually shows in place of the
+row range. It is not in the default footer; add it through the slot.
 
 `state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
 `canPreviousPage`, `canNextPage`, `from`, `to` and `isPagingActive`. `actions`
 carries `setPageIndex`, `setPageSize`, `previousPage`, `nextPage`, `firstPage`
-and `lastPage`. `getTMDataGridPaginationApi(table)` returns the same
-`{ state, actions }` outside the Footer. `Controls` is bound to the grid
-context, so those components work only inside the slot.
-
-Grouping suspends the pager: it greys out and the range becomes
-`Grouped · all N rows`. `isPagingActive(table, features)` is the live state,
-whether the pager is slicing anything right now, while
+and `lastPage`. Outside the Footer,
+`getTMDataGridPaginationApi(table, isPagingActive(table, grid.features))`
+returns the same `{ state, actions }`. Without the second argument
+`state.isPagingActive` is `true`, also while the rows are grouped. `Controls`
+is bound to the grid context, so those components work only inside the slot.
+
+Grouping suspends the pager: the built-in controls grey out and the range
+becomes `Grouped · all N rows`. The default footer also carries
+`data-paging-suspended` on its bar and shows `labels.pagingSuspendedHint` as a
+tooltip; a footer with `renderPagination` has neither. There is no option to
+keep the built-in pager active while grouped. `isPagingActive(table, features)`
+is the live state, whether the pager is slicing anything right now, while
 `getGridCapabilities(...).canPaginate` is the configuration. The two differ
 while a grouping is active.
 
@@ -141,14 +151,13 @@ arrival rather than on every scroll event. For loading more rows use
 `onReachEnd` (the `server-side` skill) instead: it fires a number of rows before
 the bottom, and latches per row count so a pending fetch is not requested twice.
 
-Two depth cues are scroll-driven animations run on the compositor, with no
-scroll listener and no React render: a shadow under the sticky header once rows
-scroll beneath it, and a band beside a pinned lane while it is covering
-content.
+Two depth cues run as scroll-driven CSS animations, with no scroll listener and
+no React render. A shadow appears under the sticky header once rows scroll
+beneath it. A band appears beside a pinned lane while it covers content.
 
 ## Empty states
 
-There are four ways to have nothing to show, and an empty body shows exactly one
+There are five ways to have nothing to show, and an empty body shows exactly one
 of them, in this order:
 
 1. **Loading** - `meta.loading` is true: a centred loader. A grid that is
@@ -156,9 +165,23 @@ of them, in this order:
 2. **Entry rows** - an open entry row from `edit.addRow()`: the entry block
    only, with no message beside the form.
 3. **`renderEmptyState`** - your node, centred where the message would be.
-4. **Filtered-empty** - a filter or search is active: `labels.noResults`, since
-   clearing the filter will bring rows back.
-5. **Truly-empty** - no data at all: `labels.noRows`.
+4. **Filtered-empty** - a column filter is active (`isFilterActive`) or the
+   quick search is not blank: `labels.noResults`, since clearing the filter
+   will bring rows back.
+5. **Truly-empty** - no column filter is active and the quick search is blank:
+   `labels.noRows`.
+
+"Empty" means no displayed row and no pinned row. States 4 and 5 are decided by
+the filter state alone, so an empty `data` array shows `noResults` while a
+filter is active. A half-typed filter, such as
+`{ operator: "contains", value: "" }`, is not active, so it does not count.
+
+The loader is the only "no data yet" signal, so set `meta.loading` during the
+first fetch too; without it the empty message shows until the rows arrive.
+`renderEmptyState` is called only once `meta.loading` is not `true`: during a
+refetch that returns no rows the loader mounts when `loading` turns `true`,
+`renderEmptyState` mounts when it turns `false`, and unmounts again on the next
+refetch.
 
 `renderEmptyState` replaces the last two with one render prop, and
 `hasActiveFilters` says which it is standing in for:
@@ -177,15 +200,14 @@ of them, in this order:
 />
 ```
 
-An empty grid is a good place to offer the action that fills it, such as
-clearing the filters or creating the first record.
-
 The body's loading state only appears while the grid is **empty**. A
 server-driven grid refetching with rows still on screen keeps showing them.
 `TMDataGrid.LoadingIndicator` covers that case: a small spinner while
 `meta.loading` is true. `TMDataGrid.SummaryCount` shows visible rows out of
-total, where the total is `meta.totalRowCount` when provided and the pre-filtered
-count otherwise.
+total. The total is `meta.totalRowCount` when provided, otherwise the
+pre-filtered count on a client-side grid; a server-driven grid
+(`manualFiltering` or `manualPagination`) without `meta.totalRowCount` shows the
+visible count alone, with no total.
 
 ## Export
 
@@ -214,15 +236,19 @@ function ExportButton() {
 }
 ```
 
-What is written: the data columns in render order (never the generated lanes,
-never a column with `meta.enableExport: false`), every row after filtering and
-sorting (a grouped grid writes the records under every group, never the group
-rows), and each cell's **value** rather than what it renders -
-`meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+What is written:
+
+- **Columns** - the data columns in render order. Never the generated lanes,
+  never a column with `meta.enableExport: false`.
+- **Rows** - every row after filtering and sorting. A grouped grid writes the
+  records under every group, never the group rows.
+- **Values** - each cell's **value** rather than what it renders.
+  `meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+
 `columns` on `exportOptions`, the items and the functions is `"visible"` (the
-default), `"all"` (hidden columns too) or a list of ids; `columns="custom"` on
-a menu item opens a picker instead - every exportable column, the visible ones
-ticked, Export and Cancel - driven by `ui.state.exportPicker` and
+default), `"all"` (hidden columns too) or a list of ids. `columns="custom"` on a
+menu item opens a picker instead: every exportable column, the visible ones
+ticked, Export and Cancel. The picker is driven by `ui.state.exportPicker` and
 `ui.actions.openExportPicker`. `TMDataGrid.Menu.ExportSelected` counts and
 writes the ticked rows of the current view, in grid order; it renders nothing
 when row selection is off.
@@ -303,10 +329,11 @@ a pending fetch is not requested twice.
 
 Source: `packages/tmdatagrid/docs/scrolling.md` (Edge callbacks).
 
-### HIGH `SummaryCount` reporting the page under manual pagination
+### HIGH `SummaryCount` without a total under manual pagination
 
-The client only holds one page, so without `meta.totalRowCount` the total is
-whatever arrived. It shows "25 of 25" over a table of thousands.
+The client holds one page, so a server-driven grid has no total of its own.
+Without `meta.totalRowCount`, `SummaryCount` shows the visible count alone, with
+no total, over a table of thousands.
 
 Correct:
 
@@ -334,7 +361,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { loading: isFetching } });
 ```
 
-Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (Precedence).
 
 ### MEDIUM Trusting the pager while grouped
 
@@ -342,7 +369,7 @@ Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
 grid is rendering the whole tree. A custom pager must read
 `isPagingActive(table, features)` rather than the page count.
 
-Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
+Source: `packages/tmdatagrid/docs/pagination.md` (Grouping).
 
 ## Reference
 
@@ -351,31 +378,31 @@ Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 | `enablePagination` | Option | `boolean` | `false` | Client-side paging and the Footer's pager. Grid-defined. |
 | `manualPagination` | Table option | `boolean` | `false` | The server pages. Implies `enablePagination`. |
 | `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
-| `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A `data` slice, so it persists. |
+| `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ pageIndex: 0, pageSize: 25 }` | Where paging starts. A `data` slice, so it persists. |
 | `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
-| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
+| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `pageSizeOptions`: `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
 | `TMDataGridFooterProps` | Type | – | – | The props of `TMDataGrid.Footer`. |
 | `Footer` `renderPagination` | Slot | `(args: TMDataGridPaginationSlotArgs) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
 | `TMDataGridPaginationSlotArgs` | Type | `TMDataGridPaginationApi & { Controls }` | – | What `renderPagination` receives: `{ state, actions, Controls }`. |
-| `getTMDataGridPaginationApi` | Export | `(table, isPaging?) => TMDataGridPaginationApi` | `isPaging`: `true` | The pager API, outside the Footer. |
+| `getTMDataGridPaginationApi` | Export | `(table, isPaging?) => TMDataGridPaginationApi` | `isPaging`: `true` | The pager API, outside the Footer. Pass `isPagingActive(table, features)` as `isPaging`. |
 | `TMDataGridPaginationApi` | Type | `{ state, actions }` | – | What `getTMDataGridPaginationApi` returns. |
 | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot argument. |
 | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |
 | `overscan` | Option | `number` | `6` | Rows kept mounted beyond each edge of the viewport. |
-| `meta.rowHeight` | Option | `number` | From `size` | Row height in pixels. The virtualizer needs a number. |
+| `meta.rowHeight` | Option | `number` | `52` at the default `md` size; see the `size` scale in the `appearance` skill | Row height in pixels. The virtualizer needs a number. |
 | `scrollToRow` | Hook return | `({ rowId, align? }) => boolean` | `align: "auto"` | Scrolls a row into view, mounted or not. |
 | `TMDataGridScrollToRowArgs` | Export | `{ rowId, align? }` | – | What `scrollToRow` takes. |
 | `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
 | `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
-| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Takes precedence over every empty message. |
+| `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. While `true` and the view is empty, the loader replaces every empty message and `renderEmptyState` is not called. |
 | `meta.noResultsLabel` | Option | `string` | `labels.noResults` | The filtered-empty message, without a render prop. |
-| `meta.totalRowCount` | Option | `number` | Pre-filtered count | The total `SummaryCount` reports. |
-| `renderEmptyState` | Table prop | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. |
+| `meta.totalRowCount` | Option | `number` | Pre-filtered count; none on a server-driven grid | The total `SummaryCount` reports. |
+| `renderEmptyState` | Table prop | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. `hasActiveFilters` is `true` when a column filter is active (`isFilterActive`) or the quick search is not blank. |
 | `TMDataGrid.LoadingIndicator` | Component | – | – | Spinner while `meta.loading`, for when the body has rows. |
 | `TMDataGrid.SummaryCount` | Component | `children` replaces the text | – | Visible rows out of total. |
 | `--dg-header-shadow-color` | CSS variable | colour | Themed | The shadow under the sticky header. |
 | `--dg-sticky-edge-range` | CSS variable | length | `20px` | How far the pinned-lane band takes to fade in. |
-| `exportOptions` | Option | `TMDataGridExportOptions` | `DEFAULT_EXPORT_OPTIONS` | Format, file name and header row for every export of the grid. |
+| `exportOptions` | Option | `TMDataGridExportOptions` | `csvExcelFormat()`, `"export"`, headers on, `"visible"` columns | Format, file name and header row for every export of the grid. |
 | `meta.enableExport` | Column meta | `boolean` | `true` | `false` leaves the column out of every export and of Ctrl+C. |
 | `meta.exportValue` | Column meta | `TMDataGridExportValueGetter`: `({ value, row, column }) => unknown` | – | The value written in place of `row.getValue`. |
 | `TMDataGrid.Menu.Export` · `TMDataGrid.Menu.ExportSelected` | Components | `TMDataGridMenuExportProps` | – | Menu items: every filtered row, and the selected rows. `columns="custom"` opens the picker. |

package/skills/editing/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.2.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/editing.md'
   - 'Jielga/react:packages/tmdatagrid/docs/draft-store.md'

package/skills/filtering/SKILL.md

@@ -18,7 +18,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.2.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/filtering.md'
   - 'Jielga/react:packages/tmdatagrid/docs/quick-search.md'
@@ -50,11 +50,12 @@ cell is tested against) and `between` (a `[min, max]` pair, an empty string
 leaving that end open).
 
 A filter with an empty value **stays in state** so the panel keeps its row while
-the user types. It matches every row, does not set the header indicator and
-produces no pill. `isFilterActive(value)` tests for that state, and
-`activeColumnFilters(columnFilters | table)` applies it across the slice and
-types what it hands back (entries in any other value shape are dropped); presence in
-`columnFilters` does not.
+the user types. The built-in matcher lets every row through, and the filter
+does not set the header indicator and produces no pill.
+`isFilterActive(value)` tells whether a value narrows anything.
+`activeColumnFilters(columnFilters | table)` returns the active entries, typed,
+and drops entries in any other value shape. An entry in `columnFilters` is not
+necessarily active.
 
 ## Operators
 
@@ -106,8 +107,8 @@ columnHelper.accessor("customer", {
 
 ## The filters option
 
-`filters` on `useTMDataGrid` picks the surface. It is read field by field, so a
-literal is fine.
+`filters` on `useTMDataGrid` picks the surface. It is read field by field, so an
+inline object literal needs no `useMemo`.
 
 | Option | Type | Default | What it does |
 | --- | --- | --- | --- |
@@ -132,13 +133,14 @@ close it; `FilterButton` is exempt from the click-away so it stays a toggle.
 the toolbar. The rows give up the width rather than being covered, a click in
 the table does not dismiss it, and clearing the filters leaves it standing.
 Escape closes it. It starts open, being a layout choice; its rows are
-`layout="stacked"`, since 280px has no room for the triple.
+`layout="stacked"`, since the default 280px cannot fit the column, operator and
+value fields side by side.
 
 **Header filters** - `inHeader: true` adds a header row of value controls, one
 per filterable column, on the same column tracks as everything else. The
 column and operator dropdowns are not there: the column is the one the cell
-sits over, and the operator is a funnel button beside the input, tinted off its
-default. The column menu's Filter item and the funnel indicator both come off,
+sits over, and the operator is a funnel button beside the input, tinted when
+the operator is not the type's default. The column menu's Filter item and the funnel indicator both come off,
 having nothing left to reveal; the filtered column's tinted title stays. A
 narrow column clips its control - give it a `minSize`.
 
@@ -158,7 +160,7 @@ hand-placed `TMDataGrid.FilterPanel` is the only one. Read
 
 The panel of filter rows - one column / operator / value triple per filter, over "Add filter" and "Clear all".
 A plain block with no title, no close button and no open state: it renders wherever it is mounted, and the popup and sidebar surfaces are wrappers around it.
-It must be inside `<TMDataGrid>` (it reads the grid from context) and it only reads and writes `columnFilters`, so a `manualFiltering` grid gets it for free.
+It must be inside `<TMDataGrid>` (it reads the grid from context) and it only reads and writes `columnFilters`, so it works unchanged under `manualFiltering`.
 Closing a surface only hides it; the filters stay.
 **Clear all** drops every filter, half-typed ones included.
 
@@ -201,7 +203,8 @@ import { TMDataGridFilterPills } from "@jielga/tmdatagrid";
 
 ## openColumnFilter
 
-`openColumnFilter(api, columnId)` seeds an empty filter if the column has none, then opens the surface on that column's panel row - or, under `inHeader`, scrolls the column's header control into view and focuses it, leaving the surface closed.
+`openColumnFilter(api, columnId)` seeds an empty filter if the column has none, then opens the surface on that column's panel row.
+Under `inHeader` it instead scrolls the column's header control into view and focuses it, leaving the surface closed.
 It is what a pill's label and the column menu's Filter item both call.
 
 ## Replacing the value control
@@ -232,41 +235,47 @@ the same way.
 inside. It handles the value only: it reads `operator` to shape itself and
 writes the bare value through `onChange`, and the grid stores the
 `{ operator, value }` pair around it. The column and operator dropdowns remain
-the panel's.
-
-```tsx
-import type { TMDataGridFilterControlComponent } from "@jielga/tmdatagrid";
-
-// Module scope: a new identity per render remounts the control mid-typing.
-const StatusFilter: TMDataGridFilterControlComponent = ({
-  operator,
-  value,
-  options,
-  onChange,
-}) => (
-  <Chip.Group
-    multiple
-    value={Array.isArray(value) ? [...value] : []}
-    onChange={onChange}
-  >
-    {options.map((option) => (
-      <Chip key={option.value} value={option.value}>
-        {option.label}
-      </Chip>
-    ))}
-  </Chip.Group>
-);
-
-meta: { type: "select", filter: { control: StatusFilter } }
-```
+the panel's. Worked example: `references/custom-filters.md` (A value control of
+your own).
 
 `args.options` arrives pre-resolved for a column that declares `meta.options` or
 is select-shaped. `args.table` is available to a control that needs more than
 that.
 
+## Writing filters from your own interface
+
+The grid's controls write plain TanStack state, so a control of your own does
+the same: `column.setFilterValue({ operator, value })` or
+`table.setColumnFilters([...])` with an envelope, and the matcher, the pills,
+the header indicator and `activeColumnFilters` all read it.
+`setFilterValue(undefined)` removes the entry; an empty envelope stays in state
+and matches every row. `getColumnOperators(column)`,
+`getColumnDefaultOperator(column)` and `emptyValueForOperator(operator)` build
+a valid envelope. To keep the grid's panel and place it yourself, set
+`filters: { surface: "none" }` and render `TMDataGrid.FilterPanel`. To drop
+only the column menu's Filter item, pass `renderColumnMenuItems` to
+`TMDataGrid.Table` and leave out the item keyed `"filter"`. To replace every
+filter control, set `enableColumnFilters: false` and write the envelope
+yourself; filters in state still apply. Worked examples:
+`references/custom-filters.md`.
+
+## Custom matching
+
 To give a column its own *matching* instead of its own control, set `filterFn`
-on the column definition. The grid provides only `"tmDataGrid"`, which is the
-default.
+on the column definition. A column `filterFn` **replaces the shared matcher**
+for that column, so its third argument is the stored `{ operator, value }`
+envelope, not the unwrapped value. Type it as `TMDataGridFilterFn<TData>` and
+delegate to `tmDataGridFilterFn(row, columnId, filter)` for the operators it
+does not handle; `matchesFilter(cellValue, filter)` applies the built-in
+matching to a derived value, and `filterValueShape(operator)` tells whether
+`value` is a string, a `ReadonlyArray<string>` (`isAnyOf` / `isNoneOf`) or a
+`[min, max]` pair (`between`). A column `filterFn` is also called with
+half-typed envelopes, which the built-in matcher treats as matching every row,
+so return `true` for `!isFilterActive(filter)` first. The column's controls do
+not change and keep reading the envelope. A filter function named by string
+also receives the envelope and does not unwrap it, so TanStack's built-ins such
+as `"includesString"` do not work as a column `filterFn`. Write custom matching
+as a function. Worked example: `references/custom-filters.md`.
 
 ## Quick search
 
@@ -298,10 +307,20 @@ excluded.
 
 ## Turning it off
 
-`enableColumnFilters: false` removes the panel, the button and the menu item;
-`enableColumnFilter: false` on a column takes that column out.
-`enableGlobalFilter: false` removes the search input, or on a column removes its
-participation in the search. The generated lanes are already excluded.
+`enableColumnFilters: false` removes the Filter item from the column menu, the
+`FilterButton`, the header filter row and the panel's column list, and disables
+the panel's "Add filter" button. It does **not** clear `columnFilters`: an entry already in
+state, or one written with `setFilterValue`, still narrows the rows, still shows
+as a pill and still sets the header indicator. Call `table.resetColumnFilters()`
+when switching the interface off. Under `filters.surface: "sidebar"`, set
+`surface: "none"` as well, as the sidebar does not follow the switch.
+`TMDataGrid.Menu` has no filter items, so the switch changes nothing there.
+
+`enableColumnFilter: false` on a column removes that column's menu item, its
+entry in the panel's column list and its header control - the header cell
+stays, empty. `enableGlobalFilter: false` removes the search input, or on a
+column removes its participation in the search. The generated lanes are already
+excluded.
 
 ## Common mistakes
 
@@ -417,17 +436,20 @@ Source: `packages/tmdatagrid/docs/quick-search.md` (Fuzzy by default).
 
 | Name | Kind | Type | Default | What it does |
 | --- | --- | --- | --- | --- |
-| `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the panel, the button and the menu item. |
+| `enableColumnFilters` | Table option | `boolean` | `true` | `false` removes the menu item, the button, the header row and the panel's column list, and disables the panel's "Add filter" button. Filters already in state still apply. |
 | `enableColumnFilter` | Column option | `boolean` | `true` | `false` takes one column out of filtering. |
 | `meta.type` | Column meta | `TMDataGridColumnType` | `"string"` | Selects the operators and the value control. |
 | `meta.filter.operators` | Column meta | `readonly TMDataGridFilterOperator[]` | The type's list | The operators this column offers, a subset of its type's. |
 | `meta.filter.defaultOperator` | Column meta | `TMDataGridFilterOperator` | The type's default, else the first offered | The operator a fresh filter opens on. |
 | `meta.filter.control` | Column meta | `TMDataGridFilterControlComponent` | By type and operator | Replaces the value control. Module scope. |
-| `filterFn` | Column option | name or fn | `"tmDataGrid"` | Custom matching for one column. |
+| `filterFn` | Column option | `TMDataGridFilterFn<TData>` or name | `"tmDataGrid"` | Custom matching for one column. Receives the `{ operator, value }` envelope. |
+| `TMDataGridFilterFn<TData>` | Type | `(row, columnId, filter: TMDataGridFilterValue, addMeta?) => boolean` | – | The signature of a column's own `filterFn`. |
+| `tmDataGridFilterFn` | Export | `(row, columnId, filterValue: unknown) => boolean`, assignable to `TMDataGridFilterFn<TData>` | – | The shared matcher, for a custom `filterFn` to delegate to. |
+| `matchesFilter` | Export | `(cellValue, filter: TMDataGridFilterValue) => boolean` | – | The built-in matching applied to one value. |
 | `quickSearchMode` | Option | `TMDataGridQuickSearchMode`: `"fuzzy" \| "contains"` | `"fuzzy"` | How the quick search matches. |
 | `enableMatchHighlighting` | Option | `boolean` | `false` | Mark matched text in default-rendered cells. |
 | `enableGlobalFilter` | Table option | `boolean` | `true` | Also a column option. Removes the input, or one column's participation. |
-| `globalFilterFn` | Table option | filter fn | fuzzy | Overrides the matching, and the ranking with it. |
+| `globalFilterFn` | Table option | filter fn or name | `"tmDataGridFuzzy"`; `"includesString"` under `quickSearchMode: "contains"` | Overrides the matching, and the ranking with it. |
 | `TMDataGrid.FilterPanel` | Component | `layout: "row" \| "stacked"`, Mantine `BoxProps` | `"row"` | The panel of filter rows, as a plain block. Style props set on it. |
 | `TMDataGridFilterPanelProps` · `TMDataGridFilterPanelLayout` | Types | – · `"row" \| "stacked"` | – | The props of `TMDataGrid.FilterPanel`, and the type of its `layout`. For wrapping the panel in a component of your own. |
 | `filters` | Table option | `TMDataGridFiltersOptions` | `{ surface: "popup" }` | Which surface holds the filter controls. |

package/skills/filtering/references/custom-filters.md

@@ -0,0 +1,118 @@
+# Custom filters
+
+Worked examples for the three ways to take over part of TMDataGrid's filtering: a value control of your own, writing the filter state from an interface of your own, and matching a column with a function of your own.
+All three keep the `{ operator, value }` envelope, so the panel, the pills, the header indicator and `activeColumnFilters` keep working.
+
+## A value control of your own
+
+`meta.filter.control` is a component that handles the value only: it reads `operator` to shape itself and writes the bare value through `onChange`.
+
+```tsx
+import type { TMDataGridFilterControlComponent } from "@jielga/tmdatagrid";
+
+// Module scope: a new identity per render remounts the control mid-typing.
+const StatusFilter: TMDataGridFilterControlComponent = ({
+  operator,
+  value,
+  options,
+  onChange,
+}) => (
+  <Chip.Group
+    multiple
+    value={Array.isArray(value) ? [...value] : []}
+    onChange={onChange}
+  >
+    {options.map((option) => (
+      <Chip key={option.value} value={option.value}>
+        {option.label}
+      </Chip>
+    ))}
+  </Chip.Group>
+);
+
+meta: { type: "select", filter: { control: StatusFilter } }
+```
+
+## Writing filters from your own interface
+
+The grid's controls write plain TanStack state, so a control of your own does the same:
+
+```tsx
+import { emptyValueForOperator, type TMDataGridFilterValue } from "@jielga/tmdatagrid";
+
+const status = grid.table.getColumn("status")!;
+
+// A set filter, as the panel would write it.
+status.setFilterValue({
+  operator: "isAnyOf",
+  value: ["active", "paused"],
+} satisfies TMDataGridFilterValue);
+
+// An empty envelope stays in state and matches every row.
+status.setFilterValue({ operator: "isAnyOf", value: emptyValueForOperator("isAnyOf") });
+
+// `undefined` removes the entry.
+status.setFilterValue(undefined);
+
+// Several columns at once.
+grid.table.setColumnFilters([
+  { id: "status", value: { operator: "equals", value: "active" } },
+  { id: "salary", value: { operator: "between", value: ["40000", ""] } },
+]);
+```
+
+`getColumnOperators(column)` returns the operators a column offers and `getColumnDefaultOperator(column)` the one a fresh filter opens on.
+`emptyValueForOperator(operator)` returns the empty value of the right shape.
+
+To keep the grid's panel and place it yourself, set `filters: { surface: "none" }` and render `TMDataGrid.FilterPanel` where it belongs.
+To keep filtering on and drop only the column menu's Filter item, pass `renderColumnMenuItems` to `TMDataGrid.Table` and leave out the item keyed `"filter"`.
+To replace every filter control, set `enableColumnFilters: false` and write the envelope yourself; filters in state still apply.
+
+## Custom matching
+
+A column `filterFn` replaces the shared matcher for that column, so its third argument is the stored envelope, not the unwrapped value.
+Type it as `TMDataGridFilterFn<TData>` and delegate to `tmDataGridFilterFn` for the operators it does not handle itself.
+A column `filterFn` is also called with half-typed envelopes, which the built-in matcher treats as matching every row, so return `true` for `!isFilterActive(filter)` first:
+
+```ts
+import {
+  isFilterActive,
+  tmDataGridFilterFn,
+  type TMDataGridFilterFn,
+} from "@jielga/tmdatagrid";
+
+// Reads "contains" as "has this tag", so "ops" matches the tag "ops" and not
+// "devops"; every other operator keeps the built-in matching.
+const matchesTags: TMDataGridFilterFn<Employee> = (row, columnId, filter) => {
+  if (!isFilterActive(filter)) return true;
+  if (filter.operator === "contains") {
+    const wanted = String(filter.value).toLowerCase();
+    return row.original.tags.some((tag) => tag.toLowerCase() === wanted);
+  }
+  return tmDataGridFilterFn(row, columnId, filter);
+};
+
+columnHelper.accessor((row) => row.tags.join(", "), {
+  id: "tags",
+  header: "Tags",
+  filterFn: matchesTags,
+  meta: { type: "string" },
+});
+```
+
+`filter.value` is a string under the scalar operators, a `ReadonlyArray<string>` under `isAnyOf` / `isNoneOf` and a `[min, max]` pair under `between`; `filterValueShape(operator)` tells which.
+`matchesFilter(cellValue, filter)` applies the built-in matching to a value derived by the function itself:
+
+```ts
+import { isFilterActive, matchesFilter, type TMDataGridFilterFn } from "@jielga/tmdatagrid";
+
+// Matches the filter against the owner's full name instead of the stored id.
+const matchesOwner: TMDataGridFilterFn<Task> = (row, _columnId, filter) => {
+  if (!isFilterActive(filter)) return true;
+  return matchesFilter(ownerName(row.original.ownerId), filter);
+};
+```
+
+The column's filter controls do not change: the operators still come from `meta.type` and `meta.filter.operators`, and the panel, the pills and the header indicator keep reading the envelope.
+A filter function named by string also receives the envelope and does not unwrap it, so TanStack's built-ins such as `"includesString"` do not work as a column `filterFn`.
+Write custom matching as a function.

package/skills/getting-started/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.1.4'
+  library_version: '2.2.0'
 sources:
   - 'Jielga/react:packages/tmdatagrid/docs/getting-started.md'
   - 'Jielga/react:packages/tmdatagrid/docs/anatomy.md'
@@ -157,7 +157,7 @@ flex column.
 | --- | --- | --- |
 | `TMDataGrid` | `table`, `ui`, `features`, `size`, `className`, `style` | Root. Provides context. `style` also takes CSS variables: `--dg-row-selected-bg`, `--dg-row-height`, `--dg-header-height`, `--dg-font-size`, `--dg-padding`. |
 | `TMDataGrid.Table` | `onRowClick(row)`, `renderRowContextMenu`, `renderColumnMenuItems`, `rowContextMenuProps` | Header, virtualized body, and whichever filter surface the `filters` option asks for. `onRowClick` runs in addition to selection under `selectionMode: "row"`. |
-| `TMDataGrid.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`), `pagination` render prop | Pagination controls. Renders nothing unless pagination is enabled. |
+| `TMDataGrid.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`, keep the array stable), `renderPagination` slot | Rows-per-page select, range and previous/next buttons. Renders nothing unless pagination is enabled. |
 | `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
 | `TMDataGrid.Spacer` | - | Pushes later toolbar items right. |
 | `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
@@ -360,6 +360,41 @@ Source: `packages/tmdatagrid/docs/card-view.md`,
 | `moveColumnByStep({ table, columnId, direction })` | Moves a column one position within its region. |
 | `SELECT_COLUMN_ID` | Id of the generated checkbox column. |
 
+## Coming from TanStack Table
+
+`useTMDataGrid` takes TanStack's `TableOptions`, so a page built on
+`useReactTable` keeps its `data`, `columns`, `state` and `onXChange` callbacks.
+Go through these differences:
+
+- **`getRowId`** - return the entity id. The index default points at another
+  record after a sort or a refetch, which breaks selection, expansion and
+  editing. Required once `editing` is set.
+- **Stable `data` and `columns`** - define `columns` outside the component and
+  keep `data` referentially stable; a fresh `[]` for the empty case belongs in
+  a module-scope constant. Under `editing`, a transient `[]` drops every open
+  draft.
+- **Sizing** - columns are fluid, `minmax(minSize, flex fr)`. `size` applies
+  only to a column pinned at mount, `maxSize` only to resizing and autosizing,
+  and `minSize` defaults to `80`. See the `columns` skill.
+- **Defaults the grid changes** - `aggregationFn` is cleared, so grouping does
+  not sum anything on its own; `groupedColumnMode` is `"remove"`;
+  `autoResetExpanded` and `autoResetPageIndex` are off; `globalFilterFn` is the
+  fuzzy matcher. The full list is in the
+  `options` skill.
+- **Filters are envelopes** - `columnFilters` holds `{ operator, value }`, and
+  a column's own `filterFn` receives that envelope. See the `filtering` skill.
+- **Interface the page already owns** - `enableGlobalFilter: false`, or no
+  `TMDataGrid.Search`, for the search; `enableColumnFilters: false`, or
+  `filters: { surface: "none" }` to keep filtering without the grid's panel.
+- **Page reset** - `resetPageOnQueryChange` (default `true`) returns to the
+  first page when a filter, the search, the sorting or the grouping changes
+  through the table. A data source re-filtered outside table state does not
+  trigger it; call `table.setPageIndex(0)` yourself, or use `manualFiltering`.
+- **State reads** - there is no `table.getState()`; read slices with
+  `useSelector(table.store, ...)`. See the `options` skill.
+- **Tests** - the grid publishes `data-dg-part`, `data-row-id` and
+  `data-column-id`, and no `data-testid`. See the `testing` skill.
+
 ## Common mistakes
 
 ### Columns or data defined during render