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

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

@@ -8,10 +8,30 @@ import type { RowSelectionState } from './rowSelectionFeature.types'
 
 // State APIs
 
+/**
+ * Returns the default row selection state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultRowSelectionState()
+ * ```
+ */
 export function getDefaultRowSelectionState(): RowSelectionState {
   return {}
 }
 
+/**
+ * Updates the table's row selection state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setRowSelection(table, (old) => old)
+ * ```
+ */
 export function table_setRowSelection<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -22,6 +42,17 @@ export function table_setRowSelection<
   table.options.onRowSelectionChange?.(updater)
 }
 
+/**
+ * Resets the table's row selection state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetRowSelection(table)
+ * table_resetRowSelection(table, true)
+ * ```
+ */
 export function table_resetRowSelection<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -34,6 +65,16 @@ export function table_resetRowSelection<
 
 // Table APIs
 
+/**
+ * Toggles all rows selected for the table.
+ *
+ * This is the table-level convenience API used by UI controls that affect many columns or rows at once.
+ *
+ * @example
+ * ```ts
+ * table_toggleAllRowsSelected(table)
+ * ```
+ */
 export function table_toggleAllRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -65,6 +106,16 @@ export function table_toggleAllRowsSelected<
   })
 }
 
+/**
+ * Toggles all page rows selected for the table.
+ *
+ * This is the table-level convenience API used by UI controls that affect many columns or rows at once.
+ *
+ * @example
+ * ```ts
+ * table_toggleAllPageRowsSelected(table)
+ * ```
+ */
 export function table_toggleAllPageRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -85,6 +136,16 @@ export function table_toggleAllPageRowsSelected<
   })
 }
 
+/**
+ * Returns pre selected row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getPreSelectedRowModel(table)
+ * ```
+ */
 export function table_getPreSelectedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -92,6 +153,16 @@ export function table_getPreSelectedRowModel<
   return table.getCoreRowModel()
 }
 
+/**
+ * Returns selected row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getSelectedRowModel(table)
+ * ```
+ */
 export function table_getSelectedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -109,6 +180,16 @@ export function table_getSelectedRowModel<
   return selectRowsFn(rowModel)
 }
 
+/**
+ * Returns filtered selected row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getFilteredSelectedRowModel(table)
+ * ```
+ */
 export function table_getFilteredSelectedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -126,6 +207,16 @@ export function table_getFilteredSelectedRowModel<
   return selectRowsFn(rowModel)
 }
 
+/**
+ * Returns grouped selected row model for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getGroupedSelectedRowModel(table)
+ * ```
+ */
 export function table_getGroupedSelectedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -143,6 +234,16 @@ export function table_getGroupedSelectedRowModel<
   return selectRowsFn(rowModel)
 }
 
+/**
+ * Returns is all rows selected for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getIsAllRowsSelected(table)
+ * ```
+ */
 export function table_getIsAllRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -167,6 +268,16 @@ export function table_getIsAllRowsSelected<
   return isAllRowsSelected
 }
 
+/**
+ * Returns is all page rows selected for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getIsAllPageRowsSelected(table)
+ * ```
+ */
 export function table_getIsAllPageRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -188,6 +299,16 @@ export function table_getIsAllPageRowsSelected<
   return isAllPageRowsSelected
 }
 
+/**
+ * Returns is some rows selected for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getIsSomeRowsSelected(table)
+ * ```
+ */
 export function table_getIsSomeRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -201,6 +322,16 @@ export function table_getIsSomeRowsSelected<
   )
 }
 
+/**
+ * Returns is some page rows selected for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getIsSomePageRowsSelected(table)
+ * ```
+ */
 export function table_getIsSomePageRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -213,6 +344,16 @@ export function table_getIsSomePageRowsSelected<
         .some((row) => row_getIsSelected(row) || row_getIsSomeSelected(row))
 }
 
+/**
+ * Returns an event handler for all rows selected handler.
+ *
+ * The handler calls the matching table toggle API and can be attached directly to checkbox or button UI.
+ *
+ * @example
+ * ```ts
+ * const value = table_getToggleAllRowsSelectedHandler(table)
+ * ```
+ */
 export function table_getToggleAllRowsSelectedHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -225,6 +366,16 @@ export function table_getToggleAllRowsSelectedHandler<
   }
 }
 
+/**
+ * Returns an event handler for all page rows selected handler.
+ *
+ * The handler calls the matching table toggle API and can be attached directly to checkbox or button UI.
+ *
+ * @example
+ * ```ts
+ * const value = table_getToggleAllPageRowsSelectedHandler(table)
+ * ```
+ */
 export function table_getToggleAllPageRowsSelectedHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -239,6 +390,16 @@ export function table_getToggleAllPageRowsSelectedHandler<
 
 // Row APIs
 
+/**
+ * Toggles selected for a row.
+ *
+ * The update is routed through the table state updater for the owning feature state slice.
+ *
+ * @example
+ * ```ts
+ * row_toggleSelected(row)
+ * ```
+ */
 export function row_toggleSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -272,6 +433,16 @@ export function row_toggleSelected<
   })
 }
 
+/**
+ * Returns is selected for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getIsSelected(row)
+ * ```
+ */
 export function row_getIsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -279,6 +450,16 @@ export function row_getIsSelected<
   return isRowSelected(row)
 }
 
+/**
+ * Returns is some selected for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getIsSomeSelected(row)
+ * ```
+ */
 export function row_getIsSomeSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -286,6 +467,16 @@ export function row_getIsSomeSelected<
   return isSubRowSelected(row) === 'some'
 }
 
+/**
+ * Returns is all sub rows selected for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getIsAllSubRowsSelected(row)
+ * ```
+ */
 export function row_getIsAllSubRowsSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -293,6 +484,16 @@ export function row_getIsAllSubRowsSelected<
   return isSubRowSelected(row) === 'all'
 }
 
+/**
+ * Returns whether a row can use select.
+ *
+ * This evaluates row data, table options, and feature-specific enablement rules.
+ *
+ * @example
+ * ```ts
+ * const value = row_getCanSelect(row)
+ * ```
+ */
 export function row_getCanSelect<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -305,6 +506,16 @@ export function row_getCanSelect<
   return options.enableRowSelection ?? true
 }
 
+/**
+ * Returns whether a row can use select sub rows.
+ *
+ * This evaluates row data, table options, and feature-specific enablement rules.
+ *
+ * @example
+ * ```ts
+ * const value = row_getCanSelectSubRows(row)
+ * ```
+ */
 export function row_getCanSelectSubRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -317,6 +528,16 @@ export function row_getCanSelectSubRows<
   return options.enableSubRowSelection ?? true
 }
 
+/**
+ * Returns whether a row can use multi select.
+ *
+ * This evaluates row data, table options, and feature-specific enablement rules.
+ *
+ * @example
+ * ```ts
+ * const value = row_getCanMultiSelect(row)
+ * ```
+ */
 export function row_getCanMultiSelect<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -329,6 +550,16 @@ export function row_getCanMultiSelect<
   return options.enableMultiRowSelection ?? true
 }
 
+/**
+ * Returns an event handler for toggling selected handler.
+ *
+ * The handler is intended for direct use in row-level controls such as expansion or selection buttons.
+ *
+ * @example
+ * ```ts
+ * const value = row_getToggleSelectedHandler(row)
+ * ```
+ */
 export function row_getToggleSelectedHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -374,6 +605,16 @@ const mutateRowIsSelected = <
   }
 }
 
+/**
+ * Builds a row model containing rows selected by the current row selection state.
+ *
+ * The result is derived from the supplied row model, so selected ids absent from the current data are not materialized as rows.
+ *
+ * @example
+ * ```ts
+ * const selectedRows = selectRowsFn(table, rowModel)
+ * ```
+ */
 export function selectRowsFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -381,32 +622,33 @@ export function selectRowsFn<
   const newSelectedFlatRows: Array<Row<TFeatures, TData>> = []
   const newSelectedRowsById: Record<string, Row<TFeatures, TData>> = {}
 
-  // Filters top level and nested rows
+  // Filters top level and nested rows.
   const recurseRows = (
     rows: Array<Row<TFeatures, TData>>,
     depth = 0,
   ): Array<Row<TFeatures, TData>> => {
-    return rows
-      .map((row) => {
-        const isSelected = isRowSelected(row)
-
-        if (isSelected) {
-          newSelectedFlatRows.push(row)
-          newSelectedRowsById[row.id] = row
-        }
+    const result: Array<Row<TFeatures, TData>> = []
+    for (let i = 0; i < rows.length; i++) {
+      let row = rows[i]!
+      const isSelected = isRowSelected(row)
+
+      if (isSelected) {
+        newSelectedFlatRows.push(row)
+        newSelectedRowsById[row.id] = row
+      }
 
-        if (row.subRows.length) {
-          row = {
-            ...row,
-            subRows: recurseRows(row.subRows, depth + 1),
-          }
+      if (row.subRows.length) {
+        row = {
+          ...row,
+          subRows: recurseRows(row.subRows, depth + 1),
         }
+      }
 
-        if (isSelected) {
-          return row
-        }
-      })
-      .filter((x) => !!x)
+      if (isSelected) {
+        result.push(row)
+      }
+    }
+    return result
   }
 
   return {
@@ -416,6 +658,14 @@ export function selectRowsFn<
   }
 }
 
+/**
+ * Returns whether a row id is selected in the current row selection state.
+ *
+ * @example
+ * ```ts
+ * const selected = isRowSelected(row, selection)
+ * ```
+ */
 export function isRowSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -423,6 +673,16 @@ export function isRowSelected<
   return (row.table.atoms.rowSelection?.get() ?? {})[row.id] ?? false
 }
 
+/**
+ * Returns whether all, some, or none of a row's selectable descendants are selected.
+ *
+ * The result is used to drive indeterminate row selection UI.
+ *
+ * @example
+ * ```ts
+ * const selectedState = isSubRowSelected(row, selection, table)
+ * ```
+ */
 export function isSubRowSelected<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/row-sorting/createSortedRowModel.ts

@@ -9,6 +9,11 @@ import type { Row } from '../../types/Row'
 import type { SortFn, SortFns } from './rowSortingFeature.types'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Creates a memoized sorted row model factory.
+ *
+ * The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline.
+ */
 export function createSortedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -74,16 +79,11 @@ function _createSortedRowModel<
   })
 
   const sortData = (rows: Array<Row<TFeatures, TData>>) => {
-    // This will also perform a stable sorting using the row index
-    // if needed.
-    // Preserve prototype chain so methods like getValue() remain accessible
-    const sortedData = rows.map((row) => {
-      const cloned = Object.create(Object.getPrototypeOf(row))
-      return Object.assign(cloned, row)
-    })
+    const sortedData = rows.slice()
 
     sortedData.sort((rowA, rowB) => {
-      for (const sortEntry of availableSorting) {
+      for (let i = 0; i < availableSorting.length; i++) {
+        const sortEntry = availableSorting[i]!
         const columnInfo = columnInfoById[sortEntry.id]!
         const sortUndefined = columnInfo.sortUndefined
         const isDesc = sortEntry.desc
@@ -130,13 +130,21 @@ function _createSortedRowModel<
       return rowA.index - rowB.index
     })
 
-    // If there are sub-rows, sort them
-    sortedData.forEach((row) => {
-      sortedFlatRows.push(row)
+    // If there are sub-rows, sort them. Clone only rows that need mutation
+    // (i.e. have subRows) so we don't corrupt the source row model.
+    for (let i = 0; i < sortedData.length; i++) {
+      const row = sortedData[i]!
       if (row.subRows.length) {
-        row.subRows = sortData(row.subRows)
+        // Preserve prototype chain so methods like getValue() remain accessible
+        const cloned = Object.create(Object.getPrototypeOf(row))
+        Object.assign(cloned, row)
+        cloned.subRows = sortData(row.subRows)
+        sortedData[i] = cloned
+        sortedFlatRows.push(cloned)
+      } else {
+        sortedFlatRows.push(row)
       }
-    })
+    }
 
     return sortedData
   }

package/src/features/row-sorting/rowSortingFeature.ts

@@ -47,6 +47,11 @@ export interface RowSortingFeatureConstructors<
   // TableState: TableState_RowSorting
 }
 
+/**
+ * Creates the stock row sorting feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructRowSortingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -77,10 +82,10 @@ export function constructRowSortingFeature<
 
     assignColumnPrototype(prototype, table) {
       assignPrototypeAPIs('rowSortingFeature', prototype, table, {
-        'column.getAutoSortFn': {
+        column_getAutoSortFn: {
           fn: (column) => column_getAutoSortFn(column),
         },
-        'column.getAutoSortDir': {
+        column_getAutoSortDir: {
           fn: (column) => column_getAutoSortDir(column),
         },
         column_getSortFn: {
@@ -131,6 +136,9 @@ export function constructRowSortingFeature<
 }
 
 /**
- * The (Row) Sorting feature adds sorting state and APIs to the table and column objects.
+ * The stock row sorting feature.
+ *
+ * Register this feature to add sorting state, column sorting APIs, and sorted
+ * row-model support for client-side or manual sorting.
  */
 export const rowSortingFeature = constructRowSortingFeature()

package/src/features/row-sorting/rowSortingFeature.types.ts

@@ -172,7 +172,9 @@ export interface TableOptions_RowSorting {
    */
   maxMultiSortColCount?: number
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.sorting` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
+   * Called with an updater when sorting state changes. Pair this with
+   * `state.sorting` when using external state; external atoms can own the slice
+   * without this callback.
    */
   onSortingChange?: OnChangeFn<SortingState>
   /**
@@ -190,7 +192,7 @@ export interface Table_RowSorting<
    */
   resetSorting: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.sorting` state.
+   * Sets sorting state using a value or updater.
    */
   setSorting: (updater: Updater<SortingState>) => void
 }
@@ -214,7 +216,9 @@ export interface CreateRowModel_Sorted<
   TData extends RowData,
 > {
   /**
-   * This function is used to retrieve the sorted row model. If using server-side sorting, this function is not required. To use client-side sorting, pass the exported `getSortedRowModel()` from your adapter to your table or implement your own.
+   * Factory used to retrieve the sorted row model. If using server-side
+   * sorting, this is not required. To use client-side sorting, pass the
+   * exported `createSortedRowModel()` or implement your own factory.
    */
   sortedRowModel?: (
     table: Table<TFeatures, TData>,