bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/source/BbSelectPopover.md

@@ -0,0 +1,2234 @@
+# BbSelectPopover — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbSelectPopover.md](../BbSelectPopover.md).
+
+## Template & Script
+
+```vue
+<template>
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: {
+				ref: setActivatorRef,
+			},
+			shown,
+			disabled,
+			readonly,
+			loading: computedLoading,
+			query,
+			selectedOptions: publicSelectedOptions,
+			text: triggerInputValue,
+			clear: onClear,
+			focus: focusPopoverContent,
+			open,
+			close,
+			toggle,
+		}"
+	/>
+
+	<!-- The search field and the options list are authored once here and reused in
+	both surfaces below, so the desktop popover and the mobile off-canvas share the
+	exact same markup, refs and event wiring. -->
+	<DefineSearch>
+		<div
+			v-if="computedAllowWriting"
+			class="bb-select-popover__search-container"
+		>
+			<input
+				:id="`${id}_search`"
+				ref="searchInput"
+				v-model="query"
+				:aria-activedescendant="activeDescendantId"
+				:aria-controls="renderListBox ? `${id}_listbox` : undefined"
+				:aria-describedby="computedAriaDescribedby"
+				:aria-invalid="computedAriaInvalid"
+				:aria-label="searchInputAriaLabel"
+				:autocomplete="autocomplete"
+				class="bb-select-popover__search-input"
+				:inputmode="inputmode"
+				role="searchbox"
+				:tabindex="shown ? 0 : -1"
+				type="text"
+				@blur.stop="onSearchInputBlur"
+				@change.stop="onSearchInputChange"
+				@focus.stop="onSearchInputFocus"
+				@input.stop="onSearchInputInput"
+				@keydown.stop.prevent.down="onArrowDown"
+				@keydown.stop.prevent.enter="onEnter"
+				@keydown.stop.prevent.esc="onEscape"
+				@keydown.stop.prevent.up="onArrowUp"
+			/>
+			<ErrorIcon
+				aria-hidden="true"
+				class="bb-select-popover__search-error-icon"
+				focusable="false"
+			/>
+			<WarningIcon
+				aria-hidden="true"
+				class="bb-select-popover__search-warning-icon"
+				focusable="false"
+			/>
+			<BbIcon
+				aria-hidden="true"
+				class="bb-select-popover__search-icon"
+				focusable="false"
+				:icon="searchIcon"
+			/>
+			<!-- Clearable: the clear button shares the lens' slot in the icon
+			stack. At rest the lens shows; hovering or focusing the search field
+			swaps it for the clear (index.css), but only while there is something
+			to clear (`--clearable-active`). It resets both the query and the
+			selection; `@mousedown.prevent` keeps focus in the field so the swap
+			doesn't collapse mid-click. Reuses the shared ClearableButton so the
+			icon, aria-label fallback and focus ring match every other clear in
+			the library. -->
+			<ClearableButton
+				v-if="clearable"
+				class="bb-select-popover__search-clear"
+				:tabindex="hasClearableValue && shown ? 0 : -1"
+				@click.stop="onSearchClear"
+				@mousedown.prevent
+			/>
+			<!-- Overlays the search field's bottom border while a re-fetch runs over
+			an existing result set — matches BbDropdown's searchable groups. -->
+			<div
+				v-if="isReloading"
+				aria-hidden="true"
+				class="bb-select-popover__search-strip"
+			></div>
+		</div>
+		<button
+			v-else
+			ref="popoverFocusProxy"
+			:aria-activedescendant="activeDescendantId"
+			:aria-controls="`${id}_listbox`"
+			:aria-describedby="computedAriaDescribedby"
+			aria-expanded="true"
+			:aria-invalid="computedAriaInvalid"
+			:aria-label="searchInputAriaLabel"
+			class="bb-select-popover__focus-proxy sr-only"
+			role="combobox"
+			tabindex="-1"
+			type="button"
+			@focus="onPopoverFocusProxyFocus"
+			@keydown.stop.prevent.down="onArrowDown"
+			@keydown.stop.prevent.enter="onEnter"
+			@keydown.stop.prevent.esc="onEscape"
+			@keydown.stop.prevent.up="onArrowUp"
+		></button>
+	</DefineSearch>
+
+	<DefineOptions>
+		<ListBox
+			:id="`${id}_listbox`"
+			ref="optionsContainer"
+			:compact="compact"
+			:groups="groupBy ? groupedOptions : undefined"
+			:header-height="headerHeight"
+			:loading="computedLoading"
+			:loading-text="loadingText"
+			:multiple="multiple"
+			:no-data-text="computedNoDataText"
+			:open="shown"
+			:option-height="itemHeight"
+			:options="groupBy ? undefined : filteredOptions"
+			@focused:change="onListboxFocusedChange"
+			@option:selected="onOptionSelected"
+			@option:unselected="onOptionUnselected"
+		>
+			<template #loading><slot name="loading" :query="query" /></template>
+			<template #no-data
+				><slot :focus="focusPopoverContent" name="no-data" :query="query"
+			/></template>
+			<template #option="data"
+				><slot :loading="computedLoading" name="option" v-bind="data"
+			/></template>
+			<template #group="data"><slot name="group" v-bind="data" /></template>
+		</ListBox>
+	</DefineOptions>
+
+	<!-- Mobile adaptive surface: a bottom sheet that reuses the search + options
+	verbatim and adds a dedicated representation of the current selection (chips for
+	multiple, the selected label for single) between them. -->
+	<BbOffCanvas
+		v-if="useOffcanvas"
+		v-model="shown"
+		class="bb-select-popover-offcanvas"
+		v-bind="{ ...offcanvasBindings, ...$attrs }"
+		@hidden="onOffcanvasHidden"
+	>
+		<template v-if="$slots.header" #header>
+			<slot name="header" v-bind="panelSlotProps" />
+		</template>
+		<div
+			class="bb-select-popover bb-select-popover--sheet"
+			:class="{
+				'bb-select-popover--errors': hasErrors,
+				'bb-select-popover--warnings': showWarning,
+				'bb-select-popover--loading': computedLoading,
+				'bb-select-popover--reloading': isReloading,
+				'bb-select-popover--clearable-active': hasClearableValue,
+			}"
+		>
+			<!-- Current selection sits above the search: chips for multiple (as in the
+			control), a plain label for single. Hidden entirely when nothing is picked. -->
+			<div
+				v-if="selectedOptions.length"
+				class="bb-select-popover__sheet-selection"
+			>
+				<div class="bb-select-popover__sheet-chips">
+					<!-- One badge per selection: removable (clearable) unless the
+					control is disabled/readonly. -->
+					<BbBadge
+						v-for="option in selectedOptions"
+						:key="option.valueHash"
+						class="bb-select-popover__sheet-chip"
+						:clearable="!disabled && !readonly"
+						size="xl"
+						variant="secondary"
+						@click:clear="onOptionUnselected(option)"
+						>{{ option.text }}</BbBadge
+					>
+				</div>
+			</div>
+
+			<ReuseSearch />
+			<BbSmoothHeight>
+				<ReuseOptions />
+			</BbSmoothHeight>
+		</div>
+		<template v-if="$slots.footer" #footer>
+			<slot name="footer" v-bind="panelSlotProps" />
+		</template>
+	</BbOffCanvas>
+
+	<!-- `tag="span"`: this popover is BbBaseSelect's root, so it mounts inside
+	BbBaseInputContainer's inline input wrapper, which only accepts phrasing
+	content. Positioning is unaffected — the wrapper is `position: fixed`. -->
+	<CommonPopover
+		v-else
+		v-model="shown"
+		:anchor="positionAnchorEl"
+		:boundary="boundary"
+		class="bb-select-popover"
+		:class="{
+			'bb-select-popover--errors': hasErrors,
+			'bb-select-popover--warnings': showWarning,
+			'bb-select-popover--loading': computedLoading,
+			'bb-select-popover--reloading': isReloading,
+			'bb-select-popover--clearable-active': hasClearableValue,
+		}"
+		:disable-flip="disableFlip"
+		hide-arrow
+		:offset="offset"
+		:padding="padding"
+		:placement="placement"
+		:style="panelStyles"
+		tag="span"
+		:transition-duration="transitionDuration"
+		v-bind="$attrs"
+	>
+		<div
+			v-if="$slots.header"
+			class="bb-select-popover__header"
+			:inert="panelChromeInert"
+		>
+			<slot name="header" v-bind="panelSlotProps" />
+		</div>
+		<ReuseSearch />
+		<ReuseOptions />
+		<div
+			v-if="$slots.footer"
+			class="bb-select-popover__footer"
+			:inert="panelChromeInert"
+		>
+			<slot name="footer" v-bind="panelSlotProps" />
+		</div>
+	</CommonPopover>
+</template>
+
+<script setup lang="ts" generic="Item = any">
+import type { Option as BaseOption, GroupedOptions } from '@/types/Option';
+import {
+	computed,
+	ref,
+	nextTick,
+	watch,
+	onBeforeMount,
+	onBeforeUnmount,
+} from 'vue';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import { get } from '@/utilities/functions/get';
+import { hash } from '@/utilities/functions/hash';
+import { useLogger } from '@/composables/useLogger';
+import { isNil } from '@/utilities/functions/isNil';
+import { matchAnyKey } from '@/utilities/functions/matchAnyKey';
+import { parseWidthString } from '@/utilities/functions/parseWidthString';
+import { toRef } from 'vue';
+import { useArray } from '@/composables/useArray';
+import { useBaseOptions } from '@/composables/useBaseOptions';
+import { useCoherence } from '@/composables/useCoherence';
+import {
+	createReusableTemplate,
+	useElementSize,
+	useIntersectionObserver,
+} from '@vueuse/core';
+import { useHashedWatcher } from '@/composables/useHashedWatcher';
+import { useId } from '@/composables/useId';
+import { useIndexById } from '@/composables/useIndexById';
+import { useItemsGetter } from '@/composables/useItemsGetter';
+import { useLocale } from '@/composables/useLocale';
+import { useMobile } from '@/composables/useMobile';
+import { usePrefill } from '@/composables/usePrefill';
+import { config } from 'virtual:bitboss-ui/config';
+import { useUntil } from '@/composables/useUntil';
+import { useClosingInert } from '@/composables/useClosingInert';
+import { wait } from '@/utilities/functions/wait';
+import BbBadge from '../BbBadge/BbBadge.vue';
+import BbIcon from '../BbIcon/BbIcon.vue';
+import BbOffCanvas from '../BbOffCanvas/BbOffCanvas.vue';
+import ClearableButton from '../ClearableButton/ClearableButton.vue';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import ErrorIcon from '../ErrorIcon/ErrorIcon.vue';
+import WarningIcon from '../WarningIcon/WarningIcon.vue';
+import searchIcon from '@/assets/svgs/search.svg?raw';
+import ListBox from '../ListBox/ListBox.vue';
+import { waitFor } from '@/utilities/functions/waitFor';
+import type {
+	BbSelectPopoverEvents,
+	BbSelectPopoverProps,
+	BbSelectPopoverSlots,
+	BbSelectResolvedOption,
+} from './types';
+import BbSmoothHeight from '../BbSmoothHeight/BbSmoothHeight.vue';
+import { transitions } from '@/utilities/misc/transitions';
+import { removedPropsFor } from '@/deprecation/removedProps';
+import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+
+const props = withDefaults(defineProps<BbSelectPopoverProps<Item>>(), {
+	// `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: () => [],
+	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>();
+
+defineSlots<BbSelectPopoverSlots<Item>>();
+
+if (process.env.NODE_ENV !== 'production')
+	warnRemovedAttrs('BbSelectPopover', removedPropsFor('BbSelectPopover'));
+
+/**
+ * Author the search field and the options list once, replay them in both the
+ * desktop popover and the mobile sheet. `ReuseSearch`/`ReuseOptions` render the
+ * captured markup inline (with the component's own refs, slots and handlers), so
+ * only ever one live instance exists at a time — the branch that is mounted.
+ */
+const [DefineSearch, ReuseSearch] = createReusableTemplate();
+const [DefineOptions, ReuseOptions] = createReusableTemplate();
+
+// Guard in `onBeforeMount` (not the setup body): the dev error still throws
+// synchronously during mount, but letting setup finish first means Vue never
+// attempts the partial render of an errored instance whose `<script setup>`
+// bindings (component imports, reusable-template handles) are all undefined —
+// which would otherwise log spurious "Invalid vnode type: undefined" warnings.
+onBeforeMount(() => {
+	if (props.multiple && !Array.isArray(props.modelValue)) {
+		useLogger().throw(
+			`BbSelectPopover: \`multiple\` requires an array modelValue, received ${
+				props.modelValue === null ? 'null' : typeof props.modelValue
+			}. Seed it with \`[]\` for an empty selection — \`null\`/\`undefined\` are not accepted, ` +
+				'because a multi-select with no array has no way to express "nothing selected" separately from "not ready".'
+		);
+	}
+});
+
+/**
+ * START ELEMENT REFERENCES
+ */
+const activatorEl = ref<HTMLElement>();
+const optionsContainer = ref<any | null>(null);
+const searchInput = ref<HTMLInputElement | null>(null);
+const popoverFocusProxy = ref<HTMLButtonElement | null>(null);
+const activeDescendantId = ref<string>();
+
+const positionAnchorEl = computed<HTMLElement | undefined>(() => {
+	if (props.anchor) {
+		const el = extractDomContainer(props.anchor);
+		if (el) return el;
+	}
+	return activatorEl.value;
+});
+
+const { width: activatorWidth } = useElementSize(
+	positionAnchorEl,
+	{ width: 0, height: 0 },
+	{
+		box: 'border-box',
+	}
+);
+
+/**
+ * END ELEMENT REFERENCES
+ */
+
+/**
+ * START ACTIVATOR MANAGEMENT
+ */
+const hasExternalActivator = computed(() => props.activator != null);
+
+const setActivatorRef = (reference: unknown) => {
+	const el = extractDomContainer(reference);
+	if (!el) return;
+	activatorEl.value = el;
+};
+
+watch(
+	() => props.activator,
+	(val) => {
+		if (val) setActivatorRef(val);
+	},
+	{ immediate: true }
+);
+/**
+ * END ACTIVATOR MANAGEMENT
+ */
+
+const { isMobile } = useMobile();
+const computedAllowWriting = computed(() => {
+	if (props.disableWriting === 'mobile') return !isMobile.value;
+	if (props.disableWriting === 'desktop') return isMobile.value;
+	return !props.disableWriting;
+});
+const inputmode = computed(() =>
+	(props.disableWriting === 'mobile' && isMobile.value) ||
+	(props.disableWriting === 'desktop' && !isMobile.value)
+		? 'none'
+		: undefined
+);
+const { t } = useLocale();
+const searchInputAriaLabel = computed(
+	() => props.searchInputAriaLabel ?? t('select.searchLabel').value
+);
+// The in-search clear affordance only lights up when there is something to
+// clear — a typed query or an actual selection — so an empty clearable popover
+// keeps showing the lens. `--clearable-active` (below) is what CSS keys the
+// lens→clear swap off; the button itself is always rendered when `clearable`
+// so the fade has an element to transition.
+const hasClearableValue = computed(
+	() =>
+		!!props.clearable &&
+		(query.value.length > 0 ||
+			(props.multiple
+				? Array.isArray(props.modelValue) && props.modelValue.length > 0
+				: !isNil(props.modelValue)))
+);
+
+const id = props.id || useId().id.value;
+const computedAriaInvalid = computed(() => {
+	const isInvalid = props.ariaInvalid ?? !!props.hasErrors;
+	return isInvalid ? 'true' : undefined;
+});
+const computedAriaDescribedby = computed(() => {
+	const describedBy = props.ariaDescribedby;
+	if (Array.isArray(describedBy)) {
+		const normalized = describedBy
+			.map((value) => value.trim())
+			.filter(Boolean)
+			.join(' ');
+		return normalized || undefined;
+	}
+	if (typeof describedBy === 'string') {
+		const normalized = describedBy.trim();
+		return normalized || undefined;
+	}
+	return undefined;
+});
+
+const { resume, pause } = useIntersectionObserver(
+	activatorEl,
+	async ([{ intersectionRatio }]) => {
+		if (intersectionRatio !== 1 && shown.value) {
+			await close();
+		}
+	},
+	{ threshold: [0, 1], immediate: false }
+);
+
+const normalizedWidth = computed(() => {
+	if (props.width === 'auto') return 'auto';
+	if (props.width == null || props.width === '') {
+		return activatorWidth.value ? `${activatorWidth.value}px` : '320px';
+	}
+
+	try {
+		const { value, unit } = parseWidthString(props.width);
+		if (unit === '%') {
+			if (!activatorWidth.value) return '320px';
+			return `${activatorWidth.value * (value / 100)}px`;
+		}
+		return `${value}${unit}`;
+	} catch {
+		if (typeof props.width === 'string') return props.width.trim();
+		return activatorWidth.value ? `${activatorWidth.value}px` : '320px';
+	}
+});
+
+const panelStyles = computed(() => ({
+	'--w': normalizedWidth.value,
+}));
+
+/**
+ * START FOCUS HELPERS
+ */
+const focusActivator = () => {
+	activatorEl.value?.focus();
+};
+const focusSearchInput = () => {
+	if (searchInput.value instanceof HTMLInputElement) {
+		searchInput.value.focus();
+	}
+};
+const focusPopoverFocusProxy = () => {
+	if (popoverFocusProxy.value instanceof HTMLButtonElement) {
+		popoverFocusProxy.value.focus();
+	}
+};
+const focusPopoverContent = () => {
+	if (computedAllowWriting.value) {
+		focusSearchInput();
+		return;
+	}
+	focusPopoverFocusProxy();
+};
+/**
+ * END FOCUS HELPERS
+ */
+
+/**
+ * Search input focus keeps the whole control in active state.
+ */
+const onSearchInputFocus = (event: FocusEvent) => {
+	emit('focus', event);
+	setActive();
+};
+
+const onSearchInputBlur = (event: FocusEvent) => {
+	emit('blur', event);
+	syncActiveStateOnBlur();
+};
+
+const onSearchInputChange = (event: Event) => {
+	emit('change', event);
+};
+
+const onPopoverFocusProxyFocus = (_event: FocusEvent) => {
+	setActive();
+};
+
+/**
+ * Search on user typing inside the popover search field.
+ */
+const onSearchInputInput = (event: Event) => {
+	emit('input', event);
+	// A user search is a first load like any other, so unlock `canLoad` — without
+	// this a search-first instance (whose `prefill` trigger is false by design)
+	// would never engage its dependency/model watchers, and results would go stale
+	// the moment a dependency changed. Marked on dispatch rather than completion:
+	// `debouncedGetter`'s superseded calls resolve too (VueUse settles them with
+	// `undefined` when `rejectOnCancel` is off), so awaiting it cannot tell a real
+	// load from a debounced-away keystroke. No-op in every other prefill mode,
+	// where opening has already prefilled.
+	markPrefilled();
+	debouncedGetter(query.value, false, props.modelValue);
+};
+
+const onListboxFocusedChange = (id: string | undefined) => {
+	activeDescendantId.value = id;
+};
+
+/**
+ * On click outside of the activator and popover, close the panel and remove active state.
+ */
+const onOutsideInteraction = async (event: Event) => {
+	const target =
+		event.target instanceof Element
+			? event.target
+			: event.target instanceof Text
+				? event.target.parentElement
+				: null;
+	if (!target) return;
+	const insideActivator = positionAnchorEl.value?.contains(target);
+	const insidePopover = !!target.closest('.bb-common-popover');
+	if (insideActivator || insidePopover) return;
+	const label =
+		target instanceof HTMLLabelElement ? target : target.closest('label');
+	if (label?.control && positionAnchorEl.value?.contains(label.control)) return;
+	await close();
+	setInactive();
+};
+
+const canProcessKeyboardBindings = computed(() => {
+	if (props.readonly) return false;
+	if (props.disabled) return false;
+	if (computedLoading.value) return false;
+	return true;
+});
+
+/**
+ * On first open the listbox is lazily mounted.
+ * Wait a few micro-cycles so imperative focus calls don't no-op.
+ */
+const waitForOptionsContainer = async () =>
+	waitFor(() => !!optionsContainer.value, { interval: 100 });
+
+const focusFirstSelectedOption = () => {
+	const firstSelected = selectedOptions.value[0];
+	if (firstSelected?.valueHash) {
+		optionsContainer.value?.focusByHash(firstSelected.valueHash);
+		return;
+	}
+	optionsContainer.value?.focusFirstSelected();
+};
+
+const focusLastSelectedOption = () => {
+	const lastSelected = selectedOptions.value[selectedOptions.value.length - 1];
+	if (lastSelected?.valueHash) {
+		optionsContainer.value?.focusByHash(lastSelected.valueHash);
+		return;
+	}
+	optionsContainer.value?.focusLastSelected();
+};
+
+/**
+ * On arrow up:
+ * When the panel is open — focus on the previous option
+ * When the panel is closed — open and focus on the last selected option
+ */
+const onArrowUp = async () => {
+	if (!canProcessKeyboardBindings.value) return;
+	if (shown.value) {
+		optionsContainer.value?.focusPrevious();
+	} else {
+		await open({ focusPopoverContent: false });
+		await waitForOptionsContainer();
+		await wait(props.transitionDuration);
+		focusLastSelectedOption();
+	}
+};
+
+const onArrowDown = async () => {
+	if (!canProcessKeyboardBindings.value) return;
+	if (shown.value) {
+		optionsContainer.value?.focusNext();
+	} else {
+		await open({ focusPopoverContent: false });
+		await waitForOptionsContainer();
+		await wait(props.transitionDuration);
+		focusFirstSelectedOption();
+	}
+};
+
+const onEnter = async () => {
+	if (!canProcessKeyboardBindings.value) {
+		return;
+	}
+	if (!shown.value) {
+		await open({ focusPopoverContent: false });
+		await waitForOptionsContainer();
+		await wait(props.transitionDuration);
+		if (selectedOptions.value.length) {
+			focusFirstSelectedOption();
+		} else if (computedAllowWriting.value) {
+			focusSearchInput();
+		} else {
+			focusPopoverFocusProxy();
+		}
+		return;
+	} else if (optionsContainer.value?.getHighlighted()) {
+		optionsContainer.value.confirmOption();
+		return;
+	}
+	if (!computedAllowWriting.value) return;
+	const text = query.value.trim();
+	if (isItemSelected(text)) return;
+	emit('option:add', text);
+	query.value = '';
+};
+
+const onEscape = async () => {
+	if (shown.value) {
+		await close();
+		focusActivator();
+	}
+};
+
+const query = ref<string>('');
+const hasInteracted = ref(false);
+
+const {
+	getter,
+	debouncedGetter,
+	items: internalItems,
+	loading,
+} = useItemsGetter({
+	items: toRef(props, 'items'),
+	debounce: props.queryDebounceTime,
+});
+
+const {
+	array: innerStash,
+	add: addToStash,
+	remove: removeFromStash,
+	set: setStash,
+} = useArray<BaseOption>();
+
+/** Whether the model currently holds anything (an empty model is always coherent). */
+const hasModelValue = computed(() =>
+	props.multiple
+		? !!(props.modelValue as unknown[])?.length
+		: !isNil(props.modelValue)
+);
+
+/**
+ * Search-first: the user must type before anything is fetched — opening the
+ * panel alone does not. Only for a *provider* with `prefill: false`, writing
+ * allowed and an empty model, because each of those is what makes deferring
+ * safe: an array costs no network (E1 rule 1), a seeded model needs its text
+ * resolved to render (and `BbBaseSelect` already forces `prefill: true` for it),
+ * and with writing disabled the search field is hidden — so a load the user
+ * cannot trigger would leave them staring at an empty panel forever.
+ */
+const isSearchFirst = computed(
+	() =>
+		props.prefill === false &&
+		!Array.isArray(props.items) &&
+		computedAllowWriting.value &&
+		!hasModelValue.value
+);
+
+/** The hint replaces "no data" only while nothing has been searched for yet. */
+const computedNoDataText = computed(() =>
+	isSearchFirst.value && !query.value
+		? t('select.searchToStart').value
+		: props.noDataText
+);
+
+const {
+	hasPrefilled,
+	isPrefilling,
+	canLoad,
+	prefill: prefillItems,
+	markPrefilled,
+} = usePrefill({
+	trigger: computed(
+		() =>
+			// Array `items` are never lazy: there is no request to defer, so waiting
+			// buys nothing and costs correctness — the selection stays unresolved
+			// (empty `text`/`selectedOptions`) and coherence cannot run. Resolving
+			// costs no network, so do it now regardless of `prefill`.
+			Array.isArray(props.items) ||
+			props.prefill === true ||
+			// Opting into `enforce-coherence` with a seeded model is a request to
+			// validate it, which is impossible without options — so load. An empty
+			// model needs no check and stays lazy.
+			(props.enforceCoherence && hasModelValue.value) ||
+			(props.prefill === 'interaction' && hasInteracted.value)
+	),
+	currentValue: undefined,
+	multiple: false,
+	fn: async (isPrefill) => {
+		await getter(query.value, isPrefill, props.modelValue);
+		if (props.stash) {
+			// Stash only the *selected* options this load resolved — the pre-seeded
+			// model items that happen to be in the fetch — so they stay resolvable
+			// when a later search/dependency no longer returns them. Stashing every
+			// fetched option (the previous behavior) hoarded rows the user never
+			// picked and contradicted `stash`'s own contract ("accumulate selected
+			// values across searches").
+			addToStash(...options.value.filter((o) => o.selected).map((o) => o.item));
+		}
+		// The first load is a load: check now rather than waiting for some later
+		// change. Without this the two watchers below only ever fire on a *change*,
+		// so a seeded-but-invalid model would survive until something else moved.
+		if (props.enforceCoherence && !coherent.value) {
+			emit('update:modelValue', coherentValue.value);
+		}
+	},
+});
+
+const { data: modelValueIndexedByHash, get: isItemSelected } = useIndexById({
+	items: computed(() => [].concat(props.modelValue)),
+});
+
+const { options } = useBaseOptions({
+	disabled: toRef(props, 'disabled'),
+	items: computed(() => [...internalItems.value, ...innerStash.value]),
+	itemText: props.itemText,
+	itemValue: props.itemValue,
+	max: props.max,
+	selectable: toRef(props, 'selectable'),
+	selectedIndexedByHash: modelValueIndexedByHash,
+});
+
+const { data: optionsIndexedByHash } = useIndexById({
+	items: options,
+	key: 'valueHash',
+});
+
+const { coherent, coherentValue } = useCoherence({
+	modelValue: toRef(props, 'modelValue'),
+	multiple: props.multiple,
+	iteratee: (item) => !!optionsIndexedByHash.value[hash(item)],
+});
+
+const selectedOptions = computed<BaseOption[]>(() =>
+	([] as any[])
+		.concat(props.modelValue)
+		.map((v) => optionsIndexedByHash.value[hash(v)])
+		.filter(Boolean)
+);
+
+/**
+ * Explicit allowlist mapping the internal `Option` to the public shape handed to
+ * consumer slots (`activator`, `header`, `footer`). Picking fields by hand — as
+ * opposed to passing the raw option — keeps `valueHash` (and anything added to
+ * the internal option later) from leaking into the public contract, so callers
+ * can never come to depend on selection internals.
+ */
+const toPublicOption = (
+	option: BaseOption<Item>
+): BbSelectResolvedOption<Item> => ({
+	item: option.item,
+	text: option.text,
+	value: option.value,
+	selected: option.selected ?? true,
+	disabled: option.disabled ?? false,
+});
+
+const publicSelectedOptions = computed<Array<BbSelectResolvedOption<Item>>>(
+	() => selectedOptions.value.map(toPublicOption)
+);
+
+const computedLoading = computed(() => !!(loading.value || props.loading));
+/**
+ * A re-fetch running over an existing result set — the options stay on screen
+ * (faint, under a loading strip) instead of a spinner, matching BbDropdown's
+ * searchable groups. A first load (no options yet) shows the listbox's loading
+ * row instead.
+ */
+const isReloading = computed(
+	() => computedLoading.value && options.value.length > 0
+);
+const hasErrors = computed(() => !!props.hasErrors);
+/** Warning chrome only when no error is claiming the same icon slot. */
+const showWarning = computed(
+	() => Boolean(props.hasWarning) && !hasErrors.value
+);
+const triggerInputValue = computed(() => {
+	return (
+		selectedOptions.value
+			.map((option) => option.text)
+			.filter(Boolean)
+			.join(', ') || ''
+	);
+});
+
+useHashedWatcher(
+	() => props.modelValue,
+	async () => {
+		if (!canLoad.value) return;
+		if (!coherent.value) {
+			await getter(query.value, true, props.modelValue);
+			if (props.enforceCoherence) {
+				emit('update:modelValue', coherentValue.value);
+				optionsContainer.value?.blur();
+			}
+		}
+	},
+	{ debounce: props.modelValueDebounceTime }
+);
+useHashedWatcher(
+	() => [props.dependencies, props.items],
+	async () => {
+		if (!canLoad.value) return;
+		await getter(query.value, true, props.modelValue);
+		if (props.enforceCoherence && !coherent.value) {
+			emit('update:modelValue', coherentValue.value);
+			optionsContainer.value?.blur();
+		}
+	},
+	{ debounce: props.depsDebounceTime }
+);
+
+const onOptionSelected = async (option: BaseOption) => {
+	if (props.multiple) {
+		emit('update:modelValue', props.modelValue.concat(option.value));
+		if (props.stash) {
+			addToStash(option.item);
+		}
+	} else {
+		if (props.stash) {
+			setStash(option.item);
+		}
+		emit('update:modelValue', option.value);
+		await nextTick();
+	}
+	if (props.multiple && computedAllowWriting.value && shown.value) {
+		focusSearchInput();
+	} else {
+		focusActivator();
+	}
+	if (!props.multiple) {
+		close();
+	}
+};
+
+const onOptionUnselected = async (option: BaseOption) => {
+	// Single select: clicking the option that is already selected is not a
+	// request to empty the field — it picks what is already picked, so the panel
+	// simply closes on the value it has. Emptying is an explicit affordance (the
+	// clear button, or the `clear` callback on the activator/panel slots), never
+	// an accidental second click. Multiple mode still toggles: there, unselecting
+	// by clicking is the whole interaction.
+	if (!props.multiple) {
+		focusActivator();
+		close();
+		return;
+	}
+
+	removeFromStash((o) => o.valueHash !== option.valueHash);
+	const copy = { ...modelValueIndexedByHash.value };
+	delete copy[option.valueHash];
+	emit('update:modelValue', Object.values(copy));
+
+	if (computedAllowWriting.value && shown.value) {
+		focusSearchInput();
+	} else {
+		focusActivator();
+	}
+};
+
+/**
+ * Filter options based on the current query.
+ */
+const filteredOptions = computed<Array<BaseOption<Item>>>(() => {
+	if (!query.value) return options.value;
+	if (!props.multiple) {
+		const queryMatchesASelectedOption = selectedOptions.value.some(
+			(option: BaseOption) => option.text === query.value
+		);
+		if (queryMatchesASelectedOption) return options.value;
+	}
+	const q = query.value.trim();
+	if (props.filterBy.length) {
+		return options.value.filter((item: BaseOption) =>
+			matchAnyKey(item.item, props.filterBy, q)
+		);
+	}
+	return options.value.filter((item: BaseOption) =>
+		matchAnyKey(item, ['text'], q)
+	);
+});
+
+const defaultGroupSymbol = Symbol('default');
+
+const getGroupData = (option: BaseOption) => {
+	if (isNil(props.groupBy)) return defaultGroupSymbol;
+	if (typeof props.groupBy === 'function') return props.groupBy(option.item);
+	return (get as any)(option.item, props.groupBy);
+};
+
+const groupedOptions = computed<GroupedOptions[]>(() => {
+	const groupIndex: Record<GroupedOptions['id'], GroupedOptions> = {};
+	for (const option of filteredOptions.value) {
+		const groupData = getGroupData(option);
+		const groupId = hash(groupData);
+		if (!groupIndex[groupId]) {
+			groupIndex[groupId] = {
+				id: groupId,
+				data: groupData ?? null,
+				options: [],
+			};
+		}
+		groupIndex[groupId].options.push(option);
+	}
+	return Object.values(groupIndex).filter((g) => g.options.length);
+});
+
+/**
+ * START POPOVER STATE
+ */
+const shown = ref(false);
+const renderListBox = useUntil(shown);
+/**
+ * `shown` is the open model — it flips the instant the panel starts closing, so
+ * binding `:inert` straight off it stripped the still-fading header/footer from
+ * the accessibility tree mid-animation. This trails CommonPopover's fade-out
+ * (same `transitionDuration`) and only then goes inert.
+ */
+const panelChromeInert = useClosingInert(shown, () => props.transitionDuration);
+
+/**
+ * START ADAPTIVE SURFACE
+ * On mobile with `adaptive`, the panel becomes a bottom off-canvas sheet instead
+ * of a floating popover. The surface is latched when the panel opens and frozen
+ * until it closes, so a mid-session resize never swaps a live popover into a sheet
+ * (or vice-versa) — mirroring BbPopover/BbDropdown/BbDialog.
+ */
+const resolveSurface = (): 'popover' | 'canvas' =>
+	(props.adaptive ?? config.adaptive) && isMobile.value ? 'canvas' : 'popover';
+const surface = ref<'popover' | 'canvas'>(resolveSurface());
+const useOffcanvas = computed(() => surface.value === 'canvas');
+
+// While closed, keep tracking the viewport so the next open resolves correctly;
+// while open the surface stays frozen.
+watch([() => props.adaptive, isMobile, shown], () => {
+	if (!shown.value) surface.value = resolveSurface();
+});
+
+const offcanvasBindings = computed(() => ({
+	side: 'bottom' as const,
+	size: 'auto' as const,
+	draggable: true,
+	// In sheet mode skip selected chips: focus the search field when writable,
+	// otherwise land on the first interactive option for immediate keyboard nav.
+	focusTarget: computedAllowWriting.value
+		? '.bb-select-popover__search-input'
+		: '.bb-listbox__option[role="option"]:not(.autocomplete-option--disabled), .bb-select-popover__focus-proxy',
+	disabled: props.disabled,
+	transitionDuration: props.transitionDuration,
+	// `width` is intentionally not forwarded — a sheet spans the viewport width.
+	...props.offCanvasProps,
+}));
+/**
+ * END ADAPTIVE SURFACE
+ */
+
+const open = async ({
+	focusPopoverContent = true,
+}: { focusPopoverContent?: boolean } = {}) => {
+	if (props.disabled || props.readonly) return;
+	if (shown.value) return;
+	// Latch the surface for this open cycle before anything reads it.
+	surface.value = resolveSurface();
+	hasInteracted.value = true;
+	shown.value = true;
+
+	// Search-first defers the one-time initial fetch to the first query, so
+	// opening must not perform it — this is the only thing separating
+	// `prefill: false` from `'interaction'`.
+	if (!hasPrefilled.value && !isPrefilling.value && !isSearchFirst.value) {
+		await prefillItems();
+		// close() may have run during the fetch — attaching listeners or
+		// stealing focus now would act on a closed popover.
+		if (!shown.value) return;
+	}
+
+	await nextTick();
+	if (!shown.value) return;
+
+	// The off-canvas sheet is modal and manages its own backdrop, Escape and focus
+	// — skip the floating-panel document listeners and the activator visibility watch.
+	if (useOffcanvas.value) return;
+
+	resume();
+	document.addEventListener('click', onOutsideInteraction);
+	document.addEventListener('focusin', onOutsideInteraction);
+
+	if (!focusPopoverContent) return;
+
+	await wait(0);
+	if (!shown.value) return;
+	if (computedAllowWriting.value) {
+		focusSearchInput();
+	} else {
+		focusPopoverFocusProxy();
+	}
+};
+
+const close = async () => {
+	if (!shown.value) return;
+	shown.value = false;
+	optionsContainer.value?.blur();
+	activeDescendantId.value = undefined;
+	query.value = '';
+
+	// In sheet mode `onOffcanvasHidden` runs the rest of the teardown once the close
+	// transition finishes; the flyout's document listeners were never attached.
+	if (useOffcanvas.value) return;
+
+	pause();
+	document.removeEventListener('click', onOutsideInteraction);
+	document.removeEventListener('focusin', onOutsideInteraction);
+};
+
+/**
+ * The sheet can also close itself (backdrop tap, drag-to-dismiss, Escape) by
+ * flipping the `shown` model without going through `close()`. Run the shared
+ * teardown after its close transition and return focus to the activator.
+ */
+const onOffcanvasHidden = () => {
+	optionsContainer.value?.blur();
+	activeDescendantId.value = undefined;
+	query.value = '';
+	setInactive();
+	focusActivator();
+};
+
+const toggle = () => {
+	if (shown.value) return close();
+	return open();
+};
+/**
+ * END POPOVER STATE
+ */
+
+/**
+ * START ACTIVE STATE
+ * Tracks whether the user is inside this whole component.
+ * We cannot use :focus-within as it doesn't work for teleported elements.
+ */
+const active = ref(false);
+
+const setActive = () => {
+	if (active.value) return;
+	active.value = true;
+	emit('active');
+};
+const setInactive = () => {
+	if (!active.value) return;
+	active.value = false;
+	emit('inactive');
+};
+
+const isFocusInsideComponent = (target: EventTarget | null) => {
+	if (!(target instanceof Node)) return false;
+	const insideActivator = !!activatorEl.value?.contains(target);
+	const insidePopover = !!optionsContainer.value?.$el
+		?.closest('.bb-common-popover')
+		?.contains(target);
+	return insideActivator || insidePopover;
+};
+
+let blurSyncTimer: ReturnType<typeof setTimeout> | undefined;
+const syncActiveStateOnBlur = () => {
+	clearTimeout(blurSyncTimer);
+	blurSyncTimer = setTimeout(() => {
+		if (shown.value) {
+			setActive();
+			return;
+		}
+		if (isFocusInsideComponent(document.activeElement)) {
+			setActive();
+			return;
+		}
+		setInactive();
+	}, 0);
+};
+/**
+ * END ACTIVE STATE
+ */
+
+const onClear = () => {
+	emit('update:modelValue', props.multiple ? [] : null);
+};
+
+// The in-search clear button resets the whole search state — both the typed
+// query and the selection — matching the searchbox affordance it sits in.
+// `@mousedown.prevent` on the button keeps focus in the input, so clearing
+// doesn't bounce focus out of the popover.
+const onSearchClear = () => {
+	query.value = '';
+	onClear();
+};
+
+/**
+ * Props exposed to the `header` / `footer` slots — identical in both the desktop
+ * popover and the adaptive sheet, so a consumer's slot markup works unchanged
+ * across surfaces.
+ */
+const panelSlotProps = computed(() => ({
+	close,
+	clear: onClear,
+	focus: focusPopoverContent,
+	query: query.value,
+	selectedOptions: publicSelectedOptions.value,
+}));
+
+/**
+ * START ACTIVATOR LISTENERS
+ * Programmatically attach accessibility attributes and event listeners
+ * to the activator element, following the BbDropdown pattern.
+ */
+let cleanupActivator: (() => void) | null = null;
+
+watch(
+	activatorEl,
+	(el) => {
+		if (cleanupActivator) {
+			cleanupActivator();
+			cleanupActivator = null;
+		}
+		if (!el) return;
+
+		el.setAttribute('role', 'combobox');
+		el.setAttribute('aria-haspopup', 'listbox');
+
+		const handleClick = async (event: MouseEvent) => {
+			emit('click', event);
+			if (props.disabled) return;
+			event.preventDefault();
+			if (props.readonly) {
+				focusActivator();
+				return;
+			}
+			if (shown.value) {
+				await close();
+				focusActivator();
+				return;
+			}
+			await open();
+		};
+
+		const handlePointerDown = (event: PointerEvent) => {
+			if (!props.readonly || props.disabled) return;
+			// Keep focus/ring stable during press in readonly mode.
+			event.preventDefault();
+			setActive();
+			focusActivator();
+		};
+
+		const handleKeydown = (event: KeyboardEvent) => {
+			switch (event.key) {
+				case 'ArrowDown':
+					event.preventDefault();
+					onArrowDown();
+					break;
+				case 'ArrowUp':
+					event.preventDefault();
+					onArrowUp();
+					break;
+				case 'Enter':
+					event.preventDefault();
+					onEnter();
+					break;
+				case 'Escape':
+					if (shown.value) {
+						event.preventDefault();
+						onEscape();
+					}
+					break;
+			}
+		};
+
+		const handleFocus = (event: FocusEvent) => {
+			emit('focus', event);
+			setActive();
+		};
+
+		const handleBlur = (event: FocusEvent) => {
+			emit('blur', event);
+			syncActiveStateOnBlur();
+		};
+
+		el.addEventListener('click', handleClick);
+		el.addEventListener('pointerdown', handlePointerDown);
+		el.addEventListener('keydown', handleKeydown);
+		el.addEventListener('focus', handleFocus);
+		el.addEventListener('blur', handleBlur);
+
+		cleanupActivator = () => {
+			el.removeEventListener('click', handleClick);
+			el.removeEventListener('pointerdown', handlePointerDown);
+			el.removeEventListener('keydown', handleKeydown);
+			el.removeEventListener('focus', handleFocus);
+			el.removeEventListener('blur', handleBlur);
+			el.removeAttribute('role');
+			el.removeAttribute('aria-haspopup');
+			el.removeAttribute('aria-expanded');
+			el.removeAttribute('aria-controls');
+			el.removeAttribute('aria-invalid');
+			el.removeAttribute('aria-describedby');
+			el.removeAttribute('aria-valuetext');
+			el.removeAttribute('aria-activedescendant');
+		};
+	},
+	{ immediate: true }
+);
+
+watch(
+	[
+		activatorEl,
+		shown,
+		renderListBox,
+		computedAriaInvalid,
+		computedAriaDescribedby,
+		triggerInputValue,
+		activeDescendantId,
+	] as const,
+	([
+		el,
+		isShown,
+		hasListBox,
+		ariaInvalid,
+		ariaDescribedby,
+		triggerText,
+		descendantId,
+	]) => {
+		if (!el) return;
+		el.setAttribute('aria-expanded', String(isShown));
+		if (ariaInvalid != null) {
+			el.setAttribute('aria-invalid', ariaInvalid);
+		} else {
+			el.removeAttribute('aria-invalid');
+		}
+		if (hasListBox) {
+			el.setAttribute('aria-controls', `${id}_listbox`);
+		} else {
+			el.removeAttribute('aria-controls');
+		}
+		if (ariaDescribedby != null) {
+			el.setAttribute('aria-describedby', ariaDescribedby);
+		} else {
+			el.removeAttribute('aria-describedby');
+		}
+		if (triggerText) {
+			el.setAttribute('aria-valuetext', triggerText);
+		} else {
+			el.removeAttribute('aria-valuetext');
+		}
+		if (isShown && descendantId) {
+			el.setAttribute('aria-activedescendant', descendantId);
+		} else {
+			el.removeAttribute('aria-activedescendant');
+		}
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	clearTimeout(blurSyncTimer);
+	cleanupActivator?.();
+	document.removeEventListener('click', onOutsideInteraction);
+	document.removeEventListener('focusin', onOutsideInteraction);
+});
+/**
+ * END ACTIVATOR LISTENERS
+ */
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { Placement } from '@/types/Placement';
+import type { ItemAccessor } from '@/types/ItemAccessor';
+import type { BbOffCanvasProps } from '../BbOffCanvas/types';
+
+/**
+ * A selected option as resolved by the select family and exposed through slot
+ * props (`selectedOptions`): the raw source `item` plus its resolved display
+ * `text` / `value` and its `selected` / `disabled` state.
+ *
+ * This is a hand-picked public shape, produced by an explicit mapper in the
+ * component — the internal `valueHash` (and any future internal field on the
+ * underlying option) is intentionally NOT exposed, so consumers cannot come to
+ * depend on selection internals.
+ */
+export type BbSelectResolvedOption<Item = any> = {
+	/** The raw source item from the `items` prop. */
+	item: Item;
+	/** The resolved display text for this option. */
+	text: string;
+	/** The resolved value for this option. */
+	value: any;
+	/** Whether this option is currently selected. */
+	selected: boolean;
+	/** Whether this option is disabled. */
+	disabled: boolean;
+};
+
+export type BbSelectPopoverProps<Item> = {
+	/**
+	 * 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;
+	/**
+	 * When `true`, the panel opens as a bottom off-canvas sheet on mobile viewports
+	 * instead of a floating popover; on desktop it stays a popover. The sheet reuses
+	 * the same search field and options list, adding a representation of the current
+	 * selection between them. Mirrors the adaptive behaviour of `BbPopover`/`BbDropdown`.
+	 *
+	 * When unset, falls back to the global `config.adaptive`.
+	 * @defaultValue `config.adaptive` (`true`)
+	 */
+	adaptive?: boolean;
+	/**
+	 * Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on
+	 * mobile (e.g. `size`, `draggable`, `fullscreen`, `stack`).
+	 */
+	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;
+	/**
+	 * Controls whether the search input is shown inside the popover panel.
+	 * Use `'mobile'` to hide the search input on mobile, `'desktop'` to hide it on desktop.
+	 *
+	 * @defaultValue `false`
+	 */
+	disableWriting?: boolean | 'mobile' | 'desktop';
+	/**
+	 * 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.
+	 */
+	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 inside the search field's icon stack: it takes the
+	 * lens' place on hover/focus while there is a query or selection to clear,
+	 * and resets both. Off by default. Leave it off when the component is
+	 * wrapped by a control that already exposes its own clear affordance (e.g.
+	 * BbSelect clears from the activator) to avoid a duplicate clear button.
+	 */
+	clearable?: boolean;
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+	/**
+	 * Reset modelValue to `null` or empty array if it no longer matches available items.
+	 */
+	enforceCoherence?: boolean;
+	/**
+	 * Property paths used to filter options when the user types in the search input.
+	 * When empty (default) options are matched against their display text.
+	 * When non-empty the provided paths are searched instead of the display text.
+	 * To disable filtering entirely set `disableWriting` so the user cannot type a query.
+	 *
+	 * @defaultValue `[]`
+	 */
+	filterBy?: string[];
+	/**
+	 * 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.
+	 */
+	hasWarning?: boolean;
+	/**
+	 * Height of group headers in the listbox (px). Defaults to 24px (compact) or 32px.
+	 * Only applies when `groupBy` is set.
+	 */
+	headerHeight?: number;
+	/**
+	 * Explicit id for the component. Used to generate ids for listbox and options.
+	 */
+	id?: HTMLAttributes['id'];
+	/**
+	 * Height of the options in the listbox (px).
+	 *
+	 * @defaultValue `40`
+	 */
+	itemHeight?: number;
+	/**
+	 * Array of items or function to load them asynchronously.
+	 * Functions receive `(query, prefill, modelValue)` and can return a promise.
+	 * `modelValue` is the raw v-model: an array in `multiple` mode, the raw
+	 * model value (possibly `null`) in single mode.
+	 *
+	 * @defaultValue `[]`
+	 */
+	items:
+		| Item[]
+		| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>)
+		| ((query: string, prefill: boolean, modelValue: any) => Item[]);
+	/**
+	 * Path to item property for display text or function to extract it.
+	 */
+	itemText?: ItemAccessor<Item, string>;
+	/**
+	 * Path to item property for value or function to extract it.
+	 */
+	itemValue?: ItemAccessor<Item>;
+	/**
+	 * 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.
+	 */
+	noDataText?: 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;
+	/**
+	 * Controls when items are pre-loaded.
+	 * `'interaction'` loads on the first user interaction (opening the
+	 * popover), `true` loads immediately on mount (and during SSR via
+	 * `onServerPrefetch`), `false` is *search-first*: nothing is fetched until
+	 * the user types a query — opening the panel alone does not load, and the
+	 * panel shows a "search to begin" hint until it does.
+	 * With the default, a seeded model resolves its option text on the first
+	 * interaction, not on mount — set `prefill: true` when the trigger must
+	 * show the selection's text without user interaction.
+	 *
+	 * Search-first needs a way to search and something to defer, so `false`
+	 * falls back to loading on open when any of these is true: `items` is an
+	 * array (nothing to defer — arrays resolve on mount), writing is disabled
+	 * (no search field, so the user could never trigger a load), or the model
+	 * is non-empty (its text must resolve to render the selection).
+	 *
+	 * @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);
+	/**
+	 * Accumulate selected items across searches instead of replacing them.
+	 */
+	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 when the activator loses focus.
+	 */
+	(e: 'blur', event: FocusEvent): void;
+	/**
+	 * Emitted when the value changes via native change event.
+	 */
+	(e: 'change', event: Event): void;
+	/**
+	 * Emitted when the activator is clicked.
+	 */
+	(e: 'click', event: MouseEvent): void;
+	/**
+	 * Emitted when the activator receives focus.
+	 */
+	(e: 'focus', event: FocusEvent): void;
+	/**
+	 * Emitted when focus moves outside the entire component after it was active.
+	 */
+	(e: 'inactive'): void;
+	/** Emitted when the component becomes active (focus enters it). */
+	(e: 'active'): void;
+	/**
+	 * Emitted on native input events from the search input.
+	 */
+	(e: 'input', event: Event): void;
+	/**
+	 * Emitted with the next selection value whenever selection changes.
+	 */
+	(e: 'update:modelValue', value: any): void;
+	/**
+	 * Emitted when the user types a new value and confirms it (Enter key) while
+	 * writing is enabled (i.e. `disableWriting` does not suppress the search
+	 * input for the current surface).
+	 */
+	(e: 'option:add', text: string): void;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbSelectPopoverActivatorSlotProps = {
+	/** Clears the current selection and query. */
+	clear: () => void;
+	/** Closes the popover. */
+	close: () => Promise<void>;
+	/** Focuses the search input when writing is enabled, otherwise the listbox. */
+	focus: () => void;
+	/** Whether the select is disabled. */
+	disabled: boolean | undefined;
+	/** Whether options are currently being fetched. */
+	loading: boolean;
+	/** Opens the popover. */
+	open: () => Promise<void>;
+	/** Bind onto the activator element with `v-bind="props"` to wire up the popover reference. */
+	props: {
+		ref: (reference: unknown) => void;
+	};
+	/** The current search query string. */
+	query: string;
+	/** Whether the select is read-only. */
+	readonly: boolean | undefined;
+	/** The resolved options that are currently selected. */
+	selectedOptions: BbSelectResolvedOption[];
+	/** Whether the popover is currently open. */
+	shown: boolean;
+	/** Display text of the current selection. */
+	text: string;
+	/** Toggles the popover open/closed. */
+	toggle: () => Promise<void>;
+};
+
+/** Props exposed by the `option` slot. */
+export type BbSelectPopoverOptionSlotProps<Item> = {
+	/** Whether this option is disabled. */
+	disabled: boolean;
+	/** Whether this option currently has keyboard focus. */
+	focused: boolean;
+	/** Zero-based index of this option in the list. */
+	index: number;
+	/** The raw item from the `items` prop. */
+	item: Item;
+	/** Whether items are still being fetched. */
+	loading: boolean;
+	/** Whether this option is currently selected. */
+	selected: boolean;
+	/** The resolved display text for this option. */
+	text: string;
+	/** The resolved value for this option. */
+	value: any;
+};
+
+/** Props exposed by the `group` slot. */
+export type BbSelectPopoverGroupSlotProps<Item> = {
+	/** Whether all options in this group are disabled. */
+	disabled: boolean;
+	/** Zero-based index of the first option in this group. */
+	index: number;
+	/** The raw group item. */
+	item: Item;
+	/** Number of options in this group. */
+	length: number;
+	/** The display text for this group. */
+	text: string;
+};
+
+/**
+ * Props exposed by the `header` / `footer` panel slots. Identical across the
+ * desktop popover and the adaptive sheet.
+ */
+export type BbSelectPopoverPanelSlotProps = {
+	/** Closes the panel. */
+	close: () => Promise<void>;
+	/** Clears the current selection. */
+	clear: () => void;
+	/** Focuses the search input (or the options when writing is disabled). */
+	focus: () => void;
+	/** The current search query string. */
+	query: string;
+	/** The resolved options that are currently selected. */
+	selectedOptions: BbSelectResolvedOption[];
+};
+
+export type BbSelectPopoverSlots<Item> = {
+	/**
+	 * Replaces the default trigger element that opens the select popover.
+	 */
+	activator?: (props: BbSelectPopoverActivatorSlotProps) => any;
+	/**
+	 * Content pinned to the top of the panel, above the search field. Rendered in
+	 * both the desktop popover and the adaptive sheet.
+	 */
+	header?: (props: BbSelectPopoverPanelSlotProps) => any;
+	/**
+	 * Content pinned to the bottom of the panel, below the options list. Rendered in
+	 * both the desktop popover and the adaptive sheet.
+	 */
+	footer?: (props: BbSelectPopoverPanelSlotProps) => any;
+	/**
+	 * Replaces the default group header rendered above grouped options.
+	 */
+	group?: (props: BbSelectPopoverGroupSlotProps<Item>) => any;
+	/**
+	 * Content shown inside the options dropdown while items are loading.
+	 */
+	loading?: (props: { query: string }) => any;
+	/**
+	 * Content shown when no options match the query or the list is empty.
+	 */
+	'no-data'?: (props: { query: string; focus: () => void }) => any;
+	/**
+	 * Replaces the default rendering of each option row in the dropdown.
+	 */
+	option?: (props: BbSelectPopoverOptionSlotProps<Item>) => any;
+};
+```
+
+## Styles
+
+```css
+/* @inherit --transition-duration --option-height — set inline by the component */
+.bb-select-popover {
+	overflow: visible;
+	text-align: left;
+	width: var(--w, 320px);
+
+	.bb-common-popover__bubble {
+		box-shadow: var(--bb-shadow);
+		overflow: hidden;
+	}
+
+	.bb-select-popover__search-container {
+		align-items: center;
+		border-bottom: 1px solid var(--bb-border);
+		display: flex;
+		padding: 0.375rem 0.75rem;
+		position: relative;
+	}
+
+	/* `header` / `footer` slot regions: pinned above the search and below the
+	   options list. In the adaptive sheet the same slots render in the off-canvas
+	   header / footer instead, so these rules only apply to the popover. */
+	.bb-select-popover__header {
+		border-bottom: 1px solid var(--bb-border);
+		padding: 0.5rem 0.75rem;
+	}
+
+	.bb-select-popover__footer {
+		border-top: 1px solid var(--bb-border);
+		padding: 0.5rem 0.75rem;
+	}
+
+	.bb-select-popover__search-icon,
+	.bb-select-popover__search-error-icon,
+	.bb-select-popover__search-warning-icon,
+	.bb-select-popover__search-clear {
+		color: var(--bb-text-muted);
+		flex-shrink: 0;
+		opacity: 0;
+		pointer-events: none;
+		position: absolute;
+		right: 0.75rem;
+		top: 50%;
+		transform: translateY(-50%);
+		transition:
+			color 0.3s,
+			opacity 0.3s;
+		/* Sized to the option checkmark (0.875rem) and right-anchored to the same
+		   column, so the search lens/clear line up vertically with the ticks in
+		   the list below. */
+		width: 0.875rem;
+	}
+
+	/* ClearableButton brings its own reset + focus ring. The clear (X) needs a
+	   larger box than the lens: its glyph fills far less of its viewBox than the
+	   magnifier, so at the lens' 0.875rem it reads tiny. Give it the full
+	   input-icon box, nudged 3px rightward off the shared right offset so its
+	   centre lands on the option checkmarks' column (the wider box would
+	   otherwise sit left of it). */
+	.bb-select-popover__search-clear,
+	.bb-select-popover__search-clear .bb-icon {
+		width: var(--bb-input-icon);
+	}
+
+	.bb-select-popover__search-clear {
+		right: calc(0.75rem - 3px);
+	}
+
+	.bb-select-popover__search-clear:hover {
+		color: var(--bb-text);
+	}
+
+	.bb-select-popover__search-input {
+		background-color: transparent;
+		border: 0;
+		color: var(--bb-text);
+		flex: 1 1 auto;
+		font-size: var(--bb-input-fs);
+		line-height: var(--bb-leading);
+		outline: none;
+		padding: 0;
+		padding-right: calc(var(--bb-input-icon) + 0.5rem);
+		width: 100%;
+	}
+
+	.bb-select-popover__search-icon {
+		opacity: 1;
+	}
+
+	&.bb-select-popover--errors {
+		.bb-select-popover__search-error-icon {
+			color: var(--bb-danger);
+			opacity: 1;
+		}
+
+		.bb-select-popover__search-icon {
+			opacity: 0;
+		}
+	}
+
+	&.bb-select-popover--warnings {
+		.bb-select-popover__search-warning-icon {
+			color: var(--bb-warn);
+			opacity: 1;
+		}
+
+		.bb-select-popover__search-icon {
+			opacity: 0;
+		}
+	}
+
+	/* Re-fetch over an existing result set: a 2px indeterminate strip on the
+	   search field's bottom border + faint options — identical to BbDropdown's
+	   searchable groups (no spinner). A first load (no options yet) shows the
+	   listbox's loading row instead. */
+	.bb-select-popover__search-strip {
+		animation: bb-select-popover-busy-slide 1.1s linear infinite;
+		background: linear-gradient(
+			90deg,
+			transparent 0%,
+			var(--bb-primary) 50%,
+			transparent 100%
+		);
+		background-repeat: no-repeat;
+		background-size: 40% 100%;
+		bottom: -1px;
+		height: 2px;
+		inset-inline: 0;
+		pointer-events: none;
+		position: absolute;
+	}
+
+	&.bb-select-popover--reloading {
+		.bb-listbox__option {
+			opacity: 0.55;
+			transition: opacity var(--bb-transition-fast, 0.15s) ease;
+		}
+	}
+
+	/* The clear replaces the lens whenever there is something to clear. It must
+	   be persistent (not hover-gated): selecting options moves focus off the
+	   search field, so a focus/hover-gated clear would flicker away on every
+	   pick. Suppressed only while the stack shows the error or warning icon.
+	   `:hover` below just deepens the clear's colour on pointer-over. */
+	&.bb-select-popover--clearable-active:not(.bb-select-popover--errors):not(
+			.bb-select-popover--warnings
+		) {
+		.bb-select-popover__search-icon {
+			opacity: 0;
+		}
+
+		.bb-select-popover__search-clear {
+			opacity: 1;
+			pointer-events: auto;
+		}
+	}
+
+	.bb-listbox {
+		--option-h: var(--option-height);
+		display: block;
+		user-select: none;
+
+		&.bb-listbox--open {
+			transition: min-height 0s 0s;
+
+			.bb-listbox__outer-container {
+				grid-template-rows: 1fr;
+				opacity: 1;
+				transition-delay: 0s, 0ms;
+
+				> * {
+					opacity: 1;
+					transition-delay: calc(var(--transition-duration) * 0.8);
+				}
+			}
+		}
+
+		&.bb-listbox--no-data {
+			.bb-listbox__outer-container {
+				.bb-listbox__inner-container {
+					.bb-listbox__no-data {
+						display: block;
+					}
+				}
+			}
+		}
+
+		&.bb-listbox--loading {
+			.bb-listbox__outer-container {
+				.bb-listbox__inner-container {
+					.bb-listbox__loading {
+						display: block;
+						text-align: left;
+					}
+				}
+			}
+		}
+
+		.bb-listbox__outer-container {
+			background-color: var(--bb-panel);
+			border-width: 0;
+			display: grid;
+			grid-template-rows: 0fr;
+			opacity: 0;
+			transition-delay: calc(var(--transition-duration) * 0.25), 0s, 0s;
+			transition-duration:
+				var(--transition-duration), calc(var(--transition-duration) * 1.4),
+				var(--transition-duration);
+			transition-property: grid-template-rows, opacity, border;
+
+			> * {
+				opacity: 0;
+				transition-delay: 0s;
+				transition-duration: calc(var(--transition-duration) * 2);
+				transition-property: opacity;
+			}
+
+			.bb-listbox__inner-container {
+				max-height: min(
+					calc(var(--option-h) * 6 + 0.5rem),
+					calc(round(down, calc(100dvh - 130px), var(--option-h)) - 1px)
+				);
+				overflow: auto;
+				overflow-x: clip;
+				padding: 0.25rem;
+				text-align: left;
+
+				.bb-listbox__loading,
+				.bb-listbox__no-data {
+					color: color-mix(in oklab, var(--bb-text) 45%, transparent);
+					display: none;
+					font-size: 0.8125rem;
+					padding: 0.375rem 0.5rem;
+				}
+
+				span[role='listbox'] {
+					display: block;
+					position: relative;
+					width: 100%;
+
+					.bb-listbox__group {
+						display: block;
+						left: 0;
+						position: absolute;
+						top: 0;
+						width: 100%;
+					}
+
+					.bb-listbox__group-header {
+						align-items: center;
+						display: flex;
+						height: var(--group-header-height, 32px);
+						padding: 0 0.5rem;
+						user-select: none;
+
+						.bb-listbox__group-header-label {
+							color: color-mix(in oklab, var(--bb-text) 45%, transparent);
+							flex: auto;
+							font-size: 0.75rem;
+							font-weight: 500;
+							overflow: hidden;
+							text-align: left;
+							text-overflow: ellipsis;
+							white-space: nowrap;
+						}
+					}
+
+					.bb-listbox__option {
+						display: block;
+						left: 0;
+						position: absolute;
+						top: 0;
+						width: 100%;
+					}
+
+					.bb-listbox__group > .bb-listbox__option {
+						position: static;
+					}
+
+					.autocomplete-option {
+						align-items: center;
+						border-radius: clamp(
+							0px,
+							calc(var(--bb-radius) - 4px),
+							calc(var(--bb-input-h) / 2)
+						);
+						color: var(--bb-text);
+						cursor: pointer;
+						display: flex;
+						gap: 0.5rem;
+						height: var(--option-h);
+						padding-left: 0.5rem;
+						padding-right: 0.5rem;
+						transition: background-color 150ms ease;
+						width: 100%;
+
+						&:hover:not(.autocomplete-option--disabled),
+						&--focused:not(.autocomplete-option--disabled) {
+							background-color: color-mix(
+								in oklab,
+								var(--bb-text) 8%,
+								transparent
+							);
+						}
+
+						&--disabled {
+							cursor: not-allowed;
+							opacity: 0.5;
+						}
+
+						&__label {
+							flex: 1 1 auto;
+							font-size: 0.875rem;
+							min-width: 0;
+							overflow: hidden;
+							text-align: left;
+							text-overflow: ellipsis;
+							white-space: nowrap;
+						}
+
+						&__check {
+							color: var(--bb-text);
+							flex-shrink: 0;
+							height: 0.875rem;
+							width: 0.875rem;
+
+							path {
+								stroke-dasharray: 30;
+								stroke-dashoffset: 30;
+								transition: stroke-dashoffset var(--bb-transition-medium)
+									var(--bb-ease);
+							}
+						}
+
+						&--selected {
+							.autocomplete-option__check {
+								path {
+									stroke-dashoffset: 0;
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
+
+@keyframes bb-select-popover-busy-slide {
+	from {
+		background-position: -40% 0;
+	}
+
+	to {
+		background-position: 140% 0;
+	}
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.bb-select-popover .bb-select-popover__search-strip {
+		animation: none;
+		background: var(--bb-primary);
+		opacity: 0.5;
+	}
+}
+
+/* ------------------------------------------------------------------------- */
+/* Adaptive bottom sheet                                                      */
+/* The sheet reuses every `.bb-select-popover` descendant rule (search field, */
+/* listbox, options) verbatim; this section only overrides the fixed popover  */
+/* width, stacks the regions vertically and styles the selection summary that */
+/* sits above the search. Declared after the base block so equal-specificity  */
+/* overrides (width, listbox max-height) win on source order.                 */
+/* ------------------------------------------------------------------------- */
+.bb-select-popover.bb-select-popover--sheet {
+	display: flex;
+	flex-direction: column;
+	min-height: 0;
+	overflow: hidden;
+	width: 100%;
+}
+
+.bb-select-popover--sheet {
+	/* Selection sits above the search; search + listbox keep the popover styling
+	   (they are the same `.bb-select-popover` descendants). */
+	.bb-select-popover__sheet-selection {
+		flex-shrink: 0;
+		padding: 0 0.25rem 0.625rem;
+		text-align: left;
+	}
+
+	.bb-select-popover__sheet-chips {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.375rem;
+	}
+
+	.bb-select-popover__sheet-single {
+		color: var(--bb-text);
+		font-size: var(--bb-input-fs);
+		line-height: var(--bb-leading);
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	/* Options list breathes a little more on a sheet and scrolls internally. */
+	.bb-listbox {
+		flex: 1 1 auto;
+		min-height: 0;
+	}
+
+	.bb-listbox .bb-listbox__outer-container .bb-listbox__inner-container {
+		max-height: min(
+			calc(var(--option-h) * 9 + 0.5rem),
+			calc(round(down, 55dvh, var(--option-h)) - 1px)
+		);
+	}
+}
+
+/* When a footer slot is present, drop the sheet body's bottom padding so the
+   footer (which brings its own border-top + padding) sits flush against the
+   options instead of leaving a gap. */
+.bb-select-popover-offcanvas:has(.bb-offcanvas__footer:not(:empty))
+	.bb-offcanvas__body-content {
+	padding-bottom: 0;
+}
+```