bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.65

package/dist/ai/source/BbDropdown.md

@@ -153,7 +153,11 @@ import {
 	FULLY_VISIBLE,
 	settlesVisible,
 } from '@/utilities/functions/settlesVisible';
-import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import {
+	domElement,
+	extractDomContainer,
+	type DomHost,
+} from '@/utilities/functions/extractDomContainer';
 import { useElementSize, useIntersectionObserver } from '@vueuse/core';
 import { parseWidthString } from '@/utilities/functions/parseWidthString';
 import { levelHasSearch, normalizeGroups } from './normalizeGroups';
@@ -178,7 +182,7 @@ import type {
 	DropdownTrigger,
 } from './types';
 import { BB_DROPDOWN_PT } from './types';
-import { usePassthrough } from '@/composables/usePassthrough';
+import { usePassthrough, variantPt } from '@/composables/usePassthrough';
 import { withoutClass } from '@/utils/passthrough';
 import type { Ref } from 'vue';
 import { transitions } from '@/utilities/misc/transitions';
@@ -186,6 +190,8 @@ import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 
 defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_DROPDOWN_PT)],
 	inheritAttrs: false,
 });
 const props = withDefaults(defineProps<BbDropdownProps>(), {
@@ -194,6 +200,8 @@ const props = withDefaults(defineProps<BbDropdownProps>(), {
 	// reach the config default, while keeping the Boolean type so the valueless
 	// `<Dropdown adaptive>` shorthand still resolves to `true`.
 	adaptive: undefined,
+	// Three-state as well: unset closes after a single-choice change only.
+	closeOnSelect: undefined,
 	placement: 'bottom',
 	transitionDuration: transitions.fast,
 	trigger: 'click',
@@ -214,6 +222,8 @@ const passthrough = usePassthrough({
 	parts: BB_DROPDOWN_PT.parts,
 	states: BB_DROPDOWN_PT.states,
 	active: { open: () => open.value },
+	// Per entry: each row passes its own variant to `part()`.
+	variant: BB_DROPDOWN_PT.variant,
 });
 const config = useConfig();
 export type {
@@ -231,7 +241,7 @@ if (process.env.NODE_ENV !== 'production')
  * themselves regardless of click/contextmenu `stopPropagation`.
  */
 const DROPDOWN_OPEN_EVENT = 'bb-dropdown:open';
-type PeerOpenDetail = { surfaceId: string; activator: HTMLElement | undefined };
+type PeerOpenDetail = { surfaceId: string; activator: DomHost | undefined };
 
 const logger = useLogger();
 
@@ -247,7 +257,7 @@ const escapeKey = Symbol('bb-dropdown-escape');
  * a user-owned element (e.g. via a directive) never clobbers its id.
  */
 const activatorId = ref(id);
-const activator = ref<HTMLElement>();
+const activator = ref<DomHost>();
 const activatorDom = computed(() => extractDomContainer(activator.value));
 const hasExternalActivator = computed(() => props.activator != null);
 const open = ref(false);
@@ -426,7 +436,7 @@ const setActivatorRef = (reference: unknown) => {
 let ignoreNextIntersection = false;
 
 const { resume, pause } = useIntersectionObserver(
-	activatorDom,
+	() => domElement(activatorDom.value),
 	async ([{ intersectionRatio }]) => {
 		if (ignoreNextIntersection) {
 			ignoreNextIntersection = false;
@@ -1039,18 +1049,14 @@ useBbDropdownContextHost(() => props.id, {
 	groups: () => contextGroups.value,
 });
 
-const selectableGroupCount = computed(
-	() => renderGroups.value.filter((group) => group.selectable).length
-);
-
 /**
  * Toggles `item` in `group` (passed by the panel, so nested-submenu groups work
  * too). Single-select groups are radios: they keep one row, and re-clicking the
  * selected item keeps it — unless the group is `clearable`, when the re-click
  * clears it (Q47.2, owner 2026-09-22). Multi-select groups toggle. Emits
  * `item:selected`/`item:unselected` per changed item (none for a no-op
- * re-click), and closes the menu when a pick is made in a *top-level* sole
- * single-select group — re-picking the same value included.
+ * re-click), and closes the menu as `closeOnSelect` says (unset: a change in
+ * a single-select group, at any depth, re-picking the same value included).
  *
  * A CONTROLLED group (Q47.6) is not written: the pick goes to its companion as
  * a request in values (`update:modelValue`, then the group's `item:*`), and the
@@ -1104,18 +1110,18 @@ const toggleSelect = (group: NormalizedGroup, item: KeyedItem) => {
 		else if (controlled) emit('item:unselected', appValueFor(groupId, key));
 	});
 
-	// Radio-like sole top-level selectable group: close once a selection is made.
-	const isTopLevelSole =
-		selectableGroupCount.value === 1 &&
-		renderGroups.value.some((g) => g.selectable && g.id === groupId);
-	// A re-click that kept the pick is a pick of the same value: close too.
+	// ATT-03: a selection closes the menu — unset `closeOnSelect`, a change in
+	// a single-choice group (an untick included), wherever it sits; `true`,
+	// every change; `false`, never. A re-click that kept the pick is a pick of
+	// the same value: it closes too.
 	const picked =
 		added.length > 0 ||
+		removed.length > 0 ||
 		(prev.includes(item.rowKey) && next.includes(item.rowKey));
-	if (picked && !group.multiple && isTopLevelSole) {
-		closeDropdown();
-		focusActivator();
-	}
+	if (picked && (props.closeOnSelect ?? !group.multiple))
+		// Through the close, not beside it: the list puts focus back on the
+		// clicked row after this returns, which the closing panel then drops.
+		void closeAndRefocus();
 };
 
 // --- async action loading state (owned by the dropdown) -----------------
@@ -1252,6 +1258,7 @@ provideDropdownContext({
 	},
 	close: () => closeDropdown(),
 	focusActivator,
+	ownsEscape: () => isTopEscapeEntry(escapeKey),
 	openModality: () => openModality,
 	toggleSelect,
 	isItemLoading,
@@ -1446,11 +1453,23 @@ const onPeerOpen = (event: Event) => {
 	closeDropdown();
 };
 
+/** Whether focus sits in one of this menu's submenu surfaces (any depth). */
+const focusInSubmenu = () => {
+	const surface = document.activeElement?.closest('[data-bb-dropdown-surface]');
+	return (
+		surface?.getAttribute('data-bb-dropdown-surface') === id &&
+		!!surface.closest('.bb-dropdown--submenu')
+	);
+};
+
 const onEsc = (event: KeyboardEvent) => {
 	if (!open.value || event.key !== 'Escape') return;
 	// Something opened on top of this menu (a popover or modal launched from an
 	// item, say) — it owns Escape until it closes.
 	if (!isTopEscapeEntry(escapeKey)) return;
+	// Focus inside a submenu: Escape closes that level only (APG menu), so it
+	// goes on to the submenu surface's own handler (`BbDropdownList`).
+	if (focusInSubmenu()) return;
 
 	event.stopImmediatePropagation();
 	event.preventDefault();
@@ -1640,7 +1659,7 @@ const reservesCheckSpace = computed(() => props.width === 'auto');
 // would otherwise fire on every layout of its host (a menu button per row of
 // a virtualized table is one observer per mounted row).
 const { width: anchorWidth } = useElementSize(
-	computed(() => (open.value ? anchorDom.value : null)),
+	computed(() => domElement(open.value ? anchorDom.value : null)),
 	{ width: 0, height: 0 },
 	{
 		box: 'border-box',
@@ -1682,10 +1701,16 @@ import type {
 	PtItemMap,
 	PtItemResult,
 	PtValue,
+	PtVariantAttrs,
 } from '@/types/passthrough';
 import type { Placement } from '@/types/Placement';
 import type { IconType } from '@/types/Icon';
-import type { DropdownItemVariantType } from '@/types/DropdownItemVariant';
+import {
+	DROPDOWN_ITEM_VARIANTS,
+	type DropdownItemVariantBuiltIn,
+	type DropdownItemVariantRegistry,
+	type DropdownItemVariantType,
+} from '@/types/DropdownItemVariant';
 import type { BbOffCanvasProps } from '../BbOffCanvas/types';
 import type { ItemProps } from '@/types/ItemProps';
 import type { BbDropdownGroupItemsContext } from '@/types/ItemsProvider';
@@ -2068,8 +2093,18 @@ export type InternalGroup = DropdownEntryBase & {
 	/** Placeholder for this group's search field. Defaults to the localized label. */
 	searchPlaceholder?: string;
 	/**
-	 * When set, items act as selectable options that render a check on the right
-	 * and keep the menu open when toggled.
+	 * Sorts the group's rows under titled sections, inside the one group (one
+	 * `v-model`, one search field): a field path read off each row (a fetched
+	 * row: its raw item) or a getter returning the section title. Rows with a
+	 * nullish title are listed without a heading. Sections keep the order in
+	 * which their first row appears, like `BbSelect`'s `groupBy`; a search hides
+	 * a section with no matching row.
+	 */
+	groupBy?: string | ((row: any) => string | null | undefined);
+	/**
+	 * When set, items act as selectable options that render a check on the right.
+	 * A change closes the menu in a single-choice group and keeps it open in a
+	 * `multiple` one; the dropdown's `closeOnSelect` decides otherwise.
 	 *
 	 * Pass a function `(item) => boolean` to gate individual rows — the same
 	 * contract as `BbSelect` and the option groups. The group is still a
@@ -2201,6 +2236,8 @@ export type NormalizedGroup = {
 	searchable?: boolean;
 	/** Placeholder for this group's search field. */
 	searchPlaceholder?: string;
+	/** Section title per row (see {@link InternalGroup.groupBy}). */
+	groupBy?: InternalGroup['groupBy'];
 	selectable: boolean;
 	/** Selected row keys (`rowKey`; injected by `BbDropdown`; empty for non-selectable groups). */
 	selected: string[];
@@ -2226,7 +2263,7 @@ export type MappedItem = InternalItem & {
  * Passthrough parts of `BbDropdown` (plans/passthrough/BbDropdown.md). Groups,
  * headings and dividers are not parts.
  *
- * Per-item functions: on the instance, an entry part (`item`, `itemText`, `itemIcon`, `itemDescription`) also accepts `({ item, selected, … }) => PtValue | false | null | undefined` — `item` is the menu entry (an `Item`: its `label`, `value`, `description`, whatever else you put on it), and every state a boolean beside it, on for it (`selected`, `disabled`, …) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). Its result is merged last, after every state entry, through the same deduper; a falsy result leaves the entry as it was. See the passthrough guide, _Per-item functions_.
+ * Per-item functions: on the instance, an entry part (`item`, `itemText`, `itemIcon`, `itemDescription`) also accepts `({ item, selected, … }) => PtValue | false | null | undefined` — `item` is the menu entry (an `Item`: its `label`, `value`, `description`, whatever else you put on it), every state a boolean beside it, on for it (`selected`, `disabled`, …), and the entry's `variant` as a string (`default` when it has none) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). Its result is merged last, after every state entry, through the same deduper; a falsy result leaves the entry as it was. See the passthrough guide, _Per-item functions_.
  *
  * @part root - The floating element — an invisible positioning wrapper; a
  *   `class` on the component lands here. No node on the phone sheet: style
@@ -2283,14 +2320,25 @@ export type BbDropdownItemPtPart =
 	| 'itemIcon'
 	| 'itemDescription';
 /**
- * Passthrough states of `BbDropdown`, true while the matching `--` modifier is on.
+ * Passthrough states of `BbDropdown`, true while the matching `--` modifier is on
+ * (the link states: while the entry's `activeClass` / `exactActiveClass` are).
  *
+ * @state activeLink - Per node, on the entry parts: an entry whose link
+ *   (`to` / `href`) points at the current page or one of its ancestors —
+ *   exactly when its `activeClass` is on. The weakest state.
+ * @state exactActiveLink - Per node, on the entry parts: an entry whose link
+ *   points at the current page itself — its `exactActiveClass` is on.
  * @state selected - Per node, on the entry parts: a selectable group's
  *   checked entry.
  * @state disabled - Per node, on the entry parts: an entry that is disabled.
  * @state open - Component-wide: the menu is open.
  */
-export type BbDropdownPtState = 'open' | 'selected' | 'disabled';
+export type BbDropdownPtState =
+	| 'activeLink'
+	| 'exactActiveLink'
+	| 'open'
+	| 'selected'
+	| 'disabled';
 /** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
 export const BB_DROPDOWN_PT = {
 	parts: [
@@ -2306,10 +2354,22 @@ export const BB_DROPDOWN_PT = {
 		'itemIcon',
 		'itemDescription',
 	],
-	states: ['selected', 'disabled', 'open'],
+	states: ['activeLink', 'exactActiveLink', 'selected', 'disabled', 'open'],
+	// Each entry's `variant` is a state on the entry parts (Q76.7), below the
+	// real ones; an entry with none is `default`.
+	variant: {
+		names: DROPDOWN_ITEM_VARIANTS,
+		option: 'dropdownItemVariants',
+		parts: ['item', 'itemText', 'itemIcon', 'itemDescription'],
+	},
 } as const satisfies {
 	parts: readonly BbDropdownPtPart[];
 	states: readonly BbDropdownPtState[];
+	variant: {
+		names: readonly DropdownItemVariantBuiltIn[];
+		option: string;
+		parts: readonly BbDropdownItemPtPart[];
+	};
 };
 
 // Spelled INLINE with this component's own unions (Vue's SFC type resolver
@@ -2320,170 +2380,189 @@ export const BB_DROPDOWN_PT = {
 export type BbDropdownProps = {
 	[K in
 		| `pt:${BbDropdownSurfacePtPart}`
-		| `pt:${BbDropdownPtPart}:${BbDropdownPtState}`]?: PtValue;
-} & {
-	// The entry parts also take a per-item function, called with the menu
-	// entry — a literal function type, not `PtItemFn` (T23).
-	[K in `pt:${BbDropdownItemPtPart}`]?:
-		| PtValue
-		| ((ctx: PtItemCtx<InternalItem, BbDropdownPtState>) => PtItemResult);
-} & {
-	/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
-	/**
-	 * Passthrough, object form: the same keys as the `pt:*` attributes
-	 * without the prefix. See the `pt:<part>` row.
-	 */
-	pt?: PtItemMap<
-		BbDropdownPtPart,
-		BbDropdownItemPtPart,
-		BbDropdownPtState,
-		InternalItem
-	>;
-	/**
-	 * An external activator element or component ref: the activator slot is not
-	 * rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` /
-	 * `aria-controls`) are attached to it; don't add your own.
-	 */
-	activator?: HTMLElement | Record<string, any> | null;
-	/**
-	 * On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom
-	 * sheet that drills into submenus one level at a time instead of hover
-	 * flyouts; slots and selection are unchanged. Unset: the global
-	 * `config.adaptive`.
-	 *
-	 * @defaultValue `config.adaptive` (`true`)
-	 */
-	adaptive?: boolean;
-	/**
-	 * Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet
-	 * rows 44px → 36px (a sheet row stays a touch target). The label size does
-	 * not change.
-	 */
-	compact?: boolean;
-	/**
-	 * The element the panel positions against when it should differ from the
-	 * activator (a wrapper the activator is part of); an HTMLElement or
-	 * component ref. It also drives a percentage `width`. Ignored with
-	 * `placement="cursor"`.
-	 *
-	 * @defaultValue the activator element
-	 */
-	anchor?: HTMLElement | Record<string, any> | null;
-	/**
-	 * Keeps the panel inside this element alongside its trigger (sideways for
-	 * a menu above or below); away from the trigger it may pass the edge, and
-	 * only the viewport flips it. An HTMLElement, a component ref or a CSS
-	 * selector: a `useTemplateRef`, never `$refs.x` (not reactive).
-	 */
-	boundary?: HTMLElement | Record<string, any> | string | null;
-	/**
-	 * Disables the component
-	 */
-	disabled?: boolean;
-	/**
-	 * Renders the menu panel at mount instead of on the first open (the phone
-	 * sheet's too), and keeps its rows after a close. Without it the rows mount
-	 * on each open and go once the menu has closed.
-	 */
-	eager?: boolean;
-	/**
-	 * 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.
-	 */
-	enforceCoherence?: boolean;
-	/**
-	 * 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.
-	 */
-	id?: string;
-	/**
-	 * The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a
-	 * flat array for one group, nested arrays for divider-separated groups, or
-	 * `InternalGroup` objects for titled / selectable sections. A row's own
-	 * `items` opens a submenu.
-	 *
-	 * @defaultValue `[]`
-	 */
-	items: Item[];
-	/**
-	 * Default placeholder text shown while a pipeline group's async items load.
-	 * A group's own `loadingText` overrides this; both fall back to the localized
-	 * `common.loadingText` (`'Loading...'`).
-	 */
-	loadingText?: string;
-	/**
-	 * 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'`).
-	 */
-	emptyText?: string;
-	/**
-	 * 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"`).
-	 */
-	failedText?: string;
-	/**
-	 * Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on
-	 * mobile), spread over its defaults. A `pt` inside it styles only the sheet
-	 * (passthrough guide § Inside the sheet). The sheet hides its ✕; `{
-	 * hideClose: false }` brings it back.
-	 */
-	offCanvasProps?: Partial<BbOffCanvasProps>;
-	/**
-	 * Space the floating container will maintain from the activator.
-	 *
-	 * @defaultValue `4`
-	 */
-	offset?: number;
-	/**
-	 * Minimum empty space to keep from the edge of the page
-	 *
-	 * @defaultValue `10`
-	 */
-	padding?: number;
-	/**
-	 * Position of the dropdown relative to the activator.
-	 * Use `'cursor'` to anchor at the mouse/touch coordinates.
-	 * (No arrow is drawn either way — arrows are tooltip-only in v3.)
-	 *
-	 * @defaultValue `'bottom'`
-	 */
-	placement?: Placement | 'cursor';
-	/**
-	 * Debounce (ms) applied to the async re-fetch a `searchable` group fires as the
-	 * user types. Applies to every searchable group in the menu.
-	 *
-	 * @defaultValue `300`
-	 */
-	queryDebounceTime?: number;
-	/**
-	 * How long the transition has to last in milliseconds. Menus use the fast
-	 * transition (150) rather than the medium one (250) the other popovers
-	 * default to: a menu is opened to pick one command and is gone again, so
-	 * it answers faster than a panel the user reads or edits in.
-	 *
-	 * @defaultValue `150`
-	 */
-	transitionDuration?: number;
-	/**
-	 * Interaction(s) that open the dropdown.
-	 * 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?: DropdownTrigger | DropdownTrigger[];
-	/**
-	 * Width of the dropdown in pixels, percentage, or 'auto' to fit content.
-	 *
-	 * @defaultValue `'auto'`
-	 */
-	width?: number | string;
-};
+		| `pt:${BbDropdownPtPart}:${BbDropdownPtState}`
+		| `pt:${BbDropdownItemPtPart}:${DropdownItemVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	BbDropdownItemPtPart,
+	keyof DropdownItemVariantRegistry
+> & {
+		// The entry parts also take a per-item function, called with the menu
+		// entry — a literal function type, not `PtItemFn` (T23).
+		[K in `pt:${BbDropdownItemPtPart}`]?:
+			| PtValue
+			| ((
+					ctx: PtItemCtx<
+						InternalItem,
+						BbDropdownPtState,
+						DropdownItemVariantBuiltIn | keyof DropdownItemVariantRegistry
+					>
+			  ) => PtItemResult);
+	} & {
+		/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
+		/**
+		 * Passthrough, object form: the same keys as the `pt:*` attributes
+		 * without the prefix. See the `pt:<part>` row.
+		 */
+		pt?: PtItemMap<
+			BbDropdownPtPart,
+			BbDropdownItemPtPart,
+			BbDropdownPtState,
+			InternalItem,
+			DropdownItemVariantBuiltIn | keyof DropdownItemVariantRegistry
+		>;
+		/**
+		 * An external activator element or component ref: the activator slot is not
+		 * rendered, and the listeners and ARIA (`aria-haspopup` / `aria-expanded` /
+		 * `aria-controls`) are attached to it; don't add your own.
+		 */
+		activator?: HTMLElement | Record<string, any> | null;
+		/**
+		 * On mobile (below `config.mobileMaxWidth`), renders the menu as a bottom
+		 * sheet that drills into submenus one level at a time instead of hover
+		 * flyouts; slots and selection are unchanged. Unset: the global
+		 * `config.adaptive`.
+		 *
+		 * @defaultValue `config.adaptive` (`true`)
+		 */
+		adaptive?: boolean;
+		/**
+		 * Whether a selection closes the menu. Unset: a change in a single-choice
+		 * group closes it (an untick too, at any depth); a `multiple` group stays
+		 * open. `true`: every selection change closes it. `false`: none does.
+		 *
+		 * @defaultValue unset (close after a single-choice change)
+		 */
+		closeOnSelect?: boolean;
+		/**
+		 * Compact density, the `BbSelect` ladder: flyout rows 28px → 24px, sheet
+		 * rows 44px → 36px (a sheet row stays a touch target). The label size does
+		 * not change.
+		 */
+		compact?: boolean;
+		/**
+		 * The element the panel positions against when it should differ from the
+		 * activator (a wrapper the activator is part of); an HTMLElement or
+		 * component ref. It also drives a percentage `width`. Ignored with
+		 * `placement="cursor"`.
+		 *
+		 * @defaultValue the activator element
+		 */
+		anchor?: HTMLElement | Record<string, any> | null;
+		/**
+		 * Keeps the panel inside this element alongside its trigger (sideways for
+		 * a menu above or below); away from the trigger it may pass the edge, and
+		 * only the viewport flips it. An HTMLElement, a component ref or a CSS
+		 * selector: a `useTemplateRef`, never `$refs.x` (not reactive).
+		 */
+		boundary?: HTMLElement | Record<string, any> | string | null;
+		/**
+		 * Disables the component
+		 */
+		disabled?: boolean;
+		/**
+		 * Renders the menu panel at mount instead of on the first open (the phone
+		 * sheet's too), and keeps its rows after a close. Without it the rows mount
+		 * on each open and go once the menu has closed.
+		 */
+		eager?: boolean;
+		/**
+		 * 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.
+		 */
+		enforceCoherence?: boolean;
+		/**
+		 * 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.
+		 */
+		id?: string;
+		/**
+		 * The menu rows, each a `BbBaseButton` (`button`, `a` or `router-link`): a
+		 * flat array for one group, nested arrays for divider-separated groups, or
+		 * `InternalGroup` objects for titled / selectable sections. A row's own
+		 * `items` opens a submenu.
+		 *
+		 * @defaultValue `[]`
+		 */
+		items: Item[];
+		/**
+		 * Default placeholder text shown while a pipeline group's async items load.
+		 * A group's own `loadingText` overrides this; both fall back to the localized
+		 * `common.loadingText` (`'Loading...'`).
+		 */
+		loadingText?: string;
+		/**
+		 * 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'`).
+		 */
+		emptyText?: string;
+		/**
+		 * 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"`).
+		 */
+		failedText?: string;
+		/**
+		 * Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on
+		 * mobile), spread over its defaults. A `pt` inside it styles only the sheet
+		 * (passthrough guide § Inside the sheet). The sheet hides its ✕; `{
+		 * hideClose: false }` brings it back.
+		 */
+		offCanvasProps?: Partial<BbOffCanvasProps>;
+		/**
+		 * Space the floating container will maintain from the activator.
+		 *
+		 * @defaultValue `4`
+		 */
+		offset?: number;
+		/**
+		 * Minimum empty space to keep from the edge of the page
+		 *
+		 * @defaultValue `10`
+		 */
+		padding?: number;
+		/**
+		 * Position of the dropdown relative to the activator.
+		 * Use `'cursor'` to anchor at the mouse/touch coordinates.
+		 * (No arrow is drawn either way — arrows are tooltip-only in v3.)
+		 *
+		 * @defaultValue `'bottom'`
+		 */
+		placement?: Placement | 'cursor';
+		/**
+		 * Debounce (ms) applied to the async re-fetch a `searchable` group fires as the
+		 * user types. Applies to every searchable group in the menu.
+		 *
+		 * @defaultValue `300`
+		 */
+		queryDebounceTime?: number;
+		/**
+		 * How long the transition has to last in milliseconds. Menus use the fast
+		 * transition (150) rather than the medium one (250) the other popovers
+		 * default to: a menu is opened to pick one command and is gone again, so
+		 * it answers faster than a panel the user reads or edits in.
+		 *
+		 * @defaultValue `150`
+		 */
+		transitionDuration?: number;
+		/**
+		 * Interaction(s) that open the dropdown.
+		 * 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?: DropdownTrigger | DropdownTrigger[];
+		/**
+		 * Width of the dropdown in pixels, percentage, or 'auto' to fit content.
+		 *
+		 * @defaultValue `'auto'`
+		 */
+		width?: number | string;
+	};
 
 export type BbDropdownEvents = {
 	/** Emitted as soon as the menu (the popover, or the sheet on a phone) starts to open. */
@@ -2598,12 +2677,28 @@ export type BbDropdownItemSlotProps = {
 	selected: boolean;
 	/** The row's label (on a group's title line, the group's label). */
 	label: InternalItem['label'];
+	/**
+	 * A link entry (`to` / `href`) pointing at the current page or one of its
+	 * ancestors: its `activeClass` is on. Not set on a group's title line.
+	 */
+	activeLink?: boolean;
+	/**
+	 * A link entry pointing at the current page itself: its `exactActiveClass`
+	 * is on. Not set on a group's title line.
+	 */
+	exactActiveLink?: boolean;
 };
 
 /** Props exposed by the `loading` and `empty` placeholder slots. */
 export type BbDropdownPlaceholderSlotProps = {
 	/** Id of the group this placeholder belongs to. */
 	groupId?: string;
+	/**
+	 * The group's current search text, as typed (`''` when it has no search
+	 * field or nothing is typed) — the same `query` BbSelect's `#empty` gets,
+	 * e.g. for "Type at least 2 characters" under a remote search's minimum.
+	 */
+	query: string;
 	/** Resolved placeholder text (group `loadingText`/`emptyText`/`failedText` → dropdown default). */
 	text: string;
 	/**
@@ -2730,6 +2825,16 @@ export type BbDropdownGroupEvents = {
 	--bg: var(--bb-panel);
 }
 
+/* The item size knobs (ATT-09), BbButton's names: `--fs` the row label,
+   `--icon-size` its prepend / append icons. Declared at specificity 0 on the
+   menu's root, so a consumer class or `pt` wins and a `--fs` an ancestor set
+   (a button, a badge) never leaks in; submenus inherit the root's. The adaptive
+   sheet reads neither: its rows keep `--sheet-option-fs` and their own icons. */
+:where(.bb-dropdown:not(.bb-dropdown--submenu)) {
+	--fs: var(--bb-fs);
+	--icon-size: 1rem;
+}
+
 /* @inherit --transition-duration — set inline by the adaptive surface;
    @inherit --py — the adaptive sheet's rules target BbOffCanvas elements, which
    declare it on the panel */
@@ -2961,8 +3066,9 @@ export type BbDropdownGroupEvents = {
 		/* `--bb-fs`, matching the select's option label. These two menus sit at
 		   the same 28px row height on the same screen and their labels were a
 		   pixel apart (13 against 14) — the desktop twin of the sheet drift, and
-		   the kind of difference nobody can name but everybody sees. */
-		font-size: var(--bb-fs);
+		   the kind of difference nobody can name but everybody sees. `--fs`
+		   (above) is the consumer's knob. */
+		font-size: var(--fs);
 		gap: 1px;
 		line-height: 1.2;
 		max-height: var(--max-h, none);
@@ -3125,9 +3231,9 @@ export type BbDropdownGroupEvents = {
 
 			.item__prepend-icon,
 			.item__append-icon {
-				--size: 16px;
+				--size: var(--icon-size);
 				flex-shrink: 0;
-				font-size: 15px;
+				font-size: calc(var(--icon-size) - 1px);
 			}
 
 			.item__content {
@@ -3188,6 +3294,11 @@ export type BbDropdownGroupEvents = {
 				flex-shrink: 0;
 				font-size: 19px;
 				margin-inline-start: auto;
+
+				/* Points where the flyout opens: the inline end. */
+				&:dir(rtl) {
+					transform: scaleX(-1);
+				}
 			}
 
 			/*
@@ -3580,9 +3691,15 @@ export type BbDropdownGroupEvents = {
 				position: absolute;
 				top: var(--bb-panel-p);
 
-				/* Same chevron_right asset the submenu rows use, pointed back. */
+				/* Same chevron_right asset the submenu rows use, pointed back:
+				   toward the inline start, which is already where it points in
+				   rtl. */
 				.bb-button__icon {
 					transform: rotate(180deg);
+
+					&:dir(rtl) {
+						transform: none;
+					}
 				}
 			}