@tanstack/angular-table 9.0.0-beta.38 → 9.0.0-beta.42

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.42'
+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.42'
+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.42'
+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.