bitboss-ui 3.0.0-beta.46 → 3.0.0-beta.48

package/README.md

@@ -57,7 +57,7 @@ Full detail: `dist/ai/guides/installation-and-plugin-setup.md`.
 
 ### Directives
 
-`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime` — plus a
+`vBbTooltip`, `vBbDropdown`, `vBbColor`, `vBbDate`, `vBbTime`, `vBbHoverCard`, `vBbPopover` — plus a
 `Bb*DirectivePlugin` for each, for app-level registration. Prefer the directive
 over the component for simple no-slot cases.
 
@@ -79,7 +79,7 @@ Product-ready components with labels, hints, errors, and consistent styling:
 - **Forms & actions:** `BbTextInput`, `BbTextarea`, `BbNumberInput`, `BbSelect`, `BbSelectPopover`, `BbCheckbox`, `BbCheckboxGroup`, `BbRadio`, `BbRadioGroup`, `BbSwitch`, `BbSwitchGroup`, `BbSlider`, `BbRating`, `BbColorInput`, `BbColorPalette`, `BbCalendar`, `BbDatePicker`, `BbDatePickerInput`, `BbTimePicker`, `BbTimePickerInput`, `BbButton`, `BbBadge`, `BbBadgeButton`, `BbIndicator`, `BbTag`, `BbDropdown`, `BbDropdownGroup`, `BbDropdownButton`, `BbAsterisk`
 - **Feedback:** `BbAlert`, `BbProgress`, `BbSpinner`, `BbToast`, `BbToastPortal`, `BbTooltip`
 - **Layout & navigation:** `BbAccordion`, `BbCollapsible`, `BbTabs` (+ `BbTabsRoot`, `BbTabsList`, `BbTabsPanels`), `BbBreadcrumbs`, `BbPagination`, `BbSmoothHeight`
-- **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`
+- **Overlays & panels:** `BbDialog`, `BbConfirm`, `BbConfirmPortal`, `BbOffCanvas`, `BbPopover`, `BbHoverCard`
 - **Data:** `BbTable`, `BbTree`
 - **Media & files:** `BbAvatar`, `BbDropzone`, `BbIcon`
 - **Forms** (`BbForm` needs the `vee-validate` peer; an app without forms needs nothing): `BbForm`, `useBbFormContext`, and the 16 form controls join the form they are inside (plus `rules` / `validation-label` / `validation-mode` / `formless`; the field's path is its `name`, else its label).

package/bin/bitboss-ui-mcp.mjs

@@ -1188,7 +1188,11 @@ function getComponent({
 		// A directive (`v-bb-tooltip`, `vBbTooltip`) — review D3-13.
 		const directiveName = String(name ?? '')
 			.trim()
-			.replace(/^vBb([A-Z]\w*)$/, (_, word) => `v-bb-${word.toLowerCase()}`)
+			.replace(
+				/^vBb([A-Z]\w*)$/,
+				// `vBbHoverCard` → `v-bb-hover-card`, the registered name.
+				(_, word) => `v-bb-${word.replace(/(?<!^)([A-Z])/g, '-$1')}`
+			)
 			.toLowerCase();
 		const directive = (manifest.directives ?? []).find(
 			(d) => d.name === directiveName

package/bin/bitboss-ui.mjs

@@ -77,6 +77,12 @@ import {
 } from '../scripts/lib/local-components.mjs';
 import { applyBitbossFixes } from '../scripts/lib/check-fix.mjs';
 import { stringControlsFor } from '../scripts/lib/text-null-value.mjs';
+import { projectResolution } from '../scripts/lib/unimported-components.mjs';
+import {
+	MAY_HAVE_PORTALS,
+	portalFindings,
+	projectPortalIndex,
+} from '../scripts/lib/portal-names.mjs';
 import { cssClassFindings } from '../scripts/lib/css-class-check.mjs';
 import {
 	cssLocalFindings,
@@ -1049,6 +1055,8 @@ async function checkCommand(
 					...validateOptions,
 					// The app's null-value policy, from the project bitboss-ui.d.ts.
 					stringControls: stringControlsFor(file),
+					// Q61.19: what the project registers globally.
+					unimported: { project: projectResolution(projectRoot) },
 				});
 		// Q46.9: a finding the author silenced for ESLint (`eslint-disable*`,
 		// usually with a reason) is silenced here too, or `check` cannot gate
@@ -1080,9 +1088,47 @@ async function checkCommand(
 		}
 	}
 
+	// Q63.8: portal names, judged against the whole project's declarations
+	// and call sites (scripts too: `confirm({ portal })` lives there). A full
+	// run reads every source file; explicit paths / `--changed`, only those.
+	// Markdown fences are never read: a doc names portals it never declares.
+	{
+		const portalIndex = projectPortalIndex(projectRoot);
+		const PORTAL_SOURCE = /\.(?:vue|[cm]?[jt]sx?)$/;
+		const TEST_FILE = /\.(?:test|spec)(?:-d)?\.[cm]?[jt]sx?$/;
+		const portalScope = (
+			changed ? changed.all : globs.length ? files : projectSources
+		).filter(
+			(path) =>
+				PORTAL_SOURCE.test(path) &&
+				!path.endsWith('.d.ts') &&
+				!TEST_FILE.test(path)
+		);
+		for (const path of portalScope) {
+			let content;
+			try {
+				content = readText(path);
+			} catch {
+				continue;
+			}
+			if (!MAY_HAVE_PORTALS.test(content)) continue;
+			const isDisabled = disabledChecker(content);
+			for (const finding of portalFindings(content, path, portalIndex)) {
+				if (isDisabled(finding.line, ruleForFinding(finding))) {
+					suppressed++;
+					continue;
+				}
+				const entry = { file: relative(projectRoot, path), ...finding };
+				if (finding.severity === 'warning') warnings.push(entry);
+				else findings.push(entry);
+			}
+		}
+	}
+
 	for (const [name, file] of projectLocal) warnLocal(name, file);
-	// Q60.6: a `vue-tsc` below 3 and a missing `checkUnknownComponents`, read
-	// from package.json and the tsconfig. One line each, never fatal.
+	// Q60.6: a `vue-tsc` below 3, read from package.json. One line, never
+	// fatal. (A missing `checkUnknownComponents` is no longer warned about:
+	// `unimported-component` covers it, Q61.19.)
 	warnings.push(...toolchainWarnings(projectRoot));
 
 	// Q25: a hand import of `bitboss-ui/styles.css` while the runtime plugin
@@ -1393,12 +1439,26 @@ Commands:
                       \`duplicate-field-identity\` (two validated fields in
                       one \`BbForm\` on the same path: the same \`name\`,
                       or the same label with no \`name\`),
+                      \`unimported-component\` (a \`.vue\` file uses a
+                      bitboss-ui tag it never imports and the project never
+                      registers globally: it renders as an empty element),
                       \`reactive-v-model\` (a \`v-model\` on a \`<script
                       setup>\` \`const x = reactive(…)\`: a production build
                       rejects the write-back; hold it in a \`ref()\`),
                       \`form-v-model\` (\`v-model\`, \`:model-value\` or an
                       \`@update:model-value\` listener on a \`BbForm\`: it
                       takes its object one way, \`:model="draft"\`),
+                      \`bare-portal-name\` (\`v-bb-popover="user-card"\` /
+                      \`v-bb-hover-card="user-card"\` without the inner
+                      quotes: an expression, not a portal name; write
+                      \`"'user-card'"\`),
+                      \`unknown-portal\` (\`v-bb-hover-card\` /
+                      \`v-bb-popover\` / \`confirm()\` names a portal no
+                      \`<…Portal name>\` in the project declares; did-you-mean
+                      in the message), \`portal-family-mismatch\` (a
+                      hover-card portal opened by \`v-bb-popover\`, or the
+                      other way round; literal names only, a \`:name\`
+                      binding or a non-literal call site is never judged),
                       \`positional-provider\` (an \`items\` provider with
                       positional arguments: it receives one object,
                       \`({ query, reason, modelValue, signal })\`),
@@ -1459,12 +1519,11 @@ Commands:
                       component uses the \`Bb\` prefix; rename it),
                       \`single-reason\` (an \`items\` provider that tests
                       \`reason\` against one cause other than \`'search'\`;
-                      check \`reason !== 'search'\`), \`vue-tsc-major\`
+                      check \`reason !== 'search'\`), \`unused-portal\` (a
+                      \`<…Portal name>\` nothing opens: no call site and the
+                      name in no string of the project), \`vue-tsc-major\`
                       (\`vue-tsc\` below 3 in package.json: the generic
-                      components' props go unchecked),
-                      \`check-unknown-components\` (no
-                      \`vueCompilerOptions.checkUnknownComponents: true\` in
-                      the tsconfig; \`ai-init\` writes it).
+                      components' props go unchecked).
   changelog [--since <version>] [--until <version>] [--json]
                       Breaking changes between two releases — "what breaks if I
                       bump". \`--since\` is the version you are ON, and is

package/dist/ai/BbAccordion.md

@@ -39,7 +39,8 @@ Step down the ladder when the composed header doesn't fit:
   **`BbSmoothHeight`** (`./BbSmoothHeight.md`).
 
 The public surface is small on purpose: `v-model` (boolean), `eager`,
-`transition-duration`, `id`, two slots, and the `update:modelValue` event.
+`transition-duration`, `id`, `heading-level`, two slots, and the
+`update:modelValue` event.
 Everything else is composition.
 
 ### Composing an FAQ
@@ -489,6 +490,25 @@ references): the body region gets your id and the header gets `<id>_header`,
 already cross-wired via `aria-controls`/`aria-labelledby`. Omitted, a unique id
 is generated for you.
 
+### Headers in the page outline
+
+Set `heading-level` when the accordion's headers are section titles a screen
+reader user should find by jumping between headings: an FAQ, a settings page's
+sections. The header button then sits inside `<h1>`–`<h6>` (the APG accordion
+shape), named after your header text. Match the page outline: under an `<h2>`
+the panels take `3`, never a level picked for its size, because the heading
+looks the same at every level (its margins and font are reset). Leave it out
+for accordions inside a form, a card or a side panel, where the headers are
+controls, not titles.
+
+```vue
+<h2>Billing questions</h2>
+<BbAccordion v-model="open" :heading-level="3">
+	<template #header>Can I change plans?</template>
+	Yes, at any time.
+</BbAccordion>
+```
+
 ### Restyling with passthrough
 
 `pt` reaches a named part with a class list — or, in the object form, a
@@ -606,7 +626,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 - The header is a real `button` with `aria-expanded`/`aria-controls`; the body
   is a `role="region"` labelled by the header via `aria-labelledby`. You add
   nothing — and you must not wrap the header slot in another interactive
-  element.
+  element. `heading-level` puts the button inside a heading (above); never wrap
+  the accordion in your own `<hN>` instead.
 - Keyboard comes free with the native button: Tab to the header, Enter/Space
   toggles. Closed content is `inert`, so it can never be tabbed into.
 - Provide a visible, meaningful header label; the chevron is decorative (mark
@@ -622,7 +643,8 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | 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: `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 `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the content at mount, while closed, instead of on the first open. Closed content is `inert` and `aria-hidden` either way. |
+| `headingLevel` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Wraps the header button in a heading of this level (`<h1>`–`<h6>`), the APG accordion shape, so the header joins the page's outline. Match the level to where the accordion sits (a section under an `<h2>` takes `3`). No visual change: the heading's margins and font are reset. Omitted, there is no heading. |
 | `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

package/dist/ai/BbButton.md

@@ -494,6 +494,11 @@ const activeView = ref<IssueView>('list');
 </script>
 ```
 
+A toggle that is on carries `aria-pressed="true"` and the class
+`bb-button--pressed`. Restyle that state with `pt:root:pressed` (or
+`pt:icon:pressed`, `pt:text:pressed`), not with a selector of your own: it is
+the state's contract.
+
 Listen to `update:modelValue` only if you need side effects; state itself is
 handled. For form-ish multi-selection prefer `BbCheckboxGroup` /
 `BbRadioGroup`; toggle buttons are for immediate, tool-bar-like state.
@@ -835,8 +840,11 @@ label span). Typography inherits from `root`, so reach for `text` only when a
 class must apply to the label ALONE — `truncate` on a long label that must not
 clip the icons beside it. That span also carries the margin the label slides by
 while the spinner is in, so a margin of your own fights the slide. States:
-`loading`, `disabled`. A name outside that list is a type error and an ESLint
-error.
+`loading`, `disabled`, `pressed` (a `v-model` toggle that is on). A name
+outside that list is a type error and an ESLint error. There is no `active`
+state: a pointer press is Tailwind's `active:` variant (`pt:root="active:scale-95"`).
+There is no `current` state either: a link to the current route is
+`active-class` / `exact-active-class` (see Active state above).
 
 **pt: a part, a part while loading, the object form**
 
@@ -1090,7 +1098,7 @@ Anti-patterns:
 
 | 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: `icon`, `root`, `spinner`, `text`. States: `disabled`, `loading`. 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 `BbButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `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: `icon`, `root`, `spinner`, `text`. States: `disabled`, `loading`, `pressed`. 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 `BbButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` | `'page'` |  | Value passed to the attribute `aria-current` when the link is exact active. |
@@ -1160,6 +1168,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `pressed` | Component-wide: a toggle button (`v-model`) is on — `aria-pressed="true"`, `--pressed` on the root. |
 | `disabled` | Component-wide: the button is `disabled`. |
 | `loading` | Component-wide: `loading` is on — the spinner shows and the button ignores the pointer. |
 

package/dist/ai/BbCalendar.md

@@ -493,11 +493,22 @@ const isOpen = (date: string) => !closed.has(date);
 </style>
 ```
 
+### The first day of the week
+
+The grid's week starts on the active locale's day, from the dayjs pack the
+plugin bundled: Monday for `it`, `de`, `fr`, `es` or `en-gb`, Sunday for bare
+`en` (US English) and `pt` (Brazil), and Sunday for a locale with no pack. The
+weekday headers follow, and so does a locale switch at runtime. Pass
+`first-day-of-week` (`0` = Sunday … `6` = Saturday) when the app's week is not
+its language's — an `en` app for a European audience takes
+`:first-day-of-week="1"`. `BbDatePicker` and `BbDatePickerInput` take the same
+prop and the same default.
+
 ### Keyboard and accessibility
 
 The calendar is an ordinary control in the tab order: **one tab stop** lands
 on the day under the cursor (the value, or today), arrows move by day and
-week, Home / End jump to the week's ends, PageUp / PageDown page by month
+week, Home / End jump to the ends of the grid's row, PageUp / PageDown page by month
 (with Shift, by year), typing a day number jumps to it, Enter or Space picks.
 The grid is a `role="grid"` of `role="row"` / `gridcell` nodes; a picked day
 carries `aria-selected` and says "selected" in its name, a pending range
@@ -580,7 +591,7 @@ the page is `BbDatePicker`.
 | `activeSegment` | `'start'` \| `'end'` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables every cell, the navigation and the time rail. |
-| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | First day of the week (0 = Sunday … 6 = Saturday). |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. With `datetime`, on its own day the time rail disables the times after it. |
 | `min` | `string \| undefined` |  |  | Minimum selectable value, in this `type`'s shape — `YYYY-MM-DD` (`YYYY-MM-DDTHH:mm` with `datetime`, `YYYY-MM` with `month`, `YYYY` with `year`). A finer bound is accepted and floored to the unit, with a warning. With `datetime`, the grid disables the days before it and, on its own day, the time rail disables the times before it. |

package/dist/ai/BbCollapsible.md

@@ -525,7 +525,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | 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`, `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 `BbCollapsibleProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the content at mount, while closed, instead of on the first open. Closed content is `inert` and `aria-hidden` either way. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. Optional, matching the runtime: `withDefaults` supplies `false`, so an omitted binding renders closed and Vue never warns. It was typed required while carrying that default, which made the manifest publish a row that was `required: true` AND `default: false` — a contradiction that read as a generator bug. |
 | `tag` | `'div'` \| `'span'` | `"span"` |  | Element rendered as the root, and mirrored by the inner animating element — so the pair is span-in-span or div-in-div, both valid. Keep the default inside phrasing content (a `<p>`); use `'div'` when the body is block content (paragraphs, lists, forms), which a `span` may not contain. |
 | `transitionDuration` | `number \| undefined` | `250` |  | How long the transition has to last in milliseconds |

package/dist/ai/BbColorPalette.md

@@ -760,7 +760,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `boundary` | `ElementOrComponentRefOrSelector \| undefined` |  |  | Constrains the popover within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disable all interaction (activator and palette). |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the palette panel at mount instead of on the first open (the phone sheet's too). |
 | `eyeDropper` | `boolean \| undefined` | `false` |  | Show an eyedropper button inside the palette to sample any color on screen. Uses the native EyeDropper API — hidden automatically on unsupported browsers. |
 | `label` | `string \| undefined` |  |  | Accessible label. The activator is named by it followed by the activator's own text, through `aria-labelledby`. Defaults to the locale string for "Open color picker" when omitted. |
 | `modelValue` | `string \| null` |  | yes | v-model: the current color as a `#RRGGBB` hex string (or `#RRGGBBAA` when `alpha` is enabled), or `null` when empty. |
@@ -827,4 +827,4 @@ Set these on the element, or on a class you put on it, to retune this component
 ## See Also
 
 - [BbColorInput](./BbColorInput.md) — Captures color values through input controls.
-- [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).

package/dist/ai/BbConfirm.md

@@ -654,6 +654,14 @@ const removeMember = async () => {
 When the portal owns its own action buttons, pass `actions: false` to hide the
 standard footer and resolve from inside the slot with its `yes` / `no` helpers.
 
+**Names are checked.** `bitboss-ui check` and the ESLint rule
+`bitboss-ui/portal-names` (in `recommended`) read every literal
+`confirm({ portal: 'name' })` in your scripts against the
+`<BbConfirmPortal name>`s in your templates: a name no file declares fails,
+with a did-you-mean, and `bitboss-ui/unused-portal` warns on a portal nothing
+opens. A `portal` held in a variable, or `confirm(options)`, is never judged.
+The slot's `props` is `any` per key, so `props.member.name` needs no cast.
+
 ### Size, fullscreen and focus
 
 - `size` picks a maximum-width preset (`'xs'` … `'2xl'`, resolvable through

package/dist/ai/BbConfirmPortal.md

@@ -20,7 +20,7 @@
 
 ## Slots
 
-- `default` — scope: `{ yes: () => void; no: () => void; props: Record<string, unknown>; }`
+- `default` — scope: `BbConfirmPortalSlotProps` `{ props: P; yes: () => void; no: () => void }`
 
 ## See Also
 

package/dist/ai/BbDatePicker.md

@@ -420,7 +420,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the activator and the calendar. |
 | `disableFlip` | `boolean \| undefined` | `false` |  | Disable the automatic flip to the opposite side on overflow. |
 | `eager` | `boolean \| undefined` | `false` |  | Render popover content before it is first shown. |
-| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `1` |  | First day of the week (0 = Sunday … 6 = Saturday). |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | Emit plain calendar strings instead of zoned ISO instants. Implied (and forced) by `type="month"` and `type="year"`. |
 | `label` | `string \| undefined` |  |  | Accessible label. The activator is named by it followed by the activator's own text ("Due date 12 Sep"), through `aria-labelledby`. |
 | `max` | `string \| undefined` |  |  | Maximum selectable value, in this `type`'s shape. A finer bound is accepted and ceiled to the unit, with a warning. |
@@ -542,4 +542,4 @@ Set these on the element, or on a class you put on it, to retune this component
 - [BbCalendar](./BbCalendar.md) — A calendar in place — the month grid (or month / year grid, or day grid plus time rail) with no popover and no field chrome; v-model of a day, range, set, month, year or datetime.
 - [BbDatePickerInput](./BbDatePickerInput.md) — Combines date selection with text input behavior.
 - [BbColorPalette](./BbColorPalette.md) — Opens an anchored popover color palette for color picking 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).

package/dist/ai/BbDatePickerInput.md

@@ -213,8 +213,10 @@ to catch config mistakes early — always pass the `YYYY-MM-DD` shape.
 
 For non-contiguous rules (no weekends, no holidays, only in-stock slots), pass a
 `selectable` predicate: it receives each date string and returns `false` to
-disable that day. `firstDayOfWeek` shifts the calendar grid (`0` = Sunday …
-`6` = Saturday).
+disable that day. The grid's week starts on the locale's day (Monday for
+`it` or `de`, Sunday for bare `en` and `pt`); `firstDayOfWeek` pins it
+(`0` = Sunday … `6` = Saturday) when the app's week differs from its
+language's.
 
 The example below combines a rolling `min`/`max` window, a weekdays-only
 predicate, `floating` output, and the `day:append` slot to dot specific days.
@@ -872,7 +874,7 @@ label>')` matches nothing; query each segment by its own label instead. See
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component. |
 | `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` | `false` |  | Disables typing into the input. Use `'mobile'` to disable typing only on mobile, `'desktop'` to disable typing only on desktop. |
 | `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby`, so the reason the field is invalid is re-read whenever the control regains focus. |
-| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` |  |  | Defines the first day of the week with `0` meaning Sunday and `6` meaning Saturday. |
+| `firstDayOfWeek` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| undefined` | `the locale's week start` |  | First day of the week (0 = Sunday … 6 = Saturday). Omitted, the active locale's week start: Monday for `it`, `de`, `fr`, `en-gb`…, Sunday for bare `en` (US) and `pt` (Brazil). |
 | `floating` | `boolean \| undefined` | `false` |  | If true the date will have a format YYYY-MM-DD instead of the default ISO string. |
 | `formless` | `boolean \| undefined` | `false` |  | Keep this control out of the enclosing `BbForm` entirely: not submitted, not dirty, not reset, not validated. For a control that is not form data (a filter, a "show advanced" switch). |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |

package/dist/ai/BbDialog.md

@@ -1214,4 +1214,4 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - [BbOffCanvas](./BbOffCanvas.md) — Shows side-panel overlay content outside normal layout flow.
 - [BbConfirm](./BbConfirm.md) — Prompts users to confirm or cancel critical actions (includes co-located BbConfirmPortal export).
-- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements; also the v-bb-popover directive (its body is a BbPopoverPortal or a component).

package/dist/ai/BbDropdown.md

@@ -1661,6 +1661,18 @@ listeners attach to the referenced element. ARIA — `aria-haspopup`,
 too, the same as it would to the slot's `props`; don't hand-write your own
 `aria-*` attributes on it, or you get a double-set conflict.)
 
+**One per row is fine, even thousands.** Until someone presses, focuses or
+right-clicks the element, the directive builds no component: the element
+carries `aria-haspopup` / `aria-expanded` itself, and a handful of listeners on
+`document` serve every sleeping menu. A menu of plain action rows (no
+selectable group, no fetched `items`) goes back to sleep once it has closed, or
+when focus leaves an element whose menu never opened, so only the open menu
+is ever a component. Measured on 3,000 elements: mount and re-render cost
+about the same as the bare elements. Two things opt a binding out: `eager`, and
+an explicit `id` (it must stay resolvable by `useBbDropdownContext(id)`). Each
+then mounts a full `BbDropdown` (about 1 ms per element), so leave both off on
+long lists.
+
 **Menu on any element, no wrapper**
 
 ```vue
@@ -2146,7 +2158,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the dropdown within a bounding element. Accepts an HTMLElement, a Vue component ref, or a CSS selector string. |
 | `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch target in a way a select option is not quite — a mis-tap fires the neighbouring COMMAND rather than picking the wrong value — so the compact sheet stops at 36px and never follows the flyout down to 24px. That is the same floor the select's sheet holds. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too). |
 | `emptyText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group resolves to no items. A group's own `emptyText` overrides this; both fall back to the localized `common.emptyText` (`'No data to display'`). |
 | `enforceCoherence` | `boolean \| undefined` | `false` |  | Default for pipeline groups: drop selections that are no longer present in a group's current items (e.g. after a `dependencies` re-fetch) from the selection and `v-model`. A group's own `enforceCoherence` overrides this. |
 | `failedText` | `string \| undefined` |  |  | Default placeholder text shown when a pipeline group's latest load FAILED (its `items` getter threw). A group's own `failedText` overrides this; both fall back to the localized `common.failedText` (`"Couldn't load items"`). |
@@ -2249,5 +2261,5 @@ Set these on the element, or on a class you put on it, to retune this component
 
 - [BbDropdownButton](./BbDropdownButton.md) — A button with primary action and all other actions collected in a dropdown.
 - [BbButton](./BbButton.md) — Button with loading state, tooltip, and icon support.
-- [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).
 - [BbBaseButton](./BbBaseButton.md) — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.

package/dist/ai/BbDropdownButton.md

@@ -637,7 +637,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `compact` | `boolean \| undefined` | `false` |  | Apply the compact density variant — the same ladder `BbSelect` uses, on both surfaces: flyout rows go 28px → 24px, sheet rows 44px → 36px. The label size does not change; density here is height, as it is for a select. A menu row is a touch target in a way a select option is not quite — a mis-tap fires the neighbouring COMMAND rather than picking the wrong value — so the compact sheet stops at 36px and never follows the flyout down to 24px. That is the same floor the select's sheet holds. |
 | `disableAutoLoading` | `boolean \| undefined` | `false` |  | Disables the automatic loading state that tracks async actions (enabled by default). Only affects the main action button: the split toggle half still mirrors the dropdown's internal async-action loading state. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the component |
-| `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
+| `eager` | `boolean \| undefined` | `false` |  | Renders the menu panel at mount instead of on the first open (the phone sheet's too). |
 | `id` | `string \| undefined` |  |  | Names this dropdown: the activator's id (unless it already has one), the menu's `menu_<id>`, and the key `useBbDropdownContext(id)` and a companion `BbDropdownGroup` pair by. Generated when omitted. |
 | `items` | `BbDropdownItem[]` | `[]` | yes | Array used to render each dropdown button. They can act as `button`, as `a`, or as `router-link` as they are based on the functionality provided by `BbBaseButton`. Pass a flat array for a single group, nest arrays for divider-separated groups, or pass {@link InternalGroup} objects for titled / selectable sections. An item may carry its own `items` to open a submenu. The shapes can be mixed. |
 | `loading` | `boolean \| undefined` | `false` |  | Triggers a loading indicator. |