@tanstack/table-core 9.0.0-alpha.6 → 9.0.0-beta.1

package/src/core/columns/constructColumn.ts

@@ -0,0 +1,119 @@
+import {} from '../../utils'
+import type { Table_Internal } from '../../types/Table'
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type {
+  AccessorFn,
+  ColumnDef,
+  ColumnDefResolved,
+} from '../../types/ColumnDef'
+import type { Column } from '../../types/Column'
+import type { Column_CoreProperties } from './coreColumnsFeature.types'
+
+/**
+ * Creates or retrieves the column prototype for a table.
+ * The prototype is cached on the table and shared by all column instances.
+ */
+function getColumnPrototype<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): object {
+  if (!table._columnPrototype) {
+    table._columnPrototype = { table }
+    const features = Object.values(table._features)
+    for (let i = 0; i < features.length; i++) {
+      features[i]!.assignColumnPrototype?.(table._columnPrototype, table)
+    }
+  }
+  return table._columnPrototype
+}
+
+/**
+ * Constructs a column 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 constructColumn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  columnDef: ColumnDef<TFeatures, TData, TValue>,
+  depth: number,
+  parent?: Column<TFeatures, TData, TValue>,
+): Column<TFeatures, TData, TValue> {
+  const defaultColumn = table.getDefaultColumnDef()
+
+  const resolvedColumnDef = {
+    ...defaultColumn,
+    ...columnDef,
+  } as ColumnDefResolved<{}, TData, TValue>
+
+  const accessorKey = resolvedColumnDef.accessorKey
+
+  const id =
+    resolvedColumnDef.id ??
+    (accessorKey ? accessorKey.replaceAll('.', '_') : undefined) ??
+    (typeof resolvedColumnDef.header === 'string'
+      ? resolvedColumnDef.header
+      : undefined)
+
+  let accessorFn: AccessorFn<TData, TValue> | undefined
+
+  if (resolvedColumnDef.accessorFn) {
+    accessorFn = resolvedColumnDef.accessorFn
+  } else if (accessorKey) {
+    // Support deep accessor keys
+    if (accessorKey.includes('.')) {
+      const keys = accessorKey.split('.')
+      accessorFn = (originalRow: TData) => {
+        let result = originalRow as Record<string, any> | undefined
+
+        for (let i = 0; i < keys.length; i++) {
+          const key = keys[i]!
+          result = result?.[key]
+          if (process.env.NODE_ENV === 'development' && result === undefined) {
+            console.warn(
+              `"${key}" in deeply nested key "${accessorKey}" returned undefined.`,
+            )
+          }
+        }
+
+        return result as TValue
+      }
+    } else {
+      accessorFn = (originalRow: TData) =>
+        (originalRow as any)[resolvedColumnDef.accessorKey]
+    }
+  }
+
+  if (!id) {
+    if (process.env.NODE_ENV === 'development') {
+      throw new Error(
+        resolvedColumnDef.accessorFn
+          ? `coreColumnsFeature require an id when using an accessorFn`
+          : `coreColumnsFeature require an id when using a non-string header`,
+      )
+    }
+    throw new Error()
+  }
+
+  // Create column with shared prototype for memory efficiency
+  const columnPrototype = getColumnPrototype(table)
+  const column = Object.create(columnPrototype) as Column_CoreProperties<
+    TFeatures,
+    TData,
+    TValue
+  >
+
+  // Only assign instance-specific properties
+  column.accessorFn = accessorFn
+  column.columnDef = resolvedColumnDef as ColumnDef<TFeatures, TData, TValue>
+  column.columns = []
+  column.depth = depth
+  column.id = `${String(id)}`
+  column.parent = parent
+
+  return column as Column<TFeatures, TData, TValue>
+}

package/src/core/columns/coreColumnsFeature.ts

@@ -0,0 +1,100 @@
+import { assignPrototypeAPIs, assignTableAPIs } from '../../utils'
+import {
+  column_getFlatColumns,
+  column_getLeafColumns,
+  table_getAllColumns,
+  table_getAllFlatColumns,
+  table_getAllFlatColumnsById,
+  table_getAllLeafColumns,
+  table_getAllLeafColumnsById,
+  table_getColumn,
+  table_getDefaultColumnDef,
+} from './coreColumnsFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   Column_Column,
+//   TableOptions_Columns,
+//   Table_Columns,
+// } from './coreColumnsFeature.types'
+
+export interface CoreColumnsFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Column: Column_Column<TFeatures, TData>
+  // Table: Table_Columns<TFeatures, TData>
+  // TableOptions: TableOptions_Columns<TFeatures, TData>
+}
+
+/**
+ * Creates the stock core columns feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructCoreColumnsFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<CoreColumnsFeatureConstructors<TFeatures, TData>> {
+  return {
+    assignColumnPrototype: (prototype, table) => {
+      assignPrototypeAPIs('coreColumnsFeature', prototype, table, {
+        column_getFlatColumns: {
+          fn: (column) => column_getFlatColumns(column),
+          memoDeps: (column) => [column.table.options.columns],
+        },
+        column_getLeafColumns: {
+          fn: (column) => column_getLeafColumns(column),
+          memoDeps: (column) => [
+            column.table.atoms.columnOrder?.get(),
+            column.table.atoms.grouping?.get(),
+            column.table.options.columns,
+            column.table.options.groupedColumnMode,
+          ],
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('coreColumnsFeature', table, {
+        table_getDefaultColumnDef: {
+          fn: () => table_getDefaultColumnDef(table),
+          memoDeps: () => [table.options.defaultColumn],
+        },
+        table_getAllColumns: {
+          fn: () => table_getAllColumns(table),
+          memoDeps: () => [table.options.columns],
+        },
+        table_getAllFlatColumns: {
+          fn: () => table_getAllFlatColumns(table),
+          memoDeps: () => [table.options.columns],
+        },
+        table_getAllFlatColumnsById: {
+          fn: () => table_getAllFlatColumnsById(table),
+          memoDeps: () => [table.options.columns],
+        },
+        table_getAllLeafColumns: {
+          fn: () => table_getAllLeafColumns(table),
+          memoDeps: () => [
+            table.atoms.columnOrder?.get(),
+            table.atoms.grouping?.get(),
+            table.options.columns,
+            table.options.groupedColumnMode,
+          ],
+        },
+        table_getAllLeafColumnsById: {
+          fn: () => table_getAllLeafColumnsById(table),
+          memoDeps: () => [table.getAllLeafColumns()],
+        },
+        table_getColumn: {
+          fn: (columnId) => table_getColumn(table, columnId),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Core Columns feature provides the core column functionality.
+ */
+export const coreColumnsFeature = constructCoreColumnsFeature()

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

@@ -0,0 +1,108 @@
+import type { Table_Internal } from '../../types/Table'
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { AccessorFn, ColumnDef } from '../../types/ColumnDef'
+import type { Column } from '../../types/Column'
+
+export interface Column_CoreProperties<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /**
+   * The resolved accessor function to use when extracting the value for the column from each row. Will only be defined if the column def has a valid accessor key or function defined.
+   */
+  accessorFn?: AccessorFn<TData, TValue>
+  /**
+   * The original column def used to create the column.
+   */
+  columnDef: ColumnDef<TFeatures, TData, TValue>
+  /**
+   * The child column (if the column is a group column). Will be an empty array if the column is not a group column.
+   */
+  columns: Array<Column<TFeatures, TData, TValue>>
+  /**
+   * The depth of the column (if grouped) relative to the root column def array.
+   */
+  depth: number
+  /**
+   * The resolved unique identifier for the column resolved in this priority:
+      - A manual `id` property from the column def
+      - The accessor key from the column def
+      - The header string from the column def
+   */
+  id: string
+  /**
+   * The parent column for this column. Will be undefined if this is a root column.
+   */
+  parent?: Column<TFeatures, TData, TValue>
+  /**
+   * Reference to the parent table instance.
+   */
+  table: Table_Internal<TFeatures, TData>
+}
+
+export interface Column_Column<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> extends Column_CoreProperties<TFeatures, TData, TValue> {
+  /**
+   * Flattens this column and every descendant column into a single array.
+   */
+  getFlatColumns: () => Array<Column<TFeatures, TData, TValue>>
+  /**
+   * Collects the terminal leaf columns below this column, or the column itself
+   * when it has no children.
+   */
+  getLeafColumns: () => Array<Column<TFeatures, TData, TValue>>
+}
+
+export interface TableOptions_Columns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+> {
+  /**
+   * The array of column defs to use for the table.
+   */
+  columns: ReadonlyArray<ColumnDef<TFeatures, TData, TValue>>
+  /**
+   * Default column options to use for all column defs supplied to the table.
+   */
+  defaultColumn?: Partial<ColumnDef<TFeatures, TData, TValue>>
+}
+
+export interface Table_Columns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns a map of all flat columns by their ID.
+   */
+  getAllFlatColumnsById: () => Record<string, Column<TFeatures, TData, unknown>>
+  /**
+   * Resolves built-in, feature-level, and user-defined default column options.
+   */
+  getDefaultColumnDef: () => Partial<ColumnDef<TFeatures, TData, unknown>>
+  /**
+   * Normalizes `options.columns` into the table's nested column hierarchy.
+   */
+  getAllColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Flattens the nested column hierarchy, including parent/group columns.
+   */
+  getAllFlatColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Collects all terminal leaf columns, excluding parent/group columns.
+   */
+  getAllLeafColumns: () => Array<Column<TFeatures, TData, unknown>>
+  /**
+   * Returns a map of all leaf-node columns by their ID. This does not include parent columns.
+   */
+  getAllLeafColumnsById: () => Record<string, Column<TFeatures, TData, unknown>>
+  /**
+   * Returns a single column by its ID.
+   */
+  getColumn: (columnId: string) => Column<TFeatures, TData, unknown> | undefined
+}

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

@@ -0,0 +1,275 @@
+import { callMemoOrStaticFn } from '../../utils'
+import { table_getOrderColumnsFn } from '../../features/column-ordering/columnOrderingFeature.utils'
+import { constructColumn } from './constructColumn'
+import type { Table_Internal } from '../../types/Table'
+import type { CellData, RowData } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type {
+  ColumnDef,
+  ColumnDefResolved,
+  GroupColumnDef,
+} from '../../types/ColumnDef'
+import type { Column } from '../../types/Column'
+
+/**
+ * Flattens this column and every descendant column into a single array.
+ *
+ * Group columns appear before their child columns, which matches the normalized
+ * column hierarchy produced during table construction.
+ *
+ * @example
+ * ```ts
+ * const flatColumns = column_getFlatColumns(column)
+ * ```
+ */
+export function column_getFlatColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column<TFeatures, TData, TValue>,
+): Array<Column<TFeatures, TData, TValue>> {
+  return [column, ...column.columns.flatMap((col) => col.getFlatColumns())]
+}
+
+/**
+ * Collects the terminal leaf columns below this column.
+ *
+ * Group columns return their ordered descendants. Non-group columns return an
+ * array containing only the column itself.
+ *
+ * @example
+ * ```ts
+ * const leafColumns = column_getLeafColumns(column)
+ * ```
+ */
+export function column_getLeafColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column<TFeatures, TData, TValue>,
+): Array<Column<TFeatures, TData, TValue>> {
+  if (column.columns.length) {
+    const leafColumns = column.columns.flatMap(
+      (col) => col.getLeafColumns(), // recursive
+    )
+
+    return callMemoOrStaticFn(
+      column.table,
+      'getOrderColumns',
+      table_getOrderColumnsFn,
+    )(leafColumns as any) as any
+  }
+
+  return [column]
+}
+
+/**
+ * Merges built-in, feature, and user default column definitions.
+ *
+ * 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 defaultColumn = table_getDefaultColumnDef(table)
+ * ```
+ */
+export function table_getDefaultColumnDef<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): Partial<ColumnDef<TFeatures, TData, unknown>> {
+  return {
+    header: (props) => {
+      const resolvedColumnDef = props.header.column
+        .columnDef as ColumnDefResolved<{}, TData>
+
+      if (resolvedColumnDef.accessorKey) {
+        return resolvedColumnDef.accessorKey
+      }
+
+      if (resolvedColumnDef.accessorFn) {
+        return resolvedColumnDef.id
+      }
+
+      return null
+    },
+    cell: (props) => props.renderValue<any>()?.toString?.() ?? null,
+    ...Object.values(table._features).reduce((obj, feature) => {
+      return Object.assign(obj, feature.getDefaultColumnDef?.())
+    }, {}),
+    ...table.options.defaultColumn,
+  } as Partial<ColumnDef<TFeatures, TData, unknown>>
+}
+
+/**
+ * Normalizes `options.columns` into the table's nested column tree.
+ *
+ * Each column definition is constructed with its parent and depth, and group
+ * column children are recursively constructed.
+ *
+ * @example
+ * ```ts
+ * const columns = table_getAllColumns(table)
+ * ```
+ */
+export function table_getAllColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): Array<Column<TFeatures, TData, unknown>> {
+  const recurseColumns = (
+    colDefs: ReadonlyArray<ColumnDef<TFeatures, TData, unknown>>,
+    parent?: Column<TFeatures, TData, unknown>,
+    depth = 0,
+  ): Array<Column<TFeatures, TData, unknown>> => {
+    return colDefs.map((columnDef) => {
+      const column = constructColumn(table, columnDef, depth, parent)
+
+      const groupingColumnDef = columnDef as GroupColumnDef<
+        TFeatures,
+        TData,
+        unknown
+      >
+
+      column.columns = groupingColumnDef.columns
+        ? recurseColumns(groupingColumnDef.columns, column, depth + 1)
+        : []
+
+      return column
+    })
+  }
+
+  return recurseColumns(table.options.columns)
+}
+
+/**
+ * Flattens every table column, including group columns and leaf columns.
+ *
+ * Use this when parent/group columns must be included in addition to data leaf
+ * columns.
+ *
+ * @example
+ * ```ts
+ * const flatColumns = table_getAllFlatColumns(table)
+ * ```
+ */
+export function table_getAllFlatColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): Array<Column<TFeatures, TData, unknown>> {
+  return table.getAllColumns().flatMap((column) => column.getFlatColumns())
+}
+
+/**
+ * Builds an id lookup for every flat column in the table.
+ *
+ * Group columns and leaf columns are included. Later columns with the same id
+ * replace earlier entries.
+ *
+ * @example
+ * ```ts
+ * const columnsById = table_getAllFlatColumnsById(table)
+ * ```
+ */
+export function table_getAllFlatColumnsById<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): Record<string, Column<TFeatures, TData, unknown>> {
+  const result: Record<string, Column<TFeatures, TData, unknown>> = {}
+  const flatColumns = table.getAllFlatColumns()
+  for (let i = 0; i < flatColumns.length; i++) {
+    const column = flatColumns[i]!
+    result[column.id] = column
+  }
+  return result
+}
+
+/**
+ * Collects all terminal leaf columns in their current table order.
+ *
+ * Column ordering features can reorder the collected leaves before the result
+ * is returned.
+ *
+ * @example
+ * ```ts
+ * const leafColumns = table_getAllLeafColumns(table)
+ * ```
+ */
+export function table_getAllLeafColumns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): Array<Column<TFeatures, TData, unknown>> {
+  const leafColumns = table.getAllColumns().flatMap(
+    (c) => c.getLeafColumns(), // recursive
+  )
+  return callMemoOrStaticFn(
+    table,
+    'getOrderColumns',
+    table_getOrderColumnsFn,
+  )(leafColumns)
+}
+
+/**
+ * Builds an id lookup for terminal leaf columns only.
+ *
+ * Parent/group columns are excluded, making this lookup appropriate for row
+ * cells and feature state keyed by data columns.
+ *
+ * @example
+ * ```ts
+ * const leavesById = table_getAllLeafColumnsById(table)
+ * ```
+ */
+export function table_getAllLeafColumnsById<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+): Record<string, Column<TFeatures, TData, unknown>> {
+  const result: Record<string, Column<TFeatures, TData, unknown>> = {}
+  const leafColumns = table.getAllLeafColumns()
+  for (let i = 0; i < leafColumns.length; i++) {
+    const column = leafColumns[i]!
+    result[column.id] = column
+  }
+  return result
+}
+
+/**
+ * Looks up a column by id from the flat column map.
+ *
+ * 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 column = table_getColumn(table, 'firstName')
+ * ```
+ */
+export function table_getColumn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  table: Table_Internal<TFeatures, TData>,
+  columnId: string,
+): Column<TFeatures, TData, unknown> | undefined {
+  const column = table.getAllFlatColumnsById()[columnId]
+
+  if (process.env.NODE_ENV === 'development' && !column) {
+    console.warn(`[Table] Column with id '${columnId}' does not exist.`)
+  }
+
+  return column
+}

package/src/core/coreFeatures.ts

@@ -0,0 +1,31 @@
+import { coreCellsFeature } from './cells/coreCellsFeature'
+import { coreColumnsFeature } from './columns/coreColumnsFeature'
+import { coreHeadersFeature } from './headers/coreHeadersFeature'
+import { coreRowModelsFeature } from './row-models/coreRowModelsFeature'
+import { coreRowsFeature } from './rows/coreRowsFeature'
+import { coreTablesFeature } from './table/coreTablesFeature'
+import type { TableReactivityBindings } from '../reactivity'
+
+export interface CoreFeatures {
+  coreReativityFeature?: TableReactivityBindings
+  coreCellsFeature: typeof coreCellsFeature
+  coreColumnsFeature: typeof coreColumnsFeature
+  coreHeadersFeature: typeof coreHeadersFeature
+  coreRowModelsFeature: typeof coreRowModelsFeature
+  coreRowsFeature: typeof coreRowsFeature
+  coreTablesFeature: typeof coreTablesFeature
+}
+
+/**
+ * The built-in core feature set required by every table.
+ *
+ * These features provide table, column, row, header, cell, and core row-model behavior before optional feature plugins are added.
+ */
+export const coreFeatures: CoreFeatures = {
+  coreCellsFeature,
+  coreColumnsFeature,
+  coreHeadersFeature,
+  coreRowModelsFeature,
+  coreRowsFeature,
+  coreTablesFeature,
+}