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

package/skills/state-management/SKILL.md

@@ -0,0 +1,388 @@
+---
+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.47'
+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/coreCellsFeature.utils.ts

@@ -3,9 +3,10 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { Cell } from '../../types/Cell'
 
 /**
- * Returns value for a cell.
+ * Reads this cell's accessor value from its owning row and column.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * This is the standalone implementation behind `cell.getValue()`, useful when
+ * importing static APIs instead of calling methods from the cell prototype.
  *
  * @example
  * ```ts
@@ -21,13 +22,14 @@ export function cell_getValue<
 }
 
 /**
- * Returns value for a cell.
+ * Reads the value that should be rendered for this cell.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * Nullish accessor values are replaced with `table.options.renderFallbackValue`,
+ * matching the behavior of `cell.renderValue()`.
  *
  * @example
  * ```ts
- * const value = cell_renderValue(cell)
+ * const rendered = cell_renderValue(cell)
  * ```
  */
 export function cell_renderValue<
@@ -39,13 +41,14 @@ export function cell_renderValue<
 }
 
 /**
- * Returns context for a cell.
+ * Builds the render context passed to a column's `cell` template.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * 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 value = cell_getContext(cell)
+ * const context = cell_getContext(cell)
  * ```
  */
 export function cell_getContext<

package/src/core/columns/coreColumnsFeature.types.ts

@@ -48,11 +48,12 @@ export interface Column_Column<
   TValue extends CellData = CellData,
 > extends Column_CoreProperties<TFeatures, TData, TValue> {
   /**
-   * Returns the flattened array of this column and all child/grand-child columns for this column.
+   * Flattens this column and every descendant column into a single array.
    */
   getFlatColumns: () => Array<Column<TFeatures, TData, TValue>>
   /**
-   * Returns an array of all leaf-node columns for this column. If a column has no children, it is considered the only leaf-node column.
+   * Collects the terminal leaf columns below this column, or the column itself
+   * when it has no children.
    */
   getLeafColumns: () => Array<Column<TFeatures, TData, TValue>>
 }
@@ -81,19 +82,19 @@ export interface Table_Columns<
    */
   getAllFlatColumnsById: () => Record<string, Column<TFeatures, TData, unknown>>
   /**
-   * Returns the default column options to use for all column defs supplied to the table.
+   * Resolves built-in, feature-level, and user-defined default column options.
    */
   getDefaultColumnDef: () => Partial<ColumnDef<TFeatures, TData, unknown>>
   /**
-   * Returns all columns in the table in their normalized and nested hierarchy.
+   * Normalizes `options.columns` into the table's nested column hierarchy.
    */
   getAllColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Returns all columns in the table flattened to a single level.
+   * Flattens the nested column hierarchy, including parent/group columns.
    */
   getAllFlatColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Returns all leaf-node columns in the table flattened to a single level. This does not include parent columns.
+   * Collects all terminal leaf columns, excluding parent/group columns.
    */
   getAllLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**

package/src/core/columns/coreColumnsFeature.utils.ts

@@ -12,13 +12,14 @@ import type {
 import type { Column } from '../../types/Column'
 
 /**
- * Returns flat columns for a column.
+ * Flattens this column and every descendant column into a single array.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Group columns appear before their child columns, which matches the normalized
+ * column hierarchy produced during table construction.
  *
  * @example
  * ```ts
- * const value = column_getFlatColumns(column)
+ * const flatColumns = column_getFlatColumns(column)
  * ```
  */
 export function column_getFlatColumns<
@@ -32,13 +33,14 @@ export function column_getFlatColumns<
 }
 
 /**
- * Returns leaf columns for a column.
+ * Collects the terminal leaf columns below this column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Group columns return their ordered descendants. Non-group columns return an
+ * array containing only the column itself.
  *
  * @example
  * ```ts
- * const value = column_getLeafColumns(column)
+ * const leafColumns = column_getLeafColumns(column)
  * ```
  */
 export function column_getLeafColumns<
@@ -64,13 +66,15 @@ export function column_getLeafColumns<
 }
 
 /**
- * Returns default column def for the table.
+ * Merges built-in, feature, and user default column definitions.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Built-in defaults provide a header and fallback cell renderer, feature
+ * defaults can add feature-specific column options, and
+ * `options.defaultColumn` wins last.
  *
  * @example
  * ```ts
- * const value = table_getDefaultColumnDef(table)
+ * const defaultColumn = table_getDefaultColumnDef(table)
  * ```
  */
 export function table_getDefaultColumnDef<
@@ -103,13 +107,14 @@ export function table_getDefaultColumnDef<
 }
 
 /**
- * Returns all columns for the table.
+ * Normalizes `options.columns` into the table's nested column tree.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Each column definition is constructed with its parent and depth, and group
+ * column children are recursively constructed.
  *
  * @example
  * ```ts
- * const value = table_getAllColumns(table)
+ * const columns = table_getAllColumns(table)
  * ```
  */
 export function table_getAllColumns<
@@ -144,13 +149,14 @@ export function table_getAllColumns<
 }
 
 /**
- * Returns all flat columns for the table.
+ * Flattens every table column, including group columns and leaf columns.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Use this when parent/group columns must be included in addition to data leaf
+ * columns.
  *
  * @example
  * ```ts
- * const value = table_getAllFlatColumns(table)
+ * const flatColumns = table_getAllFlatColumns(table)
  * ```
  */
 export function table_getAllFlatColumns<
@@ -163,13 +169,14 @@ export function table_getAllFlatColumns<
 }
 
 /**
- * Returns all flat columns by id for the table.
+ * Builds an id lookup for every flat column in the table.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Group columns and leaf columns are included. Later columns with the same id
+ * replace earlier entries.
  *
  * @example
  * ```ts
- * const value = table_getAllFlatColumnsById(table)
+ * const columnsById = table_getAllFlatColumnsById(table)
  * ```
  */
 export function table_getAllFlatColumnsById<
@@ -188,13 +195,14 @@ export function table_getAllFlatColumnsById<
 }
 
 /**
- * Returns all leaf columns for the table.
+ * Collects all terminal leaf columns in their current table order.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Column ordering features can reorder the collected leaves before the result
+ * is returned.
  *
  * @example
  * ```ts
- * const value = table_getAllLeafColumns(table)
+ * const leafColumns = table_getAllLeafColumns(table)
  * ```
  */
 export function table_getAllLeafColumns<
@@ -214,13 +222,14 @@ export function table_getAllLeafColumns<
 }
 
 /**
- * Returns all leaf columns by id for the table.
+ * Builds an id lookup for terminal leaf columns only.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Parent/group columns are excluded, making this lookup appropriate for row
+ * cells and feature state keyed by data columns.
  *
  * @example
  * ```ts
- * const value = table_getAllLeafColumnsById(table)
+ * const leavesById = table_getAllLeafColumnsById(table)
  * ```
  */
 export function table_getAllLeafColumnsById<
@@ -239,13 +248,14 @@ export function table_getAllLeafColumnsById<
 }
 
 /**
- * Returns column for the table.
+ * Looks up a column by id from the flat column map.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The lookup can return group columns or leaf columns. In development, a
+ * missing id logs a warning to help catch stale column references.
  *
  * @example
  * ```ts
- * const value = table_getColumn(table)
+ * const column = table_getColumn(table, 'firstName')
  * ```
  */
 export function table_getColumn<

package/src/core/headers/coreHeadersFeature.types.ts

@@ -10,19 +10,21 @@ export interface Table_Headers<
   TData extends RowData,
 > {
   /**
-   * Returns all header groups for the table.
+   * Builds the visible header groups for the current column tree, visibility,
+   * and pinning state.
    */
   getHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns the footer groups for the table.
+   * Builds footer groups by reversing the current header group order.
    */
   getFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns headers for all columns in the table, including parent headers.
+   * Flattens every header from every header group, including parent and
+   * placeholder headers.
    */
   getFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * Returns headers for all leaf columns in the table, (not including parent headers).
+   * Collects only leaf headers, excluding parent/group headers.
    */
   getLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
 }