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

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

@@ -6,6 +6,16 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { Row } from '../../types/Row'
 import type { Cell } from '../../types/Cell'
 
+/**
+ * Returns value 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_getValue(row)
+ * ```
+ */
 export function row_getValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -25,6 +35,16 @@ export function row_getValue<
   return row._valuesCache[columnId]
 }
 
+/**
+ * Returns unique values 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_getUniqueValues(row)
+ * ```
+ */
 export function row_getUniqueValues<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -52,6 +72,17 @@ export function row_getUniqueValues<
   return row._uniqueValuesCache[columnId]
 }
 
+/**
+ * Returns a renderable row value for a column.
+ *
+ * If the accessor value is nullish, the table's `renderFallbackValue` is used
+ * instead.
+ *
+ * @example
+ * ```ts
+ * const value = row_renderValue(row)
+ * ```
+ */
 export function row_renderValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -59,6 +90,16 @@ export function row_renderValue<
   return row.getValue(columnId) ?? row.table.options.renderFallbackValue
 }
 
+/**
+ * Returns leaf rows 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_getLeafRows(row)
+ * ```
+ */
 export function row_getLeafRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -66,6 +107,16 @@ export function row_getLeafRows<
   return flattenBy(row.subRows, (d) => d.subRows)
 }
 
+/**
+ * Returns parent row 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_getParentRow(row)
+ * ```
+ */
 export function row_getParentRow<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -73,6 +124,16 @@ export function row_getParentRow<
   return row.parentId ? row.table.getRow(row.parentId, true) : undefined
 }
 
+/**
+ * Returns parent rows 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_getParentRows(row)
+ * ```
+ */
 export function row_getParentRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -89,6 +150,16 @@ export function row_getParentRows<
   return parentRows.reverse()
 }
 
+/**
+ * Returns all cells 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_getAllCells(row)
+ * ```
+ */
 export function row_getAllCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -98,19 +169,37 @@ export function row_getAllCells<
   })
 }
 
+/**
+ * Returns all cells by column id 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_getAllCellsByColumnId(row)
+ * ```
+ */
 export function row_getAllCellsByColumnId<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>) {
-  return row.getAllCells().reduce(
-    (acc, cell) => {
-      acc[cell.column.id] = cell
-      return acc
-    },
-    {} as Record<string, Cell<TFeatures, TData, unknown>>,
-  )
+  const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
+  for (const cell of row.getAllCells()) {
+    result[cell.column.id] = cell
+  }
+  return result
 }
 
+/**
+ * Returns row id 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_getRowId(table)
+ * ```
+ */
 export function table_getRowId<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -126,6 +215,16 @@ export function table_getRowId<
   )
 }
 
+/**
+ * Returns row 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_getRow(table)
+ * ```
+ */
 export function table_getRow<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/core/table/constructTable.ts

@@ -8,6 +8,11 @@ import type { Table, Table_Internal } from '../../types/Table'
 import type { TableOptions } from '../../types/TableOptions'
 import type { TableState } from '../../types/TableState'
 
+/**
+ * Builds the initial table state from registered features and user initial state.
+ *
+ * Each feature contributes its default state before user-provided `initialState` values are merged in.
+ */
 export function getInitialTableState<TFeatures extends TableFeatures>(
   features: TFeatures,
   initialState: Partial<TableState<TFeatures>> | undefined = {},
@@ -18,6 +23,11 @@ export function getInitialTableState<TFeatures extends TableFeatures>(
   return cloneState(initialState) as TableState<TFeatures>
 }
 
+/**
+ * Constructs a table instance from normalized table internals.
+ *
+ * This wires core properties, feature prototype APIs, and instance data used by table rendering and row-model operations.
+ */
 export function constructTable<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/core/table/coreTablesFeature.ts

@@ -12,6 +12,11 @@ export interface CoreTablesFeatureConstructors<
   // TableOptions: TableOptions_Table<TFeatures, TData>
 }
 
+/**
+ * Creates the stock core tables feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructCoreTablesFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,

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

@@ -76,9 +76,9 @@ export interface TableOptions_Table<
   /**
    * Optionally, provide your own external writable atoms for individual state slices.
    * When an atom is provided for a given slice, it takes precedence over `options.state[key]`
-   * and the internal base atom for that slice. Writes originating from the library are
-   * still routed through the internal base atom; consumers are responsible for
-   * mirroring changes back to their external atom via the corresponding `onXChange` callback.
+   * and the internal base atom for that slice. Feature state update APIs write through
+   * the corresponding atom updater, so external atoms are the preferred v9 ownership
+   * model for app-managed table state slices.
    */
   readonly atoms?: ExternalAtoms<TFeatures>
   /**
@@ -90,8 +90,10 @@ export interface TableOptions_Table<
    */
   readonly data: ReadonlyArray<TData>
   /**
-   * Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. `options.autoResetPageIndex`) or via functions like `table.resetRowSelection()`. Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state.
-   * Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable.
+   * Optionally provide starting values for registered table state slices.
+   * Feature reset APIs use this value by default, and many reset APIs accept
+   * `true` to reset to that feature's blank/default state instead. Changing this
+   * object later does not reset table state, so it does not need to be stable.
    */
   readonly initialState?: Partial<TableState<TFeatures>>
   /**
@@ -106,7 +108,11 @@ export interface TableOptions_Table<
    */
   readonly meta?: TableMeta<TFeatures, TData>
   /**
-   * Pass in individual self-managed state to the table.
+   * Optionally provide externally managed values for individual state slices.
+   *
+   * Pair each slice with its matching `on[State]Change` callback so table state
+   * updates can be persisted outside the table. External atoms take precedence
+   * over this option when both are provided for the same slice.
    */
   readonly state?: Partial<TableState<TFeatures>>
 }
@@ -167,10 +173,9 @@ export interface Table_CoreProperties<
    */
   readonly options: TableOptions<TFeatures, TData>
   /**
-   * Writable atom for table options. Only created when `createOptionsStore` is true
-   * on `coreReativityFeature` (e.g. Lit, Vue, Solid). React/Preact use `createOptionsStore: false`:
-   * options are held as plain data with a lightweight revision + subscribe source; there is
-   * no writable atom backing the full options object. Use {@link getTableOptionsStore} to subscribe.
+   * Writable atom for table options. Only created when `createOptionsStore` is
+   * true on the active core reactivity bindings. Adapters that opt out keep
+   * options as plain resolved data instead of backing them with an atom.
    */
   readonly optionsStore?: Atom<TableOptions<TFeatures, TData>> | undefined
   /**
@@ -185,11 +190,16 @@ export interface Table_Table<
   TData extends RowData,
 > extends Table_CoreProperties<TFeatures, TData> {
   /**
-   * Call this function to reset the table state to the initial state.
+   * Resets the table's internal base atoms to `table.initialState`.
+   *
+   * 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: () => void
   /**
-   * This function can be used to update the table options.
+   * Updates the table options by applying a value or updater to the current
+   * resolved options and then merging them through `options.mergeOptions`.
    */
   setOptions: (newOptions: Updater<TableOptions<TFeatures, TData>>) => void
 }

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

@@ -4,6 +4,17 @@ 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,
@@ -28,6 +39,17 @@ export function table_syncExternalStateToBaseAtoms<
   })
 }
 
+/**
+ * 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,
@@ -40,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,
@@ -57,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,

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>,