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

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

@@ -0,0 +1,340 @@
+---
+name: svelte/getting-started
+description: >
+  End-to-end first-table journey for `@tanstack/svelte-table@9` on Svelte 5. Install the adapter,
+  declare `_features` with `tableFeatures()`, register `_rowModels` factories with their `*Fns`
+  parameters, build a typed column helper with both `TFeatures` and `TData` generics, instantiate
+  the table with `createTable(options)` using `$state` data and `get data()` reactive option getters,
+  and render with `FlexRender`. Svelte 5+ only — Svelte 3/4 must use v8.
+type: lifecycle
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.48'
+requires:
+  - setup
+  - column-definitions
+  - state-management
+  - svelte/table-state
+sources:
+  - TanStack/table:docs/installation.md
+  - TanStack/table:docs/framework/svelte/svelte-table.md
+  - TanStack/table:examples/svelte/basic-create-table/
+  - TanStack/table:examples/svelte/basic-app-table/
+  - TanStack/table:examples/svelte/basic-snippets/
+  - TanStack/table:packages/svelte-table/src/index.ts
+---
+
+# Getting Started — Svelte
+
+A first working `@tanstack/svelte-table` v9 table from a blank Svelte 5 project. Read this
+end-to-end before searching the docs — the v9 shape diverges enough from v8 (and from your
+muscle memory) that skimming will produce broken code.
+
+## CRITICAL: Svelte version
+
+**`@tanstack/svelte-table@9` requires Svelte 5 or newer.** The adapter is built on runes
+(`$state`, `$derived.by`, `$effect.pre`). If your project is on Svelte 3 or 4, do **one** of:
+
+- Upgrade the project to Svelte 5, then install v9.
+- Stay on `@tanstack/svelte-table@8` for that project.
+
+There is no shim, no `/legacy` export, and no support path that runs v9 on Svelte 4.
+
+## 1. Install
+
+```bash
+pnpm add @tanstack/svelte-table
+# optional: external atoms / fine-grained selectors
+pnpm add @tanstack/svelte-store
+```
+
+You do **not** install `@tanstack/table-core` separately — the Svelte adapter re-exports
+everything you need (column helpers, feature objects, row-model factories, types).
+
+## 2. Define `_features` and `_rowModels`
+
+v9 is explicit. You opt in to every feature and every row model. The core row model is
+included by default, so the minimum viable table is:
+
+```ts
+const _features = tableFeatures({})
+const _rowModels = {}
+```
+
+For anything beyond a flat table, register the features you'll use **and** the matching
+row-model factories. Row-model factories take `*Fns` registries as parameters:
+
+```ts
+import {
+  columnFilteringFeature,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  filterFns,
+  rowPaginationFeature,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from '@tanstack/svelte-table'
+
+const _features = tableFeatures({
+  rowPaginationFeature,
+  rowSortingFeature,
+  columnFilteringFeature,
+})
+
+const _rowModels = {
+  paginatedRowModel: createPaginatedRowModel(),
+  sortedRowModel: createSortedRowModel(sortFns),
+  filteredRowModel: createFilteredRowModel(filterFns),
+}
+```
+
+**Skipping a feature** in `_features` means its state slice does not exist on `table.atoms`,
+its options on `createTable` do nothing, and its derived APIs (`table.setSorting`,
+`column.getCanSort`) are not on the instance.
+
+## 3. Type your data and define columns
+
+```ts
+type Person = {
+  firstName: string
+  lastName: string
+  age: number
+  visits: number
+  status: 'relationship' | 'complicated' | 'single'
+  progress: number
+}
+```
+
+Both `ColumnDef` and the column helper take the two generics `<typeof _features, TData>`:
+
+```ts
+import { createColumnHelper, type ColumnDef } from '@tanstack/svelte-table'
+
+const columnHelper = createColumnHelper<typeof _features, Person>()
+
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    header: 'First Name',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor((row) => row.lastName, {
+    id: 'lastName',
+    header: () => 'Last Name',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor('age', { header: 'Age' }),
+  columnHelper.accessor('visits', { header: 'Visits' }),
+  columnHelper.accessor('status', { header: 'Status' }),
+  columnHelper.accessor('progress', { header: 'Profile Progress' }),
+])
+```
+
+Or use raw `ColumnDef` arrays if you don't want the helper:
+
+```ts
+const columns: Array<ColumnDef<typeof _features, Person>> = [
+  {
+    accessorKey: 'firstName',
+    header: 'First Name',
+    cell: (info) => info.getValue(),
+  },
+]
+```
+
+## 4. Create the table
+
+Use Svelte 5 `$state` for the data and pass it through a **reactive getter** so the table
+re-evaluates `data` when the rune changes. The same pattern applies for any other reactive
+option (`columns`, `rowCount`, `state.*`).
+
+```svelte
+<script lang="ts">
+  import { createTable, tableFeatures } from '@tanstack/svelte-table'
+  import { makeData, type Person } from './makeData'
+
+  const _features = tableFeatures({})
+
+  // ... columns from step 3 ...
+
+  let data = $state<Person[]>(makeData(20))
+
+  const refreshData = () => {
+    data = makeData(20)
+  }
+
+  const table = createTable({
+    _features,
+    _rowModels: {},
+    columns,
+    get data() {
+      return data
+    },
+  })
+</script>
+```
+
+`createTable` syncs options inside `$effect.pre`, so external `$state` updates flow into the
+table **before** the DOM reads `getRowModel()` — no stale-frame bugs.
+
+## 5. Render with `FlexRender`
+
+`FlexRender` handles plain strings, function renderers, component renderers
+(`renderComponent`), and snippet renderers (`renderSnippet`).
+
+```svelte
+<script lang="ts">
+  import { FlexRender } from '@tanstack/svelte-table'
+</script>
+
+<button onclick={refreshData}>Regenerate</button>
+
+<table>
+  <thead>
+    {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
+      <tr>
+        {#each headerGroup.headers as header (header.id)}
+          <th>
+            {#if !header.isPlaceholder}
+              <FlexRender {header} />
+            {/if}
+          </th>
+        {/each}
+      </tr>
+    {/each}
+  </thead>
+  <tbody>
+    {#each table.getRowModel().rows as row (row.id)}
+      <tr>
+        {#each row.getAllCells() as cell (cell.id)}
+          <td><FlexRender {cell} /></td>
+        {/each}
+      </tr>
+    {/each}
+  </tbody>
+</table>
+```
+
+**Key the `{#each}` blocks on stable ids.** Without keys, Svelte recreates nodes and loses
+focus, scroll, and any per-row component state.
+
+## 6. Adding a feature — pagination
+
+```svelte
+<script lang="ts">
+  import {
+    createPaginatedRowModel,
+    createTable,
+    rowPaginationFeature,
+    tableFeatures,
+  } from '@tanstack/svelte-table'
+
+  const _features = tableFeatures({ rowPaginationFeature })
+
+  const table = createTable({
+    _features,
+    _rowModels: {
+      paginatedRowModel: createPaginatedRowModel(),
+    },
+    columns,
+    get data() {
+      return data
+    },
+    initialState: {
+      pagination: { pageIndex: 0, pageSize: 10 },
+    },
+  })
+</script>
+
+<div>
+  <button
+    onclick={() => table.previousPage()}
+    disabled={!table.getCanPreviousPage()}>Prev</button
+  >
+  <span
+    >Page {table.atoms.pagination.get().pageIndex + 1} of {table.getPageCount()}</span
+  >
+  <button onclick={() => table.nextPage()} disabled={!table.getCanNextPage()}
+    >Next</button
+  >
+</div>
+```
+
+To make pagination reactive in the controls, either pass a selector to `createTable` or use
+`subscribeTable`:
+
+```ts
+import { subscribeTable } from '@tanstack/svelte-table'
+
+const pagination = subscribeTable(table.atoms.pagination)
+// pagination.current.pageIndex is reactive
+```
+
+## 7. `createTableHook` (when you have more than one table)
+
+For apps with multiple tables, define the `_features`, `_rowModels`, and shared components
+once:
+
+```ts
+// hooks/table.ts
+import {
+  createPaginatedRowModel,
+  createSortedRowModel,
+  createTableHook,
+  rowPaginationFeature,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from '@tanstack/svelte-table'
+
+export const { createAppTable, createAppColumnHelper } = createTableHook({
+  _features: tableFeatures({ rowPaginationFeature, rowSortingFeature }),
+  _rowModels: {
+    paginatedRowModel: createPaginatedRowModel(),
+    sortedRowModel: createSortedRowModel(sortFns),
+  },
+})
+```
+
+```svelte
+<script lang="ts">
+  import { createAppColumnHelper, createAppTable } from './hooks/table'
+
+  const columnHelper = createAppColumnHelper<Person>()
+  const columns = columnHelper.columns([
+    columnHelper.accessor('firstName', { header: 'First' }),
+  ])
+
+  const table = createAppTable({
+    columns,
+    get data() {
+      return data
+    },
+  })
+</script>
+```
+
+## Common failure modes
+
+- **Svelte 3/4.** Adapter will not work. See top of file.
+- **`createSvelteTable` / `useSvelteTable` / `getCoreRowModel`** — all v8 names. v9 uses
+  `createTable` and `_rowModels: { paginatedRowModel: createPaginatedRowModel(), ... }`.
+- **Plain `data` instead of `get data()` getter.** Table will not see data updates. Always
+  pass a reactive getter for state that lives in `$state`.
+- **Missing feature in `_features`.** `table.setSorting` / `column.getCanSort` won't exist.
+  TypeScript will tell you; if it doesn't, you're missing the `<typeof _features, TData>`
+  generics on the column helper or `ColumnDef`.
+- **Plain object instead of `tableFeatures({...})`.** Loses typed atom keys; you'll get
+  `unknown` state shapes everywhere.
+- **Unkeyed `{#each}` blocks.** Reuse bugs (focus jumps, wrong row selected).
+- **Reimplementing built-ins.** If you write a manual sort comparator across rows, you're
+  re-doing `rowSortingFeature`. Register it instead.
+
+## Next steps
+
+- `tanstack-table/svelte/table-state` — reactivity model, selectors, subscribeTable, ownership.
+- `tanstack-table/core/filtering` / `pagination` / `sorting` / `row-selection` — feature-by-feature.
+- `tanstack-table/svelte/compose-with-tanstack-query` — server-side data.
+- `tanstack-table/svelte/compose-with-tanstack-virtual` — large datasets.
+- `tanstack-table/svelte/production-readiness` — selector tuning, bundle size.

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

@@ -0,0 +1,256 @@
+---
+name: svelte/migrate-v8-to-v9
+description: >
+  Mechanical migration from `@tanstack/svelte-table@8` to `@tanstack/svelte-table@9`. v9 in Svelte
+  is a full rewrite — Svelte 5 runes only (no Svelte 3/4), no `/legacy` adapter (unlike React),
+  `createSvelteTable` → `createTable`, `getCoreRowModel` / `getSortedRowModel` factories → required
+  `_features` + `_rowModels` registration, `flexRender` helper → `<FlexRender>` component,
+  writable-store `state` → rune-based getters / external atoms, `onStateChange` → per-slice
+  `on[State]Change` or `atoms`. Plan a feature-by-feature audit, not a search-and-replace.
+type: lifecycle
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.48'
+requires:
+  - setup
+  - state-management
+  - column-definitions
+sources:
+  - TanStack/table:docs/framework/svelte/svelte-table.md
+  - TanStack/table:docs/framework/svelte/guide/table-state.md
+  - TanStack/table:packages/svelte-table/src/
+  - TanStack/table:examples/svelte/basic-create-table/
+  - TanStack/table:examples/svelte/basic-external-atoms/
+  - TanStack/table:examples/svelte/basic-external-state/
+---
+
+# Migrate v8 → v9 (Svelte)
+
+## CRITICAL: v9 = Svelte 5
+
+**v9 of the Svelte adapter only supports Svelte 5+.** No backport. No shim. No `/legacy` import.
+The v9 adapter is built on Svelte 5 runes (`$state`, `$derived.by`, `$effect.pre`). If your app
+is still on Svelte 3/4, you have two real options:
+
+1. Stay on `@tanstack/svelte-table@8`. v8 keeps working with the Svelte 3/4 writable-store API.
+2. Migrate the app to Svelte 5 first, then migrate the table.
+
+There is no third option. Trying to install v9 on a Svelte 4 codebase will error at compile.
+
+> This makes the Svelte migration heavier than React's. React has a `/legacy` re-export that
+> mirrors the v8 surface; Svelte does not. Plan for a real rewrite of every table screen.
+
+## What changed at the type / API level
+
+| v8                                                 | v9                                                                                    |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `createSvelteTable(options)`                       | `createTable(options, selector?)`                                                     |
+| `getCoreRowModel()`                                | included by default; no factory                                                       |
+| `getPaginationRowModel()`                          | `_rowModels.paginatedRowModel: createPaginatedRowModel()`                             |
+| `getSortedRowModel()`                              | `_rowModels.sortedRowModel: createSortedRowModel(sortFns)`                            |
+| `getFilteredRowModel()`                            | `_rowModels.filteredRowModel: createFilteredRowModel(filterFns)`                      |
+| `getExpandedRowModel()`                            | `_rowModels.expandedRowModel: createExpandedRowModel()`                               |
+| `getGroupedRowModel()`                             | `_rowModels.groupedRowModel: createGroupedRowModel(aggregationFns)`                   |
+| `getFacetedRowModel()` / `MinMax` / `UniqueValues` | facet APIs auto-derived when `*Facet*Feature` registered                              |
+| `flexRender(template, ctx)` helper                 | `<FlexRender header={h} />` / `<FlexRender cell={c} />` / `<FlexRender footer={h} />` |
+| `ColumnDef<TData>`                                 | `ColumnDef<TFeatures, TData>` (extra generic)                                         |
+| `createColumnHelper<TData>()`                      | `createColumnHelper<TFeatures, TData>()`                                              |
+| writable store on the table instance               | `table.atoms.<slice>` + `table.store` + `table.state`                                 |
+| `onStateChange` (monolithic)                       | per-slice `on[State]Change`, or external `atoms`                                      |
+| `useSvelteTable` (rare)                            | gone                                                                                  |
+
+## What did NOT change
+
+- The data array is still the source of truth; columns are still defined the same way
+  shape-wise (`accessorKey` / `accessorFn` / `header` / `cell` / `footer`).
+- Filter, sort, aggregation function registries are still `filterFns`, `sortFns`,
+  `aggregationFns` — but now passed into row-model factories instead of being auto-resolved.
+- Feature APIs (`table.nextPage()`, `column.getCanSort()`, `row.toggleSelected()`) keep the
+  same names.
+
+## Migration checklist (per file)
+
+For each Svelte component that uses the table:
+
+1. **Upgrade Svelte.** Ensure the app is on Svelte 5 and the component compiles in runes mode.
+2. **Replace store with rune.** `let data = writable([])` → `let data = $state([])`. Reads
+   inside markup are no longer `$data` — just `data`.
+3. **Import surface.** `import { createSvelteTable, getCoreRowModel, flexRender }` →
+   `import { createTable, FlexRender, tableFeatures, ... }`.
+4. **Add `_features`.** Create `const _features = tableFeatures({ ... only the features this
+table uses ... })`.
+5. **Move row-model factories.** Every `get*RowModel: get*RowModel()` becomes a `_rowModels`
+   entry with the matching `create*RowModel(*Fns)` factory.
+6. **Generic columns.** Add `<typeof _features, TData>` to `ColumnDef<>` and
+   `createColumnHelper<>()`. TypeScript will tell you when you missed one.
+7. **`data` as a getter.** `data: data` → `get data() { return data }`. Same for any other
+   reactive option (`state.*`, `columns`, `rowCount`).
+8. **State.** Pick the new ownership model — see below.
+9. **Rendering.** `{flexRender(header.column.columnDef.header, header.getContext())}` →
+   `<FlexRender header={header} />`. Same for cells and footers.
+10. **Components / snippets in cells.** v8: pass a Svelte component constructor. v9: wrap with
+    `renderComponent(MyCell, props)` or `renderSnippet(snippet, args)`.
+
+## State ownership — choose one per slice
+
+### Was: `writable` store + `onStateChange`
+
+```svelte
+<script lang="ts">
+  // v8
+  import { writable } from 'svelte/store'
+  const options = writable({ ... })
+  $: $options.state = $state
+</script>
+```
+
+### Now: pick one of three
+
+**Internal (default).** Pass only `initialState` and let the table own it.
+
+```ts
+const table = createTable({
+  _features,
+  _rowModels: { paginatedRowModel: createPaginatedRowModel() },
+  columns,
+  get data() {
+    return data
+  },
+  initialState: {
+    pagination: { pageIndex: 0, pageSize: 25 },
+  },
+})
+```
+
+**External `state` + per-slice `on[State]Change`.** Closest to a literal v8 port.
+
+```svelte
+<script lang="ts">
+  let sorting: SortingState = $state([])
+  let pagination: PaginationState = $state({ pageIndex: 0, pageSize: 10 })
+
+  const table = createTable({
+    _features,
+    _rowModels: { ... },
+    columns,
+    get data() { return data },
+    state: {
+      get sorting() { return sorting },
+      get pagination() { return pagination },
+    },
+    onSortingChange: (updater) => {
+      sorting = updater instanceof Function ? updater(sorting) : updater
+    },
+    onPaginationChange: (updater) => {
+      pagination = updater instanceof Function ? updater(pagination) : updater
+    },
+  })
+</script>
+```
+
+**External atoms (preferred for shared state).** Atomic, subscribable from anywhere.
+
+```ts
+import { createAtom, useSelector } from '@tanstack/svelte-store'
+
+const sortingAtom = createAtom<SortingState>([])
+const paginationAtom = createAtom<PaginationState>({ pageIndex: 0, pageSize: 10 })
+
+const sorting = useSelector(sortingAtom)
+const pagination = useSelector(paginationAtom)
+
+const table = createTable({
+  _features,
+  _rowModels: { ... },
+  columns,
+  get data() { return data },
+  atoms: {
+    sorting: sortingAtom,
+    pagination: paginationAtom,
+  },
+})
+```
+
+**Do not combine** `state.pagination` with `atoms.pagination` — atoms always win, `state` is
+discarded silently, you'll think your callbacks aren't firing.
+
+## Rendering migration cheat sheet
+
+```svelte
+<!-- v8 -->
+<th>
+  {#if !header.isPlaceholder}
+    <svelte:component
+      this={flexRender(header.column.columnDef.header, header.getContext())}
+    />
+  {/if}
+</th>
+
+<!-- v9 -->
+<th>
+  {#if !header.isPlaceholder}
+    <FlexRender {header} />
+  {/if}
+</th>
+```
+
+For cells that render a custom Svelte component:
+
+```svelte
+<!-- v8: column def -->
+{ cell: () => MyCellComponent }
+
+<!-- v9: column def -->
+import { renderComponent } from '@tanstack/svelte-table'
+{ cell: ({ row }) => renderComponent(MyCellComponent, { row }) }
+```
+
+For inline snippets:
+
+```svelte
+<!-- v9 -->
+import { renderSnippet } from '@tanstack/svelte-table'
+
+{#snippet myCell(row)}
+  <strong>{row.original.firstName}</strong>
+{/snippet}
+
+{ cell: ({ row }) => renderSnippet(myCell, row) }
+```
+
+## After the rewrite — verify
+
+- `pnpm test:types` (or `svelte-check`) catches missing `<typeof _features, TData>` generics,
+  missing `_features` / `_rowModels`, and feature APIs called on tables that didn't register
+  them.
+- `pnpm build` should pass with the new `_features` set. Bundle should shrink — only the
+  features you register are included.
+- Click through every table screen. Reset buttons, multi-sort, pagination reset on filter,
+  expanded-row count under pagination — these are all the spots where v8 muscle memory
+  reaches for an option (`autoResetPageIndex` etc.) that's still named the same in v9 but
+  only takes effect if the matching feature is registered.
+
+## Common failure modes during migration
+
+- **Trying to skip the Svelte 5 upgrade.** Will not work.
+- **Reaching for `useLegacyTable`.** Doesn't exist in `@tanstack/svelte-table`. That's a
+  React-only escape hatch.
+- **Importing from `@tanstack/table-core` directly.** Re-exported by the adapter — go through
+  the adapter.
+- **Plain `data` instead of `get data()` getter.** Largest single source of "but my data
+  changed" bugs during migration.
+- **Plain `_features: { rowPaginationFeature }` instead of `tableFeatures({...})`.** Loses
+  inference; you'll get `any` everywhere.
+- **Forgetting feature registration after copying the row-model factory.** Adding
+  `paginatedRowModel: createPaginatedRowModel()` without `rowPaginationFeature` in
+  `_features` does nothing.
+- **Reimplementing v8 helpers** (`flexRender`-style functions, manual store subscriptions,
+  hand-rolled selectors) instead of using `FlexRender` / `subscribeTable` / atom selectors.
+  That's the #1 AI tell on this migration.
+
+## Related skills
+
+- `tanstack-table/svelte/getting-started` — clean-slate setup.
+- `tanstack-table/svelte/table-state` — the v9 state model in depth.
+- `tanstack-table/core/state-management` — atom precedence rules.
+- `tanstack-table/svelte/production-readiness` — post-migration tuning.