@tanstack/angular-table 9.0.0-alpha.9 → 9.0.0-beta.1

package/skills/angular/migrate-v8-to-v9/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: angular/migrate-v8-to-v9
+description: >
+  Mechanical v8 → v9 migration for `@tanstack/angular-table`: `createAngularTable` →
+  `injectTable`, `get*RowModel()` options → `rowModels` factories with explicit `*Fns`,
+  required `features` via `tableFeatures()`, state access via `table.atoms.<slice>.get()`
+  or `table.state` instead of `table.getState()`, `createColumnHelper<TFeatures, TData>()` generic-order flip, every
+  type now requires `TFeatures`, `enablePinning` split into `enableColumnPinning` /
+  `enableRowPinning`, `sortingFn` → `sortFn` rename pile, `ColumnSizingInfo` → `ColumnResizing`
+  split, removal of `_`-prefixed internals, signal-backed atoms replacing v8 memoized accessors,
+  and structural-directive rendering replacing v8 component-based rendering.
+type: lifecycle
+library: tanstack-table
+framework: angular
+library_version: '9.0.0-alpha.48'
+requires:
+  - angular/table-state
+  - angular/getting-started
+  - angular/angular-rendering-directives
+sources:
+  - TanStack/table:docs/framework/angular/guide/migrating.md
+  - TanStack/table:docs/framework/angular/angular-table.md
+  - TanStack/table:packages/angular-table/src/injectTable.ts
+  - TanStack/table:packages/angular-table/src/reactivity.ts
+---
+
+# Migrate from TanStack Table v8 to v9 (Angular)
+
+> **Angular does not ship a legacy v8 API in v9** (unlike React's
+> `useLegacyTable`). You migrate directly to v9's `injectTable` + `features` +
+> `rowModels` shape. There is no incremental in-place adapter — the public
+> entrypoint name itself changes.
+
+This skill is a mechanical translation table. Work through it top-to-bottom.
+
+For exhaustive lookup tables (row-model mapping, feature registration, type
+generics, sorting renames, sizing-vs-resizing split, etc.) →
+[`references/v8-to-v9-mapping.md`](references/v8-to-v9-mapping.md).
+
+---
+
+## 1. Entrypoint rename
+
+```ts
+// v8
+import { createAngularTable, getCoreRowModel } from '@tanstack/angular-table'
+
+const v8Table = createAngularTable(() => ({
+  columns,
+  data: data(),
+  getCoreRowModel: getCoreRowModel(),
+}))
+
+// v9
+import { injectTable, tableFeatures } from '@tanstack/angular-table'
+
+const features = tableFeatures({}) // empty is valid; core row model is automatic
+
+const v9Table = injectTable(() => ({
+  features,
+  rowModels: {},
+  columns,
+  data: data(),
+}))
+```
+
+Key behavioral change: **the `injectTable` initializer re-runs when signals
+inside it change**, then the adapter calls `table.setOptions({ ...prev, ...new })`.
+Move stable values (`columns`, `features`, `rowModels`) **outside** the
+initializer so they aren't recreated on every data update.
+
+---
+
+## 2. Required new options: `features` + `rowModels`
+
+v9 is opt-in for every feature. **Both options are required.**
+
+```ts
+// v8 — features were bundled, row models added piecewise
+createAngularTable(() => ({
+  columns,
+  data: data(),
+  getCoreRowModel: getCoreRowModel(),
+  getFilteredRowModel: getFilteredRowModel(),
+  getSortedRowModel: getSortedRowModel(),
+  getPaginationRowModel: getPaginationRowModel(),
+  filterFns, // root option
+  sortingFns, // root option
+}))
+
+// v9
+import {
+  injectTable,
+  tableFeatures,
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowPaginationFeature,
+  createFilteredRowModel,
+  createSortedRowModel,
+  createPaginatedRowModel,
+  filterFns,
+  sortFns, // note rename: sortingFns → sortFns
+} from '@tanstack/angular-table'
+
+const features = tableFeatures({
+  columnFilteringFeature,
+  rowSortingFeature,
+  rowPaginationFeature,
+})
+
+injectTable(() => ({
+  features,
+  rowModels: {
+    filteredRowModel: createFilteredRowModel(filterFns), // fns are PARAMETERS now
+    sortedRowModel: createSortedRowModel(sortFns),
+    paginatedRowModel: createPaginatedRowModel(),
+  },
+  columns,
+  data: data(),
+}))
+```
+
+Row-model and feature lookup tables → [`references/v8-to-v9-mapping.md`](references/v8-to-v9-mapping.md#row-model-migration-table).
+
+---
+
+## 3. State access: `getState()` → atoms or `table.state`
+
+```ts
+// v8
+const { sorting, pagination } = table.getState()
+
+// v9 — full-state flat proxy
+const { sorting, pagination } = table.state
+
+// v9 — per slice (preferred for Angular render code)
+const sorting = table.atoms.sorting.get()
+const pagination = table.atoms.pagination.get()
+```
+
+In Angular, all three (`table.atoms.<slice>`, `table.state`,
+`table.baseAtoms.<slice>`) are signal-backed — reading them inside a template,
+`computed(...)`, or `effect(...)` registers an Angular dependency
+automatically. No `toSignal(...)` wrappers needed. Prefer direct atom reads for
+specific slices; keep `table.state` for full-state JSON/debug output or code
+that genuinely wants the flat state shape.
+
+See `tanstack-table/angular/table-state` for the full state surface mental
+model.
+
+---
+
+## 4. Controlled state — `on[State]Change` shape
+
+The shape is largely the same. **`onStateChange` (the single global v8 hook) is
+gone in v9.** Slices are controlled individually via `state.<slice>` +
+`on[State]Change` callbacks. Each callback receives either a new value or an
+updater function:
+
+```ts
+// v9 pattern
+import { signal } from '@angular/core'
+import type { SortingState, PaginationState } from '@tanstack/angular-table'
+
+readonly sorting = signal<SortingState>([])
+readonly pagination = signal<PaginationState>({ pageIndex: 0, pageSize: 10 })
+
+readonly table = injectTable(() => ({
+  features,
+  rowModels: { /* … */ },
+  columns,
+  data: this.data(),
+  state: {
+    sorting: this.sorting(),
+    pagination: this.pagination(),
+  },
+  onSortingChange: (updater) => {
+    updater instanceof Function
+      ? this.sorting.update(updater)
+      : this.sorting.set(updater)
+  },
+  onPaginationChange: (updater) => {
+    updater instanceof Function
+      ? this.pagination.update(updater)
+      : this.pagination.set(updater)
+  },
+}))
+```
+
+> Always check `updater instanceof Function` (or `typeof updater === 'function'`).
+> TanStack Table calls the callback with both shapes depending on the
+> transition.
+
+---
+
+## 5. Column helper generic-order flip
+
+```ts
+// v8
+const columnHelper = createColumnHelper<Person>()
+
+// v9 — TFeatures FIRST, then TData
+const columnHelper = createColumnHelper<typeof features, Person>()
+```
+
+New in v9: `columnHelper.columns([...])` preserves each column's `TValue` —
+prefer it over a bare array literal:
+
+```ts
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    header: 'First',
+    cell: (i) => i.getValue(),
+  }),
+  columnHelper.display({
+    id: 'actions',
+    header: 'Actions',
+    cell: () => 'Edit',
+  }),
+])
+```
+
+If you don't want to repeat `TFeatures` everywhere, use `createTableHook(...)`
+and the resulting `createAppColumnHelper<Person>()` which pre-binds features.
+
+Every public type now requires `TFeatures` (`ColumnDef<TFeatures, TData, TValue>`,
+`Cell<TFeatures, TData, TValue>`, etc.). Full mapping →
+[`references/v8-to-v9-mapping.md`](references/v8-to-v9-mapping.md#type-generics--every-type-takes-tfeatures-now).
+
+---
+
+## 6. Rendering — directive-based, with shorthand directives
+
+v8 Angular rendering was already directive-flavored, but v9 adds the
+**shorthand directives** (`*flexRenderCell`, `*flexRenderHeader`,
+`*flexRenderFooter`) that auto-resolve the column-def slot and context. Prefer
+them over the long `*flexRender="… ; props: …"` form.
+
+```html
+<!-- v8 / v9 long form (still works) -->
+<td
+  *flexRender="cell.column.columnDef.cell; props: cell.getContext(); let rendered"
+>
+  {{ rendered }}
+</td>
+
+<!-- v9 shorthand — recommended -->
+<td *flexRenderCell="cell; let value">{{ value }}</td>
+<th *flexRenderHeader="header; let value">{{ value }}</th>
+<th *flexRenderFooter="footer; let value">{{ value }}</th>
+```
+
+```ts
+import { FlexRender } from '@tanstack/angular-table' // ← imports both directives
+@Component({ imports: [FlexRender], ... })
+```
+
+v9-only:
+
+- `flexRenderComponent(Component, { inputs, outputs, bindings, directives, injector })`
+  for explicit component rendering.
+- DI tokens (`TanStackTable` / `TanStackTableHeader` / `TanStackTableCell`
+  directives + `injectTableContext()` / `injectTableHeaderContext()` /
+  `injectTableCellContext()` / `injectFlexRenderContext()`) — no more input
+  drilling.
+- Column-def `cell` / `header` / `footer` functions run inside
+  `runInInjectionContext`, so `inject(...)` and signals work in them.
+
+See `tanstack-table/angular/angular-rendering-directives` for the full surface.
+
+---
+
+## 7. Reactivity model — signals replace v8 memo accessors
+
+v8 backed reactivity with manual memoized getters. v9's adapter
+(`angularReactivity(injector)`) backs every readonly atom with an Angular
+`computed` and every writable atom with an Angular `signal`. Consequences:
+
+- **No `toSignal(...)` adapters around table state.** Read `table.atoms.x.get()`
+  directly inside templates, `computed`, `effect` for specific slices. Use
+  `table.state` when you need the full-state flat shape.
+- **`computed(...)` is for derivation / equality, not for "make it reactive".**
+  Use `{ equal: shallow }` from `@tanstack/angular-table` on object/array
+  slices to skip downstream work on no-op updates.
+- **The `injectTable` initializer re-runs on signal changes.** Don't put
+  expensive object literals in there.
+
+---
+
+## 8. Renames at a glance
+
+- `sortingFn` → `sortFn`, `sortingFns` → `sortFns`, `SortingFn` → `SortFn`
+  (full table in [`references/v8-to-v9-mapping.md`](references/v8-to-v9-mapping.md#naming-renames--sorting)).
+- `enablePinning` → `enableColumnPinning` / `enableRowPinning` (split).
+- `columnSizingInfo` state → `columnResizing` state (sizing/resizing split into
+  two features — see [`references/v8-to-v9-mapping.md`](references/v8-to-v9-mapping.md#column-sizing-vs-resizing--split)).
+- All `_`-prefixed internal APIs removed; use the public equivalents.
+
+---
+
+## Migration checklist
+
+- [ ] Replace `createAngularTable` import + call with `injectTable`.
+- [ ] Add `features: tableFeatures({...})` (or `stockFeatures`) — required.
+- [ ] Convert every `get*RowModel()` option to a `rowModels.<slot>` entry with
+      the matching `create*RowModel(...)` factory.
+- [ ] Add `filterFns` / `sortFns` / `aggregationFns` as **factory parameters**
+      where needed.
+- [ ] Update `createColumnHelper<Person>()` → `createColumnHelper<typeof features, Person>()`.
+- [ ] Update every `ColumnDef<Person>` / `Cell<Person, X>` etc. to include
+      `TFeatures`.
+- [ ] Replace `table.getState().slice` reads with `table.atoms.<slice>.get()`
+      where possible; use `table.state` for full-state/debug reads.
+- [ ] Remove any usage of the v8 single `onStateChange` — split into per-slice
+      `on[State]Change`.
+- [ ] In `on[State]Change` callbacks, handle both value and updater-fn shapes.
+- [ ] Move `columns`, `features`, `rowModels` **outside** the `injectTable`
+      initializer.
+- [ ] Switch any `flexRender` long-form to `*flexRenderCell` / `*flexRenderHeader` /
+      `*flexRenderFooter` shorthand where applicable.
+- [ ] Where you need component rendering with explicit options, switch wrapper
+      shape to `flexRenderComponent(Component, { inputs, outputs, ... })`.
+- [ ] Replace prop-drilled cell/header inputs with
+      `injectTableCellContext()` / `injectTableHeaderContext()` /
+      `injectFlexRenderContext()` (optional but worthwhile).
+- [ ] Rename `sortingFn` → `sortFn`, `getSortingFn` → `getSortFn`,
+      `sortingFns` → `sortFns`, `SortingFn` → `SortFn`.
+- [ ] Replace `columnSizingInfo` state / setters / change handler with the
+      `columnResizing` equivalents; add `columnResizingFeature` to `features`
+      if you actually drag-resize.
+- [ ] Replace `enablePinning` with `enableColumnPinning` / `enableRowPinning`.
+- [ ] Update `ColumnMeta` module augmentation to include the `TFeatures`
+      generic.
+- [ ] Drop any `_`-prefixed internal API usages; replace with public
+      equivalents.
+- [ ] (Optional) Adopt `tableOptions(...)` for shared base config.
+- [ ] (Optional) Adopt `createTableHook(...)` for app-wide table infrastructure.
+
+---
+
+## Failure modes
+
+### 1. (CRITICAL) Leaving `getCoreRowModel()` / `getSortedRowModel()` / etc. in v9 options
+
+These options don't exist anymore. They become `rowModels` entries with
+factory functions. The TypeScript error is loud but agents sometimes silence
+it with `as any` — don't.
+
+### 2. (CRITICAL) Reaching for `createAngularTable` from v8 muscle memory
+
+Always `injectTable(() => ({...}))`. The injection-context requirement means
+it must run from a class field, constructor, or
+`runInInjectionContext(injector, () => injectTable(...))`.
+
+### 3. (CRITICAL) Registering a feature but forgetting its row model
+
+```ts
+// ❌ filtering enabled, but no filtered row model — UI changes, rows don't filter
+features: tableFeatures({ columnFilteringFeature })
+rowModels: {
+} // missing filteredRowModel
+
+// ✅
+rowModels: {
+  filteredRowModel: createFilteredRowModel(filterFns)
+}
+```
+
+Same for sorting, pagination, expanding, grouping, faceting. Selection,
+visibility, ordering, pinning, sizing, resizing do **not** need a row model.
+
+### 4. (HIGH) `getState()` → `table.state` text replacement can be too broad
+
+Bulk-replacing `table.getState().x` with `table.state.x` works for _current
+value_ reads, but it hides which slice the component depends on. For Angular
+render code and reactive derivations, switch to `table.atoms.x.get()` — it's
+already signal-backed and needs no wrapper. Keep `table.state` for full-state
+debug output.
+
+### 5. (HIGH) Stale `sortingFn` / `sortingFns` references in column defs
+
+The rename is mechanical: `sortingFn` → `sortFn`, `sortingFns` → `sortFns`,
+`getSortingFn` → `getSortFn`. Missed renames produce silent runtime fallbacks
+to default sort.
+
+### 6. (HIGH) Column helper using v8 generic order
+
+```ts
+// ❌ TS will complain — the first generic is TFeatures, not TData
+const columnHelper = createColumnHelper<Person>()
+```
+
+### 7. (HIGH) Putting `features` / `columns` / row-model factories inside the `injectTable` initializer
+
+The v8 mental model was "build columns inside the hook". v9's
+`injectTable` initializer re-runs on every signal read change — keep heavy
+literals outside.
+
+Lower-severity failure modes (MEDIUM/LOW: `stockFeatures` cleanup, `enablePinning`
+removal, `columnSizingInfo` rename, single-handler porting, hand-rolled
+`TFeatures` in render fns, `_`-prefix internal usage, reimplementing built-in
+APIs, `ColumnMeta` augmentation drift, `flexRender` as a function, mixing v8/v9
+atoms) → [`references/v8-to-v9-mapping.md`](references/v8-to-v9-mapping.md#lower-severity-failure-modes-mediumlow).
+
+---
+
+## References
+
+- [Full v8 → v9 mapping tables (row models, features, types, renames, MEDIUM failure modes)](references/v8-to-v9-mapping.md)
+
+---
+
+## See also
+
+- `tanstack-table/angular/getting-started` — what the v9 target shape looks like
+- `tanstack-table/angular/table-state` — signal-backed atom model
+- `tanstack-table/angular/angular-rendering-directives` — full rendering API
+- `tanstack-table/angular/production-readiness` — once compiling, optimize the bundle
+- `tanstack-table/core/migrate-v8-to-v9` — framework-agnostic core changes

package/skills/angular/migrate-v8-to-v9/references/v8-to-v9-mapping.md

@@ -0,0 +1,261 @@
+# v8 → v9 Mapping Tables — Full Reference
+
+Mechanical translation tables and detailed renames for the Angular Table v8 →
+v9 migration. The SKILL.md keeps the primary patterns; this file is the
+exhaustive lookup.
+
+---
+
+## Row-model migration table
+
+| v8 option                  | v9 `rowModels` key    | v9 factory                              |
+| -------------------------- | --------------------- | --------------------------------------- |
+| `getCoreRowModel()`        | (automatic)           | —                                       |
+| `getFilteredRowModel()`    | `filteredRowModel`    | `createFilteredRowModel(filterFns)`     |
+| `getSortedRowModel()`      | `sortedRowModel`      | `createSortedRowModel(sortFns)`         |
+| `getPaginationRowModel()`  | `paginatedRowModel`   | `createPaginatedRowModel()`             |
+| `getExpandedRowModel()`    | `expandedRowModel`    | `createExpandedRowModel()`              |
+| `getGroupedRowModel()`     | `groupedRowModel`     | `createGroupedRowModel(aggregationFns)` |
+| `getFacetedRowModel()`     | `facetedRowModel`     | `createFacetedRowModel()`               |
+| `getFacetedMinMaxValues()` | `facetedMinMaxValues` | `createFacetedMinMaxValues()`           |
+| `getFacetedUniqueValues()` | `facetedUniqueValues` | `createFacetedUniqueValues()`           |
+
+## Feature registration table
+
+| v8 (implicit)   | v9 feature import         |
+| --------------- | ------------------------- |
+| filter columns  | `columnFilteringFeature`  |
+| global filter   | `globalFilteringFeature`  |
+| sort rows       | `rowSortingFeature`       |
+| pagination      | `rowPaginationFeature`    |
+| row selection   | `rowSelectionFeature`     |
+| expanding rows  | `rowExpandingFeature`     |
+| pin rows        | `rowPinningFeature`       |
+| pin columns     | `columnPinningFeature`    |
+| hide columns    | `columnVisibilityFeature` |
+| reorder columns | `columnOrderingFeature`   |
+| size columns    | `columnSizingFeature`     |
+| resize columns  | `columnResizingFeature`   |
+| group columns   | `columnGroupingFeature`   |
+| facet columns   | `columnFacetingFeature`   |
+
+> If you don't want to think about tree-shaking yet, you can pass
+> `stockFeatures`:
+>
+> ```ts
+> import { stockFeatures } from '@tanstack/angular-table'
+> features: stockFeatures
+> ```
+>
+> This restores v8-like "everything bundled" behavior — but the v9 bundle
+> wins are gone. Plan to migrate to a curated `tableFeatures({...})` as part of
+> productionization.
+
+---
+
+## Type generics — every type takes `TFeatures` now
+
+```txt
+v8                                  v9
+---                                 ---
+Column<TData>                      → Column<TFeatures, TData, TValue>
+ColumnDef<TData>                   → ColumnDef<TFeatures, TData, TValue>
+Table<TData>                       → Table<TFeatures, TData>
+Row<TData>                         → Row<TFeatures, TData>
+Cell<TData, TValue>                → Cell<TFeatures, TData, TValue>
+Header<TData, TValue>              → Header<TFeatures, TData, TValue>
+HeaderContext<TData, TValue>       → HeaderContext<TFeatures, TData, TValue>
+CellContext<TData, TValue>         → CellContext<TFeatures, TData, TValue>
+```
+
+Easiest fix: extract `typeof features` once.
+
+```ts
+const features = tableFeatures({ rowSortingFeature, columnFilteringFeature })
+
+type Features = typeof features
+
+const columns: Array<ColumnDef<Features, Person>> = [
+  /* … */
+]
+```
+
+If you're on `stockFeatures`:
+
+```ts
+import type { StockFeatures, ColumnDef } from '@tanstack/angular-table'
+const columns: Array<ColumnDef<StockFeatures, Person>> = [
+  /* … */
+]
+```
+
+`ColumnMeta` module augmentation also needs `TFeatures`:
+
+```ts
+declare module '@tanstack/angular-table' {
+  interface ColumnMeta<
+    TFeatures extends TableFeatures,
+    TData extends RowData,
+    TValue,
+  > {
+    align?: 'left' | 'right'
+  }
+}
+```
+
+---
+
+## Naming renames — sorting
+
+| v8                                  | v9                       |
+| ----------------------------------- | ------------------------ |
+| `sortingFn` (column-def field)      | `sortFn`                 |
+| `column.getSortingFn()`             | `column.getSortFn()`     |
+| `column.getAutoSortingFn()`         | `column.getAutoSortFn()` |
+| `SortingFn` type                    | `SortFn`                 |
+| `SortingFns` interface              | `SortFns`                |
+| `sortingFns` (built-in fn registry) | `sortFns`                |
+
+Find-and-replace, then update `createSortedRowModel(sortFns)`.
+
+---
+
+## Column sizing vs resizing — split
+
+v8 combined sizing and resizing into one feature. v9 splits them so you can
+ship only what you use.
+
+| v8                                | v9                                                         |
+| --------------------------------- | ---------------------------------------------------------- |
+| `ColumnSizing` (single feature)   | `columnSizingFeature` + `columnResizingFeature` (separate) |
+| `columnSizingInfo` state          | `columnResizing` state                                     |
+| `setColumnSizingInfo()`           | `setColumnResizing()`                                      |
+| `onColumnSizingInfoChange` option | `onColumnResizingChange` option                            |
+
+If you only render fixed-width columns and never drag-to-resize, import only
+`columnSizingFeature`.
+
+---
+
+## Pinning option split
+
+```ts
+// v8
+enablePinning: true
+
+// v9 — explicit
+enableColumnPinning: true
+enableRowPinning: true
+```
+
+---
+
+## Row API: privates promoted to public
+
+| v8                                       | v9                                     |
+| ---------------------------------------- | -------------------------------------- |
+| `row._getAllCellsByColumnId()` (private) | `row.getAllCellsByColumnId()` (public) |
+
+All other `_`-prefixed internal APIs from v8 are removed in v9 — use the
+public equivalents. If you were touching `_`-prefixed members, you were on
+unsupported territory; v9 forces the fix.
+
+---
+
+## `tableOptions(...)` — new composition helper
+
+v9 ships `tableOptions(...)` for type-safe partial option composition. Useful
+during migration if you have shared base config:
+
+```ts
+import { tableOptions, tableFeatures, rowSortingFeature } from '@tanstack/angular-table'
+
+const baseOptions = tableOptions({
+  features: tableFeatures({ rowSortingFeature }),
+  debugTable: isDevMode(),
+})
+
+readonly table = injectTable(() => ({
+  ...baseOptions,
+  rowModels: { /* … */ },
+  columns: this.columns,
+  data: this.data(),
+}))
+```
+
+And for whole-app patterns, `createTableHook(...)` — see
+`tanstack-table/angular/angular-rendering-directives`.
+
+---
+
+## `RowData` type tightened
+
+`RowData` is now stricter (object-like; no primitives). If you had
+`type Row = string`, that won't fly in v9 — wrap it in an object.
+
+---
+
+## Lower-severity failure modes (MEDIUM/LOW)
+
+### Skipping `stockFeatures` cleanup later
+
+Using `stockFeatures` is a fine migration shortcut, but it forgoes the v9
+bundle wins. Once everything compiles, swap `stockFeatures` for an explicit
+`tableFeatures({...})` listing only the features you use.
+
+### Forgetting `enablePinning` is gone
+
+`enablePinning: true` silently does nothing. Use `enableColumnPinning: true`
+and/or `enableRowPinning: true`.
+
+### Forgetting `columnSizingInfo` is gone
+
+Replace state name `columnSizingInfo` with `columnResizing`, setter
+`setColumnSizingInfo` with `setColumnResizing`, handler
+`onColumnSizingInfoChange` with `onColumnResizingChange`. And add
+`columnResizingFeature` to `features` if you actually need resizing.
+
+### Single global `onStateChange` ported as a giant per-slice fan-out
+
+In v9 each slice has its own callback. If you previously used `onStateChange`
+to multiplex changes, port to the specific `on[State]Change` callbacks you
+actually care about — don't recreate a megaswitch.
+
+### Hand-rolling `TFeatures` in render-fn types
+
+When a `cell` / `header` function signature requires `CellContext<TFeatures, TData, TValue>`,
+let `createColumnHelper<typeof features, TData>()` infer it for you. Spelling
+features by hand in dozens of render-fn signatures is a sign you should be
+using `createAppColumnHelper` from `createTableHook`.
+
+### Reaching for `_`-prefixed internals because the public method "doesn't exist"
+
+The "missing" method usually means the feature isn't in `features`. Add the
+feature; don't peek at internals.
+
+### Reimplementing what the table API already does
+
+Symptoms of v8 muscle memory carrying through:
+
+- Manually sorting the data signal in `effect(...)` instead of
+  `table.setSorting(...)` and using `table.getRowModel().rows`.
+- Manually paginating the rows array instead of using `paginatedRowModel`.
+- Hand-rolling `getSelectedRowModel().flatRows` from a `rowSelection` signal.
+
+If a v8 escape hatch was needed because of a bug or missing API, check the v9
+public API first — many things were added in v9.
+
+### `ColumnMeta` augmentation without the `TFeatures` generic
+
+The interface now takes `TFeatures` first. Old declarations get silently merged
+but typed wrong.
+
+### Importing `flexRender` as a function
+
+There's no `flexRender(fn, ctx)` in Angular. `FlexRender` is a directive tuple
+constant. Imports + template directive form is the only shape.
+
+### Trying to share v9 atoms with v8 — incompatible
+
+If you have a partial v8 codebase coexisting, **don't** try to bridge atoms
+across the version boundary. Migrate per-component.