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

package/src/core/columns/coreColumnsFeature.utils.ts

@@ -12,13 +12,14 @@ import type {
 import type { Column } from '../../types/Column'
 
 /**
- * Returns flat columns for a column.
+ * Flattens this column and every descendant column into a single array.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Group columns appear before their child columns, which matches the normalized
+ * column hierarchy produced during table construction.
  *
  * @example
  * ```ts
- * const value = column_getFlatColumns(column)
+ * const flatColumns = column_getFlatColumns(column)
  * ```
  */
 export function column_getFlatColumns<
@@ -32,13 +33,14 @@ export function column_getFlatColumns<
 }
 
 /**
- * Returns leaf columns for a column.
+ * Collects the terminal leaf columns below this column.
  *
- * This derives the value from the column definition, table options, and the feature state atoms registered on the table.
+ * Group columns return their ordered descendants. Non-group columns return an
+ * array containing only the column itself.
  *
  * @example
  * ```ts
- * const value = column_getLeafColumns(column)
+ * const leafColumns = column_getLeafColumns(column)
  * ```
  */
 export function column_getLeafColumns<
@@ -64,13 +66,15 @@ export function column_getLeafColumns<
 }
 
 /**
- * Returns default column def for the table.
+ * Merges built-in, feature, and user default column definitions.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Built-in defaults provide a header and fallback cell renderer, feature
+ * defaults can add feature-specific column options, and
+ * `options.defaultColumn` wins last.
  *
  * @example
  * ```ts
- * const value = table_getDefaultColumnDef(table)
+ * const defaultColumn = table_getDefaultColumnDef(table)
  * ```
  */
 export function table_getDefaultColumnDef<
@@ -103,13 +107,14 @@ export function table_getDefaultColumnDef<
 }
 
 /**
- * Returns all columns for the table.
+ * Normalizes `options.columns` into the table's nested column tree.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Each column definition is constructed with its parent and depth, and group
+ * column children are recursively constructed.
  *
  * @example
  * ```ts
- * const value = table_getAllColumns(table)
+ * const columns = table_getAllColumns(table)
  * ```
  */
 export function table_getAllColumns<
@@ -144,13 +149,14 @@ export function table_getAllColumns<
 }
 
 /**
- * Returns all flat columns for the table.
+ * Flattens every table column, including group columns and leaf columns.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Use this when parent/group columns must be included in addition to data leaf
+ * columns.
  *
  * @example
  * ```ts
- * const value = table_getAllFlatColumns(table)
+ * const flatColumns = table_getAllFlatColumns(table)
  * ```
  */
 export function table_getAllFlatColumns<
@@ -163,13 +169,14 @@ export function table_getAllFlatColumns<
 }
 
 /**
- * Returns all flat columns by id for the table.
+ * Builds an id lookup for every flat column in the table.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Group columns and leaf columns are included. Later columns with the same id
+ * replace earlier entries.
  *
  * @example
  * ```ts
- * const value = table_getAllFlatColumnsById(table)
+ * const columnsById = table_getAllFlatColumnsById(table)
  * ```
  */
 export function table_getAllFlatColumnsById<
@@ -179,20 +186,23 @@ export function table_getAllFlatColumnsById<
   table: Table_Internal<TFeatures, TData>,
 ): Record<string, Column<TFeatures, TData, unknown>> {
   const result: Record<string, Column<TFeatures, TData, unknown>> = {}
-  for (const column of table.getAllFlatColumns()) {
+  const flatColumns = table.getAllFlatColumns()
+  for (let i = 0; i < flatColumns.length; i++) {
+    const column = flatColumns[i]!
     result[column.id] = column
   }
   return result
 }
 
 /**
- * Returns all leaf columns for the table.
+ * Collects all terminal leaf columns in their current table order.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Column ordering features can reorder the collected leaves before the result
+ * is returned.
  *
  * @example
  * ```ts
- * const value = table_getAllLeafColumns(table)
+ * const leafColumns = table_getAllLeafColumns(table)
  * ```
  */
 export function table_getAllLeafColumns<
@@ -212,13 +222,14 @@ export function table_getAllLeafColumns<
 }
 
 /**
- * Returns all leaf columns by id for the table.
+ * Builds an id lookup for terminal leaf columns only.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Parent/group columns are excluded, making this lookup appropriate for row
+ * cells and feature state keyed by data columns.
  *
  * @example
  * ```ts
- * const value = table_getAllLeafColumnsById(table)
+ * const leavesById = table_getAllLeafColumnsById(table)
  * ```
  */
 export function table_getAllLeafColumnsById<
@@ -228,20 +239,23 @@ export function table_getAllLeafColumnsById<
   table: Table_Internal<TFeatures, TData>,
 ): Record<string, Column<TFeatures, TData, unknown>> {
   const result: Record<string, Column<TFeatures, TData, unknown>> = {}
-  for (const column of table.getAllLeafColumns()) {
+  const leafColumns = table.getAllLeafColumns()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const column = leafColumns[i]!
     result[column.id] = column
   }
   return result
 }
 
 /**
- * Returns column for the table.
+ * Looks up a column by id from the flat column map.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The lookup can return group columns or leaf columns. In development, a
+ * missing id logs a warning to help catch stale column references.
  *
  * @example
  * ```ts
- * const value = table_getColumn(table)
+ * const column = table_getColumn(table, 'firstName')
  * ```
  */
 export function table_getColumn<

package/src/core/headers/buildHeaderGroups.ts

@@ -37,15 +37,14 @@ export function buildHeaderGroups<
   ) => {
     maxDepth = Math.max(maxDepth, depth)
 
-    columns
-      .filter((column) =>
-        callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible),
-      )
-      .forEach((column) => {
+    for (let i = 0; i < columns.length; i++) {
+      const column = columns[i]!
+      if (callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)) {
         if (column.columns.length) {
           findMaxDepth(column.columns, depth + 1)
         }
-      }, 0)
+      }
+    }
   }
 
   findMaxDepth(allColumns)
@@ -136,43 +135,43 @@ export function buildHeaderGroups<
 
   headerGroups.reverse()
 
-  // headerGroups = headerGroups.filter(headerGroup => {
-  //   return !headerGroup.headers.every(header => header.isPlaceholder)
-  // })
-
   const recurseHeadersForSpans = (
     headers: Array<Header<TFeatures, TData, TValue>>,
   ): Array<{ colSpan: number; rowSpan: number }> => {
-    const filteredHeaders = headers.filter((header) =>
-      callMemoOrStaticFn(header.column, 'getIsVisible', column_getIsVisible),
-    )
+    const results: Array<{ colSpan: number; rowSpan: number }> = []
+
+    for (let i = 0; i < headers.length; i++) {
+      const header = headers[i]!
+      if (
+        !callMemoOrStaticFn(header.column, 'getIsVisible', column_getIsVisible)
+      ) {
+        continue
+      }
 
-    return filteredHeaders.map((header) => {
       let colSpan = 0
-      let rowSpan = 0
-      let childRowSpans = [0]
+      let minChildRowSpan = Infinity
 
       if (header.subHeaders.length) {
-        childRowSpans = []
-
-        recurseHeadersForSpans(header.subHeaders).forEach(
-          ({ colSpan: childColSpan, rowSpan: childRowSpan }) => {
-            colSpan += childColSpan
-            childRowSpans.push(childRowSpan)
-          },
-        )
+        const childSpans = recurseHeadersForSpans(header.subHeaders)
+        for (let j = 0; j < childSpans.length; j++) {
+          const child = childSpans[j]!
+          colSpan += child.colSpan
+          if (child.rowSpan < minChildRowSpan) {
+            minChildRowSpan = child.rowSpan
+          }
+        }
       } else {
         colSpan = 1
+        minChildRowSpan = 0
       }
 
-      const minChildRowSpan = Math.min(...childRowSpans)
-      rowSpan = rowSpan + minChildRowSpan
-
       header.colSpan = colSpan
-      header.rowSpan = rowSpan
+      header.rowSpan = minChildRowSpan
 
-      return { colSpan, rowSpan }
-    })
+      results.push({ colSpan, rowSpan: header.rowSpan })
+    }
+
+    return results
   }
 
   recurseHeadersForSpans(

package/src/core/headers/constructHeader.ts

@@ -15,8 +15,9 @@ function getHeaderPrototype<
 >(table: Table_Internal<TFeatures, TData>): object {
   if (!table._headerPrototype) {
     table._headerPrototype = { table }
-    for (const feature of Object.values(table._features)) {
-      feature.assignHeaderPrototype?.(table._headerPrototype, table)
+    const features = Object.values(table._features)
+    for (let i = 0; i < features.length; i++) {
+      features[i]!.assignHeaderPrototype?.(table._headerPrototype, table)
     }
   }
   return table._headerPrototype

package/src/core/headers/coreHeadersFeature.ts

@@ -1,13 +1,4 @@
-import {
-  assignPrototypeAPIs,
-  assignTableAPIs,
-  callMemoOrStaticFn,
-} from '../../utils'
-import {
-  table_getCenterHeaderGroups,
-  table_getLeftHeaderGroups,
-  table_getRightHeaderGroups,
-} from '../../features/column-pinning/columnPinningFeature.utils'
+import { assignPrototypeAPIs, assignTableAPIs } from '../../utils'
 import {
   header_getContext,
   header_getLeafHeaders,
@@ -74,23 +65,7 @@ export function constructCoreHeadersFeature<
         },
         table_getLeafHeaders: {
           fn: () => table_getLeafHeaders(table),
-          memoDeps: () => [
-            callMemoOrStaticFn(
-              table,
-              'getLeftHeaderGroups',
-              table_getLeftHeaderGroups,
-            ),
-            callMemoOrStaticFn(
-              table,
-              'getCenterHeaderGroups',
-              table_getCenterHeaderGroups,
-            ),
-            callMemoOrStaticFn(
-              table,
-              'getRightHeaderGroups',
-              table_getRightHeaderGroups,
-            ),
-          ],
+          memoDeps: () => [table.getHeaderGroups()],
         },
       })
     },

package/src/core/headers/coreHeadersFeature.types.ts

@@ -10,19 +10,21 @@ export interface Table_Headers<
   TData extends RowData,
 > {
   /**
-   * Returns all header groups for the table.
+   * Builds the visible header groups for the current column tree, visibility,
+   * and pinning state.
    */
   getHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns the footer groups for the table.
+   * Builds footer groups by reversing the current header group order.
    */
   getFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
   /**
-   * Returns headers for all columns in the table, including parent headers.
+   * Flattens every header from every header group, including parent and
+   * placeholder headers.
    */
   getFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
   /**
-   * Returns headers for all leaf columns in the table, (not including parent headers).
+   * Collects only leaf headers, excluding parent/group headers.
    */
   getLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
 }

package/src/core/headers/coreHeadersFeature.utils.ts

@@ -1,9 +1,4 @@
-import {
-  getDefaultColumnPinningState,
-  table_getCenterHeaderGroups,
-  table_getLeftHeaderGroups,
-  table_getRightHeaderGroups,
-} from '../../features/column-pinning/columnPinningFeature.utils'
+import { getDefaultColumnPinningState } from '../../features/column-pinning/columnPinningFeature.utils'
 import {
   column_getIsVisible,
   table_getVisibleLeafColumns,
@@ -18,13 +13,14 @@ import type { Header_Header } from './coreHeadersFeature.types'
 import type { Column } from '../../types/Column'
 
 /**
- * Returns leaf headers for a header.
+ * Walks a header tree and collects all descendant leaf headers.
  *
- * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ * The header itself is included after its descendants, matching the recursive
+ * shape used by nested header groups.
  *
  * @example
  * ```ts
- * const value = header_getLeafHeaders(header)
+ * const leafHeaders = header_getLeafHeaders(header)
  * ```
  */
 export function header_getLeafHeaders<
@@ -47,13 +43,13 @@ export function header_getLeafHeaders<
 }
 
 /**
- * Returns context for a header.
+ * Builds the render context passed to a column's `header` or `footer` template.
  *
- * This is the static implementation behind the matching header instance API and can account for nested header groups.
+ * The context contains the header, its column, and the owning table instance.
  *
  * @example
  * ```ts
- * const value = header_getContext(header)
+ * const context = header_getContext(header)
  * ```
  */
 export function header_getContext<
@@ -69,13 +65,14 @@ export function header_getContext<
 }
 
 /**
- * Returns header groups for the table.
+ * Builds visible header groups for the current column tree.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Column visibility and pinning are applied before groups are built. When no
+ * columns are pinned, the fast path skips pin partitioning.
  *
  * @example
  * ```ts
- * const value = table_getHeaderGroups(table)
+ * const headerGroups = table_getHeaderGroups(table)
  * ```
  */
 export function table_getHeaderGroups<
@@ -90,11 +87,17 @@ export function table_getHeaderGroups<
     'getVisibleLeafColumns',
     table_getVisibleLeafColumns,
   ) as Array<Column<TFeatures, TData, unknown>>
+
+  // Fast path: no columns are pinned — skip per-side lookups, partition, and spread.
+  if (!left.length && !right.length) {
+    return buildHeaderGroups(allColumns, leafColumns, table)
+  }
+
   const leafColumnsById = table.getAllLeafColumnsById()
 
   const leftColumns: typeof leafColumns = []
-  for (const columnId of left) {
-    const column = leafColumnsById[columnId]
+  for (let i = 0; i < left.length; i++) {
+    const column = leafColumnsById[left[i]!]
     if (
       column &&
       callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)
@@ -104,8 +107,8 @@ export function table_getHeaderGroups<
   }
 
   const rightColumns: typeof leafColumns = []
-  for (const columnId of right) {
-    const column = leafColumnsById[columnId]
+  for (let i = 0; i < right.length; i++) {
+    const column = leafColumnsById[right[i]!]
     if (
       column &&
       callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)
@@ -118,23 +121,22 @@ export function table_getHeaderGroups<
     (column) => !left.includes(column.id) && !right.includes(column.id),
   )
 
-  const headerGroups = buildHeaderGroups(
+  return buildHeaderGroups(
     allColumns,
     [...leftColumns, ...centerColumns, ...rightColumns],
     table,
   )
-
-  return headerGroups
 }
 
 /**
- * Returns footer groups for the table.
+ * Builds footer groups by reversing the current header groups.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Footer rendering uses the same header objects and grouping structure, but
+ * renders them from leaf level back toward the root.
  *
  * @example
  * ```ts
- * const value = table_getFooterGroups(table)
+ * const footerGroups = table_getFooterGroups(table)
  * ```
  */
 export function table_getFooterGroups<
@@ -146,13 +148,14 @@ export function table_getFooterGroups<
 }
 
 /**
- * Returns flat headers for the table.
+ * Flattens every header from every header group into one array.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The result includes parent headers and placeholder headers, in header-group
+ * order from top to bottom.
  *
  * @example
  * ```ts
- * const value = table_getFlatHeaders(table)
+ * const flatHeaders = table_getFlatHeaders(table)
  * ```
  */
 export function table_getFlatHeaders<
@@ -160,50 +163,38 @@ export function table_getFlatHeaders<
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
   const headerGroups = table.getHeaderGroups()
-  return headerGroups
-    .map((headerGroup) => {
-      return headerGroup.headers
-    })
-    .flat()
+  const result: Array<Header<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < headerGroups.length; i++) {
+    const headers = headerGroups[i]!.headers
+    for (let j = 0; j < headers.length; j++) {
+      result.push(headers[j]!)
+    }
+  }
+  return result
 }
 
 /**
- * Returns leaf headers for the table.
+ * Collects only the leaf headers from the current header tree.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Parent/group headers are skipped, making the result suitable for rendering
+ * one header per visible leaf column.
  *
  * @example
  * ```ts
- * const value = table_getLeafHeaders(table)
+ * const leafHeaders = table_getLeafHeaders(table)
  * ```
  */
 export function table_getLeafHeaders<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(table: Table_Internal<TFeatures, TData>) {
-  const left = callMemoOrStaticFn(
-    table,
-    'getLeftHeaderGroups',
-    table_getLeftHeaderGroups,
-  )
-  const center = callMemoOrStaticFn(
-    table,
-    'getCenterHeaderGroups',
-    table_getCenterHeaderGroups,
-  )
-  const right = callMemoOrStaticFn(
-    table,
-    'getRightHeaderGroups',
-    table_getRightHeaderGroups,
-  )
-
-  return [
-    ...(left[0]?.headers ?? []),
-    ...(center[0]?.headers ?? []),
-    ...(right[0]?.headers ?? []),
-  ]
-    .map((header) => {
-      return header.getLeafHeaders()
-    })
-    .flat()
+  const topHeaders = table.getHeaderGroups()[0]?.headers ?? []
+  const result: Array<Header<TFeatures, TData, unknown>> = []
+  for (let i = 0; i < topHeaders.length; i++) {
+    const leafHeaders = topHeaders[i]!.getLeafHeaders()
+    for (let j = 0; j < leafHeaders.length; j++) {
+      result.push(leafHeaders[j]!)
+    }
+  }
+  return result
 }

package/src/core/reactivity/coreReactivityFeature.types.ts

@@ -38,4 +38,8 @@ export interface TableReactivityBindings {
    * Batches reactive updates to avoid intermediate recomputation.
    */
   batch: (fn: () => void) => void
+  /**
+   * Schedules a function to run. This is used to defer updates after the current call stack (render, etc.) has finished
+   */
+  schedule: (fn: () => void) => void
 }