bitboss-ui 3.0.0-beta.57 → 3.0.0-beta.59

package/dist/ai/BbDialog.md

@@ -203,8 +203,9 @@ reads `data` in two places:
   `data` (typed `any`, so `data.name` reads with no cast);
 - in code, `useBbDialogContext<T>(id)` returns it typed, along with `open`,
   `show(data?)` and `hide()`. A component inside the dialog can call it too.
-  On an open dialog, `show(newData)` replaces the data and a bare `show()`
-  (or a trigger without `data`) keeps it.
+  A `show()` on an open dialog changes nothing: it joins the opening (its
+  promise, its data); the new data, trigger and `onComplete` are ignored. A
+  show during the close transition opens it again.
 
 `data` stays set until the close transition has run, so the content never
 flashes empty while the dialog fades out. The edit-record example in
@@ -241,7 +242,8 @@ The rules:
 - **An open before the dialog mounts waits for it.** A `show()`, or a
   `v-bb-dialog` click whose own handler renders the dialog through a `v-if`,
   is held until the dialog registers, so one click opens it (up to 1s; then
-  it settles `'missing'` with a dev warning, and `onComplete` never runs).
+  it settles `'missing'` with a dev warning, and `onComplete` never runs). A
+  `hide()` meanwhile cancels a held `show()`, silently: it settles `'hide'`.
   The warning suggests the nearest registered id for a typo, and says when a
   dialog with that id exists but is out of reach (inside an on-demand dialog,
   which is private, or parked by KeepAlive) or is a `BbOffCanvas`.
@@ -323,7 +325,6 @@ const replace = (saved: Member) => {
   | `'close'`                 | the ✕ or the slots' `close()`                                                                                    |
   | `'swipe'`                 | the phone sheet swiped away                                                                                      |
   | `'hide'`                  | `hide()`, or the model set to `false` (also a bound `v-model` whose parent refused the open)                     |
-  | `'replaced'`              | a newer `show()` on the open dialog took over                                                                    |
   | `'missing'`               | no dialog with that id mounted within 1s                                                                         |
   | `'unmounted'`             | the dialog unmounted (or KeepAlive parked it), or a waiting `show()`'s caller went away                          |
   | `'failed'`                | an on-demand dialog could not render                                                                             |
@@ -340,6 +341,101 @@ const replace = (saved: Member) => {
   flags the unawaited promise of a bare `edit.show(row)`, write
   `void edit.show(row)`.
 
+#### The page saves: a promise from `onComplete`
+
+When the page owns the save (it knows the endpoint, the list to update),
+`onComplete` returns the request's promise. `complete(value)` calls it first,
+and the dialog stays open and **locked** until it settles: the ✕, Cancel,
+Escape and the backdrop are refused, and a footer `BbButton` whose click
+returns `complete(value)` spins. Resolved, the dialog closes and the opening
+settles `{ completed: true, value }`; rejected, it stays open with its data
+and `complete()` rejects with the same error, so the dialog can show it.
+
+```vue
+<template>
+	<BbButton v-bb-dialog="{ id: 'rename', data: row, onComplete: save }">
+		Rename
+	</BbButton>
+	<BbDialog id="rename" v-slot="{ data, complete }" title="Rename">
+		<BbForm :model="data" @submit="() => complete(data)">
+			<BbTextInput label="Name" name="name" />
+			<BbButton type="submit">Save</BbButton>
+		</BbForm>
+	</BbDialog>
+</template>
+```
+
+From code: `edit.show(row, { onComplete: save })` (both the id and the
+component handle). A `save` function passed in `data` is no longer needed.
+A sync `onComplete` (or none) closes at once, as before.
+
+`onComplete` is just a function. A trigger inside a child component gets the
+page's save the way your app already shares things: a function prop
+(`:save="saveMember"`), a page `provide` / `inject`, or a store action. Not an
+emit: an emit cannot return the promise.
+
+To show a rejected save's field errors, keep them in a `ref` bound on the
+form, `<BbForm :field-errors="fieldErrors">` (BbForm § The page's errors
+object): the dialog stays open, and each message lands under its field until
+the user edits it.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+
+const fieldErrors = ref<Record<string, string[]>>({});
+</script>
+
+<template>
+	<BbDialog id="rename" v-slot="{ data, complete }" title="Rename">
+		<BbForm
+			:field-errors="fieldErrors"
+			:model="data"
+			@submit="
+				() =>
+					complete(data).catch((error) => {
+						// Your save's rejection: the 422 body's `errors` by field path.
+						fieldErrors = error.errors ?? {};
+					})
+			"
+		>
+			<BbTextInput label="Name" name="name" />
+			<BbButton type="submit">Save</BbButton>
+		</BbForm>
+	</BbDialog>
+</template>
+```
+
+With Inertia, the page's `useForm().errors` is that object already; the
+record-form recipe (`ai/recipes/inertia/record-form.md`) binds
+`<BbForm :field-errors="form.errors">` the same way.
+
+An Inertia visit (`router.put`, `form.put`) returns no promise and never
+rejects on its own, so `onComplete` wraps it: a validation error rejects
+with the errors (the example above reads `error.errors`), success resolves,
+and a visit cut short by another visit resolves too, closing the dialog.
+
+```ts
+import { router } from '@inertiajs/vue3';
+
+type User = { id: number; name: string };
+
+const save = (user: User) =>
+	new Promise<void>((resolve, reject) => {
+		router.put(`/users/${user.id}`, user, {
+			onSuccess: () => resolve(),
+			onError: (errors) => reject({ errors }),
+			// Cancelled or interrupted: close. Anything else that ends here
+			// unsettled (a 500, a network error) keeps the dialog open.
+			// Both are no-ops after onSuccess / onError.
+			onFinish: (visit) =>
+				visit.cancelled || visit.interrupted
+					? resolve()
+					: reject(new Error('The save failed')),
+		});
+	});
+```
+
 #### The data is a copy
 
 Every opening holds its own **reactive copy** of the `data` it was given
@@ -421,7 +517,7 @@ default.
 			</div>
 		</template>
 		<template #footer="{ data, close, complete, reset }">
-			<!-- `reset()` restores the default, on an edit too: it clears. -->
+			<!-- `reset()` clears the default's keys; an edit keeps its `id`. -->
 			<BbButton variant="ghost" @click="reset">Clear</BbButton>
 			<BbButton variant="ghost" @click="close">Cancel</BbButton>
 			<BbButton
@@ -462,9 +558,11 @@ const save = (saved: Member) => {
 </script>
 ```
 
-- **`reset()`** (the slots', or `useBbDialogContext(id).reset()`) restores a
-  fresh copy of `default-data`, on an edit too: it clears the form, it doesn't
-  go back to the row. Cancel is what discards an edit.
+- **`reset()`** (the slots', or `useBbDialogContext(id).reset()`) restores
+  the keys `default-data` declares from a fresh copy, on an edit too, and keeps
+  every key it doesn't declare: the row's `id` stays, so a cleared edit still
+  saves as an edit. It doesn't go back to the row's values; Cancel is what
+  discards an edit.
 - **Every close resets it** as well: nothing to do on `@show` or `@hidden`.
 - **An object, not a function.** The dialog copies it every time and never
   writes it, so a module constant is safe.
@@ -577,10 +675,16 @@ const createForDesign = async () => {
   KeepAlive park. A flow that changes the URL inside one dialog (a wizard
   whose steps are routes) opens it from the parent route or the persistent
   layout, which stays mounted. A `show()` from a store lives until closed.
-- **A second `show()` stacks** a second instance on top, with its own promise.
-  Give a create flow one trigger: several buttons each opening the same
-  component stack copies. Opened by id, the single mounted dialog dedupes
-  instead.
+- **From a store.** Create the handle in the setup store's body (or under
+  `app.runWithContext()`), then `show()` / `hide()` from its actions or a
+  router hook. Created in a plain module, outside any injection context,
+  `show()` settles `'failed'` with a dev warning.
+- **One handle, one dialog.** `useBbDialogContext(Component)` is the same
+  handle as the id form (`isReady`, `open`, `data`, `show`, `hide`,
+  `complete`, `reset`), about its own dialog: a `show()` while it is open
+  joins it. Another handle (another `useBbDialogContext(Component)` call, or
+  another trigger element) opens its own instance on top, with its own
+  promise. `isReady` says a `<BbHost />` is mounted to render it.
 - **Each opening gets its own DOM id**, so two stacked instances stay valid
   HTML; `aria-controls` on the trigger follows it. A template dialog keeps the
   `id` you gave it. To find one in an e2e test, use its role and title,
@@ -968,6 +1072,18 @@ const form = useBbFormContext('edit-member-form');
   field uses, `form.setErrors({ ...errors, _request: [message] })`, and shows in
   the form's `unmatchedErrors` (see BbForm § Server errors).
 
+#### Steps in one dialog
+
+- **Each step's first field gets `autofocus`**: it fires when the field
+  mounts, so focus follows the step with no watcher (`focus-target` picks only
+  where the opening starts).
+- **A final success step with no field is a status region**
+  (`role="status"`), announced as it appears, not a focus target.
+- **A footer button that changes type in place** (Next, `type="button"`,
+  becoming Accept, `type="submit"`, during its own click): give each its own
+  `key`. Unkeyed, Vue reuses the element, its type flips mid-click, and the
+  click on Next submits the form.
+
 ### Lifecycle events and lazy content
 
 Four events bracket the transitions — `show` fires as the model turns `true`,
@@ -987,11 +1103,16 @@ Every way to close, side by side:
 | Escape, Back on a URL dialog, a backdrop click, a swipe | the user     | yes: `persistent` too                 | `reason: 'escape'` / `'backdrop'` / `'swipe'` | on the key, Back, click or swipe                                                    |
 | `hide()` (context), the model set to `false`            | your code    | no                                    | `{ completed: false, reason: 'hide' }`        | at once                                                                             |
 | `complete(value)` (slots, context)                      | your code    | no                                    | `{ completed: true, value }`                  | at once                                                                             |
-| `@hide`                                                 | the dialog   | it reports a close, it can't stop one | settled together with it                      | as any close above **starts**                                                       |
+| `@hide`                                                 | the dialog   | it reports a close, it can't stop one | emits it (the same object)                    | as any close above **starts**                                                       |
 | `@hidden`                                               | the dialog   | it reports a close, it can't stop one | already settled                               | after the close transition; focus returns, `data` clears and the body unmounts then |
 
 A refused close fires nothing and settles nothing. Use `@hide` for what
-follows the decision (a toast, a refresh), `@hidden` for teardown.
+follows the decision (a toast, a refresh), `@hidden` for teardown. `@hide`
+carries the opening's result, so a live preview reverts on a dismissal with
+no flag of its own: `@hide="(r) => { if (!r.completed) restore() }"`. To
+tell a save from a cancel, close a save with `complete()` (slots or context),
+not by writing the model: on a `v-model` dialog too, it closes through the
+model and reports `{ completed: true }`.
 
 The body lives **per opening**: nothing inside the dialog renders until it
 opens, and the body unmounts after the close transition (right after
@@ -1003,7 +1124,9 @@ tests that query content before opening): `data` still clears while closed (to
 `undefined`, or the `default-data` copy), so an eager body guards its own
 reads. `transition-duration` (ms, default
 `250`) times both the open/close animation and when `hidden` fires — reopening
-during the close transition keeps the dialog open instead of snapping shut.
+during the close transition keeps the dialog open instead of snapping shut, with
+a fresh body: every new opening gets one, a reopen mid-close included (an
+`eager` body is kept).
 
 ### Size
 
@@ -1056,6 +1179,11 @@ Every dismissal path is governed by two props, and by a form inside:
   - `true`: always locked.
   - `false`: never locked, not even mid-save. Closing mid-save is then on you.
 
+  Binding it to your own flag: beside a `BbForm`, another async action (a
+  footer Delete) binds `:prevent-close="deleting || undefined"`; a plain
+  `false` while idle would switch the form's lock off. A dialog with no
+  `BbForm` binds `:prevent-close="saving"`.
+
 `persistent` keeps the ✕ (and the slots' `close`) as the deliberate exit;
 `prevent-close` removes every exit but the model.
 
@@ -1392,7 +1520,26 @@ const route = useRoute();
 ```
 
 Template dialogs only: a dialog opened on demand has no place in the page URL
-(`navigation` is ignored there, with a dev warning). On the phone the adaptive
+(`navigation` is ignored there, with a dev warning). A wrapper component that
+should live in the URL is rendered in the page and opened by id: reload opens
+it, Back closes it, closing strips the key. State it needs fresh on every
+opening (a form object made in setup) goes in its body, a small component
+inside the BbDialog whose setup runs per opening, or in the opening's `data`
+with `default-data`:
+
+```vue
+<!-- CreatePatientDialog.vue renders
+     <BbDialog id="create-patient" navigation query-key="create">
+       <PatientForm /> (its own setup: a fresh form per opening)
+     </BbDialog> -->
+<CreatePatientDialog />
+<BbButton v-bb-dialog="'create-patient'">New patient</BbButton>
+```
+
+On demand stays for openings with no page to live in (a command palette, a
+store action, stacked copies of one dialog), which want no URL anyway.
+
+On the phone the adaptive
 sheet is the same dialog: one key, and Back is refused by the sheet's own
 gates. Under Inertia, a Back that changes only dialog keys never reaches
 Inertia, so the page is not remounted; this needs `bitbossUiPlugin` installed
@@ -1580,6 +1727,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   `href`/`to` to the button.
 - **Don't toggle `v-model` from `@hide`/`@hidden` handlers** to "cancel" a
   close — use `persistent` instead; the close paths already guard correctly.
+- **Catch `complete()` in a reusable dialog** whenever an opener may pass an
+  `onComplete` that rejects (`complete(data).catch(…)`, as in § The page
+  saves). Uncaught, the rejection travels through the form's `@submit` and
+  reaches `app.config.errorHandler`.
 - **Don't leave the `header` slot without a close control** — it replaces the
   default ×, so you must render your own wired to `close`.
 - **Don't query dialog content before it has opened, or after it has closed**,
@@ -1625,7 +1776,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | --- | --- | --- | --- | --- |
 | `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: `close`, `content`, `description`, `footer`, `header`, `root`, `sheet`, `title`. States: `fullscreen`, `open`. 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 `BbDialogProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | On mobile, renders as a `BbOffCanvas` drawer instead of a centred dialog; the surface is chosen when the dialog opens and kept until it closes. Unset: the global `config.adaptive`. |
-| `defaultData` | `Record<string, any> \| undefined` |  |  | The `data` of an opening that passes none (a create), as an object: copied at once and exposed as `data`, so inputs bind `data.x` with no guard. An opening with data lays it over this (`{ ...defaultData, ...row }`, one level). `reset()` restores a fresh copy, and every close does too. |
+| `defaultData` | `Record<string, any> \| undefined` |  |  | What `data` is when an opening passes none (a create): an object, copied at once, so inputs bind `data.x` with no guard. An opening's data lays over it (`{ ...defaultData, ...row }`, one level). `reset()` restores its keys but keeps an edit's `id`; a close restores it. |
 | `description` | `string \| undefined` |  |  | One short line under the title, muted (the shadcn `DialogDescription` shape), and the only element `aria-describedby` points at. Keep it to a sentence; anything longer belongs in the body. |
 | `eager` | `boolean \| undefined` | `false` |  | Keep the body mounted while closed, from before the first opening. Without it the body mounts per opening and unmounts after `@hidden`. `data` still clears while closed, so an eager body guards its reads. |
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
@@ -1633,16 +1784,16 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `hideClose` | `boolean \| undefined` | `false` |  | Hide the default close (×) button. The button is shown by default; set this to remove it (e.g. for a `persistent` dialog you don't want dismissible — the × otherwise still closes a persistent dialog). |
 | `id` | `string \| undefined` |  |  | Names the dialog for `v-bb-dialog="'edit'"` and `useBbDialogContext`, found nearest to the trigger, so two pages may reuse an id. Also the DOM `id`: one dialog per id, rows pass `data`. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the dialog. A dialog with no `v-model` starts closed. |
-| `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL carrying the key opens the dialog on load, and Back closes it (refused like Escape when locked). Template dialogs only; a record id stays in your own query. |
+| `navigation` | `boolean \| undefined` | `false` |  | Syncs the open state with the URL: opening writes `?<queryKey>=true`, closing removes it, a URL with the key opens the dialog on load, and Back closes it (refused whenever Escape is). Template dialogs only; keep a record id in your own query. |
 | `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on mobile), spread over its defaults. A `pt` inside it styles only the sheet (passthrough guide § Inside the sheet). |
-| `persistent` | `boolean \| undefined` | `false` |  | Prevent closing via outside clicks or Escape key. The header close (×) button STILL closes a persistent dialog — that is the documented escape hatch; combine with `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close is still allowed. |
-| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape and the ✕, and the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always. `false`: never, not even mid-save. |
+| `persistent` | `boolean \| undefined` | `false` |  | Blocks closing by outside click or Escape. The header close (×) STILL closes a persistent dialog, the documented escape hatch: add `hideClose` to remove it, or use `preventClose` to block every dismissal. Programmatic close still works. |
+| `preventClose` | `boolean \| undefined` | ``undefined` (follows a saving form inside)` |  | Refuses every user close (backdrop, Escape, the ✕, the slots' `close`) with the deny nudge; `v-model` still closes. Unset: locked while a `BbForm` inside saves (an async `@submit`). `true`: always; `false`: never, not even mid-save. Beside a form: `busy \|\| undefined`. |
 | `queryKey` | `string \| undefined` | `"dialog"` |  | The query key `navigation` writes. |
 | `replace` | `boolean \| undefined` | `false` |  | With `navigation`, replaces the history entry instead of pushing one, so Back leaves the page instead of closing the dialog. |
 | `size` | `Responsive<NonNullable<number \| CssSize \| keyof BbDialogSizes \| undefined>> \| undefined` | `"sm"` |  | Controls the maximum width of the dialog. Accepts named presets from `'xs'` to `'2xl'`, a custom CSS width string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch width responsively. |
 | `snap` | `BbSnapPoint \| undefined` |  |  | The phone sheet's snap stop (Q71.8), one of the `snapPoints` entries. The desktop dialog ignores it. |
-| `snapPoints` | `BbSnapPoint[] \| undefined` |  |  | Heights the phone sheet rests at, smallest first: a fraction of the screen (`0.5`; `1` = as tall as it gets) or a pixel height (`'240px'`). The first stop is the opening height; `v-model:snap` reads and sets the stop. Phone sheet only: the desktop dialog ignores it. |
-| `stack` | `string \| undefined` |  |  | Name of the stack this dialog belongs to. Dialogs sharing the same `stack` value replace one another: only the most recently opened stays visible while the others in the stack are hidden beneath it. Dialogs in different stacks — or with no `stack` — never affect each other and remain fully visible. |
+| `snapPoints` | `BbSnapPoint[] \| undefined` |  |  | Heights the phone sheet rests at, smallest first: a screen fraction (`0.5`; `1` = as tall as it gets) or pixels (`'240px'`). The first is the opening height; `v-model:snap` reads and sets the stop. Sheet only: the centred dialog ignores it. |
+| `stack` | `string \| undefined` |  |  | Name of this dialog's stack. Dialogs with the same `stack` replace one another: only the latest opened shows, the rest of the stack hide beneath it. Dialogs in different stacks, or with no `stack`, never affect each other and stay fully visible. |
 | `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered (unless a `header` slot is supplied) and accessibility must be handled manually. |
 | `transitionDuration` | `number \| undefined` | `250` |  | Controls the duration of the open and close animations. |
 
@@ -1671,7 +1822,7 @@ States are listed in precedence order: when two are on at once and their entries
 ## Events
 
 - `hidden` — `(): void` — Emitted after the close transition completes and the dialog is fully dismissed.
-- `hide` — `(): void` — Emitted as soon as the dialog starts to close (model becomes false).
+- `hide` — `(result: BbDialogResult): void` — Emitted as soon as the dialog starts to close (model becomes false), with the opening's result: the same object its promise settles with, `{ completed: true, value }` or `{ completed: false, reason }` (Q73.6).
 - `show` — `(): void` — Emitted as soon as the dialog starts to open (model becomes true).
 - `shown` — `(): void` — Emitted once the open transition has run (symmetric with `hidden`): the dialog is settled, so code that measures or anchors to its content sees the final layout. Not emitted for a dialog closed before it finished opening.
 - `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
@@ -1679,10 +1830,10 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `default` — scope: `BbDialogDefaultSlotProps` `{ close: () => void; complete: (value?: any) => void; reset: () => void; data: any }` — Primary body content of the dialog, rendered in the scrollable body area.
+- `default` — scope: `BbDialogDefaultSlotProps` `{ close: () => void; complete: (value?: any) => Promise<void>; reset: () => void; data: any }` — Primary body content of the dialog, rendered in the scrollable body area.
 - `description` — scope: `BbDialogDescriptionSlotProps` `{ text: string; data: any }` — Replaces the description text under the title. Renders the header even when `title` and `description` are unset — a slotted description is a description, the same rule `#title` follows.
-- `footer` — scope: `BbDialogFooterSlotProps` `{ close: () => void; complete: (value?: any) => void; reset: () => void; data: any }` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
-- `header` — scope: `BbDialogHeaderSlotProps` `{ titleId: string; close: () => void; complete: (value?: any) => void; reset: () => void; title: string; data: any }` — Replaces the whole header (title and ✕) on both surfaces, so it owns closing: wire your control to `close`, and `titleId` onto your title. It renders even without `title`. Its root is a flex item: give it `flex-1` to fill the width.
+- `footer` — scope: `BbDialogFooterSlotProps` `{ close: () => void; complete: (value?: any) => Promise<void>; reset: () => void; data: any }` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
+- `header` — scope: `BbDialogHeaderSlotProps` `{ titleId: string; close: () => void; complete: (value?: any) => Promise<void>; reset: () => void; title: string; data: any }` — Replaces the whole header (title and ✕) on both surfaces, so it owns closing: wire your control to `close`, and `titleId` onto your title. It renders even without `title`. Its root is a flex item: give it `flex-1` to fill the width.
 - `title` — scope: `BbDialogTitleSlotProps` `{ text: string; data: any }` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.
 
 ## CSS custom properties

package/dist/ai/BbDropdown.md

@@ -2124,8 +2124,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   width; pass a number when menus must align across rows.
 - Item `variant`s other than `destructive` render only a class hook — register
   names via the `dropdownItemVariants` plugin option and ship their CSS.
-- `<BbDropdownGroup>` must sit in a `BbDropdown` (or `BbDropdownButton`)
-  default slot, its `id` must match a group's `id`, and a `multiple` group's
+- `<BbDropdownGroup>` must sit in a `BbDropdown`'s default slot (a
+  `BbDropdownButton`'s `#dropdown`), its `id` must match a group's `id`, and a `multiple` group's
   model must be an array — all three misuses throw.
 - Placeholder texts default to the config locale's "Loading…" / "No results"
   strings (`locale` plugin option) unless you set `loading-text` /