@tanstack/preact-table 9.0.0-alpha.46 → 9.0.0-alpha.48

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

@@ -0,0 +1,186 @@
+---
+name: preact/compose-with-tanstack-pacer
+description: >
+  Use `@tanstack/preact-pacer` to debounce / throttle the high-frequency writes
+  that drive an interactive table: column filter inputs and column resize
+  state. Pattern: import `useDebouncedCallback` from
+  `@tanstack/preact-pacer/debouncer` (or `useThrottledCallback` for resize),
+  wrap your `column.setFilterValue` / `table.setColumnSizing` calls, and let
+  the table's expensive row-model recompute happen on the trailing edge.
+  Routing keywords: preact-pacer, debounce filter, throttle resize, useDebouncedCallback,
+  performant filtering.
+type: composition
+library: tanstack-table
+framework: preact
+library_version: '9.0.0-alpha.47'
+requires:
+  - filtering
+  - column-layout
+sources:
+  - TanStack/table:examples/preact/filters/
+  - TanStack/table:examples/preact/column-resizing-performant/
+  - TanStack/table:examples/react/with-tanstack-form/
+---
+
+Filtering and column resizing fire a lot of events. Each `column.setFilterValue(...)` invalidates `filteredRowModel`, then `paginatedRowModel`, then re-renders subscribed components. For large tables that is the difference between a snappy UI and a janky one. Debounce or throttle the writes with @tanstack/preact-pacer.
+
+## Install
+
+```bash
+npm install @tanstack/preact-pacer
+```
+
+## Pattern 1 — Debounced column filter input
+
+Render the input value from local state (immediate visual feedback) and push the value into the table on a debounce.
+
+```tsx
+import { useState } from 'preact/hooks'
+import { useDebouncedCallback } from '@tanstack/preact-pacer/debouncer'
+import type { Column } from '@tanstack/preact-table'
+
+function FilterInput<TFeatures, TData>({
+  column,
+}: {
+  column: Column<TFeatures, TData>
+}) {
+  const initial = (column.getFilterValue() as string | undefined) ?? ''
+  const [value, setValue] = useState(initial)
+
+  const pushToTable = useDebouncedCallback(
+    (next: string) => column.setFilterValue(next),
+    { wait: 250 },
+  )
+
+  return (
+    <input
+      type="text"
+      value={value}
+      onInput={(e) => {
+        const next = (e.target as HTMLInputElement).value
+        setValue(next)
+        pushToTable(next)
+      }}
+      placeholder="Search…"
+    />
+  )
+}
+```
+
+The local `value` keeps the cursor and typing responsive; `pushToTable` only runs on the trailing edge, so the table only recomputes the filtered row model once per pause.
+
+Same pattern works for the global filter via `table.setGlobalFilter`.
+
+Source: `examples/preact/filters/`.
+
+## Pattern 2 — Throttled column resize
+
+Column resize fires per-mousemove. Throttling keeps the resize visually smooth without re-running the full layout on every pixel.
+
+```tsx
+import { useThrottledCallback } from '@tanstack/preact-pacer/throttler'
+
+function ResizeHandle({ header, table }) {
+  const pushSize = useThrottledCallback(
+    (size: number) => {
+      table.setColumnSizing((prev) => ({ ...prev, [header.column.id]: size }))
+    },
+    { wait: 16 }, // ~60fps
+  )
+
+  // Hook this into your existing pointermove handler.
+  return null
+}
+```
+
+In v9, column sizing is driven by `columnSizingFeature` + `table.setColumnSizing`. The throttle wraps the write side; the read side stays direct.
+
+Source: `examples/preact/column-resizing-performant/`.
+
+## When NOT to debounce
+
+- Sorting (`table.setSorting`) — fires once per click.
+- Pagination (`table.setPageIndex`, `table.setPageSize`) — fires once per page.
+- Row selection (`row.toggleSelected`) — fires once per toggle.
+
+Debouncing these adds latency for no win. Reach for pacer only on input/resize/scroll-driven writes.
+
+## With External Atoms
+
+If you've moved a slice to an external atom, debounce the atom write instead of the table API.
+
+```tsx
+const globalFilterAtom = useCreateAtom<string>('')
+
+const pushFilter = useDebouncedCallback(
+  (next: string) => globalFilterAtom.set(next),
+  { wait: 250 },
+)
+```
+
+The table reads from the atom; the atom now changes less often; the row model recomputes less often.
+
+## Common Mistakes
+
+### CRITICAL Wrapping `column.setFilterValue` AND reading filter via `column.getFilterValue()` in the same input
+
+Wrong:
+
+```tsx
+const debouncedSet = useDebouncedCallback(
+  (v: string) => column.setFilterValue(v),
+  { wait: 250 },
+)
+return (
+  <input
+    value={(column.getFilterValue() ?? '') as string} // doesn't reflect typed value
+    onInput={(e) => debouncedSet((e.target as HTMLInputElement).value)}
+  />
+)
+```
+
+Correct: hold local state for the visual `value`, debounce the write.
+
+```tsx
+const [v, setV] = useState((column.getFilterValue() ?? '') as string)
+const debouncedSet = useDebouncedCallback(
+  (next: string) => column.setFilterValue(next),
+  { wait: 250 },
+)
+
+return (
+  <input
+    value={v}
+    onInput={(e) => {
+      const next = (e.target as HTMLInputElement).value
+      setV(next)
+      debouncedSet(next)
+    }}
+  />
+)
+```
+
+Otherwise the input lags by the debounce wait — the user sees stale characters.
+
+### HIGH Debouncing the wrong direction
+
+Wrong: debouncing the read (`column.getFilterValue`), which is just a memoized derivation.
+
+Correct: debounce the **write** (`column.setFilterValue`) — that's what triggers the row-model recompute.
+
+### HIGH Treating pacer as a substitute for stable references
+
+Wrong: debouncing every `useTable` call.
+
+Correct: pacer doesn't fix unstable `_features` / `columns` / `data` references. Stabilize those first; reach for pacer for input/scroll/resize hotspots.
+Source: `docs/framework/preact/guide/table-state.md` (FAQ #1).
+
+### MEDIUM Forgetting that debounce delays the trailing edge
+
+The first keystroke still hits the table at the trailing edge of the debounce window. If you want a leading-edge call (e.g. fire immediately, then debounce subsequent calls), use the `{ leading: true, trailing: true }` shape.
+
+## See Also
+
+- `tanstack-table/filtering` — column / global filter state shape.
+- `tanstack-table/column-layout` — column sizing / pinning / visibility.
+- `tanstack-table/preact/production-readiness` — narrow selectors, stable refs.

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

@@ -0,0 +1,283 @@
+---
+name: preact/compose-with-tanstack-query
+description: >
+  Server-side / async data flow with `@tanstack/preact-query`. Key the query on
+  the table state that drives the request (pagination + sort + filters), pass
+  `placeholderData: keepPreviousData` to avoid a "0 rows flash" between pages,
+  set `manualPagination` / `manualSorting` / `manualFiltering` for the slices
+  the server owns, supply `rowCount`, and let `table.set*` writes to external
+  atoms re-key the query. Routing keywords: preact-query, server pagination,
+  keepPreviousData, useQuery, manualPagination, rowCount, fetchData.
+type: composition
+library: tanstack-table
+framework: preact
+library_version: '9.0.0-alpha.47'
+requires:
+  - preact/client-to-server
+  - pagination
+  - state-management
+sources:
+  - TanStack/table:examples/preact/with-tanstack-query/src/main.tsx
+  - TanStack/table:examples/preact/with-tanstack-query/src/fetchData.ts
+  - TanStack/table:docs/framework/preact/guide/table-state.md
+---
+
+This skill is the @tanstack/preact-query recipe for server-side tables. Read `tanstack-table/preact/client-to-server` first for the manual-mode mechanics; this skill is the Preact Query-specific wiring on top.
+
+## Install
+
+```bash
+npm install @tanstack/preact-query @tanstack/preact-table @tanstack/preact-store
+```
+
+## The Standard Recipe
+
+Own the slices that drive the request with external atoms. Read them with `useSelector` so the `queryKey` is reactive. Pass them through `options.atoms`. Set `manual*` for the slices the server owns. Use `placeholderData: keepPreviousData` so pagination doesn't flash empty.
+
+```tsx
+import { useMemo, useReducer } from 'preact/hooks'
+import { render } from 'preact'
+import {
+  QueryClient,
+  QueryClientProvider,
+  keepPreviousData,
+  useQuery,
+} from '@tanstack/preact-query'
+import { useCreateAtom, useSelector } from '@tanstack/preact-store'
+import {
+  createColumnHelper,
+  rowPaginationFeature,
+  tableFeatures,
+  useTable,
+  type PaginationState,
+} from '@tanstack/preact-table'
+import { fetchData } from './fetchData'
+import type { Person } from './fetchData'
+
+const queryClient = new QueryClient()
+const _features = tableFeatures({ rowPaginationFeature })
+const columnHelper = createColumnHelper<typeof _features, Person>()
+
+const columns = columnHelper.columns([
+  columnHelper.accessor('firstName', {
+    header: 'First Name',
+    cell: (info) => info.getValue(),
+  }),
+  columnHelper.accessor('lastName', { header: 'Last Name' }),
+  columnHelper.accessor('age', { header: 'Age' }),
+])
+
+function App() {
+  const paginationAtom = useCreateAtom<PaginationState>({
+    pageIndex: 0,
+    pageSize: 10,
+  })
+  const pagination = useSelector(paginationAtom)
+
+  const dataQuery = useQuery({
+    queryKey: ['data', pagination],
+    queryFn: () => fetchData(pagination),
+    placeholderData: keepPreviousData, // no "0 rows" flash between pages
+  })
+
+  const defaultData = useMemo(() => [], [])
+
+  const table = useTable(
+    {
+      _features,
+      _rowModels: {}, // server owns slicing
+      columns,
+      data: dataQuery.data?.rows ?? defaultData,
+      rowCount: dataQuery.data?.rowCount,
+      atoms: { pagination: paginationAtom },
+      manualPagination: true,
+    },
+    (state) => state,
+  )
+
+  // table.nextPage() writes to paginationAtom → queryKey changes → refetch.
+  return null
+}
+
+render(
+  <QueryClientProvider client={queryClient}>
+    <App />
+  </QueryClientProvider>,
+  document.getElementById('root')!,
+)
+```
+
+Source: `examples/preact/with-tanstack-query/src/main.tsx`.
+
+## Server `fetchData` Shape
+
+The fetcher returns the page of rows plus the total row count so `table.getPageCount()` is correct.
+
+```ts
+// fetchData.ts
+import type { PaginationState } from '@tanstack/preact-table'
+
+export type Person = {
+  firstName: string
+  lastName: string
+  age: number /* … */
+}
+
+export async function fetchData(pagination: PaginationState): Promise<{
+  rows: Person[]
+  rowCount: number
+}> {
+  // server returns the current page and the total count
+  const res = await fetch(
+    `/api/people?page=${pagination.pageIndex}&size=${pagination.pageSize}`,
+  )
+  return res.json()
+}
+```
+
+Source: `examples/preact/with-tanstack-query/src/fetchData.ts`.
+
+## Adding Sorting and Filters
+
+Add more external atoms; include them in the `queryKey`; set the matching `manual*` flag. The server's fetcher accepts whatever shape you forward.
+
+```tsx
+const _features = tableFeatures({
+  rowPaginationFeature,
+  rowSortingFeature,
+  columnFilteringFeature,
+  globalFilteringFeature,
+})
+
+const paginationAtom = useCreateAtom<PaginationState>({
+  pageIndex: 0,
+  pageSize: 10,
+})
+const sortingAtom = useCreateAtom<SortingState>([])
+const columnFiltersAtom = useCreateAtom<ColumnFiltersState>([])
+const globalFilterAtom = useCreateAtom<string>('')
+
+const pagination = useSelector(paginationAtom)
+const sorting = useSelector(sortingAtom)
+const columnFilters = useSelector(columnFiltersAtom)
+const globalFilter = useSelector(globalFilterAtom)
+
+const dataQuery = useQuery({
+  queryKey: ['data', pagination, sorting, columnFilters, globalFilter],
+  queryFn: () =>
+    fetchData({ pagination, sorting, columnFilters, globalFilter }),
+  placeholderData: keepPreviousData,
+})
+
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data: dataQuery.data?.rows ?? defaultData,
+  rowCount: dataQuery.data?.rowCount,
+  atoms: {
+    pagination: paginationAtom,
+    sorting: sortingAtom,
+    columnFilters: columnFiltersAtom,
+    globalFilter: globalFilterAtom,
+  },
+  manualPagination: true,
+  manualSorting: true,
+  manualFiltering: true,
+})
+```
+
+## Common Mistakes
+
+### CRITICAL `manualPagination` without `rowCount`
+
+Wrong:
+
+```tsx
+useTable({
+  /* … */,
+  data: dataQuery.data?.rows ?? defaultData,
+  manualPagination: true,
+  atoms: { pagination: paginationAtom },
+  // no rowCount
+})
+table.getPageCount() // Infinity
+```
+
+Correct: always pass `rowCount: dataQuery.data?.rowCount`.
+Source: `examples/preact/with-tanstack-query/src/main.tsx`.
+
+### CRITICAL `queryKey` that doesn't include reactive table state
+
+Wrong:
+
+```tsx
+useQuery({
+  queryKey: ['data'],
+  queryFn: () => fetchData(pagination),
+})
+```
+
+Correct:
+
+```tsx
+useQuery({
+  queryKey: ['data', pagination /* + sorting, filters, etc. */],
+  queryFn: () => fetchData(pagination),
+})
+```
+
+The query cache must vary by the slice values, or you'll fetch once and never refresh on user interaction.
+Source: `examples/preact/with-tanstack-query/src/main.tsx`.
+
+### HIGH Missing `placeholderData: keepPreviousData`
+
+Wrong: data goes `undefined` between pages; the table flashes empty.
+
+Correct: include `placeholderData: keepPreviousData` so the table keeps the last page rendered until the new page resolves.
+Source: `examples/preact/with-tanstack-query/src/main.tsx`.
+
+### HIGH Inline `data: dataQuery.data?.rows ?? []`
+
+Wrong:
+
+```tsx
+useTable({ /* … */, data: dataQuery.data?.rows ?? [] }) // new [] every render
+```
+
+Correct:
+
+```tsx
+const defaultData = useMemo(() => [], [])
+useTable({ /* … */, data: dataQuery.data?.rows ?? defaultData })
+```
+
+A new empty array each render busts row-model memos.
+
+### HIGH Keeping the client-side `_rowModels` when manual
+
+Wrong:
+
+```tsx
+useTable({
+  _features,
+  _rowModels: { paginatedRowModel: createPaginatedRowModel() }, // wasted work
+  /* … */,
+  manualPagination: true,
+})
+```
+
+Correct: drop the row-model factory whose stage the server owns. With `manualPagination: true`, the server returns the page slice already.
+
+### MEDIUM Creating a new `paginationAtom` per render
+
+Wrong: `createAtom(...)` inside the component body.
+
+Correct: `useCreateAtom(...)` (or atom at module scope).
+Source: `examples/preact/basic-external-atoms/src/main.tsx`.
+
+## See Also
+
+- `tanstack-table/preact/client-to-server` — manual-mode mechanics independent of any specific async lib.
+- `tanstack-table/preact/compose-with-tanstack-store` — slice atoms and sharing state.
+- `tanstack-table/preact/production-readiness` — narrow selectors, stable refs.