sygnal 5.3.7 → 6.0.0

package/dist/guide/accessibility.md

@@ -0,0 +1,257 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Accessibility
+
+`sygnal-check` has an accessibility lane, SYG701 to SYG708 and SYG722. It finds the markup mistakes that lock keyboard and screen-reader users out without any visible sign: a clickable `<div>`, a field without a label, an icon button with no name. Like the other checks, it reads your source, so it works the same in the editor, in CI and in the dev server.
+
+## Severity
+
+- **Warning** by default: `npx --no-install sygnal-check` prints the findings and exits with code 1, like any other warning.
+- **Still a warning under `--strict`.** Strict mode checks the canonical forms; it doesn't turn markup that already shipped into errors when you upgrade.
+- **Error** when you ask for it: `sygnal-check --a11y=error`, `check(paths, { a11y: 'error' })`, or `check: { a11y: 'error' }` in the [Vite plugin](https://sygnal.js.org/integration/bundler-config/#plugin-options), where errors also open Vite's error overlay. Use it in CI once an app is clean.
+- **On in the dev server**: the Vite plugin runs `sygnal-check` when it is installed, so the findings appear in the terminal and the browser console as you edit.
+
+The checks are static only: markup that is built at runtime (spread props, a dynamic `type` or `role`) is skipped rather than guessed at.
+
+To keep one finding on purpose, put `// sygnal-ignore SYG70x` on the line above it, or at the end of the line (see [Suppressing a finding](#suppressing-a-finding)).
+
+## The rules
+
+Each example shows the flagged form as a comment, then the fix.
+
+### SYG701: click listener on a non-interactive element
+
+The intent listens for clicks on a `<div>`, `<span>`, `<li>`, `<p>`, `<img>` or similar without a `role` and `tabIndex`. Mouse users can click it; keyboard users can't reach it, and screen readers don't announce it as something to activate. Render a button instead:
+
+```jsx
+// Flagged:
+// function Card({ state }) { return <div className="card">{state.title}</div> }
+
+function Card({ state }) {
+  return <button type="button" className="card">{state.title}</button>
+}
+
+Card.intent = ({ DOM }) => ({ OPEN: DOM.click('.card') })
+Card.model = { OPEN: (state) => ({ ...state, open: true }) }
+```
+
+If the element must stay a `<div>`, give it `role="button"` and `tabIndex={0}`, and handle Enter and Space too:
+
+```jsx
+import { xs } from 'sygnal'
+
+function Card({ state }) {
+  return <div className="card" role="button" tabIndex={0}>{state.title}</div>
+}
+
+Card.intent = ({ DOM }) => ({
+  OPEN: xs.merge(
+    DOM.click('.card'),
+    DOM.keydown('.card').filter(e => e.key === 'Enter' || e.key === ' '),
+  ),
+})
+Card.model = { OPEN: (state) => ({ ...state, open: true }) }
+```
+
+The rule applies to a [control](https://sygnal.js.org/guide/controls/)'s element too (`controls({ Card: 'div' })` listened to for clicks: declare it as `'button'`). An element that contains a button, link or form field isn't flagged, since a click on those bubbles up to the listener.
+
+### SYG702: form field without a label
+
+An `<input>`, `<select>` or `<textarea>` has no accessible name, so a screen reader announces only "edit text". Wrap it in a `<label>`, link a `<label for>` to its `id` (with [`uid()`](#ids-with-uid), below), or, for a field with no visible label, add `aria-label`:
+
+```jsx
+// Flagged: <input className="search" type="search" value={state.query} />
+
+function Search({ state }) {
+  return <input className="search" type="search" aria-label="Search tasks" value={state.query} />
+}
+
+Search.initialState = { query: '' }
+Search.intent = ({ DOM }) => ({ QUERY: DOM.input('.search').value() })
+Search.model = { QUERY: (state, query) => ({ ...state, query }) }
+```
+
+A `placeholder` counts as a last-resort name, but it disappears as soon as the user types; prefer a visible label.
+
+### SYG703: image without alt text
+
+Every `<img>` needs `alt`. Describe what the image shows, or use `alt=""` for a decorative image, which screen readers then skip:
+
+```jsx
+// Flagged: <img src={state.avatarUrl} />
+
+function Profile({ state }) {
+  return (
+    <div>
+      <img src={state.avatarUrl} alt={state.name} />
+      <img src="/divider.svg" alt="" />
+    </div>
+  )
+}
+```
+
+### SYG704: link without href used as a button
+
+An `<a>` without `href` is not focusable and is announced as plain text. Use a button for an action, and keep `<a href>` for navigation:
+
+```jsx
+// Flagged: <a className="more">Show more</a> with DOM.click('.more')
+
+function Comments({ state }) {
+  return (
+    <div>
+      <p>{state.shown} of {state.total} comments</p>
+      <button type="button" className="more">Show more</button>
+    </div>
+  )
+}
+
+Comments.intent = ({ DOM }) => ({ MORE: DOM.click('.more') })
+Comments.model = { MORE: (state) => ({ ...state, shown: Math.min(state.total, state.shown + 10) }) }
+```
+
+### SYG705: button without an accessible name
+
+A button whose only content is an icon is announced as just "button". Add `aria-label`, and hide the icon from screen readers:
+
+```jsx
+// Flagged: <button type="button" className="close"><span>×</span></button>, no name for "×"...
+// ...and an icon with no text: <button type="button" className="close"><i className="icon-x" /></button>
+
+function Banner({ state }) {
+  return (
+    <div role="status">
+      {state.message}
+      <button type="button" className="close" aria-label="Dismiss">
+        <i className="icon-x" aria-hidden="true" />
+      </button>
+    </div>
+  )
+}
+
+Banner.intent = ({ DOM }) => ({ DISMISS: DOM.click('.close') })
+Banner.model = { DISMISS: (state) => ({ ...state, message: '' }) }
+```
+
+Only literal content is checked: a button whose children include an expression (`{state.label}`) or a component isn't flagged.
+
+### SYG706: positive tabIndex
+
+`tabIndex={1}` and higher move the element ahead of everything else in the Tab order. Use `tabIndex={0}` (focusable in document order) or `tabIndex={-1}` (focusable only from code), and change the markup order to change the Tab order:
+
+```jsx
+// Flagged: <div className="preview" tabIndex={1}>…</div>
+
+function Preview({ state }) {
+  return <div className="preview" tabIndex={0} aria-label="Preview">{state.html}</div>
+}
+```
+
+### SYG707: unknown ARIA attribute or invalid role
+
+A misspelled `aria-*` attribute, or a `role` that isn't a WAI-ARIA role (including abstract roles such as `widget`), is ignored by assistive technology. The message suggests the closest valid name:
+
+```jsx
+// Flagged: aria-labeledby (a typo), role="widget" (abstract)
+
+function Tabs({ state }) {
+  return (
+    <div>
+      <h2 id="tabs-title">Settings</h2>
+      <div role="tablist" aria-labelledby="tabs-title">
+        {state.tabs.map(tab => <button type="button" role="tab" aria-selected={String(tab === state.current)}>{tab}</button>)}
+      </div>
+    </div>
+  )
+}
+```
+
+### SYG708: label or ARIA reference to an id that isn't rendered
+
+A `<label for>`, `aria-describedby` or `aria-labelledby` names an id that no element has, so the label is attached to nothing. This usually comes from an id renamed on one side only. Inside a component, use `uid()` on both sides:
+
+```jsx
+// Flagged: <input id="email" … /> with <label for="e-mail">
+
+function EmailField({ state, uid }) {
+  return (
+    <p>
+      <label for={uid('email')}>Email</label>
+      <input id={uid('email')} type="email" className="email" value={state.email} aria-describedby={uid('email-error')} />
+      {state.error && <span id={uid('email-error')}>{state.error}</span>}
+    </p>
+  )
+}
+
+EmailField.initialState = { email: '', error: '' }
+EmailField.intent = ({ DOM }) => ({ EMAIL: DOM.input('.email').value() })
+EmailField.model = { EMAIL: (state, email) => ({ ...state, email, error: email.includes('@') ? '' : 'Enter an email address' }) }
+```
+
+A `uid('x')` reference needs an element in the same component with `id={uid('x')}`; a literal id may be anywhere in the checked files.
+
+### SYG722: Menu, Select or Combobox without an accessible name
+
+A [Menu](./ui/menu.md), [Select](./ui/select.md) or [Combobox](./ui/combobox.md) without `label`, `aria-label` or `aria-labelledby`. The part names its control from them (Menu's trigger text is its `label`), so without one the menu button or combobox is announced without a name. Give it a visible `label`; when the label is elsewhere, point at it with `aria-labelledby`; for an icon-only menu trigger, use `aria-label`:
+
+```jsx
+import { Select } from 'sygnal/ui/select'
+import { Menu } from 'sygnal/ui/menu'
+
+// Flagged: <Select className="size" items={SIZES} />
+
+function Sizes({ state }) {
+  return (
+    <div>
+      <Select className="size" label="Size" items={['S', 'M', 'L']} value={state.size} />
+      <Menu className="more" label="⋯" aria-label="More actions" items={['Duplicate', 'Delete']} />
+    </div>
+  )
+}
+
+Sizes.initialState = { size: null }
+Sizes.intent = ({ DOM }) => ({ SIZE: DOM.select('.size').events('value-change').detail() })
+Sizes.model = { SIZE: (state, size) => ({ ...state, size }) }
+```
+
+## ARIA values in JSX
+
+An `aria-*` attribute set to `true` renders `"true"`. Set to `false`, it renders `"false"` on the ARIA states that have a false value (`aria-expanded`, `aria-hidden`, `aria-pressed`, `aria-checked`, `aria-selected`, `aria-disabled`, `aria-invalid`, `aria-current`, `aria-haspopup`, `aria-busy`, `aria-modal`, `aria-required`, `aria-readonly`, `aria-multiline`, `aria-multiselectable`, `aria-atomic`, `aria-grabbed`); on any other `aria-*` (a label, an id reference, a number) `false` removes the attribute, so `aria-describedby={hasError && uid('error')}` doesn't announce "false". `null` and `undefined` remove it. Passed to a component, `role`, `for`, `tabindex` and `aria-*` are ordinary props: the component gets the value as written.
+
+## Ids with uid()
+
+Labels and ARIA references need ids, and ids must be unique on the page, which a literal id isn't once the component is rendered twice. Every view gets a `uid` prop: `uid()` is an id for this component instance, and `uid('email')` an id derived from it. They are stable across renders and the same on the server and the client, so they are safe with [SSR](./ssr.md#stable-ids-uid). See [Forms](./inputs.md#labels-and-ids-uid) for a full example. The checks understand `uid()`: SYG702 and SYG708 match `for={uid('email')}` with `id={uid('email')}`.
+
+## Suppressing a finding
+
+A comment on the line above (or at the end of the line) suppresses one finding:
+
+```jsx
+import { xs } from 'sygnal'
+
+function Dialog({ state }) {
+  return (
+    <div>
+      <div className="backdrop" />
+      <div role="dialog" aria-modal="true" aria-label="Settings">{state.body}</div>
+    </div>
+  )
+}
+
+Dialog.intent = ({ DOM }) => ({
+  CLOSE: xs.merge(
+    // a mouse shortcut: keyboard users close the dialog with Escape
+    // sygnal-ignore SYG701
+    DOM.click('.backdrop'),
+    DOM.keydown('document').key().filter(key => key === 'Escape'),
+  ),
+})
+Dialog.model = { CLOSE: { PARENT: () => 'closed' } }
+```
+
+A backdrop that closes a dialog on click is a common case: the dialog itself is reachable, and keyboard users close it with Escape. Without codes, `// sygnal-ignore` suppresses every code on that line. To turn a rule off for the dev server, add it to the Vite plugin's ignore list: `sygnal({ check: { ignore: ['SYG705'] } })`.
+
+## Related
+
+- [Error Reference](https://sygnal.js.org/reference/errors/#syg701): every SYG7xx code, its cause and its fix
+- [Diagnostics](https://sygnal.js.org/guide/diagnostics/#the-static-checker): running `sygnal-check`
+- [Forms](./forms.md): validation and server errors; [Inputs, Labels and Focus](./inputs.md): labels, controlled inputs and focus

package/dist/guide/adapters.md

@@ -0,0 +1,221 @@
+<!-- Generated from docs/src/content/docs/guide by scripts/copy-guides.mjs; online: https://sygnal.js.org/guide/ -->
+# Adapters
+
+An adapter turns code written for another model into a Sygnal [widget](./widgets.md) tag: you render it with a class, read its events in the intent with `.detail()`, and send it [element commands](./element-commands.md), as with any widget.
+
+- **`fromZag`** (`sygnal/zag`) runs a [Zag.js](https://zagjs.com) state machine and renders its parts with Sygnal JSX. It is what [Menu](./ui/menu.md), [Select](./ui/select.md) and [Combobox](./ui/combobox.md) are built on.
+- **`fromReact`** (`sygnal/react`) renders a React component, or a Preact one through `preact/compat`.
+
+**Adapters are an escape hatch.** Reach for one for the component you can't replace, not as a way to build the app. First look for a native answer (`<dialog>`, the Popover API, [`sygnal/ui`](./ui/overview.md)), a [web component](./web-components.md), or a framework-agnostic library through [`defineWidget`](./widgets.md). A React component in a Sygnal app:
+
+- **brings its runtime**: React and react-dom add about 68 KB gzipped (Preact through `preact/compat` about 8 KB);
+- **doesn't see your context or providers**: React context, a theme provider, a router or a query client from a React tree don't cross the boundary, and Sygnal's `.context` doesn't reach the component. Pass what it needs as props;
+- **can render outside its host**: a React portal (a modal, a tooltip) goes where React puts it, so Sygnal's `DOM.select` doesn't see events from it; use the component's callbacks instead;
+- **doesn't run in the mock DOM**: test it with `renderComponent(App, { dom: 'real' })` (jsdom or a browser).
+
+The libraries are optional peer dependencies of `sygnal`: an app that doesn't import an adapter never installs or ships them. When one is missing, `sygnal/vite` names it ([SYG666](https://sygnal.js.org/reference/errors/#syg666)).
+
+## React components: fromReact
+
+```bash
+npm install react react-dom
+```
+
+The React component here is a small one of our own, written with React's `createElement` (the JSX on these pages is Sygnal's); a component from npm is wrapped the same way:
+
+```js live-file=./Rating.js
+// Rating.js: a React component
+import { createElement as h } from 'react'
+
+export function Rating({ value, max, onChange }) {
+  return h('span', { role: 'group', 'aria-label': 'Rating' },
+    Array.from({ length: max }, (_, i) => h('button', {
+      key: i, type: 'button', 'aria-label': `${i + 1} of ${max}`, 'aria-pressed': i < value, onClick: () => onChange(i + 1),
+    }, i < value ? '★' : '☆')))
+}
+```
+
+```jsx live-file=./Stars.js
+// Stars.js
+import { fromReact } from 'sygnal/react'
+import { Rating } from './Rating.js'
+
+export const Stars = fromReact(Rating, { events: { rate: 'onChange' } })
+```
+
+```jsx live
+// Review.jsx
+import { Stars } from './Stars.js'
+
+export function Review({ state }) {
+  return (
+    <div>
+      <Stars className="rating" value={state.rating} max={5} />
+      <p>{state.rating} of 5</p>
+    </div>
+  )
+}
+
+Review.initialState = { rating: 0 }
+Review.intent = ({ DOM }) => ({
+  RATE: DOM.select('.rating').events('rate').detail(),
+})
+Review.model = {
+  RATE: (state, rating) => ({ ...state, rating }),
+}
+```
+
+The tag renders a host `<div class="rating">` and a React root inside it. Every render passes the newest props to the component (`value`, `max`); the props are routed between the host and the component:
+
+| Props | Go to |
+|---|---|
+| `className`, `class`, `id`, `style`, `attrs`, `tabIndex`, `hidden` | the host only (one tab stop) |
+| `aria-*`, `role`, `title` | the component only: a React control names itself, so `<IconButton aria-label="Delete" />` labels the component's `<button>`, not the generic host `<div>` |
+| `data-*` | both |
+| everything else | the component (`name`, `placeholder`, `lang` and `dir` also go on the host, as for any widget) |
+
+List a host prop in `ownProps` to send it to the component instead, or a component-only one in `hostProps` to put it on the host too. A React component that doesn't pass `aria-*` and `role` on to its element (it takes only the props it names) gets no accessible name this way: fix the component to spread them, or list them in `hostProps` (`hostProps: ['role', 'aria-label']`) so the host carries the role and the name. When the component calls `onChange(4)`, the adapter dispatches a `rate` event on the host with `4` as its detail.
+
+When the host leaves the page (also inside a shadow root, as with `sygnal/element`'s `shadow: true`), the React root unmounts. A host can also be destroyed while its element stays in the page, for example during a `<Transition>` leave that never gets its `transitionend`. The React root then stays mounted until the element is removed, and for at most 10 seconds, so no root or observer is leaked. A component's cleanup (`useEffect` returns) can therefore run up to 10 seconds after the host was destroyed.
+
+| Option | |
+|---|---|
+| `events` | `{ eventName: 'onCallback' }`: each callback prop becomes a DOM event with that name. An array (`['onChange']`) uses the callback's own name as the event name. The detail is the callback's argument, or an array of them when it gets several. A callback you pass as a prop still runs, first |
+| `props` | `(props) => componentProps`, when the component's props differ from the tag's |
+| `commands` | Element commands, called with `{ root, el, props }` |
+| `tag`, `name`, `fallback`, `hostProps`, `ownProps` | As in [`defineWidget`](./widgets.md#the-definition) |
+
+Prefer event names of your own (`'rate'`) to the browser's (`'change'`): the component's own `<input>`s fire native `change` events that bubble out of the host too.
+
+### Preact
+
+The adapter uses only `createElement` (from `react`), `createRoot` (from `react-dom/client`) and `flushSync` (from `react-dom`), which `preact/compat` provides. Alias the React packages in the bundler, and the same adapter and the same component code run on Preact:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import sygnal from 'sygnal/vite'
+
+export default defineConfig({
+  plugins: [sygnal()],
+  resolve: {
+    alias: {
+      react: 'preact/compat',
+      'react-dom/client': 'preact/compat/client',
+      'react-dom': 'preact/compat',
+    },
+  },
+})
+```
+
+```bash
+npm install preact
+```
+
+## Zag machines: fromZag
+
+[Zag.js](https://zagjs.com) implements UI patterns (menus, comboboxes, date pickers, sliders) as framework-agnostic state machines, with the keyboard and ARIA work done. `fromZag(zag, render, options)` runs one on a widget host:
+
+```bash
+npm install @zag-js/vanilla@~1.45.0 @zag-js/menu@~1.45.0
+```
+
+```jsx live-file=./Actions.jsx
+// Actions.jsx
+import { fromZag } from 'sygnal/zag'
+import * as menu from '@zag-js/menu'
+
+export const Actions = fromZag(menu, (api, props) => (
+  <div>
+    <button {...api.getTriggerProps()}>{props.label}</button>
+    <div {...api.getPositionerProps()}>
+      <ul {...api.getContentProps()}>
+        {props.items.map((item) => <li {...api.getItemProps({ value: item })}>{item}</li>)}
+      </ul>
+    </div>
+  </div>
+), {
+  name: 'Actions',
+  events: { pick: ['onSelect', (details) => details.value] },
+  commands: { open: (api) => api.setOpen(true) },
+})
+```
+
+```jsx live live-height=170
+// Toolbar.jsx
+import { Actions } from './Actions.jsx'
+
+export function Toolbar({ state }) {
+  return <div><Actions className="actions" label="Edit" items={['cut', 'copy', 'paste']} /><p>{state.last}</p></div>
+}
+
+Toolbar.initialState = { last: '' }
+Toolbar.intent = ({ DOM }) => ({
+  PICK: DOM.select('.actions').events('pick').detail(),
+})
+Toolbar.model = {
+  PICK: (state, last) => ({ ...state, last }),
+}
+```
+
+Zag's parts come unstyled. Style them by the `data-scope` and `data-part` attributes the prop getters put on them:
+
+```css live
+[data-scope="menu"][data-part="content"] { margin: 0; padding: 0.25rem 0; list-style: none; background: Canvas; border: 1px solid GrayText; z-index: 1; }
+[data-scope="menu"][data-part="item"] { padding: 0.25rem 0.75rem; cursor: pointer; }
+[data-scope="menu"][data-part="item"][data-highlighted] { background: Highlight; color: HighlightText; }
+```
+
+- **`zag`** is the machine package as a namespace (`import * as menu from '@zag-js/menu'`): its `machine` and `connect`.
+- **`render(api, props, instance)`** returns one element. `api` is the machine's connected API: spread its prop getters on your elements (`{...api.getTriggerProps()}`); they carry the ARIA attributes, the ids and the event handlers. It runs again whenever the machine's state changes and when the tag gets new props, and the result is patched into the host. Render **plain elements only**: the adapter patches the result itself, outside the component tree, so a Sygnal component, a widget tag or special JSX (`<Transition>`, `<Portal>`, `<Collection>`…) inside it doesn't run. Pass data in through the tag's props, and keep components and widgets around the tag in the view ([SYG669](https://sygnal.js.org/reference/errors/#syg669) in dev).
+- **Props** go to the machine as they are (`open`, `value`, `positioning`...), always the newest ones: a controlled prop such as `open={state.menuOpen}` drives the machine. `options.props(props, instance)` maps them when they differ (Select turns `value: 'm'` into Zag's `['m']`).
+- **`events`**: `{ eventName: 'onCallback' }` dispatches the callback's details object; `{ eventName: ['onCallback', (details) => detail] }` dispatches what the function returns.
+- **`commands`**: `{ name: (api, options, instance) => … }` for `ELEMENT`.
+
+Pin Zag's version (`~1.45.0`, all packages the same): the adapter uses `@zag-js/vanilla`'s machine runtime, whose API changes in Zag 2.0.
+
+## Testing
+
+In the default mock DOM, an adapter's tag renders its host and nothing runs inside it. `t.widget(selector)` gives the props the view passed and dispatches the adapter's events, so the component's logic can be tested without React or Zag:
+
+```jsx
+import { it, expect } from 'vitest'
+import { renderComponent } from 'sygnal'
+import { Review } from './Review.jsx'
+
+it('stores the rating', async () => {
+  const t = renderComponent(Review)
+  await t.ready()
+  t.widget('.rating').dispatch('rate', 4)
+  await t.next((state) => state.rating === 4)
+  expect(t.widget('.rating').props.value).toBe(4)
+  t.dispose()
+})
+```
+
+To run the React component or the machine itself, use `renderComponent(Review, { dom: 'real' })` (in a jsdom test environment), click with `t.query(...)`, and wait for the state with `t.next`. Zag's positioning and list scrolling use `ResizeObserver`, `CSS.escape` and `Element.prototype.scrollTo`, which jsdom lacks: while a `dom: 'real'` test runs, `renderComponent` adds the missing ones (a `ResizeObserver` that observes nothing, a `scrollTo` that does nothing) and removes them when the last test instance is disposed. An implementation the environment already has is kept. Outside `renderComponent` (a test that calls `run()` itself), stub them in a setup file.
+
+## Server rendering
+
+`renderToString` renders an adapter's host with its `fallback` inside, like any widget; React and Zag run only in the browser. The client's first render replaces the fallback.
+
+## Size
+
+Gzipped, added to a small app:
+
+| | Adds |
+|---|---|
+| `fromReact` with React 19 + react-dom | 68 KB (the adapter itself: 0.6 KB) |
+| `fromReact` with `preact/compat` | 8 KB |
+| `fromZag` with Zag's dialog machine | 20 KB (the adapter itself: 2 KB) |
+| [Menu](./ui/menu.md), [Select](./ui/select.md), [Combobox](./ui/combobox.md) | 33–34 KB each, 47 KB for the three |
+
+## Diagnostics
+
+| Code | When |
+|---|---|
+| [SYG666](https://sygnal.js.org/reference/errors/#syg666) | An adapter entry is imported, but a package it needs isn't installed (`sygnal/vite`) |
+| [SYG667](https://sygnal.js.org/reference/errors/#syg667) | `fromZag` or `fromReact` got something that isn't a machine package or a component |
+| [SYG669](https://sygnal.js.org/reference/errors/#syg669) | A `fromZag` render returned a Sygnal component, a widget tag or special JSX, which can't run there (dev) |
+
+The widget codes ([SYG140–144](./widgets.md#diagnostics), [SYG660–662](https://sygnal.js.org/reference/errors/#syg660)) apply to adapters as to any widget.