@tanstack/angular-table 9.0.0-alpha.47 → 9.0.0-alpha.49

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()`.

package/skills/angular/angular-rendering-directives/references/create-table-hook-registries.md

@@ -0,0 +1,89 @@
+# `createTableHook` — Component Registries Reference
+
+`createTableHook(...)` returns Angular helpers with three optional component
+registries:
+
+| Registry           | Lives on                                                                          | Inject inside it with                                       |
+| ------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `tableComponents`  | `table.<ComponentName>` (the table object)                                        | `injectTableContext()`                                      |
+| `cellComponents`   | the `Cell` prototype (`cell.<ComponentName>` after `table.appCell(cell)`)         | `injectTableCellContext()` (or `injectFlexRenderContext()`) |
+| `headerComponents` | the `Header` prototype (`header.<ComponentName>` after `table.appHeader(header)`) | `injectTableHeaderContext()`                                |
+
+```ts
+import {
+  createTableHook,
+  tableFeatures,
+  rowSortingFeature,
+} from '@tanstack/angular-table'
+import { PaginationControls, RowCount } from './components/table-components'
+import { TextCell, NumberCell, StatusCell } from './components/cell-components'
+import { SortIndicator, ColumnFilter } from './components/header-components'
+
+export const {
+  injectAppTable,
+  createAppColumnHelper,
+  injectTableContext,
+  injectTableCellContext,
+  injectTableHeaderContext,
+} = createTableHook({
+  _features: tableFeatures({ rowSortingFeature }),
+  _rowModels: {
+    /* … */
+  },
+  tableComponents: { PaginationControls, RowCount },
+  cellComponents: { TextCell, NumberCell, StatusCell },
+  headerComponents: { SortIndicator, ColumnFilter },
+})
+```
+
+Use `NgComponentOutlet` to render table components:
+
+```html
+<ng-container *ngComponentOutlet="table.PaginationControls" />
+<ng-container *ngComponentOutlet="table.RowCount" />
+```
+
+Reference cell components from column defs (type-safe through
+`createAppColumnHelper<Person>()`):
+
+```ts
+const columnHelper = createAppColumnHelper<Person>()
+
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    cell: ({ cell }) => cell.TextCell, // ✅ TS autocompletes registered components
+  }),
+  columnHelper.accessor('age', {
+    cell: ({ cell }) => cell.NumberCell,
+  }),
+])
+```
+
+Headers via `table.appHeader(header)`:
+
+```html
+@for (_h of headerGroup.headers; track _h.id) { @let header =
+table.appHeader(_h);
+<th>
+  <ng-container *flexRenderHeader="header; let value">
+    {{ value }}
+  </ng-container>
+  <ng-container
+    *flexRender="header.SortIndicator; props: header.getContext(); let v"
+  >
+    <div [innerHTML]="v"></div>
+  </ng-container>
+</th>
+}
+```
+
+A header component is just an injection-context function or component:
+
+```ts
+export function SortIndicator(): string | null {
+  const header = injectTableHeaderContext()
+  const sorted = header().column.getIsSorted()
+  if (!sorted) return null
+  return sorted === 'asc' ? '🔼' : '🔽'
+}
+```

package/skills/angular/angular-rendering-directives/references/di-tokens.md

@@ -0,0 +1,171 @@
+# DI Tokens & Context Injection — Full Reference
+
+`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                           | Available inside                                                                                       |
+| ------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `injectFlexRenderContext<T>()`              | `T` (full props proxy)            | a component rendered via `*flexRender` / `*flexRenderCell` / `*flexRenderHeader` / `*flexRenderFooter` |
+| `injectTableContext<TData>()`               | `Signal<Table<TFeatures, TData>>` | anything under `[tanStackTable]` or rendered via `*flexRender` whose context has `table`               |
+| `injectTableHeaderContext<TValue, TData>()` | `Signal<Header<...>>`             | anything under `[tanStackTableHeader]` or rendered via `*flexRenderHeader`                             |
+| `injectTableCellContext<TValue, TData>()`   | `Signal<Cell<...>>`               | anything under `[tanStackTableCell]` or rendered via `*flexRenderCell`                                 |
+
+The full props passed via `*flexRender`'s `props:` (or auto-derived by the
+shorthand directives) is wrapped in a `Proxy` so property access always reads
+the _latest_ value across re-renders.
+
+---
+
+## Pattern A — inject inside the rendered component itself
+
+If your component **is** the cell, header, or footer (rendered through
+`*flexRender*`), you don't need any extra directive — the token is auto-provided.
+
+```ts
+@Component({
+  template: `
+    <span>{{ context.getValue() }}</span>
+    <button (click)="context.row.toggleSelected()">Toggle</button>
+  `,
+})
+export class InteractiveCell {
+  readonly context = injectFlexRenderContext<CellContext<any, any, any>>()
+}
+```
+
+Or, for just the cell signal:
+
+```ts
+@Component({ template: `{{ cell().getValue() }}` })
+export class TextCell {
+  readonly cell = injectTableCellContext<string>()
+}
+```
+
+---
+
+## Pattern B — context for _descendants outside the FlexRender tree_
+
+When you have a component that lives next to the `*flexRenderCell` block, or
+when you want any nested element to inject the table/header/cell, use the
+context **host directives**:
+
+```ts
+import {
+  FlexRender,
+  TanStackTable,
+  TanStackTableHeader,
+  TanStackTableCell,
+} from '@tanstack/angular-table'
+
+@Component({
+  imports: [FlexRender, TanStackTable, TanStackTableHeader, TanStackTableCell],
+  templateUrl: './app.html',
+})
+export class App {}
+```
+
+```html
+<table [tanStackTable]="table">
+  @for (headerGroup of table.getHeaderGroups(); track headerGroup.id) {
+  <tr>
+    @for (header of headerGroup.headers; track header.id) {
+    <th [tanStackTableHeader]="header">
+      <ng-container *flexRenderHeader="header; let value">
+        {{ value }}
+      </ng-container>
+      <!-- Any component here can call injectTableHeaderContext() -->
+    </th>
+    }
+  </tr>
+  } @for (row of table.getRowModel().rows; track row.id) {
+  <tr>
+    @for (cell of row.getVisibleCells(); track cell.id) {
+    <td [tanStackTableCell]="cell">
+      <ng-container *flexRenderCell="cell; let value">{{ value }}</ng-container>
+      <app-cell-actions />
+      <!-- ↑ cell-actions calls injectTableCellContext() — no input drilling -->
+    </td>
+    }
+  </tr>
+  }
+</table>
+```
+
+```ts
+@Component({
+  selector: 'app-cell-actions',
+  template: `<button (click)="cell().row.toggleSelected()">Toggle</button>`,
+})
+export class CellActionsComponent {
+  readonly cell = injectTableCellContext()
+}
+```
+
+Each directive uses Angular's `providers` array to register a per-host factory,
+so contexts are correctly scoped — multiple `[tanStackTableCell]` directives on
+sibling cells provide independent values.
+
+---
+
+## `*flexRender` directly (custom props)
+
+Reach for the long form `*flexRender` when:
+
+- You're rendering something that isn't `columnDef.cell` / `header` / `footer`
+  (e.g. a registered `headerComponents` member, see `createTableHook`).
+- You want to override the props passed to the render function.
+
+```html
+<ng-container
+  *flexRender="
+    cell.column.columnDef.cell;
+    props: cell.getContext();
+    let rendered
+  "
+>
+  {{ rendered }}
+</ng-container>
+```
+
+Custom props (e.g. extending the default context):
+
+```html
+<ng-container
+  *flexRender="
+    cell.column.columnDef.cell;
+    props: {
+      ...cell.getContext(),
+      extra: someValue(),
+    };
+    let rendered
+  "
+>
+  {{ rendered }}
+</ng-container>
+```
+
+Inside the rendered component, `injectFlexRenderContext()` returns this full
+props object.
+
+You can also pass `flexRenderInjector:` to override the injector used for
+`createComponent`.
+
+---
+
+## Render-function injection context
+
+Because column-def `cell` / `header` / `footer` functions run inside
+`runInInjectionContext`, this **works** at the top of those functions:
+
+```ts
+cell: ({ getValue }) => {
+  const router = inject(Router) // ✅ legal
+  return router.url.endsWith('/admin') ? `[admin] ${getValue()}` : getValue()
+}
+```
+
+Be deliberate: this runs every time the cell renders. For per-app values that
+don't change, prefer `inject(...)` at the component level and close over.

package/skills/angular/angular-rendering-directives/references/flex-render-component-options.md

@@ -0,0 +1,64 @@
+# `flexRenderComponent` — Full Options Reference
+
+When you need custom inputs not derived from the render context, output
+callbacks, a custom injector, or Angular v20+ `bindings` / `directives`,
+**wrap the component**:
+
+```ts
+import { flexRenderComponent, type ColumnDef } from '@tanstack/angular-table'
+import { EditableCell } from './editable-cell'
+
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  {
+    accessorKey: 'firstName',
+    cell: ({ getValue, row, column, table }) =>
+      flexRenderComponent(EditableCell, {
+        inputs: {
+          value: getValue(),
+        },
+        outputs: {
+          change: (value) => {
+            table.options.meta?.updateData(row.index, column.id, value)
+          },
+        },
+      }),
+  },
+]
+```
+
+## How inputs/outputs are wired
+
+- **`inputs`** → applied via `ComponentRef.setInput(key, value)` (works with
+  both `input()` signals and legacy `@Input()`). Diffed per change-detection
+  cycle with `KeyValueDiffers` — unchanged values are _not_ re-set, so object
+  inputs are reference-checked. Keep input objects referentially stable when
+  you can.
+- **`outputs`** → resolved at component-instance level. The wrapper reads the
+  property by name, checks it is an `OutputEmitterRef`, and subscribes. The
+  subscription is cleaned up when the component is destroyed.
+- **`injector`** → use when the rendered component needs to inject from a
+  specific scope (e.g. a feature module / sub-injector).
+- **`bindings`** (Angular v20+) → forwarded directly to
+  `ViewContainerRef.createComponent` at creation time. Use this with
+  `inputBinding`, `outputBinding`, `twoWayBinding` for native programmatic
+  rendering semantics.
+- **`directives`** (Angular v20+) → host directives forwarded the same way.
+
+```ts
+import { inputBinding, outputBinding, twoWayBinding, signal } from '@angular/core'
+
+readonly name = signal('Ada')
+
+cell: () =>
+  flexRenderComponent(EditableNameCell, {
+    bindings: [
+      inputBinding('value', this.name),
+      twoWayBinding('value', this.name),
+      outputBinding('valueChange', (v) => console.log('changed', v)),
+    ],
+  })
+```
+
+> **Do not mix `bindings` with `inputs`/`outputs`** on the same component.
+> `bindings` apply at creation time and participate in the initial CD cycle;
+> `inputs`/`outputs` apply after. Mixing them risks double-initialization.