@tanstack/table-core 9.0.0-beta.7 → 9.0.0-beta.71

package/skills/state-management/SKILL.md

@@ -1,388 +0,0 @@
----
-name: state-management
-description: >
-  Coordinate TanStack Table v9 state across `initialState`, controlled
-  `state`+`on*Change`, and external `atoms`. Covers the atom model
-  (`table.atoms.<slice>`, `table.baseAtoms.<slice>`, `table.store`, `table.state`),
-  per-slice precedence (atoms beat state beat initialState beat baseAtoms),
-  `manualSorting` / `manualFiltering` / `manualPagination` / `manualGrouping` /
-  `manualExpanding` for server-side data, `autoResetPageIndex` / `autoResetAll`,
-  reset APIs (`resetSorting`, `resetPagination`, `reset()`), and the
-  `SortingState` / `PaginationState` / `RowSelectionState` / `ColumnFiltersState` /
-  `GroupingState` shapes. Foundational for every other skill.
-type: core
-library: tanstack-table
-library_version: '9.0.0-alpha.48'
-sources:
-  - TanStack/table:docs/framework/vanilla/guide/table-state.md
-  - TanStack/table:docs/framework/react/guide/table-state.md
-  - TanStack/table:packages/table-core/src/store-reactivity-bindings.ts
-  - TanStack/table:packages/table-core/src/reactivity.ts
-  - TanStack/table:packages/table-core/src/core/table/constructTable.ts
----
-
-## Setup
-
-TanStack Table v9 is built on TanStack Store. Each state slice (sorting, pagination, columnFilters, rowSelection, columnVisibility, …) is a separate atom. There are four ownership patterns, and the table reads from them in a fixed precedence.
-
-```ts
-import {
-  constructTable,
-  tableFeatures,
-  rowSortingFeature,
-  rowPaginationFeature,
-  createSortedRowModel,
-  createPaginatedRowModel,
-  sortFns,
-} from '@tanstack/table-core'
-
-const features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
-
-const table = constructTable({
-  features,
-  rowModels: {
-    sortedRowModel: createSortedRowModel(sortFns),
-    paginatedRowModel: createPaginatedRowModel(),
-  },
-  columns,
-  data,
-  // 1. initialState — set starting values; read once at construction
-  initialState: {
-    sorting: [{ id: 'lastName', desc: false }],
-    pagination: { pageIndex: 0, pageSize: 10 },
-  },
-})
-
-// Read APIs:
-table.store.state // flat snapshot of every slice (no subscription)
-table.atoms.sorting.get() // single-slice atom read (no subscription)
-table.state // typed output of the `useTable` selector (framework adapters)
-
-// Write APIs use the feature setters — they're atom-aware:
-table.setSorting([{ id: 'firstName', desc: true }])
-table.setPageIndex(2)
-```
-
-The four ownership patterns per slice:
-
-| Pattern                             | When to use                                          | Wins over                       |
-| ----------------------------------- | ---------------------------------------------------- | ------------------------------- |
-| internal (default)                  | Most slices in a simple table                        | nothing — baseline              |
-| `initialState.<slice>`              | Set starting value only                              | internal default                |
-| `state.<slice>` + `on<Slice>Change` | v8-style controlled state                            | `initialState`                  |
-| `atoms.<slice>`                     | v9 preferred — share with other components / queries | `state`+`on*Change` (silently!) |
-
-## Core Patterns
-
-### Internal state with `initialState`
-
-```ts
-const table = constructTable({
-  features,
-  rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-  columns,
-  data,
-  initialState: { sorting: [{ id: 'age', desc: false }] },
-})
-// State lives entirely inside the table.
-table.setSorting([{ id: 'firstName', desc: true }])
-```
-
-### Controlled state with `state` + `on*Change` (v8-style)
-
-```tsx
-const [sorting, setSorting] = React.useState<SortingState>([])
-
-const table = useTable({
-  features,
-  rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-  columns,
-  data,
-  state: { sorting },
-  onSortingChange: setSorting,
-})
-```
-
-`state` and `on*Change` must be paired. Without the callback the table cannot update React state, so toggling sort appears to do nothing.
-
-### External atom (v9 preferred for shared slices)
-
-```tsx
-import { useCreateAtom } from '@tanstack/react-store'
-
-function MyTable() {
-  // Hoist or pass via context to share with queries / other components.
-  const paginationAtom = useCreateAtom<PaginationState>({
-    pageIndex: 0,
-    pageSize: 10,
-  })
-
-  const table = useTable({
-    features,
-    rowModels: { paginatedRowModel: createPaginatedRowModel() },
-    columns,
-    data,
-    atoms: { pagination: paginationAtom },
-    // no state.pagination, no onPaginationChange needed
-  })
-
-  return <Pager paginationAtom={paginationAtom} />
-}
-```
-
-The atom IS the source of truth; `table.atoms.pagination` derives from it.
-
-### Server-side / manual mode
-
-```tsx
-const [pagination, setPagination] = React.useState({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const dataQuery = useQuery({
-  queryKey: ['rows', pagination],
-  queryFn: () => fetchPage(pagination),
-})
-
-const table = useTable({
-  features: tableFeatures({ rowPaginationFeature }),
-  rowModels: {}, // can drop paginatedRowModel — server paginates
-  columns,
-  data: dataQuery.data?.rows ?? EMPTY,
-  rowCount: dataQuery.data?.rowCount, // server tells the table the total
-  state: { pagination },
-  onPaginationChange: setPagination,
-  manualPagination: true, // ← tell the table to NOT re-paginate
-})
-```
-
-The same shape applies to `manualSorting`, `manualFiltering`, `manualGrouping`, `manualExpanding`. Without the flag, the table re-applies its client-side pipeline on top of already-prepared server data.
-
-## Common Mistakes
-
-### [CRITICAL] Passing both `state.<slice>` and `atoms.<slice>`
-
-Wrong:
-
-```tsx
-// both ownership paths for the same slice
-const paginationAtom = useCreateAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })
-const [pagination, setPagination] = React.useState(...)
-
-const table = useTable({
-  features, rowModels: {...}, columns, data,
-  state: { pagination },                  // ignored
-  onPaginationChange: setPagination,
-  atoms: { pagination: paginationAtom },  // wins
-})
-```
-
-Correct:
-
-```tsx
-// pick one ownership path per slice — here, external atoms
-const paginationAtom = useCreateAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })
-
-const table = useTable({
-  features, rowModels: {...}, columns, data,
-  atoms: { pagination: paginationAtom },
-})
-```
-
-When both are supplied, the external atom wins silently. `state.pagination` becomes dead config and `setPagination` writes never reach the table.
-
-Source: docs/framework/react/guide/table-state.md; packages/table-core/src/core/table/constructTable.ts
-
-### [CRITICAL] Using external `state` without the matching `on*Change` callback
-
-Wrong:
-
-```tsx
-const [sorting, setSorting] = React.useState<SortingState>([])
-const table = useTable({
-  features,
-  rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-  columns,
-  data,
-  state: { sorting }, // no onSortingChange
-})
-```
-
-Correct:
-
-```tsx
-const [sorting, setSorting] = React.useState<SortingState>([])
-const table = useTable({
-  features,
-  rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-  columns,
-  data,
-  state: { sorting },
-  onSortingChange: setSorting,
-})
-```
-
-The table keeps reading from `state.sorting`, so the UI looks stuck — sort toggles never make it back into React state.
-
-Source: docs/framework/react/guide/table-state.md; examples/react/basic-external-state/src/main.tsx
-
-### [HIGH] Using `initialState` to control or update state
-
-Wrong:
-
-```tsx
-// updates to initialState are ignored after first render
-function MyTable({ defaultSort }: { defaultSort: SortingState }) {
-  const table = useTable({
-    features,
-    rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-    columns,
-    data,
-    initialState: { sorting: defaultSort }, // later changes never sync
-  })
-}
-```
-
-Correct:
-
-```tsx
-function MyTable({ defaultSort }: { defaultSort: SortingState }) {
-  const [sorting, setSorting] = React.useState(defaultSort)
-  const table = useTable({
-    features,
-    rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
-    columns,
-    data,
-    state: { sorting },
-    onSortingChange: setSorting,
-  })
-}
-```
-
-`initialState` is read once at construction to seed `baseAtoms`. Mutating it later does nothing.
-
-Source: docs/framework/vanilla/guide/table-state.md; docs/framework/react/guide/table-state.md
-
-### [HIGH] Writing to `table.baseAtoms.<slice>` while `atoms.<slice>` owns the slice
-
-Wrong:
-
-```ts
-const paginationAtom = useCreateAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })
-const table = useTable({ features, rowModels: {...}, columns, data, atoms: { pagination: paginationAtom } })
-
-table.baseAtoms.pagination.set((old) => ({ ...old, pageIndex: 0 }))
-// baseAtom updated, but table.atoms.pagination still reads from paginationAtom
-```
-
-Correct:
-
-```ts
-// Write to the external atom directly, OR use the feature's setter API
-paginationAtom.set((old) => ({ ...old, pageIndex: 0 }))
-// or
-table.setPageIndex(0) // setter writes through the slice's updater (atom-aware)
-```
-
-When an external atom owns a slice, `table.atoms.<slice>` derives from it — not from `baseAtoms`. Direct base-atom writes drift and never surface in the UI.
-
-Source: docs/framework/vanilla/guide/table-state.md; packages/table-core/src/core/table/constructTable.ts
-
-### [CRITICAL] Forgetting `manualSorting` / `manualFiltering` / `manualPagination` for server-side data
-
-Wrong:
-
-```tsx
-// data is already paginated server-side, but table still slices it
-const dataQuery = useQuery({
-  queryKey: ['data', pagination],
-  queryFn: fetchPage,
-})
-const table = useTable({
-  features,
-  rowModels: { paginatedRowModel: createPaginatedRowModel() },
-  columns,
-  data: dataQuery.data?.rows ?? [],
-  rowCount: dataQuery.data?.rowCount,
-  atoms: { pagination: paginationAtom },
-  // ❌ missing manualPagination: true
-})
-```
-
-Correct:
-
-```tsx
-const table = useTable({
-  features,
-  rowModels: {}, // drop paginatedRowModel if fully server-side
-  columns,
-  data: dataQuery.data?.rows ?? [],
-  rowCount: dataQuery.data?.rowCount,
-  atoms: { pagination: paginationAtom },
-  manualPagination: true,
-})
-```
-
-Without the manual flag, the table re-applies its client-side row models on top of already-prepared server data — wrong rows, broken page math, blank pages.
-
-Source: docs/framework/react/guide/table-state.md; packages/table-core/src/features/row-pagination/rowPaginationFeature.types.ts
-
-### [HIGH] Using `table.reset()` to clear externally owned state
-
-Wrong:
-
-```ts
-// external atom keeps its current value; only baseAtoms reset
-const sortingAtom = useCreateAtom<SortingState>([])
-const table = useTable({
-  features, rowModels: {...}, columns, data,
-  atoms: { sorting: sortingAtom },
-})
-table.reset() // sortingAtom is NOT cleared
-```
-
-Correct:
-
-```ts
-// Use feature-specific reset — atom-aware
-table.resetSorting()
-// or, to clear the external atom specifically:
-sortingAtom.set([])
-```
-
-`table.reset()` only resets `baseAtoms` to `initialState`; slices owned by external atoms or external `state` are untouched. The atom split makes `reset()` less safe than v8.
-
-Source: docs/framework/vanilla/guide/table-state.md; packages/table-core/src/core/table/coreTablesFeature.utils.ts
-
-### [CRITICAL] Reimplementing what built-in setters provide
-
-Wrong:
-
-```ts
-// Reimplements sorting state manually instead of using the API
-const [sorting, setSorting] = useState([])
-const sortedData = useMemo(() => [...data].sort(/* ... */), [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()
-```
-
-The setters honor reset behavior, multi-sort, internal invariants. Hand-rolled state loops skip all of that.
-
-Source: maintainer interview (Phase 4, 2026-05-17)
-
-## See also
-
-- `tanstack-table/setup` — how `features` and `rowModels` are wired
-- `tanstack-table/pagination`, `tanstack-table/sorting`, `tanstack-table/filtering` — feature-specific `manual*` and reset semantics
-- `tanstack-table/migrate-v8-to-v9` — `table.getState()` → `table.store.state` / `table.atoms.<slice>.get()`

package/src/core/cells/constructCell.ts

@@ -1,55 +0,0 @@
-import type { Table_Internal } from '../../types/Table'
-import type { CellData, RowData } from '../../types/type-utils'
-import type { TableFeatures } from '../../types/TableFeatures'
-import type { Row } from '../../types/Row'
-import type { Cell } from '../../types/Cell'
-import type { Column } from '../../types/Column'
-import type { Cell_CoreProperties } from './coreCellsFeature.types'
-
-/**
- * Creates or retrieves the cell prototype for a table.
- * The prototype is cached on the table and shared by all cell instances.
- */
-function getCellPrototype<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(table: Table_Internal<TFeatures, TData>): object {
-  if (!table._cellPrototype) {
-    table._cellPrototype = { table }
-    const features = Object.values(table._features)
-    for (let i = 0; i < features.length; i++) {
-      features[i]!.assignCellPrototype?.(table._cellPrototype, table)
-    }
-  }
-  return table._cellPrototype
-}
-
-/**
- * Constructs a cell instance from normalized table internals.
- *
- * This wires core properties, feature prototype APIs, and instance data used by table rendering and row-model operations.
- */
-export function constructCell<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
->(
-  column: Column<TFeatures, TData, TValue>,
-  row: Row<TFeatures, TData>,
-  table: Table_Internal<TFeatures, TData>,
-): Cell<TFeatures, TData, TValue> {
-  // Create cell with shared prototype for memory efficiency
-  const cellPrototype = getCellPrototype(table)
-  const cell = Object.create(cellPrototype) as Cell_CoreProperties<
-    TFeatures,
-    TData,
-    TValue
-  >
-
-  // Only assign instance-specific properties
-  cell.column = column
-  cell.id = `${row.id}_${column.id}`
-  cell.row = row
-
-  return cell as Cell<TFeatures, TData, TValue>
-}

package/src/core/cells/coreCellsFeature.ts

@@ -1,27 +0,0 @@
-import { assignPrototypeAPIs } from '../../utils'
-import {
-  cell_getContext,
-  cell_getValue,
-  cell_renderValue,
-} from './coreCellsFeature.utils'
-import type { TableFeature } from '../../types/TableFeatures'
-
-/**
- * Core feature that adds cell value, render, and context APIs.
- */
-export const coreCellsFeature: TableFeature = {
-  assignCellPrototype: (prototype, table) => {
-    assignPrototypeAPIs('coreCellsFeature', prototype, table, {
-      cell_getValue: {
-        fn: (cell) => cell_getValue(cell),
-      },
-      cell_renderValue: {
-        fn: (cell) => cell_renderValue(cell),
-      },
-      cell_getContext: {
-        fn: (cell) => cell_getContext(cell),
-        memoDeps: (cell) => [cell],
-      },
-    })
-  },
-}

package/src/core/cells/coreCellsFeature.types.ts

@@ -1,68 +0,0 @@
-import type { CellData, Getter, RowData } from '../../types/type-utils'
-import type { TableFeatures } from '../../types/TableFeatures'
-import type { Table, Table_Internal } from '../../types/Table'
-import type { Row } from '../../types/Row'
-import type { Cell } from '../../types/Cell'
-import type { Column } from '../../types/Column'
-
-export interface CellContext<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
-> {
-  cell: Cell<TFeatures, TData, TValue>
-  column: Column<TFeatures, TData, TValue>
-  getValue: Getter<TValue>
-  renderValue: Getter<TValue | null>
-  row: Row<TFeatures, TData>
-  table: Table<TFeatures, TData>
-}
-
-export interface Cell_CoreProperties<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
-> {
-  /**
-   * The associated Column object for the cell.
-   */
-  column: Column<TFeatures, TData, TValue>
-  /**
-   * The unique ID for the cell across the entire table.
-   */
-  id: string
-  /**
-   * The associated Row object for the cell.
-   */
-  row: Row<TFeatures, TData>
-  /**
-   * Reference to the parent table instance.
-   */
-  table: Table_Internal<TFeatures, TData>
-}
-
-export interface Cell_Cell<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
-> extends Cell_CoreProperties<TFeatures, TData, TValue> {
-  /**
-   * Returns the rendering context (or props) for cell-based components like cells and aggregated cells. Use these props with your framework's `flexRender` utility to render these using the template of your choice:
-   */
-  getContext: () => CellContext<TFeatures, TData, TValue>
-  /**
-   * Returns the value for the cell, accessed via the associated column's accessor key or accessor function.
-   */
-  getValue: CellContext<TFeatures, TData, TValue>['getValue']
-  /**
-   * Renders the value for a cell the same as `getValue`, but will return the `renderFallbackValue` if no value is found.
-   */
-  renderValue: CellContext<TFeatures, TData, TValue>['renderValue']
-}
-
-export interface TableOptions_Cell {
-  /**
-   * Value used when the desired value is not found in the data.
-   */
-  renderFallbackValue?: any
-}

package/src/core/cells/coreCellsFeature.utils.ts

@@ -1,68 +0,0 @@
-import type { CellData, RowData } from '../../types/type-utils'
-import type { TableFeatures } from '../../types/TableFeatures'
-import type { Cell } from '../../types/Cell'
-
-/**
- * Reads this cell's accessor value from its owning row and column.
- *
- * This is the standalone implementation behind `cell.getValue()`, useful when
- * importing static APIs instead of calling methods from the cell prototype.
- *
- * @example
- * ```ts
- * const value = cell_getValue(cell)
- * ```
- */
-export function cell_getValue<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
->(cell: Cell<TFeatures, TData, TValue>): TValue {
-  return cell.row.getValue(cell.column.id)
-}
-
-/**
- * Reads the value that should be rendered for this cell.
- *
- * Nullish accessor values are replaced with `table.options.renderFallbackValue`,
- * matching the behavior of `cell.renderValue()`.
- *
- * @example
- * ```ts
- * const rendered = cell_renderValue(cell)
- * ```
- */
-export function cell_renderValue<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
->(cell: Cell<TFeatures, TData, TValue>) {
-  return cell.getValue() ?? cell.table.options.renderFallbackValue
-}
-
-/**
- * Builds the render context passed to a column's `cell` template.
- *
- * The returned object includes stable references to the table, row, column, and
- * cell, plus bound `getValue` and `renderValue` helpers for render functions.
- *
- * @example
- * ```ts
- * const context = cell_getContext(cell)
- * ```
- */
-export function cell_getContext<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
-  TValue extends CellData = CellData,
->(cell: Cell<TFeatures, TData, TValue>) {
-  return {
-    table: cell.table,
-    column: cell.column,
-    row: cell.row,
-    cell: cell,
-    // Wrap in arrow functions to preserve `this` binding (methods are on prototype)
-    getValue: () => cell.getValue(),
-    renderValue: () => cell.renderValue(),
-  }
-}