@tanstack/vue-table 9.0.0-alpha.9 → 9.0.0-beta.2

package/dist/useTable.d.ts

@@ -0,0 +1,76 @@
+import { MaybeRef, VNode } from "vue";
+import { NoInfer, RowData, Table, TableFeatures, TableOptions, TableState } from "@tanstack/table-core";
+import { Atom, ReadonlyAtom, ReadonlyStore, Store } from "@tanstack/vue-store";
+
+//#region src/useTable.d.ts
+type SubscribeSource<TValue> = Atom<TValue> | ReadonlyAtom<TValue> | Store<TValue> | ReadonlyStore<TValue>;
+type TableOptionsWithReactiveData<TFeatures extends TableFeatures, TData extends RowData> = { [K in keyof TableOptions<TFeatures, TData>]: K extends 'data' ? MaybeRef<ReadonlyArray<TData>> : MaybeRef<TableOptions<TFeatures, TData>[K]> };
+type VueTable<TFeatures extends TableFeatures, TData extends RowData, TSelected = TableState<TFeatures>> = Omit<Table<TFeatures, TData>, 'store'> & {
+  /**
+   * @deprecated Prefer `table.state` for render reads,
+   * `table.atoms.<slice>.get()` for slice snapshots, or
+   * `table.Subscribe` / `useSelector(table.store, selector)` for explicit
+   * subscriptions. `table.store.state` is a current-value snapshot and is easy
+   * to misuse in render code.
+   */
+  readonly store: Table<TFeatures, TData>['store'];
+  /**
+   * Store mode: `selector` required. Source mode: pass `source` (atom or store); omit
+   * `selector` for the whole value (identity), or pass `selector` to project. Split
+   * overloads so source-only infers `TSourceValue` for `children` (see React `Subscribe`).
+   */
+  Subscribe: {
+    <TSourceValue>(props: {
+      source: SubscribeSource<TSourceValue>;
+      selector?: undefined;
+      children: ((state: Readonly<TSourceValue>) => VNode | Array<VNode>) | VNode | Array<VNode>;
+    }): VNode | Array<VNode>;
+    <TSourceValue, TSubSelected>(props: {
+      source: SubscribeSource<TSourceValue>;
+      selector: (state: TSourceValue) => TSubSelected;
+      children: ((state: Readonly<TSubSelected>) => VNode | Array<VNode>) | VNode | Array<VNode>;
+    }): VNode | Array<VNode>;
+    <TSubSelected>(props: {
+      selector: (state: NoInfer<TableState<TFeatures>>) => TSubSelected;
+      children: ((state: Readonly<TSubSelected>) => VNode | Array<VNode>) | VNode | Array<VNode>;
+    }): VNode | Array<VNode>;
+  };
+  /**
+   * The selected state of the table. This state may not match the structure of
+   * the full table state because it is selected by the selector function that
+   * you pass as the 2nd argument to `useTable`.
+   *
+   * @example
+   * const table = useTable(options, (state) => ({ globalFilter: state.globalFilter })) // only globalFilter is part of the selected state
+   *
+   * console.log(table.state.globalFilter)
+   */
+  readonly state: Readonly<TSelected>;
+};
+/**
+ * Creates a Vue table instance backed by Vue-aware TanStack Store atoms.
+ *
+ * Table options may contain Vue refs or computed values. The adapter unwraps
+ * those reactive inputs, watches them with synchronous flushing, and keeps the
+ * table options in sync. The optional selector projects from `table.store` and
+ * exposes the selected value on `table.state`.
+ *
+ * @example
+ * ```ts
+ * const table = useTable(
+ *   {
+ *     features,
+ *     rowModels: {},
+ *     columns,
+ *     data,
+ *   },
+ *   (state) => ({ pagination: state.pagination }),
+ * )
+ *
+ * table.state.pagination
+ * ```
+ */
+declare function useTable<TFeatures extends TableFeatures, TData extends RowData, TSelected = TableState<TFeatures>>(tableOptions: TableOptions<TFeatures, TData> | TableOptionsWithReactiveData<TFeatures, TData>, selector?: (state: TableState<TFeatures>) => TSelected): VueTable<TFeatures, TData, TSelected>;
+//#endregion
+export { SubscribeSource, TableOptionsWithReactiveData, VueTable, useTable };
+//# sourceMappingURL=useTable.d.ts.map

package/dist/useTable.js

@@ -0,0 +1,83 @@
+import { flatMerge, mergeProxy } from "./merge-proxy.js";
+import { vueReactivity } from "./reactivity.js";
+import { unref, watch } from "vue";
+import { constructTable } from "@tanstack/table-core";
+import { shallow, useSelector } from "@tanstack/vue-store";
+
+//#region src/useTable.ts
+function getOptionsWithReactiveValues(options) {
+	const resolvedOptions = {};
+	for (const key of Object.keys(options)) resolvedOptions[key] = unref(options[key]);
+	return mergeProxy(options, resolvedOptions);
+}
+function getReactiveOptionDeps(options) {
+	return Object.keys(options).map((key) => unref(options[key]));
+}
+/**
+* Creates a Vue table instance backed by Vue-aware TanStack Store atoms.
+*
+* Table options may contain Vue refs or computed values. The adapter unwraps
+* those reactive inputs, watches them with synchronous flushing, and keeps the
+* table options in sync. The optional selector projects from `table.store` and
+* exposes the selected value on `table.state`.
+*
+* @example
+* ```ts
+* const table = useTable(
+*   {
+*     features,
+*     rowModels: {},
+*     columns,
+*     data,
+*   },
+*   (state) => ({ pagination: state.pagination }),
+* )
+*
+* table.state.pagination
+* ```
+*/
+function useTable(tableOptions, selector) {
+	const syncTableOptions = (table, options) => {
+		table.setOptions((prev) => flatMerge(prev, getOptionsWithReactiveValues(options)));
+	};
+	const mergedOptions = mergeProxy(tableOptions, { features: {
+		coreReativityFeature: vueReactivity(),
+		...unref(tableOptions.features) ?? {}
+	} });
+	const coreTable = constructTable(mergeProxy(getOptionsWithReactiveValues(mergedOptions), { mergeOptions: (defaultOptions, newOptions) => {
+		return flatMerge(defaultOptions, newOptions);
+	} }));
+	const table = coreTable;
+	watch(() => getReactiveOptionDeps(mergedOptions), () => {
+		syncTableOptions(coreTable, mergedOptions);
+	}, { immediate: true });
+	watch(() => {
+		const controlledState = unref(tableOptions.state);
+		const controlledAtoms = unref(tableOptions.atoms);
+		if (!controlledState) return [];
+		const controlledValues = [];
+		for (const key of Object.keys(table.initialState)) {
+			if (!(key in controlledState) || (controlledAtoms === null || controlledAtoms === void 0 ? void 0 : controlledAtoms[key]) !== void 0) continue;
+			controlledValues.push(controlledState[key]);
+		}
+		return controlledValues;
+	}, (controlledValues) => {
+		if (controlledValues.length > 0) syncTableOptions(coreTable, mergedOptions);
+	}, { immediate: true });
+	table.Subscribe = ((props) => {
+		const selected = useSelector(props.source ?? table.store, props.selector, { compare: shallow });
+		if (typeof props.children === "function") return props.children(selected.value);
+		return props.children;
+	});
+	const stateStore = useSelector(table.store, selector);
+	return {
+		...table,
+		get state() {
+			return stateStore.value;
+		}
+	};
+}
+
+//#endregion
+export { useTable };
+//# sourceMappingURL=useTable.js.map

package/dist/useTable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTable.js","names":[],"sources":["../src/useTable.ts"],"sourcesContent":["import { unref, watch } from 'vue'\nimport { constructTable } from '@tanstack/table-core'\nimport { shallow, useSelector } from '@tanstack/vue-store'\nimport { flatMerge, mergeProxy } from './merge-proxy'\nimport { vueReactivity } from './reactivity'\nimport type {\n  Atom,\n  ReadonlyAtom,\n  ReadonlyStore,\n  Store,\n} from '@tanstack/vue-store'\nimport type {\n  NoInfer,\n  RowData,\n  Table,\n  TableFeatures,\n  TableOptions,\n  TableState,\n} from '@tanstack/table-core'\nimport type { MaybeRef, VNode } from 'vue'\n\nexport type SubscribeSource<TValue> =\n  | Atom<TValue>\n  | ReadonlyAtom<TValue>\n  | Store<TValue>\n  | ReadonlyStore<TValue>\n\nexport type TableOptionsWithReactiveData<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n> = {\n  [K in keyof TableOptions<TFeatures, TData>]: K extends 'data'\n    ? MaybeRef<ReadonlyArray<TData>>\n    : MaybeRef<TableOptions<TFeatures, TData>[K]>\n}\n\nfunction getOptionsWithReactiveValues<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(options: TableOptionsWithReactiveData<TFeatures, TData>) {\n  const resolvedOptions: Record<string, unknown> = {}\n\n  for (const key of Object.keys(options)) {\n    resolvedOptions[key] = unref(\n      options[key as keyof TableOptionsWithReactiveData<TFeatures, TData>],\n    )\n  }\n\n  return mergeProxy(options, resolvedOptions)\n}\n\nfunction getReactiveOptionDeps<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(options: TableOptionsWithReactiveData<TFeatures, TData>) {\n  return Object.keys(options).map((key) =>\n    unref(options[key as keyof TableOptionsWithReactiveData<TFeatures, TData>]),\n  )\n}\n\nexport type VueTable<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TSelected = TableState<TFeatures>,\n> = Omit<Table<TFeatures, TData>, 'store'> & {\n  /**\n   * @deprecated Prefer `table.state` for render reads,\n   * `table.atoms.<slice>.get()` for slice snapshots, or\n   * `table.Subscribe` / `useSelector(table.store, selector)` for explicit\n   * subscriptions. `table.store.state` is a current-value snapshot and is easy\n   * to misuse in render code.\n   */\n  readonly store: Table<TFeatures, TData>['store']\n  /**\n   * Store mode: `selector` required. Source mode: pass `source` (atom or store); omit\n   * `selector` for the whole value (identity), or pass `selector` to project. Split\n   * overloads so source-only infers `TSourceValue` for `children` (see React `Subscribe`).\n   */\n  Subscribe: {\n    <TSourceValue>(props: {\n      source: SubscribeSource<TSourceValue>\n      selector?: undefined\n      children:\n        | ((state: Readonly<TSourceValue>) => VNode | Array<VNode>)\n        | VNode\n        | Array<VNode>\n    }): VNode | Array<VNode>\n    <TSourceValue, TSubSelected>(props: {\n      source: SubscribeSource<TSourceValue>\n      selector: (state: TSourceValue) => TSubSelected\n      children:\n        | ((state: Readonly<TSubSelected>) => VNode | Array<VNode>)\n        | VNode\n        | Array<VNode>\n    }): VNode | Array<VNode>\n    <TSubSelected>(props: {\n      selector: (state: NoInfer<TableState<TFeatures>>) => TSubSelected\n      children:\n        | ((state: Readonly<TSubSelected>) => VNode | Array<VNode>)\n        | VNode\n        | Array<VNode>\n    }): VNode | Array<VNode>\n  }\n  /**\n   * The selected state of the table. This state may not match the structure of\n   * the full table state because it is selected by the selector function that\n   * you pass as the 2nd argument to `useTable`.\n   *\n   * @example\n   * const table = useTable(options, (state) => ({ globalFilter: state.globalFilter })) // only globalFilter is part of the selected state\n   *\n   * console.log(table.state.globalFilter)\n   */\n  readonly state: Readonly<TSelected>\n}\n\n/**\n * Creates a Vue table instance backed by Vue-aware TanStack Store atoms.\n *\n * Table options may contain Vue refs or computed values. The adapter unwraps\n * those reactive inputs, watches them with synchronous flushing, and keeps the\n * table options in sync. The optional selector projects from `table.store` and\n * exposes the selected value on `table.state`.\n *\n * @example\n * ```ts\n * const table = useTable(\n *   {\n *     features,\n *     rowModels: {},\n *     columns,\n *     data,\n *   },\n *   (state) => ({ pagination: state.pagination }),\n * )\n *\n * table.state.pagination\n * ```\n */\nexport function useTable<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TSelected = TableState<TFeatures>,\n>(\n  tableOptions:\n    | TableOptions<TFeatures, TData>\n    | TableOptionsWithReactiveData<TFeatures, TData>,\n  selector?: (state: TableState<TFeatures>) => TSelected,\n): VueTable<TFeatures, TData, TSelected> {\n  const syncTableOptions = (\n    table: Table<TFeatures, TData>,\n    options: TableOptionsWithReactiveData<TFeatures, TData>,\n  ) => {\n    table.setOptions((prev) =>\n      flatMerge(prev, getOptionsWithReactiveValues(options)),\n    )\n  }\n\n  const mergedOptions = mergeProxy(tableOptions, {\n    features: {\n      coreReativityFeature: vueReactivity(),\n      ...(unref(tableOptions.features) ?? {}),\n    },\n  }) as TableOptionsWithReactiveData<TFeatures, TData>\n\n  const resolvedOptions = mergeProxy(\n    getOptionsWithReactiveValues(mergedOptions),\n    {\n      // Remove state and onStateChange - store handles it internally\n      mergeOptions: (\n        defaultOptions: TableOptions<TFeatures, TData>,\n        newOptions: Partial<TableOptions<TFeatures, TData>>,\n      ) => {\n        return flatMerge(defaultOptions, newOptions)\n      },\n    },\n  ) as TableOptions<TFeatures, TData>\n\n  const coreTable = constructTable(resolvedOptions)\n  const table = coreTable as unknown as VueTable<TFeatures, TData, TSelected>\n\n  watch(\n    () => getReactiveOptionDeps(mergedOptions),\n    () => {\n      syncTableOptions(coreTable, mergedOptions)\n    },\n    { immediate: true },\n  )\n\n  watch(\n    () => {\n      const controlledState = unref(tableOptions.state) as\n        | Record<string, unknown>\n        | undefined\n      const controlledAtoms = unref(tableOptions.atoms) as\n        | Record<string, unknown>\n        | undefined\n\n      if (!controlledState) {\n        return []\n      }\n\n      const controlledValues: Array<unknown> = []\n\n      for (const key of Object.keys(table.initialState)) {\n        if (!(key in controlledState) || controlledAtoms?.[key] !== undefined) {\n          continue\n        }\n\n        // Reading only controlled state slices here lets Vue subscribe to\n        // getters/computed values that are passed through `options.state`.\n        controlledValues.push(controlledState[key])\n      }\n\n      return controlledValues\n    },\n    (controlledValues) => {\n      if (controlledValues.length > 0) {\n        syncTableOptions(coreTable, mergedOptions)\n      }\n    },\n    { immediate: true },\n  )\n\n  table.Subscribe = ((props: {\n    source?: SubscribeSource<unknown>\n    selector?: ((state: unknown) => unknown) | undefined\n    children:\n      | ((state: Readonly<unknown>) => VNode | Array<VNode>)\n      | VNode\n      | Array<VNode>\n  }) => {\n    const source = props.source ?? table.store\n    const selected = useSelector(source as never, props.selector as never, {\n      compare: shallow,\n    })\n    if (typeof props.children === 'function') {\n      return props.children(selected.value as Readonly<unknown>)\n    }\n    return props.children\n  }) as VueTable<TFeatures, TData, TSelected>['Subscribe']\n\n  const stateStore = useSelector(table.store, selector)\n\n  return {\n    ...table,\n    get state() {\n      return stateStore.value\n    },\n  }\n}\n"],"mappings":";;;;;;;AAoCA,SAAS,6BAGP,SAAyD;CACzD,MAAM,kBAA2C,CAAC;CAElD,KAAK,MAAM,OAAO,OAAO,KAAK,OAAO,GACnC,gBAAgB,OAAO,MACrB,QAAQ,IACV;CAGF,OAAO,WAAW,SAAS,eAAe;AAC5C;AAEA,SAAS,sBAGP,SAAyD;CACzD,OAAO,OAAO,KAAK,OAAO,CAAC,CAAC,KAAK,QAC/B,MAAM,QAAQ,IAA4D,CAC5E;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAgB,SAKd,cAGA,UACuC;CACvC,MAAM,oBACJ,OACA,YACG;EACH,MAAM,YAAY,SAChB,UAAU,MAAM,6BAA6B,OAAO,CAAC,CACvD;CACF;CAEA,MAAM,gBAAgB,WAAW,cAAc,EAC7C,UAAU;EACR,sBAAsB,cAAc;EACpC,GAAI,MAAM,aAAa,QAAQ,KAAK,CAAC;CACvC,EACF,CAAC;CAeD,MAAM,YAAY,eAbM,WACtB,6BAA6B,aAAa,GAC1C,EAEE,eACE,gBACA,eACG;EACH,OAAO,UAAU,gBAAgB,UAAU;CAC7C,EACF,CAG6C,CAAC;CAChD,MAAM,QAAQ;CAEd,YACQ,sBAAsB,aAAa,SACnC;EACJ,iBAAiB,WAAW,aAAa;CAC3C,GACA,EAAE,WAAW,KAAK,CACpB;CAEA,YACQ;EACJ,MAAM,kBAAkB,MAAM,aAAa,KAAK;EAGhD,MAAM,kBAAkB,MAAM,aAAa,KAAK;EAIhD,IAAI,CAAC,iBACH,OAAO,CAAC;EAGV,MAAM,mBAAmC,CAAC;EAE1C,KAAK,MAAM,OAAO,OAAO,KAAK,MAAM,YAAY,GAAG;GACjD,IAAI,EAAE,OAAO,uFAAoB,gBAAkB,UAAS,QAC1D;GAKF,iBAAiB,KAAK,gBAAgB,IAAI;EAC5C;EAEA,OAAO;CACT,IACC,qBAAqB;EACpB,IAAI,iBAAiB,SAAS,GAC5B,iBAAiB,WAAW,aAAa;CAE7C,GACA,EAAE,WAAW,KAAK,CACpB;CAEA,MAAM,cAAc,UAOd;EAEJ,MAAM,WAAW,YADF,MAAM,UAAU,MAAM,OACS,MAAM,UAAmB,EACrE,SAAS,QACX,CAAC;EACD,IAAI,OAAO,MAAM,aAAa,YAC5B,OAAO,MAAM,SAAS,SAAS,KAA0B;EAE3D,OAAO,MAAM;CACf;CAEA,MAAM,aAAa,YAAY,MAAM,OAAO,QAAQ;CAEpD,OAAO;EACL,GAAG;EACH,IAAI,QAAQ;GACV,OAAO,WAAW;EACpB;CACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-table",
-  "version": "9.0.0-alpha.9",
+  "version": "9.0.0-beta.2",
   "description": "Headless UI for building powerful tables & datagrids for Vue.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -18,42 +18,54 @@
     "vue",
     "table",
     "vue-table",
-    "datagrid"
+    "datagrid",
+    "tanstack-intent"
   ],
   "type": "module",
-  "types": "dist/esm/index.d.ts",
-  "main": "dist/cjs/index.cjs",
-  "module": "dist/esm/index.js",
+  "types": "./dist/index.d.cts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/esm/index.d.ts",
-        "default": "./dist/esm/index.js"
-      },
-      "require": {
-        "types": "./dist/cjs/index.d.cts",
-        "default": "./dist/cjs/index.cjs"
-      }
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./flex-render": {
+      "import": "./dist/flex-render.js",
+      "require": "./dist/flex-render.cjs"
+    },
+    "./static-functions": {
+      "import": "./dist/static-functions.js",
+      "require": "./dist/static-functions.cjs"
     },
     "./package.json": "./package.json"
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=12"
+    "node": ">=16"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "dependencies": {
-    "@tanstack/table-core": "9.0.0-alpha.8"
+    "@tanstack/table-core": "9.0.0-beta.1",
+    "@tanstack/vue-store": "^0.11.0"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^5.0.5",
-    "vue": "^3.4.31"
+    "@vitejs/plugin-vue": "^6.0.7",
+    "eslint-plugin-vue": "^10.9.2",
+    "vue": "^3.5.35"
   },
   "peerDependencies": {
     "vue": ">=3.2"
   },
-  "scripts": {}
+  "scripts": {
+    "clean": "rimraf ./build && rimraf ./dist",
+    "test:eslint": "eslint ./src",
+    "test:types": "tsc",
+    "test:build": "publint --strict",
+    "build": "tsdown"
+  }
 }

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

@@ -0,0 +1,365 @@
+---
+name: vue/client-to-server
+description: >
+  Convert a client-side `@tanstack/vue-table` to server-side. Set `manualPagination` /
+  `manualSorting` / `manualFiltering` / `manualGrouping` / `manualExpanding` for whichever
+  slices the server owns; drop the matching `rowModels` factories (don't ship
+  `paginatedRowModel` when the server paginates); supply `rowCount` so `table.getPageCount()`
+  works; own the relevant state slices via either external atoms (`@tanstack/vue-store`
+  `createAtom` + `options.atoms`) or `state` + `on[State]Change` with getter wrappers. Key any
+  data fetch (TanStack Query / fetch / rxResource alternative) on the controlled state and use
+  `placeholderData: keepPreviousData` (or equivalent) to avoid a 0-rows flash between pages.
+type: lifecycle
+library: tanstack-table
+framework: vue
+library_version: '9.0.0-alpha.48'
+requires:
+  - state-management
+  - pagination
+  - filtering
+  - sorting
+sources:
+  - examples/vue/basic-external-atoms/
+  - examples/vue/basic-external-state/
+  - examples/vue/with-tanstack-query/
+  - docs/framework/vue/guide/table-state.md
+---
+
+# Client-to-Server Conversion (Vue)
+
+## Dependencies
+
+```bash
+pnpm add @tanstack/vue-table @tanstack/vue-store
+# Recommended fetch layer:
+pnpm add @tanstack/vue-query
+```
+
+External atoms (`@tanstack/vue-store`) are recommended for server-managed slices. They cut the
+`on[State]Change` plumbing entirely — the table writes to the atom; the query keys on the atom.
+
+## Setup — minimal server-paginated table
+
+```vue
+<script setup lang="ts">
+import { computed, ref, watchEffect } from 'vue'
+import { createAtom, useSelector } from '@tanstack/vue-store'
+import { keepPreviousData, useQuery } from '@tanstack/vue-query'
+import {
+  FlexRender,
+  createColumnHelper,
+  rowPaginationFeature,
+  tableFeatures,
+  useTable,
+  type PaginationState,
+} from '@tanstack/vue-table'
+import { fetchPeople } from './api'
+
+type Person = { firstName: string; lastName: string; age: number }
+
+const features = tableFeatures({ rowPaginationFeature })
+const columnHelper = createColumnHelper<typeof features, Person>()
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', { header: 'First' }),
+  columnHelper.accessor('lastName', { header: 'Last' }),
+  columnHelper.accessor('age', { header: 'Age' }),
+])
+
+// 1) Own pagination in an external atom. Cheap for the table to write through.
+const paginationAtom = createAtom<PaginationState>({
+  pageIndex: 0,
+  pageSize: 10,
+})
+const pagination = useSelector(paginationAtom)
+
+// 2) Key the query on the atom value. table.setPageIndex(...) writes to the atom
+//    → useSelector re-evaluates → useQuery refetches.
+const dataQuery = useQuery(() => ({
+  queryKey: ['people', pagination.value],
+  queryFn: () => fetchPeople(pagination.value),
+  placeholderData: keepPreviousData, // avoid "0 rows" flash between pages
+}))
+
+const tableData = computed<Person[]>(() => dataQuery.data.value?.rows ?? [])
+const rowCount = ref(0)
+watchEffect(() => {
+  const next = dataQuery.data.value?.rowCount
+  if (next != null) rowCount.value = next // keep last known total for pager UI
+})
+
+// 3) Manual pagination + `rowCount`. NO paginatedRowModel in `rowModels` — server paginates.
+const table = useTable({
+  features,
+  rowModels: {},
+  columns,
+  data: tableData,
+  rowCount,
+  atoms: { pagination: paginationAtom },
+  manualPagination: true,
+})
+</script>
+```
+
+Source: `examples/vue/with-tanstack-query/src/App.tsx`, `examples/vue/basic-external-atoms/`.
+
+## Core Patterns
+
+### 1. The `manual*` flag + `rowModels` drop pair
+
+Pick which slices live server-side and flip the matching `manual*` flag. **Also drop the
+matching `rowModels` factory** — otherwise the table re-processes server-processed rows.
+
+| Server owns | Set                      | Drop from `rowModels` |
+| ----------- | ------------------------ | --------------------- |
+| Pagination  | `manualPagination: true` | `paginatedRowModel`   |
+| Sorting     | `manualSorting: true`    | `sortedRowModel`      |
+| Filtering   | `manualFiltering: true`  | `filteredRowModel`    |
+| Grouping    | `manualGrouping: true`   | `groupedRowModel`     |
+| Expanding   | `manualExpanding: true`  | `expandedRowModel`    |
+
+Column visibility / ordering / pinning / row selection are client-side state and stay as-is.
+
+### 2. `rowCount` so `getPageCount()` works
+
+Without `rowCount`, `getPageCount()` falls back to `Math.ceil(data.length / pageSize)` — i.e.
+`1` if the server already paginated. The pager locks at "Page 1 of 1".
+
+```ts
+useTable({
+  features,
+  rowModels: {},
+  columns,
+  data: tableData,
+  rowCount: dataQuery.data.value?.rowCount, // or a stable ref/computed
+  atoms: { pagination: paginationAtom },
+  manualPagination: true,
+})
+```
+
+If `rowCount` isn't immediately available, hold the last known value in a `ref` and update via
+`watchEffect` so the pager doesn't reset to 0 during refetches.
+
+### 3. Two state-ownership shapes (pick one per slice)
+
+**External atoms (recommended with Query).** Table writes through to the atom. No
+`on[State]Change` needed.
+
+```ts
+const paginationAtom = createAtom<PaginationState>({
+  pageIndex: 0,
+  pageSize: 10,
+})
+useTable({
+  features,
+  rowModels: {},
+  columns,
+  data,
+  rowCount,
+  atoms: { pagination: paginationAtom },
+  manualPagination: true,
+})
+```
+
+**Classic `state` + `on[State]Change` with getters.** Required when migrating from v8 or
+integrating with existing Vue ref-based state. Each slice must be a getter so Vue tracks
+`.value`.
+
+```ts
+const pagination = ref<PaginationState>({ pageIndex: 0, pageSize: 10 })
+
+useTable({
+  features,
+  rowModels: {},
+  columns,
+  data,
+  rowCount,
+  state: {
+    get pagination() {
+      return pagination.value
+    },
+  },
+  onPaginationChange: (u) => {
+    pagination.value = typeof u === 'function' ? u(pagination.value) : u
+  },
+  manualPagination: true,
+})
+```
+
+**Precedence:** `atoms[slice]` > `state[slice]` > internal `baseAtoms[slice]`. Don't pass the
+same slice through both — the atoms wins silently.
+
+### 4. Cache keys must include controlled state
+
+```ts
+const sortingAtom = createAtom<SortingState>([])
+const paginationAtom = createAtom<PaginationState>({
+  pageIndex: 0,
+  pageSize: 10,
+})
+const sorting = useSelector(sortingAtom)
+const pagination = useSelector(paginationAtom)
+
+const dataQuery = useQuery(() => ({
+  queryKey: [
+    'people',
+    { sorting: sorting.value, pagination: pagination.value },
+  ],
+  queryFn: () =>
+    fetchPeople({ sorting: sorting.value, pagination: pagination.value }),
+  placeholderData: keepPreviousData,
+}))
+```
+
+If pagination/sort/filter aren't in `queryKey`, Query won't refetch when the user clicks a
+pager button — the buttons "do nothing" from the user's POV.
+
+### 5. Mixed client + server features still work
+
+Column visibility, ordering, pinning, and row selection are client state — they don't depend
+on the row model and continue to function with `manualPagination`/`manualSorting`/`manualFiltering`.
+You can have a server-paginated table where the user pins or hides columns locally.
+
+## Common Mistakes
+
+### Forgetting `manualPagination` / `manualSorting` / `manualFiltering` (CRITICAL)
+
+The table double-processes server-processed rows. If the server returned page 2 of 50,
+the table will paginate that 10-row slice again and show "Page 1 of 1".
+
+```ts
+// ❌
+useTable({
+  features,
+  rowModels: {},
+  columns,
+  data: serverPage.rows,
+  rowCount,
+  atoms: { pagination: paginationAtom },
+  // missing: manualPagination: true
+})
+```
+
+### Leaving `paginatedRowModel` registered when server paginates (CRITICAL)
+
+```ts
+// ❌ Factory ships for nothing AND the table re-paginates server-sliced data.
+rowModels: {
+  paginatedRowModel: createPaginatedRowModel()
+}
+
+// ✅
+rowModels: {
+}
+```
+
+Same applies to `sortedRowModel`, `filteredRowModel`, `groupedRowModel`, `expandedRowModel`
+when the server owns the slice.
+
+### Omitting `rowCount` (CRITICAL)
+
+`getPageCount()` returns `1` if the server already paginated. The pager UI locks at
+"Page 1 of 1" and users can't navigate.
+
+### Passing `state.pagination` without `onPaginationChange` (CRITICAL)
+
+```ts
+// ❌ table.setPageIndex(2) is a no-op — no writeback handler.
+const pagination = ref({ pageIndex: 0, pageSize: 10 })
+useTable({
+  features,
+  rowModels: {},
+  columns,
+  data,
+  rowCount,
+  state: {
+    get pagination() {
+      return pagination.value
+    },
+  },
+  manualPagination: true,
+})
+
+// ✅ Either pair `state` with `on[State]Change`, OR use `atoms`.
+```
+
+### Mixing `state.pagination` AND `atoms.pagination` for the same slice (HIGH)
+
+```ts
+useTable({
+  // ...
+  state: {
+    get pagination() {
+      return localPagination.value
+    },
+  }, // silently ignored
+  onPaginationChange: setLocalPagination, // silently ignored
+  atoms: { pagination: paginationAtom }, // wins
+})
+```
+
+Atoms beat `state`; the `state` plumbing is dead but lingering in the code. Pick one mechanism.
+
+### Forgetting to include controlled state in `queryKey` (CRITICAL)
+
+```ts
+// ❌ Never refetches when pagination changes.
+useQuery(() => ({
+  queryKey: ['people'],
+  queryFn: () => fetchPeople(pagination.value),
+}))
+
+// ✅
+useQuery(() => ({
+  queryKey: ['people', pagination.value],
+  queryFn: () => fetchPeople(pagination.value),
+}))
+```
+
+### Skipping `placeholderData: keepPreviousData` (HIGH)
+
+Between fetches the table collapses to 0 rows, the row container collapses, and scroll
+position jumps. `keepPreviousData` keeps the previous page visible during the refetch.
+
+### Passing a raw `ref` to `state.pagination` without a getter (CRITICAL — Vue-specific)
+
+```ts
+// ❌ Vue can't track .value changes on the captured ref object.
+state: { pagination: pagination }
+
+// ✅
+state: { get pagination() { return pagination.value } }
+```
+
+### Hand-rolling sort/page state instead of using the API (CRITICAL — #1 AI tell)
+
+```ts
+// ❌ Manual state machine.
+const pageIndex = ref(0)
+const next = () => {
+  pageIndex.value++
+  refetch()
+}
+
+// ✅ Built-ins.
+table.nextPage()
+table.setPageIndex(0)
+table.setSorting([{ id: 'age', desc: true }])
+table.setColumnFilters(/* ... */)
+```
+
+### "API missing" because the feature isn't in `features` (CRITICAL — v9-specific)
+
+Server-side pagination still needs `rowPaginationFeature` in `tableFeatures({...})` — that's
+what surfaces `table.setPageIndex`, `table.nextPage`, `table.getPageCount`. The factory in
+`rowModels` is what you drop; the feature stays.
+
+```ts
+const features = tableFeatures({ rowPaginationFeature }) // ✅ even with manualPagination
+```
+
+## See Also
+
+- `tanstack-table/vue/compose-with-tanstack-query` — the Query-specific wiring
+- `tanstack-table/vue/compose-with-tanstack-store` — external atoms in depth
+- `tanstack-table/vue/table-state` — getter rule, atom precedence
+- `tanstack-table/table-core/pagination` — `manualPagination` / `rowCount` semantics