@tanstack/svelte-table 9.0.0-beta.7 → 9.0.0-beta.71

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

@@ -1,256 +0,0 @@
----
-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.

package/skills/svelte/production-readiness/SKILL.md

@@ -1,256 +0,0 @@
----
-name: svelte/production-readiness
-description: >
-  Ship-ready optimizations for `@tanstack/svelte-table@9` on Svelte 5. Tree-shake by registering
-  ONLY the `features` you use; keep `features`, `columns`, and `data` stable; replace broad
-  `(state) => state` selectors with narrow projections on `createTable`; reach for
-  `subscribeTable(atom, selector?)` when only one block of markup should react; lean on rune-aware
-  atom reads (`table.atoms.<slice>.get()`) for non-reactive paths; key every `{#each}` block on
-  stable ids; debounce high-frequency writes with `@tanstack/svelte-pacer`. Svelte 5+ only.
-type: lifecycle
-library: tanstack-table
-framework: svelte
-library_version: '9.0.0-alpha.48'
-requires:
-  - setup
-  - state-management
-  - svelte/table-state
-sources:
-  - TanStack/table:docs/guide/features.md
-  - TanStack/table:docs/framework/svelte/guide/table-state.md
-  - TanStack/table:packages/svelte-table/src/createTable.svelte.ts
-  - TanStack/table:packages/svelte-table/src/subscribe.ts
-  - TanStack/table:examples/svelte/basic-external-atoms/
-  - TanStack/table:examples/svelte/virtualized-rows/
----
-
-# Production Readiness — Svelte
-
-Once your tables work, this is the checklist for making them fast and small. Most of these are
-v9-specific — v8 tables won't have any of these levers.
-
-## 1. Register only the features you use
-
-`features` is the bundle gate. Any feature you don't register is tree-shaken out — including
-its state slice, its API surface, and its reactive plumbing.
-
-```ts
-// good — minimal table, ~smallest bundle
-const features = tableFeatures({})
-
-// good — feature-by-feature opt-in
-const features = tableFeatures({
-  rowPaginationFeature,
-  rowSortingFeature,
-})
-
-// bad — kitchen sink, every state slice created even when unused
-const features = tableFeatures({
-  columnFilteringFeature,
-  columnGroupingFeature,
-  columnOrderingFeature,
-  columnPinningFeature,
-  columnResizingFeature,
-  columnSizingFeature,
-  columnVisibilityFeature,
-  globalFilteringFeature,
-  rowExpandingFeature,
-  rowPaginationFeature,
-  rowPinningFeature,
-  rowSelectionFeature,
-  rowSortingFeature,
-})
-```
-
-If you find yourself running a table without a feature's UI ever showing, drop the feature.
-
-## 2. Stable identities for `features`, `columns`, `data`
-
-`createTable` syncs options in `$effect.pre`. If any of these identities flip every component
-run, the table re-syncs more than it needs to.
-
-- **`features` and `rowModels`**: declare at module scope, not inside the component
-  function, and never inside `$derived` / `$effect`.
-- **`columns`**: same — module scope or `$state.frozen` / a non-reactive `const` in the
-  component. Reactive recompute of columns is rare and almost always a bug.
-- **`data`**: pass with a getter (`get data()`) so the reference is stable when the data
-  doesn't change. If you're reshaping data inside the component, do it once in a `$derived`,
-  not on every read.
-
-```svelte
-<script lang="ts">
-  // module scope is fine in .svelte too, when truly static
-  const features = tableFeatures({ rowPaginationFeature })
-  const rowModels = { paginatedRowModel: createPaginatedRowModel() }
-  const columns = columnHelper.columns([
-    /* ... */
-  ])
-
-  let rawRows = $state<Person[]>([])
-  const data = $derived(rawRows.map(normalize)) // computed once per rawRows change
-
-  const table = createTable({
-    features,
-    rowModels,
-    columns,
-    get data() {
-      return data
-    },
-  })
-</script>
-```
-
-## 3. Narrow the `table.state` selector
-
-The default selector is `(state) => state`. That makes `table.state` re-run any consumer when
-**any** slice changes. Pass a focused selector and you only re-render markup that actually
-depends on that slice.
-
-```ts
-// good — only re-projects when pagination changes
-const table = createTable(options, (state) => ({
-  pagination: state.pagination,
-}))
-
-// even better — only what your UI actually reads
-const table = createTable(options, (state) => ({
-  pageIndex: state.pagination.pageIndex,
-  pageSize: state.pagination.pageSize,
-}))
-```
-
-If different parts of the UI need different slices, **don't** widen the selector — use
-`subscribeTable` instead (next section).
-
-## 4. Reach for `subscribeTable` for fine-grained reactivity
-
-`subscribeTable(source, selector?)` is the per-block subscription. It returns an object whose
-`.current` re-runs only when the selected value changes (shallow compared).
-
-```svelte
-<script lang="ts">
-  import { subscribeTable } from '@tanstack/svelte-table'
-
-  // dedicated subscription for the pager
-  const pagination = subscribeTable(table.atoms.pagination)
-
-  // dedicated subscription for a single row's selection state
-  const isSelected = subscribeTable(
-    table.atoms.rowSelection,
-    (rs) => !!rs[row.id],
-  )
-</script>
-
-<input type="checkbox" checked={isSelected.current} />
-```
-
-Use it inside per-row components — the row block re-renders only on its own selection toggle,
-not on every row's toggle.
-
-## 5. Non-reactive reads where you don't need reactivity
-
-Inside event handlers, derived calculations, or one-shot logic, read atoms directly. Cheaper
-than subscribing.
-
-```ts
-function exportSelected() {
-  const selection = table.atoms.rowSelection.get()
-  const selectedIds = Object.keys(selection).filter((id) => selection[id])
-  // ...
-}
-```
-
-`table.state` is the same idea for a full snapshot.
-
-## 6. Key every `{#each}` block on a stable id
-
-Svelte without keys recreates nodes on reorder. Result: lost input focus, lost scroll, lost
-component state. Every TanStack Table loop has a stable id.
-
-```svelte
-{#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
-  <tr>
-    {#each headerGroup.headers as header (header.id)}
-      <th>...</th>
-    {/each}
-  </tr>
-{/each}
-
-{#each table.getRowModel().rows as row (row.id)}
-  <tr>
-    {#each row.getVisibleCells() as cell (cell.id)}
-      <td>...</td>
-    {/each}
-  </tr>
-{/each}
-```
-
-## 7. Don't fight `$effect.pre`
-
-`createTable` is already syncing options in `$effect.pre`. Don't write a second `$effect`
-that calls `table.setOptions` — it'll race with the built-in sync and may render with stale
-state.
-
-If you need to react to an option change with a side effect, put the side effect in your own
-`$effect`, not the option write.
-
-## 8. Debounce high-frequency writes
-
-Two places will hammer table state at keystroke / pointermove rate:
-
-- **Filter inputs.** Wrap `setFilterValue` calls with a debounced callback.
-- **Column resizing.** v9 commits `columnSizing` continuously by default; use the resize-end
-  commit mode or debounce.
-
-```ts
-import { createDebouncer } from '@tanstack/svelte-pacer/debouncer'
-
-const debouncedSetFilter = createDebouncer(
-  (value: string) => column.setFilterValue(value),
-  { wait: 200 },
-)
-```
-
-See the `compose-with-tanstack-pacer` skill for full examples.
-
-## 9. Virtualization for large datasets
-
-`getRowModel().rows.length > ~1000` and rows are simple? Performance is fine without
-virtualization. Above that, or with heavy per-row markup, use `@tanstack/svelte-virtual`. See
-the `compose-with-tanstack-virtual` skill.
-
-## 10. Don't ship debug flags
-
-`debugTable: true`, `debugRows`, `debugHeaders` all log. Strip them or gate on `import.meta.env.DEV`.
-
-## 11. Don't reimplement built-ins
-
-The #1 production-readiness regression we see in audits: somebody hand-rolled the thing the
-table already does. If you're writing any of these, register the feature instead.
-
-- Hand-rolled sort comparator across rows → `rowSortingFeature` + `createSortedRowModel`
-- Hand-rolled page math (`rows.slice(start, end)`) → `rowPaginationFeature` +
-  `createPaginatedRowModel`
-- Hand-rolled selection toggle (`selected[row.id] = !selected[row.id]`) → `rowSelectionFeature`
-- Hand-rolled column hide map → `columnVisibilityFeature`
-- Hand-rolled column resizer → `columnResizingFeature`
-- Hand-rolled debounced filter that doesn't update through `setFilterValue` →
-  `columnFilteringFeature` + pacer
-
-Each rewrite breaks tree-shaking, breaks the reset APIs, and breaks devtools introspection.
-
-## Quick smoke test before shipping
-
-- Bundle: does the table chunk match the features you registered? (`pnpm build` and inspect.)
-- DevTools profiler: clicking sort triggers exactly one re-render of the headers and rows,
-  not every consumer of `table.state`.
-- Resize / filter: no jank, no per-keystroke server hits (pacer / debounce).
-- Reload: state restored from your atom / URL / storage, no flicker.
-- Stress: 100k-row dataset with virtualization stays interactive.
-
-## Related skills
-
-- `tanstack-table/svelte/table-state` — selectors, atoms, subscribeTable.
-- `tanstack-table/svelte/compose-with-tanstack-pacer` — debounce patterns.
-- `tanstack-table/svelte/compose-with-tanstack-virtual` — virtualization.
-- `tanstack-table/svelte/compose-with-tanstack-store` — atom ownership patterns.