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

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

@@ -5,13 +5,14 @@ import type { Table_Internal } from '../../types/Table'
 import type { Column_Internal } from '../../types/Column'
 
 /**
- * Returns faceted min max values for a column.
+ * Computes min and max numeric facet values for one column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The configured `facetedMinMaxValues` row-model factory owns the calculation.
+ * If no factory is registered, the result is `undefined`.
  *
  * @example
  * ```ts
- * const value = column_getFacetedMinMaxValues(column)
+ * const range = column_getFacetedMinMaxValues(column, table)
  * ```
  */
 export function column_getFacetedMinMaxValues<
@@ -29,13 +30,15 @@ export function column_getFacetedMinMaxValues<
 }
 
 /**
- * Returns faceted row model for a column.
+ * Computes the row model used to derive one column's facet values.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The faceted row model normally applies every other active filter while
+ * excluding this column's own filter. If no factory is registered, the
+ * pre-filtered row model is returned.
  *
  * @example
  * ```ts
- * const value = column_getFacetedRowModel(column)
+ * const rows = column_getFacetedRowModel(column, table)
  * ```
  */
 export function column_getFacetedRowModel<
@@ -53,13 +56,14 @@ export function column_getFacetedRowModel<
 }
 
 /**
- * Returns faceted unique values for a column.
+ * Computes unique facet values and their occurrence counts for one column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The configured `facetedUniqueValues` row-model factory owns the calculation.
+ * If no factory is registered, an empty `Map` is returned.
  *
  * @example
  * ```ts
- * const value = column_getFacetedUniqueValues(column)
+ * const values = column_getFacetedUniqueValues(column, table)
  * ```
  */
 export function column_getFacetedUniqueValues<
@@ -77,13 +81,14 @@ export function column_getFacetedUniqueValues<
 }
 
 /**
- * Returns global faceted min max values for the table.
+ * Computes min and max numeric facet values for the global filter context.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The global context is requested with the internal `__global__` column id. If
+ * no factory is registered, the result is `undefined`.
  *
  * @example
  * ```ts
- * const value = table_getGlobalFacetedMinMaxValues(table)
+ * const range = table_getGlobalFacetedMinMaxValues(table)
  * ```
  */
 export function table_getGlobalFacetedMinMaxValues<
@@ -97,13 +102,15 @@ export function table_getGlobalFacetedMinMaxValues<
 }
 
 /**
- * Returns global faceted row model for the table.
+ * Computes the row model used to derive global facet values.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The global context is requested with the internal `__global__` column id. If
+ * no faceted row-model factory is registered, the pre-filtered row model is
+ * returned.
  *
  * @example
  * ```ts
- * const value = table_getGlobalFacetedRowModel(table)
+ * const rows = table_getGlobalFacetedRowModel(table)
  * ```
  */
 export function table_getGlobalFacetedRowModel<
@@ -117,13 +124,14 @@ export function table_getGlobalFacetedRowModel<
 }
 
 /**
- * Returns global faceted unique values for the table.
+ * Computes unique values and occurrence counts for the global filter context.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The global context is requested with the internal `__global__` column id. If
+ * no factory is registered, an empty `Map` is returned.
  *
  * @example
  * ```ts
- * const value = table_getGlobalFacetedUniqueValues(table)
+ * const values = table_getGlobalFacetedUniqueValues(table)
  * ```
  */
 export function table_getGlobalFacetedUniqueValues<

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

@@ -83,7 +83,10 @@ export interface ColumnDef_ColumnFiltering<
   TData extends RowData,
 > {
   /**
-   * Enables/disables the **column** filter for this column.
+   * Enables this column to participate in column-specific filtering.
+   *
+   * Defaults to `true`; table-level `enableColumnFilters` and `enableFilters`
+   * must also allow filtering.
    */
   enableColumnFilter?: boolean
   /**
@@ -101,7 +104,7 @@ export interface Column_ColumnFiltering<
    */
   getAutoFilterFn: () => FilterFn<TFeatures, TData>
   /**
-   * Returns whether or not the column can be **column** filtered.
+   * Checks whether this accessor column can currently be column-filtered.
    */
   getCanFilter: () => boolean
   /**
@@ -113,15 +116,18 @@ export interface Column_ColumnFiltering<
    */
   getFilterIndex: () => number
   /**
-   * Returns the current filter value for the column.
+   * Reads this column's current value from `state.columnFilters`.
    */
   getFilterValue: () => unknown
   /**
-   * Returns whether or not the column is currently filtered.
+   * Checks whether this column has an active entry in `state.columnFilters`.
    */
   getIsFiltered: () => boolean
   /**
-   * A function that sets the current filter value for the column. You can pass it a value or an updater function for immutability-safe operations on existing values.
+   * Adds, updates, or removes this column's filter value.
+   *
+   * Updater functions receive the previous filter value. Values that satisfy
+   * the filter function's `autoRemove` rule are removed from filter state.
    */
   setFilterValue: (updater: Updater<any>) => void
 }
@@ -145,11 +151,13 @@ export interface TableOptions_ColumnFiltering<
   TData extends RowData,
 > {
   /**
-   * Enables/disables **column** filtering for all columns.
+   * Enables column-specific filtering for all columns that also allow it.
    */
   enableColumnFilters?: boolean
   /**
-   * Enables/disables all filtering for the table.
+   * Enables all filtering features for the table.
+   *
+   * Set this to `false` to disable both column filtering and global filtering.
    */
   enableFilters?: boolean
   /**
@@ -176,11 +184,13 @@ export interface TableOptions_ColumnFiltering<
 
 export interface Table_ColumnFiltering {
   /**
-   * Resets the **columnFilters** state to `initialState.columnFilters`, or `true` can be passed to force a default blank state reset to `[]`.
+   * Resets `columnFilters` to `initialState.columnFilters`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
    */
   resetColumnFilters: (defaultState?: boolean) => void
   /**
-   * Sets column filter state using a value or updater.
+   * Updates column filter state with a next array or updater function.
    */
   setColumnFilters: (updater: Updater<ColumnFiltersState>) => void
 }
@@ -190,11 +200,11 @@ export interface Table_RowModels_Filtered<
   TData extends RowData,
 > {
   /**
-   * Returns the row model for the table after **column** filtering has been applied.
+   * Resolves the row model after column and global filters have been applied.
    */
   getFilteredRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns the row model for the table before any **column** filtering has been applied.
+   * Reads the row model immediately before filtering.
    */
   getPreFilteredRowModel: () => RowModel<TFeatures, TData>
 }

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

@@ -9,13 +9,14 @@ import type {
 } from './columnFilteringFeature.types'
 
 /**
- * Returns the default column filters state.
+ * Creates the default column filter state.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * The feature default is an empty array, meaning no column filters are active.
+ * Reset APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultColumnFiltersState()
+ * const filters = getDefaultColumnFiltersState()
  * ```
  */
 export function getDefaultColumnFiltersState(): ColumnFiltersState {
@@ -23,13 +24,15 @@ export function getDefaultColumnFiltersState(): ColumnFiltersState {
 }
 
 /**
- * Infers filter fn for a column.
+ * Chooses a built-in filter function from the column's first core row value.
  *
- * The inference uses the column definition, table options, and sampled row values when needed.
+ * Strings use `includesString`, numbers use `inNumberRange`, booleans and
+ * objects use `equals`, arrays use `arrIncludes`, and unknown values fall back
+ * to `weakEquals`.
  *
  * @example
  * ```ts
- * const value = column_getAutoFilterFn(column)
+ * const filterFn = column_getAutoFilterFn(column)
  * ```
  */
 export function column_getAutoFilterFn<
@@ -68,13 +71,15 @@ export function column_getAutoFilterFn<
 }
 
 /**
- * Returns filter fn for a column.
+ * Resolves the filter function configured for a column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Function-valued `columnDef.filterFn` is returned directly, `'auto'` delegates
+ * to `column_getAutoFilterFn`, and string values are looked up in the table's
+ * filter function registry.
  *
  * @example
  * ```ts
- * const value = column_getFilterFn(column)
+ * const filterFn = column_getFilterFn(column)
  * ```
  */
 export function column_getFilterFn<
@@ -103,13 +108,14 @@ export function column_getFilterFn<
 }
 
 /**
- * Returns whether a column can use filter.
+ * Checks whether column filtering is enabled for this accessor column.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * The column must have an accessor and filtering must be enabled by the column
+ * definition, `enableColumnFilters`, and the table-wide `enableFilters` option.
  *
  * @example
  * ```ts
- * const value = column_getCanFilter(column)
+ * const canFilter = column_getCanFilter(column)
  * ```
  */
 export function column_getCanFilter<
@@ -126,13 +132,14 @@ export function column_getCanFilter<
 }
 
 /**
- * Returns is filtered for a column.
+ * Checks whether this column currently has an entry in `state.columnFilters`.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * This only reflects filter state presence; it does not indicate whether the
+ * filter removes any rows.
  *
  * @example
  * ```ts
- * const value = column_getIsFiltered(column)
+ * const isFiltered = column_getIsFiltered(column)
  * ```
  */
 export function column_getIsFiltered<
@@ -144,9 +151,9 @@ export function column_getIsFiltered<
 }
 
 /**
- * Returns filter value for a column.
+ * Reads this column's current filter value from `state.columnFilters`.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Missing filter entries return `undefined`.
  *
  * @example
  * ```ts
@@ -164,13 +171,13 @@ export function column_getFilterValue<
 }
 
 /**
- * Returns filter index for a column.
+ * Finds this column's position in the ordered `state.columnFilters` array.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The result is `-1` when the column has no active filter.
  *
  * @example
  * ```ts
- * const value = column_getFilterIndex(column)
+ * const index = column_getFilterIndex(column)
  * ```
  */
 export function column_getFilterIndex<
@@ -186,13 +193,14 @@ export function column_getFilterIndex<
 }
 
 /**
- * Updates filter value for a column.
+ * Adds, updates, or removes this column's filter value.
  *
- * This delegates to the owning table state updater so external state, external atoms, and internal state stay synchronized.
+ * The incoming value may be an updater. After resolution, `autoRemove` rules
+ * decide whether the filter should be removed instead of stored.
  *
  * @example
  * ```ts
- * column_setFilterValue(column, (old) => old)
+ * column_setFilterValue(column, (old) => String(old ?? '').trim())
  * ```
  */
 export function column_setFilterValue<
@@ -233,13 +241,15 @@ export function column_setFilterValue<
 }
 
 /**
- * Updates the table's column filters state slice.
+ * Routes a column filter updater through the table's filter change handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The resolved filters are cleaned before they are emitted: filters for known
+ * columns are removed when their filter function says the value should be
+ * auto-removed.
  *
  * @example
  * ```ts
- * table_setColumnFilters(table, (old) => old)
+ * table_setColumnFilters(table, (old) => old.filter((filter) => filter.id !== 'age'))
  * ```
  */
 export function table_setColumnFilters<
@@ -271,9 +281,10 @@ export function table_setColumnFilters<
 }
 
 /**
- * Resets the table's column filters state slice.
+ * Resets `columnFilters` to the configured initial state or feature default.
  *
- * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ * With no argument, the reset clones `table.initialState.columnFilters` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
  *
  * @example
  * ```ts

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

@@ -66,7 +66,9 @@ export interface ColumnDef_ColumnGrouping<
    */
   aggregationFn?: AggregationFnOption<TFeatures, TData>
   /**
-   * Enables/disables grouping for this column.
+   * Allows this column to be added to grouping state.
+   *
+   * Defaults to `true`; table-level `enableGrouping` must also allow grouping.
    */
   enableGrouping?: boolean
   /**
@@ -88,15 +90,15 @@ export interface Column_ColumnGrouping<
    */
   getAutoAggregationFn: () => AggregationFn<TFeatures, TData> | undefined
   /**
-   * Returns whether or not the column can be grouped.
+   * Checks whether this column can currently be grouped.
    */
   getCanGroup: () => boolean
   /**
-   * Returns the index of the column in the grouping state.
+   * Finds this column's position in the ordered grouping state.
    */
   getGroupedIndex: () => number
   /**
-   * Returns whether or not the column is currently grouped.
+   * Checks whether this column id is present in grouping state.
    */
   getIsGrouped: () => boolean
   /**
@@ -112,11 +114,11 @@ export interface Column_ColumnGrouping<
 export interface Row_ColumnGrouping {
   _groupingValuesCache: Record<string, any>
   /**
-   * Returns the grouping value for any row and column (including leaf rows).
+   * Reads the value used to group this row for a column id.
    */
   getGroupingValue: (columnId: string) => unknown
   /**
-   * Returns whether or not the row is currently grouped.
+   * Checks whether this row represents a grouped row.
    */
   getIsGrouped: () => boolean
   /**
@@ -131,15 +133,15 @@ export interface Row_ColumnGrouping {
 
 export interface Cell_ColumnGrouping {
   /**
-   * Returns whether or not the cell is currently aggregated.
+   * Checks whether this cell should render an aggregated value.
    */
   getIsAggregated: () => boolean
   /**
-   * Returns whether or not the cell is currently grouped.
+   * Checks whether this cell represents the active grouping column.
    */
   getIsGrouped: () => boolean
   /**
-   * Returns whether or not the cell is currently a placeholder cell.
+   * Checks whether this cell is hidden as a grouping placeholder.
    */
   getIsPlaceholder: () => boolean
 }
@@ -151,7 +153,7 @@ export interface ColumnDefaultOptions {
 
 export interface TableOptions_ColumnGrouping {
   /**
-   * Enables/disables grouping for the table.
+   * Allows columns to be grouped for this table.
    */
   enableGrouping?: boolean
   /**
@@ -177,11 +179,13 @@ export interface Table_ColumnGrouping<
   TData extends RowData,
 > {
   /**
-   * Resets the **grouping** state to `initialState.grouping`, or `true` can be passed to force a default blank state reset to `[]`.
+   * Resets `grouping` to `initialState.grouping`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
    */
   resetGrouping: (defaultState?: boolean) => void
   /**
-   * Sets grouping state using a value or updater.
+   * Updates grouping state with a next ordered id array or updater function.
    */
   setGrouping: (updater: Updater<GroupingState>) => void
 }
@@ -191,11 +195,11 @@ export interface Table_RowModels_Grouped<
   TData extends RowData,
 > {
   /**
-   * Returns the row model for the table after grouping has been applied.
+   * Resolves the row model after grouping and aggregation have been applied.
    */
   getGroupedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns the row model for the table before any grouping has been applied.
+   * Reads the row model immediately before grouping.
    */
   getPreGroupedRowModel: () => RowModel<TFeatures, TData>
 }