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

package/dist/ai/BbDialog.md

@@ -53,6 +53,20 @@ the `default`/`footer` slots, `default-data`, `navigation`, `persistent`,
 `focus-target`, `eager`, `stack`, `transition-duration`), so moving a surface
 between them is mostly a tag swap.
 
+#### Which one?
+
+How you open it follows from where its state lives:
+
+- **A dialog in its own file whose state must start fresh** (a form, a
+  fetched step), **or one opened with a row's data** → on demand,
+  `useBbDialog(EditMember).show(member)`: every opening mounts a new
+  instance, so there is nothing to reset ([On-demand dialogs](#on-demand-dialogs-open-a-component)).
+- **A page-level dialog that needs the URL or Back** → a placed `<BbDialog id>`
+  opened by id, `v-bb-dialog="'invite'"` ([In the URL](#in-the-url-navigation)).
+- **A yes / no** → `useConfirm`, not a dialog.
+
+A `v-model` is for state your page already owns.
+
 ### Open and close with v-model
 
 With a `v-model`, the model owns visibility: bind a boolean and flip it.
@@ -201,7 +215,7 @@ reads `data` in two places:
 
 - in the template, the `default`, `header` and `footer` slots receive it as
   `data` (typed `any`, so `data.name` reads with no cast);
-- in code, `useBbDialogContext<T>(id)` returns it typed, along with `open`,
+- in code, `useBbDialog<T>(id)` returns it typed, along with `open`,
   `show(data?)` and `hide()`. A component inside the dialog can call it too.
   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
@@ -216,7 +230,7 @@ closes with `complete(data)`, handing the edited copy to the row's
 
 The rules:
 
-- **Lookup nearest to the trigger.** The directive (and the context) looks
+- **Lookup nearest to the trigger.** The directive (and the handle) looks
   for the dialog in the component whose template it is written in and in the
   components that one renders, nearest first. Then it moves up to the parent
   and repeats. So a dialog wrapped in a component of its own works:
@@ -228,14 +242,14 @@ The rules:
   page's topbar, a toolbar or a selection bar opens the page's dialog with
   `v-bb-dialog` itself: the lookup climbs from the topbar to the page that
   renders `<CreateInvoiceDialog />`. Don't emit an event (`emit('create')`)
-  that the page turns into `useBbDialogContext(id).show()`. That's more
+  that the page turns into `useBbDialog(id).show()`. That's more
   wiring, and the button loses `aria-haspopup`, `aria-expanded` and
   `aria-controls`. Keep
   `show()` for opens no button makes: a keyboard shortcut, a menu item, an
   open after a fetch.
 - **`v-model` still wins.** On a dialog that has one, the directive writes the
   model. A parent that refuses the change keeps the dialog closed.
-- **Three closes.** `complete(value)` (slots and context) closes with a
+- **Three closes.** `complete(value)` (slots and handle) closes with a
   result, and `hide()` is the code's close, like setting the model to
   `false`. Both close even under `prevent-close`; use one after a save. The
   slots' `close()` stays the user's close, and `prevent-close` refuses it.
@@ -255,7 +269,7 @@ The rules:
   is safe: it takes the same open and user-close paths. Prefer `v-bb-dialog`.
 
 `bitboss-ui check` and the ESLint rule `bitboss-ui/portal-names` report a
-`v-bb-dialog` or `useBbDialogContext` id that no `<BbDialog id>` in the
+`v-bb-dialog` or `useBbDialog` id that no `<BbDialog id>` in the
 project declares (`unknown-dialog`). A dialog that lives in a dependency is
 listed in `dialogIdsWhitelist` (`bitboss-ui.check.json`, or the `"bitboss-ui"`
 key of package.json).
@@ -267,7 +281,7 @@ An opening hands back how it ended. The directive takes `onComplete`, and
 fetch):
 
 ```ts
-const edit = useBbDialogContext<Member, Member>('edit-member');
+const edit = useBbDialog<Member, Member>('edit-member');
 const result = await edit.show(member);
 if (result.completed) replace(result.value);
 ```
@@ -315,7 +329,7 @@ const replace = (saved: Member) => {
 ```
 
 - `complete(value)` (the `default`, `header` and `footer` slots, and
-  `useBbDialogContext(id).complete`) closes the dialog and resolves
+  `useBbDialog(id).complete`) closes the dialog and resolves
   `{ completed: true, value }`. It wins over `prevent-close`, like `hide()`.
 - Every other close is a dismissal, `{ completed: false, reason }`:
 
@@ -383,7 +397,7 @@ the user edits it.
 <script setup lang="ts">
 import { ref } from 'vue';
 
-const fieldErrors = ref<Record<string, string[]>>({});
+const fieldErrors = ref<Record<string, string | string[]>>({});
 </script>
 
 <template>
@@ -394,8 +408,9 @@ const fieldErrors = ref<Record<string, string[]>>({});
 			@submit="
 				() =>
 					complete(data).catch((error) => {
-						// Your save's rejection: the 422 body's `errors` by field path.
-						fieldErrors = error.errors ?? {};
+						// Your save's rejection. With the Inertia helpers it IS the
+						// error bag (messages by field path); an Error has no bag.
+						fieldErrors = error instanceof Error ? {} : error;
 					})
 			"
 		>
@@ -411,29 +426,21 @@ 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.
+rejects on its own. Save through the Inertia helpers' `usePromiseRouter`
+(Inertia helpers guide § usePromiseRouter) instead: its promise resolves when
+the server answered (and on a visit another visit cut short, closing the
+dialog), and on a validation error it **rejects with the error bag itself**,
+`{ name: 'The name is taken.' }`, not `{ errors }`: the example above binds
+the rejection as it is. Anything else (an error page, a network error)
+rejects with an `Error`, which has no bag.
 
 ```ts
-import { router } from '@inertiajs/vue3';
+import { usePromiseRouter } from '@/composables/inertia-helpers/usePromiseRouter';
 
 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')),
-		});
-	});
+const { put } = usePromiseRouter();
+const save = (user: User) => put(`/users/${user.id}`, user);
 ```
 
 #### The data is a copy
@@ -453,7 +460,7 @@ a `File`, a `Map`) is the same object you passed. So:
   saved. A dialog with no round trip (a local filters panel) returns the edit
   itself with `complete(data)`.
 - `data` is not the object you passed (`data !== row`), so compare by id, never
-  by identity. The slots' `data` and `useBbDialogContext(id).data` are the
+  by identity. The slots' `data` and `useBbDialog(id).data` are the
   same copy, and it is reactive: a title bound to `data.name` follows the
   typing.
 
@@ -558,7 +565,7 @@ const save = (saved: Member) => {
 </script>
 ```
 
-- **`reset()`** (the slots', or `useBbDialogContext(id).reset()`) restores
+- **`reset()`** (the slots', or `useBbDialog(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
@@ -571,7 +578,7 @@ const save = (saved: Member) => {
 
 **Whose surroundings the dialog takes.** The directive sits on the trigger in
 the template, so the dialog it opens follows the trigger's surroundings: a
-`<BbPtScope>` around the button themes it. A context call (`edit.show()`) is
+`<BbPtScope>` around the button themes it. A handle call (`edit.show()`) is
 the code form of opening and knows nothing about the element that led to
 it: it inherits only what the calling component's setup sees (the page's
 provides), not a `<BbPtScope>` the page writes around the button in its own
@@ -621,13 +628,13 @@ const save = async (values: Record<string, unknown>): Promise<User> => ({
 ```
 
 Open it from a button with the directive, the tersest form, or from code with
-the context. Both take explicit `<In, Out>`; nothing is inferred from the
+the handle. Both take explicit `<In, Out>`; nothing is inferred from the
 component:
 
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, useBbDialogContext } from 'bitboss-ui';
+import { BbButton, useBbDialog } from 'bitboss-ui';
 import UserCreateDialog from './UserCreateDialog.vue';
 
 type User = { id: number; name: string; team: string };
@@ -635,7 +642,7 @@ const users = ref<User[]>([]);
 const add = (user: User) => users.value.push(user);
 
 // From code: a shortcut, an open after a fetch.
-const create = useBbDialogContext<{ team: string }, User>(UserCreateDialog);
+const create = useBbDialog<{ team: string }, User>(UserCreateDialog);
 const createForDesign = async () => {
 	const result = await create.show({ team: 'Design' });
 	if (result.completed) add(result.value);
@@ -660,29 +667,32 @@ const createForDesign = async () => {
 </template>
 ```
 
-- **It needs `<BbHost />`** at the app root, which renders the openings (and
-  every confirm and toast). With no host the opening waits a second, then
-  settles `'unmounted'` with a dev warning.
+- **It renders in `<BbHost />`**, which the plugin renders beside the app (it
+  renders every confirm and toast too): nothing to mount. Without the plugin
+  there is no host, and the opening waits a second, then settles
+  `'unmounted'` with a dev warning.
 - **Results** are the dialog's own, as in the section above: `complete(value)`
   resolves `{ completed: true, value }`, every other close a dismissal, at
   close start. The instance unmounts after the close transition.
 - **It injects like its opener.** The directive's dialog takes the trigger's
   surroundings (a row's `provide`, a `<BbPtScope>` around the button, an
-  enclosing `BbForm`); a context's takes the calling component's. It paints
+  enclosing `BbForm`); a handle's takes the calling component's. It paints
   in the host, outside the page's DOM.
 - **Lifetime.** The opening is dismissed (`'unmounted'`) when what opened it
   goes away: the page on a route change, a row that re-renders away, a
-  KeepAlive park. A flow that changes the URL inside one dialog (a wizard
+  KeepAlive park, a button in a closing panel (a select's `#empty`, which
+  unmounts as the dialog takes focus). Open those from a handle made in setup,
+  `useBbDialog(Component)`, which lives as long as its component. 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.
 - **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
+- **One handle, one dialog.** `useBbDialog(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
+  joins it. Another handle (another `useBbDialog(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
@@ -691,7 +701,7 @@ const createForDesign = async () => {
   e.g. `getByRole('dialog', { name: 'Edit account' })`: its HTML id is
   generated per opening.
 - **It must render its dialog.** A component that renders no `<BbDialog>` /
-  `<BbOffCanvas>`, or whose `useBbDialogContext(id)` names another id than its
+  `<BbOffCanvas>`, or whose `useBbDialog(id)` names another id than its
   dialog's, settles `'failed'` with a dev warning instead of hanging. So does a
   `defineAsyncComponent` whose chunk fails to load. Define an async component
   once, at module scope: an inline `defineAsyncComponent(() => import(…))` per
@@ -1015,19 +1025,13 @@ Two rules keep dialog forms honest:
 
 Close only when the save worked. When the server answers with field errors
 (a 422), don't call `complete` or `hide`: hand the errors to the form with
-`useBbFormContext(id).setErrors`, and the dialog stays open with each message
+`useBbForm(id).setErrors`, and the dialog stays open with each message
 under its field and focus on the first one. The user fixes it and submits
 again; Cancel still throws the copy away.
 
 ```vue
 <script setup lang="ts">
-import {
-	BbButton,
-	BbDialog,
-	BbForm,
-	BbTextInput,
-	useBbFormContext,
-} from 'bitboss-ui';
+import { BbButton, BbDialog, BbForm, BbTextInput, useBbForm } from 'bitboss-ui';
 
 type Member = { id: number; name: string; email: string };
 type FieldErrors = Record<string, string[]>;
@@ -1038,7 +1042,7 @@ const save = async (member: Member): Promise<Member | FieldErrors> =>
 		? { ...member }
 		: { email: ['Use your work address.'] };
 
-const form = useBbFormContext('edit-member-form');
+const form = useBbForm('edit-member-form');
 </script>
 
 <template>
@@ -1093,7 +1097,7 @@ transition completes. A surface closed before it finished opening fires no
 `shown`.
 
 `@show` carries no payload: read the opening's `data` from the slots or
-`useBbDialogContext(id).data`.
+`useBbDialog(id).data`.
 
 Every way to close, side by side:
 
@@ -1101,8 +1105,8 @@ Every way to close, side by side:
 | ------------------------------------------------------- | ------------ | ------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
 | the ✕, the slots' `close()`                             | the user     | yes: `prevent-close`, a saving form   | `{ completed: false, reason: 'close' }`       | on the click                                                                        |
 | 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()` (handle), the model set to `false`             | your code    | no                                    | `{ completed: false, reason: 'hide' }`        | at once                                                                             |
+| `complete(value)` (slots, handle)                       | your code    | no                                    | `{ completed: true, value }`                  | at once                                                                             |
 | `@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 |
 
@@ -1110,7 +1114,7 @@ A refused close fires nothing and settles nothing. Use `@hide` for what
 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),
+tell a save from a cancel, close a save with `complete()` (slots or handle),
 not by writing the model: on a `v-model` dialog too, it closes through the
 model and reports `{ completed: true }`.
 
@@ -1537,8 +1541,9 @@ with `default-data`:
 <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.
+Everything else can stay on demand: an opening that needs no URL (a dialog
+that must start fresh, per-row data, a command palette, a store action,
+stacked copies of one dialog) needs no placed dialog either.
 
 On the phone the adaptive
 sheet is the same dialog: one key, and Back is refused by the sheet's own
@@ -1783,7 +1788,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
 | `fullscreen` | `boolean \| "mobile" \| undefined` |  |  | Display the dialog fullscreen. Use `'mobile'` to restrict fullscreen to small devices. |
 | `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`. |
+| `id` | `string \| undefined` |  |  | Names the dialog for `v-bb-dialog="'edit'"` and `useBbDialog`, 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 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). |

package/dist/ai/BbDropdown.md

@@ -57,7 +57,7 @@ An `items` entry is one of three shapes, and you can mix them freely:
   [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.
+  `useBbDropdown` while rendering no heading in the menu.
 
 Each item extends `BbBaseButton`'s prop surface, so an item is an action, a
 link, or a submenu opener depending on which fields it carries:
@@ -98,7 +98,7 @@ hook, an `aria-*`) goes through `pt:item`, per row with the function form:
 
 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).
+yes (the plugin's `<BbHost />` renders it; nothing to mount).
 
 **A mixed action menu**
 
@@ -130,18 +130,11 @@ yes (`<BbHost />` mounts once per app, at the root).
 				/>
 			</template>
 		</BbDropdown>
-
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbButton, BbHost, BbDropdown, useConfirm } from 'bitboss-ui';
+import { BbButton, BbDropdown, useConfirm } from 'bitboss-ui';
 import type { BbDropdownItem } from 'bitboss-ui';
 
 const last = ref('No action yet');
@@ -435,7 +428,7 @@ const statusGroup = {
   selected ones stay live so the user can swap.
 - The function receives the **row object** in a hand-written group and the
   **raw fetched item** in a fetched group.
-- `useBbDropdownContext(id).groups[groupId].selectable` stays a plain `true`.
+- `useBbDropdown(id).groups[groupId].selectable` stays a plain `true`.
 
 This is also how a fetched row gets disabled — see
 [why fetched rows have no `disabled`](#additional-row-fields-itemprops).
@@ -913,7 +906,7 @@ const assigneeGroup = {
 };
 ```
 
-**Fetched assignees: description, icon, selectable gate, context**
+**Fetched assignees: description, icon, selectable gate, handle**
 
 ```vue
 <template>
@@ -953,7 +946,7 @@ import {
 	BbButton,
 	BbDropdown,
 	BbDropdownGroup,
-	useBbDropdownContext,
+	useBbDropdown,
 } from 'bitboss-ui';
 import type { BbDropdownItem } from 'bitboss-ui';
 
@@ -999,11 +992,11 @@ const items: BbDropdownItem[] = [
 
 const assignees = ref<string[]>(['u1']);
 
-// The resolved description is on the context's `selectedOptions` too — no
+// The resolved description is on the handle's `selectedOptions` too — no
 // second fetch to show the picked emails outside the menu.
-const context = useBbDropdownContext('invoice-assignees');
+const assigneeMenu = useBbDropdown('invoice-assignees');
 const emails = computed(() =>
-	(context.groups.value.assignees?.selectedOptions ?? [])
+	(assigneeMenu.groups.value.assignees?.selectedOptions ?? [])
 		.map((option) => option.description)
 		.filter(Boolean)
 		.join(', ')
@@ -1095,7 +1088,7 @@ structure — `value`, `label`, `items`, `group` — and `disabled`:
 
 - `description` — a muted second line under the text, announced as the row's
   description (never part of its name), searched with the text, and exposed as
-  `description` on `useBbDropdownContext(id).groups[groupId].selectedOptions`.
+  `description` on `useBbDropdown(id).groups[groupId].selectedOptions`.
 - `prepend:icon`, `append:icon`, `variant`.
 - `onClick`, `href`, `to`, `target`, `rel`, `download`, `external`, and the
   Inertia visit options.
@@ -1223,15 +1216,15 @@ searchable group in the menu:
 
 A searchable surface is a `role="dialog"`, not a `menu` — see Accessibility.
 
-### Reading a dropdown from anywhere: `useBbDropdownContext`
+### Reading a dropdown from anywhere: `useBbDropdown`
 
 Give the dropdown an explicit `id` and any component — no shared parent needed —
 can read its live state. This is how you render **filter chips outside the menu
 without a second fetch**: the dropdown already resolved each pick's label when
-the user chose it, so the context hands it back.
+the user chose it, so the handle hands it back.
 
 ```ts
-const { isReady, open, groups } = useBbDropdownContext('invoice-filters');
+const { isReady, open, groups } = useBbDropdown('invoice-filters');
 ```
 
 - `isReady` — a dropdown with that id is mounted.
@@ -1253,7 +1246,7 @@ still want a chip prefix.
 Two rules worth knowing:
 
 - **It is read-only.** To change a selection, write to that group's own
-  `v-model` — the context never mutates.
+  `v-model` — the handle never mutates.
 - **It is lazy.** Reading never triggers a fetch, so a seeded value in a
   search-first group stays `{ value }` (no label) until that group loads. Set
   `prefill: true` on the group to resolve a seeded selection eagerly.
@@ -1781,7 +1774,7 @@ selectable group, no fetched `items`) goes back to sleep once it has closed, or
 when focus leaves an element whose menu never opened, so only the open menu
 is ever a component. Measured on 3,000 elements: mount and re-render cost
 about the same as the bare elements. Two things opt a binding out: `eager`, and
-an explicit `id` (it must stay resolvable by `useBbDropdownContext(id)`). Each
+an explicit `id` (it must stay resolvable by `useBbDropdown(id)`). Each
 then mounts a full `BbDropdown` (about 1 ms per element), so leave both off on
 long lists.
 
@@ -2237,6 +2230,11 @@ own sizes.
   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.
+- **An on/off entry ("Show deleted") is a selectable group too**, never an
+  action row with a check icon drawn in: a screen reader hears that as a plain
+  `menuitem`, with no state. Make it a `multiple` group of one row (a
+  `menuitemcheckbox` with `aria-checked`), bound to a one-value array; add
+  `close-on-select` when the menu should close after the toggle.
 - **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.
@@ -2263,7 +2261,10 @@ own sizes.
   referenced element — don't hand-write your own `aria-*` there either; it's
   the same double-set conflict as skipping the slot `props`.
 - An icon-only trigger still needs an `aria-label` (see the nested-menu
-  example).
+  example). A trigger with visible text (an account row: name and email)
+  takes none: an `aria-label` replaces the words on screen, and a voice user
+  saying them misses the button (WCAG 2.5.3). The activator `props` already
+  carry `aria-haspopup` / `aria-expanded`.
 - The panel is a `role="menu"` labelled by the activator; rows render as
   `menuitem`, or `menuitemradio` / `menuitemcheckbox` with `aria-checked` in
   selectable groups; submenu openers carry their own `aria-haspopup` /
@@ -2336,7 +2337,7 @@ it, and at the top level closes the sheet.
 | `emptyText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `emptyText` overrides this; both fall back to the localized `common.emptyText` (`'No data to display'`). |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
 | `failedText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group's latest load FAILED (its `items` getter threw). A group's own `failedText` overrides this; both fall back to the localized `common.failedText` (`"Couldn't load items"`). |
-| `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
+| `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdown(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
 | `items` | `BbDropdownItem[]` | `[]` | yes | The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a flat array for one group, nested arrays for divider-separated groups, or `InternalGroup` objects for titled / selectable sections. A row's own `items` opens a submenu. |
 | `loadingText` | `string \| undefined` |  |  | Default placeholder text shown while a pipeline group's async items load. A group's own `loadingText` overrides this; both fall back to the localized `common.loadingText` (`'Loading...'`). |
 | `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). The sheet hides its ✕; `{ hideClose: false }` brings it back. |

package/dist/ai/BbDropdownButton.md

@@ -309,18 +309,11 @@ not the one that needs a second thought.
 				Redeploy
 			</BbDropdownButton>
 		</div>
-
-		<!--
-			Standalone example: it mounts its own host because it has no app root.
-			A real app mounts exactly one <BbHost /> at the app root, and pages
-			mount none. See ai/guides/agent-contract.md § Global Host Rule.
-		-->
-		<BbHost />
 	</div>
 </template>
 <script setup lang="ts">
 import { ref } from 'vue';
-import { BbHost, BbDropdownButton, useConfirm } from 'bitboss-ui';
+import { BbDropdownButton, useConfirm } from 'bitboss-ui';
 import type { BbDropdownItem } from 'bitboss-ui';
 
 const status = ref('dpl_7k2f · deployed 2026-07-08 14:32');
@@ -648,7 +641,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `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. |
-| `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
+| `ariaCurrentValue` | `"time" \| "true" \| "false" \| "page" \| "step" \| "location" \| "date" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
 | `async` | `boolean \| undefined` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
 | `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. |
@@ -666,9 +659,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `external` | `boolean \| undefined` | `false` |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — same intent as Nuxt's `external`. A native-anchor signal alongside `target` and `download`. |
 | `form` | `string \| undefined` |  |  | The id of the `BbForm` the main button submits from outside it (the native `form` attribute), with `type="submit"`. |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
-| `href` | `string \| undefined` |  |  | Returns the hyperlink's URL. Can be set, to change the URL. |
+| `href` | `string \| { url: string; method: "get" \| "post" \| "put" \| "patch" \| "delete"; } \| undefined` |  |  | The link target: renders an anchor (an Inertia `<Link>` under Inertia). Also takes Inertia's `{ url, method }`, a Wayfinder route: Inertia visits with its method; elsewhere the link is its `url`. |
 | `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |
-| `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
+| `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdown(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
 | `instant` | `boolean \| undefined` | `false` |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `interactiveWhileLoading` | `boolean \| undefined` | `false` |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
 | `items` | `BbDropdownItem[] \| undefined` |  |  | The menu: every entry is a row (BbDropdown's item model, groups and submenus included). The main action is the component itself (its default slot, `@click`, `href` / `to`, `type`), never an item. Unset or empty with no `#dropdown` slot: no toggle, a plain button. |
@@ -704,7 +697,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route Location the link should navigate to when clicked on. |
 | `toggle:icon` | `string \| undefined` |  |  | Replaces the chevron shown inside the dropdown toggle button. A constrained alternative to a slot: only the toggle's icon changes, so the button keeps its semantics. Named after the part it sits in (the `toggle`), the way `prepend:icon` / `append:icon` name theirs. |
 | `transitionDuration` | `number \| undefined` | `150` |  | How long the transition has to last in milliseconds. Menus use the fast transition (150) rather than the medium one (250) the other popovers default to: a menu is opened to pick one command and is gone again, so it answers faster than a panel the user reads or edits in. |
-| `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Gets the classification and default behavior of the button. |
+| `type` | `"button" \| "reset" \| "submit" \| undefined` |  |  | Gets the classification and default behavior of the button. |
 | `variant` | `'outline'` \| `'primary'` \| `'destructive'` \| `'secondary'` \| `'none'` \| `'ghost'` \| `'link'` | `"primary"` |  | Visual variant shared by both buttons of the split control. `'none'` takes no look (you own hover, focus and disabled); register a real one with the plugin's `buttonVariants` and style `.bb-button--<name>`. |
 | `viewTransition` | `boolean \| undefined` | `false` |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 | `width` | `string \| number \| undefined` | `'auto'` |  | Width of the dropdown in pixels, percentage, or 'auto' to fit content. |

package/dist/ai/BbDropzone.md

@@ -1179,8 +1179,7 @@ onBeforeUnmount(() => controller?.abort());
 </style>
 ```
 
-`useToast` needs `<BbHost />` mounted once in your app layout — without it,
-toasts are enqueued but never shown. This demo fakes the transfer with a timer;
+`useToast` renders in the plugin's `<BbHost />`; nothing to mount. This demo fakes the transfer with a timer;
 the wiring is identical against real `XHR`/`fetch` progress events. **Abort and
 retry live in your request layer, not in `BbDropzone`** — the component has no
 cancel/retry API. Use an `AbortController` for cancellation and re-issue the
@@ -1672,7 +1671,7 @@ button, grows with every file added, and changes mid-drag. So:
 | `maxFiles` | `number \| undefined` |  |  | Maximum number of acceptable files. |
 | `maxSize` | `number \| undefined` |  |  | Max size of the files in bytes. |
 | `modelValue` | `File \| File[] \| null \| undefined` |  |  | Used by v-model. |
-| `multiple` | `boolean \| undefined` | `false` |  | Allows the selection of multiple items. |
+| `multiple` | `boolean` | `false` |  | Allows the selection of multiple items. |
 | `name` | `string \| undefined` |  |  | Defines the name of the input. |
 | `readonly` | `boolean \| undefined` | `false` |  | Shows the files; the user cannot change them: drop, the file picker and the `open()` slot prop do nothing, yet the input stays focusable and a `name`d zone still submits its files (unlike `disabled`). Your slot renders the list: hide your remove buttons with the slot's `readonly`. |
 | `rules` | `RuleExpression<File \| File[] \| null>` |  |  | vee-validate rules for this field. Only inside a `BbForm`. |