diff --git a/docs/config.json b/docs/config.json index ea5744ffe3..653264a6fc 100644 --- a/docs/config.json +++ b/docs/config.json @@ -843,7 +843,7 @@ { "label": "coreTablesFeature", "to": "reference/index/variables/coreTablesFeature" }, { "label": "columnFilteringFeature", "to": "reference/index/variables/columnFilteringFeature" }, { "label": "columnFacetingFeature", "to": "reference/index/variables/columnFacetingFeature" }, - { "label": "aggregationFeature", "to": "reference/index/variables/aggregationFeature" }, + { "label": "rowAggregationFeature", "to": "reference/index/variables/rowAggregationFeature" }, { "label": "columnGroupingFeature", "to": "reference/index/variables/columnGroupingFeature" }, { "label": "columnOrderingFeature", "to": "reference/index/variables/columnOrderingFeature" }, { "label": "columnPinningFeature", "to": "reference/index/variables/columnPinningFeature" }, diff --git a/docs/framework/alpine/guide/aggregation.md b/docs/framework/alpine/guide/aggregation.md index 19f43db173..521e675ed5 100644 --- a/docs/framework/alpine/guide/aggregation.md +++ b/docs/framework/alpine/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Alpine) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/alpine-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/alpine/guide/grouping.md b/docs/framework/alpine/guide/grouping.md index 7e2cce1fa2..bdf3a98753 100644 --- a/docs/framework/alpine/guide/grouping.md +++ b/docs/framework/alpine/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Alpine examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. Read your reactive inputs such as `data` through a getter (for example backing them with `Alpine.reactive`) when creating the table, so the table sees updates. diff --git a/docs/framework/angular/guide/aggregation.md b/docs/framework/angular/guide/aggregation.md index 21f33f4b42..4bd4ba097f 100644 --- a/docs/framework/angular/guide/aggregation.md +++ b/docs/framework/angular/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Angular) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/angular-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/angular/guide/grouping.md b/docs/framework/angular/guide/grouping.md index 5a11bf4a6b..dde034a6fb 100644 --- a/docs/framework/angular/guide/grouping.md +++ b/docs/framework/angular/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Angular examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. ### Grouping Setup diff --git a/docs/framework/angular/guide/migrating.md b/docs/framework/angular/guide/migrating.md index 22ec2fc7c2..1f5f0ad388 100644 --- a/docs/framework/angular/guide/migrating.md +++ b/docs/framework/angular/guide/migrating.md @@ -2,14 +2,20 @@ title: Migrating to TanStack Table V9 (Angular) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. + +--- > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. + +--- > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Model Factories](#row-model-factories) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See the row models section below for the new shape. + +--- ## What's New in TanStack Table V9 @@ -44,6 +50,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - **`tableOptions`**: Compose reusable table configuration, including features, row models, and default options. - **`createTableHook`**: Create reusable, strongly typed Angular table factories with pre-bound features, row models, default options, and component registries. +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Upgrades Are Opt-in While v9 is a significant upgrade, **you don't have to adopt everything at once**: @@ -55,35 +66,6 @@ The main change is **how you define a table** with the Angular adapter, specific ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Entrypoint Change The Angular adapter entrypoint to create a table instance is `injectTable`: @@ -107,23 +89,6 @@ const v9Table = injectTable(() => ({ > Note: `injectTable` evaluates your initializer whenever any Angular signal read inside of it changes. > Keep expensive/static values (like `columns` and `features`) as stable references outside the initializer. -### Instance Methods Must Be Called on Their Instance - -In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```ts -// v8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// v9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In Table V9, you must explicitly declare which features your table uses. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -172,8 +137,6 @@ const v9Table = injectTable(() => ({ })) ``` ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior If you want all features without thinking about it (like Table V8), import `stockFeatures`: @@ -190,94 +153,31 @@ class TableCmp { } ``` -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - -### Available Features +#### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Model Factories +### Row Model Factories Row models are the functions that process your data (filtering, sorting, pagination, etc.). In Table V9, row model factories and their `*Fns` registries move from a separate `rowModels` option into `tableFeatures`. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. -### Migration Mapping +#### Migration Mapping | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -293,7 +193,7 @@ Row models are the functions that process your data (filtering, sorting, paginat The `filterFns`, `sortFns`, and `aggregationFns` objects are now registered as named slots on `tableFeatures` rather than passed as arguments to the factory functions. -### Key Change: Row Model Factories and Fn Registries Move into `tableFeatures` +#### Key Change: Row Model Factories and Fn Registries Move into `tableFeatures` ```ts import { @@ -310,7 +210,7 @@ import { const features = tableFeatures({ columnFilteringFeature, rowSortingFeature, - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, rowPaginationFeature, filteredRowModel: createFilteredRowModel(), @@ -331,7 +231,7 @@ class TableCmp { } ``` -### Full Migration Example +#### Full Migration Example ```ts // v8 @@ -388,7 +288,7 @@ const v9Table = injectTable(() => ({ })) ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -416,6 +316,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```ts +// v8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// v9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -550,6 +467,154 @@ const unsubscribe = this.table.store.subscribe((state) => { --- +## Feature-by-Feature Breaking Changes + +### Sorting + +Sorting-related APIs have been renamed for consistency: + +| v8 | v9 | +| --------------------------------- | ------------------------ | +| `sortingFn` (column def option) | `sortFn` | +| `column.getSortingFn()` | `column.getSortFn()` | +| `column.getAutoSortingFn()` | `column.getAutoSortFn()` | +| `SortingFn` type | `SortFn` type | +| `SortingFns` interface | `SortFns` interface | +| `sortingFns` (built-in functions) | `sortFns` | + +Update your column definitions. + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +The `enablePinning` option has also been split into separate options: + +```ts +// v8 +enablePinning: true + +// v9 +enableColumnPinning: true +enableRowPinning: true +``` + +### Column Sizing vs. Column Resizing Split + +In v8, column sizing and resizing were combined in a single feature. In v9, they've been split into separate features for better tree-shaking. + +| v8 | v9 | +| --------------------------------- | ----------------------------------------------- | +| `ColumnSizing` (combined feature) | `columnSizingFeature` + `columnResizingFeature` | +| `columnSizingInfo` state | `columnResizing` state | +| `setColumnSizingInfo()` | `setColumnResizing()` | +| `onColumnSizingInfoChange` option | `onColumnResizingChange` option | + +If you only need column sizing (fixed widths) without interactive resizing, you can import just `columnSizingFeature`. If you need drag-to-resize functionality, import both. + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | v8 | v9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| v8 | v9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents. + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes The `createColumnHelper` function now requires a `TFeatures` type parameter in addition to `TData`: @@ -785,86 +850,6 @@ For full setup and patterns, see the [Composable Tables Guide](./composable-tabl --- -## Other Breaking Changes - -### Column Pinning Option Split - -The `enablePinning` option has been split into separate options: - -```ts -// v8 -enablePinning: true - -// v9 -enableColumnPinning: true -enableRowPinning: true -``` - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents. - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Column Sizing vs. Column Resizing Split - -In v8, column sizing and resizing were combined in a single feature. In v9, they've been split into separate features for better tree-shaking. - -| v8 | v9 | -| --------------------------------- | ----------------------------------------------- | -| `ColumnSizing` (combined feature) | `columnSizingFeature` + `columnResizingFeature` | -| `columnSizingInfo` state | `columnResizing` state | -| `setColumnSizingInfo()` | `setColumnResizing()` | -| `onColumnSizingInfoChange` option | `onColumnResizingChange` option | - -If you only need column sizing (fixed widths) without interactive resizing, you can import just `columnSizingFeature`. If you need drag-to-resize functionality, import both. - -### Sorting API Renames - -Sorting-related APIs have been renamed for consistency: - -| v8 | v9 | -| --------------------------------- | ------------------------ | -| `sortingFn` (column def option) | `sortFn` | -| `column.getSortingFn()` | `column.getSortFn()` | -| `column.getAutoSortingFn()` | `column.getAutoSortFn()` | -| `SortingFn` type | `SortFn` type | -| `SortingFns` interface | `SortFns` interface | -| `sortingFns` (built-in functions) | `sortFns` | - -Update your column definitions. - -### Row API Changes - -Some row APIs have changed from private to public: - -| v8 | v9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | v8 | v9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -983,16 +968,17 @@ This change improves type safety. If you were passing unusual data types, ensure - [ ] Update your table setup to v9 and define `features` using `tableFeatures()` (or use `stockFeatures`) - [ ] Migrate `get*RowModel()` options: move row model factories into `tableFeatures` as named slots - [ ] Move `filterFns`, `sortFns`, and `aggregationFns` into `tableFeatures` as named slots (no longer passed as factory arguments) -- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot -- [ ] Update TypeScript types to include `TFeatures` generic -- [ ] Update state access: `table.getState().slice` → `table.atoms..get()` where possible; use `table.store.get()` for full-state/debug reads -- [ ] Update `createColumnHelper()` → `createColumnHelper()` -- [ ] Replace `enablePinning` with `enableColumnPinning`/`enableRowPinning` if used +- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`) - [ ] Rename `sortingFn` → `sortFn` in column definitions -- [ ] Split column sizing/resizing: use both `columnSizingFeature` and `columnResizingFeature` if needed +- [ ] Update column pinning to `start`/`end` terminology (`columnPinning.start`, `column.pin('end')`, `getStart*`/`getEnd*` APIs) +- [ ] Replace `enablePinning` with `enableColumnPinning`/`enableRowPinning` if used - [ ] Rename `columnSizingInfo` state → `columnResizing` (and related options) +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions +- [ ] Update state access: `table.getState().slice` → `table.atoms..get()` where possible; use `table.store.get()` for full-state/debug reads +- [ ] Update TypeScript types to include `TFeatures` generic +- [ ] Update `createColumnHelper()` → `createColumnHelper()` - [ ] If you use `TableMeta`/`ColumnMeta` declaration merging, add the `TFeatures` generic to your augmentations (optionally, switch to the per-table `tableMeta`/`columnMeta` feature slots) -- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`) +- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot - [ ] (Optional) Use `tableOptions()` for composable configurations - [ ] (Optional) Use `createTableHook` for reusable table patterns diff --git a/docs/framework/ember/guide/aggregation.md b/docs/framework/ember/guide/aggregation.md index 8198571c6c..af9324346d 100644 --- a/docs/framework/ember/guide/aggregation.md +++ b/docs/framework/ember/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Ember) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/ember-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/ember/guide/grouping.md b/docs/framework/ember/guide/grouping.md index 6df0290fb9..5cb29413fc 100644 --- a/docs/framework/ember/guide/grouping.md +++ b/docs/framework/ember/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Ember examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. ### Grouping Setup diff --git a/docs/framework/lit/guide/aggregation.md b/docs/framework/lit/guide/aggregation.md index e6faab5f57..7cc7cfddc3 100644 --- a/docs/framework/lit/guide/aggregation.md +++ b/docs/framework/lit/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Lit) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -22,7 +22,7 @@ directly to a column does not require a registry entry. ```ts import { TableController, - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/lit-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -108,7 +108,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/lit/guide/grouping.md b/docs/framework/lit/guide/grouping.md index d800ca224e..a7b7fd3b0b 100644 --- a/docs/framework/lit/guide/grouping.md +++ b/docs/framework/lit/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Lit examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. ### Grouping Setup diff --git a/docs/framework/lit/guide/migrating.md b/docs/framework/lit/guide/migrating.md index eb97e776f1..07cd4e8da1 100644 --- a/docs/framework/lit/guide/migrating.md +++ b/docs/framework/lit/guide/migrating.md @@ -2,14 +2,14 @@ title: Migrating to TanStack Table V9 (Lit) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Model and Function Registry Migration](#row-model-and-function-registry-migration) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See the row models section below for the new shape. ## What's New in TanStack Table V9 @@ -46,6 +46,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - **`tableOptions()`**: Compose reusable table configuration, including features, row models, and default options. - **`createTableHook()`**: Define shared Lit table factories with pre-bound features, row models, defaults, and render helpers. +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Table Logic Is Still Familiar - Column definitions keep the same basic `accessorKey`, `accessorFn`, `header`, `cell`, and `footer` shapes. @@ -58,35 +63,6 @@ The main migration is replacing the v8 controller-with-options-thunk with a v9 c ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Controller Construction Change ```ts @@ -117,23 +93,6 @@ protected render() { The v9 controller takes the host only. Pass options to `.table(...)` during render. -### Instance Methods Must Be Called on Their Instance - -In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```ts -// v8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// v9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In Table V9, you must explicitly declare which features your table uses. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -183,8 +142,6 @@ protected render() { } ``` ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior `stockFeatures` is useful for early migration before you audit feature usage. @@ -201,94 +158,31 @@ const table = this.tableController.table({ Use it as a temporary migration shortcut. Explicit feature registration is the production target. -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - -### Available Features +#### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Model and Function Registry Migration +### Row Model and Function Registry Migration Row model factories and function registries are now slots on `tableFeatures({...})`. The separate `rowModels` option is removed. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. -### Migration Mapping +#### Migration Mapping | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -304,7 +198,7 @@ Row model factories and function registries are now slots on `tableFeatures({... Function registries move to slots too: pass `filterFns`, `sortFns`, and `aggregationFns` directly to `tableFeatures` instead of as factory arguments. -### Full Migration Example +#### Full Migration Example ```ts // v8 @@ -369,7 +263,7 @@ protected render() { } ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -397,6 +291,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```ts +// v8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// v9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -556,6 +467,145 @@ Do not provide both `atoms.pagination` and `state.pagination`; the atom owns tha --- +## Feature-by-Feature Breaking Changes + +### Sorting + +| v8 | v9 | +| -------------------- | ----------------- | +| `sortingFn` | `sortFn` | +| `sortingFns` | `sortFns` | +| `getSortingFn()` | `getSortFn()` | +| `getAutoSortingFn()` | `getAutoSortFn()` | +| `SortingFn` | `SortFn` | + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +Table-level `enablePinning` split into: + +```ts +enableColumnPinning: true +enableRowPinning: true +``` + +### Column Sizing vs. Column Resizing Split + +Column resizing now has its own feature and state slice. + +```ts +const features = tableFeatures({ + columnSizingFeature, + columnResizingFeature, +}) +``` + +`columnSizingInfo` became `columnResizing`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | v8 | v9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| Table V8 | Table V9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes Column helpers and column types now include `TFeatures` first. @@ -662,79 +712,6 @@ See the [Composable Tables Guide](./composable-tables.md) for full patterns. --- -## Other Breaking Changes - -### Column Pinning Option Split - -Table-level `enablePinning` split into: - -```ts -enableColumnPinning: true -enableRowPinning: true -``` - -### Column Sizing vs. Column Resizing Split - -Column resizing now has its own feature and state slice. - -```ts -const features = tableFeatures({ - columnSizingFeature, - columnResizingFeature, -}) -``` - -`columnSizingInfo` became `columnResizing`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. - -### Sorting API Renames - -| v8 | v9 | -| -------------------- | ----------------- | -| `sortingFn` | `sortFn` | -| `sortingFns` | `sortFns` | -| `getSortingFn()` | `getSortFn()` | -| `getAutoSortingFn()` | `getAutoSortFn()` | -| `SortingFn` | `SortFn` | - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Row API Changes - -Some row APIs have changed from private to public: - -| Table V8 | Table V9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -If you were accessing this internal API, you can now use it without the underscore prefix. - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | v8 | v9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -846,17 +823,16 @@ type Person = { - [ ] Replace controller construction with `new TableController(this)`. - [ ] Move table options from the controller constructor into `tableController.table(...)`. - [ ] Define `features` using `tableFeatures()` (or use `stockFeatures`) -- [ ] If aggregating, add `aggregationFeature`; add `columnGroupingFeature` separately only when grouping rows -- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Move row model factories and function registries into `tableFeatures({...})` slots (remove the separate `rowModels` option). - [ ] Remove `getCoreRowModel`; the core row model is automatic. - [ ] Register `sortFns`, `filterFns`, and `aggregationFns` as slots on `tableFeatures({...})` (not as factory arguments). -- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. +- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). - [ ] Rename `sortingFn` to `sortFn`. -- [ ] Add `typeof features` to column helpers and types. +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Replace `table.getState()` reads with `table.state`, `table.store.state`, or `table.atoms..get()`. - [ ] Replace top-level `onStateChange` with per-slice callbacks or external atoms. -- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). +- [ ] Add `typeof features` to column helpers and types. +- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. - [ ] Replace `flexRender(...)` calls with `FlexRender({ cell | header | footer })`. - [ ] Audit `stockFeatures` before production. diff --git a/docs/framework/preact/guide/aggregation.md b/docs/framework/preact/guide/aggregation.md index 0e51c2f7bd..e9423a05cb 100644 --- a/docs/framework/preact/guide/aggregation.md +++ b/docs/framework/preact/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Preact) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```tsx import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/preact-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```tsx const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/preact/guide/grouping.md b/docs/framework/preact/guide/grouping.md index 8b0904e292..a5433a4be1 100644 --- a/docs/framework/preact/guide/grouping.md +++ b/docs/framework/preact/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Preact examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. ### Grouping Setup diff --git a/docs/framework/preact/guide/migrating.md b/docs/framework/preact/guide/migrating.md index 91ac868be0..56699d0b80 100644 --- a/docs/framework/preact/guide/migrating.md +++ b/docs/framework/preact/guide/migrating.md @@ -2,14 +2,20 @@ title: Migrating to TanStack Table V9 (Preact) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. + +--- > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. + +--- > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Model Factories](#row-model-factories) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See the row models section below for the new shape. + +--- ## What's New in TanStack Table V9 @@ -44,6 +50,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - **`tableOptions()`**: Compose reusable table configuration, including features, row models, and default options. - **`createTableHook()`**: Create app-level Preact table factories with shared features, row models, defaults, and component conventions. +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Upgrades Are Opt-in - You can start with `stockFeatures` while migrating, then replace it with explicit feature registration. @@ -62,35 +73,6 @@ This guide is for migrating that setup to the native v9 `@tanstack/preact-table` ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Hook Rename ```tsx @@ -105,23 +87,6 @@ import { useTable } from '@tanstack/preact-table' const table = useTable(options) ``` -### Instance Methods Must Be Called on Their Instance - -In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```tsx -// v8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// v9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In v9, a table must declare its feature set. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -171,8 +136,6 @@ const table = useTable({ Keep the `features` object outside the component when possible so the reference stays stable. ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior `stockFeatures` includes the common feature set and can be useful for smoke tests or early migration. It gives up the main bundle-size benefit of v9, so audit it before shipping. @@ -187,94 +150,31 @@ const table = useTable({ }) ``` -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - -### Available Features +#### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Model Factories +### Row Model Factories Row models process data for features like filtering, sorting, grouping, expanding, faceting, and pagination. In v9, row model factories and function registries are slots on `tableFeatures` rather than a separate `rowModels` option. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. -### Migration Mapping +#### Migration Mapping | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -290,7 +190,7 @@ Row models process data for features like filtering, sorting, grouping, expandin Function registries move to slots too: pass `filterFns`, `sortFns`, and `aggregationFns` directly to `tableFeatures` instead of as factory arguments. -### Full Migration Example +#### Full Migration Example ```tsx // v8 / before: React adapter through preact/compat @@ -347,7 +247,7 @@ const table = useTable({ }) ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -375,6 +275,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```tsx +// v8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// v9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -539,6 +456,150 @@ When `atoms.pagination` is provided, table writes like `table.setPageIndex(2)` w --- +## Feature-by-Feature Breaking Changes + +### Sorting + +| v8 | v9 | +| -------------------- | ----------------- | +| `sortingFn` | `sortFn` | +| `sortingFns` | `sortFns` | +| `getSortingFn()` | `getSortFn()` | +| `getAutoSortingFn()` | `getAutoSortFn()` | +| `SortingFn` | `SortFn` | +| `SortingFns` | `SortFns` | + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +At the table level, `enablePinning` split into column and row options: + +```tsx +const table = useTable({ + enableColumnPinning: true, + enableRowPinning: true, +}) +``` + +Per-column `enablePinning` remains a column option. + +### Column Sizing vs. Column Resizing Split + +Column resizing now has its own feature and state slice. + +```tsx +const features = tableFeatures({ + columnSizingFeature, + columnResizingFeature, +}) +``` + +`columnSizingInfo` is now `columnResizing`, and `onColumnSizingInfoChange` is now `onColumnResizingChange`. + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | v8 | v9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| Table V8 | Table V9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes `TFeatures` is now the first generic for column helpers and table types. @@ -641,84 +702,6 @@ See the [Composable Tables Guide](./composable-tables.md) for full patterns. --- -## Other Breaking Changes - -### Column Pinning Option Split - -At the table level, `enablePinning` split into column and row options: - -```tsx -const table = useTable({ - enableColumnPinning: true, - enableRowPinning: true, -}) -``` - -Per-column `enablePinning` remains a column option. - -### Column Sizing vs. Column Resizing Split - -Column resizing now has its own feature and state slice. - -```tsx -const features = tableFeatures({ - columnSizingFeature, - columnResizingFeature, -}) -``` - -`columnSizingInfo` is now `columnResizing`, and `onColumnSizingInfoChange` is now `onColumnResizingChange`. - -### Sorting API Renames - -| v8 | v9 | -| -------------------- | ----------------- | -| `sortingFn` | `sortFn` | -| `sortingFns` | `sortFns` | -| `getSortingFn()` | `getSortFn()` | -| `getAutoSortingFn()` | `getAutoSortFn()` | -| `SortingFn` | `SortFn` | -| `SortingFns` | `SortFns` | - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Row API Changes - -Some row APIs have changed from private to public: - -| Table V8 | Table V9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -If you were accessing this internal API, you can now use it without the underscore prefix. - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | v8 | v9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -835,12 +818,11 @@ type Person = { - [ ] Replace `@tanstack/react-table` imports used through `preact/compat` with `@tanstack/preact-table`. - [ ] Replace `useReactTable` with `useTable`. - [ ] Define `features` using `tableFeatures()` (or use `stockFeatures`) -- [ ] If aggregating, add `aggregationFeature`; add `columnGroupingFeature` separately only when grouping rows -- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Migrate `get*RowModel()` options (or earlier-beta `rowModels: {...}` entries) to `tableFeatures({...})` slots (e.g. `filteredRowModel: createFilteredRowModel()`). - [ ] Drop `getCoreRowModel`; the core row model is automatic. - [ ] Move `sortingFns`, `filterFns`, and `aggregationFns` into `tableFeatures` slots (not factory args). - [ ] Rename `sortingFn` to `sortFn` and `sortingFns` to `sortFns`. +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Replace `declare module` augmentation for `FilterFns`/`SortFns`/`AggregationFns`/`FilterMeta` with registry slots on `tableFeatures` (`filterFns`, `sortFns`, `aggregationFns`, `filterMeta`). - [ ] Update column helpers and types to include `typeof features`. - [ ] Replace broad `table.getState()` reads with `table.state`, `table.store.state`, or `table.atoms..get()`. diff --git a/docs/framework/react/guide/aggregation.md b/docs/framework/react/guide/aggregation.md index dcb39b563a..bc31370e79 100644 --- a/docs/framework/react/guide/aggregation.md +++ b/docs/framework/react/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (React) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```tsx import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/react-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```tsx const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/react/guide/grouping.md b/docs/framework/react/guide/grouping.md index c4991ae09f..3f97bb3635 100644 --- a/docs/framework/react/guide/grouping.md +++ b/docs/framework/react/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these React examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. ### Grouping Setup diff --git a/docs/framework/react/guide/migrating.md b/docs/framework/react/guide/migrating.md index a9348650a5..4b8377f8fd 100644 --- a/docs/framework/react/guide/migrating.md +++ b/docs/framework/react/guide/migrating.md @@ -2,14 +2,18 @@ title: Migrating to TanStack Table V9 (React) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. + +--- > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. + +--- > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Model Factories](#row-model-factories) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See [Row Model Factories](#row-model-factories) for the new shape. --- @@ -46,6 +50,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - `tableOptions`: Compose reusable table configuration, including features, row models, and default options. - `createTableHook`: Create custom table hooks with pre-bound features and components when you need a reusable app-level table pattern. See the [composable-tables (createTableHook) guide](./composable-tables.md). +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Upgrades Are Opt-in While Table V9 is a significant upgrade, **you don't have to adopt everything at once**: @@ -84,38 +93,9 @@ The rest of this guide focuses on migrating to the full Table V9 API and taking ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Hook Rename -The hook name has been simplified to be consistent across all TanStack libraries: +The number one change: `useReactTable` is now `useTable`, consistent with hook naming across all TanStack libraries: ```tsx // Table V8 @@ -127,23 +107,6 @@ import { useTable } from '@tanstack/react-table' const table = useTable(options) ``` -### Instance Methods Must Be Called on Their Instance - -In Table V9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```tsx -// Table V8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// Table V9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In Table V9, you must explicitly declare which features your table uses. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -191,8 +154,6 @@ const table = useTable({ }) ``` ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior If you want all features without having to think about it (like Table V8), import `stockFeatures`: @@ -207,94 +168,31 @@ const table = useTable({ }) ``` -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - -### Available Features +#### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Model Factories +### Row Model Factories -Row models are the functions that process your data (filtering, sorting, pagination, etc.). In Table V9, row model factories live on the `tableFeatures({})` call rather than a separate `rowModels` option. The processing function registries (`filterFns`, `sortFns`, `aggregationFns`) are also registered on features. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. +Row models are the functions that process your data (filtering, sorting, pagination, etc.). In Table V9, row model factories live on the `tableFeatures({})` call rather than a separate table option. The processing function registries (`filterFns`, `sortFns`, `aggregationFns`) are also registered on features. This enables better tree-shaking: you only bundle the row model code and filter/sort/aggregation functions you actually register. -### Migration Mapping +Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -308,10 +206,6 @@ Row models are the functions that process your data (filtering, sorting, paginat | `getFacetedMinMaxValues()` | `facetedMinMaxValues` | `createFacetedMinMaxValues()` | | `getFacetedUniqueValues()` | `facetedUniqueValues` | `createFacetedUniqueValues()` | -### Key Change: Row Model Factories and Fns Registries Move to `tableFeatures` - -Row model factories and their processing function registries are now slots on `tableFeatures`. This enables better tree-shaking: you only bundle the row model code and filter/sort/aggregation functions you actually register. - ```tsx import { tableFeatures, @@ -326,7 +220,7 @@ import { const features = tableFeatures({ columnFilteringFeature, rowSortingFeature, - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, rowPaginationFeature, filteredRowModel: createFilteredRowModel(), @@ -345,7 +239,7 @@ const table = useTable({ }) ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -373,6 +267,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In Table V9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```tsx +// Table V8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// Table V9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -599,6 +510,184 @@ When you register an external atom for a slice: --- +## Feature-by-Feature Breaking Changes + +### Sorting + +Sorting-related APIs have been renamed for consistency: + +| Table V8 | Table V9 | +| --------------------------------- | ------------------------ | +| `sortingFn` (column def option) | `sortFn` | +| `column.getSortingFn()` | `column.getSortFn()` | +| `column.getAutoSortingFn()` | `column.getAutoSortFn()` | +| `SortingFn` type | `SortFn` type | +| `SortingFns` interface | `SortFns` interface | +| `sortingFns` (built-in functions) | `sortFns` | + +Update your column definitions: + +```tsx +// Table V8 +const columns = [ + { + accessorKey: 'name', + sortingFn: 'alphanumeric', // or custom function + }, +] + +// Table V9 +const columns = [ + { + accessorKey: 'name', + sortFn: 'alphanumeric', // or custom function + }, +] +``` + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +The `enablePinning` option has also been split into separate options: + +```tsx +// Table V8 +enablePinning: true + +// Table V9 +enableColumnPinning: true +enableRowPinning: true +``` + +### Column Sizing vs. Column Resizing Split + +In Table V8, column sizing and resizing were combined in a single feature. In Table V9, they've been split into separate features for better tree-shaking. + +| Table V8 | Table V9 | +| --------------------------------- | ----------------------------------------------- | +| `ColumnSizing` (combined feature) | `columnSizingFeature` + `columnResizingFeature` | +| `columnSizingInfo` state | `columnResizing` state | +| `setColumnSizingInfo()` | `setColumnResizing()` | +| `onColumnSizingInfoChange` option | `onColumnResizingChange` option | + +If you only need column sizing (fixed widths) without interactive resizing, you can import just `columnSizingFeature`. If you need drag-to-resize functionality, import both: + +```tsx +import { + columnSizingFeature, + columnResizingFeature, +} from '@tanstack/react-table' + +const features = tableFeatures({ + columnSizingFeature, + columnResizingFeature, // Only if you need interactive resizing +}) +``` + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | Table V8 | Table V9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In Table V8 these returned `false` once every row was selected; in Table V9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| Table V8 | Table V9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes The `createColumnHelper` function now requires a `TFeatures` type parameter in addition to `TData`: @@ -940,118 +1029,6 @@ export function PaginationControls() { --- -## Other Breaking Changes - -### Column Pinning Option Split - -The `enablePinning` option has been split into separate options: - -```tsx -// Table V8 -enablePinning: true - -// Table V9 -enableColumnPinning: true -enableRowPinning: true -``` - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Column Sizing vs. Column Resizing Split - -In Table V8, column sizing and resizing were combined in a single feature. In Table V9, they've been split into separate features for better tree-shaking. - -| Table V8 | Table V9 | -| --------------------------------- | ----------------------------------------------- | -| `ColumnSizing` (combined feature) | `columnSizingFeature` + `columnResizingFeature` | -| `columnSizingInfo` state | `columnResizing` state | -| `setColumnSizingInfo()` | `setColumnResizing()` | -| `onColumnSizingInfoChange` option | `onColumnResizingChange` option | - -If you only need column sizing (fixed widths) without interactive resizing, you can import just `columnSizingFeature`. If you need drag-to-resize functionality, import both: - -```tsx -import { - columnSizingFeature, - columnResizingFeature, -} from '@tanstack/react-table' - -const features = tableFeatures({ - columnSizingFeature, - columnResizingFeature, // Only if you need interactive resizing -}) -``` - -### Sorting API Renames - -Sorting-related APIs have been renamed for consistency: - -| Table V8 | Table V9 | -| --------------------------------- | ------------------------ | -| `sortingFn` (column def option) | `sortFn` | -| `column.getSortingFn()` | `column.getSortFn()` | -| `column.getAutoSortingFn()` | `column.getAutoSortFn()` | -| `SortingFn` type | `SortFn` type | -| `SortingFns` interface | `SortFns` interface | -| `sortingFns` (built-in functions) | `sortFns` | - -Update your column definitions: - -```tsx -// Table V8 -const columns = [ - { - accessorKey: 'name', - sortingFn: 'alphanumeric', // or custom function - }, -] - -// Table V9 -const columns = [ - { - accessorKey: 'name', - sortFn: 'alphanumeric', // or custom function - }, -] -``` - -### Row API Changes - -Some row APIs have changed from private to public: - -| Table V8 | Table V9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -If you were accessing this internal API, you can now use it without the underscore prefix. - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | Table V8 | Table V9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In Table V8 these returned `false` once every row was selected; in Table V9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -1192,20 +1169,19 @@ This change improves type safety. If you were passing unusual data types, ensure - [ ] Update import: `useReactTable` → `useTable` - [ ] Define `features` using `tableFeatures()` (or use `stockFeatures`) -- [ ] If aggregating, add `aggregationFeature`; add `columnGroupingFeature` separately only when grouping rows -- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions - [ ] Migrate `get*RowModel()` options to `tableFeatures` slots (e.g. `filteredRowModel: createFilteredRowModel()`) - [ ] Register `filterFns` / `sortFns` / `aggregationFns` registries as slots on `tableFeatures` (row model factories no longer take arguments) -- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot -- [ ] Update TypeScript types to include `TFeatures` generic -- [ ] Update state access: `table.getState()` → `table.store.state` or `table.state` -- [ ] Update `createColumnHelper()` → `createColumnHelper()` -- [ ] Replace `enablePinning` with `enableColumnPinning`/`enableRowPinning` if used +- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`) - [ ] Rename `sortingFn` → `sortFn` in column definitions -- [ ] Split column sizing/resizing: use both `columnSizingFeature` and `columnResizingFeature` if needed +- [ ] Update column pinning to `start`/`end` terminology (`columnPinning.start`, `column.pin('end')`, `getStart*`/`getEnd*` APIs) +- [ ] Replace `enablePinning` with `enableColumnPinning`/`enableRowPinning` if used - [ ] Rename `columnSizingInfo` state → `columnResizing` (and related options) +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions +- [ ] Update state access: `table.getState()` → `table.store.state` or `table.state` +- [ ] Update TypeScript types to include `TFeatures` generic +- [ ] Update `createColumnHelper()` → `createColumnHelper()` - [ ] If you use `TableMeta`/`ColumnMeta` declaration merging, add the `TFeatures` generic to your augmentations (optionally, switch to the per-table `tableMeta`/`columnMeta` feature slots) -- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`) +- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot - [ ] (Optional) Add `table.Subscribe` for render optimizations - [ ] (Optional) Subscribe to individual slices via `table.atoms.` + `useSelector` for the narrowest re-renders - [ ] (Optional) Pass writable atoms via the new `atoms` option to own specific state slices externally diff --git a/docs/framework/react/reference/legacy/interfaces/LegacyRowModelOptions.md b/docs/framework/react/reference/legacy/interfaces/LegacyRowModelOptions.md index cd6bc76c37..08824b63d0 100644 --- a/docs/framework/react/reference/legacy/interfaces/LegacyRowModelOptions.md +++ b/docs/framework/react/reference/legacy/interfaces/LegacyRowModelOptions.md @@ -29,7 +29,7 @@ Additional aggregation functions to apply to the table. #### Deprecated -Use the `groupedRowModel`/`aggregationFns` slots on the `features` option with `createGroupedRowModel()` instead. +Use `rowAggregationFeature` with the `aggregationFns` slot instead. Add `columnGroupingFeature` and `groupedRowModel` only when grouping rows. *** @@ -157,7 +157,7 @@ Returns the grouped row model for the table. #### Deprecated -Use the `groupedRowModel`/`aggregationFns` slots on the `features` option with `createGroupedRowModel()` instead. +Use `columnGroupingFeature` with the `groupedRowModel` slot and `createGroupedRowModel()` instead. Add `rowAggregationFeature` separately when grouped rows aggregate values. *** diff --git a/docs/framework/solid/guide/aggregation.md b/docs/framework/solid/guide/aggregation.md index 31fb2535ab..9d9f36baef 100644 --- a/docs/framework/solid/guide/aggregation.md +++ b/docs/framework/solid/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Solid) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```tsx import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/solid-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```tsx const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/solid/guide/grouping.md b/docs/framework/solid/guide/grouping.md index 2ba2e660f6..adb4a9dbe3 100644 --- a/docs/framework/solid/guide/grouping.md +++ b/docs/framework/solid/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Solid examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. Use getters for reactive inputs such as `data` when passing Solid signals to `createTable`. diff --git a/docs/framework/solid/guide/migrating.md b/docs/framework/solid/guide/migrating.md index f807c57102..0a026217df 100644 --- a/docs/framework/solid/guide/migrating.md +++ b/docs/framework/solid/guide/migrating.md @@ -2,14 +2,14 @@ title: Migrating to TanStack Table V9 (Solid) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Model Factories](#row-model-factories) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See the row models section below for the new shape. ## What's New in TanStack Table V9 @@ -44,6 +44,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - **`tableOptions()`**: Compose reusable table configuration, including features, row models, and default options. - **`createTableHook()`**: Define app-specific table factories with shared features, row models, defaults, and components. +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Upgrades Are Opt-in - You can begin with `stockFeatures`, then audit down to explicit features. @@ -56,35 +61,6 @@ The main migration is replacing `createSolidTable` with `createTable`, then movi ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Entrypoint Rename ```tsx @@ -99,23 +75,6 @@ import { createTable } from '@tanstack/solid-table' const table = createTable(options) ``` -### Instance Methods Must Be Called on Their Instance - -In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```tsx -// v8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// v9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In Table V9, you must explicitly declare which features your table uses. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -167,8 +126,6 @@ const table = createTable({ Keep `features` and column definitions outside reactive component work when they are static. ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior `stockFeatures` is useful when you want a quick v8-like migration path before auditing features. @@ -187,94 +144,31 @@ const table = createTable({ Use it as a migration shortcut, not as the preferred production end state. -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - -### Available Features +#### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Model Factories +### Row Model Factories Row model factories now live inside `tableFeatures` alongside feature objects. Function registries (`filterFns`, `sortFns`, `aggregationFns`) are also passed as slots in `tableFeatures` rather than as arguments to the factory functions. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. -### Migration Mapping +#### Migration Mapping | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -288,7 +182,7 @@ Row model factories now live inside `tableFeatures` alongside feature objects. F | `getFacetedMinMaxValues()` | `facetedMinMaxValues` | `createFacetedMinMaxValues()` | | `getFacetedUniqueValues()` | `facetedUniqueValues` | `createFacetedUniqueValues()` | -### Full Migration Example +#### Full Migration Example ```tsx // v8 @@ -349,7 +243,7 @@ const table = createTable({ }) ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -377,6 +271,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```tsx +// v8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// v9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -513,6 +424,153 @@ Do not provide both `atoms.pagination` and `state.pagination`; the atom owns tha --- +## Feature-by-Feature Breaking Changes + +### Sorting + +Sorting-related APIs have been renamed for consistency: + +| v8 | v9 | +| -------------------- | ----------------- | +| `sortingFn` | `sortFn` | +| `sortingFns` | `sortFns` | +| `getSortingFn()` | `getSortFn()` | +| `getAutoSortingFn()` | `getAutoSortFn()` | +| `SortingFn` | `SortFn` | + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +The `enablePinning` option has also been split into separate options: + +```tsx +// Table V8 +enablePinning: true + +// Table V9 +enableColumnPinning: true +enableRowPinning: true +``` + +### Column Sizing vs. Column Resizing Split + +Column resizing is now a separate feature and state slice. + +```tsx +const features = tableFeatures({ + columnSizingFeature, + columnResizingFeature, +}) +``` + +`columnSizingInfo` became `columnResizing`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. The `setColumnSizingInfo()` API became `setColumnResizing()`. + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | v8 | v9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| Table V8 | Table V9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +If you were accessing this internal API, you can now use it without the underscore prefix. + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes Column helpers and column types now include `TFeatures` first. @@ -617,79 +675,6 @@ See the [Composable Tables Guide](./composable-tables) for complete patterns. --- -## Other Breaking Changes - -### Column Pinning Option Split - -Table-level `enablePinning` split into: - -```tsx -enableColumnPinning: true -enableRowPinning: true -``` - -### Column Sizing vs. Column Resizing Split - -Column resizing is now a separate feature and state slice. - -```tsx -const features = tableFeatures({ - columnSizingFeature, - columnResizingFeature, -}) -``` - -`columnSizingInfo` became `columnResizing`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. The `setColumnSizingInfo()` API became `setColumnResizing()`. - -### Sorting API Renames - -| v8 | v9 | -| -------------------- | ----------------- | -| `sortingFn` | `sortFn` | -| `sortingFns` | `sortFns` | -| `getSortingFn()` | `getSortFn()` | -| `getAutoSortingFn()` | `getAutoSortFn()` | -| `SortingFn` | `SortFn` | - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Row API Changes - -Some row APIs have changed from private to public: - -| Table V8 | Table V9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -If you were accessing this internal API, you can now use it without the underscore prefix. - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | v8 | v9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -800,18 +785,17 @@ type Person = { - [ ] Replace `createSolidTable` with `createTable`. - [ ] Define `features` using `tableFeatures()` (or use `stockFeatures`) -- [ ] If aggregating, add `aggregationFeature`; add `columnGroupingFeature` separately only when grouping rows -- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Move every `get*RowModel` factory into `tableFeatures` as a slot (e.g. `sortedRowModel: createSortedRowModel()`). - [ ] Remove `getCoreRowModel`; the core row model is automatic. - [ ] Move `sortFns`, `filterFns`, and `aggregationFns` into `tableFeatures` as slots (not as factory arguments). -- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. +- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). - [ ] Rename `sortingFn` to `sortFn`. -- [ ] Add `typeof features` to column helpers and table types. - [ ] Use getters for reactive `data` and controlled `state` slices. - [ ] Replace `table.getState()` reads with `table.atoms..get()` or `table.store.get()`. - [ ] Replace top-level `onStateChange` with per-slice handlers or external atoms. -- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). +- [ ] Add `typeof features` to column helpers and table types. +- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. - [ ] Replace `flexRender(...)` calls with ``. - [ ] Audit `stockFeatures` before production. diff --git a/docs/framework/svelte/guide/aggregation.md b/docs/framework/svelte/guide/aggregation.md index 81e09dfe39..09a07ac282 100644 --- a/docs/framework/svelte/guide/aggregation.md +++ b/docs/framework/svelte/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Svelte) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/svelte-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/svelte/guide/grouping.md b/docs/framework/svelte/guide/grouping.md index fa972c1b1f..e43eafa0ad 100644 --- a/docs/framework/svelte/guide/grouping.md +++ b/docs/framework/svelte/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Svelte examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. Use getters for reactive inputs such as `data` when passing Svelte state to `createTable`. diff --git a/docs/framework/svelte/guide/migrating.md b/docs/framework/svelte/guide/migrating.md index 48c9fb769d..fc94c314ad 100644 --- a/docs/framework/svelte/guide/migrating.md +++ b/docs/framework/svelte/guide/migrating.md @@ -2,14 +2,14 @@ title: Migrating to TanStack Table V9 (Svelte) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Models](#row-models) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See the row models section below for the new shape. ## What's New in TanStack Table V9 @@ -44,6 +44,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - **`tableOptions()`**: Compose reusable table configuration, including features, row models, and default options. - **`createTableHook()`**: Define shared Svelte table factories with pre-bound features, row models, defaults, and registered components. +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Table Logic Is Still Familiar - Column definitions keep the same basic `accessorKey`, `accessorFn`, `header`, `cell`, and `footer` shapes. @@ -69,35 +74,6 @@ There is no Svelte 3/4 compatibility shim for the v9 Svelte adapter. ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Entrypoint Rename ```ts @@ -112,23 +88,6 @@ import { createTable } from '@tanstack/svelte-table' const table = createTable(options) ``` -### Instance Methods Must Be Called on Their Instance - -In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```ts -// v8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// v9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In Table V9, you must explicitly declare which features your table uses. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -178,8 +137,6 @@ const table = createTable({ In Svelte 5, pass reactive values like `data` through getters so table options read the current rune value. ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior `stockFeatures` is useful for early migration when you have not audited feature usage yet. @@ -198,94 +155,31 @@ const table = createTable({ Use it as a temporary migration shortcut. Explicit feature registration is the production target. -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - -### Available Features +#### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Models +### Row Models Row model factories now live as slots directly inside `tableFeatures({...})`. The `rowModels` option no longer exists. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. -### Migration Mapping +#### Migration Mapping | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -301,7 +195,7 @@ Row model factories now live as slots directly inside `tableFeatures({...})`. Th Function registries move to slots too: pass `filterFns`, `sortFns`, and `aggregationFns` directly to `tableFeatures` instead of as factory arguments. -### Full Migration Example +#### Full Migration Example ```svelte ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -396,6 +290,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```ts +// v8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// v9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -567,6 +478,145 @@ Do not provide both `atoms.pagination` and `state.pagination`; the atom owns tha --- +## Feature-by-Feature Breaking Changes + +### Sorting + +| v8 | v9 | +| -------------------- | ----------------- | +| `sortingFn` | `sortFn` | +| `sortingFns` | `sortFns` | +| `getSortingFn()` | `getSortFn()` | +| `getAutoSortingFn()` | `getAutoSortFn()` | +| `SortingFn` | `SortFn` | + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +Table-level `enablePinning` split into: + +```ts +enableColumnPinning: true +enableRowPinning: true +``` + +### Column Sizing vs. Column Resizing Split + +Column resizing now has its own feature and state slice. + +```ts +const features = tableFeatures({ + columnSizingFeature, + columnResizingFeature, +}) +``` + +`columnSizingInfo` became `columnResizing`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | v8 | v9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| Table V8 | Table V9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes Column helpers and column types now include `TFeatures` first. @@ -695,79 +745,6 @@ See the [Composable Tables Guide](./composable-tables) for full patterns. --- -## Other Breaking Changes - -### Column Pinning Option Split - -Table-level `enablePinning` split into: - -```ts -enableColumnPinning: true -enableRowPinning: true -``` - -### Column Sizing vs. Column Resizing Split - -Column resizing now has its own feature and state slice. - -```ts -const features = tableFeatures({ - columnSizingFeature, - columnResizingFeature, -}) -``` - -`columnSizingInfo` became `columnResizing`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. - -### Sorting API Renames - -| v8 | v9 | -| -------------------- | ----------------- | -| `sortingFn` | `sortFn` | -| `sortingFns` | `sortFns` | -| `getSortingFn()` | `getSortFn()` | -| `getAutoSortingFn()` | `getAutoSortFn()` | -| `SortingFn` | `SortFn` | - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Row API Changes - -Some row APIs have changed from private to public: - -| Table V8 | Table V9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -If you were accessing this internal API, you can now use it without the underscore prefix. - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | v8 | v9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -878,20 +855,19 @@ type Person = { - [ ] Upgrade the app to Svelte 5. - [ ] Replace `createSvelteTable` with `createTable`. -- [ ] Replace Svelte 3/4 writable-store table patterns with runes and getters. - [ ] Define `features` using `tableFeatures()` (or use `stockFeatures`) -- [ ] If aggregating, add `aggregationFeature`; add `columnGroupingFeature` separately only when grouping rows -- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Move row model factories into `tableFeatures({...})` as slots (e.g. `filteredRowModel: createFilteredRowModel()`). - [ ] Remove `getCoreRowModel`; the core row model is automatic. - [ ] Pass `sortFns`, `filterFns`, and `aggregationFns` as slots in `tableFeatures({...})` instead of as factory arguments (row model factories no longer take arguments). -- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. +- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). - [ ] Rename `sortingFn` to `sortFn`. -- [ ] Add `typeof features` to column helpers and types. +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. +- [ ] Replace Svelte 3/4 writable-store table patterns with runes and getters. - [ ] Pass reactive `data` and controlled `state` slices through getters. - [ ] Replace `table.getState()` reads with `table.state`, `table.store.state`, `table.atoms..get()`, or `subscribeTable`. - [ ] Replace `onStateChange` with per-slice callbacks or external atoms. -- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). +- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. +- [ ] Add `typeof features` to column helpers and types. - [ ] Replace `flexRender(...)` and `` table rendering with ``. - [ ] Use `renderComponent` or `renderSnippet` for Svelte component/snippet cells. - [ ] Audit `stockFeatures` before production. diff --git a/docs/framework/vanilla/guide/aggregation.md b/docs/framework/vanilla/guide/aggregation.md index c6ed345704..8020ddc5a7 100644 --- a/docs/framework/vanilla/guide/aggregation.md +++ b/docs/framework/vanilla/guide/aggregation.md @@ -6,7 +6,7 @@ title: Aggregation (Vanilla) Guide - [Aggregation](../examples/aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -20,7 +20,7 @@ directly to a column does not require a registry entry. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -30,7 +30,7 @@ import { } from '@tanstack/table-core' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -105,7 +105,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/vue/guide/aggregation.md b/docs/framework/vue/guide/aggregation.md index da20bc3686..209fe417d4 100644 --- a/docs/framework/vue/guide/aggregation.md +++ b/docs/framework/vue/guide/aggregation.md @@ -7,7 +7,7 @@ title: Aggregation (Vue) Guide - [Aggregation](../examples/aggregation) - [Grouped Aggregation](../examples/grouped-aggregation) -Aggregation is independent from column grouping. Register `aggregationFeature` +Aggregation is independent from column grouping. Register `rowAggregationFeature` whenever columns calculate totals or aggregated values. Add `columnGroupingFeature` separately only when the table also groups rows. @@ -21,7 +21,7 @@ directly to a column does not require a registry entry. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -31,7 +31,7 @@ import { } from '@tanstack/vue-table' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { count: aggregationFn_count, extent: aggregationFn_extent, @@ -106,7 +106,7 @@ should produce grouped values. ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, diff --git a/docs/framework/vue/guide/grouping.md b/docs/framework/vue/guide/grouping.md index f01f92118e..5223ca203e 100644 --- a/docs/framework/vue/guide/grouping.md +++ b/docs/framework/vue/guide/grouping.md @@ -8,7 +8,7 @@ Want to skip to the implementation? Check out these Vue examples: - [Grouping](../examples/grouping) -> **Note:** `columnGroupingFeature` and `aggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. +> **Note:** `columnGroupingFeature` and `rowAggregationFeature` are now separate features. Register either one independently, or register both when grouped rows should also calculate aggregate values. See the [Aggregation Guide](./aggregation) for aggregation setup. Vue refs can be passed directly where the adapter expects reactive table options. diff --git a/docs/framework/vue/guide/migrating.md b/docs/framework/vue/guide/migrating.md index cc5956966e..f9f1cb35c9 100644 --- a/docs/framework/vue/guide/migrating.md +++ b/docs/framework/vue/guide/migrating.md @@ -2,14 +2,20 @@ title: Migrating to TanStack Table V9 (Vue) --- -> [!IMPORTANT] -> `v9.0.0-beta.48` and `v9.0.0-beta.49` introduces breaking aggregation changes. `columnGroupingFeature` no longer provides aggregation options or APIs. Tables that group rows and calculate aggregate values must now register both `columnGroupingFeature` and `aggregationFeature`. Grouping-only tables can register only `columnGroupingFeature`, while grand totals or other aggregation without grouping can register only `aggregationFeature`. `stockFeatures` already contains both. If you use an explicit feature list, add `aggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation definitions, row-depth selection, and the `getAggregationValue` signature also changed; see [Aggregation Feature Split](#aggregation-feature-split), the [Grouping Guide](./grouping), and the [Aggregation Guide](./aggregation). +> [!NOTE] +> `v9.0.0-beta.48`/`beta.49` split aggregation out of `columnGroupingFeature` into a new `rowAggregationFeature` (`stockFeatures` includes both). If you declare features explicitly, add `rowAggregationFeature` anywhere you use `aggregationFns`, `aggregationFn`, `aggregatedCell`, `cell.getIsAggregated()`, or `column.getAggregationValue()`. Aggregation function definitions, row-depth selection, and the `getAggregationValue` signature also changed. See [Grouping and Aggregation](#grouping-and-aggregation) below. + +--- > [!NOTE] -> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology. These are logical positions: in LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. If you migrated on an earlier beta, update `columnPinning.left` to `columnPinning.start`, `columnPinning.right` to `columnPinning.end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*` / `getRight*` table and row APIs to `getStart*` / `getEnd*`. See the [Column Pinning](#column-pinning) section below for the full mapping. +> `v9.0.0-beta.38` renames column pinning from physical `left`/`right` terminology to logical `start`/`end` terminology (in LTR layouts `start` usually means left; in RTL it usually means right). Update `columnPinning.left`/`right` to `columnPinning.start`/`end`, `column.pin('left' | 'right')` to `column.pin('start' | 'end')`, and `getLeft*`/`getRight*` APIs to `getStart*`/`getEnd*`. See [Column Pinning](#column-pinning) for the full mapping. + +--- > [!NOTE] -> `v9.0.0-beta.10` introduces a breaking change in how row models are defined in order to bring increased type-safety features. Row model factories and function registries now live as slots on the `features` object instead of a separate `rowModels` option, and the factories no longer take arguments. If you migrated on an earlier beta, see the [Row Model Factories](#row-model-factories) section below for the new shape. +> `v9.0.0-beta.10` moves row model factories and the `filterFns`/`sortFns`/`aggregationFns` registries onto the `features` object (the separate `rowModels` option is gone, and the factories no longer take arguments). See [Row Model Factories](#row-model-factories) for the new shape. + +--- ## What's New in TanStack Table V9 @@ -44,6 +50,11 @@ TanStack Table V9 is a major release with significant internal architectural imp - **`tableOptions()`**: Compose reusable table configuration, including features, row models, and default options. - **`createTableHook()`**: Define shared Vue table factories with pre-bound features, row models, defaults, and components. +### 6. Refreshed Feature APIs + +- **More capable features**: Aggregation, Row Selection, Column Pinning, and Column Resizing have all been made more feature rich (multiple aggregation definitions per column, Shift range selection, logical `start`/`end` pinning, and more). +- **New core APIs**: New table and row APIs (like `table.getMaxSubRowDepth()`, `row.getDisplayIndex()`) round out the core feature set. + ### The Good News: Most Table Logic Is Still Familiar - Column definitions keep the same basic `accessorKey`, `accessorFn`, `header`, `cell`, and `footer` shapes. @@ -56,35 +67,6 @@ The main migration is replacing `useVueTable` with `useTable`, then moving featu ## Core Breaking Changes -### Column Pinning - -`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. - -| Before beta.38 | beta.38+ | -| ------------------------------------ | ------------------------------------ | -| `columnPinning.left` | `columnPinning.start` | -| `columnPinning.right` | `columnPinning.end` | -| `column.pin('left')` | `column.pin('start')` | -| `column.pin('right')` | `column.pin('end')` | -| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | -| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | -| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | -| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | -| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | -| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | -| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | -| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | -| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | -| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | -| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | -| `table.getRightTotalSize()` | `table.getEndTotalSize()` | -| `column.getStart('left')` | `column.getStart('start')` | -| `column.getAfter('right')` | `column.getAfter('end')` | -| `column.getIndex('left')` | `column.getIndex('start')` | -| `column.getIndex('right')` | `column.getIndex('end')` | - -This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. - ### Hook Rename ```ts @@ -99,23 +81,6 @@ import { useTable } from '@tanstack/vue-table' const table = useTable(options) ``` -### Instance Methods Must Be Called on Their Instance - -In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. - -```ts -// v8 - worked because getValue closed over the row object -const { getValue } = row -const value = getValue('name') - -// v9 - call the method on the instance -const value = row.getValue('name') -``` - -This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. - -Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. - ### New Required `features` Table Option In Table V9, you must explicitly declare which features your table uses. Features, Row Models, and Row Model processing "Fns" are defined on the new `features` table option. @@ -163,8 +128,6 @@ const table = useTable({ `data` can be a raw array, a `ref`, a `computed`, or a getter. The adapter unwraps reactive option values and keeps the table synced. ---- - #### Shortcut: Use `stockFeatures` for Table V8-like Behavior `stockFeatures` is useful for early migration before you audit feature usage. @@ -181,94 +144,31 @@ const table = useTable({ Use it as a temporary migration shortcut. Explicit feature registration is the production target. -### Aggregation Feature Split - -Aggregation is now independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `aggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. Root totals can use aggregation without grouping. - -```ts -const features = tableFeatures({ - aggregationFeature, - columnGroupingFeature, // only for grouped rows - groupedRowModel: createGroupedRowModel(), - aggregationFns: { sum: aggregationFn_sum }, -}) -``` - -Custom aggregation callables have changed to context-based definitions: - -```ts -// Table V8/earlier V9 betas -const total = (columnId, leafRows, childRows) => - leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) - -// Current V9 -const total = constructAggregationFn({ - aggregate: ({ rows, getValue }) => - rows.reduce((sum, row) => sum + Number(getValue(row)), 0), -}) -``` - -Aggregation row selection is now depth-based and shared by every definition on -a column. `maxAggregationDepth` defaults to `0` (the supplied root rows); use -`1` for direct sub-rows or `Infinity` for terminal rows. An explicit -`column.getAggregationValue({ rows, maxDepth })` call can override the column -default. - -`getAggregationValue` now has one options-object signature. Calls without -arguments are unchanged, but positional row and depth arguments must be moved -into the object: - -```ts -// Table V8/earlier V9 betas -column.getAggregationValue(rows, maxDepth) - -// Current V9 -column.getAggregationValue({ rows, maxDepth }) -``` - -All built-in definitions on a column now consume the same depth-selected -`context.rows` frontier. This replaces the old per-function choice between -`childRows` and `leafRows`. The default depth `0` preserves direct-child -grouped aggregation; set `maxAggregationDepth: Infinity` to aggregate terminal -rows. Custom definitions can still inspect grouped `context.subRows`, and -`merge` receives matching `subRowResults` for nested groups. - -`table.getMaxSubRowDepth()` returns the deepest structural depth in the core -row model. For example, use `Math.max(0, table.getMaxSubRowDepth() - 1)` as -`maxDepth` to target one level before the maximum structural depth; shorter -branches still contribute their deepest available row. Default no-row calls -are cached; calls with `options.rows` are recomputed because the caller owns -that array. - -`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions. A single `aggregationFn` still returns a scalar; an array returns an object keyed by function name or descriptor `id`. The old callable `AggregationFn` and `CreatedAggregationFn` types are replaced by `AggregationFnDef`. - ### Available Features | Feature | Import Name | | ----------------- | ------------------------- | +| Column Faceting | `columnFacetingFeature` | | Column Filtering | `columnFilteringFeature` | +| Column Grouping | `columnGroupingFeature` | +| Column Ordering | `columnOrderingFeature` | +| Column Pinning | `columnPinningFeature` | +| Column Resizing | `columnResizingFeature` | +| Column Sizing | `columnSizingFeature` | +| Column Visibility | `columnVisibilityFeature` | | Global Filtering | `globalFilteringFeature` | -| Row Sorting | `rowSortingFeature` | -| Row Pagination | `rowPaginationFeature` | -| Row Selection | `rowSelectionFeature` | +| Row Aggregation | `rowAggregationFeature` | | Row Expanding | `rowExpandingFeature` | +| Row Pagination | `rowPaginationFeature` | | Row Pinning | `rowPinningFeature` | -| Column Pinning | `columnPinningFeature` | -| Column Visibility | `columnVisibilityFeature` | -| Column Ordering | `columnOrderingFeature` | -| Column Sizing | `columnSizingFeature` | -| Column Resizing | `columnResizingFeature` | -| Column Grouping | `columnGroupingFeature` | -| Aggregation | `aggregationFeature` | -| Column Faceting | `columnFacetingFeature` | - ---- +| Row Selection | `rowSelectionFeature` | +| Row Sorting | `rowSortingFeature` | -## Row Model Factories +### Row Model Factories Row model factories now live on the `features` object (passed to `tableFeatures`). The `rowModels` option has been removed. Function registries (`filterFns`, `sortFns`, `aggregationFns`) are also slots on the features object. Row model slots are type-checked, so each row model must be specified after its associated feature in the same `tableFeatures` call. -### Migration Mapping +#### Migration Mapping | Table V8 Option | Table V9 `tableFeatures` Slot | Table V9 Factory Function | | -------------------------- | ----------------------------- | ----------------------------- | @@ -282,7 +182,7 @@ Row model factories now live on the `features` object (passed to `tableFeatures` | `getFacetedMinMaxValues()` | `facetedMinMaxValues` | `createFacetedMinMaxValues()` | | `getFacetedUniqueValues()` | `facetedUniqueValues` | `createFacetedUniqueValues()` | -### Full Migration Example +#### Full Migration Example ```ts // v8 @@ -339,7 +239,7 @@ const table = useTable({ }) ``` -### Prefer Individual Fn Imports Over Full Registries +#### Prefer Individual Fn Imports Over Full Registries The `filterFns`, `sortFns`, and `aggregationFns` registry exports are now deprecated in favor of importing individual `filterFn_*`, `sortFn_*`, and `aggregationFn_*` functions and registering only the ones you use (or passing functions directly in column definitions with no registration at all). The full registries still work, but spreading them puts every built-in function in your bundle. Keep in mind that string names, including the default `'auto'`, only resolve functions you have registered. @@ -367,6 +267,23 @@ const features = tableFeatures({ }) ``` +### Instance Methods Must Be Called on Their Instance + +In v9, methods on rows, cells, columns, headers, and similar table objects are shared on the object's prototype instead of being created as arrow functions on each object. This improves memory usage, but it means destructuring those methods loses the `this` context they need to operate on the instance. + +```ts +// v8 - worked because getValue closed over the row object +const { getValue } = row +const value = getValue('name') + +// v9 - call the method on the instance +const value = row.getValue('name') +``` + +This applies to row, cell, column, header, and related instance APIs, but not to the table instance itself. Audit code that destructures methods from table objects or passes them around as bare callbacks. Prefer calling them through the original object, for example `row.getValue('name')`, `cell.getContext()`, `column.getCanSort()`, or `header.getContext()`. + +Because these methods now live on the prototype, they also do not appear as own properties in `Object.keys(instance)`, object spread, or `JSON.stringify`. A shallow clone like `{ ...row }` copies row data but does not copy row methods. The methods are still callable normally because JavaScript looks them up through the prototype chain. + --- ## State Management Changes @@ -543,6 +460,145 @@ Do not provide both `atoms.pagination` and `state.pagination`; the atom owns tha --- +## Feature-by-Feature Breaking Changes + +### Sorting + +| v8 | v9 | +| -------------------- | ----------------- | +| `sortingFn` | `sortFn` | +| `sortingFns` | `sortFns` | +| `getSortingFn()` | `getSortFn()` | +| `getAutoSortingFn()` | `getAutoSortFn()` | +| `SortingFn` | `SortFn` | + +### Column Pinning + +`v9.0.0-beta.38` changes column pinning to use logical `start`/`end` terminology instead of physical `left`/`right` terminology. In LTR languages/layouts, `start` usually corresponds to left and `end` to right; in RTL languages/layouts, `start` usually corresponds to right and `end` to left. There are no deprecated aliases in beta.38. + +| Before beta.38 | beta.38+ | +| ------------------------------------ | ------------------------------------ | +| `columnPinning.left` | `columnPinning.start` | +| `columnPinning.right` | `columnPinning.end` | +| `column.pin('left')` | `column.pin('start')` | +| `column.pin('right')` | `column.pin('end')` | +| `column.getIsPinned() === 'left'` | `column.getIsPinned() === 'start'` | +| `column.getIsPinned() === 'right'` | `column.getIsPinned() === 'end'` | +| `row.getLeftVisibleCells()` | `row.getStartVisibleCells()` | +| `row.getRightVisibleCells()` | `row.getEndVisibleCells()` | +| `table.getLeftHeaderGroups()` | `table.getStartHeaderGroups()` | +| `table.getRightHeaderGroups()` | `table.getEndHeaderGroups()` | +| `table.getLeftLeafColumns()` | `table.getStartLeafColumns()` | +| `table.getRightLeafColumns()` | `table.getEndLeafColumns()` | +| `table.getLeftVisibleLeafColumns()` | `table.getStartVisibleLeafColumns()` | +| `table.getRightVisibleLeafColumns()` | `table.getEndVisibleLeafColumns()` | +| `table.getLeftTotalSize()` | `table.getStartTotalSize()` | +| `table.getRightTotalSize()` | `table.getEndTotalSize()` | +| `column.getStart('left')` | `column.getStart('start')` | +| `column.getAfter('right')` | `column.getAfter('end')` | +| `column.getIndex('left')` | `column.getIndex('start')` | +| `column.getIndex('right')` | `column.getIndex('end')` | + +This rename is about logical table regions, not automatic DOM direction handling. For sticky column pinning, prefer CSS logical properties like `insetInlineStart` and `insetInlineEnd`. The `columnResizeDirection` table option is unchanged. + +The table-level `enablePinning` option has also been split into separate options: + +```ts +enableColumnPinning: true +enableRowPinning: true +``` + +### Column Sizing vs. Column Resizing Split + +Column resizing now has its own feature and state slice. + +```ts +const features = tableFeatures({ + columnSizingFeature, + columnResizingFeature, +}) +``` + +`columnSizingInfo` became `columnResizing`, `setColumnSizingInfo()` became `setColumnResizing()`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. + +### Grouping and Aggregation + +Aggregation is now its own feature, independent from column grouping. `stockFeatures` still includes both, so tables using it need no feature-registration change. If you declare features explicitly, add `rowAggregationFeature` whenever columns use `aggregationFn`, `aggregatedCell`, `getAggregationValue`, or `cell.getIsAggregated`. Add `columnGroupingFeature` and `groupedRowModel` only when you also group rows. + +```ts +const features = tableFeatures({ + rowAggregationFeature, + columnGroupingFeature, // only for grouped rows + groupedRowModel: createGroupedRowModel(), + aggregationFns: { sum: aggregationFn_sum }, +}) +``` + +Custom aggregation callables have changed to context-based definitions: + +```ts +// Table V8/earlier V9 betas +const total = (columnId, leafRows, childRows) => + leafRows.reduce((sum, row) => sum + row.getValue(columnId), 0) + +// Current V9 +const total = constructAggregationFn({ + aggregate: ({ rows, getValue }) => + rows.reduce((sum, row) => sum + Number(getValue(row)), 0), +}) +``` + +The old per-function choice between `childRows` and `leafRows` is replaced by a single depth-selected `context.rows`, controlled by the `maxAggregationDepth` column option. The default (`0`) preserves V8's direct-child grouped aggregation; use `Infinity` to aggregate terminal leaf rows. + +`column.getAggregationValue()` now takes a single options object instead of positional arguments: + +```ts +// Table V8/earlier V9 betas +column.getAggregationValue(rows, maxDepth) + +// Current V9 +column.getAggregationValue({ rows, maxDepth }) +``` + +`column.getAggregationFn()` is now `column.getAggregationFns()` because a column can run multiple definitions, and the old callable `AggregationFn`/`CreatedAggregationFn` types are replaced by `AggregationFnDef`. + +See the [Grouping Guide](./grouping) and the [Aggregation Guide](./aggregation) for full documentation of the new capabilities. + +### Row Selection + +> [!WARNING] +> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. +> +> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). + +The "some rows selected" checks were simplified to mean "at least one row is selected": + +| API | v8 | v9 | +| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | +| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | +| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | + +In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: + +`getIsSomeRowsSelected() && !getIsAllRowsSelected()` + +### Row and Internal API Changes + +Some row APIs have changed from private to public: + +| Table V8 | Table V9 | +| ---------------------------------------- | -------------------------------------- | +| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | + +All other internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: + +- Removed: `table._getPinnedRows()` +- Removed: `table._getFacetedRowModel()` +- Removed: `table._getFacetedMinMaxValues()` +- Removed: `table._getFacetedUniqueValues()` + +--- + ## Column Helper Changes Column helpers and column types now include `TFeatures` first. @@ -637,79 +693,6 @@ See the [Composable Tables Guide](./composable-tables) for full patterns. --- -## Other Breaking Changes - -### Column Pinning Option Split - -Table-level `enablePinning` split into: - -```ts -enableColumnPinning: true -enableRowPinning: true -``` - -### Column Sizing vs. Column Resizing Split - -Column resizing now has its own feature and state slice. - -```ts -const features = tableFeatures({ - columnSizingFeature, - columnResizingFeature, -}) -``` - -`columnSizingInfo` became `columnResizing`, `setColumnSizingInfo()` became `setColumnResizing()`, and `onColumnSizingInfoChange` became `onColumnResizingChange`. - -### Sorting API Renames - -| v8 | v9 | -| -------------------- | ----------------- | -| `sortingFn` | `sortFn` | -| `sortingFns` | `sortFns` | -| `getSortingFn()` | `getSortFn()` | -| `getAutoSortingFn()` | `getAutoSortFn()` | -| `SortingFn` | `SortFn` | - -### Removed Internal APIs - -All internal APIs prefixed with `_` have been removed. If you were using any of these, use their public equivalents: - -- Removed: `table._getPinnedRows()` -- Removed: `table._getFacetedRowModel()` -- Removed: `table._getFacetedMinMaxValues()` -- Removed: `table._getFacetedUniqueValues()` - -### Row API Changes - -Some row APIs have changed from private to public: - -| Table V8 | Table V9 | -| ---------------------------------------- | -------------------------------------- | -| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) | - -If you were accessing this internal API, you can now use it without the underscore prefix. - -### Row Selection API Changes - -> [!WARNING] -> **Minor breaking change:** `row.getToggleSelectedHandler()` now enables inclusive Shift range selection by default when `rowSelectionFeature` is enabled. Existing checkboxes or rows wired through this handler establish an anchor on an ordinary interaction and select or deselect the current display-order range on a Shift interaction. Direct `row.toggleSelected()` calls are unchanged. -> -> Set `enableRowRangeSelection: false` to preserve the previous non-range handler behavior. The handler must receive an event that exposes Shift directly or through `nativeEvent`; see [Shift Range Selection](./row-selection.md#shift-range-selection). - -The "some rows selected" checks were simplified to mean "at least one row is selected": - -| API | v8 | v9 | -| ----------------------------------- | --------------------------------------------------- | --------------------------------------------- | -| `table.getIsSomeRowsSelected()` | `true` when some but not all rows are selected | `true` when at least one row is selected | -| `table.getIsSomePageRowsSelected()` | `true` when some but not all page rows are selected | `true` when at least one page row is selected | - -In v8 these returned `false` once every row was selected; in v9 they stay `true`. If you use them to drive an indeterminate "select all" checkbox, gate the indeterminate state on the matching all-selected check so it clears at full selection: - -`getIsSomeRowsSelected() && !getIsAllRowsSelected()` - ---- - ## TypeScript Changes Summary ### Type Generics @@ -820,18 +803,17 @@ type Person = { - [ ] Replace `useVueTable` with `useTable`. - [ ] Define `features` using `tableFeatures()` (or use `stockFeatures`) -- [ ] If aggregating, add `aggregationFeature`; add `columnGroupingFeature` separately only when grouping rows -- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. - [ ] Move row model factories into `tableFeatures` as slots (e.g. `filteredRowModel: createFilteredRowModel()`). - [ ] Remove `getCoreRowModel`; the core row model is automatic. - [ ] Move `sortFns`, `filterFns`, and `aggregationFns` into `tableFeatures` as slots (row model factories no longer take arguments). -- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. -- [ ] Rename `sortingFn` to `sortFn`. -- [ ] Add `typeof features` to column helpers and types. +- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). - [ ] Replace `table.getState()` reads with `table.atoms..get()` or `table.store.get()`. - [ ] Use Vue getters for controlled `state` slices. - [ ] Replace top-level `onStateChange` with per-slice callbacks or external atoms. -- [ ] Replace destructured row/cell/column/header methods with calls on the instance (for example, `row.getValue('name')`). +- [ ] Rename `sortingFn` to `sortFn`. +- [ ] Convert custom aggregation callables to `constructAggregationFn({ aggregate, merge? })` definitions. +- [ ] Add `typeof features` to column helpers and types. +- [ ] Replace `declare module` augmentation of `FilterFns`/`SortFns`/`AggregationFns` with registry-slot registration, and `FilterMeta` augmentation with the `filterMeta` slot. - [ ] Prefer ``, `:header`, and `:footer` shorthand rendering. - [ ] Audit `stockFeatures` before production. diff --git a/docs/guide/aggregation.md b/docs/guide/aggregation.md index 0aa5539024..3ae08f4917 100644 --- a/docs/guide/aggregation.md +++ b/docs/guide/aggregation.md @@ -9,20 +9,20 @@ grouping when grouped rows should also expose aggregate values. ## Setup -Register `aggregationFeature` and the named definitions referenced by your +Register `rowAggregationFeature` and the named definitions referenced by your columns. Registering individual built-ins keeps unused functions out of the bundle. ```ts import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_sum, tableFeatures, } from '@tanstack/table-core' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, aggregationFns: { mean: aggregationFn_mean, sum: aggregationFn_sum, @@ -32,14 +32,14 @@ const features = tableFeatures({ The full `aggregationFns` registry remains available for compatibility, but it bundles every built-in. Tables using `stockFeatures` already include -`aggregationFeature`; they still need the definitions that named column options +`rowAggregationFeature`; they still need the definitions that named column options should resolve. To combine aggregation with grouped rows, register both independent features: ```ts const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, groupedRowModel: createGroupedRowModel(), aggregationFns: { sum: aggregationFn_sum }, @@ -202,7 +202,7 @@ const amountColumn = columnHelper.accessor('amount', { ``` Use `cell.getIsAggregated()` to distinguish these cells. Grouping-only tables -do not expose this method; it belongs to `aggregationFeature`. +do not expose this method; it belongs to `rowAggregationFeature`. ## Providing Server or External Values diff --git a/docs/guide/row-models.md b/docs/guide/row-models.md index abc0c5c5b0..190b9158fa 100644 --- a/docs/guide/row-models.md +++ b/docs/guide/row-models.md @@ -138,7 +138,7 @@ For normal rendering use cases, you will probably only need to use the `table.ge - `getFilteredRowModel` - returns a row model that accounts for column filtering and global filtering. - `getPreFilteredRowModel` - returns a row model before column filtering and global filtering are applied. -- `getGroupedRowModel` - returns a row model that applies grouping and creates sub-rows. When `aggregationFeature` is also registered, configured aggregate values are computed for those grouped rows. +- `getGroupedRowModel` - returns a row model that applies grouping and creates sub-rows. When `rowAggregationFeature` is also registered, configured aggregate values are computed for those grouped rows. - `getPreGroupedRowModel` - returns the row model before grouping. Its root rows are the default row set used by `column.getAggregationValue()` for grand totals; `maxAggregationDepth` can select a deeper frontier. - `getSortedRowModel` - returns a row model that has had sorting applied to it. diff --git a/docs/guide/worker-row-models.md b/docs/guide/worker-row-models.md index 9d01557a47..2d08998b92 100644 --- a/docs/guide/worker-row-models.md +++ b/docs/guide/worker-row-models.md @@ -106,7 +106,7 @@ Offloaded stages must form a contiguous prefix of the pipeline (filtered, then g - **Flat source data only** for now (no `getSubRows`). - **Table options that affect processing** (a custom `globalFilterFn`, for example) must be passed to `initTableWorker` in the shared config, not just to your table hook. -- **Grouping aggregates** require both `aggregationFeature` and `columnGroupingFeature` in the shared feature set. They are computed eagerly in the worker, but only for columns with an explicit `aggregationFn` or `aggregatedCell`; group-row `getValue()` for other columns returns `undefined`. +- **Grouping aggregates** require both `rowAggregationFeature` and `columnGroupingFeature` in the shared feature set. They are computed eagerly in the worker, but only for columns with an explicit `aggregationFn` or `aggregatedCell`; group-row `getValue()` for other columns returns `undefined`. - **Multiple aggregation results** are transferred as keyed objects. Custom aggregation results must be supported by the browser's structured-clone algorithm. - **Grand totals and caller-selected row totals** from `column.getAggregationValue(options?)` run on the main thread. The worker currently offloads row-model stages, not arbitrary aggregation requests. - **SSR** works out of the box: on the server (no `Worker` global) the table renders unprocessed rows, and the client takes over after hydration. diff --git a/docs/reference/index/functions/constructAggregationFn.md b/docs/reference/index/functions/constructAggregationFn.md index ce349904f8..12c9bea50b 100644 --- a/docs/reference/index/functions/constructAggregationFn.md +++ b/docs/reference/index/functions/constructAggregationFn.md @@ -9,7 +9,7 @@ title: constructAggregationFn function constructAggregationFn(definition): AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:83](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L83) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:83](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L83) Creates a typed context-based aggregation definition for a column or aggregation-function registry. diff --git a/docs/reference/index/functions/createGroupedRowModel.md b/docs/reference/index/functions/createGroupedRowModel.md index fddb2904ac..eaad73d106 100644 --- a/docs/reference/index/functions/createGroupedRowModel.md +++ b/docs/reference/index/functions/createGroupedRowModel.md @@ -15,7 +15,7 @@ Creates a memoized grouped row model factory. The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline. -When aggregationFeature is also registered, grouped rows use its shared +When rowAggregationFeature is also registered, grouped rows use its shared executor for non-group values. Grouping remains useful without aggregation. ## Type Parameters diff --git a/docs/reference/index/functions/makeStateUpdater.md b/docs/reference/index/functions/makeStateUpdater.md index ad28b1308e..f7f327f865 100644 --- a/docs/reference/index/functions/makeStateUpdater.md +++ b/docs/reference/index/functions/makeStateUpdater.md @@ -57,7 +57,7 @@ The updater writes through the table base atom for the slice and supports both v #### updater -[`Updater`](../type-aliases/Updater.md)\<`TableState_WorkerRowModels` & [`TableState_ColumnGrouping`](../interfaces/TableState_ColumnGrouping.md) & [`TableState_ColumnPinning`](../interfaces/TableState_ColumnPinning.md) & [`TableState_ColumnSizing`](../interfaces/TableState_ColumnSizing.md) & [`TableState_ColumnResizing`](../interfaces/TableState_ColumnResizing.md) & [`TableState_GlobalFiltering`](../interfaces/TableState_GlobalFiltering.md) & [`TableState_ColumnVisibility`](../interfaces/TableState_ColumnVisibility.md) & [`TableState_RowExpanding`](../interfaces/TableState_RowExpanding.md) & [`TableState_RowPinning`](../interfaces/TableState_RowPinning.md) & [`TableState_RowSelection`](../interfaces/TableState_RowSelection.md) & [`TableState_ColumnFiltering`](../interfaces/TableState_ColumnFiltering.md) & [`TableState_RowPagination`](../interfaces/TableState_RowPagination.md) & [`TableState_RowSorting`](../interfaces/TableState_RowSorting.md) & [`TableState_ColumnOrdering`](../interfaces/TableState_ColumnOrdering.md)\[`K` & +[`Updater`](../type-aliases/Updater.md)\<`TableState_WorkerRowModels` & [`TableState_ColumnGrouping`](../interfaces/TableState_ColumnGrouping.md) & [`TableState_ColumnPinning`](../interfaces/TableState_ColumnPinning.md) & [`TableState_ColumnSizing`](../interfaces/TableState_ColumnSizing.md) & [`TableState_ColumnResizing`](../interfaces/TableState_ColumnResizing.md) & [`TableState_GlobalFiltering`](../interfaces/TableState_GlobalFiltering.md) & [`TableState_ColumnVisibility`](../interfaces/TableState_ColumnVisibility.md) & [`TableState_RowExpanding`](../interfaces/TableState_RowExpanding.md) & [`TableState_RowPinning`](../interfaces/TableState_RowPinning.md) & [`TableState_RowSelection`](../interfaces/TableState_RowSelection.md) & [`TableState_ColumnFiltering`](../interfaces/TableState_ColumnFiltering.md) & [`TableState_RowPagination`](../interfaces/TableState_RowPagination.md) & [`TableState_RowSorting`](../interfaces/TableState_RowSorting.md) & [`TableState_ColumnOrdering`](../interfaces/TableState_ColumnOrdering.md)\[`K` & \| `"expanded"` \| `"columnFilters"` \| `"globalFilter"` diff --git a/docs/reference/index/index.md b/docs/reference/index/index.md index d330a9a3b5..e4be8ccf0b 100644 --- a/docs/reference/index/index.md +++ b/docs/reference/index/index.md @@ -287,7 +287,6 @@ title: index ## Variables -- [aggregationFeature](variables/aggregationFeature.md) - [aggregationFn\_count](variables/aggregationFn_count.md) - [aggregationFn\_extent](variables/aggregationFn_extent.md) - [aggregationFn\_first](variables/aggregationFn_first.md) @@ -340,6 +339,7 @@ title: index - [~~filterFns~~](variables/filterFns.md) - [globalFilteringFeature](variables/globalFilteringFeature.md) - [reSplitAlphaNumeric](variables/reSplitAlphaNumeric.md) +- [rowAggregationFeature](variables/rowAggregationFeature.md) - [rowExpandingFeature](variables/rowExpandingFeature.md) - [rowPaginationFeature](variables/rowPaginationFeature.md) - [rowPinningFeature](variables/rowPinningFeature.md) diff --git a/docs/reference/index/interfaces/AggregationContext.md b/docs/reference/index/interfaces/AggregationContext.md index 46010c52a6..6fa6ba50fa 100644 --- a/docs/reference/index/interfaces/AggregationContext.md +++ b/docs/reference/index/interfaces/AggregationContext.md @@ -5,7 +5,7 @@ title: AggregationContext # Interface: AggregationContext\ -Defined in: [features/aggregation/aggregationFeature.types.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L14) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L14) Values and table objects available while one aggregation is evaluated. @@ -35,7 +35,7 @@ Values and table objects available while one aggregation is evaluated. column: Column; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:20](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L20) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:20](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L20) The column whose values are being aggregated. @@ -47,7 +47,7 @@ The column whose values are being aggregated. columnId: string; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:22](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L22) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:22](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L22) Convenience alias for `column.id`. @@ -59,7 +59,7 @@ Convenience alias for `column.id`. getValue: (row) => TValue; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:32](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L32) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:32](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L32) Reads this column's value from one of `rows`. @@ -81,7 +81,7 @@ Reads this column's value from one of `rows`. optional groupingRow: Row; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:38](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L38) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:38](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L38) The synthetic grouped row receiving this result. This property is omitted for root or caller-supplied-row aggregation. Its `depth` identifies the @@ -95,7 +95,7 @@ grouping level when grouped aggregation needs that distinction. maxDepth: number; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:24](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L24) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:24](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L24) Maximum relative sub-row depth used to select `rows`. @@ -107,7 +107,7 @@ Maximum relative sub-row depth used to select `rows`. rows: readonly Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:43](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L43) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:43](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L43) Unique rows selected at `maxDepth`. Branches that end before `maxDepth` contribute their deepest available row. @@ -120,7 +120,7 @@ contribute their deepest available row. optional subRows: readonly Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:30](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L30) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:30](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L30) Immediate sub-rows for grouped aggregation. This property is omitted for root or caller-supplied-row aggregation. At a terminal grouping level @@ -134,6 +134,6 @@ these are the direct data rows; at a nested level they are sub-row groups. table: Table; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:45](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L45) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:45](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L45) The table that owns the column and rows. diff --git a/docs/reference/index/interfaces/AggregationFnDef.md b/docs/reference/index/interfaces/AggregationFnDef.md index 4d711adab2..4d2a2c2de6 100644 --- a/docs/reference/index/interfaces/AggregationFnDef.md +++ b/docs/reference/index/interfaces/AggregationFnDef.md @@ -5,7 +5,7 @@ title: AggregationFnDef # Interface: AggregationFnDef\ -Defined in: [features/aggregation/aggregationFeature.types.ts:62](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L62) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:62](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L62) A context-based aggregation definition and optional grouped-result merge. @@ -35,7 +35,7 @@ A context-based aggregation definition and optional grouped-result merge. aggregate: (context) => TResult; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:69](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L69) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:69](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L69) Computes a result directly from the selected `rows`. @@ -57,7 +57,7 @@ Computes a result directly from the selected `rows`. optional merge: (context) => TResult; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:74](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L74) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:74](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L74) Combines already-computed immediate sub-row results. When omitted, nested grouping falls back to `aggregate` over the group's selected rows. diff --git a/docs/reference/index/interfaces/AggregationFnDescriptor.md b/docs/reference/index/interfaces/AggregationFnDescriptor.md index 194bc8a340..bc9bc8a9ad 100644 --- a/docs/reference/index/interfaces/AggregationFnDescriptor.md +++ b/docs/reference/index/interfaces/AggregationFnDescriptor.md @@ -5,7 +5,7 @@ title: AggregationFnDescriptor # Interface: AggregationFnDescriptor\ -Defined in: [features/aggregation/aggregationFeature.types.ts:128](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L128) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:128](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L128) Gives an aggregation reference a stable key in a multiple result. @@ -35,7 +35,7 @@ Gives an aggregation reference a stable key in a multiple result. aggregationFn: AggregationFnRef; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:135](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L135) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:135](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L135) The named, automatic, or inline definition to execute. @@ -47,6 +47,6 @@ The named, automatic, or inline definition to execute. id: string; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:137](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L137) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:137](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L137) Stable key used in the object returned by a multiple aggregation. diff --git a/docs/reference/index/interfaces/AggregationFns.md b/docs/reference/index/interfaces/AggregationFns.md index b60705d3e2..9ed0dc0211 100644 --- a/docs/reference/index/interfaces/AggregationFns.md +++ b/docs/reference/index/interfaces/AggregationFns.md @@ -5,6 +5,6 @@ title: AggregationFns # Interface: AggregationFns -Defined in: [features/aggregation/aggregationFeature.types.ts:11](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L11) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:11](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L11) Declaration-merging fallback for named aggregation definitions. diff --git a/docs/reference/index/interfaces/AggregationMergeContext.md b/docs/reference/index/interfaces/AggregationMergeContext.md index b4f39cdb99..f14d257f5a 100644 --- a/docs/reference/index/interfaces/AggregationMergeContext.md +++ b/docs/reference/index/interfaces/AggregationMergeContext.md @@ -5,7 +5,7 @@ title: AggregationMergeContext # Interface: AggregationMergeContext\ -Defined in: [features/aggregation/aggregationFeature.types.ts:49](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L49) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:49](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L49) Additional values available when merging nested grouped results. @@ -39,7 +39,7 @@ Additional values available when merging nested grouped results. column: Column; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:20](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L20) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:20](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L20) The column whose values are being aggregated. @@ -55,7 +55,7 @@ The column whose values are being aggregated. columnId: string; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:22](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L22) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:22](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L22) Convenience alias for `column.id`. @@ -71,7 +71,7 @@ Convenience alias for `column.id`. getValue: (row) => TValue; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:32](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L32) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:32](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L32) Reads this column's value from one of `rows`. @@ -97,7 +97,7 @@ Reads this column's value from one of `rows`. optional groupingRow: Row; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:38](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L38) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:38](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L38) The synthetic grouped row receiving this result. This property is omitted for root or caller-supplied-row aggregation. Its `depth` identifies the @@ -115,7 +115,7 @@ grouping level when grouped aggregation needs that distinction. maxDepth: number; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:24](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L24) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:24](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L24) Maximum relative sub-row depth used to select `rows`. @@ -131,7 +131,7 @@ Maximum relative sub-row depth used to select `rows`. rows: readonly Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:43](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L43) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:43](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L43) Unique rows selected at `maxDepth`. Branches that end before `maxDepth` contribute their deepest available row. @@ -148,7 +148,7 @@ contribute their deepest available row. subRowResults: readonly TResult[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:56](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L56) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:56](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L56) Results produced for each immediate sub-row group, in sub-row order. @@ -160,7 +160,7 @@ Results produced for each immediate sub-row group, in sub-row order. subRows: readonly Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:58](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L58) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:58](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L58) Immediate sub-row groups corresponding to `subRowResults`. @@ -176,7 +176,7 @@ Immediate sub-row groups corresponding to `subRowResults`. table: Table; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:45](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L45) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:45](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L45) The table that owns the column and rows. diff --git a/docs/reference/index/interfaces/AggregationValueContext.md b/docs/reference/index/interfaces/AggregationValueContext.md index 1d6d069fb8..3c59d18ec5 100644 --- a/docs/reference/index/interfaces/AggregationValueContext.md +++ b/docs/reference/index/interfaces/AggregationValueContext.md @@ -5,7 +5,7 @@ title: AggregationValueContext # Interface: AggregationValueContext\ -Defined in: [features/aggregation/aggregationFeature.types.ts:310](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L310) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:310](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L310) Values passed to a column-level aggregation-value provider. @@ -31,7 +31,7 @@ Values passed to a column-level aggregation-value provider. column: Column; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:316](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L316) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:316](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L316) The column whose value was requested. @@ -43,7 +43,7 @@ The column whose value was requested. maxDepth: number; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:318](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L318) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:318](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L318) Maximum relative sub-row depth used for the request. @@ -55,7 +55,7 @@ Maximum relative sub-row depth used for the request. optional rows: readonly Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:320](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L320) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:320](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L320) Caller-provided rows, or `undefined` for the default row model. @@ -67,6 +67,6 @@ Caller-provided rows, or `undefined` for the default row model. table: Table; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:322](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L322) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:322](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L322) The table that owns the column. diff --git a/docs/reference/index/interfaces/AggregationValueOptions.md b/docs/reference/index/interfaces/AggregationValueOptions.md index 42214e47c9..d817a52be3 100644 --- a/docs/reference/index/interfaces/AggregationValueOptions.md +++ b/docs/reference/index/interfaces/AggregationValueOptions.md @@ -5,7 +5,7 @@ title: AggregationValueOptions # Interface: AggregationValueOptions\ -Defined in: [features/aggregation/aggregationFeature.types.ts:287](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L287) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:287](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L287) Options for a caller-requested column aggregation value. @@ -27,7 +27,7 @@ Options for a caller-requested column aggregation value. optional maxDepth: number; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:292](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L292) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:292](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L292) Overrides the column's `maxAggregationDepth` for this request. @@ -39,6 +39,6 @@ Overrides the column's `maxAggregationDepth` for this request. optional rows: readonly Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:294](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L294) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:294](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L294) Rows to aggregate instead of the default pre-grouped row model. diff --git a/docs/reference/index/interfaces/AggregationValueResult.md b/docs/reference/index/interfaces/AggregationValueResult.md index 0b56c9aff7..00f008b4df 100644 --- a/docs/reference/index/interfaces/AggregationValueResult.md +++ b/docs/reference/index/interfaces/AggregationValueResult.md @@ -5,7 +5,7 @@ title: AggregationValueResult # Interface: AggregationValueResult\ -Defined in: [features/aggregation/aggregationFeature.types.ts:326](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L326) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:326](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L326) Marks an aggregation-value override as handled. @@ -23,6 +23,6 @@ Marks an aggregation-value override as handled. value: TResult; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:328](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L328) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:328](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L328) The supplied value. `undefined` is still a handled result. diff --git a/docs/reference/index/interfaces/Cell_Aggregation.md b/docs/reference/index/interfaces/Cell_Aggregation.md index 18b399208c..c3ada522a0 100644 --- a/docs/reference/index/interfaces/Cell_Aggregation.md +++ b/docs/reference/index/interfaces/Cell_Aggregation.md @@ -5,9 +5,9 @@ title: Cell_Aggregation # Interface: Cell\_Aggregation -Defined in: [features/aggregation/aggregationFeature.types.ts:298](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L298) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:298](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L298) -Cell instance APIs installed by `aggregationFeature`. +Cell instance APIs installed by `rowAggregationFeature`. ## Properties @@ -17,7 +17,7 @@ Cell instance APIs installed by `aggregationFeature`. getIsAggregated: () => boolean; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:300](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L300) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:300](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L300) Whether this cell displays an aggregate on a synthetic grouped row. diff --git a/docs/reference/index/interfaces/Cell_FeatureMap.md b/docs/reference/index/interfaces/Cell_FeatureMap.md index be71681a66..2ef3cd52c3 100644 --- a/docs/reference/index/interfaces/Cell_FeatureMap.md +++ b/docs/reference/index/interfaces/Cell_FeatureMap.md @@ -9,20 +9,20 @@ Defined in: [types/Cell.ts:13](https://github.com/TanStack/table/blob/main/packa ## Properties -### aggregationFeature +### columnGroupingFeature ```ts -aggregationFeature: Cell_Aggregation; +columnGroupingFeature: Cell_ColumnGrouping; ``` -Defined in: [types/Cell.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Cell.ts#L14) +Defined in: [types/Cell.ts:15](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Cell.ts#L15) *** -### columnGroupingFeature +### rowAggregationFeature ```ts -columnGroupingFeature: Cell_ColumnGrouping; +rowAggregationFeature: Cell_Aggregation; ``` -Defined in: [types/Cell.ts:15](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Cell.ts#L15) +Defined in: [types/Cell.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Cell.ts#L14) diff --git a/docs/reference/index/interfaces/ColumnDef_Aggregation.md b/docs/reference/index/interfaces/ColumnDef_Aggregation.md index e60a36caca..7e5f8812b9 100644 --- a/docs/reference/index/interfaces/ColumnDef_Aggregation.md +++ b/docs/reference/index/interfaces/ColumnDef_Aggregation.md @@ -5,9 +5,9 @@ title: ColumnDef_Aggregation # Interface: ColumnDef\_Aggregation\ -Defined in: [features/aggregation/aggregationFeature.types.ts:233](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L233) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:233](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L233) -Column-definition options installed by `aggregationFeature`. +Column-definition options installed by `rowAggregationFeature`. ## Type Parameters @@ -31,7 +31,7 @@ Column-definition options installed by `aggregationFeature`. optional aggregatedCell: ColumnDefTemplate["getContext"]>>; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:239](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L239) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:239](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L239) Renderer used for a grouped row's aggregated cell. @@ -43,7 +43,7 @@ Renderer used for a grouped row's aggregated cell. optional aggregationFn: AggregationFnOption; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:246](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L246) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:246](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L246) One aggregation reference for a scalar result, or an array for a keyed result object. Inline definitions in an array require an explicit `id`. @@ -58,7 +58,7 @@ optional getAggregationValue: (context) => | undefined; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:258](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L258) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:258](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L258) Optionally supplies a precomputed aggregation value for this column. Return `{ value }` to handle the request, including `{ value: undefined }`; @@ -83,7 +83,7 @@ return `undefined` to use the local aggregation fallback. optional maxAggregationDepth: number; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:252](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L252) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:252](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L252) Maximum relative sub-row depth used for grouped aggregation and cached default totals. `0` selects the supplied root rows, `1` their direct diff --git a/docs/reference/index/interfaces/ColumnDef_FeatureMap.md b/docs/reference/index/interfaces/ColumnDef_FeatureMap.md index 8184890c5c..c55f10e3a8 100644 --- a/docs/reference/index/interfaces/ColumnDef_FeatureMap.md +++ b/docs/reference/index/interfaces/ColumnDef_FeatureMap.md @@ -23,16 +23,6 @@ Defined in: [types/ColumnDef.ts:131](https://github.com/TanStack/table/blob/main ## Properties -### aggregationFeature - -```ts -aggregationFeature: ColumnDef_Aggregation; -``` - -Defined in: [types/ColumnDef.ts:136](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/ColumnDef.ts#L136) - -*** - ### columnFilteringFeature ```ts @@ -103,6 +93,16 @@ Defined in: [types/ColumnDef.ts:140](https://github.com/TanStack/table/blob/main *** +### rowAggregationFeature + +```ts +rowAggregationFeature: ColumnDef_Aggregation; +``` + +Defined in: [types/ColumnDef.ts:136](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/ColumnDef.ts#L136) + +*** + ### rowSortingFeature ```ts diff --git a/docs/reference/index/interfaces/Column_Aggregation.md b/docs/reference/index/interfaces/Column_Aggregation.md index 7d7eace791..5e85cab81f 100644 --- a/docs/reference/index/interfaces/Column_Aggregation.md +++ b/docs/reference/index/interfaces/Column_Aggregation.md @@ -5,9 +5,9 @@ title: Column_Aggregation # Interface: Column\_Aggregation\ -Defined in: [features/aggregation/aggregationFeature.types.ts:264](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L264) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:264](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L264) -Column instance APIs installed by `aggregationFeature`. +Column instance APIs installed by `rowAggregationFeature`. ## Type Parameters @@ -27,7 +27,7 @@ Column instance APIs installed by `aggregationFeature`. getAggregationFns: () => readonly ResolvedAggregationFn[]; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:269](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L269) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:269](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L269) Resolves the configured scalar or multiple aggregation definitions. @@ -43,7 +43,7 @@ readonly [`ResolvedAggregationFn`](ResolvedAggregationFn.md)\<`TFeatures`, `TDat getAggregationValue: (options?) => TResult; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:277](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L277) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:277](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L277) Aggregates this column over the default pre-grouped row model, or over a caller-provided array of rows. `options.maxDepth` overrides the column's @@ -75,7 +75,7 @@ getAutoAggregationFn: () => | undefined; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:281](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L281) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:281](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L281) Infers `sum` for a numeric first row and `extent` for a Date first row. diff --git a/docs/reference/index/interfaces/Column_FeatureMap.md b/docs/reference/index/interfaces/Column_FeatureMap.md index c99c15e668..1298e789c7 100644 --- a/docs/reference/index/interfaces/Column_FeatureMap.md +++ b/docs/reference/index/interfaces/Column_FeatureMap.md @@ -19,16 +19,6 @@ Defined in: [types/Column.ts:24](https://github.com/TanStack/table/blob/main/pac ## Properties -### aggregationFeature - -```ts -aggregationFeature: Column_Aggregation; -``` - -Defined in: [types/Column.ts:28](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Column.ts#L28) - -*** - ### columnFacetingFeature ```ts @@ -119,6 +109,16 @@ Defined in: [types/Column.ts:37](https://github.com/TanStack/table/blob/main/pac *** +### rowAggregationFeature + +```ts +rowAggregationFeature: Column_Aggregation; +``` + +Defined in: [types/Column.ts:28](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Column.ts#L28) + +*** + ### rowSortingFeature ```ts diff --git a/docs/reference/index/interfaces/FeatureSlotPrereqs.md b/docs/reference/index/interfaces/FeatureSlotPrereqs.md index 9a43f32f88..3c596f6235 100644 --- a/docs/reference/index/interfaces/FeatureSlotPrereqs.md +++ b/docs/reference/index/interfaces/FeatureSlotPrereqs.md @@ -18,7 +18,7 @@ interface to get the same validation from `tableFeatures()`. ### aggregationFns ```ts -aggregationFns: "aggregationFeature"; +aggregationFns: "rowAggregationFeature"; ``` Defined in: [types/TableFeatures.ts:95](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/TableFeatures.ts#L95) diff --git a/docs/reference/index/interfaces/ResolvedAggregationFn.md b/docs/reference/index/interfaces/ResolvedAggregationFn.md index 5041d01e95..f70e978f5e 100644 --- a/docs/reference/index/interfaces/ResolvedAggregationFn.md +++ b/docs/reference/index/interfaces/ResolvedAggregationFn.md @@ -5,7 +5,7 @@ title: ResolvedAggregationFn # Interface: ResolvedAggregationFn\ -Defined in: [features/aggregation/aggregationFeature.types.ts:222](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L222) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:222](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L222) A validated aggregation entry returned by `column.getAggregationFns()`. @@ -29,7 +29,7 @@ aggregationFn: | undefined; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:227](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L227) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:227](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L227) Resolved definition, or `undefined` when configuration is invalid. @@ -41,6 +41,6 @@ Resolved definition, or `undefined` when configuration is invalid. id: string | undefined; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:229](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L229) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:229](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L229) Key used for a multiple result; scalar inline definitions have no id. diff --git a/docs/reference/index/interfaces/RowModelFns_Aggregation.md b/docs/reference/index/interfaces/RowModelFns_Aggregation.md index 7f0a3d8c6d..421a9eca0f 100644 --- a/docs/reference/index/interfaces/RowModelFns_Aggregation.md +++ b/docs/reference/index/interfaces/RowModelFns_Aggregation.md @@ -5,7 +5,7 @@ title: RowModelFns_Aggregation # Interface: RowModelFns\_Aggregation\ -Defined in: [features/aggregation/aggregationFeature.types.ts:95](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L95) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:95](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L95) Aggregation-definition registry carried by a table feature set. @@ -27,4 +27,4 @@ Aggregation-definition registry carried by a table feature set. aggregationFns: Record>; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:99](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L99) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:99](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L99) diff --git a/docs/reference/index/interfaces/RowModelFns_All.md b/docs/reference/index/interfaces/RowModelFns_All.md index 5789ff99d0..2fdfb05cab 100644 --- a/docs/reference/index/interfaces/RowModelFns_All.md +++ b/docs/reference/index/interfaces/RowModelFns_All.md @@ -29,7 +29,7 @@ Defined in: [types/RowModelFns.ts:25](https://github.com/TanStack/table/blob/mai optional aggregationFns: Record>; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:99](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L99) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:99](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L99) #### Inherited from diff --git a/docs/reference/index/interfaces/RowModelFns_FeatureMap.md b/docs/reference/index/interfaces/RowModelFns_FeatureMap.md index 1276bebb74..b02d3e6004 100644 --- a/docs/reference/index/interfaces/RowModelFns_FeatureMap.md +++ b/docs/reference/index/interfaces/RowModelFns_FeatureMap.md @@ -19,23 +19,23 @@ Defined in: [types/RowModelFns.ts:9](https://github.com/TanStack/table/blob/main ## Properties -### aggregationFeature +### columnFilteringFeature ```ts -aggregationFeature: RowModelFns_Aggregation; +columnFilteringFeature: RowModelFns_ColumnFiltering; ``` -Defined in: [types/RowModelFns.ts:13](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/RowModelFns.ts#L13) +Defined in: [types/RowModelFns.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/RowModelFns.ts#L14) *** -### columnFilteringFeature +### rowAggregationFeature ```ts -columnFilteringFeature: RowModelFns_ColumnFiltering; +rowAggregationFeature: RowModelFns_Aggregation; ``` -Defined in: [types/RowModelFns.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/RowModelFns.ts#L14) +Defined in: [types/RowModelFns.ts:13](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/RowModelFns.ts#L13) *** diff --git a/docs/reference/index/interfaces/Row_Aggregation.md b/docs/reference/index/interfaces/Row_Aggregation.md index 8344e345c3..cac19b6a48 100644 --- a/docs/reference/index/interfaces/Row_Aggregation.md +++ b/docs/reference/index/interfaces/Row_Aggregation.md @@ -5,7 +5,7 @@ title: Row_Aggregation # Interface: Row\_Aggregation -Defined in: [features/aggregation/aggregationFeature.types.ts:304](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L304) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:304](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L304) Internal per-row cache used while grouped aggregates are evaluated. @@ -17,6 +17,6 @@ Internal per-row cache used while grouped aggregates are evaluated. _aggregationValuesCache: Record; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:306](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L306) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:306](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L306) Cached aggregate results keyed by column id. diff --git a/docs/reference/index/interfaces/Row_FeatureMap.md b/docs/reference/index/interfaces/Row_FeatureMap.md index e97b54d9e2..d84f6b937f 100644 --- a/docs/reference/index/interfaces/Row_FeatureMap.md +++ b/docs/reference/index/interfaces/Row_FeatureMap.md @@ -19,16 +19,6 @@ Defined in: [types/Row.ts:18](https://github.com/TanStack/table/blob/main/packag ## Properties -### aggregationFeature - -```ts -aggregationFeature: Row_Aggregation; -``` - -Defined in: [types/Row.ts:22](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Row.ts#L22) - -*** - ### columnFilteringFeature ```ts @@ -69,6 +59,16 @@ Defined in: [types/Row.ts:26](https://github.com/TanStack/table/blob/main/packag *** +### rowAggregationFeature + +```ts +rowAggregationFeature: Row_Aggregation; +``` + +Defined in: [types/Row.ts:22](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/Row.ts#L22) + +*** + ### rowExpandingFeature ```ts diff --git a/docs/reference/index/interfaces/StockFeatures.md b/docs/reference/index/interfaces/StockFeatures.md index db24168606..0df976d4a5 100644 --- a/docs/reference/index/interfaces/StockFeatures.md +++ b/docs/reference/index/interfaces/StockFeatures.md @@ -9,16 +9,6 @@ Defined in: [features/stockFeatures.ts:17](https://github.com/TanStack/table/blo ## Properties -### aggregationFeature - -```ts -aggregationFeature: TableFeature; -``` - -Defined in: [features/stockFeatures.ts:18](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/stockFeatures.ts#L18) - -*** - ### columnFacetingFeature ```ts @@ -109,6 +99,16 @@ Defined in: [features/stockFeatures.ts:27](https://github.com/TanStack/table/blo *** +### rowAggregationFeature + +```ts +rowAggregationFeature: TableFeature; +``` + +Defined in: [features/stockFeatures.ts:18](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/stockFeatures.ts#L18) + +*** + ### rowExpandingFeature ```ts diff --git a/docs/reference/index/interfaces/TableFeatures.md b/docs/reference/index/interfaces/TableFeatures.md index 2fff0e39a7..8f41baca2c 100644 --- a/docs/reference/index/interfaces/TableFeatures.md +++ b/docs/reference/index/interfaces/TableFeatures.md @@ -21,20 +21,6 @@ options, and state types. ## Properties -### aggregationFeature? - -```ts -optional aggregationFeature: TableFeature; -``` - -Defined in: [features/stockFeatures.ts:18](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/stockFeatures.ts#L18) - -#### Inherited from - -[`StockFeatures`](StockFeatures.md).[`aggregationFeature`](StockFeatures.md#aggregationfeature) - -*** - ### aggregationFns? ```ts @@ -588,6 +574,20 @@ server-side pagination. *** +### rowAggregationFeature? + +```ts +optional rowAggregationFeature: TableFeature; +``` + +Defined in: [features/stockFeatures.ts:18](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/stockFeatures.ts#L18) + +#### Inherited from + +[`StockFeatures`](StockFeatures.md).[`rowAggregationFeature`](StockFeatures.md#rowaggregationfeature) + +*** + ### rowExpandingFeature? ```ts diff --git a/docs/reference/index/interfaces/TableOptions_Aggregation.md b/docs/reference/index/interfaces/TableOptions_Aggregation.md index 5658150dbe..dc8b63caee 100644 --- a/docs/reference/index/interfaces/TableOptions_Aggregation.md +++ b/docs/reference/index/interfaces/TableOptions_Aggregation.md @@ -5,9 +5,9 @@ title: TableOptions_Aggregation # Interface: TableOptions\_Aggregation -Defined in: [features/aggregation/aggregationFeature.types.ts:332](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L332) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:332](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L332) -Table options installed by `aggregationFeature`. +Table options installed by `rowAggregationFeature`. ## Properties @@ -17,7 +17,7 @@ Table options installed by `aggregationFeature`. optional manualAggregation: boolean; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:338](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L338) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:338](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L338) Disables local `column.getAggregationValue()` calculation when a column override does not handle the request. Group values supplied by manually diff --git a/docs/reference/index/interfaces/TableOptions_FeatureMap.md b/docs/reference/index/interfaces/TableOptions_FeatureMap.md index 9e53d11f69..c5945f93f4 100644 --- a/docs/reference/index/interfaces/TableOptions_FeatureMap.md +++ b/docs/reference/index/interfaces/TableOptions_FeatureMap.md @@ -19,16 +19,6 @@ Defined in: [types/TableOptions.ts:58](https://github.com/TanStack/table/blob/ma ## Properties -### aggregationFeature - -```ts -aggregationFeature: TableOptions_Aggregation; -``` - -Defined in: [types/TableOptions.ts:62](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/TableOptions.ts#L62) - -*** - ### columnFilteringFeature ```ts @@ -109,6 +99,16 @@ Defined in: [types/TableOptions.ts:70](https://github.com/TanStack/table/blob/ma *** +### rowAggregationFeature + +```ts +rowAggregationFeature: TableOptions_Aggregation; +``` + +Defined in: [types/TableOptions.ts:62](https://github.com/TanStack/table/blob/main/packages/table-core/src/types/TableOptions.ts#L62) + +*** + ### rowExpandingFeature ```ts diff --git a/docs/reference/index/type-aliases/AggregationFnListItem.md b/docs/reference/index/type-aliases/AggregationFnListItem.md index ef6d040c9f..29c29bb7f7 100644 --- a/docs/reference/index/type-aliases/AggregationFnListItem.md +++ b/docs/reference/index/type-aliases/AggregationFnListItem.md @@ -12,7 +12,7 @@ type AggregationFnListItem = | AggregationFnDescriptor; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:141](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L141) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:141](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L141) One named or explicitly keyed entry in a multiple aggregation option. diff --git a/docs/reference/index/type-aliases/AggregationFnOption.md b/docs/reference/index/type-aliases/AggregationFnOption.md index 136aa9fc24..0488871de1 100644 --- a/docs/reference/index/type-aliases/AggregationFnOption.md +++ b/docs/reference/index/type-aliases/AggregationFnOption.md @@ -6,12 +6,12 @@ title: AggregationFnOption # Type Alias: AggregationFnOption\ ```ts -type AggregationFnOption = +type AggregationFnOption = | AggregationFnRef | ReadonlyArray>; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:151](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L151) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:151](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L151) A scalar aggregation reference or a list that produces a keyed object. diff --git a/docs/reference/index/type-aliases/AggregationFnRef.md b/docs/reference/index/type-aliases/AggregationFnRef.md index e19012a8c1..45c079bada 100644 --- a/docs/reference/index/type-aliases/AggregationFnRef.md +++ b/docs/reference/index/type-aliases/AggregationFnRef.md @@ -12,7 +12,7 @@ type AggregationFnRef = | AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:117](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L117) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:117](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L117) A registered name, automatic inference, or inline aggregation definition. diff --git a/docs/reference/index/type-aliases/AggregationResult.md b/docs/reference/index/type-aliases/AggregationResult.md index 8e68acda85..037fc4577a 100644 --- a/docs/reference/index/type-aliases/AggregationResult.md +++ b/docs/reference/index/type-aliases/AggregationResult.md @@ -9,7 +9,7 @@ title: AggregationResult type AggregationResult = TOption extends ReadonlyArray ? { [TKey in AggregationEntryId]: AggregationResultOfRef>, TFeatures> } : AggregationResultOfRef; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:198](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L198) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:198](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L198) Infers the scalar or keyed result produced by an aggregation option. diff --git a/docs/reference/index/type-aliases/AggregationResultOf.md b/docs/reference/index/type-aliases/AggregationResultOf.md index 0507d848bd..93d303c413 100644 --- a/docs/reference/index/type-aliases/AggregationResultOf.md +++ b/docs/reference/index/type-aliases/AggregationResultOf.md @@ -9,7 +9,7 @@ title: AggregationResultOf type AggregationResultOf = TDefinition extends AggregationFnDef ? TResult : unknown; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:160](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L160) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:160](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L160) Extracts the result type produced by an aggregation definition. diff --git a/docs/reference/index/type-aliases/BuiltInAggregationFn.md b/docs/reference/index/type-aliases/BuiltInAggregationFn.md index 26e2913ad5..c131b526fb 100644 --- a/docs/reference/index/type-aliases/BuiltInAggregationFn.md +++ b/docs/reference/index/type-aliases/BuiltInAggregationFn.md @@ -9,4 +9,4 @@ title: BuiltInAggregationFn type BuiltInAggregationFn = keyof typeof aggregationFns; ``` -Defined in: [features/aggregation/aggregationFns.ts:345](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L345) +Defined in: [features/row-aggregation/aggregationFns.ts:345](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L345) diff --git a/docs/reference/index/type-aliases/ColumnAggregationValue.md b/docs/reference/index/type-aliases/ColumnAggregationValue.md index b4e5ff782b..e2ba54e51a 100644 --- a/docs/reference/index/type-aliases/ColumnAggregationValue.md +++ b/docs/reference/index/type-aliases/ColumnAggregationValue.md @@ -12,7 +12,7 @@ type ColumnAggregationValue = | undefined; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:216](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L216) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:216](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L216) Default public result union when a column's precise option is not known. diff --git a/docs/reference/index/type-aliases/CustomAggregationFns.md b/docs/reference/index/type-aliases/CustomAggregationFns.md index 43a58215d1..ee839c0aba 100644 --- a/docs/reference/index/type-aliases/CustomAggregationFns.md +++ b/docs/reference/index/type-aliases/CustomAggregationFns.md @@ -9,7 +9,7 @@ title: CustomAggregationFns type CustomAggregationFns = Record>; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:103](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L103) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:103](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L103) Named context-based aggregation definitions registered on a feature set. diff --git a/docs/reference/index/type-aliases/ExtractAggregationFnKeys.md b/docs/reference/index/type-aliases/ExtractAggregationFnKeys.md index 0607e96b14..d3f2708036 100644 --- a/docs/reference/index/type-aliases/ExtractAggregationFnKeys.md +++ b/docs/reference/index/type-aliases/ExtractAggregationFnKeys.md @@ -11,7 +11,7 @@ type ExtractAggregationFnKeys = IsAny extends true ? | BuiltInAggregationFn : TFeatures extends object ? Extract : keyof AggregationFns; ``` -Defined in: [features/aggregation/aggregationFeature.types.ts:109](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.types.ts#L109) +Defined in: [features/row-aggregation/rowAggregationFeature.types.ts:109](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.types.ts#L109) String names available from a feature set's aggregation registry. diff --git a/docs/reference/index/variables/aggregationFeature.md b/docs/reference/index/variables/aggregationFeature.md deleted file mode 100644 index 6449e5fe2e..0000000000 --- a/docs/reference/index/variables/aggregationFeature.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -id: aggregationFeature -title: aggregationFeature ---- - -# Variable: aggregationFeature - -```ts -const aggregationFeature: TableFeature; -``` - -Defined in: [features/aggregation/aggregationFeature.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.ts#L14) - -Independent aggregation feature for grouped values and root/custom-row totals. diff --git a/docs/reference/index/variables/aggregationFn_count.md b/docs/reference/index/variables/aggregationFn_count.md index 23fc4545a8..871b9797b6 100644 --- a/docs/reference/index/variables/aggregationFn_count.md +++ b/docs/reference/index/variables/aggregationFn_count.md @@ -9,6 +9,6 @@ title: aggregationFn_count const aggregationFn_count: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:282](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L282) +Defined in: [features/row-aggregation/aggregationFns.ts:282](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L282) Counts rows, independently of the column's values. diff --git a/docs/reference/index/variables/aggregationFn_extent.md b/docs/reference/index/variables/aggregationFn_extent.md index 67235c6968..e0763c9907 100644 --- a/docs/reference/index/variables/aggregationFn_extent.md +++ b/docs/reference/index/variables/aggregationFn_extent.md @@ -9,7 +9,7 @@ title: aggregationFn_extent const aggregationFn_extent: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:146](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L146) +Defined in: [features/row-aggregation/aggregationFns.ts:146](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L146) Finds the minimum and maximum numeric or Date values from the selected rows. Empty inputs return diff --git a/docs/reference/index/variables/aggregationFn_first.md b/docs/reference/index/variables/aggregationFn_first.md index 62dae0f6fe..ff2356dd7e 100644 --- a/docs/reference/index/variables/aggregationFn_first.md +++ b/docs/reference/index/variables/aggregationFn_first.md @@ -9,6 +9,6 @@ title: aggregationFn_first const aggregationFn_first: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:300](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L300) +Defined in: [features/row-aggregation/aggregationFns.ts:300](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L300) Returns the first row's value, including a nullish value. diff --git a/docs/reference/index/variables/aggregationFn_last.md b/docs/reference/index/variables/aggregationFn_last.md index e611677421..4dda251314 100644 --- a/docs/reference/index/variables/aggregationFn_last.md +++ b/docs/reference/index/variables/aggregationFn_last.md @@ -9,6 +9,6 @@ title: aggregationFn_last const aggregationFn_last: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:312](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L312) +Defined in: [features/row-aggregation/aggregationFns.ts:312](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L312) Returns the last row's value, including a nullish value. diff --git a/docs/reference/index/variables/aggregationFn_max.md b/docs/reference/index/variables/aggregationFn_max.md index 50f3977729..c99ef8ec04 100644 --- a/docs/reference/index/variables/aggregationFn_max.md +++ b/docs/reference/index/variables/aggregationFn_max.md @@ -9,7 +9,7 @@ title: aggregationFn_max const aggregationFn_max: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:109](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L109) +Defined in: [features/row-aggregation/aggregationFns.ts:109](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L109) Finds the maximum numeric or Date value from the selected rows. Invalid value types are ignored; `NaN` preserves the legacy numeric seeding behavior. diff --git a/docs/reference/index/variables/aggregationFn_mean.md b/docs/reference/index/variables/aggregationFn_mean.md index 81b3a77462..a64c335ce3 100644 --- a/docs/reference/index/variables/aggregationFn_mean.md +++ b/docs/reference/index/variables/aggregationFn_mean.md @@ -9,7 +9,7 @@ title: aggregationFn_mean const aggregationFn_mean: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:201](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L201) +Defined in: [features/row-aggregation/aggregationFns.ts:201](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L201) Averages number and number-like row values. Nullish and non-numeric values are ignored; other values retain the legacy unary-plus coercion behavior. diff --git a/docs/reference/index/variables/aggregationFn_median.md b/docs/reference/index/variables/aggregationFn_median.md index 7aa9261c8b..b0b1efe1bd 100644 --- a/docs/reference/index/variables/aggregationFn_median.md +++ b/docs/reference/index/variables/aggregationFn_median.md @@ -9,7 +9,7 @@ title: aggregationFn_median const aggregationFn_median: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:227](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L227) +Defined in: [features/row-aggregation/aggregationFns.ts:227](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L227) Computes the median when every row value is a number. Returns `undefined` for empty inputs or when any value is non-numeric. diff --git a/docs/reference/index/variables/aggregationFn_min.md b/docs/reference/index/variables/aggregationFn_min.md index 5faac44990..ec661b7605 100644 --- a/docs/reference/index/variables/aggregationFn_min.md +++ b/docs/reference/index/variables/aggregationFn_min.md @@ -9,7 +9,7 @@ title: aggregationFn_min const aggregationFn_min: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:73](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L73) +Defined in: [features/row-aggregation/aggregationFns.ts:73](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L73) Finds the minimum numeric or Date value from the selected rows. Invalid value types are ignored; `NaN` preserves the legacy numeric seeding behavior. diff --git a/docs/reference/index/variables/aggregationFn_sum.md b/docs/reference/index/variables/aggregationFn_sum.md index 5594e9b5e6..8661685561 100644 --- a/docs/reference/index/variables/aggregationFn_sum.md +++ b/docs/reference/index/variables/aggregationFn_sum.md @@ -9,7 +9,7 @@ title: aggregationFn_sum const aggregationFn_sum: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:45](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L45) +Defined in: [features/row-aggregation/aggregationFns.ts:45](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L45) Sums numeric selected-row values. Non-number values contribute zero. As in the previous API, `NaN` is a number and therefore propagates through the sum. diff --git a/docs/reference/index/variables/aggregationFn_unique.md b/docs/reference/index/variables/aggregationFn_unique.md index 0f2a44a317..99c015d042 100644 --- a/docs/reference/index/variables/aggregationFn_unique.md +++ b/docs/reference/index/variables/aggregationFn_unique.md @@ -9,6 +9,6 @@ title: aggregationFn_unique const aggregationFn_unique: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:250](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L250) +Defined in: [features/row-aggregation/aggregationFns.ts:250](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L250) Collects distinct row values using JavaScript `Set` semantics. diff --git a/docs/reference/index/variables/aggregationFn_uniqueCount.md b/docs/reference/index/variables/aggregationFn_uniqueCount.md index 84feb77f1c..8a993463c4 100644 --- a/docs/reference/index/variables/aggregationFn_uniqueCount.md +++ b/docs/reference/index/variables/aggregationFn_uniqueCount.md @@ -9,6 +9,6 @@ title: aggregationFn_uniqueCount const aggregationFn_uniqueCount: AggregationFnDef; ``` -Defined in: [features/aggregation/aggregationFns.ts:266](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L266) +Defined in: [features/row-aggregation/aggregationFns.ts:266](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L266) Counts distinct row values using JavaScript `Set` semantics. diff --git a/docs/reference/index/variables/aggregationFns.md b/docs/reference/index/variables/aggregationFns.md index 3a6af75044..ed6ceee628 100644 --- a/docs/reference/index/variables/aggregationFns.md +++ b/docs/reference/index/variables/aggregationFns.md @@ -9,7 +9,7 @@ title: aggregationFns const aggregationFns: object; ``` -Defined in: [features/aggregation/aggregationFns.ts:331](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFns.ts#L331) +Defined in: [features/row-aggregation/aggregationFns.ts:331](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/aggregationFns.ts#L331) Full built-in registry. Register individual definitions for tree-shaking. diff --git a/docs/reference/index/variables/rowAggregationFeature.md b/docs/reference/index/variables/rowAggregationFeature.md new file mode 100644 index 0000000000..8c90b34a66 --- /dev/null +++ b/docs/reference/index/variables/rowAggregationFeature.md @@ -0,0 +1,14 @@ +--- +id: rowAggregationFeature +title: rowAggregationFeature +--- + +# Variable: rowAggregationFeature + +```ts +const rowAggregationFeature: TableFeature; +``` + +Defined in: [features/row-aggregation/rowAggregationFeature.ts:14](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.ts#L14) + +Independent aggregation feature for grouped values and root/custom-row totals. diff --git a/docs/reference/static-functions/functions/aggregateColumnValue.md b/docs/reference/static-functions/functions/aggregateColumnValue.md index 73a835d98f..53b17407e4 100644 --- a/docs/reference/static-functions/functions/aggregateColumnValue.md +++ b/docs/reference/static-functions/functions/aggregateColumnValue.md @@ -9,7 +9,7 @@ title: aggregateColumnValue function aggregateColumnValue(args): unknown; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:261](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L261) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:261](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L261) Executes every configured aggregation over a depth-selected row frontier. diff --git a/docs/reference/static-functions/functions/cell_getIsAggregated.md b/docs/reference/static-functions/functions/cell_getIsAggregated.md index e7cb3e1ab2..fe8c464dde 100644 --- a/docs/reference/static-functions/functions/cell_getIsAggregated.md +++ b/docs/reference/static-functions/functions/cell_getIsAggregated.md @@ -9,7 +9,7 @@ title: cell_getIsAggregated function cell_getIsAggregated(cell): boolean; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:393](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L393) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:393](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L393) Implements `cell.getIsAggregated()` for synthetic grouped rows. diff --git a/docs/reference/static-functions/functions/column_getAggregationFns.md b/docs/reference/static-functions/functions/column_getAggregationFns.md index f8d136f0a7..6e46a9e703 100644 --- a/docs/reference/static-functions/functions/column_getAggregationFns.md +++ b/docs/reference/static-functions/functions/column_getAggregationFns.md @@ -9,7 +9,7 @@ title: column_getAggregationFns function column_getAggregationFns(column): readonly ResolvedAggregationFn[]; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:155](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L155) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:155](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L155) Resolves and validates a column's scalar or multiple aggregation option. diff --git a/docs/reference/static-functions/functions/column_getAggregationValue.md b/docs/reference/static-functions/functions/column_getAggregationValue.md index 3beed6b69b..17ef1824ad 100644 --- a/docs/reference/static-functions/functions/column_getAggregationValue.md +++ b/docs/reference/static-functions/functions/column_getAggregationValue.md @@ -9,7 +9,7 @@ title: column_getAggregationValue function column_getAggregationValue(column, options?): ColumnAggregationValue; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:330](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L330) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:330](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L330) Implements `column.getAggregationValue(options?)` and its default cache. diff --git a/docs/reference/static-functions/functions/column_getAutoAggregationFn.md b/docs/reference/static-functions/functions/column_getAutoAggregationFn.md index 9ddd8bccc0..3f8ecf3189 100644 --- a/docs/reference/static-functions/functions/column_getAutoAggregationFn.md +++ b/docs/reference/static-functions/functions/column_getAutoAggregationFn.md @@ -11,7 +11,7 @@ function column_getAutoAggregationFn(column): | undefined; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:113](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L113) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:113](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L113) Resolves the `sum` or `extent` definition inferred from the first core row. diff --git a/docs/reference/static-functions/functions/formatAggregatedCellValue.md b/docs/reference/static-functions/functions/formatAggregatedCellValue.md index 5a815296f4..bdc2fea8f3 100644 --- a/docs/reference/static-functions/functions/formatAggregatedCellValue.md +++ b/docs/reference/static-functions/functions/formatAggregatedCellValue.md @@ -9,7 +9,7 @@ title: formatAggregatedCellValue function formatAggregatedCellValue(value, option): string | null; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:414](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L414) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:414](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L414) Formats the default scalar or keyed aggregated-cell representation. diff --git a/docs/reference/static-functions/functions/normalizeAggregationRows.md b/docs/reference/static-functions/functions/normalizeAggregationRows.md index 9d0b4520fd..41d89599a3 100644 --- a/docs/reference/static-functions/functions/normalizeAggregationRows.md +++ b/docs/reference/static-functions/functions/normalizeAggregationRows.md @@ -9,7 +9,7 @@ title: normalizeAggregationRows function normalizeAggregationRows(rows, maxDepth): Row[]; ``` -Defined in: [features/aggregation/aggregationFeature.utils.ts:66](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/aggregation/aggregationFeature.utils.ts#L66) +Defined in: [features/row-aggregation/rowAggregationFeature.utils.ts:66](https://github.com/TanStack/table/blob/main/packages/table-core/src/features/row-aggregation/rowAggregationFeature.utils.ts#L66) Selects unique rows at a maximum relative depth in encounter order. Branches that end before the requested depth contribute their deepest row. diff --git a/examples/alpine/aggregation/src/main.ts b/examples/alpine/aggregation/src/main.ts index e8491233d7..759160c3ff 100644 --- a/examples/alpine/aggregation/src/main.ts +++ b/examples/alpine/aggregation/src/main.ts @@ -1,7 +1,7 @@ import Alpine from 'alpinejs' import { FlexRender, - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -25,7 +25,7 @@ import type { Table } from '@tanstack/alpine-table' type RowSource = 'all' | 'custom' | 'filtered' | 'page' | 'selected' type AggregationTableMeta = { rowSource: RowSource } const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/alpine/grouped-aggregation/src/main.ts b/examples/alpine/grouped-aggregation/src/main.ts index 7b3a315a44..c6f692edf2 100644 --- a/examples/alpine/grouped-aggregation/src/main.ts +++ b/examples/alpine/grouped-aggregation/src/main.ts @@ -1,7 +1,7 @@ import Alpine from 'alpinejs' import { FlexRender, - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_median, aggregationFn_sum, @@ -29,7 +29,7 @@ import type { ColumnDef } from '@tanstack/alpine-table' import type { Person } from './makeData' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, columnGroupingFeature, rowExpandingFeature, diff --git a/examples/angular/aggregation/src/app/app.ts b/examples/angular/aggregation/src/app/app.ts index 1637dda3bd..a81c12b48f 100644 --- a/examples/angular/aggregation/src/app/app.ts +++ b/examples/angular/aggregation/src/app/app.ts @@ -1,7 +1,7 @@ import { ChangeDetectionStrategy, Component, signal } from '@angular/core' import { FlexRender, - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -23,7 +23,7 @@ import type { Sale } from './makeData' type RowSource = 'all' | 'custom' | 'filtered' | 'page' | 'selected' type AggregationTableMeta = { rowSource: RowSource } const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/angular/grouped-aggregation/src/app/columns.ts b/examples/angular/grouped-aggregation/src/app/columns.ts index 974c154377..5dc9db9a9a 100644 --- a/examples/angular/grouped-aggregation/src/app/columns.ts +++ b/examples/angular/grouped-aggregation/src/app/columns.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_median, aggregationFn_sum, @@ -17,7 +17,7 @@ import { import type { Person } from './makeData' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, rowPaginationFeature, columnFilteringFeature, diff --git a/examples/ember/aggregation/app/templates/application.gts b/examples/ember/aggregation/app/templates/application.gts index de485240e5..86d0b4d063 100644 --- a/examples/ember/aggregation/app/templates/application.gts +++ b/examples/ember/aggregation/app/templates/application.gts @@ -3,7 +3,7 @@ import { tracked } from '@glimmer/tracking' import { on } from '@ember/modifier' import { useTable, - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -30,7 +30,7 @@ type RowSource = 'all' | 'custom' | 'filtered' | 'page' | 'selected' type AggregationTableMeta = { rowSource: RowSource } const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/ember/grouped-aggregation/app/templates/application.gts b/examples/ember/grouped-aggregation/app/templates/application.gts index 2b6efbce41..2dcc5a5902 100644 --- a/examples/ember/grouped-aggregation/app/templates/application.gts +++ b/examples/ember/grouped-aggregation/app/templates/application.gts @@ -3,7 +3,7 @@ import { tracked } from '@glimmer/tracking' import { on } from '@ember/modifier' import { useTable, - aggregationFeature, + rowAggregationFeature, FlexRenderCell, FlexRenderHeader, FlexRenderFooter, @@ -39,7 +39,7 @@ import type { ComponentLike, ContentValue } from '@glint/template' import { makeData, type Person } from '../utils/make-data' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnGroupingFeature, rowExpandingFeature, rowPaginationFeature, diff --git a/examples/lit/aggregation/src/main.ts b/examples/lit/aggregation/src/main.ts index 3dee2691da..4ca183e0b9 100644 --- a/examples/lit/aggregation/src/main.ts +++ b/examples/lit/aggregation/src/main.ts @@ -4,7 +4,7 @@ import { repeat } from 'lit/directives/repeat.js' import { FlexRender, TableController, - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -27,7 +27,7 @@ type RowSource = 'all' | 'custom' | 'filtered' | 'page' | 'selected' type AggregationTableMeta = { rowSource: RowSource } const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/lit/grouped-aggregation/src/main.ts b/examples/lit/grouped-aggregation/src/main.ts index cab89ec6fe..727170ed69 100644 --- a/examples/lit/grouped-aggregation/src/main.ts +++ b/examples/lit/grouped-aggregation/src/main.ts @@ -4,7 +4,7 @@ import { repeat } from 'lit/directives/repeat.js' import { FlexRender, TableController, - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_median, aggregationFn_sum, @@ -30,7 +30,7 @@ import type { ColumnDef } from '@tanstack/lit-table' import type { Person } from './makeData' const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, columnGroupingFeature, rowExpandingFeature, diff --git a/examples/preact/aggregation/src/main.tsx b/examples/preact/aggregation/src/main.tsx index 6cc952f6bb..f9b344149f 100644 --- a/examples/preact/aggregation/src/main.tsx +++ b/examples/preact/aggregation/src/main.tsx @@ -2,7 +2,7 @@ import { render } from 'preact' import { useMemo, useState } from 'preact/hooks' import './index.css' import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -26,7 +26,7 @@ type RowSource = 'all' | 'custom' | 'filtered' | 'page' | 'selected' type AggregationTableMeta = { rowSource: RowSource } const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/preact/grouped-aggregation/src/main.tsx b/examples/preact/grouped-aggregation/src/main.tsx index cf6af58631..c2f27f2fb0 100644 --- a/examples/preact/grouped-aggregation/src/main.tsx +++ b/examples/preact/grouped-aggregation/src/main.tsx @@ -2,7 +2,7 @@ import { useMemo, useState } from 'preact/hooks' import { render } from 'preact' import './index.css' import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_median, aggregationFn_sum, @@ -28,7 +28,7 @@ import type { Person } from './makeData' // this example happens to use the createTableHook pattern, but it is not required const { useAppTable, createAppColumnHelper } = createTableHook({ features: { - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, columnGroupingFeature, rowExpandingFeature, diff --git a/examples/react/aggregation/src/main.tsx b/examples/react/aggregation/src/main.tsx index ef7409a624..20b854615f 100644 --- a/examples/react/aggregation/src/main.tsx +++ b/examples/react/aggregation/src/main.tsx @@ -2,7 +2,7 @@ import React from 'react' import ReactDOM from 'react-dom/client' import './index.css' import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -28,7 +28,7 @@ type AggregationTableMeta = { } const features = { - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/grouped-aggregation/src/main.tsx b/examples/react/grouped-aggregation/src/main.tsx index bfc5837d6d..9f578a92fc 100644 --- a/examples/react/grouped-aggregation/src/main.tsx +++ b/examples/react/grouped-aggregation/src/main.tsx @@ -2,7 +2,7 @@ import React from 'react' import ReactDOM from 'react-dom/client' import './index.css' import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_median, aggregationFn_sum, @@ -28,7 +28,7 @@ import type { Person } from './makeData' // this example happens to use the createTableHook pattern, but it is not required const { useAppTable, createAppColumnHelper } = createTableHook({ features: { - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, columnGroupingFeature, rowExpandingFeature, diff --git a/examples/react/kitchen-sink-chakra-ui/src/hooks/features.ts b/examples/react/kitchen-sink-chakra-ui/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-chakra-ui/src/hooks/features.ts +++ b/examples/react/kitchen-sink-chakra-ui/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/kitchen-sink-hero-ui/src/hooks/features.ts b/examples/react/kitchen-sink-hero-ui/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-hero-ui/src/hooks/features.ts +++ b/examples/react/kitchen-sink-hero-ui/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/kitchen-sink-mantine/src/hooks/features.ts b/examples/react/kitchen-sink-mantine/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-mantine/src/hooks/features.ts +++ b/examples/react/kitchen-sink-mantine/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/kitchen-sink-material-ui/src/hooks/features.ts b/examples/react/kitchen-sink-material-ui/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-material-ui/src/hooks/features.ts +++ b/examples/react/kitchen-sink-material-ui/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/kitchen-sink-react-aria/src/hooks/features.ts b/examples/react/kitchen-sink-react-aria/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-react-aria/src/hooks/features.ts +++ b/examples/react/kitchen-sink-react-aria/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/kitchen-sink-shadcn-base/src/hooks/features.ts b/examples/react/kitchen-sink-shadcn-base/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-shadcn-base/src/hooks/features.ts +++ b/examples/react/kitchen-sink-shadcn-base/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/kitchen-sink-shadcn-radix/src/hooks/features.ts b/examples/react/kitchen-sink-shadcn-radix/src/hooks/features.ts index ffb5e86be1..1985b8b905 100644 --- a/examples/react/kitchen-sink-shadcn-radix/src/hooks/features.ts +++ b/examples/react/kitchen-sink-shadcn-radix/src/hooks/features.ts @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_min, columnFacetingFeature, @@ -48,7 +48,7 @@ const fuzzyFilterFn = ( } export const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/react/web-worker-row-models/src/tableConfig.tsx b/examples/react/web-worker-row-models/src/tableConfig.tsx index 028d346e7f..46faae618e 100644 --- a/examples/react/web-worker-row-models/src/tableConfig.tsx +++ b/examples/react/web-worker-row-models/src/tableConfig.tsx @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_extent, aggregationFn_mean, aggregationFn_median, @@ -43,7 +43,7 @@ import type { Person } from './makeData' // crosses threads at all. export const sharedFeatures = tableFeatures({ - aggregationFeature, + rowAggregationFeature, rowSortingFeature, columnFilteringFeature, globalFilteringFeature, diff --git a/examples/solid/aggregation/src/App.tsx b/examples/solid/aggregation/src/App.tsx index 88a23979e6..9820a46d63 100644 --- a/examples/solid/aggregation/src/App.tsx +++ b/examples/solid/aggregation/src/App.tsx @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_count, aggregationFn_extent, aggregationFn_mean, @@ -23,7 +23,7 @@ import type { Table } from '@tanstack/solid-table' type RowSource = 'all' | 'custom' | 'filtered' | 'page' | 'selected' type AggregationTableMeta = { rowSource: RowSource } const features = tableFeatures({ - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, rowPaginationFeature, rowSelectionFeature, diff --git a/examples/solid/grouped-aggregation/src/App.tsx b/examples/solid/grouped-aggregation/src/App.tsx index c0ca35bc58..b325baa6cb 100644 --- a/examples/solid/grouped-aggregation/src/App.tsx +++ b/examples/solid/grouped-aggregation/src/App.tsx @@ -1,5 +1,5 @@ import { - aggregationFeature, + rowAggregationFeature, aggregationFn_mean, aggregationFn_median, aggregationFn_sum, @@ -25,7 +25,7 @@ import type { Person } from './makeData' const { createAppTable, createAppColumnHelper } = createTableHook({ features: { - aggregationFeature, + rowAggregationFeature, columnFilteringFeature, columnGroupingFeature, rowExpandingFeature, diff --git a/examples/svelte/aggregation/src/App.svelte b/examples/svelte/aggregation/src/App.svelte index 9dd9a358a5..31cee13053 100644 --- a/examples/svelte/aggregation/src/App.svelte +++ b/examples/svelte/aggregation/src/App.svelte @@ -1,5 +1,5 @@