@tanstack/svelte-table 9.0.0-alpha.5 → 9.0.0-alpha.50

package/dist/render-component.d.ts

@@ -1,20 +1,51 @@
-import type { Component, ComponentProps } from 'svelte';
+import type { Component, ComponentProps, Snippet } from 'svelte';
 /**
- * A helper class to make it easy to identify Svelte components in `columnDef.cell` and `columnDef.header` properties.
+ * A helper class to make it easy to identify Svelte components in
+ * `columnDef.cell` and `columnDef.header` properties.
+ *
+ * > NOTE: This class should only be used internally by the adapter. If you're
+ * reading this and you don't know what this is for, you probably don't need it.
+ *
  * @example
  * ```svelte
- * {#if cell.column.columnDef.cell(cell.getContext()) instanceof RenderComponentConfig}
- *   <svelte:component this={columnDef.cell.component} {...columnDef.cell.props} />
+ * {@const result = content(context as any)}
+ * {#if result instanceof RenderComponentConfig}
+ *   {@const { component: Component, props } = result}
+ *   <Component {...props} />
  * {/if}
  * ```
  * */
-export declare class RenderComponentConfig<TComponent extends Component<any>> {
+export declare class RenderComponentConfig<TComponent extends Component> {
     component: TComponent;
-    props: ComponentProps<TComponent>;
-    constructor(component: TComponent, props: ComponentProps<TComponent>);
+    props?: (ComponentProps<TComponent> | Record<string, never>) | undefined;
+    constructor(component: TComponent, props?: (ComponentProps<TComponent> | Record<string, never>) | undefined);
 }
 /**
- * A helper function to help create cells from Svelte components through ColumnDef's `cell` and `header` properties.
+ * A helper class to make it easy to identify Svelte Snippets in `columnDef.cell` and `columnDef.header` properties.
+ *
+ * > NOTE: This class should only be used internally by the adapter. If you're
+ * reading this and you don't know what this is for, you probably don't need it.
+ *
+ * @example
+ * ```svelte
+ * {@const result = content(context as any)}
+ * {#if result instanceof RenderSnippetConfig}
+ *   {@const { snippet, params } = result}
+ *   {@render snippet(params)}
+ * {/if}
+ * ```
+ * */
+export declare class RenderSnippetConfig<TProps> {
+    snippet: Snippet<[TProps]>;
+    params?: TProps | undefined;
+    constructor(snippet: Snippet<[TProps]>, params?: TProps | undefined);
+}
+/**
+ * Wraps a Svelte component so it can be returned from a column definition
+ * renderer such as `cell`, `header`, or `footer`.
+ *
+ * This is only to be used with Svelte Components - use `renderSnippet` for Svelte Snippets.
+ *
  * @param component A Svelte component
  * @param props The props to pass to `component`
  * @returns A `RenderComponentConfig` object that helps svelte-table know how to render the header/cell component.
@@ -32,4 +63,30 @@ export declare class RenderComponentConfig<TComponent extends Component<any>> {
  * ```
  * @see {@link https://tanstack.com/table/latest/docs/guide/column-defs}
  */
-export declare const renderComponent: <TComponent extends Component<any, {}, string>>(component: TComponent, props: ComponentProps<TComponent>) => RenderComponentConfig<TComponent>;
+export declare const renderComponent: <TComponent extends Component<any>, TProps extends ComponentProps<TComponent>>(component: TComponent, props?: TProps) => RenderComponentConfig<TComponent>;
+/**
+ * Wraps a Svelte snippet so it can be returned from a column definition
+ * renderer such as `cell`, `header`, or `footer`.
+ *
+ * *The snippet must only take one parameter.*
+ *
+ * This is only to be used with Snippets - use `renderComponent` for Svelte Components.
+ *
+ * @param snippet The snippet to render.
+ * @param params The single parameter object passed to the snippet.
+ * @returns A `RenderSnippetConfig` consumed by the Svelte `FlexRender` component.
+ * @example
+ * ```ts
+ * // +page.svelte
+ * const defaultColumns = [
+ *   columnHelper.accessor('name', {
+ *     cell: cell => renderSnippet(nameSnippet, { name: cell.row.name }),
+ *   }),
+ *   columnHelper.accessor('state', {
+ *     cell: cell => renderSnippet(stateSnippet, { state: cell.row.state }),
+ *   }),
+ * ]
+ * ```
+ * @see {@link https://tanstack.com/table/latest/docs/guide/column-defs}
+ */
+export declare const renderSnippet: <TProps>(snippet: Snippet<[TProps]>, params?: TProps) => RenderSnippetConfig<TProps>;

package/dist/render-component.js

@@ -1,9 +1,16 @@
 /**
- * A helper class to make it easy to identify Svelte components in `columnDef.cell` and `columnDef.header` properties.
+ * A helper class to make it easy to identify Svelte components in
+ * `columnDef.cell` and `columnDef.header` properties.
+ *
+ * > NOTE: This class should only be used internally by the adapter. If you're
+ * reading this and you don't know what this is for, you probably don't need it.
+ *
  * @example
  * ```svelte
- * {#if cell.column.columnDef.cell(cell.getContext()) instanceof RenderComponentConfig}
- *   <svelte:component this={columnDef.cell.component} {...columnDef.cell.props} />
+ * {@const result = content(context as any)}
+ * {#if result instanceof RenderComponentConfig}
+ *   {@const { component: Component, props } = result}
+ *   <Component {...props} />
  * {/if}
  * ```
  * */
@@ -14,7 +21,32 @@ export class RenderComponentConfig {
     }
 }
 /**
- * A helper function to help create cells from Svelte components through ColumnDef's `cell` and `header` properties.
+ * A helper class to make it easy to identify Svelte Snippets in `columnDef.cell` and `columnDef.header` properties.
+ *
+ * > NOTE: This class should only be used internally by the adapter. If you're
+ * reading this and you don't know what this is for, you probably don't need it.
+ *
+ * @example
+ * ```svelte
+ * {@const result = content(context as any)}
+ * {#if result instanceof RenderSnippetConfig}
+ *   {@const { snippet, params } = result}
+ *   {@render snippet(params)}
+ * {/if}
+ * ```
+ * */
+export class RenderSnippetConfig {
+    constructor(snippet, params) {
+        this.snippet = snippet;
+        this.params = params;
+    }
+}
+/**
+ * Wraps a Svelte component so it can be returned from a column definition
+ * renderer such as `cell`, `header`, or `footer`.
+ *
+ * This is only to be used with Svelte Components - use `renderSnippet` for Svelte Snippets.
+ *
  * @param component A Svelte component
  * @param props The props to pass to `component`
  * @returns A `RenderComponentConfig` object that helps svelte-table know how to render the header/cell component.
@@ -33,3 +65,29 @@ export class RenderComponentConfig {
  * @see {@link https://tanstack.com/table/latest/docs/guide/column-defs}
  */
 export const renderComponent = (component, props) => new RenderComponentConfig(component, props);
+/**
+ * Wraps a Svelte snippet so it can be returned from a column definition
+ * renderer such as `cell`, `header`, or `footer`.
+ *
+ * *The snippet must only take one parameter.*
+ *
+ * This is only to be used with Snippets - use `renderComponent` for Svelte Components.
+ *
+ * @param snippet The snippet to render.
+ * @param params The single parameter object passed to the snippet.
+ * @returns A `RenderSnippetConfig` consumed by the Svelte `FlexRender` component.
+ * @example
+ * ```ts
+ * // +page.svelte
+ * const defaultColumns = [
+ *   columnHelper.accessor('name', {
+ *     cell: cell => renderSnippet(nameSnippet, { name: cell.row.name }),
+ *   }),
+ *   columnHelper.accessor('state', {
+ *     cell: cell => renderSnippet(stateSnippet, { state: cell.row.state }),
+ *   }),
+ * ]
+ * ```
+ * @see {@link https://tanstack.com/table/latest/docs/guide/column-defs}
+ */
+export const renderSnippet = (snippet, params) => new RenderSnippetConfig(snippet, params);

package/dist/static-functions.d.ts

@@ -0,0 +1 @@
+export * from '@tanstack/table-core/static-functions';

package/dist/static-functions.js

@@ -0,0 +1 @@
+export * from '@tanstack/table-core/static-functions';

package/dist/subscribe.d.ts

@@ -0,0 +1,24 @@
+import { useSelector } from '@tanstack/svelte-store';
+import type { Atom, ReadonlyAtom, ReadonlyStore, Store } from '@tanstack/svelte-store';
+export type SubscribeSource<TValue> = Atom<TValue> | ReadonlyAtom<TValue> | Store<TValue> | ReadonlyStore<TValue>;
+/**
+ * Creates a fine-grained Svelte subscription to a TanStack Store source.
+ *
+ * Pass a table atom or store and optionally project it with a selector. The
+ * returned selector store exposes `.current`, making it useful for reading
+ * focused table state outside the broad `createTable` selector.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   const selected = subscribeTable(
+ *     table.atoms.rowSelection,
+ *     (rowSelection) => rowSelection[row.id],
+ *   )
+ * </script>
+ *
+ * <input type="checkbox" checked={!!selected.current} />
+ * ```
+ */
+export declare function subscribeTable<TSourceValue>(source: SubscribeSource<TSourceValue>): ReturnType<typeof useSelector<TSourceValue>>;
+export declare function subscribeTable<TSourceValue, TSelected>(source: SubscribeSource<TSourceValue>, selector: (state: TSourceValue) => TSelected): ReturnType<typeof useSelector<TSourceValue, TSelected>>;

package/dist/subscribe.js

@@ -0,0 +1,4 @@
+import { shallow, useSelector } from '@tanstack/svelte-store';
+export function subscribeTable(source, selector) {
+    return useSelector(source, selector, { compare: shallow });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-table",
-  "version": "9.0.0-alpha.5",
+  "version": "9.0.0-alpha.50",
   "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",
@@ -30,26 +31,45 @@
       "svelte": "./dist/index.js",
       "import": "./dist/index.js"
     },
+    "./static-functions": {
+      "types": "./dist/static-functions.d.ts",
+      "svelte": "./dist/static-functions.js",
+      "import": "./dist/static-functions.js"
+    },
+    "./flex-render": {
+      "types": "./dist/flex-render.d.ts",
+      "svelte": "./dist/flex-render.js",
+      "import": "./dist/flex-render.js"
+    },
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=12"
+    "node": ">=16"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "dependencies": {
-    "@tanstack/table-core": "9.0.0-alpha.4"
+    "@tanstack/svelte-store": "^0.12.0",
+    "@tanstack/table-core": "9.0.0-alpha.49"
   },
   "devDependencies": {
-    "@sveltejs/package": "^2.3.2",
-    "@sveltejs/vite-plugin-svelte": "^4.0.0-next",
-    "svelte": "^5.0.0-next",
-    "svelte-check": "^3.8.0"
+    "@sveltejs/package": "^2.5.7",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "eslint-plugin-svelte": "^3.17.1",
+    "svelte": "^5.55.7",
+    "svelte-check": "^4.4.8"
   },
   "peerDependencies": {
-    "svelte": "^5.0.0-next"
+    "svelte": "^5.0.0"
   },
-  "scripts": {}
+  "scripts": {
+    "clean": "rimraf ./build && rimraf ./dist",
+    "test:eslint": "eslint ./src",
+    "test:types": "svelte-check --tsconfig ./tsconfig.json",
+    "test:build": "publint --strict",
+    "build": "svelte-package --input ./src --output ./dist"
+  }
 }

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.