@tanstack/table-core 9.0.0-alpha.42 → 9.0.0-alpha.46

package/src/features/row-pinning/rowPinningFeature.utils.ts

@@ -11,6 +11,16 @@ import type {
 
 // State Utils
 
+/**
+ * Returns the default row pinning state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultRowPinningState()
+ * ```
+ */
 export function getDefaultRowPinningState(): RowPinningState {
   return {
     top: [],
@@ -18,6 +28,16 @@ export function getDefaultRowPinningState(): RowPinningState {
   }
 }
 
+/**
+ * Updates the table's row pinning state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setRowPinning(table, (old) => old)
+ * ```
+ */
 export function table_setRowPinning<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -28,6 +48,17 @@ export function table_setRowPinning<
   table.options.onRowPinningChange?.(updater)
 }
 
+/**
+ * Resets the table's row pinning state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetRowPinning(table)
+ * table_resetRowPinning(table, true)
+ * ```
+ */
 export function table_resetRowPinning<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -44,6 +75,16 @@ export function table_resetRowPinning<
 
 // Table Utils
 
+/**
+ * Returns is some rows pinned 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_getIsSomeRowsPinned(table)
+ * ```
+ */
 export function table_getIsSomeRowsPinned<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -90,6 +131,16 @@ function table_getPinnedRows<
   return filteredRows
 }
 
+/**
+ * Returns top rows 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_getTopRows(table)
+ * ```
+ */
 export function table_getTopRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -97,6 +148,16 @@ export function table_getTopRows<
   return table_getPinnedRows(table, 'top')
 }
 
+/**
+ * Returns bottom rows 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_getBottomRows(table)
+ * ```
+ */
 export function table_getBottomRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -104,6 +165,16 @@ export function table_getBottomRows<
   return table_getPinnedRows(table, 'bottom')
 }
 
+/**
+ * Returns center rows 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_getCenterRows(table)
+ * ```
+ */
 export function table_getCenterRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -118,6 +189,16 @@ export function table_getCenterRows<
 
 // Row Utils
 
+/**
+ * Returns whether a row can use pin.
+ *
+ * This evaluates row data, table options, and feature-specific enablement rules.
+ *
+ * @example
+ * ```ts
+ * const value = row_getCanPin(row)
+ * ```
+ */
 export function row_getCanPin<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -129,6 +210,16 @@ export function row_getCanPin<
   return enableRowPinning ?? true
 }
 
+/**
+ * Returns is pinned 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_getIsPinned(row)
+ * ```
+ */
 export function row_getIsPinned<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -143,6 +234,16 @@ export function row_getIsPinned<
       : false
 }
 
+/**
+ * Returns pinned index 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_getPinnedIndex(row)
+ * ```
+ */
 export function row_getPinnedIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -159,6 +260,17 @@ export function row_getPinnedIndex<
   return visiblePinnedRowIds.indexOf(row.id)
 }
 
+/**
+ * Pins or unpins a row.
+ *
+ * Optional flags let callers include parent rows or leaf rows when updating
+ * the row pinning state.
+ *
+ * @example
+ * ```ts
+ * row_pin(row, 'top')
+ * ```
+ */
 export function row_pin<TFeatures extends TableFeatures, TData extends RowData>(
   row: Row<TFeatures, TData>,
   position: RowPinningPosition,

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

@@ -47,6 +47,11 @@ export interface RowSelectionFeatureConstructors<
   // TableState: TableState_RowSelection
 }
 
+/**
+ * Creates the stock row selection feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructRowSelectionFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -159,6 +164,9 @@ export function constructRowSelectionFeature<
 }
 
 /**
- * The Row Selection feature adds row selection state and APIs to the table and row objects.
+ * The stock row selection feature.
+ *
+ * Register this feature to add row selection state, selected row-model helpers,
+ * and table/row APIs for checkbox and bulk-selection UI.
  */
 export const rowSelectionFeature = constructRowSelectionFeature()

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

@@ -29,7 +29,9 @@ export interface TableOptions_RowSelection<
    */
   enableSubRowSelection?: boolean | ((row: Row<TFeatures, TData>) => boolean)
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.rowSelection` 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 row selection state changes. Pair this with
+   * `state.rowSelection` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onRowSelectionChange?: OnChangeFn<RowSelectionState>
   // enableGroupingRowSelection?:
@@ -129,7 +131,7 @@ export interface Table_RowSelection<
    */
   resetRowSelection: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.rowSelection` state.
+   * Sets row selection state using a value or updater.
    */
   setRowSelection: (updater: Updater<RowSelectionState>) => void
   /**

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,
@@ -416,6 +657,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 +672,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,

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()