@tanstack/react-table 9.0.0-alpha.8 → 9.0.0-beta.1

package/skills/react/production-readiness/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: react/production-readiness
+description: >
+  Ship-ready optimizations for `@tanstack/react-table` v9: tree-shake the
+  bundle by registering ONLY the `features` you actually use; memoize
+  `features`, `data`, and `columns` for stable identity; replace
+  `(state) => state` with narrow selectors or per-slice
+  `useSelector(table.atoms.<slice>)` subscriptions; and push state-driven
+  re-renders down the tree with `<table.Subscribe>` / `<Subscribe>` so the
+  expensive table body doesn't re-render every time you toggle a sort
+  indicator. Don't over-optimize small tables — the default selector +
+  inline rendering is fine until measured perf demands more.
+type: lifecycle
+library: tanstack-table
+framework: react
+library_version: '9.0.0-alpha.48'
+requires:
+  - setup
+  - state-management
+  - react/table-state
+sources:
+  - TanStack/table:docs/guide/features.md
+  - TanStack/table:docs/framework/react/guide/table-state.md
+  - TanStack/table:examples/react/basic-subscribe/src/main.tsx
+  - TanStack/table:examples/react/basic-external-atoms/src/main.tsx
+  - TanStack/table:examples/react/kitchen-sink/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management` and `tanstack-table/react/table-state`. Read those first — `features` tree-shaking and the atom reactivity model are the foundation; this skill is about _which_ of the patterns introduced there you actually need in production.
+
+## When to optimize
+
+The default `useTable` selector is `(state) => state` — the component re-renders on any state change. That's correct and ergonomic, and for tables with a few hundred rows and basic features it's the right default. Don't reach for `<Subscribe>` walls or per-slice atom subscriptions until you've **measured** a problem (slow keystrokes in a filter input, dropped frames during scrolling, long-running renders). On small tables the optimization noise costs more than it saves.
+
+## Setup — stable references
+
+The biggest single perf win is keeping `features`, `rowModels`, `columns`, and `data` references stable across renders. Internal memoization keys off identity, so a new object every render forces full recomputation.
+
+```tsx
+// ✓ Module scope = stable identity
+const features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
+const rowModels = {
+  sortedRowModel: createSortedRowModel(sortFns),
+  paginatedRowModel: createPaginatedRowModel(),
+}
+const columnHelper = createColumnHelper<typeof features, Person>()
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', { header: 'First' }),
+  columnHelper.accessor('age', { header: 'Age' }),
+])
+
+// Module-scope empty array for the "no data yet" branch.
+const EMPTY: Person[] = []
+
+function MyTable({ data }: { data: Person[] | undefined }) {
+  const table = useTable({
+    features,
+    rowModels,
+    columns,
+    data: data ?? EMPTY,
+  })
+}
+```
+
+## Core Patterns
+
+### 1. Tree-shake `features` to only what you use
+
+Avoid `stockFeatures` in production. A sort-only table is ~6–7kb registered explicitly versus ~15–20kb if you import the whole stock set.
+
+```tsx
+// ✓ Pay only for what you render
+const features = tableFeatures({
+  rowSortingFeature,
+  rowPaginationFeature,
+})
+
+// ✗ Ships filtering, faceting, grouping, pinning, expanding, sizing,
+//   resizing, visibility, ordering, row-selection, row-pinning…
+const features = tableFeatures(stockFeatures)
+```
+
+Source: `docs/guide/features.md`; maintainer guidance.
+
+### 2. Narrow the `useTable` selector
+
+`(state) => state` re-renders the holding component on any state change. If only one component cares about one slice, pass a narrow selector — or pass `() => null` and rely on `<table.Subscribe>` walls inside.
+
+```tsx
+// Narrow to specific slices at the table level.
+const table = useTable({ features, rowModels, columns, data }, (state) => ({
+  sorting: state.sorting,
+  pagination: state.pagination,
+}))
+
+// Or: opt out completely at the top, subscribe surgically inside.
+const table = useTable(opts, () => null)
+```
+
+Source: `examples/react/basic-subscribe/src/main.tsx` (uses `() => null`).
+
+### 3. Push re-renders down with `<table.Subscribe>`
+
+A noisy footer that re-renders on every keystroke in a filter doesn't need to re-render the whole `<TableBody>`. Wrap each consumer in `<table.Subscribe>` with its own selector.
+
+```tsx
+function MyTable({ data, columns }) {
+  const table = useTable(
+    { features, rowModels, columns, data },
+    () => null, // top-level opt-out
+  )
+  return (
+    <>
+      <TableBody table={table} /> {/* heavy — keep stable */}
+      {/* Footer re-renders only on pagination changes */}
+      <table.Subscribe selector={(s) => s.pagination}>
+        {(pagination) => <PageFooter pagination={pagination} table={table} />}
+      </table.Subscribe>
+    </>
+  )
+}
+```
+
+Source: `examples/react/basic-subscribe/src/main.tsx`.
+
+### 4. Per-slice `useSelector(table.atoms.<slice>)` for narrowest scope
+
+Even narrower than `<table.Subscribe>`: subscribe a leaf component to a single atom. Skips constructing a state snapshot entirely.
+
+```tsx
+import { useSelector } from '@tanstack/react-store'
+
+function SelectedCount({ table }) {
+  // Re-renders ONLY when rowSelection changes — not sorting / pagination / etc.
+  const selection = useSelector(table.atoms.rowSelection)
+  return <span>{Object.keys(selection).length} selected</span>
+}
+```
+
+Source: `examples/react/basic-external-atoms/src/main.tsx`.
+
+### 5. React Compiler — read state via `<Subscribe>` in nested components
+
+The compiler can't see through the `table` closure, so reads via builder APIs (`column.getIsPinned()`, `row.getIsSelected()`) in memoized child components go stale. Wrap them in `<Subscribe>` (see `tanstack-table/react/react-subscribe-compiler-compat`).
+
+### 6. Virtualization in the deepest possible component
+
+Keep `useVirtualizer` in the deepest component (`TableBody`, not `App`). Any state change in the holder of the virtualizer re-runs it and tanks scroll perf. See `tanstack-table/react/compose-with-tanstack-virtual`.
+
+## Common Mistakes
+
+### HIGH Using `stockFeatures` in production
+
+Wrong:
+
+```tsx
+import { useTable, stockFeatures, tableFeatures } from '@tanstack/react-table'
+const features = tableFeatures(stockFeatures) // ships every feature
+```
+
+Correct:
+
+```tsx
+import {
+  useTable,
+  tableFeatures,
+  rowSortingFeature,
+  rowPaginationFeature,
+} from '@tanstack/react-table'
+const features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
+```
+
+Tree-shaking via `features` is one of the headline reasons for the v9 rewrite. `stockFeatures` exists for migration / "everything on" smoke tests, not production.
+Source: maintainer guidance; `docs/guide/features.md`.
+
+### HIGH Unstable `features` / `rowModels` / `columns` references
+
+Wrong:
+
+```tsx
+function MyTable({ data }) {
+  const features = tableFeatures({ rowSortingFeature }) // new every render
+  const rowModels = { sortedRowModel: createSortedRowModel(sortFns) } // new every render
+  const table = useTable({ features, rowModels, columns, data })
+}
+```
+
+Correct:
+
+```tsx
+// Module scope — declared once.
+const features = tableFeatures({ rowSortingFeature })
+const rowModels = { sortedRowModel: createSortedRowModel(sortFns) }
+
+function MyTable({ data }) {
+  const table = useTable({ features, rowModels, columns, data })
+}
+```
+
+Internal memoization keys off identity. A new object every render busts memos and forces full recomputation.
+Source: FAQ #1; `examples/react/basic-use-table/src/main.tsx`.
+
+### HIGH `data={rows ?? []}` in JSX
+
+Wrong:
+
+```tsx
+<MyTable data={query.data?.rows ?? []} columns={columns} />
+```
+
+Correct:
+
+```tsx
+const EMPTY: Person[] = []  // module scope
+
+<MyTable data={query.data?.rows ?? EMPTY} columns={columns} />
+// or memoize the fallback:
+const data = React.useMemo(() => query.data?.rows ?? [], [query.data])
+```
+
+The `?? []` produces a new array identity each render, busting internal memos that depend on `data` reference.
+Source: `examples/react/with-tanstack-query/src/main.tsx`.
+
+### MEDIUM Leaving `(state) => state` when only one component cares
+
+Wrong:
+
+```tsx
+// Default selector — whole tree re-renders on every state change.
+const table = useTable(opts)
+return <DeeplyNestedTable table={table} />
+```
+
+Correct:
+
+```tsx
+const table = useTable(opts, () => null)
+return (
+  <>
+    <TableBody table={table} />
+    <table.Subscribe selector={(s) => s.pagination}>
+      {(p) => <PageFooter pagination={p} />}
+    </table.Subscribe>
+  </>
+)
+```
+
+Once you've measured a problem, narrow the top selector and add `<table.Subscribe>` walls around the components that actually need state.
+Source: `examples/react/basic-subscribe/src/main.tsx`.
+
+### MEDIUM Subscribing to the whole `table.store` when a single atom would do
+
+Wrong:
+
+```tsx
+<table.Subscribe selector={(s) => s.rowSelection}>
+  {(rs) => <span>{Object.keys(rs).length} selected</span>}
+</table.Subscribe>
+```
+
+Correct:
+
+```tsx
+import { useSelector } from '@tanstack/react-store'
+
+function SelectedCount({ table }) {
+  const selection = useSelector(table.atoms.rowSelection)
+  return <span>{Object.keys(selection).length} selected</span>
+}
+```
+
+`<table.Subscribe>` still selects from `table.state` (the full state). For a single slice, `useSelector(table.atoms.X)` skips even constructing the snapshot.
+Source: `docs/framework/react/guide/table-state.md`.
+
+### MEDIUM Hoisting heavy table state reads above virtualizers
+
+Wrong:
+
+```tsx
+function App() {
+  const rowVirtualizer = useVirtualizer({
+    /* … */
+  }) // virtualizer too high
+  const table = useTable(opts)
+  return <TableBody table={table} virtualizer={rowVirtualizer} />
+}
+```
+
+Correct:
+
+```tsx
+function App() {
+  const tableContainerRef = React.useRef<HTMLDivElement>(null)
+  const table = useTable(opts)
+  return (
+    <div ref={tableContainerRef} style={{ overflow: 'auto', height: 800 }}>
+      <TableBody table={table} tableContainerRef={tableContainerRef} />
+    </div>
+  )
+}
+function TableBody({ table, tableContainerRef }) {
+  const rowVirtualizer = useVirtualizer({
+    /* … */
+  }) // virtualizer at the bottom
+  /* … */
+}
+```
+
+The virtualizer in the deepest component avoids re-running on unrelated state changes.
+Source: `examples/react/virtualized-rows/src/main.tsx`.
+
+### MEDIUM Premature `<Subscribe>` / narrow selectors on small tables
+
+Wrong:
+
+```tsx
+// 50-row table with Subscribe around every cell.
+header: ({ table }) => (
+  <Subscribe source={table.store} selector={(s) => s.sorting}>
+    {() => <SortHeader />}
+  </Subscribe>
+)
+```
+
+Correct:
+
+```tsx
+const table = useTable({ features, rowModels, columns, data })
+// Reach for Subscribe later, scoped to actual hotspots.
+```
+
+Advanced state-management patterns are for advanced cases. On small tables the boundary churn costs more than it saves.
+Source: maintainer guidance (Phase 4).
+
+## See Also
+
+- `tanstack-table/react/table-state` — the API surface this skill optimizes against.
+- `tanstack-table/react/react-subscribe-compiler-compat` — required reading if React Compiler is on.
+- `tanstack-table/react/compose-with-tanstack-store` — fine-grained subscriptions via external atoms.
+- `tanstack-table/react/compose-with-tanstack-virtual` — row/column virtualization patterns.
+- `tanstack-table/react/compose-with-tanstack-devtools` — `/production` import for live devtools in prod.

package/skills/react/react-subscribe-compiler-compat/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: react/react-subscribe-compiler-compat
+description: >
+  React Compiler compatibility for `@tanstack/react-table` v9. When you read
+  table state via builder APIs (`column.getIsPinned()`, `row.getIsSelected()`,
+  `cell.getIsAggregated()`, `header.column.getIsSorted()`) inside a nested
+  custom component, React Compiler memoizes the child against the stable
+  `column` / `row` / `cell` reference and never re-runs when the underlying
+  atom changes. Symptom: stale checkboxes, frozen sort indicators, dead pin
+  buttons. Fix: wrap the JSX in `<Subscribe source={table.store} selector={…}>`
+  or `<Subscribe source={table.atoms.X}>` so the dependency is visible to the
+  compiler. Routing keywords: Subscribe, table.Subscribe, React Compiler,
+  stale checkbox, memoized header/cell, builder API.
+type: framework
+library: tanstack-table
+framework: react
+library_version: '9.0.0-alpha.48'
+requires:
+  - react/table-state
+sources:
+  - TanStack/table:docs/framework/react/guide/table-state.md
+  - TanStack/table:packages/react-table/src/Subscribe.ts
+  - TanStack/table:examples/react/basic-subscribe/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management` and `tanstack-table/react/table-state`. Read those first — the atom model is what makes builder reads invisible to React Compiler, and `table-state` covers the basics of `<Subscribe>` / `<table.Subscribe>`. This skill is laser-focused on the **one** React-specific failure mode that comes up when React Compiler is enabled.
+
+## Why this exists
+
+Under React Compiler, JSX is memoized against the props your component receives. A custom `DraggableHeader({ header })` receives a stable `header` reference; the compiler hashes the JSX it produces against that reference. When you call `header.column.getIsPinned()` inside that component, the compiler **cannot see the atom read** hidden behind the method — it returns the cached JSX, and the UI goes stale.
+
+The fix is to make the dependency visible: read the slice via `<Subscribe>` or `<table.Subscribe>`. The compiler sees the selector function, picks up the dependency edge, and re-runs the children whenever the subscribed slice changes.
+
+## Setup
+
+You only need `<Subscribe>` from `@tanstack/react-table`. It's the same component shown in `table-state`, applied specifically around builder-pattern reads in custom nested components.
+
+```tsx
+import { Subscribe } from '@tanstack/react-table'
+```
+
+## Core Pattern: wrap nested builder reads in `<Subscribe>`
+
+Whenever a child component reads state via a builder method (`getIs*`, `getCan*`, etc.) inside JSX that the compiler memoizes, wrap it in `<Subscribe>` keyed on the relevant slice.
+
+### Pin / sort indicator on a custom header component
+
+```tsx
+import { Subscribe } from '@tanstack/react-table'
+
+function DraggableHeader({ header, table }) {
+  return (
+    <Subscribe
+      source={table.store}
+      selector={(s) => ({ columnPinning: s.columnPinning, sorting: s.sorting })}
+    >
+      {() => {
+        // Reads run inside the Subscribe child — re-evaluated on selected slice changes.
+        const isPinned = header.column.getIsPinned()
+        const sortDir = header.column.getIsSorted()
+        return (
+          <th data-pinned={isPinned}>
+            {header.column.id}
+            {sortDir === 'asc' ? ' 🔼' : sortDir === 'desc' ? ' 🔽' : null}
+          </th>
+        )
+      }}
+    </Subscribe>
+  )
+}
+```
+
+Source: `docs/framework/react/guide/table-state.md` (Subscribe for React Compiler Compatibility); `packages/react-table/src/Subscribe.ts`.
+
+### Row-selection checkbox inside a cell — narrowest subscription
+
+```tsx
+columnHelper.display({
+  id: 'select',
+  cell: ({ row, table }) => (
+    // Subscribe to the rowSelection ATOM (not table.store) and project to ONE row.
+    // Re-renders ONLY when this row's selection flips.
+    <Subscribe
+      source={table.atoms.rowSelection}
+      selector={(rowSelection) => rowSelection[row.id]}
+    >
+      {(isSelected) => (
+        <input
+          type="checkbox"
+          checked={!!isSelected}
+          disabled={!row.getCanSelect()}
+          indeterminate={row.getIsSomeSelected()}
+          onChange={row.getToggleSelectedHandler()}
+        />
+      )}
+    </Subscribe>
+  ),
+})
+```
+
+Source: `examples/react/basic-subscribe/src/main.tsx` (this exact pattern).
+
+### Component-level vs cell-level — which API
+
+| Context                                                      | `table` is                     | API                                                                          |
+| ------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------- |
+| Component receiving `table` from `useTable`                  | `ReactTable<…>`                | `<table.Subscribe>` works                                                    |
+| Inside `cell: ({ table }) => …` / `header: ({ table }) => …` | core `Table<TFeatures, TData>` | `table.Subscribe` is **undefined**. Use the standalone `<Subscribe>` import. |
+
+## Common Mistakes
+
+### CRITICAL Builder read in a nested component without `<Subscribe>`
+
+Wrong:
+
+```tsx
+function DraggableHeader({ header }) {
+  const isPinned = header.column.getIsPinned() // hidden atom read
+  return <th data-pinned={isPinned}>{header.column.id}</th>
+}
+```
+
+Correct:
+
+```tsx
+import { Subscribe } from '@tanstack/react-table'
+
+function DraggableHeader({ header, table }) {
+  return (
+    <Subscribe source={table.store} selector={(s) => s.columnPinning}>
+      {() => {
+        const isPinned = header.column.getIsPinned()
+        return <th data-pinned={isPinned}>{header.column.id}</th>
+      }}
+    </Subscribe>
+  )
+}
+```
+
+React Compiler memoizes the child's JSX against the stable `header` reference. The state-dependent builder method hides its atom dependency, so the memoized JSX never re-runs.
+Source: `docs/framework/react/guide/table-state.md`; `examples/react/basic-subscribe/src/main.tsx`; `packages/react-table/src/Subscribe.ts`.
+
+### HIGH Using `table.Subscribe` from inside a cell or header definition
+
+Wrong:
+
+```tsx
+cell: ({ row, table }) => (
+  <table.Subscribe
+    source={table.atoms.rowSelection}
+    selector={(s) => s[row.id]}
+  >
+    {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
+  </table.Subscribe>
+)
+```
+
+Correct:
+
+```tsx
+import { Subscribe } from '@tanstack/react-table'
+
+cell: ({ row, table }) => (
+  <Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
+    {(isSelected) => (
+      <input
+        type="checkbox"
+        checked={!!isSelected}
+        onChange={row.getToggleSelectedHandler()}
+      />
+    )}
+  </Subscribe>
+)
+```
+
+Cell and header render contexts type `table` as `Table<TFeatures, TData>`, not `ReactTable` — `table.Subscribe` is undefined. Import the standalone `<Subscribe>`.
+Source: `docs/framework/react/guide/table-state.md` (Tips); `packages/react-table/src/Subscribe.ts`.
+
+### MEDIUM Wrapping every cell in `<Subscribe>` by default
+
+Wrong:
+
+```tsx
+// Inline cell that already re-runs on every parent render — wrap is unnecessary.
+{
+  row.getVisibleCells().map((cell) => (
+    <Subscribe source={table.store} selector={(s) => s.rowSelection}>
+      {() => (
+        <td>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
+      )}
+    </Subscribe>
+  ))
+}
+```
+
+Correct:
+
+```tsx
+{
+  row.getVisibleCells().map((cell) => (
+    <td key={cell.id}>
+      <table.FlexRender cell={cell} />
+    </td>
+  ))
+}
+```
+
+`<Subscribe>` is overhead. For inline JSX in the parent component the compiler always re-evaluates on parent re-render, so wrapping adds subscription churn without correctness benefit. Reach for `<Subscribe>` only at custom-component boundaries that the compiler memoizes.
+Source: `docs/framework/react/guide/table-state.md`.
+
+### MEDIUM Subscribing to the whole `table.store` for one row's checkbox
+
+Wrong:
+
+```tsx
+<Subscribe source={table.store} selector={(s) => s.rowSelection[row.id]}>
+  {(isSelected) => <input type="checkbox" checked={!!isSelected} />}
+</Subscribe>
+```
+
+Correct:
+
+```tsx
+<Subscribe source={table.atoms.rowSelection} selector={(s) => s[row.id]}>
+  {(isSelected) => (
+    <input
+      type="checkbox"
+      checked={!!isSelected}
+      onChange={row.getToggleSelectedHandler()}
+    />
+  )}
+</Subscribe>
+```
+
+Every change to `table.store` re-runs the Subscribe child. Subscribing to `table.atoms.rowSelection` (a single slice atom) with a per-row projection limits work to actual selection changes for that row.
+Source: `examples/react/basic-subscribe/src/main.tsx`; `docs/framework/react/guide/table-state.md` (Tips).
+
+### CRITICAL Reading raw state with `table.getState()` on v9 instead of `<Subscribe>`
+
+Wrong:
+
+```tsx
+function Toolbar({ table }) {
+  // v8 muscle memory — does NOT subscribe in v9.
+  const { rowSelection } = table.getState()
+  return <div>{Object.keys(rowSelection).length} selected</div>
+}
+```
+
+Correct:
+
+```tsx
+function Toolbar({ table }) {
+  return (
+    <table.Subscribe selector={(s) => Object.keys(s.rowSelection).length}>
+      {(count) => <div>{count} selected</div>}
+    </table.Subscribe>
+  )
+}
+```
+
+`table.getState()` is a current-value read in v9; it does not subscribe the component. The default `useTable` selector subscribes the parent, but deeply-nested children should opt in explicitly.
+Source: PR #6246; `packages/react-table/src/useTable.ts` JSDoc.
+
+## See Also
+
+- `tanstack-table/react/table-state` — base `<Subscribe>` / `<table.Subscribe>` API and external atoms.
+- `tanstack-table/react/production-readiness` — selector narrowing and per-slice `useSelector(table.atoms.X)`.
+- `tanstack-table/react/migrate-v8-to-v9` — replacing `useReactTable` with `useTable` to fix the React Compiler "incompatible library" warning.