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

package/src/features/column-visibility/columnVisibilityFeature.types.ts

@@ -15,7 +15,9 @@ export interface TableOptions_ColumnVisibility {
    */
   enableHiding?: boolean
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnVisibility` 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 visibility state changes. Pair this with
+   * `state.columnVisibility` when using external state; external atoms can own
+   * the slice without this callback.
    */
   onColumnVisibilityChange?: OnChangeFn<ColumnVisibilityState>
 }
@@ -54,7 +56,7 @@ export interface Table_ColumnVisibility<
    */
   resetColumnVisibility: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.columnVisibility` state.
+   * Sets column visibility state using a value or updater.
    */
   setColumnVisibility: (updater: Updater<ColumnVisibilityState>) => void
   /**
@@ -74,7 +76,6 @@ export interface Row_ColumnVisibility<
   TFeatures extends TableFeatures,
   TData extends RowData,
 > {
-  getAllVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
    * Returns an array of cells that account for column visibility for the row.
    */

package/src/features/column-visibility/columnVisibilityFeature.utils.ts

@@ -1,4 +1,5 @@
 import { callMemoOrStaticFn, cloneState } from '../../utils'
+import { getDefaultColumnPinningState } from '../column-pinning/columnPinningFeature.utils'
 import type { CellData, RowData, Updater } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
@@ -7,10 +8,30 @@ import type { Column_Internal } from '../../types/Column'
 import type { ColumnVisibilityState } from './columnVisibilityFeature.types'
 import type { Row } from '../../types/Row'
 
+/**
+ * Returns the default column visibility state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnVisibilityState()
+ * ```
+ */
 export function getDefaultColumnVisibilityState(): ColumnVisibilityState {
   return {}
 }
 
+/**
+ * Toggles visibility for a column.
+ *
+ * The update is applied through the owning table state slice and respects the feature options for that column.
+ *
+ * @example
+ * ```ts
+ * column_toggleVisibility(column)
+ * ```
+ */
 export function column_toggleVisibility<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -26,6 +47,16 @@ export function column_toggleVisibility<
   }
 }
 
+/**
+ * Returns is visible 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_getIsVisible(column)
+ * ```
+ */
 export function column_getIsVisible<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -41,6 +72,16 @@ export function column_getIsVisible<
   )
 }
 
+/**
+ * Returns whether a column can use hide.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanHide(column)
+ * ```
+ */
 export function column_getCanHide<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -52,6 +93,16 @@ export function column_getCanHide<
   )
 }
 
+/**
+ * Returns an event handler for toggling visibility handler.
+ *
+ * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ *
+ * @example
+ * ```ts
+ * const value = column_getToggleVisibilityHandler(column)
+ * ```
+ */
 export function column_getToggleVisibilityHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -65,28 +116,66 @@ export function column_getToggleVisibilityHandler<
   }
 }
 
-export function row_getAllVisibleCells<
+/**
+ * Returns visible cells 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_getVisibleCells(row)
+ * ```
+ */
+export function row_getVisibleCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
->(row: Row<TFeatures, TData>) {
-  return row
+>(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
+  const cells = row
     .getAllCells()
     .filter((cell) =>
       callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible),
     )
-}
+  const { left, right } =
+    row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
+  if (!left.length && !right.length) return cells // no pinning, return early
 
-export function row_getVisibleCells<
-  TFeatures extends TableFeatures,
-  TData extends RowData,
->(
-  left: Array<Cell<TFeatures, TData, unknown>>,
-  center: Array<Cell<TFeatures, TData, unknown>>,
-  right: Array<Cell<TFeatures, TData, unknown>>,
-) {
-  return [...left, ...center, ...right]
+  const cellsByColumnId = new Map<string, Cell<TFeatures, TData, unknown>>()
+  for (const cell of cells) cellsByColumnId.set(cell.column.id, cell)
+
+  const leftCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (const columnId of left) {
+    const cell = cellsByColumnId.get(columnId)
+    if (cell) leftCells.push(cell)
+  }
+
+  const rightCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (const columnId of right) {
+    const cell = cellsByColumnId.get(columnId)
+    if (cell) rightCells.push(cell)
+  }
+
+  // Center cells: visible cells in natural column order, minus pinned ones.
+  const leftSet = new Set(left)
+  const rightSet = new Set(right)
+  const centerCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (const cell of cells) {
+    const id = cell.column.id
+    if (!leftSet.has(id) && !rightSet.has(id)) centerCells.push(cell)
+  }
+
+  return [...leftCells, ...centerCells, ...rightCells]
 }
 
+/**
+ * Returns visible flat columns 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_getVisibleFlatColumns(table)
+ * ```
+ */
 export function table_getVisibleFlatColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -98,6 +187,16 @@ export function table_getVisibleFlatColumns<
     )
 }
 
+/**
+ * Returns visible leaf columns 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_getVisibleLeafColumns(table)
+ * ```
+ */
 export function table_getVisibleLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -109,6 +208,16 @@ export function table_getVisibleLeafColumns<
     )
 }
 
+/**
+ * Updates the table's column visibility state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnVisibility(table, (old) => old)
+ * ```
+ */
 export function table_setColumnVisibility<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -119,6 +228,17 @@ export function table_setColumnVisibility<
   table.options.onColumnVisibilityChange?.(updater)
 }
 
+/**
+ * Resets the table's column visibility state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnVisibility(table)
+ * table_resetColumnVisibility(table, true)
+ * ```
+ */
 export function table_resetColumnVisibility<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -129,24 +249,40 @@ export function table_resetColumnVisibility<
   )
 }
 
+/**
+ * Toggles all columns visible for the table.
+ *
+ * This is the table-level convenience API used by UI controls that affect many columns or rows at once.
+ *
+ * @example
+ * ```ts
+ * table_toggleAllColumnsVisible(table)
+ * ```
+ */
 export function table_toggleAllColumnsVisible<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>, value?: boolean) {
   value = value ?? !table_getIsAllColumnsVisible(table)
 
-  table_setColumnVisibility(
-    table,
-    table.getAllLeafColumns().reduce(
-      (obj, column) => ({
-        ...obj,
-        [column.id]: !value ? !column_getCanHide(column) : value,
-      }),
-      {},
-    ),
-  )
+  const visibility: Record<string, boolean> = {}
+  for (const column of table.getAllLeafColumns()) {
+    visibility[column.id] = !value ? !column_getCanHide(column) : value
+  }
+
+  table_setColumnVisibility(table, visibility)
 }
 
+/**
+ * Returns is all columns visible 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_getIsAllColumnsVisible(table)
+ * ```
+ */
 export function table_getIsAllColumnsVisible<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -159,6 +295,16 @@ export function table_getIsAllColumnsVisible<
     )
 }
 
+/**
+ * Returns is some columns visible 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_getIsSomeColumnsVisible(table)
+ * ```
+ */
 export function table_getIsSomeColumnsVisible<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -170,6 +316,16 @@ export function table_getIsSomeColumnsVisible<
     )
 }
 
+/**
+ * Returns an event handler for all columns visibility handler.
+ *
+ * The handler calls the matching table toggle API and can be attached directly to checkbox or button UI.
+ *
+ * @example
+ * ```ts
+ * const value = table_getToggleAllColumnsVisibilityHandler(table)
+ * ```
+ */
 export function table_getToggleAllColumnsVisibilityHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/global-filtering/globalFilteringFeature.ts

@@ -31,6 +31,11 @@ export interface GlobalFilteringFeatureConstructors<
   // TableState: TableState_GlobalFiltering
 }
 
+/**
+ * Creates the stock global filtering feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructGlobalFilteringFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -86,7 +91,9 @@ export function constructGlobalFilteringFeature<
 }
 
 /**
- * The Global Filtering feature adds global filtering state and APIs to the table and column objects.
- * **Note:** This is dependent on the columnFilteringFeature feature.
+ * The stock global filtering feature.
+ *
+ * Register this feature with column filtering support to add global filter
+ * state, global filter function resolution, and column eligibility APIs.
  */
 export const globalFilteringFeature = constructGlobalFilteringFeature()

package/src/features/global-filtering/globalFilteringFeature.types.ts

@@ -56,7 +56,9 @@ export interface TableOptions_GlobalFiltering<
    */
   globalFilterFn?: FilterFnOption<TFeatures, TData>
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.globalFilter` 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 global filter state changes. Pair this with
+   * `state.globalFilter` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onGlobalFilterChange?: OnChangeFn<any>
 }
@@ -78,7 +80,7 @@ export interface Table_GlobalFiltering<
    */
   resetGlobalFilter: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.globalFilter` state.
+   * Sets global filter state using a value or updater.
    */
   setGlobalFilter: (updater: Updater<any>) => void
 }

package/src/features/global-filtering/globalFilteringFeature.utils.ts

@@ -6,6 +6,16 @@ import type { CellData, RowData } from '../../types/type-utils'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
 
+/**
+ * Returns whether a column can use global filter.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanGlobalFilter(column)
+ * ```
+ */
 export function column_getCanGlobalFilter<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -20,10 +30,30 @@ export function column_getCanGlobalFilter<
   )
 }
 
+/**
+ * Returns global auto filter 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_getGlobalAutoFilterFn(table)
+ * ```
+ */
 export function table_getGlobalAutoFilterFn() {
   return filterFn_includesString
 }
 
+/**
+ * Returns global filter 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_getGlobalFilterFn(table)
+ * ```
+ */
 export function table_getGlobalFilterFn<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -41,6 +71,16 @@ export function table_getGlobalFilterFn<
       : filterFns?.[globalFilterFn as string]
 }
 
+/**
+ * Updates the table's global filter state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setGlobalFilter(table, (old) => old)
+ * ```
+ */
 export function table_setGlobalFilter<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -48,6 +88,17 @@ export function table_setGlobalFilter<
   table.options.onGlobalFilterChange?.(updater)
 }
 
+/**
+ * Resets the table's global filter state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetGlobalFilter(table)
+ * table_resetGlobalFilter(table, true)
+ * ```
+ */
 export function table_resetGlobalFilter<
   TFeatures extends TableFeatures,
   TData extends RowData,

package/src/features/row-expanding/createExpandedRowModel.ts

@@ -6,6 +6,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 expanded 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 createExpandedRowModel<
   TFeatures extends TableFeatures,
   TData extends RowData = any,
@@ -48,6 +53,11 @@ function _createExpandedRowModel<
   return expandRows(rowModel)
 }
 
+/**
+ * Expands a row model according to the current expanded row state.
+ *
+ * Expanded sub-rows are inserted into the flattened row order while preserving the original row hierarchy.
+ */
 export function expandRows<
   TFeatures extends TableFeatures,
   TData extends RowData = any,

package/src/features/row-expanding/rowExpandingFeature.ts

@@ -43,6 +43,11 @@ export interface RowExpandingFeatureConstructors<
   // TableState: TableState_RowExpanding
 }
 
+/**
+ * Creates the stock row expanding feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructRowExpandingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -117,6 +122,9 @@ export function constructRowExpandingFeature<
 }
 
 /**
- * The Row Expanding feature adds row expanding state and APIs to the table and row objects.
+ * The stock row expanding feature.
+ *
+ * Register this feature to add expanded row state, row expansion APIs, and
+ * helpers for deriving expanded row models and expansion depth.
  */
 export const rowExpandingFeature = constructRowExpandingFeature()

package/src/features/row-expanding/rowExpandingFeature.types.ts

@@ -39,7 +39,7 @@ export interface TableOptions_RowExpanding<
   TData extends RowData,
 > {
   /**
-   * Enable this setting to automatically reset the expanded state of the table when expanding state changes.
+   * Enables automatic expanded-state resets when page-altering table state changes.
    */
   autoResetExpanded?: boolean
   /**
@@ -59,7 +59,9 @@ export interface TableOptions_RowExpanding<
    */
   manualExpanding?: boolean
   /**
-   * This function is called when the `expanded` table state changes. If a function is provided, you will be responsible for managing this state on your own. To pass the managed state back to the table, use the `tableOptions.state.expanded` option.
+   * Called with an updater when expanded state changes. Pair this with
+   * `state.expanded` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onExpandedChange?: OnChangeFn<ExpandedState>
   /**
@@ -94,11 +96,12 @@ export interface Table_RowExpanding<
    */
   getToggleAllRowsExpandedHandler: () => (event: unknown) => void
   /**
-   * Resets the expanded state of the table to the initial state.
+   * Resets expanded state to `initialState.expanded`. Pass `true` to reset to
+   * the feature default of `{}`.
    */
   resetExpanded: (defaultState?: boolean) => void
   /**
-   * Updates the expanded state of the table via an update function or value.
+   * Sets expanded state using a value or updater.
    */
   setExpanded: (updater: Updater<ExpandedState>) => void
   /**
@@ -126,7 +129,9 @@ export interface CreateRowModel_Expanded<
   TData extends RowData,
 > {
   /**
-   * This function is responsible for returning the expanded row model. If this function is not provided, the table will not expand rows. You can use the default exported `getExpandedRowModel` function to get the expanded row model or implement your own.
+   * Factory used to retrieve the expanded row model. If this function is not
+   * provided, the table will not expand rows. To use client-side expansion,
+   * pass `createExpandedRowModel()` or implement your own factory.
    */
   expandedRowModel?: (
     table: Table<TFeatures, TData>,