sygnal 5.3.7 → 6.0.0

package/dist/guide/inputs.md

@@ -0,0 +1,173 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Inputs, Labels and Focus
+
+How Sygnal treats the value of a field, how to give labels and descriptions ids that stay unique, and how to focus a field when it appears. For forms with validation, see [Forms](./forms.md).
+
+## Controlled Inputs
+
+An `<input>`, `<textarea>` or `<select>` with a `value` prop (or a checkbox/radio with `checked`) is **controlled**: on every render, Sygnal writes the value from your view into the element, like React does. That keeps the field in sync with state (clearing a field after "Add" works even when both happen in the same tick), but it means the field must update state as the user types. Otherwise any re-render resets what they typed.
+
+A form-associated custom element (one whose class has `static formAssociated = true`, such as Web Awesome's `<wa-input>` or `<wa-rating>`) with a `value` or `checked` prop is controlled the same way.
+
+To refuse what the user entered, return `ABORT` (or the state unchanged): the state stays as it was, and because the action came from an `input` or `change` event, the component still renders, so the field shows the state's value again. A digits-only field:
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function Pin({ state }) {
+  return <input className="pin" aria-label="PIN" inputMode="numeric" value={state.pin} />
+}
+
+Pin.initialState = { pin: '' }
+Pin.intent = ({ DOM }) => ({ PIN: DOM.input('.pin').value() })
+Pin.model = {
+  PIN: (state, pin) => /^\d{0,6}$/.test(pin) ? { ...state, pin } : ABORT,
+}
+```
+
+This applies only while the `input` or `change` event is being handled (an intent that delays the action, with `debounce` for example, gets no extra render). `ABORT` from any other action (a click, a timer, a reply) still renders nothing.
+
+Pick one of two patterns:
+
+**Controlled**: bind `value` to state and update state on `input`:
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function NewTodo({ state }) {
+  return (
+    <div>
+      <input className="new-todo" aria-label="New todo" value={state.draft} />
+      <button className="add">Add</button>
+      <ul>{state.items.map((item) => <li>{item}</li>)}</ul>
+    </div>
+  )
+}
+
+NewTodo.initialState = { draft: '', items: [] }
+
+NewTodo.intent = ({ DOM }) => ({
+  DRAFT: DOM.input('.new-todo').value(),
+  ADD:   DOM.click('.add'),
+})
+
+NewTodo.model = {
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  ADD:   (state) => state.draft.trim()
+    ? { ...state, items: [...state.items, state.draft.trim()], draft: '' }
+    : ABORT,
+}
+```
+
+**Uncontrolled**: leave out `value`, and read the element's value from the event when you need it (on blur, Enter or submit), or with [`processForm()`](./forms-reference.md#processform):
+
+```jsx live
+import { ABORT } from 'sygnal'
+
+function Rename({ state }) {
+  return <input className="rename" aria-label="Title" placeholder={state.title} />
+}
+
+Rename.initialState = { title: 'Untitled' }
+
+Rename.intent = ({ DOM }) => ({
+  RENAME: DOM.keydown('.rename').filter(e => e.key === 'Enter').map(e => e.target.value),
+})
+
+Rename.model = {
+  RENAME: (state, title) => title ? { ...state, title } : ABORT,
+}
+```
+
+What doesn't work is a bound `value` with no `input`/`change` listener, for example a "save on blur" field that only listens to `blur`: the first re-render while the user types puts the old value back. `sygnal-check` reports that as [SYG111](https://sygnal.js.org/reference/errors/#syg111). Literal values (`value=""`) are controlled too, so they reset the field on every render as well.
+
+`value={null}` (or `checked={null}`) clears the field and keeps it controlled; leaving the prop out makes the field uncontrolled, so whatever the user typed stays.
+
+## Labels and ids: uid()
+
+Every field needs a label ([SYG702](./accessibility.md#syg702-form-field-without-a-label)). Wrapping the field in a `<label>` needs no id. When the label sits elsewhere, or a hint is attached with `aria-describedby`, the elements need ids, and a literal `id="email"` is repeated as soon as the component renders twice. Use the `uid` view prop instead:
+
+```jsx
+function Signup({ state, uid }) {
+  return (
+    <form className="signup">
+      <label for={uid('email')}>Email</label>
+      <input id={uid('email')} type="email" className="email" value={state.email} aria-describedby={uid('email-help')} />
+      <p id={uid('email-help')}>We only use it to sign you in.</p>
+    </form>
+  )
+}
+
+Signup.initialState = { email: '' }
+Signup.intent = ({ DOM }) => ({ EMAIL: DOM.input('.email').value() })
+Signup.model = { EMAIL: (state, email) => ({ ...state, email }) }
+```
+
+`uid()` returns an id for this component instance, and `uid('email')` one derived from it (for example `u-email` at the root, longer further down the tree). Ids come from the instance's position in the tree and its Collection item key, never from a counter, so they:
+
+- differ between two instances of the component, and between Collection items;
+- stay the same across renders, and move with their item when a Collection is reordered;
+- are the same on the server and after hydration ([SSR](./ssr.md#stable-ids-uid)).
+
+`uid` is also on the reducers' `props` argument. It is a reserved prop: a parent can't pass its own `uid` to a child ([SYG106](https://sygnal.js.org/reference/errors/#syg106)). `sygnal-check` matches `for={uid('email')}` with `id={uid('email')}` ([SYG708](./accessibility.md#syg708-label-or-aria-reference-to-an-id-that-isnt-rendered)).
+
+## Focus Management
+
+Sygnal components are pure functions — they never touch real DOM elements. But web apps frequently need to focus an element programmatically, for example when an input appears for inline editing.
+
+The `autoFocus` and `autoSelect` JSX props handle this declaratively. No imperative code in your view, no drivers, no hooks.
+
+### autoFocus
+
+Add `autoFocus={true}` to any element. When that element enters the DOM, it receives focus automatically:
+
+```jsx
+function SearchBar({ state }) {
+  return (
+    <div>
+      {state.isOpen &&
+        <input autoFocus={true} className="search-input" placeholder="Search..." />
+      }
+    </div>
+  )
+}
+```
+
+### autoSelect
+
+Add `autoSelect={true}` alongside `autoFocus` to select all text in the element after focusing. This is ideal for edit-in-place patterns where the user typically wants to replace the existing value:
+
+```jsx live
+function EditableTitle({ state }) {
+  return (
+    <div>
+      {state.isEditing
+        ? <input autoFocus={true} autoSelect={true} value={state.draft} className="title-input" aria-label="Title" />
+        : <h2 className="title">{state.title}</h2>
+      }
+    </div>
+  )
+}
+
+EditableTitle.initialState = { title: 'Double-click to rename', isEditing: false, draft: '' }
+
+EditableTitle.intent = ({ DOM }) => ({
+  EDIT:  DOM.dblclick('.title'),
+  DRAFT: DOM.input('.title-input').value(),
+  SAVE:  DOM.blur('.title-input'),
+})
+
+EditableTitle.model = {
+  EDIT:  (state) => ({ ...state, isEditing: true, draft: state.title }),
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  SAVE:  (state) => ({ ...state, isEditing: false, title: state.draft }),
+}
+```
+
+When the user double-clicks to edit, the input appears focused with all text selected — ready to type a replacement.
+
+### How It Works
+
+These props are intercepted by the JSX pragma before they reach the DOM. Under the hood, a snabbdom `insert` hook calls `.focus()` (and optionally `.select()`) when the element is first inserted. The props are never passed to the actual DOM element.
+
+If you also set a manual `hook={{ insert: fn }}` on the same element, both hooks run — yours first, then the focus behavior.

package/dist/guide/persistence.md

@@ -0,0 +1,245 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Persistence
+
+`persist()` saves part of the app's state in the browser's storage and puts it back when the app starts again. You declare it once, on the root component: which keys to keep, under which storage key, and in which version of their shape.
+
+```jsx live
+// TodoApp.jsx
+import { ABORT, persist } from 'sygnal'
+
+export function TodoApp({ state }) {
+  const shown = state.filter === 'open' ? state.todos.filter((todo) => !todo.done) : state.todos
+  return (
+    <main>
+      <label>New todo <input className="draft" value={state.draft} /></label>
+      <button className="add">Add</button>
+      <button className="show-all">All</button>
+      <button className="show-open">Open</button>
+      <button className="start-over">Start over</button>
+      <ul>{shown.map((todo) => <li>{todo.title}</li>)}</ul>
+    </main>
+  )
+}
+
+TodoApp.initialState = { todos: [], filter: 'all', draft: '' }
+
+TodoApp.intent = ({ DOM }) => ({
+  DRAFT: DOM.input('.draft').value(),
+  ADD: DOM.click('.add'),
+  SHOW_ALL: DOM.click('.show-all'),
+  SHOW_OPEN: DOM.click('.show-open'),
+  START_OVER: DOM.click('.start-over'),
+})
+
+TodoApp.model = {
+  DRAFT: (state, draft) => ({ ...state, draft }),
+  ADD: (state) => state.draft
+    ? { ...state, todos: [...state.todos, { title: state.draft, done: false }], draft: '' }
+    : ABORT,
+  SHOW_ALL: (state) => ({ ...state, filter: 'all' }),
+  SHOW_OPEN: (state) => ({ ...state, filter: 'open' }),
+  START_OVER: {
+    STATE: (state) => ({ ...state, todos: [], filter: 'all' }),
+    PERSIST: { clear: true },
+  },
+}
+
+// Version 1 saved { items: ['milk', ...] }; version 2 saves { todos: [{ title, done }], filter }
+TodoApp.persist = persist({
+  key: 'todo-app',
+  pick: ['todos', 'filter'],
+  version: 2,
+  migrate: (old, fromVersion) => fromVersion === 1
+    ? { todos: old.items.map((title) => ({ title, done: false })), filter: 'all' }
+    : undefined,
+})
+```
+
+Reload the page and the todos and the filter are still there; the half-typed `draft` is not, because it isn't picked. **Start over** empties the list and removes the saved copy.
+
+## What is saved
+
+The stored value is JSON, `{ version, state }`, under `key`:
+
+```json
+{"version":2,"state":{"todos":[{"title":"milk","done":false}],"filter":"all"}}
+```
+
+`state` has the top-level keys listed in `pick`, or, with `omit` instead, every key except those. [Calculated fields](https://sygnal.js.org/guide/calculated-fields/) are never saved: they are computed again from the restored state. Pick what has to survive a reload (the user's data, a chosen view) and leave out what doesn't (drafts, loading flags, server data you fetch again, an undo history). A [behavior](./behaviors.md#persisted-state-and-undo-steps) of the root component whose slice is UI state (`persist: false`, as [`sortable`](./drag-and-drop.md)'s drag state) is never saved or restored, even when `pick` names it. A sub-component's or Collection item's behavior slice is part of the data it lives in and is saved with it.
+
+Values must survive `JSON.stringify`: plain objects, arrays, strings, numbers, booleans and `null`. A `Date` comes back as a string, and a `Map` or `Set` as `{}`.
+
+### A plain format
+
+When something else reads or writes the same entry (an older version of the app, another script, a spec that fixes the format), `format: 'plain'` stores the picked keys themselves, with no envelope:
+
+```jsx
+Note.persist = persist({ key: 'note-draft', pick: ['title', 'body'], format: 'plain' })
+```
+
+```json
+{"title":"Groceries","body":"milk, eggs"}
+```
+
+A plain entry has no version, so `version` and `migrate` don't apply: TypeScript rejects them with `format: 'plain'`, and they are ignored at runtime. A stored value that isn't an object (an array, a string, a number) is ignored, and the app starts from `initialState`. Everything else (`pick`/`omit`, `sync`, `storage`, clearing, the restore and the debounced writes) works as with the default `format: 'versioned'`.
+
+## When it is restored
+
+When the app starts, the root component reads the stored entry synchronously, before its first state, and merges the saved keys into `initialState`. The first render already shows the saved todos, and the `INITIALIZE` action carries them: there is no separate "load" step and no flash of the empty list.
+
+`persist` works on the **root component** only, the one passed to `run()`. It saves and restores the app's whole state tree, and a sub-component's state is a slice of it: to save a child's state, pick the key the root keeps it under. On any other component the static is ignored, which is [SYG224](https://sygnal.js.org/reference/errors/#syg224) in development and in `sygnal-check`.
+
+:::note[Where persist works]
+On any component that is its app's root:
+
+- the component you pass to `run()`
+- the component you pass to [`renderComponent`](#testing) in tests
+- an [Astro](https://sygnal.js.org/integration/astro/) island (each island is its own app)
+- a [Vike](https://sygnal.js.org/integration/vike/) page with no Layout or Wrapper
+
+Not (yet) on a Vike page, Layout or Wrapper rendered in a Layout/Wrapper shell: the shell is the root there, so `persist` is ignored and SYG224 says so. Save that state yourself: write it with [`STATE.watch`](https://sygnal.js.org/guide/intent/#reacting-to-state-changes-statewatch) and read it back in `BOOTSTRAP`.
+:::
+
+## When it is saved
+
+A write happens after the state stops changing for `debounceMs` (100 ms by default), so typing or a burst of actions makes one write. A pending write is also made at once when the page is hidden for good (the `pagehide` event: closing the tab, navigating away) and when the app is disposed. Nothing is written while the picked keys are unchanged, and the initial state is not written back.
+
+## Versions and migrate
+
+`version` (default 1) is saved with the state (not with `format: 'plain'`). When the stored entry has another version, `migrate(old, fromVersion)` turns the old `state` into this version's keys; the result is merged into `initialState` like any restore and saved under the new version on the next write. When `migrate` returns nothing (`undefined` or `null`), or there is no `migrate`, the stored entry is ignored and the app starts from `initialState`.
+
+Bump `version` whenever the shape of a picked key changes, and keep the `migrate` branches for the versions your users may still have.
+
+## Clearing
+
+`PERSIST: { clear: true }` in a model entry removes the stored copy. Like other sinks it can be a function of `(state, data)` that returns the command, or `ABORT` to do nothing:
+
+```jsx
+Account.model = {
+  LOG_OUT: {
+    STATE: (state) => ({ ...state, user: null, cart: [] }),
+    PERSIST: { clear: true },
+  },
+}
+```
+
+The state the same action produces isn't saved; the next change is. `PERSIST` needs no driver.
+
+## Several tabs: sync
+
+With `sync: true`, a write made in another tab (or window) of the same site is applied in this one, as a built-in `RESTORE` action whose data is the saved keys. The default `RESTORE` merges them into the state; a `RESTORE` entry in your model replaces it:
+
+```jsx
+TodoApp.persist = persist({ key: 'todo-app', pick: ['todos', 'filter'], version: 2, migrate, sync: true })
+```
+
+Clearing in another tab doesn't reset this one: it keeps its state and saves it again on its next change.
+
+## Storage
+
+`storage` is `'local'` (`localStorage`, the default), `'session'` (`sessionStorage`: one tab, until it closes) or an object with synchronous `getItem`, `setItem` and `removeItem`. With `sync`, an object can also have `subscribe(fn)`: call `fn(key, newValue)` when another writer changes a key, and return a function that unsubscribes.
+
+```jsx
+const memory = new Map()
+
+export const memoryStorage = {
+  getItem: (key) => memory.get(key) ?? null,
+  setItem: (key, value) => { memory.set(key, value) },
+  removeItem: (key) => { memory.delete(key) },
+}
+```
+
+Asynchronous storages (IndexedDB, a server) don't fit the synchronous restore. Load from those with a request in `BOOTSTRAP` and save with [`STATE.watch`](https://sygnal.js.org/guide/intent/#reacting-to-state-changes-statewatch) instead.
+
+During server rendering nothing is read or written: `renderToString` runs views only.
+
+## Server rendering: hydrate
+
+When the client starts from server-rendered HTML (the [`hydrateState`](./ssr.md) state), restoring before the first render would make that render differ from the server's markup. So when the app hydrates, the first render uses the server's state, and the saved keys follow in a `RESTORE` action once it is on the page. The app hydrates when:
+
+- `run()`'s mount point starts with markup from [`renderToString()`](./ssr.md): its root element carries a `data-sygnal-ssr` attribute, which the first client render removes. Other markup in the mount point, such as a client-only app's loading placeholder, isn't server markup: the saved keys are part of the first render
+- an [Astro](https://sygnal.js.org/integration/astro/) island was rendered on the server (not `client:only`)
+- a [Vike](https://sygnal.js.org/integration/vike/) page hydrates its server HTML (not a client-side navigation)
+
+```jsx
+App.persist = persist({ key: 'app', pick: ['theme'] })
+App.initialState = window.__SYGNAL_STATE__ || App.initialState
+
+run(App, {}, { mountPoint: '#app' })
+```
+
+The `hydrate` option overrides the detection: `hydrate: true` always restores after the first render, `hydrate: false` always before it. Use `hydrate: true` when the server's HTML doesn't come from `renderToString()` (another renderer, or markup you post-process without the attribute).
+
+## With undo
+
+Keep an [undo history](./undo.md) out of the saved state: pick the document, not `history`. After a reload the document is back and the history starts empty.
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG642](https://sygnal.js.org/reference/errors/#syg642) (warning) | The stored entry isn't JSON, `migrate` threw, or a write failed (the storage is full or blocked). The app continues: from `initialState` after a failed restore, unsaved after a failed write (retried at the next state change). Printed in production too, once per kind (restore, save, clear): a storage that refuses every write warns once, and again only after a save has worked |
+| [SYG223](https://sygnal.js.org/reference/errors/#syg223) (warning) | A `pick` or `omit` key that isn't a key of `initialState` (a typo) |
+| [SYG224](https://sygnal.js.org/reference/errors/#syg224) (error) | `persist` on a component that isn't the root |
+
+## Testing
+
+`renderComponent` gives a persisting root a fake storage. The `storage` option fills it (key to stored entry, or a raw string), `t.storage(key)` reads an entry, and `t.settle()` makes the pending writes:
+
+```jsx
+// TodoApp.test.jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { TodoApp } from './TodoApp.jsx'
+
+it('restores version 1 todos and saves version 2', async () => {
+  const t = renderComponent(TodoApp, {
+    storage: { 'todo-app': { version: 1, state: { items: ['milk'] } } },
+  })
+  await t.ready()
+  expect(t.state.todos).toEqual([{ title: 'milk', done: false }])
+
+  t.simulateAction('DRAFT', 'eggs')
+  t.simulateAction('ADD')
+  await t.settle()
+  expect(t.storage('todo-app')).toEqual({
+    version: 2,
+    state: { todos: [{ title: 'milk', done: false }, { title: 'eggs', done: false }], filter: 'all' },
+  })
+  t.dispose()
+})
+```
+
+The object you pass is used as the storage, not copied: writes land in it, and two `renderComponent` calls given the same object share it, so `sync: true` can be tested with two instances. The fake serves `'local'` and `'session'` alike; a component whose `storage` is an object uses that object.
+
+With `format: 'plain'` the entries are the stored keys themselves, both in the `storage` option and from `t.storage(key)`:
+
+```jsx
+it('saves the draft as { title, body }', async () => {
+  const t = renderComponent(Note, { storage: { 'note-draft': { title: 'Groceries', body: '' } } })
+  await t.ready()
+  expect(t.state.title).toBe('Groceries')
+
+  t.simulateAction('BODY', 'milk')
+  await t.settle()
+  expect(t.storage('note-draft')).toEqual({ title: 'Groceries', body: 'milk' })
+  t.dispose()
+})
+```
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `key` | (required) | The storage key |
+| `pick` | all keys | The top-level state keys to save |
+| `omit` | `[]` | The top-level state keys not to save (instead of `pick`) |
+| `version` | `1` | Saved with the state; another stored version goes through `migrate` |
+| `migrate` | none | `(old, fromVersion) => keys` for a stored entry of another version; nothing discards it |
+| `format` | `'versioned'` | `'versioned'` stores `{ version, state }`; `'plain'` stores the picked keys themselves (no `version` / `migrate`) |
+| `storage` | `'local'` | `'local'`, `'session'` or a synchronous `{ getItem, setItem, removeItem, subscribe? }` |
+| `sync` | `false` | Apply other tabs' writes (a `RESTORE` action) |
+| `hydrate` | detected | Restore after the first render (in `RESTORE`): `true` / `false` override the detection of server-rendered HTML |
+| `debounceMs` | `100` | Wait this long without a state change before writing |
+
+In TypeScript, `pick` and `omit` are checked against the root component's state keys.

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.