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

package/src/features/column-resizing/columnResizingFeature.utils.ts

@@ -14,13 +14,14 @@ import type { ColumnSizingState } from '../column-sizing/columnSizingFeature.typ
 import type { columnResizingState } from './columnResizingFeature.types'
 
 /**
- * Returns the default column resizing state.
+ * Creates the default transient column resizing state.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * The feature default represents no active drag interaction. Reset APIs use
+ * this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultColumnResizingState()
+ * const resizeInfo = getDefaultColumnResizingState()
  * ```
  */
 export function getDefaultColumnResizingState(): columnResizingState {
@@ -35,13 +36,14 @@ export function getDefaultColumnResizingState(): columnResizingState {
 }
 
 /**
- * Returns whether a column can use resize.
+ * Checks whether this column can start a resize interaction.
  *
- * This combines column options, table options, and any required accessor or feature state for the capability.
+ * Both `columnDef.enableResizing` and table `enableColumnResizing` default to
+ * `true`.
  *
  * @example
  * ```ts
- * const value = column_getCanResize(column)
+ * const canResize = column_getCanResize(column)
  * ```
  */
 export function column_getCanResize<
@@ -56,13 +58,13 @@ export function column_getCanResize<
 }
 
 /**
- * Returns is resizing for a column.
+ * Checks whether this column is the active column resize target.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The value is read from `state.columnResizing.isResizingColumn`.
  *
  * @example
  * ```ts
- * const value = column_getIsResizing(column)
+ * const isResizing = column_getIsResizing(column)
  * ```
  */
 export function column_getIsResizing<
@@ -76,9 +78,11 @@ export function column_getIsResizing<
 }
 
 /**
- * Returns resize handler for a header.
+ * Creates the pointer/touch start handler for resizing a header.
  *
- * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ * The handler records starting sizes for all leaf headers, tracks drag deltas,
+ * writes transient resize info, and commits column sizes on change or drag end
+ * depending on `columnResizeMode`.
  *
  * @example
  * ```ts
@@ -263,13 +267,14 @@ export function header_getResizeHandler<
 }
 
 /**
- * Updates the table's column resizing state slice.
+ * Routes a transient column resizing updater through the table's resize handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * This state tracks the active drag interaction; committed widths live in
+ * `columnSizing`.
  *
  * @example
  * ```ts
- * table_setColumnResizing(table, (old) => old)
+ * table_setColumnResizing(table, (old) => ({ ...old, deltaOffset: 12 }))
  * ```
  */
 export function table_setColumnResizing<
@@ -283,9 +288,11 @@ export function table_setColumnResizing<
 }
 
 /**
- * Resets the table's header size info state slice.
+ * Resets `columnResizing` 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.columnResizing` when
+ * it exists. Passing `true` ignores initial state and resets to the no-drag
+ * default state.
  *
  * @example
  * ```ts
@@ -307,10 +314,12 @@ export function table_resetHeaderSizeInfo<
   )
 }
 
+let passiveSupported: boolean | null = null
 /**
  * Detects whether the current environment supports passive event listeners.
  *
- * Column resizing uses this to register pointer and touch listeners with the safest available options.
+ * Column resizing uses this to register pointer and touch listeners with
+ * `passive: false` only when the environment understands passive options.
  *
  * @example
  * ```ts
@@ -318,8 +327,6 @@ export function table_resetHeaderSizeInfo<
  * ```
  */
 export function passiveEventSupported() {
-  let passiveSupported: boolean | null = null
-
   if (typeof passiveSupported === 'boolean') return passiveSupported
 
   let supported = false
@@ -343,9 +350,10 @@ export function passiveEventSupported() {
 }
 
 /**
- * Returns whether an event is a touch-start event.
+ * Narrows an unknown event to a `touchstart` event.
  *
- * Column resizing uses this to normalize mouse and touch resize interactions.
+ * Column resizing uses this before reading touch coordinates and installing
+ * touch-specific listeners.
  *
  * @example
  * ```ts

package/src/features/column-sizing/columnSizingFeature.types.ts

@@ -23,19 +23,19 @@ export type ColumnSizingDefaultOptions = Pick<
 
 export interface Table_ColumnSizing {
   /**
-   * If pinning, returns the total size of the center portion of the table by calculating the sum of the sizes of all unpinned/center leaf-columns.
+   * Sums the current sizes of visible center-region leaf columns.
    */
   getCenterTotalSize: () => number
   /**
-   * Returns the total size of the left portion of the table by calculating the sum of the sizes of all left leaf-columns.
+   * Sums the current sizes of visible left-pinned leaf columns.
    */
   getLeftTotalSize: () => number
   /**
-   * Returns the total size of the right portion of the table by calculating the sum of the sizes of all right leaf-columns.
+   * Sums the current sizes of visible right-pinned leaf columns.
    */
   getRightTotalSize: () => number
   /**
-   * Returns the total size of the table by calculating the sum of the sizes of all leaf-columns.
+   * Sums the current sizes of all visible leaf columns.
    */
   getTotalSize: () => number
   /**
@@ -44,37 +44,44 @@ export interface Table_ColumnSizing {
    */
   resetColumnSizing: (defaultState?: boolean) => void
   /**
-   * Sets committed column sizing state using a value or updater.
+   * Updates committed column sizing state with a next map or updater function.
    */
   setColumnSizing: (updater: Updater<ColumnSizingState>) => void
 }
 
 export interface ColumnDef_ColumnSizing {
   /**
-   * The maximum allowed size for the column
+   * Upper bound used when resolving this column's size.
    */
   maxSize?: number
   /**
-   * The minimum allowed size for the column
+   * Lower bound used when resolving this column's size.
    */
   minSize?: number
   /**
-   * The desired size for the column
+   * Initial size used before column sizing state overrides it.
    */
   size?: number
 }
 
 export interface Column_ColumnSizing {
   /**
-   * Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the header. This is effectively a sum of the offset measurements of all succeeding (right) headers in relation to the current column.
+   * Measures the offset from this column's end edge to the end of its region.
+   *
+   * Pass a pinned region to measure within that region. The value is the sum
+   * of visible leaf column sizes after this column.
    */
   getAfter: (position?: ColumnPinningPosition | 'center') => number
   /**
-   * Returns the current size of the column.
+   * Resolves the column's current size after state and min/max constraints.
    */
   getSize: () => number
   /**
-   * Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the header. This is effectively a sum of the offset measurements of all preceding (left) headers in relation to the current column.
+   * Measures the offset from the start of this column's region to its start
+   * edge.
+   *
+   * Pass a pinned region to measure within that region. The value is the sum
+   * of visible leaf column sizes before this column.
    */
   getStart: (position?: ColumnPinningPosition | 'center') => number
   /**
@@ -85,7 +92,7 @@ export interface Column_ColumnSizing {
 
 export interface Header_ColumnSizing {
   /**
-   * Returns the current size of the header.
+   * Computes this header's rendered size from its leaf columns.
    */
   getSize: () => number
   /**

package/src/features/column-sizing/columnSizingFeature.utils.ts

@@ -15,13 +15,14 @@ import type { Column_Internal } from '../../types/Column'
 import type { ColumnSizingState } from './columnSizingFeature.types'
 
 /**
- * Returns the default column sizing state.
+ * Creates the default committed column sizing 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 map, so columns fall back to their column def
+ * size or the built-in sizing defaults.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultColumnSizingState()
+ * const sizing = getDefaultColumnSizingState()
  * ```
  */
 export function getDefaultColumnSizingState(): ColumnSizingState {
@@ -29,13 +30,15 @@ export function getDefaultColumnSizingState(): ColumnSizingState {
 }
 
 /**
- * Returns the default column sizing column def.
+ * Creates the built-in sizing defaults for column definitions.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * Columns default to `size: 150`, `minSize: 20`, and
+ * `maxSize: Number.MAX_SAFE_INTEGER` unless overridden by column definitions or
+ * table defaults.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultColumnSizingColumnDef()
+ * const defaults = getDefaultColumnSizingColumnDef()
  * ```
  */
 export function getDefaultColumnSizingColumnDef() {
@@ -47,13 +50,14 @@ export function getDefaultColumnSizingColumnDef() {
 }
 
 /**
- * Returns size for a column.
+ * Resolves a column's current pixel size.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Committed `state.columnSizing[column.id]` wins over `columnDef.size`, then the
+ * built-in default size. The result is clamped between min and max size.
  *
  * @example
  * ```ts
- * const value = column_getSize(column)
+ * const width = column_getSize(column)
  * ```
  */
 export function column_getSize<
@@ -74,13 +78,14 @@ export function column_getSize<
 }
 
 /**
- * Returns start for a column.
+ * Computes the offset from the start edge of a pinning region to this column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The value is the sum of all previous visible leaf column sizes in the
+ * requested `'left'`, `'center'`, or `'right'` region.
  *
  * @example
  * ```ts
- * const value = column_getStart(column)
+ * const leftOffset = column_getStart(column, 'left')
  * ```
  */
 export function column_getStart<
@@ -114,13 +119,14 @@ export function column_getStart<
 }
 
 /**
- * Returns after for a column.
+ * Computes the offset from the end edge of a pinning region after this column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * The value is the sum of all following visible leaf column sizes in the
+ * requested region.
  *
  * @example
  * ```ts
- * const value = column_getAfter(column)
+ * const rightOffset = column_getAfter(column, 'right')
  * ```
  */
 export function column_getAfter<
@@ -153,13 +159,14 @@ export function column_getAfter<
 }
 
 /**
- * Reset Size. for a column.
+ * Removes this column's committed size override.
  *
- * This is the static implementation behind the matching column instance API.
+ * After reset, the column resolves size from `columnDef.size` or built-in
+ * defaults again.
  *
  * @example
  * ```ts
- * const value = column_resetSize(column)
+ * column_resetSize(column)
  * ```
  */
 export function column_resetSize<
@@ -173,13 +180,14 @@ export function column_resetSize<
 }
 
 /**
- * Returns size for a header.
+ * Computes a header's rendered size from its leaf headers.
  *
- * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ * Group headers sum the sizes of all descendant leaf columns. Leaf headers use
+ * their column's current size.
  *
  * @example
  * ```ts
- * const value = header_getSize(header)
+ * const width = header_getSize(header)
  * ```
  */
 export function header_getSize<
@@ -203,13 +211,14 @@ export function header_getSize<
 }
 
 /**
- * Returns start for a header.
+ * Computes a header's offset from the start of its header group.
  *
- * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ * The offset is the previous sibling header's start plus size, or `0` for the
+ * first header in the group.
  *
  * @example
  * ```ts
- * const value = header_getStart(header)
+ * const offset = header_getStart(header)
  * ```
  */
 export function header_getStart<
@@ -233,13 +242,14 @@ export function header_getStart<
 // Table APIs
 
 /**
- * Updates the table's column sizing state slice.
+ * Routes a committed column sizing updater through the table's sizing 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 size map or a function of the previous map,
+ * matching the instance `table.setColumnSizing` behavior.
  *
  * @example
  * ```ts
- * table_setColumnSizing(table, (old) => old)
+ * table_setColumnSizing(table, (old) => ({ ...old, age: 96 }))
  * ```
  */
 export function table_setColumnSizing<
@@ -253,9 +263,10 @@ export function table_setColumnSizing<
 }
 
 /**
- * Resets the table's column sizing state slice.
+ * Resets `columnSizing` 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.columnSizing` when it
+ * exists. Passing `true` ignores initial state and resets to `{}`.
  *
  * @example
  * ```ts
@@ -274,13 +285,13 @@ export function table_resetColumnSizing<
 }
 
 /**
- * Returns total size for the table.
+ * Sums the rendered size of the full table header row.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * This includes left, center, and right columns in the main header group.
  *
  * @example
  * ```ts
- * const value = table_getTotalSize(table)
+ * const width = table_getTotalSize(table)
  * ```
  */
 export function table_getTotalSize<
@@ -295,13 +306,13 @@ export function table_getTotalSize<
 }
 
 /**
- * Returns left total size for the table.
+ * Sums the rendered size of the left pinned header region.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * An empty left pinning region returns `0`.
  *
  * @example
  * ```ts
- * const value = table_getLeftTotalSize(table)
+ * const width = table_getLeftTotalSize(table)
  * ```
  */
 export function table_getLeftTotalSize<
@@ -320,13 +331,13 @@ export function table_getLeftTotalSize<
 }
 
 /**
- * Returns center total size for the table.
+ * Sums the rendered size of the center, unpinned header region.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * An empty center region returns `0`.
  *
  * @example
  * ```ts
- * const value = table_getCenterTotalSize(table)
+ * const width = table_getCenterTotalSize(table)
  * ```
  */
 export function table_getCenterTotalSize<
@@ -345,13 +356,13 @@ export function table_getCenterTotalSize<
 }
 
 /**
- * Returns right total size for the table.
+ * Sums the rendered size of the right pinned header region.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * An empty right pinning region returns `0`.
  *
  * @example
  * ```ts
- * const value = table_getRightTotalSize(table)
+ * const width = table_getRightTotalSize(table)
  * ```
  */
 export function table_getRightTotalSize<

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

@@ -32,31 +32,34 @@ export interface Table_ColumnVisibility<
   TData extends RowData,
 > {
   /**
-   * Returns whether all columns are visible
+   * Checks whether every leaf column is currently visible.
    */
   getIsAllColumnsVisible: () => boolean
   /**
-   * Returns whether any columns are visible
+   * Checks whether at least one leaf column is currently visible.
    */
   getIsSomeColumnsVisible: () => boolean
   /**
-   * Returns a handler for toggling the visibility of all columns, meant to be bound to a `input[type=checkbox]` element.
+   * Creates a checkbox-style handler that shows or hides all columns.
    */
   getToggleAllColumnsVisibilityHandler: () => (event: unknown) => void
   /**
-   * Returns a flat array of columns that are visible, including parent columns.
+   * Lists visible columns in flat table order, including parent columns that
+   * have visible descendants.
    */
   getVisibleFlatColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Returns a flat array of leaf-node columns that are visible.
+   * Lists visible leaf columns in the order used for row cells and headers.
    */
   getVisibleLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
   /**
-   * Resets the column visibility state to the initial state. If `defaultState` is provided, the state will be reset to `{}`
+   * Resets `columnVisibility` to `initialState.columnVisibility`.
+   *
+   * Pass `true` to ignore initial state and reset to `{}`.
    */
   resetColumnVisibility: (defaultState?: boolean) => void
   /**
-   * Sets column visibility state using a value or updater.
+   * Updates column visibility state with a next map or updater function.
    */
   setColumnVisibility: (updater: Updater<ColumnVisibilityState>) => void
   /**
@@ -67,7 +70,7 @@ export interface Table_ColumnVisibility<
 
 export interface ColumnDef_ColumnVisibility {
   /**
-   * Enables/disables column hiding for this column. Defaults to `true`.
+   * Allows this column to be hidden. Defaults to `true`.
    */
   enableHiding?: boolean
 }
@@ -77,11 +80,11 @@ export interface Row_ColumnVisibility<
   TData extends RowData,
 > {
   /**
-   * Returns an array of cells that account for column visibility for the row.
+   * Gets this row's cells for currently visible columns.
    */
   getVisibleCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
-   * Returns visible cells by column id for the row.
+   * Maps this row's currently visible cells by column id.
    */
   getVisibleCellsByColumnId: () => Record<
     string,
@@ -91,15 +94,15 @@ export interface Row_ColumnVisibility<
 
 export interface Column_ColumnVisibility {
   /**
-   * Returns whether the column can be hidden
+   * Checks whether this column is allowed to be hidden.
    */
   getCanHide: () => boolean
   /**
-   * Returns whether the column is visible
+   * Checks whether this column is currently visible.
    */
   getIsVisible: () => boolean
   /**
-   * Returns a function that can be used to toggle the column visibility. This function can be used to bind to an event handler to a checkbox.
+   * Creates a checkbox-style handler that toggles this column's visibility.
    */
   getToggleVisibilityHandler: () => (event: unknown) => void
   /**