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

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

@@ -13,13 +13,14 @@ import type {
 } from './columnGroupingFeature.types'
 
 /**
- * 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()
  * ```
  */
 export function getDefaultGroupingState(): GroupingState {
@@ -27,9 +28,10 @@ export 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
@@ -52,13 +54,14 @@ export function column_toggleGrouping<
 }
 
 /**
- * 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)
  * ```
  */
 export function column_getCanGroup<
@@ -74,13 +77,14 @@ export function column_getCanGroup<
 }
 
 /**
- * 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)
  * ```
  */
 export function column_getIsGrouped<
@@ -92,13 +96,13 @@ export function column_getIsGrouped<
 }
 
 /**
- * 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)
  * ```
  */
 export function column_getGroupedIndex<
@@ -110,13 +114,13 @@ export function column_getGroupedIndex<
 }
 
 /**
- * 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)
  * ```
  */
 export function column_getToggleGroupingHandler<
@@ -133,13 +137,14 @@ export function column_getToggleGroupingHandler<
 }
 
 /**
- * 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)
  * ```
  */
 export function column_getAutoAggregationFn<
@@ -165,13 +170,15 @@ export function column_getAutoAggregationFn<
 }
 
 /**
- * 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)
  * ```
  */
 export function column_getAggregationFn<
@@ -191,13 +198,14 @@ export function column_getAggregationFn<
 }
 
 /**
- * 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'])
  * ```
  */
 export function table_setGrouping<
@@ -208,9 +216,10 @@ export function table_setGrouping<
 }
 
 /**
- * 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
@@ -229,13 +238,13 @@ export function table_resetGrouping<
 }
 
 /**
- * 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)
  * ```
  */
 export function row_getIsGrouped<
@@ -246,13 +255,14 @@ export function row_getIsGrouped<
 }
 
 /**
- * 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')
  * ```
  */
 export function row_getGroupingValue<
@@ -282,13 +292,13 @@ export function row_getGroupingValue<
 }
 
 /**
- * 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)
  * ```
  */
 export function cell_getIsGrouped<
@@ -303,13 +313,14 @@ export function cell_getIsGrouped<
 }
 
 /**
- * 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)
  * ```
  */
 export function cell_getIsPlaceholder<
@@ -321,13 +332,14 @@ export function cell_getIsPlaceholder<
 }
 
 /**
- * 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)
  * ```
  */
 export function cell_getIsAggregated<

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

@@ -19,15 +19,22 @@ export interface TableOptions_ColumnOrdering {
 
 export interface Column_ColumnOrdering {
   /**
-   * Returns the index of the column in the order of the visible columns. Optionally pass a `position` parameter to get the index of the column in a sub-section of the table
+   * Finds this column's zero-based index among visible columns.
+   *
+   * Pass `'left'`, `'center'`, or `'right'` to measure within that pinned
+   * region instead of the full visible leaf order.
    */
   getIndex: (position?: ColumnPinningPosition | 'center') => number
   /**
-   * Returns `true` if the column is the first column in the order of the visible columns. Optionally pass a `position` parameter to check if the column is the first in a sub-section of the table.
+   * Checks whether this column is the first visible column.
+   *
+   * Pass a pinned region to check the first column within that region.
    */
   getIsFirstColumn: (position?: ColumnPinningPosition | 'center') => boolean
   /**
-   * Returns `true` if the column is the last column in the order of the visible columns. Optionally pass a `position` parameter to check if the column is the last in a sub-section of the table.
+   * Checks whether this column is the last visible column.
+   *
+   * Pass a pinned region to check the last column within that region.
    */
   getIsLastColumn: (position?: ColumnPinningPosition | 'center') => boolean
 }
@@ -41,11 +48,13 @@ export interface Table_ColumnOrdering<
   TData extends RowData,
 > {
   /**
-   * Resets the **columnOrder** state to `initialState.columnOrder`, or `true` can be passed to force a default blank state reset to `[]`.
+   * Resets `columnOrder` to `initialState.columnOrder`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
    */
   resetColumnOrder: (defaultState?: boolean) => void
   /**
-   * Sets column order state using a value or updater.
+   * Updates column order state with a next ordered id array or updater function.
    */
   setColumnOrder: (updater: Updater<ColumnOrderState>) => void
 }

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

@@ -9,13 +9,14 @@ import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeatu
 import type { ColumnOrderState } from './columnOrderingFeature.types'
 
 /**
- * Returns the default column order state.
+ * Creates the default column order 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 leaf columns keep their natural
+ * definition order. Reset APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultColumnOrderState()
+ * const order = getDefaultColumnOrderState()
  * ```
  */
 export function getDefaultColumnOrderState(): ColumnOrderState {
@@ -23,13 +24,14 @@ export function getDefaultColumnOrderState(): ColumnOrderState {
 }
 
 /**
- * Returns index for a column.
+ * Finds this column's index within a visible pinning region.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Pass `'left'`, `'center'`, or `'right'` to search that region; omit the
+ * position to search the full visible leaf column list.
  *
  * @example
  * ```ts
- * const value = column_getIndex(column)
+ * const index = column_getIndex(column, 'center')
  * ```
  */
 export function column_getIndex<
@@ -45,13 +47,13 @@ export function column_getIndex<
 }
 
 /**
- * Returns is first column for a column.
+ * Checks whether this column is the first visible column in a pinning region.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The same `position` semantics as `column_getIndex` apply.
  *
  * @example
  * ```ts
- * const value = column_getIsFirstColumn(column)
+ * const isFirst = column_getIsFirstColumn(column, 'left')
  * ```
  */
 export function column_getIsFirstColumn<
@@ -67,13 +69,13 @@ export function column_getIsFirstColumn<
 }
 
 /**
- * Returns is last column for a column.
+ * Checks whether this column is the last visible column in a pinning region.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The same `position` semantics as `column_getIndex` apply.
  *
  * @example
  * ```ts
- * const value = column_getIsLastColumn(column)
+ * const isLast = column_getIsLastColumn(column, 'right')
  * ```
  */
 export function column_getIsLastColumn<
@@ -89,13 +91,14 @@ export function column_getIsLastColumn<
 }
 
 /**
- * Updates the table's column order state slice.
+ * Routes a column order updater through the table's column-order 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 ordered id array or a function of the previous
+ * array, matching the instance `table.setColumnOrder` behavior.
  *
  * @example
  * ```ts
- * table_setColumnOrder(table, (old) => old)
+ * table_setColumnOrder(table, ['firstName', 'lastName', 'age'])
  * ```
  */
 export function table_setColumnOrder<
@@ -106,9 +109,10 @@ export function table_setColumnOrder<
 }
 
 /**
- * Resets the table's column order state slice.
+ * Resets `columnOrder` 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.columnOrder` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
  *
  * @example
  * ```ts
@@ -127,13 +131,14 @@ export function table_resetColumnOrder<
 }
 
 /**
- * Returns order columns fn for the table.
+ * Creates the ordering function used to arrange leaf columns.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The returned function applies `state.columnOrder`, preserves unspecified
+ * columns in their original order, then delegates to grouping rules.
  *
  * @example
  * ```ts
- * const value = table_getOrderColumnsFn(table)
+ * const orderColumnsForTable = table_getOrderColumnsFn(table)
  * ```
  */
 export function table_getOrderColumnsFn<
@@ -184,13 +189,15 @@ export function table_getOrderColumnsFn<
 }
 
 /**
- * Orders leaf columns with manual ordering, grouping, and pinning rules.
+ * Applies grouped-column placement rules to an already ordered leaf-column list.
  *
- * This helper is used by the column ordering feature to produce the final visible column order.
+ * `groupedColumnMode: 'remove'` drops grouped columns from the list.
+ * `groupedColumnMode: 'reorder'` moves grouped columns to the front in grouping
+ * state order.
  *
  * @example
  * ```ts
- * const orderedColumns = orderColumns(leafColumns, columnOrder, grouping, groupedColumnMode)
+ * const orderedColumns = orderColumns(table, leafColumns)
  * ```
  */
 export function orderColumns<

package/src/features/column-pinning/columnPinningFeature.types.ts

@@ -18,7 +18,10 @@ export interface TableState_ColumnPinning {
 
 export interface TableOptions_ColumnPinning {
   /**
-   * Enables/disables column pinning for the table. Defaults to `true`.
+   * Allows columns to be pinned into left and right regions.
+   *
+   * Defaults to `true`; column-level `enablePinning` can still opt individual
+   * columns out.
    */
   enableColumnPinning?: boolean
   /**
@@ -35,26 +38,30 @@ export interface ColumnPinningDefaultOptions {
 
 export interface ColumnDef_ColumnPinning {
   /**
-   * Enables/disables column pinning for this column. Defaults to `true`.
+   * Allows this column's leaf columns to be pinned.
+   *
+   * Defaults to `true`; table-level `enableColumnPinning` must also allow
+   * pinning.
    */
   enablePinning?: boolean
 }
 
 export interface Column_ColumnPinning {
   /**
-   * Returns whether or not the column can be pinned.
+   * Checks whether this column or any of its leaves can be pinned.
    */
   getCanPin: () => boolean
   /**
-   * Returns the pinned position of the column. (`'left'`, `'right'` or `false`)
+   * Reads the column's pinned position: `'left'`, `'right'`, or `false`.
    */
   getIsPinned: () => ColumnPinningPosition
   /**
-   * Returns the numeric pinned index of the column within a pinned column group.
+   * Finds this column's index within its pinned region.
    */
   getPinnedIndex: () => number
   /**
-   * Pins a column to the `'left'` or `'right'`, or unpins the column to the center if `false` is passed.
+   * Pins this column's leaf columns left or right, or unpins them when `false`
+   * is passed.
    */
   pin: (position: ColumnPinningPosition) => void
 }
@@ -64,15 +71,15 @@ export interface Row_ColumnPinning<
   TData extends RowData,
 > {
   /**
-   * Returns all center pinned (unpinned) leaf cells in the row.
+   * Gets visible row cells whose columns are not pinned left or right.
    */
   getCenterVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
-   * Returns all left pinned leaf cells in the row.
+   * Gets visible row cells whose columns are pinned left.
    */
   getLeftVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
-   * Returns all right pinned leaf cells in the row.
+   * Gets visible row cells whose columns are pinned right.
    */
   getRightVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
 }
@@ -82,87 +89,92 @@ export interface Table_ColumnPinning<
   TData extends RowData,
 > {
   /**
-   * If pinning, returns headers for all columns that are not pinned, including parent headers.
+   * Builds flat center-region headers for columns that are not pinned,
+   * including parent headers.
    */
   getCenterFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns the footer groups for columns that are not pinned.
+   * Builds footer groups for the center region of unpinned columns.
    */
   getCenterFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * If pinning, returns the header groups for columns that are not pinned.
+   * Builds header groups for the center region of unpinned columns.
    */
   getCenterHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns all center pinned (unpinned) leaf columns.
+   * Gets leaf columns that are not pinned left or right.
    */
   getCenterLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns headers for all columns that are not pinned, (not including parent headers).
+   * Builds center-region leaf headers for columns that are not pinned.
    */
   getCenterLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * If column pinning, returns a flat array of leaf-node columns that are visible in the unpinned/center portion of the table.
+   * Lists visible leaf columns in the unpinned center region.
    */
   getCenterVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Returns whether or not any columns are pinned. Optionally specify to only check for pinned columns in either the `left` or `right` position.
+   * Checks whether any columns are pinned, optionally limited to one side.
    */
   getIsSomeColumnsPinned: (position?: ColumnPinningPosition) => boolean
   /**
-   * If pinning, returns headers for all left pinned columns in the table, including parent headers.
+   * Builds flat left-region headers for pinned columns, including parent
+   * headers.
    */
   getLeftFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns the footer groups for the left pinned columns.
+   * Builds footer groups for left-pinned columns.
    */
   getLeftFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * If pinning, returns the header groups for the left pinned columns.
+   * Builds header groups for left-pinned columns.
    */
   getLeftHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns all left pinned leaf columns.
+   * Gets leaf columns pinned to the left region in pinning-state order.
    */
   getLeftLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns headers for all left pinned leaf columns in the table, (not including parent headers).
+   * Builds leaf headers for left-pinned columns.
    */
   getLeftLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * If column pinning, returns a flat array of leaf-node columns that are visible in the left portion of the table.
+   * Lists visible leaf columns in the left pinned region.
    */
   getLeftVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns headers for all right pinned columns in the table, including parent headers.
+   * Builds flat right-region headers for pinned columns, including parent
+   * headers.
    */
   getRightFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns the footer groups for the right pinned columns.
+   * Builds footer groups for right-pinned columns.
    */
   getRightFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * If pinning, returns the header groups for the right pinned columns.
+   * Builds header groups for right-pinned columns.
    */
   getRightHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns all right pinned leaf columns.
+   * Gets leaf columns pinned to the right region in pinning-state order.
    */
   getRightLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * If pinning, returns headers for all right pinned leaf columns in the table, (not including parent headers).
+   * Builds leaf headers for right-pinned columns.
    */
   getRightLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * If column pinning, returns a flat array of leaf-node columns that are visible in the right portion of the table.
+   * Lists visible leaf columns in the right pinned region.
    */
   getRightVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Resets the **columnPinning** state to `initialState.columnPinning`, or `true` can be passed to force a default blank state reset to `{ left: [], right: [], }`.
+   * Resets `columnPinning` to `initialState.columnPinning`.
+   *
+   * Pass `true` to ignore initial state and reset to empty left/right arrays.
    */
   resetColumnPinning: (defaultState?: boolean) => void
   /**
-   * Sets column pinning state using a value or updater.
+   * Updates column pinning state with a next state or updater function.
    */
   setColumnPinning: (updater: Updater<ColumnPinningState>) => void
   /**
@@ -172,7 +184,7 @@ export interface Table_ColumnPinning<
     position: ColumnPinningPosition | 'center',
   ) => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Returns visible pinned leaf columns for the requested pinning region.
+   * Lists visible leaf columns for the requested pinning region.
    */
   getPinnedVisibleLeafColumns: (
     position: ColumnPinningPosition | 'center',