@tanstack/table-core 9.0.0-beta.9 → 9.0.0

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'
+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/dist/index.d.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/dist/
+```
+
+For an adapter API, start at `node_modules/@tanstack/<framework>-table/dist/index.d.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 `dist/index.d.ts`, installed core `dist/index.d.ts`, then the exported implementation or feature directory. Prefer `dist/**/*.d.ts` (Ember: `declarations/**/*.d.ts`; Angular: `dist/types/*.d.ts`).

package/skills/cell-selection/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: cell-selection
+description: >
+  Select, add, and subtract rectangular cell ranges with cellSelectionFeature: ordered include/exclude operations keyed by row and column id, modifier dragging, final positive bounds, selection edges, render-order resolution under pinning, and autoResetCellSelection. Load for spreadsheet-style selection, “select all except” behavior, unexpected range changes after sorting or reordering, drag performance, or copy-to-clipboard.
+metadata:
+  { type: sub-skill, library: '@tanstack/table-core', library_version: '9.0.0' }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/cell-selection.md'
+  - 'TanStack/table:packages/table-core/src/features/cell-selection'
+  - 'TanStack/table:examples/react/cell-selection'
+---
+
+This skill builds on `core` and `table-features`. `cellSelection` is an ordered operation log of rectangles, each stored as two corner cells identified by row and column id. It is not a per-cell map, and it is not positional. Table resolves the log into disjoint positive rectangles for membership and derived reads.
+
+## Setup
+
+```ts
+import { cellSelectionFeature, tableFeatures } from '@tanstack/table-core'
+
+type Person = { id: string; name: string }
+export const features = tableFeatures({ cellSelectionFeature })
+export const options = {
+  getRowId: (row: Person) => row.id,
+}
+```
+
+State shape:
+
+```ts
+type CellSelectionRange = {
+  anchorRowId: string
+  anchorColumnId: string
+  focusRowId: string
+  focusColumnId: string
+  operation?: 'include' | 'exclude'
+}
+type CellSelectionState = Array<CellSelectionRange>
+```
+
+The `anchor` corner stays put; the `focus` corner moves during a drag or Shift-extend. Two corners are what make Shift-extend possible, and they keep a drag across thousands of cells to a two-field write. Operations apply in array order. An omitted `operation` means `include` for backward compatibility; `exclude` subtracts from the selection produced by preceding entries.
+
+## Core Patterns
+
+### Bind both mouse handlers
+
+```ts
+const onMouseDown = cell.getSelectionStartHandler()
+const onMouseEnter = cell.getSelectionExtendHandler()
+```
+
+The start handler attaches its own document-level `mouseup` listener and removes it when the drag ends, so a pointer released outside the table still finishes correctly. Pass a document explicitly (`cell.getSelectionStartHandler(iframeDocument)`) only when the table renders into another document.
+
+With the default event predicates, Shift extends the active operation. Ctrl/Cmd starts an inclusion when the starting cell is unselected and an exclusion when it is selected. That choice remains fixed for the drag, so shrinking an exclusion restores cells that leave its rectangle. Set `enableMultiCellRangeSelection: false` to disable both modifier behaviors.
+
+### Apply ranges programmatically
+
+```ts
+table.selectCellRange(range) // replace
+table.selectCellRange(range, { mode: 'include' })
+table.selectCellRange(range, { mode: 'exclude' })
+```
+
+Use `mode` when the operation is known. The deprecated `{ additive: true }` option is only an alias for include mode; an explicit `mode` wins.
+
+### Read the selection
+
+```ts
+const count = table.getSelectedCellCount()
+const bounds = table.getCellSelectionBounds()
+const grids = table.getSelectedCellRangesData() // [range][row][column]
+```
+
+`bounds` and `grids` describe the final disjoint positive regions after all operations, not one entry per stored state operation. Expansion APIs are memoized and pull-based, so a table that only highlights cells never pays to enumerate a large selection. Cell count uses rectangle arithmetic unless a per-cell `enableCellSelection` predicate requires enumeration.
+
+### Draw the outline from edges
+
+`cell.getSelectionEdges()` marks a side `true` when the neighbouring cell in that direction is not selected, which yields one continuous outline around a union of rectangles. All sides are `false` when the cell is not selected.
+
+### Drive keyboard navigation externally
+
+The feature ships no keydown handling. Call `table.moveCellSelection(direction)`, `table.extendCellSelection(direction)`, `table.setFocusedCell(rowId, columnId)`, `table.selectAllCells()`, and `table.resetCellSelection(true)` from a hotkey library such as `@tanstack/react-hotkeys`, scoped to the grid element rather than the document. Extending preserves the active operation. `getFocusedCell()` follows the latest anchor, so an excluded cell can remain focused without being selected.
+
+## Common Mistakes
+
+### [HIGH] Expecting a per-cell selection map
+
+Wrong: `const isSelected = table.state.cellSelection[cell.id]`
+
+Correct: `const isSelected = cell.getIsSelected()`
+
+`cellSelection` holds ordered rectangle operations, not cell keys. Membership is resolved against the memoized final positive bounds.
+
+Source: `packages/table-core/src/features/cell-selection/cellSelectionFeature.types.ts`
+
+### [HIGH] Treating stored operations as final selected regions
+
+Wrong: serialize or render each `table.state.cellSelection` entry as a selected rectangle.
+
+Correct: use `table.getCellSelectionBounds()`, `cell.getIsSelected()`, or `table.getSelectedCellRangesData()` for the resolved selection.
+
+An exclusion is an instruction, not a selected region, and a subtraction can split one included rectangle into four disjoint positive regions. Re-including a later rectangle applies after the exclusion because state order is significant.
+
+Source: `packages/table-core/src/features/cell-selection/cellSelectionGeometry.ts`
+
+### [HIGH] Assuming a range is frozen to the cells it originally covered
+
+Ranges are anchored to corner ids, so sorting, filtering, and column reordering keep the corners and recompute what sits between them. A range can therefore widen onto columns or rows the user never selected. Reset in userland when the product needs stricter behavior:
+
+```ts
+// after a column reorder or pin
+table.resetCellSelection(true)
+```
+
+Hiding a column that a corner sits on makes the range inert rather than deleting it; it returns when the column is shown again.
+
+Source: `docs/framework/react/guide/cell-selection.md#how-ranges-survive-table-changes`
+
+### [HIGH] Binding only mousedown and expecting drag
+
+Wrong:
+
+```ts
+const props = { onMouseDown: cell.getSelectionStartHandler() }
+```
+
+Correct:
+
+```ts
+const props = {
+  onMouseDown: cell.getSelectionStartHandler(),
+  onMouseEnter: cell.getSelectionExtendHandler(),
+}
+```
+
+Without the extend handler a drag selects only the origin cell. Do not add a `mouseup` binding; the start handler already owns one.
+
+Source: `examples/react/cell-selection`
+
+### [HIGH] Deriving column position from column definition order
+
+Wrong: `const index = column.getIndex()`
+
+Correct: `const isSelected = cell.getIsSelected()`
+
+Cells render start-pinned first, then center, then end. `getVisibleLeafColumns()` and `column.getIndex()` are not pinning-reordered, so indexing a selection against them makes a rectangle visually scattered as soon as a column is pinned. The feature resolves its own render-order index map; use the cell APIs rather than recomputing membership.
+
+Source: `packages/table-core/src/features/cell-selection/cellSelectionFeature.utils.ts`
+
+### [HIGH] Re-rendering every cell on each drag update
+
+Wrong: one subscription wrapping the whole `<tbody>`.
+
+Correct: one subscription per row, with a selector returning only what changes that row's appearance.
+
+A drag writes state on every cell boundary crossed. A table-wide subscription reconciles every cell each time. Subscribe per row against `table.atoms.cellSelection` and derive a key from `table.getCellSelectionBounds()` (memoized, so it computes once per change) covering the row itself plus the rows above and below, which decide its top and bottom edges.
+
+Source: `docs/framework/react/guide/cell-selection.md#performance-with-tablesubscribe`
+
+### [MEDIUM] Drawing selection borders on a border-collapse table
+
+Wrong: `.cell-selected { border: 2px solid blue }`
+
+Correct: `.cell-selected { box-shadow: inset 0 0 0 2px blue }`
+
+On a `border-collapse` table a thicker border widens the shared grid line, so rows change height as cells become selected. Box-shadow never affects layout.
+
+Source: `examples/react/cell-selection/src/index.css`
+
+### [MEDIUM] Expecting a clipboard string from the table
+
+Wrong: `navigator.clipboard.writeText(table.getSelectedCellsAsTsv())`
+
+Correct: `navigator.clipboard.writeText(toTsv(table.getSelectedCellRangesData()))`
+
+The table returns raw values only. The delimiter, the representation of `null`, and quoting rules are application decisions, so serialization is userland. Quote any field containing a tab, newline, or quote, or a pasted spreadsheet gains phantom columns.
+
+Source: `docs/framework/react/guide/cell-selection.md#copying-a-selection`
+
+### [MEDIUM] Persisting a selection and expecting drag state with it
+
+`cellSelection` is safe to persist because drag session state is deliberately non-reactive instance data, not part of the slice. Preserve array order and each `operation`; sorting or deduplicating the entries changes the resolved selection. Do not add an `isSelecting` field to the persisted state; a stored `true` would rehydrate into a drag that hovering extends and nothing ever ends.
+
+Source: `packages/table-core/src/features/cell-selection/cellSelectionFeature.types.ts`
+
+### [MEDIUM] Fighting the automatic reset on data change
+
+Selection resets to `initialState.cellSelection` whenever `data` changes, because new data can invalidate the row ids a range points at or silently re-select cells when ids are reused. Opt out deliberately:
+
+```ts
+export const keepAcrossDataChanges = { autoResetCellSelection: false }
+```
+
+`autoResetAll` overrides this option.
+
+Source: `packages/table-core/src/features/cell-selection/cellSelectionFeature.ts`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/features/cell-selection/` for `CellSelectionRange`, `CellSelectionRangeOperation`, `CellSelectionRangeMode`, `CellSelectionState`, `CellSelectionBounds`, `SelectCellRangeOptions`, the enablement and `is*Event` options, and the cell and table instance APIs.

package/skills/cell-spanning/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: cell-spanning
+description: >
+  Merge adjacent body cells with cellSpanningFeature: value-based rowSpan opt-in per column via spanRows, per-row colSpan via spanColumns, and the covered-cell convention where a span of 0 means skip the cell. Load for merged data grids, spans that disappear after sorting or paginating, ragged table rows, or a cell that unexpectedly merges down the whole tbody.
+metadata:
+  { type: sub-skill, library: '@tanstack/table-core', library_version: '9.0.0' }
+requires: ['core', 'table-features']
+sources:
+  - 'TanStack/table:docs/framework/react/guide/cell-spanning.md'
+  - 'TanStack/table:packages/table-core/src/features/cell-spanning'
+  - 'TanStack/table:examples/react/cell-spanning'
+---
+
+This skill builds on `core` and `table-features`. Cell spanning is stateless and fully derived: a memoized table-level span index is rebuilt from the rows that are actually rendered, and per-cell reads are O(1) lookups against it. Sorting, filtering, pagination, and row pinning only change adjacency; spans follow automatically and never persist.
+
+## Setup
+
+<!-- skill-snippet:check -->
+
+```ts
+import { cellSpanningFeature, tableFeatures } from '@tanstack/table-core'
+
+export const features = tableFeatures({ cellSpanningFeature })
+```
+
+## Core Patterns
+
+### Opt columns into value-based row spanning
+
+```ts
+const columns = [
+  { accessorKey: 'region', spanRows: true },
+  {
+    accessorKey: 'createdAt',
+    spanRows: ({
+      anchorValue,
+      value,
+    }: {
+      anchorValue: unknown
+      value: unknown
+    }) => sameMonth(anchorValue as Date, value as Date),
+  },
+]
+```
+
+`spanRows: true` merges adjacent rendered rows whose values match under `Object.is`. Nullish values never merge under the default comparison; a predicate can opt in. Predicates are anchored: every candidate row is tested against the run's first row (`anchorRow`/`anchorValue`), which keeps runs transitive.
+
+### Declare column spans per row
+
+```ts
+const columns = [
+  {
+    accessorKey: 'label',
+    spanColumns: ({ row }: { row: { original: { isSummary?: boolean } } }) =>
+      row.original.isSummary ? Infinity : 1,
+  },
+]
+```
+
+`spanColumns` counts visible columns in render order and clamps to the end of the cell's pinned region, so `Infinity` means "the rest of my region" and a span never crosses a start/center/end pinning boundary. Cells only join a vertical run when their column spans match, so a full-width summary row never merges into the data run above it.
+
+### Render with the skip-covered-cells loop
+
+```tsx
+{
+  row.getVisibleCells().map((cell) => {
+    const rowSpan = cell.getRowSpan()
+    const colSpan = cell.getColSpan()
+    if (rowSpan === 0 || colSpan === 0) return null
+    return (
+      <td key={cell.id} rowSpan={rowSpan} colSpan={colSpan}>
+        {flexRender(cell.column.columnDef.cell, cell.getContext())}
+      </td>
+    )
+  })
+}
+```
+
+A span of `0` means the cell is covered; `cell.getIsCovered()` is the same check as one call. This mirrors the `header.rowSpan` convention for uneven header trees.
+
+### Disable
+
+`enableCellSpanning: false` as a table option disables everything; the same flag on a column def opts a single column out and wins over the table option.
+
+## Common Mistakes
+
+### [CRITICAL] Rendering rowSpan={0} instead of skipping the cell
+
+Wrong:
+
+```tsx
+<td rowSpan={cell.getRowSpan()} colSpan={cell.getColSpan()}>
+```
+
+Correct:
+
+```tsx
+cell.getIsCovered() ? null : (
+  <td rowSpan={cell.getRowSpan()} colSpan={cell.getColSpan()}>
+)
+```
+
+In HTML, `rowspan="0"` is valid and means "span to the end of the row group", so the wrong version does not render an empty cell. It merges the covered cell down the entire tbody and shifts every later cell out of its column.
+
+### [HIGH] Expecting spanning to sort or group the rows
+
+Wrong:
+
+```ts
+const features = tableFeatures({ cellSpanningFeature })
+// data arrives unsorted; the table renders zero merged cells
+```
+
+Correct:
+
+```ts
+const features = tableFeatures({
+  cellSpanningFeature,
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric },
+})
+// sort by the spanned column, or emit data with equal values adjacent
+```
+
+Value-based spanning merges adjacent equal values only. It does not reorder rows, and it is not grouping; register `columnGroupingFeature` when collapsible group rows are what is wanted.
+
+### [HIGH] Precomputing spans from the source data
+
+Wrong:
+
+```ts
+const spans = useMemo(() => computeSpans(data), [data])
+```
+
+Correct:
+
+```ts
+const rowSpan = cell.getRowSpan()
+```
+
+Spans derive from the final row model. A span precomputed from `data` survives sorting, filtering, and page changes, producing ragged rows the moment any of them changes.
+
+### [MEDIUM] Assuming a run continues across a page boundary
+
+A run is clipped by the paginated row model. The next page opens a fresh cell for the continuing value; nothing carries over, and nothing needs to.
+
+### [MEDIUM] Reimplementing merge-aware selection on top of cellSelectionFeature
+
+When both features are registered, selection is already merge-aware: ranges expand at derivation time to fully enclose any merge they touch (includes and excludes alike), navigation crosses a merge in one step, and `getSelectedCellCount()` counts a merge once. Do not pre-expand stored selection corners yourself; stored corners stay stable while sorting or paging changes the merges, and pre-expanded corners go stale.
+
+### [MEDIUM] Spanning a grouped column
+
+`spanRows` is ignored while its column is grouped, and grouped rows never join runs in any column. Grouping already collapses repeated values into group rows; spanning them again would merge twice.
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/table-core/dist/features/cell-spanning/` for the full API: `cell.getRowSpan()`, `cell.getColSpan()`, `cell.getIsCovered()`, `table.getCellSpanIndex()`, and the `spanRows`/`spanColumns`/`enableCellSpanning` column and table options.

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'
+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/dist/core/row-models/coreRowModelsFeature.utils.d.ts` for pipeline order and each feature's `.types.d.ts` for its `manual*` contract.