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

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

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

package/skills/svelte/table-state/SKILL.md

@@ -0,0 +1,441 @@
+---
+name: svelte/table-state
+description: >
+  Svelte 5 rune-based reactivity for TanStack Table v9. Covers `createTable(options, selector?)`,
+  the `table.state` selector projection, fine-grained `subscribeTable(atom, selector?)` with `.current`,
+  reading and writing `table.atoms` / `table.baseAtoms`, the `svelteReactivity()` bridge that backs
+  readonly atoms with `$derived.by` and writable atoms with `$state`, and the `$effect.pre` option
+  sync. State ownership: `initialState`, `state` + `on[State]Change`, or external `atoms` from
+  `@tanstack/svelte-store` (`createAtom`, `useSelector`). Svelte 5+ only — no Svelte 3/4 support.
+type: framework
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.47'
+requires:
+  - state-management
+  - setup
+sources:
+  - TanStack/table:docs/framework/svelte/svelte-table.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/createTableHook.svelte.ts
+  - TanStack/table:packages/svelte-table/src/reactivity.svelte.ts
+  - TanStack/table:packages/svelte-table/src/subscribe.ts
+  - TanStack/table:examples/svelte/basic-create-table/
+  - TanStack/table:examples/svelte/basic-external-atoms/
+  - TanStack/table:examples/svelte/basic-external-state/
+---
+
+# Svelte Table State, `subscribeTable` & `createTableHook`
+
+> **TanStack Table is a state-management coordinator for table state.** Understanding how state
+> flows through atoms, runes, and selectors is foundational to everything else you do with the
+> Svelte adapter.
+
+## Critical: Svelte 5+ only
+
+`@tanstack/svelte-table@9` requires **Svelte 5 or newer**. The adapter is built on runes
+(`$state`, `$derived.by`, `$effect.pre`). For Svelte 3/4 projects, stay on
+`@tanstack/svelte-table@8` — there is no v9 path that supports the legacy stores API.
+
+## How v9 state is wired in Svelte
+
+A table instance has three (and a half) state surfaces:
+
+- `table.baseAtoms.<slice>` — writable atoms created from the resolved initial state.
+- `table.atoms.<slice>` — readonly derived atoms, exposed per registered feature.
+- `table.store` — readonly flat TanStack Store, a derived view of all registered atoms.
+- `table.state` — the value returned by the optional selector passed as the second argument to
+  `createTable`. **Svelte-only surface.**
+
+The Svelte adapter installs `svelteReactivity()` as the `coreReativityFeature`:
+
+| Core concept  | Svelte binding  |
+| ------------- | --------------- |
+| readonly atom | `$derived.by()` |
+| writable atom | `$state`        |
+| subscription  | rune `$effect`  |
+| option sync   | `$effect.pre`   |
+| batch         | `flushSync`     |
+
+`createTable` reads reactive option getters inside `$effect.pre` so the table sees fresh data,
+columns, and controlled state **before** the DOM renders — `getRowModel()` is never a frame behind.
+
+## Feature-based state — registered features only
+
+State slices only exist for the features registered in `_features`. Reading
+`table.atoms.rowSelection` without `rowSelectionFeature` is a TypeScript error and a runtime
+`undefined`. **This is the most common v9 mistake.**
+
+```ts
+import {
+  createTable,
+  rowPaginationFeature,
+  rowSortingFeature,
+  tableFeatures,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+} from '@tanstack/svelte-table'
+
+const _features = tableFeatures({
+  rowPaginationFeature,
+  rowSortingFeature,
+})
+
+const table = createTable({
+  _features,
+  _rowModels: {
+    paginatedRowModel: createPaginatedRowModel(),
+    sortedRowModel: createSortedRowModel(sortFns),
+  },
+  columns,
+  get data() {
+    return data
+  },
+})
+
+table.atoms.pagination.get() // ok
+table.atoms.sorting.get() // ok
+// table.atoms.rowSelection  // TypeScript error
+```
+
+## Reading state — pick the right tool for the job
+
+### Current value, no reactivity
+
+Read the atom directly. Cheapest path; only reactive when called inside a rune-tracked context.
+
+```ts
+const sorting = table.atoms.sorting.get()
+const pagination = table.atoms.pagination.get()
+const flat = table.store.state
+```
+
+### Reactive read inside markup — `table.state` selector
+
+Pass a TanStack Store selector as the second argument to `createTable`. The selected value is
+exposed as `table.state`. The default selector returns the full registered state.
+
+```svelte
+<script lang="ts">
+  const table = createTable(
+    {
+      _features,
+      _rowModels: { paginatedRowModel: createPaginatedRowModel() },
+      columns,
+      get data() {
+        return data
+      },
+    },
+    (state) => ({ pagination: state.pagination }),
+  )
+</script>
+
+<strong>
+  Page {table.state.pagination.pageIndex + 1} of {table.getPageCount()}
+</strong>
+```
+
+### Fine-grained — `subscribeTable`
+
+`subscribeTable(source, selector?)` wraps a `useSelector` with `shallow` compare and returns an
+object whose `.current` is the selected value. Use it when only one block of markup should
+re-render on a state change.
+
+```ts
+import { subscribeTable } from '@tanstack/svelte-table'
+
+const pageIndex = subscribeTable(table.atoms.pagination, (p) => p.pageIndex)
+```
+
+```svelte
+<strong>Page {pageIndex.current + 1}</strong>
+```
+
+## Setting state — APIs first, atoms last
+
+Use the feature APIs. They handle updaters, external-atom routing, and validation:
+
+```ts
+table.nextPage()
+table.previousPage()
+table.setPageIndex(0)
+table.setPageSize(25)
+table.setSorting([{ id: 'age', desc: true }])
+column.toggleVisibility()
+row.toggleSelected()
+```
+
+Direct base-atom writes are a last resort:
+
+```ts
+table.baseAtoms.pagination.set((old) => ({ ...old, pageIndex: 0 }))
+```
+
+When a slice is owned by an external atom (passed through `atoms`), write to the external atom —
+`table.atoms.<slice>` will read from it, not from `baseAtoms`.
+
+## State ownership — three patterns
+
+### 1. Initial state only
+
+The default: set starting values, let the table own the rest. `initialState` also drives
+`resetSorting()`, `resetPagination()`, etc.
+
+```ts
+const table = createTable({
+  _features,
+  _rowModels: {},
+  columns,
+  get data() {
+    return data
+  },
+  initialState: {
+    sorting: [{ id: 'age', desc: true }],
+    pagination: { pageIndex: 0, pageSize: 25 },
+  },
+})
+```
+
+### 2. External atoms (recommended for shared state)
+
+When the app should own a slice, create a stable atom with `createAtom`, pass it through `atoms`,
+and subscribe with `useSelector` or `subscribeTable`. The table writes through the external atom
+on `setPageIndex`, `setSorting`, etc.
+
+```ts
+import { createAtom, useSelector } from '@tanstack/svelte-store'
+import {
+  createTable,
+  rowPaginationFeature,
+  rowSortingFeature,
+  tableFeatures,
+  type PaginationState,
+  type SortingState,
+} from '@tanstack/svelte-table'
+
+const _features = tableFeatures({
+  rowPaginationFeature,
+  rowSortingFeature,
+})
+
+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,
+  },
+})
+```
+
+When you use `atoms` for a slice, **do not** pair it with the matching `on[State]Change` callback.
+
+### 3. External `state` + `on[State]Change` (migration / simple cases)
+
+Classic pattern, still supported. Use Svelte 5 `$state` and getter properties so the table sees
+updates.
+
+```svelte
+<script lang="ts">
+  import {
+    createTable,
+    rowPaginationFeature,
+    rowSortingFeature,
+    tableFeatures,
+    type PaginationState,
+    type SortingState,
+  } from '@tanstack/svelte-table'
+
+  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>
+```
+
+> The v8-style monolithic `onStateChange` is gone in v9. Use per-slice `on[State]Change` or, better,
+> external atoms.
+
+### Precedence — do not mix sources
+
+External `atoms` win over external `state`. External `state` syncs into the internal base atom.
+For any given slice, pick **one** source of truth. Don't pass `initialState.pagination` and
+`atoms.pagination` and `state.pagination` together.
+
+## Rendering — `FlexRender`
+
+`FlexRender` handles `header`, `cell`, and `footer` definitions whether they're plain strings,
+Svelte components wrapped with `renderComponent`, or snippets wrapped with `renderSnippet`.
+
+```svelte
+<script lang="ts">
+  import {
+    FlexRender,
+    renderComponent,
+    renderSnippet,
+  } from '@tanstack/svelte-table'
+</script>
+
+<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.getVisibleCells() as cell (cell.id)}
+        <td><FlexRender {cell} /></td>
+      {/each}
+    </tr>
+  {/each}
+</tbody>
+```
+
+Always key `{#each}` blocks on stable ids (`headerGroup.id`, `header.id`, `row.id`, `cell.id`).
+
+## `createTableHook` — app-wide composition
+
+Create one configured hook per app: shared `_features`, `_rowModels`, defaults, and pre-bound
+component registries.
+
+```ts
+import {
+  createPaginatedRowModel,
+  createSortedRowModel,
+  createTableHook,
+  rowPaginationFeature,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from '@tanstack/svelte-table'
+import TextCell from './cells/TextCell.svelte'
+import SortIndicator from './headers/SortIndicator.svelte'
+
+export const {
+  createAppTable,
+  createAppColumnHelper,
+  useTableContext,
+  useCellContext,
+  useHeaderContext,
+} = createTableHook({
+  _features: tableFeatures({ rowPaginationFeature, rowSortingFeature }),
+  _rowModels: {
+    paginatedRowModel: createPaginatedRowModel(),
+    sortedRowModel: createSortedRowModel(sortFns),
+  },
+  cellComponents: { TextCell },
+  headerComponents: { SortIndicator },
+})
+```
+
+In components:
+
+```svelte
+<script lang="ts">
+  import { createAppTable, createAppColumnHelper } 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>
+
+<table.AppTable>
+  {#snippet children()}
+    <table>
+      <thead>
+        {#each table.getHeaderGroups() as group (group.id)}
+          <tr>
+            {#each group.headers as header (header.id)}
+              <table.AppHeader {header}>
+                {#snippet children(h)}
+                  <th><h.SortIndicator /></th>
+                {/snippet}
+              </table.AppHeader>
+            {/each}
+          </tr>
+        {/each}
+      </thead>
+    </table>
+  {/snippet}
+</table.AppTable>
+```
+
+Inside custom `cellComponents` / `headerComponents` / `tableComponents`, use `useCellContext()` /
+`useHeaderContext()` / `useTableContext()` instead of prop-drilling.
+
+## Common failure modes
+
+- **Svelte 4 code with v9 adapter.** Will not run. `$state` / `$derived.by` are Svelte 5 syntax.
+- **`createSvelteTable` import.** v8 name. v9 uses `createTable`. There is no `useSvelteTable`,
+  `getCoreRowModel`, `getSortedRowModel`, etc. — those are v8 names too.
+- **Forgetting `tableFeatures()`.** `_features` must come from `tableFeatures({...})` for type
+  inference; passing a raw object loses the typed state slice keys.
+- **Forgetting feature registration.** Calling `table.setSorting(...)` without
+  `rowSortingFeature` in `_features` is a runtime no-op (the API method won't exist).
+- **Mixing ownership.** `atoms.pagination` + `state.pagination` + `initialState.pagination` is
+  ambiguous; the table will not "merge" them the way you expect.
+- **Reactive getters dropped.** If you pass `data` as a plain value instead of a getter, the
+  table won't re-render when `data` changes. Always use `get data() { return data }`.
+- **Reimplementing built-ins.** If you're hand-rolling sorting comparators, pagination math, or
+  selection toggles, you're skipping `rowSortingFeature` / `rowPaginationFeature` /
+  `rowSelectionFeature` and their reset / state APIs. Register the feature instead.
+
+## Related skills
+
+- `tanstack-table/core/state-management` — atom model, slice precedence, base vs derived atoms.
+- `tanstack-table/svelte/getting-started` — end-to-end first table.
+- `tanstack-table/svelte/compose-with-tanstack-store` — direct atom interop.
+- `tanstack-table/svelte/production-readiness` — selector / subscription tuning.

package/src/reactivity.svelte.ts

@@ -38,6 +38,7 @@ function subscribeToRune<T>(
 export function svelteReactivity(): TableReactivityBindings {
   return {
     createOptionsStore: true,
+    schedule: (fn) => queueMicrotask(() => fn()),
     createReadonlyAtom: <T>(fn: () => T, _options?: TableAtomOptions<T>) => {
       const value = $derived.by(fn)