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

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

@@ -1,286 +0,0 @@
----
-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.48'
-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.

package/skills/svelte/getting-started/SKILL.md

@@ -1,340 +0,0 @@
----
-name: svelte/getting-started
-description: >
-  End-to-end first-table journey for `@tanstack/svelte-table@9` on Svelte 5. Install the adapter,
-  declare `features` with `tableFeatures()`, register `rowModels` factories with their `*Fns`
-  parameters, build a typed column helper with both `TFeatures` and `TData` generics, instantiate
-  the table with `createTable(options)` using `$state` data and `get data()` reactive option getters,
-  and render with `FlexRender`. Svelte 5+ only — Svelte 3/4 must use v8.
-type: lifecycle
-library: tanstack-table
-framework: svelte
-library_version: '9.0.0-alpha.48'
-requires:
-  - setup
-  - column-definitions
-  - state-management
-  - svelte/table-state
-sources:
-  - TanStack/table:docs/installation.md
-  - TanStack/table:docs/framework/svelte/svelte-table.md
-  - TanStack/table:examples/svelte/basic-create-table/
-  - TanStack/table:examples/svelte/basic-app-table/
-  - TanStack/table:examples/svelte/basic-snippets/
-  - TanStack/table:packages/svelte-table/src/index.ts
----
-
-# Getting Started — Svelte
-
-A first working `@tanstack/svelte-table` v9 table from a blank Svelte 5 project. Read this
-end-to-end before searching the docs — the v9 shape diverges enough from v8 (and from your
-muscle memory) that skimming will produce broken code.
-
-## CRITICAL: Svelte version
-
-**`@tanstack/svelte-table@9` requires Svelte 5 or newer.** The adapter is built on runes
-(`$state`, `$derived.by`, `$effect.pre`). If your project is on Svelte 3 or 4, do **one** of:
-
-- Upgrade the project to Svelte 5, then install v9.
-- Stay on `@tanstack/svelte-table@8` for that project.
-
-There is no shim, no `/legacy` export, and no support path that runs v9 on Svelte 4.
-
-## 1. Install
-
-```bash
-pnpm add @tanstack/svelte-table
-# optional: external atoms / fine-grained selectors
-pnpm add @tanstack/svelte-store
-```
-
-You do **not** install `@tanstack/table-core` separately — the Svelte adapter re-exports
-everything you need (column helpers, feature objects, row-model factories, types).
-
-## 2. Define `features` and `rowModels`
-
-v9 is explicit. You opt in to every feature and every row model. The core row model is
-included by default, so the minimum viable table is:
-
-```ts
-const features = tableFeatures({})
-const rowModels = {}
-```
-
-For anything beyond a flat table, register the features you'll use **and** the matching
-row-model factories. Row-model factories take `*Fns` registries as parameters:
-
-```ts
-import {
-  columnFilteringFeature,
-  createFilteredRowModel,
-  createPaginatedRowModel,
-  createSortedRowModel,
-  filterFns,
-  rowPaginationFeature,
-  rowSortingFeature,
-  sortFns,
-  tableFeatures,
-} from '@tanstack/svelte-table'
-
-const features = tableFeatures({
-  rowPaginationFeature,
-  rowSortingFeature,
-  columnFilteringFeature,
-})
-
-const rowModels = {
-  paginatedRowModel: createPaginatedRowModel(),
-  sortedRowModel: createSortedRowModel(sortFns),
-  filteredRowModel: createFilteredRowModel(filterFns),
-}
-```
-
-**Skipping a feature** in `features` means its state slice does not exist on `table.atoms`,
-its options on `createTable` do nothing, and its derived APIs (`table.setSorting`,
-`column.getCanSort`) are not on the instance.
-
-## 3. Type your data and define columns
-
-```ts
-type Person = {
-  firstName: string
-  lastName: string
-  age: number
-  visits: number
-  status: 'relationship' | 'complicated' | 'single'
-  progress: number
-}
-```
-
-Both `ColumnDef` and the column helper take the two generics `<typeof features, TData>`:
-
-```ts
-import { createColumnHelper, type ColumnDef } from '@tanstack/svelte-table'
-
-const columnHelper = createColumnHelper<typeof features, Person>()
-
-const columns = columnHelper.columns([
-  columnHelper.accessor('firstName', {
-    header: 'First Name',
-    cell: (info) => info.getValue(),
-  }),
-  columnHelper.accessor((row) => row.lastName, {
-    id: 'lastName',
-    header: () => 'Last Name',
-    cell: (info) => info.getValue(),
-  }),
-  columnHelper.accessor('age', { header: 'Age' }),
-  columnHelper.accessor('visits', { header: 'Visits' }),
-  columnHelper.accessor('status', { header: 'Status' }),
-  columnHelper.accessor('progress', { header: 'Profile Progress' }),
-])
-```
-
-Or use raw `ColumnDef` arrays if you don't want the helper:
-
-```ts
-const columns: Array<ColumnDef<typeof features, Person>> = [
-  {
-    accessorKey: 'firstName',
-    header: 'First Name',
-    cell: (info) => info.getValue(),
-  },
-]
-```
-
-## 4. Create the table
-
-Use Svelte 5 `$state` for the data and pass it through a **reactive getter** so the table
-re-evaluates `data` when the rune changes. The same pattern applies for any other reactive
-option (`columns`, `rowCount`, `state.*`).
-
-```svelte
-<script lang="ts">
-  import { createTable, tableFeatures } from '@tanstack/svelte-table'
-  import { makeData, type Person } from './makeData'
-
-  const features = tableFeatures({})
-
-  // ... columns from step 3 ...
-
-  let data = $state<Person[]>(makeData(20))
-
-  const refreshData = () => {
-    data = makeData(20)
-  }
-
-  const table = createTable({
-    features,
-    rowModels: {},
-    columns,
-    get data() {
-      return data
-    },
-  })
-</script>
-```
-
-`createTable` syncs options inside `$effect.pre`, so external `$state` updates flow into the
-table **before** the DOM reads `getRowModel()` — no stale-frame bugs.
-
-## 5. Render with `FlexRender`
-
-`FlexRender` handles plain strings, function renderers, component renderers
-(`renderComponent`), and snippet renderers (`renderSnippet`).
-
-```svelte
-<script lang="ts">
-  import { FlexRender } from '@tanstack/svelte-table'
-</script>
-
-<button onclick={refreshData}>Regenerate</button>
-
-<table>
-  <thead>
-    {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
-      <tr>
-        {#each headerGroup.headers as header (header.id)}
-          <th>
-            {#if !header.isPlaceholder}
-              <FlexRender {header} />
-            {/if}
-          </th>
-        {/each}
-      </tr>
-    {/each}
-  </thead>
-  <tbody>
-    {#each table.getRowModel().rows as row (row.id)}
-      <tr>
-        {#each row.getAllCells() as cell (cell.id)}
-          <td><FlexRender {cell} /></td>
-        {/each}
-      </tr>
-    {/each}
-  </tbody>
-</table>
-```
-
-**Key the `{#each}` blocks on stable ids.** Without keys, Svelte recreates nodes and loses
-focus, scroll, and any per-row component state.
-
-## 6. Adding a feature — pagination
-
-```svelte
-<script lang="ts">
-  import {
-    createPaginatedRowModel,
-    createTable,
-    rowPaginationFeature,
-    tableFeatures,
-  } from '@tanstack/svelte-table'
-
-  const features = tableFeatures({ rowPaginationFeature })
-
-  const table = createTable({
-    features,
-    rowModels: {
-      paginatedRowModel: createPaginatedRowModel(),
-    },
-    columns,
-    get data() {
-      return data
-    },
-    initialState: {
-      pagination: { pageIndex: 0, pageSize: 10 },
-    },
-  })
-</script>
-
-<div>
-  <button
-    onclick={() => table.previousPage()}
-    disabled={!table.getCanPreviousPage()}>Prev</button
-  >
-  <span
-    >Page {table.atoms.pagination.get().pageIndex + 1} of {table.getPageCount()}</span
-  >
-  <button onclick={() => table.nextPage()} disabled={!table.getCanNextPage()}
-    >Next</button
-  >
-</div>
-```
-
-To make pagination reactive in the controls, either pass a selector to `createTable` or use
-`subscribeTable`:
-
-```ts
-import { subscribeTable } from '@tanstack/svelte-table'
-
-const pagination = subscribeTable(table.atoms.pagination)
-// pagination.current.pageIndex is reactive
-```
-
-## 7. `createTableHook` (when you have more than one table)
-
-For apps with multiple tables, define the `features`, `rowModels`, and shared components
-once:
-
-```ts
-// hooks/table.ts
-import {
-  createPaginatedRowModel,
-  createSortedRowModel,
-  createTableHook,
-  rowPaginationFeature,
-  rowSortingFeature,
-  sortFns,
-  tableFeatures,
-} from '@tanstack/svelte-table'
-
-export const { createAppTable, createAppColumnHelper } = createTableHook({
-  features: tableFeatures({ rowPaginationFeature, rowSortingFeature }),
-  rowModels: {
-    paginatedRowModel: createPaginatedRowModel(),
-    sortedRowModel: createSortedRowModel(sortFns),
-  },
-})
-```
-
-```svelte
-<script lang="ts">
-  import { createAppColumnHelper, createAppTable } from './hooks/table'
-
-  const columnHelper = createAppColumnHelper<Person>()
-  const columns = columnHelper.columns([
-    columnHelper.accessor('firstName', { header: 'First' }),
-  ])
-
-  const table = createAppTable({
-    columns,
-    get data() {
-      return data
-    },
-  })
-</script>
-```
-
-## Common failure modes
-
-- **Svelte 3/4.** Adapter will not work. See top of file.
-- **`createSvelteTable` / `useSvelteTable` / `getCoreRowModel`** — all v8 names. v9 uses
-  `createTable` and `rowModels: { paginatedRowModel: createPaginatedRowModel(), ... }`.
-- **Plain `data` instead of `get data()` getter.** Table will not see data updates. Always
-  pass a reactive getter for state that lives in `$state`.
-- **Missing feature in `features`.** `table.setSorting` / `column.getCanSort` won't exist.
-  TypeScript will tell you; if it doesn't, you're missing the `<typeof features, TData>`
-  generics on the column helper or `ColumnDef`.
-- **Plain object instead of `tableFeatures({...})`.** Loses typed atom keys; you'll get
-  `unknown` state shapes everywhere.
-- **Unkeyed `{#each}` blocks.** Reuse bugs (focus jumps, wrong row selected).
-- **Reimplementing built-ins.** If you write a manual sort comparator across rows, you're
-  re-doing `rowSortingFeature`. Register it instead.
-
-## Next steps
-
-- `tanstack-table/svelte/table-state` — reactivity model, selectors, subscribeTable, ownership.
-- `tanstack-table/core/filtering` / `pagination` / `sorting` / `row-selection` — feature-by-feature.
-- `tanstack-table/svelte/compose-with-tanstack-query` — server-side data.
-- `tanstack-table/svelte/compose-with-tanstack-virtual` — large datasets.
-- `tanstack-table/svelte/production-readiness` — selector tuning, bundle size.