bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbPopover.md

@@ -1,592 +1,629 @@
 # BbPopover
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Overlay**
+- Description: Anchors floating content to reference elements.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbPopover.md](./source/BbPopover.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbPopover` when you need a **small floating panel with interactive
+content** anchored to a trigger: a quick-settings form, a notifications list, a
+mini picker, an inline detail card. It opens on click and stays open — the user
+can click, type, and toggle inside it — dismissing only on an outside click or
+`Escape`.
+
+Pick a sibling when the shape is more specific:
+
+- A one-line non-interactive hint on hover/focus → `BbTooltip`. Richer field
+  help with links or actions still belongs in a popover (see below).
+- A standard list of actions (a menu) → `BbDropdown`.
+- A searchable option list bound to a value → `BbSelect` / `BbSelectPopover`.
+- A focused, page-blocking task → `BbDialog`; supplementary side content →
+  `BbOffCanvas`.
+
+`BbPopover` is a lightweight floating panel, **not** a blocking modal: it does
+not dim or lock the page, and an outside click dismisses it. If the surface must
+own the user's attention until resolved, that is `BbDialog`.
+
+### Activator and content
+
+Render your trigger in the `activator` slot and **spread its `props`** onto the
+element — that is the whole contract. `props` carries the accessibility
+attributes (`aria-expanded`, `aria-controls`, `aria-haspopup="dialog"`), the
+element `id`, the `disabled` state, the positioning `ref`, and the open/close
+handler for whichever `trigger` is active. Miss the spread and the popover has
+no anchor and no way to open.
+
+The `activator` slot scope also exposes `isOpen`, `placement` and `disabled` so
+the trigger can react (rotate a chevron, swap a label). The `default` slot
+receives `close` (plus `open`, `placement`, `disabled`) so controls inside can
+dismiss the panel.
+
+**Quick display settings**
 
 ```vue
 <template>
-	<slot
-		v-if="!hasExternalActivator"
-		name="activator"
-		v-bind="{
-			props: activatorProps,
-			disabled: !!disabled,
-			isOpen,
-			placement,
-		}"
-	/>
-
-	<CommonPopover
-		:id="popoverId"
-		ref="popoverRef"
-		v-model="isOpen"
-		:anchor="effectiveAnchor"
-		:aria-labelledby="hasOpenedOnce ? activatorId : undefined"
-		:arrow-padding="arrowPadding"
-		:boundary="boundary"
-		class="bb-popover"
-		:class="`bb-popover--${theme}`"
-		dialog
-		:eager="eager"
-		:offset="offset"
-		:hide-arrow="placement === 'cursor'"
-		:padding="padding"
-		:placement="placement === 'cursor' ? 'bottom-start' : placement"
-		:scrollable="scrollable"
-		:style="{ width: parsedWidth }"
-		:transition-duration="transitionDuration"
-		v-bind="$attrs"
+	<div
+		class="flex max-w-sm items-center justify-between gap-3 rounded-[var(--bb-radius)] border p-3"
 	>
-		<span class="bb-popover__content" :inert="!isOpen">
-			<BaseButton
-				v-if="showClose"
-				:aria-label="closeLabel || t('common.closeLabel').value"
-				class="bb-popover__close"
-				@click="close"
-			>
-				<svg
-					aria-hidden="true"
-					fill="none"
-					viewBox="0 0 24 24"
-					xmlns="http://www.w3.org/2000/svg"
+		<div class="min-w-0">
+			<p class="truncate text-sm font-medium">Invoices</p>
+			<p class="truncate text-xs text-gray-500">24 open · last synced 2m ago</p>
+		</div>
+		<BbPopover :width="240">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					prepend:icon="lucide:sliders-horizontal"
+					variant="outline"
 				>
-					<path
-						d="M23 23L1 1M23 1L1 23"
-						stroke="currentColor"
-						stroke-linecap="round"
-						stroke-width="2"
+					Display
+				</BbButton>
+			</template>
+			<template #default>
+				<div class="grid gap-3">
+					<BbSwitch v-model="compact" label="Compact rows" />
+					<BbSwitch v-model="avatars" label="Show avatars" />
+				</div>
+			</template>
+		</BbPopover>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbPopover, BbSwitch } from 'bitboss-ui';
+
+const compact = ref(true);
+const avatars = ref(false);
+</script>
+```
+
+### A mini-form popover
+
+The most common interactive popover is a small form that commits on save and
+uses the slot's `close` to dismiss. Keep the primary action gated on validity,
+keep Cancel always live, and close only after the write. This companion renames
+a record and closes itself on save via the `close` callback.
+
+**Rename in a popover**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center justify-between gap-2 rounded-[var(--bb-radius)] border p-3"
+	>
+		<div class="min-w-0">
+			<p class="truncate text-sm font-medium">{{ name }}</p>
+			<p class="truncate text-xs text-gray-500">Shared report · edited today</p>
+		</div>
+		<BbPopover :width="260">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Rename"
+					icon="lucide:pencil"
+					size="sm"
+					variant="ghost"
+				/>
+			</template>
+			<template #default="{ close }">
+				<form class="grid gap-3" @submit.prevent="() => save(close)">
+					<BbTextInput
+						v-model="draft"
+						compact
+						label="Name"
+						placeholder="Report name"
 					/>
-				</svg>
-			</BaseButton>
-			<slot
-				:close="close"
-				:disabled="!!disabled"
-				:open="isOpen"
-				:placement="placement"
-			/>
-		</span>
-	</CommonPopover>
+					<div class="flex justify-end gap-2">
+						<BbButton type="button" variant="ghost" @click="close">
+							Cancel
+						</BbButton>
+						<BbButton :disabled="!draft.trim()" type="submit" variant="primary">
+							Save
+						</BbButton>
+					</div>
+				</form>
+			</template>
+		</BbPopover>
+	</div>
 </template>
 
 <script setup lang="ts">
-import { computed, nextTick, ref, useTemplateRef, watch } from 'vue';
-import { useId } from '@/composables/useId';
-import { useElementSize, useIntersectionObserver } from '@vueuse/core';
-import { useLocale } from '@/composables/useLocale';
-import { useUntil } from '@/composables/useUntil';
-import BaseButton from '../BaseButton/BaseButton.vue';
-import CommonPopover from '../CommonPopover/CommonPopover.vue';
-import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
-import { parseWidthString } from '@/utilities/functions/parseWidthString';
-import type {
-	BbPopoverProps,
-	BbPopoverEvents,
-	BbPopoverSlots,
-	PopoverTrigger,
-} from './types';
-
-const props = withDefaults(defineProps<BbPopoverProps>(), {
-	arrowPadding: 10,
-	offset: 3,
-	padding: 10,
-	placement: 'bottom',
-	restoreFocus: true,
-	scrollable: false,
-	showClose: true,
-	theme: 'default',
-	transitionDuration: 300,
-	trigger: 'click',
-});
-
-const emit = defineEmits<BbPopoverEvents>();
-
-defineSlots<BbPopoverSlots>();
-
-defineOptions({ inheritAttrs: false });
-
-// --- Core state ---
-
-const { t } = useLocale();
-const { id } = useId();
-const activatorId = props.id ?? id.value;
-const popoverId = `bbp_${activatorId}`;
-
-const activatorEl = ref<HTMLElement>();
-const popoverRef = useTemplateRef('popoverRef');
-const popoverEl = computed(() => extractDomContainer(popoverRef.value));
-
-const isOpen = defineModel<boolean>({ default: false });
-const hasOpenedOnce = useUntil(isOpen);
-const hasExternalActivator = computed(() => props.activator != null);
-
-const triggers = computed(() => {
-	const raw = props.trigger;
-	return new Set(Array.isArray(raw) ? raw : [raw]);
-});
-
-const createVirtualElement = (x: number, y: number) => ({
-	getBoundingClientRect: () => ({
-		x,
-		y,
-		width: 0,
-		height: 0,
-		top: y,
-		left: x,
-		right: x,
-		bottom: y,
-		toJSON() {
-			return this;
-		},
-	}),
-});
-
-const cursorAnchor = ref<ReturnType<typeof createVirtualElement> | null>(null);
-
-const effectiveAnchor = computed(() =>
-	props.placement === 'cursor' && cursorAnchor.value
-		? cursorAnchor.value
-		: activatorEl.value
-);
-
-// --- Long-press (mobile equivalent of contextMenu) ---
-
-const LONG_PRESS_DELAY = 500;
-const LONG_PRESS_MOVE_THRESHOLD = 10;
-let longPressTimer: ReturnType<typeof setTimeout> | undefined;
-let longPressOrigin: { x: number; y: number } | null = null;
-let longPressTriggered = false;
-
-const clearLongPress = () => {
-	clearTimeout(longPressTimer);
-	longPressOrigin = null;
+import { ref } from 'vue';
+import { BbButton, BbPopover, BbTextInput } from 'bitboss-ui';
+
+const name = ref('Q3 report');
+const draft = ref(name.value);
+
+/** Commit the draft name, then dismiss via the slot `close`. */
+const save = (close: () => void) => {
+	const next = draft.value.trim();
+	if (!next) return;
+	name.value = next;
+	close();
 };
+</script>
+```
 
-// --- Activator management ---
+### An anchored profile card
 
-const setActivatorRef = (reference: unknown) => {
-	activatorEl.value = extractDomContainer(reference) ?? undefined;
-};
+The read-only counterpart is a **detail card** anchored to an identity — click a
+member's name in a comment or an activity feed and see who they are without
+leaving the page (the GitHub-hovercard pattern, click-triggered here because a
+popover opens on click). `placement="bottom-start"` aligns the card's edge with
+the name, and the panel is pure content: any navigation ("View profile") is an
+`href`, never an `@click`.
 
-const activatorProps = computed(() => {
-	const active = triggers.value;
-	return {
-		'aria-expanded': hasOpenedOnce.value ? isOpen.value : undefined,
-		'aria-controls': hasOpenedOnce.value ? popoverId : undefined,
-		'aria-haspopup': 'dialog' as const,
-		id: activatorId,
-		disabled: !!props.disabled,
-		ref: setActivatorRef,
-		...(active.has('click') ? { onClick: toggle } : {}),
-		...(active.has('contextMenu')
-			? {
-					onContextmenu: onContextMenu,
-					onPointerdown: onPointerDown,
-					onPointermove: onPointerMove,
-					onPointerup: onPointerUp,
-					onPointercancel: onPointerUp,
-				}
-			: {}),
-	};
-});
-
-// Sync external activator prop to internal ref
-watch(
-	() => props.activator,
-	(val) => {
-		if (val) setActivatorRef(val);
-	},
-	{ immediate: true }
-);
-
-// Attach trigger listeners for external activators
-watch(
-	[activatorEl, triggers] as const,
-	([el, active], _, onCleanup) => {
-		if (!el || !hasExternalActivator.value) return;
-
-		const removers: (() => void)[] = [];
-
-		if (active.has('click')) {
-			el.addEventListener('click', toggle);
-			removers.push(() => el.removeEventListener('click', toggle));
-		}
-
-		if (active.has('contextMenu')) {
-			el.addEventListener('contextmenu', onContextMenu);
-			el.addEventListener('pointerdown', onPointerDown);
-			el.addEventListener('pointermove', onPointerMove);
-			el.addEventListener('pointerup', onPointerUp);
-			el.addEventListener('pointercancel', onPointerUp);
-			removers.push(() => {
-				el.removeEventListener('contextmenu', onContextMenu);
-				el.removeEventListener('pointerdown', onPointerDown);
-				el.removeEventListener('pointermove', onPointerMove);
-				el.removeEventListener('pointerup', onPointerUp);
-				el.removeEventListener('pointercancel', onPointerUp);
-				clearLongPress();
-			});
-		}
-
-		el.setAttribute('aria-haspopup', 'dialog');
-
-		onCleanup(() => {
-			removers.forEach((fn) => fn());
-			el.removeAttribute('aria-expanded');
-			el.removeAttribute('aria-controls');
-			el.removeAttribute('aria-haspopup');
-		});
-	},
-	{ immediate: true }
-);
-
-// Sync aria-expanded for external activators
-watch(
-	[activatorEl, isOpen, hasOpenedOnce] as const,
-	([el, open, opened]) => {
-		if (!el || !hasExternalActivator.value || !opened) return;
-		el.setAttribute('id', activatorId);
-		el.setAttribute('aria-expanded', String(open));
-		el.setAttribute('aria-controls', popoverId);
-	},
-	{ immediate: true }
-);
-
-// Close when activator scrolls out of view
-useIntersectionObserver(
-	activatorEl,
-	([{ intersectionRatio }]) => {
-		if (intersectionRatio !== 1 && isOpen.value) close();
-	},
-	{ threshold: [0, 1] }
-);
-
-// --- Open / Close logic ---
-
-const onDocumentClick = (event: MouseEvent) => {
-	const target = event.target;
-	if (!(target instanceof Node)) return;
-
-	const isInsidePopover = popoverEl.value?.contains(target);
-	const isInsideActivator = activatorEl.value?.contains(target);
-
-	if (!isInsidePopover && !isInsideActivator) {
-		close();
-	}
-};
+**Member profile card**
 
-const onKeydown = (event: KeyboardEvent) => {
-	if (event.key === 'Escape') {
-		event.preventDefault();
-		close();
-	}
-};
+```vue
+<template>
+	<div
+		class="max-w-md rounded-[var(--bb-radius)] border p-3 text-sm text-gray-500"
+	>
+		Deploy of
+		<span class="font-medium text-[var(--bb-text)]">invoice-export</span>
+		approved by
+		<BbPopover placement="bottom-start" :width="280">
+			<template #activator="{ props }">
+				<BbBaseButton
+					v-bind="props"
+					class="font-medium text-inherit underline decoration-dotted underline-offset-2"
+				>
+					{{ member.name }}
+				</BbBaseButton>
+			</template>
+			<div class="grid gap-3">
+				<div class="flex items-center gap-2.5">
+					<BbAvatar :alt="member.name" size="xl">
+						<span>{{ member.initials }}</span>
+					</BbAvatar>
+					<div class="min-w-0">
+						<div class="truncate text-sm font-medium text-[var(--bb-text)]">
+							{{ member.name }}
+						</div>
+						<div class="truncate text-xs text-gray-500">{{ member.role }}</div>
+					</div>
+				</div>
+				<div class="grid gap-1 text-xs text-gray-500">
+					<div class="flex items-center gap-1.5">
+						<BbIcon icon="lucide:mail" size="xs" />
+						<span class="truncate">{{ member.email }}</span>
+					</div>
+					<div class="flex items-center gap-1.5">
+						<BbIcon icon="lucide:map-pin" size="xs" />
+						<span>{{ member.location }}</span>
+					</div>
+				</div>
+				<BbButton
+					class="w-full"
+					href="#profile-maria-bianchi"
+					prepend:icon="lucide:external-link"
+					variant="outline"
+				>
+					View profile
+				</BbButton>
+			</div>
+		</BbPopover>
+		2 hours ago.
+	</div>
+</template>
 
-const addGlobalListeners = () => {
-	document.addEventListener('click', onDocumentClick, { passive: true });
-	document.addEventListener('contextmenu', onDocumentClick, { passive: true });
-	document.addEventListener('keydown', onKeydown);
+<script setup lang="ts">
+import {
+	BbAvatar,
+	BbBaseButton,
+	BbButton,
+	BbIcon,
+	BbPopover,
+} from 'bitboss-ui';
+
+const member = {
+	name: 'Maria Bianchi',
+	initials: 'MB',
+	role: 'Platform engineer · Infra',
+	email: 'maria.bianchi@acme.dev',
+	location: 'Milan, Italy (UTC+2)',
 };
+</script>
+```
 
-const removeGlobalListeners = () => {
-	document.removeEventListener('click', onDocumentClick);
-	document.removeEventListener('contextmenu', onDocumentClick);
-	document.removeEventListener('keydown', onKeydown);
-};
+### Inline field help
+
+For a one-line non-interactive hint, prefer `BbTooltip`. Reach for a popover
+when the explanation needs room — a short paragraph plus a docs link, related
+actions, or anything the user might click. Pair an icon-only ghost activator
+(`aria-label` required) with the field it explains; keep the panel narrow and
+dismissible.
+
+**Field help with a docs link**
 
-const openPopover = async () => {
-	if (props.disabled) return;
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Invoice retention</p>
+			<p class="text-xs text-gray-500">
+				How long paid invoices stay searchable in the workspace.
+			</p>
+		</div>
+		<div class="flex items-end gap-1.5">
+			<BbTextInput
+				v-model="days"
+				class="min-w-0 flex-1"
+				compact
+				label="Retention period"
+			>
+				<template #suffix>days</template>
+			</BbTextInput>
+			<BbPopover placement="top-end" :width="260">
+				<template #activator="{ props }">
+					<BbButton
+						v-bind="props"
+						aria-label="About retention period"
+						class="shrink-0"
+						icon="lucide:circle-question-mark"
+						variant="ghost"
+					/>
+				</template>
+				<div class="grid gap-2 text-sm">
+					<p class="m-0 font-medium">Retention period</p>
+					<p class="m-0 text-xs text-gray-500">
+						Paid invoices older than this window are archived and drop out of
+						search. Drafts and unpaid invoices are never archived by retention.
+					</p>
+					<BbButton
+						class="justify-start"
+						href="#docs-retention"
+						prepend:icon="lucide:book-open"
+						size="sm"
+						variant="ghost"
+					>
+						Read the retention guide
+					</BbButton>
+				</div>
+			</BbPopover>
+		</div>
+	</div>
+</template>
 
-	isOpen.value = true;
-	addGlobalListeners();
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbPopover, BbTextInput } from 'bitboss-ui';
 
-	await nextTick();
+const days = ref('90');
+</script>
+```
 
-	const focusSelector =
-		props.focusTarget ??
-		(props.showClose
-			? '.bb-popover__close'
-			: '[tabindex]:not([tabindex="-1"]), button, a, input, select, textarea');
-	const focusTarget = popoverEl.value?.querySelector(focusSelector);
+### Placement, offset and boundary
 
-	if (focusTarget instanceof HTMLElement) {
-		focusTarget.focus();
-	}
+`placement` positions the panel around the activator — the `top` / `right` /
+`bottom` / `left` families, each with `-start` / `-end` alignment variants
+(e.g. `bottom-start`). It defaults to `bottom`. The panel **auto-flips** to stay
+in view near a viewport edge, so pick the placement that reads best in the
+common case and let it correct itself.
 
-	emit('shown');
-};
+Fine-tune the geometry with:
 
-const toggle = async (event: MouseEvent) => {
-	if (isOpen.value) {
-		close();
-		return;
-	}
-	if (longPressTriggered) {
-		longPressTriggered = false;
-		event.preventDefault();
-		event.stopPropagation();
-		return;
-	}
-	event.stopImmediatePropagation();
-	if (props.placement === 'cursor') {
-		cursorAnchor.value = createVirtualElement(event.clientX, event.clientY);
-	}
-	await openPopover();
-};
+- `offset` — gap (px) between the activator and the panel (default `3`).
+- `padding` — minimum gap (px) the panel keeps from the page edge (default
+  `10`).
+- `boundary` — an element, ref, or CSS selector that constrains the panel so it
+  never escapes a scrolling region or sidebar.
 
-const onContextMenu = (event: MouseEvent) => {
-	if (props.disabled) return;
-	event.preventDefault();
-	event.stopPropagation();
-	if (props.placement === 'cursor') {
-		cursorAnchor.value = createVirtualElement(event.clientX, event.clientY);
-		if (isOpen.value) return;
-	}
-	if (isOpen.value) close();
-	else openPopover();
-};
+`BbPopover` is a floating **panel**, not a speech bubble — it never renders an
+arrow. Reach for `BbTooltip` when you want an arrow pointing back at the trigger
+for a one-line, non-interactive hint.
 
-const onPointerDown = (event: PointerEvent) => {
-	if (props.disabled || event.pointerType === 'mouse') return;
-	longPressTriggered = false;
-	longPressOrigin = { x: event.clientX, y: event.clientY };
-	longPressTimer = setTimeout(() => {
-		longPressTriggered = true;
-		if (props.placement === 'cursor' && longPressOrigin) {
-			cursorAnchor.value = createVirtualElement(
-				longPressOrigin.x,
-				longPressOrigin.y
-			);
-		}
-		longPressOrigin = null;
-		openPopover();
-	}, LONG_PRESS_DELAY);
-};
+**Placement around the trigger**
 
-const onPointerMove = (event: PointerEvent) => {
-	if (!longPressOrigin) return;
-	const dx = event.clientX - longPressOrigin.x;
-	const dy = event.clientY - longPressOrigin.y;
-	if (Math.sqrt(dx * dx + dy * dy) > LONG_PRESS_MOVE_THRESHOLD) {
-		clearLongPress();
-	}
-};
+```vue
+<div class="flex flex-wrap gap-2">
+	<BbPopover
+		v-for="side in ['top', 'right', 'bottom', 'left']"
+		:key="side"
+		:placement="side"
+		:width="150"
+	>
+		<template #activator="{ props }">
+			<BbButton v-bind="props" variant="outline">{{ side }}</BbButton>
+		</template>
+		<div class="text-sm">Placed <strong>{{ side }}</strong></div>
+	</BbPopover>
+</div>
+```
 
-const onPointerUp = () => {
-	clearLongPress();
-};
+### Header, footer and scrollable content
+
+Tall content (a notifications feed, a long list) should set `scrollable`: it
+caps the panel to the available viewport height and scrolls the body internally.
+Pin a title in the `header` slot and actions in the `footer` slot — both stay
+put outside the scroll region, with their own padding and dividers, so you never
+need `sticky` hacks. This companion left-aligns its rows with the `justify-start`
+utility (BbButton centers labels by default).
 
-const close = () => {
-	if (!isOpen.value) return;
+**A notifications popover**
 
-	isOpen.value = false;
-	removeGlobalListeners();
+```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="truncate text-sm font-medium">Acme Studio</p>
+			<p class="truncate text-xs text-gray-500">Workspace · Billing</p>
+		</div>
+		<BbPopover scrollable :width="300">
+			<template #activator="{ props }">
+				<BbButton
+					v-bind="props"
+					aria-label="Notifications"
+					icon="lucide:bell"
+					size="sm"
+					variant="ghost"
+				/>
+			</template>
+			<template #header>
+				<strong class="text-sm">Notifications</strong>
+			</template>
+			<template #default="{ close }">
+				<div class="grid gap-1">
+					<BbButton
+						v-for="item in items"
+						:key="item.id"
+						class="justify-start"
+						:href="`#notification-${item.id}`"
+						size="sm"
+						:variant="item.read ? 'ghost' : 'secondary'"
+						@click="close"
+					>
+						{{ item.title }}
+					</BbButton>
+				</div>
+			</template>
+			<template #footer>
+				<div class="flex justify-end">
+					<BbButton
+						prepend:icon="lucide:check"
+						size="sm"
+						variant="ghost"
+						@click="markAllRead"
+					>
+						Mark all as read
+					</BbButton>
+				</div>
+			</template>
+		</BbPopover>
+	</div>
+</template>
 
-	if (props.restoreFocus && activatorEl.value) {
-		activatorEl.value.focus();
-	}
+<script setup lang="ts">
+import { reactive } from 'vue';
+import { BbButton, BbPopover } from 'bitboss-ui';
 
-	emit('hidden');
+type Notification = {
+	id: number;
+	title: string;
+	read: boolean;
 };
 
-// --- Width calculation ---
-
-const needsReactiveWidth = computed(() => {
-	if (!props.width) return false;
-	const { unit } = parseWidthString(props.width);
-	return unit === '%';
-});
-
-const { width: activatorWidth } = useElementSize(
-	computed(() => (needsReactiveWidth.value ? activatorEl.value : undefined)),
-	{ width: 0, height: 0 },
-	{ box: 'border-box' }
-);
-
-const parsedWidth = computed(() => {
-	if (!props.width) return undefined;
-
-	const { value, unit } = parseWidthString(props.width);
-	if (unit === '%' && activatorEl.value) {
-		return `${activatorWidth.value * (value / 100)}px`;
-	}
-	return `${value}px`;
-});
-
-// --- Public API ---
-
-defineExpose({
-	/** Opens the popover programmatically */
-	show: openPopover,
-	/** Closes the popover programmatically */
-	close,
-	/** Whether the popover is currently open */
-	isOpen: computed(() => isOpen.value),
-});
+const items = reactive<Notification[]>([
+	{ id: 1, title: 'Invoice #INV-2043 was paid', read: false },
+	{ id: 2, title: 'Maria commented on “Q3 report”', read: false },
+	{ id: 3, title: 'Your export is ready to download', read: true },
+]);
+
+const markAllRead = () => {
+	items.forEach((item) => (item.read = true));
+};
 </script>
+```
+
+### Triggers and cursor anchoring
 
-<style lang="postcss">
-@import './index.css';
-</style>
+`trigger` chooses the interaction: `'click'` (default), `'contextMenu'`
+(right-click on desktop, long-press on mobile), or an array to combine them.
+Pair `contextMenu` with `placement="cursor"` to anchor the panel at the pointer
+— a context surface for richer, interactive content. (For a plain list of
+actions, reach for `BbDropdown` instead.)
+
+**Right-click for a context panel**
+
+```vue
+<div class="max-w-sm">
+	<BbPopover placement="cursor" trigger="contextMenu" :width="200">
+		<template #activator="{ props }">
+			<button
+				v-bind="props"
+				type="button"
+				class="grid h-24 w-full place-items-center rounded-[var(--bb-radius)] border border-dashed text-sm text-gray-500"
+			>
+				Right-click anywhere here
+			</button>
+		</template>
+		<template #default="{ close }">
+			<div class="grid gap-1">
+				<BbButton class="justify-start" size="sm" variant="ghost" @click="close">Preview</BbButton>
+				<BbButton class="justify-start" href="#rename" size="sm" variant="ghost" @click="close">Rename</BbButton>
+			</div>
+		</template>
+	</BbPopover>
+</div>
 ```
 
-## Types
-
-```ts
-import type { CommonProps } from '@/types/CommonProps';
-
-export type PopoverTrigger = 'click' | 'contextMenu';
-
-export type BbPopoverProps = Pick<
-	CommonProps,
-	| 'arrowPadding'
-	| 'closeLabel'
-	| 'block'
-	| 'disabled'
-	| 'eager'
-	| 'id'
-	| 'offset'
-	| 'padding'
-	| 'showClose'
-	| 'theme'
-	| 'transitionDuration'
-> & {
-	/**
-	 * Position of the popover relative to the activator.
-	 * Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow).
-	 *
-	 * @defaultValue `'bottom'`
-	 */
-	placement?: CommonProps['placement'] | 'cursor';
-	/**
-	 * External activator element or component ref.
-	 * When provided, the activator slot is not rendered and click events
-	 * are attached programmatically to the referenced element.
-	 */
-	activator?: HTMLElement | Record<string, any> | null;
-	/**
-	 * Constrains the popover within a bounding element.
-	 * When provided, the popover will not overflow this container's bounds (e.g. a sidebar).
-	 * Accepts an HTMLElement, a Vue component ref, or a CSS selector string.
-	 */
-	boundary?: HTMLElement | Record<string, any> | string | null;
-	/**
-	 * Selector for the element that receives focus after opening.
-	 * Defaults to the close button, or first focusable element if no close button.
-	 */
-	focusTarget?: string;
-	/**
-	 * Whether to restore focus to the activator when closed.
-	 *
-	 * @defaultValue `true`
-	 */
-	restoreFocus?: boolean;
-	/**
-	 * Theme class applied to the popover container.
-	 *
-	 * @deprecated Use a CSS class on the component instead.
-	 * @defaultValue `'default'`
-	 */
-	theme?: string;
-	/**
-	 * Interaction(s) that open the popover.
-	 * Accepts a single trigger or an array to combine them.
-	 * - `'click'` — left-click / tap (default)
-	 * - `'contextMenu'` — right-click on desktop, long-press on mobile
-	 *
-	 * @defaultValue `'click'`
-	 */
-	trigger?: PopoverTrigger | PopoverTrigger[];
-	/**
-	 * Caps the popover height to the available viewport space and enables internal scrolling.
-	 *
-	 * @defaultValue `false`
-	 */
-	scrollable?: boolean;
-	/**
-	 * Width of the popover. Accepts pixels or percentage (relative to activator width).
-	 */
-	width?: number | string;
-};
+### External activator
 
-export type BbPopoverEvents = {
-	/** Emitted after the popover is fully opened and focus has been moved inside. */
-	(e: 'shown'): void;
-	/** Emitted after the popover is closed and focus has been restored to the activator. */
-	(e: 'hidden'): void;
-};
+When the trigger already exists elsewhere (a toolbar button, a table cell), pass
+it as the `activator` prop instead of using the slot — the listeners and ARIA
+are attached to that element directly, so you don't spread `props`. This needs a
+template ref, so it is a **static** snippet (a live fence has no `<script>` to
+declare the ref):
 
-/** Props exposed by the `activator` slot. */
-export type BbPopoverActivatorSlotProps = {
-	/** Accessibility and positioning attributes to spread onto the activator element. */
-	props: {
-		'aria-expanded'?: boolean;
-		'aria-controls'?: string;
-		'aria-haspopup': 'dialog';
-		id: string;
-		disabled: boolean;
-		ref: (reference: unknown) => void;
-	};
-	/** Whether the popover is globally disabled. */
-	disabled: boolean;
-	/** Whether the popover is currently open. */
-	isOpen: boolean;
-	/** The current placement of the popover panel. */
-	placement: BbPopoverProps['placement'];
-};
+```vue
+<template>
+	<BbButton ref="triggerRef" icon="lucide:settings">Options</BbButton>
+	<BbPopover :activator="triggerRef">
+		<div class="grid gap-1">
+			<BbSwitch v-model="notify" label="Email me" />
+		</div>
+	</BbPopover>
+</template>
 
-/** Props exposed by the `default` slot. */
-export type BbPopoverDefaultSlotProps = {
-	/** Programmatically closes the popover. */
-	close: () => void;
-	/** Whether the popover is globally disabled. */
-	disabled: boolean;
-	/** Whether the popover is currently open. */
-	open: boolean;
-	/** The current placement of the popover panel. */
-	placement: BbPopoverProps['placement'];
-};
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbPopover, BbSwitch } from 'bitboss-ui';
 
-export type BbPopoverSlots = {
-	/**
-	 * The element that triggers the popover to open. Spread `props` onto your trigger element.
-	 */
-	activator?: (props: BbPopoverActivatorSlotProps) => any;
-	/**
-	 * The popover body content rendered inside the floating panel.
-	 */
-	default?: (props: BbPopoverDefaultSlotProps) => any;
-};
+const triggerRef = ref();
+const notify = ref(true);
+</script>
 ```
 
-## Styles
-
-```css
-.bb-popover {
-	.bb-popover__content {
-		color: var(--bb-text);
-		display: block;
-		padding: 8px;
-		.bb-popover__close {
-			border-radius: var(--bb-radius);
-			float: right;
-			isolation: isolate;
-			/* margin-right pulls the button back by its own width (8px + 10px svg + 8px)
-			   so the float no longer contributes to the bubble's max-content width */
-			margin: calc(var(--bb-ring-size) * -1) -4px 0px
-				calc(var(--bb-ring-size) * -1 - 26px);
-			outline: none;
-			padding: 8px;
-			position: sticky;
-			top: 4px;
-			z-index: 1;
-
-			&:hover {
-				color: var(--bb-primary);
-			}
-
-			svg {
-				width: 10px;
-			}
-		}
-	}
-}
-```
+The `activator` prop accepts an `HTMLElement` or a component ref; BbPopover
+resolves the underlying element, wires `click` / `contextMenu` listeners, and
+sets `aria-haspopup` / `aria-expanded` / `aria-controls` on it.
+
+### Width and sizing
+
+`width` accepts pixels (`:width="240"`) or a percentage relative to the
+activator's width — `width="100%"` matches the trigger exactly, handy for
+select-like panels; only the `%` form tracks the activator on resize. With no
+`width` the panel sizes to its content. `scrollable` (above) is what bounds the
+height; without it a tall panel grows freely.
+
+### Lifecycle, focus and lazy content
+
+- Four lifecycle events fire, matching `BbDialog`/`BbOffCanvas`: `show` as the
+  panel starts opening and `shown` after it has opened and focus has moved inside;
+  `hide` as it starts closing and `hidden` after it has closed and focus has
+  returned to the activator.
+- Focus moves into the panel on open (first focusable element) and returns to
+  the activator on close; `focus-target` (a CSS selector) overrides where it
+  first lands.
+- Content is **lazy** — the body renders on first open. Set `eager` to render it
+  up front (pre-measure a chart, let tests query it closed).
+- `transition-duration` (ms) times the open/close animation.
+- For imperative open/close, use `v-model`: write `true` to open and `false` to
+  close, and the popover writes it back on every dismiss (outside click, Escape,
+  backdrop) — the self-correcting two-way model `BbDialog`/`BbOffCanvas` use.
+  There is no template-ref `show()`/`close()` API; the boolean model is it.
+
+### Top layer: escaping overflow and z-index
+
+The floating panel opens in the browser **top layer** (a native `<dialog>`), so
+it paints above every `z-index`, sticky header, `overflow: hidden` clip, or
+transformed ancestor — there is nothing to z-index-manage, and a popover inside
+a scrolling card or table cell is not clipped by it. A popover, select, or
+tooltip opened from **inside** a `BbDialog` / `BbOffCanvas` also layers correctly
+above that surface with no extra wiring. In tests, query the panel via
+`document.body` (the open panel carries both classes on one element —
+`.bb-popover.bb-common-popover--open`) after `attachTo: document.body`.
+
+The popover closes automatically if its activator scrolls out of view — it is
+tethered to the trigger, not left floating over the page.
+
+### Adaptive: a bottom sheet on mobile
+
+By default (`config.adaptive`, `true` out of the box) a popover opened on a small
+viewport (below `config.mobileMaxWidth`, 768px) renders as a bottom-anchored,
+draggable `BbOffCanvas` sheet instead of a floating panel — better ergonomics
+for thumbs. The surface is **latched when the popover opens** and stays fixed for
+that session, so a mid-session resize never swaps panel ↔ sheet.
+
+- The `header`, `default`, and `footer` slots carry over to the sheet unchanged.
+- `width` is **ignored** in sheet mode (a sheet sizes itself); tune the sheet
+  with `off-canvas-props` (merged over the defaults `direction: 'bottom'`,
+  `size: 'auto'`, `draggable: true`).
+- `:adaptive="false"` keeps the floating panel everywhere; a bare `adaptive`
+  forces the sheet 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
+
+- `BbButton` — the natural activator; spread the slot `props` onto it.
+- `BbSwitch`, `BbCheckbox`, `BbTextInput` — the interactive controls a popover
+  exists to hold; wire the `default` slot's `close` to commit-and-dismiss.
+- `BbDialog` / `BbOffCanvas` — a popover opened from inside either layers above
+  it correctly; reach for those instead when the content is a full task.
+- `BbDropdown` — when the panel is really just a menu of actions, use the
+  dropdown; a popover is for interactive content.
+
+### Gotchas & anti-patterns
+
+- **Don't forget to spread `props`** onto the activator (or pass an `activator`
+  ref) — without it there is no anchor, no ARIA, and no open handler.
+- **Don't put a blocking task in a popover** — it doesn't lock the page and
+  dismisses on outside click; use `BbDialog`.
+- **Don't reach for a popover when you mean a menu** — a plain list of actions is
+  `BbDropdown`.
+- **Don't set `width` and expect it on mobile** — the adaptive sheet ignores it;
+  size the sheet with `off-canvas-props`.
+- **Don't query popover content before first open** unless `eager` — the body is
+  lazy.
+- **Don't hand-roll cursor positioning** — `placement="cursor"` anchors at the
+  pointer for you.
+
+### Accessibility
+
+- Always spread the `activator` slot's `props` onto your trigger (or pass an
+  `activator`); that is what publishes `aria-expanded` / `aria-controls` /
+  `aria-haspopup` and makes the trigger operable by keyboard.
+- Focus moves into the panel on open and returns to the activator on close;
+  `focus-target` overrides where it lands first.
+- The popover is a floating panel, not a modal — it does not trap focus or lock
+  the page behind it. For a blocking task, use `BbDialog`.
+- Give an icon-only activator its own `aria-label`; the popover does not name it.
+
+## v-model
+
+- `v-model` — type: `boolean \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and click events are attached programmatically to the referenced element. |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | On mobile viewports (below `config.mobileMaxWidth`), render the popover as a bottom-anchored, auto-sized off-canvas sheet instead of a floating panel. The `header`, `default` and `footer` slots are forwarded to the sheet. The `width` prop i… |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. When provided, the popover will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `eager` | `boolean \| undefined` |  |  | Prevents rendering content before it's made visible. |
+| `focusTarget` | `string \| undefined` |  |  | Selector for the element that receives focus after opening. Defaults to the first focusable element inside the popover. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `modelValue` | `boolean \| undefined` | `false` |  |  |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Overrides forwarded to the underlying `BbOffCanvas` when `adaptive` renders the sheet on mobile. Merged over the adaptive defaults (`direction: 'bottom'`, `size: 'auto'`, `draggable: true`). Ignored when `adaptive` is `false`. |
+| `offset` | `number \| undefined` | `3` |  | Space the floating container will maintain from the activator. |
+| `padding` | `number \| undefined` | `10` |  | Minimum empty space to keep from the edge of the page. |
+| `placement` | `Placement \| "cursor" \| undefined` | `"bottom"` |  | Position of the popover relative to the activator. Use `'cursor'` to anchor at the mouse/touch coordinates (hides arrow). |
+| `scrollable` | `boolean \| undefined` | `false` |  | Caps the popover height to the available viewport space and enables internal scrolling. Useful for tall content like filter panels. Not recommended for atomic popovers (calendars, color pickers). |
+| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | How long the transition has to last in milliseconds. |
+| `trigger` | `PopoverTrigger \| PopoverTrigger[] \| undefined` | `"click"` |  | Interaction(s) that open the popover. Accepts a single trigger or an array to combine them. - `'click'` — left-click / tap (default) - `'contextMenu'` — right-click on desktop, long-press on mobile |
+| `width` | `string \| number \| undefined` |  |  | Width of the popover. Accepts pixels or percentage (relative to activator width). |
+
+## 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
+
+- `activator` — scope: `BbPopoverActivatorSlotProps` — The element that triggers the popover to open. Spread `props` onto your trigger element.
+- `default` — scope: `BbPopoverDefaultSlotProps` — The popover body content rendered inside the floating panel.
+- `footer` — scope: `BbPopoverDefaultSlotProps` — Content pinned to the bottom of the panel, outside the scroll region. Stays visible while the body scrolls (when `scrollable`) and carries its own padding and top divider, so footer actions need no negative-margin or `sticky` workarounds.
+- `header` — scope: `BbPopoverDefaultSlotProps` — Content pinned to the top of the panel, outside the scroll region. Stays visible while the body scrolls (when `scrollable`) and carries its own padding and bottom divider, so a title or search field needs no negative-margin or `sticky` work…
+
+## See Also
+
+- [BbTooltip](./BbTooltip.md) — Displays contextual helper text on interaction.
+- [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
+- [BbDropdown](./BbDropdown.md) — Displays contextual action menus and menu content.