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

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

@@ -3,19 +3,14 @@ import {
   assignTableAPIs,
   makeStateUpdater,
 } from '../../utils'
-import {
-  row_getCenterVisibleCells,
-  row_getLeftVisibleCells,
-  row_getRightVisibleCells,
-} from '../column-pinning/columnPinningFeature.utils'
 import {
   column_getCanHide,
   column_getIsVisible,
   column_getToggleVisibilityHandler,
   column_toggleVisibility,
   getDefaultColumnVisibilityState,
-  row_getAllVisibleCells,
   row_getVisibleCells,
+  row_getVisibleCellsByColumnId,
   table_getIsAllColumnsVisible,
   table_getIsSomeColumnsVisible,
   table_getToggleAllColumnsVisibilityHandler,
@@ -48,6 +43,11 @@ export interface ColumnVisibilityFeatureConstructors<
   // TableState: TableState_ColumnVisibility
 }
 
+/**
+ * Creates the stock column visibility feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnVisibilityFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -71,8 +71,8 @@ export function constructColumnVisibilityFeature<
         column_getIsVisible: {
           fn: (column) => column_getIsVisible(column),
           memoDeps: (column) => [
-            column.table.options.columns,
-            column.table.atoms.columnVisibility?.get(),
+            table.options.columns,
+            table.atoms.columnVisibility?.get(),
             column.columns,
           ],
         },
@@ -90,20 +90,19 @@ export function constructColumnVisibilityFeature<
 
     assignRowPrototype: (prototype, table) => {
       assignPrototypeAPIs('columnVisibilityFeature', prototype, table, {
-        row_getAllVisibleCells: {
-          fn: (row) => row_getAllVisibleCells(row),
+        row_getVisibleCells: {
+          fn: (row) => row_getVisibleCells(row),
           memoDeps: (row) => [
             row.getAllCells(),
-            row.table.atoms.columnVisibility?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
           ],
         },
-        row_getVisibleCells: {
-          fn: (row, left, center, right) =>
-            row_getVisibleCells(left, center, right),
+        row_getVisibleCellsByColumnId: {
+          fn: (row) => row_getVisibleCellsByColumnId(row),
           memoDeps: (row) => [
-            row_getLeftVisibleCells(row),
-            row_getCenterVisibleCells(row),
-            row_getRightVisibleCells(row),
+            row.getAllCells(),
+            table.atoms.columnVisibility?.get(),
           ],
         },
       })
@@ -152,6 +151,9 @@ export function constructColumnVisibilityFeature<
 }
 
 /**
- * The Column Visibility feature adds column visibility state and APIs to the table, row, and column objects.
+ * The stock column visibility feature.
+ *
+ * Register this feature to add column visibility state and APIs for deriving
+ * visible columns and visible row cells.
  */
 export const columnVisibilityFeature = constructColumnVisibilityFeature()

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,11 +76,17 @@ 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.
    */
   getVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
+  /**
+   * Returns visible cells by column id for the row.
+   */
+  getVisibleCellsByColumnId: () => Record<
+    string,
+    Cell<TFeatures, TData, unknown>
+  >
 }
 
 export interface Column_ColumnVisibility {

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,97 @@ 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
-    .getAllCells()
-    .filter((cell) =>
-      callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible),
-    )
+>(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
+  const allCells = row.getAllCells()
+  const visibleCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < allCells.length; i++) {
+    const cell = allCells[i]!
+    if (callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible)) {
+      visibleCells.push(cell)
+    }
+  }
+
+  const { left, right } =
+    row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
+  if (!left.length && !right.length) return visibleCells // no pinning, return early
+
+  const visibleCellsByColumnId = callMemoOrStaticFn(
+    row,
+    'getVisibleCellsByColumnId',
+    row_getVisibleCellsByColumnId,
+  )
+
+  const leftCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < left.length; i++) {
+    const cell = visibleCellsByColumnId[left[i]!]
+    if (cell) leftCells.push(cell)
+  }
+
+  const rightCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < right.length; i++) {
+    const cell = visibleCellsByColumnId[right[i]!]
+    if (cell) rightCells.push(cell)
+  }
+
+  // Center cells: visible cells in natural column order, minus pinned ones.
+  const centerCells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < visibleCells.length; i++) {
+    const cell = visibleCells[i]!
+    const id = cell.column.id
+    if (!left.includes(id) && !right.includes(id)) centerCells.push(cell)
+  }
+
+  return [...leftCells, ...centerCells, ...rightCells]
 }
 
-export function row_getVisibleCells<
+/**
+ * Returns visible cells by column id 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_getVisibleCellsByColumnId(row)
+ * ```
+ */
+export function row_getVisibleCellsByColumnId<
   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]
+>(row: Row<TFeatures, TData>): Record<string, Cell<TFeatures, TData, unknown>> {
+  const result: Record<string, Cell<TFeatures, TData, unknown>> = {}
+  const allCells = row.getAllCells()
+  for (let i = 0; i < allCells.length; i++) {
+    const cell = allCells[i]!
+    if (callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible)) {
+      result[cell.column.id] = cell
+    }
+  }
+  return result
 }
 
+/**
+ * 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 +218,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 +239,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 +259,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 +280,42 @@ 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> = {}
+  const leafColumns = table.getAllLeafColumns()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const column = leafColumns[i]!
+    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 +328,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 +349,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>,