@tanstack/angular-table 9.0.0-beta.4 → 9.0.0-beta.43

package/skills/table-state/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: table-state
+description: >
+  Use Angular-signal-backed table.atoms, direct template reads, computed selectors, controlled signals, value-or-updater callbacks, and external Angular Store atoms while accounting for injectTable initializer reruns.
+metadata:
+  type: framework
+  library: '@tanstack/angular-table'
+  framework: angular
+  library_version: '9.0.0-beta.43'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+sources:
+  - 'TanStack/table:docs/framework/angular/guide/table-state.md'
+  - 'TanStack/table:examples/angular/basic-external-state'
+  - 'TanStack/table:packages/angular-table/src/injectTable.ts'
+---
+
+This skill builds on `@tanstack/table-core#core` and `getting-started`. Read them first for state ownership and Angular construction.
+
+## State Mental Model
+
+TanStack Table is primarily a state coordinator. Keep state internal unless another system must read, persist, or drive it. Without `initialState`, `atoms`, `state`, or `on[State]Change`, the table owns all registered slices.
+
+- `table.baseAtoms` are internal writable atoms initialized from resolved initial state.
+- `table.atoms` are readonly derived atoms for the active owner of each registered slice.
+- `table.store` combines those atoms into one readonly flat store.
+
+The Angular adapter backs atoms with Angular signals. Reads participate in tracking inside templates, `computed`, and `effect`; signal reads inside the `injectTable` initializer also rerun that initializer and call `setOptions`. State is feature-based: missing pagination state or APIs indicate a missing `rowPaginationFeature`. Hoist stable `features` and `columns` outside the initializer, and return signal-backed `data` without mapping or slicing inline.
+
+## Setup
+
+```ts
+import { computed, signal } from '@angular/core'
+import {
+  injectTable,
+  rowPaginationFeature,
+  tableFeatures,
+} from '@tanstack/angular-table'
+
+const features = tableFeatures({ rowPaginationFeature })
+const columns = [{ accessorKey: 'name' }]
+
+export class TableComponent {
+  readonly data = signal([{ name: 'Ada' }])
+  readonly table = injectTable(() => ({ features, columns, data: this.data() }))
+  readonly pageIndex = computed(
+    () => this.table.atoms.pagination.get().pageIndex,
+  )
+}
+```
+
+Angular-backed table atom reads are signal reads. Templates, `computed`, and `effect` track them directly.
+
+## Core Patterns
+
+### Prefer external atoms for cross-system state
+
+```ts
+import { createAtom } from '@tanstack/angular-store'
+import type { PaginationState } from '@tanstack/angular-table'
+
+readonly paginationAtom = createAtom<PaginationState>({ pageIndex: 0, pageSize: 20 })
+readonly table = injectTable(() => ({
+  features, columns, data: this.data(), atoms: { pagination: this.paginationAtom },
+}))
+```
+
+The atom can feed Query without making every state write rerun the Table initializer.
+
+### Resolve controlled signal updaters
+
+```ts
+readonly pagination = signal({ pageIndex: 0, pageSize: 20 })
+readonly table = injectTable(() => ({
+  features, columns, data: this.data(), state: { pagination: this.pagination() },
+  onPaginationChange: next => typeof next === 'function' ? this.pagination.update(next) : this.pagination.set(next),
+}))
+```
+
+## Choose State Ownership
+
+Use one owner for each slice:
+
+- Prefer internal state and feature APIs for local interaction.
+- Use `initialState` for starting/reset values; later changes do not reset current state.
+- Prefer a stable atom from `@tanstack/angular-store` in `atoms` for Query or other cross-system state. Table APIs update it without a change callback.
+- Use an Angular signal read in `state.<slice>` plus the matching callback for simple controlled state. Handle raw values and updater functions.
+
+External atoms win over controlled `state`, which syncs into the internal base atom. Do not give a slice two owners. The global v8 `onStateChange` option is gone; subscribe to `table.store` when all state changes must be observed.
+
+## Initialize, Update, and Reset
+
+Prefer feature methods such as `setSorting`, `nextPage`, `toggleVisibility`, and `toggleSelected`. Direct base-atom writes are a rare escape hatch for internal state; write the external atom when it owns a slice.
+
+```ts
+this.table.resetSorting()
+this.table.resetPagination()
+this.table.resetPagination(true)
+```
+
+Feature resets use `table.initialState` unless `true` requests the feature default, and can update external owners. Core `table.reset()` resets internal base atoms only. Use feature-specific types such as `PaginationState`; use `TableState<typeof features>` when the complete registered state type is needed.
+
+## Common Mistakes
+
+### MEDIUM Wrapping atoms redundantly
+
+Wrong:
+
+```ts
+readonly pagination = computed(() => computed(() => this.table.atoms.pagination.get())())
+```
+
+Correct:
+
+```ts
+readonly pagination = computed(() => this.table.atoms.pagination.get())
+```
+
+Table atoms already bridge to Angular signals; one tracked read is sufficient.
+
+Source: `docs/framework/angular/guide/table-state.md`
+
+### HIGH Ignoring initializer reruns
+
+Wrong:
+
+```ts
+injectTable(() => ({
+  features: tableFeatures({ rowPaginationFeature }),
+  columns: makeColumns(),
+  state: { pagination: this.pagination() },
+  data,
+}))
+```
+
+Correct:
+
+```ts
+injectTable(() => ({
+  features,
+  columns,
+  state: { pagination: this.pagination() },
+  data,
+}))
+```
+
+Controlled signal writes rerun the initializer, so static work must remain outside it.
+
+Source: `packages/angular-table/src/injectTable.ts`
+
+### HIGH Storing updater functions
+
+Wrong:
+
+```ts
+onPaginationChange: (next) => this.pagination.set(next)
+```
+
+Correct:
+
+```ts
+onPaginationChange: (next) =>
+  typeof next === 'function'
+    ? this.pagination.update(next)
+    : this.pagination.set(next)
+```
+
+Callbacks receive a value or updater; assigning the function corrupts owned state.
+
+Source: `examples/angular/basic-external-state/src/app/app.ts`
+
+### MEDIUM Giving one slice multiple owners
+
+Wrong:
+
+```ts
+{ initialState: { pagination: start }, atoms: { pagination: this.paginationAtom } }
+```
+
+Correct:
+
+```ts
+{
+  atoms: {
+    pagination: this.paginationAtom
+  }
+}
+```
+
+External atoms/state override initial state; choose one owner for each slice.
+
+Source: `docs/framework/angular/guide/table-state.md`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/angular-table/src/injectTable.ts` and `reactivity.ts`; inspect `@tanstack/angular-store/src` for external atoms and installed core feature source for state APIs.

package/skills/with-tanstack-query/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: with-tanstack-query
+description: >
+  Compose Angular Query with signal-owned Table filtering, sorting, and pagination state using reactive query options, manual row-model boundaries, direct query data, server counts, and valid injection context.
+metadata:
+  type: composition
+  library: '@tanstack/angular-table'
+  framework: angular
+  library_version: '9.0.0-beta.43'
+requires:
+  - '@tanstack/table-core#client-vs-server'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:examples/angular/with-tanstack-query'
+  - 'TanStack/table:docs/framework/angular/guide/table-state.md'
+  - 'TanStack/table:docs/framework/angular/guide/pagination.md'
+---
+
+This skill builds on `@tanstack/table-core#client-vs-server`, `getting-started`, and `table-state`. Decide the server-owned stages and dataset before wiring Query.
+
+## Setup
+
+```ts
+import {
+  injectQuery,
+  keepPreviousData,
+} from '@tanstack/angular-query-experimental'
+import { signal } from '@angular/core'
+import {
+  injectTable,
+  rowPaginationFeature,
+  tableFeatures,
+} from '@tanstack/angular-table'
+
+const features = tableFeatures({ rowPaginationFeature })
+const EMPTY_ROWS: never[] = []
+
+export class PeopleTable {
+  readonly pagination = signal({ pageIndex: 0, pageSize: 20 })
+  readonly query = injectQuery(() => ({
+    queryKey: [
+      'people',
+      this.pagination().pageIndex,
+      this.pagination().pageSize,
+    ],
+    queryFn: () =>
+      fetch(
+        `/api/people?page=${this.pagination().pageIndex}&size=${this.pagination().pageSize}`,
+      ).then((r) => r.json()),
+    placeholderData: keepPreviousData,
+  }))
+  readonly table = injectTable(() => ({
+    features,
+    columns,
+    data: this.query.data()?.rows ?? EMPTY_ROWS,
+    rowCount: this.query.data()?.rowCount ?? 0,
+    manualPagination: true,
+    state: { pagination: this.pagination() },
+    onPaginationChange: (next) =>
+      typeof next === 'function'
+        ? this.pagination.update(next)
+        : this.pagination.set(next),
+  }))
+}
+```
+
+## Core Patterns
+
+### Track every server-owned input
+
+Read pagination, sorting, and filtering signals inside `injectQuery(() => ...)` and include them in the query key. Return data already processed for each manual stage.
+
+### Keep Query data authoritative
+
+Read the Query signal directly in `injectTable`. Create another signal only for a deliberate editable draft with an explicit cache synchronization policy.
+
+## Common Mistakes
+
+### HIGH Capturing query inputs outside tracking
+
+Wrong:
+
+```ts
+const page = this.pagination().pageIndex
+readonly query = injectQuery(() => ({ queryKey: ['people', page], queryFn }))
+```
+
+Correct:
+
+```ts
+readonly query = injectQuery(() => ({ queryKey: ['people', this.pagination().pageIndex], queryFn }))
+```
+
+Signal reads inside the options function establish refetch dependencies.
+
+Source: `examples/angular/with-tanstack-query/src/app/app.ts`
+
+### HIGH Expecting manual mode to request
+
+Wrong:
+
+```ts
+injectTable(() => ({ features, columns, data, manualPagination: true }))
+```
+
+Correct:
+
+```ts
+injectTable(() => ({
+  features,
+  columns,
+  data: this.query.data()?.rows ?? EMPTY_ROWS,
+  manualPagination: true,
+}))
+```
+
+Manual flags only bypass client row processing; Query performs network work.
+
+Source: `examples/angular/with-tanstack-query/src/app/app.ts`
+
+### HIGH Omitting total counts
+
+Wrong:
+
+```ts
+{ data: this.query.data()?.rows ?? EMPTY_ROWS, manualPagination: true }
+```
+
+Correct:
+
+```ts
+{ data: this.query.data()?.rows ?? EMPTY_ROWS, rowCount: this.query.data()?.rowCount ?? 0, manualPagination: true }
+```
+
+Table needs `rowCount` or `pageCount` to constrain navigation across server pages.
+
+Source: `docs/framework/angular/guide/pagination.md`
+
+## API Discovery
+
+Inspect installed `@tanstack/angular-table/src/injectTable.ts`, the relevant core feature source, and installed Angular Query source for the exact `injectQuery` package/version contract.

package/skills/with-tanstack-virtual/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: with-tanstack-virtual
+description: >
+  Virtualize Angular Table final row or column models inside the correct injection and reactive lifecycle with signal counts, scroll elements, keys, measurement, transforms, sticky regions, grid/flex sizing, and infinite data.
+metadata:
+  type: composition
+  library: '@tanstack/angular-table'
+  framework: angular
+  library_version: '9.0.0-beta.43'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:docs/framework/angular/guide/virtualization.md'
+  - 'TanStack/table:examples/angular/virtualized-rows'
+  - 'TanStack/table:examples/angular/virtualized-columns'
+  - 'TanStack/table:examples/angular/virtualized-infinite-scrolling'
+---
+
+This skill builds on `@tanstack/table-core#core`, `getting-started`, and `table-state`. Virtual is a rendering concern over final Table models, not a feature plugin.
+
+## Setup
+
+```ts
+import { computed, viewChild } from '@angular/core'
+import { injectVirtualizer } from '@tanstack/angular-virtual'
+import type { ElementRef } from '@angular/core'
+
+export class VirtualTable {
+  readonly scrollElement =
+    viewChild<ElementRef<HTMLDivElement>>('scrollElement')
+  readonly rows = computed(() => this.table.getRowModel().rows)
+  readonly rowVirtualizer = injectVirtualizer(() => ({
+    count: this.rows().length,
+    scrollElement: this.scrollElement()?.nativeElement,
+    estimateSize: () => 34,
+    getItemKey: (index) => this.rows()[index]!.id,
+    overscan: 5,
+  }))
+  readonly virtualRows = computed(() => this.rowVirtualizer.getVirtualItems())
+  readonly totalSize = computed(() => this.rowVirtualizer.getTotalSize())
+}
+```
+
+## Core Patterns
+
+### Derive reactive models
+
+Use `computed(() => table.getRowModel().rows)` and `computed(() => table.getVisibleLeafColumns())`. `injectVirtualizer` tracks signal reads in its initializer and requires injection context.
+
+### Own the layout contract
+
+Give the scroll element bounded overflow, create a total-size spacer, and translate or measure each virtual item. Use grid/flex widths for dynamic rows/columns and keep sticky headers inside the correct scroll geometry.
+
+### Gate infinite fetches
+
+When the last virtual item approaches fetched length, fetch only if more server rows exist and a request is not active. Manual sorting requires server-sorted pages and a reset/refetch policy.
+
+## Common Mistakes
+
+### CRITICAL Constructing outside injection context
+
+Wrong:
+
+```ts
+export function virtualize(options) {
+  return injectVirtualizer(() => options)
+}
+```
+
+Correct:
+
+```ts
+export class VirtualTable {
+  readonly virtualizer = injectVirtualizer(() => options())
+}
+```
+
+The Angular virtualizer follows DI lifecycle rules just like `injectTable`.
+
+Source: `examples/angular/virtualized-rows/src/app/app.ts`
+
+### HIGH Virtualizing raw data
+
+Wrong:
+
+```ts
+readonly rows = computed(() => this.data())
+```
+
+Correct:
+
+```ts
+readonly rows = computed(() => this.table.getRowModel().rows)
+```
+
+Raw data bypasses Table filtering, sorting, expansion, grouping, and pagination.
+
+Source: `docs/framework/angular/guide/virtualization.md`
+
+### HIGH Forgetting spacer and transforms
+
+Wrong:
+
+```html
+@for (item of virtualRows(); track item.key) {
+<div>{{ rows()[item.index].id }}</div>
+}
+```
+
+Correct:
+
+```html
+<div [style.height.px]="totalSize()" style="position:relative">
+  <div style="position:absolute"></div>
+</div>
+```
+
+Virtual computes ranges and sizes but does not apply DOM geometry, sticky CSS, or column widths.
+
+Source: `examples/angular/virtualized-columns/src/app/app.ts`
+
+## API Discovery
+
+Inspect installed `@tanstack/angular-table/src`, installed `@tanstack/angular-virtual/src`, and the maintained Angular examples for current row, column, measurement, and infinite patterns.

package/src/flex-render/flexRenderComponent.ts

@@ -107,13 +107,13 @@ interface FlexRenderOptions<
 }
 
 type Inputs<T> = {
-  [K in keyof T as T[K] extends InputSignal<infer R>
+  [K in keyof T as T[K] extends InputSignal<infer _R>
     ? K
     : never]?: T[K] extends InputSignal<infer R> ? R : never
 }
 
 type Outputs<T> = {
-  [K in keyof T as T[K] extends OutputEmitterRef<infer R>
+  [K in keyof T as T[K] extends OutputEmitterRef<infer _R>
     ? K
     : never]?: T[K] extends OutputEmitterRef<infer R>
     ? OutputEmitterRef<R>['emit']

package/src/flex-render/view.ts

@@ -107,7 +107,7 @@ export class FlexRenderTemplateView extends FlexRenderView<
     super(initialContent, view)
   }
 
-  override updateProps(props: Record<string, any>) {
+  override updateProps(_props: Record<string, any>) {
     this.view.markForCheck()
   }
 

package/src/helpers/cell.ts

@@ -23,7 +23,7 @@ export interface TanStackTableCellContext<
  * This token is provided by the {@link TanStackTableCell} directive.
  */
 export const TanStackTableCellToken = new InjectionToken<
-  TanStackTableCellContext<any, any, any>['cell']
+  TanStackTableCellContext<TableFeatures, RowData, CellData>['cell']
 >('[TanStack Table] CellContext')
 
 /**
@@ -100,5 +100,9 @@ export function injectTableCellContext<
   TData extends RowData,
   TValue extends CellData,
 >(): TanStackTableCellContext<TFeatures, TData, TValue>['cell'] {
-  return inject(TanStackTableCellToken)
+  return inject(TanStackTableCellToken) as unknown as TanStackTableCellContext<
+    TFeatures,
+    TData,
+    TValue
+  >['cell']
 }

package/src/helpers/createTableHook.ts

@@ -28,7 +28,6 @@ import type {
   TableFeature,
   TableFeatures,
   TableOptions,
-  TableState,
 } from '@tanstack/table-core'
 import type { Signal, Type } from '@angular/core'
 
@@ -314,16 +313,16 @@ export type CreateTableHookResult<
     THeaderComponents
   >
   injectTableContext: <TData extends RowData = RowData>() => Signal<
-    AngularTable<TFeatures, TData>
+    AngularTable<TFeatures, TData> & TTableComponents
   >
   injectTableHeaderContext: <
     TValue extends CellData = CellData,
     TRowData extends RowData = RowData,
-  >() => Signal<Header<TFeatures, TRowData, TValue>>
+  >() => Signal<Header<TFeatures, TRowData, TValue> & THeaderComponents>
   injectTableCellContext: <
     TValue extends CellData = CellData,
     TRowData extends RowData = RowData,
-  >() => Signal<Cell<TFeatures, TRowData, TValue>>
+  >() => Signal<Cell<TFeatures, TRowData, TValue> & TCellComponents>
   injectFlexRenderHeaderContext: <
     TData extends RowData,
     TValue extends CellData,
@@ -333,10 +332,7 @@ export type CreateTableHookResult<
     TValue extends CellData,
   >() => CellContext<TFeatures, TData, TValue>
   injectAppTable: <TData extends RowData>(
-    tableOptions: () => Omit<
-      TableOptions<TFeatures, TData>,
-      'features' | 'rowModels'
-    >,
+    tableOptions: () => Omit<TableOptions<TFeatures, TData>, 'features'>,
   ) => AppAngularTable<
     TFeatures,
     TData,
@@ -358,7 +354,6 @@ export type CreateTableHookResult<
  * ```ts
  * const { injectAppTable, createAppColumnHelper } = createTableHook({
  *   features,
- *   rowModels: {},
  *   tableComponents: {},
  *   cellComponents: {},
  *   headerComponents: {},
@@ -387,23 +382,46 @@ export function createTableHook<
   THeaderComponents
 > {
   function injectTableContext<TData extends RowData = RowData>(): Signal<
-    AngularTable<TFeatures, TData>
+    AngularTable<TFeatures, TData> & TTableComponents
   > {
-    return _injectTableContext<TFeatures, TData>()
+    // `injectAppTable` Object.assign-es `tableComponents` onto the same table
+    // instance it returns (via `constructTableAPIs`), and that instance is what
+    // gets provided to DI, so this asserts the runtime shape.
+    return _injectTableContext<TFeatures, TData>() as unknown as Signal<
+      AngularTable<TFeatures, TData> & TTableComponents
+    >
   }
 
   function injectTableHeaderContext<
     TValue extends CellData = CellData,
     TRowData extends RowData = RowData,
-  >(): Signal<Header<TFeatures, TRowData, TValue>> {
-    return _injectTableHeaderContext<TFeatures, TRowData, TValue>()
+  >(): Signal<Header<TFeatures, TRowData, TValue> & THeaderComponents> {
+    // `injectAppTable` Object.assign-es `headerComponents` onto the header
+    // prototype (via `assignHeaderPrototype`), so every header instance carries
+    // them. This asserts the runtime shape.
+    return _injectTableHeaderContext<
+      TFeatures,
+      TRowData,
+      TValue
+    >() as unknown as Signal<
+      Header<TFeatures, TRowData, TValue> & THeaderComponents
+    >
   }
 
   function injectTableCellContext<
     TValue extends CellData = CellData,
     TRowData extends RowData = RowData,
-  >(): Signal<Cell<TFeatures, TRowData, TValue>> {
-    return _injectTableCellContext<TFeatures, TRowData, TValue>()
+  >(): Signal<Cell<TFeatures, TRowData, TValue> & TCellComponents> {
+    // `injectAppTable` Object.assign-es `cellComponents` onto the cell prototype
+    // (via `assignCellPrototype`), so every cell instance carries them. This
+    // asserts the runtime shape.
+    return _injectTableCellContext<
+      TFeatures,
+      TRowData,
+      TValue
+    >() as unknown as Signal<
+      Cell<TFeatures, TRowData, TValue> & TCellComponents
+    >
   }
 
   function injectFlexRenderHeaderContext<
@@ -420,14 +438,8 @@ export function createTableHook<
     return injectFlexRenderContext<CellContext<TFeatures, TData, TValue>>()
   }
 
-  function injectAppTable<
-    TData extends RowData,
-    TSelected = TableState<TFeatures>,
-  >(
-    tableOptions: () => Omit<
-      TableOptions<TFeatures, TData>,
-      'features' | 'rowModels'
-    >,
+  function injectAppTable<TData extends RowData>(
+    tableOptions: () => Omit<TableOptions<TFeatures, TData>, 'features'>,
   ): AppAngularTable<
     TFeatures,
     TData,
@@ -447,7 +459,7 @@ export function createTableHook<
       return footer as Header<TFeatures, TData, any> & THeaderComponents
     }
 
-    const appTableFeatures: TableFeature<{}> = {
+    const appTableFeatures: TableFeature = {
       constructTableAPIs: (table) => {
         Object.assign(table, tableComponents, { appCell, appHeader, appFooter })
       },
@@ -467,8 +479,14 @@ export function createTableHook<
           ...defaultTableOptions.features,
           appTableFeatures,
         },
-      } as TableOptions<TFeatures, TData>
-    }) as AngularTable<any, any>
+      } as unknown as TableOptions<TFeatures, TData>
+    }) as unknown as AppAngularTable<
+      TFeatures,
+      TData,
+      TTableComponents,
+      TCellComponents,
+      THeaderComponents
+    >
   }
 
   function createAppColumnHelper<TData extends RowData>(): AppColumnHelper<

package/src/helpers/flexRenderCell.ts

@@ -94,6 +94,20 @@ export class FlexRenderCell<
       const header = this.header()
       const footer = this.footer()
       if (cell) {
+        const def = cell.column.columnDef
+        const groupingCell = cell as typeof cell & {
+          getIsAggregated?: () => boolean
+          getIsPlaceholder?: () => boolean
+        }
+        const groupingDef = def as typeof def & {
+          aggregatedCell?: typeof def.cell
+        }
+        if (groupingCell.getIsAggregated?.()) {
+          return [groupingDef.aggregatedCell ?? def.cell, cell.getContext()]
+        }
+        if (groupingCell.getIsPlaceholder?.()) {
+          return [null, null]
+        }
         return [cell.column.columnDef.cell, cell.getContext()]
       }
       if (header) {

package/src/helpers/header.ts

@@ -23,7 +23,7 @@ export interface TanStackTableHeaderContext<
  * This token is provided by the {@link TanStackTableHeader} directive.
  */
 export const TanStackTableHeaderToken = new InjectionToken<
-  TanStackTableHeaderContext<any, any, any>['header']
+  TanStackTableHeaderContext<TableFeatures, RowData, CellData>['header']
 >('[TanStack Table] HeaderContext')
 
 /**
@@ -95,5 +95,7 @@ export function injectTableHeaderContext<
   TData extends RowData,
   TValue extends CellData,
 >(): TanStackTableHeaderContext<TFeatures, TData, TValue>['header'] {
-  return inject(TanStackTableHeaderToken)
+  return inject(
+    TanStackTableHeaderToken,
+  ) as unknown as TanStackTableHeaderContext<TFeatures, TData, TValue>['header']
 }