@tanstack/table-core 9.0.0-beta.37 → 9.0.0-beta.42

package/skills/sorting/SKILL.md

@@ -1,344 +1,80 @@
 ---
 name: sorting
 description: >
-  Sort rows in TanStack Table v9 with the `sortedRowModel` stage. Covers
-  `rowSortingFeature` + `createSortedRowModel()` (registered on `features`), 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.42',
+  }
+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,
+  rowSortingFeature,
   sortFns,
-  createColumnHelper,
-  constructTable,
+  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({
+export const features = tableFeatures({
   rowSortingFeature,
   sortedRowModel: createSortedRowModel(),
   sortFns,
 })
-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,
-  columns,
-  data,
-  initialState: { sorting: [] satisfies SortingState },
-})
-
-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
-
 ```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`
-
-```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 }),
-  // omit sortedRowModel from features — 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
-```
-
-Correct:
-
-```tsx
-import { sortFns, createSortedRowModel } from '@tanstack/react-table'
-
-columnHelper.accessor('firstName', {
-  sortFn: 'alphanumeric',
-})
-
-const features = tableFeatures({
-  rowSortingFeature,
-  sortedRowModel: createSortedRowModel(),
-  sortFns: {
-    ...sortFns,
-    myCustom: (a, b, id) => a.original[id] - b.original[id],
-  },
-})
-
-const table = useTable({ features, columns, data })
-```
-
-v9 renamed `columnDef.sortingFn → sortFn`, the fn registry slot `sortingFns → sortFns` (now registered on `features`), 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.
-
-Source: packages/table-core/src/features/row-sorting/rowSortingFeature.utils.ts
-
-### [MEDIUM] Expecting `sortUndefined: 'first' | 'last'` to work in v8
+### [CRITICAL] Expecting manual mode to reorder
 
-Wrong:
+Wrong: `const options = { data: unsortedRows, manualSorting: true }`
 
-```tsx
-// agent assumes numeric and literal forms are interchangeable
-{ accessorKey: 'lastName', sortUndefined: -1 } // ascending-first, descending-LAST
-```
-
-Correct:
-
-```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
-
-### [MEDIUM] Custom `sortFn` factors `desc` in itself
-
-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:
+Correct: `const options = { data: serverSortedRows, manualSorting: true }`
 
-```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.
+Manual sorting bypasses `sortedRowModel` and trusts incoming order.
 
-Source: examples/react/filters-fuzzy/src/main.tsx
+Source: `packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts`
 
-### [MEDIUM] `getCanSort` returns false for display columns under `manualSorting`
+### [HIGH] Reversing inside the comparator
 
-Wrong:
+Wrong: `const newest: SortFn<any, any> = (a, b, id) => b.getValue<number>(id) - a.getValue<number>(id)`
 
-```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: `const numeric: SortFn<any, any> = (a, b, id) => a.getValue<number>(id) - b.getValue<number>(id)`
 
-Correct:
+Return ascending comparison only; Table reverses it when sorting is descending.
 
-```ts
-columnHelper.display({
-  id: 'computed',
-  header: 'Computed',
-  enableSorting: true, // force-enable for manualSorting
-  cell: (info) => info.row.original.x + info.row.original.y,
-})
-```
+Source: `docs/framework/react/guide/sorting.md#custom-sorting-functions`
 
-`getCanSort` checks for `accessorKey`/`accessorFn` even under `manualSorting`. Force it on display columns via `enableSorting: true` (and let the server sort).
+### [MEDIUM] Leaving ambiguous sort policy
 
-Source: https://github.com/TanStack/table/issues/4136
+Wrong: `const options = { enableSortingRemoval: true }`
 
-### [CRITICAL] Reimplementing what built-in APIs provide
+Correct: `const options = { enableSortingRemoval: false }; const rankColumn = { sortUndefined: 'last' as const }`
 
-Wrong:
-
-```ts
-const [sorting, setSorting] = useState([])
-const sortedData = useMemo(
-  () => [...data].sort(/* …custom… */),
-  [data, sorting],
-)
-// then uses sortedData directly, bypassing the table
-```
-
-Correct:
-
-```ts
-const features = tableFeatures({
-  rowSortingFeature,
-  sortedRowModel: createSortedRowModel(),
-  sortFns,
-})
-const table = useTable({ features, 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,153 @@
+---
+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.42'
+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 {
+  aggregationFns,
+  columnGroupingFeature,
+  createFilteredRowModel,
+  createSortedRowModel,
+  columnFilteringFeature,
+  filterFns,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from '@tanstack/table-core'
+
+export const features = tableFeatures({
+  columnFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns,
+  columnGroupingFeature,
+  aggregationFns,
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns,
+})
+```
+
+## 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,
+  rowSortingFeature,
+  sortFns,
+  columnGroupingFeature,
+  aggregationFns,
+})
+```
+
+`filterFns`, `sortFns`, and `aggregationFns` are feature slots, not table
+options. They respectively require `columnFilteringFeature`,
+`rowSortingFeature`, and `columnGroupingFeature`. A registered key can be used
+as a typed string name; 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.42'
+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.

package/src/core/headers/buildHeaderGroups.ts

@@ -21,7 +21,7 @@ export function buildHeaderGroups<
   allColumns: Array<Column<TFeatures, TData, TValue>>,
   columnsToGroup: Array<Column<TFeatures, TData, TValue>>,
   table: Table_Internal<TFeatures, TData>,
-  headerFamily?: 'center' | 'left' | 'right',
+  headerFamily?: 'center' | 'start' | 'end',
 ) {
   // Find the max depth of the columns:
   // build the leaf column row