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

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,
@@ -41,10 +46,11 @@ function _createFacetedUniqueValues<
 >(columnId: string, flatRows: Array<Row<TFeatures, TData>>): Map<any, number> {
   const facetedUniqueValues = new Map<any, number>()
 
-  for (const row of flatRows) {
-    const values = row.getUniqueValues(columnId)
+  for (let i = 0; i < flatRows.length; i++) {
+    const values = flatRows[i]!.getUniqueValues(columnId)
 
-    for (const value of values) {
+    for (let j = 0; j < values.length; j++) {
+      const value = values[j]
       if (facetedUniqueValues.has(value)) {
         facetedUniqueValues.set(
           value,

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,
@@ -52,9 +57,11 @@ function _createFilteredRowModel<
   const globalFilter = table.atoms.globalFilter?.get()
 
   if (!rowModel.rows.length || (!columnFilters?.length && !globalFilter)) {
-    for (const row of rowModel.flatRows as Array<
+    const flatRows = rowModel.flatRows as Array<
       Row<TFeatures, TData> & Partial<Row_ColumnFiltering<TFeatures, TData>>
-    >) {
+    >
+    for (let i = 0; i < flatRows.length; i++) {
+      const row = flatRows[i]!
       row.columnFilters = {}
       row.columnFiltersMeta = {}
     }
@@ -105,13 +112,16 @@ function _createFilteredRowModel<
   }
 
   // Flag the pre-filtered row model with each filter state
-  for (const row of rowModel.flatRows as Array<
+  const flatRows = rowModel.flatRows as Array<
     Row<TFeatures, TData> & Partial<Row_ColumnFiltering<TFeatures, TData>>
-  >) {
+  >
+  for (let i = 0; i < flatRows.length; i++) {
+    const row = flatRows[i]!
     row.columnFilters = {}
 
     if (resolvedColumnFilters.length) {
-      for (const currentColumnFilter of resolvedColumnFilters) {
+      for (let j = 0; j < resolvedColumnFilters.length; j++) {
+        const currentColumnFilter = resolvedColumnFilters[j]!
         const id = currentColumnFilter.id
 
         // Tag the row with the column filter state
@@ -129,7 +139,8 @@ function _createFilteredRowModel<
     }
 
     if (resolvedGlobalFilters.length) {
-      for (const currentGlobalFilter of resolvedGlobalFilters) {
+      for (let j = 0; j < resolvedGlobalFilters.length; j++) {
+        const currentGlobalFilter = resolvedGlobalFilters[j]!
         const id = currentGlobalFilter.id
         // Tag the row with the first truthy global filter state
         if (
@@ -159,8 +170,8 @@ function _createFilteredRowModel<
     row: Row<TFeatures, TData> & Row_ColumnFiltering<TFeatures, TData>,
   ) => {
     // Horizontally filter rows through each column
-    for (const columnId of filterableIds) {
-      if (row.columnFilters[columnId] === false) {
+    for (let i = 0; i < filterableIds.length; i++) {
+      if (row.columnFilters[filterableIds[i]!] === false) {
         return false
       }
     }

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

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

@@ -12,10 +12,30 @@ import type {
   Row_ColumnGrouping,
 } from './columnGroupingFeature.types'
 
+/**
+ * Returns the default grouping state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultGroupingState()
+ * ```
+ */
 export function getDefaultGroupingState(): GroupingState {
   return []
 }
 
+/**
+ * Toggles grouping for a column.
+ *
+ * The update is applied through the owning table state slice and respects the feature options for that column.
+ *
+ * @example
+ * ```ts
+ * column_toggleGrouping(column)
+ * ```
+ */
 export function column_toggleGrouping<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -31,6 +51,16 @@ export function column_toggleGrouping<
   })
 }
 
+/**
+ * Returns whether a column can use group.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanGroup(column)
+ * ```
+ */
 export function column_getCanGroup<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -43,6 +73,16 @@ export function column_getCanGroup<
   )
 }
 
+/**
+ * Returns is grouped 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_getIsGrouped(column)
+ * ```
+ */
 export function column_getIsGrouped<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -51,6 +91,16 @@ export function column_getIsGrouped<
   return !!column.table.atoms.grouping?.get()?.includes(column.id)
 }
 
+/**
+ * Returns grouped 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_getGroupedIndex(column)
+ * ```
+ */
 export function column_getGroupedIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -59,6 +109,16 @@ export function column_getGroupedIndex<
   return column.table.atoms.grouping?.get()?.indexOf(column.id) ?? -1
 }
 
+/**
+ * Returns an event handler for toggling grouping handler.
+ *
+ * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ *
+ * @example
+ * ```ts
+ * const value = column_getToggleGroupingHandler(column)
+ * ```
+ */
 export function column_getToggleGroupingHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -72,6 +132,16 @@ export function column_getToggleGroupingHandler<
   }
 }
 
+/**
+ * Infers aggregation fn for a column.
+ *
+ * The inference uses the column definition, table options, and sampled row values when needed.
+ *
+ * @example
+ * ```ts
+ * const value = column_getAutoAggregationFn(column)
+ * ```
+ */
 export function column_getAutoAggregationFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -94,6 +164,16 @@ export function column_getAutoAggregationFn<
   }
 }
 
+/**
+ * Returns aggregation 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_getAggregationFn(column)
+ * ```
+ */
 export function column_getAggregationFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -110,6 +190,16 @@ export function column_getAggregationFn<
       : aggregationFns?.[column.columnDef.aggregationFn as string]
 }
 
+/**
+ * Updates the table's grouping state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setGrouping(table, (old) => old)
+ * ```
+ */
 export function table_setGrouping<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -117,6 +207,17 @@ export function table_setGrouping<
   table.options.onGroupingChange?.(updater)
 }
 
+/**
+ * Resets the table's grouping state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetGrouping(table)
+ * table_resetGrouping(table, true)
+ * ```
+ */
 export function table_resetGrouping<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -127,6 +228,16 @@ export function table_resetGrouping<
   )
 }
 
+/**
+ * Returns is grouped 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_getIsGrouped(row)
+ * ```
+ */
 export function row_getIsGrouped<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -134,6 +245,16 @@ export function row_getIsGrouped<
   return !!row.groupingColumnId
 }
 
+/**
+ * Returns grouping 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_getGroupingValue(row)
+ * ```
+ */
 export function row_getGroupingValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -160,6 +281,16 @@ export function row_getGroupingValue<
   return row._groupingValuesCache?.[columnId]
 }
 
+/**
+ * Returns is grouped for a cell.
+ *
+ * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ *
+ * @example
+ * ```ts
+ * const value = cell_getIsGrouped(cell)
+ * ```
+ */
 export function cell_getIsGrouped<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -171,6 +302,16 @@ export function cell_getIsGrouped<
   )
 }
 
+/**
+ * Returns is placeholder for a cell.
+ *
+ * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ *
+ * @example
+ * ```ts
+ * const value = cell_getIsPlaceholder(cell)
+ * ```
+ */
 export function cell_getIsPlaceholder<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -179,6 +320,16 @@ export function cell_getIsPlaceholder<
   return !cell_getIsGrouped(cell) && column_getIsGrouped(cell.column)
 }
 
+/**
+ * Returns is aggregated for a cell.
+ *
+ * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ *
+ * @example
+ * ```ts
+ * const value = cell_getIsAggregated(cell)
+ * ```
+ */
 export function cell_getIsAggregated<
   TFeatures extends TableFeatures,
   TData extends RowData,

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

@@ -19,6 +19,11 @@ import type { Table, Table_Internal } from '../../types/Table'
 import type { Row } from '../../types/Row'
 import type { RowData } from '../../types/type-utils'
 
+/**
+ * Creates a memoized grouped 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 createGroupedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData = any,