@tanstack/preact-table 9.0.0-alpha.46 → 9.0.0-alpha.48

package/skills/preact/getting-started/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: preact/getting-started
+description: >
+  End-to-end first-table journey for `@tanstack/preact-table` v9: install the
+  adapter, declare `_features` via `tableFeatures()`, declare `_rowModels` with
+  their factories and *Fns parameters, build a typed column helper, call
+  `useTable` with stable references, and render with `table.FlexRender`.
+  Routing keywords: install preact-table, first table, getting started,
+  tableFeatures, _features, _rowModels, useTable, FlexRender, basic-use-table.
+type: lifecycle
+library: tanstack-table
+framework: preact
+library_version: '9.0.0-alpha.47'
+requires:
+  - setup
+  - column-definitions
+  - state-management
+  - preact/table-state
+sources:
+  - TanStack/table:docs/installation.md
+  - TanStack/table:docs/framework/preact/preact-table.md
+  - TanStack/table:examples/preact/basic-use-table/src/main.tsx
+  - TanStack/table:packages/preact-table/src/useTable.ts
+---
+
+This skill walks through a first working Preact v9 table end-to-end. It assumes you have read `tanstack-table/setup` and `tanstack-table/state-management` for core concepts and `tanstack-table/preact/table-state` for adapter wiring.
+
+## Install
+
+`@tanstack/preact-table` is the Preact adapter. It pulls in `@tanstack/table-core` and `@tanstack/preact-store` (used internally for atom-backed state).
+
+```bash
+npm install @tanstack/preact-table
+```
+
+Peer dependency: `preact >=10`.
+
+Source: `packages/preact-table/package.json`.
+
+## Step 1 — Declare `_features`
+
+v9 is explicit about what a table uses. `_features` is a registry of every feature the table needs. Use `tableFeatures({...})` to get an object whose TypeScript shape drives state inference, API surface, and tree-shaking.
+
+```tsx
+import {
+  tableFeatures,
+  rowPaginationFeature,
+  rowSortingFeature,
+} from '@tanstack/preact-table'
+
+const _features = tableFeatures({
+  rowPaginationFeature,
+  rowSortingFeature,
+})
+```
+
+If `_features` does not include `rowSelectionFeature`, then `table.atoms.rowSelection`, `table.setRowSelection`, `table.getIsAllRowsSelected()`, etc. all become TypeScript errors — and the runtime won't ship that logic. Pass `tableFeatures({})` for a minimum-overhead table with just the core row model.
+
+Source: `docs/framework/preact/preact-table.md`; `docs/guide/features.md`.
+
+## Step 2 — Declare `_rowModels`
+
+Each registered feature that needs a row-model stage maps to a factory under `_rowModels`. The factory takes a record of \*Fns (predicates, comparators, etc.) for that stage.
+
+```tsx
+import {
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+} from '@tanstack/preact-table'
+
+const _rowModels = {
+  paginatedRowModel: createPaginatedRowModel(),
+  sortedRowModel: createSortedRowModel(sortFns),
+}
+```
+
+The core row model is always included — `_rowModels: {}` is valid for a feature-free table.
+
+Source: `docs/framework/preact/preact-table.md`.
+
+## Step 3 — Type your data and build columns
+
+Declare your row shape once and feed it to `createColumnHelper<typeof _features, TData>()`. This is the type-safe path; `ColumnDef<typeof _features, Person>[]` also works.
+
+```tsx
+import { createColumnHelper, type ColumnDef } from '@tanstack/preact-table'
+
+type Person = {
+  firstName: string
+  lastName: string
+  age: number
+  visits: number
+  status: string
+  progress: number
+}
+
+const columnHelper = createColumnHelper<typeof _features, Person>()
+
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    header: 'First Name',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor('lastName', { header: () => <span>Last Name</span> }),
+  columnHelper.accessor('age', { header: 'Age' }),
+  columnHelper.accessor('visits', { header: 'Visits' }),
+  columnHelper.accessor('status', { header: 'Status' }),
+  columnHelper.accessor('progress', { header: 'Profile Progress' }),
+])
+```
+
+Source: `examples/preact/basic-use-table/src/main.tsx`.
+
+## Step 4 — Call `useTable` and render
+
+`useTable` takes options and an optional selector. Render headers, cells, and footers with `table.FlexRender` so column defs can be strings or Preact components.
+
+```tsx
+import { render } from 'preact'
+import { useState } from 'preact/hooks'
+import { useTable } from '@tanstack/preact-table'
+
+const defaultData: Person[] = [
+  {
+    firstName: 'tanner',
+    lastName: 'linsley',
+    age: 24,
+    visits: 100,
+    status: 'In Relationship',
+    progress: 50,
+  },
+  {
+    firstName: 'kevin',
+    lastName: 'vandy',
+    age: 12,
+    visits: 100,
+    status: 'Single',
+    progress: 70,
+  },
+]
+
+function App() {
+  const [data] = useState(() => [...defaultData])
+
+  const table = useTable(
+    {
+      _features,
+      _rowModels,
+      columns,
+      data,
+      debugTable: true,
+    },
+    (state) => state, // default selector
+  )
+
+  return (
+    <table>
+      <thead>
+        {table.getHeaderGroups().map((hg) => (
+          <tr key={hg.id}>
+            {hg.headers.map((h) => (
+              <th key={h.id} onClick={h.column.getToggleSortingHandler()}>
+                {h.isPlaceholder ? null : <table.FlexRender header={h} />}
+              </th>
+            ))}
+          </tr>
+        ))}
+      </thead>
+      <tbody>
+        {table.getRowModel().rows.map((row) => (
+          <tr key={row.id}>
+            {row.getAllCells().map((cell) => (
+              <td key={cell.id}>
+                <table.FlexRender cell={cell} />
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+      <tfoot>
+        {table.getFooterGroups().map((fg) => (
+          <tr key={fg.id}>
+            {fg.headers.map((h) => (
+              <th key={h.id}>
+                {h.isPlaceholder ? null : <table.FlexRender footer={h} />}
+              </th>
+            ))}
+          </tr>
+        ))}
+      </tfoot>
+    </table>
+  )
+}
+
+render(<App />, document.getElementById('root')!)
+```
+
+Source: `examples/preact/basic-use-table/src/main.tsx`.
+
+## Step 5 — Drive features with feature APIs
+
+Reach for `table.setSorting(...)`, `table.setPageIndex(...)`, `table.nextPage()`, `column.toggleVisibility()`, `row.toggleSelected()`, etc. — never edit `table.store.state` directly.
+
+```tsx
+<button onClick={() => table.setPageIndex(0)} disabled={!table.getCanPreviousPage()}>First</button>
+<button onClick={() => table.nextPage()}      disabled={!table.getCanNextPage()}>Next</button>
+```
+
+For starting values, use `initialState`. For controlled slices, use `atoms` (preferred) or `state` + `on*Change` — see `tanstack-table/preact/table-state`.
+
+## Common Mistakes
+
+### CRITICAL Calling a feature API when the feature is not in `_features`
+
+Wrong:
+
+```tsx
+const _features = tableFeatures({}) // no rowPaginationFeature
+const table = useTable({ _features, _rowModels: {}, columns, data })
+
+table.setPageIndex(0) // TypeScript error AND runtime no-op
+```
+
+Correct:
+
+```tsx
+const _features = tableFeatures({ rowPaginationFeature })
+const table = useTable({
+  _features,
+  _rowModels: { paginatedRowModel: createPaginatedRowModel() },
+  columns,
+  data,
+})
+
+table.setPageIndex(0)
+```
+
+v9 generates feature APIs and state slices only for registered features. The missing-feature failure mode (calling `setSorting`, accessing `state.pagination`, etc. before registering the feature) is the #1 v9 trap.
+Source: `docs/guide/features.md`; `docs/framework/preact/guide/table-state.md`.
+
+### HIGH Forgetting the matching row-model factory
+
+Wrong:
+
+```tsx
+const _features = tableFeatures({ rowSortingFeature })
+const table = useTable({ _features, _rowModels: {}, columns, data })
+table.setSorting([{ id: 'age', desc: true }])
+// table.getRowModel().rows is still unsorted — no sortedRowModel registered
+```
+
+Correct:
+
+```tsx
+const _features = tableFeatures({ rowSortingFeature })
+const table = useTable({
+  _features,
+  _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+  columns,
+  data,
+})
+```
+
+Each row-model feature (sorting, filtering, pagination, grouping, expanding, faceting) requires its row-model factory in `_rowModels` to actually transform the rows.
+Source: `docs/framework/preact/preact-table.md`.
+
+### HIGH Unstable `_features` / `columns` / `data` references
+
+Wrong:
+
+```tsx
+function MyTable({ rows }) {
+  const _features = tableFeatures({ rowSortingFeature }) // new every render
+  const columns = [
+    /* … */
+  ] // new every render
+  const data = rows ?? [] // new [] every render
+  const table = useTable({ _features, _rowModels: {}, columns, data })
+}
+```
+
+Correct:
+
+```tsx
+const _features = tableFeatures({ rowSortingFeature })
+const columns: ColumnDef<typeof _features, Person>[] = [
+  /* … */
+]
+const EMPTY: Person[] = []
+
+function MyTable({ rows }) {
+  const data = rows ?? EMPTY
+  const table = useTable({ _features, _rowModels: {}, columns, data })
+}
+```
+
+Internal memos key off identity. Fresh references bust everything every render.
+Source: `docs/framework/preact/guide/table-state.md` (FAQ #1).
+
+### HIGH Reimplementing built-in feature logic
+
+Wrong:
+
+```tsx
+const sorted = useMemo(() => [...data].sort(/* … */), [data, sorting]) // duplicates rowSortingFeature
+```
+
+Correct:
+
+```tsx
+const _features = tableFeatures({ rowSortingFeature })
+const table = useTable({
+  _features,
+  _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+  columns,
+  data,
+})
+const rows = table.getRowModel().rows // already sorted
+```
+
+v9 ships built-ins for sorting, filtering, pagination, grouping, expanding, faceting, row selection, column visibility/order/pinning/sizing, and row pinning. Use them.
+Source: `docs/guide/features.md`.
+
+### MEDIUM Using v8 hook names (`getCoreRowModel`, `useReactTable`, etc.)
+
+Wrong:
+
+```tsx
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+} from '@tanstack/preact-table'
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getSortedRowModel: getSortedRowModel(),
+})
+```
+
+Correct:
+
+```tsx
+import {
+  useTable,
+  tableFeatures,
+  rowSortingFeature,
+  createSortedRowModel,
+  sortFns,
+} from '@tanstack/preact-table'
+
+const _features = tableFeatures({ rowSortingFeature })
+
+const table = useTable({
+  _features,
+  _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+  columns,
+  data,
+})
+```
+
+v8 used `useReactTable` and `get*RowModel` options. v9 uses `useTable` plus `_features` + `_rowModels`. See `tanstack-table/preact/migrate-v8-to-v9` for the full mapping.
+Source: `docs/framework/preact/preact-table.md`.
+
+## See Also
+
+- `tanstack-table/preact/table-state` — atoms, Subscribe, createTableHook.
+- `tanstack-table/preact/migrate-v8-to-v9` — moving an existing v8 codebase over.
+- `tanstack-table/preact/production-readiness` — perf, tree-shaking, stable refs.

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

@@ -0,0 +1,322 @@
+---
+name: preact/migrate-v8-to-v9
+description: >
+  Mechanical breaking-change migration from TanStack Table v8 to v9 for
+  `@tanstack/preact-table`. Maps every old-shaped option, helper, type, and
+  method an agent will reproduce from v8 muscle memory to its v9 equivalent:
+  `useReactTable` → `useTable`, per-row-model `get*RowModel` options →
+  `_features` + `_rowModels`, plain column helpers → typed column helpers,
+  `state` + `on*Change` → `atoms`, `flexRender` → `table.FlexRender`, and core
+  type renames. Routing keywords: v8 to v9, migration, useReactTable, table
+  v8 preact, get*RowModel, _features.
+type: lifecycle
+library: tanstack-table
+framework: preact
+library_version: '9.0.0-alpha.47'
+requires:
+  - setup
+  - state-management
+  - column-definitions
+sources:
+  - TanStack/table:docs/framework/preact/preact-table.md
+  - TanStack/table:docs/framework/preact/guide/table-state.md
+  - TanStack/table:docs/framework/react/guide/use-legacy-table.md
+  - TanStack/table:packages/preact-table/src/useTable.ts
+---
+
+The Preact adapter mirrors the React v9 surface, so any v8 → v9 migration guide for React applies almost line-for-line. There is no `useLegacyTable` shim in `@tanstack/preact-table` — migrate directly.
+
+## The Core Mapping
+
+| v8 (Preact / React-compatible)                                           | v9 (`@tanstack/preact-table`)                                                                                                                                                                                                            |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useReactTable(opts)`                                                    | `useTable(opts, selector?)`                                                                                                                                                                                                              |
+| `getCoreRowModel: getCoreRowModel()`                                     | included by default — `_rowModels: {}` is valid                                                                                                                                                                                          |
+| `getSortedRowModel: getSortedRowModel()`                                 | `_features: { rowSortingFeature }` + `_rowModels: { sortedRowModel: createSortedRowModel(sortFns) }`                                                                                                                                     |
+| `getFilteredRowModel: getFilteredRowModel()`                             | `_features: { columnFilteringFeature, globalFilteringFeature }` + `_rowModels: { filteredRowModel: createFilteredRowModel(filterFns) }`                                                                                                  |
+| `getPaginationRowModel: getPaginationRowModel()`                         | `_features: { rowPaginationFeature }` + `_rowModels: { paginatedRowModel: createPaginatedRowModel() }`                                                                                                                                   |
+| `getGroupedRowModel: getGroupedRowModel()`                               | `_features: { columnGroupingFeature }` + `_rowModels: { groupedRowModel: createGroupedRowModel(aggregationFns) }`                                                                                                                        |
+| `getExpandedRowModel: getExpandedRowModel()`                             | `_features: { rowExpandingFeature }` + `_rowModels: { expandedRowModel: createExpandedRowModel() }`                                                                                                                                      |
+| `getFacetedRowModel`, `getFacetedUniqueValues`, `getFacetedMinMaxValues` | `_features: { columnFacetingFeature, globalFacetingFeature }` + `_rowModels: { facetedRowModel: createFacetedRowModel(facetedFns), facetedUniqueValues: createFacetedUniqueValues(), facetedMinMaxValues: createFacetedMinMaxValues() }` |
+| `flexRender(def, ctx)`                                                   | `<table.FlexRender cell={cell} />` / `header={...}` / `footer={...}`                                                                                                                                                                     |
+| `state`, `on*Change` (only)                                              | still supported, plus `atoms` (preferred per slice)                                                                                                                                                                                      |
+| `createColumnHelper<TData>()`                                            | `createColumnHelper<typeof _features, TData>()` — both generics required                                                                                                                                                                 |
+| `ColumnDef<TData, TValue>`                                               | `ColumnDef<TFeatures, TData, TValue>` — `TFeatures` is now the first generic                                                                                                                                                             |
+| `Table<TData>`                                                           | `Table<TFeatures, TData>`                                                                                                                                                                                                                |
+
+Source: `docs/framework/preact/preact-table.md`; `docs/framework/preact/guide/table-state.md`.
+
+## Migration Steps
+
+### 1. Update the package import
+
+```tsx
+// v8
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  flexRender,
+  type ColumnDef,
+} from '@tanstack/preact-table'
+
+// v9
+import {
+  useTable,
+  tableFeatures,
+  rowSortingFeature,
+  createSortedRowModel,
+  sortFns,
+  type ColumnDef,
+} from '@tanstack/preact-table'
+```
+
+### 2. Declare `_features` and `_rowModels`
+
+Replace each `get*RowModel: get*RowModel()` option with a feature import + a row-model factory.
+
+```tsx
+// v8
+const table = useReactTable({
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(),
+  getSortedRowModel: getSortedRowModel(),
+  getFilteredRowModel: getFilteredRowModel(),
+  getPaginationRowModel: getPaginationRowModel(),
+})
+
+// v9
+const _features = tableFeatures({
+  rowSortingFeature,
+  columnFilteringFeature,
+  rowPaginationFeature,
+})
+
+const table = useTable({
+  _features,
+  _rowModels: {
+    sortedRowModel: createSortedRowModel(sortFns),
+    filteredRowModel: createFilteredRowModel(filterFns),
+    paginatedRowModel: createPaginatedRowModel(),
+  },
+  columns,
+  data,
+})
+```
+
+Move `_features` to module scope. Reference stability matters — see `tanstack-table/preact/production-readiness`.
+
+### 3. Update column types and helpers
+
+`TFeatures` is now the first generic on `ColumnDef`, `Table`, and `createColumnHelper`.
+
+```tsx
+// v8
+const columnHelper = createColumnHelper<Person>()
+const columns: ColumnDef<Person>[] = columnHelper.columns([
+  /* … */
+])
+
+// v9
+const columnHelper = createColumnHelper<typeof _features, Person>()
+const columns: Array<ColumnDef<typeof _features, Person>> =
+  columnHelper.columns([
+    /* … */
+  ])
+```
+
+### 4. Replace `flexRender` calls with `table.FlexRender`
+
+```tsx
+// v8
+<th>{flexRender(header.column.columnDef.header, header.getContext())}</th>
+<td>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
+
+// v9
+<th>{header.isPlaceholder ? null : <table.FlexRender header={header} />}</th>
+<td><table.FlexRender cell={cell} /></td>
+```
+
+`flexRender` is still exported for advanced cases, but `table.FlexRender` (or the standalone `FlexRender` component) handles grouping placeholder/aggregated branches for you.
+
+Source: `packages/preact-table/src/FlexRender.tsx`.
+
+### 5. Move external state to atoms (recommended)
+
+`state` + `on*Change` still works, but v9 prefers slice atoms for fine-grained reactivity.
+
+```tsx
+// v8 / v9 fallback
+const [sorting, setSorting] = useState<SortingState>([])
+const table = useTable({
+  _features,
+  _rowModels,
+  columns,
+  data,
+  state: { sorting },
+  onSortingChange: setSorting,
+})
+
+// v9 preferred — external atom
+import { useCreateAtom } from '@tanstack/preact-store'
+const sortingAtom = useCreateAtom<SortingState>([])
+const table = useTable({
+  _features,
+  _rowModels,
+  columns,
+  data,
+  atoms: { sorting: sortingAtom },
+  // no onSortingChange needed
+})
+```
+
+Source: `examples/preact/basic-external-atoms/src/main.tsx`.
+
+### 6. Drop `onStateChange`
+
+The v8-style global `onStateChange` is gone. Subscribe per-slice with `on*Change`, an external atom, or `table.store.subscribe(...)` if you really need every change.
+
+Source: `docs/framework/preact/guide/table-state.md`.
+
+## Common Mistakes
+
+### CRITICAL Keeping `get*RowModel` options after upgrading
+
+Wrong:
+
+```tsx
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  getSortedRowModel: getSortedRowModel(), // v8 leftover — silently ignored
+})
+table.setSorting([{ id: 'age', desc: true }]) // rows are NOT sorted
+```
+
+Correct:
+
+```tsx
+const _features = tableFeatures({ rowSortingFeature })
+const table = useTable({
+  _features,
+  _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+  columns,
+  data,
+})
+```
+
+v9 doesn't read the `get*RowModel` options. The row model only runs for stages registered in `_rowModels`, and the feature only mounts if it is in `_features`.
+Source: `docs/framework/preact/preact-table.md`.
+
+### CRITICAL Forgetting to register a feature whose API you are calling
+
+Wrong:
+
+```tsx
+const _features = tableFeatures({}) // no rowSelectionFeature
+const table = useTable({ _features, _rowModels: {}, columns, data })
+table.getIsAllRowsSelected() // TypeScript error / runtime no-op
+row.toggleSelected(true) // same
+```
+
+Correct:
+
+```tsx
+const _features = tableFeatures({ rowSelectionFeature })
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  enableRowSelection: true,
+})
+table.getIsAllRowsSelected()
+```
+
+v9 generates feature APIs and state slices only for registered features. This is the #1 v9 trap.
+Source: `docs/guide/features.md`.
+
+### HIGH Re-using `getCoreRowModel: getCoreRowModel()` from v8
+
+Wrong:
+
+```tsx
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  getCoreRowModel: getCoreRowModel(), // no-op in v9
+})
+```
+
+Correct:
+
+```tsx
+const table = useTable({ _features, _rowModels: {}, columns, data })
+```
+
+The core row model is always included in v9. There is no `getCoreRowModel` option.
+Source: `docs/framework/preact/preact-table.md`.
+
+### HIGH Single-generic column helper / `ColumnDef`
+
+Wrong:
+
+```tsx
+const columnHelper = createColumnHelper<Person>() // v8 shape
+const columns: ColumnDef<Person>[] = [
+  /* … */
+] // v8 shape
+```
+
+Correct:
+
+```tsx
+const columnHelper = createColumnHelper<typeof _features, Person>()
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  /* … */
+]
+```
+
+`TFeatures` is the first generic for nearly every public type in v9. Without it, types degrade to `any` for feature methods.
+Source: `docs/framework/preact/preact-table.md`.
+
+### HIGH Reimplementing built-ins (the #1 AI tell)
+
+Wrong:
+
+```tsx
+// Manual sorting, manual filtering, manual pagination, manual row-selection objects
+```
+
+Correct: register the matching feature in `_features`, register its factory in `_rowModels`, and use the feature API. v9 ships built-ins for sorting, filtering, pagination, grouping, expanding, faceting, row selection, column visibility/order/pinning/sizing, and row pinning.
+Source: `docs/guide/features.md`.
+
+### MEDIUM Calling `flexRender` directly when grouping is on
+
+Wrong:
+
+```tsx
+<td>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
+```
+
+Correct:
+
+```tsx
+<td>
+  <table.FlexRender cell={cell} />
+</td>
+```
+
+`<table.FlexRender cell={...}>` handles aggregated / placeholder cells when `columnGroupingFeature` is registered. Raw `flexRender` does not.
+Source: `packages/preact-table/src/FlexRender.tsx`.
+
+## See Also
+
+- `tanstack-table/preact/getting-started` — green-field v9 setup.
+- `tanstack-table/preact/table-state` — atom model and Subscribe patterns.
+- `tanstack-table/preact/production-readiness` — perf, tree-shaking, stable refs.