sygnal 5.3.7 → 6.0.0

package/dist/guide/recipes/i18n.md

@@ -0,0 +1,222 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Translations (i18n)
+
+[i18next](https://www.i18next.com/) looks up translated strings, fills in values and picks plural forms. In a Sygnal app the chosen locale is ordinary state: the root keeps it, [`.context`](https://sygnal.js.org/guide/context/) hands every component a `t()` for that locale, and [`persist()`](../persistence.md) remembers it for the next visit. Switching the language is an action like any other, and every component re-renders in the new language.
+
+## Install
+
+```sh
+npm install i18next
+```
+
+## The i18next instance
+
+```js live-file=./i18n.js
+// i18n.js
+import i18next from 'i18next'
+
+export const LOCALES = { en: 'English', fr: 'Français' }
+
+export const i18n = i18next.createInstance()
+i18n.init({
+  initAsync: false, // the resources are here: ready before the first render
+  interpolation: { escapeValue: false }, // Sygnal renders strings as text, never as HTML
+  fallbackLng: 'en',
+  supportedLngs: Object.keys(LOCALES),
+  resources: {
+    en: {
+      translation: {
+        language: 'Language',
+        greeting: 'Hello, {{name}}!',
+        cart: {
+          title: 'Your cart',
+          add: 'Add a coffee',
+          items_one: '{{count}} item',
+          items_other: '{{count}} items',
+          total: 'Total: {{total, currency(EUR)}}',
+        },
+      },
+    },
+    fr: {
+      translation: {
+        language: 'Langue',
+        greeting: 'Bonjour, {{name}} !',
+        cart: {
+          title: 'Votre panier',
+          add: 'Ajouter un café',
+          items_one: '{{count}} article',
+          items_other: '{{count}} articles',
+          total: 'Total : {{total, currency(EUR)}}',
+        },
+      },
+    },
+  },
+})
+
+// One t() per locale, made once: the context value changes only when the locale does
+const fixed = {}
+export const translator = (locale) => (fixed[locale] ||= i18n.getFixedT(locale))
+
+// The browser's language; 'en' on the server (Node 21+ has a navigator too, with the server's)
+export function detectLocale() {
+  const lang = typeof window === 'undefined' ? 'en' : (navigator.language || '').slice(0, 2)
+  return lang in LOCALES ? lang : 'en'
+}
+```
+
+- `initAsync: false` with the translations inline makes `t()` work as soon as the module is loaded, so the first render is already translated.
+- `escapeValue: false`: i18next escapes the values it fills in for HTML by default (`&` becomes `&amp;`). Sygnal puts strings into the page as text, which is already safe, so escaping would show the entities.
+- `getFixedT(locale)` returns a `t` bound to one locale. The app never calls `i18n.changeLanguage()`: the locale lives in Sygnal's state, not in the i18next instance, so several apps (or tests) can show different languages at once.
+- `translator` keeps one `t` per locale, so the function only changes when the locale does.
+
+## The app
+
+```jsx live
+// App.jsx
+import { persist } from 'sygnal'
+import { LOCALES, translator, detectLocale } from './i18n.js'
+import { Cart } from './Cart.jsx'
+
+export function App({ state }) {
+  const t = translator(state.locale)
+  return (
+    <main lang={state.locale}>
+      <label>
+        {t('language')}
+        <select className="locale" value={state.locale}>
+          {Object.entries(LOCALES).map(([code, name]) => <option value={code}>{name}</option>)}
+        </select>
+      </label>
+      <h1>{t('greeting', { name: state.name })}</h1>
+      <Cart state="cart" />
+    </main>
+  )
+}
+
+App.initialState = { locale: detectLocale(), name: 'Ada', cart: { items: 0 } }
+
+App.context = { t: (state) => translator(state.locale) }
+
+App.intent = ({ DOM }) => ({
+  LOCALE: DOM.change('.locale').value(),
+})
+
+App.model = {
+  LOCALE: (state, locale) => ({ ...state, locale }),
+}
+
+App.persist = persist({ key: 'locale', pick: ['locale'] })
+```
+
+```jsx live-file=./Cart.jsx
+// Cart.jsx
+const PRICE = 4.5
+
+export function Cart({ state, context }) {
+  const { t } = context
+  return (
+    <section>
+      <h2>{t('cart.title')}</h2>
+      <p className="count">{t('cart.items', { count: state.items })}</p>
+      <p className="total">{t('cart.total', { total: state.items * PRICE })}</p>
+      <button className="add">{t('cart.add')}</button>
+    </section>
+  )
+}
+
+Cart.intent = ({ DOM }) => ({
+  ADD: DOM.click('.add'),
+})
+
+Cart.model = {
+  ADD: (state) => ({ ...state, items: state.items + 1 }),
+}
+```
+
+- **The locale** is a key of the root's state. On the first visit it comes from the browser (`detectLocale()`); after that, `persist()` restores the saved one before the first render, so there is no flash of the wrong language.
+- **`t` for every component**: `App.context.t` is computed from the root's state, and every component below reads it as `context.t`, however deep. When the locale changes, the context changes, and the components that use it render again. The root itself calls `translator(state.locale)`, since the locale is in its own state.
+- **Reducers** get the context too, on their fourth argument: `(state, data, next, { context }) => ... context.t('saved') ...`, for a message the model builds.
+
+## Plurals, values and formats
+
+- **Plurals**: pass `count`, and i18next picks the key with the language's plural suffix (`items_one`, `items_other`; some languages have `_zero`, `_two`, `_few`, `_many`). The rules are the language's own, from `Intl.PluralRules`: French uses the singular for 0 ("0 article"), English the plural ("0 items").
+- **Values**: `{{name}}` in a string is filled from the options: `t('greeting', { name: state.name })`.
+- **Formats**: `{{total, currency(EUR)}}` formats with `Intl.NumberFormat` for the locale: "€4.50" in English, "4,50 €" in French. `number`, `datetime`, `relativetime` and `list` work the same way.
+
+## Accessibility
+
+- Put the locale in a `lang` attribute (here on `<main>`), so screen readers pronounce the text in the right language. For the whole page, set `document.documentElement.lang` from an `EFFECT` in the `LOCALE` entry and in `BOOTSTRAP`.
+- Translated labels are fine. sygnal-check's accessibility rules ([SYG702](https://sygnal.js.org/reference/errors/#syg702), [SYG705](https://sygnal.js.org/reference/errors/#syg705)) check that a field has a label and a button has a name; a `{t('...')}` expression counts as one. They can't check what the translation says, so keep the keys for labels and names present in every language (a missing key shows the key itself).
+- Translate `aria-label`s, `alt` text and `title`s too: `aria-label={t('cart.remove')}`.
+
+## Testing
+
+`renderComponent` gives a persisting root a fake storage; fill it to start in a saved locale, and read what was saved with `t.storage()`:
+
+```jsx
+// App.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { App } from './App.jsx'
+
+const text = (t, selector) => t.query(selector).textContent.replace(/\s/g, ' ')
+
+test('restores the saved locale, pluralises, switches language and saves it', async () => {
+  const t = renderComponent(App, { storage: { locale: { version: 1, state: { locale: 'fr' } } } })
+  await t.ready()
+  expect(text(t, 'h1')).toBe('Bonjour, Ada !')
+  expect(text(t, '.count')).toBe('0 article')
+
+  t.simulateEvent('.add', 'click')
+  t.simulateEvent('.add', 'click')
+  await t.next((state) => state.cart.items === 2)
+  expect(text(t, '.count')).toBe('2 articles')
+  expect(text(t, '.total')).toBe('Total : 9,00 €')
+
+  t.simulateEvent('.locale', 'change', { value: 'en' })
+  await t.next((state) => state.locale === 'en')
+  expect(text(t, 'h2')).toBe('Your cart')
+  expect(text(t, '.count')).toBe('2 items')
+  expect(text(t, '.total')).toBe('Total: €9.00')
+  expect(t.query('main').getAttribute('lang')).toBe('en')
+
+  await t.settle()
+  expect(t.storage('locale')).toEqual({ version: 1, state: { locale: 'en' } })
+  t.dispose()
+})
+```
+
+`Intl` puts non-breaking spaces in French numbers and punctuation ("9,00 €", "Ada !"); the `text` helper turns them into plain spaces before comparing.
+
+A component further down reads `t` from the context, which comes from its ancestors. To test it alone, pass its state and the context its ancestors would give it ([`renderComponent`'s `context`](https://sygnal.js.org/integration/testing/#context)):
+
+```jsx
+// Cart.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Cart } from './Cart.jsx'
+import { translator } from './i18n.js'
+
+test('the cart in French', async () => {
+  // the state and the context the app would give it
+  const t = renderComponent(Cart, { initialState: { items: 1 }, context: { t: translator('fr') } })
+  await t.ready()
+  expect(t.query('.count').textContent).toBe('1 article')
+  t.simulateEvent('.add', 'click')
+  await t.next((state) => state.items === 2)
+  expect(t.query('.count').textContent).toBe('2 articles')
+  t.dispose()
+})
+```
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included: **15.5 KB** for i18next and this recipe (the translations are part of it). Larger apps keep each language in its own JSON file and load only the chosen one (below).
+
+## Pitfalls
+
+- **Don't call `i18n.changeLanguage()`.** It changes a global inside i18next that Sygnal doesn't see, so nothing re-renders. Keep the locale in state and use `getFixedT`.
+- **Keep `t` stable per locale.** `getFixedT` returns a new function on each call. Called directly in `.context`, it gives the context a new value whenever the root's state changes, not only when the locale does; `translator` hands out the same function until the locale changes.
+- **Load translations before switching.** With translations in separate files, fetch the new language first (a `makeFetchDriver` request on the `LOCALE` action), add it with `i18n.addResourceBundle(locale, 'translation', data)` in an `EFFECT` of the reply's action (a reducer only returns state), and only then put the new locale in state (the same action's `STATE` entry: the `EFFECT` runs synchronously and the view renders after the whole action, so the strings are there). A locale whose strings aren't loaded shows the keys.
+- **Server rendering.** Take the locale from the request (the URL or `Accept-Language`) and pass it in the server's state. A locale saved only in `localStorage` reaches a server-rendered page after hydration, as a `RESTORE` action: the page shows the server's language first.
+- **Missing keys show the key.** `t('cart.titel')` renders "cart.titel". Set `saveMissing` with a `missingKeyHandler` in development to log them.

package/dist/guide/recipes/icons.md

@@ -0,0 +1,115 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Icons (Lucide)
+
+[Lucide](https://lucide.dev/) has about 1,600 icons. Its framework-neutral package, `lucide`, exports each icon as plain data: a list of SVG elements and their attributes. A small helper turns that data into Sygnal SVG vnodes, so an icon is part of the view like any other markup: it is patched, server-rendered and tested in the mock DOM.
+
+## Install
+
+```sh
+npm install lucide
+```
+
+## The helper
+
+```jsx live-file=./icon.jsx
+// icon.jsx
+// A Lucide icon (an array of [tag, attributes, children?]) as Sygnal SVG vnodes
+const parts = (node) => node.map(([Tag, attrs, children]) => <Tag {...attrs}>{children && parts(children)}</Tag>)
+
+export function icon(node, { label, size = 24 } = {}) {
+  return (
+    <svg className="icon" width={size} height={size} viewBox="0 0 24 24" fill="none" stroke="currentColor"
+      stroke-width="2" stroke-linecap="round" stroke-linejoin="round"
+      role={label ? 'img' : undefined} aria-label={label} aria-hidden={label ? undefined : 'true'}>
+      {parts(node)}
+    </svg>
+  )
+}
+```
+
+`icon` is a plain function that returns vnodes, not a component: call it in the view (`{icon(Plus)}`), don't render it as a tag. A component per icon would cost an instance, a state and a stream for each one, for markup that never changes.
+
+The `<svg>` gets Lucide's default attributes (a 24 × 24 view box, a 2-pixel round stroke in `currentColor`, so the icon takes the text colour). Inside an `<svg>`, Sygnal's JSX sets every prop as an attribute in the SVG namespace, so the data's `d`, `cx` or `points` work as written.
+
+## Using it
+
+```jsx live
+// Toolbar.jsx
+import { Plus, Trash2, CloudCheck, CloudOff } from 'lucide'
+import { icon } from './icon.jsx'
+
+export function Toolbar({ state }) {
+  return (
+    <div role="toolbar" aria-label="Items">
+      <button className="add">{icon(Plus)} Add</button>
+      <button className="remove" aria-label="Remove the last item">{icon(Trash2)}</button>
+      <span className="status">
+        {state.online ? icon(CloudCheck, { label: 'Saved' }) : icon(CloudOff, { label: 'Offline' })}
+      </span>
+      <span className="count">{state.count} items</span>
+    </div>
+  )
+}
+
+Toolbar.initialState = { count: 0, online: true }
+
+Toolbar.intent = ({ DOM }) => ({
+  ADD: DOM.click('.add'),
+  REMOVE: DOM.click('.remove'),
+})
+
+Toolbar.model = {
+  ADD: (state) => ({ ...state, count: state.count + 1 }),
+  REMOVE: (state) => ({ ...state, count: Math.max(0, state.count - 1) }),
+}
+```
+
+Three cases, three ways to make the icon accessible:
+
+| Icon | Example | How |
+|---|---|---|
+| Next to text that says the same | **Add** | Decorative: no label, so the helper sets `aria-hidden="true"`. |
+| The only content of a button or link | **Remove** | The button carries the name (`aria-label`); the icon stays hidden. |
+| Meaning on its own, no text | **Saved / Offline** | Pass `label`: the icon gets `role="img"` and an `aria-label`. |
+
+sygnal-check reports a button with no accessible name ([SYG705](https://sygnal.js.org/reference/errors/#syg705)) when the `<svg>` is written inside it, and when its only content is an `icon(...)` call with an icon imported from `lucide` (or another icon package) and no `label`: `<button>{icon(Trash2)}</button>` is reported, `<button aria-label="Remove">{icon(Trash2)}</button>` is not. Only `label` names the icon, as in the helper above (`title` or `aria-label` in the options are ignored by the helper, so they don't count). It knows only a function named `icon` (or `renderIcon`); a helper with another name, or an icon passed through a variable, isn't checked, so assert the button's name in a test as below. If your own `icon` helper renders screen-reader text itself, put the name on the button instead, or silence the line with `// sygnal-ignore SYG705`.
+
+```css live
+.icon { vertical-align: -0.125em; width: 1.25em; height: 1.25em; }
+```
+
+## Testing
+
+```jsx
+// Toolbar.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Toolbar } from './Toolbar.jsx'
+
+test('decorative icons are hidden, a meaningful icon has a name', async () => {
+  const t = renderComponent(Toolbar)
+  await t.ready()
+  expect(t.query('.add svg').getAttribute('aria-hidden')).toBe('true')
+  expect(t.query('.remove svg').getAttribute('aria-hidden')).toBe('true')
+  expect(t.query('.remove').getAttribute('aria-label')).toBe('Remove the last item')
+  expect(t.query('.status svg').getAttribute('role')).toBe('img')
+  expect(t.query('.status svg').getAttribute('aria-label')).toBe('Saved')
+  expect(t.queryAll('.add svg path').length).toBe(2)
+
+  t.simulateEvent('.add', 'click')
+  await t.next((state) => state.count === 1)
+  expect(t.query('.count').textContent).toBe('1 items')
+  t.dispose()
+})
+```
+
+## Size
+
+Each icon is a few hundred bytes. Measured with Vite, minified and gzipped, Sygnal not included: the four icons and the helper above add **0.9 KB**. Import icons by name (`import { Plus } from 'lucide'`) so the bundler drops the rest.
+
+## Pitfalls
+
+- **Don't look icons up by name at runtime.** `import { icons } from 'lucide'` and `icons[name]` keep every icon in the bundle: 94 KB instead of 0.9. Map the names you need yourself: `const STATUS = { saved: CloudCheck, offline: CloudOff }`.
+- **Don't use `createIcons()`.** It replaces `<i data-lucide="...">` elements in the page with SVG after the fact; Sygnal owns those elements and puts its own back on the next render. `createElement(Plus)` from `lucide` returns a DOM element, which is useful inside a [widget](../widgets.md)'s `mount`, not in a view.
+- **Icon-only buttons need a name.** The icon is hidden from screen readers, so the button must say what it does.
+- **Not `lucide-react`.** The React package returns React elements; use `lucide`, whose icons are plain data.

package/dist/guide/recipes/overview.md

@@ -0,0 +1,33 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Recipes
+
+Most JavaScript UI libraries don't need a Sygnal version. A library that builds its UI inside an element you give it becomes a JSX tag with [`defineWidget`](../widgets.md); a library that only computes (a table model, a translation) is called from the view or the context, as a pure function of state. Each recipe shows the code, how to test it, what it adds to the bundle, and the mistakes to avoid.
+
+| Recipe | Library | How |
+|---|---|---|
+| [Charts](./charts.md) | Chart.js, ECharts | Widget |
+| [Rich text](./rich-text.md) | Tiptap | Widget, toolbar as element commands |
+| [Code editor](./code-editor.md) | CodeMirror 6 | Widget, `focus` command |
+| [Carousel](./carousel.md) | Embla Carousel | Widget, previous/next as element commands |
+| [Data table](./data-table.md) | TanStack Table v9 | A pure function of state in the view |
+| [Data grid](./data-grid.md) | AG Grid Community | Widget, immutable row data |
+| [Icons](./icons.md) | Lucide | A helper that returns Sygnal SVG vnodes |
+| [Translations (i18n)](./i18n.md) | i18next | `t()` in `.context`, the locale saved with `persist()` |
+
+Elsewhere in the docs:
+
+- **Positioning** (tooltips, popovers, menus) with Floating UI: [Floating UI for older browsers](../ui/overview.md#floating-ui-for-older-browsers). Current browsers position `sygnal/ui` parts with CSS anchor positioning and need no library.
+- **List animations** with AutoAnimate and Motion: [View Transitions](https://sygnal.js.org/guide/view-transitions/#recipe-autoanimate).
+- **Date pickers** (flatpickr): the [Widgets](../widgets.md) guide's example.
+- **Web components** (Web Awesome, Shoelace): no wrapper needed, see [Web components](../web-components.md).
+- **Forms with validation** (zod, valibot): the [`form` behavior](../forms.md).
+
+## Choosing a pattern
+
+- **The library owns some DOM** (a canvas, an editor, a slider): `defineWidget`. Sygnal renders the host element and never touches what the library builds inside it. Props flow in through `update`, events flow out through `dispatch` and the intent, and the model calls the library's methods through the widget's `commands`.
+- **The library only computes** (rows to show, a translated string, an icon's shape): call it in the view or in `.context`, and render the result with JSX. Sygnal keeps rendering the DOM, so the output is ordinary markup: it is server-rendered, tested in the mock DOM, and checked by sygnal-check.
+- **The library is a framework component** (React, Vue): see [Adapters](../adapters.md), and look for a framework-agnostic core first (most headless libraries have one).
+
+## Size numbers
+
+Each recipe gives what it adds to an app, measured with Vite (minified, gzipped), Sygnal itself not included. `defineWidget` adds about 1.1 KB the first time an app uses it.

package/dist/guide/recipes/rich-text.md

@@ -0,0 +1,154 @@
+<!-- Generated from docs/src/content/docs/recipes by scripts/copy-guides.mjs; online: https://sygnal.js.org/recipes/ -->
+# Rich Text (Tiptap)
+
+[Tiptap](https://tiptap.dev/) is a rich-text editor built on ProseMirror. Its core doesn't depend on a framework, so [`defineWidget`](../widgets.md) turns it into a JSX tag: the document is HTML in your state, each edit comes back as an event, and toolbar buttons run the editor's commands through [element commands](../element-commands.md).
+
+## Install
+
+```sh
+npm install @tiptap/core @tiptap/pm @tiptap/starter-kit
+```
+
+## The widget
+
+```js live-file=./RichText.js
+// RichText.js
+import { defineWidget } from 'sygnal'
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+
+const editorProps = (props) => ({ attributes: { role: 'textbox', 'aria-multiline': 'true', 'aria-label': props.label } })
+
+// the state gets the HTML as Tiptap writes it ('Hi' → '<p>Hi</p>'), so update() doesn't see a
+// difference and reset the content (and the selection) on the next prop change
+const dispatches = new WeakMap()
+const normalise = (editor, html) => {
+  if (editor.getHTML() !== html) dispatches.get(editor)('edit', editor.getHTML())
+}
+
+export const RichText = defineWidget({
+  name: 'RichText',
+  mount: (el, props, dispatch) => {
+    const editor = new Editor({
+      element: el,
+      extensions: [StarterKit],
+      content: props.html,
+      editorProps: editorProps(props),
+      onUpdate: ({ editor }) => dispatch('edit', editor.getHTML()),
+    })
+    dispatches.set(editor, dispatch)
+    normalise(editor, props.html)
+    return editor
+  },
+  update: (editor, props) => {
+    if (props.html !== editor.getHTML()) {
+      editor.commands.setContent(props.html, { emitUpdate: false })
+      normalise(editor, props.html)
+    }
+    // a new label (another language): Tiptap's options are read at mount, so set them again
+    if (props.label !== editor.options.editorProps.attributes['aria-label']) editor.setOptions({ editorProps: editorProps(props) })
+  },
+  unmount: (editor) => editor.destroy(),
+  events: ['edit'],
+  commands: {
+    bold: (editor) => editor.chain().focus().toggleBold().run(),
+    italic: (editor) => editor.chain().focus().toggleItalic().run(),
+  },
+})
+```
+
+- `mount` creates the editor inside the host `<div>`. Tiptap adds its own editable element there; `editorProps.attributes` labels it.
+- `onUpdate` runs after each change the user makes and sends the new HTML as the `edit` event.
+- `update` gets the HTML from state. When the user typed it, it is what the editor already holds and nothing happens. When the state changed it some other way (a reset, a loaded draft), `setContent` replaces the document, with `emitUpdate: false` so the change isn't sent back as an edit.
+- The `bold` and `italic` commands run Tiptap commands on the instance. `focus()` comes first because clicking a toolbar button moves the focus to the button.
+
+## Using it
+
+```jsx live
+// Notes.jsx
+import { RichText } from './RichText.js'
+
+export function Notes({ state }) {
+  return (
+    <section>
+      <div role="toolbar" aria-label="Formatting">
+        <button type="button" className="make-bold">Bold</button>
+        <button type="button" className="make-italic">Italic</button>
+        <button type="button" className="clear">Clear</button>
+      </div>
+      <RichText className="body" label="Notes" html={state.html} />
+      <p className="saved">{state.html.length} characters saved</p>
+    </section>
+  )
+}
+
+Notes.initialState = { html: '<p>Hello</p>' }
+
+Notes.intent = ({ DOM }) => ({
+  EDIT: DOM.select('.body').events('edit').detail(),
+  BOLD: DOM.click('.make-bold'),
+  ITALIC: DOM.click('.make-italic'),
+  CLEAR: DOM.click('.clear'),
+})
+
+Notes.model = {
+  EDIT: (state, html) => ({ ...state, html }),
+  BOLD: { ELEMENT: { bold: '.body' } },
+  ITALIC: { ELEMENT: { italic: '.body' } },
+  CLEAR: (state) => ({ ...state, html: '<p></p>' }),
+}
+```
+
+```css live
+.body .tiptap { border: 1px solid #8888; border-radius: 4px; padding: 0 0.75rem; min-height: 6rem; }
+```
+
+Tiptap brings no styles of its own. Its editable element has the class `tiptap`: give it a border and a height, so it looks like a place to type.
+
+The label is a prop of its own (`label`), not `aria-label`: an `aria-label` prop would go on the host `<div>`, and the element a screen reader lands on is Tiptap's editable element inside it. Tiptap reads its options when it starts, so `update` sets them again when the label changes (a translated label after a language switch).
+
+Tiptap writes HTML its own way (`Hello` becomes `<p>Hello</p>`). `mount` sends the editor's HTML back as an `edit` when it differs from the `html` prop, so the state holds what the editor holds; otherwise the next prop change (a new label) would see a difference and reset the content.
+
+To save the notes across reloads, add [`persist()`](../persistence.md) to the root and pick `html`.
+
+## Testing
+
+In the mock DOM, `t.widget('.body')` sends the editor's events, and `t.commands()` lists the element commands the toolbar sent:
+
+```jsx
+// Notes.test.jsx
+import { test, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Notes } from './Notes.jsx'
+
+test('edits reach the state, and the toolbar sends commands to the editor', async () => {
+  const t = renderComponent(Notes)
+  await t.ready()
+  t.widget('.body').dispatch('edit', '<p>Hello <strong>you</strong></p>')
+  await t.next((state) => state.html === '<p>Hello <strong>you</strong></p>')
+
+  t.simulateEvent('.make-bold', 'click')
+  t.simulateEvent('.make-italic', 'click')
+  await t.settle()
+  expect(t.commands()).toEqual([{ bold: '.body' }, { italic: '.body' }])
+
+  t.simulateEvent('.clear', 'click')
+  await t.next((state) => state.html === '<p></p>')
+  expect(t.widget('.body').props.html).toBe('<p></p>')
+  t.dispose()
+})
+```
+
+Tiptap also starts in jsdom: with `renderComponent(Notes, { dom: 'real' })`, `t.widget('.body').instance` is the editor, and `t.dispose()` destroys it (`editor.isDestroyed`). Typing and selecting text need a real browser (Playwright); there, select a word, click **Bold**, and the state's HTML gets a `<strong>`.
+
+## Size
+
+Measured with Vite, minified and gzipped, Sygnal not included: Tiptap with `StarterKit` (paragraphs, headings, lists, code, quotes, marks, history) adds **128 KB**. Pass only the extensions you need instead of `StarterKit` to make it smaller. `defineWidget` adds 1.1 KB for the first widget in an app.
+
+## Pitfalls
+
+- **Compare before `setContent`.** Without the `props.html !== editor.getHTML()` check, every keystroke would set the content again and move the cursor to the end.
+- **Tiptap normalises HTML.** `getHTML()` returns the editor's own serialisation (`<p>Hello</p>`, an empty document is `<p></p>`), which may differ from the HTML you started with. Store what `getHTML()` returns; then the comparison in `update` holds. The widget does this for HTML that comes from state: after `mount` and after a `setContent` in `update`, it sends an `edit` with the normalised HTML when it differs, so a later prop change (a new label) doesn't set the content again and lose the selection.
+- **Keep `emitUpdate: false`.** Without it, a reset from state comes back as an `edit` event: harmless here (the same HTML), but a second action for every external change.
+- **Toolbar state.** To show which marks are active (`aria-pressed` on the Bold button), add an `onSelectionUpdate` / `onTransaction` callback that dispatches `editor.isActive('bold')` as an event of its own, and keep it in state.
+- **Untrusted HTML.** Tiptap only keeps what its extensions know, but HTML you save and show elsewhere (`innerHTML`) still needs sanitising there.