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

package/README.md

@@ -49,6 +49,16 @@ A headless table library for building powerful datagrids with full control over
 
 ### <a href="https://tanstack.com/table">Read the Docs →</a>
 
+## Using an AI Coding Agent?
+
+TanStack Table ships [TanStack Intent](https://github.com/TanStack/intent) skills inside each adapter package. After installing the library, run:
+
+```sh
+npx @tanstack/intent@latest install
+```
+
+to add skill-loading guidance for your agent (Claude Code, Cursor, Copilot, etc.). The same CLI also exposes `intent list` to browse available skills and `intent load <skill>` to print one for inspection. Skills version with the library — your agent gets guidance that matches the version of `@tanstack/<framework>-table` you installed. Only available for v9 and above.
+
 ## Get Involved
 
 - We welcome issues and pull requests!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-table",
-  "version": "9.0.0-alpha.47",
+  "version": "9.0.0-alpha.49",
   "description": "Headless UI for building powerful tables & datagrids for Svelte.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -18,7 +18,8 @@
     "svelte",
     "table",
     "svelte-table",
-    "datagrid"
+    "datagrid",
+    "tanstack-intent"
   ],
   "type": "module",
   "types": "dist/index.d.ts",
@@ -47,17 +48,18 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "dependencies": {
     "@tanstack/svelte-store": "^0.12.0",
-    "@tanstack/table-core": "9.0.0-alpha.47"
+    "@tanstack/table-core": "9.0.0-alpha.49"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^7.1.2",
     "eslint-plugin-svelte": "^3.17.1",
-    "svelte": "^5.55.5",
+    "svelte": "^5.55.7",
     "svelte-check": "^4.4.8"
   },
   "peerDependencies": {

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

@@ -0,0 +1,238 @@
+---
+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.

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

@@ -0,0 +1,295 @@
+---
+name: svelte/compose-with-tanstack-form
+description: >
+  Editable cells in `@tanstack/svelte-table` powered by `@tanstack/svelte-form`. The table is the
+  layout primitive; the form owns the state. Use `createFormHook` to register reusable field
+  components (`TextField`, `NumberField`, `SelectField`), then in each column's `cell` renderer
+  return `renderComponent(MyFieldCell, { form, rowIndex, fieldName })` and inside that cell call
+  `form.Field` (or an `AppField`) with `name="data[${rowIndex}].${fieldName}"`. Drive the table's
+  `data` from `form.state.values.data`. Svelte 5+ only.
+type: composition
+library: tanstack-table
+framework: svelte
+library_version: '9.0.0-alpha.48'
+requires:
+  - row-selection
+  - column-definitions
+sources:
+  - TanStack/table:examples/svelte/with-tanstack-form/
+  - TanStack/table:docs/framework/svelte/svelte-table.md
+---
+
+# Compose with TanStack Form (Svelte)
+
+Editable tables are a classic source of state-management chaos. With v9 + TanStack Form, the
+division of labor is crisp:
+
+- **Form** owns the editable values (per-row, per-field).
+- **Table** owns the layout (columns, filtering, pagination of the same form data).
+- **Cells** are just field renderers — they read and write through Form's field APIs.
+
+## Install
+
+```bash
+pnpm add @tanstack/svelte-form @tanstack/svelte-table
+```
+
+## Set up a field-component-rich Form hook
+
+Define a `createAppForm` once with the reusable field components. This is the form-side
+equivalent of `createTableHook`.
+
+```ts
+// hooks/form.ts
+import { createFormHook, createFormHookContexts } from '@tanstack/svelte-form'
+import TextField from '../components/TextField.svelte'
+import NumberField from '../components/NumberField.svelte'
+import SelectField from '../components/SelectField.svelte'
+import SubmitButton from '../components/SubmitButton.svelte'
+import FormStateIndicator from '../components/FormStateIndicator.svelte'
+
+export const { fieldContext, formContext } = createFormHookContexts()
+
+export const { useAppForm: createAppForm } = createFormHook({
+  fieldComponents: { TextField, NumberField, SelectField },
+  formComponents: { SubmitButton, FormStateIndicator },
+  fieldContext,
+  formContext,
+})
+```
+
+## Reusable field cell components
+
+Each cell type is a small Svelte component that knows which row + field it edits and uses
+`form.Field`. The shape is the same across types — `TextFieldCell`, `NumberFieldCell`,
+`SelectFieldCell`.
+
+```svelte
+<!-- TextFieldCell.svelte -->
+<script lang="ts">
+  type Props = {
+    form: ReturnType<typeof createAppForm>
+    rowIndex: number
+    fieldName: string
+  }
+  let { form, rowIndex, fieldName }: Props = $props()
+</script>
+
+<form.Field name={`data[${rowIndex}].${fieldName}`}>
+  {#snippet children(field)}
+    <input
+      type="text"
+      value={field.state.value}
+      oninput={(e) => field.handleChange((e.target as HTMLInputElement).value)}
+      onblur={field.handleBlur}
+    />
+    {#if field.state.meta.errors?.length}
+      <small class="error">{field.state.meta.errors.join(', ')}</small>
+    {/if}
+  {/snippet}
+</form.Field>
+```
+
+## Wire the table to form state
+
+```svelte
+<script lang="ts">
+  import {
+    columnFilteringFeature,
+    createColumnHelper,
+    createFilteredRowModel,
+    createPaginatedRowModel,
+    createTable,
+    filterFns,
+    FlexRender,
+    renderComponent,
+    rowPaginationFeature,
+    tableFeatures,
+  } from '@tanstack/svelte-table'
+  import { z } from 'zod'
+  import { createAppForm } from './hooks/form'
+  import TextFieldCell from './TextFieldCell.svelte'
+  import NumberFieldCell from './NumberFieldCell.svelte'
+  import SelectFieldCell from './SelectFieldCell.svelte'
+  import { makeData, type Person } from './makeData'
+
+  const _features = tableFeatures({
+    rowPaginationFeature,
+    columnFilteringFeature,
+  })
+
+  const columnHelper = createColumnHelper<typeof _features, Person>()
+
+  const personSchema = z.object({
+    firstName: z.string().min(1),
+    lastName: z.string().min(1),
+    age: z.number().min(0).max(150),
+    visits: z.number().min(0),
+    progress: z.number().min(0).max(100),
+    status: z.enum(['relationship', 'complicated', 'single']),
+  })
+
+  const formSchema = z.object({ data: z.array(personSchema) })
+  type FormData = z.infer<typeof formSchema>
+
+  const form = createAppForm(() => ({
+    defaultValues: { data: makeData(1_000) } as FormData,
+    validators: { onChange: formSchema },
+    onSubmit: ({ value }) => alert(`Saved ${value.data.length} rows`),
+  }))
+
+  const columns = columnHelper.columns([
+    columnHelper.accessor('firstName', {
+      header: 'First Name',
+      cell: ({ row }) =>
+        renderComponent(TextFieldCell, {
+          form,
+          rowIndex: row.index,
+          fieldName: 'firstName',
+        }),
+    }),
+    columnHelper.accessor('age', {
+      header: 'Age',
+      cell: ({ row }) =>
+        renderComponent(NumberFieldCell, {
+          form,
+          rowIndex: row.index,
+          fieldName: 'age',
+        }),
+    }),
+    columnHelper.accessor('status', {
+      header: 'Status',
+      cell: ({ row }) =>
+        renderComponent(SelectFieldCell, {
+          form,
+          rowIndex: row.index,
+        }),
+    }),
+    // ...
+  ])
+
+  const table = createTable({
+    _features,
+    _rowModels: {
+      filteredRowModel: createFilteredRowModel(filterFns),
+      paginatedRowModel: createPaginatedRowModel(),
+    },
+    columns,
+    get data() {
+      // The form is the source of truth.
+      return form.state.values.data
+    },
+  })
+</script>
+
+<form
+  onsubmit={(e) => {
+    e.preventDefault()
+    void form.handleSubmit()
+  }}
+>
+  <form.AppForm>
+    {#snippet children()}
+      <form.FormStateIndicator />
+      <form.SubmitButton label="Save" />
+    {/snippet}
+  </form.AppForm>
+
+  <button
+    type="button"
+    onclick={() =>
+      form.pushFieldValue('data', {
+        firstName: '',
+        lastName: '',
+        age: 0,
+        visits: 0,
+        progress: 0,
+        status: 'single',
+      })}>Add Row</button
+  >
+
+  <table>
+    <thead>
+      {#each table.getHeaderGroups() as headerGroup (headerGroup.id)}
+        <tr>
+          {#each headerGroup.headers as header (header.id)}
+            <th><FlexRender {header} /></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>
+</form>
+```
+
+## Why `row.index` and not `row.id`?
+
+Form indexes its arrays positionally. `row.index` is the position inside the **current** row
+model (after filter + sort + paging). If you want a positional address into `form.state.values.data`,
+you usually want the **original** index — pass `row.original` somewhere that exposes it, or
+store an `id` field and look it up.
+
+For the common case where the table renders the array in its natural order (no sort, no
+filter that reorders), `row.index` matches the form-array position.
+
+## Add Row / Remove Row
+
+Use the form's array helpers; the table re-renders because its `data` getter points at
+`form.state.values.data`.
+
+```ts
+form.pushFieldValue('data', newPerson)
+form.removeFieldValue('data', rowIndex)
+form.replaceFieldValue('data', rowIndex, updatedPerson)
+```
+
+## Pairing with selection
+
+Add `rowSelectionFeature` to enable row checkboxes, then a "delete selected" button can use
+`table.getSelectedRowModel()` to collect rows and `form.removeFieldValue` to remove them.
+
+```ts
+const selectedRows = table.getSelectedRowModel().rows
+const indexesDesc = selectedRows.map((r) => r.index).sort((a, b) => b - a)
+for (const i of indexesDesc) {
+  form.removeFieldValue('data', i)
+}
+table.resetRowSelection()
+```
+
+Remove in descending order so earlier removals don't shift later indexes.
+
+## Pairing with virtualization
+
+You can virtualize the rows even with editable cells — but be aware that **virtualized rows
+unmount when scrolled out of view**, taking their inline form fields with them. If a cell has
+unsaved local-only state, you'll lose it. Use Form fields (which live on the form's state)
+and you're fine — the field state survives the unmount.
+
+## Common failure modes
+
+- **`renderComponent` from React docs.** Use the Svelte adapter's `renderComponent` from
+  `@tanstack/svelte-table`. The signature is the same shape but the runtime is different.
+- **`form` not reactive in cells.** Pass `form` as a prop; don't reach for it via context
+  unless you set up `formContext`.
+- **Wrong field name.** `data[${row.index}].firstName` — string template, not a plain join.
+- **Reordering / filtering breaks `row.index`.** As above. Either keep a stable id and resolve
+  back to the form-array index, or accept that `row.index` only addresses the visible window.
+- **Editing inside virtualized rows without form state.** Field values lost on scroll.
+- **Reimplementing form state with `$state` per cell.** Defeats the whole point — Form already
+  owns this state and runs validation.
+
+## Related skills
+
+- `tanstack-table/core/row-selection` — checkbox column patterns.
+- `tanstack-table/core/column-definitions` — accessor / display columns.
+- `tanstack-table/svelte/table-state` — `getRowModel()` and reactivity.