sygnal 5.4.0 → 6.1.0

package/dist/guide/recipes/ai-support-inbox.md

@@ -0,0 +1,190 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Support Inbox
+
+A support inbox where every ticket is triaged as it arrives: its topic picks the team, its urgency sorts the list. A [decision model](../ai-decisions.md) answers in a few hundred milliseconds for each ticket. The few it is unsure about go to a [chat model](../ai-chat.md), which answers with structured output: a topic and the reason.
+
+The pieces:
+
+- **Each ticket is a Collection item with its own resource.** The decision follows the ticket's text, and its result is written into the ticket, so the inbox can sort by it.
+- **The resource's `ok` action checks the confidence**, and only an unsure ticket sends a chat request.
+- **The chat model's answer is typed**: `output` is a schema, and `ok` gets the validated value.
+
+## Install
+
+Nothing beyond Sygnal and a schema library for the structured output:
+
+```sh
+npm install sygnal zod
+```
+
+`main.js` registers both drivers: the fetch driver for decisions, the chat driver for the escalations.
+
+```js
+import { run, makeFetchDriver } from 'sygnal'
+import { makeChatDriver, uiMessageStream } from 'sygnal/ai'
+import Inbox from './Inbox.jsx'
+
+run(Inbox, {
+  HTTP: makeFetchDriver(),
+  LLM: makeChatDriver({ transport: uiMessageStream('/api/chat') }),
+})
+```
+
+`decide()` posts to `/api/decide` and the chat driver to `/api/chat`: your server's routes, which hold the keys ([decisions](../ai-decisions.md#keys-stay-on-the-server), [chat](../ai-chat.md#shipping-it)). In development, point them at a local Ollama instead.
+
+## The inbox
+
+In this demo, the demo server answers for both models. The third ticket is ambiguous, so its escalation runs as soon as the demo shows.
+
+```js live-server
+import { encodeOpenResponses } from 'sygnal/ai'
+
+const has = (text, words) => words.some((w) => text.toLowerCase().includes(w))
+
+export default {
+  'POST /v1/systemone': ({ json }) => {
+    const t = String(json.state)
+    const topic = has(t, ['charge', 'refund']) ? 'billing' : has(t, ['crash', 'error']) ? 'bug' : 'account'
+    const sure = has(t, ['charge', 'crash', 'password']) ? 0.93 : 0.38
+    const others = ['billing', 'bug', 'account'].filter((k) => k !== topic)
+    return {
+      delayMs: 500,
+      json: {
+        model: json.model,
+        answers: {
+          topic: { type: 'choice', choice: topic, confidence: sure, probabilities: { [topic]: sure, [others[0]]: (1 - sure) / 2, [others[1]]: (1 - sure) / 2 } },
+          urgent: { type: 'noul', noul: has(t, ['twice', 'down', 'today']) ? 0.92 : 0.1 },
+        },
+      },
+    }
+  },
+  'POST /v1/responses': () => ({
+    sse: encodeOpenResponses(['{"topic":"billing",', '"reason":"They ask', ' for an invoice', ' copy, a billing', ' document."}']),
+    delayMs: 300,
+    chunkMs: 60,
+  }),
+}
+```
+
+```jsx live live-height=280
+import { z } from 'zod'
+import { ABORT, Collection } from 'sygnal'
+import { decide, choice, noul } from 'sygnal/ai'
+
+const TOPICS = { billing: 'Payments, invoices, plans, refunds', bug: 'Something in the product is broken', account: 'Login, access or profile' }
+const TEAMS = { billing: 'Billing team', bug: 'Engineering', account: 'Account support' }
+
+const questions = {
+  topic: choice('What is this ticket about?', TOPICS),
+  urgent: noul('Does the customer need this handled today?', {
+    true: 'Blocked, losing money, or a deadline',
+    false: 'A question or a minor issue',
+  }),
+}
+
+const SecondOpinion = z.object({
+  topic: z.enum(['billing', 'bug', 'account']),
+  reason: z.string().describe('One short sentence'),
+})
+
+const SURE = 0.6
+
+// the topic to act on: the chat model's when it was asked, else the decision's
+const topicOf = (ticket) => ticket.opinion?.topic ?? ticket.triage?.data?.answers.topic.choice
+const urgency = (ticket) => ticket.triage?.data?.answers.urgent.noul ?? 0
+
+function TicketRow({ state }) {
+  const { status, data } = state.triage
+  const topic = topicOf(state)
+  return (
+    <li className="ticket">
+      <p><b>{state.from}</b>: {state.text}</p>
+      <p className="labels" aria-live="polite">
+        {status === 'loading' && 'Triaging…'}
+        {status === 'error' && 'Not triaged: a person will look at it.'}
+        {state.asking && 'Unsure, asking the chat model…'}
+        {topic && !state.asking && <>→ {TEAMS[topic]}</>}
+        {data && data.answers.urgent.noul > 0.5 && <strong> urgent</strong>}
+      </p>
+      {state.opinion && <p className="reason"><i>{state.opinion.reason}</i></p>}
+    </li>
+  )
+}
+
+TicketRow.resources = {
+  triage: (state) => decide({ url: '/v1/systemone', model: 'nimble', state: state.text, questions, ok: 'TRIAGED' }),
+}
+
+TicketRow.model = {
+  TRIAGED: {
+    STATE: (state, { answers }) => (answers.topic.confidence < SURE ? { ...state, asking: true } : ABORT),
+    LLM: (state, { answers }) => (answers.topic.confidence < SURE
+      ? {
+        instructions: 'Classify the support ticket and give one short reason.',
+        messages: [{ role: 'user', content: state.text }],
+        output: SecondOpinion,
+        ok: 'CLASSIFIED',
+        error: 'NOT_CLASSIFIED',
+      }
+      : ABORT),
+  },
+  CLASSIFIED: (state, { value }) => ({ ...state, asking: false, opinion: value }),
+  NOT_CLASSIFIED: (state) => ({ ...state, asking: false }),
+}
+
+function Inbox({ state }) {
+  const urgent = state.tickets.filter((t) => urgency(t) > 0.5).length
+  return (
+    <section className="inbox">
+      <h3>Inbox ({urgent} urgent)</h3>
+      <ul>
+        <Collection of={TicketRow} from="tickets" sort={(a, b) => urgency(b) - urgency(a)} />
+      </ul>
+    </section>
+  )
+}
+
+Inbox.initialState = {
+  tickets: [
+    { id: 1, from: 'Ana', text: 'The app crashes when I export a report' },
+    { id: 2, from: 'Ben', text: 'I was charged twice, please fix it today' },
+    { id: 3, from: 'Cleo', text: 'Where can I get a copy of last month\'s invoice?' },
+  ],
+}
+```
+
+- **The resource lives on the item.** Each `TicketRow` has its own `triage` resource, written into its ticket: `state.tickets[i].triage` in the inbox. That is how `Inbox` counts the urgent ones and sorts by urgency, with no messages between the two. The items keep their instances as they move.
+- **One request per ticket.** A decision model answers each in a few hundred milliseconds, and questions are answered in parallel. For hundreds of tickets, triage on the server when they arrive and store the answers instead.
+- **The escalation is typed.** The chat model's answer must match `SecondOpinion`. An answer that doesn't arrives as `NOT_CLASSIFIED`, and the ticket shows the decision's topic.
+- **Unsure is information.** Show it: a ticket the models disagree about, or both are unsure about, is one for a person.
+
+## Testing
+
+`answers()` builds a decision reply typed from the questions; the LLM fake answers the escalation. Export `TicketRow` and `questions` from the module to test a row on its own:
+
+```js
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { answers } from 'sygnal/ai'
+import { TicketRow, questions } from './Inbox.jsx'
+
+it('routes a confident ticket and asks the chat model about an unsure one', async () => {
+  const sure = renderComponent(TicketRow, { initialState: { id: 1, from: 'Ana', text: 'It crashes' } })
+  await sure.respond('HTTP', answers(questions, { topic: 'bug' }), 'triage')
+  expect(sure.html()).toContain('Engineering')
+  expect(sure.requests('LLM')).toEqual([])
+  sure.dispose()
+
+  const unsure = renderComponent(TicketRow, { initialState: { id: 3, from: 'Cleo', text: 'Invoice copy?' } })
+  await unsure.respond('HTTP', answers(questions, { topic: { choice: 'account', confidence: 0.4 } }), 'triage')
+  await unsure.respond('LLM', { topic: 'billing', reason: 'An invoice is a billing document.' })
+  expect(unsure.html()).toContain('Billing team')
+  unsure.dispose()
+})
+```
+
+## Pitfalls
+
+- **Don't put the decision on the inbox.** One resource on the list would send every ticket again when one changes. A resource per item sends one request per ticket, and only again when that ticket's text changes.
+- **Keep the escalation rare.** Tune `SURE` on real tickets: if most go to the chat model, the questions or their option descriptions need work.
+- **A chat model's topic can be anything** without `output`. With a `z.enum`, it can only be one of yours.

package/dist/guide/recipes/carousel.md

@@ -0,0 +1,155 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Carousel (Embla)
+
+[Embla Carousel](https://www.embla-carousel.com/) handles the hard parts of a carousel: dragging and swiping, snapping, momentum. It renders no buttons and no styles of its own. [`defineWidget`](../widgets.md) turns it into a JSX tag; the buttons are ordinary Sygnal markup that send the carousel [element commands](../element-commands.md), and the slide Embla settles on comes back as state.
+
+## Install
+
+```sh
+npm install embla-carousel
+```
+
+## The widget
+
+```js live-file=./Carousel.js
+// Carousel.js
+import { defineWidget } from 'sygnal'
+import EmblaCarousel from 'embla-carousel'
+
+// Embla moves a track inside the viewport (the host): the widget builds the track from the props
+function fill(el, photos) {
+  const track = document.createElement('div')
+  track.className = 'slides'
+  photos.forEach((photo, i) => {
+    const slide = document.createElement('div')
+    slide.className = 'slide'
+    slide.setAttribute('role', 'group')
+    slide.setAttribute('aria-roledescription', 'slide')
+    slide.setAttribute('aria-label', `${i + 1} of ${photos.length}`)
+    slide.append(Object.assign(document.createElement('img'), { src: photo.src, alt: photo.alt }))
+    track.append(slide)
+  })
+  el.replaceChildren(track)
+}
+
+export const Carousel = defineWidget({
+  name: 'Carousel',
+  mount: (el, props, dispatch) => {
+    fill(el, props.photos)
+    const embla = EmblaCarousel(el, { loop: false })
+    // reInit (new photos) can move the selection without a select event: report both
+    const report = () => dispatch('slide', embla.selectedScrollSnap())
+    embla.on('select', report).on('reInit', report)
+    return embla
+  },
+  update: (embla, props, el) => {
+    fill(el, props.photos)
+    embla.reInit()
+  },
+  unmount: (embla) => embla.destroy(),
+  events: ['slide'],
+  commands: {
+    prev: (embla) => embla.scrollPrev(),
+    next: (embla) => embla.scrollNext(),
+    goTo: (embla, { index }) => embla.scrollTo(index),
+  },
+})
+```
+
+Embla expects a viewport element with one child, the track, whose children are the slides. The host `<div>` is the viewport, and the widget builds the track itself, because Sygnal never renders inside a widget's host. `update` rebuilds it when the photos change and `reInit()` makes Embla measure the new slides; the instance stays the same.
+
+## Using it
+
+```jsx live
+// Gallery.jsx
+import { Carousel } from './Carousel.js'
+
+export function Gallery({ state }) {
+  const last = state.photos.length - 1
+  return (
+    <section aria-roledescription="carousel" aria-label="Photos">
+      <Carousel className="photos" photos={state.photos} />
+      <button className="prev" aria-label="Previous photo" aria-disabled={state.index === 0}>‹</button>
+      <button className="next" aria-label="Next photo" aria-disabled={state.index === last}>›</button>
+      {state.photos.map((photo, i) => (
+        <button className="dot" data={{ index: i }} aria-label={`Show photo ${i + 1}`}
+          aria-current={i === state.index ? 'true' : undefined} />
+      ))}
+      <p className="where" aria-live="polite">Photo {state.index + 1} of {state.photos.length}</p>
+    </section>
+  )
+}
+
+Gallery.initialState = {
+  photos: [
+    { src: '/photos/harbour.jpg', alt: 'Boats in the harbour at dawn' },
+    { src: '/photos/market.jpg', alt: 'The fish market' },
+    { src: '/photos/cliffs.jpg', alt: 'Cliffs north of the town' },
+  ],
+  index: 0,
+}
+
+Gallery.intent = ({ DOM }) => ({
+  SLIDE: DOM.select('.photos').events('slide').detail(),
+  PREV: DOM.click('.prev'),
+  NEXT: DOM.click('.next'),
+  GO_TO: DOM.click('.dot').data('index', Number),
+})
+
+Gallery.model = {
+  SLIDE: (state, index) => ({ ...state, index }),
+  PREV: { ELEMENT: { prev: '.photos' } },
+  NEXT: { ELEMENT: { next: '.photos' } },
+  GO_TO: { ELEMENT: (state, index) => ({ goTo: '.photos', index }) },
+}
+```
+
+```css live
+.photos { overflow: hidden; }
+.photos .slides { display: flex; }
+.photos .slide { flex: 0 0 100%; min-width: 0; }
+.photos img { display: block; width: 100%; height: auto; }
+```
+
+The buttons don't change `index` themselves. They ask Embla to scroll, and `index` follows from the `slide` event, the same way it does after a swipe: Embla decides where the carousel stops, and the state always says where it is. The widget also reports the slide after `reInit()`: when the photos shrink below the current one, Embla moves to the last slide without a `select` event.
+
+At the ends, Previous and Next are marked `aria-disabled` rather than `disabled`: a `disabled` button loses focus as it is pressed (keyboard users land on the page body), while an `aria-disabled` one keeps it, is announced as unavailable, and a press does nothing (Embla doesn't scroll past the ends). Style it with `[aria-disabled="true"]`.
+
+## Testing
+
+```jsx
+// Gallery.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Gallery } from './Gallery.jsx'
+
+test('the buttons send commands, and the shown slide comes back as state', async () => {
+  const t = renderComponent(Gallery)
+  await t.ready()
+  t.simulateEvent('.next', 'click')
+  t.simulateEvent('.dot[data-index="2"]', 'click')
+  await t.settle()
+  expect(t.commands()).toEqual([{ next: '.photos' }, { goTo: '.photos', index: 2 }])
+
+  t.widget('.photos').dispatch('slide', 2)
+  await t.next((state) => state.index === 2)
+  expect(t.query('.where').textContent).toBe('Photo 3 of 3')
+  expect(t.query('.next').getAttribute('aria-disabled')).toBe('true')
+  expect(t.query('.prev').getAttribute('aria-disabled')).toBe('false')
+  t.dispose()
+})
+```
+
+Dragging needs layout, so test it in a real browser: with `renderComponent(Gallery, { dom: 'real' })` under Playwright, drag across `.photos` and `t.waitForState((state) => state.index === 1)`; `t.widget('.photos').instance` is the Embla API (`selectedScrollSnap()`, `slideNodes()`).
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included: **9 KB** for Embla and this recipe. `defineWidget` adds 1.1 KB for the first widget in an app.
+
+## Pitfalls
+
+- **Build the slides in the widget.** Children passed to a widget tag are ignored, and markup rendered next to the host isn't inside the viewport. Pass the slides' data as a prop and build them in `mount`/`update`, as `fill` does.
+- **`reInit()` after the slides change.** Embla measures the slides when it starts; without `reInit()` it keeps scrolling over the old ones. `reInit()` emits `reInit`, not `select`, so listen to both to keep `index` right.
+- **Initial state belongs to the page.** `Gallery` keeps its photos in `initialState`, which is fine for the root component or a page. A child component rendered by a parent can't have an `initialState` ([SYG405](https://sygnal.js.org/reference/errors/#syg405)): there, drop it, and pass `photos` and `index` down in the parent's state.
+- **Name commands after what they do.** A command called `scrollTo` would replace the host `<div>`'s own `scrollTo()` method for element commands; `goTo` avoids the confusion.
+- **Accessibility.** Give the carousel a name and each slide its position (`role="group"`, `aria-roledescription="slide"`, `aria-label="2 of 3"`), give the icon buttons labels, and announce the current slide (`aria-live="polite"`). Don't auto-play; if you add it, add a pause button and stop on focus or hover.

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.