@tanstack/svelte-table 9.0.0-beta.5 → 9.0.0-beta.51

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.51'
+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.

package/src/createTable.svelte.ts

@@ -51,7 +51,6 @@ export type SvelteTable<
  *   const table = createTable(
  *     {
  *       features,
- *       rowModels: {},
  *       columns,
  *       data,
  *     },
@@ -73,7 +72,7 @@ export function createTable<
   // 1. Merge reactivity into options using mergeObjects (preserves getters)
   const mergedOptions = mergeObjects(tableOptions, {
     features: {
-      coreReativityFeature: svelteReactivity(),
+      coreReactivityFeature: svelteReactivity(),
       ...tableOptions.features,
     },
   }) as TableOptions<TFeatures, TData>

package/src/createTableHook.svelte.ts

@@ -376,6 +376,84 @@ export type AppSvelteTable<
     FlexRender: typeof FlexRenderSvelte
   }
 
+export interface CreateTableHookResult<
+  TFeatures extends TableFeatures,
+  TTableComponents extends Record<string, ComponentType<any>>,
+  TCellComponents extends Record<string, ComponentType<any>>,
+  THeaderComponents extends Record<string, ComponentType<any>>,
+> {
+  /** The features object that was passed to `createTableHook`. */
+  appFeatures: TFeatures
+  /**
+   * A column helper pre-bound to `TFeatures` and the registered components, so
+   * the cell/header/footer render props expose the bound components.
+   */
+  createAppColumnHelper: <TData extends RowData>() => AppColumnHelper<
+    TFeatures,
+    TData,
+    TCellComponents,
+    THeaderComponents
+  >
+  /**
+   * Creates a table with the `App*` wrapper components and registered
+   * `tableComponents` attached. `TData` is inferred from the `data` option.
+   */
+  createAppTable: <TData extends RowData, TSelected = TableState<TFeatures>>(
+    tableOptions: Omit<TableOptions<TFeatures, TData>, 'features'>,
+    selector?: (state: TableState<TFeatures>) => TSelected,
+  ) => AppSvelteTable<
+    TFeatures,
+    TData,
+    TSelected,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
+  >
+  /**
+   * Reads the table provided by the nearest `<table.AppTable>`. This is the same
+   * extended instance `createAppTable` returns, so the `App*` components and your
+   * `tableComponents` are available on it.
+   *
+   * Pass `TSelected` to match the selector you gave `createAppTable`, so
+   * `table.state` is typed as the selected slice. It cannot be inferred
+   * automatically (context does not carry the provider's generics), so it
+   * defaults to the full table state, which is correct for the common case of
+   * `createAppTable` without a selector.
+   */
+  useTableContext: <
+    TData extends RowData = RowData,
+    TSelected = TableState<TFeatures>,
+  >() => AppSvelteTable<
+    TFeatures,
+    TData,
+    TSelected,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
+  >
+  /**
+   * Reads the cell provided by the nearest `<table.AppCell>`, extended with your
+   * `cellComponents` and a context-bound `FlexRender`.
+   */
+  useCellContext: <TValue extends CellData = CellData>() => Cell<
+    TFeatures,
+    any,
+    TValue
+  > &
+    TCellComponents & { FlexRender: typeof FlexRenderSvelte }
+  /**
+   * Reads the header provided by the nearest `<table.AppHeader>` /
+   * `<table.AppFooter>`, extended with your `headerComponents` and a
+   * context-bound `FlexRender`.
+   */
+  useHeaderContext: <TValue extends CellData = CellData>() => Header<
+    TFeatures,
+    any,
+    TValue
+  > &
+    THeaderComponents & { FlexRender: typeof FlexRenderSvelte }
+}
+
 // =============================================================================
 // createTableHook Factory
 // =============================================================================
@@ -404,12 +482,12 @@ export type AppSvelteTable<
  *     rowPaginationFeature,
  *     rowSortingFeature,
  *     columnFilteringFeature,
- *   }),
- *   rowModels: {
  *     paginatedRowModel: createPaginatedRowModel(),
- *     sortedRowModel: createSortedRowModel(sortFns),
- *     filteredRowModel: createFilteredRowModel(filterFns),
- *   },
+ *     sortedRowModel: createSortedRowModel(),
+ *     filteredRowModel: createFilteredRowModel(),
+ *     sortFns,
+ *     filterFns,
+ *   }),
  *   tableComponents: { PaginationControls, RowCount },
  *   cellComponents: { TextCell, NumberCell },
  *   headerComponents: { SortIndicator, ColumnFilter },
@@ -431,7 +509,12 @@ export function createTableHook<
   TTableComponents,
   TCellComponents,
   THeaderComponents
->) {
+>): CreateTableHookResult<
+  TFeatures,
+  TTableComponents,
+  TCellComponents,
+  THeaderComponents
+> {
   /**
    * Create a column helper pre-bound to the features and components configured in this table hook.
    * The cell, header, and footer contexts include pre-bound components (e.g., `cell.TextCell`).
@@ -455,9 +538,16 @@ export function createTableHook<
    * Use this in custom `tableComponents` passed to `createTableHook`.
    * TFeatures is already known from the createTableHook call.
    */
-  function useTableContext<TData extends RowData = RowData>(): SvelteTable<
+  function useTableContext<
+    TData extends RowData = RowData,
+    TSelected = TableState<TFeatures>,
+  >(): AppSvelteTable<
     TFeatures,
-    TData
+    TData,
+    TSelected,
+    TTableComponents,
+    TCellComponents,
+    THeaderComponents
   > {
     const table = getContext(tableContextKey)
 
@@ -468,7 +558,17 @@ export function createTableHook<
       )
     }
 
-    return table as SvelteTable<TFeatures, TData>
+    // `<table.AppTable>` provides the extended table (the App* wrapper
+    // components and `tableComponents` are Object.assign-ed onto the same
+    // instance `createAppTable` returns), so this asserts the runtime shape.
+    return table as unknown as AppSvelteTable<
+      TFeatures,
+      TData,
+      TSelected,
+      TTableComponents,
+      TCellComponents,
+      THeaderComponents
+    >
   }
 
   /**
@@ -480,7 +580,8 @@ export function createTableHook<
     TFeatures,
     any,
     TValue
-  > {
+  > &
+    TCellComponents & { FlexRender: typeof FlexRenderSvelte } {
     const cell = getContext(cellContextKey)
 
     if (!cell) {
@@ -490,7 +591,11 @@ export function createTableHook<
       )
     }
 
-    return cell as Cell<TFeatures, any, TValue>
+    // `<table.AppCell>` Object.assign-es `cellComponents` and `FlexRender` onto
+    // the same cell instance it puts in context, so this asserts the runtime
+    // shape.
+    return cell as unknown as Cell<TFeatures, any, TValue> &
+      TCellComponents & { FlexRender: typeof FlexRenderSvelte }
   }
 
   /**
@@ -502,7 +607,8 @@ export function createTableHook<
     TFeatures,
     any,
     TValue
-  > {
+  > &
+    THeaderComponents & { FlexRender: typeof FlexRenderSvelte } {
     const header = getContext(headerContextKey)
 
     if (!header) {
@@ -511,7 +617,10 @@ export function createTableHook<
       )
     }
 
-    return header as Header<TFeatures, any, TValue>
+    // `<table.AppHeader>` / `<table.AppFooter>` Object.assign `headerComponents`
+    // and `FlexRender` onto the same header instance they put in context.
+    return header as unknown as Header<TFeatures, any, TValue> &
+      THeaderComponents & { FlexRender: typeof FlexRenderSvelte }
   }
 
   /**
@@ -527,10 +636,7 @@ export function createTableHook<
     TData extends RowData,
     TSelected = TableState<TFeatures>,
   >(
-    tableOptions: Omit<
-      TableOptions<TFeatures, TData>,
-      'features' | 'rowModels'
-    >,
+    tableOptions: Omit<TableOptions<TFeatures, TData>, 'features'>,
     selector?: (state: TableState<TFeatures>) => TSelected,
   ): AppSvelteTable<
     TFeatures,
@@ -573,7 +679,7 @@ export function createTableHook<
       return AppTableSvelte(internal, { ...props })
     }) as Component<{ children: Snippet }>
 
-    const AppCell = ((internal: any, { children, cell, ...rest }: any) => {
+    const AppCell = ((internal: any, { children, cell }: any) => {
       setContext(cellContextKey, cell)
       return AppCellSvelte(internal, {
         cell,
@@ -585,7 +691,7 @@ export function createTableHook<
       children: Snippet<[any]>
     }>
 
-    const AppHeader = ((internal: any, { children, header, ...rest }: any) => {
+    const AppHeader = ((internal: any, { children, header }: any) => {
       setContext(headerContextKey, header)
       return AppHeaderSvelte(internal, {
         header,
@@ -598,7 +704,7 @@ export function createTableHook<
     }>
 
     // AppFooter reuses AppHeaderSvelte (footers use Header type in table-core)
-    const AppFooter = ((internal: any, { children, header, ...rest }: any) => {
+    const AppFooter = ((internal: any, { children, header }: any) => {
       setContext(headerContextKey, header)
       return AppHeaderSvelte(internal, {
         header,
@@ -629,7 +735,7 @@ export function createTableHook<
   }
 
   return {
-    appFeatures: defaultTableOptions.features as TFeatures,
+    appFeatures: defaultTableOptions.features,
     createAppColumnHelper,
     createAppTable,
     useTableContext,

package/src/experimental-worker-plugin.ts

@@ -0,0 +1 @@
+export * from '@tanstack/table-core/experimental-worker-plugin'

package/src/index.ts

@@ -14,6 +14,7 @@ export type {
   AppSvelteTable,
   ComponentType,
   CreateTableHookOptions,
+  CreateTableHookResult,
 } from './createTableHook.svelte'
 export { createTableState } from './createTableState.svelte'
 export { default as FlexRender } from './FlexRender.svelte'

package/skills/svelte/client-to-server/SKILL.md

@@ -1,238 +0,0 @@
----
-name: svelte/client-to-server
-description: >
-  Convert a client-side Svelte table to server-side (manual) modes. Toggle `manualPagination`,
-  `manualSorting`, `manualFiltering`, `manualGrouping`, `manualExpanding` for whatever the server
-  owns, drop the matching `rowModels` factories and `features` you no longer need, supply
-  `rowCount` for the pager, then drive the request from `table.atoms.pagination` /
-  `table.atoms.sorting` / etc. (or external atoms you own) — using rune-aware getters
-  (`get data()`, `get rowCount()`) so the table re-syncs in `$effect.pre`. Svelte 5+ only.
-type: lifecycle
-library: tanstack-table
-framework: svelte
-library_version: '9.0.0-alpha.48'
-requires:
-  - state-management
-  - pagination
-  - filtering
-  - sorting
-  - svelte/table-state
-sources:
-  - TanStack/table:examples/svelte/basic-external-atoms/
-  - TanStack/table:examples/svelte/basic-external-state/
-  - TanStack/table:examples/svelte/with-tanstack-query/
-  - TanStack/table:docs/framework/svelte/guide/table-state.md
----
-
-# Client → Server (Svelte)
-
-You have a working client-side table. The dataset is too big to ship to the browser, or it
-lives behind an API. You want sorting / filtering / pagination to run on the server while the
-table still feels the same in the UI.
-
-## Mental model
-
-Each "manual mode" flag tells the table: **don't run this stage of the pipeline; trust the data
-you receive.** You can mix modes freely — manual pagination + client-side sorting on the
-already-paged window is perfectly valid for medium datasets.
-
-| Flag               | Meaning                                      | What you must provide                                       |
-| ------------------ | -------------------------------------------- | ----------------------------------------------------------- |
-| `manualPagination` | Server owns slicing; do not paginate locally | `rowCount` (or `pageCount`)                                 |
-| `manualSorting`    | Server owns ordering                         | Sort the server query by `sorting` state                    |
-| `manualFiltering`  | Server owns row filtering                    | Filter the server query by `columnFilters` / `globalFilter` |
-| `manualGrouping`   | Server returns already-grouped rows          | Pre-shaped data                                             |
-| `manualExpanding`  | Server resolves sub-rows                     | Server-provided sub-row tree                                |
-
-When a stage is manual, you can drop its row-model factory. `manualPagination: true` does not
-need `paginatedRowModel: createPaginatedRowModel()`.
-
-## Step 1 — Identify what's moving server-side
-
-For a typical "search and paginate against a database" screen:
-
-- Pagination → server
-- Filtering (column filter inputs + a global search box) → server
-- Sorting → server (usually, since a partial page can't be sorted client-side meaningfully)
-- Selection / visibility / column ordering → still client
-
-So the table keeps `rowSelectionFeature` etc., drops `columnFilteringFeature` /
-`rowPaginationFeature` / `rowSortingFeature` _row models_ but keeps the _features_ so the
-state slices and UI APIs still exist.
-
-> Subtle point: keep the **feature** even if you drop the row model. The feature is what gives
-> you `column.getCanSort()`, `table.setPageIndex()`, `column.setFilterValue()` — all the
-> control-surface APIs. Dropping it kills the UI.
-
-## Step 2 — Own the relevant state with external atoms
-
-External atoms make state portable: the data layer (a fetch / query / store) can read the
-same atoms the table writes to. Use `@tanstack/svelte-store`:
-
-```ts
-import { createAtom, useSelector } from '@tanstack/svelte-store'
-import type {
-  ColumnFiltersState,
-  PaginationState,
-  SortingState,
-} from '@tanstack/svelte-table'
-
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const sortingAtom = createAtom<SortingState>([])
-const filtersAtom = createAtom<ColumnFiltersState>([])
-
-// For Svelte markup that should react to changes:
-const pagination = useSelector(paginationAtom)
-const sorting = useSelector(sortingAtom)
-const filters = useSelector(filtersAtom)
-```
-
-## Step 3 — Configure the table
-
-```svelte
-<script lang="ts">
-  import {
-    columnFilteringFeature,
-    createTable,
-    rowPaginationFeature,
-    rowSortingFeature,
-    tableFeatures,
-  } from '@tanstack/svelte-table'
-
-  const features = tableFeatures({
-    columnFilteringFeature,
-    rowPaginationFeature,
-    rowSortingFeature,
-  })
-
-  // No row-model factories for these — server owns them.
-  const table = createTable({
-    features,
-    rowModels: {},
-    columns,
-    get data() {
-      return query.data?.rows ?? []
-    },
-    get rowCount() {
-      return query.data?.rowCount
-    },
-    atoms: {
-      pagination: paginationAtom,
-      sorting: sortingAtom,
-      columnFilters: filtersAtom,
-    },
-    manualPagination: true,
-    manualSorting: true,
-    manualFiltering: true,
-  })
-</script>
-```
-
-`rowCount` is what makes `table.getPageCount()` / `table.getCanNextPage()` correct under
-manual pagination. Without it the pager has no idea how many pages exist.
-
-## Step 4 — Drive the fetch from those atoms
-
-Wire whatever data layer you use (TanStack Query, a raw `fetch`, SvelteKit `load`, etc.) to
-read the atoms. With TanStack Query:
-
-```ts
-import { createQuery, keepPreviousData } from '@tanstack/svelte-query'
-
-const dataQuery = createQuery<{ rows: Array<Person>; rowCount: number }>(
-  () => ({
-    queryKey: ['people', pagination.current, sorting.current, filters.current],
-    queryFn: () =>
-      fetch('/api/people', {
-        method: 'POST',
-        body: JSON.stringify({
-          pageIndex: pagination.current.pageIndex,
-          pageSize: pagination.current.pageSize,
-          sorting: sorting.current,
-          filters: filters.current,
-        }),
-      }).then((r) => r.json()),
-    placeholderData: keepPreviousData,
-  }),
-)
-```
-
-`placeholderData: keepPreviousData` is what kills the "rows blank for one tick on every
-page change" flash.
-
-## Step 5 — Reset behavior
-
-When the user changes a filter, you usually want to jump back to page 0. The table does this
-automatically when client-side filtering owns the data, but with manual mode the data layer
-controls it. Simplest fix: explicitly reset.
-
-```ts
-$effect(() => {
-  // re-runs whenever filters.current identity changes
-  filters.current
-  table.setPageIndex(0)
-})
-```
-
-Or wrap your filter `onChange` handlers to also call `table.setPageIndex(0)`.
-
-## Step 6 — A note on global filtering
-
-If you also support `globalFilterFeature`, debounce the input. `column.setFilterValue` and
-`table.setGlobalFilter` fire per keystroke; without debouncing you fire one request per typed
-character. See the `compose-with-tanstack-pacer` skill for the pattern.
-
-## Hybrid example — manual pagination only
-
-Sometimes you only paginate server-side and let the page-sized window sort/filter on the
-client.
-
-```ts
-const table = createTable({
-  features: tableFeatures({
-    columnFilteringFeature,
-    rowPaginationFeature,
-    rowSortingFeature,
-  }),
-  rowModels: {
-    filteredRowModel: createFilteredRowModel(filterFns), // client filters the page
-    sortedRowModel: createSortedRowModel(sortFns), // client sorts the page
-  },
-  columns,
-  get data() {
-    return query.data?.rows ?? []
-  },
-  get rowCount() {
-    return query.data?.rowCount
-  },
-  atoms: { pagination: paginationAtom },
-  manualPagination: true,
-})
-```
-
-Only the manual flag for the stage you're moving server-side.
-
-## Common failure modes
-
-- **Forgot `rowCount`.** `table.getPageCount()` returns `-1`, the pager looks broken.
-- **Dropped the feature, not just the row model.** Lost `column.getCanSort()` and friends.
-  Keep the feature when you still need its UI APIs; only drop the row-model factory.
-- **Both `state.pagination` and `atoms.pagination`.** Atoms silently win; the `on*Change`
-  callback never fires.
-- **Re-creating atoms inside reactive blocks.** Atoms must be stable across renders. Declare
-  them at module / component-init scope, not inside `$derived` or `$effect`.
-- **Forgetting to reset page on filter change.** Stay on page 12 of a now-2-page result set.
-- **Plain `data: query.data?.rows`.** No getter, no reactivity. Use `get data()`.
-- **Reimplementing pagination math.** `table.setPageIndex / nextPage / previousPage /
-firstPage / lastPage / setPageSize / getCanNextPage / getCanPreviousPage / getPageCount`
-  already exist and respect manual mode.
-
-## Related skills
-
-- `tanstack-table/svelte/compose-with-tanstack-query` — the same flow with a Query data layer.
-- `tanstack-table/svelte/compose-with-tanstack-pacer` — debouncing filter inputs.
-- `tanstack-table/svelte/compose-with-tanstack-store` — atom interop and per-slice subscription.
-- `tanstack-table/core/pagination` / `filtering` / `sorting` — feature deep dives.