bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbOffCanvas.md

@@ -1,548 +1,947 @@
 # BbOffCanvas
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Overlay**
+- Description: Shows side-panel overlay content outside normal layout flow.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbOffCanvas.md](./source/BbOffCanvas.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbOffCanvas` for **supplementary content that lives beside the main
+task**: a filter panel, a record's detail view, a settings drawer, a
+notifications tray. It slides in from an edge, dims the page, and leaves as
+quickly as it came — the user is topping up context, not switching tasks.
+
+Choose a sibling when the intent differs:
+
+- A single focused task the user must finish (a form, a confirm, an
+  announcement) → `BbDialog` (centered modal).
+- A plain yes/no or destructive confirm → `BbConfirm` with `useConfirm`.
+- A small anchored menu or bit of interactive content → `BbPopover`.
+
+`BbDialog` and `BbOffCanvas` share most of their API (v-model, `title`, the
+`header` / `default` / `footer` slots, `persistent`, `disabled`, `hide-close`,
+`focus-target`, `eager`, `stack`, `transition-duration`, and the four lifecycle
+events), so moving a surface between them is mostly a tag swap. The differences
+are physical: `size` means the panel's **extent along its axis** (not a max
+width), and `side`, `draggable` and `stack-gap` are off-canvas-only.
+
+### Open and close with v-model
+
+`v-model` owns visibility — there is no imperative `open()`. Bind a boolean and
+flip it. The panel 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, and footer buttons simply set the model back to
+`false`.
+
+**A right-hand panel**
 
 ```vue
 <template>
-	<dialog
-		ref="dialog"
-		:aria-describedby="
-			hasRenderedAtLeastOnce && description ? descriptionId : undefined
-		"
-		:aria-labelledby="hasRenderedAtLeastOnce && title ? titleId : undefined"
-		:aria-live="model ? 'polite' : 'off'"
-		class="bb-offcanvas"
-		:class="
-			[
-				{
-					'bb-offcanvas--open': model,
-					'bb-offcanvas--fullscreen': isFullscreen,
-					'bb-offcanvas--compact': compact,
-					'bb-offcanvas--deny-close': denyClose,
-					[`bb-offcanvas--${props.direction}`]: true,
-				},
-				overlayClasses,
-				panelClasses,
-			].flat()
-		"
-		:inert="!model"
-		:style="{
-			'--max-size': maxSize,
-			'--transition-duration': `${props.transitionDuration}ms`,
-		}"
-		@cancel="userClose"
-		@click.self="userClose"
+	<div
+		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
 	>
-		<template v-if="hasRenderedAtLeastOnce">
-			<div ref="header" class="bb-offcanvas__header">
-				<slot :close="close" name="header" :title="title" :title-id="titleId">
-					<span :id="titleId" class="bb-offcanvas__title">
-						<slot name="title" :text="title">{{ title }}</slot>
-					</span>
-					<span class="bb-offcanvas__close">
-						<button
-							v-if="showClose"
-							:aria-label="closeLabel"
-							:disabled="props.disabled"
-							type="button"
-							@click="close"
-						>
-							<slot name="close">
-								<span class="bb-offcanvas__close-icon"
-									><svg
-										aria-hidden="true"
-										fill="none"
-										viewBox="0 0 24 24"
-										xmlns="http://www.w3.org/2000/svg"
-									>
-										<path
-											d="M23 23L1 1M23 1L1 23"
-											stroke="currentColor"
-											stroke-linecap="round"
-											stroke-width="3"
-										/>
-									</svg>
-								</span>
-							</slot>
-						</button>
-					</span>
-				</slot>
-			</div>
-			<div ref="body" class="bb-offcanvas__body scrollbar-border">
-				<div class="bb-offcanvas__body-content">
-					<slot
-						:description-id="descriptionId"
-						name="description"
-						:text="description"
-						><div
-							v-if="description"
-							:id="descriptionId"
-							class="bb-offcanvas__description sr-only"
-						>
-							{{ description }}
-						</div>
-					</slot>
-					<slot></slot>
+		<div class="min-w-0">
+			<p class="m-0 text-sm font-medium">Workspace</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				3 updates since yesterday
+			</p>
+		</div>
+		<BbButton variant="outline" @click="open = true">Open activity</BbButton>
+	</div>
+	<BbOffCanvas v-model="open" side="right" title="Recent activity">
+		<template #default="{ close }">
+			<div class="grid gap-3 text-sm">
+				<div v-for="entry in activity" :key="entry.id" class="grid gap-0.5">
+					<p class="m-0">{{ entry.text }}</p>
+					<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+						{{ entry.when }}
+					</p>
 				</div>
-			</div>
-
-			<div ref="footer" class="bb-offcanvas__footer">
-				<slot name="footer"></slot>
+				<BbButton class="justify-self-start" variant="ghost" @click="close">
+					Close
+				</BbButton>
 			</div>
 		</template>
-	</dialog>
+	</BbOffCanvas>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas } from 'bitboss-ui';
+
+type ActivityEntry = {
+	id: number;
+	text: string;
+	when: string;
+};
+
+const open = ref(false);
+
+const activity: ActivityEntry[] = [
+	{
+		id: 1,
+		text: 'Invoice #INV-2043 was paid.',
+		when: '12 minutes ago',
+	},
+	{
+		id: 2,
+		text: 'Maria commented on “Q3 report”.',
+		when: '1 hour ago',
+	},
+	{
+		id: 3,
+		text: 'Webhook delivery to Stripe succeeded.',
+		when: 'Yesterday · 16:42',
+	},
+];
+</script>
+```
+
+### Direction
+
+`side` sets the edge the panel enters from — `left`, `right`, `top`, or
+`bottom` (default `left`). Use `right` for detail and filter panels that sit
+beside a right-aligned action flow, `bottom` for mobile-style sheets, `top` for
+banners and command surfaces. The side also decides the drag axis and which
+dimension `size` controls.
 
+**Enter from any edge**
+
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-wrap gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<BbButton
+			v-for="edge in edges"
+			:key="edge"
+			variant="outline"
+			@click="activeSide = edge"
+		>
+			{{ edge }}
+		</BbButton>
+		<BbOffCanvas
+			:model-value="activeSide !== null"
+			:side="activeSide ?? 'right'"
+			:title="`From ${activeSide ?? 'right'}`"
+			@update:model-value="
+				(value) => {
+					if (!value) activeSide = null;
+				}
+			"
+		>
+			<p class="m-0 text-sm">
+				This panel slid in from the <strong>{{ activeSide }}</strong> edge.
+			</p>
+		</BbOffCanvas>
+	</div>
+</template>
 <script setup lang="ts">
-import { computed, nextTick, onMounted, ref, watch, type Ref } from 'vue';
-import { parseSize } from '@/utilities/functions/parseSize';
-import { useId } from '@/composables/useId';
-import { useLocale } from '@/composables/useLocale';
-import { useMobile } from '@/composables/useMobile';
-import { useUntil } from '@/composables/useUntil';
-import { wait } from '@/utilities/functions/wait';
-import { _config } from '@/composables/useBbConfig';
-import type {
-	BbOffCanvasProps,
-	BbOffCanvasEvents,
-	BbOffCanvasSlots,
-	Sizes,
-} from './types';
-
-const props = withDefaults(defineProps<BbOffCanvasProps>(), {
-	direction: 'left',
-	showClose: true,
-	size: 'sm',
-	panelClasses: () => [],
-	overlayClasses: () => [],
-	transitionDuration: 300,
-});
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas } from 'bitboss-ui';
 
-const emit = defineEmits<BbOffCanvasEvents>();
+type Side = 'left' | 'top' | 'right' | 'bottom';
 
-defineSlots<BbOffCanvasSlots>();
+const edges: Side[] = ['left', 'right', 'top', 'bottom'];
+const activeSide = ref<Side | null>(null);
+</script>
+```
 
-const model = defineModel<boolean>({ default: false });
+### Header, footer and body
 
-const { t } = useLocale();
-const closeLabel = computed(
-	() => props.closeLabel || t('dialog.closeLabel').value
-);
+A `title` prop renders the standard header (title text + close button) and wires
+`aria-labelledby` for you. Put content in the `default` slot and actions in the
+`footer` slot. The body area scrolls internally when content overflows; the
+header and footer stay pinned.
 
-const dialog = ref<HTMLDialogElement | null>(null);
-const hasRenderedAtLeastOnce: Ref<boolean> = useUntil(
-	() => model.value || props.eager,
-	{
-		initialValue: model.value || props.eager,
-	}
-);
-
-const titleId = `title_${useId().id.value}`;
-const descriptionId = `description_${useId().id.value}`;
-
-const handleKeyDown = (e: KeyboardEvent) => {
-	if (e.key !== 'Escape') return;
-	e.stopImmediatePropagation();
-	if (props.disabled || props.persistent) {
-		e.preventDefault();
-		denyClose.value = true;
-		wait(200).then(() => {
-			denyClose.value = false;
-		});
-		return false;
-	}
-};
-const toggleDialog = async (value: boolean) => {
-	if (value) {
-		emit('show');
-		// On first opening set variable for scrollbar width that is used to pad the body
-		if (
-			window.globalThis?.document &&
-			!document.documentElement.style.getPropertyValue('--scrollbar-width')
-		) {
-			document.documentElement.style.setProperty(
-				'--scrollbar-width',
-				`${getScrollBarWidth()}px`
-			);
-		}
-		document.addEventListener('keydown', handleKeyDown, { capture: true });
-		await nextTick();
-		dialog.value?.showModal();
-		if (props.focusTarget) {
-			const element = dialog.value?.querySelector(props.focusTarget!);
-			if (element && element instanceof HTMLElement) {
-				element.focus();
-			}
-		}
-		emit('shown');
-	} else {
-		emit('hide');
-		await wait(props.transitionDuration);
-		if (window.globalThis?.document) {
-			document.removeEventListener('keydown', handleKeyDown, { capture: true });
-		}
-		dialog.value?.close();
-		emit('hidden');
-	}
+- Use the `title` slot to restyle just the title text — it stays wired to
+  `aria-labelledby` and receives the `title` prop as `text`.
+- Unlike `BbDialog`, the **`header` slot is fully supported here** and replaces
+  the whole header section; it receives `titleId`, `title` and `close`, so you
+  can build a custom header and still keep the accessible name wired through
+  `titleId`.
+- Omitting `title` (and the `header` slot) removes the header entirely — you
+  then own the accessible name.
+
+### A filters drawer
+
+The archetypal off-canvas: search + toggles in the `default` slot, Apply/Reset
+in the `footer`. Keep one primary action (Apply) and align actions to the end.
+This companion seeds typed filter state and resets it in place.
+
+**Invoice filters**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="min-w-0">
+			<p class="m-0 text-sm font-medium">Invoices</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				{{ matchingLabel }}
+			</p>
+		</div>
+		<BbButton
+			prepend:icon="lucide:sliders-horizontal"
+			variant="outline"
+			@click="open = true"
+		>
+			Filters
+		</BbButton>
+	</div>
+	<BbOffCanvas v-model="open" side="right" title="Filter invoices">
+		<div class="grid gap-3">
+			<BbTextInput
+				v-model="filters.query"
+				compact
+				label="Search"
+				placeholder="Invoice #, customer…"
+			/>
+			<BbCheckbox v-model="filters.overdue" label="Only overdue" />
+			<BbCheckbox v-model="filters.unpaid" label="Only unpaid" />
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="reset">Reset</BbButton>
+				<BbButton variant="primary" @click="open = false">Apply</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+<script setup lang="ts">
+import { computed, reactive, ref } from 'vue';
+import { BbButton, BbCheckbox, BbOffCanvas, BbTextInput } from 'bitboss-ui';
+
+type InvoiceFilterState = {
+	query: string;
+	overdue: boolean;
+	unpaid: boolean;
 };
 
-watch(model, toggleDialog);
-onMounted(() => {
-	if (model.value) toggleDialog(true);
+const open = ref(false);
+const filters = reactive<InvoiceFilterState>({
+	query: '',
+	overdue: false,
+	unpaid: true,
 });
 
-const maxSize = computed(() => {
-	if (!isFullscreen.value) {
-		if (props.size === 'auto') return 'fit-content';
-		return parseSize(props.size, _config.offCanvasDefaultSizes);
-	}
+const activeCount = computed(() => {
+	let count = 0;
+	if (filters.query.trim()) count += 1;
+	if (filters.overdue) count += 1;
+	if (filters.unpaid) count += 1;
+	return count;
+});
 
-	return '100%';
+const matchingLabel = computed(() => {
+	const n = activeCount.value;
+	if (n === 0) return '48 total · no filters';
+	return `12 matching · ${n} filter${n === 1 ? '' : 's'} on`;
 });
 
-/**
- * This function is called when the user attempts to close the dialog.
- * It differs from programmatically closing the dialog in that it allows for
- * custom logic to be executed.
- */
-const userClose = (event: Event) => {
-	event.preventDefault();
-	// If the user forces closing just allow them
-	if (props.disabled || props.persistent) {
-		denyClose.value = true;
-		wait(300).then(() => {
-			denyClose.value = false;
-		});
-		return false;
-	}
-
-	close();
+/** Clear every filter back to the empty baseline. */
+const reset = () => {
+	filters.query = '';
+	filters.overdue = false;
+	filters.unpaid = false;
 };
+</script>
+```
 
-const close = () => {
-	model.value = false;
-};
+### A record inspector
+
+The other archetype: a record's detail view opened beside a list, so the user
+keeps their place in the table. Open from a row, show identity + status + key
+fields in a `right`-hand panel, and let footer actions navigate or close. This
+companion opens an inspector per selected member and offloads the "open full
+record" action to `BbButton`'s `href` rather than a click handler.
 
-const denyClose = ref(false);
+**Record inspector**
 
-const getScrollBarWidth = () => {
-	if (!globalThis.document) return 0;
-	return window.innerWidth - document.documentElement.clientWidth;
+```vue
+<template>
+	<div class="grid max-w-sm gap-1 rounded-[var(--bb-radius)] border p-1">
+		<p
+			class="m-0 px-2 pt-1.5 text-xs font-medium text-[color:var(--bb-text-muted)]"
+		>
+			Members
+		</p>
+		<BbButton
+			v-for="member in members"
+			:key="member.id"
+			class="justify-start"
+			size="sm"
+			variant="ghost"
+			@click="openDetail(member)"
+		>
+			<span class="flex min-w-0 items-center gap-2">
+				<BbAvatar :alt="member.name" size="xs">
+					{{ member.initials }}
+				</BbAvatar>
+				<span class="truncate">{{ member.name }}</span>
+			</span>
+		</BbButton>
+	</div>
+	<BbOffCanvas v-model="open" side="right" size="sm" :title="selected?.name">
+		<div v-if="selected" class="grid gap-4 text-sm">
+			<div class="flex items-start gap-3">
+				<BbAvatar :alt="selected.name" size="lg">
+					{{ selected.initials }}
+				</BbAvatar>
+				<div class="grid min-w-0 gap-1.5">
+					<p class="m-0 font-medium">{{ selected.role }}</p>
+					<BbBadge size="sm" :variant="selected.statusVariant">
+						{{ selected.status }}
+					</BbBadge>
+				</div>
+			</div>
+			<dl class="m-0 grid gap-2">
+				<div
+					v-for="row in detailRows"
+					:key="row.label"
+					class="flex items-baseline justify-between gap-3"
+				>
+					<dt class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">
+						{{ row.label }}
+					</dt>
+					<dd class="m-0 truncate text-right">{{ row.value }}</dd>
+				</div>
+			</dl>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Close</BbButton>
+				<BbButton
+					append:icon="lucide:arrow-right"
+					:href="`#member-${selected?.id}`"
+					variant="primary"
+				>
+					Open full record
+				</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbAvatar, BbBadge, BbButton, BbOffCanvas } from 'bitboss-ui';
+
+type MemberStatus = 'Active' | 'Away';
+
+type Member = {
+	id: number;
+	name: string;
+	initials: string;
+	role: string;
+	email: string;
+	joined: string;
+	team: string;
+	status: MemberStatus;
+	statusVariant: 'soft-green' | 'soft-amber';
 };
 
-const { isMobile } = useMobile();
-const isFullscreen = computed(
-	() =>
-		props.fullscreen === true ||
-		(props.fullscreen === 'mobile' && isMobile.value)
-);
+const members: Member[] = [
+	{
+		id: 1,
+		name: 'Ada Lovelace',
+		initials: 'AL',
+		role: 'Lead engineer',
+		email: 'ada@northwind.co',
+		joined: 'Mar 2021',
+		team: 'Platform',
+		status: 'Active',
+		statusVariant: 'soft-green',
+	},
+	{
+		id: 2,
+		name: 'Grace Hopper',
+		initials: 'GH',
+		role: 'Principal engineer',
+		email: 'grace@northwind.co',
+		joined: 'Sep 2019',
+		team: 'Billing',
+		status: 'Away',
+		statusVariant: 'soft-amber',
+	},
+];
+
+const open = ref(false);
+const selected = ref<Member | null>(null);
+
+const detailRows = computed(() => {
+	const member = selected.value;
+	if (!member) return [];
+	return [
+		{ label: 'Email', value: member.email },
+		{ label: 'Team', value: member.team },
+		{ label: 'Joined', value: member.joined },
+	];
+});
+
+/** Open the inspector for the chosen member beside the list. */
+const openDetail = (member: Member) => {
+	selected.value = member;
+	open.value = true;
+};
 </script>
 
-<style lang="postcss">
-@import './index.css';
+<!-- Non-scoped: soft status palette for the inspector badge.
+     Canonical source: ai/guides/design-language.md § Using color. -->
+<style>
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-amber {
+	--accent: #d97706;
+}
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-amber {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
 </style>
 ```
 
-## Types
+### A mobile nav sheet
 
-```ts
-import type { Classes } from '@/types/Classes';
-import type { CommonProps, Size } from '@/types/CommonProps';
+The third classic: app navigation behind a menu button. A `left` drawer at
+`size="xs"` reads as the familiar mobile nav; every destination is a real link
+(`href` — hash-only here, in an app pass `to` for the router), never an
+`@click` handler. Icon names live as typed literals on the nav data and flow
+into `BbButton`'s `prepend:icon`; the active route gets the one non-ghost
+treatment in the list, and account/sign-out sit in the footer.
 
-export type Sizes = {
-	sm: number;
-	md: number;
-	lg: number;
-};
+**Mobile navigation sheet**
 
-export type BbOffCanvasProps = Pick<
-	CommonProps,
-	| 'closeLabel'
-	| 'compact'
-	| 'disabled'
-	| 'eager'
-	| 'persistent'
-	| 'showClose'
-	| 'title'
-	| 'transitionDuration'
-> &
-	Size<Sizes> & {
-		/**
-		 * Description of the content of the modal. Extremely useful for accessibility reasons.
-		 */
-		description?: string;
-		/**
-		 * Element that obtains focus immediately after opening the dialog.
-		 * By default it's the first tabbable item.
-		 */
-		focusTarget?: string;
-		/**
-		 * Displays the modal as fullscreen with no margin to the page.
-		 */
-		fullscreen?: boolean | 'mobile';
-
-		/**
-		 * Classes to apply to the panel of the dialog.
-		 *
-		 * @deprecated Pass a common `class` attribute to the component instead.
-		 */
-		panelClasses?: Classes;
-		/**
-		 * Classes to apply to the overlay of the dialog.
-		 *
-		 * @deprecated Pass a common `class` attribute to the component instead.
-		 */
-		overlayClasses?: Classes;
-		/**
-		 * Defines the direction the offcanvas should appear from.
-		 *
-		 * @defaultValue `'left'`
-		 */
-		direction?: 'left' | 'top' | 'right' | 'bottom';
-	};
-
-export type BbOffCanvasEvents = {
-	/** Emitted as soon as the user triggers the open action (model becomes true). */
-	(e: 'show'): void;
-	/** Emitted as soon as the user triggers the close action (model becomes false). */
-	(e: 'hide'): void;
-	/** Emitted after the offcanvas is fully opened using `showModal()`. */
-	(e: 'shown'): void;
-	/** Emitted after the close transition completes and the offcanvas is fully dismissed. */
-	(e: 'hidden'): void;
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-2"
+	>
+		<div class="min-w-0">
+			<p class="m-0 truncate text-sm font-medium">Acme Billing</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">Workspace</p>
+		</div>
+		<BbButton
+			aria-label="Open navigation"
+			icon="lucide:menu"
+			variant="outline"
+			@click="open = true"
+		>
+			Menu
+		</BbButton>
+	</div>
+	<BbOffCanvas v-model="open" side="left" size="xs" title="Acme Billing">
+		<nav aria-label="Primary" class="grid gap-1">
+			<p
+				class="m-0 px-1 pb-0.5 text-xs font-medium text-[color:var(--bb-text-muted)]"
+			>
+				Navigate
+			</p>
+			<BbButton
+				v-for="item in navItems"
+				:key="item.href"
+				class="justify-start"
+				:href="item.href"
+				:prepend:icon="item.icon"
+				size="sm"
+				:variant="item.active ? 'secondary' : 'ghost'"
+			>
+				{{ item.label }}
+			</BbButton>
+		</nav>
+		<template #footer>
+			<div class="grid gap-1">
+				<BbButton
+					class="w-full justify-start"
+					href="#account"
+					prepend:icon="lucide:circle-user"
+					size="sm"
+					variant="ghost"
+				>
+					Alex Rivera
+				</BbButton>
+				<BbButton
+					class="w-full justify-start"
+					href="#sign-out"
+					prepend:icon="lucide:log-out"
+					size="sm"
+					variant="ghost"
+				>
+					Sign out
+				</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas, type IconType } from 'bitboss-ui';
+
+type NavItem = {
+	label: string;
+	href: string;
+	icon: IconType;
+	active?: boolean;
 };
 
-/** Props exposed by the `header` slot. */
-export type BbOffCanvasHeaderSlotProps = {
-	/** The `id` assigned to the title element, wired to `aria-labelledby`. */
-	titleId: string;
-	/** Programmatically closes the off-canvas panel. */
-	close: () => void;
-	/** The `title` prop value. */
-	title: BbOffCanvasProps['title'];
-};
+const open = ref(false);
 
-/** Props exposed by the `title` slot. */
-export type BbOffCanvasTitleSlotProps = {
-	/** The `title` prop value. */
-	text: BbOffCanvasProps['title'];
-};
+const navItems: NavItem[] = [
+	{
+		label: 'Dashboard',
+		href: '#dashboard',
+		icon: 'lucide:house',
+		active: true,
+	},
+	{ label: 'Invoices', href: '#invoices', icon: 'lucide:receipt' },
+	{ label: 'Customers', href: '#customers', icon: 'lucide:users' },
+	{ label: 'Reports', href: '#reports', icon: 'lucide:chart-line' },
+	{ label: 'Settings', href: '#settings', icon: 'lucide:settings' },
+];
+</script>
+```
+
+### Size and `auto`
+
+`size` runs the shared `xs`–`2xl` scale **plus `auto`**, and controls the
+panel's extent along its travel axis — width for `left`/`right`, height for
+`top`/`bottom`. The presets map to `config.offCanvasDefaultSizes` (320px for
+`xs` up to 672px for `2xl`; the default `sm` is 384px, overridable in the plugin
+options). A number is pixels, a string passes through as a CSS size, and `auto`
+hugs the content (`fit-content`) — the basis of a content-sized sheet.
+
+Give it a per-breakpoint map to switch responsively without media queries of
+your own. Like `BbDialog`, a **bare size is resolved once**; only the map form
+reacts to live resizes.
+
+**Responsive extent**
+
+```vue
+<div>
+	<BbButton variant="outline" @click="state.open = true">Settings</BbButton>
+	<BbOffCanvas
+		v-model="state.open"
+		side="right"
+		:size="{ default: 'sm', lg: 'lg' }"
+		title="Settings"
+	>
+		<p class="m-0 text-sm">
+			<strong>sm</strong> (384px) on smaller viewports, <strong>lg</strong>
+			(512px) from the <code>lg</code> breakpoint up — resize to see it switch.
+		</p>
+	</BbOffCanvas>
+</div>
+```
+
+### Draggable sheets
+
+Set `draggable` to let the user flick the panel toward its edge to dismiss; a
+grab handle appears on the inner edge as the affordance. A draggable,
+`auto`-sized bottom panel is the canonical mobile sheet.
+
+The gesture is physical, not just a tap target:
+
+- Dragging past **a quarter of the panel's extent**, or a fast **flick toward
+  the edge**, dismisses it; a shorter drag springs back to fully open.
+- On a vertical (top/bottom) sheet with a scrollable body, the drag **hands off
+  to native scrolling** first — you only start dragging the sheet once the body
+  is scrolled to its edge, so scrolling a long sheet never accidentally closes
+  it.
+- `persistent` / `disabled` still win: a drag that would dismiss instead plays
+  the "deny" nudge and springs back.
+
+**A draggable bottom sheet**
+
+```vue
+<div>
+	<BbButton variant="outline" @click="state.open = true">Share</BbButton>
+	<BbOffCanvas
+		v-model="state.open"
+		side="bottom"
+		draggable
+		size="auto"
+		title="Share invoice"
+	>
+		<div class="flex flex-wrap gap-2">
+			<BbButton append:icon="lucide:link" variant="outline">Copy link</BbButton>
+			<BbButton append:icon="lucide:mail" variant="outline">Email</BbButton>
+			<BbButton append:icon="lucide:download" variant="outline">Download PDF</BbButton>
+		</div>
+	</BbOffCanvas>
+</div>
+```
 
-/** Props exposed by the `description` slot. */
-export type BbOffCanvasDescriptionSlotProps = {
-	/** The `id` to assign to your custom description element for `aria-describedby` wiring. */
-	descriptionId: string;
-	/** The `description` prop value. */
-	text: BbOffCanvasProps['description'];
+### Stacking drill-downs
+
+Give panels the same `stack` name and they step back behind one another as you
+drill in: opening a child shifts the parent inward by `stack-gap` (default
+`60`px), leaving a peeking band of it visible so the hierarchy reads clearly.
+Closing the child brings the parent forward. Panels with **different names (or
+none) are independent** and simply layer by open order.
+
+Only the top two open panels keep their dimmed/blurred backdrop; deeper ones go
+transparent, so a three-deep stack does not stack three backdrops. Use a stack
+for master → detail flows where the trail should stay visible; if the parent
+should be fully replaced instead, that is what `BbDialog`'s `stack` (which swaps
+rather than peeks) is for.
+
+**Master → detail, stacked**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="min-w-0">
+			<p class="m-0 text-sm font-medium">Team</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				Drill into a member
+			</p>
+		</div>
+		<BbButton variant="outline" @click="listOpen = true">
+			Team members
+		</BbButton>
+	</div>
+	<BbOffCanvas
+		v-model="listOpen"
+		side="right"
+		stack="team"
+		:stack-gap="72"
+		title="Team members"
+	>
+		<div class="grid gap-1">
+			<BbButton
+				v-for="member in members"
+				:key="member.name"
+				class="justify-start"
+				size="sm"
+				variant="ghost"
+				@click="openDetail(member)"
+			>
+				{{ member.name }}
+			</BbButton>
+		</div>
+	</BbOffCanvas>
+	<BbOffCanvas
+		v-model="detailOpen"
+		side="right"
+		stack="team"
+		:stack-gap="72"
+		:title="selected?.name"
+	>
+		<div v-if="selected" class="grid gap-2 text-sm">
+			<p class="m-0">
+				<span class="text-xs text-[color:var(--bb-text-muted)]">Role</span
+				><br />
+				{{ selected.role }}
+			</p>
+			<p class="m-0">
+				<span class="text-xs text-[color:var(--bb-text-muted)]">Joined</span
+				><br />
+				{{ selected.joined }}
+			</p>
+		</div>
+	</BbOffCanvas>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas } from 'bitboss-ui';
+
+type Member = { name: string; role: string; joined: string };
+
+const members: Member[] = [
+	{ name: 'Ada Lovelace', role: 'Lead engineer', joined: 'Mar 2021' },
+	{ name: 'Grace Hopper', role: 'Principal engineer', joined: 'Sep 2019' },
+];
+
+const listOpen = ref(false);
+const detailOpen = ref(false);
+const selected = ref<Member | null>(null);
+
+/** Push the detail drawer onto the shared stack. */
+const openDetail = (member: Member) => {
+	selected.value = member;
+	detailOpen.value = true;
 };
+</script>
+```
+
+### Fullscreen
+
+`fullscreen` expands the panel to fill the viewport (minus the standard page
+padding — it is intentionally not edge-to-edge), which suits content-heavy
+detail views. Pass `fullscreen="mobile"` to go fullscreen only below the mobile
+breakpoint (`config.mobileMaxWidth`, 768px) while keeping the sized panel on
+desktop — the usual choice for a `right` detail panel that should take the whole
+screen on a phone.
+
+**Fullscreen on mobile only**
 
-export type BbOffCanvasSlots = {
-	/**
-	 * Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
-	 */
-	header?: (props: BbOffCanvasHeaderSlotProps) => any;
-	/**
-	 * Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`.
-	 */
-	title?: (props: BbOffCanvasTitleSlotProps) => any;
-	/**
-	 * Replaces the default close icon rendered inside the header's close button.
-	 */
-	close?: (props: object) => any;
-	/**
-	 * Replaces the default accessible description block. The provided content is linked to the panel via `aria-describedby`.
-	 */
-	description?: (props: BbOffCanvasDescriptionSlotProps) => any;
-	/**
-	 * Primary body content of the off-canvas panel, rendered in the scrollable body area.
-	 */
-	default?: (props: object) => any;
-	/**
-	 * Content rendered in the panel footer, below the body area. Typically used for action buttons.
-	 */
-	footer?: (props: object) => any;
+```vue
+<div>
+	<BbButton variant="outline" @click="state.open = true">Open article</BbButton>
+	<BbOffCanvas
+		v-model="state.open"
+		side="right"
+		fullscreen="mobile"
+		size="md"
+		title="Release notes"
+	>
+		<p class="m-0 text-sm">
+			Sized (md) on desktop, full-screen below the mobile breakpoint.
+		</p>
+	</BbOffCanvas>
+</div>
+```
+
+### 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 panel 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 slide animation and when `hidden` fires — reopening during the
+close transition keeps the panel open instead of snapping shut.
+
+The classic `@show` job is reseeding a draft: reset the working copy from the
+last saved value every time the panel opens, so Cancel is a real discard —
+half-typed edits never survive a close.
+
+**Reseed a draft with @show**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="min-w-0">
+			<p class="m-0 text-sm font-medium">INV-2043</p>
+			<p class="m-0 truncate text-xs text-[color:var(--bb-text-muted)]">
+				{{ saved }}
+			</p>
+		</div>
+		<BbButton variant="outline" @click="open = true">Add note</BbButton>
+	</div>
+	<BbOffCanvas
+		v-model="open"
+		side="right"
+		title="Note · INV-2043"
+		@show="draft = saved"
+	>
+		<BbTextarea v-model="draft" auto-grow compact label="Internal note" />
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton variant="primary" @click="save">Save note</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas, BbTextarea } from 'bitboss-ui';
+
+const open = ref(false);
+const saved = ref('Customer asked to postpone pickup.');
+const draft = ref(saved.value);
+
+/** Persist the draft and dismiss the panel. */
+const save = () => {
+	saved.value = draft.value;
+	open.value = false;
 };
+</script>
 ```
 
-## Styles
-
-```css
-.bb-offcanvas {
-	--translate-x: 0%;
-	--translate-y: 0%;
-	--translate: 1;
-	--transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-	position: fixed;
-	transition:
-		max-width var(--transition-duration) var(--transition-timing-function),
-		max-height var(--transition-duration) var(--transition-timing-function),
-		translate var(--transition-duration) var(--transition-timing-function),
-		display var(--transition-duration) var(--transition-duration)
-			var(--transition-timing-function);
-	background-color: var(--bb-panel);
-	color: var(--bb-text);
-	display: flex;
-	flex-direction: column;
-	z-index: var(--bb-overlay-z-index);
-	overscroll-behavior: contain;
-	overflow: hidden;
-	outline: none;
-	transition-behavior: allow-discrete;
-	margin: 0 0;
-	translate: calc(var(--translate-x) * var(--translate))
-		calc(var(--translate-y) * var(--translate));
-
-	&.bb-offcanvas--left,
-	&.bb-offcanvas--right {
-		max-height: 100%;
-		max-width: var(--max-size);
-		width: 100%;
-		top: 0px;
-		height: 100%;
-	}
-	&.bb-offcanvas--left {
-		--translate-x: -100%;
-		left: 0px;
-	}
-	&.bb-offcanvas--right {
-		--translate-x: 100%;
-		right: 0px;
-		left: auto;
-	}
-	&.bb-offcanvas--top,
-	&.bb-offcanvas--bottom {
-		max-height: min(var(--max-size), 100%);
-		height: var(--max-size);
-		max-width: 100%;
-		width: 100%;
-		left: 0;
-		right: 0;
-	}
-	&.bb-offcanvas--top {
-		--translate-y: -100%;
-		top: 0px;
-		bottom: auto;
-	}
-	&.bb-offcanvas--bottom {
-		--translate-y: 100%;
-		bottom: 0px;
-		top: auto;
-	}
-
-	&.bb-offcanvas--fullscreen {
-		border-radius: 0;
-		width: 100%;
-		height: 100%;
-	}
-
-	&.bb-offcanvas--compact {
-		.bb-offcanvas__header {
-			border-bottom: none;
-		}
-		.bb-offcanvas__body {
-			padding-top: 0;
-		}
-	}
-
-	&.bb-offcanvas--open {
-		--translate: 0;
-
-		&::backdrop {
-			opacity: 1;
-
-			@starting-style {
-				opacity: 0;
-			}
-		}
-	}
-	&.bb-offcanvas--deny-close {
-		--translate: 0.1;
-	}
-
-	&:has(.bb-offcanvas.bb-offcanvas--open),
-	&:has(.bb-base-dialog.bb-base-dialog--open) {
-		--translate: 1;
-	}
-
-	&::backdrop {
-		background-color: color-mix(
-			in srgb,
-			var(--bb-overlay-color) calc(var(--bb-overlay-opacity) * 100%),
-			transparent
-		);
-		opacity: 0;
-		transition: opacity var(--transition-duration) cubic-bezier(0.4, 0, 0.2, 1);
-	}
-
-	.bb-offcanvas__header {
-		align-items: center;
-		border-bottom: 1px solid var(--bb-border);
-		column-gap: 12px;
-		display: flex;
-		justify-content: space-between;
-		padding: var(--bb-dialog-py) var(--bb-dialog-px);
-		flex-shrink: 0;
-
-		.bb-offcanvas__title {
-			font-size: var(--bb-dialog-title-size);
-			font-weight: var(--bb-dialog-title-weight);
-		}
-
-		.bb-offcanvas__close {
-			transition: color var(--transition-duration);
-			&:hover {
-				color: var(--bb-primary);
-			}
-
-			button {
-				border-radius: var(--bb-radius);
-				box-shadow: 0px 0px 0px 0px var(--bb-ring);
-				display: flex;
-				margin-right: -8px;
-				outline: 2px solid transparent;
-				outline-offset: 2px;
-				outline-style: none;
-				padding: 8px;
-				transition: box-shadow 0.2s;
-
-				&:focus-visible {
-					box-shadow: 0px 0px 0px var(--bb-ring-size) var(--bb-ring);
-				}
-			}
+### Controlling dismissal
 
-			.bb-offcanvas__close-icon {
-				display: inline-flex;
-				svg {
-					width: var(--bb-dialog-close);
-				}
-			}
-		}
-	}
-
-	.bb-offcanvas__body {
-		overflow: auto;
-		position: relative;
-		padding: var(--bb-dialog-py) calc(var(--bb-dialog-px) - var(--bb-ring-size))
-			calc(var(--bb-dialog-py) - var(--bb-ring-size));
-		flex: 1 1 auto;
-
-		.bb-offcanvas__body-content {
-			margin: 0 min(var(--bb-ring-size), var(--bb-dialog-px));
-		}
-	}
-
-	.bb-offcanvas__footer {
-		padding: var(--bb-dialog-py) var(--bb-dialog-px);
-		pointer-events: auto;
-
-		&:empty {
-			display: none;
-		}
-	}
-}
+Every dismissal path is governed by two props:
 
-body:has(.bb-offcanvas--open) {
-	overflow: hidden;
-	padding-right: var(--scrollbar-width);
-}
+- `persistent` — backdrop click, `Escape`, and a drag-to-dismiss no longer
+  close; the panel 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.
+
+Two more knobs shape the surface:
+
+- `hide-close` removes the header close button. (The close button is shown by
+  default.)
+- `focus-target` — a CSS selector resolved inside the panel — moves initial
+  focus to a specific element; otherwise the first tabbable element receives it.
+
+Constraint: the header **close (×) button bypasses `persistent`** (it is the
+documented escape hatch) but **respects `disabled`** — a busy panel cannot be
+dismissed mid-work. When a panel must be resolved from the footer, pair
+`persistent` with `hide-close` and keep a visible Cancel so users are never
+trapped. Backdrop clicks are also drag-protected: a text selection that starts
+inside the panel and releases over the backdrop does not close it — only a
+genuine click that starts and ends on the backdrop (≤4px travel) does.
+
+**Persistent — resolve from the footer**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="min-w-0">
+			<p class="m-0 text-sm font-medium">PR #1842</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				Needs a reviewer before merge
+			</p>
+		</div>
+		<BbButton variant="outline" @click="open = true">Assign reviewer</BbButton>
+	</div>
+	<BbOffCanvas
+		v-model="open"
+		focus-target="input"
+		hide-close
+		persistent
+		side="right"
+		title="Assign reviewer"
+	>
+		<div class="grid gap-3">
+			<BbTextInput
+				v-model="reviewer"
+				compact
+				label="Reviewer"
+				placeholder="Name or email"
+			/>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				Backdrop and Escape stay locked — resolve from the footer.
+			</p>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton variant="primary" @click="open = false">Assign</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
+
+const open = ref(false);
+const reviewer = ref('');
+</script>
 ```
+
+### Top layer: what's above, what's inert
+
+The panel is a native `<dialog>` opened with `showModal()` — the same mechanics
+`BbDialog` relies on, and worth designing around:
+
+- 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-offcanvas--open`) after `attachTo: document.body`.
+- Everything outside the panel is **inert** while it is open: no hover, click,
+  or tab reaches the page behind.
+- Later top-layer surfaces paint above earlier ones: a `BbSelect`, `BbPopover`,
+  `BbTooltip`, `BbConfirm`, or nested drawer opened from inside works with no
+  special wiring. `BbToast` regions re-home into the open panel so toasts fired
+  from a drawer stay clickable.
+
+### Works well with
+
+- `BbDialog` — the same content as a blocking modal when the task is focused
+  rather than supplementary; the shared API keeps the swap cheap.
+- `BbConfirm` + `useConfirm` — a destructive action inside a drawer should raise
+  a confirm on top, not a hand-built panel.
+- `BbToast` + `useToast` — fire the success toast right before closing; it stays
+  interactive above the panel.
+- `BbButton` `href` / `to` — a footer action that navigates should carry the
+  link, never an `@click` + `router.push`.
+
+### Gotchas & anti-patterns
+
+- **Don't rely on the close (x) button respecting `persistent`** — it doesn't
+  (though it does respect `disabled`); hide it (`hide-close`) when the panel
+  must be resolved explicitly, and keep a visible Cancel.
+- **Don't reach for `BbOffCanvas` for a focused, blocking task** — that is
+  `BbDialog`; use a drawer for content that sits beside the page.
+- **Don't confuse `size` with a width** — it is the panel's extent along its
+  axis (height for top/bottom drawers).
+- **Don't query panel content before it has opened** unless you set `eager` —
+  the body renders lazily.
+- **Don't toggle `v-model` from `@hide`/`@hidden`** to "cancel" a close — use
+  `persistent`; the close paths already guard correctly.
+- **Don't stack unrelated drawers** expecting them to peek — the peeking band
+  only appears for panels sharing a `stack` name and side.
+
+### Accessibility
+
+- Prefer passing `title`: it names the panel via `aria-labelledby`. Without a
+  header you own the accessible name — label a heading in the body and wire it
+  through the `header` slot's `titleId`.
+- The panel is a true modal (`showModal()`): focus is contained 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`).
+- Draggable dismissal is a convenience, not the only way out — the close button,
+  backdrop, and `Escape` all remain, so keyboard and assistive-tech users are
+  never stranded.
+- Don't lean on `persistent` to trap users. Keep a visible way out (a Cancel or
+  Close button) even when backdrop/`Escape`/drag dismissal is disabled.
+
+## v-model
+
+- `v-model` — type: `boolean \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `disabled` | `boolean \| undefined` |  |  | Disable EVERY user-initiated dismissal: backdrop click, Escape, drag-to-dismiss 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 drawer cannot be dismissed mi… |
+| `draggable` | `boolean \| undefined` | `false` |  | Enable drag-to-dismiss. The panel can be dragged from anywhere toward its edge to close, and a grab handle is shown on the inner edge as the affordance. When `false`, the panel is static (dismiss via the close button, backdrop, or Escape on… |
+| `eager` | `boolean \| undefined` |  |  | Render offcanvas 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 offcanvas fullscreen. Use `'mobile'` to restrict fullscreen to small devices. |
+| `hideClose` | `boolean \| undefined` |  |  | Hides the default close (×) button in the header (e.g. for a `persistent` drawer you don't want dismissible — the × otherwise still closes a persistent drawer). |
+| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the panel. A panel with no `v-model` starts closed. |
+| `persistent` | `boolean \| undefined` |  |  | Prevent closing via outside clicks, Escape key or drag-to-dismiss. The header close (×) button STILL closes a persistent drawer — that is the documented escape hatch; combine with `hideClose` to remove it, or use `disabled` to block every d… |
+| `side` | `"left" \| "right" \| "top" \| "bottom" \| undefined` | `"left"` |  | Which viewport edge the offcanvas docks to (and slides in from). |
+| `size` | `Responsive<OffCanvasSize> \| undefined` | `"sm"` |  | Controls the maximum size of the offcanvas panel. Accepts named presets from `'xs'` to `'2xl'`, `'auto'`, a custom CSS size string, or a numeric pixel value — or a per-breakpoint map (e.g. `{ default: 'sm', lg: 'lg' }`) to switch responsive… |
+| `stack` | `string \| undefined` |  |  | Name of the stack this drawer belongs to. Drawers sharing the same `stack` value step back behind one another as later ones open; drawers in different stacks never affect each other. When omitted, the drawer stacks with nothing. |
+| `stackGap` | `number \| undefined` | `60` |  | Pixels each stacked parent drawer shifts inward when a child opens on top, leaving a peeking band of the parent visible. |
+| `title` | `string \| undefined` |  |  | Title text announced to assistive technologies. If omitted, no header is rendered 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: `{ close: () => void; }` — Primary body content of the off-canvas panel, rendered in the scrollable body area.
+- `footer` — scope: `object` — Content rendered in the panel footer, below the body area. Typically used for action buttons.
+- `header` — scope: `BbOffCanvasHeaderSlotProps` — Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
+- `title` — scope: `BbOffCanvasTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`.
+
+## See Also
+
+- [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.