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

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

@@ -32,6 +32,11 @@ export interface ColumnResizingFeatureConstructors<
   // TableState: TableState_ColumnResizing
 }
 
+/**
+ * Creates the stock column resizing feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnResizingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -86,7 +91,9 @@ export function constructColumnResizingFeature<
 }
 
 /**
- * The Column Resizing feature adds column resizing state and APIs to the table and column objects.
- * **Note:** This is dependent on the Column Sizing feature.
+ * The stock column resizing feature.
+ *
+ * Register this feature with `columnSizingFeature` to add resize interaction
+ * state and APIs for drag-based column resizing.
  */
 export const columnResizingFeature = constructColumnResizingFeature()

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

@@ -19,19 +19,23 @@ export type ColumnResizeDirection = 'ltr' | 'rtl'
 
 export interface TableOptions_ColumnResizing {
   /**
-   * Determines when the columnSizing state is updated. `onChange` updates the state when the user is dragging the resize handle. `onEnd` updates the state when the user releases the resize handle.
+   * Determines when committed `columnSizing` values are updated. `onChange`
+   * commits sizes while the resize handle is dragged; `onEnd` commits when the
+   * resize interaction finishes.
    */
   columnResizeMode?: ColumnResizeMode
   /**
-   * Enables or disables column resizing for the column.
+   * Enables or disables column resizing for the whole table.
    */
   enableColumnResizing?: boolean
   /**
-   * Enables or disables right-to-left support for resizing the column. defaults to 'ltr'.
+   * Sets the resize direction used to calculate drag offsets. Defaults to `ltr`.
    */
   columnResizeDirection?: ColumnResizeDirection
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnResizing` changes. This overrides the default internal state management, so you will also need to supply `state.columnResizing` from your own managed state.
+   * Called with an updater when the transient `columnResizing` state changes.
+   * Pair this with `state.columnResizing` when using external state; external
+   * atoms can own the slice without this callback.
    */
   onColumnResizingChange?: OnChangeFn<columnResizingState>
 }
@@ -43,11 +47,15 @@ export type ColumnResizingDefaultOptions = Pick<
 
 export interface Table_ColumnResizing {
   /**
-   * Resets column sizing info to its initial state. If `defaultState` is `true`, the default state for the table will be used instead of the initialValue provided to the table.
+   * Resets transient resize interaction state to `initialState.columnResizing`.
+   * Pass `true` to reset to the feature's default blank resize state instead.
    */
   resetHeaderSizeInfo: (defaultState?: boolean) => void
   /**
-   * Sets the column sizing info state using an updater function or a value. This will trigger the underlying `oncolumnResizingChange` function if one is passed to the table options, otherwise the state will be managed automatically by the table.
+   * Sets the transient resize interaction state using a value or updater.
+   *
+   * The lowercase `c` in this API name matches the current generated v9 table
+   * API for the `columnResizing` state slice.
    */
   setcolumnResizing: (updater: Updater<columnResizingState>) => void
 }

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

@@ -13,6 +13,16 @@ import type { Column_Internal } from '../../types/Column'
 import type { ColumnSizingState } from '../column-sizing/columnSizingFeature.types'
 import type { columnResizingState } from './columnResizingFeature.types'
 
+/**
+ * Returns the default column resizing state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnResizingState()
+ * ```
+ */
 export function getDefaultColumnResizingState(): columnResizingState {
   return {
     startOffset: null,
@@ -24,6 +34,16 @@ export function getDefaultColumnResizingState(): columnResizingState {
   }
 }
 
+/**
+ * Returns whether a column can use resize.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanResize(column)
+ * ```
+ */
 export function column_getCanResize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -35,6 +55,16 @@ export function column_getCanResize<
   )
 }
 
+/**
+ * Returns is resizing 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_getIsResizing(column)
+ * ```
+ */
 export function column_getIsResizing<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -45,6 +75,16 @@ export function column_getIsResizing<
   )
 }
 
+/**
+ * Returns resize handler for a header.
+ *
+ * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ *
+ * @example
+ * ```ts
+ * const onMouseDown = header_getResizeHandler(header)
+ * ```
+ */
 export function header_getResizeHandler<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -222,6 +262,16 @@ export function header_getResizeHandler<
   }
 }
 
+/**
+ * Updates the table's column resizing state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnResizing(table, (old) => old)
+ * ```
+ */
 export function table_setColumnResizing<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -232,6 +282,17 @@ export function table_setColumnResizing<
   table.options.onColumnResizingChange?.(updater)
 }
 
+/**
+ * Resets the table's header size info state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetHeaderSizeInfo(table)
+ * table_resetHeaderSizeInfo(table, true)
+ * ```
+ */
 export function table_resetHeaderSizeInfo<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -246,6 +307,16 @@ export function table_resetHeaderSizeInfo<
   )
 }
 
+/**
+ * Detects whether the current environment supports passive event listeners.
+ *
+ * Column resizing uses this to register pointer and touch listeners with the safest available options.
+ *
+ * @example
+ * ```ts
+ * const canUsePassiveListeners = passiveEventSupported()
+ * ```
+ */
 export function passiveEventSupported() {
   let passiveSupported: boolean | null = null
 
@@ -271,6 +342,16 @@ export function passiveEventSupported() {
   return passiveSupported
 }
 
+/**
+ * Returns whether an event is a touch-start event.
+ *
+ * Column resizing uses this to normalize mouse and touch resize interactions.
+ *
+ * @example
+ * ```ts
+ * const isTouch = isTouchStartEvent(event)
+ * ```
+ */
 export function isTouchStartEvent(e: unknown): e is TouchEvent {
   return (e as TouchEvent).type === 'touchstart'
 }

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

@@ -1,10 +1,8 @@
 import {
   assignPrototypeAPIs,
   assignTableAPIs,
-  callMemoOrStaticFn,
   makeStateUpdater,
 } from '../../utils'
-import { table_getPinnedVisibleLeafColumns } from '../column-pinning/columnPinningFeature.utils'
 import {
   column_getAfter,
   column_getSize,
@@ -44,6 +42,11 @@ export interface ColumnSizingFeatureConstructors<
   // TableState: TableState_ColumnSizing
 }
 
+/**
+ * Creates the stock column sizing feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructColumnSizingFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -70,31 +73,31 @@ export function constructColumnSizingFeature<
       assignPrototypeAPIs('columnSizingFeature', prototype, table, {
         column_getSize: {
           fn: (column) => column_getSize(column),
+          memoDeps: (column) => [
+            table.options.columns,
+            table.atoms.columnSizing?.get()?.[column.id], // just this column's size state
+          ],
         },
         column_getStart: {
           fn: (column, position) => column_getStart(column, position),
           memoDeps: (column, position) => [
             position,
-            callMemoOrStaticFn(
-              column.table,
-              'getPinnedVisibleLeafColumns',
-              table_getPinnedVisibleLeafColumns,
-              position,
-            ),
-            column.table.atoms.columnSizing?.get(),
+            table.options.columns,
+            table.atoms.columnSizing?.get(),
+            table.atoms.columnOrder?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
           ],
         },
         column_getAfter: {
           fn: (column, position) => column_getAfter(column, position),
           memoDeps: (column, position) => [
             position,
-            callMemoOrStaticFn(
-              column.table,
-              'getPinnedVisibleLeafColumns',
-              table_getPinnedVisibleLeafColumns,
-              position,
-            ),
-            column.table.atoms.columnSizing?.get(),
+            table.options.columns,
+            table.atoms.columnSizing?.get(),
+            table.atoms.columnOrder?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
           ],
         },
         column_resetSize: {
@@ -107,9 +110,23 @@ export function constructColumnSizingFeature<
       assignPrototypeAPIs('columnSizingFeature', prototype, table, {
         header_getSize: {
           fn: (header) => header_getSize(header),
+          memoDeps: (header) => [
+            table.options.columns,
+            header.column.columns.length > 0
+              ? table.atoms.columnSizing?.get() // must be all columns (sum child columns)
+              : table.atoms.columnSizing?.get()?.[header.column.id], // can just check it's associated column size state
+          ],
         },
         header_getStart: {
           fn: (header) => header_getStart(header),
+          memoDeps: (header, position) => [
+            position,
+            table.options.columns,
+            table.atoms.columnSizing?.get(),
+            table.atoms.columnOrder?.get(),
+            table.atoms.columnPinning?.get(),
+            table.atoms.columnVisibility?.get(),
+          ],
         },
       })
     },
@@ -124,15 +141,31 @@ export function constructColumnSizingFeature<
         },
         table_getTotalSize: {
           fn: () => table_getTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
         },
         table_getLeftTotalSize: {
           fn: () => table_getLeftTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
         },
         table_getCenterTotalSize: {
           fn: () => table_getCenterTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
         },
         table_getRightTotalSize: {
           fn: () => table_getRightTotalSize(table),
+          memoDeps: () => [
+            table.atoms.columnSizing?.get(),
+            table.getHeaderGroups(),
+          ],
         },
       })
     },
@@ -140,7 +173,10 @@ export function constructColumnSizingFeature<
 }
 
 /**
- * The Column Sizing feature adds column sizing state and APIs to the table, header, and column objects.
- * **Note:** This does not include column resizing. The columnResizingFeature feature has been split out into its own standalone feature.
+ * The stock column sizing feature.
+ *
+ * Register this feature to add column width state and table, header, and column
+ * APIs for reading and resetting sizes. Column drag resizing lives in
+ * `columnResizingFeature`.
  */
 export const columnSizingFeature = constructColumnSizingFeature()

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

@@ -9,7 +9,9 @@ export type ColumnSizingState = Record<string, number>
 
 export interface TableOptions_ColumnSizing {
   /**
-   * If provided, this function will be called with an `updaterFn` when `state.columnSizing` changes. This overrides the default internal state management, so you will also need to supply `state.columnSizing` from your own managed state.
+   * Called with an updater when committed column sizing state changes. Pair
+   * this with `state.columnSizing` when using external state; external atoms
+   * can own the slice without this callback.
    */
   onColumnSizingChange?: OnChangeFn<ColumnSizingState>
 }
@@ -37,11 +39,12 @@ export interface Table_ColumnSizing {
    */
   getTotalSize: () => number
   /**
-   * Resets column sizing to its initial state. If `defaultState` is `true`, the default state for the table will be used instead of the initialValue provided to the table.
+   * Resets column sizing to `initialState.columnSizing`. Pass `true` to reset
+   * to the feature default of `{}`.
    */
   resetColumnSizing: (defaultState?: boolean) => void
   /**
-   * Sets the column sizing state using an updater function or a value. This will trigger the underlying `onColumnSizingChange` function if one is passed to the table options, otherwise the state will be managed automatically by the table.
+   * Sets committed column sizing state using a value or updater.
    */
   setColumnSizing: (updater: Updater<ColumnSizingState>) => void
 }

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

@@ -14,10 +14,30 @@ import type { Header } from '../../types/Header'
 import type { Column_Internal } from '../../types/Column'
 import type { ColumnSizingState } from './columnSizingFeature.types'
 
+/**
+ * Returns the default column sizing state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnSizingState()
+ * ```
+ */
 export function getDefaultColumnSizingState(): ColumnSizingState {
   return {}
 }
 
+/**
+ * Returns the default column sizing column def.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnSizingColumnDef()
+ * ```
+ */
 export function getDefaultColumnSizingColumnDef() {
   return {
     size: 150,
@@ -26,6 +46,16 @@ export function getDefaultColumnSizingColumnDef() {
   }
 }
 
+/**
+ * Returns size 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_getSize(column)
+ * ```
+ */
 export function column_getSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -43,6 +73,16 @@ export function column_getSize<
   )
 }
 
+/**
+ * Returns start 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_getStart(column)
+ * ```
+ */
 export function column_getStart<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -51,6 +91,14 @@ export function column_getStart<
   column: Column_Internal<TFeatures, TData, TValue>,
   position: ColumnPinningPosition | 'center',
 ): number {
+  const index = callMemoOrStaticFn(
+    column,
+    'getIndex',
+    column_getIndex,
+    position,
+  )
+  if (index <= 0) return 0
+
   const visibleLeafColumns = callMemoOrStaticFn(
     column.table,
     'getPinnedVisibleLeafColumns',
@@ -58,11 +106,23 @@ export function column_getStart<
     position,
   )
 
-  return visibleLeafColumns
-    .slice(0, callMemoOrStaticFn(column, 'getIndex', column_getIndex, position))
-    .reduce((sum: number, c) => sum + column_getSize(c), 0)
+  const prevColumn = visibleLeafColumns[index - 1]!
+  return (
+    callMemoOrStaticFn(prevColumn, 'getStart', column_getStart, position) +
+    callMemoOrStaticFn(prevColumn, 'getSize', column_getSize)
+  )
 }
 
+/**
+ * Returns after 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_getAfter(column)
+ * ```
+ */
 export function column_getAfter<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -77,14 +137,31 @@ export function column_getAfter<
     table_getPinnedVisibleLeafColumns,
     position,
   )
+  const index = callMemoOrStaticFn(
+    column,
+    'getIndex',
+    column_getIndex,
+    position,
+  )
+  if (index < 0 || index >= visibleLeafColumns.length - 1) return 0
 
-  return visibleLeafColumns
-    .slice(
-      callMemoOrStaticFn(column, 'getIndex', column_getIndex, position) + 1,
-    )
-    .reduce((sum: number, c) => sum + column_getSize(c), 0)
+  const nextColumn = visibleLeafColumns[index + 1]!
+  return (
+    callMemoOrStaticFn(nextColumn, 'getSize', column_getSize) +
+    callMemoOrStaticFn(nextColumn, 'getAfter', column_getAfter, position)
+  )
 }
 
+/**
+ * Reset Size. for a column.
+ *
+ * This is the static implementation behind the matching column instance API.
+ *
+ * @example
+ * ```ts
+ * const value = column_resetSize(column)
+ * ```
+ */
 export function column_resetSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -95,6 +172,16 @@ export function column_resetSize<
   })
 }
 
+/**
+ * Returns size for a header.
+ *
+ * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ *
+ * @example
+ * ```ts
+ * const value = header_getSize(header)
+ * ```
+ */
 export function header_getSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -115,6 +202,16 @@ export function header_getSize<
   return sum
 }
 
+/**
+ * Returns start for a header.
+ *
+ * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ *
+ * @example
+ * ```ts
+ * const value = header_getStart(header)
+ * ```
+ */
 export function header_getStart<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -124,7 +221,8 @@ export function header_getStart<
     const prevSiblingHeader = header.headerGroup?.headers[header.index - 1]
     if (prevSiblingHeader) {
       return (
-        header_getStart(prevSiblingHeader) + header_getSize(prevSiblingHeader)
+        callMemoOrStaticFn(prevSiblingHeader, 'getStart', header_getStart) +
+        callMemoOrStaticFn(prevSiblingHeader, 'getSize', header_getSize)
       )
     }
   }
@@ -134,6 +232,16 @@ export function header_getStart<
 
 // Table APIs
 
+/**
+ * Updates the table's column sizing state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnSizing(table, (old) => old)
+ * ```
+ */
 export function table_setColumnSizing<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -144,6 +252,17 @@ export function table_setColumnSizing<
   table.options.onColumnSizingChange?.(updater)
 }
 
+/**
+ * Resets the table's column sizing state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnSizing(table)
+ * table_resetColumnSizing(table, true)
+ * ```
+ */
 export function table_resetColumnSizing<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -154,6 +273,16 @@ export function table_resetColumnSizing<
   )
 }
 
+/**
+ * Returns total size 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_getTotalSize(table)
+ * ```
+ */
 export function table_getTotalSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -165,6 +294,16 @@ export function table_getTotalSize<
   )
 }
 
+/**
+ * Returns left total size 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_getLeftTotalSize(table)
+ * ```
+ */
 export function table_getLeftTotalSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -180,6 +319,16 @@ export function table_getLeftTotalSize<
   )
 }
 
+/**
+ * Returns center total size 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_getCenterTotalSize(table)
+ * ```
+ */
 export function table_getCenterTotalSize<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -195,6 +344,16 @@ export function table_getCenterTotalSize<
   )
 }
 
+/**
+ * Returns right total size 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_getRightTotalSize(table)
+ * ```
+ */
 export function table_getRightTotalSize<
   TFeatures extends TableFeatures,
   TData extends RowData,