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

package/dist/features/column-grouping/columnGroupingFeature.utils.d.cts

@@ -8,20 +8,22 @@ import { Cell } from "../../types/Cell.cjs";
 
 //#region src/features/column-grouping/columnGroupingFeature.utils.d.ts
 /**
- * Returns the default grouping state.
+ * Creates the default grouping 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 columns are grouped. Reset
+ * APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultGroupingState()
+ * const grouping = getDefaultGroupingState()
  * ```
  */
 declare function getDefaultGroupingState(): GroupingState;
 /**
- * Toggles grouping for a column.
+ * Adds or removes this column id from the grouping state.
  *
- * The update is applied through the owning table state slice and respects the feature options for that column.
+ * Existing grouped columns keep their order. A column already present in
+ * `state.grouping` is removed; otherwise it is appended.
  *
  * @example
  * ```ts
@@ -30,86 +32,93 @@ declare function getDefaultGroupingState(): GroupingState;
  */
 declare function column_toggleGrouping<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): void;
 /**
- * Returns whether a column can use group.
+ * Checks whether this column can be used for grouping.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * Grouping must be enabled at the column and table level, and the column must
+ * either have an accessor or provide `getGroupingValue`.
  *
  * @example
  * ```ts
- * const value = column_getCanGroup(column)
+ * const canGroup = column_getCanGroup(column)
  * ```
  */
 declare function column_getCanGroup<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): boolean;
 /**
- * Returns is grouped for a column.
+ * Checks whether this column id is present in `state.grouping`.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The result only reflects grouping state, not whether the grouped row model has
+ * been calculated yet.
  *
  * @example
  * ```ts
- * const value = column_getIsGrouped(column)
+ * const isGrouped = column_getIsGrouped(column)
  * ```
  */
 declare function column_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): boolean;
 /**
- * Returns grouped index for a column.
+ * Finds this column's position in the ordered grouping state.
  *
- * 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 is not grouped.
  *
  * @example
  * ```ts
- * const value = column_getGroupedIndex(column)
+ * const index = column_getGroupedIndex(column)
  * ```
  */
 declare function column_getGroupedIndex<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): number;
 /**
- * Returns an event handler for toggling grouping handler.
+ * Creates a header/control handler that toggles grouping for this column.
  *
- * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ * The handler is a no-op when `column_getCanGroup(column)` is false.
  *
  * @example
  * ```ts
- * const value = column_getToggleGroupingHandler(column)
+ * const onClick = column_getToggleGroupingHandler(column)
  * ```
  */
 declare function column_getToggleGroupingHandler<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): () => void;
 /**
- * Infers aggregation fn for a column.
+ * Chooses a built-in aggregation function from the first core row value.
  *
- * The inference uses the column definition, table options, and sampled row values when needed.
+ * Numeric columns default to `sum`, date-like values default to `extent`, and
+ * other value types leave aggregation unspecified.
  *
  * @example
  * ```ts
- * const value = column_getAutoAggregationFn(column)
+ * const aggregationFn = column_getAutoAggregationFn(column)
  * ```
  */
 declare function column_getAutoAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): AggregationFn<TFeatures, TData> | undefined;
 /**
- * Returns aggregation fn for a column.
+ * Resolves the aggregation 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.aggregationFn` is returned directly, `'auto'`
+ * delegates to `column_getAutoAggregationFn`, and string values are looked up in
+ * the table's aggregation function registry.
  *
  * @example
  * ```ts
- * const value = column_getAggregationFn(column)
+ * const aggregationFn = column_getAggregationFn(column)
  * ```
  */
 declare function column_getAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): AggregationFn<TFeatures, TData> | undefined;
 /**
- * Updates the table's grouping state slice.
+ * Routes a grouping updater through the table's grouping change handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The updater may be a next `GroupingState` array or a function of the previous
+ * grouping state, matching the instance `table.setGrouping` behavior.
  *
  * @example
  * ```ts
- * table_setGrouping(table, (old) => old)
+ * table_setGrouping(table, (old) => [...old, 'status'])
  * ```
  */
 declare function table_setGrouping<TFeatures extends TableFeatures, TData extends RowData>(table: Table_Internal<TFeatures, TData>, updater: Updater<GroupingState>): void;
 /**
- * Resets the table's grouping state slice.
+ * Resets `grouping` 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.grouping` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
  *
  * @example
  * ```ts
@@ -119,57 +128,60 @@ declare function table_setGrouping<TFeatures extends TableFeatures, TData extend
  */
 declare function table_resetGrouping<TFeatures extends TableFeatures, TData extends RowData>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean): void;
 /**
- * Returns is grouped for a row.
+ * Checks whether this row was created as a grouped row.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * Grouped rows carry a `groupingColumnId`; ordinary leaf rows do not.
  *
  * @example
  * ```ts
- * const value = row_getIsGrouped(row)
+ * const isGrouped = row_getIsGrouped(row)
  * ```
  */
 declare function row_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>): boolean;
 /**
- * Returns grouping value for a row.
+ * Reads and caches this row's grouping value for a column.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * `columnDef.getGroupingValue` wins when provided; otherwise the normal row
+ * accessor value is used.
  *
  * @example
  * ```ts
- * const value = row_getGroupingValue(row)
+ * const groupValue = row_getGroupingValue(row, 'status')
  * ```
  */
 declare function row_getGroupingValue<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>, columnId: string): any;
 /**
- * Returns is grouped for a cell.
+ * Checks whether this cell represents the grouped column for a grouped row.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * This is the cell that usually renders the grouped value and expansion control.
  *
  * @example
  * ```ts
- * const value = cell_getIsGrouped(cell)
+ * const isGroupedCell = cell_getIsGrouped(cell)
  * ```
  */
 declare function cell_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
 /**
- * Returns is placeholder for a cell.
+ * Checks whether this cell is a placeholder hidden by grouping.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * Placeholder cells belong to grouped columns other than the row's active
+ * grouping column.
  *
  * @example
  * ```ts
- * const value = cell_getIsPlaceholder(cell)
+ * const isPlaceholder = cell_getIsPlaceholder(cell)
  * ```
  */
 declare function cell_getIsPlaceholder<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
 /**
- * Returns is aggregated for a cell.
+ * Checks whether this cell should render an aggregated value.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * Aggregated cells are non-placeholder, non-grouped cells on rows that have
+ * subRows.
  *
  * @example
  * ```ts
- * const value = cell_getIsAggregated(cell)
+ * const isAggregated = cell_getIsAggregated(cell)
  * ```
  */
 declare function cell_getIsAggregated<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;

package/dist/features/column-grouping/columnGroupingFeature.utils.d.ts

@@ -8,20 +8,22 @@ import { Cell } from "../../types/Cell.js";
 
 //#region src/features/column-grouping/columnGroupingFeature.utils.d.ts
 /**
- * Returns the default grouping state.
+ * Creates the default grouping 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 columns are grouped. Reset
+ * APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultGroupingState()
+ * const grouping = getDefaultGroupingState()
  * ```
  */
 declare function getDefaultGroupingState(): GroupingState;
 /**
- * Toggles grouping for a column.
+ * Adds or removes this column id from the grouping state.
  *
- * The update is applied through the owning table state slice and respects the feature options for that column.
+ * Existing grouped columns keep their order. A column already present in
+ * `state.grouping` is removed; otherwise it is appended.
  *
  * @example
  * ```ts
@@ -30,86 +32,93 @@ declare function getDefaultGroupingState(): GroupingState;
  */
 declare function column_toggleGrouping<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): void;
 /**
- * Returns whether a column can use group.
+ * Checks whether this column can be used for grouping.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * Grouping must be enabled at the column and table level, and the column must
+ * either have an accessor or provide `getGroupingValue`.
  *
  * @example
  * ```ts
- * const value = column_getCanGroup(column)
+ * const canGroup = column_getCanGroup(column)
  * ```
  */
 declare function column_getCanGroup<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): boolean;
 /**
- * Returns is grouped for a column.
+ * Checks whether this column id is present in `state.grouping`.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The result only reflects grouping state, not whether the grouped row model has
+ * been calculated yet.
  *
  * @example
  * ```ts
- * const value = column_getIsGrouped(column)
+ * const isGrouped = column_getIsGrouped(column)
  * ```
  */
 declare function column_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): boolean;
 /**
- * Returns grouped index for a column.
+ * Finds this column's position in the ordered grouping state.
  *
- * 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 is not grouped.
  *
  * @example
  * ```ts
- * const value = column_getGroupedIndex(column)
+ * const index = column_getGroupedIndex(column)
  * ```
  */
 declare function column_getGroupedIndex<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): number;
 /**
- * Returns an event handler for toggling grouping handler.
+ * Creates a header/control handler that toggles grouping for this column.
  *
- * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ * The handler is a no-op when `column_getCanGroup(column)` is false.
  *
  * @example
  * ```ts
- * const value = column_getToggleGroupingHandler(column)
+ * const onClick = column_getToggleGroupingHandler(column)
  * ```
  */
 declare function column_getToggleGroupingHandler<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): () => void;
 /**
- * Infers aggregation fn for a column.
+ * Chooses a built-in aggregation function from the first core row value.
  *
- * The inference uses the column definition, table options, and sampled row values when needed.
+ * Numeric columns default to `sum`, date-like values default to `extent`, and
+ * other value types leave aggregation unspecified.
  *
  * @example
  * ```ts
- * const value = column_getAutoAggregationFn(column)
+ * const aggregationFn = column_getAutoAggregationFn(column)
  * ```
  */
 declare function column_getAutoAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): AggregationFn<TFeatures, TData> | undefined;
 /**
- * Returns aggregation fn for a column.
+ * Resolves the aggregation 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.aggregationFn` is returned directly, `'auto'`
+ * delegates to `column_getAutoAggregationFn`, and string values are looked up in
+ * the table's aggregation function registry.
  *
  * @example
  * ```ts
- * const value = column_getAggregationFn(column)
+ * const aggregationFn = column_getAggregationFn(column)
  * ```
  */
 declare function column_getAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): AggregationFn<TFeatures, TData> | undefined;
 /**
- * Updates the table's grouping state slice.
+ * Routes a grouping updater through the table's grouping change handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The updater may be a next `GroupingState` array or a function of the previous
+ * grouping state, matching the instance `table.setGrouping` behavior.
  *
  * @example
  * ```ts
- * table_setGrouping(table, (old) => old)
+ * table_setGrouping(table, (old) => [...old, 'status'])
  * ```
  */
 declare function table_setGrouping<TFeatures extends TableFeatures, TData extends RowData>(table: Table_Internal<TFeatures, TData>, updater: Updater<GroupingState>): void;
 /**
- * Resets the table's grouping state slice.
+ * Resets `grouping` 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.grouping` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
  *
  * @example
  * ```ts
@@ -119,57 +128,60 @@ declare function table_setGrouping<TFeatures extends TableFeatures, TData extend
  */
 declare function table_resetGrouping<TFeatures extends TableFeatures, TData extends RowData>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean): void;
 /**
- * Returns is grouped for a row.
+ * Checks whether this row was created as a grouped row.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * Grouped rows carry a `groupingColumnId`; ordinary leaf rows do not.
  *
  * @example
  * ```ts
- * const value = row_getIsGrouped(row)
+ * const isGrouped = row_getIsGrouped(row)
  * ```
  */
 declare function row_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>): boolean;
 /**
- * Returns grouping value for a row.
+ * Reads and caches this row's grouping value for a column.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * `columnDef.getGroupingValue` wins when provided; otherwise the normal row
+ * accessor value is used.
  *
  * @example
  * ```ts
- * const value = row_getGroupingValue(row)
+ * const groupValue = row_getGroupingValue(row, 'status')
  * ```
  */
 declare function row_getGroupingValue<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>, columnId: string): any;
 /**
- * Returns is grouped for a cell.
+ * Checks whether this cell represents the grouped column for a grouped row.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * This is the cell that usually renders the grouped value and expansion control.
  *
  * @example
  * ```ts
- * const value = cell_getIsGrouped(cell)
+ * const isGroupedCell = cell_getIsGrouped(cell)
  * ```
  */
 declare function cell_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
 /**
- * Returns is placeholder for a cell.
+ * Checks whether this cell is a placeholder hidden by grouping.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * Placeholder cells belong to grouped columns other than the row's active
+ * grouping column.
  *
  * @example
  * ```ts
- * const value = cell_getIsPlaceholder(cell)
+ * const isPlaceholder = cell_getIsPlaceholder(cell)
  * ```
  */
 declare function cell_getIsPlaceholder<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
 /**
- * Returns is aggregated for a cell.
+ * Checks whether this cell should render an aggregated value.
  *
- * This is the static implementation behind the matching cell instance API and uses the owning row and column context.
+ * Aggregated cells are non-placeholder, non-grouped cells on rows that have
+ * subRows.
  *
  * @example
  * ```ts
- * const value = cell_getIsAggregated(cell)
+ * const isAggregated = cell_getIsAggregated(cell)
  * ```
  */
 declare function cell_getIsAggregated<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;