@tanstack/vue-table 9.0.0-beta.5 → 9.0.0-beta.50

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

@@ -1,369 +0,0 @@
----
-name: vue/compose-with-tanstack-form
-description: >
-  Editable cells with `@tanstack/vue-form` + `@tanstack/vue-table` v9. The table is the layout
-  primitive; the form owns state. Wire `data: form.state.values.data` (where `data` is the
-  array field) so the table reads from the form. In each column's `cell` renderer use a
-  `<form.Field name="data[${row.index}].fieldName">` slot to bind an input. Typing gotcha: if
-  your row type has recursive `subRows`, type the form rows as `Omit<Row, 'subRows'>` —
-  TanStack Form's `DeepKeys` walks the recursion and hits TS2589. Subscribe to
-  `form.state.values.data.length` (not the whole array) to drive row add/remove re-renders.
-  Pair with TanStack Pacer for debounced filter inputs on the same screen.
-type: composition
-library: tanstack-table
-framework: vue
-library_version: '9.0.0-alpha.48'
-requires:
-  - row-selection
-  - column-definitions
-sources:
-  - examples/react/with-tanstack-form/
-  - packages/vue-table/src/useTable.ts
----
-
-# Compose @tanstack/vue-table with @tanstack/vue-form
-
-## Dependencies
-
-```bash
-pnpm add @tanstack/vue-table @tanstack/vue-form
-```
-
-`@tanstack/vue-form` exposes `useForm` and the `<Field>` / `form.Field` component pattern. It
-does NOT currently ship a `createFormHook` factory — that's a React-only convenience. In Vue,
-you write component-local `<form.Field>` bindings directly. The canonical example for the
-_shape_ of this pattern lives in `examples/react/with-tanstack-form/`; the Vue translation
-maps the React `<form.AppField>` to Vue's `<form.Field>` slot.
-
-## Setup — editable rows
-
-```vue
-<script setup lang="ts">
-import { computed, ref } from 'vue'
-import { useForm, useStore } from '@tanstack/vue-form'
-import {
-  FlexRender,
-  createColumnHelper,
-  createPaginatedRowModel,
-  rowPaginationFeature,
-  tableFeatures,
-  useTable,
-} from '@tanstack/vue-table'
-import { makeData } from './makeData'
-
-// 1) Critical typing: flatten the row shape if your data is recursive.
-type Person = {
-  firstName: string
-  lastName: string
-  age: number
-  subRows?: Person[] // recursive — fine for the table
-}
-type FormRow = Omit<Person, 'subRows'> // <-- avoid TS2589 in form DeepKeys
-
-const features = tableFeatures({ rowPaginationFeature })
-const columnHelper = createColumnHelper<typeof features, FormRow>()
-
-// 2) Form owns the data array. The table reads it.
-const form = useForm({
-  defaultValues: { data: makeData(100) as FormRow[] },
-  onSubmit: async ({ value }) => {
-    // POST value.data
-  },
-})
-
-// 3) Subscribe to LENGTH only — every keystroke re-rendering the entire table
-//    is the canonical performance trap with form-in-table.
-const dataLength = useStore(form.store, (s) => s.values.data.length)
-
-// 4) Columns reference `form` via closure. Re-bind through `form.Field` slot.
-const columns = computed(() =>
-  columnHelper.columns([
-    columnHelper.accessor('firstName', {
-      header: 'First',
-      cell: ({ row }) => {
-        // Return a function/VNode that <FlexRender> can render. Easier: render
-        // <form.Field> in the template by passing row.index out — see template below.
-        return row.index
-      },
-    }),
-    columnHelper.accessor('lastName', {
-      header: 'Last',
-      cell: ({ row }) => row.index,
-    }),
-    columnHelper.accessor('age', {
-      header: 'Age',
-      cell: ({ row }) => row.index,
-    }),
-  ]),
-)
-
-const table = useTable({
-  features,
-  rowModels: { paginatedRowModel: createPaginatedRowModel() },
-  get columns() {
-    return columns.value
-  },
-  // 5) Critical: read straight from form state. Length subscription drives re-renders.
-  get data() {
-    return form.state.values.data as FormRow[]
-  },
-})
-
-void dataLength
-
-const addRow = () => {
-  form.pushFieldValue('data', {
-    firstName: '',
-    lastName: '',
-    age: 0,
-  } as FormRow)
-}
-
-const removeRow = (index: number) => {
-  form.removeFieldValue('data', index)
-}
-</script>
-
-<template>
-  <button @click="addRow">Add row</button>
-
-  <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>
-      <!-- In Vue, the cleanest way to bind cells is to render <form.Field> in
-           the template using row + column id, instead of stuffing JSX into
-           the `cell` def. -->
-      <tr v-for="row in table.getRowModel().rows" :key="row.id">
-        <td>
-          <form.Field :name="`data[${row.index}].firstName`">
-            <template #default="{ field }">
-              <input
-                :value="field.state.value"
-                @input="(e: any) => field.handleChange(e.target.value)"
-                @blur="field.handleBlur"
-              />
-            </template>
-          </form.Field>
-        </td>
-        <td>
-          <form.Field :name="`data[${row.index}].lastName`">
-            <template #default="{ field }">
-              <input
-                :value="field.state.value"
-                @input="(e: any) => field.handleChange(e.target.value)"
-              />
-            </template>
-          </form.Field>
-        </td>
-        <td>
-          <form.Field :name="`data[${row.index}].age`">
-            <template #default="{ field }">
-              <input
-                type="number"
-                :value="field.state.value"
-                @input="(e: any) => field.handleChange(Number(e.target.value))"
-              />
-            </template>
-          </form.Field>
-        </td>
-        <td><button @click="removeRow(row.index)">×</button></td>
-      </tr>
-    </tbody>
-  </table>
-</template>
-```
-
-Source: `examples/react/with-tanstack-form/src/main.tsx` (React canonical); pattern translated
-to Vue's `<form.Field>` slot API.
-
-## Core Patterns
-
-### 1. Form owns the data, table renders it
-
-```ts
-const form = useForm({ defaultValues: { data: makeData(100) } })
-
-const table = useTable({
-  features,
-  rowModels: { paginatedRowModel: createPaginatedRowModel() },
-  columns,
-  get data() {
-    return form.state.values.data
-  },
-})
-```
-
-The table is a layout primitive — pagination, sorting, filtering on the form's data. The form
-handles editing, validation, dirty tracking, submit.
-
-### 2. Cell bindings via `<form.Field name="data[${row.index}].field">`
-
-In React-form, the convention is `<form.AppField name="..." />` inside `cell:`. In Vue-form,
-prefer rendering `<form.Field>` directly in the `<template>` instead of from `cell` — the slot
-API doesn't translate cleanly through `cell: ({ row }) => ...` because cell functions return
-VNodes, not template fragments.
-
-If you do return VNodes from `cell`, use `h()`:
-
-```ts
-import { h } from 'vue'
-
-columnHelper.accessor('firstName', {
-  header: 'First',
-  cell: ({ row, table: _t }) =>
-    h(
-      form.Field,
-      { name: `data[${row.index}].firstName` },
-      {
-        default: ({ field }: any) =>
-          h('input', {
-            value: field.state.value,
-            onInput: (e: any) => field.handleChange(e.target.value),
-          }),
-      },
-    ),
-})
-```
-
-### 3. Length-only subscription to drive add/remove re-renders
-
-```ts
-import { useStore } from '@tanstack/vue-form'
-
-// ✅ Re-renders only when an item is added/removed — not on every keystroke.
-const dataLength = useStore(form.store, (s) => s.values.data.length)
-```
-
-```ts
-// ❌ Subscribing to the whole array re-renders the whole table on every keystroke.
-const allData = useStore(form.store, (s) => s.values.data)
-```
-
-The table reads `form.state.values.data` synchronously per render — you don't need the full
-array in a watcher; you just need to trigger a re-render when length changes.
-
-### 4. Recursive row types: `Omit<Row, 'subRows'>` for the form
-
-```ts
-type Person = { firstName: string; subRows?: Person[] } // recursive — fine for the TABLE
-type FormRow = Omit<Person, 'subRows'> // flat — required for the FORM
-```
-
-TanStack Form's `DeepKeys` walks `subRows` recursively and TypeScript hits TS2589 ("type
-instantiation is excessively deep"). Always flatten the row type before passing to the form.
-
-### 5. Pair with Pacer for debounced filter inputs on the same page
-
-Editable cells re-render on every keystroke; a filter input on top of the same table would
-recompute the row model per character. Wrap the filter writer in a debounced callback — see
-`tanstack-table/vue/compose-with-tanstack-pacer`.
-
-## Common Mistakes
-
-### Typing rows with recursive `subRows` and feeding to `useForm` (CRITICAL)
-
-```ts
-// ❌ TS2589: "Type instantiation is excessively deep and possibly infinite"
-const form = useForm({ defaultValues: { data: makeData(100) as Person[] } })
-
-// ✅
-type FormRow = Omit<Person, 'subRows'>
-const form = useForm({ defaultValues: { data: makeData(100) as FormRow[] } })
-```
-
-### Subscribing to the entire `form.state.values.data` (HIGH)
-
-```ts
-// ❌ Every keystroke re-renders the entire App.
-const data = useStore(form.store, (s) => s.values.data)
-
-// ✅
-const dataLength = useStore(form.store, (s) => s.values.data.length)
-// then in useTable: get data() { return form.state.values.data }
-```
-
-### Putting `form` itself in `useTable`'s `data` (HIGH)
-
-```ts
-// ❌
-useTable({ ..., data: form })
-
-// ✅
-useTable({ ..., get data() { return form.state.values.data } })
-```
-
-The table only consumes the rows array — not the form instance.
-
-### Returning a `<form.Field>` template fragment from `cell:` (MEDIUM — Vue-specific)
-
-Vue templates can't be returned from JS functions — they're compiled to render fns at build
-time. From `cell:`, return either a plain value or a VNode via `h()`. For binding with
-templates, render `<form.Field>` in the `<template>` instead.
-
-### Forgetting `useMemo`/`computed` around `columns` when columns close over `form` (HIGH)
-
-```ts
-// ❌ New columns array each render → table re-binds → form bindings reset.
-const columns = columnHelper.columns([
-  /* refs form */
-])
-```
-
-```ts
-// ✅
-const columns = computed(() =>
-  columnHelper.columns([
-    /* refs form */
-  ]),
-)
-const table = useTable({
-  features,
-  rowModels: {},
-  get columns() {
-    return columns.value
-  },
-  get data() {
-    return form.state.values.data
-  },
-})
-```
-
-### Reusing the v8 `useReactTable` + `tableMeta.updateData` editable-cell pattern (HIGH)
-
-That worked in v8 (and mechanically still does), but the v9-blessed approach is form
-composition. You get validation, dirty tracking, submit, and reset for free.
-
-### Hallucinating `createFormHook` in Vue (HIGH — Vue-specific)
-
-`createFormHook` is React-form's factory for pre-bound field components. Vue-form does not
-ship it. Use `useForm` + `<form.Field>` slots directly.
-
-### "API missing" because feature not in `features` (CRITICAL — v9-specific)
-
-The table still needs `tableFeatures({ rowPaginationFeature, … })` for whatever features
-your editable table uses. The form composition doesn't replace that requirement.
-
-### Reimplementing form state in `ref`s per cell (CRITICAL — #1 AI tell)
-
-```ts
-// ❌ A ref per cell, custom validation, manual dirty tracking…
-const firstNameRefs = new Map<string, Ref<string>>()
-```
-
-```ts
-// ✅ Let TanStack Form own it.
-form.state.values.data[row.index].firstName
-```
-
-## See Also
-
-- `tanstack-table/vue/compose-with-tanstack-pacer` — debounce filter inputs alongside editing
-- `tanstack-table/vue/compose-with-tanstack-store` — share atoms with the form's `form.store`
-- `tanstack-table/table-core/row-selection` — selection + editable rows together
-- `tanstack-table/table-core/column-definitions` — `cell` renderer typing

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

@@ -1,318 +0,0 @@
----
-name: vue/compose-with-tanstack-pacer
-description: >
-  Use `@tanstack/pacer` to debounce/throttle high-frequency writes in `@tanstack/vue-table` v9:
-  column filter inputs and column-resize state. There is no `@tanstack/vue-pacer` adapter yet —
-  use the framework-agnostic core `@tanstack/pacer` (`Debouncer`, `Throttler`, or the
-  `debounce`/`throttle` function helpers) directly from a Vue component. Pattern: keep local
-  state for the input value so typing feels instant; route the table-writing callback through
-  a `Debouncer` instance scoped to the component (so cleanup happens on unmount); pick
-  `wait: 300` for filter inputs and `wait: 16` (one frame) for column resize. Pacer replaces
-  the hand-rolled `setTimeout`-based `DebouncedInput` component that appears in every v8
-  filtering example.
-type: composition
-library: tanstack-table
-framework: vue
-library_version: '9.0.0-alpha.48'
-requires:
-  - filtering
-  - column-layout
-sources:
-  - examples/vue/filters/src/DebouncedInput.vue
-  - examples/react/with-tanstack-form/
-  - packages/pacer/src/debouncer.ts
----
-
-# Compose @tanstack/vue-table with @tanstack/pacer
-
-## Dependencies
-
-```bash
-pnpm add @tanstack/vue-table @tanstack/pacer
-```
-
-**Note:** there is no `@tanstack/vue-pacer` adapter at the time of writing — only React,
-Preact, Solid, and Angular ship dedicated Pacer adapters. Vue users consume the
-framework-agnostic core (`@tanstack/pacer`) directly. That's a fine fit: `Debouncer` and
-`Throttler` are plain classes; integration with Vue is just `onBeforeUnmount(() => debouncer.cancel())`.
-
-## Setup — debounced filter input
-
-```vue
-<!-- DebouncedInput.vue — the v9 replacement for the hand-rolled v8 component -->
-<script setup lang="ts">
-import { onBeforeUnmount, ref, watch } from 'vue'
-import { Debouncer } from '@tanstack/pacer'
-
-const props = defineProps<{
-  modelValue: string | number
-  debounce?: number
-}>()
-const emit = defineEmits<{ 'update:modelValue': [value: string | number] }>()
-
-// 1) Local state — instant UI updates while the user types.
-const local = ref(props.modelValue)
-
-// 2) One Debouncer per component instance. Reset between renders is not needed.
-const debouncer = new Debouncer(
-  (next: string | number) => emit('update:modelValue', next),
-  { wait: props.debounce ?? 300 },
-)
-
-// 3) Keep local in sync with external changes (e.g. table.resetColumnFilters()).
-watch(
-  () => props.modelValue,
-  (v) => {
-    local.value = v
-  },
-)
-
-const onInput = (e: Event) => {
-  const v = (e.target as HTMLInputElement).value
-  local.value = v
-  debouncer.maybeExecute(v)
-}
-
-// 4) Cancel pending work on unmount.
-onBeforeUnmount(() => debouncer.cancel())
-</script>
-
-<template>
-  <input :value="local" @input="onInput" />
-</template>
-```
-
-Use it in a column filter:
-
-```vue
-<DebouncedInput
-  :model-value="(column.getFilterValue() ?? '') as string"
-  @update:model-value="(v) => column.setFilterValue(v)"
-  placeholder="Search…"
-  :debounce="300"
-/>
-```
-
-## Core Patterns
-
-### 1. Local state + debounced writer = instant input, deferred store write
-
-```ts
-// ❌ Writes to the table on every keystroke. Row model recomputes per character.
-@input="(e) => column.setFilterValue(e.target.value)"
-```
-
-```ts
-// ✅ Local ref drives the input; Debouncer batches the store write at wait=300.
-const local = ref('')
-const debouncer = new Debouncer((v) => column.setFilterValue(v), { wait: 300 })
-const onInput = (e) => {
-  local.value = e.target.value
-  debouncer.maybeExecute(local.value)
-}
-```
-
-### 2. `Debouncer` vs `Throttler`
-
-| Use case                                 | Pick        | Typical `wait`      |
-| ---------------------------------------- | ----------- | ------------------- |
-| Filter input (commit after typing stops) | `Debouncer` | `300` ms            |
-| Global filter (same shape)               | `Debouncer` | `250–500` ms        |
-| Column resize drag                       | `Throttler` | `16` ms (one frame) |
-| Scroll-triggered fetch                   | `Throttler` | `100–250` ms        |
-
-```ts
-import { Throttler } from '@tanstack/pacer'
-
-const resizeThrottler = new Throttler(
-  (event: ColumnResizeInfoEvent) => /* commit resize */,
-  { wait: 16 },
-)
-```
-
-### 3. Throttling column resize via the atoms write path
-
-If you own column resize state externally (via `@tanstack/vue-store`), throttle the atom
-write:
-
-```ts
-import { Throttler } from '@tanstack/pacer'
-import { createAtom } from '@tanstack/vue-store'
-import type { ColumnResizingState } from '@tanstack/vue-table'
-
-const columnResizingAtom = createAtom<ColumnResizingState>(
-  {} as ColumnResizingState,
-)
-const throttler = new Throttler(
-  (next: ColumnResizingState) => columnResizingAtom.set(next),
-  { wait: 16 },
-)
-
-useTable({
-  features,
-  rowModels: {},
-  columns,
-  data,
-  state: {
-    get columnResizing() {
-      return columnResizingAtom.get()
-    },
-  },
-  onColumnResizingChange: (u) => {
-    const next = typeof u === 'function' ? u(columnResizingAtom.get()) : u
-    throttler.maybeExecute(next)
-  },
-})
-```
-
-For pure local resize state, the same pattern using `ref` + `onColumnResizingChange` works.
-
-### 4. Global filter debounce
-
-```vue
-<script setup lang="ts">
-import { onBeforeUnmount, ref, watch } from 'vue'
-import { Debouncer } from '@tanstack/pacer'
-
-const props = defineProps<{ table: any }>() // import the typed Table<TFeatures, TData> in real code
-const local = ref('')
-
-const debouncer = new Debouncer((v: string) => props.table.setGlobalFilter(v), {
-  wait: 250,
-})
-
-watch(local, (v) => debouncer.maybeExecute(v))
-onBeforeUnmount(() => debouncer.cancel())
-</script>
-
-<template>
-  <input v-model="local" placeholder="Search all columns…" />
-</template>
-```
-
-### 5. The `debounce`/`throttle` function helpers (alternative shape)
-
-If you don't need access to the instance (`cancel`, `flush`, etc.), the function helpers are
-the lowest-overhead form:
-
-```ts
-import { debounce } from '@tanstack/pacer'
-
-const writeFilter = debounce((v: string) => column.setFilterValue(v), {
-  wait: 300,
-})
-// later: writeFilter(value)
-```
-
-They still register internally for proper cleanup via the Pacer event client; you just don't
-expose a handle.
-
-## Common Mistakes
-
-### Writing `column.setFilterValue` directly on every keystroke (HIGH)
-
-```ts
-// ❌ Whole filtered row model recomputes per character.
-@input="(e) => column.setFilterValue(e.target.value)"
-```
-
-Fine for 100 rows, miserable for 10k+. Debounce the writer.
-
-### Hand-rolling `setTimeout`-based debounce (HIGH)
-
-```ts
-// ❌ The v8-era DebouncedInput pattern — works, but reinvents what Pacer does correctly.
-const t = ref<ReturnType<typeof setTimeout>>()
-const setter = (v) => {
-  if (t.value) clearTimeout(t.value)
-  t.value = setTimeout(() => emit('update:modelValue', v), 300)
-}
-onBeforeUnmount(() => clearTimeout(t.value))
-```
-
-Pacer handles `cancel`/`flush`/`maybeExecute`/leading edge/trailing edge consistently and
-integrates with the Pacer Devtools event client.
-
-### Importing from `@tanstack/vue-pacer` (HIGH — Vue-specific)
-
-There is no `@tanstack/vue-pacer` package. Import from `@tanstack/pacer` directly.
-
-```ts
-// ❌
-import { useDebouncedCallback } from '@tanstack/vue-pacer'
-
-// ✅
-import { Debouncer } from '@tanstack/pacer'
-```
-
-### Debouncing the local input state too (MEDIUM)
-
-The user sees stale characters in the input. Local state must be **instant**; only the
-table/store write should debounce.
-
-```ts
-// ❌
-const debouncedLocal = new Debouncer((v) => (local.value = v), { wait: 300 })
-
-// ✅ Local instant, store deferred.
-local.value = e.target.value
-debouncer.maybeExecute(local.value)
-```
-
-### Throttling resize at 250ms (MEDIUM)
-
-Too long — drag feels laggy. Use `wait: 16` (roughly one animation frame) for resize. 250ms
-is a filter-input wait.
-
-### Forgetting `onBeforeUnmount(() => debouncer.cancel())` (MEDIUM)
-
-Pending fires after unmount → call into a stale closure / nonexistent table → console error.
-Always cancel on unmount.
-
-### Hallucinating `useDebouncedCallback` from React (CRITICAL — top AI tell)
-
-`useDebouncedCallback` is a React-pacer hook. It doesn't exist in `@tanstack/vue-pacer` (which
-doesn't exist either) or in core `@tanstack/pacer`. Use the `Debouncer` class or the
-`debounce` function helper in Vue.
-
-### Hallucinating pre-v9 table APIs in the writer (CRITICAL)
-
-The debounced callback wraps `column.setFilterValue`, `table.setGlobalFilter`,
-`columnResizingAtom.set`, etc. These are v9 APIs — `useVueTable` /
-`table.setGlobalFilter` on a v8 table would not exist. See
-`tanstack-table/vue/migrate-v8-to-v9`.
-
-### "Filter API missing" because feature not in `features` (CRITICAL — v9-specific)
-
-`column.setFilterValue` is only available if `columnFilteringFeature` is registered.
-`table.setGlobalFilter` requires `globalFilteringFeature`. Debouncing a missing API is still
-a missing API.
-
-### Reimplementing per-keystroke filter logic (CRITICAL — #1 AI tell)
-
-```ts
-// ❌ Filter rows yourself.
-const filtered = computed(() =>
-  data.value.filter((r) => r.name.includes(local.value)),
-)
-useTable({ ..., data: filtered })
-```
-
-```ts
-// ✅ Use the table's filter feature; debounce the writer.
-useTable({
-  features: tableFeatures({ columnFilteringFeature, globalFilteringFeature }),
-  rowModels: { filteredRowModel: createFilteredRowModel(filterFns) },
-  columns,
-  data,
-})
-// In a filter input:
-debouncer.maybeExecute(local.value) // → table.setGlobalFilter(local.value)
-```
-
-## See Also
-
-- `tanstack-table/vue/compose-with-tanstack-form` — debounce filter while editing
-- `tanstack-table/vue/production-readiness` — debounce + tree-shake together
-- `tanstack-table/table-core/filtering` — `columnFilteringFeature` / `globalFilteringFeature`
-- `tanstack-table/table-core/column-layout` — column resizing state