@tanstack/angular-table 9.0.0-alpha.5 → 9.0.0-alpha.52

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@tanstack/angular-table",
-  "version": "9.0.0-alpha.5",
+  "version": "9.0.0-alpha.52",
   "description": "Headless UI for building powerful tables & datagrids for Angular.",
   "author": "Tanner Linsley",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/TanStack/table.git",
+    "url": "git+https://github.com/TanStack/table.git",
     "directory": "packages/angular-table"
   },
   "homepage": "https://tanstack.com/table",
@@ -18,16 +18,23 @@
     "angular",
     "table",
     "angular-table",
-    "datagrid"
+    "datagrid",
+    "tanstack-intent"
   ],
   "type": "module",
-  "module": "dist/esm2022/index.mjs",
-  "types": "dist/index.d.ts",
+  "module": "dist/fesm2022/tanstack-angular-table.mjs",
+  "types": "dist/types/tanstack-angular-table.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "esm": "./dist/esm2022/index.mjs",
-      "esm2022": "./dist/esm2022/index.mjs",
+      "types": "./dist/types/tanstack-angular-table.d.ts",
+      "default": "./dist/fesm2022/tanstack-angular-table.mjs"
+    },
+    "./static-functions": {
+      "types": "./dist/types/tanstack-angular-table-static-functions.d.ts",
+      "default": "./dist/fesm2022/tanstack-angular-table-static-functions.mjs"
+    },
+    "./flex-render": {
+      "types": "./dist/types/tanstack-angular-table.d.ts",
       "default": "./dist/fesm2022/tanstack-angular-table.mjs"
     },
     "./package.json": {
@@ -35,26 +42,39 @@
     }
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=18"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "static-functions",
+    "skills"
   ],
   "dependencies": {
-    "tslib": "^2.6.3",
-    "@tanstack/table-core": "9.0.0-alpha.4"
+    "@tanstack/angular-store": "^0.11.0",
+    "tslib": "^2.8.1",
+    "@tanstack/table-core": "9.0.0-alpha.52"
   },
   "devDependencies": {
-    "@analogjs/vite-plugin-angular": "^1.5.0",
-    "@angular/core": "^18.0.3",
-    "@angular/platform-browser": "^18.0.3",
-    "@angular/platform-browser-dynamic": "^18.0.3",
-    "ng-packagr": "^18.0.0"
+    "@analogjs/vite-plugin-angular": "^2.5.2",
+    "@analogjs/vitest-angular": "^2.5.2",
+    "@angular/core": "^21.2.15",
+    "@angular/platform-browser": "^21.2.15",
+    "ng-packagr": "^21.2.3",
+    "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "@angular/core": ">=17"
+    "@angular/core": ">=19"
   },
   "sideEffects": false,
-  "scripts": {}
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json -c tsconfig.build.json && rimraf ./dist/package.json",
+    "build:types": "tsc --emitDeclarationOnly",
+    "clean": "rimraf ./build && rimraf ./dist",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "vitest --watch",
+    "test:types": "tsc && vitest --typecheck"
+  }
 }

package/skills/angular/angular-rendering-directives/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: angular/angular-rendering-directives
+description: >
+  Angular's structural-directive rendering pipeline for TanStack Table v9. Covers `FlexRender`
+  (`*flexRender`), the shorthand directives `*flexRenderCell` / `*flexRenderHeader` /
+  `*flexRenderFooter`, the `flexRenderComponent(Component, { inputs, outputs, bindings, directives, injector })`
+  wrapper, DI tokens `TanStackTableToken` / `TanStackTableHeaderToken` / `TanStackTableCellToken`
+  with their `injectTableContext()` / `injectTableHeaderContext()` / `injectTableCellContext()`
+  helpers, the `[tanStackTable]` / `[tanStackTableHeader]` / `[tanStackTableCell]` host directives,
+  `injectFlexRenderContext()`, automatic token injection inside `*flexRender`, and the four
+  content shapes (primitive, `TemplateRef`, component type, `flexRenderComponent` wrapper).
+type: framework
+library: tanstack-table
+framework: angular
+library_version: '9.0.0-alpha.48'
+requires:
+  - angular/table-state
+  - column-definitions
+sources:
+  - TanStack/table:docs/framework/angular/guide/rendering.md
+  - TanStack/table:packages/angular-table/src/flexRender.ts
+  - TanStack/table:packages/angular-table/src/helpers/flexRenderCell.ts
+  - TanStack/table:packages/angular-table/src/helpers/cell.ts
+  - TanStack/table:packages/angular-table/src/helpers/header.ts
+  - TanStack/table:packages/angular-table/src/helpers/table.ts
+  - TanStack/table:packages/angular-table/src/flex-render/flexRenderComponent.ts
+  - TanStack/table:packages/angular-table/src/flex-render/context.ts
+  - TanStack/table:packages/angular-table/src/flex-render/renderer.ts
+  - TanStack/table:examples/angular/basic-inject-table/
+  - TanStack/table:examples/angular/editable/
+  - TanStack/table:examples/angular/row-selection-signal/
+  - TanStack/table:examples/angular/composable-tables/
+---
+
+# Angular Rendering Directives (v9)
+
+> **This skill is Angular-only.** Agents trained on React/Vue copy the wrong
+> pattern here — there is no `flexRender(cell.column.columnDef.cell, cell.getContext())`
+> call expression in Angular. Rendering is **structural-directive based**:
+> `*flexRender`, `*flexRenderCell`, `*flexRenderHeader`, `*flexRenderFooter`.
+>
+> Read `tanstack-table/angular/table-state` first.
+
+---
+
+## 1. Setup: the single import — `FlexRender`
+
+`FlexRender` is exported as a _tuple_ of two directives so a single import gets
+you everything:
+
+```ts
+import { FlexRender } from '@tanstack/angular-table'
+
+@Component({
+  imports: [FlexRender], // imports BOTH FlexRenderDirective + FlexRenderCell
+  templateUrl: './app.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class App {}
+```
+
+`FlexRender` ≡ `[FlexRenderDirective, FlexRenderCell] as const`. Prefer this over
+importing the individual directives — it survives future additions.
+
+Tokens / context directives (`TanStackTable`, `TanStackTableHeader`,
+`TanStackTableCell`) are separate imports — add them only when you use them.
+
+---
+
+## 2. The shorthand directives — your default
+
+For standard header / cell / footer rendering, **prefer the shorthand directives**.
+They resolve `columnDef.cell` / `columnDef.header` / `columnDef.footer` and the
+right context for you, so you don't write `props:` by hand.
+
+| Directive                               | Input    | Resolves                                   |
+| --------------------------------------- | -------- | ------------------------------------------ |
+| `*flexRenderCell="cell; let value"`     | `Cell`   | `columnDef.cell` + `cell.getContext()`     |
+| `*flexRenderHeader="header; let value"` | `Header` | `columnDef.header` + `header.getContext()` |
+| `*flexRenderFooter="footer; let value"` | `Header` | `columnDef.footer` + `header.getContext()` |
+
+```html
+<table>
+  <thead>
+    @for (headerGroup of table.getHeaderGroups(); track headerGroup.id) {
+    <tr>
+      @for (header of headerGroup.headers; track header.id) {
+      <th>
+        @if (!header.isPlaceholder) {
+        <ng-container *flexRenderHeader="header; let value">
+          {{ value }}
+        </ng-container>
+        }
+      </th>
+      }
+    </tr>
+    }
+  </thead>
+
+  <tbody>
+    @for (row of table.getRowModel().rows; track row.id) {
+    <tr>
+      @for (cell of row.getVisibleCells(); track cell.id) {
+      <td>
+        <ng-container *flexRenderCell="cell; let value">
+          {{ value }}
+        </ng-container>
+      </td>
+      }
+    </tr>
+    }
+  </tbody>
+
+  <tfoot>
+    @for (footerGroup of table.getFooterGroups(); track footerGroup.id) {
+    <tr>
+      @for (footer of footerGroup.headers; track footer.id) {
+      <th *flexRenderFooter="footer; let value">{{ value }}</th>
+      }
+    </tr>
+    }
+  </tfoot>
+</table>
+```
+
+The shorthand selector matches on `ng-template[flexRenderCell]`, so applying it
+to a `<td>` host (`<td *flexRenderCell="cell; let value">`) desugars to an
+`<ng-template>` Angular renders inside the `<td>`. Both forms are valid.
+
+---
+
+## 3. The four content shapes a column def can produce
+
+`columnDef.cell` / `header` / `footer` can return any of these — `FlexRender`
+dispatches on the shape:
+
+| Returned value                                          | Renderer behavior                                                                                |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| **Primitive** (`string`, `number`, `null`, `undefined`) | implicit `$implicit` value via `createEmbeddedView`.                                             |
+| **`TemplateRef`**                                       | render context passed as `$implicit`.                                                            |
+| **Component type** (`Type<T>`)                          | `createComponent`; context properties forwarded via `setInput(...)` to matching `input()` slots. |
+| **`flexRenderComponent(Component, options)`**           | `createComponent` with explicit `inputs`, `outputs`, `bindings`, `directives`, `injector`.       |
+
+Render functions run inside `runInInjectionContext`, so you can call `inject()`,
+read signals, and access DI tokens from within `cell: () => …`.
+
+See [`references/content-shapes.md`](references/content-shapes.md) for full
+worked examples of each shape (primitives, `TemplateRef` via `viewChild`,
+returning component classes with `input()` slots).
+
+---
+
+## 4. The primitive cell pattern
+
+The 90% case — return a value, render it.
+
+```ts
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  {
+    accessorKey: 'firstName',
+    header: 'First name',
+    cell: (info) => info.getValue(),
+  },
+]
+```
+
+```html
+<td *flexRenderCell="cell; let value">{{ value }}</td>
+```
+
+---
+
+## 5. Component cells: pass-through vs `flexRenderComponent`
+
+### Pass-through — return the component class
+
+```ts
+@Component({
+  selector: 'app-select-all',
+  template: `
+    <input
+      type="checkbox"
+      [checked]="table().getIsAllRowsSelected()"
+      (change)="table().toggleAllRowsSelected()"
+    />
+  `,
+})
+export class SelectAllComponent<T> {
+  readonly table = input.required<Table<any, T>>()
+}
+
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  {
+    id: 'select',
+    header: () => SelectAllComponent,
+    cell: () => RowSelectComponent,
+  },
+]
+```
+
+The renderer calls `setInput(name, value)` for every property on the render
+context — declare `input()` / `input.required()` for the names you need.
+
+### `flexRenderComponent(Component, options)` — explicit wiring
+
+Reach for the wrapper when you need custom inputs not on the context, output
+callbacks, a custom injector, or Angular v20+ `bindings` / `directives`:
+
+```ts
+import { flexRenderComponent } from '@tanstack/angular-table'
+
+cell: ({ getValue, row, column, table }) =>
+  flexRenderComponent(EditableCell, {
+    inputs: { value: getValue() },
+    outputs: {
+      change: (value) =>
+        table.options.meta?.updateData(row.index, column.id, value),
+    },
+  })
+```
+
+Full option semantics (how `inputs` diff, how `outputs` resolve `OutputEmitterRef`,
+when to use `bindings` vs `inputs`, and the v20+ `inputBinding` / `twoWayBinding`
+API) → [`references/flex-render-component-options.md`](references/flex-render-component-options.md).
+
+---
+
+## 6. DI tokens & context injection — the prop-drill killer
+
+`FlexRender` automatically provides DI tokens for the render context to any
+component rendered through `*flexRender` / `*flexRenderCell` / etc. The renderer
+inspects the props object — if it has `table`, `header`, or `cell`, it
+provides the matching token in the child injector.
+
+| Helper                                      | Returns                           |
+| ------------------------------------------- | --------------------------------- |
+| `injectFlexRenderContext<T>()`              | `T` (full props proxy)            |
+| `injectTableContext<TData>()`               | `Signal<Table<TFeatures, TData>>` |
+| `injectTableHeaderContext<TValue, TData>()` | `Signal<Header<...>>`             |
+| `injectTableCellContext<TValue, TData>()`   | `Signal<Cell<...>>`               |
+
+### Pattern A — inside the rendered component itself (auto-provided)
+
+```ts
+@Component({ template: `{{ cell().getValue() }}` })
+export class TextCell {
+  readonly cell = injectTableCellContext<string>()
+}
+```
+
+### Pattern B — for descendants outside the FlexRender tree
+
+Apply `[tanStackTable]`, `[tanStackTableHeader]`, or `[tanStackTableCell]` on
+the host element to make the token available to children that aren't rendered
+through `*flexRender*`:
+
+```html
+<td [tanStackTableCell]="cell">
+  <ng-container *flexRenderCell="cell; let value">{{ value }}</ng-container>
+  <app-cell-actions />
+  <!-- ↑ calls injectTableCellContext() — no input drilling -->
+</td>
+```
+
+Full directive shapes, scoping rules, `*flexRender` long-form, custom
+`flexRenderInjector:`, and `runInInjectionContext` behavior in column defs →
+[`references/di-tokens.md`](references/di-tokens.md).
+
+---
+
+## 7. The `track` value matters
+
+Angular `@for` requires `track` and TanStack Table gives you stable IDs. Use
+them:
+
+```html
+@for (headerGroup of table.getHeaderGroups(); track headerGroup.id) { ... } @for
+(header of headerGroup.headers; track header.id) { ... } @for (row of
+table.getRowModel().rows; track row.id) { ... } @for (cell of
+row.getVisibleCells(); track cell.id) { ... } @for (footerGroup of
+table.getFooterGroups(); track footerGroup.id) { ... }
+```
+
+`row.id` defaults to row index; provide `getRowId: (row) => row.id` in your
+table options when you have a stable primary key (required for stable row
+selection across re-fetches, see `compose-with-tanstack-query`).
+
+---
+
+## 8. `createTableHook` — registering components for whole-app use
+
+`createTableHook(...)` accepts three optional component registries
+(`tableComponents`, `cellComponents`, `headerComponents`) that become
+type-safe members on `table.<Name>`, `cell.<Name>`, `header.<Name>`. Use them
+to standardize cell/header/control components across an app while keeping
+column defs short and typed.
+
+```ts
+export const { injectAppTable, createAppColumnHelper } = createTableHook({
+  _features: tableFeatures({ rowSortingFeature }),
+  _rowModels: {
+    /* … */
+  },
+  tableComponents: { PaginationControls, RowCount },
+  cellComponents: { TextCell, NumberCell, StatusCell },
+  headerComponents: { SortIndicator, ColumnFilter },
+})
+```
+
+Full registry semantics, `table.appCell(cell)` / `table.appHeader(header)`
+narrowing, `NgComponentOutlet` usage, and worked examples →
+[`references/create-table-hook-registries.md`](references/create-table-hook-registries.md).
+
+---
+
+## Failure modes
+
+### 1. (CRITICAL) Copying React/Vue's `flexRender(fn, ctx)` call into Angular
+
+```ts
+// ❌ This is the React/Vue pattern — no such call expression exists in Angular
+{{ flexRender(cell.column.columnDef.cell, cell.getContext()) }}
+
+// ✅ Angular is directive-based
+<td *flexRenderCell="cell; let value">{{ value }}</td>
+```
+
+If an agent imports `flexRender` as a function from `@tanstack/angular-table`,
+they've crossed wires. `FlexRender` in Angular is a **directive tuple constant**
+used in `imports: [FlexRender]`.
+
+### 2. (CRITICAL) Returning a component without `input()` slots
+
+```ts
+@Component({ template: `{{ row.original.firstName }}` })
+export class NameCell {
+  row: any
+} // ❌ no input() — `row` is never set
+```
+
+The renderer calls `setInput('row', cell.row)`. Without `row = input<Row<any, any>>()`,
+the property stays `undefined`. Either:
+
+- declare `input()` / `input.required()` for the context properties you need, or
+- use `injectFlexRenderContext()` / `injectTableCellContext()` for the full
+  proxy.
+
+### 3. (CRITICAL) Reaching for `flexRenderComponent` for plain pass-through
+
+If you don't need custom inputs/outputs/bindings/injector, **return the
+component class directly** and let the renderer wire context inputs. Reserve
+`flexRenderComponent(...)` for the cases that need explicit options.
+
+```ts
+// Plain pass-through — no wrapper needed
+cell: () => TextCellComponent
+
+// Wrapper needed — custom inputs/outputs
+cell: ({ getValue }) =>
+  flexRenderComponent(EditableCell, {
+    inputs: { value: getValue() },
+    outputs: { change: (v) => {} },
+  })
+```
+
+### 4. (HIGH) Mixing `flexRenderComponent`'s `bindings` with `inputs` / `outputs`
+
+`bindings` apply at component creation; `inputs`/`outputs` apply imperatively
+after. Mixing them on the same property double-initializes the input or
+conflicts the output. Pick one mechanism per component.
+
+### 5. (HIGH) Forgetting `@if (!header.isPlaceholder)` for grouped/spanned headers
+
+Grouped column defs produce placeholder headers in some header rows. Rendering
+their `header` definition there is wrong. Always guard:
+
+```html
+@if (!header.isPlaceholder) {
+<ng-container *flexRenderHeader="header; let value">{{ value }}</ng-container>
+}
+```
+
+### 6. (MEDIUM) Drilling cell/header inputs through layers of wrapper components
+
+The whole point of `[tanStackTableCell]` / `[tanStackTableHeader]` / `[tanStackTable]`
+plus the inject helpers is to **stop input drilling**. If you find yourself
+passing `cell` (or any context) through 3 component layers, replace it with
+`injectTableCellContext()` at the leaf.
+
+### 7. (MEDIUM) Assuming `injectTableCellContext()` works outside the FlexRender tree without the directive
+
+The token is provided automatically inside `*flexRenderCell` / `*flexRender`
+(when context has `cell`). For a sibling component in the same `<td>` that is
+**not** rendered through `*flexRender*`, you must apply `[tanStackTableCell]="cell"`
+on the host to make the token available. Same rule for header and table.
+
+---
+
+## References
+
+- [Full content shape reference (primitive / TemplateRef / component class)](references/content-shapes.md)
+- [`flexRenderComponent` options reference (inputs/outputs/bindings/injector)](references/flex-render-component-options.md)
+- [DI tokens & host directives — patterns A & B, `*flexRender` long-form](references/di-tokens.md)
+- [`createTableHook` component registries (table/cell/header)](references/create-table-hook-registries.md)
+
+---
+
+## See also
+
+- `tanstack-table/angular/table-state` — state model & `injectTable`
+- `tanstack-table/angular/getting-started` — end-to-end first table
+- `tanstack-table/core/column-definitions` — `cell` / `header` / `footer`
+  function signatures (framework-agnostic)
+- `tanstack-table/angular/migrate-v8-to-v9` — `FlexRenderDirective` →
+  `*flexRender` shorthand evolution

package/skills/angular/angular-rendering-directives/references/content-shapes.md

@@ -0,0 +1,142 @@
+# Content Shapes — Full Reference
+
+`columnDef.cell` / `header` / `footer` can return any of these — `FlexRender`
+dispatches on the shape:
+
+| Returned value                                          | Renderer behavior                                                                                                                                                                       |
+| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Primitive** (`string`, `number`, `null`, `undefined`) | `createEmbeddedView` on the host `ng-template`; value is the implicit `$implicit` (so `let value` gets the primitive).                                                                  |
+| **`TemplateRef`**                                       | `createEmbeddedView` of the template; the render context (`CellContext` / `HeaderContext`) is passed as `$implicit`.                                                                    |
+| **Component type** (`Type<T>`)                          | `createComponent` via `ViewContainerRef`; every property of the render context is forwarded via `ComponentRef.setInput(...)` to matching `input()` / `@Input()` slots on the component. |
+| **`flexRenderComponent(Component, options)`** wrapper   | `createComponent`, applying the wrapper's explicit `inputs`, `outputs`, `bindings`, `directives`, and optional `injector`.                                                              |
+
+Render functions run inside `runInInjectionContext`, so you can call `inject()`,
+read signals, and access DI tokens from within `cell: () => …`.
+
+---
+
+## Returning a primitive
+
+The most common cell — read the value and return it.
+
+```ts
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  {
+    accessorKey: 'firstName',
+    header: 'First name',
+    cell: (info) => info.getValue(),
+  },
+  {
+    accessorKey: 'age',
+    header: () => 'Age',
+    cell: (info) => info.getValue(),
+  },
+]
+```
+
+Use the template's `let value` for the primitive:
+
+```html
+<td *flexRenderCell="cell; let value">{{ value }}</td>
+```
+
+If the primitive is HTML you trust, use `[innerHTML]`:
+
+```html
+<td *flexRenderCell="cell; let value">
+  <div [innerHTML]="value"></div>
+</td>
+```
+
+---
+
+## Returning a `TemplateRef`
+
+Capture a template with `viewChild(...)`, then return it from the column def.
+The render context arrives as `$implicit`, so use `let context`:
+
+```ts
+import { Component, TemplateRef, viewChild } from '@angular/core'
+import type {
+  CellContext,
+  ColumnDef,
+  HeaderContext,
+} from '@tanstack/angular-table'
+
+@Component({
+  template: `
+    <ng-template #ageHeader let-context>
+      Age (sorted: {{ context.column.getIsSorted() }})
+    </ng-template>
+
+    <ng-template #ageCell let-context>
+      <strong>{{ context.getValue() }}</strong>
+    </ng-template>
+  `,
+})
+export class App {
+  readonly ageHeader =
+    viewChild.required<
+      TemplateRef<{ $implicit: HeaderContext<any, any, any> }>
+    >('ageHeader')
+  readonly ageCell =
+    viewChild.required<TemplateRef<{ $implicit: CellContext<any, any, any> }>>(
+      'ageCell',
+    )
+
+  readonly columns: Array<ColumnDef<any, any>> = [
+    {
+      accessorKey: 'age',
+      header: () => this.ageHeader(),
+      cell: () => this.ageCell(),
+    },
+  ]
+}
+```
+
+`TemplateRef` rendering creates an injector that includes the DI context tokens,
+so descendants inside the template can call `injectTableCellContext()`,
+`injectTableHeaderContext()`, etc.
+
+For reusable render blocks shared across screens, prefer a component over a
+`TemplateRef`.
+
+---
+
+## Returning an Angular component
+
+You can return a component class directly. The renderer calls `setInput(name, value)`
+for every property on the render context — define `input()` (or
+`input.required()`) signals matching the names you want.
+
+```ts
+import { Component, input } from '@angular/core'
+import type { ColumnDef, Table } from '@tanstack/angular-table'
+
+@Component({
+  selector: 'app-select-all',
+  template: `
+    <input
+      type="checkbox"
+      [checked]="table().getIsAllRowsSelected()"
+      [indeterminate]="table().getIsSomeRowsSelected()"
+      (change)="table().toggleAllRowsSelected()"
+    />
+  `,
+})
+export class SelectAllComponent<T> {
+  readonly table = input.required<Table<any, T>>()
+}
+
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  {
+    id: 'select',
+    header: () => SelectAllComponent,
+    cell: () => RowSelectComponent,
+  },
+]
+```
+
+> **Only inputs declared with `input()` / `input.required()` are set.** Other
+> context properties are silently ignored at the input-binding level — but they
+> are still reachable via `injectFlexRenderContext()`.