@tanstack/vue-table 9.0.0-beta.7 → 9.0.0-beta.71

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

@@ -1,385 +0,0 @@
----
-name: vue/compose-with-tanstack-query
-description: >
-  Server-side / async data flow for `@tanstack/vue-table` v9 + `@tanstack/vue-query`. Key the
-  `useQuery` query on the table state that drives the request (pagination + sorting + filters).
-  Set `manualPagination` / `manualSorting` / `manualFiltering` for slices the server owns.
-  Drop the matching `rowModels` factory (don't ship `paginatedRowModel` when the server
-  paginates). Pass `rowCount` so `table.getPageCount()` works without all rows in memory. Pass
-  `placeholderData: keepPreviousData` to avoid a "0 rows flash" between pages. The cleanest
-  wiring uses external `createAtom`s + `options.atoms` so the table writes through to the atom
-  and the query refetches with no `on[State]Change` plumbing. The canonical Vue example is at
-  `examples/vue/with-tanstack-query/`.
-type: composition
-library: tanstack-table
-framework: vue
-library_version: '9.0.0-alpha.48'
-requires:
-  - vue/client-to-server
-  - pagination
-  - state-management
-sources:
-  - examples/vue/with-tanstack-query/src/App.tsx
-  - examples/vue/with-tanstack-query/src/fetchData.ts
-  - examples/vue/with-tanstack-query/src/useService.ts
----
-
-# Compose @tanstack/vue-table with @tanstack/vue-query
-
-## Dependencies
-
-```bash
-pnpm add @tanstack/vue-table @tanstack/vue-query @tanstack/vue-store
-```
-
-`@tanstack/vue-store` is the recommended way to own server-controlled state slices
-(pagination / sorting / global filter). It removes the `on[State]Change` plumbing — the table
-writes through to your atom, and the query refetches because the atom drives `queryKey`.
-
-## Setup — paginated server 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 './fetchData'
-
-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('age', { header: 'Age' }),
-])
-
-// 1) Own pagination state in an atom.
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const pagination = useSelector(paginationAtom)
-
-// 2) Vue Query: function-returning-options form ensures reactivity over pagination.value.
-const dataQuery = useQuery(() => ({
-  queryKey: ['people', pagination.value],
-  queryFn: () => fetchPeople(pagination.value),
-  placeholderData: keepPreviousData,
-}))
-
-// 3) Stable empty array — avoid `?? []` inline in options.
-const EMPTY: Person[] = []
-const tableData = computed<Person[]>(() => dataQuery.data.value?.rows ?? EMPTY)
-
-// 4) Hold last known total so the pager doesn't reset during refetches.
-const rowCount = ref(0)
-watchEffect(() => {
-  const next = dataQuery.data.value?.rowCount
-  if (next != null) rowCount.value = next
-})
-
-// 5) Manual pagination. No paginatedRowModel — server paginates.
-const table = useTable({
-  features,
-  rowModels: {},
-  columns,
-  data: tableData,
-  rowCount,
-  atoms: { pagination: paginationAtom },
-  manualPagination: true,
-  // NOTE: no `onPaginationChange` — table.setPageIndex writes through to paginationAtom.
-})
-</script>
-
-<template>
-  <div>
-    <table>
-      <thead>
-        <tr v-for="hg in table.getHeaderGroups()" :key="hg.id">
-          <th v-for="h in hg.headers" :key="h.id">
-            <FlexRender v-if="!h.isPlaceholder" :header="h" />
-          </th>
-        </tr>
-      </thead>
-      <tbody>
-        <tr v-for="row in table.getRowModel().rows" :key="row.id">
-          <td v-for="cell in row.getAllCells()" :key="cell.id">
-            <FlexRender :cell="cell" />
-          </td>
-        </tr>
-      </tbody>
-    </table>
-
-    <button
-      @click="table.previousPage()"
-      :disabled="!table.getCanPreviousPage()"
-    >
-      ‹
-    </button>
-    <span
-      >Page {{ pagination.pageIndex + 1 }} of {{ table.getPageCount() }}</span
-    >
-    <button @click="table.nextPage()" :disabled="!table.getCanNextPage()">
-      ›
-    </button>
-    <span v-if="dataQuery.isFetching.value">Loading…</span>
-  </div>
-</template>
-```
-
-Source: `examples/vue/with-tanstack-query/src/App.tsx`.
-
-## Core Patterns
-
-### 1. `useQuery` accepts a getter for reactive keys
-
-```ts
-// ✅ The function form re-evaluates whenever its reactive reads (pagination.value) change.
-const dataQuery = useQuery(() => ({
-  queryKey: ['people', pagination.value],
-  queryFn: () => fetchPeople(pagination.value),
-  placeholderData: keepPreviousData,
-}))
-
-// ❌ Object form with raw value — captured once, never refetches on pagination changes.
-const dataQuery = useQuery({
-  queryKey: ['people', pagination.value],
-  queryFn: () => fetchPeople(pagination.value),
-})
-```
-
-Vue Query's reactive options require the function form. This is unlike React Query's object
-form — a common transcription error from copy-pasting React examples.
-
-### 2. Why external atoms beat `state` + `on*Change` for Query
-
-External atoms collapse two flows into one:
-
-```ts
-// Atom flow
-table.nextPage()        // table writes to atom
-  → paginationAtom.set( ... )
-    → useSelector ref updates
-      → queryKey changes
-        → useQuery refetches
-```
-
-```ts
-// state + on*Change flow (still supported; works fine)
-table.nextPage()
-  → onPaginationChange(updater)
-    → setLocalPagination(updater)
-      → ref updates
-        → queryKey changes
-          → useQuery refetches
-```
-
-Same end-to-end, but the atom version doesn't need `onPaginationChange` plumbing and a
-sibling component can `useSelector(paginationAtom)` directly without prop-drilling.
-
-### 3. Multiple server-controlled slices
-
-```ts
-const sortingAtom = createAtom<SortingState>([])
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-const filtersAtom = createAtom<ColumnFiltersState>([])
-
-const sorting = useSelector(sortingAtom)
-const pagination = useSelector(paginationAtom)
-const filters = useSelector(filtersAtom)
-
-const dataQuery = useQuery(() => ({
-  queryKey: [
-    'people',
-    {
-      sorting: sorting.value,
-      pagination: pagination.value,
-      filters: filters.value,
-    },
-  ],
-  queryFn: () =>
-    fetchPeople({
-      sorting: sorting.value,
-      pagination: pagination.value,
-      filters: filters.value,
-    }),
-  placeholderData: keepPreviousData,
-}))
-
-const table = useTable({
-  features: tableFeatures({
-    rowSortingFeature,
-    rowPaginationFeature,
-    columnFilteringFeature,
-  }),
-  rowModels: {}, // server owns all three
-  columns,
-  data: computed(() => dataQuery.data.value?.rows ?? EMPTY),
-  rowCount,
-  atoms: {
-    sorting: sortingAtom,
-    pagination: paginationAtom,
-    columnFilters: filtersAtom,
-  },
-  manualSorting: true,
-  manualPagination: true,
-  manualFiltering: true,
-})
-```
-
-### 4. Mutations + `invalidateQueries`
-
-```ts
-import { useMutation, useQueryClient } from '@tanstack/vue-query'
-
-const queryClient = useQueryClient()
-
-const addPerson = useMutation({
-  mutationFn: (person: Person) => savePerson(person),
-  onSuccess: () => {
-    queryClient.invalidateQueries({ queryKey: ['people'] })
-  },
-})
-```
-
-The table is a downstream consumer — it has no way to know the server data changed unless
-Query tells it. Always invalidate on writes.
-
-## Common Mistakes
-
-### Omitting `manualPagination` / `manualSorting` / `manualFiltering` (CRITICAL)
-
-```ts
-// ❌ Table re-paginates the already-paginated server response.
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data: tableData,
-  rowCount,
-  atoms: { pagination: paginationAtom },
-  // missing: manualPagination: true
-})
-```
-
-The visible symptom is "Page 1 of 1, but I see 10 rows of a 1000-row dataset" — the table
-slices the 10-row page locally.
-
-### Missing `rowCount` (CRITICAL)
-
-`getPageCount()` falls back to `Math.ceil(data.length / pageSize)` — which is `1` if the
-server already paginated. The pager locks at "Page 1 of 1".
-
-### Leaving `paginatedRowModel` registered with `manualPagination` (HIGH)
-
-```ts
-// ❌ Ships the factory for nothing AND it tries to paginate server-paginated data.
-rowModels: {
-  paginatedRowModel: createPaginatedRowModel()
-}
-
-// ✅
-rowModels: {
-}
-```
-
-### Forgetting controlled state in `queryKey` (CRITICAL)
-
-```ts
-// ❌ Never refetches when the user pages.
-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, scroll position
-jumps. `keepPreviousData` keeps the previous page visible during the refetch.
-
-### Passing `useQuery({...})` object form with reactive deps (HIGH — Vue-specific)
-
-`@tanstack/vue-query` requires the function form `useQuery(() => ({ ... }))` for reactive
-options. The object form snapshots once and never re-evaluates `queryKey`.
-
-### Inline `?? []` in `data` option (MEDIUM)
-
-```ts
-// ❌ Fresh array identity every recompute → table option diff churns.
-data: computed(() => dataQuery.data.value?.rows ?? [])
-
-// ✅
-const EMPTY: Person[] = []
-const tableData = computed(() => dataQuery.data.value?.rows ?? EMPTY)
-```
-
-### Passing the same slice via both `state` and `atoms` (HIGH)
-
-`atoms` wins; `state` is silently ignored. Pick one mechanism per slice.
-
-### Hallucinating React Query in a Vue project (CRITICAL — top AI tell)
-
-```ts
-// ❌ React Query — wrong package for Vue.
-import { useQuery, keepPreviousData } from '@tanstack/react-query'
-
-// ✅
-import { useQuery, keepPreviousData } from '@tanstack/vue-query'
-```
-
-Same hooks names, different reactivity model (function-returning-options instead of object).
-
-### Hallucinating pre-v9 table APIs (CRITICAL)
-
-`useVueTable` + `getCoreRowModel: getCoreRowModel()` is v8. v9 uses `useTable` +
-`features` + `rowModels`. See `tanstack-table/vue/migrate-v8-to-v9`.
-
-### "API missing" because feature not in `features` (CRITICAL — v9-specific)
-
-Server-side pagination still needs `rowPaginationFeature` in `tableFeatures({...})`. The
-feature gives you `table.nextPage` / `table.setPageIndex` / `table.getPageCount`. The
-`rowModels` factory is what you drop; the feature stays.
-
-### Reimplementing pagination loop manually (CRITICAL — #1 AI tell)
-
-```ts
-// ❌ Hand-rolled — bypasses table invariants.
-const nextPage = () => {
-  paginationAtom.set({
-    ...paginationAtom.get(),
-    pageIndex: paginationAtom.get().pageIndex + 1,
-  })
-}
-
-// ✅ Built-ins.
-table.nextPage()
-table.previousPage()
-table.setPageIndex(0)
-table.setPageSize(25)
-```
-
-## See Also
-
-- `tanstack-table/vue/client-to-server` — manual modes + `rowCount`
-- `tanstack-table/vue/compose-with-tanstack-store` — external atoms in depth
-- `tanstack-table/vue/table-state` — reactivity model
-- `tanstack-table/table-core/pagination` — `manualPagination` semantics

package/skills/vue/compose-with-tanstack-store/SKILL.md

@@ -1,301 +0,0 @@
----
-name: vue/compose-with-tanstack-store
-description: >
-  `@tanstack/vue-table` v9 is built on TanStack Store. Each state slice (sorting, pagination,
-  rowSelection, columnFilters, ...) is a separate atom. Three read surfaces:
-  `table.atoms.<slice>` (per-slice readonly), `table.store` (flat readonly view), `table.state`
-  (selector output from `useTable`'s second argument). Two write paths: the internal
-  `table.baseAtoms.<slice>` OR your own `options.atoms[slice]` if you opt to own it. In Vue, create
-  atoms with `createAtom` from `@tanstack/vue-store`, read them with `useSelector` (returns a
-  ref-like reactive value) or `computed(() => atom.get())`. The Vue adapter installs
-  `vueReactivity()` automatically so atoms back onto `computed`/`shallowRef` and subscriptions use
-  `watch(..., { flush: 'sync' })`. Precedence is `atoms[key]` > `state[key]` > internal baseAtom.
-type: composition
-library: tanstack-table
-framework: vue
-library_version: '9.0.0-alpha.48'
-requires:
-  - state-management
-sources:
-  - docs/framework/vue/guide/table-state.md
-  - examples/vue/basic-external-atoms/
-  - packages/vue-table/src/useTable.ts
-  - packages/vue-table/src/reactivity.ts
----
-
-# Compose @tanstack/vue-table with @tanstack/vue-store
-
-## Dependencies
-
-```bash
-pnpm add @tanstack/vue-table @tanstack/vue-store
-```
-
-`@tanstack/vue-store` provides `createAtom`, `useSelector`, and the `shallow` comparator. The
-Vue table adapter is built on TanStack Store internally — this skill is about exposing that
-machinery to your own app code via external atoms.
-
-## Setup — own a slice, share it across components
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { createAtom, useSelector } from '@tanstack/vue-store'
-import {
-  FlexRender,
-  createColumnHelper,
-  createPaginatedRowModel,
-  createSortedRowModel,
-  rowPaginationFeature,
-  rowSortingFeature,
-  sortFns,
-  tableFeatures,
-  useTable,
-  type PaginationState,
-  type SortingState,
-} from '@tanstack/vue-table'
-
-type Person = { firstName: string; lastName: string; age: number }
-
-const features = tableFeatures({ rowSortingFeature, rowPaginationFeature })
-const columnHelper = createColumnHelper<typeof features, Person>()
-const columns = columnHelper.columns([
-  columnHelper.accessor('firstName', { header: 'First' }),
-  columnHelper.accessor('age', { header: 'Age' }),
-])
-
-// 1) Module / setup scope — stable atom identity. createAtom returns the same atom every call;
-//    do NOT recreate it inside a watcher or render fn.
-const sortingAtom = createAtom<SortingState>([])
-const paginationAtom = createAtom<PaginationState>({
-  pageIndex: 0,
-  pageSize: 10,
-})
-
-// 2) Reactive reads anywhere — sibling components can call useSelector on the same atom.
-const sorting = useSelector(sortingAtom)
-const pagination = useSelector(paginationAtom)
-
-const data = ref<Person[]>([])
-
-// 3) Pass via `options.atoms`. NO `onSortingChange` / `onPaginationChange` needed —
-//    `table.setSorting()` writes through to your atom.
-const table = useTable({
-  features,
-  rowModels: {
-    sortedRowModel: createSortedRowModel(sortFns),
-    paginatedRowModel: createPaginatedRowModel(),
-  },
-  columns,
-  data,
-  atoms: {
-    sorting: sortingAtom,
-    pagination: paginationAtom,
-  },
-})
-</script>
-
-<template>
-  <div>
-    Page {{ pagination.pageIndex + 1 }}, sorted by
-    {{ sorting[0]?.id ?? 'none' }}
-  </div>
-</template>
-```
-
-Source: `examples/vue/basic-external-atoms/src/App.tsx`.
-
-## Core Patterns
-
-### 1. The three read surfaces — pick the narrowest
-
-```ts
-// (a) Atom — narrowest. Reads/writes one slice.
-table.atoms.sorting.get()
-table.atoms.sorting.set([{ id: 'age', desc: true }])
-useSelector(table.atoms.sorting) // reactive ref-like
-computed(() => table.atoms.sorting.get()) // alternative
-
-// (b) Flat store — full snapshot.
-table.state // readonly
-table.state.sorting // current value
-
-// (c) useTable selector — typed reactive projection.
-const table = useTable(opts, (s) => ({ sorting: s.sorting }))
-table.state.sorting
-```
-
-`table.atoms.<slice>` only contains slices for features registered in `features`. If
-`rowSortingFeature` is not registered, `table.atoms.sorting` is `undefined`.
-
-### 2. Atom precedence rules
-
-Per slice, the resolution order is:
-
-```
-options.atoms[slice]    >  options.state[slice]  >  table.baseAtoms[slice]
-(external, you own)        (controlled state)       (internal default)
-```
-
-```ts
-// ❌ Passing both for the SAME slice. `atoms.sorting` wins; `state.sorting` is silently dead.
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data,
-  state: {
-    get sorting() {
-      return localSorting.value
-    },
-  }, // ignored
-  onSortingChange: setLocalSorting, // ignored
-  atoms: { sorting: sortingAtom }, // wins
-})
-```
-
-Pick **one mechanism per slice**. Different slices can use different mechanisms freely.
-
-### 3. When to choose external atoms vs `state` + `on[State]Change`
-
-External atoms are better when:
-
-- A sibling component (sidebar, header, breadcrumbs) needs to read the same slice without going
-  through `table`.
-- You want to persist the slice (localStorage, URL params) — write a `watch(atom, persist)`
-  outside the table.
-- You're integrating with TanStack Query and want `queryKey: ['x', useSelector(atom).value]`
-  to drive refetches without `on*Change` plumbing.
-
-`state` + `on[State]Change` (with **getter wrappers** on each slice — Vue-specific) is fine
-when:
-
-- You're migrating from v8 and want the smallest diff.
-- The slice is already a `ref` you don't want to convert.
-
-### 4. Reset is YOUR responsibility for owned atoms
-
-```ts
-// ❌ table.reset() does NOT clear external atoms — it only resets internally-owned slices.
-table.reset()
-
-// ✅ Reset your atoms yourself.
-sortingAtom.set([])
-paginationAtom.set({ pageIndex: 0, pageSize: 10 })
-table.reset() // optional — for any slices the table owns internally
-```
-
-Same applies to per-slice resets: `table.resetSorting()` will update through the atom because
-the atom is the slice's source of truth — but a base-atom reset (`table.resetSorting(true)`)
-only resets internal default state, not your owned atom. Read the source if you're chaining
-resets across mixed ownership.
-
-### 5. Persisting an atom outside the table
-
-```ts
-import { watch } from 'vue'
-
-const sortingAtom = createAtom<SortingState>(
-  JSON.parse(localStorage.getItem('mySort') ?? '[]'),
-)
-const sorting = useSelector(sortingAtom)
-watch(sorting, (s) => localStorage.setItem('mySort', JSON.stringify(s)))
-```
-
-The table now writes through `table.setSorting()` → `sortingAtom.set(...)` → the watcher
-persists. No `on*Change` involved.
-
-## Common Mistakes
-
-### Creating atoms inside a render fn or component body without stable identity (CRITICAL)
-
-```vue
-<script setup>
-// ❌ A new atom every component setup → the table re-binds every mount → "state resets"
-//    feels random to the user. Only an issue when atoms are created in a reactive scope.
-const sortingAtom = computed(() => createAtom < SortingState > [])
-</script>
-```
-
-```vue
-<script setup>
-// ✅ Setup scope is once per component instance — fine.
-const sortingAtom = createAtom < SortingState > []
-
-// ✅ Module scope — shared across instances.
-// (declare at top of file outside <script setup>)
-</script>
-```
-
-### Passing the same slice via both `state` and `atoms` (HIGH)
-
-`atoms` wins; the `state` plumbing is silently dead. Pick one mechanism per slice.
-
-### Pairing `atoms.sorting` with `onSortingChange` (MEDIUM)
-
-```ts
-// ❌ Confusing — the handler never fires usefully because the atom is the writeback.
-useTable({
-  // ...
-  atoms: { sorting: sortingAtom },
-  onSortingChange: (u) => {
-    /* dead */
-  },
-})
-```
-
-When using `atoms` for a slice, drop the matching `on[State]Change`. Subscribe to the atom
-itself (`watch(useSelector(sortingAtom), ...)` or `subscribe`) if you need side effects on change.
-
-### Expecting `table.reset()` to clear external atoms (HIGH)
-
-```ts
-// ❌
-table.reset() // does not touch your atoms
-
-// ✅ Reset what you own.
-sortingAtom.set([])
-paginationAtom.set({ pageIndex: 0, pageSize: 10 })
-```
-
-### Reading `table.state.<slice>` in a deeply-nested component when only that slice matters (MEDIUM)
-
-```ts
-// ❌ All of table.state is computed and tracked even if the component only cares about rowSelection.
-const table = inject(TABLE)
-const count = computed(() => Object.keys(table.state.rowSelection).length)
-
-// ✅ Subscribe to the atom directly.
-const selection = useSelector(table.atoms.rowSelection)
-const count = computed(() => Object.keys(selection.value).length)
-```
-
-### Reading `atom.get()` outside a reactive scope (HIGH — Vue-specific)
-
-```ts
-// ❌ One-shot read; doesn't track.
-const sorting = sortingAtom.get()
-
-// ✅ useSelector returns a reactive ref-like.
-const sorting = useSelector(sortingAtom)
-
-// ✅ or wrap in computed.
-const sorting = computed(() => sortingAtom.get())
-```
-
-### Hallucinating pre-v9 API names (CRITICAL)
-
-`useVueTable`, `table.getState()` — both v8. v9 uses `useTable` and `table.state` /
-`table.state` / `table.atoms.<slice>.get()`. See `tanstack-table/vue/migrate-v8-to-v9`.
-
-### "API missing" because feature not in `features` (CRITICAL — v9-specific)
-
-`table.atoms.sorting` is `undefined` unless `rowSortingFeature` is registered. The fix isn't to
-fall back to `state` — it's to add the feature to `tableFeatures({...})`.
-
-## See Also
-
-- `tanstack-table/vue/table-state` — read surfaces and selector reactivity
-- `tanstack-table/vue/client-to-server` — atoms + manual modes wiring
-- `tanstack-table/vue/compose-with-tanstack-query` — atoms in the queryKey
-- `tanstack-table/vue/production-readiness` — `useSelector` per-slice for narrow re-renders