@tanstack/table-core 9.0.0-alpha.8 → 9.0.0-beta.10

package/src/core/headers/buildHeaderGroups.ts

@@ -0,0 +1,182 @@
+import { callMemoOrStaticFn } from '../../utils'
+import { column_getIsVisible } from '../../features/column-visibility/columnVisibilityFeature.utils'
+import { constructHeader } from './constructHeader'
+import type { Table_Internal } from '../../types/Table'
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Header } from '../../types/Header'
+import type { HeaderGroup } from '../../types/HeaderGroup'
+import type { Column } from '../../types/Column'
+
+/**
+ * Builds the nested header group structure for a table.
+ *
+ * The result accounts for visible leaf columns, pinned column groups, and placeholder headers needed to render multi-level headers.
+ */
+export function buildHeaderGroups<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  allColumns: Array<Column<TFeatures, TData, TValue>>,
+  columnsToGroup: Array<Column<TFeatures, TData, TValue>>,
+  table: Table_Internal<TFeatures, TData>,
+  headerFamily?: 'center' | 'left' | 'right',
+) {
+  // Find the max depth of the columns:
+  // build the leaf column row
+  // build each buffer row going up
+  //    placeholder for non-existent level
+  //    real column for existing level
+
+  let maxDepth = 0
+
+  const findMaxDepth = (
+    columns: Array<Column<TFeatures, TData, TValue>>,
+    depth = 1,
+  ) => {
+    maxDepth = Math.max(maxDepth, depth)
+
+    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)
+        }
+      }
+    }
+  }
+
+  findMaxDepth(allColumns)
+
+  const headerGroups: Array<HeaderGroup<TFeatures, TData>> = []
+
+  const constructHeaderGroup = (
+    headersToGroup: Array<Header<TFeatures, TData, TValue>>,
+    depth: number,
+  ) => {
+    // The header group we are creating
+    const headerGroup: HeaderGroup<TFeatures, TData> = {
+      depth,
+      id: [headerFamily, `${depth}`].filter(Boolean).join('_'),
+      headers: [],
+    }
+
+    // The parent columns we're going to scan next
+    const pendingParentHeaders: Array<Header<TFeatures, TData, TValue>> = []
+
+    // Scan each column for parents
+    headersToGroup.forEach((headerToGroup) => {
+      // What is the latest (last) parent column?
+
+      const latestPendingParentHeader =
+        pendingParentHeaders[pendingParentHeaders.length - 1]
+
+      const isLeafHeader = headerToGroup.column.depth === headerGroup.depth
+
+      let column: Column<TFeatures, TData, TValue>
+      let isPlaceholder = false
+
+      if (isLeafHeader && headerToGroup.column.parent) {
+        // The parent header is new
+        column = headerToGroup.column.parent
+      } else {
+        // The parent header is repeated
+        column = headerToGroup.column
+        isPlaceholder = true
+      }
+
+      if (
+        latestPendingParentHeader &&
+        latestPendingParentHeader.column === column
+      ) {
+        // This column is repeated. Add it as a sub header to the next batch
+        latestPendingParentHeader.subHeaders.push(headerToGroup)
+      } else {
+        // This is a new header. Let's create it
+        const header = constructHeader(table, column, {
+          id: [headerFamily, depth, column.id, headerToGroup.id]
+            .filter(Boolean)
+            .join('_'),
+          isPlaceholder,
+          placeholderId: isPlaceholder
+            ? `${pendingParentHeaders.filter((d) => d.column === column).length}`
+            : undefined,
+          depth,
+          index: pendingParentHeaders.length,
+        })
+
+        // Add the headerToGroup as a subHeader of the new header
+        header.subHeaders.push(headerToGroup)
+        // Add the new header to the pendingParentHeaders to get grouped
+        // in the next batch
+        pendingParentHeaders.push(header)
+      }
+
+      headerGroup.headers.push(headerToGroup)
+      headerToGroup.headerGroup = headerGroup
+    })
+
+    headerGroups.push(headerGroup)
+
+    if (depth > 0) {
+      constructHeaderGroup(pendingParentHeaders, depth - 1)
+    }
+  }
+
+  const bottomHeaders = columnsToGroup.map((column, index) =>
+    constructHeader(table, column, {
+      depth: maxDepth,
+      index,
+    }),
+  )
+
+  constructHeaderGroup(bottomHeaders, maxDepth - 1)
+
+  headerGroups.reverse()
+
+  const recurseHeadersForSpans = (
+    headers: Array<Header<TFeatures, TData, TValue>>,
+  ): Array<{ colSpan: number; rowSpan: number }> => {
+    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
+      }
+
+      let colSpan = 0
+      let minChildRowSpan = Infinity
+
+      if (header.subHeaders.length) {
+        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
+      }
+
+      header.colSpan = colSpan
+      header.rowSpan = minChildRowSpan
+
+      results.push({ colSpan, rowSpan: header.rowSpan })
+    }
+
+    return results
+  }
+
+  recurseHeadersForSpans(
+    (headerGroups[0]?.headers ?? []) as Array<Header<TFeatures, TData, TValue>>,
+  )
+
+  return headerGroups
+}

package/src/core/headers/constructHeader.ts

@@ -0,0 +1,67 @@
+import type { Table_Internal } from '../../types/Table'
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Header } from '../../types/Header'
+import type { Column } from '../../types/Column'
+import type { Header_CoreProperties } from './coreHeadersFeature.types'
+
+/**
+ * Creates or retrieves the header prototype for a table.
+ * The prototype is cached on the table and shared by all header instances.
+ */
+function getHeaderPrototype<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): object {
+  if (!table._headerPrototype) {
+    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
+}
+
+/**
+ * Constructs a header instance from normalized table internals.
+ *
+ * This wires core properties, feature prototype APIs, and instance data used by table rendering and row-model operations.
+ */
+export function constructHeader<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  column: Column<TFeatures, TData, TValue>,
+  options: {
+    id?: string
+    isPlaceholder?: boolean
+    placeholderId?: string
+    index: number
+    depth: number
+  },
+): Header<TFeatures, TData, TValue> {
+  // Create header with shared prototype for memory efficiency
+  const headerPrototype = getHeaderPrototype(table)
+  const header = Object.create(headerPrototype) as Header_CoreProperties<
+    TFeatures,
+    TData,
+    TValue
+  >
+
+  // Only assign instance-specific properties
+  header.colSpan = 0
+  header.column = column
+  header.depth = options.depth
+  header.headerGroup = null
+  header.id = options.id ?? column.id
+  header.index = options.index
+  header.isPlaceholder = !!options.isPlaceholder
+  header.placeholderId = options.placeholderId
+  header.rowSpan = 0
+  header.subHeaders = []
+
+  return header as Header<TFeatures, TData, TValue>
+}

package/src/core/headers/coreHeadersFeature.ts

@@ -0,0 +1,56 @@
+import { assignPrototypeAPIs, assignTableAPIs } from '../../utils'
+import {
+  header_getContext,
+  header_getLeafHeaders,
+  table_getFlatHeaders,
+  table_getFooterGroups,
+  table_getHeaderGroups,
+  table_getLeafHeaders,
+} from './coreHeadersFeature.utils'
+import type { TableFeature } from '../../types/TableFeatures'
+
+/**
+ * Core feature that builds header groups and exposes header context APIs.
+ */
+export const coreHeadersFeature: TableFeature = {
+  assignHeaderPrototype: (prototype, table) => {
+    assignPrototypeAPIs('coreHeadersFeature', prototype, table, {
+      header_getLeafHeaders: {
+        fn: (header) => header_getLeafHeaders(header),
+        memoDeps: (header) => [header.column.table.options.columns],
+      },
+      header_getContext: {
+        fn: (header) => header_getContext(header),
+        memoDeps: (header) => [header.column.table.options.columns],
+      },
+    })
+  },
+
+  constructTableAPIs: (table) => {
+    assignTableAPIs('coreHeadersFeature', table, {
+      table_getHeaderGroups: {
+        fn: () => table_getHeaderGroups(table),
+        memoDeps: () => [
+          table.options.columns,
+          table.atoms.columnOrder?.get(),
+          table.atoms.grouping?.get(),
+          table.atoms.columnPinning?.get(),
+          table.atoms.columnVisibility?.get(),
+          table.options.groupedColumnMode,
+        ],
+      },
+      table_getFooterGroups: {
+        fn: () => table_getFooterGroups(table),
+        memoDeps: () => [table.getHeaderGroups()],
+      },
+      table_getFlatHeaders: {
+        fn: () => table_getFlatHeaders(table),
+        memoDeps: () => [table.getHeaderGroups()],
+      },
+      table_getLeafHeaders: {
+        fn: () => table_getLeafHeaders(table),
+        memoDeps: () => [table.getHeaderGroups()],
+      },
+    })
+  },
+}

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

@@ -0,0 +1,125 @@
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table } from '../../types/Table'
+import type { Header } from '../../types/Header'
+import type { HeaderGroup } from '../../types/HeaderGroup'
+import type { Column } from '../../types/Column'
+
+export interface Table_Headers<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Builds the visible header groups for the current column tree, visibility,
+   * and pinning state.
+   */
+  getHeaderGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Builds footer groups by reversing the current header group order.
+   */
+  getFooterGroups: () => Array<HeaderGroup<TFeatures, TData>>
+  /**
+   * Flattens every header from every header group, including parent and
+   * placeholder headers.
+   */
+  getFlatHeaders: () => Array<Header<TFeatures, TData, unknown>>
+  /**
+   * Collects only leaf headers, excluding parent/group headers.
+   */
+  getLeafHeaders: () => Array<Header<TFeatures, TData, unknown>>
+}
+
+export interface HeaderContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /**
+   * An instance of a column.
+   */
+  column: Column<TFeatures, TData, TValue>
+  /**
+   * An instance of a header.
+   */
+  header: Header<TFeatures, TData, TValue>
+  /**
+   * The table instance.
+   */
+  table: Table<TFeatures, TData>
+}
+
+export interface Header_CoreProperties<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /**
+   * The col-span for the header.
+   */
+  colSpan: number
+  /**
+   * The header's associated column object.
+   */
+  column: Column<TFeatures, TData, TValue>
+  /**
+   * The depth of the header, zero-indexed based.
+   */
+  depth: number
+  /**
+   * The header's associated header group object.
+   */
+  headerGroup: HeaderGroup<TFeatures, TData> | null
+  /**
+   * The unique identifier for the header.
+   */
+  id: string
+  /**
+   * The index for the header within the header group.
+   */
+  index: number
+  /**
+   * A boolean denoting if the header is a placeholder header.
+   */
+  isPlaceholder: boolean
+  /**
+   * If the header is a placeholder header, this will be a unique header ID that does not conflict with any other headers across the table.
+   */
+  placeholderId?: string
+  /**
+   * The row-span for the header.
+   */
+  rowSpan: number
+  /**
+   * The header's hierarchical sub/child headers. Will be empty if the header's associated column is a leaf-column.
+   */
+  subHeaders: Array<Header<TFeatures, TData, TValue>>
+  /**
+   * Reference to the parent table instance.
+   */
+  table: Table<TFeatures, TData>
+}
+
+export interface Header_Header<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> extends Header_CoreProperties<TFeatures, TData, TValue> {
+  /**
+   * Returns the rendering context (or props) for column-based components like headers, footers and filters.
+   */
+  getContext: () => HeaderContext<TFeatures, TData, TValue>
+  /**
+   * Returns the leaf headers hierarchically nested under this header.
+   */
+  getLeafHeaders: () => Array<Header<TFeatures, TData, TValue>>
+}
+
+export interface HeaderGroup_Header<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  depth: number
+  headers: Array<Header<TFeatures, TData, TValue>>
+  id: string
+}

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

@@ -0,0 +1,200 @@
+import { getDefaultColumnPinningState } from '../../features/column-pinning/columnPinningFeature.utils'
+import {
+  column_getIsVisible,
+  table_getVisibleLeafColumns,
+} from '../../features/column-visibility/columnVisibilityFeature.utils'
+import { callMemoOrStaticFn } from '../../utils'
+import { buildHeaderGroups } from './buildHeaderGroups'
+import type { Table_Internal } from '../../types/Table'
+import type { Header } from '../../types/Header'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Header_Header } from './coreHeadersFeature.types'
+import type { Column } from '../../types/Column'
+
+/**
+ * Walks a header tree and collects all descendant leaf headers.
+ *
+ * The header itself is included after its descendants, matching the recursive
+ * shape used by nested header groups.
+ *
+ * @example
+ * ```ts
+ * const leafHeaders = header_getLeafHeaders(header)
+ * ```
+ */
+export function header_getLeafHeaders<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue,
+>(header: Header<TFeatures, TData, TValue>) {
+  const leafHeaders: Array<Header<TFeatures, TData, TValue>> = []
+
+  const recurseHeader = (h: Header_Header<TFeatures, TData, TValue>) => {
+    if (h.subHeaders.length) {
+      h.subHeaders.map(recurseHeader)
+    }
+    leafHeaders.push(h as Header<TFeatures, TData, TValue>)
+  }
+
+  recurseHeader(header)
+
+  return leafHeaders
+}
+
+/**
+ * Builds the render context passed to a column's `header` or `footer` template.
+ *
+ * The context contains the header, its column, and the owning table instance.
+ *
+ * @example
+ * ```ts
+ * const context = header_getContext(header)
+ * ```
+ */
+export function header_getContext<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue,
+>(header: Header<TFeatures, TData, TValue>) {
+  return {
+    column: header.column,
+    header,
+    table: header.column.table,
+  }
+}
+
+/**
+ * Builds visible header groups for the current column tree.
+ *
+ * Column visibility and pinning are applied before groups are built. When no
+ * columns are pinned, the fast path skips pin partitioning.
+ *
+ * @example
+ * ```ts
+ * const headerGroups = table_getHeaderGroups(table)
+ * ```
+ */
+export function table_getHeaderGroups<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const { left, right } =
+    table.atoms.columnPinning?.get() ?? getDefaultColumnPinningState()
+  const allColumns = table.getAllColumns()
+  const leafColumns = callMemoOrStaticFn(
+    table,
+    'getVisibleLeafColumns',
+    table_getVisibleLeafColumns,
+  )
+
+  // 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 (let i = 0; i < left.length; i++) {
+    const column = leafColumnsById[left[i]!]
+    if (
+      column &&
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)
+    ) {
+      leftColumns.push(column)
+    }
+  }
+
+  const rightColumns: typeof leafColumns = []
+  for (let i = 0; i < right.length; i++) {
+    const column = leafColumnsById[right[i]!]
+    if (
+      column &&
+      callMemoOrStaticFn(column, 'getIsVisible', column_getIsVisible)
+    ) {
+      rightColumns.push(column)
+    }
+  }
+
+  const centerColumns = leafColumns.filter(
+    (column) => !left.includes(column.id) && !right.includes(column.id),
+  )
+
+  return buildHeaderGroups(
+    allColumns,
+    [...leftColumns, ...centerColumns, ...rightColumns],
+    table,
+  )
+}
+
+/**
+ * Builds footer groups by reversing the current header groups.
+ *
+ * Footer rendering uses the same header objects and grouping structure, but
+ * renders them from leaf level back toward the root.
+ *
+ * @example
+ * ```ts
+ * const footerGroups = table_getFooterGroups(table)
+ * ```
+ */
+export function table_getFooterGroups<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const headerGroups = table.getHeaderGroups()
+  return [...headerGroups].reverse()
+}
+
+/**
+ * Flattens every header from every header group into one array.
+ *
+ * The result includes parent headers and placeholder headers, in header-group
+ * order from top to bottom.
+ *
+ * @example
+ * ```ts
+ * const flatHeaders = table_getFlatHeaders(table)
+ * ```
+ */
+export function table_getFlatHeaders<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const headerGroups = table.getHeaderGroups()
+  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
+}
+
+/**
+ * Collects only the leaf headers from the current header tree.
+ *
+ * Parent/group headers are skipped, making the result suitable for rendering
+ * one header per visible leaf column.
+ *
+ * @example
+ * ```ts
+ * const leafHeaders = table_getLeafHeaders(table)
+ * ```
+ */
+export function table_getLeafHeaders<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  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

@@ -0,0 +1,56 @@
+import type {
+  Atom,
+  AtomOptions,
+  ReadonlyAtom,
+  Subscription,
+} from '@tanstack/store'
+
+export interface TableAtomOptions<T> extends AtomOptions<T> {
+  /**
+   * A debug name for the atom, useful for debugging.
+   */
+  debugName: string
+}
+
+/**
+ * Framework reactivity bindings used by table-core.
+ *
+ * Adapters (React, Solid, Vue, etc.) provide concrete implementations so
+ * core features can create derived/writable atoms and integrate with their
+ * scheduling primitives.
+ */
+export interface TableReactivityBindings {
+  createOptionsStore: boolean
+  wrapExternalAtoms: boolean
+  addSubscription: (subscription: Subscription) => void
+  /**
+   * Creates a writable atom with an initial value.
+   */
+  createWritableAtom: <T>(
+    initialValue: T,
+    options?: TableAtomOptions<T>,
+  ) => Atom<T>
+  /**
+   * Creates a readonly/derived atom from a compute function.
+   */
+  createReadonlyAtom: <T>(
+    fn: () => T,
+    options?: TableAtomOptions<T>,
+  ) => ReadonlyAtom<T>
+  /**
+   * Evaluates a function without tracking reactive dependencies.
+   */
+  untrack: <T>(fn: () => T) => T
+  /**
+   * 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
+  /**
+   * Unmounts the table, performing any necessary cleanup. This is called when the table is destroyed or unmounted in the framework adapter.
+   */
+  unmount?: () => void
+}