@tanstack/table-core 9.0.0-beta.2 → 9.0.0-beta.21

package/skills/customizing-feature-behavior/SKILL.md

@@ -3,8 +3,7 @@ name: customizing-feature-behavior
 description: >
   Override per-column `sortFn`, `filterFn`, `aggregationFn` and table-level
   `globalFilterFn` in TanStack Table v9. Covers built-in `filterFns` / `sortFns` /
-  `aggregationFns` registries (passed to `createFilteredRowModel(filterFns)` /
-  `createSortedRowModel(sortFns)` / `createGroupedRowModel(aggregationFns)`),
+  `aggregationFns` registries (registered as slots on `tableFeatures({...})`),
   authoring custom functions with the `FilterFn` / `SortFn` / `AggregationFn`
   signatures, chaining filter→sort via the `addMeta` callback +
   `row.columnFiltersMeta`, `resolveFilterValue`, `autoRemove`, `invertSorting`,
@@ -31,7 +30,7 @@ This skill builds on `tanstack-table/state-management`. Read it first for how fe
 
 v9 customization happens in three places:
 
-1. **Built-in function registries** — `filterFns`, `sortFns`, `aggregationFns` — passed as arguments to row-model factories so unused fns tree-shake away.
+1. **Built-in function registries** — `filterFns`, `sortFns`, `aggregationFns` — registered as named slots on `tableFeatures({...})` so unused fns tree-shake away.
 2. **Per-column overrides** — `columnDef.filterFn`, `columnDef.sortFn`, `columnDef.aggregationFn` (string name OR inline function).
 3. **Table-level overrides** — `tableOptions.globalFilterFn`.
 
@@ -50,9 +49,15 @@ import {
   filterFns,
   sortFns,
   aggregationFns,
+  metaHelper,
   createColumnHelper,
 } from '@tanstack/table-core'
-import type { FilterFn, SortFn, AggregationFn } from '@tanstack/table-core'
+import type {
+  FilterFn,
+  SortFn,
+  AggregationFn,
+  TableFeatures,
+} from '@tanstack/table-core'
 import {
   rankItem,
   compareItems,
@@ -67,25 +72,15 @@ type Person = {
   status: 'single' | 'complicated' | 'relationship'
 }
 
-const features = tableFeatures({
-  rowSortingFeature,
-  columnFilteringFeature,
-  globalFilteringFeature,
-  columnGroupingFeature,
-  rowExpandingFeature,
-})
-
-// Module augmentation registers custom fn names so columnDef.filterFn typechecks.
-declare module '@tanstack/table-core' {
-  interface FilterFns {
-    fuzzy: FilterFn<typeof features, Person>
-  }
-  interface FilterMeta {
-    itemRank?: RankingInfo
-  }
+// 1. Describe meta shape for the fuzzy filter.
+interface FuzzyFilterMeta {
+  itemRank?: RankingInfo
 }
 
-const fuzzyFilter: FilterFn<typeof features, Person> = (
+// 2. Extend TableFeatures so FilterFn / SortFn can reference filterMeta types.
+type FuzzyFeatures = TableFeatures & { filterMeta: FuzzyFilterMeta }
+
+const fuzzyFilter: FilterFn<FuzzyFeatures, Person> = (
   row,
   columnId,
   value,
@@ -96,11 +91,28 @@ const fuzzyFilter: FilterFn<typeof features, Person> = (
   return itemRank.passed
 }
 
+// 3. Register everything on features — fn registries are named slots.
+const features = tableFeatures({
+  rowSortingFeature,
+  columnFilteringFeature,
+  globalFilteringFeature,
+  columnGroupingFeature,
+  rowExpandingFeature,
+  filteredRowModel: createFilteredRowModel(),
+  sortedRowModel: createSortedRowModel(),
+  groupedRowModel: createGroupedRowModel(),
+  expandedRowModel: createExpandedRowModel(),
+  filterFns: { ...filterFns, fuzzy: fuzzyFilter }, // keep built-ins + add custom
+  sortFns,
+  aggregationFns,
+  filterMeta: metaHelper<FuzzyFilterMeta>(),
+})
+
 const columnHelper = createColumnHelper<typeof features, Person>()
 
 const columns = columnHelper.columns([
   columnHelper.accessor('firstName', {
-    filterFn: 'fuzzy', // ← refers to registered name
+    filterFn: 'fuzzy', // ← string ref typechecks because 'fuzzy' is in features.filterFns
     sortFn: 'alphanumeric',
   }),
   columnHelper.accessor('revenue', {
@@ -111,15 +123,6 @@ const columns = columnHelper.columns([
 
 const table = constructTable({
   features,
-  rowModels: {
-    filteredRowModel: createFilteredRowModel({
-      ...filterFns, // keep built-ins
-      fuzzy: fuzzyFilter, // add custom
-    }),
-    sortedRowModel: createSortedRowModel(sortFns),
-    groupedRowModel: createGroupedRowModel(aggregationFns),
-    expandedRowModel: createExpandedRowModel(),
-  },
   columns,
   data,
   globalFilterFn: 'fuzzy',
@@ -198,12 +201,16 @@ const weightedMean: AggregationFn<typeof features, Person> = (
   return totalWeight === 0 ? 0 : weightedSum / totalWeight
 }
 
+const customFeatures = tableFeatures({
+  columnGroupingFeature,
+  rowExpandingFeature,
+  groupedRowModel: createGroupedRowModel(),
+  expandedRowModel: createExpandedRowModel(),
+  aggregationFns: { ...aggregationFns, weightedMean },
+})
+
 const table = constructTable({
-  features,
-  rowModels: {
-    groupedRowModel: createGroupedRowModel({ ...aggregationFns, weightedMean }),
-    expandedRowModel: createExpandedRowModel(),
-  },
+  features: customFeatures,
   columns: columnHelper.columns([
     columnHelper.accessor('revenue', {
       aggregationFn: 'weightedMean',
@@ -221,13 +228,15 @@ const table = constructTable({
 Wrong:
 
 ```ts
-// "fuzzy" string never registered
+// "fuzzy" string never registered in features.filterFns
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns, // ❌ built-ins only — no fuzzy
+})
 const table = useTable({
   features,
   columns: [columnHelper.accessor('fullName', { filterFn: 'fuzzy' })],
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns), // ❌ no fuzzy
-  },
   data,
 })
 ```
@@ -235,13 +244,7 @@ const table = useTable({
 Correct:
 
 ```ts
-declare module '@tanstack/react-table' {
-  interface FilterFns {
-    fuzzy: FilterFn<typeof features, Person>
-  }
-}
-
-const fuzzyFilter: FilterFn<typeof features, Person> = (
+const fuzzyFilter: FilterFn<FuzzyFeatures, Person> = (
   row,
   columnId,
   value,
@@ -252,20 +255,21 @@ const fuzzyFilter: FilterFn<typeof features, Person> = (
   return itemRank.passed
 }
 
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { ...filterFns, fuzzy: fuzzyFilter }, // ✅ registered
+  filterMeta: metaHelper<FuzzyFilterMeta>(),
+})
+
 const table = useTable({
   features,
   columns: [columnHelper.accessor('fullName', { filterFn: 'fuzzy' })],
-  rowModels: {
-    filteredRowModel: createFilteredRowModel({
-      ...filterFns,
-      fuzzy: fuzzyFilter,
-    }),
-  },
   data,
 })
 ```
 
-String values are looked up in `table._rowModelFns.filterFns`. Unregistered names log `Could not find a valid 'column.filterFn' …` in dev and silently no-op in prod.
+String values are looked up in `features.filterFns`. Unregistered names log `Could not find a valid 'column.filterFn' …` in dev and silently no-op in prod.
 
 Source: examples/react/filters-fuzzy/src/main.tsx; packages/table-core/src/features/column-filtering/columnFilteringFeature.utils.ts
 
@@ -399,8 +403,11 @@ Correct:
 
 ```ts
 const table = useTable({
-  features: tableFeatures({ rowSortingFeature }),
-  rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+  features: tableFeatures({
+    rowSortingFeature,
+    sortedRowModel: createSortedRowModel(),
+    sortFns,
+  }),
   columns,
   data,
 })

package/skills/filtering/SKILL.md

@@ -3,7 +3,7 @@ name: filtering
 description: >
   Filter rows in TanStack Table v9 with the `filteredRowModel` pipeline stage.
   Covers `columnFilteringFeature` + `globalFilteringFeature` + `columnFacetingFeature`,
-  `createFilteredRowModel(filterFns)`, `createFacetedRowModel()` /
+  `createFilteredRowModel()` (registered on `features` with `filterFns` slot), `createFacetedRowModel()` /
   `createFacetedUniqueValues()` / `createFacetedMinMaxValues()`, fuzzy filtering
   with `@tanstack/match-sorter-utils`, the built-in `filterFns` registry, custom
   `filterFn` + module augmentation, `state.columnFilters` (Array<{ id, value }>),
@@ -36,13 +36,13 @@ This skill builds on `tanstack-table/state-management` and `tanstack-table/custo
 
 Filtering has five subsystems in v9 — register only the features you need:
 
-| Subsystem        | Feature                  | Row-model                           |
-| ---------------- | ------------------------ | ----------------------------------- |
-| column-filtering | `columnFilteringFeature` | `createFilteredRowModel(filterFns)` |
-| global-filtering | `globalFilteringFeature` | (same `filteredRowModel`)           |
-| column-faceting  | `columnFacetingFeature`  | `createFacetedRowModel()` + helpers |
-| global-faceting  | `globalFacetingFeature`  | global versions of the helpers      |
-| fuzzy-filtering  | (custom filterFn)        | `@tanstack/match-sorter-utils`      |
+| Subsystem        | Feature                  | Row-model                                     |
+| ---------------- | ------------------------ | --------------------------------------------- |
+| column-filtering | `columnFilteringFeature` | `createFilteredRowModel()` + `filterFns` slot |
+| global-filtering | `globalFilteringFeature` | (same `filteredRowModel`)                     |
+| column-faceting  | `columnFacetingFeature`  | `createFacetedRowModel()` + helpers           |
+| global-faceting  | `globalFacetingFeature`  | global versions of the helpers                |
+| fuzzy-filtering  | (custom filterFn)        | `@tanstack/match-sorter-utils`                |
 
 ```ts
 import {
@@ -60,14 +60,13 @@ const features = tableFeatures({
   columnFilteringFeature,
   globalFilteringFeature,
   rowPaginationFeature,
+  filteredRowModel: createFilteredRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  filterFns,
 })
 
 const table = constructTable({
   features,
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
-    paginatedRowModel: createPaginatedRowModel(),
-  },
   columns,
   data,
   initialState: {
@@ -130,7 +129,7 @@ function Filter({ column }) {
 
 ### Faceted filter UIs and fuzzy global search
 
-Faceting requires `createFacetedRowModel()` as the base plus `createFacetedUniqueValues()` / `createFacetedMinMaxValues()`; fuzzy filtering wires a custom `FilterFn` backed by `@tanstack/match-sorter-utils` (`rankItem` / `compareItems`) with module augmentation for `FilterFns` + `FilterMeta`. Full examples in [faceting-and-fuzzy.md](references/faceting-and-fuzzy.md).
+Faceting requires `createFacetedRowModel()` as the base plus `createFacetedUniqueValues()` / `createFacetedMinMaxValues()` — all registered on the `features` object; fuzzy filtering wires a custom `FilterFn` backed by `@tanstack/match-sorter-utils` (`rankItem` / `compareItems`) with the `filterFns` registry slot and `filterMeta` slot for type-safe meta. Full examples in [faceting-and-fuzzy.md](references/faceting-and-fuzzy.md).
 
 ### Server-side filtering
 
@@ -143,7 +142,7 @@ const { data } = useQuery({
 })
 const table = useTable({
   features: tableFeatures({ columnFilteringFeature }),
-  rowModels: {}, // no filteredRowModel needed for manual filtering
+  // no filteredRowModel registered — server filters
   data,
   columns,
   manualFiltering: true,
@@ -155,12 +154,15 @@ const table = useTable({
 ### Filter tree data and keep matching descendants visible
 
 ```ts
+const features = tableFeatures({
+  columnFilteringFeature,
+  rowExpandingFeature,
+  filteredRowModel: createFilteredRowModel(),
+  expandedRowModel: createExpandedRowModel(),
+  filterFns,
+})
 const table = constructTable({
-  features: tableFeatures({ columnFilteringFeature, rowExpandingFeature }),
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
-    expandedRowModel: createExpandedRowModel(),
-  },
+  features,
   columns,
   data,
   getSubRows: (r) => r.subRows,
@@ -176,13 +178,15 @@ Wrong:
 
 ```tsx
 const table = useTable({
-  features: tableFeatures({ columnFacetingFeature, columnFilteringFeature }),
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
+  features: tableFeatures({
+    columnFacetingFeature,
+    columnFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
     // BUG: missing facetedRowModel
     facetedUniqueValues: createFacetedUniqueValues(),
     facetedMinMaxValues: createFacetedMinMaxValues(),
-  },
+    filterFns,
+  }),
   columns,
   data,
 })
@@ -196,14 +200,13 @@ const table = useTable({
     columnFacetingFeature,
     columnFilteringFeature,
     rowPaginationFeature,
-  }),
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
+    filteredRowModel: createFilteredRowModel(),
     paginatedRowModel: createPaginatedRowModel(),
     facetedRowModel: createFacetedRowModel(), // REQUIRED base
     facetedMinMaxValues: createFacetedMinMaxValues(),
     facetedUniqueValues: createFacetedUniqueValues(),
-  },
+    filterFns,
+  }),
   columns,
   data,
 })
@@ -220,8 +223,11 @@ Wrong:
 ```tsx
 // manualFiltering bypasses the filteredRowModel — filter UI changes do nothing
 const table = useTable({
-  features: tableFeatures({ columnFilteringFeature }),
-  rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
+  features: tableFeatures({
+    columnFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    filterFns,
+  }),
   data,
   columns,
   manualFiltering: true,
@@ -241,7 +247,7 @@ const { data } = useQuery({
 
 const table = useTable({
   features: tableFeatures({ columnFilteringFeature }),
-  rowModels: {}, // no filteredRowModel needed
+  // no filteredRowModel registered for manual mode
   data,
   columns,
   manualFiltering: true,
@@ -260,9 +266,11 @@ Wrong:
 
 ```tsx
 // drops the built-in registry
-filteredRowModel: createFilteredRowModel({
-  fuzzy: fuzzyFilter,
-}),
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { fuzzy: fuzzyFilter }, // BUG: drops built-ins
+})
 // Column with filterFn: 'includesString' now warns and never filters
 ```
 
@@ -271,13 +279,17 @@ Correct:
 ```tsx
 import { filterFns } from '@tanstack/react-table'
 
-filteredRowModel: createFilteredRowModel({
-  ...filterFns, // KEEP built-ins
-  fuzzy: fuzzyFilter, // ADD custom
-}),
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: {
+    ...filterFns, // KEEP built-ins
+    fuzzy: fuzzyFilter, // ADD custom
+  },
+})
 ```
 
-`createFilteredRowModel` replaces the registry with whatever you pass. Any column using a built-in name like `'includesString'` becomes a no-op.
+The `filterFns` slot replaces the registry with whatever you provide. Any column using a built-in name like `'includesString'` becomes a no-op if the built-ins are dropped.
 
 Source: examples/react/filters-fuzzy/src/main.tsx
 
@@ -298,8 +310,11 @@ Correct:
 
 ```tsx
 const table = useTable({
-  features: tableFeatures({ globalFilteringFeature }),
-  rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
+  features: tableFeatures({
+    globalFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    filterFns,
+  }),
   columns,
   data,
   globalFilterFn: 'includesString',
@@ -333,8 +348,11 @@ Correct:
 
 ```ts
 const table = useTable({
-  features: tableFeatures({ columnFilteringFeature }),
-  rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
+  features: tableFeatures({
+    columnFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    filterFns,
+  }),
   columns,
   data,
 })

package/skills/filtering/references/faceting-and-fuzzy.md

@@ -16,17 +16,16 @@ const features = tableFeatures({
   columnFacetingFeature,
   columnFilteringFeature,
   rowPaginationFeature,
+  filteredRowModel: createFilteredRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  facetedRowModel: createFacetedRowModel(), // REQUIRED base
+  facetedMinMaxValues: createFacetedMinMaxValues(),
+  facetedUniqueValues: createFacetedUniqueValues(),
+  filterFns,
 })
 
 const table = constructTable({
   features,
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
-    paginatedRowModel: createPaginatedRowModel(),
-    facetedRowModel: createFacetedRowModel(), // REQUIRED base
-    facetedMinMaxValues: createFacetedMinMaxValues(),
-    facetedUniqueValues: createFacetedUniqueValues(),
-  },
   columns,
   data,
 })
@@ -44,18 +43,28 @@ import {
   compareItems,
   type RankingInfo,
 } from '@tanstack/match-sorter-utils'
-import type { FilterFn, SortFn } from '@tanstack/table-core'
+import {
+  tableFeatures,
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowSortingFeature,
+  createFilteredRowModel,
+  createSortedRowModel,
+  filterFns,
+  sortFns,
+  metaHelper,
+} from '@tanstack/table-core'
+import type { FilterFn, SortFn, TableFeatures } from '@tanstack/table-core'
 
-declare module '@tanstack/react-table' {
-  interface FilterFns {
-    fuzzy: FilterFn<typeof features, Person>
-  }
-  interface FilterMeta {
-    itemRank?: RankingInfo
-  }
+// 1. Describe the filterMeta shape for this feature set.
+interface FuzzyFilterMeta {
+  itemRank?: RankingInfo
 }
 
-const fuzzyFilter: FilterFn<typeof features, Person> = (
+// 2. Extend TableFeatures so FilterFn / SortFn can read filterMeta types.
+type FuzzyFeatures = TableFeatures & { filterMeta: FuzzyFilterMeta }
+
+const fuzzyFilter: FilterFn<FuzzyFeatures, Person> = (
   row,
   columnId,
   value,
@@ -66,7 +75,7 @@ const fuzzyFilter: FilterFn<typeof features, Person> = (
   return itemRank.passed
 }
 
-const fuzzySort: SortFn<typeof features, Person> = (rowA, rowB, columnId) => {
+const fuzzySort: SortFn<FuzzyFeatures, Person> = (rowA, rowB, columnId) => {
   let dir = 0
   if (rowA.columnFiltersMeta[columnId]) {
     dir = compareItems(
@@ -77,21 +86,35 @@ const fuzzySort: SortFn<typeof features, Person> = (rowA, rowB, columnId) => {
   return dir === 0 ? sortFns.alphanumeric(rowA, rowB, columnId) : dir
 }
 
+// 3. Register everything on features — no rowModels option needed.
+const features = tableFeatures({
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowSortingFeature,
+  filteredRowModel: createFilteredRowModel(),
+  sortedRowModel: createSortedRowModel(),
+  filterFns: { ...filterFns, fuzzy: fuzzyFilter },
+  sortFns: { ...sortFns, fuzzy: fuzzySort },
+  filterMeta: metaHelper<FuzzyFilterMeta>(),
+})
+
 const table = constructTable({
   features,
-  rowModels: {
-    filteredRowModel: createFilteredRowModel({
-      ...filterFns,
-      fuzzy: fuzzyFilter,
-    }),
-    sortedRowModel: createSortedRowModel(sortFns),
-  },
   columns,
   data,
   globalFilterFn: 'fuzzy',
 })
 ```
 
+Use string refs in column defs when the fn is registered:
+
+```ts
+columnHelper.accessor('fullName', {
+  filterFn: 'fuzzy', // string ref — typechecks because 'fuzzy' is in features.filterFns
+  sortFn: 'fuzzy',
+})
+```
+
 ## Additional MEDIUM-priority failure modes
 
 ### Using `state.columnFilters` AND `initialState.columnFilters` simultaneously
@@ -131,11 +154,13 @@ Wrong:
 ```tsx
 // filterFromLeafRows hides children that don't match individually
 const table = useTable({
-  features: tableFeatures({ columnFilteringFeature, rowExpandingFeature }),
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
+  features: tableFeatures({
+    columnFilteringFeature,
+    rowExpandingFeature,
+    filteredRowModel: createFilteredRowModel(),
     expandedRowModel: createExpandedRowModel(),
-  },
+    filterFns,
+  }),
   columns,
   data,
   getSubRows: (r) => r.subRows,
@@ -150,11 +175,13 @@ Correct:
 ```tsx
 // Filter root-only to preserve all sub-rows under a matching parent
 const table = useTable({
-  features: tableFeatures({ columnFilteringFeature, rowExpandingFeature }),
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns),
+  features: tableFeatures({
+    columnFilteringFeature,
+    rowExpandingFeature,
+    filteredRowModel: createFilteredRowModel(),
     expandedRowModel: createExpandedRowModel(),
-  },
+    filterFns,
+  }),
   columns,
   data,
   getSubRows: (r) => r.subRows,