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

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

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,

package/src/features/column-ordering/columnOrderingFeature.ts

@@ -31,6 +31,11 @@ export interface ColumnOrderingFeatureConstructors<
   // TableState: TableState_ColumnOrdering
 }
 
+/**
+ * Creates the stock column ordering feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnOrderingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -58,6 +63,7 @@ export function constructColumnOrderingFeature<
             column.table.atoms.columnOrder?.get(),
             column.table.atoms.columnPinning?.get(),
             column.table.atoms.grouping?.get(),
+            column.table.atoms.columnVisibility?.get(),
           ],
         },
         column_getIsFirstColumn: {
@@ -91,6 +97,9 @@ export function constructColumnOrderingFeature<
 }
 
 /**
- * The Column Ordering feature adds column ordering state and APIs to the table and column objects.
+ * The stock column ordering feature.
+ *
+ * Register this feature to add column order state and APIs for deriving the
+ * ordered leaf column list alongside grouping and pinning.
  */
 export const columnOrderingFeature = constructColumnOrderingFeature()

package/src/features/column-ordering/columnOrderingFeature.types.ts

@@ -10,7 +10,9 @@ export interface TableState_ColumnOrdering {
 
 export interface TableOptions_ColumnOrdering {
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnOrder` 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 order state changes. Pair this with
+   * `state.columnOrder` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onColumnOrderChange?: OnChangeFn<ColumnOrderState>
 }
@@ -43,7 +45,7 @@ export interface Table_ColumnOrdering<
    */
   resetColumnOrder: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.columnOrder` state.
+   * Sets column order state using a value or updater.
    */
   setColumnOrder: (updater: Updater<ColumnOrderState>) => void
 }