@tanstack/svelte-table 9.0.0-alpha.9 → 9.0.0-beta.10

package/skills/svelte/compose-with-tanstack-query/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: svelte/compose-with-tanstack-query
+description: >
+  Server-side / async data flow with `@tanstack/svelte-query` and `@tanstack/svelte-table`.
+  Key the `createQuery` on the table state that drives the request (pagination + sort +
+  filters), pass `placeholderData: keepPreviousData` to avoid a "0 rows flash" between pages,
+  set `manualPagination` (and optionally `manualSorting` / `manualFiltering`), supply
+  `rowCount`, and feed the query result through reactive getters (`get data()`,
+  `get rowCount()`). Own driver state with `$state` or `@tanstack/svelte-store` atoms.
+  Svelte 5+ only.
+type: composition
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.48'
+requires:
+  - svelte/client-to-server
+  - pagination
+  - state-management
+sources:
+  - TanStack/table:examples/svelte/with-tanstack-query/
+  - TanStack/table:docs/framework/svelte/guide/table-state.md
+---
+
+# Compose with TanStack Query (Svelte)
+
+`@tanstack/svelte-query` and `@tanstack/svelte-table` complement each other naturally:
+
+- **Query** owns server data — fetching, caching, retries, placeholder data.
+- **Table** owns view state — pagination, sort, filters, selection.
+
+The integration is short and predictable: drive the query key from the view state, manual-mode
+the affected pipeline stages, pipe the result back through reactive getters.
+
+## The pattern in 30 seconds
+
+```svelte
+<script lang="ts">
+  import { createQuery, keepPreviousData } from '@tanstack/svelte-query'
+  import {
+    createTable,
+    rowPaginationFeature,
+    tableFeatures,
+    type PaginationState,
+  } from '@tanstack/svelte-table'
+
+  const features = tableFeatures({ rowPaginationFeature })
+
+  let pagination: PaginationState = $state({ pageIndex: 0, pageSize: 10 })
+
+  const dataQuery = createQuery<{
+    rows: Array<Person>
+    rowCount: number
+  }>(() => ({
+    queryKey: ['people', pagination],
+    queryFn: () => fetchPeople(pagination),
+    placeholderData: keepPreviousData,
+  }))
+
+  const table = createTable({
+    features,
+    columns,
+    get data() {
+      return dataQuery.data?.rows ?? []
+    },
+    get rowCount() {
+      return dataQuery.data?.rowCount
+    },
+    state: {
+      get pagination() {
+        return pagination
+      },
+    },
+    onPaginationChange: (updater) => {
+      pagination = typeof updater === 'function' ? updater(pagination) : updater
+    },
+    manualPagination: true,
+  })
+</script>
+```
+
+Three things to notice:
+
+1. `queryKey` includes the driver state (`pagination`). Query re-fetches when the page or page
+   size changes.
+2. `placeholderData: keepPreviousData` keeps the previous page visible while the next page
+   loads. Without it, `dataQuery.data?.rows` is `undefined` for one tick on every page change
+   and the table flashes empty.
+3. `manualPagination: true` tells the table the data is already paged. Without `rowCount` the
+   pager has no idea how many pages exist.
+
+## Driver-state ownership choices
+
+You can drive the query from either:
+
+- **Component `$state` + `state` + `on[State]Change`** (shown above) — simplest, mirrors
+  what most v8 codebases look like after migration.
+- **External `@tanstack/svelte-store` atoms + `atoms`** — preferable when the same state
+  drives multiple components (a toolbar, a sidebar, a URL syncer).
+
+```ts
+import { createAtom, useSelector } from '@tanstack/svelte-store'
+
+const paginationAtom = createAtom<PaginationState>({
+  pageIndex: 0,
+  pageSize: 10,
+})
+const pagination = useSelector(paginationAtom)
+
+const dataQuery = createQuery(() => ({
+  queryKey: ['people', pagination.current],
+  queryFn: () => fetchPeople(pagination.current),
+  placeholderData: keepPreviousData,
+}))
+
+const table = createTable({
+  features,
+  columns,
+  get data() {
+    return dataQuery.data?.rows ?? []
+  },
+  get rowCount() {
+    return dataQuery.data?.rowCount
+  },
+  atoms: { pagination: paginationAtom },
+  manualPagination: true,
+})
+```
+
+`table.setPageIndex(2)` writes through `paginationAtom`, which invalidates `queryKey`, which
+fetches page 3.
+
+## Adding sort and filters
+
+```ts
+import type { ColumnFiltersState, SortingState } from '@tanstack/svelte-table'
+
+let sorting: SortingState = $state([])
+let filters: ColumnFiltersState = $state([])
+let pagination: PaginationState = $state({ pageIndex: 0, pageSize: 10 })
+
+const dataQuery = createQuery(() => ({
+  queryKey: ['people', pagination, sorting, filters],
+  queryFn: () => fetchPeople({ pagination, sorting, filters }),
+  placeholderData: keepPreviousData,
+}))
+
+const table = createTable({
+  features: tableFeatures({
+    rowPaginationFeature,
+    rowSortingFeature,
+    columnFilteringFeature,
+  }),
+  columns,
+  get data() {
+    return dataQuery.data?.rows ?? []
+  },
+  get rowCount() {
+    return dataQuery.data?.rowCount
+  },
+  state: {
+    get pagination() {
+      return pagination
+    },
+    get sorting() {
+      return sorting
+    },
+    get columnFilters() {
+      return filters
+    },
+  },
+  onPaginationChange: (u) =>
+    (pagination = typeof u === 'function' ? u(pagination) : u),
+  onSortingChange: (u) => (sorting = typeof u === 'function' ? u(sorting) : u),
+  onColumnFiltersChange: (u) =>
+    (filters = typeof u === 'function' ? u(filters) : u),
+  manualPagination: true,
+  manualSorting: true,
+  manualFiltering: true,
+})
+```
+
+## Reset page on filter / sort change
+
+Otherwise a user filters from "all 5000 people" to "5 named Alice" and stays on page 12.
+
+```ts
+$effect(() => {
+  // re-run on identity change
+  filters
+  sorting
+  table.setPageIndex(0)
+})
+```
+
+## Debounce keystroke-driven filters
+
+Without debouncing, a search input fires one request per character.
+
+```ts
+import { createDebouncer } from '@tanstack/svelte-pacer/debouncer'
+
+const debouncedSetGlobalFilter = createDebouncer(
+  (value: string) => table.setGlobalFilter(value),
+  { wait: 250 },
+)
+```
+
+```svelte
+<input
+  oninput={(e) => debouncedSetGlobalFilter.maybeExecute(e.currentTarget.value)}
+/>
+```
+
+See the `compose-with-tanstack-pacer` skill for the full pacer pattern.
+
+## Loading and empty states
+
+`createQuery` exposes `isFetching`, `isPending`, `isError`, `data`. Use them around the
+table, not inside the row loop.
+
+```svelte
+{#if dataQuery.isPending}
+  <div>Loading…</div>
+{:else if dataQuery.isError}
+  <div>Failed: {dataQuery.error.message}</div>
+{:else}
+  <table>...</table>
+{/if}
+
+{#if dataQuery.isFetching}
+  <small>Refreshing…</small>
+{/if}
+```
+
+`isFetching` is helpful for the "loading next page" indicator while
+`placeholderData: keepPreviousData` still shows the old rows.
+
+## Optimistic updates (when you also mutate)
+
+```ts
+import { createMutation, useQueryClient } from '@tanstack/svelte-query'
+
+const queryClient = useQueryClient()
+
+const updatePerson = createMutation(() => ({
+  mutationFn: (input: Partial<Person>) =>
+    fetch(`/api/people/${input.id}`, {
+      method: 'PATCH',
+      body: JSON.stringify(input),
+    }),
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: ['people'] }),
+}))
+```
+
+After the mutation succeeds, `invalidateQueries` re-fetches; `placeholderData` keeps the old
+rows visible during the refresh.
+
+## SvelteKit `load` integration (a sketch)
+
+If your table is on a SvelteKit page, `+page.ts` can hydrate the query cache with the first
+page so SSR renders rows immediately. Subsequent pages still go through `createQuery`.
+
+```ts
+// +page.ts
+export const load = async ({ fetch }) => {
+  const initial = await fetchPeople({ pageIndex: 0, pageSize: 10 }, fetch)
+  return { initial }
+}
+```
+
+```svelte
+<script lang="ts">
+  let { data } = $props()
+  // pass data.initial into placeholderData on first render
+</script>
+```
+
+## Common failure modes
+
+- **Forgot `rowCount`.** Pager shows zero pages.
+- **No `placeholderData: keepPreviousData`.** Empty-table flash on every page change.
+- **Forgot `manualPagination: true`.** Table tries to paginate the already-paged window.
+  `getPageCount()` returns 1.
+- **Driver state in `queryKey` is stale.** Always pass the current value, not a captured one.
+- **No reset on filter change.** Stays on dead pages.
+- **Plain `data: dataQuery.data?.rows`.** No reactivity — must be a getter.
+- **Re-creating `createQuery` inside `$effect`.** It's a one-time call; create it at component init.
+- **Reimplementing pagination math against `query.data` instead of calling
+  `table.nextPage()`.** Don't.
+
+## Related skills
+
+- `tanstack-table/svelte/client-to-server` — base server-side pattern (without Query).
+- `tanstack-table/svelte/compose-with-tanstack-store` — atom-based driver state.
+- `tanstack-table/svelte/compose-with-tanstack-pacer` — debounce / throttle high-frequency inputs.
+- `tanstack-table/core/pagination` — manual mode semantics.

package/skills/svelte/compose-with-tanstack-store/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: svelte/compose-with-tanstack-store
+description: >
+  TanStack Table v9 is built on TanStack Store. Each state slice (sorting, pagination,
+  rowSelection, columnFilters, ...) is a separate atom. In Svelte, `@tanstack/svelte-store`
+  exposes `createAtom`, `useSelector`, `shallow`. Read `table.atoms.<slice>` per slice,
+  `table.store` flat, or `table.state` for the selector projection. Subscribe with
+  `subscribeTable(atom, selector?)` (returns `.current`). Own a slice externally with
+  `createAtom` + `atoms: { sorting: sortingAtom }`. Svelte 5+ only — `$state` / `$derived.by` /
+  `$effect.pre` reactivity.
+type: composition
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.48'
+requires:
+  - state-management
+sources:
+  - TanStack/table:docs/framework/svelte/guide/table-state.md
+  - TanStack/table:packages/svelte-table/src/reactivity.svelte.ts
+  - TanStack/table:packages/svelte-table/src/subscribe.ts
+  - TanStack/table:examples/svelte/basic-external-atoms/
+---
+
+# Compose with TanStack Store (Svelte)
+
+`@tanstack/svelte-store` is the reactive primitive under `@tanstack/svelte-table` v9. The
+table doesn't merely _use_ Store — its entire reactivity model is built from Store atoms with
+rune backings.
+
+## Mental model — three read surfaces
+
+A registered v9 table exposes:
+
+| Surface               | Shape                       | When to use                                |
+| --------------------- | --------------------------- | ------------------------------------------ |
+| `table.atoms.<slice>` | `ReadonlyAtom<TSlice>`      | Per-slice subscription / `.get()` snapshot |
+| `table.store`         | `ReadonlyStore<FlatState>`  | Flat snapshot across registered slices     |
+| `table.state`         | `TSelected` (from selector) | The selector projection (Svelte-only)      |
+
+Plus the writable internals:
+
+- `table.baseAtoms.<slice>` — writable atom for state the table owns.
+
+If a slice is supplied externally via `atoms`, `table.atoms.<slice>` reads from your atom and
+`table.baseAtoms.<slice>` is unused for that slice.
+
+## The Svelte bindings (what `svelteReactivity()` actually does)
+
+The Svelte adapter ships `svelteReactivity()` and installs it as `coreReactivityFeature`. It
+maps Store primitives to runes:
+
+- Readonly atoms → `$derived.by(fn)`
+- Writable atoms → `$state(initialValue)`
+- Subscriptions → `$effect.root` + `$effect`
+- Batch → `flushSync`
+
+This is why simple atom reads inside `.svelte` components (templates, `$derived`, `$effect`)
+participate in reactivity automatically. There is no React-style `useStore` requirement.
+
+## Pattern 1 — Read a slice without subscribing
+
+For event handlers, async work, exports, anything outside of reactive markup. Cheap, no
+subscription setup.
+
+```ts
+import type { SortingState } from '@tanstack/svelte-table'
+
+function logSort() {
+  const sorting: SortingState = table.atoms.sorting.get()
+  console.log(sorting)
+}
+```
+
+`table.state` is the full snapshot equivalent.
+
+## Pattern 2 — Reactive selector via `createTable`
+
+The second argument to `createTable` is a TanStack Store selector. The result is exposed on
+`table.state`. The default selector is `(state) => state`.
+
+```svelte
+<script lang="ts">
+  const table = createTable(
+    {
+      features,
+      columns,
+      get data() {
+        return data
+      },
+    },
+    (state) => ({
+      pageIndex: state.pagination.pageIndex,
+      pageSize: state.pagination.pageSize,
+    }),
+  )
+</script>
+
+<strong>Page {table.state.pageIndex + 1}</strong>
+```
+
+The narrower the selector, the less your markup re-renders.
+
+## Pattern 3 — Per-block subscription with `subscribeTable`
+
+`subscribeTable(source, selector?)` is the dedicated per-component subscription. It uses
+`shallow` compare and exposes a `.current` accessor.
+
+```svelte
+<script lang="ts">
+  import { subscribeTable } from '@tanstack/svelte-table'
+
+  // whole slice
+  const pagination = subscribeTable(table.atoms.pagination)
+
+  // narrowed
+  const pageSize = subscribeTable(table.atoms.pagination, (p) => p.pageSize)
+
+  // works on table.store too
+  const fullSnapshot = subscribeTable(table.store)
+</script>
+
+<span
+  >Page {pagination.current.pageIndex + 1} ({pageSize.current} per page)</span
+>
+```
+
+Inside per-row components, `subscribeTable(table.atoms.rowSelection, (s) => !!s[row.id])` keeps
+that row's checkbox reactive without subscribing to the entire selection map.
+
+## Pattern 4 — Own a slice externally with `createAtom`
+
+When the app should own a slice — share across components, sync with URL, persist to storage —
+create a stable atom and hand it to the table via `atoms`.
+
+```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,
+})
+
+// Optional: a Svelte-reactive view onto each atom for use in markup.
+const sorting = useSelector(sortingAtom)
+const pagination = useSelector(paginationAtom)
+
+const table = createTable({
+  features,
+  columns,
+  get data() {
+    return data
+  },
+  atoms: {
+    sorting: sortingAtom,
+    pagination: paginationAtom,
+  },
+})
+
+// table.setPageIndex(2) writes through paginationAtom.
+// paginationAtom.set(...) updates table.atoms.pagination immediately.
+```
+
+Atom precedence: external `atoms.<slice>` wins over external `state.<slice>` which writes
+into the internal `baseAtoms.<slice>`. **Never combine them on the same slice.**
+
+## Pattern 5 — Cross-component / cross-module state
+
+Because atoms are first-class subscribable values, you can read them outside the table component.
+
+```ts
+// stores/table-state.ts
+import { createAtom } from '@tanstack/svelte-store'
+import type { RowSelectionState } from '@tanstack/svelte-table'
+
+export const rowSelectionAtom = createAtom<RowSelectionState>({})
+```
+
+```svelte
+<!-- Toolbar.svelte -->
+<script lang="ts">
+  import { useSelector } from '@tanstack/svelte-store'
+  import { rowSelectionAtom } from './stores/table-state'
+
+  const selection = useSelector(rowSelectionAtom)
+  const selectedCount = $derived(
+    Object.values(selection.current).filter(Boolean).length,
+  )
+</script>
+
+<button disabled={selectedCount === 0}>Delete {selectedCount}</button>
+```
+
+```svelte
+<!-- TablePage.svelte -->
+<script lang="ts">
+  import { rowSelectionAtom } from './stores/table-state'
+
+  const table = createTable({
+    features,
+    columns,
+    get data() {
+      return data
+    },
+    atoms: { rowSelection: rowSelectionAtom },
+  })
+</script>
+```
+
+## Pattern 6 — `useSelector` with custom equality
+
+`useSelector(source, selector, { compare })` lets you switch comparison strategies — useful
+for object selectors so you don't re-fire on every reference change.
+
+```ts
+import { shallow, useSelector } from '@tanstack/svelte-store'
+
+const filterValues = useSelector(
+  table.atoms.columnFilters,
+  (filters) => Object.fromEntries(filters.map((f) => [f.id, f.value])),
+  { compare: shallow },
+)
+```
+
+`subscribeTable` already uses `shallow` by default, so prefer it for table sources unless you
+need a custom compare.
+
+## Pattern 7 — Direct base-atom writes (last resort)
+
+When a slice is internally owned and you really need to write outside a feature API:
+
+```ts
+table.baseAtoms.pagination.set((old) => ({ ...old, pageIndex: 0 }))
+```
+
+Do not do this for externally-owned slices — write to your external atom instead. The base
+atom is dormant in that case and your write will be silently ignored next sync.
+
+## Common failure modes
+
+- **Reading a slice that wasn't registered.** `table.atoms.rowSelection` is `undefined` if
+  `rowSelectionFeature` isn't in `features`. TS will catch it if you used `tableFeatures()`.
+- **Creating atoms inside reactive blocks.** Atoms must be stable. Module scope or top-level
+  component scope, never inside `$derived` / `$effect`.
+- **`useSelector` without `.current`.** `selection.pageIndex` is wrong — `selection.current.pageIndex`.
+- **Mixing `atoms.X` and `state.X`.** Atom wins, callback never fires.
+- **`tableState` as a plain object.** No reactivity. Use `subscribeTable`, `useSelector`, or
+  the `createTable` selector.
+- **Reimplementing `useSelector` with `$effect`.** Built-in is more efficient and uses
+  shallow compare.
+
+## Related skills
+
+- `tanstack-table/svelte/table-state` — full reactivity model and selector patterns.
+- `tanstack-table/core/state-management` — atom precedence rules.
+- `tanstack-table/svelte/client-to-server` — atoms as the data-driver for server queries.
+- `tanstack-table/svelte/production-readiness` — selector / subscription tuning.