@tanstack/svelte-table 9.0.0-beta.37 → 9.0.0-beta.42

package/skills/table-state/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: table-state
+description: >
+  Use Svelte 5 rune-backed table.atoms/store and selected table.state, reactive option getters, controlled $state slices, value-or-updater callbacks, external atoms, and auto-reset behavior without snapshot mismatches.
+metadata:
+  type: framework
+  library: '@tanstack/svelte-table'
+  framework: svelte
+  library_version: '9.0.0-beta.42'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+sources:
+  - 'TanStack/table:docs/framework/svelte/guide/table-state.md'
+  - 'TanStack/table:docs/framework/svelte/guide/pagination.md'
+  - 'TanStack/table:examples/svelte/basic-external-state'
+  - 'TanStack/table:packages/svelte-table/src/createTable.svelte.ts'
+---
+
+This skill builds on `@tanstack/table-core#core` and `getting-started`. Read them first for table ownership and Svelte construction.
+
+## State Mental Model
+
+TanStack Table is primarily a state coordinator. Keep state internal unless another system must read, persist, or drive it. Without `initialState`, `atoms`, `state`, or `on[State]Change`, the table owns all registered slices.
+
+- `table.baseAtoms` are internal writable atoms initialized from resolved initial state.
+- `table.atoms` are readonly derived atoms for the active owner of each registered slice.
+- `table.store` is the readonly flat store assembled from those atoms.
+- `table.state` is only the result selected by the second `createTable` argument.
+
+Svelte 5 backs these surfaces with runes and synchronizes reactive options before DOM updates. Only registered features create state and types. If pagination is missing, register `rowPaginationFeature`; do not add a cast or an ad hoc state field. Keep `features` and `columns` stable and pass changing `data` through a getter.
+
+## Setup
+
+Keep state internal unless another subsystem needs to own it. Select only render state that the component needs.
+
+```svelte
+<script lang="ts">
+  import {
+    createTable,
+    rowPaginationFeature,
+    tableFeatures,
+  } from '@tanstack/svelte-table'
+
+  const features = tableFeatures({ rowPaginationFeature })
+  const columns = [{ accessorKey: 'name' }]
+  let data = $state([{ name: 'Ada' }])
+  const table = createTable(
+    {
+      features,
+      columns,
+      get data() {
+        return data
+      },
+    },
+    (state) => ({ pagination: state.pagination }),
+  )
+</script>
+
+<button onclick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
+  Page {table.state.pagination.pageIndex + 1}
+</button>
+```
+
+## Core Patterns
+
+### Control a slice with value-or-updater semantics
+
+```ts
+import type { PaginationState, Updater } from '@tanstack/svelte-table'
+
+let pagination = $state<PaginationState>({ pageIndex: 0, pageSize: 20 })
+const updatePagination = (next: Updater<PaginationState>) => {
+  pagination = typeof next === 'function' ? next(pagination) : next
+}
+```
+
+Pass `get state() { return { pagination } }` and `onPaginationChange: updatePagination` to `createTable`.
+
+### Subscribe narrowly outside selected table.state
+
+```ts
+import { subscribeTable } from '@tanstack/svelte-table'
+
+const pageIndex = subscribeTable(
+  table.atoms.pagination,
+  (value) => value.pageIndex,
+)
+```
+
+Read `pageIndex.current` in rune-tracked Svelte code. Use feature APIs for writes; `baseAtoms` is a low-level escape hatch.
+
+## Choose State Ownership
+
+Use one owner per slice:
+
+- Prefer internal state plus feature APIs for table-local interaction.
+- Use `initialState` for starting/reset values; changing it later does not reset state.
+- Prefer a stable external atom in `atoms` for state shared with Query, routing, or another component. Do not also add its change callback.
+- Use a `$state` value exposed through a `state` getter plus the matching callback for simple controlled state. Always resolve value-or-updater semantics.
+
+External atoms win over controlled `state`, which syncs into the internal base atom. Avoid multiple owners. The global v8 `onStateChange` option is gone; subscribe to `table.store` if all state changes must be observed.
+
+## Initialize, Update, and Reset
+
+Prefer `setSorting`, `nextPage`, `toggleVisibility`, `toggleSelected`, and other feature APIs over direct state writes. Write a base atom only for rare internal-state needs; write the external atom when `atoms.<slice>` owns it.
+
+```ts
+table.resetSorting()
+table.resetPagination()
+table.resetPagination(true)
+```
+
+Feature resets use `table.initialState` unless `true` requests the feature default and can flow to external owners. Core `table.reset()` resets internal base atoms only. Use feature types such as `PaginationState` for a slice and `TableState<typeof features>` for the complete registered state.
+
+## Common Mistakes
+
+### HIGH Controlling without writing back
+
+Wrong:
+
+```ts
+const options = { state: { pagination }, onPaginationChange: console.log }
+```
+
+Correct:
+
+```ts
+const options = {
+  get state() {
+    return { pagination }
+  },
+  onPaginationChange: updatePagination,
+}
+```
+
+A controlled slice is frozen unless every updater is resolved into the owning rune.
+
+Source: `docs/framework/svelte/guide/table-state.md`
+
+### HIGH Reading snapshots outside tracking
+
+Wrong:
+
+```ts
+const pageIndex = table.store.state.pagination.pageIndex
+```
+
+Correct:
+
+```ts
+const pageIndex = subscribeTable(
+  table.atoms.pagination,
+  (value) => value.pageIndex,
+)
+```
+
+`store.state` is a current snapshot; it does not create a future Svelte update outside a tracked scope.
+
+Source: `packages/svelte-table/src/createTable.svelte.ts`
+
+### MEDIUM Declaring one slice in two owners
+
+Wrong:
+
+```ts
+const options = { initialState: { pagination: start }, state: { pagination } }
+```
+
+Correct:
+
+```ts
+const options = {
+  get state() {
+    return { pagination }
+  },
+}
+```
+
+Controlled `atoms` or `state` wins over `initialState`; choose one owner per slice.
+
+Source: `docs/framework/svelte/guide/table-state.md`
+
+### MEDIUM Fighting automatic page reset
+
+Wrong:
+
+```ts
+table.setPageIndex(4)
+data = filteredData
+```
+
+Correct:
+
+```ts
+const options = { autoResetPageIndex: false }
+```
+
+Client row-model changes reset the page by default; disable it only when the application handles invalid empty pages.
+
+Source: `docs/framework/svelte/guide/pagination.md`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/svelte-table/src/createTable.svelte.ts`, `createTableState.svelte.ts`, and `subscribe.ts`; inspect registered state slices in the matching core feature source.

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

@@ -0,0 +1,147 @@
+---
+name: with-tanstack-query
+description: >
+  Compose Svelte Query with Svelte Table manual filtering, sorting, and pagination using reactive query inputs, query-result data getters, server counts, and a single source of server-data truth.
+metadata:
+  type: composition
+  library: '@tanstack/svelte-table'
+  framework: svelte
+  library_version: '9.0.0-beta.42'
+requires:
+  - '@tanstack/table-core#client-vs-server'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:examples/svelte/with-tanstack-query'
+  - 'TanStack/table:docs/framework/svelte/guide/pagination.md'
+---
+
+This skill builds on `@tanstack/table-core#client-vs-server`, `getting-started`, and `table-state`. Decide which row-processing stages the server owns before composing Query.
+
+## Setup
+
+```ts
+import { createQuery, keepPreviousData } from '@tanstack/svelte-query'
+import {
+  createTable,
+  rowPaginationFeature,
+  tableFeatures,
+} from '@tanstack/svelte-table'
+
+const features = tableFeatures({ rowPaginationFeature })
+let pagination = $state({ pageIndex: 0, pageSize: 20 })
+const defaultData: Array<{ name: string }> = []
+const dataQuery = createQuery<{
+  rows: Array<{ name: string }>
+  rowCount: number
+}>(() => ({
+  queryKey: ['people', pagination.pageIndex, pagination.pageSize],
+  queryFn: () =>
+    fetch(
+      `/api/people?page=${pagination.pageIndex}&size=${pagination.pageSize}`,
+    ).then((r) => r.json()),
+  placeholderData: keepPreviousData,
+}))
+const table = createTable({
+  features,
+  columns,
+  get data() {
+    return dataQuery.data?.rows ?? defaultData
+  },
+  get rowCount() {
+    return dataQuery.data?.rowCount ?? 0
+  },
+  manualPagination: true,
+  get state() {
+    return { pagination }
+  },
+  onPaginationChange: (next) => {
+    pagination = typeof next === 'function' ? next(pagination) : next
+  },
+})
+```
+
+## Core Patterns
+
+### Put every server-owned stage in the query key
+
+If sorting or filtering is manual too, control those slices and include their serializable values in `queryKey`. Return data already processed in that same order.
+
+### Keep Query as server-data owner
+
+Expose `dataQuery.data` through Table getters. Copy it into `$state` only when the application explicitly owns an editable draft and defines cache synchronization.
+
+## Common Mistakes
+
+### HIGH Building a non-reactive query
+
+Wrong:
+
+```ts
+const query = createQuery({
+  queryKey: ['people', pagination.pageIndex],
+  queryFn,
+})
+```
+
+Correct:
+
+```ts
+const query = createQuery(() => ({
+  queryKey: ['people', pagination.pageIndex],
+  queryFn,
+}))
+```
+
+The options function lets Svelte Query track the rune read and refetch on page changes.
+
+Source: `examples/svelte/with-tanstack-query/src/App.svelte`
+
+### HIGH Expecting manual mode to fetch
+
+Wrong:
+
+```ts
+const options = { manualPagination: true }
+```
+
+Correct:
+
+```ts
+const options = {
+  manualPagination: true,
+  get data() {
+    return dataQuery.data?.rows ?? defaultData
+  },
+}
+```
+
+Manual mode only bypasses Table pagination; Query or application code performs the request. Hoist `defaultData` instead of creating a new `[]` from a repeatedly evaluated getter.
+
+Source: `docs/framework/svelte/guide/pagination.md`
+
+### HIGH Omitting total counts
+
+Wrong:
+
+```ts
+const options = { manualPagination: true, data: pageRows }
+```
+
+Correct:
+
+```ts
+const options = {
+  manualPagination: true,
+  data: pageRows,
+  rowCount: response.rowCount,
+}
+```
+
+Table cannot derive navigation limits from one server page; provide `rowCount` or `pageCount`.
+
+Source: `docs/framework/svelte/guide/pagination.md`
+
+## API Discovery
+
+Inspect `node_modules/@tanstack/svelte-table/src/index.ts` for adapter APIs and installed `@tanstack/svelte-query/src` for the exact Query version. Table manual-stage options live in the matching core feature source.

package/skills/with-tanstack-virtual/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: with-tanstack-virtual
+description: >
+  Virtualize Svelte Table final row or column models with reactive counts and scroll targets, stable keys, dynamic measurement, absolute transforms, sticky regions, grid/flex sizing, and infinite data.
+metadata:
+  type: composition
+  library: '@tanstack/svelte-table'
+  framework: svelte
+  library_version: '9.0.0-beta.42'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:docs/framework/svelte/guide/virtualization.md'
+  - 'TanStack/table:examples/svelte/virtualized-rows'
+  - 'TanStack/table:examples/svelte/virtualized-columns'
+  - 'TanStack/table:examples/svelte/virtualized-infinite-scrolling'
+---
+
+This skill builds on `@tanstack/table-core#core`, `getting-started`, and `table-state`. Virtual is a rendering layer over Table’s final model, never a `tableFeatures` plugin.
+
+## Setup
+
+```svelte
+<script lang="ts">
+  import { get } from 'svelte/store'
+  import { createVirtualizer } from '@tanstack/svelte-virtual'
+
+  let scrollElement = $state<HTMLDivElement>()
+  const rows = $derived(table.getRowModel().rows)
+  const rowVirtualizer = createVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollElement ?? null,
+    estimateSize: () => 34,
+    getItemKey: (index) => rows[index]!.id,
+    overscan: 5,
+  })
+
+  // The store adapter does not track getter options. Push reactive inputs.
+  $effect(() => {
+    get(rowVirtualizer).setOptions({
+      count: rows.length,
+      getScrollElement: () => scrollElement ?? null,
+    })
+  })
+</script>
+
+<div
+  bind:this={scrollElement}
+  style="height: 500px; overflow: auto; position: relative"
+>
+  <div style:height={`${$rowVirtualizer.getTotalSize()}px`}>
+    {#each $rowVirtualizer.getVirtualItems() as item (item.key)}
+      <div style={`position:absolute;transform:translateY(${item.start}px)`}>
+        {rows[item.index].id}
+      </div>
+    {/each}
+  </div>
+</div>
+```
+
+## Core Patterns
+
+### Virtualize visible models
+
+Use `table.getRowModel().rows` for rows and `table.getVisibleLeafColumns()` for columns. Recompute counts when filtering, sorting, expansion, or visibility changes.
+
+### Make CSS geometry agree with measurement
+
+Use one scroll container, a total-size spacer, positioned items, and either fixed estimates or `measureElement`. For semantic tables with dynamic rows, follow the maintained grid/flex examples rather than assuming native table layout will honor transforms.
+
+### Fetch before the virtual end
+
+In infinite scrolling, compare the last virtual item with fetched row count, then request the next Query page only when more server rows exist and no fetch is active.
+
+## Common Mistakes
+
+### HIGH Virtualizing raw data
+
+Wrong:
+
+```ts
+const rows = data
+```
+
+Correct:
+
+```ts
+const rows = $derived(table.getRowModel().rows)
+```
+
+Raw data ignores Table filtering, sorting, grouping, expansion, and pagination decisions.
+
+Source: `examples/svelte/virtualized-rows/src/App.svelte`
+
+### HIGH Expecting getter options to stay reactive
+
+Wrong:
+
+```ts
+const virtualizer = createVirtualizer({
+  get count() {
+    return rows.length
+  },
+  getScrollElement,
+})
+```
+
+Correct:
+
+```ts
+const virtualizer = createVirtualizer({ count: rows.length, getScrollElement })
+$effect(() => {
+  get(virtualizer).setOptions({
+    count: rows.length,
+    getScrollElement,
+  })
+})
+```
+
+`createVirtualizer` returns a Svelte store, and its adapter does not track getter options. Push rune-derived counts and the bound scroll element with `$effect` and `get(store).setOptions(...)`.
+
+Source: `examples/svelte/virtualized-rows/src/App.svelte`
+
+### HIGH Omitting the geometry contract
+
+Wrong:
+
+```svelte
+{#each rowVirtualizer.getVirtualItems() as item}<div>
+    {rows[item.index].id}
+  </div>{/each}
+```
+
+Correct:
+
+```svelte
+<div style:height={`${$rowVirtualizer.getTotalSize()}px`}>
+  <div style="position:absolute"></div>
+</div>
+```
+
+Virtual supplies ranges and measurements, not spacer height, transforms, sticky regions, or column widths. In markup, call virtualizer methods through the store auto-subscription (`$rowVirtualizer`); use `get(rowVirtualizer)` in script code.
+
+Source: `docs/framework/svelte/guide/virtualization.md`
+
+## API Discovery
+
+Inspect installed `@tanstack/svelte-table/src` for Table APIs and `@tanstack/svelte-virtual/src` for the exact virtualizer options. Use the maintained Svelte examples for layout combinations.