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

package/dist/ai/BbDialog.md

@@ -48,9 +48,10 @@ Pick a sibling instead when the shape fits it better:
   `useConfirm`, not a hand-built dialog.
 - A small anchored menu or bit of interactive content → `BbPopover`.
 
-`BbDialog` and `BbOffCanvas` share most of their API (v-model, `title`, the
-`default`/`footer` slots, `persistent`, `focus-target`, `eager`, `stack`,
-`transition-duration`), so moving a surface between them is mostly a tag swap.
+`BbDialog` and `BbOffCanvas` share most of their API (`id`, v-model, `title`,
+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.
 
 ### Open and close with v-model
 
@@ -91,21 +92,29 @@ buttons and is refused while `prevent-close` is on.
 	</div>
 	<!-- `v-model` on purpose: this is the guide's "open and close with
 	v-model" example. Without that lesson, `v-bb-dialog` opens it by id. -->
-	<BbDialog v-model="open" title="Create label" @show="reset">
-		<div class="grid gap-3">
-			<BbTextInput
-				v-model="name"
-				compact
-				label="Label name"
-				placeholder="e.g. Priority"
-			/>
-			<p class="m-0 text-xs text-(--bb-text-muted)">
-				Names are unique per workspace and show up in filters.
-			</p>
-		</div>
-		<template #footer>
+	<!-- eslint-disable-next-line bitboss-ui/prefer-v-bb-dialog -->
+	<BbDialog v-model="open" :default-data="{ name: '' }" title="Create label">
+		<template #default="{ data }">
+			<div class="grid gap-3">
+				<BbTextInput
+					v-model="data.name"
+					compact
+					label="Label name"
+					placeholder="e.g. Priority"
+				/>
+				<p class="m-0 text-xs text-(--bb-text-muted)">
+					Names are unique per workspace and show up in filters.
+				</p>
+			</div>
+		</template>
+		<template #footer="{ data }">
 			<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
-			<BbButton :disabled="!name?.trim()" variant="primary" @click="create">
+			<!-- Persist the new label here, then close through the model. -->
+			<BbButton
+				:disabled="!data.name?.trim()"
+				variant="primary"
+				@click="open = false"
+			>
 				Create
 			</BbButton>
 		</template>
@@ -117,17 +126,6 @@ import { ref } from 'vue';
 import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const name = ref<string | null>('');
-
-// Re-seed on `@show`, not on close — a dismissed dialog may be reopened.
-const reset = () => {
-	name.value = '';
-};
-
-const create = () => {
-	// Persist the new label here, then close.
-	open.value = false;
-};
 </script>
 ```
 
@@ -211,9 +209,9 @@ reads `data` in two places:
 `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
 [Header, footer and body](#header-footer-and-body) below works this way: each
-row's Edit button passes its contact, the script reads it as
-`useBbDialogContext<Contact>('edit-contact').data`, and Save closes with
-`hide()`.
+row's Edit button passes its contact, the slots read it as `data`, and Save
+closes with `complete(data)`, handing the edited copy to the row's
+`onComplete`.
 
 The rules:
 
@@ -244,10 +242,15 @@ The rules:
   `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).
+  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`.
 - **Accessibility.** The button gets `aria-haspopup="dialog"`,
   `aria-expanded` and `aria-controls`, and focus returns to it when the
   dialog closes. On a phone, the adaptive sheet opens the same way.
 - **The server** renders the button untouched. The ARIA arrives on mount.
+- **A native `<button commandfor="…" command="show-modal">`** (or `"close"`)
+  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
@@ -314,17 +317,17 @@ const replace = (saved: Member) => {
   `{ completed: true, value }`. It wins over `prevent-close`, like `hide()`.
 - Every other close is a dismissal, `{ completed: false, reason }`:
 
-  | `reason`                  | When                                                                                         |
-  | ------------------------- | -------------------------------------------------------------------------------------------- |
-  | `'escape'` / `'backdrop'` | Escape, a backdrop click                                                                     |
-  | `'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                                                         |
-  | `'server'`                | `show()` called during a server render: nothing opens there                                  |
+  | `reason`                  | When                                                                                                             |
+  | ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+  | `'escape'` / `'backdrop'` | the system's close request (Esc, Android back, Back on a [URL dialog](#in-the-url-navigation)), a backdrop click |
+  | `'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                                                                             |
+  | `'server'`                | `show()` called during a server render: nothing opens there                                                      |
 
 - On Android, the system back button closes the top dialog like Escape (it is the browser's close request), so `prevent-close` and a saving form refuse it the same way; iOS swipe-back and the desktop back button are page navigation.
 - It settles when the close **starts**, together with `@hide`, so a list can
@@ -358,6 +361,116 @@ a `File`, a `Map`) is the same object you passed. So:
   same copy, and it is reactive: a title bound to `data.name` follows the
   typing.
 
+#### Create and edit in one dialog: `default-data`
+
+Opened without data (a create), `data` is `undefined`. A
+`<BbForm :model="data">` copes (the form starts blank), but `v-model="data.name"`
+or `{{ data.name }}` throws. Give the dialog a `default-data` object: every
+opening that passes no data gets a fresh copy of it, so the fields bind
+`data.x` with no guard. An edit lays its row over the default
+(`{ ...default, ...row }`, one level), so a field the row lacks starts from the
+default.
+
+**Create and edit with default-data**
+
+```vue
+<template>
+	<div class="flex w-full max-w-sm flex-col gap-2">
+		<ul class="m-0 flex list-none flex-col gap-2 p-0">
+			<li
+				v-for="member in members"
+				:key="member.id"
+				class="flex items-center justify-between gap-3 rounded-(--bb-radius) border p-3"
+			>
+				<div class="min-w-0">
+					<p class="m-0 truncate text-sm font-medium">{{ member.name }}</p>
+					<p class="m-0 truncate text-xs text-(--bb-text-muted)">
+						{{ member.email }}{{ member.admin ? ' · admin' : '' }}
+					</p>
+				</div>
+				<!-- An edit: the row is laid over the default. -->
+				<BbButton
+					v-bb-dialog="{ id: 'member', data: member, onComplete: save }"
+					:aria-label="`Edit ${member.name}`"
+					size="sm"
+					variant="outline"
+				>
+					Edit
+				</BbButton>
+			</li>
+		</ul>
+		<!-- A create: no data, so `data` is a fresh copy of the default. -->
+		<BbButton
+			v-bb-dialog="{ id: 'member', onComplete: save }"
+			prepend:icon="lucide:plus"
+			variant="outline"
+		>
+			Add member
+		</BbButton>
+	</div>
+	<!-- `data` is never undefined: the fields bind it with no guard. -->
+	<BbDialog id="member" :default-data="NEW_MEMBER" size="md" title="Member">
+		<template #title="{ data }">
+			{{ data.id ? `Edit ${data.name}` : 'New member' }}
+		</template>
+		<template #default="{ data }">
+			<div class="grid gap-3">
+				<BbTextInput v-model="data.name" compact label="Name" />
+				<BbTextInput v-model="data.email" compact label="Email" type="email" />
+				<BbSwitch v-model="data.admin" label="Admin" />
+			</div>
+		</template>
+		<template #footer="{ data, close, complete, reset }">
+			<!-- `reset()` restores the default, on an edit too: it clears. -->
+			<BbButton variant="ghost" @click="reset">Clear</BbButton>
+			<BbButton variant="ghost" @click="close">Cancel</BbButton>
+			<BbButton
+				:disabled="!data.name.trim()"
+				variant="primary"
+				@click="complete(data)"
+			>
+				Save
+			</BbButton>
+		</template>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog, BbSwitch, BbTextInput } from 'bitboss-ui';
+
+type Member = { id?: number; name: string; email: string; admin: boolean };
+
+// A plain object: the dialog copies it for every create.
+const NEW_MEMBER: Member = { name: '', email: '', admin: false };
+
+// The records — in a real app these come from your store/API.
+const members = ref<Member[]>([
+	{ id: 1, name: 'Ada Lovelace', email: 'ada@analytical.co', admin: true },
+	{ id: 2, name: 'Grace Hopper', email: 'grace@navy.mil', admin: false },
+]);
+
+// Persist here: an id updates that row, none adds one.
+const save = (saved: Member) => {
+	if (saved.id === undefined)
+		members.value.push({ ...saved, id: members.value.length + 1 });
+	else
+		members.value = members.value.map((member) =>
+			member.id === saved.id ? 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.
+- **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.
+- An edit-only dialog, always opened with a row, needs no `default-data` and no
+  guard: its body exists only while an opening holds data.
+
 **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
@@ -470,7 +583,9 @@ const createForDesign = async () => {
   instead.
 - **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.
+  `id` you gave it. To find one in an e2e test, use its role and title,
+  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
   dialog's, settles `'failed'` with a dev warning instead of hanging. So does a
@@ -528,7 +643,7 @@ with `complete(data)` for the row's `onComplete`.
 	     directly, Cancel throws it away, Save returns it. -->
 	<BbDialog id="edit-contact" size="md" title="Edit contact">
 		<template #default="{ data }">
-			<div v-if="data" class="grid gap-3">
+			<div class="grid gap-3">
 				<BbTextInput v-model="data.name" compact label="Full name" />
 				<BbTextInput v-model="data.email" compact label="Email" type="email" />
 				<BbTextInput
@@ -663,6 +778,32 @@ use the **`title` slot**: it replaces the title text alone, so the ✕, the
 </BbDialog>
 ```
 
+**The `title` prop can't see `data`.** It is bound in the page's template,
+where the opening's `data` does not exist. A title about the record goes in
+the `title` slot, which receives `data` like the other slots (so does the
+`description` slot):
+
+```vue
+<template>
+	<BbButton v-bb-dialog="{ id: 'rename', data: { name: 'Roadmap' } }">
+		Rename
+	</BbButton>
+	<BbDialog id="rename">
+		<template #title="{ data }">Rename “{{ data.name }}”</template>
+		<template #default="{ data, complete }">
+			<BbForm :model="data" @submit="complete(data)">
+				<BbTextInput label="Name" name="name" />
+				<BbButton type="submit">Rename</BbButton>
+			</BbForm>
+		</template>
+	</BbDialog>
+</template>
+```
+
+`data` is a reactive copy, so the title follows the typing; to show the name
+as it was, keep it apart (`data: { project, name: project.name }`) or read it
+from the row.
+
 The `header` slot is for the rare header that is not a title: it replaces the
 **entire** header on both surfaces, ✕ included — you own the close control
 (the slot hands you `close`) and must wire `titleId` for `aria-labelledby`.
@@ -673,8 +814,9 @@ Give your root element `flex-1` so it fills the header row.
 The most common dialog is a small form: validate in place, keep the primary
 action disabled until the input is usable, and close only on success. Cancel
 must always work — never gate it on validity. This companion disables **Send
-invite** until the email is plausible, and resets its fields on `@show` so a
-dismissed invite doesn't resurface half-typed:
+invite** until the email is plausible, and binds its fields to `data`, a fresh
+copy of `default-data` on every opening, so a dismissed invite never resurfaces
+half-typed:
 
 **Invite a teammate**
 
@@ -699,28 +841,37 @@ dismissed invite doesn't resurface half-typed:
 			</BbButton>
 		</div>
 	</div>
-	<BbDialog id="invite-teammate" title="Invite a teammate" @show="reset">
-		<div class="grid gap-3">
-			<BbTextInput
-				v-model="email"
-				compact
-				label="Email address"
-				placeholder="teammate@company.com"
-				type="email"
-			/>
-			<BbSelect v-model="role" compact :items="roles" label="Role" />
-			<p class="m-0 text-xs text-(--bb-text-muted)">
-				They'll get an email with a link that expires in 7 days.
-			</p>
-		</div>
-		<template #footer="{ close }">
+	<!-- `default-data` is the blank invite: every opening starts from a fresh
+	copy, so a dismissed invite never resurfaces half-typed. -->
+	<BbDialog
+		id="invite-teammate"
+		:default-data="{ email: '', role: 'member' }"
+		title="Invite a teammate"
+	>
+		<template #default="{ data }">
+			<div class="grid gap-3">
+				<BbTextInput
+					v-model="data.email"
+					compact
+					label="Email address"
+					placeholder="teammate@company.com"
+					type="email"
+				/>
+				<BbSelect v-model="data.role" compact :items="roles" label="Role" />
+				<p class="m-0 text-xs text-(--bb-text-muted)">
+					They'll get an email with a link that expires in 7 days.
+				</p>
+			</div>
+		</template>
+		<template #footer="{ data, close, complete }">
 			<!-- Cancel is never gated on validity. -->
 			<BbButton variant="ghost" @click="close">Cancel</BbButton>
+			<!-- Send the invite, then close only on success. -->
 			<BbButton
-				:disabled="!canSend"
+				:disabled="!EMAIL.test(data.email ?? '')"
 				prepend:icon="lucide:send"
 				variant="primary"
-				@click="send"
+				@click="complete(data)"
 			>
 				Send invite
 			</BbButton>
@@ -729,14 +880,7 @@ dismissed invite doesn't resurface half-typed:
 </template>
 
 <script setup lang="ts">
-import { computed, ref } from 'vue';
-import {
-	BbButton,
-	BbDialog,
-	BbSelect,
-	BbTextInput,
-	useBbDialogContext,
-} from 'bitboss-ui';
+import { BbButton, BbDialog, BbSelect, BbTextInput } from 'bitboss-ui';
 
 const roles = [
 	{ label: 'Member', value: 'member' },
@@ -744,53 +888,120 @@ const roles = [
 	{ label: 'Viewer', value: 'viewer' },
 ];
 
-const dialog = useBbDialogContext('invite-teammate');
-const email = ref<string | null>('');
-const role = ref('member');
-
-// Re-seed on `@show`, not on close — a dismissed dialog may be reopened.
-const reset = () => {
-	email.value = '';
-	role.value = 'member';
-};
-
 // Primary action stays disabled until the email is plausible.
-const canSend = computed(() =>
-	/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email.value ?? '')
-);
-
-const send = () => {
-	// Send the invite here, then close only on success.
-	dialog.hide();
-};
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 </script>
 ```
 
 Two rules keep dialog forms honest:
 
-- Bind the form to `data` (an edit) or start it blank (a create): `data` is
-  the opening's own copy, so Cancel discards, and every opening, the same row
-  again included, starts from a fresh one. There is nothing to seed on
-  `@show` and nothing to clear on `@hidden`. A create opened without data can
-  still reset its own fields on `@show`, as above.
+- Bind the form to `data`: it is the opening's own copy, so Cancel discards,
+  and every opening, the same row again included, starts from a fresh one
+  with a fresh body. There is nothing to seed on `@show` and nothing to clear
+  on `@hidden`. A create gets `default-data`'s copy, or `undefined` without
+  one: then only a `<BbForm :model="data">` starts blank, and anything reading
+  `data.x` needs `default-data` (see
+  [Create and edit in one dialog](#create-and-edit-in-one-dialog-default-data)).
 - On success, do the work first, then close: `complete(await api.save(values))`
   hands the saved record to whoever opened the dialog; `hide()` (or the model
   set to `false`) closes with no result. The close transition runs while
   your toast/refresh happens.
 
+#### A failed save stays open
+
+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
+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';
+
+type Member = { id: number; name: string; email: string };
+type FieldErrors = Record<string, string[]>;
+
+// Your API call: the saved member, or the 422's field errors.
+const save = async (member: Member): Promise<Member | FieldErrors> =>
+	member.email.endsWith('@example.com')
+		? { ...member }
+		: { email: ['Use your work address.'] };
+
+const form = useBbFormContext('edit-member-form');
+</script>
+
+<template>
+	<BbDialog id="edit-member" v-slot="{ data, complete }" title="Edit member">
+		<BbForm
+			id="edit-member-form"
+			:model="data"
+			@submit="
+				async () => {
+					const answer = await save(data);
+					if ('id' in answer) complete(answer);
+					else form.setErrors(answer);
+				}
+			"
+		>
+			<BbTextInput label="Name" name="name" />
+			<BbTextInput label="Email" name="email" type="email" />
+			<BbButton type="submit">Save</BbButton>
+		</BbForm>
+	</BbDialog>
+</template>
+```
+
+- **While it saves, the dialog refuses every user close** (the ✕, Cancel's
+  `close()`, Escape, the backdrop): the form locks it until the promise
+  settles, so the answer never lands on a closed dialog.
+- **The opener sees nothing until it completes.** A failed attempt settles
+  no result; `onComplete` (or `await show()`) gets the saved member once a
+  later attempt calls `complete`, or a dismissal if the user gives up.
+- A message with no field (Laravel's `message`, a 403) goes under a key no
+  field uses, `form.setErrors({ ...errors, _request: [message] })`, and shows in
+  the form's `unmatchedErrors` (see BbForm § Server errors).
+
 ### Lifecycle events and lazy content
 
 Four events bracket the transitions — `show` fires as the model turns `true`,
 `shown` after the open transition completes (focus has already moved in at
 `showModal()`), `hide` as the model turns `false`, and `hidden` after the close
 transition completes. A surface closed before it finished opening fires no
-`shown`. Use
-`@show` to reset a create form that was opened without data, `@hidden` to tear
-down expensive content.
-
-Body content is **lazy**: nothing inside the dialog renders until the first
-open. Set `eager` to render it immediately (e.g. so a chart can pre-measure, or
-tests can query content before opening). `transition-duration` (ms, default
+`shown`.
+
+`@show` carries no payload: read the opening's `data` from the slots or
+`useBbDialogContext(id).data`.
+
+Every way to close, side by side:
+
+| What                                                    | Who calls it | Can it be refused?                    | Result it settles                             | When it happens                                                                     |
+| ------------------------------------------------------- | ------------ | ------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| 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`                                                 | the dialog   | it reports a close, it can't stop one | settled together with it                      | 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.
+
+The body lives **per opening**: nothing inside the dialog renders until it
+opens, and the body unmounts after the close transition (right after
+`@hidden`), so the next opening renders it fresh. Inner tabs, scroll and
+touched fields start over, and nothing re-renders against a cleared `data`;
+state that must outlive an opening belongs in the page. Set `eager` to keep
+the body mounted from the start and across closes (a chart that pre-measures,
+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.
 
@@ -887,32 +1098,40 @@ element.
 			>
 		</div>
 	</div>
+	<!-- Every opening starts from a fresh copy of `default-data`. -->
 	<BbDialog
 		id="complete-profile"
+		:default-data="{ displayName: '', company: '' }"
 		focus-target="input"
 		hide-close
 		persistent
 		title="Complete your profile"
-		@show="reset"
 	>
-		<div class="grid gap-3">
-			<BbTextInput
-				v-model="displayName"
-				compact
-				label="Display name"
-				placeholder="Ada Lovelace"
-			/>
-			<BbTextInput
-				v-model="company"
-				compact
-				label="Company"
-				placeholder="Acme Inc."
-			/>
-		</div>
-		<template #footer="{ close }">
+		<template #default="{ data }">
+			<div class="grid gap-3">
+				<BbTextInput
+					v-model="data.displayName"
+					compact
+					label="Display name"
+					placeholder="Ada Lovelace"
+				/>
+				<BbTextInput
+					v-model="data.company"
+					compact
+					label="Company"
+					placeholder="Acme Inc."
+				/>
+			</div>
+		</template>
+		<template #footer="{ data, close, complete }">
 			<!-- Keep a visible way out — never trap the user. -->
 			<BbButton variant="ghost" @click="close">Skip</BbButton>
-			<BbButton :disabled="!company?.trim()" variant="primary" @click="save">
+			<!-- Persist the profile, then close with it. -->
+			<BbButton
+				:disabled="!data.company?.trim()"
+				variant="primary"
+				@click="complete(data)"
+			>
 				Save
 			</BbButton>
 		</template>
@@ -920,28 +1139,7 @@ element.
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue';
-import {
-	BbButton,
-	BbDialog,
-	BbTextInput,
-	useBbDialogContext,
-} from 'bitboss-ui';
-
-const dialog = useBbDialogContext('complete-profile');
-const displayName = ref<string | null>('');
-const company = ref<string | null>('');
-
-// Re-seed on `@show` so a dismissed step reopens clean.
-const reset = () => {
-	displayName.value = '';
-	company.value = '';
-};
-
-const save = () => {
-	// Persist the profile here, then close: `hide()` is the code's close.
-	dialog.hide();
-};
+import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
 </script>
 ```
 
@@ -998,11 +1196,10 @@ form in a popover inside the dialog does not lock the dialog.
 		</template>
 		<template #footer="{ data, close }">
 			<BbButton variant="ghost" @click="close">Cancel</BbButton>
-			<!-- Outside the form, so it binds the save's spinner itself. -->
+			<!-- Outside the form: `form` links it, so it spins with the save. -->
 			<BbButton
 				:disabled="!data?.name?.trim()"
 				form="rename-project-form"
-				:loading="form.submitting.value"
 				type="submit"
 				variant="primary"
 			>
@@ -1014,19 +1211,12 @@ form in a popover inside the dialog does not lock the dialog.
 
 <script setup lang="ts">
 import { ref } from 'vue';
-import {
-	BbButton,
-	BbDialog,
-	BbForm,
-	BbTextInput,
-	useBbFormContext,
-} from 'bitboss-ui';
+import { BbButton, BbDialog, BbForm, BbTextInput } from 'bitboss-ui';
 
 type Project = { name: string };
 
 // The record being renamed — in a real app this comes from your store/API.
 const project = ref<Project>({ name: 'acme-storefront' });
-const form = useBbFormContext('rename-project-form');
 
 // Your API call: return the promise, and the form (and the dialog around it)
 // stays locked until it settles. It resolves the saved project.
@@ -1128,8 +1318,9 @@ consequences an agent should design around:
   or tab reaches the page behind.
 - Later top-layer surfaces paint above earlier ones: a `BbPopover`, `BbSelect`,
   `BbTooltip` or nested `BbDialog`/`BbConfirm` opened from inside a dialog
-  appears above it and works — no special wiring. `BbToast` regions re-home
-  themselves into the open modal so toasts fired from a dialog stay clickable.
+  appears above it and works — no special wiring. The toast regions
+  `<BbHost />` renders re-home themselves into the open modal, so toasts fired
+  from a dialog stay clickable.
 
 **Don't teleport overlays out of an open dialog or sheet.** A
 `<Teleport to="body">` (or any `z-index` layer) opened from inside renders
@@ -1163,7 +1354,49 @@ On Nuxt or Inertia the same button carries a platform-native navigation:
 ```
 
 Because a modal dialog is client-side UI, SSR (Nuxt) renders it closed and
-empty; content appears on first open (or immediately with `eager`).
+empty; content appears when it opens (or immediately with `eager`).
+
+### In the URL: `navigation`
+
+`navigation` puts the open state in the query, like BbTabs: opening writes
+`?dialog=true`, closing removes it, a link or reload carrying the key opens
+the dialog, and **Back closes it**. Back is the system's close request, so it
+settles `reason: 'escape'`, and `persistent`, `prevent-close` or a saving
+form refuse it like Escape (the key comes back, with the deny nudge).
+
+```vue
+<BbDialog id="filters" navigation title="Filters">…</BbDialog>
+```
+
+- `query-key` names the parameter (default `'dialog'`; BbOffCanvas:
+  `'offcanvas'`). Two URL dialogs on one page each need their own.
+- `replace` writes without a history entry: Back then leaves the page.
+- A value opens unless it is `'false'` (`?dialog`, `?dialog=1` both open).
+- It carries the open state only. A record id is your own query (here
+  vue-router's; on Inertia, your page prop):
+
+```vue
+<script setup lang="ts">
+import { BbDialog } from 'bitboss-ui';
+import { useRoute } from 'vue-router';
+
+const route = useRoute();
+</script>
+
+<template>
+	<!-- /invoices?invoice=12&dialog=true opens on invoice 12 -->
+	<BbDialog id="invoice" navigation title="Invoice">
+		<p>Invoice {{ route.query.invoice }}</p>
+	</BbDialog>
+</template>
+```
+
+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
+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
+(the standard setup), which registers its history listener first.
 
 ### Adaptive: a bottom sheet on mobile
 
@@ -1191,6 +1424,10 @@ so a mid-flow resize never swaps modal ↔ sheet.
   `{ pt: { header: 'pt-10' } }` does the same; both merge after what the
   dialog forwards, so nothing of yours is lost (passthrough guide § Inside
   the sheet).
+- `snap-points` and `v-model:snap` give the phone sheet several resting
+  heights (`:snap-points="[0.5, 1]"`: opens at half the screen, drags up to
+  full). The desktop dialog ignores them. Everything about the stops (drag,
+  scroll, the slider handle) is in the BbOffCanvas guide, § Snap points.
 - `:adaptive="false"` keeps the centered dialog everywhere; a bare `adaptive`
   forces the sheet behavior on regardless of the global config.
 
@@ -1244,35 +1481,37 @@ a row at the end), a muted ✕ on `pt:close`, a primary ring with offset while
 	<BbDialog
 		id="record-payment"
 		:adaptive="false"
+		:default-data="NEW_PAYMENT"
 		pt:close="text-(--bb-text-muted)"
 		pt:footer="bg-(--bb-hover)"
 		pt:header="bg-(--bb-muted)"
 		pt:root:open="ring-2 ring-offset-2 ring-(--bb-primary)"
 		title="Record payment — INV-2048"
-		@show="seed"
 	>
-		<div class="grid gap-3">
-			<BbNumberInput
-				v-model="draft.amount"
-				label="Amount"
-				label-mode="outside"
-				:max-precision="2"
-				:min="0"
-			>
-				<template #prefix>€</template>
-			</BbNumberInput>
-			<BbDatePickerInput
-				v-model="draft.paidAt"
-				label="Paid on"
-				label-mode="outside"
-			/>
-			<BbSelect
-				v-model="draft.method"
-				:items="['bank transfer', 'card', 'check']"
-				label="Method"
-				label-mode="outside"
-			/>
-		</div>
+		<template #default="{ data }">
+			<div class="grid gap-3">
+				<BbNumberInput
+					v-model="data.amount"
+					label="Amount"
+					label-mode="outside"
+					:max-precision="2"
+					:min="0"
+				>
+					<template #prefix>€</template>
+				</BbNumberInput>
+				<BbDatePickerInput
+					v-model="data.paidAt"
+					label="Paid on"
+					label-mode="outside"
+				/>
+				<BbSelect
+					v-model="data.method"
+					:items="['bank transfer', 'card', 'check']"
+					label="Method"
+					label-mode="outside"
+				/>
+			</div>
+		</template>
 		<template #footer="{ close }">
 			<BbButton variant="ghost" @click="close">Cancel</BbButton>
 			<BbButton variant="secondary" @click="close"> Record payment </BbButton>
@@ -1281,7 +1520,6 @@ a row at the end), a muted ✕ on `pt:close`, a primary ring with offset while
 </template>
 
 <script setup lang="ts">
-import { reactive } from 'vue';
 import {
 	BbButton,
 	BbDatePickerInput,
@@ -1301,17 +1539,11 @@ type PaymentDraft = {
 // already lays its actions out in a row at the end), muted ✕ on `pt:close`, a
 // primary ring with offset while `pt:root:open`. There is no `panel` — the
 // `<dialog>` is the surface. Backdrop is `::backdrop`, CSS not pt.
-const draft = reactive<PaymentDraft>({
-	amount: null,
-	paidAt: null,
-	method: null,
-});
-
-/** Re-seed on `@show` so a canceled draft never leaks into the next open. */
-const seed = () => {
-	draft.amount = 1280;
-	draft.paidAt = new Date().toISOString();
-	draft.method = 'bank transfer';
+// Every opening edits a fresh copy, so a canceled draft never leaks.
+const NEW_PAYMENT: PaymentDraft = {
+	amount: 1280,
+	paidAt: new Date().toISOString(),
+	method: 'bank transfer',
 };
 </script>
 ```
@@ -1350,8 +1582,9 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
   close — use `persistent` instead; the close paths already guard correctly.
 - **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** unless you set `eager` —
-  the body renders lazily.
+- **Don't query dialog content before it has opened, or after it has closed**,
+  unless you set `eager`: the body exists only while the dialog is open or
+  closing.
 - **Don't forget `viewport-fit=cover`** in the page's viewport meta when the
   dialog is `adaptive`: on a phone its sheet keeps its bands clear of the
   notch and home indicator with band padding (and lifts above the on-screen
@@ -1384,6 +1617,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 ## v-model
 
 - `v-model` — type: `boolean \| undefined`
+- `v-model:snap` — type: `BbSnapPoint \| undefined`
 
 ## Props
 
@@ -1391,17 +1625,23 @@ 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. |
 | `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` |  | Render dialog content immediately instead of waiting for the first open. |
+| `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. |
 | `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`. |
 | `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. |
 | `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. |
+| `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. |
 | `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. |
@@ -1435,14 +1675,15 @@ States are listed in precedence order: when two are on at once and their entries
 - `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.
+- `update:snap` — `(value: BbSnapPoint \| undefined): void` — Emitted with the new value whenever `v-model:snap` changes.
 
 ## Slots
 
-- `default` — scope: `BbDialogDefaultSlotProps` `{ close: () => void; complete: (value?: any) => void; data: any }` — Primary body content of the dialog, rendered in the scrollable body area.
-- `description` — scope: `BbDialogDescriptionSlotProps` `{ text: string }` — 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; 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; 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 }` — 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.
+- `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.
+- `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.
+- `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
 
@@ -1470,7 +1711,7 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - `BbDialog` _(this component)_ — its own template binds: `header` → `div.bb-dialog__header`, `title` → `span.bb-dialog__title`, `description` → `p.bb-dialog__description`, `close` → `CloseButton`, `content` → `div.bb-dialog__content`, `footer` → `div.bb-dialog__footer`; hands `BbOffCanvas` the pt map `{ root: 'root', header: 'header', title: 'title', description: 'description', content: 'content', footer: 'footer', close: 'close', sheet: 'root', }` (ours → theirs)
   - `CloseButton` _(internal — not importable, reach it through `BbDialog`)_ — documented CSS variables: `--size`, `--p`
-  - `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`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`; also mounts `CloseButton`
+  - `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`; also mounts `CloseButton`
 
 ## See Also