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

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

@@ -9,13 +9,14 @@ import type { ColumnVisibilityState } from './columnVisibilityFeature.types'
 import type { Row } from '../../types/Row'
 
 /**
- * Returns the default column visibility state.
+ * Creates the default column visibility 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 object, where missing column ids are treated
+ * as visible. Reset APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultColumnVisibilityState()
+ * const visibility = getDefaultColumnVisibilityState()
  * ```
  */
 export function getDefaultColumnVisibilityState(): ColumnVisibilityState {
@@ -23,9 +24,10 @@ export function getDefaultColumnVisibilityState(): ColumnVisibilityState {
 }
 
 /**
- * Toggles visibility for a column.
+ * Updates this column's visibility when hiding is allowed.
  *
- * The update is applied through the owning table state slice and respects the feature options for that column.
+ * Passing `visible` stores that value. Omitting it flips the column's current
+ * visibility state. Columns that cannot hide are left unchanged.
  *
  * @example
  * ```ts
@@ -48,13 +50,15 @@ export function column_toggleVisibility<
 }
 
 /**
- * Returns is visible for a column.
+ * Checks whether this column is visible.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Leaf columns read `state.columnVisibility[column.id]`, where missing entries
+ * default to visible. Parent columns are visible when at least one child column
+ * is visible.
  *
  * @example
  * ```ts
- * const value = column_getIsVisible(column)
+ * const visible = column_getIsVisible(column)
  * ```
  */
 export function column_getIsVisible<
@@ -73,13 +77,13 @@ export function column_getIsVisible<
 }
 
 /**
- * Returns whether a column can use hide.
+ * Checks whether this column is allowed to be hidden.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * Both `columnDef.enableHiding` and table `enableHiding` default to `true`.
  *
  * @example
  * ```ts
- * const value = column_getCanHide(column)
+ * const canHide = column_getCanHide(column)
  * ```
  */
 export function column_getCanHide<
@@ -94,13 +98,14 @@ export function column_getCanHide<
 }
 
 /**
- * Returns an event handler for toggling visibility handler.
+ * Creates a checkbox-style handler that writes this column's visibility.
  *
- * The handler is intended for direct use in column header controls such as buttons or checkboxes.
+ * The handler reads `event.target.checked`, so it is intended for visibility
+ * controls whose checked state means "visible".
  *
  * @example
  * ```ts
- * const value = column_getToggleVisibilityHandler(column)
+ * const onChange = column_getToggleVisibilityHandler(column)
  * ```
  */
 export function column_getToggleVisibilityHandler<
@@ -117,63 +122,96 @@ export function column_getToggleVisibilityHandler<
 }
 
 /**
- * Returns visible cells for a row.
+ * Collects the cells from this row whose columns are visible.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * When column pinning is active, the result is ordered as left-pinned cells,
+ * center cells, then right-pinned cells.
  *
  * @example
  * ```ts
- * const value = row_getVisibleCells(row)
+ * const visibleCells = row_getVisibleCells(row)
  * ```
  */
 export function row_getVisibleCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
-  const cells = row
-    .getAllCells()
-    .filter((cell) =>
-      callMemoOrStaticFn(cell.column, 'getIsVisible', column_getIsVisible),
-    )
+  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 cells // no pinning, return early
+  if (!left.length && !right.length) return visibleCells // no pinning, return early
 
-  const cellsByColumnId = new Map<string, Cell<TFeatures, TData, unknown>>()
-  for (const cell of cells) cellsByColumnId.set(cell.column.id, cell)
+  const visibleCellsByColumnId = callMemoOrStaticFn(
+    row,
+    'getVisibleCellsByColumnId',
+    row_getVisibleCellsByColumnId,
+  )
 
   const leftCells: Array<Cell<TFeatures, TData, unknown>> = []
-  for (const columnId of left) {
-    const cell = cellsByColumnId.get(columnId)
+  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 (const columnId of right) {
-    const cell = cellsByColumnId.get(columnId)
+  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 leftSet = new Set(left)
-  const rightSet = new Set(right)
   const centerCells: Array<Cell<TFeatures, TData, unknown>> = []
-  for (const cell of cells) {
+  for (let i = 0; i < visibleCells.length; i++) {
+    const cell = visibleCells[i]!
     const id = cell.column.id
-    if (!leftSet.has(id) && !rightSet.has(id)) centerCells.push(cell)
+    if (!left.includes(id) && !right.includes(id)) centerCells.push(cell)
   }
 
   return [...leftCells, ...centerCells, ...rightCells]
 }
 
 /**
- * Returns visible flat columns for the table.
+ * Builds a lookup map of this row's visible cells keyed by column id.
+ *
+ * Hidden columns are omitted from the map.
+ *
+ * @example
+ * ```ts
+ * const visibleCellsById = row_getVisibleCellsByColumnId(row)
+ * ```
+ */
+export function row_getVisibleCellsByColumnId<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(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
+}
+
+/**
+ * Filters the flat column list down to visible columns.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Parent/group columns are included when `column_getIsVisible` considers them
+ * visible.
  *
  * @example
  * ```ts
- * const value = table_getVisibleFlatColumns(table)
+ * const columns = table_getVisibleFlatColumns(table)
  * ```
  */
 export function table_getVisibleFlatColumns<
@@ -188,13 +226,14 @@ export function table_getVisibleFlatColumns<
 }
 
 /**
- * Returns visible leaf columns for the table.
+ * Filters leaf columns down to those currently visible.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * This is the column list most row rendering code uses before pinning-specific
+ * partitioning.
  *
  * @example
  * ```ts
- * const value = table_getVisibleLeafColumns(table)
+ * const columns = table_getVisibleLeafColumns(table)
  * ```
  */
 export function table_getVisibleLeafColumns<
@@ -209,13 +248,14 @@ export function table_getVisibleLeafColumns<
 }
 
 /**
- * Updates the table's column visibility state slice.
+ * Routes a column visibility updater through the table's visibility 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 visibility map or a function of the previous map,
+ * matching the instance `table.setColumnVisibility` behavior.
  *
  * @example
  * ```ts
- * table_setColumnVisibility(table, (old) => old)
+ * table_setColumnVisibility(table, (old) => ({ ...old, age: false }))
  * ```
  */
 export function table_setColumnVisibility<
@@ -229,9 +269,10 @@ export function table_setColumnVisibility<
 }
 
 /**
- * Resets the table's column visibility state slice.
+ * Resets `columnVisibility` 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.columnVisibility` when
+ * it exists. Passing `true` ignores initial state and resets to `{}`.
  *
  * @example
  * ```ts
@@ -250,9 +291,9 @@ export function table_resetColumnVisibility<
 }
 
 /**
- * Toggles all columns visible for the table.
+ * Shows or hides every hideable leaf column.
  *
- * This is the table-level convenience API used by UI controls that affect many columns or rows at once.
+ * Columns that cannot hide stay visible when toggling all columns off.
  *
  * @example
  * ```ts
@@ -266,7 +307,9 @@ export function table_toggleAllColumnsVisible<
   value = value ?? !table_getIsAllColumnsVisible(table)
 
   const visibility: Record<string, boolean> = {}
-  for (const column of table.getAllLeafColumns()) {
+  const leafColumns = table.getAllLeafColumns()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const column = leafColumns[i]!
     visibility[column.id] = !value ? !column_getCanHide(column) : value
   }
 
@@ -274,13 +317,14 @@ export function table_toggleAllColumnsVisible<
 }
 
 /**
- * Returns is all columns visible for the table.
+ * Checks whether every leaf column is currently visible.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Non-hideable columns are naturally visible because missing visibility entries
+ * default to `true`.
  *
  * @example
  * ```ts
- * const value = table_getIsAllColumnsVisible(table)
+ * const allVisible = table_getIsAllColumnsVisible(table)
  * ```
  */
 export function table_getIsAllColumnsVisible<
@@ -296,13 +340,13 @@ export function table_getIsAllColumnsVisible<
 }
 
 /**
- * Returns is some columns visible for the table.
+ * Checks whether at least one leaf column is currently visible.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * This is useful for tri-state "show all columns" controls.
  *
  * @example
  * ```ts
- * const value = table_getIsSomeColumnsVisible(table)
+ * const someVisible = table_getIsSomeColumnsVisible(table)
  * ```
  */
 export function table_getIsSomeColumnsVisible<
@@ -317,13 +361,14 @@ export function table_getIsSomeColumnsVisible<
 }
 
 /**
- * Returns an event handler for all columns visibility handler.
+ * Creates a checkbox-style handler that shows or hides all columns.
  *
- * The handler calls the matching table toggle API and can be attached directly to checkbox or button UI.
+ * The handler reads `event.target.checked`, so it is intended for controls whose
+ * checked state means "all columns visible".
  *
  * @example
  * ```ts
- * const value = table_getToggleAllColumnsVisibilityHandler(table)
+ * const onChange = table_getToggleAllColumnsVisibilityHandler(table)
  * ```
  */
 export function table_getToggleAllColumnsVisibilityHandler<

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

@@ -17,14 +17,17 @@ export interface TableState_GlobalFiltering {
 
 export interface ColumnDef_GlobalFiltering {
   /**
-   * Enables/disables the **global** filter for this column.
+   * Allows this column to be scanned by global filtering.
+   *
+   * Defaults to `true`; table-level global filtering and `enableFilters` must
+   * also allow filtering.
    */
   enableGlobalFilter?: boolean
 }
 
 export interface Column_GlobalFiltering {
   /**
-   * Returns whether or not the column can be **globally** filtered. Set to `false` to disable a column from being scanned during global filtering.
+   * Checks whether this accessor column participates in global filtering.
    */
   getCanGlobalFilter: () => boolean
 }
@@ -34,7 +37,7 @@ export interface TableOptions_GlobalFiltering<
   TData extends RowData,
 > {
   /**
-   * Enables/disables **global** filtering for all columns.
+   * Enables global filtering across columns that allow it.
    */
   enableGlobalFilter?: boolean
   /**
@@ -76,11 +79,13 @@ export interface Table_GlobalFiltering<
    */
   getGlobalFilterFn: () => FilterFn<TFeatures, TData> | undefined
   /**
-   * Resets the **globalFilter** state to `initialState.globalFilter`, or `true` can be passed to force a default blank state reset to `undefined`.
+   * Resets `globalFilter` to `initialState.globalFilter`.
+   *
+   * Pass `true` to ignore initial state and reset to `undefined`.
    */
   resetGlobalFilter: (defaultState?: boolean) => void
   /**
-   * Sets global filter state using a value or updater.
+   * Updates global filter state with a next value or updater function.
    */
   setGlobalFilter: (updater: Updater<any>) => void
 }

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

@@ -7,13 +7,14 @@ import type { TableFeatures } from '../../types/TableFeatures'
 import type { Table_Internal } from '../../types/Table'
 
 /**
- * Returns whether a column can use global filter.
+ * Checks whether this accessor column participates in global filtering.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * The column must have an accessor and pass column-level, table-level, and
+ * optional `getColumnCanGlobalFilter` checks.
  *
  * @example
  * ```ts
- * const value = column_getCanGlobalFilter(column)
+ * const canGlobalFilter = column_getCanGlobalFilter(column)
  * ```
  */
 export function column_getCanGlobalFilter<
@@ -31,13 +32,14 @@ export function column_getCanGlobalFilter<
 }
 
 /**
- * Returns global auto filter fn for the table.
+ * Provides the built-in automatic global filter function.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Global filtering defaults to `includesString`, which gives search-box style
+ * matching across globally filterable columns.
  *
  * @example
  * ```ts
- * const value = table_getGlobalAutoFilterFn(table)
+ * const filterFn = table_getGlobalAutoFilterFn()
  * ```
  */
 export function table_getGlobalAutoFilterFn() {
@@ -45,13 +47,15 @@ export function table_getGlobalAutoFilterFn() {
 }
 
 /**
- * Returns global filter fn for the table.
+ * Resolves the filter function used for global filtering.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Function-valued `options.globalFilterFn` is returned directly, `'auto'`
+ * delegates to `table_getGlobalAutoFilterFn`, and string values are looked up in
+ * the table's filter function registry.
  *
  * @example
  * ```ts
- * const value = table_getGlobalFilterFn(table)
+ * const filterFn = table_getGlobalFilterFn(table)
  * ```
  */
 export function table_getGlobalFilterFn<
@@ -72,13 +76,14 @@ export function table_getGlobalFilterFn<
 }
 
 /**
- * Updates the table's global filter state slice.
+ * Routes a global filter updater through the table's global filter 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 value or a function of the previous value, matching
+ * the instance `table.setGlobalFilter` behavior.
  *
  * @example
  * ```ts
- * table_setGlobalFilter(table, (old) => old)
+ * table_setGlobalFilter(table, 'search text')
  * ```
  */
 export function table_setGlobalFilter<
@@ -89,9 +94,10 @@ export function table_setGlobalFilter<
 }
 
 /**
- * Resets the table's global filter state slice.
+ * Resets `globalFilter` 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.globalFilter`. Passing
+ * `true` ignores initial state and resets to `undefined`.
  *
  * @example
  * ```ts

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

@@ -13,19 +13,19 @@ export interface TableState_RowExpanding {
 
 export interface Row_RowExpanding {
   /**
-   * Returns whether the row can be expanded.
+   * Checks whether this row can be expanded.
    */
   getCanExpand: () => boolean
   /**
-   * Returns whether all parent rows of the row are expanded.
+   * Checks whether every ancestor of this row is expanded.
    */
   getIsAllParentsExpanded: () => boolean
   /**
-   * Returns whether the row is expanded.
+   * Checks whether this row is currently expanded.
    */
   getIsExpanded: () => boolean
   /**
-   * Returns a function that can be used to toggle the expanded state of the row. This function can be used to bind to an event handler to a button.
+   * Creates a handler that toggles this row's expanded state.
    */
   getToggleExpandedHandler: () => () => void
   /**
@@ -43,7 +43,7 @@ export interface TableOptions_RowExpanding<
    */
   autoResetExpanded?: boolean
   /**
-   * Enable/disable expanding for all rows.
+   * Allows rows with subRows to be expanded.
    */
   enableExpanding?: boolean
   /**
@@ -76,32 +76,33 @@ export interface Table_RowExpanding<
 > {
   autoResetExpanded: () => void
   /**
-   * Returns whether there are any rows that can be expanded.
+   * Checks whether at least one row can be expanded.
    */
   getCanSomeRowsExpand: () => boolean
   /**
-   * Returns the maximum depth of the expanded rows.
+   * Computes the deepest expanded row id depth.
    */
   getExpandedDepth: () => number
   /**
-   * Returns whether all rows are currently expanded.
+   * Checks whether all rows in the current row model are expanded.
    */
   getIsAllRowsExpanded: () => boolean
   /**
-   * Returns whether there are any rows that are currently expanded.
+   * Checks whether any row is currently expanded.
    */
   getIsSomeRowsExpanded: () => boolean
   /**
-   * Returns a handler that can be used to toggle the expanded state of all rows. This handler is meant to be used with an `input[type=checkbox]` element.
+   * Creates a handler that toggles all rows expanded.
    */
   getToggleAllRowsExpandedHandler: () => (event: unknown) => void
   /**
-   * Resets expanded state to `initialState.expanded`. Pass `true` to reset to
-   * the feature default of `{}`.
+   * Resets `expanded` to `initialState.expanded`.
+   *
+   * Pass `true` to ignore initial state and reset to `{}`.
    */
   resetExpanded: (defaultState?: boolean) => void
   /**
-   * Sets expanded state using a value or updater.
+   * Updates expanded state with `true`, a row-id map, or an updater function.
    */
   setExpanded: (updater: Updater<ExpandedState>) => void
   /**
@@ -115,11 +116,11 @@ export interface Table_RowModels_Expanded<
   TData extends RowData,
 > {
   /**
-   * Returns the row model after expansion has been applied.
+   * Resolves the row model after expanded rows have been flattened into view.
    */
   getExpandedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns the row model before expansion has been applied.
+   * Reads the row model immediately before expansion.
    */
   getPreExpandedRowModel: () => RowModel<TFeatures, TData>
 }