@tanstack/table-core 9.0.0-beta.49 → 9.0.0-beta.50

package/skills/global-filtering/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.49',
+    library_version: '9.0.0-beta.50',
   }
 requires: ['core', 'table-features', 'client-vs-server', 'column-filtering']
 sources:

package/skills/grouping/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.49',
+    library_version: '9.0.0-beta.50',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/migrate-v8-to-v9/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: lifecycle
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.49'
+  library_version: '9.0.0-beta.50'
 requires: ['core', 'table-features', 'typescript']
 sources:
   - 'TanStack/table:docs/framework/react/guide/migrating.md'
@@ -123,14 +123,22 @@ Move registries from table options or factory arguments into these feature slots
 Register only the built-ins the table references by string name, importing each individually (`filterFn_includesString`, `sortFn_alphanumeric`, `aggregationFn_sum`, and so on) alongside any custom functions. The full registry objects (`filterFns`, `sortFns`, `aggregationFns` exports) still work but bundle every built-in. A slot's keys become the valid string names in column definitions, and `'auto'` resolves only registered functions.
 
 Aggregation is independent from grouping. Add `aggregationFeature` for
-`aggregationFn`, `aggregatedCell`, `column.getAggregationValue(rows?)`, and
+`aggregationFn`, `aggregatedCell`, `column.getAggregationValue(options?)`, and
 `cell.getIsAggregated`. A root total does not require grouping. Convert legacy
 custom callables `(columnId, leafRows, childRows) => result` to
 `constructAggregationFn({ aggregate: (context) => result, merge? })`
 definitions. Replace `column.getAggregationFn()` with
 `column.getAggregationFns()`; arrays in `aggregationFn` return keyed objects.
 Replace the old `AggregationFn` and `CreatedAggregationFn` types with
-`AggregationFnDef`.
+`AggregationFnDef`. Aggregation row selection is shared across every definition
+on a column: `maxAggregationDepth` defaults to `0`, while `1` selects direct
+sub-rows and `Infinity` selects terminal rows. Explicit totals can override it
+with the single object signature
+`column.getAggregationValue({ rows, maxDepth })`; positional row and depth
+arguments are not supported. All built-ins consume the same selected `rows`.
+Custom definitions can inspect grouped `subRows`, and `merge` receives matching
+`subRowResults`. Use `table.getMaxSubRowDepth()` when a depth should derive from
+the deepest structural row in the core model.
 
 ### 3. Migrate state reads and whole-state observation
 

package/skills/pagination/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.49',
+    library_version: '9.0.0-beta.50',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/row-pinning/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.49',
+    library_version: '9.0.0-beta.50',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/row-selection/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.49',
+    library_version: '9.0.0-beta.50',
   }
 requires: ['core', 'table-features']
 sources:

package/skills/sorting/SKILL.md

@@ -6,7 +6,7 @@ metadata:
   {
     type: sub-skill,
     library: '@tanstack/table-core',
-    library_version: '9.0.0-beta.49',
+    library_version: '9.0.0-beta.50',
   }
 requires: ['core', 'table-features', 'client-vs-server']
 sources:

package/skills/table-features/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: sub-skill
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.49'
+  library_version: '9.0.0-beta.50'
 requires: ['core']
 sources:
   - 'TanStack/table:docs/guide/row-models.md'

package/skills/typescript/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: sub-skill
   library: '@tanstack/table-core'
-  library_version: '9.0.0-beta.49'
+  library_version: '9.0.0-beta.50'
 requires: ['core', 'table-features']
 sources:
   - 'TanStack/table:docs/guide/helpers.md'

package/src/core/rows/coreRowsFeature.ts

@@ -9,6 +9,7 @@ import {
   row_getUniqueValues,
   row_getValue,
   row_renderValue,
+  table_getMaxSubRowDepth,
   table_getRow,
   table_getRowId,
   table_getRowsInDisplayOrder,
@@ -73,6 +74,10 @@ export const coreRowsFeature: TableFeature = {
         fn: (id: string, searchAll?: boolean) =>
           table_getRow(table, id, searchAll),
       },
+      table_getMaxSubRowDepth: {
+        fn: () => table_getMaxSubRowDepth(table),
+        memoDeps: () => [table.getCoreRowModel()],
+      },
     })
   },
 }

package/src/core/rows/coreRowsFeature.types.ts

@@ -131,6 +131,11 @@ export interface Table_Rows<
   in out TFeatures extends TableFeatures,
   in out TData extends RowData,
 > {
+  /**
+   * Returns the deepest structural row depth in the core row model.
+   * Root rows are depth `0`, direct sub-rows are depth `1`, and so on.
+   */
+  getMaxSubRowDepth: () => number
   /**
    * Returns the rows in the current display order and assigns their display
    * indexes. When expanded rows bypass pagination, expanded descendants are
@@ -138,6 +143,9 @@ export interface Table_Rows<
    * `row.getDisplayIndex()`.
    */
   getRowsInDisplayOrder: () => Array<Row<TFeatures, TData>>
+  /**
+   * Returns the row id for a given row.
+   */
   getRowId: (_: TData, index: number, parent?: Row<TFeatures, TData>) => string
   /**
    * Returns the row with the given ID.

package/src/core/rows/coreRowsFeature.utils.ts

@@ -167,6 +167,24 @@ export function row_getLeafRows<
   return flattenBy(row.subRows, (d) => d.subRows)
 }
 
+/**
+ * Returns the deepest structural row depth in the core row model.
+ * Root rows are depth `0`, their direct sub-rows are depth `1`, and so on.
+ */
+export function table_getMaxSubRowDepth<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>): number {
+  const rows = table.getCoreRowModel().flatRows
+  let maxDepth = 0
+
+  for (let i = 0; i < rows.length; i++) {
+    maxDepth = Math.max(maxDepth, rows[i]!.depth)
+  }
+
+  return maxDepth
+}
+
 /**
  * Looks up this row's direct parent, if it has one.
  *

package/src/features/aggregation/aggregationFeature.ts

@@ -16,6 +16,7 @@ export const aggregationFeature: TableFeature = {
     aggregatedCell: ({ column, getValue }: any) =>
       formatAggregatedCellValue(getValue(), column.columnDef.aggregationFn),
     aggregationFn: 'auto',
+    maxAggregationDepth: 0,
   }),
 
   getDefaultTableOptions: () => ({
@@ -36,7 +37,7 @@ export const aggregationFeature: TableFeature = {
         fn: (column) => column_getAggregationFns(column),
       },
       column_getAggregationValue: {
-        fn: (column, rows) => column_getAggregationValue(column, rows),
+        fn: (column, options) => column_getAggregationValue(column, options),
       },
       column_getAutoAggregationFn: {
         fn: (column) => column_getAutoAggregationFn(column),

package/src/features/aggregation/aggregationFeature.types.ts

@@ -20,6 +20,14 @@ export interface AggregationContext<
   column: Column<TFeatures, TData, TValue>
   /** Convenience alias for `column.id`. */
   columnId: string
+  /** Maximum relative sub-row depth used to select `rows`. */
+  maxDepth: number
+  /**
+   * Immediate sub-rows for grouped aggregation. This property is omitted
+   * for root or caller-supplied-row aggregation. At a terminal grouping level
+   * these are the direct data rows; at a nested level they are sub-row groups.
+   */
+  subRows?: ReadonlyArray<Row<TFeatures, TData>>
   /** Reads this column's value from one of `rows`. */
   getValue: (row: Row<TFeatures, TData>) => TValue
   /**
@@ -29,8 +37,8 @@ export interface AggregationContext<
    */
   groupingRow?: Row<TFeatures, TData>
   /**
-   * Terminal leaf rows included in this aggregation. The executor normalizes
-   * hierarchical and duplicate row inputs before invoking the definition.
+   * Unique rows selected at `maxDepth`. Branches that end before `maxDepth`
+   * contribute their deepest available row.
    */
   rows: ReadonlyArray<Row<TFeatures, TData>>
   /** The table that owns the column and rows. */
@@ -44,10 +52,10 @@ export interface AggregationMergeContext<
   TValue,
   TResult,
 > extends AggregationContext<TFeatures, TData, TValue> {
-  /** Results produced for each immediate child group, in child-row order. */
-  childResults: ReadonlyArray<TResult>
-  /** Immediate child group rows corresponding to `childResults`. */
-  childRows: ReadonlyArray<Row<TFeatures, TData>>
+  /** Results produced for each immediate sub-row group, in sub-row order. */
+  subRowResults: ReadonlyArray<TResult>
+  /** Immediate sub-row groups corresponding to `subRowResults`. */
+  subRows: ReadonlyArray<Row<TFeatures, TData>>
 }
 
 /** A context-based aggregation definition and optional grouped-result merge. */
@@ -57,11 +65,11 @@ export interface AggregationFnDef<
   TValue = unknown,
   TResult = unknown,
 > {
-  /** Computes a result directly from normalized terminal rows. */
+  /** Computes a result directly from the selected `rows`. */
   aggregate: (context: AggregationContext<TFeatures, TData, TValue>) => TResult
   /**
-   * Combines already-computed immediate child-group results. When omitted,
-   * nested grouping falls back to `aggregate` over the group's terminal rows.
+   * Combines already-computed immediate sub-row results. When omitted,
+   * nested grouping falls back to `aggregate` over the group's selected rows.
    */
   merge?: (
     context: AggregationMergeContext<TFeatures, TData, TValue, TResult>,
@@ -236,6 +244,12 @@ export interface ColumnDef_Aggregation<
    * result object. Inline definitions in an array require an explicit `id`.
    */
   aggregationFn?: AggregationFnOption<TFeatures, TData, TValue>
+  /**
+   * Maximum relative sub-row depth used for grouped aggregation and cached
+   * default totals. `0` selects the supplied root rows, `1` their direct
+   * sub-rows, and so on. Defaults to `0`.
+   */
+  maxAggregationDepth?: number
   /**
    * Optionally supplies a precomputed aggregation value for this column.
    * Return `{ value }` to handle the request, including `{ value: undefined }`;
@@ -257,11 +271,11 @@ export interface Column_Aggregation<
   >
   /**
    * Aggregates this column over the default pre-grouped row model, or over a
-   * caller-provided array of rows. Explicit rows are normalized to unique
-   * terminal leaves and are intentionally not cached.
+   * caller-provided array of rows. `options.maxDepth` overrides the column's
+   * `maxAggregationDepth`. Explicit-row calls are intentionally not cached.
    */
   getAggregationValue: <TResult = ColumnAggregationValue<TFeatures>>(
-    rows?: ReadonlyArray<Row<TFeatures, TData>>,
+    options?: AggregationValueOptions<TFeatures, TData>,
   ) => TResult
   /** Infers `sum` for a numeric first row and `extent` for a Date first row. */
   getAutoAggregationFn: () =>
@@ -269,6 +283,17 @@ export interface Column_Aggregation<
     | undefined
 }
 
+/** Options for a caller-requested column aggregation value. */
+export interface AggregationValueOptions<
+  in out TFeatures extends TableFeatures,
+  in out TData extends RowData,
+> {
+  /** Overrides the column's `maxAggregationDepth` for this request. */
+  maxDepth?: number
+  /** Rows to aggregate instead of the default pre-grouped row model. */
+  rows?: ReadonlyArray<Row<TFeatures, TData>>
+}
+
 /** Cell instance APIs installed by `aggregationFeature`. */
 export interface Cell_Aggregation {
   /** Whether this cell displays an aggregate on a synthetic grouped row. */
@@ -289,6 +314,8 @@ export interface AggregationValueContext<
 > {
   /** The column whose value was requested. */
   column: Column<TFeatures, TData, TValue>
+  /** Maximum relative sub-row depth used for the request. */
+  maxDepth: number
   /** Caller-provided rows, or `undefined` for the default row model. */
   rows?: ReadonlyArray<Row<TFeatures, TData>>
   /** The table that owns the column. */

package/src/features/aggregation/aggregationFeature.utils.ts

@@ -5,9 +5,11 @@ import type { Row } from '../../types/Row'
 import type { TableFeatures } from '../../types/TableFeatures'
 import type { CellData, RowData } from '../../types/type-utils'
 import type {
+  AggregationContext,
   AggregationFnDef,
   AggregationFnDescriptor,
   AggregationFnRef,
+  AggregationValueOptions,
   ColumnAggregationValue,
   ResolvedAggregationFn,
 } from './aggregationFeature.types'
@@ -15,6 +17,7 @@ import type {
 interface AggregationCacheEntry {
   aggregationFnOption: unknown
   dependency: unknown
+  maxDepth: number
   registry: unknown
   value: unknown
 }
@@ -50,21 +53,31 @@ function warn(message: string) {
   }
 }
 
+function resolveMaxAggregationDepth(maxDepth: number | undefined) {
+  return maxDepth === undefined || Number.isNaN(maxDepth)
+    ? 0
+    : Math.max(0, Math.floor(maxDepth))
+}
+
 /**
- * Flattens hierarchical row inputs to unique terminal leaves in encounter
- * order. This is the normalization used by public aggregation-value calls.
+ * Selects unique rows at a maximum relative depth in encounter order.
+ * Branches that end before the requested depth contribute their deepest row.
  */
 export function normalizeAggregationRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
->(rows: ReadonlyArray<Row<TFeatures, TData>>): Array<Row<TFeatures, TData>> {
+>(
+  rows: ReadonlyArray<Row<TFeatures, TData>>,
+  maxDepth = 0,
+): Array<Row<TFeatures, TData>> {
   const result: Array<Row<TFeatures, TData>> = []
   const seen = new Set<string>()
+  const normalizedMaxDepth = resolveMaxAggregationDepth(maxDepth)
 
-  const visit = (row: Row<TFeatures, TData>) => {
-    if (row.subRows.length) {
+  const visit = (row: Row<TFeatures, TData>, depth: number) => {
+    if (row.subRows.length && depth < normalizedMaxDepth) {
       for (let i = 0; i < row.subRows.length; i++) {
-        visit(row.subRows[i]!)
+        visit(row.subRows[i]!, depth + 1)
       }
       return
     }
@@ -76,7 +89,7 @@ export function normalizeAggregationRows<
   }
 
   for (let i = 0; i < rows.length; i++) {
-    visit(rows[i]!)
+    visit(rows[i]!, 0)
   }
 
   return result
@@ -232,35 +245,40 @@ export function column_getAggregationFns<
   return finish(resolved)
 }
 
-function getChildResult(
-  childValue: unknown,
+function getSubRowResult(
+  subRowValue: unknown,
   isMultiple: boolean,
   id: string | undefined,
 ) {
-  if (!isMultiple) return childValue
-  if (!id || !childValue || typeof childValue !== 'object') return undefined
-  return hasOwn(childValue, id)
-    ? (childValue as Record<string, unknown>)[id]
+  if (!isMultiple) return subRowValue
+  if (!id || !subRowValue || typeof subRowValue !== 'object') return undefined
+  return hasOwn(subRowValue, id)
+    ? (subRowValue as Record<string, unknown>)[id]
     : undefined
 }
 
-/** Executes every configured aggregation for a column over normalized rows. */
+/** Executes every configured aggregation over a depth-selected row frontier. */
 export function aggregateColumnValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
 >(args: {
-  childRows?: ReadonlyArray<Row<TFeatures, TData>>
+  maxDepth?: number
+  subRows?: ReadonlyArray<Row<TFeatures, TData>>
   column: Column<TFeatures, TData, unknown>
   groupingRow?: Row<TFeatures, TData>
   rows: ReadonlyArray<Row<TFeatures, TData>>
 }): unknown {
-  const { childRows, column, groupingRow, rows } = args
+  const { subRows, column, groupingRow, rows } = args
   const internalColumn = column as Column_Internal<TFeatures, TData, unknown>
+  const maxDepth = resolveMaxAggregationDepth(
+    args.maxDepth ?? internalColumn.columnDef.maxAggregationDepth,
+  )
+  const aggregationRows = normalizeAggregationRows(rows, maxDepth)
   const entries = column_getAggregationFns(internalColumn)
   const isMultiple = Array.isArray(internalColumn.columnDef.aggregationFn)
   const canMerge =
-    !!childRows?.length &&
-    childRows.every(
+    !!subRows?.length &&
+    subRows.every(
       (row) =>
         !!(row as any).groupingColumnId &&
         (row as any).groupingColumnId !== column.id,
@@ -270,22 +288,24 @@ export function aggregateColumnValue<
     const definition = entry.aggregationFn
     if (!definition) return undefined
 
-    const context = {
+    const context: AggregationContext<TFeatures, TData, unknown> = {
+      ...(subRows ? { subRows } : {}),
       column,
       columnId: column.id,
       getValue: (row: Row<TFeatures, TData>) => row.getValue(column.id),
       ...(groupingRow ? { groupingRow } : {}),
-      rows,
+      maxDepth,
+      rows: aggregationRows,
       table: column.table as any,
     }
 
     if (canMerge && definition.merge) {
       return definition.merge({
         ...context,
-        childResults: childRows.map((row) =>
-          getChildResult(row.getValue(column.id), isMultiple, entry.id),
+        subRowResults: subRows.map((row) =>
+          getSubRowResult(row.getValue(column.id), isMultiple, entry.id),
         ),
-        childRows: childRows,
+        subRows,
       })
     }
 
@@ -306,17 +326,22 @@ export function aggregateColumnValue<
   return result
 }
 
-/** Implements `column.getAggregationValue(rows?)` and its default-value cache. */
+/** Implements `column.getAggregationValue(options?)` and its default cache. */
 export function column_getAggregationValue<
   TFeatures extends TableFeatures,
   TData extends RowData,
   TValue extends CellData = CellData,
 >(
   column: Column_Internal<TFeatures, TData, TValue>,
-  rows?: ReadonlyArray<Row<TFeatures, TData>>,
+  options?: AggregationValueOptions<TFeatures, TData>,
 ): ColumnAggregationValue<TFeatures> {
+  const rows = options?.rows
+  const resolvedMaxDepth = resolveMaxAggregationDepth(
+    options?.maxDepth ?? column.columnDef.maxAggregationDepth,
+  )
   const providedResult = column.columnDef.getAggregationValue?.({
     column: column as any,
+    maxDepth: resolvedMaxDepth,
     rows,
     table: column.table as any,
   })
@@ -327,7 +352,8 @@ export function column_getAggregationValue<
   if (rows !== undefined) {
     return aggregateColumnValue({
       column: column as any,
-      rows: normalizeAggregationRows(rows),
+      maxDepth: resolvedMaxDepth,
+      rows,
     }) as any
   }
 
@@ -341,6 +367,7 @@ export function column_getAggregationValue<
   if (
     previous &&
     previous.dependency === model &&
+    previous.maxDepth === resolvedMaxDepth &&
     previous.registry === registry &&
     previous.aggregationFnOption === aggregationFnOption
   ) {
@@ -349,11 +376,13 @@ export function column_getAggregationValue<
 
   const value = aggregateColumnValue({
     column: column as any,
-    rows: normalizeAggregationRows(model.rows),
+    maxDepth: resolvedMaxDepth,
+    rows: model.rows,
   })
   ;(column as any)._aggregationValueCache = {
     aggregationFnOption,
     dependency: model,
+    maxDepth: resolvedMaxDepth,
     registry,
     value,
   } satisfies AggregationCacheEntry