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

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

@@ -0,0 +1,263 @@
+---
+name: preact/compose-with-tanstack-store
+description: >
+  `@tanstack/preact-table` v9 is built on TanStack Store. Each registered state
+  slice is an atom. The table exposes three reactive surfaces:
+  `table.atoms.<slice>` (per-slice readonly), `table.store` (flat readonly
+  view), and `table.baseAtoms.<slice>` (internal writable). Use external atoms
+  via `useCreateAtom` + `options.atoms` to hand slice ownership to your app,
+  share atoms across components with `useSelector`, and subscribe imperatively
+  with `atom.subscribe(...)` for persistence/sync. Routing keywords:
+  preact-store, useCreateAtom, useSelector, atoms, external state, slice
+  ownership, persistence.
+type: composition
+library: tanstack-table
+framework: preact
+library_version: '9.0.0-alpha.47'
+requires:
+  - state-management
+  - preact/table-state
+sources:
+  - TanStack/table:docs/framework/preact/guide/table-state.md
+  - TanStack/table:examples/preact/basic-external-atoms/src/main.tsx
+  - TanStack/table:examples/preact/basic-subscribe/src/main.tsx
+  - TanStack/table:packages/preact-table/src/useTable.ts
+  - TanStack/table:packages/preact-table/src/reactivity.ts
+---
+
+`@tanstack/preact-table` v9 stores every registered state slice as a TanStack Store atom under the hood, and `useTable` wires Preact to those atoms via `@tanstack/preact-store`. This skill is the bridge between table state and the rest of your TanStack Store-powered app.
+
+## The Three Surfaces
+
+| Surface                   | Shape                                                      | Use when                                            |
+| ------------------------- | ---------------------------------------------------------- | --------------------------------------------------- |
+| `table.atoms.<slice>`     | `ReadonlyAtom<TSliceState>` per slice                      | Read or subscribe to one slice (preferred)          |
+| `table.store`             | `ReadonlyStore<TableState<TFeatures>>` (flat derived view) | Reading full table state, selecting projections     |
+| `table.baseAtoms.<slice>` | `Atom<TSliceState>` (writable internal)                    | Low-level writes when the slice is internally owned |
+
+External atoms passed via `options.atoms.<slice>` take precedence over `options.state[<slice>]` and over `table.baseAtoms.<slice>`. Writes from feature APIs (`table.setSorting(...)`, `table.setPageIndex(...)`, etc.) flow into whichever atom owns the slice.
+
+Source: `docs/framework/preact/guide/table-state.md`; `packages/preact-table/src/useTable.ts`.
+
+## Pattern 1 — Hand a slice to your app
+
+```tsx
+import { useCreateAtom, useSelector } from '@tanstack/preact-store'
+import {
+  rowPaginationFeature,
+  rowSortingFeature,
+  tableFeatures,
+  useTable,
+  type PaginationState,
+  type SortingState,
+} from '@tanstack/preact-table'
+
+const _features = tableFeatures({ rowPaginationFeature, rowSortingFeature })
+
+function PeopleTable({ data }) {
+  // Stable atoms owned by this component.
+  const sortingAtom = useCreateAtom<SortingState>([])
+  const paginationAtom = useCreateAtom<PaginationState>({
+    pageIndex: 0,
+    pageSize: 10,
+  })
+
+  // Independent reactive reads — only re-renders for the slice that changed.
+  const sorting = useSelector(sortingAtom)
+  const pagination = useSelector(paginationAtom)
+
+  const table = useTable({
+    _features,
+    _rowModels: {
+      /* … */
+    },
+    columns,
+    data,
+    atoms: { sorting: sortingAtom, pagination: paginationAtom },
+  })
+
+  // table.setSorting / table.setPageIndex write to your atoms.
+  return null
+}
+```
+
+Source: `examples/preact/basic-external-atoms/src/main.tsx`.
+
+## Pattern 2 — Share an atom across components
+
+Lift the atom to a module / context. Any component can read or write it, and the table stays in sync.
+
+```tsx
+// shared/atoms.ts
+import { createAtom } from '@tanstack/preact-store'
+import type { RowSelectionState } from '@tanstack/preact-table'
+
+export const selectionAtom = createAtom<RowSelectionState>({})
+```
+
+```tsx
+// TableScreen.tsx
+import { selectionAtom } from '../shared/atoms'
+
+const table = useTable({
+  _features,
+  _rowModels: {},
+  columns,
+  data,
+  atoms: { rowSelection: selectionAtom },
+})
+```
+
+```tsx
+// SelectionSummary.tsx
+import { useSelector } from '@tanstack/preact-store'
+import { selectionAtom } from '../shared/atoms'
+
+function SelectionSummary() {
+  const sel = useSelector(selectionAtom)
+  return <span>{Object.keys(sel).length} selected</span>
+}
+```
+
+Module-scope atoms are stable identities — no `useCreateAtom` needed. Don't create module-scope atoms inside a component-render body.
+
+Source: `docs/framework/preact/guide/table-state.md`.
+
+## Pattern 3 — Subscribe imperatively for persistence / sync
+
+`Atom.subscribe` returns an `{ unsubscribe }` handle. Persist to `localStorage`, push to a URL, or fan out to other stores.
+
+```tsx
+import { useEffect } from 'preact/hooks'
+
+useEffect(() => {
+  const sub = paginationAtom.subscribe((next) => {
+    localStorage.setItem('table:pagination', JSON.stringify(next))
+  })
+  return () => sub.unsubscribe()
+}, [paginationAtom])
+```
+
+You can also subscribe to `table.atoms.<slice>` directly without owning the slice. The subscription fires whenever the slice changes — whoever owns it (your atom or `baseAtoms`).
+
+Source: `packages/preact-table/src/reactivity.ts`.
+
+## Pattern 4 — Read inside cells with the standalone `<Subscribe>`
+
+Inside a cell or header render context, `table` is the core `Table<TFeatures, TData>`, not `PreactTable`. `table.Subscribe` is undefined — import the standalone component.
+
+```tsx
+import { Subscribe } from '@tanstack/preact-table'
+
+columnHelper.display({
+  id: 'select',
+  cell: ({ row, table }) => (
+    <Subscribe source={table.atoms.rowSelection} selector={(rs) => rs[row.id]}>
+      {(isSelected) => (
+        <input
+          type="checkbox"
+          checked={!!isSelected}
+          onChange={row.getToggleSelectedHandler()}
+        />
+      )}
+    </Subscribe>
+  ),
+})
+```
+
+Source: `packages/preact-table/src/Subscribe.ts`; `examples/preact/basic-subscribe/src/main.tsx`.
+
+## Common Mistakes
+
+### CRITICAL Creating an atom inside the render body without `useCreateAtom`
+
+Wrong:
+
+```tsx
+function MyTable() {
+  const sortingAtom = createAtom<SortingState>([]) // new atom every render
+  useTable({ /* … */, atoms: { sorting: sortingAtom } })
+}
+```
+
+Correct:
+
+```tsx
+function MyTable() {
+  const sortingAtom = useCreateAtom<SortingState>([]) // stable
+  useTable({ /* … */, atoms: { sorting: sortingAtom } })
+}
+```
+
+A fresh atom each render unbinds the slice and resets it to the initial value on every render.
+Source: `examples/preact/basic-external-atoms/src/main.tsx`.
+
+### HIGH Writing to `table.baseAtoms.X.set()` when the slice is externally owned
+
+Wrong:
+
+```tsx
+useTable({ /* … */, atoms: { pagination: paginationAtom } })
+table.baseAtoms.pagination.set((old) => ({ ...old, pageIndex: 0 })) // updates the wrong atom
+```
+
+Correct:
+
+```tsx
+// Use the feature API (writes to whichever atom owns the slice).
+table.setPageIndex(0)
+// Or write to your external atom directly.
+paginationAtom.set((old) => ({ ...old, pageIndex: 0 }))
+```
+
+`table.baseAtoms` is the internal writable atom — used only when the slice is internally owned. When you hand a slice to an external atom, the external atom is the source of truth.
+Source: `docs/framework/preact/guide/table-state.md`.
+
+### HIGH Reading `.get()` and expecting re-renders
+
+Wrong:
+
+```tsx
+function Pager() {
+  const { pageIndex } = table.atoms.pagination.get() // current-value read
+  return <span>Page {pageIndex + 1}</span>
+}
+```
+
+Correct:
+
+```tsx
+import { useSelector } from '@tanstack/preact-store'
+
+function Pager() {
+  const pageIndex = useSelector(table.atoms.pagination, (p) => p.pageIndex)
+  return <span>Page {pageIndex + 1}</span>
+}
+// or
+;<table.Subscribe source={table.atoms.pagination} selector={(p) => p.pageIndex}>
+  {(pageIndex) => <span>Page {pageIndex + 1}</span>}
+</table.Subscribe>
+```
+
+`.get()` returns the current value without subscribing.
+
+### MEDIUM Passing the same slice via `atoms` AND `state`
+
+Wrong:
+
+```tsx
+useTable({
+  /* … */,
+  atoms: { pagination: paginationAtom },
+  state: { pagination },             // silently ignored
+  onPaginationChange: setPagination, // silently ignored
+})
+```
+
+Correct: pick exactly one ownership path per slice.
+
+## See Also
+
+- `tanstack-table/preact/table-state` — atoms / Subscribe / FlexRender reference.
+- `tanstack-table/preact/compose-with-tanstack-query` — server-side flow keyed by atoms.
+- `tanstack-table/preact/production-readiness` — when to reach for narrow subscriptions.

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

@@ -0,0 +1,275 @@
+---
+name: preact/compose-with-tanstack-virtual
+description: >
+  TanStack Table does NOT include virtualization — pair with TanStack Virtual.
+  Preact has no dedicated `@tanstack/preact-virtual` adapter yet; use
+  `@tanstack/virtual-core`'s `Virtualizer` class behind a small hook, or use
+  the React adapter via `preact/compat`. Pattern: get `rows = table.getRowModel().rows`,
+  feed `rows.length` to the virtualizer, render only virtual items, and use
+  CSS transforms for row positioning. Routing keywords: preact virtualization,
+  large table, virtual rows, virtual-core, getVirtualItems, table-core.
+type: composition
+library: tanstack-table
+framework: preact
+library_version: '9.0.0-alpha.47'
+requires:
+  - preact/table-state
+  - row-expanding
+sources:
+  - TanStack/table:docs/guide/virtualization.md
+  - TanStack/table:examples/lit/virtualized-rows/src/main.ts
+  - TanStack/table:examples/react/virtualized-rows/
+  - TanStack/table:examples/react/virtualized-columns/
+---
+
+TanStack Table is headless — it does not virtualize rows or columns. For long lists, pair the table with TanStack Virtual.
+
+> **Adapter status:** There is no published `@tanstack/preact-virtual` adapter as of `@tanstack/table` v9.0.0-alpha.47. The two supported paths are:
+>
+> 1. **Use `@tanstack/virtual-core` directly.** The framework-agnostic `Virtualizer` class wrapped in a small Preact hook is the recommended path.
+> 2. **Use `@tanstack/react-virtual` via `preact/compat`.** Works if your project already aliases `react` → `preact/compat`.
+>
+> The patterns below use path 1. Both paths feed the same `rows = table.getRowModel().rows` array to the virtualizer.
+
+## Install
+
+```bash
+npm install @tanstack/virtual-core
+```
+
+## The Pattern (Row Virtualization)
+
+1. Build the table with `useTable` as usual.
+2. Get `const { rows } = table.getRowModel()` — the table is the source of truth for which rows to render (already sorted, filtered, paginated, etc.).
+3. Pass `rows.length` to the virtualizer.
+4. Render only `virtualizer.getVirtualItems()`.
+5. Each virtual row is absolutely positioned via `transform: translateY(${item.start}px)`.
+
+```tsx
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks'
+import {
+  Virtualizer,
+  observeElementOffset,
+  observeElementRect,
+  elementScroll,
+} from '@tanstack/virtual-core'
+import {
+  useTable,
+  createSortedRowModel,
+  rowSortingFeature,
+  sortFns,
+  tableFeatures,
+} from '@tanstack/preact-table'
+import type { JSX } from 'preact'
+
+const _features = tableFeatures({ rowSortingFeature })
+
+// Minimal Preact hook around the framework-agnostic Virtualizer.
+function useVirtualizer<TScrollEl extends Element, TItemEl extends Element>(
+  options: Omit<
+    ConstructorParameters<typeof Virtualizer<TScrollEl, TItemEl>>[0],
+    'observeElementRect' | 'observeElementOffset' | 'scrollToFn'
+  > & { onChange?: (instance: Virtualizer<TScrollEl, TItemEl>) => void },
+) {
+  const [, force] = useState(0)
+  const virtualizer = useMemo(
+    () =>
+      new Virtualizer<TScrollEl, TItemEl>({
+        ...options,
+        observeElementRect,
+        observeElementOffset,
+        scrollToFn: elementScroll,
+        onChange: (inst) => {
+          options.onChange?.(inst)
+          force((n) => n + 1)
+        },
+      }),
+    [],
+  )
+
+  // Sync count / estimateSize / overscan when they change.
+  virtualizer.setOptions({
+    ...virtualizer.options,
+    count: options.count,
+    estimateSize: options.estimateSize,
+    overscan: options.overscan,
+  })
+
+  useEffect(() => {
+    return virtualizer._didMount()
+  }, [virtualizer])
+
+  useEffect(() => {
+    virtualizer._willUpdate()
+  })
+
+  return virtualizer
+}
+
+function BigTable({ data }) {
+  const table = useTable(
+    {
+      _features,
+      _rowModels: { sortedRowModel: createSortedRowModel(sortFns) },
+      columns,
+      data,
+    },
+    () => null, // huge table — opt out at the top, subscribe lower down
+  )
+
+  const { rows } = table.getRowModel()
+
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  const rowVirtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => scrollRef.current!,
+    estimateSize: () => 33,
+    overscan: 5,
+  })
+
+  return (
+    <div
+      ref={scrollRef}
+      style={{ overflow: 'auto', height: 800, position: 'relative' }}
+    >
+      <table style={{ display: 'grid' }}>
+        <thead
+          style={{ display: 'grid', position: 'sticky', top: 0, zIndex: 1 }}
+        >
+          {table.getHeaderGroups().map((hg) => (
+            <tr key={hg.id} style={{ display: 'flex', width: '100%' }}>
+              {hg.headers.map((h) => (
+                <th key={h.id} style={{ display: 'flex', width: h.getSize() }}>
+                  <table.FlexRender header={h} />
+                </th>
+              ))}
+            </tr>
+          ))}
+        </thead>
+
+        <tbody
+          style={{
+            display: 'grid',
+            height: `${rowVirtualizer.getTotalSize()}px`,
+            position: 'relative',
+          }}
+        >
+          {rowVirtualizer.getVirtualItems().map((virtualItem) => {
+            const row = rows[virtualItem.index]
+            return (
+              <tr
+                key={row.id}
+                ref={(node) => rowVirtualizer.measureElement(node!)}
+                data-index={virtualItem.index}
+                style={{
+                  display: 'flex',
+                  position: 'absolute',
+                  transform: `translateY(${virtualItem.start}px)`,
+                  width: '100%',
+                }}
+              >
+                {row.getAllCells().map((cell) => (
+                  <td
+                    key={cell.id}
+                    style={{ display: 'flex', width: cell.column.getSize() }}
+                  >
+                    <table.FlexRender cell={cell} />
+                  </td>
+                ))}
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+```
+
+The structure matches the Lit virtualized-rows example one-for-one; only the host framework changes.
+Source: `examples/lit/virtualized-rows/src/main.ts`; `docs/guide/virtualization.md`.
+
+## Column Virtualization
+
+Same idea, but the virtualizer's `count` is `columns.length` and you index the visible columns inside each row. Useful for wide kitchen-sink tables.
+
+## With Pagination / Filtering
+
+Use the row model that's already been transformed by registered features. The virtualizer count is `rows.length` — the table handles sorting, filtering, and pagination upstream.
+
+## Combining with `<table.Subscribe>`
+
+On large tables, pass `() => null` to `useTable` (or use the standalone `<Subscribe>`) and wrap the `<tbody>` in a subscription that re-renders only when the row model can actually change.
+
+```tsx
+<table.Subscribe
+  selector={(s) => ({
+    columnFilters: s.columnFilters,
+    globalFilter: s.globalFilter,
+    sorting: s.sorting,
+  })}
+>
+  {() => <tbody>{/* virtualized rows */}</tbody>}
+</table.Subscribe>
+```
+
+Source: `examples/preact/basic-subscribe/src/main.tsx`.
+
+## Common Mistakes
+
+### CRITICAL Reimplementing virtualization by hand
+
+Wrong:
+
+```tsx
+// Manual slicing + intersection observer + per-row offset calculation
+```
+
+Correct: use TanStack Virtual's `Virtualizer` — it handles measurement, overscan, scroll alignment, and dynamic sizing.
+Source: `docs/guide/virtualization.md`.
+
+### HIGH Using the wrong row source
+
+Wrong:
+
+```tsx
+const virtualizer = useVirtualizer({ count: data.length /* … */ }) // bypasses sort/filter/paginate
+```
+
+Correct:
+
+```tsx
+const { rows } = table.getRowModel()
+const virtualizer = useVirtualizer({ count: rows.length /* … */ })
+```
+
+Always feed `table.getRowModel().rows.length` — that's the post-feature row array.
+
+### HIGH Forgetting `position: relative` on the scroll parent / `position: absolute` on rows
+
+Wrong:
+
+```tsx
+<div ref={scrollRef} style={{ overflow: 'auto', height: 800 }}>
+  <tbody style={{ height: rowVirtualizer.getTotalSize() }}>{/* rows */}</tbody>
+</div>
+```
+
+Correct: the absolute rows need a `position: relative` ancestor with the total height set. Without it, rows stack at the top.
+
+### HIGH Forgetting to set up `measureElement` for dynamic sizing
+
+Wrong: rows render but `estimateSize` is wrong and rows overlap or leave gaps.
+
+Correct: attach `ref={(node) => rowVirtualizer.measureElement(node!)}` to each row element so the virtualizer can measure actual size.
+
+### MEDIUM Mixing virtualization with `manualPagination`
+
+You usually don't need both — server pagination already limits the row count. Virtualize when the client holds the full dataset.
+
+## See Also
+
+- `tanstack-table/preact/table-state` — Subscribe for fine-grained re-renders.
+- `tanstack-table/preact/production-readiness` — narrow selectors, stable refs.
+- `tanstack-table/row-expanding` — virtualizing rows with sub-component rows requires variable height + measureElement.