@tanstack/table-core 9.0.0-beta.5 → 9.0.0-beta.51

package/dist/worker/tableWorkerProtocol.d.ts

@@ -0,0 +1,88 @@
+import { RowData } from "../types/type-utils.js";
+
+//#region src/worker/tableWorkerProtocol.d.ts
+/**
+ * Row model stages that can be offloaded to the worker, in pipeline order.
+ * Everything else in this module is derived from this list; adding a stage
+ * means adding an entry here and to `tableWorkerStageStateDeps`.
+ */
+declare const tableWorkerPipeline: readonly ["filtered", "grouped", "sorted", "expanded"];
+type TableWorkerStage = (typeof tableWorkerPipeline)[number];
+/**
+ * The state slices each stage's computation depends on. The main thread sends
+ * the union of deps for its registered stages; a change to any of them
+ * triggers one worker round trip.
+ */
+declare const tableWorkerStageStateDeps: Record<TableWorkerStage, Array<string>>;
+/**
+ * A serialized synthetic (group) row. Leaf rows serialize as their position in
+ * `options.data`; group rows carry what `constructRow` + the grouped row model
+ * need to rebuild them, plus eagerly computed aggregate values so no
+ * aggregation runs on the main thread.
+ */
+interface TableWorkerGroupNode {
+  id: string;
+  groupingColumnId: string;
+  groupingValue: unknown;
+  index: number;
+  aggregates: Record<string, unknown>;
+  children: Array<TableWorkerRowNode>;
+}
+type TableWorkerRowNode = number | TableWorkerGroupNode;
+/**
+ * A stage result. Flat models (every row is a data row) travel as a
+ * transferable index permutation; models containing synthetic rows (grouping)
+ * travel as a tree. The kind is chosen from the model's actual shape at
+ * runtime, not from the stage name: a sorted model is flat without grouping
+ * and a tree with it.
+ *
+ * `unchanged` means the stage's model is identical to the last one sent for
+ * this dataset (its memoized inputs did not change); the main thread keeps
+ * its previous result and skips the rebuild entirely.
+ */
+type TableWorkerStagePayload = {
+  kind: 'flat';
+  indices: Uint32Array;
+} | {
+  kind: 'tree';
+  children: Array<TableWorkerRowNode>;
+} | {
+  kind: 'unchanged';
+};
+type TableWorkerRequest<TData extends RowData = any> = {
+  type: 'data';
+  dataVersion: number;
+  data: Array<TData>;
+} | {
+  type: 'process';
+  requestId: number;
+  dataVersion: number; /** The stages the main thread has worker-backed row models for. */
+  stages: Array<TableWorkerStage>; /** Serializable state slices (union of the stages' deps). */
+  state: Record<string, unknown>;
+};
+interface TableWorkerResult {
+  type: 'result';
+  requestId: number;
+  dataVersion: number;
+  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload };
+  computeMs: number;
+}
+type TableWorkerResponse = TableWorkerResult;
+/**
+ * The state slice added by `workerRowModelsFeature`. `version` bumps when a
+ * worker result lands (driving re-renders through the normal state path);
+ * `isPending` is true while a request is in flight. The timing fields expose
+ * the last result's worker compute time and full round trip for devtools and
+ * debugging.
+ */
+interface TableState_WorkerRowModels {
+  workerRowModels: {
+    version: number;
+    isPending: boolean;
+    lastComputeMs?: number;
+    lastRoundTripMs?: number;
+  };
+}
+//#endregion
+export { TableState_WorkerRowModels, TableWorkerGroupNode, TableWorkerRequest, TableWorkerResponse, TableWorkerResult, TableWorkerRowNode, TableWorkerStage, TableWorkerStagePayload, tableWorkerPipeline, tableWorkerStageStateDeps };
+//# sourceMappingURL=tableWorkerProtocol.d.ts.map

package/dist/worker/tableWorkerProtocol.js

@@ -0,0 +1,27 @@
+//#region src/worker/tableWorkerProtocol.ts
+/**
+* Row model stages that can be offloaded to the worker, in pipeline order.
+* Everything else in this module is derived from this list; adding a stage
+* means adding an entry here and to `tableWorkerStageStateDeps`.
+*/
+const tableWorkerPipeline = [
+	"filtered",
+	"grouped",
+	"sorted",
+	"expanded"
+];
+/**
+* The state slices each stage's computation depends on. The main thread sends
+* the union of deps for its registered stages; a change to any of them
+* triggers one worker round trip.
+*/
+const tableWorkerStageStateDeps = {
+	filtered: ["columnFilters", "globalFilter"],
+	grouped: ["grouping"],
+	sorted: ["sorting"],
+	expanded: ["expanded"]
+};
+
+//#endregion
+export { tableWorkerPipeline, tableWorkerStageStateDeps };
+//# sourceMappingURL=tableWorkerProtocol.js.map

package/dist/worker/tableWorkerProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableWorkerProtocol.js","names":[],"sources":["../../src/worker/tableWorkerProtocol.ts"],"sourcesContent":["import type { RowData } from '../types/type-utils'\n\n/**\n * Row model stages that can be offloaded to the worker, in pipeline order.\n * Everything else in this module is derived from this list; adding a stage\n * means adding an entry here and to `tableWorkerStageStateDeps`.\n */\nexport const tableWorkerPipeline = [\n  'filtered',\n  'grouped',\n  'sorted',\n  'expanded',\n] as const\n\nexport type TableWorkerStage = (typeof tableWorkerPipeline)[number]\n\n/**\n * The state slices each stage's computation depends on. The main thread sends\n * the union of deps for its registered stages; a change to any of them\n * triggers one worker round trip.\n */\nexport const tableWorkerStageStateDeps: Record<\n  TableWorkerStage,\n  Array<string>\n> = {\n  filtered: ['columnFilters', 'globalFilter'],\n  grouped: ['grouping'],\n  sorted: ['sorting'],\n  expanded: ['expanded'],\n}\n\n/**\n * A serialized synthetic (group) row. Leaf rows serialize as their position in\n * `options.data`; group rows carry what `constructRow` + the grouped row model\n * need to rebuild them, plus eagerly computed aggregate values so no\n * aggregation runs on the main thread.\n */\nexport interface TableWorkerGroupNode {\n  id: string\n  groupingColumnId: string\n  groupingValue: unknown\n  index: number\n  aggregates: Record<string, unknown>\n  children: Array<TableWorkerRowNode>\n}\n\nexport type TableWorkerRowNode = number | TableWorkerGroupNode\n\n/**\n * A stage result. Flat models (every row is a data row) travel as a\n * transferable index permutation; models containing synthetic rows (grouping)\n * travel as a tree. The kind is chosen from the model's actual shape at\n * runtime, not from the stage name: a sorted model is flat without grouping\n * and a tree with it.\n *\n * `unchanged` means the stage's model is identical to the last one sent for\n * this dataset (its memoized inputs did not change); the main thread keeps\n * its previous result and skips the rebuild entirely.\n */\nexport type TableWorkerStagePayload =\n  | { kind: 'flat'; indices: Uint32Array }\n  | { kind: 'tree'; children: Array<TableWorkerRowNode> }\n  | { kind: 'unchanged' }\n\nexport type TableWorkerRequest<TData extends RowData = any> =\n  | {\n      type: 'data'\n      dataVersion: number\n      data: Array<TData>\n    }\n  | {\n      type: 'process'\n      requestId: number\n      dataVersion: number\n      /** The stages the main thread has worker-backed row models for. */\n      stages: Array<TableWorkerStage>\n      /** Serializable state slices (union of the stages' deps). */\n      state: Record<string, unknown>\n    }\n\nexport interface TableWorkerResult {\n  type: 'result'\n  requestId: number\n  dataVersion: number\n  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload }\n  computeMs: number\n}\n\nexport type TableWorkerResponse = TableWorkerResult\n\n/**\n * The state slice added by `workerRowModelsFeature`. `version` bumps when a\n * worker result lands (driving re-renders through the normal state path);\n * `isPending` is true while a request is in flight. The timing fields expose\n * the last result's worker compute time and full round trip for devtools and\n * debugging.\n */\nexport interface TableState_WorkerRowModels {\n  workerRowModels: {\n    version: number\n    isPending: boolean\n    lastComputeMs?: number\n    lastRoundTripMs?: number\n  }\n}\n"],"mappings":";;;;;;AAOA,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;AACF;;;;;;AASA,MAAa,4BAGT;CACF,UAAU,CAAC,iBAAiB,cAAc;CAC1C,SAAS,CAAC,UAAU;CACpB,QAAQ,CAAC,SAAS;CAClB,UAAU,CAAC,UAAU;AACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/table-core",
-  "version": "9.0.0-beta.5",
+  "version": "9.0.0-beta.51",
   "description": "Headless UI for building powerful tables & datagrids for TS/JS.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,6 +35,10 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./experimental-worker-plugin": {
+      "import": "./dist/experimental-worker-plugin.js",
+      "require": "./dist/experimental-worker-plugin.cjs"
+    },
     "./flex-render": {
       "import": "./dist/flex-render.js",
       "require": "./dist/flex-render.cjs"
@@ -55,7 +59,7 @@
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=16"
+    "node": ">=20"
   },
   "files": [
     "dist/",
@@ -69,10 +73,11 @@
     "clean": "rimraf ./build && rimraf ./dist",
     "lint:fix": "eslint ./src --fix",
     "test:eslint": "eslint ./src",
+    "test:coverage": "vitest run --coverage",
     "test:lib": "vitest",
     "test:lib:dev": "pnpm test:lib --watch",
     "test:types": "tsc && tsc -p tests/tsconfig.declaration-emit.json",
     "test:build": "publint --strict",
-    "build": "tsdown"
+    "build": "tsdown && node ../../scripts/rewrite-table-core-dts.mjs"
   }
 }

package/skills/aggregation/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: aggregation
+description: >
+  Aggregate TanStack Table columns independently of grouping, including grand totals, caller-selected row totals, multiple keyed aggregations, custom context-based definitions, grouped merges, manual values, and worker constraints.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.51',
+  }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/guide/aggregation.md'
+  - 'TanStack/table:docs/framework/react/guide/aggregation.md'
+  - 'TanStack/table:packages/table-core/src/features/row-aggregation'
+  - 'TanStack/table:examples/react/aggregation'
+  - 'TanStack/table:examples/react/grouped-aggregation'
+---
+
+This skill builds on `core` and `table-features`. Aggregation is independent
+from grouping: use it alone for totals, or combine it with the `grouping` skill
+for synthetic grouped rows.
+
+## Setup
+
+<!-- skill-snippet:check -->
+
+```ts
+import {
+  rowAggregationFeature,
+  aggregationFn_mean,
+  aggregationFn_sum,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  rowAggregationFeature,
+  aggregationFns: {
+    mean: aggregationFn_mean,
+    sum: aggregationFn_sum,
+  },
+})
+```
+
+## Core Patterns
+
+### Grand total and selected row scopes
+
+```ts
+const grandTotal = salaryColumn.getAggregationValue()
+const filteredTotal = salaryColumn.getAggregationValue({
+  rows: table.getFilteredRowModel().rows,
+})
+const childTotal = salaryColumn.getAggregationValue({
+  rows: table.getCoreRowModel().rows,
+  maxDepth: 1,
+})
+```
+
+The default uses the pre-grouped row model. Explicit rows can come from any row
+model or caller-selected subset. `maxAggregationDepth` defaults to `0`, which
+selects the supplied roots; `1` selects direct sub-rows, and `Infinity` selects
+terminal rows. Branches that end early contribute their deepest available row.
+Default calls are cached; explicit-row calls intentionally are not because array
+identity and contents are caller-owned. `table.getMaxSubRowDepth()` returns the
+deepest structural depth in the core row model.
+
+### Multiple aggregations
+
+```ts
+columnHelper.accessor('salary', {
+  aggregationFn: ['mean', { id: 'range', aggregationFn: 'extent' }],
+})
+
+const value = salaryColumn.getAggregationValue<{
+  mean: number
+  range: [number, number]
+}>()
+```
+
+A scalar option returns a scalar. An array returns a keyed object. Named
+functions use their registry name; descriptors provide a stable `id`, which is
+required for inline definitions in an array.
+
+### Custom definitions
+
+```ts
+const weightedMean = constructAggregationFn({
+  aggregate: ({ rows, getValue }) => {
+    const total = rows.reduce((sum, row) => sum + Number(getValue(row)), 0)
+    return rows.length ? total / rows.length : undefined
+  },
+})
+```
+
+The context provides depth-selected `rows`, `maxDepth`, `getValue`, `column`,
+`columnId`, `table`, and optional grouped-only `groupingRow` and `subRows`.
+Every aggregation configured on a column receives the same row frontier. Add
+`merge({ subRowResults, subRows, ...context })` when nested groups can more
+efficiently combine already-computed sub-row results; otherwise the engine calls
+`aggregate` with both row sets. `subRowResults[i]` corresponds to `subRows[i]`.
+
+### Manual or remote values
+
+Set a column definition's `getAggregationValue(context)` to return `{ value }`
+for requests handled by a server or another execution environment. Returning
+`undefined` falls back to the local definition. `manualAggregation: true`
+disables that local fallback.
+
+## Common Mistakes
+
+### [HIGH] Adding grouping for a grand total
+
+Wrong: registering `columnGroupingFeature` solely to total a column.
+
+Correct: register `rowAggregationFeature` and call
+`column.getAggregationValue()`. Grouping is only required for grouped rows.
+
+### [HIGH] Passing a scope label and rows
+
+There is no scope option. Call `getAggregationValue()` for the cached default,
+or pass a single options object containing rows from the desired row model and
+`maxDepth` when the desired frontier is below those rows.
+
+### [HIGH] Reusing the legacy callable signature
+
+Wrong: `(columnId, leafRows, childRows) => result`.
+
+Correct: `constructAggregationFn({ aggregate: ({ rows, subRows, getValue }) => result })`.
+
+### [MEDIUM] Assuming arbitrary totals run in the worker
+
+The experimental worker computes grouped row-model aggregates. Public
+`getAggregationValue(options?)` totals execute on the main thread, and custom
+grouped results sent by the worker must be structured-cloneable.
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/row-aggregation/` and the
+Aggregation Guide. Use `Column_Aggregation`, `AggregationFnDef`,
+`AggregationContext`, and `AggregationResult` for the typed public surface.

package/skills/api-not-found/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: api-not-found
+description: >
+  Diagnose missing TanStack Table v9 exports, options, state slices, and instance methods. Load before inventing an API when code sees a type error, undefined feature method, absent object key, adapter mismatch, or v8-shaped example.
+metadata:
+  type: sub-skill
+  library: '@tanstack/table-core'
+  library_version: '9.0.0-beta.51'
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:packages/table-core/src/index.ts'
+  - 'TanStack/table:packages/table-core/src/types/TableFeatures.ts'
+  - 'TanStack/table:docs/framework/react/guide/migrating.md'
+---
+
+This skill builds on `core` and `table-features`. Treat the installed package—not remembered docs—as exact API truth.
+
+## Setup
+
+```ts
+import { readFile } from 'node:fs/promises'
+
+const packageJson = JSON.parse(
+  await readFile('node_modules/@tanstack/table-core/package.json', 'utf8'),
+)
+const entrypoint = await readFile(
+  'node_modules/@tanstack/table-core/src/index.ts',
+  'utf8',
+)
+console.log(packageJson.version, entrypoint.includes('rowSortingFeature'))
+```
+
+## Core Patterns
+
+### Trace an export to source
+
+```sh
+rg "export .*rowSortingFeature|rowSortingFeature" node_modules/@tanstack/table-core/src
+```
+
+For an adapter API, start at `node_modules/@tanstack/<framework>-table/src/index.ts`.
+
+### Check feature gating before replacement
+
+```ts
+const features = tableFeatures({ rowSortingFeature })
+```
+
+If the export exists but the instance API does not, inspect `TableFeatures.ts` and the table's registry.
+
+## Common Mistakes
+
+### [CRITICAL] Substituting a remembered v8 API
+
+Wrong:
+
+```ts
+const options = { getSortedRowModel: getSortedRowModel() }
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+})
+```
+
+V9 moved row-model factories to named feature slots and renamed `get*` factories to `create*`.
+
+Source: `docs/framework/react/guide/migrating.md#row-model-factories`
+
+### [HIGH] Mistaking omitted feature for removal
+
+Wrong:
+
+```ts
+const features = tableFeatures({})
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({ columnVisibilityFeature })
+```
+
+Optional APIs and state are typed and installed from the concrete feature registry.
+
+Source: `packages/table-core/src/types/TableFeatures.ts`
+
+### [HIGH] Discovering methods through own keys
+
+Wrong:
+
+```ts
+const methods = Object.keys(row).filter((key) => key.startsWith('get'))
+```
+
+Correct:
+
+```ts
+const value = row.getValue('name')
+const prototype = Object.getPrototypeOf(row)
+```
+
+V9 shares many instance methods through prototypes, so spread, serialization, and `Object.keys` omit them.
+
+Source: `docs/framework/react/guide/migrating.md#instance-methods-must-be-called-on-their-instance`
+
+## API Discovery
+
+Use this order: installed `package.json` version, installed adapter `src/index.ts`, installed core `src/index.ts`, then the exported implementation or feature directory. If `src` is absent, inspect installed declarations for that exact version.

package/skills/client-vs-server/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: client-vs-server
+description: >
+  Choose client or server ownership for filtering, grouping, sorting, expanding, and pagination in TanStack Table v9. Load for manual* flags, mixed pipelines, server counts, or deciding which dataset each row-model stage receives.
+metadata:
+  type: sub-skill
+  library: '@tanstack/table-core'
+  library_version: '9.0.0-beta.51'
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/guide/row-models.md'
+  - 'TanStack/table:packages/table-core/src/core/row-models/coreRowModelsFeature.utils.ts'
+  - 'TanStack/table:examples/react/with-tanstack-query'
+---
+
+This skill builds on `core` and `table-features`. Read them first for the model pipeline and plugin slots.
+
+## Setup
+
+```ts
+import {
+  rowPaginationFeature,
+  rowSortingFeature,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  rowSortingFeature,
+  rowPaginationFeature,
+})
+export const serverOptions = {
+  manualSorting: true,
+  manualPagination: true,
+  rowCount: 12_450,
+} as const
+```
+
+## Core Patterns
+
+### Client owns the complete pipeline
+
+```ts
+const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
+})
+```
+
+Pass the full client dataset so each stage can process all rows.
+
+### Server owns processing
+
+```ts
+const options = {
+  data: serverPage.rows,
+  manualFiltering: true,
+  manualSorting: true,
+  manualPagination: true,
+  rowCount: serverPage.total,
+}
+```
+
+Put controlled filter, sorting, and pagination state into the request/query key.
+
+## Common Mistakes
+
+### [CRITICAL] Treating manual flags as requests
+
+Wrong:
+
+```ts
+const options = { manualSorting: true, data: unsortedRows }
+```
+
+Correct:
+
+```ts
+const sortedPage = await fetchPage({ sorting })
+const options = { manualSorting: true, data: sortedPage.rows }
+```
+
+`manualSorting` only bypasses client sorting; it never calls a backend.
+
+Source: `packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts`
+
+### [HIGH] Expecting manual pagination to slice
+
+Wrong:
+
+```ts
+const options = { data: allRows, manualPagination: true }
+```
+
+Correct:
+
+```ts
+const page = await fetchPage({ pageIndex, pageSize })
+const options = {
+  data: page.rows,
+  manualPagination: true,
+  rowCount: page.rowCount,
+}
+```
+
+Manual pagination assumes `data` already represents the intended page. Pass the stable page result directly. If the application deliberately performs custom local slicing instead, derive it with the framework's memo/computed primitive and keep the reference stable until its actual inputs change.
+
+Source: `docs/framework/react/guide/pagination.md#manual-server-side-pagination`
+
+### [HIGH] Sorting only the loaded page accidentally
+
+Wrong:
+
+```ts
+const options = {
+  data: serverPage.rows,
+  manualPagination: true,
+  manualSorting: false,
+}
+```
+
+Correct:
+
+```ts
+const options = {
+  data: serverPage.rows,
+  manualPagination: true,
+  manualSorting: true,
+}
+```
+
+Client sorting can see only loaded rows, so it cannot produce database-wide order.
+
+Source: `docs/guide/row-models.md`
+
+### [HIGH] Recreating processed data or columns inline
+
+Wrong:
+
+```ts
+const options = {
+  data: allRows.filter(matchesFilters).slice(pageStart, pageEnd),
+  columns: makeColumns(),
+}
+```
+
+Correct:
+
+```ts
+const processedRows = pageResult.rows
+const columns = sharedColumns
+const options = { data: processedRows, columns }
+```
+
+`data` and `columns` are model inputs. Keep both references stable between meaningful changes with module constants, state, or the adapter's memo/computed primitive; otherwise Table repeatedly invalidates row and column models and some adapters can enter render loops. “Manual” describes processing ownership, not permission to derive new arrays inside table options.
+
+Source: `docs/guide/data.md`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/core/row-models/coreRowModelsFeature.utils.ts` for pipeline order and each feature's `.types.ts` for its `manual*` contract.

package/skills/column-faceting/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: column-faceting
+description: >
+  Build faceted filter UIs with columnFacetingFeature, facetedRowModel, facetedUniqueValues, and facetedMinMaxValues. Load for facet counts, numeric ranges, own-filter exclusion, or server-page facet completeness.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.51',
+  }
+requires: ['core', 'table-features', 'column-filtering']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/column-faceting.md'
+  - 'TanStack/table:packages/table-core/src/features/column-faceting'
+  - 'TanStack/table:examples/react/filters-faceted'
+---
+
+This skill builds on `core`, `table-features`, and `column-filtering`. Faceting derives filter choices; it does not render controls.
+
+## Setup
+
+```ts
+import {
+  columnFacetingFeature,
+  columnFilteringFeature,
+  createFacetedMinMaxValues,
+  createFacetedRowModel,
+  createFacetedUniqueValues,
+  createFilteredRowModel,
+  filterFn_includesString,
+  filterFn_inNumberRange,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: {
+    includesString: filterFn_includesString,
+    inNumberRange: filterFn_inNumberRange,
+  },
+  columnFacetingFeature,
+  facetedRowModel: createFacetedRowModel(),
+  facetedUniqueValues: createFacetedUniqueValues(),
+  facetedMinMaxValues: createFacetedMinMaxValues(),
+})
+```
+
+## Core Patterns
+
+```ts
+const counts = table.getColumn('status')?.getFacetedUniqueValues() ?? new Map()
+const range = table.getColumn('age')?.getFacetedMinMaxValues()
+```
+
+Use unique values for discrete controls and min/max only for numeric ranges.
+The filtered model makes facets respond to the table's other active filters.
+Register individually imported built-ins under their conventional keys so
+columns can reference them by string name; a column may instead receive a
+filter function directly without registering it. The full `filterFns` registry
+object still works but bundles every built-in.
+
+## Common Mistakes
+
+### [HIGH] Registering APIs without model slots
+
+Wrong: `tableFeatures({ columnFilteringFeature, columnFacetingFeature })`
+
+Correct: `tableFeatures({ columnFilteringFeature, columnFacetingFeature, facetedRowModel: createFacetedRowModel(), facetedUniqueValues: createFacetedUniqueValues() })`
+
+Each faceting getter needs its matching factory slot.
+
+Source: `packages/table-core/src/features/column-faceting/columnFacetingFeature.ts`
+
+### [MEDIUM] Expecting facet to apply itself
+
+Wrong: `column.getFacetedUniqueValues().get(activeValue) === 0`
+
+Correct: `column.getFacetedUniqueValues().get(activeValue) ?? 0`
+
+A column facet intentionally excludes that column's own filter while applying other filters.
+
+Source: `docs/framework/react/guide/column-faceting.md`
+
+### [HIGH] Treating page facets as global
+
+Wrong: `const globalCounts = column.getFacetedUniqueValues()`
+
+Correct: `const globalCounts = await fetchFacetCounts(activeFilters)`
+
+With server pagination, client faceting sees only loaded data.
+
+Source: `docs/framework/react/guide/column-faceting.md#custom-server-side-faceting`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/features/column-faceting/` for exact getters and factory return types.