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

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<
@@ -156,11 +161,15 @@ export function table_getOrderColumnsFn<
         string,
         Column_Internal<TFeatures, TData, unknown>
       >()
-      for (const column of columns) remaining.set(column.id, column)
+      for (let i = 0; i < columns.length; i++) {
+        const column = columns[i]!
+        remaining.set(column.id, column)
+      }
 
       // Place columns in the requested order, removing each as it's used
       // (handles duplicates and unknown ids in columnOrder)
-      for (const id of columnOrder) {
+      for (let i = 0; i < columnOrder.length; i++) {
+        const id = columnOrder[i]!
         const column = remaining.get(id)
         if (column) {
           orderedColumns.push(column)
@@ -169,7 +178,8 @@ export function table_getOrderColumnsFn<
       }
 
       // Append leftover columns in their original order
-      for (const column of columns) {
+      for (let i = 0; i < columns.length; i++) {
+        const column = columns[i]!
         if (remaining.has(column.id)) orderedColumns.push(column)
       }
     }
@@ -179,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<
@@ -214,11 +226,14 @@ export function orderColumns<
     string,
     Column_Internal<TFeatures, TData, unknown>
   >()
-  for (const col of leafColumns) leafColumnsById.set(col.id, col)
+  for (let i = 0; i < leafColumns.length; i++) {
+    const col = leafColumns[i]!
+    leafColumnsById.set(col.id, col)
+  }
 
   const groupingColumns: Array<Column_Internal<TFeatures, TData, unknown>> = []
-  for (const g of grouping) {
-    const col = leafColumnsById.get(g)
+  for (let i = 0; i < grouping.length; i++) {
+    const col = leafColumnsById.get(grouping[i]!)
     if (col) groupingColumns.push(col)
   }