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

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

@@ -1,220 +0,0 @@
-# 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

@@ -1,416 +0,0 @@
----
-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