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

package/skills/row-selection/SKILL.md

@@ -1,391 +1,174 @@
 ---
 name: row-selection
 description: >
-  Track which rows are selected in TanStack Table v9 via
-  `rowSelection: Record<rowId, boolean | undefined>`. Covers `rowSelectionFeature`,
-  the three selected-row APIs (`getSelectedRowModel`, `getFilteredSelectedRowModel`,
-  `getGroupedSelectedRowModel`), `row.toggleSelected` / `getIsSelected` /
-  `getIsSomeSelected` (indeterminate) / `getCanSelect` / `getCanMultiSelect`,
-  `row.getToggleSelectedHandler`, header APIs (`getIsAllRowsSelected` /
-  `getIsSomeRowsSelected` / `getToggleAllRowsSelectedHandler` and the page-aware
-  variants), `enableRowSelection` (bool or predicate),
-  `enableMultiRowSelection: false` for radio-style, `enableSubRowSelection`,
-  and why `getRowId` is essentially mandatory — especially under server pagination.
-type: core
-library: tanstack-table
-library_version: '9.0.0-alpha.48'
-requires:
-  - state-management
-  - column-definitions
+  Maintain rowSelection ID state with stable getRowId, single, multi, subrow, and Shift-range rules, selected row models, handler anchors, and manual-pagination semantics. Load when implementing getToggleSelectedHandler, enableRowRangeSelection, selectChildren, deselectParents, or selected IDs that outlive loaded Row objects.
+metadata:
+  { type: sub-skill, library: '@tanstack/table-core', library_version: '9.0.0' }
+requires: ['core', 'table-features']
 sources:
-  - TanStack/table:docs/guide/row-selection.md
-  - TanStack/table:packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts
-  - TanStack/table:packages/table-core/src/features/row-selection/rowSelectionFeature.types.ts
-  - TanStack/table:examples/react/row-selection/src/main.tsx
+  - 'TanStack/table:docs/framework/react/guide/row-selection.md'
+  - 'TanStack/table:packages/table-core/src/features/row-selection'
+  - 'TanStack/table:examples/react/row-selection'
 ---
 
-This skill builds on `tanstack-table/state-management` and `tanstack-table/column-definitions`. Read those first for state ownership and `getRowId`.
+This skill builds on `core` and `table-features`. Selection is independent ID state; selected row models can only materialize loaded rows.
 
 ## Setup
 
 ```ts
 import {
-  tableFeatures,
   rowSelectionFeature,
-  constructTable,
+  tableFeatures,
+  type Row,
 } from '@tanstack/table-core'
-import type { RowSelectionState } from '@tanstack/table-core'
-
-const features = tableFeatures({ rowSelectionFeature })
-
-const table = constructTable({
-  features,
-  rowModels: {},
-  columns,
-  data,
-  getRowId: (row) => row.id, // ← essentially mandatory
-  initialState: { rowSelection: {} satisfies RowSelectionState },
-  enableRowSelection: true,
-})
-```
-
-## Core Patterns
-
-### Select column with header "select all" + per-row checkbox
-
-```tsx
-// From examples/react/row-selection/src/main.tsx
-columnHelper.display({
-  id: 'select',
-  header: ({ table }) => (
-    <Checkbox
-      checked={table.getIsAllRowsSelected()}
-      indeterminate={table.getIsSomeRowsSelected()}
-      onChange={table.getToggleAllRowsSelectedHandler()}
-    />
-  ),
-  cell: ({ row }) => (
-    <Checkbox
-      checked={row.getIsSelected()}
-      indeterminate={row.getIsSomeSelected()}
-      disabled={!row.getCanSelect()}
-      onChange={row.getToggleSelectedHandler()}
-    />
-  ),
-}),
-```
 
-### Single-select (radio-style)
-
-```tsx
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature }),
-  rowModels: {},
-  columns,
-  data,
-  getRowId: (row) => row.id,
-  enableMultiRowSelection: false, // ← radio-like
-})
-
-// Cell renders a radio, no "select all" header makes sense
-columnHelper.display({
-  id: 'select',
-  header: '', // no select-all in single-select mode
-  cell: ({ row }) => (
-    <input
-      type="radio"
-      name="row-selection"
-      checked={row.getIsSelected()}
-      disabled={!row.getCanSelect()}
-      onChange={row.getToggleSelectedHandler()}
-    />
-  ),
-})
+type Person = { id: string; name: string }
+export const features = tableFeatures({ rowSelectionFeature })
+export const options = {
+  getRowId: (row: Person) => row.id,
+  enableSubRowSelection: false,
+}
 ```
 
-### Conditional selection per row
+## Core Patterns
 
 ```ts
-const table = useTable({
-  features,
-  columns,
-  data,
-  getRowId: (row) => row.id,
-  enableRowSelection: (row) => row.original.age > 18, // predicate form
-})
+const selectedIds = table.getSelectedRowIds()
+const loadedSelectedRows = table.getSelectedRowModel().rows
 ```
 
-### Three selected-row APIs
+Use IDs for database-wide intent and row models for currently loaded objects.
+
+### Inclusive Shift ranges through the row handler
 
 ```ts
-table.getSelectedRowModel() // built off core — raw data
-table.getFilteredSelectedRowModel() // built off filtered — current filters applied
-table.getGroupedSelectedRowModel() // built off grouped — current groups applied
+export function getSelectionHandler(row: Row<typeof features, Person>) {
+  return row.getToggleSelectedHandler()
+}
 ```
 
-### Hoist selection to an external atom
-
-```tsx
-import { useCreateAtom } from '@tanstack/react-store'
+The handler establishes a table-local anchor on ordinary interactions and applies the checked value to the inclusive current display-order range on Shift interactions. Range behavior is enabled by default; set `enableRowRangeSelection: false` to preserve non-range handler behavior. Direct `row.toggleSelected()` and `table.setRowSelection()` calls do not move that anchor.
 
-const rowSelectionAtom = useCreateAtom<RowSelectionState>({})
+Pass the original checkbox click event to this handler. DOM `change` events often omit modifier keys, so use the framework's click binding for row checkboxes unless its change event exposes the original click through `nativeEvent` (as React does).
 
-const table = useTable({
-  features,
-  columns,
-  data,
-  getRowId: (row) => row.id,
-  atoms: { rowSelection: rowSelectionAtom },
-})
+### Limit a range to explicitly displayed rows
 
-// Send selected IDs to an API call from a sibling component
-function ExportButton() {
-  const selection = useStore(rowSelectionAtom)
-  return (
-    <button onClick={() => api.export(Object.keys(selection))}>Export</button>
-  )
+```ts
+export function getDisplayedRowsOnlyHandler(row: Row<typeof features, Person>) {
+  return row.getToggleSelectedHandler({ selectChildren: false })
 }
 ```
 
-## Common Mistakes
-
-### [HIGH] Omitting `getRowId` under `manualPagination`
+The default `selectChildren: true` recursively changes selectable descendants of parents encountered in the range. Set it to `false` when collapsed descendants outside the display-order interval must remain unchanged.
 
-Wrong:
+### Prune stale parent ids on child deselection
 
 ```ts
-// Server-side pagination + default row.id = row.index
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature, rowPaginationFeature }),
-  data, // only current page from server
-  manualPagination: true,
-  rowCount,
-})
-// After paging, rowSelection: { '5': true } is ambiguous
-// — selection appears to move with the user.
+export function getPruningHandler(row: Row<typeof features, Person>) {
+  return row.getToggleSelectedHandler({ deselectParents: true })
+}
 ```
 
-Correct:
+Selecting a parent cascades its id plus selectable descendant ids into state, but deselecting a child later leaves the parent id behind by default (some tables treat state ids as literal selections, e.g. with `selectChildren: false`). The default `deselectParents: false` preserves that; set it to `true` so deselecting any row also deletes every ancestor id, keeping `row.getIsSelected()` honest for parents. Applies to `toggleSelected` and both plain and Shift-range handler paths.
 
-```ts
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature, rowPaginationFeature }),
-  data,
-  manualPagination: true,
-  rowCount,
-  getRowId: (row) => row.uuid, // stable across pages
-})
-
-// For "X of Y selected" with server-side pagination, read state directly:
-const totalSelected = Object.keys(table.state.rowSelection).length
-```
+### Select-all honors sub-row selection rules
 
-`row.id` defaults to `row.index`. Under `manualPagination`, every page reuses indices 0..n-1, so selection IDs collide across pages.
+With `enableSubRowSelection: false` (or a per-row predicate), `table.toggleAllRowsSelected()` skips descendants of blocking parents, and `getIsAllRowsSelected()`/`getIsAllPageRowsSelected()` exclude those descendants from the all-selected computation, so the header checkbox still reads checked. Deselect-all skips rows whose `enableRowSelection` resolves false, preserving their selection; use `toggleAllRowsSelected(false, { deselectAll: true })` or `resetRowSelection(true)` to clear everything including disabled and out-of-model ids.
 
-Source: docs/guide/row-selection.md; examples/react/row-selection/src/main.tsx
-
-### [MEDIUM] `enableMultiRowSelection: false` + a "select all" checkbox header
+## Common Mistakes
 
-Wrong:
+### [HIGH] Expecting selection to clean itself
 
-```tsx
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature }),
-  enableMultiRowSelection: false, // radio-like
-})
-
-// Header still renders a checkbox + indeterminate
-<Checkbox
-  checked={table.getIsAllRowsSelected()}
-  indeterminate={table.getIsSomeRowsSelected()}
-  onChange={table.getToggleAllRowsSelectedHandler()}
-/>
-```
+Wrong: `data = data.filter(row => row.id !== deletedId)`
 
-Correct:
+Correct: `data = data.filter(row => row.id !== deletedId); table.setRowSelection(old => { const next = { ...old }; delete next[deletedId]; return next })`
 
-```tsx
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature }),
-  enableMultiRowSelection: false,
-  getRowId: (row) => row.id,
-})
-
-// Drop the toggle-all header in single-select mode
-columnHelper.display({
-  id: 'select',
-  header: '',
-  cell: ({ row }) => (
-    <input
-      type="radio"
-      name="row-selection"
-      checked={row.getIsSelected()}
-      disabled={!row.getCanSelect()}
-      onChange={row.getToggleSelectedHandler()}
-    />
-  ),
-})
-```
+Selection is independent state and can retain IDs after data removal.
 
-In single-select mode, `mutateRowIsSelected` clears all other ids before adding the new one. "Select all" becomes effectively no-op and indeterminate is meaningless.
+Source: `https://github.com/TanStack/table/issues/5850`
 
-Source: docs/guide/row-selection.md; packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts
+### [HIGH] Selecting mutable indexes
 
-### [HIGH] `getSelectedRowModel().flatRows` for counts under `manualPagination`
+Wrong: `const options = { getRowId: (_row: Person, index: number) => String(index) }`
 
-Wrong:
+Correct: `const options = { getRowId: (row: Person) => row.id }`
 
-```ts
-// Under manualPagination, only counts the visible page's selected rows
-const selectedCount = table.getSelectedRowModel().flatRows.length
+Stable application IDs preserve identity as row order and pages change.
 
-const handleBulkAction = () => {
-  const ids = table.getSelectedRowModel().flatRows.map((row) => row.original.id)
-  api.archive(ids) // missing all selections from other pages!
-}
-```
+Source: `docs/framework/react/guide/row-selection.md#useful-row-ids`
 
-Correct:
+### [HIGH] Treating loaded model as global selection
 
-```ts
-// For counts and id lists under manualPagination, read state directly
-const selectedCount = Object.keys(table.state.rowSelection).length
+Wrong: `const allSelectedRecords = table.getSelectedRowModel().rows`
 
-const handleBulkAction = () => {
-  const ids = Object.keys(table.state.rowSelection)
-  api.archive(ids)
-}
-// (Client-side: getSelectedRowModel is fine — data contains every row.)
-```
+Correct: `const allSelectedIds = table.getSelectedRowIds()`
 
-`getSelectedRowModel` walks the core row model — which under `manualPagination` only contains the current page. `state.rowSelection` may contain ids that aren't in `data` (that's by design).
+Under manual pagination, unloaded selected IDs have no `Row` object in the current model.
 
-Source: docs/guide/row-selection.md; packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts
+Source: `docs/framework/react/guide/row-selection.md#note-if-you-are-using-manualpagination`
 
-### [MEDIUM] Surprise sub-row propagation from `enableSubRowSelection` default
+### [HIGH] Bypassing the range-selection handler
 
 Wrong:
 
 ```ts
-// Default behavior: clicking the parent selects all children
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature, rowExpandingFeature }),
-  getSubRows: (row) => row.subRows,
-  // enableSubRowSelection unset — defaults to true
-})
+const onChange = (event: { target: { checked: boolean } }) =>
+  row.toggleSelected(event.target.checked)
 ```
 
 Correct:
 
 ```ts
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature, rowExpandingFeature }),
-  getSubRows: (row) => row.subRows,
-  enableSubRowSelection: false, // toggling parent doesn't touch subRows
-})
-
-// Or selectively:
-enableSubRowSelection: (row) => row.depth > 0,
-
-// Indeterminate parent checkbox
-<Checkbox
-  checked={row.getIsSelected()}
-  indeterminate={row.getIsSomeSelected()} // 'some' descendants selected
-  disabled={!row.getCanSelect()}
-  onChange={row.getToggleSelectedHandler()}
-/>
+const onChange = row.getToggleSelectedHandler()
 ```
 
-`enableSubRowSelection: true` is the default. `mutateRowIsSelected` recurses into `row.subRows` when truthy. Decide deliberately — "select group as a whole" UX wants this off.
+Only successful interactions through `getToggleSelectedHandler()` establish or advance the Shift-range anchor. The handler also supports custom range-event detection through `isRowRangeSelectionEvent`.
 
-Source: docs/guide/row-selection.md; packages/table-core/src/features/row-selection/rowSelectionFeature.utils.ts
+Source: `docs/framework/react/guide/row-selection.md#shift-range-selection`
 
-### [HIGH] Parent checkbox stuck "unchecked" with all sub-rows selected (deep trees)
+### [HIGH] Binding a DOM change event that drops Shift
 
 Wrong:
 
 ```ts
-// Returns false even when all leaf descendants are selected
-const isParentChecked = row.getIsAllSubRowsSelected()
+checkbox.addEventListener('change', row.getToggleSelectedHandler())
 ```
 
 Correct:
 
 ```ts
-const allLeafs = row.getLeafRows()
-const allSelected =
-  allLeafs.length > 0 && allLeafs.every((r) => r.getIsSelected())
-const someSelected = allLeafs.some((r) => r.getIsSelected())
+checkbox.addEventListener('click', row.getToggleSelectedHandler())
 ```
 
-`getIsAllSubRowsSelected` only counts direct children. With multi-level grouping, a parent reports based on a partial count.
+The range modifier must be present on the event passed to the handler. Raw DOM `change` events do not reliably expose click modifier keys.
 
-Source: https://github.com/TanStack/table/issues/4878; https://github.com/TanStack/table/issues/4759
+Source: `docs/framework/svelte/guide/row-selection.md#shift-range-selection`
 
-### [HIGH] Stale rowSelection IDs after data refresh
+### [MEDIUM] Expecting ranges across unloaded server pages
 
 Wrong:
 
 ```ts
-useEffect(() => {
-  refreshData() // selection still references deleted IDs
-}, [trigger])
+const options = {
+  manualPagination: true,
+  enableRowRangeSelection: true,
+}
+// Shift cannot select rows absent from data.
 ```
 
 Correct:
 
 ```ts
-useEffect(() => {
-  setRowSelection((prev) => {
-    const validIds = new Set(data.map((row) => row.id))
-    const next: RowSelectionState = {}
-    for (const id in prev) if (validIds.has(id)) next[id] = prev[id]
-    return next
-  })
-}, [data])
-```
-
-v8 removed v7's `autoResetSelectedRows`. With websockets / refetch, IDs that no longer exist remain in `rowSelection` and `getIsAllRowsSelected()` returns true based on stale state. Prune yourself.
-
-Source: https://github.com/TanStack/table/issues/5850; https://github.com/TanStack/table/issues/4498
-
-### [CRITICAL] Reimplementing selection state manually
-
-Wrong:
-
-```ts
-// Hand-rolled "selected" set, bypassing the table
-const [selected, setSelected] = useState(new Set<string>())
-const toggle = (id: string) => {
-  setSelected((s) => {
-    const next = new Set(s)
-    next.has(id) ? next.delete(id) : next.add(id)
-    return next
-  })
+const options = {
+  manualPagination: true,
+  getRowId: (row: Person) => row.id,
 }
 ```
 
-Correct:
-
-```ts
-const table = useTable({
-  features: tableFeatures({ rowSelectionFeature }),
-  rowModels: {},
-  columns,
-  data,
-  getRowId: (row) => row.id,
-})
-row.toggleSelected()
-row.toggleSelected(true)
-table.toggleAllRowsSelected()
-table.setRowSelection({ abc: true })
-```
+Client-side ranges can cross pages because display order is pre-pagination. Manual/server pagination cannot include rows absent from the loaded `data`; select database-wide IDs in application state when that behavior is required.
 
-Source: maintainer interview (Phase 4, 2026-05-17)
+Source: `docs/framework/react/guide/row-selection.md#shift-range-selection`, `https://github.com/TanStack/table/issues/4781`
 
-## See also
+## API Discovery
 
-- `tanstack-table/column-definitions` — `getRowId` is the foundation of every row-keyed feature
-- `tanstack-table/state-management` — `rowSelection` slice + atoms for sharing selection
-- `tanstack-table/pagination` — server-pagination "select all" pitfalls
-- `tanstack-table/grouping` — `getGroupedSelectedRowModel` distinction
+Inspect `node_modules/@tanstack/table-core/dist/features/row-selection/` for state, row-model variants, and selection enablement callbacks.