sygnal 5.4.0 → 6.1.0

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,43 @@
+<!-- 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).
+
+## AI
+
+Recipes for [`sygnal/ai`](../ai-chat.md): models through the chat driver and decision requests, no library beyond a schema validator.
+
+| Recipe | Model | How |
+|---|---|---|
+| [Support inbox](./ai-support-inbox.md) | A decision model, a chat model for the unsure tickets | A `decide()` resource per Collection item, escalation with structured output |
+| [Structured output into a form](./ai-form-fill.md) | A chat model | `output` schema, `form.CHANGE` per extracted field |
+| [On-device summaries](./ai-summarize.md) | Chrome's built-in model | `chromePrompt()`, an excerpt where it is unavailable |
+
+## 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.