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

package/skills/migrate-v8-to-v9/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: migrate-v8-to-v9
+description: >
+  Complete Svelte v8-to-v9 migration reference: Svelte 5, createTable, explicit features and row-model slots, atom/rune state, rendering helpers, prototype methods, type generics, sorting, sizing, selection, and logical pinning.
+metadata:
+  type: lifecycle
+  library: '@tanstack/svelte-table'
+  framework: svelte
+  library_version: '9.0.0-beta.51'
+requires:
+  - '@tanstack/table-core#migrate-v8-to-v9'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:docs/framework/svelte/guide/migrating.md'
+  - 'TanStack/table:packages/svelte-table/src/index.ts'
+  - 'TanStack/table:examples/svelte/basic-create-table'
+---
+
+Use this as the complete breaking-change checklist, not merely a quick start. V9 is treated as the current API. Migrate the app to Svelte 5 before migrating Table; the v9 adapter has no Svelte 3/4 compatibility layer.
+
+Framework prerequisite: Svelte 5 (`svelte ^5.0.0`).
+
+## Recommended Migration Order
+
+1. Upgrade to Svelte 5 and replace v8 stores with runes/getters.
+2. Rename `createSvelteTable` to `createTable`.
+3. Define explicit `tableFeatures`, then move row models and registries into it.
+4. Update state reads/ownership and rendering.
+5. Apply every shared API and type rename below.
+6. Use `stockFeatures` only as a temporary audit bridge; explicit features are the production target.
+
+```ts
+const features = tableFeatures({
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric },
+})
+
+const table = createTable({
+  features,
+  columns,
+  get data() {
+    return data
+  },
+})
+```
+
+## Construction and Feature Registration
+
+| v8                                           | v9                                                         |
+| -------------------------------------------- | ---------------------------------------------------------- |
+| `createSvelteTable(options)`                 | `createTable(options, selector?)`                          |
+| All features bundled                         | Required `features: tableFeatures({...})`                  |
+| `getCoreRowModel()` option                   | Remove; the core row model is automatic                    |
+| `get*RowModel()` table options               | `create*RowModel()` slots in `tableFeatures`               |
+| `sortingFns` table option                    | `sortFns` feature slot                                     |
+| `filterFns` / `aggregationFns` table options | Same-named feature slots                                   |
+| Top-level `onStateChange`                    | Per-slice callbacks, external atoms, or store subscription |
+
+Available feature imports are `columnFilteringFeature`, `globalFilteringFeature`, `rowSortingFeature`, `rowPaginationFeature`, `rowSelectionFeature`, `rowExpandingFeature`, `rowPinningFeature`, `columnPinningFeature`, `columnVisibilityFeature`, `columnOrderingFeature`, `columnSizingFeature`, `columnResizingFeature`, `rowAggregationFeature`, `columnGroupingFeature`, and `columnFacetingFeature`. An API does not exist unless its feature is registered. Put a feature before its dependent slot in the same `tableFeatures` call. Aggregation is independent from grouping: register `rowAggregationFeature` for aggregation APIs and add `columnGroupingFeature` only for grouped rows.
+
+### Row-model mapping
+
+| v8 option                  | v9 slot and factory                                                 |
+| -------------------------- | ------------------------------------------------------------------- |
+| `getFilteredRowModel()`    | `filteredRowModel: createFilteredRowModel()` after column filtering |
+| `getSortedRowModel()`      | `sortedRowModel: createSortedRowModel()` after row sorting          |
+| `getPaginationRowModel()`  | `paginatedRowModel: createPaginatedRowModel()` after pagination     |
+| `getExpandedRowModel()`    | `expandedRowModel: createExpandedRowModel()` after expanding        |
+| `getGroupedRowModel()`     | `groupedRowModel: createGroupedRowModel()` after grouping           |
+| `getFacetedRowModel()`     | `facetedRowModel: createFacetedRowModel()` after faceting           |
+| `getFacetedMinMaxValues()` | `facetedMinMaxValues: createFacetedMinMaxValues()`                  |
+| `getFacetedUniqueValues()` | `facetedUniqueValues: createFacetedUniqueValues()`                  |
+
+Factories take no arguments. Register `filterFns`, `sortFns`, and `aggregationFns` as sibling feature slots holding individually imported built-ins (`filterFn_includesString`, `sortFn_alphanumeric`, `aggregationFn_sum`) under their conventional keys. The full registry objects still work but bundle every built-in.
+
+## Svelte State Migration
+
+- Reactive option inputs must remain live: use getters for rune values such as `data` and controlled state slices.
+- `table.getState().sorting` becomes `table.state.sorting`, `table.store.state.sorting`, or the narrow `table.atoms.sorting.get()`.
+- `table.state` contains all registered state by default. Pass a second-argument selector to `createTable` only to narrow its reactive surface.
+- `subscribeTable(table.atoms.pagination, selector?)` exposes `.current` for fine-grained template subscriptions.
+- For Svelte-owned controlled slices, use `createTableState` and matching `onSortingChange`, `onPaginationChange`, and other per-slice callbacks.
+- For shared ownership, provide atoms created by `@tanstack/svelte-store` through `atoms`. Never provide both `atoms.pagination` and `state.pagination`.
+- Subscribe to `table.store` to observe every state change. Do not port the removed top-level `onStateChange`.
+- Treat `table.baseAtoms` as internal writable state; prefer feature APIs or external atoms.
+
+## Rendering and Composition
+
+| v8                                       | v9                                                                               |
+| ---------------------------------------- | -------------------------------------------------------------------------------- |
+| `flexRender(...)` / `<svelte:component>` | `<FlexRender {cell} />`, `<FlexRender {header} />`, or `<FlexRender {footer} />` |
+| Component returned directly              | `renderComponent(Component, props)`                                              |
+| Svelte snippet content                   | `renderSnippet(snippet, props)`                                                  |
+| Repeated raw options                     | `tableOptions(...)` composition                                                  |
+| Repeated table conventions               | `createTableHook({ features, ... })` and its pre-bound helpers                   |
+
+`createTableHook` returns a feature-bound table creator and column helper; use it for application-wide conventions, not as a required migration step.
+
+## Complete Shared Breaking-Change Map
+
+### Instance methods
+
+Row, cell, column, header, and related object methods now live on shared prototypes and use `this`. Call `row.getValue(...)`, `cell.getContext()`, `column.getCanSort()`, and `header.getContext()` on their instances. Do not destructure them or pass them as bare callbacks. They are not own enumerable properties, so object spread, `Object.keys`, and JSON serialization do not preserve them. Table methods are not affected.
+
+### Logical column pinning
+
+There are no `left`/`right` aliases in beta.38.
+
+| old                                                            | new                                                           |
+| -------------------------------------------------------------- | ------------------------------------------------------------- |
+| `columnPinning.left` / `.right`                                | `.start` / `.end`                                             |
+| `column.pin('left' \| 'right')`                                | `column.pin('start' \| 'end')`                                |
+| `getIsPinned() === 'left' \| 'right'`                          | `'start' \| 'end'`                                            |
+| `row.getLeftVisibleCells()` / `getRightVisibleCells()`         | `getStartVisibleCells()` / `getEndVisibleCells()`             |
+| `getLeftHeaderGroups()` / `getRightHeaderGroups()`             | `getStartHeaderGroups()` / `getEndHeaderGroups()`             |
+| `getLeftFooterGroups()` / `getRightFooterGroups()`             | `getStartFooterGroups()` / `getEndFooterGroups()`             |
+| `getLeftFlatHeaders()` / `getRightFlatHeaders()`               | `getStartFlatHeaders()` / `getEndFlatHeaders()`               |
+| `getLeftLeafHeaders()` / `getRightLeafHeaders()`               | `getStartLeafHeaders()` / `getEndLeafHeaders()`               |
+| `getLeftLeafColumns()` / `getRightLeafColumns()`               | `getStartLeafColumns()` / `getEndLeafColumns()`               |
+| `getLeftVisibleLeafColumns()` / `getRightVisibleLeafColumns()` | `getStartVisibleLeafColumns()` / `getEndVisibleLeafColumns()` |
+| `getLeftTotalSize()` / `getRightTotalSize()`                   | `getStartTotalSize()` / `getEndTotalSize()`                   |
+| `column.getStart('left')`                                      | `column.getStart('start')`                                    |
+| `column.getAfter('right')`                                     | `column.getAfter('end')`                                      |
+| `column.getIndex('left' \| 'right')`                           | `column.getIndex('start' \| 'end')`                           |
+
+This is logical region naming, not automatic DOM direction handling. Prefer CSS `inset-inline-start`/`inset-inline-end`. `columnResizeDirection` is unchanged.
+
+### Feature and state splits
+
+- `enablePinning` splits into `enableColumnPinning` and `enableRowPinning`.
+- Interactive resizing requires both `columnSizingFeature` and `columnResizingFeature`; fixed widths need only sizing.
+- `columnSizingInfo` becomes `columnResizing`.
+- `setColumnSizingInfo()` becomes `setColumnResizing()`.
+- `onColumnSizingInfoChange` becomes `onColumnResizingChange`.
+
+### Sorting, rows, and selection
+
+| v8                             | v9                            |
+| ------------------------------ | ----------------------------- |
+| `sortingFn`                    | `sortFn`                      |
+| `sortingFns`                   | `sortFns`                     |
+| `getSortingFn()`               | `getSortFn()`                 |
+| `getAutoSortingFn()`           | `getAutoSortFn()`             |
+| `SortingFn` / `SortingFns`     | `SortFn` / `SortFns`          |
+| `row._getAllCellsByColumnId()` | `row.getAllCellsByColumnId()` |
+
+All other `_`-prefixed internal APIs are removed, including `_getPinnedRows`, `_getFacetedRowModel`, `_getFacetedMinMaxValues`, and `_getFacetedUniqueValues`; do not seek replacements unless a public API is documented.
+
+`getIsSomeRowsSelected()` and `getIsSomePageRowsSelected()` now mean at least one, including all. For an indeterminate checkbox, combine “some” with `!getIsAllRowsSelected()` or `!getIsAllPageRowsSelected()`.
+
+## TypeScript Migration
+
+- Core types now take `TFeatures` first: `ColumnDef<typeof features, Person>`, `Column<typeof features, Person>`, `Row<typeof features, Person>`, `Table<typeof features, Person>`.
+- Replace `createColumnHelper<Person>()` with `createColumnHelper<typeof features, Person>()`; wrap arrays in `columnHelper.columns([...])` for inference.
+- With `stockFeatures`, use `StockFeatures` as the feature type.
+- `TableMeta` and `ColumnMeta` declaration merging still works only after adding `TFeatures` first. Prefer per-table `tableMeta`/`columnMeta: metaHelper<...>()` slots.
+- Replace global `FilterFns`, `SortFns`, `AggregationFns`, and `FilterMeta` augmentation with `filterFns`, `sortFns`, `aggregationFns`, and `filterMeta: metaHelper<...>()` slots. Registered keys become valid string references.
+- Prefer explicit object row types; `RowData` is restricted to records or arrays.
+
+## Common Migration Failures
+
+### CRITICAL: Running v9 on Svelte 3/4
+
+Upgrade to Svelte 5 first. Writable-store-era table setup is not a supported v9 adapter contract.
+
+### HIGH: Moving the feature but not its row model
+
+Register both the feature and its `create*RowModel()` slot. Leaving `get*RowModel` on table options silently leaves the v9 processing pipeline incomplete.
+
+### HIGH: Snapshotting a rune value
+
+Use `get data() { return data }`; a one-time `data` snapshot does not remain reactive.
+
+### HIGH: Destructuring instance methods
+
+Keep calls bound to row/cell/column/header instances; shallow copies do not contain prototype methods.
+
+## Final Checklist
+
+- [ ] Svelte is version 5+; old writable-store patterns are removed.
+- [ ] `createSvelteTable` is replaced by `createTable`.
+- [ ] Explicit features, row models, and function registries are in `tableFeatures`.
+- [ ] `getCoreRowModel` and the separate `rowModels` shape are removed.
+- [ ] Reactive inputs and controlled slices use getters/runes; state reads use v9 surfaces.
+- [ ] `onStateChange` is replaced; atom/state ownership does not overlap.
+- [ ] Rendering uses `FlexRender`, `renderComponent`, or `renderSnippet`.
+- [ ] Prototype method calls, pinning, sizing/resizing, sorting, row, and selection semantics are audited.
+- [ ] Helpers, types, meta, registries, and `RowData` use the v9 generic/slot shapes.
+- [ ] Temporary `stockFeatures` usage has an explicit removal plan.
+
+## API Discovery
+
+Verify the installed target in `node_modules/@tanstack/svelte-table/src/index.ts` and its adapter sources. Verify feature slots and exact beta APIs in `node_modules/@tanstack/table-core/src`; do not reconstruct v9 APIs from v8 memory.

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