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

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

@@ -4,6 +4,52 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
 import type { TableOptions } from '../../types/TableOptions'
 
+/**
+ * Synchronizes externally controlled state slices into the table's base atoms.
+ *
+ * This keeps legacy `options.state` values reflected in the atom graph so
+ * derived atoms, stores, and table APIs read a consistent snapshot.
+ *
+ * @example
+ * ```ts
+ * const value = table_syncExternalStateToBaseAtoms(table)
+ * ```
+ */
+export function table_syncExternalStateToBaseAtoms<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): void {
+  const state = table.options.state
+  if (!state) {
+    return
+  }
+
+  table._reactivity.batch(() => {
+    for (const key in state) {
+      const baseAtom = (table.baseAtoms as Record<string, any>)[key]
+      if (!baseAtom) {
+        continue
+      }
+
+      const externalState = state[key as keyof typeof state]
+      if (externalState !== baseAtom.get()) {
+        baseAtom.set(() => externalState)
+      }
+    }
+  })
+}
+
+/**
+ * Resets all internal table base atoms to `table.initialState`.
+ *
+ * This resets internally owned state slices in a single reactivity batch. Use
+ * feature-specific reset APIs when a slice may be externally owned.
+ *
+ * @example
+ * ```ts
+ * table_reset(table)
+ * ```
+ */
 export function table_reset<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -16,6 +62,17 @@ export function table_reset<
   })
 }
 
+/**
+ * Merges new table options with the current resolved options.
+ *
+ * If `options.mergeOptions` is provided, it owns the merge behavior; otherwise
+ * options are shallow-merged.
+ *
+ * @example
+ * ```ts
+ * const value = table_mergeOptions(table)
+ * ```
+ */
 export function table_mergeOptions<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -33,6 +90,17 @@ export function table_mergeOptions<
   }
 }
 
+/**
+ * Updates the table options object.
+ *
+ * The updater receives the current resolved options and the merged result is
+ * immediately assigned to the table instance.
+ *
+ * @example
+ * ```ts
+ * table_setOptions(table, (old) => old)
+ * ```
+ */
 export function table_setOptions<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -42,5 +110,10 @@ export function table_setOptions<
 ): void {
   const newOptions = functionalUpdate(updater, table.options)
   const mergedOptions = table_mergeOptions(table, newOptions)
-  table.optionsStore.set(() => mergedOptions)
+  if (table.optionsStore) {
+    table.optionsStore.set(() => mergedOptions)
+  } else {
+    table.options = mergedOptions
+  }
+  table_syncExternalStateToBaseAtoms(table)
 }

package/src/features/column-faceting/columnFacetingFeature.ts

@@ -29,6 +29,11 @@ export interface ColumnFacetingFeatureConstructors<
   // CreateRowModels: CreateRowModel_Faceted<TFeatures, TData>
 }
 
+/**
+ * Creates the stock column faceting feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnFacetingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -107,6 +112,9 @@ export function constructColumnFacetingFeature<
 }
 
 /**
- * The Column Faceting feature adds column faceting APIs to the column objects.
+ * The stock column faceting feature.
+ *
+ * Register this feature to add faceted row model, unique value, and min/max
+ * helpers for column and global filter UIs.
  */
 export const columnFacetingFeature = constructColumnFacetingFeature()

package/src/features/column-faceting/columnFacetingFeature.types.ts

@@ -27,17 +27,17 @@ export interface Table_RowModels_Faceted<
 > {
   /**
    * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
-   * > ⚠️ Requires that you pass a valid `getFacetedMinMaxValues` function to `options.getFacetedMinMaxValues`. A default implementation is provided via the exported `getFacetedMinMaxValues` function.
+   * > Requires that you pass a valid `facetedMinMaxValues` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedMinMaxValues` function.
    */
   getFacetedMinMaxValues: () => undefined | [number, number]
   /**
    * Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
-   * > ⚠️ Requires that you pass a valid `getFacetedRowModel` function to `options.facetedRowModel`. A default implementation is provided via the exported `getFacetedRowModel` function.
+   * > Requires that you pass a valid `facetedRowModel` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedRowModel` function.
    */
   getFacetedRowModel: () => RowModel<TFeatures, TData>
   /**
    * A function that **computes and returns** a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
-   * > ⚠️ Requires that you pass a valid `getFacetedUniqueValues` function to `options.getFacetedUniqueValues`. A default implementation is provided via the exported `getFacetedUniqueValues` function.
+   * > Requires that you pass a valid `facetedUniqueValues` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedUniqueValues` function.
    */
   getFacetedUniqueValues: () => Map<any, number>
 }
@@ -47,21 +47,27 @@ export interface CreateRowModel_Faceted<
   TData extends RowData,
 > {
   /**
-   * This function is used to retrieve the faceted min/max values. If using server-side faceting, this function is not required. To use client-side faceting, pass the exported `getFacetedMinMaxValues()` from your adapter to your table or implement your own.
+   * Factory used to retrieve faceted min/max values. If using server-side
+   * faceting, this is not required. To use client-side faceting, pass
+   * `createFacetedMinMaxValues()` or implement your own factory.
    */
   facetedMinMaxValues?: (
     table: Table<TFeatures, TData>,
     columnId: string,
   ) => () => [number, number] | undefined
   /**
-   * This function is used to retrieve the faceted row model. If using server-side faceting, this function is not required. To use client-side faceting, pass the exported `getFacetedRowModel()` from your adapter to your table or implement your own.
+   * Factory used to retrieve the faceted row model. If using server-side
+   * faceting, this is not required. To use client-side faceting, pass
+   * `createFacetedRowModel()` or implement your own factory.
    */
   facetedRowModel?: (
     table: Table<TFeatures, TData>,
     columnId: string,
   ) => () => RowModel<TFeatures, TData>
   /**
-   * This function is used to retrieve the faceted unique values. If using server-side faceting, this function is not required. To use client-side faceting, pass the exported `getFacetedUniqueValues()` from your adapter to your table or implement your own.
+   * Factory used to retrieve faceted unique values. If using server-side
+   * faceting, this is not required. To use client-side faceting, pass
+   * `createFacetedUniqueValues()` or implement your own factory.
    */
   facetedUniqueValues?: (
     table: Table<TFeatures, TData>,

package/src/features/column-faceting/columnFacetingFeature.utils.ts

@@ -4,6 +4,16 @@ import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
 import type { Table_Internal } from '../../types/Table'
 import type { Column_Internal } from '../../types/Column'
 
+/**
+ * Returns faceted min max values for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFacetedMinMaxValues(column)
+ * ```
+ */
 export function column_getFacetedMinMaxValues<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -18,6 +28,16 @@ export function column_getFacetedMinMaxValues<
   return facetedMinMaxValuesFn()
 }
 
+/**
+ * Returns faceted row model for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFacetedRowModel(column)
+ * ```
+ */
 export function column_getFacetedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -32,6 +52,16 @@ export function column_getFacetedRowModel<
   return facetedRowModelFn()
 }
 
+/**
+ * Returns faceted unique values for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFacetedUniqueValues(column)
+ * ```
+ */
 export function column_getFacetedUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -46,6 +76,16 @@ export function column_getFacetedUniqueValues<
   return facetedUniqueValuesFn()
 }
 
+/**
+ * Returns global faceted min max values 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_getGlobalFacetedMinMaxValues(table)
+ * ```
+ */
 export function table_getGlobalFacetedMinMaxValues<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -56,6 +96,16 @@ export function table_getGlobalFacetedMinMaxValues<
   return facetedMinMaxValuesFn()
 }
 
+/**
+ * Returns global faceted 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_getGlobalFacetedRowModel(table)
+ * ```
+ */
 export function table_getGlobalFacetedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -66,6 +116,16 @@ export function table_getGlobalFacetedRowModel<
   return facetedRowModelFn()
 }
 
+/**
+ * Returns global faceted unique values 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_getGlobalFacetedUniqueValues(table)
+ * ```
+ */
 export function table_getGlobalFacetedUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/column-faceting/createFacetedMinMaxValues.ts

@@ -5,6 +5,11 @@ import type { Table, Table_Internal } from '../../types/Table'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Creates a memoized faceted min max values helper for faceted filtering.
+ *
+ * The returned function derives facet data from the table row model and relevant filter state so filter UIs can display available values.
+ */
 export function createFacetedMinMaxValues<
   TFeatures extends TableFeatures,
   TData extends RowData = any,

package/src/features/column-faceting/createFacetedRowModel.ts

@@ -10,6 +10,11 @@ import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
 import type { Row } from '../../types/Row'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Creates a memoized faceted 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 createFacetedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData = any,

package/src/features/column-faceting/createFacetedUniqueValues.ts

@@ -5,6 +5,11 @@ import type { Table, Table_Internal } from '../../types/Table'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Creates a memoized faceted unique values helper for faceted filtering.
+ *
+ * The returned function derives facet data from the table row model and relevant filter state so filter UIs can display available values.
+ */
 export function createFacetedUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData = any,

package/src/features/column-filtering/columnFilteringFeature.ts

@@ -44,6 +44,11 @@ export interface ColumnFilteringFeatureConstructors<
   // TableState: TableState_ColumnFiltering
 }
 
+/**
+ * Creates the stock column filtering feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnFilteringFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -115,7 +120,10 @@ export function constructColumnFilteringFeature<
 }
 
 /**
- * The Column Filtering feature adds column filtering state and APIs to the table, row, and column objects.
- * **Note:** This does not include Global Filtering. The globalFilteringFeature feature has been split out into its own standalone feature.
+ * The stock column filtering feature.
+ *
+ * Register this feature to add column filter state, filter defaults, and
+ * table/row/column APIs for client-side or manual column filtering. Global
+ * filtering is provided by `globalFilteringFeature`.
  */
 export const columnFilteringFeature = constructColumnFilteringFeature()

package/src/features/column-filtering/columnFilteringFeature.types.ts

@@ -167,7 +167,9 @@ export interface TableOptions_ColumnFiltering<
      */
   maxLeafRowFilterDepth?: number
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnFilters` 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 column filter state changes. Pair this with
+   * `state.columnFilters` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>
 }
@@ -178,7 +180,7 @@ export interface Table_ColumnFiltering {
    */
   resetColumnFilters: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.columnFilters` state.
+   * Sets column filter state using a value or updater.
    */
   setColumnFilters: (updater: Updater<ColumnFiltersState>) => void
 }
@@ -202,9 +204,10 @@ export interface CreateRowModel_Filtered<
   TData extends RowData,
 > {
   /**
-   * If provided, this function is called **once** per table and should return a **new function** which will calculate and return the row model for the table when it's filtered.
+   * If provided, this factory is called once per table and should return a
+   * function that calculates the filtered row model.
    * - For server-side filtering, this function is unnecessary and can be ignored since the server should already return the filtered row model.
-   * - For client-side filtering, this function is required. A default implementation is provided via any table adapter's `{ getFilteredRowModel }` export.
+   * - For client-side filtering, pass the exported `createFilteredRowModel()` or implement your own factory.
    */
   filteredRowModel?: (
     table: Table<TFeatures, TData>,

package/src/features/column-filtering/columnFilteringFeature.utils.ts

@@ -8,10 +8,30 @@ import type {
   FilterFn,
 } from './columnFilteringFeature.types'
 
+/**
+ * Returns the default column filters state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnFiltersState()
+ * ```
+ */
 export function getDefaultColumnFiltersState(): ColumnFiltersState {
   return []
 }
 
+/**
+ * Infers filter fn for a column.
+ *
+ * The inference uses the column definition, table options, and sampled row values when needed.
+ *
+ * @example
+ * ```ts
+ * const value = column_getAutoFilterFn(column)
+ * ```
+ */
 export function column_getAutoFilterFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -47,6 +67,16 @@ export function column_getAutoFilterFn<
   return filterFns?.weakEquals
 }
 
+/**
+ * Returns filter fn for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFilterFn(column)
+ * ```
+ */
 export function column_getFilterFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -72,6 +102,16 @@ export function column_getFilterFn<
   return filterFn
 }
 
+/**
+ * Returns whether a column can use filter.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanFilter(column)
+ * ```
+ */
 export function column_getCanFilter<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -85,6 +125,16 @@ export function column_getCanFilter<
   )
 }
 
+/**
+ * Returns is filtered for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getIsFiltered(column)
+ * ```
+ */
 export function column_getIsFiltered<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -93,6 +143,16 @@ export function column_getIsFiltered<
   return column_getFilterIndex(column) > -1
 }
 
+/**
+ * Returns filter value for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFilterValue(column)
+ * ```
+ */
 export function column_getFilterValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -103,6 +163,16 @@ export function column_getFilterValue<
     ?.find((d) => d.id === column.id)?.value
 }
 
+/**
+ * Returns filter index for a column.
+ *
+ * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ *
+ * @example
+ * ```ts
+ * const value = column_getFilterIndex(column)
+ * ```
+ */
 export function column_getFilterIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -115,6 +185,16 @@ export function column_getFilterIndex<
   )
 }
 
+/**
+ * Updates filter value for a column.
+ *
+ * This delegates to the owning table state updater so external state, external atoms, and internal state stay synchronized.
+ *
+ * @example
+ * ```ts
+ * column_setFilterValue(column, (old) => old)
+ * ```
+ */
 export function column_setFilterValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -152,6 +232,16 @@ export function column_setFilterValue<
   })
 }
 
+/**
+ * Updates the table's column filters state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnFilters(table, (old) => old)
+ * ```
+ */
 export function table_setColumnFilters<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -159,11 +249,11 @@ export function table_setColumnFilters<
   table: Table_Internal<TFeatures, TData>,
   updater: Updater<ColumnFiltersState>,
 ) {
-  const leafColumns = table.getAllLeafColumns()
+  const leafColumnsById = table.getAllLeafColumnsById()
 
   const updateFn = (old: ColumnFiltersState) => {
     return functionalUpdate(updater, old).filter((filter) => {
-      const column = leafColumns.find((d) => d.id === filter.id)
+      const column = leafColumnsById[filter.id]
 
       if (column) {
         const filterFn = column_getFilterFn(column)
@@ -180,6 +270,17 @@ export function table_setColumnFilters<
   table.options.onColumnFiltersChange?.(updateFn)
 }
 
+/**
+ * Resets the table's column filters state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnFilters(table)
+ * table_resetColumnFilters(table, true)
+ * ```
+ */
 export function table_resetColumnFilters<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -190,6 +291,16 @@ export function table_resetColumnFilters<
   )
 }
 
+/**
+ * Returns whether a filter value should be removed from filter state.
+ *
+ * This checks the filter function's `autoRemove` hook and built-in empty-value rules.
+ *
+ * @example
+ * ```ts
+ * const removeFilter = shouldAutoRemoveFilter(filterFn, value, column)
+ * ```
+ */
 export function shouldAutoRemoveFilter<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/column-filtering/createFilteredRowModel.ts

@@ -19,6 +19,11 @@ import type {
   Row_ColumnFiltering,
 } from './columnFilteringFeature.types'
 
+/**
+ * Creates a memoized filtered 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 createFilteredRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData = any,

package/src/features/column-filtering/filterRowsUtils.ts

@@ -6,6 +6,11 @@ import type { Table_Internal } from '../../types/Table'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Filters a row model with the supplied row predicate.
+ *
+ * The helper supports both filtering from leaf rows upward and filtering parents before descendants, depending on table options.
+ */
 export function filterRows<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/column-grouping/columnGroupingFeature.ts

@@ -51,6 +51,11 @@ export interface ColumnGroupingFeatureConstructors<
   // TableState: TableState_ColumnGrouping
 }
 
+/**
+ * Creates the stock column grouping feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnGroupingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -146,6 +151,9 @@ export function constructColumnGroupingFeature<
 }
 
 /**
- * The (Column) Grouping feature adds column grouping state and APIs to the table, row, column, and cell objects.
+ * The stock column grouping feature.
+ *
+ * Register this feature to add grouping state, aggregation defaults, grouped
+ * row-model support, and table/row/column/cell grouping APIs.
  */
 export const columnGroupingFeature = constructColumnGroupingFeature()

package/src/features/column-grouping/columnGroupingFeature.types.ts

@@ -163,7 +163,9 @@ export interface TableOptions_ColumnGrouping {
    */
   manualGrouping?: boolean
   /**
-   * If this function is provided, it will be called when the grouping state changes and you will be expected to manage the state yourself. You can pass the managed state back to the table via the `tableOptions.state.grouping` option.
+   * Called with an updater when grouping state changes. Pair this with
+   * `state.grouping` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onGroupingChange?: OnChangeFn<GroupingState>
 }
@@ -179,7 +181,7 @@ export interface Table_ColumnGrouping<
    */
   resetGrouping: (defaultState?: boolean) => void
   /**
-   * Updates the grouping state of the table via an update function or value.
+   * Sets grouping state using a value or updater.
    */
   setGrouping: (updater: Updater<GroupingState>) => void
 }
@@ -203,7 +205,9 @@ export interface CreateRowModel_Grouped<
   TData extends RowData,
 > {
   /**
-   * Returns the row model after grouping has taken place, but no further.
+   * Factory used to retrieve the grouped row model. If using server-side
+   * grouping, this is not required. To use client-side grouping, pass
+   * `createGroupedRowModel()` or implement your own factory.
    */
   groupedRowModel?: (
     table: Table<TFeatures, TData>,