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

package/skills/sorting/SKILL.md

@@ -1,344 +1,86 @@
 ---
 name: sorting
 description: >
-  Sort rows in TanStack Table v9 with the `sortedRowModel` stage. Covers
-  `rowSortingFeature` + `createSortedRowModel(sortFns)`, the built-in `sortFns`
-  registry (renamed from v8 `sortingFns`), `state.sorting` (SortingState =
-  Array<{ id, desc }>), `onSortingChange`, `columnDef.sortFn`
-  (string | function | 'auto'), `sortDescFirst`, `sortUndefined`
-  ('first'|'last'|-1|1|false), `invertSorting`, `enableMultiSort`,
-  `maxMultiSortColCount`, `isMultiSortEvent`, `table.setSorting` /
-  `resetSorting`, `column.getToggleSortingHandler` /
-  `getNextSortingOrder` / `clearSorting` / `getCanSort` / `getCanMultiSort`,
-  `manualSorting` for server-side, and fuzzy `compareItems` pairing.
-type: core
-library: tanstack-table
-library_version: '9.0.0-alpha.48'
-requires:
-  - state-management
-  - customizing-feature-behavior
+  Sort with rowSortingFeature, sortedRowModel, sortFns, multi-sort and removal options, sortUndefined, and manualSorting. Load for comparator direction, incoming server order, or product-specific sorting cycles.
+metadata:
+  {
+    type: sub-skill,
+    library: '@tanstack/table-core',
+    library_version: '9.0.0-beta.51',
+  }
+requires: ['core', 'table-features', 'client-vs-server']
 sources:
-  - TanStack/table:docs/guide/sorting.md
-  - TanStack/table:packages/table-core/src/fns/sortFns.ts
-  - TanStack/table:packages/table-core/src/features/row-sorting/createSortedRowModel.ts
-  - TanStack/table:packages/table-core/src/features/row-sorting/rowSortingFeature.utils.ts
-  - TanStack/table:examples/react/sorting/src/main.tsx
+  - 'TanStack/table:docs/framework/react/guide/sorting.md'
+  - 'TanStack/table:packages/table-core/src/features/row-sorting'
+  - 'TanStack/table:examples/react/sorting'
 ---
 
-This skill builds on `tanstack-table/state-management` and `tanstack-table/customizing-feature-behavior`. Read those first for the atom model and `sortFn` overrides.
+This skill builds on `core`, `table-features`, and `client-vs-server`. Sorting state describes order; client processing requires a sorted model and server processing requires sorted input.
 
 ## Setup
 
 ```ts
 import {
-  tableFeatures,
-  rowSortingFeature,
   createSortedRowModel,
-  sortFns,
-  createColumnHelper,
-  constructTable,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  sortFn_text,
+  tableFeatures,
 } from '@tanstack/table-core'
-import type { SortingState } from '@tanstack/table-core'
-
-type Person = {
-  firstName: string
-  lastName: string
-  age: number
-  status: 'single' | 'complicated' | 'relationship'
-}
 
-const features = tableFeatures({ rowSortingFeature })
-const columnHelper = createColumnHelper<typeof features, Person>()
-
-const columns = columnHelper.columns([
-  columnHelper.accessor('firstName', { sortFn: 'alphanumeric' }),
-  columnHelper.accessor('lastName', {
-    sortUndefined: 'last',
-    sortDescFirst: false,
-  }),
-  columnHelper.accessor('age', { sortFn: 'basic' }),
-])
-
-const table = constructTable({
-  features,
-  rowModels: {
-    sortedRowModel: createSortedRowModel(sortFns),
-  },
-  columns,
-  data,
-  initialState: { sorting: [] satisfies SortingState },
+export const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric, text: sortFn_text },
 })
-
-table.setSorting([{ id: 'age', desc: true }])
-```
-
-## Core Patterns
-
-### Clickable header sorting with multi-sort on Shift+click
-
-```tsx
-// From examples/react/sorting/src/main.tsx
-{
-  headerGroup.headers.map((header) => (
-    <th
-      key={header.id}
-      onClick={header.column.getToggleSortingHandler()}
-      style={{ cursor: header.column.getCanSort() ? 'pointer' : 'default' }}
-    >
-      <table.FlexRender header={header} />
-      {{ asc: ' 🔼', desc: ' 🔽' }[header.column.getIsSorted() as string] ??
-        null}
-    </th>
-  ))
-}
 ```
 
-`getToggleSortingHandler` already handles multi-sort when the user holds Shift (configurable via `isMultiSortEvent`).
-
-### Custom `sortFn` for an enum
+Import individual `sortFn_*` built-ins and register only those your columns
+reference by string name or that `sortFn: 'auto'` should resolve for your data
+types. The full `sortFns` registry object still works but bundles every
+built-in; numeric columns fall back to a basic comparator without registration.
 
-```ts
-// From examples/react/sorting/src/main.tsx
-const sortStatusFn: SortFn<typeof features, Person> = (
-  rowA,
-  rowB,
-  _columnId,
-) => {
-  const statusOrder = ['single', 'complicated', 'relationship']
-  return (
-    statusOrder.indexOf(rowA.original.status) -
-    statusOrder.indexOf(rowB.original.status)
-  )
-}
-
-columnHelper.accessor('status', { sortFn: sortStatusFn })
-```
-
-Always return an ascending-order comparison. The row model multiplies by `-1` for descending and again for `invertSorting`.
-
-### Direction control with `sortUndefined` and `invertSorting`
+## Core Patterns
 
 ```ts
-columnHelper.accessor('rank', {
-  invertSorting: true, // rank 1 above rank 2 even when "descending"
-})
-
-columnHelper.accessor('lastName', {
-  sortUndefined: 'last', // ABSOLUTE: end regardless of asc/desc
-  sortDescFirst: false,
-})
+const options = { enableSortingRemoval: false, enableMultiSort: true }
+const numericColumn = { sortUndefined: 'last' as const }
 ```
 
-`sortUndefined` literals (`'first'`, `'last'`) are absolute. Numeric (`-1`, `1`) flips with `desc`.
-
-### Server-side sorting
-
-```tsx
-const [sorting, setSorting] = useState<SortingState>([])
-const { data } = useQuery({
-  queryKey: ['rows', sorting],
-  queryFn: () =>
-    fetch('/api/rows?sort=' + serialize(sorting)).then((r) => r.json()),
-})
-
-const table = useTable({
-  features: tableFeatures({ rowSortingFeature }),
-  rowModels: {}, // omit sortedRowModel — server sorts
-  columns,
-  data,
-  manualSorting: true,
-  state: { sorting },
-  onSortingChange: setSorting,
-})
-```
+Configure sort cycles and undefined placement to match the product rather than relying on implicit defaults.
 
 ## Common Mistakes
 
-### [HIGH] Using v8 `sortingFn` / `sortingFns` names
-
-Wrong:
-
-```tsx
-{
-  accessorKey: 'fullName',
-  sortingFn: 'alphanumeric', // v8 name — falls through to sortFn_basic
-}
-// useTable({ sortingFns: { ...sortingFns, myFn } }) // v8 option name
-```
+### [CRITICAL] Expecting manual mode to reorder
 
-Correct:
+Wrong: `const options = { data: unsortedRows, manualSorting: true }`
 
-```tsx
-import { sortFns, createSortedRowModel } from '@tanstack/react-table'
+Correct: `const options = { data: serverSortedRows, manualSorting: true }`
 
-columnHelper.accessor('firstName', {
-  sortFn: 'alphanumeric',
-})
+Manual sorting bypasses `sortedRowModel` and trusts incoming order.
 
-const table = useTable({
-  features: tableFeatures({ rowSortingFeature }),
-  rowModels: {
-    sortedRowModel: createSortedRowModel({
-      ...sortFns,
-      myCustom: (a, b, id) => a.original[id] - b.original[id],
-    }),
-  },
-  columns,
-  data,
-})
-```
+Source: `packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts`
 
-v9 renamed `columnDef.sortingFn → sortFn`, `tableOptions.sortingFns → sortFns`, exported registry `sortingFns → sortFns`. The new column option defaults to `'auto'` and falls back to `sortFn_basic` when lookup misses — wrong names sort wrong, silently.
+### [HIGH] Reversing inside the comparator
 
-Source: packages/table-core/src/features/row-sorting/rowSortingFeature.utils.ts
+Wrong: `const newest: SortFn<any, any> = (a, b, id) => b.getValue<number>(id) - a.getValue<number>(id)`
 
-### [MEDIUM] Expecting `sortUndefined: 'first' | 'last'` to work in v8
+Correct: `const numeric: SortFn<any, any> = (a, b, id) => a.getValue<number>(id) - b.getValue<number>(id)`
 
-Wrong:
+Return ascending comparison only; Table reverses it when sorting is descending.
 
-```tsx
-// agent assumes numeric and literal forms are interchangeable
-{ accessorKey: 'lastName', sortUndefined: -1 } // ascending-first, descending-LAST
-```
+Source: `docs/framework/react/guide/sorting.md#custom-sorting-functions`
 
-Correct:
+### [MEDIUM] Leaving ambiguous sort policy
 
-```tsx
-// From examples/react/sorting/src/main.tsx
-columnHelper.accessor((row) => row.lastName, {
-  id: 'lastName',
-  sortUndefined: 'last', // ABSOLUTE: always at end regardless of asc/desc
-  sortDescFirst: false,
-})
-```
-
-v8 only had `false | -1 | 1`. v9 added `'first'` / `'last'`. Numeric flips with `desc`; literals are absolute.
-
-Source: packages/table-core/src/features/row-sorting/createSortedRowModel.ts
+Wrong: `const options = { enableSortingRemoval: true }`
 
-### [MEDIUM] Custom `sortFn` factors `desc` in itself
+Correct: `const options = { enableSortingRemoval: false }; const rankColumn = { sortUndefined: 'last' as const }`
 
-Wrong:
-
-```tsx
-// takes sort direction into account, breaks the toggle
-const customSort: SortFn<any, any> = (a, b, id, desc) => {
-  // desc isn't even a parameter — agents try to detect via state
-  const cmp = a.original[id] - b.original[id]
-  return desc ? -cmp : cmp
-}
-```
-
-Correct:
-
-```tsx
-// From examples/react/sorting/src/main.tsx
-// Always return ascending; the row model handles desc & invertSorting.
-const sortStatusFn: SortFn<any, any> = (rowA, rowB, _columnId) => {
-  const statusOrder = ['single', 'complicated', 'relationship']
-  return (
-    statusOrder.indexOf(rowA.original.status) -
-    statusOrder.indexOf(rowB.original.status)
-  )
-}
-```
-
-From the docs guide: "The comparison function does not need to take whether or not the column is in descending or ascending order into account. The row models will take care of that logic." Doubly-flipping yields broken toggles.
-
-Source: packages/table-core/src/features/row-sorting/createSortedRowModel.ts
-
-### [MEDIUM] Fuzzy filter without a fuzzy-aware `sortFn`
-
-Wrong:
-
-```ts
-columnHelper.accessor('fullName', {
-  filterFn: 'fuzzy',
-  // BUG: rows sort alphabetically, not by match rank
-})
-```
-
-Correct:
-
-```ts
-import { compareItems } from '@tanstack/match-sorter-utils'
-
-const fuzzySort: SortFn<typeof features, 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
-}
-
-columnHelper.accessor('fullName', { filterFn: 'fuzzy', sortFn: fuzzySort })
-```
-
-The fuzzy filter writes `{ itemRank }` into `row.columnFiltersMeta[columnId]` via `addMeta`. Without a sortFn that reads it, results sort alphabetically and defeat the fuzzy ranking.
-
-Source: examples/react/filters-fuzzy/src/main.tsx
-
-### [MEDIUM] `getCanSort` returns false for display columns under `manualSorting`
-
-Wrong:
-
-```ts
-// getCanSort() returns false even though manualSorting is true
-const table = useTable({
-  manualSorting: true,
-  columns: [
-    { id: 'computed', header: 'Computed', cell: (info) => row.x + row.y },
-  ],
-})
-```
-
-Correct:
-
-```ts
-columnHelper.display({
-  id: 'computed',
-  header: 'Computed',
-  enableSorting: true, // force-enable for manualSorting
-  cell: (info) => info.row.original.x + info.row.original.y,
-})
-```
-
-`getCanSort` checks for `accessorKey`/`accessorFn` even under `manualSorting`. Force it on display columns via `enableSorting: true` (and let the server sort).
-
-Source: https://github.com/TanStack/table/issues/4136
-
-### [CRITICAL] Reimplementing what built-in APIs provide
-
-Wrong:
-
-```ts
-const [sorting, setSorting] = useState([])
-const sortedData = useMemo(
-  () => [...data].sort(/* …custom… */),
-  [data, sorting],
-)
-// then uses sortedData directly, bypassing the table
-```
-
-Correct:
-
-```ts
-const table = useTable({
-  features: tableFeatures({ rowSortingFeature }),
-  rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-  columns,
-  data,
-})
-// table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
-```
+Undefined placement and removal cycles can differ from expected product behavior unless configured.
 
-Source: maintainer interview (Phase 4, 2026-05-17)
+Source: `packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts`
 
-## See also
+## API Discovery
 
-- `tanstack-table/customizing-feature-behavior` — `sortFn` authoring + `addMeta` chain
-- `tanstack-table/filtering` — fuzzy filter pattern that pairs with `fuzzySort`
-- `tanstack-table/state-management` — `manualSorting` + server-side state ownership
+Inspect `node_modules/@tanstack/table-core/src/features/row-sorting/` and `src/fns/sortFns.ts` for current names and comparator contracts.

package/skills/table-features/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: table-features
+description: >
+  Register TanStack Table v9 tableFeatures, feature plugins, create*RowModel factories, and function registries in prerequisite order. Load when an option, state slice, or instance API is missing, or when choosing explicit features versus stockFeatures.
+metadata:
+  type: sub-skill
+  library: '@tanstack/table-core'
+  library_version: '9.0.0-beta.51'
+requires: ['core']
+sources:
+  - 'TanStack/table:docs/guide/row-models.md'
+  - 'TanStack/table:packages/table-core/src/types/TableFeatures.ts'
+  - 'TanStack/table:packages/table-core/src/features/stockFeatures.ts'
+  - 'TanStack/table:packages/table-core/src/core/table/constructTable.ts'
+---
+
+This skill builds on `core`. Read it first for the headless model and stable inputs.
+
+## Setup
+
+<!-- skill-snippet:check -->
+
+```ts
+import {
+  rowAggregationFeature,
+  aggregationFn_sum,
+  columnGroupingFeature,
+  createFilteredRowModel,
+  createSortedRowModel,
+  columnFilteringFeature,
+  filterFn_includesString,
+  rowSortingFeature,
+  sortFn_alphanumeric,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { includesString: filterFn_includesString },
+  rowAggregationFeature,
+  columnGroupingFeature,
+  aggregationFns: { sum: aggregationFn_sum },
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric },
+})
+```
+
+## Core Patterns
+
+### Register feature before its dependent slot
+
+```ts
+const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+})
+```
+
+`tableFeatures` checks slot prerequisites and its inferred type gates APIs throughout the table.
+
+### Register named function slots with their features
+
+```ts
+const features = tableFeatures({
+  columnFilteringFeature,
+  filterFns: { includesString: filterFn_includesString },
+  rowSortingFeature,
+  sortFns: { alphanumeric: sortFn_alphanumeric },
+  rowAggregationFeature,
+  columnGroupingFeature,
+  aggregationFns: { sum: aggregationFn_sum },
+})
+```
+
+`filterFns`, `sortFns`, and `aggregationFns` are feature slots, not table
+options. They respectively require `columnFilteringFeature`,
+`rowSortingFeature`, and `rowAggregationFeature`. Import individual built-ins
+(`filterFn_*`, `sortFn_*`, `aggregationFn_*`) and register them under their
+conventional keys; the full registry objects (`filterFns`, `sortFns`,
+`aggregationFns` exports) still work but bundle every built-in. A registered
+key can be used as a typed string name, and `'auto'` resolves only registered
+functions; pass a function directly when no registry name is needed.
+
+### Prefer explicit features
+
+```ts
+const features = tableFeatures({ columnFilteringFeature })
+```
+
+Use `stockFeatures` only for deliberate kitchen-sink or temporary migration behavior.
+
+## Common Mistakes
+
+### [CRITICAL] Calling an unregistered feature API
+
+Wrong:
+
+```ts
+const features = tableFeatures({})
+table.setSorting([{ id: 'name', desc: false }])
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({ rowSortingFeature })
+```
+
+Optional feature state and APIs are installed only when their feature is registered.
+
+Source: `packages/table-core/src/core/table/constructTable.ts`
+
+### [HIGH] Omitting a slot prerequisite
+
+Wrong:
+
+```ts
+const features = tableFeatures({ sortedRowModel: createSortedRowModel() })
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+})
+```
+
+The sorted model slot requires `rowSortingFeature`; the same rule applies to every mapped slot.
+
+Source: `packages/table-core/src/types/TableFeatures.ts#FeatureSlotPrereqs`
+
+### [MEDIUM] Shipping all features by default
+
+Wrong:
+
+```ts
+const features = stockFeatures
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+})
+```
+
+`stockFeatures` registers every stock plugin and processing slot, defeating v9's normal tree-shaking strategy.
+
+Source: `packages/table-core/src/features/stockFeatures.ts`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/types/TableFeatures.ts` for current slots and `FeatureSlotPrereqs`, and `src/features/stockFeatures.ts` for the stock inventory.

package/skills/typescript/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: typescript
+description: >
+  Preserve TanStack Table v9 inference with createColumnHelper, columns(), tableOptions, tableFeatures, and metaHelper. Load for ColumnDef errors, reusable tables, typed meta, named registries, or unnecessary manual feature generics.
+metadata:
+  type: sub-skill
+  library: '@tanstack/table-core'
+  library_version: '9.0.0-beta.51'
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/guide/helpers.md'
+  - 'TanStack/table:docs/guide/column-defs.md'
+  - 'TanStack/table:docs/guide/table-and-column-meta.md'
+  - 'TanStack/table:packages/table-core/src/helpers'
+---
+
+This skill builds on `core` and `table-features`. Let the feature object and helpers carry types through userland.
+
+## Setup
+
+```ts
+import {
+  createColumnHelper,
+  metaHelper,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+type Person = { id: string; age: number }
+type ColumnMeta = { align?: 'start' | 'end' }
+const features = tableFeatures({ columnMeta: metaHelper<ColumnMeta>() })
+const helper = createColumnHelper<typeof features, Person>()
+export const columns = helper.columns([
+  helper.accessor('age', { meta: { align: 'end' } }),
+])
+```
+
+## Core Patterns
+
+### Preserve heterogeneous accessor values
+
+```ts
+const columns = helper.columns([
+  helper.accessor('id', { header: 'ID' }),
+  helper.accessor('age', { header: 'Age' }),
+])
+```
+
+`columns()` preserves each accessor's `TValue` instead of widening the array.
+
+### Compose options through the helper
+
+```ts
+const defaults = tableOptions<typeof features, Person>({
+  defaultColumn: { meta: { align: 'start' } },
+})
+```
+
+Use `tableOptions` for reusable fragments; direct adapter options are enough for one-offs.
+
+## Common Mistakes
+
+### [HIGH] Erasing accessor value inference
+
+Wrong:
+
+```ts
+const columns: ColumnDef<typeof features, Person, unknown>[] = [
+  helper.accessor('age', {}),
+]
+```
+
+Correct:
+
+```ts
+const columns = helper.columns([helper.accessor('age', {})])
+```
+
+The broad annotation discards the accessor-specific `number` value type.
+
+Source: `docs/guide/helpers.md#createcolumnhelper`
+
+### [MEDIUM] Threading internal feature generics manually
+
+Wrong:
+
+```ts
+type Features = TableFeatures
+```
+
+Correct:
+
+```ts
+type Features = typeof features
+```
+
+The concrete registry is the source of feature-gated APIs and registry keys.
+
+Source: `packages/table-core/src/types/TableFeatures.ts`
+
+### [MEDIUM] Globally merging per-table meta
+
+Wrong:
+
+```ts
+declare module '@tanstack/table-core' {
+  interface ColumnMeta<TData, TValue> {
+    align?: string
+  }
+}
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({
+  columnMeta: metaHelper<{ align?: 'start' | 'end' }>(),
+})
+```
+
+V9 type-only feature slots keep meta types scoped to the table factory.
+
+Source: `docs/guide/table-and-column-meta.md`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/src/helpers/` and the signatures re-exported by `src/index.ts`; avoid copying deep internal generic signatures into application code.