bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbSelectPopover.md

@@ -0,0 +1,2010 @@
+# BbSelectPopover
+
+## Template & Script
+
+```vue
+<template>
+	<slot
+		v-if="!hasExternalActivator"
+		name="activator"
+		v-bind="{
+			props: {
+				ref: setActivatorRef,
+			},
+			shown,
+			disabled,
+			readonly,
+			loading: computedLoading,
+			query,
+			selectedOptions,
+			text: triggerInputValue,
+			clear: onClear,
+			open,
+			close,
+			toggle,
+		}"
+	/>
+	<CommonPopover
+		v-model="shown"
+		:anchor="activatorEl"
+		:arrow-padding="arrowPadding"
+		:boundary="boundary"
+		class="bb-select-popover"
+		:class="{
+			'bb-select-popover--errors': hasErrors,
+			'bb-select-popover--loading': computedLoading,
+		}"
+		:flip="flip"
+		:placement="placement"
+		:offset="offset"
+		:padding="padding"
+		:transition-duration="transitionDuration"
+		:hide-arrow="hideArrow"
+		:style="panelStyles"
+	>
+		<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"
+				:tabindex="shown ? 0 : -1"
+				role="searchbox"
+				: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"
+			/>
+			<BbSpinner
+				aria-hidden="true"
+				class="bb-select-popover__search-spinner"
+				focusable="false"
+			/>
+			<svg
+				class="bb-select-popover__search-icon"
+				xmlns="http://www.w3.org/2000/svg"
+				viewBox="0 0 24 24"
+				aria-hidden="true"
+			>
+				<path
+					fill="none"
+					stroke="currentColor"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					stroke-width="2"
+					d="m21 21-4.343-4.343m0 0A8 8 0 1 0 5.343 5.343a8 8 0 0 0 11.314 11.314"
+				/>
+			</svg>
+		</div>
+		<button
+			v-else
+			ref="popoverFocusProxy"
+			class="bb-select-popover__focus-proxy sr-only"
+			type="button"
+			:aria-controls="`${id}_listbox`"
+			:aria-describedby="computedAriaDescribedby"
+			:aria-invalid="computedAriaInvalid"
+			:aria-label="searchInputAriaLabel"
+			tabindex="-1"
+			@focus="onPopoverFocusProxyFocus"
+			@keydown.stop.prevent.down="onArrowDown"
+			@keydown.stop.prevent.up="onArrowUp"
+			@keydown.stop.prevent.enter="onEnter"
+			@keydown.stop.prevent.esc="onEscape"
+		>
+			Focus options
+		</button>
+		<div
+			class="bb-select-popover__options-outer"
+			:aria-hidden="shown ? undefined : 'true'"
+			:inert="!shown"
+		>
+			<slot name="options:prepend:outer" :focus="focusPopoverContent" />
+		</div>
+		<ListBox
+			:id="`${id}_listbox`"
+			ref="optionsContainer"
+			:compact="compact"
+			:loading="computedLoading"
+			:loading-text="loadingText"
+			:multiple="multiple"
+			:no-data-text="noDataText"
+			:open="shown"
+			:options="groupBy ? undefined : filteredOptions"
+			:groups="groupBy ? groupedOptions : undefined"
+			:header-height="headerHeight"
+			:option-height="itemHeight"
+			@focused:change="onListboxFocusedChange"
+			@option:selected="onOptionSelected"
+			@option:unselected="onOptionUnselected"
+		>
+			<template #options:prepend
+				><slot name="options:prepend" :focus="focusPopoverContent"
+			/></template>
+			<template #loading><slot name="loading" :query="query" /></template>
+			<template #no-data
+				><slot name="no-data" :query="query" :focus="focusPopoverContent"
+			/></template>
+			<template #options:append
+				><slot name="options:append" :focus="focusPopoverContent"
+			/></template>
+			<template #option="data"
+				><slot :loading="computedLoading" name="option" v-bind="data"
+			/></template>
+			<template #group="data"><slot name="group" v-bind="data" /></template>
+		</ListBox>
+		<div
+			class="bb-select-popover__options-outer"
+			:aria-hidden="shown ? undefined : 'true'"
+			:inert="!shown"
+		>
+			<slot name="options:append:outer" :focus="focusPopoverContent" />
+		</div>
+	</CommonPopover>
+</template>
+
+<script setup lang="ts" generic="Item = any">
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { CommonProps } from '@/types/CommonProps';
+import type { Option as BaseOption, GroupedOptions } from '@/types/Option';
+import { computed, ref, nextTick, watch, onBeforeUnmount } from 'vue';
+import { extractDomContainer } from '@/utilities/functions/extractDomContainer';
+import { get } from '@/utilities/functions/get';
+import { hash } from '@/utilities/functions/hash';
+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 { 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 { useMobile } from '@/composables/useMobile';
+import { usePrefill } from '@/composables/usePrefill';
+import { useUntil } from '@/composables/useUntil';
+import { wait } from '@/utilities/functions/wait';
+import { BbSpinner } from '@/index';
+import CommonPopover from '../CommonPopover/CommonPopover.vue';
+import ErrorIcon from '../ErrorIcon/ErrorIcon.vue';
+import ListBox from '../ListBox/ListBox.vue';
+import { waitFor } from '@/utilities/functions/waitFor';
+
+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;
+
+	/**
+	 * Controls whether the search input is shown inside the popover panel.
+	 * Use `'not-mobile'` to hide the search input on mobile.
+	 * @default false
+	 */
+	allowWriting?: boolean | 'not-mobile';
+
+	/**
+	 * Browser autocomplete hint for the popover search input.
+	 * @default 'off'
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+
+	/**
+	 * Apply the compact density variant.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Space the arrow keeps from popover edges.
+	 * Useful with rounded corners.
+	 * @default 10
+	 */
+	arrowPadding?: CommonProps['arrowPadding'];
+
+	/**
+	 * Constrains the popover to a specific boundary element.
+	 */
+	boundary?: HTMLElement | Record<string, any> | string | null;
+
+	/**
+	 * Additional dependencies that trigger item reloading when changed.
+	 * @default []
+	 */
+	dependencies?: any[];
+
+	/**
+	 * Debounce delay (ms) for dependency-triggered reloads.
+	 * @default 0
+	 */
+	depsDebounceTime?: number;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Marks the component as being in error state.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit invalid state for accessibility semantics.
+	 * Falls back to `hasErrors` when not provided.
+	 */
+	ariaInvalid?: boolean;
+
+	/**
+	 * Space-separated IDREF(s) that describe this field for assistive technologies.
+	 * Accepts either a string or array of ids.
+	 */
+	ariaDescribedby?: string | string[];
+
+	/**
+	 * Enable or disable floating flip behavior.
+	 * @default true
+	 */
+	flip?: boolean;
+
+	/**
+	 * Whether the floating arrow is hidden.
+	 * @default true
+	 */
+	hideArrow?: boolean;
+
+	/**
+	 * Reset modelValue to `null` or empty array if it no longer matches available items.
+	 */
+	enforceCoherence?: boolean;
+
+	/**
+	 * Controls how options are filtered during search.
+	 * Options are always filtered by display text, but can also match additional properties
+	 * when set to a string path, array of paths, or custom function.
+	 * Set to `false` to disable filtering, or `'not_stashed'` to exclude stashed items.
+	 * @default () => []
+	 */
+	filterBy?:
+		| string
+		| string[]
+		| false
+		| 'not_stashed'
+		| ((value: any, item: any, query: string | null) => boolean)
+		| null;
+
+	groupBy?: string | ((item: Item) => string | number | symbol);
+
+	/**
+	 * 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'];
+
+	/**
+	 * Array of items or function to load them asynchronously.
+	 * Functions receive `(query, prefill, modelValue)` and can return a promise.
+	 * @default []
+	 */
+	items:
+		| Item[]
+		| ((query: string, prefill: boolean, modelValue: any[]) => Promise<Item[]>)
+		| ((query: string, prefill: boolean, modelValue: any[]) => Item[]);
+
+	/**
+	 * Height of the options in the listbox (px).
+	 * @default 40
+	 */
+	itemHeight?: number;
+
+	/**
+	 * Path to item property for display text or function to extract it.
+	 */
+	itemText?: string | ((item: Item) => string) | undefined;
+
+	/**
+	 * Path to item property for value or function to extract it.
+	 */
+	itemValue?: string | ((item: Item) => string) | undefined;
+
+	/**
+	 * 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).
+	 * @default Infinity
+	 */
+	max?: number;
+
+	/**
+	 * v-model value. Single value for single select, array for multiple select.
+	 */
+	modelValue: any;
+
+	/**
+	 * Debounce delay (ms) for modelValue change handling.
+	 * @default 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.
+	 * @default 4
+	 */
+	offset?: number;
+
+	/**
+	 * Minimum page padding used by floating shift middleware.
+	 * @default 0
+	 */
+	padding?: CommonProps['padding'];
+
+	/**
+	 * Floating placement of the popover.
+	 * @default 'bottom'
+	 */
+	placement?: CommonProps['placement'];
+
+	/**
+	 * Controls when items are pre-loaded.
+	 * `'interaction'` loads on first user interaction (first popover open),
+	 * `true` loads immediately, `false` loads only on explicit search/open flows.
+	 * @default 'interaction'
+	 */
+	prefill?: boolean | 'interaction';
+
+	/**
+	 * Debounce delay (ms) before triggering search queries after user input stops.
+	 * @default 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.
+	 * @default 'Search options'
+	 */
+	searchInputAriaLabel?: string;
+
+	/**
+	 * Accumulate selected items across searches instead of replacing them.
+	 */
+	stash?: boolean;
+
+	/**
+	 * Transition duration (ms) for popover show/hide animations.
+	 * @default 300
+	 */
+	transitionDuration?: number;
+
+	/**
+	 * Width of the popover in pixels, percentage, or `'auto'`.
+	 */
+	width?: number | string;
+};
+
+export type BbSelectPopoverEvents = {
+	(e: 'blur', event: FocusEvent): void;
+	(e: 'change', event: Event): void;
+	(e: 'click', event: MouseEvent): void;
+	(e: 'focus', event: FocusEvent): void;
+	(e: 'inactive'): void;
+	(e: 'input', event: Event): void;
+	(e: 'update:modelValue', value: any): void;
+	(e: 'option:add', text: string): void;
+};
+
+export type BbSelectPopoverSlots<Item> = {
+	/**
+	 * Replaces the default trigger element that opens the select popover.
+	 * @param props - Bind these onto the activator element with `v-bind="props"` to wire up the popover reference.
+	 * @param shown - Whether the popover is currently open.
+	 * @param disabled - Whether the select is disabled.
+	 * @param readonly - Whether the select is read-only.
+	 * @param loading - Whether options are currently being fetched.
+	 * @param query - The current search query string.
+	 * @param clear - Clears the current selection and query.
+	 * @param open - Opens the popover.
+	 * @param close - Closes the popover.
+	 * @param toggle - Toggles the popover open/closed.
+	 */
+	activator?: (props: {
+		props: {
+			ref: (reference: unknown) => void;
+		};
+		shown: boolean;
+		disabled: boolean | undefined;
+		readonly: boolean | undefined;
+		loading: boolean;
+		query: string;
+		clear: () => void;
+		open: () => Promise<void>;
+		close: () => Promise<void>;
+		toggle: () => Promise<void>;
+	}) => any;
+	/**
+	 * Content shown inside the options dropdown while items are loading.
+	 * @param query - The current search query string.
+	 */
+	loading?: (props: { query: string }) => any;
+	/**
+	 * Content shown when no options match the query or the list is empty.
+	 * @param query - The current search query string.
+	 * @param focus - Focuses the internal search input.
+	 */
+	'no-data'?: (props: { query: string; focus: () => void }) => any;
+	/**
+	 * Replaces the default rendering of each option row in the dropdown.
+	 * @param disabled - Whether this option is disabled.
+	 * @param focused - Whether this option currently has keyboard focus.
+	 * @param index - Zero-based index of this option in the list.
+	 * @param item - The raw item from the `items` prop.
+	 * @param loading - Whether items are still being fetched.
+	 * @param selected - Whether this option is currently selected.
+	 * @param text - The resolved display text for this option.
+	 * @param value - The resolved value for this option.
+	 */
+	option?: (props: {
+		disabled: boolean;
+		focused: boolean;
+		index: number;
+		item: Item;
+		loading: boolean;
+		selected: boolean;
+		text: string;
+		value: any;
+	}) => any;
+	/**
+	 * Replaces the default group header rendered above grouped options.
+	 * @param text - The display text for this group.
+	 * @param item - The raw group item.
+	 * @param index - Zero-based index of the first option in this group.
+	 * @param length - Number of options in this group.
+	 * @param disabled - Whether all options in this group are disabled.
+	 */
+	group?: (props: {
+		text: string;
+		item: Item;
+		index: number;
+		length: number;
+		disabled: boolean;
+	}) => any;
+	/**
+	 * Content appended inside the options list, after the last option.
+	 * @param focus - Focuses the internal search input.
+	 */
+	'options:append'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content appended outside the options list container.
+	 * @param focus - Focuses the internal search input.
+	 */
+	'options:append:outer'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content prepended inside the options list, before the first option.
+	 * @param focus - Focuses the internal search input.
+	 */
+	'options:prepend'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content prepended outside the options list container.
+	 * @param focus - Focuses the internal search input.
+	 */
+	'options:prepend:outer'?: (props: { focus: () => void }) => any;
+};
+
+const props = withDefaults(defineProps<BbSelectPopoverProps<Item>>(), {
+	allowWriting: true,
+	arrowPadding: 10,
+	autocomplete: 'off',
+	depsDebounceTime: 0,
+	dependencies: () => [],
+	filterBy: () => [],
+	flip: true,
+	hideArrow: true,
+	max: Infinity,
+	modelValueDebounceTime: 0,
+	offset: 4,
+	padding: 10,
+	placement: 'bottom',
+	prefill: 'interaction',
+	queryDebounceTime: 500,
+	transitionDuration: 300,
+	width: '200',
+});
+
+const emit = defineEmits<BbSelectPopoverEvents>();
+
+defineSlots<BbSelectPopoverSlots<Item>>();
+
+if (props.multiple && !Array.isArray(props.modelValue)) {
+	throw new Error('Multiple is set to "true" but modelValue is not an array.');
+}
+
+/**
+ * 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 { width: activatorWidth } = useElementSize(
+	activatorEl,
+	{ 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.allowWriting === 'not-mobile') return !isMobile.value;
+	return !!props.allowWriting;
+});
+const inputmode = computed(() =>
+	props.allowWriting === 'not-mobile' && isMobile.value ? 'none' : undefined
+);
+const searchInputAriaLabel = computed(
+	() => props.searchInputAriaLabel ?? 'Search options'
+);
+
+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(() => ({
+	'--bb-select-popover-width': 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);
+	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 = activatorEl.value?.contains(target);
+	const insidePopover = !!target.closest('.bb-common-popover');
+	if (insideActivator || insidePopover) 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, 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>();
+
+const {
+	hasPrefilled,
+	isPrefilling,
+	canLoad,
+	prefill: prefillItems,
+} = usePrefill({
+	trigger: computed(
+		() =>
+			props.prefill === true ||
+			(props.prefill === 'interaction' && hasInteracted.value)
+	),
+	currentValue: undefined,
+	multiple: false,
+	fn: async (isPrefill) => {
+		await getter(query.value, isPrefill, props.modelValue);
+		if (props.stash) {
+			addToStash(...options.value.map((o) => o.item));
+		}
+	},
+});
+
+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: true,
+	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)
+);
+
+const computedLoading = computed(() => !!(loading.value || props.loading));
+const hasErrors = computed(() => !!props.hasErrors);
+const triggerInputValue = computed(() => {
+	if (props.multiple) return '';
+	return selectedOptions.value[0]?.text ?? '';
+});
+
+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) => {
+	removeFromStash((o) => o.valueHash !== option.valueHash);
+	if (props.multiple) {
+		const copy = { ...modelValueIndexedByHash.value };
+		delete copy[option.valueHash];
+		emit('update:modelValue', Object.values(copy));
+	} else {
+		emit('update:modelValue', null);
+	}
+	if (props.multiple && computedAllowWriting.value && shown.value) {
+		focusSearchInput();
+	} else {
+		focusActivator();
+	}
+};
+
+/**
+ * Filter options based on the current query.
+ */
+const filteredOptions = computed<BaseOption<Item>[]>(() => {
+	const queryMatchesASelectedOption = selectedOptions.value.some(
+		(option: BaseOption) => option.text === query.value
+	);
+	const shouldFilter =
+		(props.multiple && query.value) ||
+		(props.filterBy === 'not_stashed' && query.value) ||
+		(query.value && !queryMatchesASelectedOption && !props.multiple);
+
+	if (!shouldFilter || !props.filterBy) return options.value;
+
+	const stashedHashes =
+		props.filterBy === 'not_stashed'
+			? new Set(innerStash.value.map((o) => o.valueHash))
+			: null;
+
+	return options.value.filter((item: BaseOption) => {
+		let matchedAnything = false;
+		if (typeof props.filterBy === 'function') {
+			matchedAnything = props.filterBy(item.value, item.item, query.value);
+		} else if (props.filterBy === 'not_stashed' && query.value) {
+			matchedAnything = !stashedHashes!.has(item.valueHash);
+		} else if (Array.isArray(props.filterBy) && props.filterBy.length) {
+			matchedAnything = matchAnyKey(
+				item.item,
+				props.filterBy,
+				query.value.trim()
+			);
+		}
+		return matchedAnything || matchAnyKey(item, ['text'], query.value.trim());
+	});
+});
+
+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);
+
+const open = async ({
+	focusPopoverContent = true,
+}: { focusPopoverContent?: boolean } = {}) => {
+	if (props.disabled || props.readonly) return;
+	if (shown.value) return;
+	hasInteracted.value = true;
+	resume();
+	shown.value = true;
+
+	if (!hasPrefilled.value && !isPrefilling.value) {
+		await prefillItems();
+	}
+
+	await nextTick();
+	document.addEventListener('click', onOutsideInteraction);
+	document.addEventListener('focusin', onOutsideInteraction);
+
+	if (!focusPopoverContent) return;
+
+	if (computedAllowWriting.value) {
+		await wait(0);
+		focusSearchInput();
+	} else {
+		await wait(0);
+		focusPopoverFocusProxy();
+	}
+};
+
+const close = async () => {
+	if (!shown.value) return;
+	shown.value = false;
+	optionsContainer.value?.blur();
+	activeDescendantId.value = undefined;
+	pause();
+	document.removeEventListener('click', onOutsideInteraction);
+	document.removeEventListener('focusin', onOutsideInteraction);
+	query.value = '';
+};
+
+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 = () => {
+	active.value = true;
+};
+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;
+};
+
+const syncActiveStateOnBlur = () => {
+	setTimeout(() => {
+		if (isFocusInsideComponent(document.activeElement)) {
+			setActive();
+			return;
+		}
+		setInactive();
+	}, 0);
+};
+/**
+ * END ACTIVE STATE
+ */
+
+const onClear = () => {
+	emit('update:modelValue', props.multiple ? [] : null);
+};
+
+/**
+ * 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 = (event: MouseEvent) => {
+			emit('click', event);
+			if (props.disabled || props.readonly) return;
+			event.preventDefault();
+			toggle();
+		};
+
+		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('keydown', handleKeydown);
+		el.addEventListener('focus', handleFocus);
+		el.addEventListener('blur', handleBlur);
+
+		cleanupActivator = () => {
+			el.removeEventListener('click', handleClick);
+			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-activedescendant');
+		};
+	},
+	{ immediate: true }
+);
+
+watch(
+	[
+		activatorEl,
+		shown,
+		renderListBox,
+		computedAriaInvalid,
+		computedAriaDescribedby,
+		activeDescendantId,
+	] as const,
+	([el, isShown, hasListBox, ariaInvalid, ariaDescribedby, 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 (isShown && descendantId) {
+			el.setAttribute('aria-activedescendant', descendantId);
+		} else {
+			el.removeAttribute('aria-activedescendant');
+		}
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	cleanupActivator?.();
+	document.removeEventListener('click', onOutsideInteraction);
+	document.removeEventListener('focusin', onOutsideInteraction);
+});
+/**
+ * END ACTIVATOR LISTENERS
+ */
+</script>
+
+<style lang="postcss">
+.bb-select-popover {
+	width: var(--bb-select-popover-width, 320px);
+
+	.bb-select-popover__search-container {
+		align-items: center;
+		border-bottom: 1px solid var(--bb-border);
+		display: flex;
+		padding: 0.375rem 0.75rem;
+		position: relative;
+	}
+
+	.bb-select-popover__search-icon,
+	.bb-select-popover__search-spinner,
+	.bb-select-popover__search-error-icon {
+		color: var(--bb-icon-color);
+		flex-shrink: 0;
+		width: var(--bb-input-icon);
+		position: absolute;
+		right: 0.75rem;
+		top: 50%;
+		transform: translateY(-50%);
+		opacity: 0;
+		transition:
+			color 0.3s,
+			opacity 0.3s;
+		pointer-events: none;
+	}
+
+	.bb-select-popover__search-input {
+		background-color: transparent;
+		border: 0;
+		color: var(--bb-input-color);
+		flex: 1 1 auto;
+		font-size: var(--bb-input-font-size);
+		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,
+		.bb-select-popover__search-spinner {
+			opacity: 0;
+		}
+	}
+
+	&.bb-select-popover--loading {
+		.bb-select-popover__search-spinner {
+			opacity: 1;
+		}
+
+		.bb-select-popover__search-icon,
+		.bb-select-popover__search-error-icon {
+			opacity: 0;
+		}
+	}
+
+	.bb-listbox {
+		--option-h: var(--option-height);
+		display: block;
+
+		&.bb-listbox--open {
+			transition: min-height 0s 0s;
+
+			.bb-listbox__outer-container {
+				grid-template-rows: 1fr;
+				opacity: 1;
+				transition-delay: 0s, 00ms;
+
+				> * {
+					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__loading {
+						display: hidden;
+					}
+				}
+			}
+		}
+
+		&.bb-listbox--multiple {
+			.autocomplete-option__checkbox {
+				display: inline-block !important;
+			}
+		}
+
+		.bb-listbox__outer-container {
+			background-color: var(--bb-panel);
+			border-color: var(--bb-primary);
+			border-radius: var(--bb-radius);
+			border-width: 0px;
+			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 {
+				overflow: auto;
+				overflow-x: clip;
+				text-align: left;
+				/* Always show options up to the bottom of the screen, but not more than 6 options */
+				max-height: min(
+					calc(var(--option-h) * 6),
+					calc(round(down, calc(100dvh - 130px), var(--option-h)) - 1px)
+				);
+
+				.bb-listbox__loading,
+				.bb-listbox__no-data {
+					color: var(--bb-text);
+					display: none;
+					padding-bottom: var(--bb-select-option-py);
+					padding-left: var(--bb-select-option-px);
+					padding-right: var(--bb-select-option-px);
+					padding-top: var(--bb-select-option-py);
+				}
+
+				span[role='listbox'] {
+					position: relative;
+					width: 100%;
+					display: block;
+
+					.bb-listbox__group {
+						left: 0;
+						position: absolute;
+						top: 0;
+						width: 100%;
+						display: block;
+					}
+
+					.bb-listbox__group-header {
+						display: flex;
+						align-items: center;
+						height: var(--group-header-height, 32px);
+						padding-left: var(--bb-select-option-px);
+						padding-right: var(--bb-select-option-px);
+
+						user-select: none;
+
+						.bb-listbox__group-header-label {
+							display: flex;
+							align-items: center;
+							gap: 16px;
+							flex: auto;
+							text-align: left;
+							overflow: hidden;
+							text-overflow: ellipsis;
+							white-space: nowrap;
+							color: color-mix(in srgb, var(--bb-text) 50%, transparent);
+							font-size: 0.75rem;
+							font-weight: 600;
+							letter-spacing: 0.025em;
+							text-transform: uppercase;
+
+							&::after {
+								content: '';
+								display: block;
+								width: 100%;
+								height: 1px;
+								background-color: var(--bb-border);
+							}
+						}
+					}
+
+					.bb-listbox__option {
+						left: 0;
+						position: absolute;
+						display: block;
+						top: 0;
+						width: 100%;
+					}
+
+					.bb-listbox__group > .bb-listbox__option {
+						position: static;
+					}
+
+					.autocomplete-option {
+						--bg-opacity: 0;
+						--bg-base-color: var(--bb-text);
+						align-items: center;
+						background-color: color-mix(
+							in srgb,
+							var(--bg-base-color) calc(100% * var(--bg-opacity)),
+							transparent
+						);
+						color: var(--bb-text);
+						cursor: pointer;
+						display: flex;
+						flex-grow: 1;
+						gap: 8px;
+						height: var(--option-h);
+						padding-left: var(--bb-select-option-px);
+						padding-right: var(--bb-select-option-px);
+						transition-duration: 250ms;
+						transition-property: color, background-color;
+						transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+						width: 100%;
+
+						&:hover:not(.autocomplete-option--disabled) {
+							--bg-opacity: 0.05;
+							--bg-base-color: var(--bb-text);
+						}
+
+						&--focused {
+							--bg-opacity: 0.15;
+							--bg-base-color: var(--bb-text);
+						}
+
+						&--focused:hover:not(.autocomplete-option--disabled) {
+							--bg-opacity: 0.2;
+						}
+
+						&--selected {
+							--bg-opacity: 0.1;
+							--bg-base-color: var(--bb-primary) !important;
+							color: var(--bb-primary);
+						}
+
+						&--selected:hover:not(.autocomplete-option--disabled) {
+							--bg-opacity: 0.15;
+						}
+
+						&--selected.autocomplete-option--focused {
+							--bg-opacity: 0.2;
+						}
+
+						&--selected.autocomplete-option--focused:hover:not(
+								.autocomplete-option--disabled
+							) {
+							--bg-opacity: 0.2;
+						}
+
+						&--disabled {
+							cursor: not-allowed;
+							opacity: 0.5;
+
+							.autocomplete-option__checkbox.autocomplete-option__checkbox {
+								background-color: var(--bb-panel-disabled);
+							}
+						}
+
+						.autocomplete-option__checkbox {
+							pointer-events: none;
+							display: none;
+							width: 16px;
+							height: 16px;
+							background-color: var(--bb-panel);
+							border-color: var(--bb-border);
+							border-radius: min(6px, var(--bb-radius));
+							border-style: solid;
+							border-width: 1px;
+							margin-left: -6px;
+							transition-duration: 300ms;
+							transition-property:
+								color, background-color, border-color, text-decoration-color,
+								box-shadow;
+							transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+
+							path {
+								stroke: var(--bb-contrasting);
+								stroke-dasharray: 105;
+								stroke-dashoffset: 105;
+								transition: stroke-dashoffset 0.3s;
+							}
+						}
+
+						.autocomplete-option__label {
+							display: block;
+							flex: auto;
+							text-align: left;
+							overflow: hidden;
+							text-overflow: ellipsis;
+							white-space: nowrap;
+						}
+
+						&.autocomplete-option--selected {
+							.autocomplete-option__checkbox {
+								background-color: var(--bb-primary);
+								border-color: var(--bb-primary);
+
+								path {
+									stroke-dashoffset: 0;
+								}
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { CommonProps } from '@/types/CommonProps';
+
+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;
+
+	/**
+	 * Controls whether the search input is shown inside the popover panel.
+	 * Use `'not-mobile'` to hide the search input on mobile.
+	 *
+	 * @defaultValue `false`
+	 */
+	allowWriting?: boolean | 'not-mobile';
+
+	/**
+	 * Browser autocomplete hint for the popover search input.
+	 *
+	 * @defaultValue `'off'`
+	 */
+	autocomplete?: InputHTMLAttributes['autocomplete'];
+
+	/**
+	 * Apply the compact density variant.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Space the arrow keeps from popover edges. Useful with rounded corners.
+	 *
+	 * @defaultValue `10`
+	 */
+	arrowPadding?: CommonProps['arrowPadding'];
+
+	/**
+	 * Constrains the popover to a specific boundary element.
+	 */
+	boundary?: HTMLElement | Record<string, any> | string | null;
+
+	/**
+	 * Additional dependencies that trigger item reloading when changed.
+	 *
+	 * @defaultValue `[]`
+	 */
+	dependencies?: any[];
+
+	/**
+	 * Debounce delay (ms) for dependency-triggered reloads.
+	 *
+	 * @defaultValue `0`
+	 */
+	depsDebounceTime?: number;
+
+	/**
+	 * Disables the component.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Marks the component as being in error state.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Explicit invalid state for accessibility semantics.
+	 * Falls back to `hasErrors` when not provided.
+	 */
+	ariaInvalid?: boolean;
+
+	/**
+	 * Space-separated IDREF(s) that describe this field for assistive technologies.
+	 * Accepts either a string or array of ids.
+	 */
+	ariaDescribedby?: string | string[];
+
+	/**
+	 * Enable or disable floating flip behavior.
+	 *
+	 * @defaultValue `true`
+	 */
+	flip?: boolean;
+
+	/**
+	 * Whether the floating arrow is hidden.
+	 *
+	 * @defaultValue `true`
+	 */
+	hideArrow?: boolean;
+
+	/**
+	 * Reset modelValue to `null` or empty array if it no longer matches available items.
+	 */
+	enforceCoherence?: boolean;
+
+	/**
+	 * Controls how options are filtered during search.
+	 *
+	 * @defaultValue `() => []`
+	 */
+	filterBy?:
+		| string
+		| string[]
+		| false
+		| 'not_stashed'
+		| ((value: any, item: any, query: string | null) => boolean)
+		| null;
+
+	/** Path to item property for grouping options. */
+	groupBy?: string | ((item: Item) => string | number | symbol);
+
+	/**
+	 * 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'];
+
+	/**
+	 * Array of items or function to load them asynchronously.
+	 * Functions receive `(query, prefill, modelValue)` and can return a promise.
+	 *
+	 * @defaultValue `[]`
+	 */
+	items:
+		| Item[]
+		| ((query: string, prefill: boolean, modelValue: any[]) => Promise<Item[]>)
+		| ((query: string, prefill: boolean, modelValue: any[]) => Item[]);
+
+	/**
+	 * Height of the options in the listbox (px).
+	 *
+	 * @defaultValue `40`
+	 */
+	itemHeight?: number;
+
+	/**
+	 * Path to item property for display text or function to extract it.
+	 */
+	itemText?: string | ((item: Item) => string) | undefined;
+
+	/**
+	 * Path to item property for value or function to extract it.
+	 */
+	itemValue?: string | ((item: Item) => string) | undefined;
+
+	/**
+	 * 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 `0`
+	 */
+	padding?: CommonProps['padding'];
+
+	/**
+	 * Floating placement of the popover.
+	 *
+	 * @defaultValue `'bottom'`
+	 */
+	placement?: CommonProps['placement'];
+
+	/**
+	 * Controls when items are pre-loaded.
+	 * `'interaction'` loads on first user interaction, `true` loads immediately,
+	 * `false` loads only on explicit search/open flows.
+	 *
+	 * @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.
+	 *
+	 * @defaultValue `'Search options'`
+	 */
+	searchInputAriaLabel?: string;
+
+	/**
+	 * Accumulate selected items across searches instead of replacing them.
+	 */
+	stash?: boolean;
+
+	/**
+	 * Transition duration (ms) for popover show/hide animations.
+	 *
+	 * @defaultValue `300`
+	 */
+	transitionDuration?: number;
+
+	/**
+	 * Width of the popover in pixels, percentage, or `'auto'`.
+	 */
+	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 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) when `allowWriting` is enabled.
+	 */
+	(e: 'option:add', text: string): void;
+};
+
+/** Props exposed by the `activator` slot. */
+export type BbSelectPopoverActivatorSlotProps = {
+	/** Bind onto the activator element with `v-bind="props"` to wire up the popover reference. */
+	props: {
+		ref: (reference: unknown) => void;
+	};
+	/** Whether the popover is currently open. */
+	shown: boolean;
+	/** Whether the select is disabled. */
+	disabled: boolean | undefined;
+	/** Whether the select is read-only. */
+	readonly: boolean | undefined;
+	/** Whether options are currently being fetched. */
+	loading: boolean;
+	/** The current search query string. */
+	query: string;
+	/** Clears the current selection and query. */
+	clear: () => void;
+	/** Opens the popover. */
+	open: () => Promise<void>;
+	/** Closes the popover. */
+	close: () => Promise<void>;
+	/** 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> = {
+	/** The display text for this group. */
+	text: string;
+	/** The raw group item. */
+	item: Item;
+	/** Zero-based index of the first option in this group. */
+	index: number;
+	/** Number of options in this group. */
+	length: number;
+	/** Whether all options in this group are disabled. */
+	disabled: boolean;
+};
+
+export type BbSelectPopoverSlots<Item> = {
+	/**
+	 * Replaces the default trigger element that opens the select popover.
+	 */
+	activator?: (props: BbSelectPopoverActivatorSlotProps) => 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;
+	/**
+	 * Replaces the default group header rendered above grouped options.
+	 */
+	group?: (props: BbSelectPopoverGroupSlotProps<Item>) => any;
+	/**
+	 * Content appended inside the options list, after the last option.
+	 */
+	'options:append'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content appended outside the options list container.
+	 */
+	'options:append:outer'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content prepended inside the options list, before the first option.
+	 */
+	'options:prepend'?: (props: { focus: () => void }) => any;
+	/**
+	 * Content prepended outside the options list container.
+	 */
+	'options:prepend:outer'?: (props: { focus: () => void }) => any;
+};
+```