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

package/src/features/column-pinning/columnPinningFeature.utils.ts

@@ -1,10 +1,12 @@
 import {
   column_getIsVisible,
-  row_getAllVisibleCells,
+  row_getVisibleCells,
+  row_getVisibleCellsByColumnId,
   table_getVisibleLeafColumns,
 } from '../column-visibility/columnVisibilityFeature.utils'
 import { buildHeaderGroups } from '../../core/headers/buildHeaderGroups'
 import { callMemoOrStaticFn, cloneState } from '../../utils'
+import type { Header } from '../../types/Header'
 import type { HeaderGroup } from '../../types/HeaderGroup'
 import type { Cell } from '../../types/Cell'
 import type { Row } from '../../types/Row'
@@ -19,6 +21,16 @@ import type {
 
 // State
 
+/**
+ * Returns the default column pinning state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultColumnPinningState()
+ * ```
+ */
 export function getDefaultColumnPinningState(): ColumnPinningState {
   return {
     left: [],
@@ -28,6 +40,16 @@ export function getDefaultColumnPinningState(): ColumnPinningState {
 
 // Column APIs
 
+/**
+ * Pin. for a column.
+ *
+ * This is the static implementation behind the matching column instance API.
+ *
+ * @example
+ * ```ts
+ * column_pin(column, 'left')
+ * ```
+ */
 export function column_pin<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -36,10 +58,13 @@ export function column_pin<
   column: Column_Internal<TFeatures, TData, TValue>,
   position: ColumnPinningPosition,
 ) {
-  const columnIds = column
-    .getLeafColumns()
-    .map((d) => d.id)
-    .filter(Boolean)
+  // Single pass: collect non-empty leaf-column ids.
+  const leafColumns = column.getLeafColumns()
+  const columnIds: Array<string> = []
+  for (let i = 0; i < leafColumns.length; i++) {
+    const id = leafColumns[i]!.id
+    if (id) columnIds.push(id)
+  }
 
   table_setColumnPinning(column.table, (old) => {
     if (position === 'right') {
@@ -66,6 +91,16 @@ export function column_pin<
   })
 }
 
+/**
+ * Returns whether a column can use pin.
+ *
+ * This combines column options, table options, and any required accessor or feature state for the capability.
+ *
+ * @example
+ * ```ts
+ * const value = column_getCanPin(column)
+ * ```
+ */
 export function column_getCanPin<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -82,6 +117,16 @@ export function column_getCanPin<
   )
 }
 
+/**
+ * Returns is pinned 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_getIsPinned(column)
+ * ```
+ */
 export function column_getIsPinned<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -100,6 +145,16 @@ export function column_getIsPinned<
   return isLeft ? 'left' : isRight ? 'right' : false
 }
 
+/**
+ * Returns pinned index 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_getPinnedIndex(column)
+ * ```
+ */
 export function column_getPinnedIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -115,14 +170,24 @@ export function column_getPinnedIndex<
 
 // Row APIs
 
+/**
+ * Returns center 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_getCenterVisibleCells(row)
+ * ```
+ */
 export function row_getCenterVisibleCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>) {
   const allCells = callMemoOrStaticFn(
     row,
-    'getAllVisibleCells',
-    row_getAllVisibleCells,
+    'getVisibleCells',
+    row_getVisibleCells,
   )
   const { left, right } =
     row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
@@ -130,50 +195,88 @@ export function row_getCenterVisibleCells<
   return allCells.filter((d) => !leftAndRight.includes(d.column.id))
 }
 
+/**
+ * Returns left 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_getLeftVisibleCells(row)
+ * ```
+ */
 export function row_getLeftVisibleCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>): Array<Cell<TFeatures, TData, unknown>> {
-  const allCells = callMemoOrStaticFn(
-    row,
-    'getAllVisibleCells',
-    row_getAllVisibleCells,
-  )
   const { left } =
     row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
-  const cells = left
-    .map((columnId) => allCells.find((cell) => cell.column.id === columnId)!)
-    .filter(Boolean)
-  // Assign position property directly to preserve prototype chain
-  cells.forEach((cell) => {
-    cell.position = 'left'
-  })
-  return cells as any
+  if (!left.length) return []
+  const allVisibleCells = callMemoOrStaticFn(
+    row,
+    'getVisibleCellsByColumnId',
+    row_getVisibleCellsByColumnId,
+  )
+  const cells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < left.length; i++) {
+    const columnId = left[i]!
+    const cell = allVisibleCells[columnId]
+    if (cell) {
+      // Assign position property directly to preserve prototype chain
+      cell.position = 'left'
+      cells.push(cell)
+    }
+  }
+  return cells
 }
 
+/**
+ * Returns right 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_getRightVisibleCells(row)
+ * ```
+ */
 export function row_getRightVisibleCells<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(row: Row<TFeatures, TData>) {
-  const allCells = callMemoOrStaticFn(
-    row,
-    'getAllVisibleCells',
-    row_getAllVisibleCells,
-  )
   const { right } =
     row.table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
-  const cells = right
-    .map((columnId) => allCells.find((cell) => cell.column.id === columnId)!)
-    .filter(Boolean)
-  // Assign position property directly to preserve prototype chain
-  cells.forEach((cell) => {
-    cell.position = 'right'
-  })
-  return cells as any
+  if (!right.length) return [] as Array<Cell<TFeatures, TData, unknown>>
+  const allVisibleCells = callMemoOrStaticFn(
+    row,
+    'getVisibleCellsByColumnId',
+    row_getVisibleCellsByColumnId,
+  )
+  const cells: Array<Cell<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < right.length; i++) {
+    const columnId = right[i]!
+    const cell = allVisibleCells[columnId]
+    if (cell) {
+      // Assign position property directly to preserve prototype chain
+      cell.position = 'right'
+      cells.push(cell)
+    }
+  }
+  return cells
 }
 
 // Table APIs
 
+/**
+ * Updates the table's column pinning state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setColumnPinning(table, (old) => old)
+ * ```
+ */
 export function table_setColumnPinning<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -184,6 +287,17 @@ export function table_setColumnPinning<
   table.options.onColumnPinningChange?.(updater)
 }
 
+/**
+ * Resets the table's column pinning state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetColumnPinning(table)
+ * table_resetColumnPinning(table, true)
+ * ```
+ */
 export function table_resetColumnPinning<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -198,6 +312,16 @@ export function table_resetColumnPinning<
   )
 }
 
+/**
+ * Returns is some columns pinned 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_getIsSomeColumnsPinned(table)
+ * ```
+ */
 export function table_getIsSomeColumnsPinned<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -212,46 +336,90 @@ export function table_getIsSomeColumnsPinned<
 
 // header groups
 
+/**
+ * Returns left header groups 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_getLeftHeaderGroups(table)
+ * ```
+ */
 export function table_getLeftHeaderGroups<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   const allColumns = table.getAllColumns()
-  const leafColumns = callMemoOrStaticFn(
-    table,
-    'getVisibleLeafColumns',
-    table_getVisibleLeafColumns,
-  ) as Array<Column_Internal<TFeatures, TData, unknown>>
+  const leafColumnsById = table.getAllLeafColumnsById() as Record<
+    string,
+    Column_Internal<TFeatures, TData, unknown>
+  >
   const { left } =
     table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
 
-  const orderedLeafColumns = left
-    .map((columnId) => leafColumns.find((d) => d.id === columnId)!)
-    .filter(Boolean)
+  const orderedLeafColumns: Array<Column_Internal<TFeatures, TData, unknown>> =
+    []
+  for (let i = 0; i < left.length; i++) {
+    const column = leafColumnsById[left[i]!]
+    if (
+      column &&
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)
+    ) {
+      orderedLeafColumns.push(column)
+    }
+  }
 
   return buildHeaderGroups(allColumns, orderedLeafColumns, table, 'left')
 }
 
+/**
+ * Returns right header groups 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_getRightHeaderGroups(table)
+ * ```
+ */
 export function table_getRightHeaderGroups<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   const allColumns = table.getAllColumns()
-  const leafColumns = callMemoOrStaticFn(
-    table,
-    'getVisibleLeafColumns',
-    table_getVisibleLeafColumns,
-  ) as unknown as Array<Column_Internal<TFeatures, TData, unknown>>
+  const leafColumnsById = table.getAllLeafColumnsById() as Record<
+    string,
+    Column_Internal<TFeatures, TData, unknown>
+  >
   const { right } =
     table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
 
-  const orderedLeafColumns = right
-    .map((columnId) => leafColumns.find((d) => d.id === columnId)!)
-    .filter(Boolean)
+  const orderedLeafColumns: Array<Column_Internal<TFeatures, TData, unknown>> =
+    []
+  for (let i = 0; i < right.length; i++) {
+    const column = leafColumnsById[right[i]!]
+    if (
+      column &&
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)
+    ) {
+      orderedLeafColumns.push(column)
+    }
+  }
 
   return buildHeaderGroups(allColumns, orderedLeafColumns, table, 'right')
 }
 
+/**
+ * Returns center header groups 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_getCenterHeaderGroups(table)
+ * ```
+ */
 export function table_getCenterHeaderGroups<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -276,6 +444,16 @@ export function table_getCenterHeaderGroups<
 
 // footer groups
 
+/**
+ * Returns left footer groups 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_getLeftFooterGroups(table)
+ * ```
+ */
 export function table_getLeftFooterGroups<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -288,6 +466,16 @@ export function table_getLeftFooterGroups<
   return [...headerGroups].reverse()
 }
 
+/**
+ * Returns right footer groups 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_getRightFooterGroups(table)
+ * ```
+ */
 export function table_getRightFooterGroups<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -300,6 +488,16 @@ export function table_getRightFooterGroups<
   return [...headerGroups].reverse()
 }
 
+/**
+ * Returns center footer groups 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_getCenterFooterGroups(table)
+ * ```
+ */
 export function table_getCenterFooterGroups<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -314,6 +512,16 @@ export function table_getCenterFooterGroups<
 
 // flat headers
 
+/**
+ * Returns left flat headers 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_getLeftFlatHeaders(table)
+ * ```
+ */
 export function table_getLeftFlatHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -323,13 +531,26 @@ export function table_getLeftFlatHeaders<
     'getLeftHeaderGroups',
     table_getLeftHeaderGroups,
   )
-  return leftHeaderGroups
-    .map((headerGroup) => {
-      return headerGroup.headers
-    })
-    .flat()
+  const result: Array<Header<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < leftHeaderGroups.length; i++) {
+    const headers = leftHeaderGroups[i]!.headers
+    for (let j = 0; j < headers.length; j++) {
+      result.push(headers[j])
+    }
+  }
+  return result
 }
 
+/**
+ * Returns right flat headers 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_getRightFlatHeaders(table)
+ * ```
+ */
 export function table_getRightFlatHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -339,13 +560,26 @@ export function table_getRightFlatHeaders<
     'getRightHeaderGroups',
     table_getRightHeaderGroups,
   )
-  return rightHeaderGroups
-    .map((headerGroup) => {
-      return headerGroup.headers
-    })
-    .flat()
+  const result: Array<Header<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < rightHeaderGroups.length; i++) {
+    const headers = rightHeaderGroups[i]!.headers
+    for (let j = 0; j < headers.length; j++) {
+      result.push(headers[j])
+    }
+  }
+  return result
 }
 
+/**
+ * Returns center flat headers 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_getCenterFlatHeaders(table)
+ * ```
+ */
 export function table_getCenterFlatHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -355,15 +589,28 @@ export function table_getCenterFlatHeaders<
     'getCenterHeaderGroups',
     table_getCenterHeaderGroups,
   )
-  return centerHeaderGroups
-    .map((headerGroup) => {
-      return headerGroup.headers
-    })
-    .flat()
+  const result: Array<Header<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < centerHeaderGroups.length; i++) {
+    const headers = centerHeaderGroups[i]!.headers
+    for (let j = 0; j < headers.length; j++) {
+      result.push(headers[j])
+    }
+  }
+  return result
 }
 
 // leaf headers
 
+/**
+ * Returns left leaf headers 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_getLeftLeafHeaders(table)
+ * ```
+ */
 export function table_getLeftLeafHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -375,6 +622,16 @@ export function table_getLeftLeafHeaders<
   ).filter((header) => !header.subHeaders.length)
 }
 
+/**
+ * Returns right leaf headers 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_getRightLeafHeaders(table)
+ * ```
+ */
 export function table_getRightLeafHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -386,6 +643,16 @@ export function table_getRightLeafHeaders<
   ).filter((header) => !header.subHeaders.length)
 }
 
+/**
+ * Returns center leaf headers 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_getCenterLeafHeaders(table)
+ * ```
+ */
 export function table_getCenterLeafHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -399,34 +666,66 @@ export function table_getCenterLeafHeaders<
 
 // leaf columns
 
+/**
+ * Returns left 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_getLeftLeafColumns(table)
+ * ```
+ */
 export function table_getLeftLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   const { left } =
     table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
-  return left
-    .map(
-      (columnId) =>
-        table.getAllLeafColumns().find((column) => column.id === columnId)!,
-    )
-    .filter(Boolean)
+  const leafColumnsById = table.getAllLeafColumnsById()
+  const result: Array<Column_Internal<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < left.length; i++) {
+    const column = leafColumnsById[left[i]!]
+    if (column) result.push(column)
+  }
+  return result
 }
 
+/**
+ * Returns right 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_getRightLeafColumns(table)
+ * ```
+ */
 export function table_getRightLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   const { right } =
     table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
-  return right
-    .map(
-      (columnId) =>
-        table.getAllLeafColumns().find((column) => column.id === columnId)!,
-    )
-    .filter(Boolean)
+  const leafColumnsById = table.getAllLeafColumnsById()
+  const result: Array<Column_Internal<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < right.length; i++) {
+    const column = leafColumnsById[right[i]!]
+    if (column) result.push(column)
+  }
+  return result
 }
 
+/**
+ * Returns center 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_getCenterLeafColumns(table)
+ * ```
+ */
 export function table_getCenterLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -437,6 +736,16 @@ export function table_getCenterLeafColumns<
   return table.getAllLeafColumns().filter((d) => !leftAndRight.includes(d.id))
 }
 
+/**
+ * Returns pinned 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_getPinnedLeafColumns(table)
+ * ```
+ */
 export function table_getPinnedLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -467,6 +776,16 @@ export function table_getPinnedLeafColumns<
 
 // visible leaf columns
 
+/**
+ * Returns left 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_getLeftVisibleLeafColumns(table)
+ * ```
+ */
 export function table_getLeftVisibleLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -480,6 +799,16 @@ export function table_getLeftVisibleLeafColumns<
   )
 }
 
+/**
+ * Returns right 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_getRightVisibleLeafColumns(table)
+ * ```
+ */
 export function table_getRightVisibleLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -493,6 +822,16 @@ export function table_getRightVisibleLeafColumns<
   )
 }
 
+/**
+ * Returns center 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_getCenterVisibleLeafColumns(table)
+ * ```
+ */
 export function table_getCenterVisibleLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -506,6 +845,16 @@ export function table_getCenterVisibleLeafColumns<
   )
 }
 
+/**
+ * Returns pinned 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_getPinnedVisibleLeafColumns(table)
+ * ```
+ */
 export function table_getPinnedVisibleLeafColumns<
   TFeatures extends TableFeatures,
   TData extends RowData,