bitboss-ui 2.1.135 → 3.0.0-alpha.1

package/dist/ai/BbDialog.md

@@ -1,129 +1,800 @@
 # BbDialog
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Overlay**
+- Description: Presents modal dialogs for focused user interactions.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbDialog.md](./source/BbDialog.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbDialog` when the user must **complete one focused task** without
+losing the context behind it: an edit form, a create step, a blocking
+announcement. It renders on top of the page with a backdrop and takes focus,
+so everything else is inert until it closes.
+
+Pick a sibling instead when the shape fits it better:
+
+- Supplementary content that sits _beside_ the page (filters, a detail panel,
+  settings) → `BbOffCanvas`.
+- A plain yes/no — especially a destructive confirm → `BbConfirm` with
+  `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.
+
+### Open and close with v-model
+
+`v-model` owns visibility — there is no imperative `open()`. Bind a boolean and
+flip it. The dialog dismisses itself on the header close button, the `Escape`
+key, and a backdrop click; the `default` slot also receives a `close` callback
+for buttons inside the body. Footer buttons simply set the model back to
+`false`.
+
+**A create-record dialog**
 
 ```vue
 <template>
-	<BaseDialog v-bind="props" v-model="model" v-on="dialogEventHandlers">
-		<template #close="data">
-			<slot name="close" v-bind="data" />
-		</template>
-		<template #default="data">
-			<slot name="default" v-bind="data" />
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">Issue labels</p>
+			<p class="m-0 text-xs text-gray-500">
+				12 labels · used across Northwind issues
+			</p>
+		</div>
+		<div>
+			<BbButton
+				prepend:icon="lucide:plus"
+				variant="primary"
+				@click="open = true"
+			>
+				New label
+			</BbButton>
+		</div>
+	</div>
+	<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-gray-500">
+				Names are unique per workspace and show up in filters.
+			</p>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton :disabled="!name.trim()" variant="primary" @click="create">
+					Create
+				</BbButton>
+			</div>
 		</template>
-		<template #description="data">
-			<slot name="description" v-bind="data" />
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
+
+const open = ref(false);
+const name = ref('');
+
+// 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>
+```
+
+### Header, footer and body
+
+A `title` prop renders the standard header (title text + close button) and wires
+`aria-labelledby` for you. Put form fields in the `default` slot and actions in
+the `footer` slot — keep exactly one primary action there and align the group to
+the end. The body area scrolls internally when content overflows; header and
+footer stay pinned. This edit-record dialog re-seeds a typed draft from the
+record on `@show` — so a canceled edit never leaks into the next session — and
+copies it back on save.
+
+**Edit-record dialog with a footer action**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div class="min-w-0">
+			<p class="m-0 truncate text-sm font-medium">{{ contact.name }}</p>
+			<p class="m-0 truncate text-xs text-gray-500">{{ contact.email }}</p>
+		</div>
+		<BbButton
+			prepend:icon="lucide:pencil"
+			variant="outline"
+			@click="open = true"
+		>
+			Edit contact
+		</BbButton>
+	</div>
+	<BbDialog v-model="open" size="md" title="Edit contact" @show="seedDraft">
+		<div class="grid gap-3">
+			<BbTextInput v-model="draft.name" compact label="Full name" />
+			<BbTextInput v-model="draft.email" compact label="Email" type="email" />
+			<BbSwitch v-model="draft.subscribed" label="Subscribed to updates" />
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton variant="primary" @click="save">Save changes</BbButton>
+			</div>
 		</template>
-		<template #footer="data">
-			<slot name="footer" v-bind="data" />
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { reactive, ref } from 'vue';
+import { BbButton, BbDialog, BbSwitch, BbTextInput } from 'bitboss-ui';
+
+type Contact = {
+	name: string;
+	email: string;
+	subscribed: boolean;
+};
+
+// The record being edited — in a real app this comes from your store/API.
+const contact = reactive<Contact>({
+	name: 'Ada Lovelace',
+	email: 'ada@analytical.co',
+	subscribed: true,
+});
+
+const open = ref(false);
+const draft = reactive<Contact>({ ...contact });
+
+// Re-seed on every open: a canceled edit must not leak into the next session.
+const seedDraft = () => {
+	Object.assign(draft, contact);
+};
+
+const save = () => {
+	// Persist here, then dismiss.
+	Object.assign(contact, draft);
+	open.value = false;
+};
+</script>
+```
+
+Use the `title` slot to restyle just the title text — it stays wired to
+`aria-labelledby` and receives the `title` prop as `text`. Omitting `title`
+removes the whole header (the close button then floats over the body corner
+unless `hide-close`), and you own the accessible name.
+
+Prefer `title` (or the `title` slot) for the standard header. The `header` slot
+replaces the entire header on both surfaces — you own the close control and must
+wire `titleId` for `aria-labelledby`. Give your root element `flex-1` so it fills
+the header row.
+
+### Forms in a dialog
+
+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 the draft on `@show` so a
+dismissed invite doesn't resurface half-typed:
+
+**Invite a teammate**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">Team · Northwind Labs</p>
+			<p class="m-0 text-xs text-gray-500">4 members · 1 pending invite</p>
+		</div>
+		<div>
+			<BbButton
+				prepend:icon="lucide:user-plus"
+				variant="primary"
+				@click="open = true"
+			>
+				Invite teammate
+			</BbButton>
+		</div>
+	</div>
+	<BbDialog v-model="open" 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
+				item-text="label"
+				item-value="value"
+				:items="roles"
+				label="Role"
+			/>
+			<p class="m-0 text-xs text-gray-500">
+				They'll get an email with a link that expires in 7 days.
+			</p>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<!-- Cancel is never gated on validity. -->
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton
+					:disabled="!canSend"
+					prepend:icon="lucide:send"
+					variant="primary"
+					@click="send"
+				>
+					Send invite
+				</BbButton>
+			</div>
 		</template>
-		<template #header="data">
-			<slot name="header" v-bind="data" />
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbButton, BbDialog, BbSelect, BbTextInput } from 'bitboss-ui';
+
+const roles = [
+	{ label: 'Member', value: 'member' },
+	{ label: 'Admin', value: 'admin' },
+	{ label: 'Viewer', value: 'viewer' },
+];
+
+const open = ref(false);
+const email = ref('');
+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.
+	open.value = false;
+};
+</script>
+```
+
+Two rules keep dialog forms honest:
+
+- Reset or re-seed the draft when the dialog opens (`@show` is the hook), not
+  when it closes — a dismissed dialog may be reopened with stale state.
+- On success, do the work first, then set the model to `false`; the close
+  transition runs while your toast/refresh happens.
+
+### Lifecycle events and lazy content
+
+Four events bracket the transitions — `show` fires as the model turns `true`,
+`shown` after the native `showModal()` call and initial focus, `hide` as the
+model turns `false`, and `hidden` after the close transition completes. Use
+`@show` to (re)seed form state, `@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
+`250`) times both the open/close animation and when `hidden` fires — reopening
+during the close transition keeps the dialog open instead of snapping shut.
+
+### Size
+
+`size` runs the shared `xs`–`2xl` scale and controls the dialog's **max width**
+(height always hugs content). The presets map to `config.dialogDefaultSizes`
+(384px for the default `sm`, up to 672px for `2xl`, overridable in the plugin
+options); a number is pixels and a string passes through as a CSS width. Give it
+a per-breakpoint map to widen responsively — narrow on phones, roomier on
+desktop — without media queries of your own. A bare size is resolved once; only
+the map form reacts to live resizes.
+
+**Responsive width**
+
+```vue
+<div>
+	<BbButton variant="outline" @click="state.open = true">
+		Release notes
+	</BbButton>
+	<BbDialog
+		v-model="state.open"
+		:size="{ default: 'sm', lg: 'xl' }"
+		title="What's new"
+	>
+		<p class="m-0 text-sm">
+			<strong>sm</strong> on phones, <strong>xl</strong> from the
+			<code>lg</code> breakpoint up — resize to see it switch.
+		</p>
+	</BbDialog>
+</div>
+```
+
+`fullscreen` overrides the scale and fills the viewport (minus the standard page
+padding — it is intentionally not edge-to-edge). Pass `fullscreen="mobile"` to
+go fullscreen only below the mobile breakpoint while keeping the sized modal on
+desktop.
+
+### Controlling dismissal
+
+Every dismissal path is governed by two props:
+
+- `persistent` — backdrop click and `Escape` no longer close; the dialog plays a
+  short "deny" nudge instead. Your own buttons (and the model) still work. Use
+  it when the user must make an explicit choice.
+- `disabled` — same guard, different intent: the surface is busy (a save in
+  flight). Combine with disabling your footer actions.
+
+Constraint: the header **close button bypasses both** — it always closes,
+regardless of `persistent`/`disabled`. When a dialog truly must be resolved from
+the footer, pair `persistent` with `hide-close`, and keep a visible Cancel so
+users are never trapped.
+
+Backdrop clicks are drag-protected: a text selection that starts inside the
+dialog and releases over the backdrop does not close it — only a genuine click
+that starts and ends on the backdrop (≤4px travel) does.
+
+`focus-target` (a CSS selector resolved inside the dialog) moves initial focus
+to a specific element; otherwise the browser gives it to the first tabbable
+element.
+
+**Persistent — must be resolved with a button**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">Finish setting up</p>
+			<p class="m-0 text-xs text-gray-500">
+				Add your company so invoices and invites look right.
+			</p>
+		</div>
+		<div>
+			<BbButton variant="outline" @click="open = true">Finish setup</BbButton>
+		</div>
+	</div>
+	<BbDialog
+		v-model="open"
+		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>
+			<div class="flex justify-end gap-2">
+				<!-- Keep a visible way out — never trap the user. -->
+				<BbButton variant="ghost" @click="open = false">Skip</BbButton>
+				<BbButton :disabled="!company.trim()" variant="primary" @click="save">
+					Save
+				</BbButton>
+			</div>
 		</template>
-		<template #title="data">
-			<slot name="title" v-bind="data" />
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
+
+const open = ref(false);
+const displayName = ref('');
+const company = ref('');
+
+// Re-seed on `@show` so a dismissed step reopens clean.
+const reset = () => {
+	displayName.value = '';
+	company.value = '';
+};
+
+const save = () => {
+	// Persist the profile here, then close.
+	open.value = false;
+};
+</script>
+```
+
+The busy case in practice: while a save is in flight, `disabled` denies
+backdrop and `Escape`, but it does **not** touch the dialog's content — pair
+it with `:disabled` on your inputs and Cancel. Return the promise from the
+primary button's `@click` and `BbButton` shows its loading state
+automatically; close only once the work resolves:
+
+**Async save — dismissal denied while in flight**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div class="min-w-0">
+			<p class="m-0 truncate text-sm font-medium">{{ projectName }}</p>
+			<p class="m-0 text-xs text-gray-500">Project · private</p>
+		</div>
+		<BbButton
+			prepend:icon="lucide:pencil"
+			variant="outline"
+			@click="open = true"
+		>
+			Rename project
+		</BbButton>
+	</div>
+	<BbDialog
+		v-model="open"
+		:disabled="saving"
+		title="Rename project"
+		@show="seed"
+	>
+		<div class="grid gap-3">
+			<BbTextInput
+				v-model="draft"
+				compact
+				:disabled="saving"
+				label="Project name"
+				placeholder="acme-storefront"
+			/>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<!-- Disable your own actions too — `disabled` only guards dismissal. -->
+				<BbButton :disabled="saving" variant="ghost" @click="open = false">
+					Cancel
+				</BbButton>
+				<!-- Returning the promise lets BbButton run its own loading state. -->
+				<BbButton :disabled="!draft.trim()" variant="primary" @click="save">
+					Rename
+				</BbButton>
+			</div>
 		</template>
-	</BaseDialog>
+	</BbDialog>
 </template>
 
 <script setup lang="ts">
-import BaseDialog from '../BaseDialog/BaseDialog.vue';
-import type {
-	BaseDialogProps,
-	BaseDialogEvents,
-	BaseDialogSlots,
-} from '../BaseDialog/types';
-
-const props = withDefaults(defineProps<BaseDialogProps>(), {
-	showClose: true,
-});
+import { ref } from 'vue';
+import { BbButton, BbDialog, BbTextInput } from 'bitboss-ui';
 
-const emit = defineEmits<BaseDialogEvents>();
+// The record being renamed — in a real app this comes from your store/API.
+const projectName = ref('acme-storefront');
 
-const dialogEventHandlers = {
-	hide: () => emit('hide'),
-	hidden: () => emit('hidden'),
-	show: () => emit('show'),
-	shown: () => emit('shown'),
-} as const;
+const open = ref(false);
+const draft = ref('');
+const saving = ref(false);
 
-defineSlots<BaseDialogSlots>();
+// Re-seed on `@show` so a dismissed rename never resurfaces half-typed.
+const seed = () => {
+	draft.value = projectName.value;
+	saving.value = false;
+};
 
-const model = defineModel<boolean>({ default: false });
+const save = async () => {
+	saving.value = true;
+	try {
+		// Simulated request — replace with your API call.
+		await new Promise((resolve) => setTimeout(resolve, 600));
+		projectName.value = draft.value.trim();
+		// Work first, then close: the transition runs while your UI refreshes.
+		open.value = false;
+	} finally {
+		saving.value = false;
+	}
+};
 </script>
-<style lang="postcss">
-@import './index.css';
-</style>
 ```
 
-## Types
+### Stacked dialogs (drill-in flows)
+
+Dialogs sharing a `stack` name **replace** one another: only the most recently
+opened member is visible, the ones beneath are hidden until it closes — the
+stack reads as a single surface whose content swaps as you drill in. Dialogs
+with different names (or none) are independent and simply layer by open order.
+Use a stack for a two-step flow that should not read as two boxes piling up.
+
+**Drill into advanced options**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">Workspace settings</p>
+			<p class="m-0 text-xs text-gray-500">Storage, backups, retention</p>
+		</div>
+		<div>
+			<BbButton variant="outline" @click="first = true">
+				Storage settings
+			</BbButton>
+		</div>
+	</div>
+	<BbDialog v-model="first" stack="settings" title="Storage">
+		<div class="grid gap-3">
+			<BbSwitch v-model="autoBackup" label="Automatic backups" />
+			<p class="m-0 text-xs text-gray-500">
+				Nightly snapshots keep the last 30 days of changes.
+			</p>
+			<BbButton
+				append:icon="lucide:chevron-right"
+				variant="outline"
+				@click="second = true"
+			>
+				Advanced retention…
+			</BbButton>
+		</div>
+	</BbDialog>
+	<BbDialog v-model="second" stack="settings" title="Advanced retention">
+		<div class="grid gap-3">
+			<BbSwitch v-model="keepForever" label="Keep monthly snapshots" />
+			<p class="m-0 text-xs text-gray-500">
+				Monthly snapshots stay available for 12 months after creation.
+			</p>
+		</div>
+		<template #footer>
+			<div class="flex justify-end">
+				<BbButton variant="primary" @click="second = false">Done</BbButton>
+			</div>
+		</template>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog, BbSwitch } from 'bitboss-ui';
+
+// Two dialogs sharing a `stack` name swap in place as you drill in.
+const first = ref(false);
+const second = ref(false);
 
-```ts
-export type {
-	BaseDialogProps as BbDialogProps,
-	BaseDialogEvents as BbDialogEvents,
-	BaseDialogSlots as BbDialogSlots,
-	Sizes,
-} from '../BaseDialog/types';
+const autoBackup = ref(true);
+const keepForever = ref(false);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-base-dialog {
-	&--transition-fade {
-		&.bb-base-dialog__overlay {
-		}
-		&.bb-base-dialog--opening {
-			&.bb-base-dialog__overlay {
-			}
-		}
-		&.bb-base-dialog--open {
-			&.bb-base-dialog__overlay {
-			}
-		}
-		&.bb-base-dialog--closing {
-			&.bb-base-dialog__overlay {
-			}
-		}
-		&.bb-base-dialog--closed {
-			&.bb-base-dialog__overlay {
-			}
-		}
-	}
+### Top layer: what's above, what's inert
 
-	&--closed {
-		&.bb-base-dialog__overlay {
-		}
-	}
+The dialog is a native `<dialog>` opened with `showModal()`. That has concrete
+consequences an agent should design around:
 
-	&--fullscreen {
-		&.bb-base-dialog__overlay {
-		}
+- It renders in the browser **top layer** — above every `z-index`, sticky
+  header, or transformed ancestor. There is nothing to z-index-manage.
+- The element stays where you declared it in the DOM (no teleport), so scoped
+  styles and provide/inject work normally; in tests, query the panel via
+  `document.body` (e.g. `.bb-dialog--open`) after `attachTo: document.body`.
+- Everything outside the dialog is **inert** while it is open: no hover, click,
+  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.
 
-		.bb-base-dialog__panel.bb-dialog {
-		}
+Nested overlays are fine in moderation (a select, a confirm on top of a form
+dialog). A second full dialog on top of another usually means the flow wants a
+`stack` (above) or a page of its own.
 
-		.bb-base-dialog__content {
-		}
-	}
+### Navigating from a dialog
 
-	&--compact {
-		.bb-base-dialog__content {
-		}
-	}
+When a dialog's action leads somewhere, let the button navigate — never wire a
+click handler to `router.push` or `window.location`. `BbButton` accepts `href`
+(or an Inertia visit) and `to` (a vue-router target), so the action stays a real
+link.
 
-	&__overlay {
-	}
-	&__panel.bb-dialog {
-		.bb-base-dialog__content {
-			.bb-base-dialog__header {
-			}
-			.bb-base-dialog__body {
-			}
-			.bb-base-dialog__footer {
-			}
-		}
-	}
-}
+**Upgrade prompt whose primary action navigates**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">Projects</p>
+			<p class="m-0 text-xs text-gray-500">
+				Free plan · {{ used }} of {{ limit }} used
+			</p>
+		</div>
+		<div>
+			<BbButton
+				prepend:icon="lucide:plus"
+				variant="outline"
+				@click="open = true"
+			>
+				New project
+			</BbButton>
+		</div>
+	</div>
+	<BbDialog v-model="open" title="Project limit reached">
+		<div class="grid gap-3">
+			<p class="m-0 text-sm">
+				The <strong>Free</strong> plan includes {{ limit }} projects and you're
+				using all of them. Upgrade to <strong>Pro</strong> for unlimited
+				projects and priority support.
+			</p>
+			<p class="m-0 text-xs text-gray-500">
+				Billing starts when you confirm — you can cancel anytime.
+			</p>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Maybe later</BbButton>
+				<!-- A navigating action is a real link — never `@click` + router.push. -->
+				<BbButton
+					append:icon="lucide:arrow-right"
+					href="#settings-billing"
+					variant="primary"
+				>
+					Upgrade to Pro
+				</BbButton>
+			</div>
+		</template>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog } from 'bitboss-ui';
+
+const used = 3;
+const limit = 3;
+const open = ref(false);
+</script>
 ```
+
+On Nuxt or Inertia the same button carries a platform-native navigation:
+
+```vue
+<!-- Inertia: href becomes an Inertia visit -->
+<BbButton href="/settings/billing" method="get">Upgrade to Pro</BbButton>
+
+<!-- Nuxt / vue-router: navigate with `to` -->
+<BbButton :to="{ name: 'settings-billing' }">Upgrade to Pro</BbButton>
+```
+
+Because a modal dialog is client-side UI, SSR (Nuxt) renders it closed and
+empty; content appears on first open (or immediately with `eager`).
+
+### Adaptive: a bottom sheet on mobile
+
+By default (`config.adaptive`, `true` out of the box) a dialog opened on a small
+viewport (below `config.mobileMaxWidth`, 768px) renders as a `BbOffCanvas`
+bottom sheet instead of a centered modal — better ergonomics for thumbs. The
+surface is **latched when the dialog opens** and stays fixed for that session,
+so a mid-flow resize never swaps modal ↔ sheet.
+
+- The sheet defaults to a bottom, draggable, content-sized drawer
+  (`direction: 'bottom'`, `draggable: true`, `size: 'auto'`); the dialog's
+  `size` is intentionally **not** forwarded (width and drawer extent mean
+  different things).
+- `title`, `persistent`, `disabled`, `hide-close`, `focus-target`, `eager`,
+  `fullscreen`, `stack` and `transition-duration` carry over; the four
+  lifecycle events fire the same either way.
+- `off-canvas-props` merges last over the sheet's props — use it to change
+  direction, size, `stack-gap`, or disable dragging on the mobile surface only.
+- `:adaptive="false"` keeps the centered dialog everywhere; a bare `adaptive`
+  forces the sheet behavior on regardless of the global config.
+
+Leave `adaptive` unset unless the project asks otherwise — the tri-state
+default falls back to `config.adaptive`.
+
+### Works well with
+
+- `BbConfirm` + `useConfirm` — a destructive action inside your dialog should
+  raise a confirm on top, not a second hand-built dialog.
+- `BbToast` + `useToast` — fire the success toast right before closing; it
+  stays interactive above the modal.
+- `BbSelect`, `BbDatePicker`-style poppers inside the body: they open in the
+  top layer above the dialog with no extra wiring.
+- `BbOffCanvas` — the same content as a side panel when it is supplementary
+  rather than blocking; the shared API keeps the swap cheap.
+
+### Gotchas & anti-patterns
+
+- **Don't rely on the close (x) button respecting `persistent`** — it doesn't;
+  hide it (`hide-close`) when the dialog must be resolved explicitly.
+- **Don't build a yes/no dialog** — that's `BbConfirm` with `useConfirm`.
+- **Don't wire `@click` + `router.push`** for a navigating action — pass
+  `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.
+- **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.
+- A dialog is not a router surface: if the task grows tabs, lists and
+  sub-navigation, it wants a page (or an `BbOffCanvas` detail panel), not a
+  bigger modal.
+
+### Accessibility
+
+- Prefer passing `title` — it labels the dialog via `aria-labelledby`. If you
+  omit it (no header) you own the accessible name: label a heading in the body
+  and wire it yourself.
+- The dialog is a true modal (`showModal()`): the browser contains focus within
+  it, the page behind is inert, and focus returns to the trigger when it
+  closes. `focus-target` only chooses where focus **starts**.
+- The header close button carries a localized `aria-label` out of the box
+  (`config.locale`).
+- Don't lean on `persistent` to trap users. Keep a visible way out (a Cancel or
+  Close button) even when backdrop/`Escape` dismissal is disabled.
+
+## v-model
+
+- `v-model` — type: `boolean \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | Adapt the surface to the viewport: render as a `BbOffCanvas` drawer on mobile instead of a centered dialog. The surface is resolved when the dialog opens and stays fixed for that session: resizing across the mobile breakpoint while open nev… |
+| `disabled` | `boolean \| undefined` |  |  | Disable EVERY user-initiated dismissal: backdrop click, Escape AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the dialog cannot be dismissed mid-work. Compare `… |
+| `eager` | `boolean \| undefined` |  |  | Render dialog content immediately instead of waiting for the first open. |
+| `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` |  |  | 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). |
+| `modelValue` | `boolean \| undefined` | `false` |  |  |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides merged over the offcanvas (mobile) surface's props. The drawer defaults to a bottom, draggable, content-sized sheet (`direction: 'bottom'`, `draggable: true`, `size: 'auto'`); use this to override those, set other drawer-only opti… |
+| `persistent` | `boolean \| undefined` |  |  | 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 `disabled` to block every dismissal. Program… |
+| `size` | `Responsive<NonNullable<number \| ({ size?: any; } & string) \| keyof Sizes \| 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. |
+| `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 … |
+| `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` | `transitions.medium` |  | Controls the duration of the open and close animations. |
+
+## Events
+
+- `hidden` — `(event: "hidden"): void`
+- `hide` — `(event: "hide"): void`
+- `show` — `(event: "show"): void`
+- `shown` — `(event: "shown"): void`
+- `update:modelValue` — `(event: "update:modelValue", value: boolean): void`
+
+## Slots
+
+- `default` — scope: `BbDialogDefaultSlotProps` — Primary body content of the dialog, rendered in the scrollable body area.
+- `footer` — scope: `object` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
+- `header` — scope: `BbDialogHeaderSlotProps` — Replaces the entire dialog header section (title + close button) on both surfaces — the desktop `<dialog>` and the mobile off-canvas. Because it replaces the default close (✕), the slot owns closing: render your own control wired to the `cl…
+- `title` — scope: `BbDialogTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`.
+
+## See Also
+
+- [BbOffCanvas](./BbOffCanvas.md) — Shows side-panel overlay content outside normal layout flow.
+- [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.