bitboss-ui 3.0.0-beta.45 → 3.0.0-beta.47

package/dist/ai/BbHoverCard.md

@@ -0,0 +1,515 @@
+# BbHoverCard
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Overlay**
+- Description: A rich preview card that opens on hover or keyboard focus (a person, an event, a link) — BbPopover's panel without the click; may hold commands that also exist elsewhere; also the v-bb-hover-card directive.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbHoverCard.md](./source/BbHoverCard.md)
+
+## Reachable through `BbHoverCard`
+
+`BbHoverCard` mounts other components (all of them: _Component tree_, near the end). These are the parts of its API that land inside them. Prefer these over `:deep()` on an inner class (a part's class is stable within 3.x, any other class is internal and can break on upgrade) — and never an import of an internal component.
+
+| pt part | Lands on | In |
+| --- | --- | --- |
+| `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
+| `pt:root` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbHoverCard` to **preview what a link or name points at** without
+leaving the page: a person behind a mention, an event in a calendar, a commit in
+an activity feed. It opens when the pointer rests on the activator (or keyboard
+focus lands on it), stays open while the pointer is over the card, and closes
+when the pointer leaves both.
+
+It is `BbPopover`'s panel with a different trigger: same placement, offset,
+width, header / footer bands, `scrollable`, `pt` parts and look. What differs
+is that nothing clicks it open, it never takes focus, and it is not a dialog.
+
+Pick a sibling when the shape is different:
+
+- One line of text that names or explains the control → `BbTooltip`.
+- Content the user works in (a form, a picker, settings) → `BbPopover`, which
+  opens on click and holds focus.
+- A list of actions → `BbDropdown`.
+
+**The rule that makes a hover card safe: everything in it must also be
+reachable another way.** A touch screen never shows it (there is no hover), and
+a screen-reader user in browse mode may never open it. The card is a shortcut
+and a preview, never the only path to a command or a fact.
+
+### Activator and content
+
+Render the activator in the `activator` slot and **spread its `props`** onto it.
+`props` carries the `id`, the positioning `ref`, the pointer / focus / keyboard
+listeners, and — once the card holds a control — `aria-expanded` /
+`aria-controls`. The activator must be focusable, so a keyboard user can open
+the card too: a link (`<a href>`) is the usual shape, since a hover card
+previews where the link goes. The `default`, `header` and `footer` slots get
+`close`, `open`, `placement` and `disabled`, exactly as `BbPopover`'s do.
+
+**A person behind a name**
+
+```vue
+<template>
+	<p class="max-w-md text-sm text-(--bb-text-muted)">
+		Deploy of
+		<span class="font-medium text-(--bb-text)">invoice-export</span>
+		approved by
+		<BbHoverCard placement="bottom-start" :width="280">
+			<template #activator="{ props }">
+				<a
+					v-bind="props"
+					class="font-medium text-(--bb-text) underline decoration-dotted underline-offset-2"
+					href="#profile-maria-bianchi"
+				>
+					{{ member.name }}
+				</a>
+			</template>
+			<div class="flex items-center gap-2.5">
+				<BbAvatar :alt="member.name" size="48" :src="member.src">
+					<span>{{ member.initials }}</span>
+				</BbAvatar>
+				<div class="min-w-0">
+					<div class="truncate text-sm font-medium text-(--bb-text)">
+						{{ member.name }}
+					</div>
+					<div class="truncate text-xs text-(--bb-text-muted)">
+						{{ member.role }}
+					</div>
+				</div>
+			</div>
+			<div class="mt-3 grid gap-1 text-xs text-(--bb-text-muted)">
+				<div class="flex items-center gap-1.5">
+					<BbIcon icon="lucide:map-pin" size="xs" />
+					<span>{{ member.location }}</span>
+				</div>
+				<div class="flex items-center gap-1.5">
+					<BbIcon icon="lucide:clock" size="xs" />
+					<span>{{ member.localTime }}</span>
+				</div>
+			</div>
+		</BbHoverCard>
+		2 hours ago.
+	</p>
+</template>
+
+<script setup lang="ts">
+import { BbAvatar, BbHoverCard, BbIcon } from 'bitboss-ui';
+// Each portrait is an inline SVG data URI, so the example loads nothing over
+// the network. Any image URL works here; swap in your own.
+const face = (bg: string, fg: string) =>
+	`data:image/svg+xml,${encodeURIComponent(
+		`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" fill="${bg}"/><circle cx="32" cy="25" r="11" fill="${fg}"/><path d="M11 64c1-13 10-20 21-20s20 7 21 20z" fill="${fg}"/></svg>`
+	)}`;
+
+const member = {
+	name: 'Maria Bianchi',
+	initials: 'MB',
+	role: 'Platform engineer · Infra',
+	location: 'Milan, Italy',
+	localTime: '16:42 local time',
+	src: face('#ffedd5', '#a24a12'),
+};
+</script>
+```
+
+### Commands in the card
+
+A card may hold shortcuts — "Open", "Reschedule", "Follow" — as long as each
+also exists elsewhere (the event page, the profile). With a control inside, the
+card becomes a group named after its activator, and the keyboard can reach it:
+**Tab** from the activator moves into the card, Tab past its last control moves
+on to whatever follows the activator (and closes the card), **Shift+Tab** from
+its first control goes back to the activator, and **Escape** closes it and puts
+focus back on the activator. Prefer `href` links for navigation; `@click` works
+too, and the slot's `close` dismisses the card from inside.
+
+**Calendar events with shortcuts**
+
+```vue
+<template>
+	<div class="grid max-w-xs gap-1.5">
+		<BbHoverCard
+			v-for="event in events"
+			:key="event.id"
+			:offset="8"
+			placement="right-start"
+			:width="260"
+		>
+			<template #activator="{ props }">
+				<a
+					v-bind="props"
+					class="block rounded-(--bb-radius) border-l-4 border-(--bb-primary) bg-(--bb-muted) px-2 py-1 text-sm text-(--bb-text)"
+					:href="`#event-${event.id}`"
+				>
+					{{ event.time }} · {{ event.title }}
+				</a>
+			</template>
+			<template #header>
+				<div class="text-sm font-medium">{{ event.title }}</div>
+				<div class="text-xs text-(--bb-text-muted)">
+					{{ event.day }}, {{ event.time }}–{{ event.end }}
+				</div>
+			</template>
+			<div class="grid gap-1 text-xs text-(--bb-text-muted)">
+				<div class="flex items-center gap-1.5">
+					<BbIcon icon="lucide:map-pin" size="xs" />
+					<span>{{ event.room }}</span>
+				</div>
+				<div class="flex items-center gap-1.5">
+					<BbIcon icon="lucide:users" size="xs" />
+					<span>{{ event.people }}</span>
+				</div>
+			</div>
+			<template #footer>
+				<!-- Shortcuts only: the event page offers both actions too. -->
+				<div class="flex gap-2">
+					<BbButton :href="`#event-${event.id}`" size="sm" variant="outline">
+						Open
+					</BbButton>
+					<BbButton
+						:href="`#event-${event.id}-reschedule`"
+						size="sm"
+						variant="ghost"
+					>
+						Reschedule
+					</BbButton>
+				</div>
+			</template>
+		</BbHoverCard>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BbButton, BbHoverCard, BbIcon } from 'bitboss-ui';
+
+const events = [
+	{
+		id: 'standup',
+		title: 'Team stand-up',
+		day: 'Tue 7 Oct',
+		time: '09:30',
+		end: '09:45',
+		room: 'Room Brera',
+		people: '6 people',
+	},
+	{
+		id: 'review',
+		title: 'Design review',
+		day: 'Tue 7 Oct',
+		time: '11:00',
+		end: '12:00',
+		room: 'Video call',
+		people: 'Ana, Luca, Maria',
+	},
+];
+</script>
+```
+
+### Timing and the safe zone
+
+`delay` (default `350` ms, the same prop name as `BbTooltip`'s) is how long the
+pointer has to rest on the activator before the card opens — long enough that a
+pointer passing over a list of names doesn't flash a card for each. Keyboard
+focus opens it after `delay` too. Closing has no prop: once the pointer has left
+both the activator and the card, the card waits a fixed 200 ms, the time the
+pointer needs to cross the gap into the card.
+
+Between the activator and the card there is a **safe zone**: the triangle from
+the point where the pointer left toward the card's corners. While the pointer
+moves inside it, the card stays open, so a diagonal path to a button in the
+card never closes it on the way. A pointer that stops there, or leaves it, lets
+those 200 ms run out.
+
+A click on the activator never toggles the card: the link does what links do.
+
+### Interaction: it gives way to what the user opened
+
+A hover card is something the pointer opened on its way past, so it gets out
+of the way of anything the user opened on purpose, with no prop to set:
+
+- **A press on the trigger closes it at once.** A click, or a right-click
+  that opens a context menu on the same row, closes the card with no close
+  delay.
+- **While a menu, popover, dialog, select or picker is open, cards on
+  triggers outside it don't open**, and an open one closes. A trigger inside
+  that overlay (a name in a dialog, a mention in a popover) still works.
+- **Nothing reopens by itself.** When the overlay closes, the next hover or
+  focus opens the card as usual.
+
+So a table row can carry both `v-bb-dropdown` (a right-click menu) and
+`v-bb-hover-card`: right-click and the card goes and the menu opens; move back
+over the row and no card covers the menu; close it and the next hover shows
+the card. The same holds for `BbTooltip` / `v-bb-tooltip`.
+
+### Placement, offset and width
+
+The same props as `BbPopover`, with the same defaults: `placement` (`bottom`,
+auto-flipping near an edge), `offset` (`4`), `padding` (`10`), `boundary`, and
+`width` in pixels or as a percentage of the activator. A hover card never has an
+arrow. `placement="cursor"` is `BbPopover`'s alone (it anchors at a click
+point).
+
+**Placement around the activator**
+
+```vue
+<div class="flex flex-wrap gap-4 text-sm">
+	<BbHoverCard
+		v-for="side in ['top', 'right', 'bottom', 'left']"
+		:key="side"
+		:placement="side"
+		:width="160"
+	>
+		<template #activator="{ props }">
+			<a v-bind="props" :href="`#${side}`" class="underline">{{ side }}</a>
+		</template>
+		Placed <strong>{{ side }}</strong>
+	</BbHoverCard>
+</div>
+```
+
+### One per row: `v-bb-hover-card`
+
+For a card on every row of a table, every event of a calendar or every mention
+in a feed, the directive keeps the page light: no component exists until the
+pointer or keyboard focus reaches the element, and it goes away again once the
+card has closed. A thousand rows with `v-bb-hover-card` cost what a thousand
+plain links cost; a thousand `<BbHoverCard>` components cost two thousand
+component instances before anyone hovers.
+
+A directive has no slot, so the card's body is a **portal**, as in
+`BbConfirm`:
+
+- **A named portal:** `v-bb-hover-card="'person-card'"` opens the
+  `<BbHoverCardPortal name="person-card">` declared once in the template. Mind
+  the inner quotes: the attribute value is an expression, so without them
+  `person-card` is `person` minus `card`, and nothing opens (`check` flags it).
+  The portal's slot gets `{ props, close }`.
+- **A component:** `v-bb-hover-card="PersonCard"` renders `PersonCard` in the
+  card. It can close the card with `emit('close')`.
+- **The object form** takes either one as `portal`, data for it as
+  `portalProps` (the named portal's `props`, or the component's real props),
+  and any `BbHoverCard` prop: `{ portal: 'person-card', portalProps: { person },
+width: 220 }`. The argument is the placement: `v-bb-hover-card:right`.
+
+The portal's content sees the page around it, as if it were written inline:
+a component portal injects from where the trigger is, a named portal from
+where its `<BbHoverCardPortal>` is declared.
+
+**A card per row, from the directive**
+
+```vue
+<template>
+	<ul class="grid max-w-xs gap-1 text-sm">
+		<li v-for="person in people" :key="person.id">
+			<!-- The inner quotes make it a name: "'person-card'". -->
+			<a
+				v-bb-hover-card:right="{
+					portal: 'person-card',
+					portalProps: { person },
+					width: 220,
+				}"
+				class="text-(--bb-text) underline decoration-dotted underline-offset-2"
+				:href="`#person-${person.id}`"
+			>
+				{{ person.name }}
+			</a>
+		</li>
+	</ul>
+
+	<!-- Declared once; renders only inside the card that opens. -->
+	<!-- Portal props are untyped (like BbConfirm's): name the shape with `as`. -->
+	<BbHoverCardPortal v-slot="{ props }" name="person-card">
+		<div class="grid gap-0.5">
+			<div class="font-medium text-(--bb-text)">
+				{{ (props.person as Person).name }}
+			</div>
+			<div class="text-xs text-(--bb-text-muted)">
+				{{ (props.person as Person).team }} ·
+				{{ (props.person as Person).city }}
+			</div>
+		</div>
+	</BbHoverCardPortal>
+</template>
+
+<script setup lang="ts">
+import { BbHoverCardPortal, vBbHoverCard } from 'bitboss-ui';
+
+type Person = { id: number; name: string; team: string; city: string };
+
+const people: Person[] = [
+	{ id: 1, name: 'Ana Ferreira', team: 'Payments', city: 'Lisbon' },
+	{ id: 2, name: 'Luca Romano', team: 'Search', city: 'Turin' },
+	{ id: 3, name: 'Maria Bianchi', team: 'Infra', city: 'Milan' },
+];
+</script>
+```
+
+### Lifecycle, v-model and lazy content
+
+- `show` / `shown` / `hide` / `hidden` fire at the same moments as
+  `BbPopover`'s. Focus never moves on open, so `shown` means only that the open
+  transition has run.
+- `v-model` reads and drives it: write `true` to open it from elsewhere (a
+  keyboard shortcut, a test) and `false` to close it.
+- Content is **lazy**: the body renders on the first open. Until then the
+  activator says nothing about the card, because the card doesn't know yet
+  whether it will hold a control. `eager` renders it up front.
+- `disabled` keeps it shut, and disabling an open card closes it — set it while
+  a drag or a resize runs over the activator.
+- It closes when the activator scrolls out of view, like `BbPopover`.
+
+### Restyling with passthrough
+
+The same parts as `BbPopover` minus the phone sheet: `root` (the floating
+element, where a `class` on the component lands), `panel` (the surface you
+see), `header`, `content`, `footer`. State: `open`.
+
+**pt:header — a commit preview**
+
+```vue
+<template>
+	<BbHoverCard
+		placement="bottom-start"
+		pt:content="text-xs leading-relaxed"
+		pt:header="bg-(--bb-muted) font-mono text-xs"
+		pt:panel="overflow-hidden"
+		:width="300"
+	>
+		<template #activator="{ props }">
+			<a
+				v-bind="props"
+				class="font-mono text-sm text-(--bb-text) underline decoration-dotted underline-offset-2"
+				href="#commit-4f780d9"
+			>
+				4f780d9
+			</a>
+		</template>
+		<template #header>4f780d9 · main</template>
+		Hover card allows commands, with the keyboard bridge.
+	</BbHoverCard>
+</template>
+
+<script setup lang="ts">
+import { BbHoverCard } from 'bitboss-ui';
+</script>
+```
+
+The full grammar is in the [passthrough guide](./guides/passthrough.md). A `pt`
+value written in `<script>` is typed as `BbHoverCardProps['pt']`.
+
+### Works well with
+
+- `BbAvatar`, `BbBadge`, `BbIcon` — the usual content of a person or record
+  preview.
+- `BbButton` with `href` — a shortcut in the footer band.
+- `BbTable` / `BbCalendar` rows — through `v-bb-hover-card`, one per row.
+
+### Gotchas & anti-patterns
+
+- **Don't put the only path to anything in a hover card.** Touch never shows
+  it. Every command and every fact in it must also exist on the page it links
+  to, or elsewhere on this one.
+- **Don't use it for a form or a picker** — the card closes when the pointer
+  wanders off. That is `BbPopover`.
+- **Don't use it for one line of text** — that is `BbTooltip`, which also
+  describes the activator to a screen reader.
+- **Don't put it on a non-focusable element** (a bare `<span>`) — keyboard users
+  could never open it. Use a link or a button.
+- **Don't open it from `@click`** — a click never toggles a hover card; bind
+  `v-model` if something else must open it.
+
+### Accessibility
+
+- **Semantics follow the content.** A read-only card has no role and adds
+  nothing to the activator: the activator's own name is what a screen reader
+  announces, and the card is a visual extra (it is not flattened into
+  `aria-describedby` the way `BbTooltip` is). A card that holds a control is a
+  `role="group"` named after its activator, and the activator carries
+  `aria-expanded` / `aria-controls`. The check runs once the card has rendered
+  on open, and again whenever its content changes while open.
+- Only keyboard focus (`:focus-visible`) opens it — not the focus a click
+  leaves behind. Focus never moves into the card on its own; Tab does that.
+- Escape closes the innermost open surface first: a hover card inside a dialog
+  closes before the dialog.
+- It is not modal: the page behind stays live, and the card is a
+  `popover="manual"` element in the top layer, not a `<dialog>`.
+
+## v-model
+
+- `v-model` — type: `boolean \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `content`, `footer`, `header`, `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbHoverCardProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `activator` | `ElementOrComponentRef \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and the hover / focus listeners are attached programmatically to the referenced element. |
+| `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the card within a bounding element. When provided, the card will not overflow this container's bounds (e.g. a sidebar). Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
+| `delay` | `number \| undefined` | `350` |  | The delay in milliseconds before the card is shown: how long the pointer rests on the activator, or keyboard focus stays on it. BbTooltip's name; a different default, because a card that opened on every pass of the pointer would be in the way. Closing has a fixed grace instead (see the guide § Timing and the safe zone). |
+| `disabled` | `boolean \| undefined` | `false` |  | Disables the component. Disabling an open card closes it. |
+| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `id` | `string \| undefined` |  |  | The activator's id (the card is `bbhc_<id>`, and is labelled by it once it holds a control). Generated when omitted. |
+| `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to open / close the card. A card with no `v-model` starts closed and is driven by hover and keyboard focus. |
+| `offset` | `number \| undefined` | `4` |  | 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` | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'top-start'` \| `'top-end'` \| `'right-start'` \| `'right-end'` \| `'bottom-start'` \| `'bottom-end'` \| `'left-start'` \| `'left-end'` | `"bottom"` |  | Position of the card relative to the activator. |
+| `scrollable` | `boolean \| undefined` | `false` |  | Caps the card height to the available viewport space and enables internal scrolling. |
+| `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds. |
+| `width` | `string \| number \| undefined` |  |  | Width of the card. Accepts pixels or percentage (relative to activator width). |
+
+## Passthrough parts and states
+
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
+
+| Part | What it is |
+| --- | --- |
+| `root` | The floating element — an invisible positioning wrapper; a `class` on the component lands here, and so does `role="group"` once the card holds a control. |
+| `panel` | The surface you see — the bordered box that paints the card and lays out its bands. |
+| `header` | The header band. |
+| `content` | The body band. |
+| `footer` | The footer band. |
+
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `open` | Component-wide: the card is open. |
+
+## Events
+
+- `hidden` — `(): void` — Emitted after the card is fully closed.
+- `hide` — `(): void` — Emitted as soon as the card starts to close (model becomes false).
+- `show` — `(): void` — Emitted as soon as the card starts to open (model becomes true).
+- `shown` — `(): void` — Emitted after the card is fully opened. Focus never moves on open.
+- `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.
+
+## Slots
+
+- `activator` — scope: `BbHoverCardActivatorSlotProps` `{ disabled: boolean; open: boolean; placement: Placement; props: { 'aria-expanded'?: boolean \| undefined; 'aria-controls'?: string \| undefined; id: string; ref: (reference: unknown) => void; onPointerenter: (event: PointerEvent) => void; onPointerleave: (event: PointerEvent) => void; onFocusin: (event: FocusEvent) => void; onFocusout: (event: FocusEvent) => void; onKeydown: (event: KeyboardEvent) => void; onPointerdown: (event: PointerEvent) => void; onContextmenu: (event: MouseEvent) => void; } }` — The element the card describes. Spread `props` onto it; it must be focusable (a link or a button) so a keyboard user can open the card too.
+- `default` — scope: `BbHoverCardDefaultSlotProps` `{ close: () => void; disabled: boolean; open: boolean; placement: Placement }` — The card body.
+- `footer` — scope: `BbHoverCardDefaultSlotProps` `{ close: () => void; disabled: boolean; open: boolean; placement: Placement }` — Content pinned to the bottom of the card, outside the scroll region.
+- `header` — scope: `BbHoverCardDefaultSlotProps` `{ close: () => void; disabled: boolean; open: boolean; placement: Placement }` — Content pinned to the top of the card, outside the scroll region.
+
+## Component tree
+
+`BbHoverCard` is not one component: rendering it mounts every component below, and each one is live inside it. **Read this before styling, theming or debugging `BbHoverCard`, and before concluding a part, a token or a behaviour does not exist** — it may live on a component further down. How to read it:
+
+- **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbHoverCard`. A pt part listed as landing there is set on `BbHoverCard` (`pt:<part>`).
+- **_public_** nodes are components with their own contract. `BbHoverCard` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbHoverCard`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
+- **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbHoverCard`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
+- Listed nodes are the ones `BbHoverCard`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is `manifest/components/BbHoverCard.tree.json`.
+
+- `BbHoverCard` _(this component)_ — its own template binds: `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `span.bb-hover-card__header`, `content` → `span.bb-hover-card__content`, `footer` → `span.bb-hover-card__footer`
+  - Also mounts `CommonPopover`
+
+## See Also
+
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).
+- [BbTooltip](./BbTooltip.md) — Displays contextual helper text on interaction.

package/dist/ai/BbHoverCardPortal.md

@@ -0,0 +1,29 @@
+# BbHoverCardPortal
+
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Overlay**
+- Description: Registers named slot content that `v-bb-hover-card="'name'"` (or `{ portal: 'name' }`) renders in the card; slot `{ props, close }`.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbHoverCardPortal.md](./source/BbHoverCardPortal.md)
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` |  | yes | The name a `v-bb-hover-card` passes as its value (`"'name'"`) or as `portal: 'name'`. |
+
+## Events
+
+- None.
+
+## Slots
+
+- `default` — scope: `DirectivePortalSlotProps` `{ props: Record<string, unknown>; close: () => void }` — The card's body. `props` is the directive's `portalProps`; `close` closes the card.
+
+## See Also
+
+- [BbHoverCard](./BbHoverCard.md) — A rich preview card that opens on hover or keyboard focus (a person, an event, a link) — BbPopover's panel without the click; may hold commands that also exist elsewhere; also the v-bb-hover-card directive.
+- [BbPopoverPortal](./BbPopoverPortal.md) — Registers named slot content that `v-bb-popover="'name'"` (or `{ portal: 'name' }`) renders in the popover; slot `{ props, close }`.
+- [BbConfirmPortal](./BbConfirmPortal.md) — Registers named slot content that confirm() renders via `portal`.

package/dist/ai/BbOffCanvas.md

@@ -216,7 +216,7 @@ header and footer stay pinned.
 			<div class="flex justify-end gap-2">
 				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
 				<BbButton
-					:disabled="!email.trim()"
+					:disabled="!email?.trim()"
 					variant="primary"
 					@click="open = false"
 				>
@@ -232,7 +232,7 @@ import { ref } from 'vue';
 import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const email = ref('');
+const email = ref<string | null>('');
 </script>
 ```
 
@@ -951,7 +951,7 @@ import { ref } from 'vue';
 import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
 
 const open = ref(false);
-const reviewer = ref('');
+const reviewer = ref<string | null>('');
 </script>
 ```
 
@@ -1268,4 +1268,4 @@ Set these on the element, or on a class you put on it, to retune this component
 ## See Also
 
 - [BbDialog](./BbDialog.md) — Presents modal dialogs for focused user interactions.
-- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).