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

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

@@ -0,0 +1,363 @@
+---
+name: react/compose-with-tanstack-form
+description: >
+  Editable cells for `@tanstack/react-table` v9 via `@tanstack/react-form`. The
+  table is the layout primitive; the form owns editing state. Use
+  `createFormHook` to register reusable field components (`TextField`,
+  `NumberField`, `SelectField`), then in each column's `cell` return
+  `<form.AppField name={`data[${row.index}].field`}>{(field) => <field.TextField />}</form.AppField>`.
+  Critical typing gotcha: if your row has a recursive `subRows`, use
+  `Omit<Row, 'subRows'>` for the form row type — TanStack Form's `DeepKeys`
+  recurses and hits TS2589. Subscribe to `form.state.values.data.length` (not
+  the whole array) for row add/remove re-renders.
+type: composition
+library: tanstack-table
+framework: react
+library_version: '9.0.0-alpha.48'
+requires:
+  - row-selection
+  - column-definitions
+  - react/table-state
+sources:
+  - TanStack/table:examples/react/with-tanstack-form/src/main.tsx
+  - TanStack/table:examples/react/with-tanstack-form/src/form.tsx
+---
+
+This skill builds on `tanstack-table/state-management`, `tanstack-table/react/table-state`, and `tanstack-table/column-definitions`. Read those first.
+
+## Why this exists
+
+TanStack Table v9 deliberately ships no built-in editing — Kevin (the maintainer) scoped it out in favor of composing with TanStack Form. The form owns row-level state, validation, dirty tracking, submit; the table is the layout/sort/filter/paginate engine. This is the v9-blessed answer to "how do I make editable cells?"
+
+## Setup
+
+```bash
+pnpm add @tanstack/react-table @tanstack/react-form zod
+```
+
+Define your field components and a form hook in a `form.tsx` module. Source: `examples/react/with-tanstack-form/src/form.tsx`.
+
+```tsx
+import { createFormHook, createFormHookContexts } from '@tanstack/react-form'
+
+const { fieldContext, formContext } = createFormHookContexts()
+
+function TextField() {
+  /* reads field state from fieldContext */
+}
+function NumberField() {
+  /* … */
+}
+function SelectField() {
+  /* … */
+}
+function SubmitButton() {
+  /* … */
+}
+function FormStateIndicator() {
+  /* … */
+}
+
+export const { useAppForm } = createFormHook({
+  fieldComponents: { TextField, NumberField, SelectField },
+  formComponents: { SubmitButton, FormStateIndicator },
+  fieldContext,
+  formContext,
+})
+```
+
+## Core Pattern — editable people table
+
+```tsx
+import * as React from 'react'
+import {
+  useTable,
+  tableFeatures,
+  columnFilteringFeature,
+  rowPaginationFeature,
+  createColumnHelper,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  filterFns,
+} from '@tanstack/react-table'
+import { useStore } from '@tanstack/react-form'
+import { z } from 'zod'
+import { useAppForm } from './form'
+import type { Person } from './makeData'
+
+// CRITICAL: flatten recursive subRows before handing rows to the form.
+// Without Omit, TanStack Form's DeepKeys walks subRows and hits TS2589.
+type FormRow = Omit<Person, 'subRows'>
+
+const features = tableFeatures({
+  rowPaginationFeature,
+  columnFilteringFeature,
+})
+const columnHelper = createColumnHelper<typeof features, FormRow>()
+
+function App() {
+  const initialData: FormRow[] = makeData(100)
+
+  const form = useAppForm({
+    defaultValues: { data: initialData },
+    onSubmit: ({ value }) => {
+      alert(`Submitted ${value.data.length} records`)
+    },
+    validators: { onChange: z.object({ data: z.array(personSchema) }) },
+  })
+
+  // Memo'd columns — field bindings close over `form`, so without memoization
+  // we'd build new column defs on every keystroke.
+  const columns = React.useMemo(
+    () =>
+      columnHelper.columns([
+        columnHelper.accessor('firstName', {
+          header: 'First Name',
+          cell: ({ row }) => (
+            <form.AppField
+              name={`data[${row.index}].firstName`}
+              validators={{ onChange: z.string().min(1, 'Required') }}
+            >
+              {(field) => <field.TextField />}
+            </form.AppField>
+          ),
+        }),
+        columnHelper.accessor('age', {
+          header: 'Age',
+          cell: ({ row }) => (
+            <form.AppField
+              name={`data[${row.index}].age`}
+              validators={{ onChange: z.number().min(0).max(150) }}
+            >
+              {(field) => <field.NumberField />}
+            </form.AppField>
+          ),
+        }),
+        columnHelper.accessor('status', {
+          header: 'Status',
+          cell: ({ row }) => (
+            <form.AppField name={`data[${row.index}].status`}>
+              {(field) => <field.SelectField />}
+            </form.AppField>
+          ),
+        }),
+      ]),
+    [form],
+  )
+
+  // Subscribe ONLY to length — triggers re-renders on add/remove without infinite loops
+  // (vs subscribing to data, which fires on every keystroke).
+  const dataLength = useStore(form.store, (state) => state.values.data.length)
+  void dataLength
+
+  const table = useTable({
+    features,
+    rowModels: {
+      filteredRowModel: createFilteredRowModel(filterFns),
+      paginatedRowModel: createPaginatedRowModel(),
+    },
+    columns,
+    data: form.state.values.data, // table reads fresh form values each render
+  })
+
+  const addRow = () =>
+    form.pushFieldValue('data', {
+      firstName: '',
+      lastName: '',
+      age: 0,
+      visits: 0,
+      progress: 0,
+      status: 'single',
+    })
+
+  const refreshData = () => form.reset({ data: makeData(100) })
+
+  return (
+    <>
+      <button onClick={addRow}>Add Row</button>
+      <button onClick={refreshData}>Refresh Data</button>
+      <table>
+        <thead>{/* … */}</thead>
+        <tbody>
+          {table.getRowModel().rows.map((row) => (
+            <tr key={row.id}>
+              {row.getAllCells().map((cell) => (
+                <td key={cell.id}>
+                  <table.FlexRender cell={cell} />
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      <form.SubmitButton />
+    </>
+  )
+}
+```
+
+Source: `examples/react/with-tanstack-form/src/main.tsx`.
+
+## Add / remove rows
+
+`form.pushFieldValue('data', newRow)` adds; `form.removeFieldValue('data', index)` removes; `form.reset({ data })` replaces. The `useStore` subscription on `state.values.data.length` re-renders the holder so the table sees the new array length and renders the new row.
+
+## Common Mistakes
+
+### CRITICAL Typing rows as `Person` with recursive `subRows`
+
+Wrong:
+
+```tsx
+const form = useAppForm({ defaultValues: { data: makeData(100) as Person[] } })
+// TanStack Form's DeepKeys walks Person.subRows recursively → TS2589
+//   ("Type instantiation is excessively deep and possibly infinite")
+```
+
+Correct:
+
+```tsx
+type FormRow = Omit<Person, 'subRows'>
+const initialData: FormRow[] = makeData(100)
+const form = useAppForm({ defaultValues: { data: initialData } })
+const columnHelper = createColumnHelper<typeof features, FormRow>()
+```
+
+Always strip the recursive child field from the row type you hand to the form.
+Source: `examples/react/with-tanstack-form/src/main.tsx`.
+
+### CRITICAL Subscribing to the whole `state.values.data` array
+
+Wrong:
+
+```tsx
+// Every keystroke in any cell re-renders App → recreates form → re-binds every cell.
+const data = useStore(form.store, (s) => s.values.data)
+```
+
+Correct:
+
+```tsx
+// Subscribe to length only — triggers re-renders on add/remove, ignores edits.
+const dataLength = useStore(form.store, (state) => state.values.data.length)
+void dataLength
+// Table reads `data: form.state.values.data` directly on render.
+```
+
+Source: `examples/react/with-tanstack-form/src/main.tsx`.
+
+### HIGH Forgetting `useMemo` around columns
+
+Wrong:
+
+```tsx
+function App() {
+  const form = useAppForm({
+    /* … */
+  })
+  const columns = columnHelper.columns([
+    // new column defs every render
+    columnHelper.accessor('firstName', {
+      cell: ({ row }) => (
+        <form.AppField name={`data[${row.index}].firstName`}>
+          {(field) => <field.TextField />}
+        </form.AppField>
+      ),
+    }),
+  ])
+}
+```
+
+Correct:
+
+```tsx
+const columns = React.useMemo(
+  () =>
+    columnHelper.columns([
+      columnHelper.accessor('firstName', {
+        cell: ({ row }) => (
+          <form.AppField name={`data[${row.index}].firstName`}>
+            {(field) => <field.TextField />}
+          </form.AppField>
+        ),
+      }),
+    ]),
+  [form],
+)
+```
+
+Cell renderers close over `form`. Without memoization the column defs change every render, busting internal memos and remounting field components.
+Source: `examples/react/with-tanstack-form/src/main.tsx`.
+
+### HIGH Passing the form itself in `useTable`'s `data`
+
+Wrong:
+
+```tsx
+const table = useTable({
+  features,
+  rowModels: {
+    /* … */
+  },
+  columns,
+  data: form, // wrong — table only needs the row array
+})
+```
+
+Correct:
+
+```tsx
+const table = useTable({
+  features,
+  rowModels: {
+    /* … */
+  },
+  columns,
+  data: form.state.values.data,
+})
+```
+
+The table consumes the rows array. Mix the form's data into the table's `data` prop; don't try to make the table aware of the form instance.
+Source: `examples/react/with-tanstack-form/src/main.tsx`.
+
+### MEDIUM Trying to reuse v8's `tableMeta.updateData` pattern
+
+Wrong:
+
+```tsx
+// v8 muscle memory: track edits in tableMeta with a per-cell useState.
+const table = useReactTable({
+  data,
+  columns,
+  meta: {
+    updateData: (rowIndex, columnId, value) => {
+      /* manual setState dance */
+    },
+  },
+})
+```
+
+Correct:
+
+```tsx
+// v9 idiom: TanStack Form owns the data, table renders it.
+const form = useAppForm({ defaultValues: { data } })
+const table = useTable({
+  features,
+  rowModels: {
+    /* … */
+  },
+  columns,
+  data: form.state.values.data,
+})
+```
+
+The v8 `tableMeta.updateData` pattern still works mechanically, but the form composition handles validation, dirty tracking, submit, and add/remove for free.
+Source: maintainer guidance.
+
+## See Also
+
+- `tanstack-table/react/table-state` — base table reactivity.
+- `tanstack-table/react/compose-with-tanstack-pacer` — debounce column filter inputs on the same screen.
+- `tanstack-table/column-definitions` — cell renderer API.
+- `tanstack-table/row-selection` — row selection works alongside per-cell editing.

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

@@ -0,0 +1,287 @@
+---
+name: react/compose-with-tanstack-pacer
+description: >
+  Use `@tanstack/react-pacer` to debounce/throttle the high-frequency writes
+  that drive an interactive `@tanstack/react-table` v9 table: column filter
+  inputs and column resize state. Pattern: import `useDebouncedCallback`
+  from `@tanstack/react-pacer/debouncer`, wrap your `onChange` writer in
+  it, and keep local input state so typing feels instant. For column
+  resizing, throttle `onColumnResizingChange` so a drag doesn't push 60+
+  state updates per second. Pacer is the v9 replacement for the hand-rolled
+  `DebouncedInput` setTimeout component from v8 examples.
+type: composition
+library: tanstack-table
+framework: react
+library_version: '9.0.0-alpha.48'
+requires:
+  - filtering
+  - column-layout
+  - react/table-state
+sources:
+  - TanStack/table:examples/react/basic-subscribe/src/main.tsx
+  - TanStack/table:examples/react/with-tanstack-form/src/main.tsx
+  - TanStack/table:examples/react/kitchen-sink/src/main.tsx
+---
+
+This skill builds on `tanstack-table/state-management`, `tanstack-table/react/table-state`, and the `filtering` core skill. Read those first.
+
+## Why this exists
+
+A column filter input writes to `state.columnFilters` on every keystroke. Each write recomputes the filtered row model. For 100 rows that's fine; for 10k+ it's visibly janky. Pacer debounces the write so the filter only fires once after typing stops, while the input itself updates instantly via local state.
+
+The same principle applies to drag-to-resize: a single drag can fire `onColumnResizingChange` 60+ times per second. Throttling at ~16ms (one frame) keeps the perceived smoothness without spamming the store.
+
+## Setup
+
+```bash
+pnpm add @tanstack/react-pacer
+```
+
+```tsx
+import { useDebouncedCallback } from '@tanstack/react-pacer/debouncer'
+import { useThrottledCallback } from '@tanstack/react-pacer/throttler'
+```
+
+## Core Pattern — `DebouncedInput` for column filters
+
+The shape comes straight from the v9 examples — keep local input state so the input is instant, debounce the writer so the store only sees the trailing value.
+
+```tsx
+import * as React from 'react'
+import { useDebouncedCallback } from '@tanstack/react-pacer/debouncer'
+
+function DebouncedInput({
+  value: initialValue,
+  onChange,
+  debounce = 300,
+  ...props
+}: {
+  value: string | number
+  onChange: (value: string | number) => void
+  debounce?: number
+} & Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange'>) {
+  // Local state so the input feels instant.
+  const [value, setValue] = React.useState(initialValue)
+
+  React.useEffect(() => {
+    setValue(initialValue)
+  }, [initialValue])
+
+  // Debounced writer — fires once after `debounce` ms of inactivity.
+  const debouncedOnChange = useDebouncedCallback(onChange, { wait: debounce })
+
+  return (
+    <input
+      {...props}
+      value={value}
+      onChange={(e) => {
+        setValue(e.target.value) // instant UI update
+        debouncedOnChange(e.target.value) // debounced store write
+      }}
+    />
+  )
+}
+
+// Usage in a column filter:
+;<DebouncedInput
+  value={(column.getFilterValue() ?? '') as string}
+  onChange={(v) => column.setFilterValue(v)}
+  placeholder="Search..."
+/>
+```
+
+Source: `examples/react/basic-subscribe/src/main.tsx`; `examples/react/with-tanstack-form/src/main.tsx`.
+
+## Debounce vs throttle — choose by intent
+
+| Pattern      | Use case                                                                 | Typical wait     |
+| ------------ | ------------------------------------------------------------------------ | ---------------- |
+| **Debounce** | "Wait until they stop typing, then commit" — filter inputs, search boxes | 250–500ms        |
+| **Throttle** | "Fire at most every N ms" — drag-to-resize, scroll-triggered fetches     | 16ms (one frame) |
+
+```tsx
+// Throttled column resize
+const throttledResize = useThrottledCallback(
+  (next: ColumnResizingState) => columnResizingAtom.set(next),
+  { wait: 16 },
+)
+```
+
+## Global filter with debounce + instant input
+
+The exact pattern used in `examples/react/basic-subscribe/src/main.tsx`:
+
+```tsx
+<table.Subscribe source={table.atoms.globalFilter}>
+  {(globalFilter) => (
+    <DebouncedInput
+      value={globalFilter ?? ''}
+      onChange={(value) => table.setGlobalFilter(value)}
+      placeholder="Search all columns..."
+    />
+  )}
+</table.Subscribe>
+```
+
+The `<table.Subscribe>` wrapper keeps the input controlled by the table's atom (so external resets propagate), while `DebouncedInput`'s local state keeps the visual update instant.
+
+## Common Mistakes
+
+### CRITICAL Writing filter values directly on every keystroke
+
+Wrong:
+
+```tsx
+<input onChange={(e) => column.setFilterValue(e.target.value)} />
+// On a 10k-row table, this recomputes the filtered row model per character — janky.
+```
+
+Correct:
+
+```tsx
+<DebouncedInput
+  value={(column.getFilterValue() ?? '') as string}
+  onChange={(v) => column.setFilterValue(v)}
+/>
+```
+
+Debounce the store write; keep the input instant via local state.
+Source: `examples/react/basic-subscribe/src/main.tsx`.
+
+### HIGH Rolling your own `setTimeout` debounce
+
+Wrong:
+
+```tsx
+function DebouncedInput({ value, onChange, debounce = 300 }) {
+  const [v, setV] = React.useState(value)
+  React.useEffect(() => {
+    const t = setTimeout(() => onChange(v), debounce)
+    return () => clearTimeout(t)
+  }, [v])
+  // Works, but reinvents what useDebouncedCallback already provides with proper
+  // ref stability, cleanup, and trailing-edge semantics.
+}
+```
+
+Correct:
+
+```tsx
+function DebouncedInput({
+  value: initialValue,
+  onChange,
+  debounce = 300,
+  ...props
+}) {
+  const [value, setValue] = React.useState(initialValue)
+  React.useEffect(() => {
+    setValue(initialValue)
+  }, [initialValue])
+  const debouncedOnChange = useDebouncedCallback(onChange, { wait: debounce })
+  return (
+    <input
+      {...props}
+      value={value}
+      onChange={(e) => {
+        setValue(e.target.value)
+        debouncedOnChange(e.target.value)
+      }}
+    />
+  )
+}
+```
+
+v8 examples shipped the hand-rolled version. v9 explicitly delegates to Pacer.
+Source: `examples/react/basic-subscribe/src/main.tsx`.
+
+### HIGH Debouncing the local input state instead of (or in addition to) the writer
+
+Wrong:
+
+```tsx
+const debouncedSetLocal = useDebouncedCallback(setValue, { wait: 300 })
+<input value={value} onChange={(e) => debouncedSetLocal(e.target.value)} />
+// User sees stale characters in the input box.
+```
+
+Correct:
+
+```tsx
+const debouncedOnChange = useDebouncedCallback(onChange, { wait: 300 })
+<input
+  value={value}
+  onChange={(e) => {
+    setValue(e.target.value)           // instant local update
+    debouncedOnChange(e.target.value)  // debounced store write only
+  }}
+/>
+```
+
+Local state should always be instant. Only the expensive store write should debounce.
+Source: `examples/react/basic-subscribe/src/main.tsx`.
+
+### HIGH Throttling column resize at 250ms
+
+Wrong:
+
+```tsx
+const throttledResize = useThrottledCallback(setResize, { wait: 250 })
+// 4 fps drag → visibly laggy.
+```
+
+Correct:
+
+```tsx
+const throttledResize = useThrottledCallback(setResize, { wait: 16 })
+// ~60 fps, smooth.
+```
+
+Use roughly one frame (16ms). 250ms is fine for filter writes; far too long for drag interactions.
+Source: maintainer guidance.
+
+### MEDIUM Wrapping `column.setFilterValue` directly without local input state
+
+Wrong:
+
+```tsx
+const debouncedSet = useDebouncedCallback(column.setFilterValue, { wait: 300 })
+<input onChange={(e) => debouncedSet(e.target.value)} />
+// Input becomes uncontrolled-feeling because the render goes through the slow path.
+```
+
+Correct:
+
+```tsx
+<DebouncedInput
+  value={(column.getFilterValue() ?? '') as string}
+  onChange={(v) => column.setFilterValue(v)}
+/>
+```
+
+The `DebouncedInput` pattern combines local state (instant) with debounced commit (cheap). Don't skip the local state.
+Source: `examples/react/basic-subscribe/src/main.tsx`.
+
+### MEDIUM Using `wait: 0` and expecting debouncing
+
+Wrong:
+
+```tsx
+const debouncedOnChange = useDebouncedCallback(onChange, { wait: 0 })
+// Effectively no debounce — fires synchronously.
+```
+
+Correct:
+
+```tsx
+const debouncedOnChange = useDebouncedCallback(onChange, { wait: 300 })
+```
+
+`wait` is meaningful. 250–500ms is the typical sweet spot for filter inputs; 16ms is the typical sweet spot for resize/scroll throttling.
+Source: maintainer guidance.
+
+## See Also
+
+- `tanstack-table/react/table-state` — Subscribe boundaries for the debounced writers to feed into.
+- `tanstack-table/filtering` — column filter feature API surface.
+- `tanstack-table/column-layout` — column resize feature.
+- `tanstack-table/react/compose-with-tanstack-query` — debounce filter input that feeds a server-side query.