sygnal 7.0.0 → 7.2.0-preview.0

package/dist/guide/ui/dialog.md

@@ -1,20 +1,22 @@
 <!-- Generated from docs/src/content/docs/ui by scripts/copy-guides.mjs; online: https://sygnal.js.org/ui/ -->
 # Dialog
 
-`dialog()` is a [behavior](../behaviors.md) for a native `<dialog>`. It opens the dialog with `showModal()`, so the browser does the hard parts: it traps the focus inside the dialog, makes the rest of the page inert, closes it on Escape and returns the focus when it closes. The behavior keeps `open` and `returnValue` in state, whichever way the dialog closed.
+`dialog()` is a [behavior](../behaviors.md) for a native `<dialog>`. It opens the dialog with `showModal()`, so the browser does the hard parts: it traps the focus inside the dialog, makes the rest of the page inert, closes it on Escape and returns the focus when it closes. The behavior keeps `open` and `returnValue` in state, and `open` drives the dialog: a reducer that writes it opens or closes it.
 
 ```jsx live
-import { dialog } from 'sygnal/ui'
+import { dialog, dialogAttrs } from 'sygnal/ui'
 
 function Profile({ state, uid }) {
+  const a = dialogAttrs(state.profile, uid)
   return (
     <div>
-      <button className="edit-profile">Edit profile</button>
-      <dialog className="profile" aria-labelledby={uid('title')}>
-        <h2 id={uid('title')}>Edit profile</h2>
+      <button className="edit-profile" {...a.trigger}>Edit profile</button>
+      <dialog className="profile" {...a.dialog}>
+        <h2 {...a.title}>Edit profile</h2>
+        <p {...a.description}>Your name as others see it.</p>
         <label>Name <input className="name" value={state.name} /></label>
         <button className="save">Save</button>
-        <button className="cancel">Cancel</button>
+        <button className="cancel" {...a.close}>Cancel</button>
       </dialog>
       <p>{state.profile.returnValue === 'saved' ? 'Profile saved' : ''}</p>
     </div>
@@ -33,7 +35,7 @@ Profile.model = {
 }
 ```
 
-A click on `.edit-profile` opens the dialog and a click on `.cancel` closes it. Save closes it from the model with a return value, through the built-in [`ELEMENT` sink](../element-commands.md).
+A click on `.edit-profile` opens the dialog and a click on `.cancel` closes it. Save closes it from the model with a return value, through the built-in [`ELEMENT` sink](../element-commands.md). `dialogAttrs` links the elements for assistive technology ([The parts' attributes](#the-parts-attributes)).
 
 ## Options
 
@@ -43,25 +45,70 @@ A click on `.edit-profile` opens the dialog and a click on `.cancel` closes it.
 | `trigger` | | Its clicks open the dialog |
 | `close` | | Its clicks close the dialog, with the return value `''` |
 | `modal` | `true` | `false` opens it with `show()`: not modal, the page stays usable |
-| `cancelable` | `true` | `false` keeps Escape from closing it: the `cancel` event is prevented, and opening it sets `closedby="none"` (Chromium closes a dialog on a second Escape otherwise; the attribute goes again when it closes). `CANCEL` still runs on each Escape. In a browser without `closedby`, a second Escape can still close it; the `CLOSED` action tells you |
+| `cancelable` | `true` | `false`: Escape doesn't close it. `CANCEL` still runs on each Escape, and the state stays open |
+| `open` | | Open at the start. Given at all, even `open: false`, it makes the dialog controlled: the browser never dismisses it, the behavior does (see [Controlled dismissal](#controlled-dismissal)) |
+| `id` | the key in `uses` | The prefix of the ids `dialogAttrs` makes |
 | `returnFocus` | `true` | When the dialog closes and the focus was lost, focus the element that opened it (the clicked trigger, when several match `trigger`), else the trigger. A selector names another element; `false` leaves the focus to the browser |
 
 The browser returns the focus to the element that had it before the dialog opened. Safari doesn't focus a button when it is clicked, so after a mouse click the focus would go back to the page itself; `returnFocus` focuses the trigger instead. It does nothing when the browser already moved the focus somewhere. It works for a dialog the host renders only while it is open, too.
 
 ## State and actions
 
-`state.profile` is `{ open, returnValue }`.
+`state.profile` is `{ id, open, returnValue }` (`id`: the prefix of `dialogAttrs`' ids); `open` drives the dialog (see [Controlled open](#controlled-open)).
 
 | Action | Data | |
 |---|---|---|
-| `profile.OPEN` | | Opens the dialog (no change when it is open) |
-| `profile.CLOSE` | the return value | Closes it with that return value |
-| `profile.CLOSED` | the return value | The dialog closed, whichever way: sets `open: false` and `returnValue` |
-| `profile.TOGGLED` | `true` / `false` | The dialog's `toggle` event: a dialog opened without the model (for example with `commandfor`) sets `open: true` |
-| `profile.CANCEL` | the event | Escape was pressed (the dialog closes next, unless `cancelable: false`). The `cancel` event; with `cancelable: false`, the Escape `keydown` in the dialog (`closedby="none"` stops the `cancel` event) |
-| `profile.SYNC` | `false` | The dialog left the page while open (a page change, a conditional render), or OPEN's `showModal()` threw (a disconnected dialog, a popover open on it): sets `open: false`, as no close event comes (your `close` listeners don't run for a dialog that never opened) |
+| `profile.OPEN` | | Sets `open: true` and opens the dialog: the trigger, a `commandfor` button with `command="show-modal"` |
+| `profile.CLOSE` | the return value | Sets `open: false` with that return value and closes it: the `close` button, a `method="dialog"` form's submit (the submit button's `value`), a `commandfor` button with `command="close"` |
+| `profile.CANCEL` | the event | Escape, a light dismiss (`closedby="any"`; controlled: a press or a focus outside), or `command="request-close"`: sets `open: false` with the return value `''`, unless `cancelable: false` |
+| `profile.CLOSED` | the return value | The dialog's `close` event: sets `open: false` and `returnValue` when it closed some other way |
+| `profile.TOGGLED` | `true` / `false` | The dialog's `toggle` event: a dialog opened without the model (`showModal()` called elsewhere) sets `open: true` |
+| `profile.SYNC` | `false`, or `true` when `showModal()` threw | The dialog left the page while open (a page change, a conditional render), or OPEN's `showModal()` threw (a disconnected dialog, a popover open on it): sets `open: false`, as no close event comes (your `close` listeners don't run for a dialog that never opened) |
 
-`OPEN` and `CLOSE` check the dialog itself before they act: `showModal()` only on a closed dialog, `close()` only on an open one. A dialog removed while open opens again when it is back.
+| `profile.APPLY` | `true` / `false` | `open` changed outside these actions (your reducer wrote it): the dialog is opened or closed to match |
+
+The commands check the dialog itself before they act: `showModal()` only on a closed dialog, `close()` only on an open one.
+
+## Controlled open
+
+`state.profile.open` is the source of truth, as Radix's controlled `open` is. Write it in any reducer and the dialog opens or closes to match:
+
+```jsx
+Profile.model = {
+  EDIT_FROM_LINK: (state) => ({ ...state, profile: { ...state.profile, open: true } }),
+}
+```
+
+Everything that would close the dialog arrives as an action first: Escape and a light dismiss as `CANCEL`, the close button, a `method="dialog"` form and `commandfor` as `CLOSE`. The behavior prevents the browser's own close and sets `open: false`; a host entry for the same action runs after it and decides. To keep the dialog open, return the state from before the action, as Radix's `onOpenChange(false)` does when you ignore it:
+
+```jsx
+Profile.model = {
+  // unsaved changes: Escape and the form don't close it
+  'profile.CANCEL': (state, event, next, { previousState }) => (state.dirty ? previousState : state),
+  'profile.CLOSE': (state, returnValue, next, { previousState }) => (state.dirty && returnValue !== 'discard' ? previousState : state),
+}
+```
+
+The dialog never closes in between, so the focus stays where it was. For Escape the behavior gives a modal dialog `closedby="none"` while it is open (unless you set `closedby` yourself) and reads the key, so a second Escape can't close it behind the state's back. A close the browser makes on its own (your own code calling `close()`) arrives as `CLOSED`; a host entry that keeps `open: true` there opens the dialog again.
+
+### Controlled dismissal
+
+Pass the `open` option, even `open: false`, and the browser never dismisses the dialog: it keeps `closedby="none"` while it is open, also when you set `closedby`, and the behavior dismisses it itself, as Radix's `DismissableLayer` does. Your `closedby` says on what, and each one arrives as `CANCEL` with its event as the data:
+
+| `closedby` | Dismissed by |
+|---|---|
+| (none) | Escape for a modal dialog, nothing for a non-modal one |
+| `"closerequest"` | Escape |
+| `"any"` | Escape, a press outside the dialog (on its backdrop), the focus moving out of it |
+| `"none"` | nothing |
+
+A refused `CANCEL` leaves the dialog open with no close in between, whatever dismissed it. Without the `open` option a light dismiss (`closedby="any"`) is the browser's `cancel` event, which the behavior prevents; a browser may refuse to let a cancel be prevented without a user gesture since the last one (the CloseWatcher rule), and then the dialog closes and opens again.
+
+Dialogs and [controlled popovers](./popover.md#controlled-dismissal) stack as layers. Escape dismisses the top layer only, so a controlled popover open in a dialog closes first and the next Escape closes the dialog. A press on the dialog outside the popover dismisses the popover only, and a press outside both dismisses both, each through its own action. A layer opened in another one counts as inside it, also when it renders through a `<Portal>`.
+
+One interaction is one `CANCEL`: a press on the backdrop that also moves the focus reports the `pointerdown`. An open [Menu](./menu.md), [Select](./select.md) or [Combobox](./combobox.md) in the dialog is a layer above it: Escape and a press outside close it first, and a press in its list isn't outside the dialog.
+
+The dialog works inside a [`<Portal>`](https://sygnal.js.org/advanced/portals/) too: the behavior finds its element, its events and its commands in the portal's content. The top layer already draws a modal dialog above the page, so a portal is rarely needed.
 
 React to a close in your own model with an entry for the namespaced action. It runs after the behavior's, on the full state:
 
@@ -71,14 +118,43 @@ Profile.model = {
 }
 ```
 
-Open the dialog from another place with an intent action of the same name, `'profile.OPEN': DOM.click('.avatar')`, or from a model entry that sends `{ showModal: '.profile' }` to `ELEMENT`.
+Open the dialog from another button by listing it in the option, `trigger: '.edit-profile, .avatar'`, from a model entry with `next('profile.OPEN')`, or by writing `open: true`. An intent action of the same name, `'profile.OPEN': DOM.click('.avatar')`, replaces the `trigger` option's clicks instead of adding to them ([SYG118](https://sygnal.js.org/reference/errors/#syg118)). (A `{ showModal: '.profile' }` command to `ELEMENT` opens it too, but skips what `OPEN` adds: the `returnFocus` opener, the `closedby` that routes Escape to `CANCEL`, and clearing the last close's return value.)
+
+## The parts' attributes
+
+`dialogAttrs(state.profile, uid)` gives each element the attributes Radix's Dialog parts put on theirs, computed from the slice. Spread them on your own markup:
+
+| Part | Spread on | Attributes |
+|---|---|---|
+| `trigger` | the button that opens it | `type="button"`, `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` (the dialog's id), `data-state` |
+| `dialog` | the `<dialog>` | `id`, `aria-labelledby` (the title), `aria-describedby` (the description), `data-state` |
+| `title` | its heading | `id` |
+| `description` | a paragraph that describes it | `id` |
+| `close` | a close button | `type="button"` |
+
+`data-state` is `open` or `closed`. The ids come from `uid()`, so each instance of the component gets its own, and the `id` option names their prefix. A dialog without a description writes `aria-describedby={undefined}` after the spread, as Radix asks for one without `Description`.
+
+There's no `role`: a `<dialog>` has `role="dialog"` already, and a modal one is `aria-modal`. There's no overlay part either: the backdrop is `::backdrop`.
+
+### Alert dialogs
+
+For a confirmation that needs an answer (Radix's `AlertDialog`), write `role="alertdialog"` on the `<dialog>`, after the spread, and give it a description: a screen reader reads it when the dialog opens. A modal dialog already ignores presses outside it; to keep Escape from closing it as well, pass `cancelable: false`. Open it with the focus on the safe answer by giving Cancel `autofocus`:
+
+```jsx
+<dialog className="confirm" {...a.dialog} role="alertdialog">
+  <h2 {...a.title}>Delete the file?</h2>
+  <p {...a.description}>This can't be undone.</p>
+  <button className="cancel" {...a.close} autofocus>Cancel</button>
+  <button className="delete">Delete</button>
+</dialog>
+```
 
 ## Accessibility
 
-- Name the dialog: `aria-labelledby` pointing at its heading, as above, or `aria-label`.
+- Name the dialog: spread `dialogAttrs`' `dialog` and `title` (`aria-labelledby` pointing at its heading), or write `aria-label`.
 - Put a close button inside. Escape closes a modal dialog, but not everyone has a keyboard.
 - The dialog element has `role="dialog"`; a modal one is also `aria-modal` to assistive technology.
-- A form inside the dialog with `method="dialog"` closes it on submit, with the submit button's `value` as the return value; `CLOSED` sees it.
+- A form inside the dialog with `method="dialog"` closes it on submit, with the submit button's `value` as the return value (the `CLOSE` action's data). Enter in a field submits with the form's first submit button, so put the confirming button first and make Cancel `type="button"` (the `close` option), or Enter cancels. `OPEN` clears the element's old return value, so an Escape after an earlier `'ok'` reads as `''` in every browser.
 
 ## Styling
 
@@ -121,4 +197,4 @@ it('opens the dialog and keeps the return value', async () => {
 })
 ```
 
-With `dom: 'real'`, the commands run on the jsdom elements; focus trapping and the backdrop need a real browser.
+With `dom: 'real'`, the commands run on the jsdom elements; focus trapping and the backdrop need a real browser. A reducer that writes `open` is applied by `APPLY`, which compares the state with the element: test it with `dom: 'real'` (renderComponent fakes jsdom's missing dialog methods) or in a browser; on the mock DOM, check `t.state`.

package/dist/guide/ui/menu.md

@@ -50,15 +50,15 @@ Without them, `sygnal/vite` stops with [SYG666](https://sygnal.js.org/reference/
 
 | Prop | | |
 |---|---|---|
-| `label` | (required) | The trigger's text: its accessible name |
+| `label` | | The trigger's content: its text, and its accessible name. For an icon trigger, pass the icon as `label` and name it with `aria-label` |
 | `aria-label`, `aria-labelledby`, `aria-describedby` | | Name or describe the trigger when there is no visible `label` (or in addition to it); they go on the trigger, not the host |
-| `items` | (required) | Strings, or `{ value, label, disabled }` objects; `{ separator: true }` draws a separator |
+| `items` | (required) | Strings, or `{ value, label, disabled }` objects; `{ separator: true }` draws a separator; checkbox and radio items, links and submenus: see [Item kinds](#item-kinds) |
 | `open` | | Controlled open state; follow the `open-change` event |
 | `defaultOpen` | `false` | |
 | `closeOnSelect` | `true` | `false` keeps the menu open after a pick |
 | `loopFocus` | `false` | The arrow keys wrap from the last item to the first |
 | `typeahead` | `true` | Typing a letter moves to the next item starting with it |
-| `positioning` | | Zag's positioning options: `{ placement: 'bottom-end', gutter: 4 }` |
+| `positioning` | `{ strategy: 'fixed' }` | Zag's positioning options: `{ placement: 'bottom-end', gutter: 4 }` ([Positioning](#positioning)) |
 | `dir` | `'ltr'` | |
 
 `className`, `id`, `style` and `aria-*` / `data-*` props go on the host `<div>`.
@@ -68,10 +68,59 @@ Without them, `sygnal/vite` stops with [SYG666](https://sygnal.js.org/reference/
 | Event | Detail |
 |---|---|
 | `select` | The value of the item picked |
+| `checked-change` | A checkbox or radio item was picked: `{ value, checked, type }` |
 | `open-change` | `true` when it opens, `false` when it closes |
 
 Open or close it from the model with an [element command](../element-commands.md) on its class: `OPEN_ACTIONS: { ELEMENT: { open: '.card-actions' } }`, or `{ close: '.card-actions' }`.
 
+## Item kinds
+
+Besides actions and separators, an item can be a checkbox, a radio, a link or a submenu, as in Radix's DropdownMenu:
+
+```jsx live live-height=280
+import { Menu } from 'sygnal/ui/menu'
+
+function Toolbar({ state }) {
+  const items = [
+    { type: 'checkbox', value: 'grid', label: 'Show grid', checked: state.grid },
+    { separator: true },
+    { type: 'radio', value: 'small', label: 'Small', checked: state.size === 'small' },
+    { type: 'radio', value: 'large', label: 'Large', checked: state.size === 'large' },
+    { separator: true },
+    { value: 'share', label: 'Share', items: [{ value: 'mail', label: 'Mail' }, { value: 'link', label: 'Copy link' }] },
+    { href: '#item-kinds', value: 'help', label: 'Help' },
+  ]
+  return (
+    <div className="toolbar">
+      <Menu className="view" label="View" items={items} />
+      <p>{`Grid ${state.grid ? 'on' : 'off'}, ${state.size}${state.last ? `; last: ${state.last}` : ''}`}</p>
+    </div>
+  )
+}
+
+Toolbar.initialState = { grid: true, size: 'small', last: '' }
+Toolbar.intent = ({ DOM }) => ({
+  CHECK: DOM.select('.view').events('checked-change').detail(),
+  PICK: DOM.select('.view').events('select').detail(),
+})
+Toolbar.model = {
+  CHECK: (state, { value, checked, type }) => (type === 'checkbox' ? { ...state, [value]: checked } : { ...state, size: value }),
+  PICK: (state, last) => ({ ...state, last }),
+}
+```
+
+```css live
+.view [data-part='content'] { background: Canvas; border: 1px solid #ddd; border-radius: 6px; padding: 4px; min-width: 10rem; }
+.view [data-part='item'], .view [data-part='trigger-item'] { display: flex; gap: 6px; padding: 4px 8px; border-radius: 4px; cursor: default; }
+.view [data-part='item'][data-highlighted], .view [data-part='trigger-item'][data-highlighted] { background: rgb(99 102 241 / 0.25); }
+.view [data-part='item-indicator'] { width: 1em; }
+.view [data-part='submenu-indicator'] { margin-left: auto; }
+```
+
+- **Checkbox and radio items**: `{ type: 'checkbox' | 'radio', value, label, checked }`, with role `menuitemcheckbox` / `menuitemradio` and a `✓` indicator (`[data-part="item-indicator"]`, `hidden` while unchecked). A pick reports `checked-change` (`{ value, checked, type }`; a radio's `checked` is always `true`) and `select`. The menu shows the `checked` the items say, so keep it in state.
+- **Links**: `{ href, value, label, target, rel }` renders an `<a href>` menu item. Click or Enter follows the link (and reports `select`).
+- **Submenus**: `{ value, label, items }`. The item (`[data-part="trigger-item"]`, with a `›` indicator) opens its own menu beside it on ArrowRight, Enter, Space or hover; ArrowLeft or Escape closes it and returns to the item. A pick inside it is the Menu's `select` and closes every level. Submenus nest. Each one is its own Zag machine, linked to its parent's.
+
 ## Keyboard
 
 | Key | |
@@ -81,13 +130,16 @@ Open or close it from the model with an [element command](../element-commands.md
 | Home / End | The first / last item |
 | A letter | The next item that starts with it |
 | Enter, Space | Pick the highlighted item and close |
+| ArrowRight / ArrowLeft | On a submenu's item: open it / inside a submenu: close it (reversed with `dir="rtl"`) |
 | Escape, Tab | Close; Escape returns the focus to the trigger |
 
 A click outside closes it too.
 
+Inside a [controlled popover](./popover.md#controlled-dismissal) or [dialog](./dialog.md#controlled-dismissal), the open list is the top layer: Escape and a press outside close it first, a press in it isn't outside the popover or dialog, and the next Escape closes that one.
+
 ## Styling
 
-The parts carry Zag's data attributes: `[data-scope="menu"]` with `[data-part="trigger"]`, `"positioner"`, `"content"`, `"item"` and `"separator"`; the content and trigger have `data-state="open" | "closed"`, an item `data-highlighted` and `data-disabled`. The content is `hidden` while closed, and the positioner places it with `position` and CSS variables (`--x`, `--y`).
+The parts carry Zag's data attributes: `[data-scope="menu"]` with `[data-part="trigger"]`, `"positioner"`, `"content"`, `"item"`, `"separator"`, and for the item kinds `"item-indicator"`, `"item-text"`, `"trigger-item"` and `"submenu-indicator"`; the content and trigger have `data-state="open" | "closed"`, an item `data-highlighted` and `data-disabled`, a checkbox or radio item `data-type` and `data-state="checked" | "unchecked"`. The content is `hidden` while closed, and the positioner places it with `position` and CSS variables (`--x`, `--y`).
 
 ```css live
 .card-actions [data-part='content'] { background: Canvas; border: 1px solid #ddd; border-radius: 6px; padding: 4px; }
@@ -98,7 +150,7 @@ The parts carry Zag's data attributes: `[data-scope="menu"]` with `[data-part="t
 
 ## Positioning
 
-The menu renders inside the widget's host, next to the trigger, and Zag positions it with `position: absolute` (the `--x` / `--y` variables on the positioner). Inside a container that clips its content (`overflow: hidden` or `auto`: a card, a scrolling panel, a table cell), the open menu is cut off at the container's edge. Pass `positioning={{ strategy: 'fixed' }}` there: the positioner is then placed relative to the viewport and escapes the clipping (it still follows the trigger when the page scrolls; an ancestor with a `transform`, `filter` or `contain` still clips it). Other options go in the same object: `positioning={{ placement: 'bottom-end', gutter: 4, strategy: 'fixed' }}`.
+The list renders inside the widget's host, next to its trigger, and Zag places it with `position: fixed` by default (as Radix's Popper does; the `--x` / `--y` variables on the positioner). So a container that clips its content (`overflow: hidden` or `auto`: a card, a scrolling panel, a table cell, a `<dialog>`) doesn't cut it off, and it still follows the trigger when the page scrolls. The caveat: an ancestor with a `transform`, `filter`, `perspective` or `contain` becomes the containing block of a fixed element, so inside one (an animated drawer, a scaled canvas) the list is placed and clipped relative to that ancestor. There, or to keep the list in the document flow, pass `positioning={{ strategy: 'absolute' }}`. Other options go in the same object and merge over the default: `positioning={{ placement: 'bottom-end', gutter: 4 }}`.
 
 ## Testing
 

package/dist/guide/ui/overview.md

@@ -9,8 +9,8 @@ import { dialog, tabs, tabsAttrs, Toaster } from 'sygnal/ui'
 
 | Part | What it is | Built on |
 |---|---|---|
-| [Dialog](./dialog.md) | A behavior for `uses` | `<dialog>`, `showModal()` |
-| [Popover](./popover.md) | A behavior for `uses` | The Popover API (`popover`, `popovertarget`) |
+| [Dialog](./dialog.md) | A behavior for `uses` (+ `dialogAttrs`) | `<dialog>`, `showModal()` |
+| [Popover](./popover.md) | A behavior for `uses` (+ `popoverAttrs` for a `trigger`) | The Popover API (`popover`, `popovertarget`) |
 | [Tooltip](./tooltip.md) | A behavior for `uses` | A manual popover placed by CSS anchor positioning, with show and hide delays |
 | [Tabs](./tabs.md) | A behavior + `tabsAttrs` | Your buttons and panels; roving focus |
 | [Accordion](./accordion.md) | A behavior + `accordionAttrs` | Your buttons and panels |
@@ -45,7 +45,7 @@ function Settings({ state, uid }) {
 Settings.uses = { settings: dialog({ dialog: '.settings', trigger: '.open-settings', close: '.close-settings' }) }
 ```
 
-`state.settings` is `{ open, returnValue }`, and the actions are `settings.OPEN`, `settings.CLOSE` and so on. Your own intent and model can trigger them and react to them, as with any behavior: an intent action `'settings.OPEN': DOM.click('.edit')` adds a trigger, and a model entry `'settings.CLOSED': (state) => …` runs after the behavior's.
+`state.settings` is `{ id, open, returnValue }`, and the actions are `settings.OPEN`, `settings.CLOSE` and so on. Every slice is the source of truth, as Radix's controlled props are: a reducer that writes `open: true` opens the dialog, and one that keeps `open: true` when the user presses Escape keeps it open ([Controlled open](./dialog.md#controlled-open)). Give a dialog or popover its `open` option, even `open: false`, and the browser never dismisses it: the behavior turns Escape, a press outside and the focus moving outside into the close request, top layer first, so a refused one never hides it for a frame ([Controlled dismissal](./popover.md#controlled-dismissal)). The parts also work inside a [`<Portal>`](https://sygnal.js.org/advanced/portals/). Your own intent and model can trigger them and react to them, as with any behavior: a model entry `'settings.CLOSED': (state) => …` runs after the behavior's, and `next('settings.OPEN')` dispatches one from your model. An intent action of the same name, `'settings.OPEN': DOM.click('.edit')`, *replaces* the behavior's trigger for that action, so the `.open-settings` clicks stop opening it; to add a second opener, list both in the option: `trigger: '.open-settings, .edit'`.
 
 Tabs, Accordion and Disclosure have no markup of their own either. A helper gives you the attributes to spread on your elements, computed from the slice: roles, ARIA states, ids that link the buttons and panels, and the roving `tabindex`. It takes the view's `uid`, so each instance of the component gets its own ids:
 
@@ -54,6 +54,8 @@ const a = tabsAttrs(state.tabs, uid)
 // <div {...a.list} aria-label="Settings"> <button className="tab" {...a.tab('general')}>General</button> …
 ```
 
+Dialog and Popover have helpers too, `dialogAttrs` and `popoverAttrs`, for their trigger's `aria-expanded` and `aria-controls` and, for a dialog, its name and description.
+
 The Toaster renders its own markup, so it is a component: render `<Toaster />` once and send `event('TOAST', { text })` from any component.
 
 ## Styling
@@ -63,7 +65,7 @@ Style the parts with your own classes, the ones you pass in the options. The par
 | Attribute | On | Values |
 |---|---|---|
 | `data-state` | tabs and tab panels | `active`, `inactive` |
-| `data-state` | accordion and disclosure buttons and panels | `open`, `closed` |
+| `data-state` | accordion and disclosure buttons and panels; dialog and popover triggers and elements (from the helpers) | `open`, `closed` |
 | `data-value` | tabs, accordion buttons | the value you passed |
 | `data-kind` | each toast | `info`, `success`, `warning`, `error` |
 | `data-paused` | the toast region | present while paused |
@@ -74,6 +76,8 @@ The browser also exposes the open state: `dialog[open]`, `:modal`, `:popover-ope
 
 The parts target current evergreen browsers: Chromium (Chrome, Edge), Firefox and Safari. They rely on `<dialog>`, the Popover API (including `popovertarget` and `toggle` events), the `:modal` pseudo-class and, for the Tooltip, CSS anchor positioning (`anchor-name`, `position-anchor`, `position-area`). Sygnal's browser suite runs every part in Chromium, Firefox and WebKit.
 
+The parts read the document of the element they act on, not the global one, so they also work in a shadow root (a [custom element](../web-components.md)), in an iframe, and on [`sygnal/host`](../renderers/custom-targets.md) trees such as the [terminal](../renderers/terminal.md#sygnalui-in-a-terminal).
+
 The package has no JavaScript positioning fallback. To support a browser without CSS anchor positioning, position the tooltip with [Floating UI](#floating-ui-for-older-browsers) instead.
 
 ### Floating UI for older browsers

package/dist/guide/ui/popover.md

@@ -32,32 +32,92 @@ Filters.model = { ONLY_OPEN: (state, onlyOpen) => ({ ...state, onlyOpen }) }
 | Option | | |
 |---|---|---|
 | `popover` | (required) | The popover element: a selector or a [control](https://sygnal.js.org/guide/controls/) |
+| `trigger` | | A button whose clicks open and close the popover through the model (`TOGGLE`), as Radix's `Popover.Trigger`; see [A trigger button](#a-trigger-button) |
 | `close` | | A button inside: its clicks close the popover |
+| `id` | the key in `uses` | The prefix of the ids `popoverAttrs` makes |
+| `open` | | Open at the start. Given at all, even `open: false`, it makes the popover controlled (see [Controlled dismissal](#controlled-dismissal)) |
 
-There is no `trigger` option: open it with a `popovertarget` button. A button that toggled an `auto` popover through the model would open it again right after closing it, because the press outside the popover light-dismisses it first; the browser exempts `popovertarget` buttons from that.
+## A trigger button
+
+A `popovertarget` button needs no option. To open and close the popover through the model instead, as Radix's `Popover.Trigger` does, name the button in `trigger` and spread `popoverAttrs` on both elements:
+
+```jsx live
+import { popover, popoverAttrs } from 'sygnal/ui'
+
+function Share({ state, uid }) {
+  const a = popoverAttrs(state.share, uid)
+  return (
+    <div>
+      <button className="share-button" {...a.trigger}>Share</button>
+      <div className="share" {...a.popover} popover="auto" aria-label="Share">
+        <button>Copy link</button>
+        <button>Email</button>
+      </div>
+      <p>{state.share.open ? 'Sharing…' : ''}</p>
+    </div>
+  )
+}
+
+Share.uses = { share: popover({ popover: '.share', trigger: '.share-button' }) }
+```
+
+- A click on the trigger dispatches `share.TOGGLE` with the value to go to, `true` or `false`. The behavior reads it from the state at the press, because a press on the trigger light-dismisses an `auto` popover before the click comes: a plain flip would open it again.
+- `popoverAttrs(state.share, uid)` gives the trigger `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` and `data-state`, and the popover its `id` and `data-state`.
+- A press on the trigger isn't outside a [controlled](#controlled-dismissal) popover.
 
 ## State and actions
 
-`state.filters` is `{ open }`. It follows the popover's `toggle` event, whatever opened or closed it.
+`state.filters` is `{ id, open }` (`id`: the prefix of `popoverAttrs`' ids), and `open` is the source of truth: a reducer that writes it shows or hides the popover, and the popover's `toggle` event writes it back, whatever opened or closed it.
 
 | Action | Data | |
 |---|---|---|
-| `filters.OPEN` | | Shows the popover (`showPopover`) |
-| `filters.CLOSE` | | Hides it (`hidePopover`) |
-| `filters.TOGGLE` | | Toggles it (`togglePopover`) |
-| `filters.TOGGLED` | `true` / `false` | The `toggle` event: sets `open` |
+| `filters.OPEN` | | Sets `open: true` and shows the popover (`showPopover`) |
+| `filters.CLOSE` | | Sets `open: false` and hides it (`hidePopover`) |
+| `filters.TOGGLE` | none, or `true` / `false` | Flips `open` (with data: sets it) and shows or hides it: the `trigger` |
+| `filters.TOGGLED` | `true` / `false` | The `toggle` event (a `popovertarget` button, a light dismiss, Escape): sets `open` |
+| `filters.DISMISS` | the event | Controlled only: Escape, a press outside, the focus moving outside (the `keydown`, `pointerdown` or `focusin` event): sets `open: false` and hides it |
 | `filters.SYNC` | `false` | The popover left the page while open (a page change, a conditional render): sets `open: false`, as no `toggle` event comes |
 
-`OPEN` and `CLOSE` check the popover itself (`:popover-open`), not `state.filters.open`, which follows the `toggle` event a moment later: `OPEN` then `CLOSE` in one go leaves it closed, and `showPopover()` is never called on an open popover.
+| `filters.APPLY` | `true` / `false` | `open` changed outside these actions (your reducer wrote it): the popover is shown or hidden to match |
+
+The commands check the popover itself (`:popover-open`): `OPEN` then `CLOSE` in one go leaves it closed, and `showPopover()` is never called on an open popover.
+
+The popover works inside a [`<Portal>`](https://sygnal.js.org/advanced/portals/) too.
+
+## Controlled dismissal
+
+Without the `open` option the browser light-dismisses an `auto` popover, and the `toggle` event tells the state afterwards. A host entry for `filters.TOGGLED` that keeps `open: true` shows it again, but the browser has already hidden it, so it can disappear for a frame.
+
+To decide before anything is hidden, pass the `open` option, even `open: false`. The popover is then controlled, as Radix's `open` / `onOpenChange` is:
+
+- It is a `manual` popover (the behavior sets `popover="manual"` before it shows it), so the browser never dismisses it.
+- The behavior dismisses it itself, as Radix's `DismissableLayer` does: Escape, a press outside and the focus moving outside arrive as `filters.DISMISS`, with the event as the data. One interaction is one `DISMISS`: a press outside that also moves the focus outside reports the `pointerdown`. A press on its `trigger` or its own `popovertarget` button isn't outside.
+- Its `popovertarget` buttons and `commandfor` commands go through the model too: the behavior prevents the browser's own toggle and dispatches `TOGGLE`, `OPEN` or `CLOSE` (from `popovertargetaction`).
+
+A host entry that keeps `open: true` keeps it shown, with no frame where it is hidden:
+
+```jsx
+Filters.uses = { filters: popover({ popover: '.filters', close: '.filters-done', open: false }) }
+Filters.model = {
+  // pinned: Escape and a click elsewhere leave it open
+  'filters.DISMISS': (state, event, next, { previousState }) => (state.pinned ? previousState : state),
+}
+```
+
+Controlled popovers and [dialogs](./dialog.md#controlled-dismissal) stack as layers. Escape dismisses the top layer only (not while an `auto` popover inside it is open, which the browser closes first), and an Escape that an element inside handled (`preventDefault()`) dismisses nothing. A press on a parent layer outside a child dismisses the child only, and a press outside both dismisses both. A layer opened in another one counts as inside it, also when it renders through a `<Portal>`. Under a modal dialog, presses can't reach the page, so the layers under it aren't dismissed by them.
+
+The [Menu](./menu.md), [Select](./select.md) and [Combobox](./combobox.md) parts are layers too. One open inside a controlled popover or dialog is the top layer: Escape and a press outside it close it first, and a press in it (in its list as well) isn't outside the popover. The next Escape closes the popover, and a press outside both closes both.
+
+A modal dialog that isn't rendered inside the popover moves the focus out of it when it opens, so it dismisses the popover, as in Radix. Keep the popover open by rendering the dialog inside it, or with a `DISMISS` entry that refuses while the dialog is open.
 
 Open it from somewhere else, for example a keyboard shortcut, with an intent action of the same name: `'filters.OPEN': DOM.keydown('document').filter((e) => e.key === 'f' && e.altKey)`.
 
 ## `auto` or `manual`
 
 - `popover="auto"` (or just `popover`): light dismiss, and opening one closes the other `auto` popovers that aren't its ancestors. Menus, pickers and filter panels.
-- `popover="manual"`: only your code and its `popovertarget` button close it. Use it for something that stays open, such as a [tooltip](./tooltip.md) or [toasts](./toaster.md).
+- `popover="manual"`: only your code and its `popovertarget` button close it. Use it for something that stays open, such as a [tooltip](./tooltip.md) or [toasts](./toaster.md). A [controlled](#controlled-dismissal) popover is a manual one with the dismissal done by the behavior.
 
-A popover inside a modal [dialog](./dialog.md) works: it opens above the dialog, the first Escape closes the popover and the second the dialog.
+A popover inside a modal [dialog](./dialog.md) works: it opens above the dialog, the first Escape closes the popover and the second the dialog (controlled or not).
 
 ## Accessibility
 

package/dist/guide/ui/select.md

@@ -42,7 +42,7 @@ Install Zag's packages first: `npm install @zag-js/vanilla@~1.45.0 @zag-js/selec
 |---|---|---|
 | `label` | | The visible label, linked to the trigger (its accessible name). Give every select one |
 | `aria-label`, `aria-labelledby`, `aria-describedby` | | Name or describe the trigger when there is no visible `label` (or in addition to it); they go on the trigger, not the host |
-| `items` | (required) | Strings, or `{ value, label, disabled }` objects. Values are strings |
+| `items` | (required) | Strings, or `{ value, label, disabled }` objects, or [groups](#groups) of them. Values are strings: a number value comes back as a string in `value-change` |
 | `value` | | Controlled: the value (an array with `multiple`); `null` for none |
 | `defaultValue` | | The start value when `value` is left out |
 | `placeholder` | | Shown while nothing is selected |
@@ -52,9 +52,57 @@ Install Zag's packages first: `npm install @zag-js/vanilla@~1.45.0 @zag-js/selec
 | `deselectable` | `false` | A click on the selected option clears it |
 | `closeOnSelect` | `true` | With `multiple`: `false` |
 | `loopFocus` | `false` | |
-| `positioning` | | Zag's positioning options: `{ placement: 'bottom-start', sameWidth: true }` |
+| `positioning` | `{ strategy: 'fixed' }` | Zag's positioning options: `{ placement: 'bottom-start', sameWidth: true }` ([Positioning](#positioning)) |
 | `open` | | Controlled open state; follow `open-change` |
 
+## Groups
+
+An item can be a group of items, `{ group, items }`. Each group renders as a `role="group"` named by its label (`[data-part="item-group"]`, `[data-part="item-group-label"]`); the arrow keys and typeahead go through the groups in order:
+
+```jsx live live-height=280
+import { Select } from 'sygnal/ui/select'
+
+const FOOD = [
+  { group: 'Fruit', items: ['Apple', 'Banana', 'Cherry'] },
+  { group: 'Vegetables', items: [{ value: 'kale', label: 'Kale' }, { value: 'leek', label: 'Leek' }] },
+]
+
+function Lunch({ state }) {
+  return (
+    <div className="lunch">
+      <Select className="food" label="Food" items={FOOD} value={state.food} placeholder="Pick one" />
+      <p>{state.food ? `Picked: ${state.food}` : ''}</p>
+    </div>
+  )
+}
+
+Lunch.initialState = { food: null }
+Lunch.intent = ({ DOM }) => ({
+  FOOD: DOM.select('.food').events('value-change').detail(),
+})
+Lunch.model = {
+  FOOD: (state, food) => ({ ...state, food }),
+}
+```
+
+```css live
+.food [data-part='content'] { background: Canvas; border: 1px solid #ddd; padding: 4px; }
+.food [data-part='item-group-label'] { font-size: 0.75rem; font-weight: 600; opacity: 0.7; padding: 4px 8px 0; }
+.food [data-part='item'] { padding: 4px 8px; }
+.food [data-part='item'][data-highlighted] { background: rgb(99 102 241 / 0.25); }
+```
+
+## Forms
+
+A Select is a form field. With `name`, the [`form` behavior](../forms.md) reads its value and marks it touched when the focus leaves it, as it does for a native `<select>` ([form fields](../widgets.md#form-fields)). A hidden native `<select>` carries the value for `FormData` and a plain form submission, and [`processForm`](../forms-reference.md#processform) entries get it:
+
+<!-- docs-check: skip -->
+```jsx
+<Select className="size" label="Size" name="size" items={SIZES} value={state.form.values.size} />
+```
+
+A form reset puts back the first value (`defaultValue`, or the controlled `value` the select started with); a controlled select reports it with `value-change`.
+
 ## Events and commands
 
 | Event | Detail |
@@ -74,9 +122,11 @@ Commands for `ELEMENT`: `open`, `close`, `clear`, and `focus` (the trigger): `CL
 | Enter | Select the highlighted option and close; the focus returns to the trigger |
 | Escape, Tab | Close |
 
+Inside a [controlled popover](./popover.md#controlled-dismissal) or [dialog](./dialog.md#controlled-dismissal), the open list is the top layer: Escape and a press outside close it first, a press in it isn't outside the popover or dialog, and the next Escape closes that one.
+
 ## Styling
 
-Zag's data attributes: `[data-scope="select"]` with `[data-part="root"]`, `"label"`, `"control"`, `"trigger"`, `"value-text"`, `"indicator"`, `"positioner"`, `"content"`, `"item"`, `"item-text"` and `"item-indicator"`. The trigger and content have `data-state`, options `data-highlighted`, `data-state="checked"` and `data-disabled`, and the value text `data-placeholder-shown` while empty. The item indicator (`✓`) is `hidden` on unselected options.
+Zag's data attributes: `[data-scope="select"]` with `[data-part="root"]`, `"label"`, `"control"`, `"trigger"`, `"value-text"`, `"indicator"`, `"positioner"`, `"content"`, `"item"`, `"item-text"`, `"item-indicator"`, and for [groups](#groups) `"item-group"` and `"item-group-label"`. The trigger and content have `data-state`, options `data-highlighted`, `data-state="checked"` and `data-disabled`, and the value text `data-placeholder-shown` while empty. The item indicator (`✓`) is `hidden` on unselected options.
 
 ```css live
 .size [data-part='trigger'] { min-width: 10rem; display: flex; justify-content: space-between; }
@@ -88,7 +138,7 @@ Zag's data attributes: `[data-scope="select"]` with `[data-part="root"]`, `"labe
 
 ## Positioning
 
-The listbox renders inside the widget's host, next to the trigger, and Zag positions it with `position: absolute` (the `--x` / `--y` variables on the positioner). Inside a container that clips its content (`overflow: hidden` or `auto`: a card, a scrolling panel, a table cell), the open listbox is cut off at the container's edge. Pass `positioning={{ strategy: 'fixed' }}` there: the positioner is then placed relative to the viewport and escapes the clipping (it still follows the trigger when the page scrolls; an ancestor with a `transform`, `filter` or `contain` still clips it). Other options go in the same object: `positioning={{ placement: 'bottom-end', gutter: 4, strategy: 'fixed' }}`.
+The list renders inside the widget's host, next to its trigger, and Zag places it with `position: fixed` by default (as Radix's Popper does; the `--x` / `--y` variables on the positioner). So a container that clips its content (`overflow: hidden` or `auto`: a card, a scrolling panel, a table cell, a `<dialog>`) doesn't cut it off, and it still follows the trigger when the page scrolls. The caveat: an ancestor with a `transform`, `filter`, `perspective` or `contain` becomes the containing block of a fixed element, so inside one (an animated drawer, a scaled canvas) the list is placed and clipped relative to that ancestor. There, or to keep the list in the document flow, pass `positioning={{ strategy: 'absolute' }}`. Other options go in the same object and merge over the default: `positioning={{ placement: 'bottom-end', gutter: 4 }}`.
 
 ## Testing
 

package/dist/guide/ui/tabs.md

@@ -57,7 +57,7 @@ Disabled tabs (`disabled`) are skipped.
 
 ## State, actions and attributes
 
-`state.tabs` is `{ id, selected, orientation }`. Actions: `tabs.SELECT` (a value; a click on a tab sends its own) and `tabs.MOVE` (a value: focus that tab, and select it unless manual). Select a tab from the model with `next('tabs.SELECT', 'billing')`, or from your intent with `'tabs.SELECT': DOM.click('.go-billing').mapTo('billing')`.
+`state.tabs` is `{ id, selected, orientation }`. Actions: `tabs.SELECT` (a value; a click on a tab sends its own) and `tabs.MOVE` (a value: focus that tab, and select it unless manual). Select a tab from the model with `next('tabs.SELECT', 'billing')`, or write the slice in your own reducer: `GO_BILLING: (state) => ({ ...state, tabs: { ...state.tabs, selected: 'billing' } })`. (An intent action named `'tabs.SELECT'` would replace the behavior's own trigger: clicks on the tabs would stop selecting them.)
 
 `tabsAttrs(state.tabs, uid)` returns:
 

package/dist/guide/ui/tooltip.md

@@ -41,13 +41,15 @@ The delays need the timer driver in `run()`. Tests don't: [fake timers](../timer
 
 ## Behavior
 
-- Hovering or focusing the trigger shows the tip after `showDelay`; leaving before that never shows it.
+- Hovering the trigger or giving it the keyboard focus shows the tip after `showDelay`; leaving before that never shows it.
+- Only a focus the browser draws a focus ring for (`:focus-visible`) shows it. A mouse click focuses a button in Chromium and Firefox, so a tip that showed it would stay after the pointer left; a clicked trigger's tip goes with the pointer instead. When a dialog closes and the focus returns to its trigger, the browser decides: after a keyboard close the tip usually shows, after a mouse close it doesn't.
 - Leaving hides it after `hideDelay`. Moving the pointer from the trigger onto the tip keeps it open, so the tip can be read and selected ([WCAG 1.4.13](https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus)).
 - The pointer and the focus count apart: it hides once both have left, so the mouse moving away doesn't hide a tip the keyboard focus still shows.
-- Touch is left out: a tap focuses the trigger, which shows the tip as focus does.
+- Touch is left out: touch pointer events are ignored, and the focus a tap gives isn't `:focus-visible`, so a tap shows no tip.
+- A press on the trigger (pointerdown) hides it at once, and the pointer shows it again only after leaving and coming back, as Radix does: clicking a button doesn't leave its tip over what the click opened.
 - Escape hides it at once, without moving the focus. (The behavior listens for it on the document only while the tip is shown or about to be.)
 
-`state.saveTip` is `{ open, pending, hover, focus }`: `pending` is `'show'` or `'hide'` while a delay runs; `hover` and `focus` say where the pointer and the focus are. The actions are `saveTip.ENTER` and `saveTip.LEAVE` (data: `'hover'` or `'focus'`), `saveTip.SHOW`, `saveTip.HIDE` (the timers), `saveTip.ESCAPE` and `saveTip.TOGGLED`. The timers are declared under the names `saveTip.show` and `saveTip.hide`, next to the component's own [`timers`](../timers.md).
+`state.saveTip` is `{ open, pending, hover, focus, pressed }`: `pending` is `'show'` or `'hide'` while a delay runs; `hover` and `focus` say where the pointer and the focus are. The actions are `saveTip.ENTER` and `saveTip.LEAVE` (data: `'hover'` or `'focus'`), `saveTip.SHOW`, `saveTip.HIDE` (the timers), `saveTip.PRESS` (a pointerdown on the trigger), `saveTip.ESCAPE` and `saveTip.TOGGLED`. The trigger and the tip can be inside a [`<Portal>`](https://sygnal.js.org/advanced/portals/). The timers are declared under the names `saveTip.show` and `saveTip.hide`, next to the component's own [`timers`](../timers.md).
 
 ## Many tooltips: `tooltips()`
 
@@ -71,7 +73,7 @@ function Glossary({ uid }) {
 Glossary.uses = { tips: tooltips({ trigger: '.term', tip: '.tip' }) }
 ```
 
-The options are those of `tooltip()`, with `trigger` and `tip` matching every trigger and every tip. Moving from one term to another while a tip is shown switches at once, without a second delay. `state.tips` is `{ id, open, pending, hover, focus }`: `id` is the tip of the trigger last entered and `open` the id of the tip shown. The actions carry the tip's id: `tips.ENTER` and `tips.LEAVE` (`{ via: 'hover' | 'focus', id }`), `tips.TOGGLED` (`{ id, open }`), plus `tips.SHOW`, `tips.HIDE` and `tips.ESCAPE`.
+The options are those of `tooltip()`, with `trigger` and `tip` matching every trigger and every tip. Moving from one term to another while a tip is shown switches at once, without a second delay. `state.tips` is `{ id, open, pending, hover, focus, pressed }`: `id` is the tip of the trigger last entered and `open` the id of the tip shown. The actions carry the tip's id: `tips.ENTER` and `tips.LEAVE` (`{ via: 'hover' | 'focus', id }`), `tips.TOGGLED` (`{ id, open }`), plus `tips.SHOW`, `tips.HIDE`, `tips.PRESS` (`{ id }`) and `tips.ESCAPE`.
 
 ## Positioning
 
@@ -100,7 +102,7 @@ Safari 26 places the tip wrongly when the trigger is inside a `position: fixed`
 
 - `aria-describedby` on the trigger points at the tip, so screen readers read the tip as the trigger's description. The trigger still needs its own name (its text or `aria-label`).
 - Keep the tip short and plain text; it can't take the focus. For anything interactive, use a [popover](./popover.md).
-- Don't rely on a tooltip for touch users: there is no hover, and a tap focuses the trigger only briefly.
+- Don't rely on a tooltip for touch users: there is no hover, and a tap shows no tip.
 
 ## Testing
 

package/dist/guide/virtual-collections.md

@@ -116,6 +116,8 @@ Rows can have any height, and each can differ. Until a row has been rendered, it
 
 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.
 
+The estimate matters most when it is too low. Rows that haven't been rendered count at `estimateSize`, so with rows taller than the estimate the list's total height is too short until the last rows have been measured: a fast scroll to the end shows blank space where they belong, and the scrollbar jumps as the total grows. Use the rows' real height, and when unsure, err high. In development, [SYG436](https://sygnal.js.org/reference/errors/#syg436) reports a numeric estimate more than 1.3× away from the median of the first 10 measured rows, with that median.
+
 A row must render one element, which is what is measured ([SYG432](https://sygnal.js.org/reference/errors/#syg432) for a fragment).
 
 ## Accessibility
@@ -181,3 +183,4 @@ It doesn't do (yet): horizontal lists, grids, sticky group headers, or scrolling
 | [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 |
+| [SYG436](https://sygnal.js.org/reference/errors/#syg436) | A numeric `estimateSize` is far from the measured row heights (blank space at the end of a fast scroll) |