bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.64

package/dist/ai/BbDropdown.md

@@ -52,7 +52,10 @@ An `items` entry is one of three shapes, and you can mix them freely:
 - a **separator section** — a nested `[ … ]` array, rendered as its own
   divider-separated anonymous group;
 - a **group object** — `{ id, label?, items, selectable?, … }`, a titled and/or
-  selectable section (next sections). A group's heading is its `label` too;
+  selectable section (next sections). A group with plain rows and no
+  `selectable` needs `group: true` to be a group rather than a submenu row;
+  [Titled sections](#titled-sections-group-true-or-groupby) compares it with
+  `groupBy`, which titles the rows of one group. A group's heading is its `label` too;
   add `hideLabel` to keep the `label` for the adaptive sheet title / chips /
   `useBbDropdownContext` while rendering no heading in the menu.
 
@@ -89,6 +92,10 @@ check` flags both (`missing-value`, `duplicate-row-label`) when the items are
   rendering a `bb-dropdown__item--variant-<name>` class hook you style yourself.
 - `disabled` — non-interactive row, skipped by keyboard navigation.
 
+Nothing else on an item reaches the row. An attribute for it (a `data-*` test
+hook, an `aria-*`) goes through `pt:item`, per row with the function form:
+`:pt:item="({ item }) => ({ attrs: { 'data-test': item.value } })"`.
+
 Note how the destructive item below follows the design rule end to end: its
 `onClick` awaits [useConfirm](./composables/useConfirm.md) and acts only on a
 yes (`<BbHost />` mounts once per app, at the root).
@@ -212,9 +219,9 @@ trigger (unless the action moved focus elsewhere, e.g. opened a dialog). When
 the `onClick` returns a promise, the dropdown keeps tracking it after the menu
 has closed: the `activator` slot's `loading` flag stays `true` until it
 settles, and re-clicks on that item are ignored while it's in flight. Reflect
-`loading` on your trigger and you get a busy state for free. Inside a
-selectable group the menu stays open instead, and the row itself carries
-`aria-busy` while its handler runs.
+`loading` on your trigger and you get a busy state for free. A selectable
+row closes the menu only as `closeOnSelect` says (see _Selectable groups_),
+and the row itself carries `aria-busy` while its handler runs.
 
 **Background sync with a busy trigger**
 
@@ -285,8 +292,11 @@ Give an item its own `items` array and it opens a submenu — recursively, to an
 depth. A chevron is shown automatically (it replaces any `append:icon`). On
 desktop, submenus are hover-intent flyouts (opening waits for the parent
 panel's transition; leaving tolerates a short diagonal move); clicking a parent
-row opens its submenu and never closes the menu. On the mobile sheet the same
-items **drill down** one level at a time with a back control instead. Use
+row opens its submenu with focus inside (its search box, when it has one) and
+never closes the menu, and `Escape` closes one level at a time (see
+[Accessibility](#accessibility) for every key). On the mobile sheet the same
+items **drill down** one level at a time with a back control instead
+(`Escape` is the same back step). Use
 submenus to group rarely-used options without crowding the top level; keep the
 nesting shallow (two levels is plenty).
 
@@ -388,10 +398,16 @@ Behavior you can rely on:
 
 - a **single** group is a radio group: re-clicking the selected row keeps it
   (the row's `onClick` still runs, no `item:selected` / `item:unselected`
-  fires). Add `clearable: true` to the group to make that re-click clear it.
-  When the group is the sole top-level selectable group, picking a value
-  (the same one included) also closes the menu;
+  fires). Add `clearable: true` to the group to make that re-click clear it;
+- a change in a **single** group closes the menu and puts focus back on the
+  trigger: a pick (the same value included) or a `clearable` group's clear,
+  wherever the group sits (inside a submenu too) and whatever else the menu
+  holds — a filter menu with a "Role" list and a "Deleted" on/off entry
+  closes after either;
 - a **multiple** group keeps the menu open while you toggle;
+- `close-on-select` overrides both: `true` closes after every selection
+  change (a multiple pick included), `false` never closes on a selection.
+  Plain actions close the menu either way;
 - the dropdown emits `item:selected` / `item:unselected` with the item's
   **value** (its `itemValue` for pipeline groups, else its own `value`) when the user
   picks or unpicks a row, never for your own changes to a group's value — the
@@ -410,8 +426,7 @@ const statusGroup = {
 ```
 
 - The group is still a selectable group (a function counts as `true`): checks,
-  `menuitemcheckbox` / `menuitemradio` roles, the menu stays open while
-  toggling.
+  `menuitemcheckbox` / `menuitemradio` roles, and the same closing rules.
 - A row the function rejects renders **disabled**: clicks do nothing and
   keyboard navigation skips it.
 - The lock holds on a row that is **already selected** — it cannot be
@@ -598,6 +613,54 @@ rows distinct values when it matters:
 - **Submenu parents.** A row that opens a submenu needs a value unique in the
   whole menu; the flyout is addressed by it.
 
+### Titled sections: `group: true` or `groupBy`
+
+Two ways to put headings in a menu, for two different needs:
+
+- **Independent sections, each its own group: `group: true`.** A group object
+  with `group: true` is a titled section (its `label` is the heading) without
+  being selectable; give it `selectable` and it becomes its own chooser. Each
+  group keeps **its own** value (its own companion and `v-model`) and, when
+  `searchable`, its own search field. Use it for sections that answer
+  different questions ("Sort by" / "Show").
+- **One choice, sorted under headings: `groupBy` on one group.** The rows of a
+  single group are listed under section headings, and it stays one group:
+  **one** `v-model`, **one** search field. Use it when the headings only
+  organise the options of one question (categories under their sector).
+
+```vue
+<BbDropdown
+	:items="[
+		{
+			id: 'category',
+			label: 'Category',
+			selectable: true,
+			searchable: true,
+			groupBy: 'sector',
+			items: [
+				{ value: 1, label: 'Bakery', sector: 'Food' },
+				{ value: 2, label: 'Clothing', sector: 'No food' },
+				{ value: 3, label: 'Discount' },
+			],
+		},
+	]"
+>
+	<BbDropdownGroup id="category" v-model="category" />
+</BbDropdown>
+```
+
+- `groupBy` is a field path (`'sector'`, `'owner.team'`) read off each row,
+  or a function `(row) => string | null | undefined`. On a fetched group it
+  reads the **raw item**, so `items: ({ query }) => …` groups the same way.
+- Sections keep the order of their first row. Rows whose `groupBy` gives
+  `null`, `undefined` or `''` have no section: they are listed **first**,
+  before every heading — the same rule as `BbSelect`'s `group-by`.
+- A heading is not a row: the arrows and typeahead skip it, and it is never
+  selected. A search hides a section left without a matching row, heading
+  included.
+- Each titled section is a `role="group"` labelled by its heading, with the
+  look of a group heading. The adaptive sheet shows the same sections.
+
 ### Loading options on demand
 
 For options that come from an API, make the group a **pipeline group**: pass an
@@ -633,8 +696,9 @@ The full grammar:
 - `loadingText` / `emptyText` / `failedText` — placeholder row text per
   group; the dropdown-level `loading-text` / `empty-text` / `failed-text` props
   set the default for all groups, and the `#loading` / `#empty` slots (payload:
-  `{ text, groupId }`, `#empty` also `error`) replace the placeholder rows
-  entirely.
+  `{ text, groupId, query }`, `#empty` also `error`) replace the placeholder
+  rows entirely. `query` is the group's search text (`''` without one), like
+  `BbSelect`'s `#empty="{ query }"`.
 - `dependencies: [...]` + `depsDebounceTime` — re-run the getter (debounced)
   when any dependency changes, e.g. a search field feeding the fetch.
 - `enforceCoherence` — after a re-fetch, drop selected values that no longer
@@ -1112,6 +1176,30 @@ What each knob does:
   `searchable`, which is the one place the three-state `prefill` differs from a
   plain menu group (`'interaction'`, the default, fetches when the group is
   first reached; `true` fetches on mount).
+- **A minimum query length** is the getter's call and the `#empty` slot's
+  copy: return `[]` below it, and read `query` in the slot. The slot also
+  replaces the search-first hint, so one condition covers both:
+
+  ```vue
+  <BbDropdown
+  	:items="[
+  		{
+  			id: 'zone',
+  			label: 'Zone',
+  			searchable: true,
+  			selectable: true,
+  			prefill: false,
+  			filterBy: false,
+  			items: ({ query }) => (query.length < 2 ? [] : api.zones({ q: query })),
+  		},
+  	]"
+  >
+  	<template #empty="{ query, text }">
+  		{{ query.length < 2 ? 'Type at least 2 characters' : text }}
+  	</template>
+  </BbDropdown>
+  ```
+
 - **`stash`** accumulates the items behind _selected_ keys so they stay
   resolvable after the query changes. Without it, selecting in one search and
   then searching for something else leaves the earlier selection unresolvable
@@ -1597,7 +1685,8 @@ const items: BbDropdownItem[] = [
 - `placement` (default `'bottom'`) accepts every floating-UI placement
   (`top`, `bottom-start`, `right-end`, …) plus `'cursor'`; the panel flips
   automatically when there's no room, and the item list caps its height to the
-  available space (scrolling inside).
+  available space (scrolling inside). It is read at open: a change while open
+  applies at the next open.
 - `width` — `'auto'` (default) sizes to content with a 128px floor; a number
   is pixels; a percentage is relative to the **anchor's width**, so
   `width="100%"` makes the menu match its trigger.
@@ -1767,7 +1856,11 @@ the same floor the select's own sheet holds.
 On viewports below the config's `mobileMaxWidth`, the menu renders as a
 bottom-anchored, draggable, auto-sized off-canvas sheet instead of a flyout.
 Nested submenus become drill-down levels with a back control (the parent
-item's text becomes the level title); selection, slots and events behave
+item's text becomes the level title, and the control points toward the
+inline start, mirrored under `dir="rtl"`). `Escape` on a drilled-in level, from
+a row or the level's search box, does what the back control does: back to the
+parent level, focus on the row that opened it. At the top level it closes the
+sheet. Selection, slots and events behave
 exactly as on desktop. The surface is **latched per open**: resizing
 mid-session never swaps a live menu between flyout and sheet.
 
@@ -1893,13 +1986,21 @@ const tags = ref<string[]>(['overdue']);
 </script>
 ```
 
-A look that depends on the ENTRY'S DATA — a destructive action, an entry
-flagged by the row it came from — is a **per-item function** on an entry
-part: `:pt:item="({ item, selected, disabled }) => …"`, called with the menu
-entry and every state as a boolean for it, its result merged after the state entries. Entry
-parts only (`item`, `itemText`, `itemIcon`, `itemDescription`), on the
-instance only; `variant: 'destructive'` on the item is still the shipped look
-for the common case — the function is for a look of your own.
+An entry's `variant` is a state of the entry parts: `pt:item:destructive`
+(or `'item:destructive'` in the object form and the global map) styles the
+destructive entries only, after the base `item` entry and before `selected` /
+`disabled`. So a base look never hides the red: a global
+`item: 'text-ink hover:bg-tint'` plus `'item:destructive': 'text-red-700'`
+keeps it, on the flyout and the phone sheet alike. An entry with no `variant`
+is `default`; a name of your own (`dropdownItemVariants: ['warning']`) works in
+every form, `pt:item:warning` included.
+
+A look that depends on the ENTRY'S DATA — an entry flagged by the row it came
+from — is a **per-item function** on an entry part:
+`:pt:item="({ item, variant, selected, disabled }) => …"`, called with the menu
+entry, every state as a boolean for it and its `variant` as a string, its
+result merged after the state entries. Entry parts only (`item`, `itemText`,
+`itemIcon`, `itemDescription`), on the instance only.
 
 **pt:item as a function — a destructive entry by its data**
 
@@ -2077,6 +2178,22 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 `pt` prop) is typed as `BbDropdownProps['pt']`, never an imported `PtValue`: see
 [passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
 
+#### Item text and icon size
+
+Two knobs on the menu set the rows' size, with BbButton's names: `--fs` the
+label (default `var(--bb-fs)`, the same as BbSelect's options) and
+`--icon-size` the prepend / append icons (default `1rem`). Submenus follow
+them. A denser desktop menu with 13px text and 14px icons:
+
+```vue
+<BbDropdown class="[--fs:13px] [--icon-size:14px]" :items="items" />
+```
+
+They size the desktop menu only. The phone sheet keeps its touch sizes (larger
+text and icons in 44px rows) and never reads them, so there is no desktop-only
+switch to add. A component inside a row (a `BbBadge` in an item slot) keeps its
+own sizes.
+
 ### Works well with
 
 - `BbDropdownButton` — the same `items` model behind a split button when one
@@ -2120,6 +2237,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   a check in `item:append`). Make the group `selectable` and bind its
   `v-model` to the current id — the check, `aria-checked` and the radio role
   come with it.
+- **A server-searched group needs `filterBy: false`.** The default local
+  match runs on the getter's answer too, so a row the server matched on a field
+  the menu doesn't show (an email, a fiscal code) is fetched and then hidden.
+  See [Searchable groups](#searchable-groups).
 - `width` defaults to `'auto'` (content-sized, ≥128px) — not a fixed pixel
   width; pass a number when menus must align across rows.
 - Item `variant`s other than `destructive` render only a class hook — register
@@ -2160,29 +2281,55 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   after the row that opened it; and the adaptive sheet, already a `<dialog>`,
   just steps its menu container aside rather than nesting a second dialog.
   Surfaces with no search field are unchanged.
-- Keyboard is fully handled — don't add your own handlers: `ArrowDown` /
-  `ArrowUp` on the trigger open the menu focusing the first/last item; inside,
-  arrows rove (skipping disabled rows, wrapping), `Home`/`End` jump, typing
-  a letter jumps to the next enabled item whose label starts with it
-  (typeahead, like a native menu), `ArrowRight` enters a submenu, `ArrowLeft` closes the level (or navigates
-  back in the sheet), `Escape` closes and refocuses the trigger. The menu is a
-  single tab stop (rows are `tabindex="-1"` per the ARIA menu pattern): `Tab`
-  leaves the menu and closes it. Focus returns to the activator after an
-  action unless the action moved it (e.g. opened a dialog).
+- Keyboard is fully handled, following the WAI-ARIA APG menu pattern — don't
+  add your own handlers (table below). The menu is a single tab stop (rows are
+  `tabindex="-1"` per the ARIA menu pattern): `Tab` leaves the menu and closes
+  it. Focus returns to the activator after an action unless the action moved
+  it (e.g. opened a dialog).
+- A submenu opener carries `aria-haspopup="menu"`, or `"dialog"` when the
+  submenu has a search field, `aria-expanded`, and `aria-controls` naming the
+  submenu while it is open; the submenu is named after its opener. Under `dir="rtl"` submenus open to the left, their
+  chevron points left, and the two inline arrows swap.
 - The focused row's highlight is keyboard-only (`:focus-visible`). The mobile
   sheet always places real focus on the level's first row when it opens — a
   modal dialog would otherwise skip the `tabindex="-1"` rows — but a menu
   opened by tap or click paints nothing, so it never looks pre-selected.
 
+#### Keyboard
+
+| Key                            | Where                                   | What happens                                                                  |
+| ------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------- |
+| `ArrowDown` / `ArrowUp`        | trigger                                 | open the menu, focus on the first / last row                                  |
+| `ArrowDown` / `ArrowUp`        | row                                     | next / previous enabled row of the same level, wrapping                       |
+| `ArrowDown` / `ArrowUp`        | search box                              | first / last row of its level                                                 |
+| `Home` / `End`                 | row                                     | first / last of the level (`Home` lands on its search box, when it has one)   |
+| a letter                       | row                                     | the level's next enabled row whose label starts with what was typed           |
+| `ArrowRight`, `Enter`, `Space` | submenu opener                          | open the submenu, focus on its search box or first row                        |
+| click                          | submenu opener                          | the same: open it with focus inside                                           |
+| hover                          | submenu opener                          | open it; focus never moves into it                                            |
+| `ArrowLeft`                    | row in a submenu                        | close that level, focus on its opener (the search box keeps it for the caret) |
+| `Escape`                       | anywhere in a submenu (row, search box) | close that level only, focus on its opener: one level per press               |
+| `Escape`                       | top level                               | close the menu, focus on the trigger                                          |
+| pointer leaves the menu        | focus inside a submenu                  | the submenu closes, focus lands on its opener                                 |
+| `Tab`                          | inside                                  | leave the menu, which closes                                                  |
+
+`ArrowLeft` / `ArrowRight` read in the row's direction: swapped under
+`dir="rtl"`. A popover or dialog opened from an item takes `Escape` first;
+the menu gets it back once that closes. On the mobile sheet the drill-down
+uses `ArrowRight` / `ArrowLeft` and its back control; `Escape` on a drilled-in
+level (row or search box) goes back one level, focus on the row that opened
+it, and at the top level closes the sheet.
+
 ## Props
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `footer`, `header`, `input`, `item`, `itemDescription`, `itemIcon`, `itemText`, `list`, `panel`, `root`, `sheet`. States: `disabled`, `open`, `selected`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDropdownProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `footer`, `header`, `input`, `item`, `itemDescription`, `itemIcon`, `itemText`, `list`, `panel`, `root`, `sheet`. States: `activeLink`, `disabled`, `exactActiveLink`, `open`, `selected`, `default`, `destructive`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDropdownProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | An external activator element or component ref: the activator slot is not rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` / `aria-controls`) are attached to it; don't add your own. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom sheet that drills into submenus one level at a time instead of hover flyouts; slots and selection are unchanged. Unset: the global `config.adaptive`. |
 | `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `the activator element` |  | The element the panel positions against when it should differ from the activator (a wrapper the activator is part of); an HTMLElement or component ref. It also drives a percentage `width`. Ignored with `placement="cursor"`. |
 | `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Keeps the panel inside this element alongside its trigger (sideways for a menu above or below); away from the trigger it may pass the edge, and only the viewport flips it. An HTMLElement, a component ref or a CSS selector: a `useTemplateRef`, never `$refs.x` (not reactive). |
+| `closeOnSelect` | `boolean \| undefined` | `unset (close after a single-choice change)` |  | Whether a selection closes the menu. Unset: a change in a single-choice group closes it (an untick too, at any depth); a `multiple` group stays open. `true`: every selection change closes it. `false`: none does. |
 | `compact` | `boolean \| undefined` | `false` |  | Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet rows 44px → 36px (a sheet row stays a touch target). The label size does not change. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
 | `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too), and keeps its rows after a close. Without it the rows mount on each open and go once the menu has closed. |
@@ -2223,9 +2370,13 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `activeLink` | Per node, on the entry parts: an entry whose link (`to` / `href`) points at the current page or one of its ancestors — exactly when its `activeClass` is on. The weakest state. |
+| `exactActiveLink` | Per node, on the entry parts: an entry whose link points at the current page itself — its `exactActiveClass` is on. |
 | `selected` | Per node, on the entry parts: a selectable group's checked entry. |
 | `disabled` | Per node, on the entry parts: an entry that is disabled. |
 | `open` | Component-wide: the menu is open. |
+| `default` | Per entry, on the entry parts: an entry with `variant: 'default'` or none. Merged after the part's base entry and before its states, so the real states still win. |
+| `destructive` | Per entry, on the entry parts: `variant: 'destructive'`. Below the real states, like every variant. |
 
 ## Events
 
@@ -2240,12 +2391,12 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `activator` — scope: `BbDropdownActivatorSlotProps` `{ disabled?: boolean; loading: boolean; open: boolean; placement: Placement \| "cursor"; props: BbDropdownActivatorProps }` — The element that triggers the dropdown to open. Spread `props` onto your trigger element.
 - `default` — scope: `any` — Hosts `<BbDropdownGroup>` companions. They register their group with the dropdown and render nothing themselves.
-- `empty` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; text: string; error?: unknown }` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group.
+- `empty` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; query: string; text: string; error?: unknown }` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group.
 - `footer` — scope: `BbDropdownEdgeSlotProps` `{ disabled?: boolean; open: boolean; placement: Placement \| "cursor" }` — Content pinned to the bottom of the dropdown panel, outside the scroll area. Stays visible while the items scroll and is separated from them by a divider — for action buttons.
 - `header` — scope: `BbDropdownEdgeSlotProps` `{ disabled?: boolean; open: boolean; placement: Placement \| "cursor" }` — Content pinned to the top of the dropdown panel, outside the scroll area. Stays visible while the items scroll and is separated from them by a divider — for a title or a filter field.
-- `item:append` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; label: string }` — The trailing region of every row (and group title line), replacing its `append:icon`. A named slot wins over it; the submenu chevron and the check on a selected row take its place.
-- `item:prepend` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; label: string }` — The leading region of every row (and group title line), replacing its `prepend:icon`. A row's own or its group's named slot wins over it.
-- `loading` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; text: string; error?: unknown }` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group.
+- `item:append` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; label: string; activeLink?: boolean; exactActiveLink?: boolean }` — The trailing region of every row (and group title line), replacing its `append:icon`. A named slot wins over it; the submenu chevron and the check on a selected row take its place.
+- `item:prepend` — scope: `BbDropdownItemSlotProps` `{ description?: string; disabled?: boolean; group: BbDropdownSlotGroup; groupTitle: boolean; level: number; index: number; item: InternalItem; loading: boolean; open: boolean; placement: Placement \| "cursor"; selected: boolean; label: string; activeLink?: boolean; exactActiveLink?: boolean }` — The leading region of every row (and group title line), replacing its `prepend:icon`. A row's own or its group's named slot wins over it.
+- `loading` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; query: string; text: string; error?: unknown }` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group.
 - `#<value>` (named from data) — scope: `BbDropdownItemSlotProps` — One row's content (label and description), by its value; in a fetched group, by its resolved `itemValue`. Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `activator`, `default`, `empty`, `footer`, `header`, `item`, `loading`.
 - `#<value>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — One row's leading region; replaces its `prepend:icon`.
 - `#<value>:append` (named from data) — scope: `BbDropdownItemSlotProps` — One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
@@ -2276,11 +2427,11 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - `BbDropdown` _(this component)_ — its own template binds: `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`
   - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
-    - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+    - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `span.bb-badge__append-icon`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
   - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
     - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
       - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
-    - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
+    - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `span.bb-button__icon`, `icon` → `BbIcon`, `icon` → `span.bb-button__prepend-icon`, `text` → `span.bb-button__text`, `icon` → `span.bb-button__append-icon`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
       - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - Also mounts `CommonPopover`, `DropdownPipelineResolver`
 

package/dist/ai/BbDropdownButton.md

@@ -379,6 +379,13 @@ activator slot: the toggle button is part of the component's contract.
 </BbDropdownButton>
 ```
 
+### Icons on the main button
+
+`icon`, `prepend:icon` and `append:icon` belong to the main button, as on
+`BbButton`, and so do the slots of the same names: `#prepend:icon="{ loading,
+activeLink }"` swaps its glyph with its states, inside its `icon` part. The
+toggle keeps its chevron (`toggle:icon` above).
+
 ### Selectable groups in a split button
 
 Because it shares `BbDropdown`'s items, a split button can also host a
@@ -637,7 +644,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `footer`, `header`, `icon`, `input`, `item`, `itemDescription`, `itemIcon`, `itemText`, `main`, `panel`, `root`, `sheet`, `spinner`, `text`, `toggle`. States: `disabled`, `loading`, `open`, `selected`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDropdownButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `footer`, `header`, `icon`, `input`, `item`, `itemDescription`, `itemIcon`, `itemText`, `main`, `panel`, `root`, `sheet`, `spinner`, `text`, `toggle`. States: `activeLink`, `disabled`, `exactActiveLink`, `loading`, `open`, `destructive`, `ghost`, `link`, `outline`, `primary`, `secondary`, `default`, `selected`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbDropdownButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom sheet that drills into submenus one level at a time instead of hover flyouts; slots and selection are unchanged. Unset: the global `config.adaptive`. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
@@ -646,6 +653,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `block` | `boolean \| undefined` | `false` |  | Displays the component as full width. |
 | `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
 | `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
+| `closeOnSelect` | `boolean \| undefined` | `unset (close after a single-choice change)` |  | Whether a selection closes the menu. Unset: a change in a single-choice group closes it (an untick too, at any depth); a `multiple` group stays open. `true`: every selection change closes it. `false`: none does. |
 | `compact` | `boolean \| undefined` | `false` |  | Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet rows 44px → 36px (a sheet row stays a touch target). The label size does not change. |
 | `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
@@ -727,10 +735,19 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `activeLink` | Component-wide while the main button is a link to the current page or one of its ancestors (its `activeClass` is on); also per node, on the entry parts: a menu entry whose link is. The weakest state. |
+| `exactActiveLink` | Component-wide while the main button is a link to the current page itself (its `exactActiveClass` is on); also per node, on the entry parts. |
 | `selected` | Per node, on the entry parts only (`item`, `itemText`, `itemIcon`, `itemDescription`): a selectable group's checked entry. `pt:root:selected` is a type error, not a silent no-op. |
 | `disabled` | Component-wide while the control is `disabled`; also per node, on the entry parts: a menu entry that is disabled. |
 | `open` | Component-wide: the menu is open. |
 | `loading` | Component-wide: `loading` is on — the main button shows its spinner. |
+| `destructive` | Per entry, on the entry parts: `variant: 'destructive'`. Below the real states, like every variant. |
+| `ghost` | Component-wide: `variant="ghost"`. Below the real states, like every variant. |
+| `link` | Component-wide: `variant="link"`. Below the real states, like every variant. |
+| `outline` | Component-wide: `variant="outline"`. Below the real states, like every variant. |
+| `primary` | Component-wide: `variant="primary"`. Merged after the part's base entry and before its states, so `disabled` / `loading` still win. |
+| `secondary` | Component-wide: `variant="secondary"`. Below the real states, like every variant. |
+| `default` | Per entry, on the entry parts: an entry with `variant: 'default'` or none. Merged after the part's base entry and before its states, so the real states still win. |
 
 ## Events
 
@@ -743,21 +760,24 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
+- `append:icon` — scope: `BbButtonIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; pressed: boolean; loading: boolean; disabled: boolean }` — The main button's trailing icon, replacing `append:icon`.
 - `default` — scope: `any` — The main button's label (falls back to `text`).
 - `dropdown` — scope: `any` — Menu companions, forwarded into the dropdown: a `<BbDropdownGroup>` binding a group of `items` by id. A `#dropdown` slot keeps the toggle even with no `items`.
-- `empty` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; text: string; error?: unknown }` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group. Forwarded to the underlying `BbDropdown`.
+- `empty` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; query: string; text: string; error?: unknown }` — Replaces the default "no data" placeholder row shown in a pipeline group that resolved to no items. Rendered once per empty group. Forwarded to the underlying `BbDropdown`.
 - `footer` — scope: `BbDropdownButtonEdgeSlotProps` `{ disabled?: boolean; open: boolean; placement: Placement \| "cursor" }` — Content pinned to the bottom of the dropdown panel, outside the scroll area.
 - `header` — scope: `BbDropdownButtonEdgeSlotProps` `{ disabled?: boolean; open: boolean; placement: Placement \| "cursor" }` — Content pinned to the top of the dropdown panel, outside the scroll area.
+- `icon` — scope: `BbButtonIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; pressed: boolean; loading: boolean; disabled: boolean }` — The main button's icon, replacing the `icon` prop; inside its `icon` part (`pt:icon`, `--icon-size`, the loading spinner), with its states.
 - `item:append` — scope: `BbDropdownButtonItemSlotProps` `{ disabled?: boolean; index: number; item: InternalItem; open: boolean; placement: Placement \| "cursor"; label: string }` — The trailing region of every menu row, replacing its `append:icon`; the submenu chevron and the check on a selected row take its place (BbDropdown's rules).
 - `item:prepend` — scope: `BbDropdownButtonItemSlotProps` `{ disabled?: boolean; index: number; item: InternalItem; open: boolean; placement: Placement \| "cursor"; label: string }` — The leading region of every menu row, replacing its `prepend:icon` (BbDropdown's rules).
-- `loading` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; text: string; error?: unknown }` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group. Forwarded to the underlying `BbDropdown`.
-- `#<value>` (named from data) — scope: `BbDropdownItemSlotProps` — One row's content (label and description), by its value; in a fetched group, by its resolved `itemValue`. Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `default`, `dropdown`, `empty`, `footer`, `header`, `item`, `loading`.
+- `loading` — scope: `BbDropdownPlaceholderSlotProps` `{ groupId?: string; query: string; text: string; error?: unknown }` — Replaces the default loading placeholder row shown in a pipeline group while its async items load. Rendered once per loading group. Forwarded to the underlying `BbDropdown`.
+- `prepend:icon` — scope: `BbButtonIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; pressed: boolean; loading: boolean; disabled: boolean }` — The main button's leading icon, replacing `prepend:icon`.
+- `#<value>` (named from data) — scope: `BbDropdownItemSlotProps` — One row's content (label and description), by its value; in a fetched group, by its resolved `itemValue`. Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `default`, `dropdown`, `empty`, `footer`, `header`, `icon`, `item`, `loading`.
 - `#<value>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — One row's leading region; replaces its `prepend:icon`.
 - `#<value>:append` (named from data) — scope: `BbDropdownItemSlotProps` — One row's trailing region; replaces its `append:icon` and its submenu chevron. The check takes its place on the selected row.
 - `#<groupId>:item` (named from data) — scope: `BbDropdownItemSlotProps` — The content of every row of that group, and no other; a row's own `#<value>` still wins.
 - `#<groupId>:item:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — The leading region of every row of that group — e.g. an avatar per record, drawn from `item.meta`, while other rows keep their `prepend:icon`.
 - `#<groupId>:item:append` (named from data) — scope: `BbDropdownItemSlotProps` — The trailing region of every row of that group; replaces their `append:icon`. The check takes its place on the selected row.
-- `#<groupId>` (named from data) — scope: `BbDropdownItemSlotProps` — That group's title line (the group is passed as `item`, `groupTitle` is `true`). Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `default`, `dropdown`, `empty`, `footer`, `header`, `item`, `loading`.
+- `#<groupId>` (named from data) — scope: `BbDropdownItemSlotProps` — That group's title line (the group is passed as `item`, `groupTitle` is `true`). Reserved names (their slot is one of this component's own, so an item value or column key spelled like them is an error): `default`, `dropdown`, `empty`, `footer`, `header`, `icon`, `item`, `loading`.
 - `#<groupId>:prepend` (named from data) — scope: `BbDropdownItemSlotProps` — The leading region of that group's title line.
 - `#<groupId>:append` (named from data) — scope: `BbDropdownItemSlotProps` — The trailing region of that group's title line.
 
@@ -771,11 +791,11 @@ States are listed in precedence order: when two are on at once and their entries
 - Listed nodes are the ones `BbDropdownButton`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is `manifest/components/BbDropdownButton.tree.json`.
 
 - `BbDropdownButton` _(this component)_ — hands `BbButton` the pt map `{ main: 'root', icon: 'icon', spinner: 'spinner', text: 'text' }` (ours → theirs); hands `BbDropdown` the pt map `{ panel: 'panel', sheet: 'sheet', header: 'header', footer: 'footer', input: 'input', item: 'item', itemText: 'itemText', itemIcon: 'itemIcon', itemDescription: 'itemDescription' }` (ours → theirs); hands `BbButton` the pt map `{ toggle: 'root' }` (ours → theirs)
-  - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
+  - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `span.bb-button__icon`, `icon` → `BbIcon`, `icon` → `span.bb-button__prepend-icon`, `text` → `span.bb-button__text`, `icon` → `span.bb-button__append-icon`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbSpinner`
     - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
     - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
-      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `span.bb-badge__append-icon`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbButton`, `BbDropdownList`
       - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`
         - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`

package/dist/ai/BbForm.md

@@ -507,14 +507,16 @@ on the problem instead of hunting for it. A field inside a `v-show`-hidden
 section, an `inert` subtree or `hidden` content is skipped; a failing path with
 no field mounted has nothing to focus.
 
-It also emits **`invalid`** with `{ errors, values }`: `errors` maps every
-failing path to all its messages, `{ [path]: string[] }` — the same shape and
-keys as the form's `errors` (`address.city`, `lines.0.qty`) — including the
-paths that are not on screen. That is what a wizard needs to jump to the
-step holding the error; focus runs after your handler, so the field that just
-came back on screen is the one that gets it. A handler that moves focus itself
-(to an [error summary](#a-summary-of-the-problems-at-the-top-of-a-long-form),
-say) keeps it: the form leaves focus alone then.
+It also emits **`invalid`** with `{ errors, values, unmatched, source }`:
+`errors` maps every failing path to all its messages, `{ [path]: string[] }` —
+the same shape and keys as the form's `errors` (`address.city`, `lines.0.qty`)
+— including the paths that are not on screen. That is what a wizard needs to
+jump to the step holding the error; focus runs after your handler, so the
+field that just came back on screen is the one that gets it. A handler that
+moves focus itself (to an [error summary](#a-summary-of-the-problems-at-the-top-of-a-long-form),
+say) keeps it: the form leaves focus alone then. `unmatched` holds the paths
+no field claims (the same shape as `unmatchedErrors`), `{}` when every error
+has its field.
 
 ```vue
 <BbForm
@@ -529,13 +531,38 @@ say) keeps it: the form leaves focus alone then.
 > Behaviour change in 3.0.0-beta.41: a failed submit used to leave focus where
 > it was (usually on the submit button).
 
-**Server errors move focus the same way.** `setErrors(map)` focuses the first
-field that got an error and is on screen, in page order (not the first key of
-the map). It holds back when focus is no longer the form's: if the user has
-moved on to something outside the form while the request ran, or if nobody
-has submitted the form yet and focus is on the page (a page that opens with
-errors in its props). Keys that match no field, and an empty map, move
-nothing; `setErrors(map, { focus: false })` never moves it.
+**Server errors move focus the same way, and emit the same event.**
+`setErrors(map)` focuses the first field that got an error and is on screen,
+in page order (not the first key of the map). It holds back when focus is no
+longer the form's: if the user has moved on to something outside the form
+while the request ran, or if nobody has submitted the form yet and focus is
+on the page (a page that opens with errors in its props). Keys that match no
+field, and an empty map, move nothing; `setErrors(map, { focus: false })`
+never moves it. Either way a non-empty map emits `invalid` first, with
+`source: 'server'`, and so does a [`field-errors`](#the-pages-errors-object-field-errors)
+value that brings messages. Errors a page loads with emit nothing: nobody
+submitted. One `@invalid` handler then covers both answers (`source:
+'submit'` for a failed submit).
+
+Errors no field shows (a 422 keyed on `assignments.0.id`, drawn by hand in
+its row) get no focus from the form: bring their row on screen in the
+handler, and the form leaves focus where you put it.
+
+```ts
+import type { BbFormInvalidPayload } from 'bitboss-ui';
+
+const onInvalid = ({ unmatched }: BbFormInvalidPayload) => {
+	const key = Object.keys(unmatched).find((path) =>
+		path.startsWith('assignments.')
+	);
+	if (!key) return;
+	const row = document.querySelector<HTMLElement>(
+		`[data-row="${key.split('.')[1]}"]`
+	);
+	row?.scrollIntoView({ block: 'center' });
+	row?.focus({ preventScroll: true }); // a row with tabindex="-1"
+};
+```
 
 ### A summary of the problems at the top of a long form
 
@@ -752,10 +779,10 @@ How it works:
   empties on a successful one, never while the user types: fixing one field
   does not reshuffle the box above them. The messages under the fields
   update as usual.
-- **Server errors** (`setErrors` after a 422) do not emit `invalid`. To list
-  them too, build the same list from
-  `{ ...form.errors.value, ...form.unmatchedErrors.value }` right after the
-  call. A path no field has (in `unmatchedErrors`) is an item without a link.
+- **Server errors list the same way.** A 422 through `setErrors` or
+  `field-errors` emits `invalid` too (`source: 'server'`), so the same handler
+  builds the box from the server's answer. A path no field has (in
+  `unmatched`) is an item with no field to focus.
 
 **When not to use it: a short form**, where every field is on screen. A
 failed submit already focuses the first invalid field and every message sits
@@ -1357,6 +1384,11 @@ async function save(values: Record<string, unknown>) {
 }
 ```
 
+A value that brings a message the object did not have (or comes back after a
+new submit) is an answer: it emits `invalid` with `source: 'server'` and
+moves focus like `setErrors`. The same content passed again, a message
+leaving, and the object the page loads with do neither.
+
 ##### A message of your own that comes and goes
 
 The object does not have to come from a server. A check that spans fields is
@@ -1514,8 +1546,9 @@ const save = async (values: Record<string, unknown>) => {
   instead: it shows while its key holds a message and goes the moment it
   does not. Calling `validate()` to wipe a `setErrors` message runs every
   rule on every field, so it puts messages on fields the user never touched.
-- `setErrors` does not emit `invalid`. It does move focus to the first failing
-  field on screen, like a failed submit (`{ focus: false }` opts out; see
+- `setErrors` emits `invalid` (`source: 'server'`) for a non-empty map, then
+  moves focus to the first failing field on screen, like a failed submit
+  (`{ focus: false }` opts out of the focus, not the event; see
   [A failed submit focuses the first invalid field](#a-failed-submit-focuses-the-first-invalid-field)).
 
 #### Fields on a step you left, and the step badge
@@ -1833,7 +1866,7 @@ marker stays consistent with the rules.
 
 ## Events
 
-- `invalid` — `(payload: BbFormInvalidPayload): void` — Fired when a submit fails validation, after the form has focused the first invalid field that is on screen. `errors` also holds paths with no field showing, so a wizard can jump to the step that has one.
+- `invalid` — `(payload: BbFormInvalidPayload): void` — Fired when a submit fails validation (`source: 'submit'`) or server errors land (`'server'`: `setErrors()`, a new `field-errors` message), before the form's own focus; a handler that moves focus keeps it. `unmatched`: the paths no field claims.
 - `submit` — `(values: BbFormSubmitValues<S>, meta: BbFormSubmitMeta): void` — Fired only when every field passes. Carries the values — with a schema, its parsed OUTPUT (transforms and coercions applied), typed from it.
 
 ## Slots