sygnal 5.3.7 → 6.0.0

package/dist/guide/recipes/charts.md

@@ -0,0 +1,177 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Charts (Chart.js, ECharts)
+
+[Chart.js](https://www.chartjs.org/) draws charts on a `<canvas>`. It doesn't know about Sygnal, and doesn't need to: [`defineWidget`](../widgets.md) turns it into a JSX tag. The data lives in your state, the chart is redrawn when it changes, and a click on a bar comes back as an event the intent reads.
+
+## Install
+
+```sh
+npm install chart.js
+```
+
+## The widget
+
+```js live-file=./SalesChart.js
+// SalesChart.js
+import { defineWidget } from 'sygnal'
+import { Chart, BarController, BarElement, CategoryScale, LinearScale, Tooltip, Colors } from 'chart.js'
+
+Chart.register(BarController, BarElement, CategoryScale, LinearScale, Tooltip, Colors)
+
+export const SalesChart = defineWidget({
+  name: 'SalesChart',
+  tag: 'canvas',
+  mount: (el, props, dispatch) => new Chart(el, {
+    type: 'bar',
+    data: { labels: props.labels, datasets: [{ label: props.series, data: props.values }] },
+    options: {
+      maintainAspectRatio: false,
+      onClick: (event, bars) => { if (bars.length) dispatch('bar-select', bars[0].index) },
+    },
+  }),
+  update: (chart, props) => {
+    chart.data.labels = props.labels
+    chart.data.datasets[0].label = props.series
+    chart.data.datasets[0].data = props.values
+    chart.update()
+  },
+  unmount: (chart) => chart.destroy(),
+  events: ['bar-select'],
+})
+```
+
+- The `Colors` plugin gives each dataset a colour from Chart.js's palette. Without it, a dataset with no `backgroundColor` is drawn in a 10% black that is hard to see on a dark page.
+- `mount` creates the chart on the `<canvas>` host and returns it: that is the instance `update` and `unmount` get.
+- `update` runs when the props change. It changes the chart's data in place and calls `chart.update()`, so the chart animates to the new values instead of being rebuilt.
+- `unmount` runs when the chart leaves the page and frees the canvas.
+- A click on a bar calls `dispatch('bar-select', index)`, a bubbling DOM event on the canvas with the bar's index as its `detail`.
+
+## Using it
+
+```jsx live
+// Sales.jsx
+import { SalesChart } from './SalesChart.js'
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr']
+
+export function Sales({ state }) {
+  const picked = state.selected === null ? 'Select a bar' : `${MONTHS[state.selected]}: ${state.values[state.selected]}`
+  return (
+    <section>
+      <div className="chart-box">
+        <SalesChart className="sales" role="img" aria-label="Sales by month"
+          labels={MONTHS} series="Sales" values={state.values} />
+      </div>
+      <p className="picked">{picked}</p>
+      <button className="add-sale">Add a sale in April</button>
+    </section>
+  )
+}
+
+Sales.initialState = { values: [12, 19, 7, 4], selected: null }
+
+Sales.intent = ({ DOM }) => ({
+  SELECT: DOM.select('.sales').events('bar-select').detail(),
+  ADD_SALE: DOM.click('.add-sale'),
+})
+
+Sales.model = {
+  SELECT: (state, index) => ({ ...state, selected: index }),
+  ADD_SALE: (state) => ({ ...state, values: [...state.values.slice(0, 3), state.values[3] + 1] }),
+}
+```
+
+```css live
+.chart-box { position: relative; height: 240px; }
+```
+
+Chart.js sizes the canvas to its parent, so the parent needs a size (and `position: relative`). With `maintainAspectRatio: false` the chart fills that box.
+
+## Testing
+
+`renderComponent`'s mock DOM doesn't draw the chart. `t.widget('.sales')` sends the widget's events and shows the props the view passed it, which is what the component is responsible for:
+
+```jsx
+// Sales.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Sales } from './Sales.jsx'
+
+test('a clicked bar is selected, and a new sale reaches the chart', async () => {
+  const t = renderComponent(Sales)
+  await t.ready()
+  t.widget('.sales').dispatch('bar-select', 1)
+  await t.next((state) => state.selected === 1)
+  expect(t.query('.picked').textContent).toBe('Feb: 19')
+
+  t.simulateEvent('.add-sale', 'click')
+  await t.next((state) => state.values[3] === 5)
+  expect(t.widget('.sales').props.values).toEqual([12, 19, 7, 5])
+  t.dispose()
+})
+```
+
+To test the chart itself (that a click on the second bar selects it), run the component in a real browser with `renderComponent(Sales, { dom: 'real' })`: `t.widget('.sales').instance` is the Chart.js object, and `Chart.getChart(canvas)` is `undefined` after `t.dispose()`. jsdom has no canvas, so Chart.js can't draw there.
+
+## ECharts
+
+[Apache ECharts](https://echarts.apache.org/) works the same way. It draws into a `<div>` (the default host), takes one `option` object for everything, and reports clicks through `chart.on('click')`:
+
+```js
+// SalesEChart.js
+import { defineWidget } from 'sygnal'
+import * as echarts from 'echarts/core'
+import { BarChart } from 'echarts/charts'
+import { GridComponent, TooltipComponent } from 'echarts/components'
+import { CanvasRenderer } from 'echarts/renderers'
+
+echarts.use([BarChart, GridComponent, TooltipComponent, CanvasRenderer])
+
+const option = (props) => ({
+  xAxis: { type: 'category', data: props.labels },
+  yAxis: { type: 'value' },
+  tooltip: {},
+  series: [{ type: 'bar', data: props.values }],
+})
+
+export const SalesEChart = defineWidget({
+  name: 'SalesEChart',
+  mount: (el, props, dispatch) => {
+    const chart = echarts.init(el)
+    chart.setOption(option(props))
+    chart.on('click', (params) => dispatch('bar-select', params.dataIndex))
+    // ECharts measures the element once: redraw at the new size when the host resizes
+    const observer = new ResizeObserver(() => chart.resize())
+    observer.observe(el)
+    return { chart, observer }
+  },
+  update: ({ chart }, props) => chart.setOption(option(props)),
+  unmount: ({ chart, observer }) => {
+    observer.disconnect()
+    chart.dispose()
+  },
+  events: ['bar-select'],
+})
+```
+
+`setOption` merges the new option into the chart, so `update` can pass the whole option every time. Give the host a height in CSS (`.sales { height: 240px; }`): ECharts measures the element when it starts, and only again on `chart.resize()`, which the `ResizeObserver` calls when the host changes size (a resized window, a sidebar that opens). The instance is `{ chart, observer }`, so `unmount` can stop both. (Chart.js watches its canvas's container itself; with `maintainAspectRatio: false` it follows the container's height.)
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included:
+
+| | Adds |
+|---|---|
+| Chart.js bar chart (the registrations above) | 60 KB |
+| ECharts bar chart (the `use` list above) | 180 KB |
+| `defineWidget` (the first widget in an app) | 1.1 KB |
+
+Register only what you draw: `import Chart from 'chart.js/auto'` registers every chart type, scale and plugin: 75 KB instead of 60.
+
+## Pitfalls
+
+- **Register what the chart uses.** Chart.js and ECharts are tree-shaken: a chart type, scale or plugin you don't register isn't there (`"bar" is not a registered controller`).
+- **Pass new arrays.** `update` runs when a prop is a different value. A reducer that changes `state.values` in place passes the same array, and the chart doesn't change. The usual immutable update (`[...values]`, `map`) is enough.
+- **A canvas has no text.** Give the host `role="img"` and an `aria-label`, and show the numbers somewhere a screen reader can reach (a table, a summary line), as `picked` does here.
+- **Clicks on bars are mouse-only.** A keyboard user can't click a bar. Offer the same choice with buttons or a `<select>` that dispatch the same action.
+- **Animations.** `chart.update()` animates and `chart.update('none')` doesn't. To respect `prefers-reduced-motion`, set `options.animation: false` in `mount` when `matchMedia('(prefers-reduced-motion: reduce)').matches`.

package/dist/guide/recipes/code-editor.md

@@ -0,0 +1,135 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Code Editor (CodeMirror)
+
+[CodeMirror 6](https://codemirror.net/) is a code editor made of an `EditorView` and extensions. [`defineWidget`](../widgets.md) turns it into a JSX tag: the code is a string in your state, each change comes back as an event, and a `focus` command focuses the editor from the model.
+
+## Install
+
+```sh
+npm install codemirror @codemirror/state @codemirror/lang-javascript
+```
+
+## The widget
+
+```js live-file=./CodeEditor.js
+// CodeEditor.js
+import { defineWidget } from 'sygnal'
+import { EditorView, basicSetup } from 'codemirror'
+import { Compartment } from '@codemirror/state'
+import { javascript } from '@codemirror/lang-javascript'
+
+// the label can change (another language): it lives in a compartment that update() reconfigures
+const labelling = new Compartment()
+const label = (props) => EditorView.contentAttributes.of(props.label == null ? {} : { 'aria-label': props.label })
+
+export const CodeEditor = defineWidget({
+  name: 'CodeEditor',
+  mount: (el, props, dispatch) => new EditorView({
+    parent: el,
+    doc: props.code,
+    extensions: [
+      basicSetup,
+      javascript(),
+      labelling.of(label(props)),
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) dispatch('edit', update.state.doc.toString())
+      }),
+    ],
+  }),
+  update: (view, props) => {
+    const code = view.state.doc.toString()
+    if (props.code !== code) view.dispatch({ changes: { from: 0, to: code.length, insert: props.code } })
+    // getAttribute gives null for no label
+    if ((props.label ?? null) !== view.contentDOM.getAttribute('aria-label')) view.dispatch({ effects: labelling.reconfigure(label(props)) })
+  },
+  unmount: (view) => view.destroy(),
+  events: ['edit'],
+  commands: { focus: (view) => view.focus() },
+})
+```
+
+- `mount` creates the view inside the host `<div>` (`parent: el`). `basicSetup` brings line numbers, history, bracket matching, search and autocompletion.
+- The update listener sends the whole document as the `edit` event after each change.
+- `update` gets the code from state. When the user typed it, it equals the editor's document and nothing happens; otherwise one transaction replaces the document.
+- `view.dispatch` is CodeMirror's own method for applying a transaction. It has nothing to do with the widget's `dispatch`, the third parameter of `mount`, which sends events to the intent.
+- The `focus` command focuses the editable area. A command the widget declares wins over the host element's method of the same name, so `{ focus: '.code' }` runs this one, not the `<div>`'s.
+
+## Using it
+
+```jsx live
+// Snippet.jsx
+import { CodeEditor } from './CodeEditor.js'
+
+const START = 'const answer = 42\n'
+
+export function Snippet({ state }) {
+  return (
+    <section>
+      <CodeEditor className="code" label="Snippet" code={state.code} />
+      <p className="lines">{state.code.split('\n').length} lines</p>
+      <button type="button" className="edit-code">Edit</button>
+      <button type="button" className="reset">Reset</button>
+    </section>
+  )
+}
+
+Snippet.initialState = { code: START }
+
+Snippet.intent = ({ DOM }) => ({
+  EDIT: DOM.select('.code').events('edit').detail(),
+  FOCUS_CODE: DOM.click('.edit-code'),
+  RESET: DOM.click('.reset'),
+})
+
+Snippet.model = {
+  EDIT: (state, code) => ({ ...state, code }),
+  FOCUS_CODE: { ELEMENT: { focus: '.code' } },
+  RESET: (state) => ({ ...state, code: START }),
+}
+```
+
+```css live
+.code .cm-editor { background: white; color: black; border: 1px solid #8888; }
+```
+
+CodeMirror's default theme is a light one: dark syntax colours and a light gutter, on whatever background the page has. On a page that can be dark, give the editor a light background, as here, or add a dark theme extension (`@codemirror/theme-one-dark`) and switch it with a compartment.
+
+## Testing
+
+```jsx
+// Snippet.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Snippet } from './Snippet.jsx'
+
+test('edits reach the state, Reset puts the start code back', async () => {
+  const t = renderComponent(Snippet)
+  await t.ready()
+  t.widget('.code').dispatch('edit', 'const answer = 42\nconsole.log(answer)\n')
+  await t.next((state) => state.code.includes('console.log'))
+  expect(t.query('.lines').textContent).toBe('3 lines')
+
+  t.simulateEvent('.reset', 'click')
+  await t.next((state) => state.code === 'const answer = 42\n')
+  expect(t.widget('.code').props.code).toBe('const answer = 42\n')
+
+  t.simulateEvent('.edit-code', 'click')
+  await t.settle()
+  expect(t.commands()).toEqual([{ focus: '.code' }])
+  t.dispose()
+})
+```
+
+CodeMirror measures text positions with layout APIs jsdom doesn't have, so test typing in a real browser: with `renderComponent(Snippet, { dom: 'real' })` under Playwright, click **Edit**, type, and `t.waitForState((state) => ...)` sees the new code; `t.widget('.code').instance` is the `EditorView`.
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included: `basicSetup` with the JavaScript language adds **177 KB**. For a smaller editor, replace `basicSetup` with `minimalSetup` (history, default keymap, special characters) and the extensions you want from `@codemirror/view`, `@codemirror/commands` and the language packages. `defineWidget` adds 1.1 KB for the first widget in an app.
+
+## Pitfalls
+
+- **Keep the comparison in `update`.** Replacing the document on every render would reset the cursor and the undo history while the user types.
+- **A reset is also an edit.** The transaction `update` dispatches changes the document, so the listener sends it back as an `edit` with the same code. That costs one extra action and changes nothing. To skip it, add an annotation to the transaction (`annotations: Transaction.remote.of(true)` from `@codemirror/state`) and ignore updates that carry it.
+- **Change configuration with compartments.** `mount` builds the extensions once. The label is in a `Compartment` that `update` reconfigures when the `label` prop changes (a translated app switching language); do the same to switch the language mode, the theme or `readOnly` from props (`view.dispatch({ effects: compartment.reconfigure(...) })`). `@codemirror/state` is installed with `codemirror`; list it yourself so there is one copy (two copies break compartments).
+- **Label the editable element.** The host `<div>` is not what receives the keyboard. `EditorView.contentAttributes` puts `aria-label` on CodeMirror's `.cm-content`, the element a screen reader announces.
+- **Tab.** CodeMirror doesn't trap Tab by default, so keyboard users can leave the editor. Adding `indentWithTab` changes that; if you do, tell users that Escape then Tab leaves the editor.

package/dist/guide/recipes/data-grid.md

@@ -0,0 +1,155 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Data Grid (AG Grid)
+
+[AG Grid](https://www.ag-grid.com/) is a full spreadsheet-like grid: virtual scrolling for large data sets, column resizing and reordering, in-cell editing, keyboard navigation, CSV export. It renders everything itself, so [`defineWidget`](../widgets.md) turns it into a JSX tag. The rows stay in your state: the grid reports edits and selection as events, and the model decides what changes.
+
+This recipe uses the free Community edition (`ag-grid-community`). For a table you style yourself, with a few hundred rows, the lighter [TanStack Table recipe](./data-table.md) is enough.
+
+## Install
+
+```sh
+npm install ag-grid-community
+```
+
+## The widget
+
+```js live-file=./Grid.js
+// Grid.js
+import { defineWidget } from 'sygnal'
+import {
+  createGrid, ModuleRegistry, ClientSideRowModelModule, RowSelectionModule,
+  TextEditorModule, NumberEditorModule, CsvExportModule,
+} from 'ag-grid-community'
+
+ModuleRegistry.registerModules([
+  ClientSideRowModelModule, RowSelectionModule, TextEditorModule, NumberEditorModule, CsvExportModule,
+])
+
+export const Grid = defineWidget({
+  name: 'Grid',
+  mount: (el, props, dispatch) => createGrid(el, {
+    columnDefs: props.columns,
+    rowData: props.rows,
+    getRowId: (params) => params.data.id,
+    // edits become events; the grid shows them once the state has them
+    readOnlyEdit: true,
+    onCellEditRequest: (event) =>
+      dispatch('cell-edit', { id: event.data.id, field: event.colDef.field, value: event.newValue }),
+    rowSelection: { mode: 'singleRow', checkboxes: false, enableClickSelection: true },
+    onSelectionChanged: (event) => dispatch('row-select', event.api.getSelectedRows()[0]?.id ?? null),
+  }),
+  update: (grid, props) => {
+    grid.setGridOption('columnDefs', props.columns)
+    grid.setGridOption('rowData', props.rows)
+  },
+  unmount: (grid) => grid.destroy(),
+  events: ['cell-edit', 'row-select'],
+  commands: {
+    exportCsv: (grid, { fileName }) => grid.exportDataAsCsv({ fileName }),
+  },
+})
+```
+
+- `readOnlyEdit: true` keeps the grid from writing an edit into the row object. It fires `onCellEditRequest` instead, the widget sends that as a `cell-edit` event, and the edit shows up in the grid when the new rows come back through `update`.
+- `getRowId` gives each row its identity, so a new `rowData` array updates only the rows that changed, and keeps the selection, the scroll position and the focused cell.
+- The `exportCsv` command gets the options of the element command (`fileName`).
+
+## Using it
+
+```jsx live
+// Stock.jsx
+import { Grid } from './Grid.js'
+
+const COLUMNS = [
+  { field: 'name', headerName: 'Item', editable: true, flex: 2 },
+  { field: 'count', headerName: 'In stock', editable: true, cellDataType: 'number', flex: 1 },
+]
+
+export function Stock({ state }) {
+  const selected = state.items.find((item) => item.id === state.selected)
+  return (
+    <section>
+      <Grid className="grid" columns={COLUMNS} rows={state.items} />
+      <p className="selected">{selected ? `${selected.name}: ${selected.count} in stock` : 'No item selected'}</p>
+      <button className="restock" disabled={!selected}>Restock 10</button>
+      <button className="export">Export CSV</button>
+    </section>
+  )
+}
+
+Stock.initialState = {
+  items: [
+    { id: 'a1', name: 'Bolts', count: 120 },
+    { id: 'a2', name: 'Nuts', count: 80 },
+    { id: 'a3', name: 'Washers', count: 0 },
+  ],
+  selected: null,
+}
+
+Stock.intent = ({ DOM }) => ({
+  EDIT: DOM.select('.grid').events('cell-edit').detail(),
+  SELECT: DOM.select('.grid').events('row-select').detail(),
+  RESTOCK: DOM.click('.restock'),
+  EXPORT: DOM.click('.export'),
+})
+
+const change = (items, id, values) => items.map((item) => (item.id === id ? { ...item, ...values } : item))
+
+Stock.model = {
+  EDIT: (state, { id, field, value }) => ({ ...state, items: change(state.items, id, { [field]: value }) }),
+  SELECT: (state, id) => ({ ...state, selected: id }),
+  RESTOCK: (state) => {
+    const item = state.items.find((it) => it.id === state.selected)
+    return { ...state, items: change(state.items, item.id, { count: item.count + 10 }) }
+  },
+  EXPORT: { ELEMENT: { exportCsv: '.grid', fileName: 'stock.csv' } },
+}
+```
+
+```css live
+.grid { height: 400px; }
+```
+
+`COLUMNS` is a module constant, so the `columns` prop keeps its identity and only a change to `items` runs `update`. The grid draws its own theme (Quartz by default); it needs a height to fill.
+
+## Testing
+
+```jsx
+// Stock.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Stock } from './Stock.jsx'
+
+test('edits and restocking change the rows the grid gets', async () => {
+  const t = renderComponent(Stock)
+  await t.ready()
+  t.widget('.grid').dispatch('cell-edit', { id: 'a2', field: 'count', value: 75 })
+  await t.next((state) => state.items[1].count === 75)
+
+  t.widget('.grid').dispatch('row-select', 'a3')
+  await t.next((state) => state.selected === 'a3')
+  t.simulateEvent('.restock', 'click')
+  await t.next((state) => state.items[2].count === 10)
+  expect(t.query('.selected').textContent).toBe('Washers: 10 in stock')
+  expect(t.widget('.grid').props.rows.map((item) => item.count)).toEqual([120, 75, 10])
+
+  t.simulateEvent('.export', 'click')
+  await t.settle()
+  expect(t.commands()).toEqual([{ exportCsv: '.grid', fileName: 'stock.csv' }])
+  t.dispose()
+})
+```
+
+In a real browser (`renderComponent(Stock, { dom: 'real' })` under Playwright), double-click a cell (`.grid [row-id="a2"] [col-id="count"]`), type and press Enter: the state gets the new count, and the cell shows it once the new rows reach the grid. `t.widget('.grid').instance` is the grid API (`getSelectedRows()`, `isDestroyed()`).
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included: **240 KB** with the five modules above. `AllCommunityModule` registers every Community feature and makes it 333 KB. `defineWidget` adds 1.1 KB for the first widget in an app.
+
+## Pitfalls
+
+- **Keep `readOnlyEdit: true`.** Without it, AG Grid writes each edit into the row object it was given, which is the object in your state: the state changes without an action, and the next render can't tell anything changed.
+- **Give rows an id.** Without `getRowId`, each new `rowData` array replaces every row: the selection and the focused cell are lost after each edit.
+- **Register the modules you use.** AG Grid 33 and later are modular. An option whose module isn't registered doesn't work, and the grid logs an error with a link; register `ValidationModule` in development to get messages that name the missing module.
+- **Don't recreate `columns` in the view.** A new array on every render runs `update` every time and makes the grid rebuild its columns. Keep column definitions in a constant, or in state if the user can change them.
+- **Keyboard and screen readers.** The grid has its own keyboard navigation and ARIA grid roles: don't wrap it in elements that capture arrow keys, and label the page section it sits in.

package/dist/guide/recipes/data-table.md

@@ -0,0 +1,196 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Data Table (TanStack Table)
+
+[TanStack Table](https://tanstack.com/table) is headless: it computes which rows to show (sorted, filtered, paged) and renders nothing. That fits Sygnal without a widget. Keep the table's settings (sorting, search, page) in your state, build the table from that state in the view, and render its rows with JSX. Sygnal still renders every element, so the table works in the mock DOM, on the server, and with sygnal-check.
+
+This recipe uses **v9** (`@tanstack/table-core` 9.x), whose API differs from v8: `constructTable` and `tableFeatures` replace `createTable` and the `get*RowModel` options.
+
+## Install
+
+```sh
+npm install @tanstack/table-core
+```
+
+## The table
+
+```js live-file=./peopleTable.js
+// peopleTable.js
+import {
+  constructTable, createColumnHelper, tableFeatures,
+  rowSortingFeature, createSortedRowModel, sortFn_alphanumeric, sortFn_basic,
+  columnFilteringFeature, globalFilteringFeature, createFilteredRowModel, filterFn_includesString,
+  rowPaginationFeature, createPaginatedRowModel,
+} from '@tanstack/table-core'
+import { storeReactivityBindings } from '@tanstack/table-core/store-reactivity-bindings'
+
+const features = tableFeatures({
+  coreReactivityFeature: storeReactivityBindings(),
+  rowSortingFeature,
+  sortedRowModel: createSortedRowModel(),
+  sortFns: { alphanumeric: sortFn_alphanumeric, basic: sortFn_basic },
+  columnFilteringFeature,
+  globalFilteringFeature,
+  filteredRowModel: createFilteredRowModel(),
+  filterFns: { includesString: filterFn_includesString },
+  rowPaginationFeature,
+  paginatedRowModel: createPaginatedRowModel(),
+})
+
+const column = createColumnHelper()
+const columns = column.columns([
+  column.accessor('name', { header: 'Name', sortFn: 'alphanumeric' }),
+  column.accessor('team', { header: 'Team', sortFn: 'alphanumeric' }),
+  column.accessor('points', { header: 'Points', sortFn: 'basic' }),
+])
+
+export const PAGE_SIZE = 3
+
+// A pure function of the component's state: the table never holds state of its own
+export const peopleTable = (state) => constructTable({
+  features,
+  columns,
+  data: state.people,
+  getRowId: (person) => person.id,
+  globalFilterFn: 'includesString',
+  state: {
+    sorting: state.sorting,
+    globalFilter: state.search,
+    pagination: { pageIndex: state.page, pageSize: PAGE_SIZE },
+  },
+})
+
+// click a column: ascending, then descending, then unsorted
+export const nextSorting = (sorting, id) =>
+  sorting[0]?.id !== id ? [{ id, desc: false }] : sorting[0].desc ? [] : [{ id, desc: true }]
+```
+
+- `features`, `columns` and the sort and filter functions are created once, at module level. v9 registers each feature explicitly; an API you didn't register (say `getCanNextPage` without `rowPaginationFeature`) doesn't exist.
+- `peopleTable(state)` passes every setting through the `state` option. The table owns no state and nobody calls its setters (`setSorting`, `nextPage`): actions change Sygnal's state, and the next render builds the table from it.
+
+## Using it
+
+```jsx live
+// People.jsx
+import { peopleTable, nextSorting } from './peopleTable.js'
+
+const ARIA_SORT = { asc: 'ascending', desc: 'descending' }
+
+export function People({ state }) {
+  const table = peopleTable(state)
+  return (
+    <section>
+      <label>Search <input className="search" value={state.search} /></label>
+      <table>
+        <thead>
+          {table.getHeaderGroups().map((group) => (
+            <tr key={group.id}>
+              {group.headers.map((header) => (
+                <th key={header.id} aria-sort={ARIA_SORT[header.column.getIsSorted()] || 'none'}>
+                  <button className="sort" data={{ column: header.id }}>{header.column.columnDef.header}</button>
+                </th>
+              ))}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {table.getRowModel().rows.map((row) => (
+            <tr key={row.id}>
+              {row.getAllCells().map((cell) => <td key={cell.id}>{cell.getValue()}</td>)}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      <button className="prev" disabled={!table.getCanPreviousPage()}>Previous</button>
+      <span className="page">Page {state.page + 1} of {Math.max(table.getPageCount(), 1)}</span>
+      <button className="next" disabled={!table.getCanNextPage()}>Next</button>
+    </section>
+  )
+}
+
+People.initialState = {
+  people: [
+    { id: 'p1', name: 'Ada', team: 'Engines', points: 36 },
+    { id: 'p2', name: 'Grace', team: 'Compilers', points: 45 },
+    { id: 'p3', name: 'Alan', team: 'Engines', points: 41 },
+    { id: 'p4', name: 'Edsger', team: 'Compilers', points: 12 },
+    { id: 'p5', name: 'Barbara', team: 'Languages', points: 28 },
+  ],
+  sorting: [],
+  search: '',
+  page: 0,
+}
+
+People.intent = ({ DOM }) => ({
+  SEARCH: DOM.input('.search').value(),
+  SORT: DOM.click('.sort').data('column'),
+  PREV: DOM.click('.prev'),
+  NEXT: DOM.click('.next'),
+})
+
+People.model = {
+  SEARCH: (state, search) => ({ ...state, search, page: 0 }),
+  SORT: (state, id) => ({ ...state, sorting: nextSorting(state.sorting, id), page: 0 }),
+  PREV: (state) => ({ ...state, page: state.page - 1 }),
+  NEXT: (state) => ({ ...state, page: state.page + 1 }),
+}
+```
+
+The column headers are buttons inside the `<th>`, so they work with the keyboard, and `aria-sort` tells screen readers which column is sorted and how.
+
+## Testing
+
+Everything is plain markup, so the mock DOM shows the result directly:
+
+```jsx
+// People.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { People } from './People.jsx'
+
+const names = (t) => t.queryAll('tbody tr').map((row) => row.querySelector('td').textContent)
+
+test('sorts, searches and pages', async () => {
+  const t = renderComponent(People)
+  await t.ready()
+  expect(names(t)).toEqual(['Ada', 'Grace', 'Alan'])
+  expect(t.query('.page').textContent).toBe('Page 1 of 2')
+
+  t.simulateEvent('.sort[data-column="points"]', 'click')
+  t.simulateEvent('.sort[data-column="points"]', 'click')
+  await t.next((state) => state.sorting[0]?.desc === true)
+  expect(names(t)).toEqual(['Grace', 'Alan', 'Ada'])
+  expect(t.queryAll('th')[2].getAttribute('aria-sort')).toBe('descending')
+
+  t.simulateEvent('.next', 'click')
+  await t.next((state) => state.page === 1)
+  expect(names(t)).toEqual(['Barbara', 'Edsger'])
+  expect(t.query('.next').disabled).toBe(true)
+
+  t.simulateEvent('.search', 'input', { value: 'compilers' })
+  await t.next((state) => state.search === 'compilers')
+  expect(names(t)).toEqual(['Grace', 'Edsger'])
+  expect(t.query('.page').textContent).toBe('Page 1 of 1')
+  t.dispose()
+})
+```
+
+`peopleTable` is a plain function too: a test can call it with a state object and check `getRowModel().rows` without rendering anything.
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included: **16 KB** for `table-core` with sorting, filtering and pagination. Each feature you register adds to it; `stockFeatures` registers all of them.
+
+## Performance
+
+The view builds a new table on every render. In a browser that took about 1.5–3 ms for 1,000 rows and 9–23 ms for 10,000 rows (sorted, filtered and paged, depending on the engine). That is fine up to a few thousand rows. Beyond that:
+
+- page or filter on the server and pass only the visible rows as `data` (`manualPagination`, `manualSorting`, `manualFiltering`);
+- or render all rows with a [`VirtualCollection`](../virtual-collections.md) and sort and filter the array in the model.
+
+## Pitfalls
+
+- **Register a reactivity binding.** v9's `constructTable` needs `coreReactivityFeature` in `features`. Without it, it throws `Cannot read properties of undefined (reading 'wrapExternalAtoms')`. `storeReactivityBindings()` is the framework-neutral one; the table's own atoms aren't used here, because the state comes from Sygnal.
+- **Create features and columns once.** Build them at module level, not in the view: TanStack expects them to keep their identity, and creating them per render also costs time.
+- **One owner per setting.** Pass each setting through `state` and change it in the model. Calling the table's own setters (`table.setSorting`, `table.nextPage`) changes nothing that lasts: the next render builds a new table from Sygnal's state.
+- **Reset the page.** A new search or sort can leave the current page past the end. The reducers here go back to page 0, as most tables do.
+- **Call methods on their objects.** `row.getValue('name')` works; `const { getValue } = row` loses `this`.