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

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

@@ -13,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<
@@ -42,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<
@@ -64,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<
@@ -127,13 +129,14 @@ export function table_getHeaderGroups<
 }
 
 /**
- * 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<
@@ -145,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<
@@ -170,13 +174,14 @@ export function table_getFlatHeaders<
 }
 
 /**
- * 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<

package/src/core/row-models/coreRowModelsFeature.utils.ts

@@ -5,13 +5,14 @@ import type { RowData } from '../../types/type-utils'
 import type { RowModel } from './coreRowModelsFeature.types'
 
 /**
- * Returns core row model for the table.
+ * Resolves the table's unmodified core row model.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The factory is created once per table, either from `options._rowModels.coreRowModel`
+ * or the built-in `createCoreRowModel()`, then reused for later calls.
  *
  * @example
  * ```ts
- * const value = table_getCoreRowModel(table)
+ * const coreRows = table_getCoreRowModel(table)
  * ```
  */
 export function table_getCoreRowModel<
@@ -28,13 +29,14 @@ export function table_getCoreRowModel<
 }
 
 /**
- * Returns pre filtered row model for the table.
+ * Reads the row model immediately before column/global filtering.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Filtering is the first derived row-model stage, so this currently aliases
+ * `table.getCoreRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreFilteredRowModel(table)
+ * const rowsBeforeFiltering = table_getPreFilteredRowModel(table)
  * ```
  */
 export function table_getPreFilteredRowModel<
@@ -45,13 +47,15 @@ export function table_getPreFilteredRowModel<
 }
 
 /**
- * Returns filtered row model for the table.
+ * Resolves the row model after column and global filtering.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualFiltering` is enabled, or no filtered row-model factory was
+ * registered, this returns the pre-filtered row model because filtering is
+ * expected to happen outside the table.
  *
  * @example
  * ```ts
- * const value = table_getFilteredRowModel(table)
+ * const filteredRows = table_getFilteredRowModel(table)
  * ```
  */
 export function table_getFilteredRowModel<
@@ -71,13 +75,13 @@ export function table_getFilteredRowModel<
 }
 
 /**
- * Returns pre grouped row model for the table.
+ * Reads the row model immediately before grouping.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Grouping runs after filtering, so this aliases `table.getFilteredRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreGroupedRowModel(table)
+ * const rowsBeforeGrouping = table_getPreGroupedRowModel(table)
  * ```
  */
 export function table_getPreGroupedRowModel<
@@ -88,13 +92,14 @@ export function table_getPreGroupedRowModel<
 }
 
 /**
- * Returns grouped row model for the table.
+ * Resolves the row model after grouping has produced grouped and aggregated rows.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualGrouping` is enabled, or no grouped row-model factory was
+ * registered, this returns the pre-grouped row model unchanged.
  *
  * @example
  * ```ts
- * const value = table_getGroupedRowModel(table)
+ * const groupedRows = table_getGroupedRowModel(table)
  * ```
  */
 export function table_getGroupedRowModel<
@@ -114,13 +119,13 @@ export function table_getGroupedRowModel<
 }
 
 /**
- * Returns pre sorted row model for the table.
+ * Reads the row model immediately before sorting.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Sorting runs after grouping, so this aliases `table.getGroupedRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreSortedRowModel(table)
+ * const rowsBeforeSorting = table_getPreSortedRowModel(table)
  * ```
  */
 export function table_getPreSortedRowModel<
@@ -131,13 +136,15 @@ export function table_getPreSortedRowModel<
 }
 
 /**
- * Returns sorted row model for the table.
+ * Resolves the row model after sorting has been applied.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualSorting` is enabled, or no sorted row-model factory was
+ * registered, this returns the pre-sorted row model because sorted data is
+ * expected to be supplied by the caller.
  *
  * @example
  * ```ts
- * const value = table_getSortedRowModel(table)
+ * const sortedRows = table_getSortedRowModel(table)
  * ```
  */
 export function table_getSortedRowModel<
@@ -157,13 +164,13 @@ export function table_getSortedRowModel<
 }
 
 /**
- * Returns pre expanded row model for the table.
+ * Reads the row model immediately before row expansion.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Expansion runs after sorting, so this aliases `table.getSortedRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPreExpandedRowModel(table)
+ * const rowsBeforeExpansion = table_getPreExpandedRowModel(table)
  * ```
  */
 export function table_getPreExpandedRowModel<
@@ -174,13 +181,14 @@ export function table_getPreExpandedRowModel<
 }
 
 /**
- * Returns expanded row model for the table.
+ * Resolves the row model after expanded rows have been flattened into view.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualExpanding` is enabled, or no expanded row-model factory was
+ * registered, this returns the pre-expanded row model unchanged.
  *
  * @example
  * ```ts
- * const value = table_getExpandedRowModel(table)
+ * const expandedRows = table_getExpandedRowModel(table)
  * ```
  */
 export function table_getExpandedRowModel<
@@ -200,13 +208,14 @@ export function table_getExpandedRowModel<
 }
 
 /**
- * Returns pre paginated row model for the table.
+ * Reads the row model immediately before pagination.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Pagination is the final built-in row-model stage, so this aliases
+ * `table.getExpandedRowModel()`.
  *
  * @example
  * ```ts
- * const value = table_getPrePaginatedRowModel(table)
+ * const rowsBeforePagination = table_getPrePaginatedRowModel(table)
  * ```
  */
 export function table_getPrePaginatedRowModel<
@@ -217,13 +226,15 @@ export function table_getPrePaginatedRowModel<
 }
 
 /**
- * Returns paginated row model for the table.
+ * Resolves the row model after pagination has sliced rows for the current page.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * When `manualPagination` is enabled, or no paginated row-model factory was
+ * registered, this returns the pre-paginated row model because pagination is
+ * expected to happen before data reaches the table.
  *
  * @example
  * ```ts
- * const value = table_getPaginatedRowModel(table)
+ * const pageRows = table_getPaginatedRowModel(table)
  * ```
  */
 export function table_getPaginatedRowModel<
@@ -243,13 +254,14 @@ export function table_getPaginatedRowModel<
 }
 
 /**
- * Returns row model for the table.
+ * Resolves the final row model consumed by renderers.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * This is the end of the built-in row-model pipeline: core -> filtering ->
+ * grouping -> sorting -> expanding -> pagination.
  *
  * @example
  * ```ts
- * const value = table_getRowModel(table)
+ * const visibleRows = table_getRowModel(table)
  * ```
  */
 export function table_getRowModel<

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

@@ -49,11 +49,11 @@ export interface Row_Row<
   TData extends RowData,
 > extends Row_CoreProperties<TFeatures, TData> {
   /**
-   * Returns all of the cells for the row by column id.
+   * Builds a lookup of this row's cells keyed by leaf column id.
    */
   getAllCellsByColumnId: () => Record<string, Cell<TFeatures, TData, unknown>>
   /**
-   * Returns all of the cells for the row.
+   * Builds one cell for each leaf column, including cells for hidden columns.
    */
   getAllCells: () => Array<Cell<TFeatures, TData, unknown>>
   /**
@@ -69,11 +69,11 @@ export interface Row_Row<
    */
   getParentRows: () => Array<Row<TFeatures, TData>>
   /**
-   * Returns a unique array of values from the row for a given columnId.
+   * Reads the values this row contributes to faceting/grouping for a column.
    */
   getUniqueValues: <TValue>(columnId: string) => Array<TValue>
   /**
-   * Returns the value from the row for a given columnId.
+   * Reads this row's accessor value for a column id and caches the result.
    */
   getValue: <TValue>(columnId: string) => TValue
   /**

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

@@ -7,13 +7,14 @@ import type { Row } from '../../types/Row'
 import type { Cell } from '../../types/Cell'
 
 /**
- * Returns value for a row.
+ * Reads and caches this row's value for a column.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The value is produced by the column accessor. Missing columns or display
+ * columns without an accessor return `undefined`.
  *
  * @example
  * ```ts
- * const value = row_getValue(row)
+ * const firstName = row_getValue(row, 'firstName')
  * ```
  */
 export function row_getValue<
@@ -36,13 +37,14 @@ export function row_getValue<
 }
 
 /**
- * Returns unique values for a row.
+ * Reads and caches the values used by faceting/grouping for a column.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * If the column defines `getUniqueValues`, that result is used. Otherwise the
+ * row's accessor value is wrapped in a single-item array.
  *
  * @example
  * ```ts
- * const value = row_getUniqueValues(row)
+ * const values = row_getUniqueValues(row, 'tags')
  * ```
  */
 export function row_getUniqueValues<
@@ -80,7 +82,7 @@ export function row_getUniqueValues<
  *
  * @example
  * ```ts
- * const value = row_renderValue(row)
+ * const value = row_renderValue(row, 'firstName')
  * ```
  */
 export function row_renderValue<
@@ -91,13 +93,13 @@ export function row_renderValue<
 }
 
 /**
- * Returns leaf rows for a row.
+ * Flattens this row's descendant tree into leaf rows.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The row itself is not included; only nested `subRows` are walked.
  *
  * @example
  * ```ts
- * const value = row_getLeafRows(row)
+ * const descendants = row_getLeafRows(row)
  * ```
  */
 export function row_getLeafRows<
@@ -108,13 +110,14 @@ export function row_getLeafRows<
 }
 
 /**
- * Returns parent row for a row.
+ * Looks up this row's direct parent, if it has one.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * Parent lookup searches the pre-pagination row model so parent relationships
+ * are available even when the parent is not on the current page.
  *
  * @example
  * ```ts
- * const value = row_getParentRow(row)
+ * const parent = row_getParentRow(row)
  * ```
  */
 export function row_getParentRow<
@@ -125,13 +128,13 @@ export function row_getParentRow<
 }
 
 /**
- * Returns parent rows for a row.
+ * Collects this row's ancestor chain from root to direct parent.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The current row is not included. Rows without a parent return an empty array.
  *
  * @example
  * ```ts
- * const value = row_getParentRows(row)
+ * const ancestors = row_getParentRows(row)
  * ```
  */
 export function row_getParentRows<
@@ -151,13 +154,14 @@ export function row_getParentRows<
 }
 
 /**
- * Returns all cells for a row.
+ * Constructs one cell for each leaf column in this row.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The result follows `table.getAllLeafColumns()` order and includes hidden
+ * columns; visibility-specific APIs filter this list later.
  *
  * @example
  * ```ts
- * const value = row_getAllCells(row)
+ * const cells = row_getAllCells(row)
  * ```
  */
 export function row_getAllCells<
@@ -175,13 +179,13 @@ export function row_getAllCells<
 }
 
 /**
- * Returns all cells by column id for a row.
+ * Builds a lookup map of this row's cells keyed by column id.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * This is the static implementation behind `row.getAllCellsByColumnId()`.
  *
  * @example
  * ```ts
- * const value = row_getAllCellsByColumnId(row)
+ * const cellsById = row_getAllCellsByColumnId(row)
  * ```
  */
 export function row_getAllCellsByColumnId<
@@ -198,13 +202,14 @@ export function row_getAllCellsByColumnId<
 }
 
 /**
- * Returns row id for the table.
+ * Resolves the stable id for a row.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * `options.getRowId` wins when provided. Otherwise root rows use their index
+ * and child rows append their index to the parent id, such as `0.2`.
  *
  * @example
  * ```ts
- * const value = table_getRowId(table)
+ * const id = table_getRowId(originalRow, table, index, parentRow)
  * ```
  */
 export function table_getRowId<
@@ -223,13 +228,14 @@ export function table_getRowId<
 }
 
 /**
- * Returns row for the table.
+ * Looks up a row by id from the current or full row model.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * By default this searches `table.getRowModel()`. Passing `searchAll` searches
+ * the pre-pagination model first, then falls back to the core model.
  *
  * @example
  * ```ts
- * const value = table_getRow(table)
+ * const row = table_getRow(table, rowId, true)
  * ```
  */
 export function table_getRow<

package/src/core/table/coreTablesFeature.types.ts

@@ -66,11 +66,15 @@ export interface TableOptions_Table<
   TData extends RowData,
 > {
   /**
-   * The features that you want to enable for the table.
+   * The feature modules registered on this table instance.
+   *
+   * Feature registration controls which state slices, options, and prototype
+   * APIs are available.
    */
   readonly _features: TFeatures
   /**
-   * The row model options that you want to enable for the table.
+   * Row model factories used by features such as filtering, grouping, sorting,
+   * expansion, and pagination.
    */
   readonly _rowModels?: CreateRowModels_All<TFeatures, TData>
   /**

package/src/core/table/coreTablesFeature.utils.ts

@@ -12,7 +12,7 @@ import type { TableOptions } from '../../types/TableOptions'
  *
  * @example
  * ```ts
- * const value = table_syncExternalStateToBaseAtoms(table)
+ * table_syncExternalStateToBaseAtoms(table)
  * ```
  */
 export function table_syncExternalStateToBaseAtoms<
@@ -72,7 +72,7 @@ export function table_reset<
  *
  * @example
  * ```ts
- * const value = table_mergeOptions(table)
+ * const options = table_mergeOptions(table, nextOptions)
  * ```
  */
 export function table_mergeOptions<

package/src/features/column-faceting/columnFacetingFeature.types.ts

@@ -8,15 +8,18 @@ export interface Column_ColumnFaceting<
   TData extends RowData,
 > {
   /**
-   * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   * Computes min/max numeric facet values for this column.
    */
   getFacetedMinMaxValues: () => undefined | [number, number]
   /**
-   * A function that **computes and returns** a row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
+   * Computes the row model used to derive this column's facet values.
+   *
+   * Other column filters are applied, while this column's own filter is
+   * excluded.
    */
   getFacetedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
+   * Computes unique facet values and occurrence counts for this column.
    */
   getFacetedUniqueValues: () => Map<any, number>
 }
@@ -26,18 +29,21 @@ export interface Table_RowModels_Faceted<
   TData extends RowData,
 > {
   /**
-   * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
-   * > Requires that you pass a valid `facetedMinMaxValues` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedMinMaxValues` function.
+   * Computes min/max numeric facet values for the active faceting context.
+   *
+   * Requires a `facetedMinMaxValues` row-model factory in `_rowModels`.
    */
   getFacetedMinMaxValues: () => undefined | [number, number]
   /**
-   * Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts.
-   * > Requires that you pass a valid `facetedRowModel` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedRowModel` function.
+   * Computes the row model used to derive facet values.
+   *
+   * Requires a `facetedRowModel` row-model factory in `_rowModels`.
    */
   getFacetedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * A function that **computes and returns** a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values.
-   * > Requires that you pass a valid `facetedUniqueValues` row model factory in `_rowModels`. A default implementation is provided via the exported `createFacetedUniqueValues` function.
+   * Computes unique facet values and occurrence counts.
+   *
+   * Requires a `facetedUniqueValues` row-model factory in `_rowModels`.
    */
   getFacetedUniqueValues: () => Map<any, number>
 }
@@ -93,7 +99,7 @@ export interface Table_ColumnFaceting<
    */
   getGlobalFacetedMinMaxValues: () => undefined | [number, number]
   /**
-   * Returns the row model for the table after **global** filtering has been applied.
+   * Computes the row model used to derive global facet values.
    */
   getGlobalFacetedRowModel: () => RowModel<TFeatures, TData>
   /**