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

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

@@ -0,0 +1,277 @@
+---
+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.47'
+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 `coreReativityFeature`. 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.store.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,
+      _rowModels: { paginatedRowModel: createPaginatedRowModel() },
+      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,
+  _rowModels: {
+    /* ... */
+  },
+  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,
+    _rowModels: {
+      /* ... */
+    },
+    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.

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

@@ -0,0 +1,286 @@
+---
+name: svelte/compose-with-tanstack-virtual
+description: >
+  `@tanstack/svelte-table` does not include virtualization — pair it with
+  `@tanstack/svelte-virtual`. Use `createVirtualizer({ count, estimateSize, getScrollElement,
+  ... })`, feed `table.getRowModel().rows.length` as `count`, render only
+  `$rowVirtualizer.getVirtualItems()`, position rows with `transform: translateY(...)` and a
+  container of `getTotalSize()`. Use `measureElement` actions for dynamic row heights. Svelte 5+
+  only — `$state` for refs, `$effect` to sync count.
+type: composition
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.47'
+requires:
+  - svelte/table-state
+  - row-expanding
+sources:
+  - TanStack/table:docs/guide/virtualization.md
+  - TanStack/table:examples/svelte/virtualized-rows/
+  - TanStack/table:examples/svelte/virtualized-columns/
+  - TanStack/table:examples/svelte/virtualized-infinite-scrolling/
+---
+
+# Compose with TanStack Virtual (Svelte)
+
+TanStack Table is **not** a virtualizer. For lists / grids past a few thousand rows (or with
+heavy per-row markup), pair it with `@tanstack/svelte-virtual`.
+
+## Install
+
+```bash
+pnpm add @tanstack/svelte-virtual
+```
+
+## Core mental model
+
+- TanStack Table gives you `rows: row[]` (already filtered / sorted / paged / grouped).
+- TanStack Virtual takes `count` (the length) and returns `virtualItems` (the slice currently
+  in view).
+- You render only those virtual items, absolutely positioned, inside a container sized to
+  `getTotalSize()` pixels.
+
+`createVirtualizer` returns a Svelte store. Read its current value with `$rowVirtualizer` or
+`get(rowVirtualizer)` (from `svelte/store`).
+
+## Basic row virtualization
+
+```svelte
+<script lang="ts">
+  import {
+    columnSizingFeature,
+    createSortedRowModel,
+    createTable,
+    rowSortingFeature,
+    sortFns,
+    tableFeatures,
+    FlexRender,
+  } from '@tanstack/svelte-table'
+  import { createVirtualizer } from '@tanstack/svelte-virtual'
+  import { get } from 'svelte/store'
+
+  const _features = tableFeatures({ columnSizingFeature, rowSortingFeature })
+
+  let data = $state<Person[]>(makeData(200_000))
+
+  const table = createTable({
+    _features,
+    _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+    columns,
+    get data() {
+      return data
+    },
+  })
+
+  let tableContainerRef = $state<HTMLDivElement | undefined>(undefined)
+
+  const rows = $derived(table.getRowModel().rows)
+
+  const rowVirtualizer = createVirtualizer({
+    get count() {
+      return rows.length
+    },
+    estimateSize: () => 33,
+    getScrollElement: () => tableContainerRef ?? null,
+    overscan: 5,
+  })
+
+  // svelte-virtual's store adapter does not reactively track getter options;
+  // push updates explicitly when ref / count change.
+  $effect(() => {
+    if (tableContainerRef) {
+      get(rowVirtualizer).setOptions({
+        getScrollElement: () => tableContainerRef ?? null,
+      })
+    }
+  })
+
+  $effect(() => {
+    get(rowVirtualizer).setOptions({ count: rows.length })
+  })
+</script>
+
+<div
+  bind:this={tableContainerRef}
+  style="overflow: auto; position: relative; height: 800px;"
+>
+  <table style="display: grid;">
+    <thead style="display: grid; position: sticky; top: 0; z-index: 1;">
+      {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
+        <tr style="display: flex; width: 100%;">
+          {#each headerGroup.headers as header (header.id)}
+            <th style="display: flex; width: {header.getSize()}px;">
+              <FlexRender {header} />
+            </th>
+          {/each}
+        </tr>
+      {/each}
+    </thead>
+    <tbody
+      style="display: grid; position: relative; height: {$rowVirtualizer.getTotalSize()}px;"
+    >
+      {#each $rowVirtualizer.getVirtualItems() as virtualRow (virtualRow.index)}
+        {@const row = rows[virtualRow.index]}
+        <tr
+          data-index={virtualRow.index}
+          style="display: flex; position: absolute; transform: translateY({virtualRow.start}px); width: 100%;"
+        >
+          {#each row.getAllCells() as cell (cell.id)}
+            <td style="display: flex; width: {cell.column.getSize()}px;">
+              <FlexRender {cell} />
+            </td>
+          {/each}
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+```
+
+Why `display: grid` / `flex` instead of native table layout? Because the rows are absolutely
+positioned, the browser's native table layout algorithm can't size columns from non-flowing
+rows. CSS layout takes over.
+
+## Dynamic row heights (`measureElement`)
+
+For variable row heights (multi-line cells, expanding rows), measure rendered nodes with the
+virtualizer's `measureElement` API.
+
+```svelte
+<script lang="ts">
+  const rowVirtualizer = createVirtualizer({
+    get count() {
+      return rows.length
+    },
+    estimateSize: () => 33,
+    getScrollElement: () => tableContainerRef ?? null,
+    measureElement:
+      typeof window !== 'undefined' &&
+      navigator.userAgent.indexOf('Firefox') === -1
+        ? (element) => element.getBoundingClientRect().height
+        : undefined,
+    overscan: 5,
+  })
+
+  // Svelte action wrapping the virtualizer's measure call.
+  function measureElement(node: HTMLTableRowElement) {
+    get(rowVirtualizer).measureElement(node)
+  }
+</script>
+
+<tr use:measureElement data-index={virtualRow.index} ...>...</tr>
+```
+
+`data-index` is required — the virtualizer uses it to map a measured element back to its
+virtual item.
+
+> Firefox measures table-border rows incorrectly. The above guards against measuring there and
+> falls back to the estimate.
+
+## Column virtualization
+
+`createVirtualizer` with `horizontal: true` against `table.getVisibleLeafColumns()`. Same
+pattern — only render `getVirtualItems()` cells per row, position with `translateX`.
+
+```ts
+const columnVirtualizer = createVirtualizer({
+  get count() {
+    return visibleColumns.length
+  },
+  estimateSize: (index) => visibleColumns[index].getSize(),
+  getScrollElement: () => tableContainerRef ?? null,
+  horizontal: true,
+  overscan: 3,
+})
+```
+
+For combined row + column virtualization, render the row virtualizer's items, and inside each
+row render the column virtualizer's items. See `examples/svelte/virtualized-columns/`.
+
+## Infinite scroll (load more on near-bottom)
+
+Subscribe to the virtualizer's `getVirtualItems()` and check the last one's index against your
+total available count.
+
+```ts
+import { createInfiniteQuery } from '@tanstack/svelte-query'
+
+const infiniteQuery = createInfiniteQuery(() => ({
+  queryKey: ['people-infinite'],
+  queryFn: ({ pageParam }) => fetchPeople({ cursor: pageParam, pageSize: 50 }),
+  initialPageParam: undefined as string | undefined,
+  getNextPageParam: (last) => last.nextCursor,
+}))
+
+const flatData = $derived(
+  infiniteQuery.data?.pages.flatMap((p) => p.rows) ?? [],
+)
+
+const table = createTable({
+  _features: tableFeatures({}),
+  _rowModels: {},
+  columns,
+  get data() {
+    return flatData
+  },
+})
+
+const rows = $derived(table.getRowModel().rows)
+
+const rowVirtualizer = createVirtualizer({
+  get count() {
+    return rows.length
+  },
+  estimateSize: () => 33,
+  getScrollElement: () => tableContainerRef ?? null,
+  overscan: 10,
+})
+
+$effect(() => {
+  const items = $rowVirtualizer.getVirtualItems()
+  const last = items[items.length - 1]
+  if (
+    last &&
+    last.index >= rows.length - 1 &&
+    infiniteQuery.hasNextPage &&
+    !infiniteQuery.isFetchingNextPage
+  ) {
+    infiniteQuery.fetchNextPage()
+  }
+})
+```
+
+## Interaction with row expanding
+
+If `rowExpandingFeature` is registered, `table.getRowModel().rows` already flattens expanded
+sub-rows into a single sequential list. The virtualizer just sees a longer list — no special
+handling needed.
+
+For variable row heights driven by expand state, you'll want `measureElement` so the
+container resizes when a row expands.
+
+## Pagination vs. virtualization
+
+Pick one. Virtualization is for "render all rows but render only the visible window".
+Pagination is for "the user navigates discrete pages". Combining them usually means you don't
+need either — drop pagination and let the virtualizer handle the rendering window.
+
+## Common failure modes
+
+- **Forgot to push `count` updates.** `svelte-virtual` does not auto-track `get count()` —
+  use `$effect` + `setOptions({ count })`.
+- **Native table layout with virtualized rows.** Columns collapse because absolutely
+  positioned rows don't contribute to layout. Use `display: grid` / `flex`.
+- **No `data-index` on `<tr>`.** `measureElement` can't map back to virtual items.
+- **No `transform: translateY`.** Rows render at `top: 0` and stack visually.
+- **Missing container `height`.** No overflow, no scroll, no virtualization.
+- **Calling `get(rowVirtualizer).getVirtualItems()` in template.** Wrong access pattern;
+  use `$rowVirtualizer.getVirtualItems()` (store auto-subscribe) or be sure to
+  `import { get } from 'svelte/store'`.
+- **Reimplementing windowing manually.** Don't.
+
+## Related skills
+
+- `tanstack-table/svelte/table-state` — `getRowModel()` and the reactivity model.
+- `tanstack-table/core/row-expanding` — flattening sub-rows for virtualization.
+- `tanstack-table/svelte/compose-with-tanstack-query` — infinite-scroll data source.