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

package/dist/ai/source/BbSelectPopover.md

@@ -158,6 +158,7 @@
 			<template #loading><slot name="loading" :query="query" /></template>
 			<template #empty
 				><slot
+					:close="close"
 					:error="itemsError"
 					:focus="focusPopoverContent"
 					name="empty"
@@ -184,7 +185,13 @@
 				() => offCanvasProps?.pt
 			)
 		"
-		v-bind="mergeProps(offcanvasBindings, sheetEvents, withoutClass($attrs))"
+		v-bind="
+			mergeProps(
+				offcanvasBindings,
+				sheetEvents,
+				asSheetAttrs(withoutClass($attrs))
+			)
+		"
 	>
 		<template v-if="$slots.header" #header="{ titleId: sheetTitleId }">
 			<!-- The sheet's own `titleId`: its dialog is labelled by it. -->
@@ -244,6 +251,7 @@
 	content. Positioning is unaffected — the wrapper is `position: fixed`. -->
 	<CommonPopover
 		v-else
+		ref="popoverSurface"
 		v-model="shown"
 		:anchor="positionAnchorEl"
 		:aria-hidden="panelSettledClosed || undefined"
@@ -256,6 +264,7 @@
 			'bb-select-popover--loading': computedLoading,
 			'bb-select-popover--reloading': isReloading,
 			'bb-select-popover--clearable-active': hasClearableValue,
+			'bb-select-popover--compact': compact,
 		}"
 		:disable-flip="disableFlip"
 		hide-arrow
@@ -293,6 +302,8 @@
 	lang="ts"
 	generic="Item = any, Known extends BbSelectKnownItems | undefined = undefined"
 >
+import { asSheetAttrs } from '../BbOffCanvas/sheetAttrs';
+import type { FallthroughAttrs } from '@/types/fallthrough';
 import type { Option as BaseOption, GroupedOptions } from '@/types/Option';
 import {
 	computed,
@@ -400,38 +411,50 @@ import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
 import { hasVnodeListener } from '@/utilities/functions/hasVnodeListener';
 
-const props = withDefaults(defineProps<BbSelectPopoverProps<Item, Known>>(), {
-	// `undefined` (declared, not omitted) keeps `adaptive` three-state: it disables
-	// Vue's absent→`false` Boolean cast so `props.adaptive ?? config.adaptive` can
-	// reach the config default, while keeping the Boolean type so the valueless
-	// `adaptive` shorthand still resolves to `true`.
-	adaptive: undefined,
-	anchor: null,
-	// Same three-state trap as `adaptive`: without this, Vue's absent→`false`
-	// Boolean cast made `props.ariaInvalid ?? !!props.hasErrors` short-circuit on
-	// `false`, so the documented hasErrors fallback never fired and an errored
-	// searchbox never announced `aria-invalid`.
-	ariaInvalid: undefined,
-	autocomplete: 'off',
-	depsDebounceTime: 0,
-	dependencies: () => [],
-	// Three-state like `adaptive`: `undefined` keeps an absent `disable-writing`
-	// distinguishable from an explicit `false`, so it can mean `'auto'`
-	// (`resolvedDisableWriting`), while the valueless shorthand still casts to
-	// `true`.
-	disableWriting: undefined,
-	filterBy: () => [],
-	max: Infinity,
-	modelValueDebounceTime: 0,
-	offset: 4,
-	padding: 10,
-	placement: 'bottom',
-	prefill: 'interaction',
-	queryDebounceTime: 500,
-	selectable: true,
-	transitionDuration: transitions.medium,
-	width: '200',
-});
+// The element(s) the fall-through attributes reach, as typed below.
+// @attrTargets span dialog
+const props = withDefaults(
+	defineProps<
+		BbSelectPopoverProps<Item, Known> &
+			/* @vue-ignore */ FallthroughAttrs<
+				'span' | 'dialog',
+				BbSelectPopoverProps<Item, Known>,
+				BbSelectPopoverEvents
+			>
+	>(),
+	{
+		// `undefined` (declared, not omitted) keeps `adaptive` three-state: it disables
+		// Vue's absent→`false` Boolean cast so `props.adaptive ?? config.adaptive` can
+		// reach the config default, while keeping the Boolean type so the valueless
+		// `adaptive` shorthand still resolves to `true`.
+		adaptive: undefined,
+		anchor: null,
+		// Same three-state trap as `adaptive`: without this, Vue's absent→`false`
+		// Boolean cast made `props.ariaInvalid ?? !!props.hasErrors` short-circuit on
+		// `false`, so the documented hasErrors fallback never fired and an errored
+		// searchbox never announced `aria-invalid`.
+		ariaInvalid: undefined,
+		autocomplete: 'off',
+		depsDebounceTime: 0,
+		dependencies: () => [],
+		// Three-state like `adaptive`: `undefined` keeps an absent `disable-writing`
+		// distinguishable from an explicit `false`, so it can mean `'auto'`
+		// (`resolvedDisableWriting`), while the valueless shorthand still casts to
+		// `true`.
+		disableWriting: undefined,
+		filterBy: () => [],
+		max: Infinity,
+		modelValueDebounceTime: 0,
+		offset: 4,
+		padding: 10,
+		placement: 'bottom',
+		prefill: 'interaction',
+		queryDebounceTime: 500,
+		selectable: true,
+		transitionDuration: transitions.medium,
+		width: '200',
+	}
+);
 
 const emit = defineEmits<BbSelectPopoverEvents>();
 
@@ -486,6 +509,7 @@ const activatorEl = ref<DomHost>();
 const optionsContainer = ref<any | null>(null);
 const searchInput = ref<HTMLInputElement | null>(null);
 const popoverFocusProxy = ref<HTMLButtonElement | null>(null);
+const popoverSurface = ref<{ $el: Element } | null>(null);
 const activeDescendantId = ref<string>();
 
 const positionAnchorEl = computed<DomHost | undefined>(() => {
@@ -1351,14 +1375,14 @@ const outsideRowFor = (valueHash: string): Item | undefined =>
  * its index, so membership costs no pass over the rows.
  */
 const optionInputs = {
-	disabled: toRef(props, 'disabled'),
+	disabled: toRef(() => props.disabled),
 	itemText: props.itemText,
-	itemProps: toRef(props, 'itemProps'),
+	itemProps: toRef(() => props.itemProps),
 	itemValue: props.itemValue,
 	optionDefaults: true,
 	// A ref, not the setup-time number: a runtime `:max` change must re-gate rows.
-	max: toRef(props, 'max'),
-	selectable: toRef(props, 'selectable'),
+	max: toRef(() => props.max),
+	selectable: toRef(() => props.selectable),
 	selectedIndexedByHash: modelValueIndexedByHash,
 };
 const fetchedProjection = useBaseOptions({
@@ -1622,11 +1646,12 @@ const pruneSticky = () => {
 };
 /**
  * Whether an unpick keeps its row where it is: only on the open-ordered list
- * (or a masked one, which shows its pins). Under a search the row leaves the
- * selected tail as on v3, and clearing the search orders like a fresh open,
- * which lists no unselected row (R7, newcode-r7-1).
+ * (a masked one opens on an empty query too, so it qualifies). Under a search
+ * the row leaves the selected tail as on v3, and clearing the search orders
+ * like a fresh open, which lists no unselected row (R7, newcode-r7-1) — also
+ * when the query was typed over the mask (Q75.6 a).
  */
-const unpickKeepsPlace = () => listMasked.value || !query.value;
+const unpickKeepsPlace = () => !query.value;
 /** B3: removals from outside the list that the user made (a field chip, the clear button). */
 const markUserUnpicked = (values: unknown[]) => {
 	if (!shown.value || !unpickKeepsPlace()) return;
@@ -1787,7 +1812,7 @@ watch(
  * it. Searches and failures never reach the prune.
  */
 const { coherent } = useCoherence({
-	modelValue: toRef(props, 'modelValue'),
+	modelValue: toRef(() => props.modelValue),
 	multiple: props.multiple,
 	iteratee: (value) => !!optionsIndexedByHash.value[hash(value)],
 });
@@ -1803,7 +1828,7 @@ const fetchedValueHashes = computed(
 
 const { coherent: fetchedCoherent, coherentValue: fetchedCoherentValue } =
 	useCoherence({
-		modelValue: toRef(props, 'modelValue'),
+		modelValue: toRef(() => props.modelValue),
 		multiple: props.multiple,
 		iteratee: (value) => {
 			const valueHash = hash(value);
@@ -2804,6 +2829,13 @@ const close = async () => {
 	// transition finishes; the flyout's document listeners were never attached.
 	if (useOffcanvas.value) return;
 
+	// The closed panel turns `aria-hidden` (Q75.5 d): a close that did not come
+	// from the activator (the slot's `toggle` from app code, the activator
+	// scrolling away) must not leave focus inside it (Q75.6 c).
+	if (popoverSurface.value?.$el.contains(document.activeElement)) {
+		activatorEl.value?.focus({ preventScroll: true });
+	}
+
 	pause();
 	removeEscapeEntry(escapeKey);
 	document.removeEventListener('click', onOutsideInteraction, {
@@ -2915,9 +2947,22 @@ const onSearchClear = () => {
  * popover and the adaptive sheet, so a consumer's slot markup works unchanged
  * across surfaces.
  */
+/**
+ * Q83.2: the list shows its empty state (no row, the load settled): no
+ * items, none matching the query, or a failed load with nothing listed.
+ */
+const listEmpty = computed(
+	() =>
+		!computedLoading.value &&
+		(props.groupBy
+			? groupedOptions.value.every((group) => !group.options.length)
+			: !filteredOptions.value.length)
+);
+
 const panelSlotProps = computed(() => ({
 	close,
 	clear: onClear,
+	empty: listEmpty.value,
 	focus: focusPopoverContent,
 	query: query.value,
 	selectedOptions: publicSelectedOptions.value,
@@ -3193,11 +3238,12 @@ onDeactivated(() => {
 
 ```ts
 import type { BbSelectItemProps } from '@/types/ItemProps';
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { HTMLAttributes } from 'vue';
 import type {
+	PtCompoundProps,
 	PtNoInfer,
 	PtItemCtx,
-	PtItemMap,
+	PtScopedItemMap,
 	PtItemResult,
 	PtValue,
 } from '@/types/passthrough';
@@ -3338,6 +3384,14 @@ export type BbSelectPopoverOptionPtPart =
  * @state open - Component-wide: the options surface is showing.
  */
 export type BbSelectPopoverPtState = 'open' | 'selected' | 'disabled';
+/**
+ * Every `part` / `part:state` key of `BbSelectPopover` — only the pairs that
+ * land: `open` everywhere, an option's `selected` / `disabled` on its parts.
+ */
+export type BbSelectPopoverPtKey =
+	| BbSelectPopoverPtPart
+	| `${BbSelectPopoverPtPart}:open`
+	| `${BbSelectPopoverOptionPtPart}:${'selected' | 'disabled'}`;
 /** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
 export const BB_SELECT_POPOVER_PT = {
 	parts: [
@@ -3355,9 +3409,22 @@ export const BB_SELECT_POPOVER_PT = {
 		'footer',
 	],
 	states: ['selected', 'disabled', 'open'],
+	/** On every part: what the resolver's `active` map turns on. */
+	wide: ['open'],
+	/** Per node: what one option knows. */
+	node: {
+		option: ['selected', 'disabled'],
+		itemText: ['selected', 'disabled'],
+		itemIcon: ['selected', 'disabled'],
+		itemDescription: ['selected', 'disabled'],
+	},
 } as const satisfies {
 	parts: readonly BbSelectPopoverPtPart[];
 	states: readonly BbSelectPopoverPtState[];
+	wide: readonly BbSelectPopoverPtState[];
+	node: Partial<
+		Record<BbSelectPopoverPtPart, readonly BbSelectPopoverPtState[]>
+	>;
 };
 
 // Spelled INLINE with this component's own unions (Vue's SFC type resolver
@@ -3372,329 +3439,332 @@ export type BbSelectPopoverProps<
 > = {
 	[K in
 		| `pt:${BbSelectPopoverSurfacePtPart}`
-		| `pt:${BbSelectPopoverPtPart}:${BbSelectPopoverPtState}`]?: PtValue;
-} & {
-	// The option parts also take a per-item function, typed on the popover's
-	// item — a literal function type, not `PtItemFn` (T23).
-	[K in `pt:${BbSelectPopoverOptionPtPart}`]?:
-		| PtValue
-		| ((
-				ctx: PtItemCtx<
-					PtNoInfer<Item>,
-					BbSelectPopoverPtState,
-					never,
-					BbSelectSlotRow<PtNoInfer<Item>, PtNoInfer<Known>>
-				>
-		  ) => 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<
-		BbSelectPopoverPtPart,
-		BbSelectPopoverOptionPtPart,
-		BbSelectPopoverPtState,
-		PtNoInfer<Item>,
-		never,
-		BbSelectSlotRow<PtNoInfer<Item>, PtNoInfer<Known>>
-	>;
-	/**
-	 * External activator element or component ref.
-	 * When provided, the activator slot is not rendered and event listeners
-	 * are attached programmatically to the referenced element.
-	 */
-	activator?: HTMLElement | Record<string, any> | null;
-	/**
-	 * On mobile, the panel opens as a bottom sheet instead of a floating
-	 * popover, with the same search and list. Unset, the global
-	 * `config.adaptive` applies.
-	 *
-	 * @defaultValue `config.adaptive` (`true`)
-	 */
-	adaptive?: boolean;
-	/**
-	 * 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).
-	 */
-	offCanvasProps?: Partial<BbOffCanvasProps>;
-	/**
-	 * Override the element used for popover positioning and width measurement.
-	 * Useful when the focusable activator is narrower than its visual container
-	 * (e.g. a button inside a wrapper). Falls back to `activatorEl` when omitted.
-	 *
-	 * @defaultValue `null`
-	 */
-	anchor?: HTMLElement | Record<string, any> | null;
-	/**
-	 * Hides the panel's search field: `true` everywhere, `'mobile'` /
-	 * `'desktop'` on that platform only. `'auto'` hides it, per open, for an
-	 * array `items` shorter than the plugin's `autoDisableWritingThreshold`
-	 * (6); never for a provider or with an `option:add` listener.
-	 *
-	 * @defaultValue `'auto'`
-	 */
-	disableWriting?: boolean | 'mobile' | 'desktop' | 'auto';
-	/**
-	 * Space-separated IDREF(s) that describe this field for assistive technologies.
-	 * Accepts either a string or array of ids.
-	 */
-	ariaDescribedby?: string | string[];
-	/**
-	 * Explicit invalid state for accessibility semantics.
-	 * Falls back to `hasErrors` when not provided.
-	 */
-	ariaInvalid?: boolean;
-	/**
-	 * Browser autocomplete hint for the popover search input.
-	 *
-	 * @defaultValue `'off'`
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-	/**
-	 * Constrains the popover to a specific boundary element: it stays inside
-	 * it alongside its trigger (sideways for a popover above or below); away
-	 * from the trigger it may pass the edge, and it flips at the viewport only.
-	 */
-	boundary?: HTMLElement | Record<string, any> | string | null;
-	/**
-	 * Apply the compact density variant.
-	 */
-	compact?: boolean;
-	/**
-	 * Additional dependencies that trigger item reloading when changed.
-	 *
-	 * @defaultValue `[]`
-	 */
-	dependencies?: unknown[];
-	/**
-	 * Debounce delay (ms) for dependency-triggered reloads.
-	 *
-	 * @defaultValue `0`
-	 */
-	depsDebounceTime?: number;
-	/**
-	 * Shows a clear button in the search field, in the lens' place while there
-	 * is a query or a selection; it resets both. None without a search field.
-	 * Leave it off when the activator already clears (as BbSelect's does).
-	 */
-	clearable?: boolean;
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-	/**
-	 * Drops the picks the items no longer contain (single: `null`). Checked
-	 * after every applied, successful load whose `reason` is not `'search'`
-	 * (an empty one included), against the FETCHED rows only (a `stash` does
-	 * not count); a search or failed load never prunes.
-	 */
-	enforceCoherence?: boolean;
-	/**
-	 * What typing filters on: empty = the display text and description; item
-	 * paths = those fields (`['name', 'email']`); `false` = no filtering.
-	 * Use `false` when the provider matched the query on the server, or its
-	 * email/accent matches show as "No results".
-	 *
-	 * @defaultValue `[]`
-	 */
-	filterBy?: string[] | false;
-	/**
-	 * Disables the automatic flip to the opposite side when the popover
-	 * would overflow (flipping is on by default).
-	 *
-	 * @defaultValue `false`
-	 */
-	disableFlip?: boolean;
-	/** Path to item property for grouping options. */
-	groupBy?: string | ((item: Item) => string | number | symbol);
-	/**
-	 * Marks the component as being in error state.
-	 */
-	hasErrors?: boolean;
-	/**
-	 * Marks the component as being in a warning state. Visually mirrors
-	 * `hasErrors` but uses `--bb-warn` chrome; errors take priority when both
-	 * are set.
-	 */
-	hasWarnings?: boolean;
-	/**
-	 * Height of group headers in the listbox (px). Defaults to 32px (24px
-	 * compact; 36px / 32px on mobile viewports). Only applies when `groupBy`
-	 * is set. An explicit value wins on every viewport.
-	 */
-	headerHeight?: number;
-	/**
-	 * Seeds the ids the popover sets: its listbox is `<id>_listbox` (the
-	 * activator's `aria-controls`) and each option's id derives from it.
-	 * Generated when omitted.
-	 */
-	id?: HTMLAttributes['id'];
-	/**
-	 * Height of the options in the listbox (px). Defaults to 28px (24px
-	 * compact; 44px / 36px on mobile viewports). An explicit value wins on
-	 * every viewport.
-	 *
-	 * @defaultValue `28`
-	 */
-	itemHeight?: number;
-	/**
-	 * The options: an array, or a sync or async provider given a
-	 * `BbSelectPopoverItemsContext` (`query`, `reason`, `modelValue`,
-	 * `signal`). Branch on `reason !== 'search'` to resolve the
-	 * selection by id. A provider fails by THROWING, never by returning `[]`.
-	 *
-	 * @defaultValue `[]`
-	 */
-	items:
-		| Item[]
-		| ((context: BbSelectPopoverItemsContext) => Item[] | Promise<Item[]>);
-	/**
-	 * Path to item property for display text or function to extract it.
-	 *
-	 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
-	 *
-	 * @defaultValue own `label`, else `text`, else `JSON.stringify(item)`
-	 */
-	itemText?: ItemAccessor<Item, string>;
-	/**
-	 * ADDITIONAL row fields, never the text or value: `description` (a muted
-	 * line under the label), `prepend:icon`, `append:icon`. An object of paths
-	 * or getters per field, or a function of the item. Nothing is read
-	 * implicitly; none shows in the trigger or the chips.
-	 */
-	itemProps?: BbSelectItemProps<Item>;
-	/**
-	 * Path to item property for value or function to extract it.
-	 *
-	 * Unset: own `value`, even `null`.
-	 *
-	 * @defaultValue own `value`, else the whole item
-	 */
-	itemValue?: ItemAccessor<Item>;
-	/**
-	 * `{ value, label }` rows naming the value the app already holds, whatever
-	 * the options' shape: the activator's `text` with no request until the
-	 * first open (`prefill: true` still loads). Not options: accessors never
-	 * run on them; slots get one as `item`, `known: true`, until the list
-	 * brings its own.
-	 */
-	knownItems?: [Known] extends [undefined] ? BbSelectKnownItems : Known;
-	/**
-	 * Display the loading state styles.
-	 */
-	loading?: boolean;
-	/**
-	 * Message shown while items are being loaded.
-	 */
-	loadingText?: string;
-	/**
-	 * Maximum number of selectable items (limits selection when `multiple` is true).
-	 *
-	 * @defaultValue `Infinity`
-	 */
-	max?: number;
-	/**
-	 * v-model value. Single value for single select, array for multiple select.
-	 */
-	modelValue: any;
-	/**
-	 * Debounce delay (ms) for modelValue change handling.
-	 *
-	 * @defaultValue `0`
-	 */
-	modelValueDebounceTime?: number;
-	/**
-	 * Enable multiple item selection. When true, modelValue must be an array.
-	 */
-	multiple?: boolean;
-	/**
-	 * Message displayed when no items are available.
-	 */
-	emptyText?: string;
-	/**
-	 * Message displayed in the empty state while the latest load FAILED (the
-	 * provider threw): the twin of `emptyText` for that case.
-	 *
-	 * @defaultValue the localized `common.failedText` ("Couldn't load items")
-	 */
-	failedText?: string;
-	/**
-	 * Distance (px) between the activator and the popover.
-	 *
-	 * @defaultValue `4`
-	 */
-	offset?: number;
-	/**
-	 * Minimum page padding used by floating shift middleware.
-	 *
-	 * @defaultValue `10`
-	 */
-	padding?: number;
-	/**
-	 * Floating placement of the popover.
-	 *
-	 * @defaultValue `'bottom'`
-	 */
-	placement?: Placement;
-	/**
-	 * When the options first load: `'interaction'` on first open, `true` on
-	 * mount (and in SSR), `false` once the user types (on open with
-	 * `disable-writing` or a non-empty model). An array `items` always
-	 * resolves on mount; else a seeded model's text waits for the first open.
-	 *
-	 * @defaultValue `'interaction'`
-	 */
-	prefill?: boolean | 'interaction';
-	/**
-	 * Debounce delay (ms) before triggering search queries after user input stops.
-	 *
-	 * @defaultValue `500`
-	 */
-	queryDebounceTime?: number;
-	/**
-	 * Prevents opening the popover while keeping the activator accessible.
-	 */
-	readonly?: boolean;
-	/**
-	 * Accessible label used by the search input rendered inside the popover.
-	 * Falls back to the localized `select.searchLabel` key when omitted.
-	 *
-	 * @defaultValue `t('select.searchLabel')` (`'Search options'`)
-	 */
-	searchInputAriaLabel?: string;
-	/**
-	 * Defines whether options are selectable.
-	 * Can be a global boolean that affects all options or a function
-	 * that accepts an item and returns a boolean that only affects that item.
-	 * Non-selectable options are rendered disabled.
-	 *
-	 * @defaultValue `true`
-	 */
-	selectable?: boolean | ((item: Item) => boolean);
-	/**
-	 * Keeps picked options named across searches: a pick stays resolvable when
-	 * a later search or a failed load no longer returns it. It follows the
-	 * model, and does not keep a pick valid: `enforce-coherence` still prunes
-	 * it.
-	 */
-	stash?: boolean;
-	/**
-	 * Transition duration (ms) for popover show/hide animations.
-	 *
-	 * @defaultValue `250`
-	 */
-	transitionDuration?: number;
-	/**
-	 * Width of the popover in pixels, percentage, or `'auto'`. A bare number is
-	 * read as pixels — the default is the string `'200'`, not the number `200`.
-	 *
-	 * @defaultValue `'200'`
-	 */
-	width?: number | string;
-};
+		| `pt:${BbSelectPopoverPtPart}:open`
+		| `pt:${BbSelectPopoverOptionPtPart}:${'selected' | 'disabled'}`]?: PtValue;
+} & /* @vue-ignore */ PtCompoundProps<typeof BB_SELECT_POPOVER_PT> & {
+		// The option parts also take a per-item function, typed on the popover's
+		// item — a literal function type, not `PtItemFn` (T23).
+		[K in `pt:${BbSelectPopoverOptionPtPart}`]?:
+			| PtValue
+			| ((
+					ctx: PtItemCtx<
+						PtNoInfer<Item>,
+						BbSelectPopoverPtState,
+						never,
+						BbSelectSlotRow<PtNoInfer<Item>, PtNoInfer<Known>>
+					>
+			  ) => 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?: PtScopedItemMap<
+			BbSelectPopoverPtKey,
+			BbSelectPopoverOptionPtPart,
+			BbSelectPopoverPtState,
+			PtNoInfer<Item>,
+			never,
+			BbSelectSlotRow<PtNoInfer<Item>, PtNoInfer<Known>>
+		>;
+		/**
+		 * External activator element or component ref.
+		 * When provided, the activator slot is not rendered and event listeners
+		 * are attached programmatically to the referenced element.
+		 */
+		activator?: HTMLElement | Record<string, any> | null;
+		/**
+		 * On mobile, the panel opens as a bottom sheet instead of a floating
+		 * popover, with the same search and list. Unset, the global
+		 * `config.adaptive` applies.
+		 *
+		 * @defaultValue `config.adaptive` (`true`)
+		 */
+		adaptive?: boolean;
+		/**
+		 * 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).
+		 */
+		offCanvasProps?: Partial<BbOffCanvasProps>;
+		/**
+		 * Override the element used for popover positioning and width measurement.
+		 * Useful when the focusable activator is narrower than its visual container
+		 * (e.g. a button inside a wrapper). Falls back to `activatorEl` when omitted.
+		 *
+		 * @defaultValue `null`
+		 */
+		anchor?: HTMLElement | Record<string, any> | null;
+		/**
+		 * Hides the panel's search field: `true` everywhere, `'mobile'` /
+		 * `'desktop'` on that platform only. `'auto'` hides it, per open, for an
+		 * array `items` shorter than the plugin's `autoDisableWritingThreshold`
+		 * (6); never for a provider or with an `option:add` listener.
+		 *
+		 * @defaultValue `'auto'`
+		 */
+		disableWriting?: boolean | 'mobile' | 'desktop' | 'auto';
+		/**
+		 * Space-separated IDREF(s) that describe this field for assistive technologies.
+		 * Accepts either a string or array of ids.
+		 */
+		ariaDescribedby?: string | string[];
+		/**
+		 * Explicit invalid state for accessibility semantics.
+		 * Falls back to `hasErrors` when not provided.
+		 */
+		ariaInvalid?: boolean;
+		/**
+		 * Browser autocomplete hint for the popover search input.
+		 *
+		 * @defaultValue `'off'`
+		 */
+		// Not Vue's InputHTMLAttributes['autocomplete']: since Vue 3.5.27 that is a
+		// ~10k-member union, and our props overflow TS on it (TS2590).
+		autocomplete?: string;
+		/**
+		 * Constrains the popover to a specific boundary element: it stays inside
+		 * it alongside its trigger (sideways for a popover above or below); away
+		 * from the trigger it may pass the edge, and it flips at the viewport only.
+		 */
+		boundary?: HTMLElement | Record<string, any> | string | null;
+		/**
+		 * Apply the compact density variant.
+		 */
+		compact?: boolean;
+		/**
+		 * Additional dependencies that trigger item reloading when changed.
+		 *
+		 * @defaultValue `[]`
+		 */
+		dependencies?: unknown[];
+		/**
+		 * Debounce delay (ms) for dependency-triggered reloads.
+		 *
+		 * @defaultValue `0`
+		 */
+		depsDebounceTime?: number;
+		/**
+		 * Shows a clear button in the search field, in the lens' place while there
+		 * is a query or a selection; it resets both. None without a search field.
+		 * Leave it off when the activator already clears (as BbSelect's does).
+		 */
+		clearable?: boolean;
+		/**
+		 * Disables the component.
+		 */
+		disabled?: boolean;
+		/**
+		 * Drops the picks the items no longer contain (single: `null`). Checked
+		 * after every applied, successful load whose `reason` is not `'search'`
+		 * (an empty one included), against the FETCHED rows only (a `stash` does
+		 * not count); a search or failed load never prunes.
+		 */
+		enforceCoherence?: boolean;
+		/**
+		 * What typing filters on: empty = the display text and description; item
+		 * paths = those fields (`['name', 'email']`); `false` = no filtering.
+		 * Use `false` when the provider matched the query on the server, or its
+		 * email/accent matches show as "No results".
+		 *
+		 * @defaultValue `[]`
+		 */
+		filterBy?: string[] | false;
+		/**
+		 * Disables the automatic flip to the opposite side when the popover
+		 * would overflow (flipping is on by default).
+		 *
+		 * @defaultValue `false`
+		 */
+		disableFlip?: boolean;
+		/** Path to item property for grouping options. */
+		groupBy?: string | ((item: Item) => string | number | symbol);
+		/**
+		 * Marks the component as being in error state.
+		 */
+		hasErrors?: boolean;
+		/**
+		 * Marks the component as being in a warning state. Visually mirrors
+		 * `hasErrors` but uses `--bb-warn` chrome; errors take priority when both
+		 * are set.
+		 */
+		hasWarnings?: boolean;
+		/**
+		 * Height of group headers in the listbox (px). Defaults to 32px (24px
+		 * compact; 36px / 32px on mobile viewports). Only applies when `groupBy`
+		 * is set. An explicit value wins on every viewport.
+		 */
+		headerHeight?: number;
+		/**
+		 * Seeds the ids the popover sets: its listbox is `<id>_listbox` (the
+		 * activator's `aria-controls`) and each option's id derives from it.
+		 * Generated when omitted.
+		 */
+		id?: HTMLAttributes['id'];
+		/**
+		 * Height of the options in the listbox (px). Defaults to 28px (24px
+		 * compact; 44px / 36px on mobile viewports). An explicit value wins on
+		 * every viewport.
+		 *
+		 * @defaultValue `28`
+		 */
+		itemHeight?: number;
+		/**
+		 * The options: an array, or a sync or async provider given a
+		 * `BbSelectPopoverItemsContext` (`query`, `reason`, `modelValue`,
+		 * `signal`). Branch on `reason !== 'search'` to resolve the
+		 * selection by id. A provider fails by THROWING, never by returning `[]`.
+		 *
+		 * @defaultValue `[]`
+		 */
+		items:
+			| Item[]
+			| ((context: BbSelectPopoverItemsContext) => Item[] | Promise<Item[]>);
+		/**
+		 * Path to item property for display text or function to extract it.
+		 *
+		 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
+		 *
+		 * @defaultValue own `label`, else `text`, else `JSON.stringify(item)`
+		 */
+		itemText?: ItemAccessor<Item, string>;
+		/**
+		 * ADDITIONAL row fields, never the text or value: `description` (a muted
+		 * line under the label), `prepend:icon`, `append:icon`. An object of paths
+		 * or getters per field, or a function of the item. Nothing is read
+		 * implicitly; none shows in the trigger or the chips.
+		 */
+		itemProps?: BbSelectItemProps<Item>;
+		/**
+		 * Path to item property for value or function to extract it.
+		 *
+		 * Unset: own `value`, even `null`.
+		 *
+		 * @defaultValue own `value`, else the whole item
+		 */
+		itemValue?: ItemAccessor<Item>;
+		/**
+		 * `{ value, label }` rows naming the value the app already holds, whatever
+		 * the options' shape: the activator's `text` with no request until the
+		 * first open (`prefill: true` still loads). Not options: accessors never
+		 * run on them; slots get one as `item`, `known: true`, until the list
+		 * brings its own.
+		 */
+		knownItems?: [Known] extends [undefined] ? BbSelectKnownItems : Known;
+		/**
+		 * Display the loading state styles.
+		 */
+		loading?: boolean;
+		/**
+		 * Message shown while items are being loaded.
+		 */
+		loadingText?: string;
+		/**
+		 * Maximum number of selectable items (limits selection when `multiple` is true).
+		 *
+		 * @defaultValue `Infinity`
+		 */
+		max?: number;
+		/**
+		 * v-model value. Single value for single select, array for multiple select.
+		 */
+		modelValue: any;
+		/**
+		 * Debounce delay (ms) for modelValue change handling.
+		 *
+		 * @defaultValue `0`
+		 */
+		modelValueDebounceTime?: number;
+		/**
+		 * Enable multiple item selection. When true, modelValue must be an array.
+		 */
+		multiple?: boolean;
+		/**
+		 * Message displayed when no items are available.
+		 */
+		emptyText?: string;
+		/**
+		 * Message displayed in the empty state while the latest load FAILED (the
+		 * provider threw): the twin of `emptyText` for that case.
+		 *
+		 * @defaultValue the localized `common.failedText` ("Couldn't load items")
+		 */
+		failedText?: string;
+		/**
+		 * Distance (px) between the activator and the popover.
+		 *
+		 * @defaultValue `4`
+		 */
+		offset?: number;
+		/**
+		 * Minimum page padding used by floating shift middleware.
+		 *
+		 * @defaultValue `10`
+		 */
+		padding?: number;
+		/**
+		 * Floating placement of the popover.
+		 *
+		 * @defaultValue `'bottom'`
+		 */
+		placement?: Placement;
+		/**
+		 * When the options first load: `'interaction'` on first open, `true` on
+		 * mount (and in SSR), `false` once the user types (on open with
+		 * `disable-writing` or a non-empty model). An array `items` always
+		 * resolves on mount; else a seeded model's text waits for the first open.
+		 *
+		 * @defaultValue `'interaction'`
+		 */
+		prefill?: boolean | 'interaction';
+		/**
+		 * Debounce delay (ms) before triggering search queries after user input stops.
+		 *
+		 * @defaultValue `500`
+		 */
+		queryDebounceTime?: number;
+		/**
+		 * Prevents opening the popover while keeping the activator accessible.
+		 */
+		readonly?: boolean;
+		/**
+		 * Accessible label used by the search input rendered inside the popover.
+		 * Falls back to the localized `select.searchLabel` key when omitted.
+		 *
+		 * @defaultValue `t('select.searchLabel')` (`'Search options'`)
+		 */
+		searchInputAriaLabel?: string;
+		/**
+		 * Defines whether options are selectable.
+		 * Can be a global boolean that affects all options or a function
+		 * that accepts an item and returns a boolean that only affects that item.
+		 * Non-selectable options are rendered disabled.
+		 *
+		 * @defaultValue `true`
+		 */
+		selectable?: boolean | ((item: Item) => boolean);
+		/**
+		 * Keeps picked options named across searches: a pick stays resolvable when
+		 * a later search or a failed load no longer returns it. It follows the
+		 * model, and does not keep a pick valid: `enforce-coherence` still prunes
+		 * it.
+		 */
+		stash?: boolean;
+		/**
+		 * Transition duration (ms) for popover show/hide animations.
+		 *
+		 * @defaultValue `250`
+		 */
+		transitionDuration?: number;
+		/**
+		 * Width of the popover in pixels, percentage, or `'auto'`. A bare number is
+		 * read as pixels — the default is the string `'200'`, not the number `200`.
+		 *
+		 * @defaultValue `'200'`
+		 */
+		width?: number | string;
+	};
 
 export type BbSelectPopoverEvents = {
 	/** Emitted as soon as the options surface starts to open (the popover, or the sheet on a phone). */
@@ -3821,6 +3891,12 @@ export type BbSelectPopoverPanelSlotProps = {
 	close: () => Promise<void>;
 	/** Clears the current selection. */
 	clear: () => void;
+	/**
+	 * True while the list shows its empty state: no items, none matching the
+	 * query, or a failed load with nothing listed (never while loading). It
+	 * follows the `#empty` slot, so a footer can switch to "Create …".
+	 */
+	empty: boolean;
 	/** Focuses the search input (or the options when writing is disabled). */
 	focus: () => void;
 	/** The current search query string. */
@@ -3867,9 +3943,15 @@ export type BbSelectPopoverSlots<
 	/**
 	 * Content shown when no options match the query or the list is empty.
 	 * `error` is what the latest failed load threw, untouched (`null` when
-	 * none).
+	 * none). `close()` closes the panel, for an action that does not move
+	 * focus out of it.
 	 */
-	empty?: (props: { query: string; focus: () => void; error: unknown }) => any;
+	empty?: (props: {
+		query: string;
+		focus: () => void;
+		close: () => Promise<void>;
+		error: unknown;
+	}) => any;
 	/**
 	 * Replaces the default rendering of each option row in the dropdown. With
 	 * `known-items` bound, a row the list has not brought yet is the known
@@ -3924,6 +4006,14 @@ export type BbSelectPopoverSlots<
 		padding: 0.5rem 0.75rem;
 	}
 
+	/* `compact` steps them down with the rows (28px → 24px): 4px less, split. */
+	&.bb-select-popover--compact {
+		.bb-select-popover__header,
+		.bb-select-popover__footer {
+			padding-block: 0.375rem;
+		}
+	}
+
 	.bb-select-popover__search-icon,
 	.bb-select-popover__search-error-icon,
 	.bb-select-popover__search-warning-icon,
@@ -4479,7 +4569,8 @@ export type BbSelectPopoverSlots<
 	.bb-select-popover__search-container {
 		background-color: var(--bb-muted);
 		border-bottom: 0;
-		border-radius: var(--bb-radius);
+		/* Clamped like the bubble: half a control height at most. */
+		border-radius: min(var(--bb-radius), calc(var(--bb-input-h) / 2));
 		margin-bottom: 0.25rem;
 		padding: 0.625rem 0.75rem;
 		transition: background-color var(--bb-transition-fast) ease;