@tanstack/table-core 9.0.0-beta.42 → 9.0.0-beta.44

package/skills/row-selection/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: row-selection
 description: >
-  Maintain rowSelection ID state with stable getRowId, single, multi, and subrow rules, selected row models, and manual-pagination semantics. Load when selected IDs outlive loaded Row objects or data removal.
+  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, or selected IDs that outlive loaded Row objects.
 metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.42',
+    library_version: '9.0.0-beta.44',
   }
 requires: ['core', 'table-features']
 sources:
@@ -20,7 +20,11 @@ This skill builds on `core` and `table-features`. Selection is independent ID st
 ## Setup
 
 ```ts
-import { rowSelectionFeature, tableFeatures } from '@tanstack/table-core'
+import {
+  rowSelectionFeature,
+  tableFeatures,
+  type Row,
+} from '@tanstack/table-core'
 
 type Person = { id: string; name: string }
 export const features = tableFeatures({ rowSelectionFeature })
@@ -39,6 +43,28 @@ const loadedSelectedRows = table.getSelectedRowModel().rows
 
 Use IDs for database-wide intent and row models for currently loaded objects.
 
+### Inclusive Shift ranges through the row handler
+
+```ts
+export function getSelectionHandler(row: Row<typeof features, Person>) {
+  return row.getToggleSelectedHandler()
+}
+```
+
+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.
+
+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).
+
+### Limit a range to explicitly displayed rows
+
+```ts
+export function getDisplayedRowsOnlyHandler(row: Row<typeof features, Person>) {
+  return row.getToggleSelectedHandler({ selectChildren: false })
+}
+```
+
+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.
+
 ## Common Mistakes
 
 ### [HIGH] Expecting selection to clean itself
@@ -71,6 +97,68 @@ Under manual pagination, unloaded selected IDs have no `Row` object in the curre
 
 Source: `docs/framework/react/guide/row-selection.md#note-if-you-are-using-manualpagination`
 
+### [HIGH] Bypassing the range-selection handler
+
+Wrong:
+
+```ts
+const onChange = (event: { target: { checked: boolean } }) =>
+  row.toggleSelected(event.target.checked)
+```
+
+Correct:
+
+```ts
+const onChange = row.getToggleSelectedHandler()
+```
+
+Only successful interactions through `getToggleSelectedHandler()` establish or advance the Shift-range anchor. The handler also supports custom range-event detection through `isRowRangeSelectionEvent`.
+
+Source: `docs/framework/react/guide/row-selection.md#shift-range-selection`
+
+### [HIGH] Binding a DOM change event that drops Shift
+
+Wrong:
+
+```ts
+checkbox.addEventListener('change', row.getToggleSelectedHandler())
+```
+
+Correct:
+
+```ts
+checkbox.addEventListener('click', row.getToggleSelectedHandler())
+```
+
+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: `docs/framework/svelte/guide/row-selection.md#shift-range-selection`
+
+### [MEDIUM] Expecting ranges across unloaded server pages
+
+Wrong:
+
+```ts
+const options = {
+  manualPagination: true,
+  enableRowRangeSelection: true,
+}
+// Shift cannot select rows absent from data.
+```
+
+Correct:
+
+```ts
+const options = {
+  manualPagination: true,
+  getRowId: (row: Person) => row.id,
+}
+```
+
+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: `docs/framework/react/guide/row-selection.md#shift-range-selection`, `https://github.com/TanStack/table/issues/4781`
+
 ## API Discovery
 
 Inspect `node_modules/@tanstack/table-core/src/features/row-selection/` for state, row-model variants, and selection enablement callbacks.

package/skills/sorting/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.42',
+    library_version: '9.0.0-beta.44',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/table-features/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: sub-skill
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.42'
+  library_version: '9.0.0-beta.44'
 requires: ['core']
 sources:
   - 'TanStack/table:docs/guide/row-models.md'

package/skills/typescript/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: sub-skill
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.42'
+  library_version: '9.0.0-beta.44'
 requires: ['core', 'table-features']
 sources:
   - 'TanStack/table:docs/guide/helpers.md'

package/src/core/rows/constructRow.ts

@@ -48,6 +48,7 @@ export const constructRow = <
   >
 
   // Only assign instance-specific properties
+  row._displayIndexCache = -1
   row._uniqueValuesCache = makeObjectMap()
   row._valuesCache = makeObjectMap()
   row.depth = depth

package/src/core/rows/coreRowsFeature.ts

@@ -2,6 +2,7 @@ import { assignPrototypeAPIs, assignTableAPIs } from '../../utils'
 import {
   row_getAllCells,
   row_getAllCellsByColumnId,
+  row_getDisplayIndex,
   row_getLeafRows,
   row_getParentRow,
   row_getParentRows,
@@ -10,6 +11,7 @@ import {
   row_renderValue,
   table_getRow,
   table_getRowId,
+  table_getRowsInDisplayOrder,
 } from './coreRowsFeature.utils'
 import type { TableFeature } from '../../types/TableFeatures'
 
@@ -19,6 +21,9 @@ import type { TableFeature } from '../../types/TableFeatures'
 export const coreRowsFeature: TableFeature = {
   assignRowPrototype: (prototype, table) => {
     assignPrototypeAPIs('coreRowsFeature', prototype, table, {
+      row_getDisplayIndex: {
+        fn: (row) => row_getDisplayIndex(row),
+      },
       row_getAllCellsByColumnId: {
         fn: (row) => row_getAllCellsByColumnId(row),
         memoDeps: (row) => [row.getAllCells()],
@@ -50,6 +55,16 @@ export const coreRowsFeature: TableFeature = {
   },
   constructTableAPIs: (table) => {
     assignTableAPIs('coreRowsFeature', table, {
+      table_getRowsInDisplayOrder: {
+        fn: () => table_getRowsInDisplayOrder(table),
+        memoDeps: () => [
+          table.getPrePaginatedRowModel().rows,
+          table.options.paginateExpandedRows,
+          table.options.paginateExpandedRows === false
+            ? table.atoms.expanded?.get()
+            : undefined,
+        ],
+      },
       table_getRowId: {
         fn: (originalRow, index, parent) =>
           table_getRowId(originalRow, table, index, parent),

package/src/core/rows/coreRowsFeature.types.ts

@@ -13,6 +13,16 @@ export interface Row_CoreProperties<
     Column<TFeatures, TData, unknown>,
     Cell<TFeatures, TData, unknown>
   >
+  /**
+   * Internal cache used while resolving the current display order.
+   *
+   * This value may be stale until display order is recomputed. Use
+   * `row.getDisplayIndex()` instead; it refreshes and validates the cached
+   * position before returning it.
+   *
+   * @internal
+   */
+  _displayIndexCache: number
   _uniqueValuesCache: Record<string, unknown>
   _valuesCache: Record<string, unknown>
   /**
@@ -53,6 +63,13 @@ export interface Row_Row<
   in out TFeatures extends TableFeatures,
   in out TData extends RowData,
 > extends Row_CoreProperties<TFeatures, TData> {
+  /**
+   * Returns the zero-based index of the row in the current display order
+   * before pagination, or `-1` if the row is not in that model. Use this for
+   * display row-number columns instead of `row.index` or the internal
+   * `_displayIndexCache` field.
+   */
+  getDisplayIndex: () => number
   /**
    * Builds a lookup of this row's cells keyed by leaf column id.
    */
@@ -114,6 +131,13 @@ export interface Table_Rows<
   in out TFeatures extends TableFeatures,
   in out TData extends RowData,
 > {
+  /**
+   * Returns the rows in the current display order and assigns their display
+   * indexes. When expanded rows bypass pagination, expanded descendants are
+   * included in this order. This is the memoized source for
+   * `row.getDisplayIndex()`.
+   */
+  getRowsInDisplayOrder: () => Array<Row<TFeatures, TData>>
   getRowId: (_: TData, index: number, parent?: Row<TFeatures, TData>) => string
   /**
    * Returns the row with the given ID.

package/src/core/rows/coreRowsFeature.utils.ts

@@ -5,6 +5,64 @@ import type { 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 { Row_RowExpanding } from '../../features/row-expanding/rowExpandingFeature.types'
+
+/**
+ * Returns this row's zero-based position in the current pre-pagination row
+ * model. Rows outside that model return `-1`.
+ */
+export function row_getDisplayIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>) {
+  const rows = row.table.getRowsInDisplayOrder()
+  const displayIndex = row._displayIndexCache
+
+  return rows[displayIndex] === row ? displayIndex : -1
+}
+
+/**
+ * Returns the rows in the current display order after assigning their
+ * zero-based display indexes.
+ *
+ * When expanded rows bypass pagination, expanded descendants are inserted into
+ * the returned order even though they are absent from the pre-pagination row
+ * model.
+ */
+export function table_getRowsInDisplayOrder<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const rows = table.getPrePaginatedRowModel().rows
+
+  if (table.options.paginateExpandedRows === false) {
+    const displayRows: Array<Row<TFeatures, TData>> = []
+
+    const handleRow = (row: Row<TFeatures, TData>) => {
+      row._displayIndexCache = displayRows.length
+      displayRows.push(row)
+
+      if (
+        row.subRows.length &&
+        (
+          row as Row<TFeatures, TData> & Partial<Row_RowExpanding>
+        ).getIsExpanded?.()
+      ) {
+        row.subRows.forEach(handleRow)
+      }
+    }
+
+    rows.forEach(handleRow)
+
+    return displayRows
+  }
+
+  for (let i = 0; i < rows.length; i++) {
+    rows[i]!._displayIndexCache = i
+  }
+
+  return rows
+}
 
 /**
  * Reads and caches this row's value for a column.

package/src/core/table/constructTable.ts

@@ -166,6 +166,10 @@ export function constructTable<
     ),
   )
 
+  for (let i = 0; i < featuresList.length; i++) {
+    featuresList[i]!.initTableInstanceData?.(table)
+  }
+
   if (
     process.env.NODE_ENV === 'development' &&
     (tableOptions.debugAll || tableOptions.debugTable)

package/src/core/table/coreTablesFeature.types.ts

@@ -229,7 +229,8 @@ export interface Table_Table<
    *
    * Prefer feature-specific reset APIs, such as `resetPagination`, when a state
    * slice may be owned by an external atom or needs that feature's blank/default
-   * reset behavior.
+   * reset behavior. After resetting internal atoms, this also invokes feature
+   * reset hooks for mutable, transient table-instance data.
    */
   reset: () => void
   /**

package/src/core/table/coreTablesFeature.utils.ts

@@ -40,7 +40,8 @@ export function table_syncExternalStateToBaseAtoms<
 }
 
 /**
- * Resets all internal table base atoms to `table.initialState`.
+ * Resets all internal table base atoms to `table.initialState`, then clears
+ * transient instance data through registered feature reset hooks.
  *
  * This resets internally owned state slices in a single reactivity batch. Use
  * feature-specific reset APIs when a slice may be externally owned.
@@ -62,6 +63,11 @@ export function table_reset<
       ;(table.baseAtoms as any)[key].set(snap[key])
     }
   })
+
+  const features = Object.values(table._features)
+  for (let i = 0; i < features.length; i++) {
+    features[i]!.resetTableInstanceData?.(table)
+  }
 }
 
 /**

package/src/features/row-selection/rowSelectionFeature.ts

@@ -35,6 +35,16 @@ import type { TableFeature } from '../../types/TableFeatures'
  * Feature that adds row selection state and APIs for row and page selection.
  */
 export const rowSelectionFeature: TableFeature = {
+  initTableInstanceData: (table) => {
+    // @ts-ignore - _lastSelectedRowId is row selection table instance data
+    table._lastSelectedRowId = null
+  },
+
+  resetTableInstanceData: (table) => {
+    // @ts-ignore - _lastSelectedRowId is row selection table instance data
+    table._lastSelectedRowId = null
+  },
+
   getInitialState: (initialState) => {
     return {
       rowSelection: getDefaultRowSelectionState(),
@@ -47,7 +57,15 @@ export const rowSelectionFeature: TableFeature = {
       onRowSelectionChange: makeStateUpdater('rowSelection', table),
       enableRowSelection: true,
       enableMultiRowSelection: true,
+      enableRowRangeSelection: true,
       enableSubRowSelection: true,
+      isRowRangeSelectionEvent: (event) => {
+        const rangeEvent = event as {
+          shiftKey?: boolean
+          nativeEvent?: { shiftKey?: boolean }
+        }
+        return Boolean(rangeEvent.shiftKey || rangeEvent.nativeEvent?.shiftKey)
+      },
     }
   },
 
@@ -85,7 +103,7 @@ export const rowSelectionFeature: TableFeature = {
         fn: (row) => row_getCanMultiSelect(row),
       },
       row_getToggleSelectedHandler: {
-        fn: (row) => row_getToggleSelectedHandler(row),
+        fn: (row, opts) => row_getToggleSelectedHandler(row, opts),
       },
     })
   },

package/src/features/row-selection/rowSelectionFeature.types.ts

@@ -5,6 +5,17 @@ import type { Row } from '../../types/Row'
 
 export type RowSelectionState = Record<string, true>
 
+/**
+ * Controls how toggling a row affects its descendants.
+ */
+export interface ToggleSelectedOptions {
+  /**
+   * Whether selectable child rows should be toggled recursively. Defaults to
+   * `true`.
+   */
+  selectChildren?: boolean
+}
+
 export interface TableState_RowSelection {
   rowSelection: RowSelectionState
 }
@@ -13,6 +24,11 @@ export interface TableOptions_RowSelection<
   in out TFeatures extends TableFeatures,
   in out TData extends RowData,
 > {
+  /**
+   * Enables inclusive row range selection through
+   * `row.getToggleSelectedHandler()`. Defaults to `true`.
+   */
+  enableRowRangeSelection?: boolean
   /**
    * Allows rows to be selected alongside other rows.
    *
@@ -32,6 +48,14 @@ export interface TableOptions_RowSelection<
    * grouping features and defaults to `true`.
    */
   enableSubRowSelection?: boolean | ((row: Row<TFeatures, TData>) => boolean)
+  /**
+   * Determines whether a row-selection handler event should select or
+   * deselect the inclusive range from the most recent handler interaction.
+   *
+   * By default, events with `shiftKey` directly on the event or on
+   * `event.nativeEvent` are treated as range-selection events.
+   */
+  isRowRangeSelectionEvent?: (event: unknown) => boolean
   /**
    * Called with an updater when row selection state changes. Pair this with
    * `state.rowSelection` when using external state; external atoms can own the
@@ -44,7 +68,6 @@ export interface TableOptions_RowSelection<
   //       row: Row<TFeatures, TData>
   //     ) => boolean)
   // isAdditiveSelectEvent?: (e: unknown) => boolean
-  // isInclusiveSelectEvent?: (e: unknown) => boolean
   // selectRowsFn?: (
   //   table: Table<TFeatures, TData>,
   //   rowModel: RowModel<TFeatures, TData>
@@ -78,18 +101,29 @@ export interface Row_RowSelection {
   getIsSomeSelected: () => boolean
   /**
    * Creates a checkbox-style handler that toggles this row's selected state.
+   * Pass the original checkbox click event, or a framework event whose
+   * `nativeEvent` is that click, so Shift range selection can detect the
+   * modifier key.
    */
-  getToggleSelectedHandler: () => (event: unknown) => void
+  getToggleSelectedHandler: (
+    opts?: ToggleSelectedOptions,
+  ) => (event: unknown) => void
   /**
    * Selects/deselects the row.
    */
-  toggleSelected: (value?: boolean, opts?: { selectChildren?: boolean }) => void
+  toggleSelected: (value?: boolean, opts?: ToggleSelectedOptions) => void
 }
 
 export interface Table_RowSelection<
   in out TFeatures extends TableFeatures,
   in out TData extends RowData,
 > {
+  /**
+   * The most recent row interacted with through the row selection handler.
+   *
+   * @internal
+   */
+  _lastSelectedRowId: string | null
   /**
    * Builds a selected-row model from rows after filtering.
    */

package/src/features/row-selection/rowSelectionFeature.utils.ts

@@ -10,7 +10,10 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
 import type { Table_Internal } from '../../types/Table'
 import type { Row } from '../../types/Row'
-import type { RowSelectionState } from './rowSelectionFeature.types'
+import type {
+  RowSelectionState,
+  ToggleSelectedOptions,
+} from './rowSelectionFeature.types'
 
 // State APIs
 
@@ -66,6 +69,8 @@ export function table_resetRowSelection<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  // @ts-ignore - _lastSelectedRowId is part of the RowSelection feature
+  table._lastSelectedRowId = null
   table_setRowSelection(
     table,
     defaultState
@@ -98,6 +103,8 @@ export function table_toggleAllRowsSelected<
   value?: boolean,
   opts?: { deselectAll?: boolean },
 ) {
+  // @ts-ignore - _lastSelectedRowId is part of the RowSelection feature
+  table._lastSelectedRowId = null
   table_setRowSelection(table, (old) => {
     value =
       typeof value !== 'undefined'
@@ -153,6 +160,8 @@ export function table_toggleAllPageRowsSelected<
   value?: boolean,
   opts?: { deselectAll?: boolean },
 ) {
+  // @ts-ignore - _lastSelectedRowId is part of the RowSelection feature
+  table._lastSelectedRowId = null
   table_setRowSelection(table, (old) => {
     const resolvedValue =
       typeof value !== 'undefined'
@@ -492,13 +501,7 @@ export function table_getToggleAllPageRowsSelectedHandler<
 export function row_toggleSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
->(
-  row: Row<TFeatures, TData>,
-  value?: boolean,
-  opts?: {
-    selectChildren?: boolean
-  },
-) {
+>(row: Row<TFeatures, TData>, value?: boolean, opts?: ToggleSelectedOptions) {
   const isSelected = row_getIsSelected(row)
 
   table_setRowSelection(row.table, (old) => {
@@ -643,7 +646,11 @@ export function row_getCanMultiSelect<
  * Creates a checkbox-style handler that selects or deselects this row.
  *
  * The handler is a no-op when the row cannot be selected and reads
- * `event.target.checked`.
+ * `event.target.checked`. Shift events select or deselect the inclusive range
+ * from the most recent selectable row handled by this table. The event's
+ * optional `persist()` method is called before it is read. Pass
+ * `selectChildren: false` to limit changes to rows explicitly present in the
+ * display-order interval.
  *
  * @example
  * ```ts
@@ -653,18 +660,111 @@ export function row_getCanMultiSelect<
 export function row_getToggleSelectedHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
->(row: Row<TFeatures, TData>) {
+>(row: Row<TFeatures, TData>, opts?: ToggleSelectedOptions) {
   const canSelect = row_getCanSelect(row)
 
   return (e: unknown) => {
     if (!canSelect) return
-    row_toggleSelected(
-      row,
-      ((e as MouseEvent).target as HTMLInputElement).checked,
-    )
+
+    const event = e as {
+      persist?: () => void
+      target: { checked: boolean }
+    }
+    event.persist?.()
+
+    const table = row.table
+    const checked = event.target.checked
+    // @ts-ignore - _lastSelectedRowId is part of the RowSelection feature
+    const anchorId = table._lastSelectedRowId
+    const canSelectRange =
+      table.options.enableRowRangeSelection !== false &&
+      anchorId !== null &&
+      row_getCanMultiSelect(row) &&
+      (table.options.isRowRangeSelectionEvent?.(e) ?? false)
+
+    if (
+      !canSelectRange ||
+      !selectRowRange(row, anchorId, checked, opts?.selectChildren ?? true)
+    ) {
+      row_toggleSelected(row, checked, opts)
+    }
+
+    // @ts-ignore - _lastSelectedRowId is part of the RowSelection feature
+    table._lastSelectedRowId = row.id
   }
 }
 
+/**
+ * Resolves and mutates an inclusive interval in the table's latest logical
+ * display order.
+ *
+ * The anchor is resolved without throwing from the pre-pagination row model,
+ * then the core row model. Both endpoint display indexes must still identify
+ * those rows in the current order and both endpoints must support
+ * multi-selection. Eligible interval rows are applied through one row
+ * selection updater; non-selectable and non-multi-selectable rows are skipped.
+ * Returns `false` when the interaction should fall back to an ordinary toggle.
+ */
+function selectRowRange<TFeatures extends TableFeatures, TData extends RowData>(
+  row: Row<TFeatures, TData>,
+  anchorId: string,
+  value: boolean,
+  includeChildren: boolean,
+): boolean {
+  const table = row.table
+  const rows = table.getRowsInDisplayOrder()
+  const anchorRow =
+    table.getPrePaginatedRowModel().rowsById[anchorId] ??
+    table.getCoreRowModel().rowsById[anchorId]
+
+  if (!anchorRow) {
+    return false
+  }
+
+  const anchorIndex = anchorRow.getDisplayIndex()
+  const rowIndex = row.getDisplayIndex()
+  const anchorAtIndex = rows[anchorIndex]
+  const rowAtIndex = rows[rowIndex]
+
+  if (
+    anchorIndex < 0 ||
+    rowIndex < 0 ||
+    anchorIndex >= rows.length ||
+    rowIndex >= rows.length ||
+    anchorAtIndex?.id !== anchorRow.id ||
+    rowAtIndex?.id !== row.id ||
+    !row_getCanMultiSelect(anchorRow) ||
+    !row_getCanMultiSelect(row)
+  ) {
+    return false
+  }
+
+  const start = Math.min(anchorIndex, rowIndex)
+  const end = Math.max(anchorIndex, rowIndex)
+
+  table_setRowSelection(table, (old) => {
+    const rowSelection = Object.assign(makeObjectMap<true>(), old)
+
+    for (let index = start; index <= end; index++) {
+      const rangeRow = rows[index]!
+      if (!row_getCanSelect(rangeRow) || !row_getCanMultiSelect(rangeRow)) {
+        continue
+      }
+      mutateRowIsSelected(
+        rowSelection,
+        rangeRow.id,
+        value,
+        includeChildren,
+        table,
+      )
+    }
+
+    return rowSelection
+  })
+
+  return true
+}
+
 const mutateRowIsSelected = <
   TFeatures extends TableFeatures,
   TData extends RowData,