@tanstack/vue-table 9.0.0-beta.40 → 9.0.0-beta.43

package/skills/with-tanstack-query/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: with-tanstack-query
+description: >
+  Compose reactive Vue Query keys and results with Vue Table manual row processing, refs/computed state, server counts, and already-processed pages without duplicating query data into a drifting local ref.
+metadata:
+  type: composition
+  library: '@tanstack/vue-table'
+  framework: vue
+  library_version: '9.0.0-beta.43'
+requires:
+  - '@tanstack/table-core#client-vs-server'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:examples/vue/with-tanstack-query'
+  - 'TanStack/table:docs/framework/vue/guide/pagination.md'
+---
+
+This skill builds on `@tanstack/table-core#client-vs-server`, `getting-started`, and `table-state`. Name each client- and server-owned processing stage first.
+
+## Setup
+
+```ts
+import { computed, ref } from 'vue'
+import { keepPreviousData, useQuery } from '@tanstack/vue-query'
+import {
+  rowPaginationFeature,
+  tableFeatures,
+  useTable,
+} from '@tanstack/vue-table'
+
+const pagination = ref({ pageIndex: 0, pageSize: 20 })
+const query = useQuery(() => ({
+  queryKey: ['people', pagination.value.pageIndex, pagination.value.pageSize],
+  queryFn: () =>
+    fetch(
+      `/api/people?page=${pagination.value.pageIndex}&size=${pagination.value.pageSize}`,
+    ).then((r) => r.json()),
+  placeholderData: keepPreviousData,
+}))
+const data = computed(() => query.data.value?.rows ?? [])
+const rowCount = computed(() => query.data.value?.rowCount ?? 0)
+const state = computed(() => ({ pagination: pagination.value }))
+const table = useTable({
+  features: tableFeatures({ rowPaginationFeature }),
+  columns,
+  data,
+  rowCount,
+  manualPagination: true,
+  state,
+  onPaginationChange: (next) => {
+    pagination.value =
+      typeof next === 'function' ? next(pagination.value) : next
+  },
+})
+```
+
+## Core Patterns
+
+### Keep query dependencies reactive
+
+Use the Vue Query options function and read refs inside it. Include every manual filter/sort/page input in the query key.
+
+### Pass Query results directly
+
+Expose result fields as computed refs. Introduce a second local data ref only for an explicit editing workflow with a cache-write policy.
+
+## Common Mistakes
+
+### HIGH Unwrapping before query construction
+
+Wrong:
+
+```ts
+const page = pagination.value.pageIndex
+useQuery(() => ({ queryKey: ['people', page], queryFn }))
+```
+
+Correct:
+
+```ts
+useQuery(() => ({ queryKey: ['people', pagination.value.pageIndex], queryFn }))
+```
+
+Only reads inside the reactive options function become query dependencies.
+
+Source: `examples/vue/with-tanstack-query/src/App.tsx`
+
+### HIGH Mirroring Query data locally
+
+Wrong:
+
+```ts
+const rows = ref(query.data.value?.rows ?? [])
+```
+
+Correct:
+
+```ts
+const rows = computed(() => query.data.value?.rows ?? [])
+```
+
+A one-time copy drifts from subsequent cache results.
+
+Source: `examples/vue/with-tanstack-query/src/App.tsx`
+
+### HIGH Omitting server counts
+
+Wrong:
+
+```ts
+useTable({ features, columns, data, manualPagination: true })
+```
+
+Correct:
+
+```ts
+useTable({ features, columns, data, rowCount, manualPagination: true })
+```
+
+One returned page cannot tell Table how many pages the server has.
+
+Source: `docs/framework/vue/guide/pagination.md`
+
+## API Discovery
+
+Inspect installed `@tanstack/vue-table/src/useTable.ts`, installed `@tanstack/vue-query/src`, and the relevant manual Table feature source for exact option types.

package/skills/with-tanstack-virtual/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: with-tanstack-virtual
+description: >
+  Virtualize Vue Table final row or column models with reactive counts and scroll targets, stable keys, measurement, spacer geometry, sticky CSS, grid/flex widths, and infinite server data.
+metadata:
+  type: composition
+  library: '@tanstack/vue-table'
+  framework: vue
+  library_version: '9.0.0-beta.43'
+requires:
+  - '@tanstack/table-core#core'
+  - getting-started
+  - table-state
+sources:
+  - 'TanStack/table:docs/framework/vue/guide/virtualization.md'
+  - 'TanStack/table:examples/vue/virtualized-rows'
+  - 'TanStack/table:examples/vue/virtualized-columns'
+  - 'TanStack/table:examples/vue/virtualized-infinite-scrolling'
+---
+
+This skill builds on `@tanstack/table-core#core`, `getting-started`, and `table-state`. Virtual consumes final Table models; it is not registered in `tableFeatures`.
+
+## Setup
+
+```ts
+import { computed, ref } from 'vue'
+import { useVirtualizer } from '@tanstack/vue-virtual'
+
+const scrollElement = ref<HTMLElement | null>(null)
+const rows = computed(() => table.getRowModel().rows)
+const rowVirtualizer = useVirtualizer(
+  computed(() => ({
+    count: rows.value.length,
+    getScrollElement: () => scrollElement.value,
+    estimateSize: () => 34,
+    getItemKey: (index) => rows.value[index]!.id,
+    overscan: 5,
+  })),
+)
+const virtualRows = computed(() => rowVirtualizer.value.getVirtualItems())
+const totalSize = computed(() => rowVirtualizer.value.getTotalSize())
+```
+
+## Core Patterns
+
+### Derive from current visible models
+
+Rows come from `table.getRowModel().rows`; columns come from `table.getVisibleLeafColumns()`. Use computed options so counts and scroll targets update.
+
+### Implement the geometry
+
+Give the scroll container a bounded height and positioning context, create a spacer using `getTotalSize()`, and translate/measure virtual items. Follow the grid/flex examples for dynamic row heights and sticky headers.
+
+### Coordinate infinite fetching
+
+Fetch near the last virtual item only while `totalFetched < serverRowCount` and no request is active. Manual sorting means the server must return the sorted order and a sort change normally resets pages.
+
+## Common Mistakes
+
+### HIGH Passing a plain options snapshot
+
+Wrong:
+
+```ts
+useVirtualizer({ count: rows.value.length, getScrollElement })
+```
+
+Correct:
+
+```ts
+useVirtualizer(computed(() => ({ count: rows.value.length, getScrollElement })))
+```
+
+Computed options keep the virtual range synchronized with Vue’s current model.
+
+Source: `examples/vue/virtualized-rows/src/App.vue`
+
+### HIGH Virtualizing source arrays
+
+Wrong:
+
+```ts
+const rows = computed(() => data.value)
+```
+
+Correct:
+
+```ts
+const rows = computed(() => table.getRowModel().rows)
+```
+
+Source arrays do not represent Table’s current filtering, sorting, expansion, or pagination.
+
+Source: `docs/framework/vue/guide/virtualization.md`
+
+### HIGH Assuming Virtual provides CSS
+
+Wrong:
+
+```vue
+<div v-for="item in virtualRows" :key="item.key">{{ rows[item.index].id }}</div>
+```
+
+Correct:
+
+```vue
+<div :style="{ height: `${totalSize}px`, position: 'relative' }"><div style="position:absolute"></div></div>
+```
+
+Virtual provides measurements, not spacer layout, transforms, sticky positioning, or Table column widths.
+
+Source: `examples/vue/virtualized-columns/src/App.vue`
+
+## API Discovery
+
+Inspect installed `@tanstack/vue-table/src` and `@tanstack/vue-virtual/src`; use the maintained Vue examples for exact row, column, and infinite layout combinations.

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

@@ -1,360 +0,0 @@
----
-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; omit the matching row model factory from `tableFeatures` (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 features — server paginates.
-const table = useTable({
-  features,
-  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 + factory omission pair
-
-Pick which slices live server-side and flip the matching `manual*` flag. **Also omit the
-matching row model factory from `tableFeatures`** — otherwise the table re-processes
-server-processed rows.
-
-| Server owns | Set                      | Omit from `tableFeatures` |
-| ----------- | ------------------------ | ------------------------- |
-| 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,
-  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,
-  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,
-  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,
-  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.
-const features = tableFeatures({
-  rowPaginationFeature,
-  paginatedRowModel: createPaginatedRowModel(),
-})
-
-// ✅ Omit the factory when the server paginates; keep the feature for its API.
-const features = tableFeatures({ rowPaginationFeature })
-```
-
-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,
-  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 row model
-factory (`paginatedRowModel`) is what you omit; 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