@tanstack/table-core 9.0.0-alpha.8 → 9.0.0-beta.10

package/skills/filtering/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: filtering
+description: >
+  Filter rows in TanStack Table v9 with the `filteredRowModel` pipeline stage.
+  Covers `columnFilteringFeature` + `globalFilteringFeature` + `columnFacetingFeature`,
+  `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 }>),
+  `state.globalFilter`, `column.setFilterValue` / `setColumnFilters` /
+  `setGlobalFilter`, `column.getFacetedUniqueValues` /
+  `column.getFacetedMinMaxValues`, `manualFiltering`, `filterFromLeafRows`,
+  `maxLeafRowFilterDepth`, `getColumnCanGlobalFilter`. Five subsystems:
+  column-filtering, global-filtering, column-faceting, global-faceting,
+  fuzzy-filtering.
+type: core
+library: tanstack-table
+library_version: '9.0.0-alpha.48'
+requires:
+  - state-management
+  - customizing-feature-behavior
+sources:
+  - TanStack/table:docs/guide/column-filtering.md
+  - TanStack/table:docs/guide/global-filtering.md
+  - TanStack/table:docs/guide/column-faceting.md
+  - TanStack/table:docs/guide/global-faceting.md
+  - TanStack/table:docs/guide/fuzzy-filtering.md
+  - TanStack/table:examples/react/filters/src/main.tsx
+  - TanStack/table:examples/react/filters-faceted/src/main.tsx
+  - TanStack/table:examples/react/filters-fuzzy/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management` and `tanstack-table/customizing-feature-behavior`. Read those first for the atom model and `filterFn`/`globalFilterFn` overrides.
+
+## Setup
+
+Filtering has five subsystems in v9 — register only the features you need:
+
+| 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 {
+  tableFeatures,
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowPaginationFeature,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  filterFns,
+} from '@tanstack/table-core'
+import type { ColumnFiltersState } from '@tanstack/table-core'
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowPaginationFeature,
+  filteredRowModel: createFilteredRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  filterFns,
+})
+
+const table = constructTable({
+  features,
+  columns,
+  data,
+  initialState: {
+    columnFilters: [] satisfies ColumnFiltersState,
+    globalFilter: '',
+  },
+  globalFilterFn: 'includesString',
+})
+
+table.setColumnFilters([{ id: 'firstName', value: 'Ada' }])
+table.setGlobalFilter('Lovelace')
+```
+
+## Core Patterns
+
+### Text / range / select column filters
+
+```tsx
+// From examples/react/filters/src/main.tsx
+function Filter({ column }) {
+  const firstValue = column
+    .getFacetedRowModel()
+    .flatRows[0]?.getValue(column.id)
+  const columnFilterValue = column.getFilterValue()
+
+  return typeof firstValue === 'number' ? (
+    <div>
+      <input
+        type="number"
+        value={(columnFilterValue as [number, number])?.[0] ?? ''}
+        onChange={(e) =>
+          column.setFilterValue((old: [number, number]) => [
+            e.target.value,
+            old?.[1],
+          ])
+        }
+        placeholder="Min"
+      />
+      <input
+        type="number"
+        value={(columnFilterValue as [number, number])?.[1] ?? ''}
+        onChange={(e) =>
+          column.setFilterValue((old: [number, number]) => [
+            old?.[0],
+            e.target.value,
+          ])
+        }
+        placeholder="Max"
+      />
+    </div>
+  ) : (
+    <input
+      value={(columnFilterValue ?? '') as string}
+      onChange={(e) => column.setFilterValue(e.target.value)}
+      placeholder="Search…"
+    />
+  )
+}
+```
+
+### Faceted filter UIs and fuzzy global search
+
+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
+
+```tsx
+const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+const { data } = useQuery({
+  queryKey: ['rows', columnFilters],
+  queryFn: () =>
+    fetch('/api/rows?' + serialize(columnFilters)).then((r) => r.json()),
+})
+const table = useTable({
+  features: tableFeatures({ columnFilteringFeature }),
+  // no filteredRowModel registered — server filters
+  data,
+  columns,
+  manualFiltering: true,
+  state: { columnFilters },
+  onColumnFiltersChange: setColumnFilters,
+})
+```
+
+### Filter tree data and keep matching descendants visible
+
+```ts
+const features = tableFeatures({
+  columnFilteringFeature,
+  rowExpandingFeature,
+  filteredRowModel: createFilteredRowModel(),
+  expandedRowModel: createExpandedRowModel(),
+  filterFns,
+})
+const table = constructTable({
+  features,
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  filterFromLeafRows: true, // bottom-up: keep parent if any descendant matches
+})
+```
+
+## Common Mistakes
+
+### [HIGH] Forgetting `createFacetedRowModel()` while registering `createFacetedUniqueValues()` / `createFacetedMinMaxValues()`
+
+Wrong:
+
+```tsx
+const table = useTable({
+  features: tableFeatures({
+    columnFacetingFeature,
+    columnFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    // BUG: missing facetedRowModel
+    facetedUniqueValues: createFacetedUniqueValues(),
+    facetedMinMaxValues: createFacetedMinMaxValues(),
+    filterFns,
+  }),
+  columns,
+  data,
+})
+```
+
+Correct:
+
+```tsx
+const table = useTable({
+  features: tableFeatures({
+    columnFacetingFeature,
+    columnFilteringFeature,
+    rowPaginationFeature,
+    filteredRowModel: createFilteredRowModel(),
+    paginatedRowModel: createPaginatedRowModel(),
+    facetedRowModel: createFacetedRowModel(), // REQUIRED base
+    facetedMinMaxValues: createFacetedMinMaxValues(),
+    facetedUniqueValues: createFacetedUniqueValues(),
+    filterFns,
+  }),
+  columns,
+  data,
+})
+```
+
+Without the base `facetedRowModel`, the unique/minMax helpers fall back to `getPreFilteredRowModel()` — facet values stop excluding the column's own active filter, and a select dropdown collapses to only the currently selected value once the user picks one.
+
+Source: packages/table-core/src/features/column-faceting/columnFacetingFeature.utils.ts; examples/react/filters-faceted/src/main.tsx
+
+### [HIGH] Setting `manualFiltering: true` without refetching data
+
+Wrong:
+
+```tsx
+// manualFiltering bypasses the filteredRowModel — filter UI changes do nothing
+const table = useTable({
+  features: tableFeatures({
+    columnFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    filterFns,
+  }),
+  data,
+  columns,
+  manualFiltering: true,
+  // ...but no useEffect / useQuery key tracking columnFilters
+})
+```
+
+Correct:
+
+```tsx
+const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+const { data } = useQuery({
+  queryKey: ['rows', columnFilters],
+  queryFn: () =>
+    fetch('/api/rows?' + serialize(columnFilters)).then((r) => r.json()),
+})
+
+const table = useTable({
+  features: tableFeatures({ columnFilteringFeature }),
+  // no filteredRowModel registered for manual mode
+  data,
+  columns,
+  manualFiltering: true,
+  state: { columnFilters },
+  onColumnFiltersChange: setColumnFilters,
+})
+```
+
+With `manualFiltering: true`, `table_getFilteredRowModel` short-circuits and returns the core rows. Rows are NOT filtered client-side — you must refetch.
+
+Source: docs/guide/column-filtering.md; packages/table-core/src/core/row-models/coreRowModelsFeature.utils.ts
+
+### [HIGH] Custom fuzzy filter without merging into `filterFns`
+
+Wrong:
+
+```tsx
+// drops the built-in registry
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { fuzzy: fuzzyFilter }, // BUG: drops built-ins
+})
+// Column with filterFn: 'includesString' now warns and never filters
+```
+
+Correct:
+
+```tsx
+import { filterFns } from '@tanstack/react-table'
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: {
+    ...filterFns, // KEEP built-ins
+    fuzzy: fuzzyFilter, // ADD custom
+  },
+})
+```
+
+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
+
+### [MEDIUM] Global filter silently skips columns with non-string/non-number values
+
+Wrong:
+
+```tsx
+// createdAt is a Date object — global filter silently skips it
+const columns = [
+  columnHelper.accessor('createdAt', { header: 'Created' }),
+  columnHelper.accessor('name', { header: 'Name' }),
+]
+// table.setGlobalFilter('2024') will never find Date rows
+```
+
+Correct:
+
+```tsx
+const table = useTable({
+  features: tableFeatures({
+    globalFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    filterFns,
+  }),
+  columns,
+  data,
+  globalFilterFn: 'includesString',
+  getColumnCanGlobalFilter: (column) => true, // include every column
+})
+
+// Or per-column:
+columnHelper.accessor('createdAt', {
+  header: 'Created',
+  enableGlobalFilter: true,
+})
+```
+
+`globalFilteringFeature` defaults `getColumnCanGlobalFilter` to a function that returns `typeof value === 'string' || typeof value === 'number'` sampled from the first row. Objects, dates, booleans, undefined all silently fail.
+
+Source: packages/table-core/src/features/global-filtering/globalFilteringFeature.ts
+
+### [CRITICAL] Reimplementing what built-in APIs provide
+
+Wrong:
+
+```ts
+// Hand-rolled filter loop, bypassing the table
+const filteredData = useMemo(
+  () => data.filter(/* …custom matching… */),
+  [data, query],
+)
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  features: tableFeatures({
+    columnFilteringFeature,
+    filteredRowModel: createFilteredRowModel(),
+    filterFns,
+  }),
+  columns,
+  data,
+})
+table.setColumnFilters([{ id: 'name', value: 'Ada' }])
+// or: column.setFilterValue('Ada')
+```
+
+`table.setColumnFilters`, `column.setFilterValue`, `table.setGlobalFilter` honor reset behavior and internal invariants.
+
+Source: maintainer interview (Phase 4, 2026-05-17)
+
+## See also
+
+- `tanstack-table/customizing-feature-behavior` — `filterFn` / `globalFilterFn` authoring, `addMeta` chain
+- `tanstack-table/sorting` — fuzzy sort pairing for `match-sorter-utils`
+- `tanstack-table/row-expanding` — `filterFromLeafRows` interaction with tree data
+
+## References
+
+- [faceting-and-fuzzy.md](references/faceting-and-fuzzy.md) — faceted filter UIs (autocomplete + range slider) with `createFacetedRowModel`/`createFacetedUniqueValues`/`createFacetedMinMaxValues`, fuzzy global search via `@tanstack/match-sorter-utils`, plus MEDIUM-priority failure modes: `state` + `initialState` collision, `filterFromLeafRows` semantics, `'auto'` filter misdetection on null first row

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

@@ -0,0 +1,218 @@
+# Faceting and fuzzy filtering — extended patterns
+
+Extended filtering patterns extracted from `SKILL.md`. The SKILL keeps simple column filter, global filter, server-side, and tree-data patterns inline; this file covers faceted UIs and fuzzy filtering with `@tanstack/match-sorter-utils`.
+
+## Faceted filter UIs (autocomplete + range slider)
+
+```ts
+import {
+  columnFacetingFeature,
+  createFacetedRowModel,
+  createFacetedUniqueValues,
+  createFacetedMinMaxValues,
+} from '@tanstack/table-core'
+
+const features = tableFeatures({
+  columnFacetingFeature,
+  columnFilteringFeature,
+  rowPaginationFeature,
+  filteredRowModel: createFilteredRowModel(),
+  paginatedRowModel: createPaginatedRowModel(),
+  facetedRowModel: createFacetedRowModel(), // REQUIRED base
+  facetedMinMaxValues: createFacetedMinMaxValues(),
+  facetedUniqueValues: createFacetedUniqueValues(),
+  filterFns,
+})
+
+const table = constructTable({
+  features,
+  columns,
+  data,
+})
+
+// In a Filter component:
+const uniqueValues = column.getFacetedUniqueValues() // Map<value, count>
+const [min, max] = column.getFacetedMinMaxValues() ?? [0, 0]
+```
+
+## Fuzzy global search with match-sorter-utils
+
+```ts
+import {
+  rankItem,
+  compareItems,
+  type RankingInfo,
+} from '@tanstack/match-sorter-utils'
+import {
+  tableFeatures,
+  columnFilteringFeature,
+  globalFilteringFeature,
+  rowSortingFeature,
+  createFilteredRowModel,
+  createSortedRowModel,
+  filterFns,
+  sortFns,
+  metaHelper,
+} from '@tanstack/table-core'
+import type { FilterFn, SortFn, TableFeatures } from '@tanstack/table-core'
+
+// 1. Describe the filterMeta shape for this feature set.
+interface FuzzyFilterMeta {
+  itemRank?: RankingInfo
+}
+
+// 2. Extend TableFeatures so FilterFn / SortFn can read filterMeta types.
+type FuzzyFeatures = TableFeatures & { filterMeta: FuzzyFilterMeta }
+
+const fuzzyFilter: FilterFn<FuzzyFeatures, Person> = (
+  row,
+  columnId,
+  value,
+  addMeta,
+) => {
+  const itemRank = rankItem(row.getValue(columnId), value)
+  addMeta?.({ itemRank })
+  return itemRank.passed
+}
+
+const fuzzySort: SortFn<FuzzyFeatures, Person> = (rowA, rowB, columnId) => {
+  let dir = 0
+  if (rowA.columnFiltersMeta[columnId]) {
+    dir = compareItems(
+      rowA.columnFiltersMeta[columnId].itemRank!,
+      rowB.columnFiltersMeta[columnId].itemRank!,
+    )
+  }
+  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,
+  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
+
+Wrong:
+
+```tsx
+const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+const table = useTable({
+  initialState: { columnFilters: [{ id: 'name', value: 'John' }] }, // IGNORED
+  state: { columnFilters }, // wins, starts empty
+  onColumnFiltersChange: setColumnFilters,
+})
+```
+
+Correct:
+
+```tsx
+// Seed the controlled state at useState time, NOT in initialState
+const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([
+  { id: 'name', value: 'John' },
+])
+const table = useTable({
+  state: { columnFilters },
+  onColumnFiltersChange: setColumnFilters,
+})
+```
+
+`state` always overrides `initialState`. Seed your controlled state instead.
+
+Source: docs/guide/column-filtering.md
+
+### Expecting `filterFromLeafRows` to keep ALL children of a matching parent visible
+
+Wrong:
+
+```tsx
+// filterFromLeafRows hides children that don't match individually
+const table = useTable({
+  features: tableFeatures({
+    columnFilteringFeature,
+    rowExpandingFeature,
+    filteredRowModel: createFilteredRowModel(),
+    expandedRowModel: createExpandedRowModel(),
+    filterFns,
+  }),
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  filterFromLeafRows: true,
+  // expectation: parent matches "John" → all children visible
+  // reality: only children that also match "John" stay visible
+})
+```
+
+Correct:
+
+```tsx
+// Filter root-only to preserve all sub-rows under a matching parent
+const table = useTable({
+  features: tableFeatures({
+    columnFilteringFeature,
+    rowExpandingFeature,
+    filteredRowModel: createFilteredRowModel(),
+    expandedRowModel: createExpandedRowModel(),
+    filterFns,
+  }),
+  columns,
+  data,
+  getSubRows: (r) => r.subRows,
+  maxLeafRowFilterDepth: 0,
+})
+```
+
+`filterFromLeafRows: true` is bottom-up. The mutually exclusive top-down default is what preserves descendants under a matching parent.
+
+Source: packages/table-core/src/features/column-filtering/filterRowsUtils.ts
+
+### Auto filter type misdetects when first row has `null`/`undefined`
+
+Wrong:
+
+```ts
+const data = [
+  { id: 1, name: null }, // first row
+  { id: 2, name: 'Alice' },
+]
+// Column filter returns 0 results — auto picked wrong filter from null
+```
+
+Correct:
+
+```ts
+columnHelper.accessor('name', {
+  filterFn: 'includesString', // explicit, don't rely on auto
+})
+```
+
+The default `'auto'` `filterFn` infers from the first row's value. If it's null/undefined, type detection fails.
+
+Source: https://github.com/TanStack/table/issues/4711