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

package/skills/table-state/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: table-state
+description: >
+  Use Svelte 5 rune-aware table atoms and stores, $derived projections, reactive option getters, controlled $state or createTableState slices, external atoms, and auto-reset behavior without broad invalidation or snapshot mismatches.
+metadata:
+  type: framework
+  library: '@tanstack/svelte-table'
+  framework: svelte
+  library_version: '9.0.0-beta.71'
+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'
+  - 'TanStack/table:packages/svelte-table/src/createTableState.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.
+
+The Svelte adapter bridges TanStack Store dependency tracking into Svelte runes. `table.atoms.<slice>.get()`, `table.store.get()`, and table APIs become reactive when called in a template, `$derived`, `$derived.by`, or `$effect`. Outside those contexts they return current snapshots.
+
+Only registered features create state and types. If pagination is missing, register `rowPaginationFeature`; do not add a cast or 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. Read only the state slices a 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
+    },
+  })
+
+  const pagination = $derived(table.atoms.pagination.get())
+</script>
+
+<button onclick={() => table.nextPage()} disabled={!table.getCanNextPage()}>
+  Page {pagination.pageIndex + 1}
+</button>
+```
+
+## Core Patterns
+
+### Read narrow or complete state
+
+```ts
+const pagination = $derived(table.atoms.pagination.get())
+const pageIndex = $derived(table.atoms.pagination.get().pageIndex)
+const rows = $derived(table.getRowModel().rows)
+const stateJson = $derived(JSON.stringify(table.store.get(), null, 2))
+```
+
+Use atom reads for normal UI. A `table.store.get()` read intentionally re-runs for any registered state change, so reserve it for debug output, persistence, or computations that need the whole state.
+
+### 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 a getter-backed `state.pagination` and `onPaginationChange: updatePagination` to `createTable`.
+
+### Reduce boilerplate with `createTableState`
+
+```ts
+import {
+  createTable,
+  createTableState,
+  rowPaginationFeature,
+  tableFeatures,
+  type PaginationState,
+} from '@tanstack/svelte-table'
+
+const features = tableFeatures({ rowPaginationFeature })
+const columns = [{ accessorKey: 'name' }]
+const data = [{ name: 'Ada' }]
+const [pagination, setPagination] = createTableState<PaginationState>({
+  pageIndex: 0,
+  pageSize: 20,
+})
+
+const table = createTable({
+  features,
+  columns,
+  data,
+  state: {
+    get pagination() {
+      return pagination()
+    },
+  },
+  onPaginationChange: setPagination,
+})
+```
+
+For better or worse, this resembles a small React `useState` hook: `pagination()` reads the current rune-backed value, while `setPagination` accepts either a value or a functional updater and can be passed directly to `onPaginationChange`.
+
+## 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.
+- Use Svelte `$state`, a getter-backed `state` entry, and the matching callback for normal Svelte-owned controlled state.
+- Use a stable external atom in `atoms` for state shared as a raw TanStack Store atom. Do not also add its change callback.
+
+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 every state change must be observed imperatively.
+
+When code outside the table consumes a raw external atom, use `useSelector` from `@tanstack/svelte-store`. Inside table-driven UI, read the rune-aware `table.atoms.<slice>.get()` wrapper.
+
+## 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 Keeping removed adapter selectors
+
+Wrong:
+
+```ts
+const table = createTable(options, (state) => state.pagination)
+const pageIndex = table.state.pageIndex
+```
+
+Correct:
+
+```ts
+const table = createTable(options)
+const pagination = $derived(table.atoms.pagination.get())
+```
+
+Starting in beta.59, `createTable` and `createAppTable` take only options, `table.state` is absent, and `subscribeTable` and `SubscribeSource` are no longer exported. Use native tracked Svelte reads and `$derived` projections.
+
+Source: `docs/framework/svelte/guide/migrating.md`
+
+### HIGH Controlling without writing back
+
+Wrong:
+
+```ts
+const options = { state: { pagination }, onPaginationChange: console.log }
+```
+
+Correct:
+
+```ts
+const options = {
+  state: {
+    get pagination() {
+      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 Snapshotting outside tracking
+
+Wrong:
+
+```ts
+const pageIndex = table.store.get().pagination.pageIndex
+```
+
+Correct inside a component:
+
+```ts
+const pageIndex = $derived(table.atoms.pagination.get().pageIndex)
+```
+
+The first line is only a current snapshot when it runs outside a template or rune. The second line is a narrow native Svelte derivation.
+
+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 = {
+  state: {
+    get pagination() {
+      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/dist/createTable.svelte.d.ts`, `createTableHook.svelte.d.ts`, and `createTableState.svelte.d.ts`; inspect registered state slices in the matching core feature source.

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

@@ -0,0 +1,149 @@
+---
+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.71'
+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,
+  state: {
+    get pagination() {
+      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/dist/index.d.ts` for adapter APIs and installed `@tanstack/svelte-query/dist/` 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.71'
+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/dist/` for Table APIs and `@tanstack/svelte-virtual/dist/` for the exact virtualizer options. Use the maintained Svelte examples for layout combinations.

package/dist/subscribe.d.ts

@@ -1,24 +0,0 @@
-import { useSelector } from '@tanstack/svelte-store';
-import type { Atom, ReadonlyAtom, ReadonlyStore, Store } from '@tanstack/svelte-store';
-export type SubscribeSource<TValue> = Atom<TValue> | ReadonlyAtom<TValue> | Store<TValue> | ReadonlyStore<TValue>;
-/**
- * Creates a fine-grained Svelte subscription to a TanStack Store source.
- *
- * Pass a table atom or store and optionally project it with a selector. The
- * returned selector store exposes `.current`, making it useful for reading
- * focused table state outside the broad `createTable` selector.
- *
- * @example
- * ```svelte
- * <script lang="ts">
- *   const selected = subscribeTable(
- *     table.atoms.rowSelection,
- *     (rowSelection) => rowSelection[row.id],
- *   )
- * </script>
- *
- * <input type="checkbox" checked={!!selected.current} />
- * ```
- */
-export declare function subscribeTable<TSourceValue>(source: SubscribeSource<TSourceValue>): ReturnType<typeof useSelector<TSourceValue>>;
-export declare function subscribeTable<TSourceValue, TSelected>(source: SubscribeSource<TSourceValue>, selector: (state: TSourceValue) => TSelected): ReturnType<typeof useSelector<TSourceValue, TSelected>>;

package/dist/subscribe.js

@@ -1,4 +0,0 @@
-import { shallow, useSelector } from '@tanstack/svelte-store';
-export function subscribeTable(source, selector) {
-    return useSelector(source, selector, { compare: shallow });
-}