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

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
 }

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

@@ -8,10 +8,30 @@ import type { Column_Internal } from '../../types/Column'
 import type { ColumnPinningPosition } from '../column-pinning/columnPinningFeature.types'
 import type { ColumnOrderState } from './columnOrderingFeature.types'
 
+/**
+ * Returns the default column order state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnOrderState()
+ * ```
+ */
 export function getDefaultColumnOrderState(): ColumnOrderState {
   return []
 }
 
+/**
+ * Returns 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_getIndex(column)
+ * ```
+ */
 export function column_getIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -24,6 +44,16 @@ export function column_getIndex<
   return columns.findIndex((d) => d.id === column.id)
 }
 
+/**
+ * Returns is first column 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_getIsFirstColumn(column)
+ * ```
+ */
 export function column_getIsFirstColumn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -36,6 +66,16 @@ export function column_getIsFirstColumn<
   return columns[0]?.id === column.id
 }
 
+/**
+ * Returns is last column 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_getIsLastColumn(column)
+ * ```
+ */
 export function column_getIsLastColumn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -48,6 +88,16 @@ export function column_getIsLastColumn<
   return columns[columns.length - 1]?.id === column.id
 }
 
+/**
+ * Updates the table's column order state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnOrder(table, (old) => old)
+ * ```
+ */
 export function table_setColumnOrder<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -55,6 +105,17 @@ export function table_setColumnOrder<
   table.options.onColumnOrderChange?.(updater)
 }
 
+/**
+ * Resets the table's column order state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnOrder(table)
+ * table_resetColumnOrder(table, true)
+ * ```
+ */
 export function table_resetColumnOrder<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -65,6 +126,16 @@ export function table_resetColumnOrder<
   )
 }
 
+/**
+ * Returns order columns fn for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getOrderColumnsFn(table)
+ * ```
+ */
 export function table_getOrderColumnsFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -80,30 +151,43 @@ export function table_getOrderColumnsFn<
     if (!columnOrder?.length) {
       orderedColumns = columns
     } else {
-      const columnOrderCopy = [...columnOrder]
-
-      // If there is an order, make a copy of the columns
-      const columnsCopy = [...columns]
-
-      // And make a new ordered array of the columns
-
-      // Loop over the columns and place them in order into the new array
-      while (columnsCopy.length && columnOrderCopy.length) {
-        const targetColumnId = columnOrderCopy.shift()
-        const foundIndex = columnsCopy.findIndex((d) => d.id === targetColumnId)
-        if (foundIndex > -1) {
-          orderedColumns.push(columnsCopy.splice(foundIndex, 1)[0]!)
+      // Index columns by id for O(1) lookup
+      const remaining = new Map<
+        string,
+        Column_Internal<TFeatures, TData, unknown>
+      >()
+      for (const column of columns) 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) {
+        const column = remaining.get(id)
+        if (column) {
+          orderedColumns.push(column)
+          remaining.delete(id)
         }
       }
 
-      // If there are any columns left, add them to the end
-      orderedColumns = [...orderedColumns, ...columnsCopy]
+      // Append leftover columns in their original order
+      for (const column of columns) {
+        if (remaining.has(column.id)) orderedColumns.push(column)
+      }
     }
 
     return orderColumns(table, orderedColumns)
   }
 }
 
+/**
+ * Orders leaf columns with manual ordering, grouping, and pinning rules.
+ *
+ * This helper is used by the column ordering feature to produce the final visible column order.
+ *
+ * @example
+ * ```ts
+ * const orderedColumns = orderColumns(leafColumns, columnOrder, grouping, groupedColumnMode)
+ * ```
+ */
 export function orderColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -126,9 +210,17 @@ export function orderColumns<
     return nonGroupingColumns
   }
 
-  const groupingColumns = grouping
-    .map((g) => leafColumns.find((col) => col.id === g)!)
-    .filter(Boolean)
+  const leafColumnsById = new Map<
+    string,
+    Column_Internal<TFeatures, TData, unknown>
+  >()
+  for (const col of leafColumns) leafColumnsById.set(col.id, col)
+
+  const groupingColumns: Array<Column_Internal<TFeatures, TData, unknown>> = []
+  for (const g of grouping) {
+    const col = leafColumnsById.get(g)
+    if (col) groupingColumns.push(col)
+  }
 
   return [...groupingColumns, ...nonGroupingColumns]
 }

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

@@ -61,6 +61,11 @@ export interface ColumnPinningFeatureConstructors<
   // TableState: TableState_ColumnPinning
 }
 
+/**
+ * Creates the stock column pinning feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnPinningFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -296,11 +301,7 @@ export function constructColumnPinningFeature<
         },
         table_getPinnedLeafColumns: {
           fn: (position) => table_getPinnedLeafColumns(table, position),
-          memoDeps: (position) => [
-            position,
-            table.options.columns,
-            table.atoms.columnPinning?.get(),
-          ],
+          // must not memo here as it's just a shortcut function
         },
         // visible leaf columns
         table_getLeftVisibleLeafColumns: {
@@ -329,12 +330,7 @@ export function constructColumnPinningFeature<
         },
         table_getPinnedVisibleLeafColumns: {
           fn: (position) => table_getPinnedVisibleLeafColumns(table, position),
-          memoDeps: (position) => [
-            position,
-            table.options.columns,
-            table.atoms.columnPinning?.get(),
-            table.atoms.columnVisibility?.get(),
-          ],
+          // must not memo here as it's just a shortcut function
         },
       })
     },
@@ -342,6 +338,9 @@ export function constructColumnPinningFeature<
 }
 
 /**
- * The Column Pinning feature adds column pinning state and APIs to the table, row, and column objects.
+ * The stock column pinning feature.
+ *
+ * Register this feature to add column pinning state plus table, row, and column
+ * APIs for splitting columns into left, center, and right regions.
  */
 export const columnPinningFeature = constructColumnPinningFeature()

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

@@ -22,7 +22,9 @@ export interface TableOptions_ColumnPinning {
    */
   enableColumnPinning?: boolean
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnPinning` changes. This overrides the default internal state management, so you will also need to supply `state.columnPinning` from your own managed state.
+   * Called with an updater when column pinning state changes. Pair this with
+   * `state.columnPinning` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onColumnPinningChange?: OnChangeFn<ColumnPinningState>
 }
@@ -160,15 +162,17 @@ export interface Table_ColumnPinning<
    */
   resetColumnPinning: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.columnPinning` state.
+   * Sets column pinning state using a value or updater.
    */
   setColumnPinning: (updater: Updater<ColumnPinningState>) => void
   /**
+   * Returns pinned leaf columns for the requested pinning region.
    */
   getPinnedLeafColumns: (
     position: ColumnPinningPosition | 'center',
   ) => Array<Column<TFeatures, TData, unknown>>
   /**
+   * Returns visible pinned leaf columns for the requested pinning region.
    */
   getPinnedVisibleLeafColumns: (
     position: ColumnPinningPosition | 'center',