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

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/fns/aggregationFns.ts

@@ -1,245 +0,0 @@
-import type { RowData } from '../types/type-utils'
-import type { TableFeatures } from '../types/TableFeatures'
-import type { Row } from '../types/Row'
-
-/**
- * Sums numeric child-row values for a grouped column.
- *
- * Non-number values contribute `0`. Child rows are used so nested group totals
- * can reuse already aggregated values.
- */
-export function aggregationFn_sum<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  columnId: string,
-  _leafRows: Array<Row<TFeatures, TData>>,
-  childRows: Array<Row<TFeatures, TData>>,
-) {
-  // It's faster to just add the aggregations together instead of
-  // process leaf nodes individually
-  return childRows.reduce((sumValue, next) => {
-    const nextValue = next.getValue(columnId)
-    return sumValue + (typeof nextValue === 'number' ? nextValue : 0)
-  }, 0)
-}
-
-/**
- * Finds the minimum numeric child-row value for a grouped column.
- *
- * Nullish and non-number values are ignored. Returns `undefined` when no
- * numeric value is found.
- */
-export function aggregationFn_min<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  columnId: string,
-  _leafRows: Array<Row<TFeatures, TData>>,
-  childRows: Array<Row<TFeatures, TData>>,
-) {
-  let minValue: number | undefined
-
-  childRows.forEach((row) => {
-    const value = row.getValue(columnId)
-
-    if (
-      value != null &&
-      typeof value === 'number' &&
-      (minValue === undefined || value < minValue)
-    ) {
-      minValue = value
-    }
-  })
-
-  return minValue
-}
-
-/**
- * Finds the maximum numeric child-row value for a grouped column.
- *
- * Nullish and non-number values are ignored. Returns `undefined` when no
- * numeric value is found.
- */
-export function aggregationFn_max<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  columnId: string,
-  _leafRows: Array<Row<TFeatures, TData>>,
-  childRows: Array<Row<TFeatures, TData>>,
-) {
-  let maxValue: number | undefined
-
-  childRows.forEach((row) => {
-    const value = row.getValue(columnId)
-    if (
-      value != null &&
-      typeof value === 'number' &&
-      (maxValue === undefined || value > maxValue)
-    ) {
-      maxValue = value
-    }
-  })
-
-  return maxValue
-}
-
-/**
- * Finds the numeric extent for a grouped column.
- *
- * Returns `[min, max]`, where each entry is `undefined` when no numeric value is
- * present.
- */
-export function aggregationFn_extent<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  columnId: string,
-  _leafRows: Array<Row<TFeatures, TData>>,
-  childRows: Array<Row<TFeatures, TData>>,
-) {
-  let minValue: number | undefined
-  let maxValue: number | undefined
-
-  childRows.forEach((row) => {
-    const value = row.getValue(columnId)
-    if (value != null && typeof value === 'number') {
-      if (minValue === undefined) {
-        minValue = maxValue = value
-      } else {
-        if (minValue > value) minValue = value
-        if (maxValue! < value) maxValue = value
-      }
-    }
-  })
-
-  return [minValue, maxValue]
-}
-
-/**
- * Averages numeric leaf-row values for a grouped column.
- *
- * Number-like values are coerced with unary `+`; nullish and non-numeric values
- * are ignored.
- */
-export function aggregationFn_mean<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
-  let count = 0
-  let sumValue = 0
-
-  leafRows.forEach((row) => {
-    const value = row.getValue(columnId)
-    if (value != null && typeof value === 'number') {
-      ++count
-      sumValue += value
-    } else if (value != null) {
-      const numValue = +value
-      if (!Number.isNaN(numValue)) {
-        ++count
-        sumValue += numValue
-      }
-    }
-  })
-
-  if (count) return sumValue / count
-
-  return
-}
-
-/**
- * Computes the median of numeric leaf-row values for a grouped column.
- *
- * All values must be numbers. If any value is non-numeric, or no leaf rows are
- * present, the result is `undefined`.
- */
-export function aggregationFn_median<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
-  if (!leafRows.length) {
-    return
-  }
-
-  const values: Array<number> = new Array(leafRows.length)
-  for (let i = 0; i < leafRows.length; i++) {
-    const v = leafRows[i]!.getValue(columnId)
-    if (typeof v !== 'number') return
-    values[i] = v
-  }
-
-  if (values.length === 1) {
-    return values[0]
-  }
-
-  const mid = Math.floor(values.length / 2)
-  values.sort((a, b) => a - b)
-  return values.length % 2 !== 0
-    ? values[mid]
-    : (values[mid - 1]! + values[mid]!) / 2
-}
-
-/**
- * Collects unique leaf-row values for a grouped column.
- *
- * Values are compared with JavaScript `Set` semantics.
- */
-export function aggregationFn_unique<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
-  const set = new Set<unknown>()
-  for (let i = 0; i < leafRows.length; i++) {
-    set.add(leafRows[i]!.getValue(columnId))
-  }
-  return Array.from(set.values())
-}
-
-/**
- * Counts unique leaf-row values for a grouped column.
- *
- * Values are compared with JavaScript `Set` semantics.
- */
-export function aggregationFn_uniqueCount<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
-  const set = new Set<unknown>()
-  for (let i = 0; i < leafRows.length; i++) {
-    set.add(leafRows[i]!.getValue(columnId))
-  }
-  return set.size
-}
-
-/**
- * Counts the number of leaf rows in the group.
- *
- * The column id is ignored because the result is based only on group size.
- */
-export function aggregationFn_count<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(_columnId: string, leafRows: Array<Row<TFeatures, TData>>) {
-  return leafRows.length
-}
-
-/**
- * The built-in aggregation function registry.
- *
- * Pass this object to grouped row model creation or extend it with custom aggregation functions for grouped columns.
- */
-export const aggregationFns = {
-  sum: aggregationFn_sum,
-  min: aggregationFn_min,
-  max: aggregationFn_max,
-  extent: aggregationFn_extent,
-  mean: aggregationFn_mean,
-  median: aggregationFn_median,
-  unique: aggregationFn_unique,
-  uniqueCount: aggregationFn_uniqueCount,
-  count: aggregationFn_count,
-}
-
-export type BuiltInAggregationFn = keyof typeof aggregationFns