sygnal 5.4.0 → 6.0.0

package/dist/guide/undo.md

@@ -0,0 +1,178 @@
+<!-- Generated from docs/src/content/docs/advanced by scripts/copy-guides.mjs; online: https://sygnal.js.org/advanced/ -->
+# Undo and Redo
+
+Sygnal records undo history for one key of a component's state. Each change to `state[key]` pushes the previous value onto `state.history.past`; undo moves it back, redo forward again. There are two ways to add it:
+
+- the **`undo` [behavior](./behaviors.md)**: `uses = { history: undo({ key: 'doc' }) }`, with `canUndo` / `canRedo` in the state and buttons wired through its options;
+- the **`undoable()` model wrapper**: `model = undoable({ … }, { key: 'doc' })`, when you want `UNDO` and `REDO` as plain actions of the component.
+
+Both take the same options and keep the same history.
+
+## The undo behavior
+
+```jsx live
+import { undo } from 'sygnal'
+
+export function Editor({ state }) {
+  return (
+    <div>
+      <label>Note <textarea className="note" value={state.doc.text} /></label>
+      <button className="undo" disabled={!state.history.canUndo}>Undo</button>
+      <button className="redo" disabled={!state.history.canRedo}>Redo</button>
+    </div>
+  )
+}
+
+Editor.initialState = { doc: { text: '' } }
+Editor.uses = { history: undo({ key: 'doc', coalesceMs: 500, undo: '.undo', redo: '.redo' }) }
+Editor.intent = ({ DOM }) => ({ TYPE: DOM.input('.note').value() })
+Editor.model = {
+  TYPE: (state, text) => ({ ...state, doc: { ...state.doc, text } }),
+}
+```
+
+`state.history` is `{ past, future, canUndo, canRedo }`. A click on `Undo` dispatches `history.UNDO`, which puts the newest snapshot from `past` back into `state.doc` and moves the current value to `future`. Any new change clears `future`.
+
+`coalesceMs: 500` joins the changes one action makes less than 500 ms apart into a single step, so typing "hello" quickly is undone at once rather than letter by letter. Without it every change is its own step.
+
+### Grouping only some actions
+
+`coalesceMs` alone joins quick repeats of *any* action: two fast clicks on a Larger button would also become one step. To group only typing, list the actions that may join in `coalesce`. Every other action is then always its own step:
+
+```jsx live
+import { undo } from 'sygnal'
+
+export function Poster({ state }) {
+  return (
+    <div>
+      <label>Headline <input className="headline" value={state.poster.headline} /></label>
+      <button className="larger">Larger</button>
+      <button className="undo" disabled={!state.history.canUndo}>Undo</button>
+      <button className="redo" disabled={!state.history.canRedo}>Redo</button>
+      <h1 style={{ fontSize: `${state.poster.size}px` }}>{state.poster.headline}</h1>
+    </div>
+  )
+}
+
+Poster.initialState = { poster: { headline: '', size: 24 } }
+Poster.uses = { history: undo({ key: 'poster', coalesce: ['HEADLINE'], coalesceMs: 1000, undo: '.undo', redo: '.redo' }) }
+Poster.intent = ({ DOM }) => ({
+  HEADLINE: DOM.input('.headline').value(),
+  LARGER: DOM.click('.larger'),
+})
+Poster.model = {
+  HEADLINE: (state, headline) => ({ ...state, poster: { ...state.poster, headline } }),
+  LARGER: (state) => ({ ...state, poster: { ...state.poster, size: state.poster.size + 4 } }),
+}
+```
+
+Typing "Sale" and then clicking Larger twice quickly makes three steps: the typing, and each click. A `HEADLINE` change joins only the previous change when that was a `HEADLINE` change too, less than `coalesceMs` earlier; a click in between starts a new step. With `coalesce`, `coalesceMs` defaults to 500.
+
+### Keyboard shortcuts
+
+A host intent action with a behavior action's name replaces the behavior's trigger. To undo with Ctrl+Z (⌘Z) as well as the button, leave out the `undo` / `redo` options and trigger the actions from the host:
+
+```jsx live
+import { undo, xs } from 'sygnal'
+
+export function Editor({ state }) {
+  return (
+    <div>
+      <label>Note <textarea className="note" value={state.doc.text} /></label>
+      <button className="undo" disabled={!state.history.canUndo}>Undo</button>
+      <button className="redo" disabled={!state.history.canRedo}>Redo</button>
+    </div>
+  )
+}
+
+const keys = (DOM, shift) => DOM.select('document').events('keydown')
+  .filter(e => (e.ctrlKey || e.metaKey) && e.key.toLowerCase() === 'z' && e.shiftKey === shift)
+
+Editor.initialState = { doc: { text: '' } }
+Editor.uses = { history: undo({ key: 'doc', coalesceMs: 500 }) }
+Editor.intent = ({ DOM }) => ({
+  TYPE: DOM.input('.note').value(),
+  'history.UNDO': xs.merge(DOM.click('.undo'), keys(DOM, false)),
+  'history.REDO': xs.merge(DOM.click('.redo'), keys(DOM, true)),
+})
+Editor.model = {
+  TYPE: (state, text) => ({ ...state, doc: { ...state.doc, text } }),
+}
+```
+
+In a text field the browser runs its own undo on Ctrl+Z too. To leave undo to the app, prevent the default for those keys: `events('keydown', { preventDefault: (e) => … })` ([Preventing the default action](https://sygnal.js.org/guide/intent/#preventing-the-default-action)).
+
+## undoable()
+
+`undoable(model, options)` wraps a model's STATE reducers and adds `UNDO` and `REDO` entries for your intent to trigger. `state.history` is `{ past, future }` (no calculated fields), and it isn't there until the first change, so read it with a default. In this demo, a stand-in server has the saved note:
+
+```js live-server
+export default {
+  'GET /api/note': () => ({ json: { text: 'Buy milk' } }),
+}
+```
+
+```jsx live
+import { undoable } from 'sygnal'
+
+export function Editor({ state }) {
+  const { past, future } = state.history || { past: [], future: [] }
+  return (
+    <div>
+      <label>Note <textarea className="note" value={state.doc.text} /></label>
+      <button className="undo" disabled={past.length === 0}>Undo</button>
+      <button className="redo" disabled={future.length === 0}>Redo</button>
+    </div>
+  )
+}
+
+Editor.initialState = { doc: { text: '' } }
+Editor.intent = ({ DOM }) => ({ TYPE: DOM.input('.note').value(), UNDO: DOM.click('.undo'), REDO: DOM.click('.redo') })
+Editor.model = undoable({
+  BOOTSTRAP: { HTTP: () => ({ url: '/api/note', ok: 'LOADED' }) },
+  LOADED: (state, doc) => ({ ...state, doc }),
+  TYPE: (state, text) => ({ ...state, doc: { ...state.doc, text } }),
+}, { key: 'doc', coalesceMs: 500, resetOn: ['LOADED'] })
+```
+
+`resetOn: ['LOADED']` clears the history when the note is loaded: undo shouldn't bring back the empty draft from before the load. Actions in `resetOn` are not recorded themselves.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `key` | (required) | The state key whose value is recorded; an array of keys (`['todo', 'done']`) records them together, as one `{ todo, done }` value per step |
+| `limit` | `100` | The most steps kept in `past`; the oldest are dropped |
+| `track` | every action with a STATE reducer | Record only these actions' changes. Built-in actions (`INITIALIZE`, `BOOTSTRAP`, …) are recorded only when listed |
+| `coalesceMs` | `0` (off); `500` with `coalesce` | Changes by the same action within this many ms join one step |
+| `coalesce` | every action | Only these actions' changes join a step (typing); every other action is always its own step |
+| `resetOn` | `[]` | Actions that clear the history |
+| `undo`, `redo` | — | (`undo()` only) A selector (or a [control](https://sygnal.js.org/guide/controls/)) whose clicks dispatch `UNDO` / `REDO` |
+
+A change is a reducer result whose `state[key]` is a different object than before (with an array of keys: any of them), so reducers that return new objects (as Sygnal reducers do) are recorded. `UNDO` and `REDO` make no change when there is nothing to undo or redo. A model entry of your own for `UNDO` / `REDO` (`'history.UNDO'` with the behavior) runs after the built-in step.
+
+A key the state doesn't have is recorded as missing: undoing back to such a step removes the key again (it isn't set to `undefined`). With one `key`, a missing key and one set to `undefined` are the same value; with an array of keys they differ, so a key that appears or goes (even as `undefined`) is a change.
+
+Snapshots are the old values themselves, not copies. Keep `key` on the part of the state the user edits (`doc`), not on the whole state, so the history doesn't hold every loading flag and list position too.
+
+For the same reason, when you save the state, save `state.doc` and leave `history` out. With [`persist()`](./persistence.md), pick the document:
+
+```jsx
+import { persist } from 'sygnal'
+
+Editor.persist = persist({ key: 'note', pick: ['doc'] })
+```
+
+After a reload the note is back and the history starts empty, so the first undo doesn't reach into the previous visit.
+
+## Gestures: one step per drag
+
+A behavior on the same host can mark its actions as one gesture with [`undoStep`](./behaviors.md#persisted-state-and-undo-steps). [`sortable`](./drag-and-drop.md#undo-and-persist) does: with `undo({ key: 'tasks' })`, a whole drag, pointer or keyboard, is one undo step, recorded when the item is dropped (`sort.DROPPED`). The live keyboard moves and a cancelled drag (Escape, a drop where it started) add no step. While a drag has moved something, `state.history.base` holds the value from before it; it is gone once the drag is dropped or cancelled. Another recorded change during a drag (an item added while one is lifted) records the value from before the drag, so it stays reachable, and the drag so far joins that change's step. UNDO during a drag goes back to the value from before it (the drag so far is the step undone); REDO during a drag records that value too, in place of the half-moved one. A drag that ends without a drop after something else changed the list (an item added, an undo; see [Drag and Drop](./drag-and-drop.md#keyboard)) leaves the item where it is: when that leaves the value different from the one before the drag, it is recorded as one step, else nothing is; either way nothing stays pending. Only the behavior that started a gesture completes it: with two gesture behaviors on one host, one's completing action doesn't record the other's gesture. This works with `undo()` (the behavior), in either `uses` order; `undoable()` can't see the host's behaviors.
+
+A sortable with several lists (`from: ['todo', 'done']`) moves items between them, so record them together: `undo({ key: ['todo', 'done'] })`. With one of them as the key, an undo after a move between lists puts that list back but not the other, and the item is in both.
+
+`track` and `coalesce` treat a gesture as one action: naming any of the behavior's actions (`'sort.DROPPED'`, `'sort.KEY'`, ...) records drags, or lets quick drops join one step. A `track` list that names none of them leaves drags unrecorded, like any untracked change: undo steps over the tracked changes only, and a drag in progress isn't undone on its own. `coalesceMs` without `coalesce` doesn't join drops: two quick drags are two steps. A name in `resetOn` (`'sort.DROPPED'`) clears the history when that action runs.
+
+## SYG226
+
+A name in `track` or `resetOn` with no model entry is [SYG226](https://sygnal.js.org/reference/errors/#syg226) (a warning): its changes are never recorded, or the history is never cleared. It is usually a typo or a renamed action. `sygnal-check` reports it statically; `undoable()` reports it when diagnostics are on, and `undo()` when the component is first created. For `undo()`, the names are the host component's actions, including other behaviors' namespaced ones (`'pager.NEXT'`); a name under a behavior's key that isn't one of its actions (`'sort.DROPED'`) is reported too.

package/dist/guide/virtual-collections.md

@@ -0,0 +1,183 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Virtual Collections
+
+A `<Collection>` makes a component for every item. With thousands of rows that is slow to create and heavy to keep. `<VirtualCollection>` takes the same props and makes components only for the rows that are in view, plus a few beyond each edge. Scrolling moves that window: rows that leave it are disposed, rows that enter it are made.
+
+`<VirtualCollection>` is itself the scroll container: it renders a `div` (`role="list"` by default) that scrolls. Put the class with the bounded height, `role` and `aria-label` on it (`<VirtualCollection className="people" aria-label="People" … />`), and don't wrap it in a scrolling `<ul>` or `<div>` of your own: it would grow with its rows, only a viewport's height of them would render, and [SYG430](https://sygnal.js.org/reference/errors/#syg430) reports it. SYG430 means: fix the height of the VirtualCollection's own class.
+
+```jsx live-file=./Row.jsx
+// Row.jsx
+export function Row({ state }) {
+  return (
+    <div className="row">
+      <span className="name">{state.name}</span>
+      <button className="star">{state.starred ? 'Unstar' : 'Star'}</button>
+    </div>
+  )
+}
+
+Row.intent = ({ DOM }) => ({ STAR: DOM.click('.star') })
+
+Row.model = {
+  STAR: (state) => ({ ...state, starred: !state.starred }),
+}
+```
+
+```jsx live
+// People.jsx
+import { VirtualCollection } from 'sygnal'
+import { Row } from './Row.jsx'
+
+export function People({ state }) {
+  return (
+    <section>
+      <button className="jump">Jump to row 9,000</button>
+      <VirtualCollection of={Row} from="people" className="people" estimateSize={32} aria-label="People" />
+    </section>
+  )
+}
+
+People.initialState = {
+  people: Array.from({ length: 10000 }, (_, i) => ({ id: i + 1, name: `Person ${i + 1}` })),
+}
+
+People.intent = ({ DOM }) => ({
+  JUMP: DOM.click('.jump').mapTo(8999),
+})
+
+People.model = {
+  JUMP: { ELEMENT: (state, index) => ({ scrollToIndex: '.people', index, align: 'start' }) },
+}
+```
+
+```css live
+.people { height: 480px; }
+```
+
+The element is its own scroll container (`overflow-y: auto`), so **give its class a bounded height**: `height`, `max-height`, or `flex: 1` with `min-height: 0` in a flex column. Without one it grows with its rows and would render all of them; Sygnal then renders only a viewport's height of rows and reports [SYG430](https://sygnal.js.org/reference/errors/#syg430). A `max-height` taller than its rows is fine: the container fits them, and they all render. A percentage `height` or `max-height` bounds it only when its parent has a height itself (`max-height: 100%` of a parent that grows doesn't); Sygnal measures this rather than reading the CSS.
+
+That measurement only happens for a container as tall as all its rows and taller than the viewport. It makes the list's spacer much taller for one forced layout and turns scroll anchoring off (`overflow-anchor: none`) on every ancestor meanwhile, so the page doesn't move. It puts each ancestor's inline style back through the CSSOM (`element.style`), not by rewriting the `style` attribute, because a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) whose `style-src` has no `'unsafe-inline'` blocks attribute writes. The browser then writes those ancestors' `style` attributes again from the declarations it parsed: the text is normalised (`PADDING-TOP:1px` becomes `padding-top: 1px;`), and a declaration it doesn't understand (another engine's vendor prefix) is dropped. Styles you set with JSX `style={{ ... }}` are unaffected. An ancestor without a `style` attribute keeps none.
+
+The viewport-high window is in the rows' own pixels under an ancestor's CSS `zoom` (`zoom: 0.5` renders twice the rows); a CSS `transform` such as `scale()` doesn't change it.
+
+## Props
+
+`of`, `from`, `filter` and `sort` work as on a [Collection](https://sygnal.js.org/guide/collections/): the same keys (an item's `id`, or its index without one), the same duplicate and missing-`from` handling, and an item writes back to its own array element. Any other prop goes to every item, as with a Collection. These are the container's:
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `className` | | The scroll container's class. Give it a bounded height |
+| `estimateSize` | `32` | A row's height in px until it is measured: a number, or `(item, index) => px` |
+| `overscan` | `5` | Rows rendered beyond each edge of the view |
+| `role` | `'list'` | The container's role. With `list`, rows without a role of their own get `role="listitem"`. `null` sets none |
+| `tabIndex` | `0` | Focusable, so the keyboard scrolls it |
+| `aria-label`, `aria-labelledby`, `aria-describedby`, `id`, `style` | | Set on the container (`style` after the defaults) |
+| `viewTransitionName` | | As on [Collection](https://sygnal.js.org/guide/view-transitions/#collection-items): each row with an `id` gets `view-transition-name: <prefix>-<id>`, so a sort in a `viewTransitions` action animates the rows in view |
+
+## Row state lives in the array
+
+A row scrolled out of the window is disposed, like a removed Collection item, and made again when it comes back. Its state is its element of the array, as for every Collection item, so nothing in state is lost: the starred flag above is still there when you scroll back.
+
+What lives only in the DOM or in the row's instance is lost:
+
+- the text of an input whose value isn't in state (bind `value` to state for anything the user types);
+- work in flight: a row's pending request, timer or `EFFECT` ends with its instance.
+
+So keep everything a row needs in its array element, which is the canonical Collection item anyway. Work that must outlive scrolling belongs in the parent.
+
+The focus is the exception: the row that holds it stays rendered while it is scrolled out of view (at its own position, outside the window), so the focus and the keyboard user's place are kept. Once the focus leaves the list, the row goes like any other.
+
+## Jumping to a row
+
+The target row is usually not rendered, so you can't scroll it into view. The container has two methods for [element commands](./element-commands.md) instead:
+
+```jsx
+Results.model = {
+  SHOW_MATCH: { ELEMENT: (state, id) => ({ scrollToId: '.results', id, align: 'center' }) },
+  TO_TOP:     { ELEMENT: { scrollToIndex: '.results', index: 0 } },
+}
+```
+
+| Command | Options |
+|---|---|
+| `{ scrollToIndex: target, index }` | `index`: a position among the shown rows (after `filter` and `sort`), from 0 |
+| `{ scrollToId: target, id }` | `id`: the `id` of an item the filter keeps |
+| both | `align`: `'auto'` (default: scrolls only when the row isn't in view), `'start'`, `'center'`, `'end'`; `behavior`: `'auto'` or `'smooth'` |
+
+The virtualizer scrolls to the row's estimated offset and keeps correcting it while the rows around it are measured, so it lands on the row even when heights vary. An index or id that isn't in the list doesn't scroll ([SYG433](https://sygnal.js.org/reference/errors/#syg433) in development).
+
+## Row heights
+
+Rows can have any height, and each can differ. Until a row has been rendered, its height is `estimateSize`; once rendered, it is measured, and a `ResizeObserver` follows later changes (an expanded row, a loaded image). A good estimate keeps the scrollbar steady: use your typical row height, or a function when rows differ predictably:
+
+```jsx
+<VirtualCollection of={Message} from="messages" className="thread" estimateSize={(message) => (message.image ? 240 : 56)} />
+```
+
+An inline function like this one is a new function at every render; that's fine, it is taken as the same estimate and the measured heights are kept. A numeric `estimateSize` that changes, or a switch between a number and a function, measures the rows again.
+
+A row must render one element, which is what is measured ([SYG432](https://sygnal.js.org/reference/errors/#syg432) for a fragment).
+
+## Accessibility
+
+- The container is a `list` named by `aria-label` (or `aria-labelledby`), and its rows are `listitem`s with `aria-setsize` (the number of shown rows) and `aria-posinset` (the row's position, from 1), so a screen reader can announce "item 4,201 of 10,000" although only a few rows exist.
+- For another pattern, set the container's `role` and give the rows theirs: `role="listbox"` with rows rendering `role="option"` (their `aria-setsize` and `aria-posinset` are set too).
+- The container is focusable (`tabIndex={0}`), so arrow keys, Page Up/Down, Home and End scroll it.
+- A focused row that scrolls out of the window keeps the focus: it stays rendered until the focus leaves the list. For keyboard navigation between rows, keep the active row in state and send `scrollToIndex` with it before focusing.
+
+## Tests and server rendering
+
+Without layout (the default mock DOM of [`renderComponent`](https://sygnal.js.org/integration/testing/), jsdom, `renderToString`), the window is the first 10 rows' estimate plus `overscan`: the first 15 rows by default. Test row behaviour on those rows, and check jumps as commands:
+
+```jsx
+import { renderComponent } from 'sygnal'
+import { People } from './People.jsx'
+
+it('jumps to row 9,000', async () => {
+  const t = renderComponent(People, { initialState: { people: Array.from({ length: 10000 }, (_, i) => ({ id: i + 1, name: 'P' + i })) } })
+  await t.ready()
+  t.simulateEvent('.jump', 'click')
+  await t.settle()
+  expect(t.commands('ELEMENT')).toEqual([{ scrollToIndex: '.people', index: 8999, align: 'start' }])
+})
+```
+
+Scrolling, measured heights and real jumps need a browser: Sygnal's own tests for them run in Chromium, Firefox and WebKit. `renderToString` renders the container and the first rows, numbered and named as the client numbers and names them; the client measures and moves the window once the page has layout. The client's first render makes the rows again (as it does every element of the server markup with a class or an id, and what is inside it), so a focus or text typed in a row before the app started is not kept.
+
+## When to use it
+
+Measured in Chromium 153 with Sygnal's benchmark harness (a 640 px container of 32 px rows; `benchmarks/RESULTS.md` in the repository). Each cell is the time from the click or scroll to the next painted frame, and in brackets the main thread's CPU time, in ms (medians):
+
+| | VirtualCollection | Collection | React + TanStack Virtual | React, every row |
+|---|---:|---:|---:|---:|
+| Create 10,000 rows | 18 (10) | 159 (161) | 17 (7) | 234 (236) |
+| Scroll by a page, 10,000 | 18 (4) | 17 (32) | 18 (3) | 17 (24) |
+| Jump to row 9,000, 10,000 | 19 (4) | 22 (37) | 18 (4) | 17 (27) |
+| Create 100,000 rows | 41 (48) | 1,600 (1,603) | 16 (23) | 11,900 (11,903) |
+| Scroll by a page, 100,000 | 22 (12) | 17 (370) | 18 (8) | 17 (166) |
+| Jump to row 9,000, 100,000 | 22 (13) | 55 (381) | 19 (8) | 33 (177) |
+
+A plain Collection costs about 14 ms per 1,000 rows to create, every row stays in the DOM, and every scroll costs the main thread more as the list grows. `VirtualCollection` costs about the same at any length. **Use it from about 1,000 rows**, or earlier when rows are expensive to render. Below a few hundred rows a plain Collection is simpler: find-in-page, printing and scroll anchoring work on every row, and no height is needed.
+
+It doesn't do (yet): horizontal lists, grids, sticky group headers, or scrolling with the page instead of its own container.
+
+## Without a bundler
+
+`VirtualCollection` uses `@tanstack/virtual-core`, a dependency of Sygnal that bundlers resolve and tree-shake. Loaded as native ES modules straight in the browser (an import map or a CDN, no build step), it needs two things a bundler would otherwise provide:
+
+- an import map entry for `@tanstack/virtual-core` (Sygnal imports it by name), next to the ones for `sygnal`, `snabbdom` and `xstream`;
+- `process.env.NODE_ENV`, which the virtualizer reads when it is created. Define it before the app loads:
+
+```html
+<script>globalThis.process ??= { env: { NODE_ENV: 'production' } }</script>
+```
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG430](https://sygnal.js.org/reference/errors/#syg430) | The container has no bounded height (0 px, or it grows with its rows) |
+| [SYG431](https://sygnal.js.org/reference/errors/#syg431) | Items without `id` (index keys: measured heights and instances follow positions) |
+| [SYG432](https://sygnal.js.org/reference/errors/#syg432) | An item renders a fragment or text, not one element |
+| [SYG433](https://sygnal.js.org/reference/errors/#syg433) | `scrollToIndex` / `scrollToId` for a row not in the list |
+| [SYG434](https://sygnal.js.org/reference/errors/#syg434) | `estimateSize` or `overscan` isn't a valid number |

package/dist/guide/web-components.md

@@ -0,0 +1,179 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Web components
+
+A web component is an element: once its library has defined the tag, the browser treats `<wa-rating>` like `<input>`. Sygnal renders it, patches its properties and listens to its events the same way, so using a component library such as [Web Awesome](https://webawesome.com) needs no adapter. This page covers [using](#using-web-components) them and [publishing](#publishing-a-component-as-a-custom-element) a Sygnal component as one.
+
+## Using web components
+
+Load the library's theme and elements once, at startup (in an app's `main.js`; this demo loads them at its top), then render the tags and select them by class like any element:
+
+```jsx live=Review
+import '@awesome.me/webawesome/dist/styles/themes/default.css'
+import '@awesome.me/webawesome/dist/components/rating/rating.js'
+import '@awesome.me/webawesome/dist/components/input/input.js'
+
+export function Review({ state }) {
+  return (
+    <div>
+      <wa-rating className="food" label="Food" value={state.food} />
+      <wa-input className="comment" label="Comment" value={state.comment} />
+      <p>{state.food} stars</p>
+    </div>
+  )
+}
+
+Review.initialState = { food: 3, comment: '' }
+
+Review.intent = ({ DOM }) => ({
+  FOOD: DOM.select('.food').events('change').value(Number),
+  COMMENT: DOM.select('.comment').events('input').value(),
+})
+
+Review.model = {
+  FOOD: (state, food) => ({ ...state, food }),
+  COMMENT: (state, comment) => ({ ...state, comment }),
+}
+```
+
+Web Awesome's inputs fire the standard `change` and `input` events and keep their value in a `value` property, so `.value()` reads them as it reads an `<input>`. Pointer, touch and keyboard input all arrive this way; the element handles them inside its shadow root.
+
+### Properties and attributes
+
+A JSX prop sets the element's **property** of that name: `value={state.food}` sets `rating.value` to the number, `readonly={state.locked}` sets a boolean property. That is what Lit-based libraries expect, and it keeps numbers, booleans, arrays and objects intact.
+
+- **camelCase properties.** A library's `with-clear` attribute is its `withClear` property: write `withClear` (`<wa-input withClear />`). A dashed JSX prop (`with-clear`) sets a property literally named `with-clear`, which the element ignores.
+- **Attributes.** For the few things that must be attributes (a `size` the library styles by, an attribute selector in your CSS, the [`name` of some form fields](#forms)), use `attrs`: `<wa-rating attrs={{ size: 'l' }} />`.
+- **Load order.** A tag rendered before its library has defined it keeps the props Sygnal set, and the element takes them over when it upgrades. Defining the elements at startup, before `run()`, is still simplest.
+
+### Events
+
+Library events cross the shadow boundary and bubble to the host (they are `composed`), so the intent selects them on the element with any name, and `.detail()` reads their payload:
+
+```jsx
+Review.intent = ({ DOM }) => ({
+  HOVER: DOM.select('.food').events('wa-hover').detail((hover) => hover.value),
+  ACTION: DOM.select('.actions').events('wa-select').detail((selected) => selected.item.value),
+})
+```
+
+`.detail(fn?)` maps each event to `event.detail` (or `fn(event.detail)`), next to `.value()`, `.checked()` and `.data()`. A custom event name type-checks in TypeScript (`events()` takes any string). The shorthand form `DOM['wa-hover']('.food')` works too, but `DOM.select(…).events(…)` is the one to prefer for custom names.
+
+Events reach only the component that renders the element, as for any element: a `<wa-rating>` in each [Collection](https://sygnal.js.org/guide/collections/) item reports to its own item.
+
+### Forms
+
+Web Awesome's fields are form-associated: inside a `<form>`, they submit their value under their `name`, and [`processForm`](https://sygnal.js.org/reference/api/#processform) on `submit` sees them as it sees an `<input>`.
+
+```jsx
+export function Signup({ state }) {
+  return (
+    <form className="signup">
+      <wa-input name="email" label="Email" value={state.email} />
+      <wa-rating attrs={{ name: 'stars' }} label="Stars" value={state.stars} />
+      <button type="submit">Sign up</button>
+    </form>
+  )
+}
+
+Signup.initialState = { email: '', stars: 3 }
+
+Signup.intent = ({ DOM }) => ({
+  SUBMIT: processForm(DOM.select('.signup'), { events: 'submit' }),
+})
+
+Signup.model = {
+  SUBMIT: (state, { email, stars }) => ({ ...state, email, stars: Number(stars) }),
+}
+```
+
+- **`name` as an attribute.** The form reads a custom element's `name` attribute. Some elements don't reflect the `name` property to the attribute (`wa-rating` doesn't, `wa-input` does), so pass it with `attrs={{ name: 'stars' }}` when in doubt.
+- **`form` is always an attribute.** `<wa-input form="signup">` links a field outside the `<form>` to `<form id="signup">`, as it does for an `<input>`: a form-associated element's `form` property is read-only. (`list`, by contrast, is a custom element's own property: it is set as one.)
+- **Read live values from the element.** A form-associated element updates its form value asynchronously. On every keystroke, `.value()` on its `input` event is current in every browser, while the form's own data can be one keystroke behind (Firefox). Use `processForm` on `submit`, and `.value()` for live input.
+
+### TypeScript
+
+Web Awesome, like most Lit libraries, adds its elements to `HTMLElementTagNameMap` (`'wa-rating': WaRating`). One augmentation types every tag of a library's prefix in JSX, with the element's own property types:
+
+```tsx
+// web-awesome.d.ts
+import type { IntrinsicControlProps } from 'sygnal'
+
+type WaTags = {
+  [K in keyof HTMLElementTagNameMap as K extends `wa-${string}` ? K : never]: IntrinsicControlProps<K>
+}
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements extends WaTags {}
+  }
+}
+```
+
+Then `<wa-rating value="3" />` is an error (the property is a number), and so are unknown props, methods and read-only properties. Function-valued properties are left out of the JSX props: set them with `props={{ getSymbol }}`. Event payloads are typed where you read them: `.detail<{ value: number }>()`.
+
+### Server rendering
+
+`renderToString` writes a custom element's props as attributes, the form its library reads when the element upgrades in the browser: `true` as a bare attribute, `false` and `null` left out. A camelCase HTML property gets its attribute (`tabIndex` → `tabindex`, `readOnly` → `readonly`, `ariaLabel` → `aria-label`); any other camelCase name is written both in kebab-case and in lowercase (`withClear` → `with-clear withclear`), since libraries differ: Web Awesome, Shoelace, Stencil and `defineElement` read `with-clear`, Lit's and FAST's default is `withclear`. The element reads the one it knows. To write one exact attribute, pass it in `attrs`. Function and object props have no attribute form and are left out; they are set on the client, when `run()` renders. Sygnal doesn't render the element's shadow DOM on the server (no declarative shadow DOM): the element renders itself once its library loads.
+
+### As controls
+
+Custom-element tags also work as [controls](https://sygnal.js.org/guide/controls/), the alternative form that names elements by identifier: `const { Rating } = controls({ Rating: 'wa-rating' })`, then `<Rating label="Service" value={state.service} />` and `DOM.select(Rating).events('wa-hover').detail()`. With the [TypeScript augmentation](#typescript), a control made from a tag is typed from the element without anything more.
+
+## Publishing a component as a custom element
+
+`defineElement` from `sygnal/element` goes the other way: it publishes a Sygnal component as a custom element, for plain HTML pages, other frameworks, or another Sygnal app.
+
+```jsx
+// score-card.js
+import { defineElement } from 'sygnal/element'
+
+function ScoreCard({ state }) {
+  return (
+    <div className="card">
+      <strong>{state.title}</strong>
+      <wa-rating className="score" label={state.title} value={state.score} />
+    </div>
+  )
+}
+
+ScoreCard.initialState = { title: 'Untitled', score: 0 }
+ScoreCard.intent = ({ DOM }) => ({ SCORE: DOM.select('.score').events('change').value(Number) })
+ScoreCard.model = {
+  SCORE: {
+    STATE: (state, score) => ({ ...state, score }),
+    PARENT: (state, score) => ({ score }),
+  },
+}
+
+defineElement('score-card', ScoreCard, {
+  props: { title: String, score: Number },
+  events: { PARENT: 'score-change' },
+})
+```
+
+```html
+<score-card title="Pasta" score="3"></score-card>
+<script>
+  document.querySelector('score-card').addEventListener('score-change', (e) => console.log(e.detail.score))
+</script>
+```
+
+- **`props`** feed the component's state. Each prop is a property (`card.score = 4`) and a kebab-case attribute (`score="4"`, `due-date` for `dueDate`); attributes are parsed to the declared type.
+- **`events`** map a sink to a DOM event: a value the component sends on `PARENT` is dispatched as a bubbling, composed `CustomEvent` named `score-change`, with the value as its `detail`.
+- **`shadow`** (`true`, `'open'` or `'closed'`) renders into a shadow root, and **`styles`** are adopted into it.
+
+Each element runs the component as its own app. In another Sygnal app it is a web component like any other: `<score-card className="pasta" title="Pasta" score={state.pasta} />`, and `DOM.select('.pasta').events('score-change').detail((d) => d.score)`.
+
+## defineWidget or defineElement?
+
+| | [`defineWidget`](./widgets.md) | `defineElement` (`sygnal/element`) |
+|---|---|---|
+| Direction | A third-party widget **into** a Sygnal view | A Sygnal component **out**, as a custom element |
+| Wraps | A framework-agnostic library (flatpickr, Chart.js, Tiptap) | A Sygnal component (view, intent, model) |
+| Result | A JSX tag rendering a host element, selected by class | A custom element tag, usable from any HTML |
+| State | None: props in, `dispatch` out | The component's own state, fed by props |
+| Events | `dispatch(name, detail)` → `CustomEvent` on the host | A sink value → `CustomEvent` on the element |
+| Methods | `commands`, sent with `ELEMENT` | The element's props as properties |
+| Used by | One app's views | Any page or framework |
+
+A web component library you only use (Web Awesome) needs neither: render its tags.