@tanstack/table-core 9.0.0-alpha.47 → 9.0.0-alpha.49

package/skills/column-layout/references/subsystems.md

@@ -0,0 +1,220 @@
+# Column-layout subsystems — full API surface
+
+Detailed reference for the five UI-state-only column features extracted from `SKILL.md`. The SKILL keeps a 2-line summary table linking here; this file documents each subsystem in detail.
+
+## Visibility — `columnVisibilityFeature`
+
+State: `columnVisibility: Record<columnId, boolean>` — missing or `true` means visible.
+
+```tsx
+// Visibility toggle panel
+{
+  table.getAllLeafColumns().map((column) => (
+    <label key={column.id}>
+      <input
+        type="checkbox"
+        checked={column.getIsVisible()}
+        disabled={!column.getCanHide()}
+        onChange={column.getToggleVisibilityHandler()}
+      />
+      {column.id}
+    </label>
+  ))
+}
+
+// Body — use Visible variants, NOT getAllLeafColumns / getAllCells
+;<tbody>
+  {table.getRowModel().rows.map((row) => (
+    <tr key={row.id}>
+      {row.getVisibleCells().map((cell) => (
+        <td key={cell.id}>
+          <table.FlexRender cell={cell} />
+        </td>
+      ))}
+    </tr>
+  ))}
+</tbody>
+```
+
+## Ordering — `columnOrderingFeature`
+
+State: `columnOrder: string[]` of leaf column ids. Empty means definition order. **Scoped to UNPINNED columns** when pinning is active — pinned columns are sequenced inside `columnPinning.left/right`.
+
+```ts
+table.setColumnOrder(['firstName', 'lastName', 'age'])
+column.getIndex('center') // ← position
+column.getIsFirstColumn()
+column.getIsLastColumn()
+```
+
+For drag-and-drop with `@dnd-kit/core`, see the "Common Mistakes" entry on dnd libraries in the SKILL — `DndContext` must wrap from OUTSIDE the `<table>`.
+
+## Pinning — `columnPinningFeature`
+
+State: `columnPinning: { left: string[]; right: string[] }`. Two render strategies:
+
+```tsx
+// Strategy A — split tables
+<thead>
+  {table.getLeftHeaderGroups().map(/* … */)}
+</thead>
+// + getCenterHeaderGroups / getRightHeaderGroups
+// + row.getLeftVisibleCells / getCenterVisibleCells / getRightVisibleCells
+
+// Strategy B — single table + sticky CSS
+<th
+  key={header.id}
+  style={{
+    position: header.column.getIsPinned() ? 'sticky' : undefined,
+    left: header.column.getIsPinned() === 'left' ? `${header.column.getStart('left')}px` : undefined,
+    right: header.column.getIsPinned() === 'right' ? `${header.column.getAfter('right')}px` : undefined,
+  }}
+>
+  ...
+</th>
+
+// Toggle a pin programmatically
+column.pin('left')  // or 'right' | false
+```
+
+## Sizing — `columnSizingFeature`
+
+State: `columnSizing: Record<columnId, number>` (pixels). Defaults via `defaultColumnSizing` ({ size: 150, minSize: 20, maxSize: Number.MAX_SAFE_INTEGER }) or `tableOptions.defaultColumn` globally.
+
+```ts
+columnHelper.accessor('firstName', {
+  size: 200,
+  minSize: 80,
+  maxSize: 400,
+})
+
+// Reads
+column.getSize() // committed size (clamped)
+header.getSize() // same, for groups sums children
+table.getTotalSize()
+table.getCenterTotalSize()
+column.resetSize() // drop the override
+```
+
+## Resizing — `columnResizingFeature`
+
+```tsx
+// Wire BOTH onMouseDown AND onTouchStart on the resize handle
+<div
+  onDoubleClick={() => header.column.resetSize()}
+  onMouseDown={header.getResizeHandler()}
+  onTouchStart={header.getResizeHandler()}
+  className={`resizer ${header.column.getIsResizing() ? 'isResizing' : ''}`}
+/>
+
+// Modes:
+// columnResizeMode: 'onEnd' (default) — commit on drag release; safer for big React tables
+// columnResizeMode: 'onChange'        — commit live; needs the perf pattern in SKILL
+// columnResizeDirection: 'ltr' (default) | 'rtl'
+```
+
+## Additional MEDIUM-priority failure modes
+
+### Trying to reorder pinned columns via `columnOrder`
+
+Wrong:
+
+```ts
+// Won't move 'actions' relative to 'firstName' while it's pinned right
+const [columnPinning] = useState({
+  left: ['select'],
+  right: ['actions'],
+})
+table.setColumnOrder(['actions', 'select', 'firstName', 'lastName'])
+```
+
+Correct:
+
+```ts
+// Reorder the pinning state itself
+table.setColumnPinning((old) => ({
+  left: ['select'],
+  right: ['summary', 'actions'], // 'summary' renders before 'actions'
+}))
+
+// columnOrder works normally for the unpinned center region
+table.setColumnOrder(['firstName', 'lastName'])
+```
+
+After the pipeline's pinning split, the left/right partitions read directly from `state.columnPinning.left/right`. `columnOrder` only affects the center.
+
+Source: docs/guide/column-ordering.md; packages/table-core/src/features/column-pinning/columnPinningFeature.utils.ts
+
+### Using `react-dnd` / `react-beautiful-dnd` for column reorder in React 18+
+
+Wrong:
+
+```tsx
+// react-dnd in React 18 Strict Mode — flicker and stale drags
+import { DndProvider } from 'react-dnd'
+import { HTML5Backend } from 'react-dnd-html5-backend'
+
+// or nesting DndContext inside <table>
+;<table>
+  <DndContext onDragEnd={handleDragEnd}>
+    <thead>...</thead>
+  </DndContext>
+</table>
+```
+
+Correct:
+
+```tsx
+// @dnd-kit + wrap from OUTSIDE the table (DndContext renders divs)
+<DndContext
+  collisionDetection={closestCenter}
+  modifiers={[restrictToHorizontalAxis]}
+  onDragEnd={handleDragEnd}
+  sensors={sensors}
+>
+  <table>
+    <thead>
+      {table.getHeaderGroups().map((hg) => (
+        <tr key={hg.id}>
+          <SortableContext
+            items={table.store.state.columnOrder}
+            strategy={horizontalListSortingStrategy}
+          >
+            {hg.headers.map((h) => (
+              <DraggableHeader key={h.id} header={h} />
+            ))}
+          </SortableContext>
+        </tr>
+      ))}
+    </thead>
+  </table>
+</DndContext>
+```
+
+`react-dnd` has Strict Mode incompatibilities; `react-beautiful-dnd` is in maintenance. dnd-kit is the v9-recommended stack.
+
+Source: examples/react/column-dnd/src/main.tsx
+
+### Wiring `header.getResizeHandler()` to only `onMouseDown`
+
+Wrong:
+
+```tsx
+// Desktop only — mobile users can't resize
+<div onMouseDown={header.getResizeHandler()} />
+```
+
+Correct:
+
+```tsx
+<div
+  onDoubleClick={() => header.column.resetSize()}
+  onMouseDown={header.getResizeHandler()}
+  onTouchStart={header.getResizeHandler()}
+  className={`resizer ${header.column.getIsResizing() ? 'isResizing' : ''}`}
+/>
+```
+
+`header_getResizeHandler` branches internally on `isTouchStartEvent`. The same handler must be installed on both DOM events.
+
+Source: docs/guide/column-resizing.md; examples/react/column-resizing/src/main.tsx

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

@@ -0,0 +1,416 @@
+---
+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)`),
+  authoring custom functions with the `FilterFn` / `SortFn` / `AggregationFn`
+  signatures, chaining filter→sort via the `addMeta` callback +
+  `row.columnFiltersMeta`, `resolveFilterValue`, `autoRemove`, `invertSorting`,
+  `sortUndefined` ('first'|'last'|-1|1), and `sortDescFirst`. Distinguishes
+  `aggregationFn` (produces value) from `aggregatedCell` (renders value).
+type: core
+library: tanstack-table
+library_version: '9.0.0-alpha.48'
+requires:
+  - state-management
+sources:
+  - TanStack/table:docs/guide/sorting.md
+  - TanStack/table:docs/guide/column-filtering.md
+  - TanStack/table:docs/guide/fuzzy-filtering.md
+  - TanStack/table:packages/table-core/src/fns/filterFns.ts
+  - TanStack/table:packages/table-core/src/fns/sortFns.ts
+  - TanStack/table:packages/table-core/src/fns/aggregationFns.ts
+  - TanStack/table:examples/react/filters-fuzzy/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management`. Read it first for how feature plugins drive state slices.
+
+## Setup
+
+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.
+2. **Per-column overrides** — `columnDef.filterFn`, `columnDef.sortFn`, `columnDef.aggregationFn` (string name OR inline function).
+3. **Table-level overrides** — `tableOptions.globalFilterFn`.
+
+```ts
+import {
+  tableFeatures,
+  rowSortingFeature,
+  columnFilteringFeature,
+  globalFilteringFeature,
+  columnGroupingFeature,
+  rowExpandingFeature,
+  createFilteredRowModel,
+  createSortedRowModel,
+  createGroupedRowModel,
+  createExpandedRowModel,
+  filterFns,
+  sortFns,
+  aggregationFns,
+  createColumnHelper,
+} from '@tanstack/table-core'
+import type { FilterFn, SortFn, AggregationFn } from '@tanstack/table-core'
+import {
+  rankItem,
+  compareItems,
+  type RankingInfo,
+} from '@tanstack/match-sorter-utils'
+
+type Person = {
+  id: string
+  firstName: string
+  lastName: string
+  revenue: number
+  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
+  }
+}
+
+const fuzzyFilter: FilterFn<typeof _features, Person> = (
+  row,
+  columnId,
+  value,
+  addMeta,
+) => {
+  const itemRank = rankItem(row.getValue(columnId), value)
+  addMeta?.({ itemRank })
+  return itemRank.passed
+}
+
+const columnHelper = createColumnHelper<typeof _features, Person>()
+
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    filterFn: 'fuzzy', // ← refers to registered name
+    sortFn: 'alphanumeric',
+  }),
+  columnHelper.accessor('revenue', {
+    aggregationFn: 'sum',
+    aggregatedCell: (info) => `$${info.getValue<number>().toLocaleString()}`,
+  }),
+])
+
+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',
+})
+```
+
+## Core Patterns
+
+### Pick a built-in `sortFn` by name + direction control
+
+```ts
+columnHelper.accessor('lastName', {
+  sortFn: 'alphanumeric',
+  sortDescFirst: false,
+  sortUndefined: 'last', // ABSOLUTE: always at end regardless of asc/desc
+})
+```
+
+Layered direction controls:
+
+- `sortDescFirst: true/false` — first click sorts descending
+- `sortUndefined: 'first' | 'last' | -1 | 1 | false` — string forms are absolute; numeric flips with `desc`
+- `invertSorting: true` — for "lower-is-better" scales (rank 1 above rank 2 even when descending)
+
+### Filter → sort handoff via `addMeta`
+
+```ts
+const fuzzyFilter: FilterFn<typeof _features, Person> = (
+  row,
+  columnId,
+  value,
+  addMeta,
+) => {
+  const itemRank = rankItem(row.getValue(columnId), value)
+  addMeta?.({ itemRank })
+  return itemRank.passed
+}
+
+// Custom sortFn reads the meta the filter stashed
+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 })
+```
+
+`row.columnFiltersMeta` is keyed by the column id that produced the meta (or `'__global__'` for the global filter). The sortFn MUST look up the same column id its filterFn used.
+
+### Custom `aggregationFn` for grouping
+
+```ts
+import type { AggregationFn } from '@tanstack/table-core'
+
+// Signature: (columnId, leafRows, childRows) → aggregated value
+// leafRows = all descendant non-grouped rows
+// childRows = immediate children (may be sub-aggregates at deeper levels)
+const weightedMean: AggregationFn<typeof _features, Person> = (
+  columnId,
+  leafRows,
+) => {
+  let totalWeight = 0
+  let weightedSum = 0
+  leafRows.forEach((row) => {
+    const v = row.getValue<number>(columnId)
+    const w = row.original.revenue
+    weightedSum += v * w
+    totalWeight += w
+  })
+  return totalWeight === 0 ? 0 : weightedSum / totalWeight
+}
+
+const table = constructTable({
+  _features,
+  _rowModels: {
+    groupedRowModel: createGroupedRowModel({ ...aggregationFns, weightedMean }),
+    expandedRowModel: createExpandedRowModel(),
+  },
+  columns: columnHelper.columns([
+    columnHelper.accessor('revenue', {
+      aggregationFn: 'weightedMean',
+      aggregatedCell: (info) => `$${info.getValue<number>().toFixed(2)}`,
+    }),
+  ]),
+  data,
+})
+```
+
+## Common Mistakes
+
+### [CRITICAL] Referencing a custom `filterFn` by string without registering it
+
+Wrong:
+
+```ts
+// "fuzzy" string never registered
+const table = useTable({
+  _features,
+  columns: [columnHelper.accessor('fullName', { filterFn: 'fuzzy' })],
+  _rowModels: {
+    filteredRowModel: createFilteredRowModel(filterFns), // ❌ no fuzzy
+  },
+  data,
+})
+```
+
+Correct:
+
+```ts
+declare module '@tanstack/react-table' {
+  interface FilterFns {
+    fuzzy: FilterFn<typeof _features, Person>
+  }
+}
+
+const fuzzyFilter: FilterFn<typeof _features, Person> = (
+  row,
+  columnId,
+  value,
+  addMeta,
+) => {
+  const itemRank = rankItem(row.getValue(columnId), value)
+  addMeta?.({ itemRank })
+  return itemRank.passed
+}
+
+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.
+
+Source: examples/react/filters-fuzzy/src/main.tsx; packages/table-core/src/features/column-filtering/columnFilteringFeature.utils.ts
+
+### [HIGH] Using v8 `sortingFn` / `sortingFns` names
+
+Wrong:
+
+```ts
+columnHelper.accessor('age', {
+  sortingFn: 'alphanumeric', // v8 name — ignored
+})
+```
+
+Correct:
+
+```ts
+columnHelper.accessor('age', {
+  sortFn: 'alphanumeric',
+})
+```
+
+v9 renamed every sorting API: `sortingFn` → `sortFn`, `sortingFns` → `sortFns`, type `SortingFn` → `SortFn`, `column.getSortingFn()` → `column.getSortFn()`. The default `sortFn` is `'auto'`, falling back to `sortFn_basic` if the lookup misses — so wrong names sort wrong instead of erroring.
+
+Source: docs/framework/react/guide/migrating.md; packages/table-core/src/features/row-sorting/rowSortingFeature.types.ts
+
+### [HIGH] Custom `sortFn` reads filter meta from a different column id
+
+Wrong:
+
+```ts
+// filter on 'fullName', sort reads meta from 'firstName'
+const fuzzySort: SortFn<typeof _features, Person> = (a, b, columnId) => {
+  const meta = a.columnFiltersMeta['firstName'] // ❌ wrong key
+  return meta
+    ? compareItems(meta.itemRank, b.columnFiltersMeta['firstName'].itemRank)
+    : 0
+}
+columnHelper.accessor('fullName', { filterFn: 'fuzzy', sortFn: fuzzySort })
+```
+
+Correct:
+
+```ts
+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
+}
+```
+
+`row.columnFiltersMeta` is keyed by the column id that produced it. Always use the `columnId` argument the sortFn receives.
+
+Source: examples/react/filters-fuzzy/src/main.tsx
+
+### [MEDIUM] Returning a complex value from the accessor while using a built-in `sortFn`
+
+Wrong:
+
+```ts
+// accessor returns object; alphanumeric sees "[object Object]"
+columnHelper.accessor((row) => row.name, {
+  id: 'name',
+  sortFn: 'alphanumeric',
+})
+```
+
+Correct:
+
+```ts
+// Option A — return a primitive
+columnHelper.accessor((row) => `${row.name.first} ${row.name.last}`, {
+  id: 'fullName',
+  sortFn: 'alphanumeric',
+})
+
+// Option B — custom sortFn that knows the shape
+columnHelper.accessor((row) => row.name, {
+  id: 'name',
+  sortFn: (a, b, id) => {
+    const av = a.getValue<{ first: string }>(id).first
+    const bv = b.getValue<{ first: string }>(id).first
+    return av === bv ? 0 : av > bv ? 1 : -1
+  },
+})
+```
+
+Built-in sortFns (`alphanumeric`, `text`, `basic`) coerce via comparison operators. Object accessors collapse to `"[object Object]"` and every row ties.
+
+Source: packages/table-core/src/fns/sortFns.ts
+
+### [MEDIUM] Confusing `aggregationFn` with `aggregatedCell`
+
+Wrong:
+
+```ts
+// rendering JSX inside the aggregation function
+columnHelper.accessor('revenue', {
+  aggregationFn: (id, leaves) => <b>${leaves.reduce((a, r) => a + r.getValue(id), 0)}</b>,
+})
+```
+
+Correct:
+
+```ts
+columnHelper.accessor('revenue', {
+  aggregationFn: 'sum', // returns a value
+  aggregatedCell: (info) => <b>${info.getValue<number>().toLocaleString()}</b>, // renders it
+})
+```
+
+`aggregationFn` produces the grouped-row value (signature `(columnId, leafRows, childRows)`). `aggregatedCell` renders it. Don't combine.
+
+Source: packages/table-core/src/features/column-grouping/columnGroupingFeature.types.ts
+
+### [CRITICAL] Reimplementing what built-in APIs provide
+
+Wrong:
+
+```ts
+// Reimplements sorting state manually instead of using the API
+const [sorting, setSorting] = useState([])
+const sortedData = useMemo(() => [...data].sort(/* … */), [data, sorting])
+```
+
+Correct:
+
+```ts
+const table = useTable({
+  _features: tableFeatures({ rowSortingFeature }),
+  _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+  columns,
+  data,
+})
+// table.setSorting(...), column.toggleSorting(), header.getToggleSortingHandler()
+```
+
+Source: maintainer interview (Phase 4, 2026-05-17)
+
+## See also
+
+- `tanstack-table/filtering` — `filterFn` placement, fuzzy filter pattern, faceted UI
+- `tanstack-table/sorting` — built-in `sortFns`, multi-sort, `sortUndefined`
+- `tanstack-table/grouping` — `aggregationFn` signature details and built-ins