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

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

@@ -0,0 +1,176 @@
+---
+name: svelte/compose-with-tanstack-pacer
+description: >
+  Use `@tanstack/svelte-pacer` to debounce / throttle high-frequency writes that drive a
+  `@tanstack/svelte-table` v9 instance — column filter inputs and column resize state are the
+  two hot paths. Import `createDebouncer` (or `createThrottler`) from
+  `@tanstack/svelte-pacer/debouncer`, wrap the call site that hits `column.setFilterValue`,
+  `table.setGlobalFilter`, or commits a resize, and call `.maybeExecute(value)` on each event.
+  Svelte 5+ only — pacer instances live at component-init scope.
+type: composition
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.48'
+requires:
+  - filtering
+  - column-layout
+sources:
+  - TanStack/table:examples/svelte/with-tanstack-form/
+  - TanStack/table:docs/framework/svelte/guide/table-state.md
+---
+
+# Compose with TanStack Pacer (Svelte)
+
+Two places in a v9 table take state writes at event-loop rate: **filter inputs** (one
+keystroke = one `setFilterValue`) and **column resizing** (one pointermove = one
+`columnSizing` write). Without rate-limiting they either flood the network (server-side
+filtering) or burn CPU on tens of thousands of re-renders per drag.
+
+`@tanstack/svelte-pacer` gives you `createDebouncer`, `createThrottler`, and friends. Wrap
+the call site and you're done.
+
+## Install
+
+```bash
+pnpm add @tanstack/svelte-pacer
+```
+
+## Debounce a column filter input
+
+Client-side debouncing reduces re-render churn. Server-side debouncing also kills request
+storms.
+
+```svelte
+<script lang="ts">
+  import { createDebouncer } from '@tanstack/svelte-pacer/debouncer'
+  import type { Column } from '@tanstack/svelte-table'
+
+  type Props = { column: Column<typeof _features, Person> }
+  let { column }: Props = $props()
+
+  let localValue = $state((column.getFilterValue() as string) ?? '')
+
+  const debouncedSetFilter = createDebouncer(
+    (value: string) => column.setFilterValue(value),
+    { wait: 200 },
+  )
+
+  function onInput(e: Event) {
+    const value = (e.target as HTMLInputElement).value
+    localValue = value
+    debouncedSetFilter.maybeExecute(value)
+  }
+</script>
+
+<input type="text" value={localValue} oninput={onInput} placeholder="Search…" />
+```
+
+Why the `localValue`? So the input stays snappy (controlled by `$state`) while the table only
+sees the debounced commit.
+
+## Debounce a global filter
+
+Same shape, calling `table.setGlobalFilter`:
+
+```svelte
+<script lang="ts">
+  import { createDebouncer } from '@tanstack/svelte-pacer/debouncer'
+
+  let search = $state('')
+  const debouncedSetGlobalFilter = createDebouncer(
+    (value: string) => table.setGlobalFilter(value),
+    { wait: 250 },
+  )
+</script>
+
+<input
+  type="text"
+  value={search}
+  oninput={(e) => {
+    search = (e.target as HTMLInputElement).value
+    debouncedSetGlobalFilter.maybeExecute(search)
+  }}
+/>
+```
+
+## Throttle column resizing
+
+`columnResizingFeature` writes to `columnSizing` continuously. v9 supports `columnResizeMode:
+'onChange' | 'onEnd'` — the default is `'onChange'` (commit per-frame). For very heavy tables,
+either:
+
+1. Set `columnResizeMode: 'onEnd'` so the commit only happens at pointerup.
+2. Or, keep `'onChange'` for the visual handle but throttle the side effects you fire off it.
+
+Throttle a side effect:
+
+```ts
+import { createThrottler } from '@tanstack/svelte-pacer/throttler'
+
+const throttledSaveSizing = createThrottler(
+  (sizing: ColumnSizingState) => persistColumnSizingToStorage(sizing),
+  { wait: 100 },
+)
+
+$effect(() => {
+  const sizing = table.atoms.columnSizing.get()
+  throttledSaveSizing.maybeExecute(sizing)
+})
+```
+
+## Patterns to avoid
+
+### Don't debounce inside a `$effect`
+
+```ts
+// WRONG — new debouncer instance every effect re-run
+$effect(() => {
+  const d = createDebouncer((v) => column.setFilterValue(v), { wait: 200 })
+  d.maybeExecute(value)
+})
+```
+
+Pacer instances must be stable. Declare them once at component init scope.
+
+### Don't debounce things that should be immediate
+
+Selection toggles, page changes, sort clicks — these are user-driven discrete events. Don't
+debounce them. The user expects instant feedback.
+
+### Don't double-commit
+
+```ts
+// WRONG — local state syncs immediately AND the debounced commit fires
+oninput={(e) => {
+  column.setFilterValue(e.currentTarget.value)
+  debouncedSetFilter.maybeExecute(e.currentTarget.value)
+}}
+```
+
+Pick one. If you want a snappy input, store the input value in local `$state` and only call
+the debounced commit.
+
+## Coordinating with TanStack Query
+
+If your filter triggers a server query, debouncing the filter handler is necessary but not
+sufficient — `placeholderData: keepPreviousData` is what keeps the UI from flashing. See the
+`compose-with-tanstack-query` skill.
+
+## Common failure modes
+
+- **Recreating pacer instances inside `$effect` / `$derived`.** Each re-run produces a fresh
+  debouncer; nothing is ever delayed.
+- **Hand-rolled `setTimeout` debounce.** Loses leading-edge / trailing-edge guarantees; harder
+  to cancel on unmount. Use pacer.
+- **Debouncing a value that drives layout.** Causes user-visible lag where there shouldn't
+  be. Keep the input controlled by local state and only debounce the table-write call.
+- **Forgetting to call `.maybeExecute`.** Constructing a debouncer doesn't enqueue anything;
+  you have to call `.maybeExecute(value)` per event.
+- **Reimplementing pacer with `$effect` timers.** Don't.
+
+## Related skills
+
+- `tanstack-table/core/filtering` — column / global filter mechanics.
+- `tanstack-table/core/column-layout` — column resizing modes (`onChange` vs `onEnd`).
+- `tanstack-table/svelte/compose-with-tanstack-query` — pairing pacer with server queries.
+- `tanstack-table/svelte/production-readiness` — where pacer fits in the perf checklist.

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

@@ -0,0 +1,299 @@
+---
+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,
+    _rowModels: {},
+    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,
+  _rowModels: {},
+  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,
+  }),
+  _rowModels: {},
+  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.