bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbSelectPopover.md

@@ -1,1669 +1,1330 @@
 # BbSelectPopover
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Provides popover-driven option selection and search.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbSelectPopover.md](./source/BbSelectPopover.md)
+
+## Usage & Guidelines
+
+### When to use
+
+`BbSelectPopover` is `BbSelect` with the inline form input removed: **you own the
+trigger**, it owns search, filtering, keyboard navigation, single/multiple
+selection and the virtualized options list. Reach for it when the control that
+opens the picker is _not_ a form field — a status pill, an avatar stack, a role
+badge, a toolbar button, a table-cell chip. It is the right tool for
+command-palette and inline-edit patterns.
+
+Prefer a sibling when the shape is different:
+
+- You want a **labelled, bordered form control** with hint/error/description
+  states → `BbSelect` (`./BbSelect.md`). That is a field, not a trigger.
+- A small, always-visible exclusive choice → `BbRadioGroup`; small static
+  multi-choice → `BbCheckboxGroup` / `BbSwitchGroup`.
+- Values the user _invents_ → `BbTag`; a known-but-growable set →
+  `BbSelectPopover` (or `BbSelect`) with `option:add`.
+
+Everything from the **Options and Items** and **Fetch Items** playbooks carries
+over unchanged — this component shares `BbSelect`'s option engine. This guide
+covers what is _specific_ to the popover: the activator, and the traps of
+driving a trigger you render yourself.
+
+### Map options with `item-text` / `item-value`
+
+Pass your domain objects to `items` as they are and name the display/value
+fields with `item-text` / `item-value` (dot-paths or extractor functions). The
+`v-model` holds the resolved **value**, not the whole object. The value-identity
+rules are the shared ones (see the Options and Items playbook), in brief:
+
+- Primitive `items` (`string[]` / `number[]`) need no mapping props; for object
+  items always set both.
+- Matching compares **value hashes** (deep structural equality), so object
+  values survive refetches — but prefer stable primitive ids.
+- Options resolving to a **duplicate value are silently dropped** (first wins).
+- Gate individual options with `selectable` — a boolean (`false` disables every
+  option) or a predicate `(item) => boolean`; rejected options render disabled
+  and keyboard navigation skips them. A `disabled` field on the item object is
+  inert domain data — feed it to the predicate
+  (`:selectable="(item) => !item.disabled"`) if it encodes availability.
+
+### Wire up an activator
+
+Provide the trigger through the `#activator` slot and **spread its `props` onto
+your element** with `v-bind="props"` — that wires the popover reference and the
+open/close handlers. The full slot scope:
+
+- `props` — spread onto the focusable trigger element.
+- `shown` — is the popover open (reflect it visually).
+- `toggle` / `open` / `close` — imperative open-state control (all async).
+- `clear` — empty the selection (and query).
+- `focus` — focus the search field (or the listbox when writing is disabled).
+- `query` — the current search string.
+- `selectedOptions` — the resolved selected options (`.text` / `.value` /
+  `.item`) — **popover state** (see below).
+- `text` — display text of the current selection — **popover state** (see below).
+- `disabled` / `readonly` / `loading` — state mirrors for styling the trigger.
+
+**The trigger must not depend on the popover's state — label it from your own
+data.** The popover is an _optional_ editing affordance: it may never be opened,
+and whether it has been opened must never change how the trigger reads. `text`
+and `selectedOptions` resolve the model against **loaded options**, so with a
+provider they stay empty until that provider first runs — by default, the first
+open. A trigger fed from them renders blank and then flickers into truth; a
+trigger fed from your own data is correct on first paint and stays that way.
+
+The robust pattern — used in the example — is a `computed` that resolves the
+label from the model against your own data:
+
+```ts
+const assigneeLabel = computed(
+	() => people.find((p) => p.id === assignee.value)?.name ?? 'Unassigned'
+);
+```
+
+(Array `items` do resolve on mount, so `text` is populated from the first paint
+there — but keep labelling from your own data anyway: it is the same amount of
+code, and it does not change meaning the day the array becomes a provider.)
+
+**Filter-pill assignee picker**
 
 ```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"
-		v-bind="$attrs"
-		: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
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
 	>
-		<div
-			v-if="computedAllowWriting"
-			class="bb-select-popover__search-container"
+		<span class="pr-1 text-xs font-medium text-gray-500">Assignee</span>
+		<BbSelectPopover
+			v-model="assignee"
+			compact
+			item-text="fullName"
+			item-value="id"
+			:items="teammates"
+			width="240px"
 		>
-			<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 #activator="{ props }">
+				<!-- The badge IS the trigger — Linear filter-pill grammar. Label
+				from our own state, never the slot's `text` (empty until first open
+				with a provider). -->
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:user"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{
+						assigneeLabel || 'Assign'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+		</BbSelectPopover>
+	</div>
 </template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
 
-<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';
-import type {
-	BbSelectPopoverEvents,
-	BbSelectPopoverProps,
-	BbSelectPopoverSlots,
-} from './types';
-
-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>>();
-defineOptions({ inheritAttrs: false });
-
-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;
+type Teammate = {
+	id: string;
+	fullName: string;
 };
 
-watch(
-	() => props.activator,
-	(val) => {
-		if (val) setActivatorRef(val);
-	},
-	{ immediate: true }
-);
-/**
- * END ACTIVATOR MANAGEMENT
- */
+const teammates: Teammate[] = [
+	{ id: 'ada', fullName: 'Ada Lovelace' },
+	{ id: 'grace', fullName: 'Grace Hopper' },
+	{ id: 'alan', fullName: 'Alan Turing' },
+	{ id: 'maggie', fullName: 'Margaret Hamilton' },
+];
 
-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 assignee = ref<string | null>(null);
 
-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 assigneeLabel = computed(
+	() => teammates.find((t) => t.id === assignee.value)?.fullName ?? ''
 );
+</script>
+```
 
-const normalizedWidth = computed(() => {
-	if (props.width === 'auto') return 'auto';
-	if (props.width == null || props.width === '') {
-		return activatorWidth.value ? `${activatorWidth.value}px` : '320px';
-	}
+### Multiple selection
 
-	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';
-	}
-});
+Add `multiple` and the model becomes an array — it **must be seeded as one**
+(`ref<string[]>([])`); a non-array model **throws at setup**
+(`"Multiple is set to \"true\" but modelValue is not an array."`). Cap the count
+with `max`: at the cap, unselected options auto-disable while selected ones never
+do, so the user can always deselect. Because the trigger is yours, _you_
+summarise the selection — a count, a chip cluster, an avatar stack — from
+`selectedOptions` or your own model.
 
-const panelStyles = computed(() => ({
-	'--bb-select-popover-width': normalizedWidth.value,
-}));
+**Reviewers filter pill with a live count**
 
-/**
- * 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
- */
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Filters</span>
+		<BbSelectPopover
+			v-model="reviewers"
+			compact
+			item-text="name"
+			item-value="id"
+			:items="people"
+			:max="4"
+			multiple
+			width="240px"
+		>
+			<template #activator="{ props }">
+				<!-- Summarise the multi-select yourself — a live count on the pill. -->
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:users"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props"
+						>Reviewers ({{ reviewers.length }})</BbBadgeButton
+					>
+				</BbBadge>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+
+type Person = { id: string; name: string };
+
+const people: Person[] = [
+	{ id: 'ada', name: 'Ada Lovelace' },
+	{ id: 'grace', name: 'Grace Hopper' },
+	{ id: 'alan', name: 'Alan Turing' },
+	{ id: 'katherine', name: 'Katherine Johnson' },
+	{ id: 'ken', name: 'Ken Thompson' },
+];
+
+// `multiple` requires an array model from the start.
+const reviewers = ref<string[]>(['ada', 'grace']);
+</script>
+```
 
-/**
- * Search input focus keeps the whole control in active state.
- */
-const onSearchInputFocus = (event: FocusEvent) => {
-	emit('focus', event);
-	setActive();
-};
+### Custom option rows
 
-const onSearchInputBlur = (event: FocusEvent) => {
-	emit('blur', event);
-	syncActiveStateOnBlur();
-};
+The `#option` slot replaces each row — exposing the raw `item`, resolved `text` /
+`value`, the row `index`, and `selected` / `focused` / `disabled` / `loading`
+flags — so options can carry avatars, badges or secondary metadata. Rows are
+fixed-height and virtualized: if your markup is taller than the default 40px
+(compact 32px), set `item-height` to match — and `header-height` for grouped
+headers.
 
-const onSearchInputChange = (event: Event) => {
-	emit('change', event);
-};
+**Option rows with avatar initials**
 
-const onPopoverFocusProxyFocus = (_event: FocusEvent) => {
-	setActive();
-};
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Owner</span>
+		<BbSelectPopover
+			v-model="owner"
+			compact
+			:item-height="40"
+			item-text="label"
+			item-value="value"
+			:items="people"
+			width="240px"
+		>
+			<template #activator="{ props }">
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:user"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{
+						ownerLabel || 'Set owner'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+			<template #option="{ item, text, selected }">
+				<span class="flex w-full items-center gap-2">
+					<BbAvatar :alt="text" size="sm">{{ item.initials }}</BbAvatar>
+					<span class="min-w-0 flex-1 truncate">{{ text }}</span>
+					<BbIcon
+						v-if="selected"
+						class="shrink-0 text-[color:var(--bb-text-muted)]"
+						icon="lucide:check"
+						:size="14"
+					/>
+				</span>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import {
+	BbAvatar,
+	BbBadge,
+	BbBadgeButton,
+	BbIcon,
+	BbSelectPopover,
+} from 'bitboss-ui';
+
+type Person = { label: string; value: string; initials: string };
+
+const people: Person[] = [
+	{ label: 'Ada Lovelace', value: 'ada', initials: 'AL' },
+	{ label: 'Grace Hopper', value: 'grace', initials: 'GH' },
+	{ label: 'Alan Turing', value: 'alan', initials: 'AT' },
+];
+
+const owner = ref<string | null>(null);
+const ownerLabel = computed(
+	() => people.find((p) => p.value === owner.value)?.label ?? ''
+);
+</script>
+```
 
-/**
- * Search on user typing inside the popover search field.
- */
-const onSearchInputInput = (event: Event) => {
-	emit('input', event);
-	debouncedGetter(query.value, false, props.modelValue);
-};
+### Fetch options with a provider
 
-const onListboxFocusedChange = (id: string | undefined) => {
-	activeDescendantId.value = id;
-};
+When options come from a backend, pass a **function** to `items`. It receives
+`(query, prefill, modelValue)` and returns `Item[]` or a `Promise<Item[]>` — the
+full call matrix is the shared one in the Fetch Items playbook. The essentials:
 
-/**
- * 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();
-};
+- `prefill === false` means exactly one thing: **the user typed** — search then.
+- Every component-initiated call (first load, dependency change, model change)
+  passes `prefill === true` and expects the current selection to stay resolvable
+  in the response — so return the selected items (by id) to keep the trigger
+  label and chips accurate.
+- `modelValue` is your v-model as-is; the prop types it `any` — an array in
+  `multiple` mode, the raw model value (possibly `null`) in single mode.
 
-const canProcessKeyboardBindings = computed(() => {
-	if (props.readonly) return false;
-	if (props.disabled) return false;
-	if (computedLoading.value) return false;
-	return true;
-});
+Runtime guarantees you should not re-implement: **debouncing** (`query-debounce-time`
+default 500ms; `deps-debounce-time` and `model-value-debounce-time` default 0),
+**race protection** (out-of-order responses discarded), **loading** (in-flight
+requests set the slot's `loading` flag automatically — the `loading` prop is only
+for _external_ pending state), and **errors** (a rejected provider is logged and
+the previous items kept — surface failures yourself via `useToast`). Enable
+`stash` to accumulate picked options across searches so chosen values stay
+resolvable even when later responses omit them.
 
-/**
- * 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);
+**Async, debounced destination picker**
 
-const focusFirstSelectedOption = () => {
-	const firstSelected = selectedOptions.value[0];
-	if (firstSelected?.valueHash) {
-		optionsContainer.value?.focusByHash(firstSelected.valueHash);
-		return;
-	}
-	optionsContainer.value?.focusFirstSelected();
-};
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Trip</span>
+		<BbSelectPopover
+			v-model="destination"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="searchCities"
+			loading-text="Searching…"
+			no-data-text="No city found"
+			:query-debounce-time="250"
+			width="240px"
+		>
+			<template #activator="{ props, loading }">
+				<!-- Badge `loading` reflects the provider's in-flight fetch. Label
+				from our own pool — never the slot's `text`. -->
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					:loading="loading"
+					prepend:icon="lucide:map-pin"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{
+						destinationLabel || 'Add destination'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+
+type City = { label: string; value: string };
+
+const pool: City[] = [
+	{ label: 'Amsterdam', value: 'amsterdam' },
+	{ label: 'Athens', value: 'athens' },
+	{ label: 'Barcelona', value: 'barcelona' },
+	{ label: 'Copenhagen', value: 'copenhagen' },
+	{ label: 'Dublin', value: 'dublin' },
+	{ label: 'Prague', value: 'prague' },
+];
+
+const fetchFromApi = (predicate: (city: City) => boolean) =>
+	new Promise<City[]>((resolve) => {
+		setTimeout(() => resolve(pool.filter(predicate)), 250);
+	});
 
-const focusLastSelectedOption = () => {
-	const lastSelected = selectedOptions.value[selectedOptions.value.length - 1];
-	if (lastSelected?.valueHash) {
-		optionsContainer.value?.focusByHash(lastSelected.valueHash);
-		return;
+const searchCities = (
+	query: string,
+	prefill: boolean,
+	// The raw v-model — type it with your own model shape: a single value (or
+	// null) here, an array in multiple mode.
+	modelValue: string | null
+): Promise<City[]> => {
+	// Prefill: resolve the current selection so the trigger label stays accurate.
+	if (prefill && modelValue) {
+		return fetchFromApi((city) => city.value === modelValue);
 	}
-	optionsContainer.value?.focusLastSelected();
+	if (!query.trim()) return Promise.resolve([]);
+	const q = query.trim().toLowerCase();
+	return fetchFromApi((city) => city.label.toLowerCase().includes(q));
 };
 
-/**
- * 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 destination = ref<string | null>(null);
+const destinationLabel = computed(
+	() => pool.find((c) => c.value === destination.value)?.label ?? ''
+);
+</script>
+```
 
-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();
-	}
-};
+### Laziness, prefill and the trigger label
+
+`prefill` controls **when the first load happens**: `'interaction'` (default) on
+first open, `true` immediately on mount (and during SSR via `onServerPrefetch`),
+`false` **search-first** — nothing is fetched until the user types a query.
+Opening the panel is not a search, so it loads nothing; until the first query the
+list shows a _"search to begin"_ hint instead of "no data".
+
+Reach for `false` when the result set is too large or too expensive to browse and
+the query is the only sensible entry point — a user picker over thousands of
+rows. Note the panel is deliberately empty on open: that is the mode telling the
+user to type.
+
+**Search-first needs both a way to search and something to defer**, so `false`
+falls back to loading on open when either is missing:
+
+- **Writing is disabled** (`disable-writing`, including the per-surface
+  `'mobile'`/`'desktop'` forms) — there is no search field, so a user could never
+  trigger the load and the panel would stay empty forever.
+- **The model is non-empty** — its text has to resolve for the selection to
+  render. (In-field `BbSelect` upgrades this to a mount prefill; see below.)
+
+**Two further cases ignore `prefill` entirely and always load**, because deferring
+would buy nothing or break a promise you made:
+
+- **`items` is an array.** There is no request to defer, so laziness would only
+  leave the selection unresolved. Options resolve on mount, whatever `prefill`
+  says — free, and it makes `text`/`selectedOptions` and coherence work from the
+  first paint.
+- **`enforce-coherence` over a non-empty model.** Validating a value is
+  impossible without options, so the popover loads and checks on that first load.
+  An empty model stays lazy — empty is always coherent, so there is nothing to
+  check.
+
+Outside those two, a standalone popover with a **provider does not** auto-upgrade
+a seeded model to an eager prefill the way in-field `BbSelect` does. That
+laziness is deliberate: a fetch per instance must be something you ask for (see
+_One popover per table row_).
+
+**Do not reach for `prefill: true` to fix a trigger label.** Resolve the label
+from your own state instead (above) — a trigger that needs a fetch to render is
+a trigger that renders wrong until the fetch lands.
+
+### Dependent fields and coherence
+
+When one picker constrains another, list the upstream value in `dependencies`:
+the provider re-runs whenever a dependency changes (value-hash compared, so array
+identity churn doesn't refetch), debounced by `deps-debounce-time`. Add
+`enforce-coherence` to auto-clean a now-invalid selection — multiple emits the
+**filtered array**, single emits **`null`**, an already-empty selection stays
+quiet. Because enforcement checks the merged result (fetched + stashed), a
+provider that returns `[]` on a `prefill: true` call **wipes a valid selection** —
+always resolve the current selection on component-initiated calls, or enable
+`stash`. The full mechanics are in the Coherence playbook.
+
+**You do not need `prefill: true` to make this work.** Asking for
+`enforce-coherence` over a seeded model _is_ a request to validate it, and that
+is impossible without options — so the popover loads on mount by itself and runs
+the check on that first load. The filter bar below relies on exactly that: no
+`prefill` prop anywhere, yet switching the project re-runs the milestone provider
+and clears a milestone the new project lacks, while a still-valid one survives.
+
+What that costs is honest and worth knowing: **`enforce-coherence` opts each
+instance into its own load**. One filter, one request. Fifty rows with a provider
+each, fifty requests. That is the trade you asked for by enabling it — and it is
+the reason the table pattern below hands every row the _same array_ instead.
+
+#### Never share one ref across instances
+
+Independent popovers each with their own model and their own `enforce-coherence`
+are fine: every instance judges **its own** value against **its own** options, so
+they never interfere. What breaks is binding them all to **one** ref:
 
-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 = '';
-};
+```vue
+<!-- WRONG: every row writes the same value -->
+<script setup>
+const status = ref(null); // ← one ref, shared by every row
+</script>
+<BbSelectPopover v-for="row in rows" v-model="status" enforce-coherence … />
+```
 
-const onEscape = async () => {
-	if (shown.value) {
-		await close();
-		focusActivator();
-	}
-};
+Now every instance judges **the same** value against **its own** options, and
+coherence's answer to a value it doesn't recognise is `null`. Pick a value only
+one row's options contain and the others each emit `null` in turn — measured with
+5 rows: the pick lands, four instances overwrite it, the model ends `null`. The
+user watches their choice vanish, with nothing logged.
 
-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)
-);
+The component cannot catch this for you: it receives a **value**, not a ref
+identity, and two rows legitimately holding the same value is ordinary. Give
+every row its own model.
 
-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 }
+**Toolbar filter pills — milestone follows project**
+
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-wrap items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Filters</span>
+		<BbSelectPopover
+			v-model="project"
+			compact
+			disable-writing
+			item-text="name"
+			item-value="id"
+			:items="projects"
+			width="200px"
+		>
+			<template #activator="{ props }">
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:folder"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{ projectLabel }}</BbBadgeButton>
+				</BbBadge>
+			</template>
+		</BbSelectPopover>
+		<BbSelectPopover
+			v-model="milestone"
+			compact
+			:dependencies="[project]"
+			:deps-debounce-time="150"
+			enforce-coherence
+			item-text="title"
+			item-value="id"
+			:items="fetchMilestones"
+			no-data-text="No milestone matches"
+			width="220px"
+		>
+			<template #activator="{ props }">
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:flag"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{
+						milestoneLabel || 'Milestone'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+
+type Project = { id: string; name: string };
+type Milestone = { id: string; title: string; project: string };
+
+const projects: Project[] = [
+	{ id: 'mobile', name: 'Mobile app' },
+	{ id: 'web', name: 'Web dashboard' },
+	{ id: 'design', name: 'Design system' },
+];
+
+const milestonePool: Milestone[] = [
+	{ id: 'ms-beta', title: 'Private beta', project: 'mobile' },
+	{ id: 'ms-launch', title: 'App Store launch', project: 'mobile' },
+	{ id: 'ms-ga', title: 'GA rollout', project: 'web' },
+	{ id: 'ms-audit', title: 'SOC 2 audit', project: 'web' },
+	{ id: 'ms-tokens', title: 'Token overhaul', project: 'design' },
+];
+
+const project = ref<string>('mobile');
+const milestone = ref<string | null>('ms-beta');
+
+// Trigger labels come from our own state — the slot's `text` is empty until
+// the popover first matches the model against loaded items.
+const projectLabel = computed(
+	() => projects.find((p) => p.id === project.value)?.name ?? 'Project'
 );
-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 milestoneLabel = computed(
+	() => milestonePool.find((m) => m.id === milestone.value)?.title ?? ''
 );
 
-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();
-	}
+// Query-aware provider. Component-initiated calls (the mount load, project
+// changes via `dependencies`) pass `prefill === true` and get the project's
+// full list back, so a still-valid selection stays resolvable —
+// `enforce-coherence` then clears only a milestone the new project lacks.
+// No `prefill` prop needed: `enforce-coherence` over a seeded model loads on
+// mount by itself, because validating a value requires having the options.
+const fetchMilestones = (
+	query: string,
+	prefill: boolean,
+	_modelValue: string | null
+): Promise<Milestone[]> => {
+	const inProject = milestonePool.filter((m) => m.project === project.value);
+	const q = query.trim().toLowerCase();
+	const matches = prefill
+		? inProject
+		: inProject.filter((m) => m.title.toLowerCase().includes(q));
+	return new Promise((resolve) => setTimeout(() => resolve(matches), 200));
 };
+</script>
+```
 
-/**
- * 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());
-	});
-});
+### One popover per table row (inline edit)
 
-const defaultGroupSymbol = Symbol('default');
+The status-pill-in-a-table is the popover's signature use — and the structure of
+the **page** decides whether it scales. Three rules, in priority order:
 
-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);
-};
+**1. Resolve the options once, for the whole page. Pass an array, not a provider.**
+This is the load-bearing decision. A provider is per-instance, so 50 rows means
+50 popovers each owning a fetch. Lift the fetch to the page, `await` it once, and
+hand every row the same array — 50 rows, **zero** requests, because there is
+nothing left to fetch. Array `items` are never lazy either: every row resolves on
+mount, so selections and coherence work immediately with no `prefill` prop.
 
-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);
-});
+```ts
+// Page level — once, not per row.
+const statuses = ref<Status[]>([]);
+onMounted(async () => (statuses.value = await api.statuses.list()));
+```
 
-/**
- * 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();
-	}
+**2. Hold the edit off the row — a page-level draft map keyed by id.** Never
+`v-model="item.status"`: writing straight back onto the slot's `item` mutates the
+table's data, so any refetch (a filter change, a poll) silently discards the edit,
+and a partially-dirty row has no clean before/after. Instead bind the value _down_
+(`:model-value="valueOf(item, 'status')"`) and commit it _up_ into a `drafts` map
+(`@update:model-value="setField(item, 'status', $event)"`). The map is the dirty
+set **and** the save payload; the row object stays pristine. This is the table
+case of the [inline-edit playbook](../../ai/guides/inline-edit-playbook.md) —
+reach for autosave there instead when the domain wants every pick to persist on
+the spot.
 
-	await nextTick();
-	document.addEventListener('click', onOutsideInteraction);
-	document.addEventListener('focusin', onOutsideInteraction);
+**3. Label the pill from your own state, not from the popover.**
+`{{ labelFor(valueOf(item, 'status')) }}` resolved against your page-level array —
+never the slot's `text`. The badge must read correctly on first paint for every
+row, including the hundreds nobody ever opens.
 
-	if (!focusPopoverContent) return;
+**Inline status cell — soft badge editor**
 
-	if (computedAllowWriting.value) {
-		await wait(0);
-		focusSearchInput();
-	} else {
-		await wait(0);
-		focusPopoverFocusProxy();
-	}
-};
+```vue
+<template>
+	<div class="flex max-w-xl flex-col gap-1.5">
+		<div
+			class="overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+		>
+			<BbTable
+				caption="Tickets — edit statuses, then Save the batch"
+				:columns="columns"
+				compact
+				item-value="id"
+				:items="tickets"
+			>
+				<!-- One popover per row. Three rules keep it cheap and correct:
+				     1. `:items="statuses"` is the SAME array for every row — resolved
+				        once at page level, so N rows cost zero extra requests.
+				     2. The edit is held in a page-level `drafts` map keyed by row id,
+				        NEVER written back onto `item`. Bind the value down with
+				        `valueOf` and commit up with `setField`; the row object stays
+				        pristine, so a refetch (filter, poll) can't wipe an edit.
+				     3. The pill renders from `valueOf(item, 'status')`, our own state —
+				        never the slot's `text` — so it is correct on first paint
+				        whether or not the popover is ever opened. -->
+				<template #status="{ item }">
+					<BbSelectPopover
+						compact
+						disable-writing
+						item-text="label"
+						item-value="value"
+						:items="statuses"
+						:model-value="valueOf(item, 'status')"
+						width="180px"
+						@update:model-value="setField(item, 'status', $event as Status)"
+					>
+						<template #activator="{ props, shown }">
+							<!-- Soft status pill: the badge IS the trigger. A dirty pill
+							(edited, not yet saved) keeps a deeper border until Save. -->
+							<BbBadge
+								append:icon="lucide:chevron-down"
+								:class="{
+									'status-trigger--editing': shown,
+									'status-trigger--dirty': isDirty(item),
+								}"
+								size="lg"
+								:variant="variantFor(valueOf(item, 'status'))"
+							>
+								<BbBadgeButton v-bind="props">{{
+									labelFor(valueOf(item, 'status'))
+								}}</BbBadgeButton>
+							</BbBadge>
+						</template>
+					</BbSelectPopover>
+				</template>
+			</BbTable>
+		</div>
 
-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 = '';
-};
+		<div class="flex items-center gap-2">
+			<BbButton :disabled="!dirtyCount" size="sm" @click="save">
+				Save{{ dirtyCount ? ` (${dirtyCount})` : '' }}
+			</BbButton>
+			<span class="text-xs text-gray-500">
+				Edits live in a draft map keyed by row id — the map is the save payload.
+				Rows are never mutated, so nothing is lost on a refetch.
+			</span>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, reactive, ref } from 'vue';
+import {
+	BbBadge,
+	BbBadgeButton,
+	BbButton,
+	BbSelectPopover,
+	BbTable,
+} from 'bitboss-ui';
+import type { BadgeVariantType, BbTableColumn } from 'bitboss-ui';
+
+type Status = 'open' | 'in-progress' | 'blocked' | 'done';
+type Ticket = { id: string; ref: string; title: string; status: Status };
+type Patch = Partial<Pick<Ticket, 'status'>>;
 
-const toggle = () => {
-	if (shown.value) return close();
-	return open();
-};
 /**
- * END POPOVER STATE
+ * The option list is resolved ONCE for the whole page and handed to every row as
+ * a plain array. With a provider per row, each popover would own its own fetch;
+ * as an array there is no request at all, and every row resolves on mount.
  */
+const statuses: Array<{ value: Status; label: string }> = [
+	{ value: 'open', label: 'Open' },
+	{ value: 'in-progress', label: 'In progress' },
+	{ value: 'blocked', label: 'Blocked' },
+	{ value: 'done', label: 'Done' },
+];
+
+const tickets = ref<Ticket[]>([
+	{
+		id: 't-1',
+		ref: 'BB-104',
+		title: 'Popover drops focus on Esc',
+		status: 'open',
+	},
+	{
+		id: 't-2',
+		ref: 'BB-118',
+		title: 'Table header misaligns at 320px',
+		status: 'in-progress',
+	},
+	{
+		id: 't-3',
+		ref: 'BB-121',
+		title: 'Token audit for dark mode',
+		status: 'blocked',
+	},
+	{
+		id: 't-4',
+		ref: 'BB-130',
+		title: 'Ship the migration guide',
+		status: 'done',
+	},
+]);
 
-/**
- * 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 columns: Array<BbTableColumn<Ticket>> = [
+	{ key: 'ref', label: 'Ref', width: 90 },
+	{ key: 'title', label: 'Title' },
+	{ key: 'status', label: 'Status', width: 140 },
+];
 
-const setActive = () => {
-	active.value = true;
-};
-const setInactive = () => {
-	if (!active.value) return;
-	active.value = false;
-	emit('inactive');
-};
+/* ---- Draft map: the edit lives here, never on the row -------------------- */
+
+const drafts = reactive<Record<string, Patch>>({});
 
-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;
+/**
+ * Read-through: the draft wins, the row is the fallback. Use a `key in` check,
+ * NOT `??` — a field legitimately drafted to a nullish value would otherwise
+ * fall through to the row.
+ */
+const valueOf = <K extends keyof Patch>(item: Ticket, key: K): Ticket[K] => {
+	const draft = drafts[item.id];
+	return draft && key in draft ? (draft[key] as Ticket[K]) : item[key];
 };
 
-const syncActiveStateOnBlur = () => {
-	setTimeout(() => {
-		if (isFocusInsideComponent(document.activeElement)) {
-			setActive();
-			return;
+/** One setter covers every field; re-picking the original un-dirties for free. */
+const setField = <K extends keyof Patch>(
+	item: Ticket,
+	key: K,
+	value: Patch[K]
+) => {
+	if (value === item[key]) {
+		delete drafts[item.id]?.[key];
+		if (drafts[item.id] && !Object.keys(drafts[item.id]).length) {
+			delete drafts[item.id];
 		}
-		setInactive();
-	}, 0);
+		return;
+	}
+	(drafts[item.id] ??= {})[key] = value;
 };
-/**
- * END ACTIVE STATE
- */
 
-const onClear = () => {
-	emit('update:modelValue', props.multiple ? [] : null);
+const isDirty = (item: Ticket) => drafts[item.id]?.status !== undefined;
+const dirtyCount = computed(() => Object.keys(drafts).length);
+
+/** The map IS the payload. Here it patches the local rows; a real app PATCHes. */
+const save = () => {
+	tickets.value = tickets.value.map((row) =>
+		drafts[row.id] ? { ...row, ...drafts[row.id] } : row
+	);
+	Object.keys(drafts).forEach((id) => delete drafts[id]);
 };
 
-/**
- * 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 }
-);
+/* Row labels come from our own state — stable regardless of popover state. */
+const labelFor = (status: Status) =>
+	statuses.find((s) => s.value === status)?.label ?? '—';
 
-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 }
-);
+const VARIANT: Record<Status, BadgeVariantType> = {
+	open: 'soft-gray',
+	'in-progress': 'soft-blue',
+	blocked: 'soft-red',
+	done: 'soft-green',
+};
 
-onBeforeUnmount(() => {
-	cleanupActivator?.();
-	document.removeEventListener('click', onOutsideInteraction);
-	document.removeEventListener('focusin', onOutsideInteraction);
-});
-/**
- * END ACTIVATOR LISTENERS
- */
+const variantFor = (status: Status) => VARIANT[status];
 </script>
 
-<style lang="postcss">
-.bb-select-popover {
-	width: var(--bb-select-popover-width, 320px);
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color.
+     Non-scoped so variant classes on the child badge receive the accents. -->
+<style>
+.bb-badge.bb-badge--soft-gray {
+	--accent: #64748b;
+}
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-red {
+	--accent: #dc2626;
+}
+.bb-badge.bb-badge--soft-gray,
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-red {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+
+/* Unsaved edit: hold a deeper border until the batch is saved. */
+.status-trigger--dirty {
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--color) 60%, var(--bb-panel));
+}
 
-	.bb-select-popover__search-container {
-		align-items: center;
-		border-bottom: 1px solid var(--bb-border);
-		display: flex;
-		padding: 0.375rem 0.75rem;
-		position: relative;
-	}
+/* While open, deepen the badge's own hue — not a generic indigo ring. */
+.status-trigger--editing {
+	--bg: color-mix(in oklab, var(--color) 25%, var(--bb-panel));
+	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
+}
+</style>
+```
 
-	.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;
-	}
+**Why this shape and not the obvious one.** The instinct is to give each row a
+provider and `enforce-coherence` so rows keep themselves honest. That inverts the
+cost: coherence with a seeded model makes every row load, so the table's request
+count tracks its row count, and each row can rewrite its own model from a
+response you never see. The page-level array collapses all of it — one source,
+one fetch, every row consistent by construction, nothing to prune because every
+row already draws from the same list.
+
+If rows genuinely need **different** option sets (per-type statuses, say),
+resolve _those_ lists at page level too — one fetch per distinct set, keyed by
+type — and pass the right array down. Still zero per-row requests. Reach for a
+per-row provider only when the options truly depend on that row's identity and
+cannot be batched, and then expect the request count to follow the row count.
+
+Pruning stale values in a table is a **page-level** job, not a per-row one: when
+the source list narrows, reconcile the rows yourself in one pass, where you can
+show the user what changed (or ask them) instead of nulling values invisibly.
+
+### Create options on the fly (`option:add`)
+
+Pressing Enter in the search field with **no option highlighted** emits
+`option:add` with the trimmed query (it can be `''`, and it won't fire if the
+query already matches a selected option). The component creates nothing itself:
+append the new item to `items` and select it. This is the idiomatic pattern for
+closed-but-growable vocabularies — the same as `BbSelect`. The behaviour is gated
+by the search field existing; `disable-writing` (which removes the field) also
+disables it.
 
-	.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%;
-	}
+```ts
+const roles = ref<string[]>(['Reviewer', 'Approver']);
+const role = ref<string | null>(null);
+
+const onAdd = (text: string) => {
+	const name = text.trim();
+	if (!name || roles.value.includes(name)) return;
+	roles.value.push(name);
+	role.value = name;
+};
+```
 
-	.bb-select-popover__search-icon {
-		opacity: 1;
-	}
+### Group options
 
-	&.bb-select-popover--errors {
-		.bb-select-popover__search-error-icon {
-			color: var(--bb-danger);
-			opacity: 1;
-		}
+`group-by` (a field path or a function) buckets options under headers; the
+`#group` slot styles each header and receives `{ text, item, index, length,
+disabled }` — `length` is the group size, `index` the list index of its first
+option. Identical to `BbSelect`, anchored to your trigger.
 
-		.bb-select-popover__search-icon,
-		.bb-select-popover__search-spinner {
-			opacity: 0;
-		}
-	}
+**Roles grouped by department**
 
-	&.bb-select-popover--loading {
-		.bb-select-popover__search-spinner {
-			opacity: 1;
-		}
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Role</span>
+		<BbSelectPopover
+			v-model="role"
+			compact
+			group-by="department"
+			item-text="label"
+			item-value="value"
+			:items="roles"
+			width="240px"
+		>
+			<template #activator="{ props }">
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:briefcase"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{
+						roleLabel || 'Assign role'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+			<template #group="{ text, length }">
+				<div
+					class="flex items-center justify-between px-2 text-xs font-medium text-gray-500"
+				>
+					<span>{{ text }}</span>
+					<span>{{ length }}</span>
+				</div>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+
+type Role = { label: string; value: string; department: string };
+
+const roles: Role[] = [
+	{ label: 'Analyst', value: 'mkt-analyst', department: 'Marketing' },
+	{ label: 'Manager', value: 'mkt-manager', department: 'Marketing' },
+	{ label: 'Frontend', value: 'eng-fe', department: 'Engineering' },
+	{ label: 'Backend', value: 'eng-be', department: 'Engineering' },
+];
+
+const role = ref<string | null>(null);
+const roleLabel = computed(
+	() => roles.find((r) => r.value === role.value)?.label ?? ''
+);
+</script>
+```
 
-		.bb-select-popover__search-icon,
-		.bb-select-popover__search-error-icon {
-			opacity: 0;
-		}
-	}
+### Panel header, footer and empty/loading states
 
-	.bb-listbox {
-		--option-h: var(--option-height);
-		display: block;
+`#header` and `#footer` pin content above the search field and below the options
+list, in **both** the desktop popover and the mobile adaptive sheet. Both receive
+`{ close, clear, focus, query, selectedOptions }` — ideal for a title and a
+"Done" action. Two more panel slots cover async states: `#loading` and
+`#no-data` (both receive `{ query }`; `#no-data` also a `focus()` callback), or
+their string equivalents `loading-text` / `no-data-text`.
 
-		&.bb-listbox--open {
-			transition: min-height 0s 0s;
+**A titled panel with a done action**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Destination</span>
+		<BbSelectPopover
+			v-model="city"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="cities"
+			width="240px"
+		>
+			<template #activator="{ props }">
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					prepend:icon="lucide:map-pin"
+					size="lg"
+					variant="outline"
+				>
+					<BbBadgeButton v-bind="props">{{
+						cityLabel || 'Add destination'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+			<template #header>
+				<span class="text-sm font-medium">Popular destinations</span>
+			</template>
+			<template #footer="{ close, clear }">
+				<div class="flex w-full items-center gap-2">
+					<BbButton class="mr-auto" variant="ghost" @click="clear"
+						>Clear</BbButton
+					>
+					<BbButton variant="primary" @click="close">Done</BbButton>
+				</div>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbBadge, BbBadgeButton, BbButton, BbSelectPopover } from 'bitboss-ui';
+
+type City = { label: string; value: string };
+
+const cities: City[] = [
+	{ label: 'Amsterdam', value: 'ams' },
+	{ label: 'Berlin', value: 'ber' },
+	{ label: 'Lisbon', value: 'lis' },
+	{ label: 'Milan', value: 'mil' },
+];
+
+const city = ref<string | null>(null);
+const cityLabel = computed(
+	() => cities.find((c) => c.value === city.value)?.label ?? ''
+);
+</script>
+```
 
-			.bb-listbox__outer-container {
-				grid-template-rows: 1fr;
-				opacity: 1;
-				transition-delay: 0s, 00ms;
+### Search field and filtering
 
-				> * {
-					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;
-					}
-				}
-			}
-		}
+The panel carries a search field (role `searchbox`). Filtering follows the shared
+semantics (Options/Fetch playbooks): array items filter locally by
+case-insensitive **substring** against the display text; `filter-by: ['path', …]`
+searches the listed paths **instead of** the text (every path must exist on every
+item or matching throws); with a provider, the local substring filter **still
+applies on top of** the response, so keep server matches substring-compatible.
 
-		&.bb-listbox--multiple {
-			.autocomplete-option__checkbox {
-				display: inline-block !important;
-			}
-		}
+`disable-writing` removes the search field entirely — `true` everywhere, or
+`'mobile'` / `'desktop'` to drop it on one platform only. It is also the
+supported way to disable typing/filtering (and, with it, `option:add`); use it
+when the option list is short enough to just scroll.
 
-		.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>
-```
+**Scroll-only status pill**
 
-## Types
+```vue
+<template>
+	<div
+		class="flex max-w-sm items-center gap-1.5 rounded-[var(--bb-radius)] border p-2"
+	>
+		<span class="pr-1 text-xs font-medium text-gray-500">Status</span>
+		<BbSelectPopover
+			v-model="status"
+			compact
+			disable-writing
+			:items="statuses"
+			width="200px"
+		>
+			<template #activator="{ props, shown }">
+				<BbBadge
+					append:icon="lucide:chevron-down"
+					:class="{ 'status-trigger--editing': shown }"
+					size="lg"
+					:variant="variantFor(status)"
+				>
+					<BbBadgeButton v-bind="props">{{
+						status ?? 'Set status'
+					}}</BbBadgeButton>
+				</BbBadge>
+			</template>
+		</BbSelectPopover>
+	</div>
+</template>
+<script setup lang="ts">
+import { BbBadge, BbBadgeButton, BbSelectPopover } from 'bitboss-ui';
+import type { BadgeVariantType } from 'bitboss-ui';
+import { ref } from 'vue';
 
-```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;
-};
+const statuses = ['Draft', 'In review', 'Approved', 'Published'];
+type Status = (typeof statuses)[number];
 
-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;
-};
+const status = ref<Status | null>(null);
 
-/** 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>;
+const VARIANT: Record<Status, BadgeVariantType> = {
+	Draft: 'soft-gray',
+	'In review': 'soft-amber',
+	Approved: 'soft-blue',
+	Published: 'soft-green',
 };
 
-/** 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;
-};
+const variantFor = (value: Status | null): BadgeVariantType =>
+	value ? VARIANT[value] : 'outline';
+</script>
 
-/** 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;
-};
+<!-- Soft status palette — canonical source: ai/guides/design-language.md § Using color. -->
+<style>
+.bb-badge.bb-badge--soft-gray {
+	--accent: #64748b;
+}
+.bb-badge.bb-badge--soft-blue {
+	--accent: #2563eb;
+}
+.bb-badge.bb-badge--soft-green {
+	--accent: #16a34a;
+}
+.bb-badge.bb-badge--soft-amber {
+	--accent: #d97706;
+}
+.bb-badge.bb-badge--soft-gray,
+.bb-badge.bb-badge--soft-blue,
+.bb-badge.bb-badge--soft-green,
+.bb-badge.bb-badge--soft-amber {
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
 
-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;
-};
+.status-trigger--editing {
+	--bg: color-mix(in oklab, var(--color) 25%, var(--bb-panel));
+	--border-color: color-mix(in oklab, var(--color) 45%, var(--bb-panel));
+	box-shadow: 0 0 0 var(--bb-ring-size) var(--ring);
+}
+</style>
 ```
+
+### Sizing and layout
+
+- `width` sets the popover width — a number (px), a CSS string (`'240px'`,
+  `'100%'`), or `'auto'`. Unlike `BbSelect` (whose panel always matches the
+  control), here the trigger and panel are independent, so size the panel
+  explicitly.
+- `compact` applies the dense density variant (32px options, 24px group headers).
+- `item-height` / `header-height` tune the virtualized row heights when you use
+  taller custom `#option` / `#group` markup.
+- Placement props mirror the palette/dropdown float: `placement`, `offset`
+  (default 4), `padding`, `boundary`, `disable-flip`, `transition-duration`. The
+  panel is a frame, not a bubble — it never shows an arrow.
+
+### Adaptive mobile sheet
+
+With `adaptive` (default: global `config.adaptive`, which is `true`), the panel
+opens as a bottom off-canvas sheet on mobile viewports (below
+`config.mobileMaxWidth`) instead of a floating popover — same search, options and
+`#header`/`#footer` slots, plus a representation of the current selection between
+them. The surface is **latched per open cycle**: a mid-open resize never swaps
+popover ↔ sheet. `off-canvas-props` forwards extra `BbOffCanvas` props to the
+sheet (`size`, `draggable`, `fullscreen`, `stack`); `:adaptive="false"` keeps a
+floating popover everywhere.
+
+### Events and v-model
+
+- `update:modelValue` — the resolved value (single) or array (multiple), on pick,
+  `clear`, coherence enforcement, and — in `multiple` mode only — deselect.
+  A second click on the current option in single mode emits nothing.
+- `option:add` — Enter on a non-matching query with nothing highlighted (above).
+- `focus` / `blur` — the activator gaining/losing focus.
+- `input` / `change` — native events from the panel search field.
+- `click` — the activator was clicked.
+- `inactive` — focus has fully left the component (**trigger and panel**). Because
+  focus legitimately moves into the panel while open, validate/react on
+  `inactive`, not on `blur`.
+
+### Config and platform
+
+- **No teleport** — the popover renders **in the component's own subtree** (it is
+  not portalled to `<body>`), so it inherits your CSS context and is directly
+  queryable (handy for tests: the open panel is `.bb-listbox--open` on the same
+  root, no portal hop).
+- **Global config** — `config.adaptive` (default for `adaptive`),
+  `config.mobileMaxWidth` (the mobile threshold), `config.locale` (the search
+  field's default accessible name and panel string defaults).
+- **SSR / Nuxt** — `prefill: true` providers also run in `onServerPrefetch`, so
+  server-rendered pages hydrate with options loaded; keep providers isomorphic
+  (no `window` access).
+
+### Works well with
+
+- `BbSelect` — the same engine as a labelled form field; swap when the trigger
+  should be an inline input with hint/error states.
+- `BbTable` — popover triggers as inline-edit cells or toolbar filters; list
+  their models in the table provider's `dependencies`.
+- `BbButton` — the natural activator (it forwards `props` and exposes a
+  `loading` state to reflect fetches).
+- `useToast` — surface provider failures the component only logs.
+
+### Gotchas and constraints
+
+- `multiple` with a non-array model **throws at setup** — seed `ref([])`.
+- A seeded model shows **no trigger `text`** until the first load (no eager
+  prefill upgrade, by design) — resolve the label from your own state. Array
+  `items` resolve on mount, so this only bites providers.
+- The local substring filter also applies to provider results — server matches
+  whose text doesn't contain the query are hidden.
+- `filter-by` is `string[]` only and matches exactly those paths; each must exist
+  on every item or matching throws.
+- `prefill: false` is search-first: opening fetches nothing and the panel shows
+  the "search to begin" hint until the user types. It quietly falls back to
+  loading on open when writing is disabled, the model is non-empty, or `items` is
+  an array.
+- `enforce-coherence` + a provider that drops the selection on component-initiated
+  (`prefill === true`) calls = wiped model — and since the check now runs on the
+  **first** load, that wipe happens at mount rather than later. Resolve the
+  current selection in those responses, or enable `stash`.
+- `enforce-coherence` opts **each instance** into its own load. One field, one
+  request; N provider-backed rows, N requests.
+- `option:add` can fire with an empty string — trim and guard.
+- **Clicking the selected option does not clear a single select** — it re-picks
+  it and closes the panel. Emptying is the `clear` callback (activator/panel
+  slot scope), never an accidental second click. Multiple mode still toggles.
+- **`null` as a real "All" option** works — it resolves and renders as the
+  selection — but it overloads the value the component uses for _nothing
+  selected_. So a `null` model stays lazy (nothing to resolve, no load, not even
+  with `enforce-coherence`), `clear` is indistinguishable from picking "All", and
+  an `enforce-coherence` prune emits `null` — i.e. a stale value **widens to
+  "All"** rather than clearing. Fine if you want it; use a sentinel
+  (`'all'`) if "everything" and "nothing" must stay distinct.
+
+### Anti-patterns
+
+- Reading `text` (or `selectedOptions`) for the trigger label instead of
+  computing it from your own state — with a provider they are empty until the
+  first load, so the trigger's appearance ends up depending on whether the panel
+  was ever opened.
+- Binding many instances to **one shared ref**: each judges the same value against
+  its own options and every instance that disagrees emits `null`, so the user's
+  pick is overwritten by its neighbours. One model per row.
+- Giving every table row its own **provider**: N rows becomes N requests. Resolve
+  the options once at page level and pass the same array down.
+- Reaching for `prefill: true` to populate a trigger label.
+- Rebuilding chips, counts or select-all in wrapper markup when `max`,
+  `selectedOptions` and the panel slots cover it.
+- Hand-rolled debounce/loading refs around the provider.
+- `watch(filter, refetch)` when `dependencies` exists; blind `model = null`
+  resets when `enforce-coherence` would preserve still-valid values.
+- Using it where an inline labelled field is wanted (that's `BbSelect`), or for a
+  static three-option choice (that's `BbRadioGroup`).
+
+### Accessibility
+
+- The activator carries the accessible name — make it a real focusable element (a
+  `<button>` or `BbButton`), and give icon-only triggers an `aria-label`.
+- The in-panel search field is labelled by `search-input-aria-label` (defaults to
+  "Search options"); override it to match your domain.
+- The component manages listbox roles, `aria-activedescendant`, the full keyboard
+  model and focus return to the trigger on close — do not reimplement them.
+- Because the trigger is yours, reflect the open state visually (the `shown` slot
+  prop) so keyboard and low-vision users can see the popover is expanded.
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `activator` | `Record<string, any> \| HTMLElement \| null \| undefined` |  |  | External activator element or component ref. When provided, the activator slot is not rendered and event listeners are attached programmatically to the referenced element. |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | 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 sele… |
+| `anchor` | `Record<string, any> \| HTMLElement \| null \| undefined` | `null` |  | 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. |
+| `ariaDescribedby` | `string \| string[] \| undefined` |  |  | Space-separated IDREF(s) that describe this field for assistive technologies. Accepts either a string or array of ids. |
+| `ariaInvalid` | `boolean \| undefined` | `undefined` |  | Explicit invalid state for accessibility semantics. Falls back to `hasErrors` when not provided. |
+| `autocomplete` | `string \| undefined` | `"off"` |  | Browser autocomplete hint for the popover search input. |
+| `boundary` | `string \| Record<string, any> \| HTMLElement \| null \| undefined` |  |  | Constrains the popover to a specific boundary element. |
+| `clearable` | `boolean \| undefined` |  |  | 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 a… |
+| `compact` | `boolean \| undefined` |  |  | Apply the compact density variant. |
+| `dependencies` | `unknown[] \| undefined` | `[]` |  | Additional dependencies that trigger item reloading when changed. |
+| `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for dependency-triggered reloads. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disableFlip` | `boolean \| undefined` |  |  | Disables the automatic flip to the opposite side when the popover would overflow (flipping is on by default). |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | 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. |
+| `enforceCoherence` | `boolean \| undefined` |  |  | Reset modelValue to `null` or empty array if it no longer matches available items. |
+| `filterBy` | `string[] \| undefined` | `[]` |  | 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 filte… |
+| `groupBy` | `string \| ((item: Item) => string \| number \| symbol) \| undefined` |  |  | Path to item property for grouping options. |
+| `hasErrors` | `boolean \| undefined` |  |  | Marks the component as being in error state. |
+| `hasWarning` | `boolean \| undefined` |  |  | Marks the component as being in a warning state. Visually mirrors `hasErrors` but uses `--bb-warn` chrome; errors take priority when both are set. |
+| `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). Defaults to 24px (compact) or 32px. Only applies when `groupBy` is set. |
+| `id` | `string \| undefined` |  |  | Explicit id for the component. Used to generate ids for listbox and options. |
+| `itemHeight` | `number \| undefined` |  |  | Height of the options in the listbox (px). |
+| `items` | `Item[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<Item[]>) \| ((query: string, prefill: boolean, modelValue: any) => Item[])` |  | yes | 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… |
+| `itemText` | `ItemAccessor<Item, string> \| undefined` |  |  | Path to item property for display text or function to extract it. |
+| `itemValue` | `ItemAccessor<Item> \| undefined` |  |  | Path to item property for value or function to extract it. |
+| `loading` | `boolean \| undefined` |  |  | Display the loading state styles. |
+| `loadingText` | `string \| undefined` |  |  | Message shown while items are being loaded. |
+| `max` | `number \| undefined` | `Infinity` |  | Maximum number of selectable items (limits selection when `multiple` is true). |
+| `modelValue` | `any` |  | yes | v-model value. Single value for single select, array for multiple select. |
+| `modelValueDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) for modelValue change handling. |
+| `multiple` | `boolean \| undefined` |  |  | Enable multiple item selection. When true, modelValue must be an array. |
+| `noDataText` | `string \| undefined` |  |  | Message displayed when no items are available. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile (e.g. `size`, `draggable`, `fullscreen`, `stack`). |
+| `offset` | `number \| undefined` | `4` |  | Distance (px) between the activator and the popover. |
+| `padding` | `number \| undefined` | `10` |  | Minimum page padding used by floating shift middleware. |
+| `placement` | `Placement \| undefined` | `"bottom"` |  | Floating placement of the popover. |
+| `prefill` | `boolean \| "interaction" \| undefined` | `"interaction"` |  | 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 th… |
+| `queryDebounceTime` | `number \| undefined` | `500` |  | Debounce delay (ms) before triggering search queries after user input stops. |
+| `readonly` | `boolean \| undefined` |  |  | Prevents opening the popover while keeping the activator accessible. |
+| `searchInputAriaLabel` | `string \| undefined` |  |  | Accessible label used by the search input rendered inside the popover. Falls back to the localized `select.searchLabel` key when omitted. |
+| `selectable` | `boolean \| ((item: Item) => boolean) \| undefined` | `true` |  | 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. |
+| `stash` | `boolean \| undefined` |  |  | Accumulate selected items across searches instead of replacing them. |
+| `transitionDuration` | `number \| undefined` | `transitions.medium` |  | Transition duration (ms) for popover show/hide animations. |
+| `width` | `string \| number \| undefined` | `"200"` |  | Width of the popover in pixels, percentage, or `'auto'`. |
+
+## Events
+
+- `active` — `(e: "active"): void` — Emitted when the component becomes active (focus enters it).
+- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when the activator loses focus.
+- `change` — `(e: "change", event: Event): void` — Emitted when the value changes via native change event.
+- `click` — `(e: "click", event: MouseEvent): void` — Emitted when the activator is clicked.
+- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when the activator receives focus.
+- `inactive` — `(e: "inactive"): void` — Emitted when focus moves outside the entire component after it was active.
+- `input` — `(e: "input", event: Event): void` — Emitted on native input events from the search input.
+- `option:add` — `(e: "option:add", text: string): 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).
+- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the next selection value whenever selection changes.
+
+## Slots
+
+- `activator` — scope: `BbSelectPopoverActivatorSlotProps` — Replaces the default trigger element that opens the select popover.
+- `footer` — scope: `BbSelectPopoverPanelSlotProps` — Content pinned to the bottom of the panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
+- `group` — scope: `BbSelectPopoverGroupSlotProps<Item>` — Replaces the default group header rendered above grouped options.
+- `header` — scope: `BbSelectPopoverPanelSlotProps` — Content pinned to the top of the panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
+- `loading` — scope: `{ query: string; }` — Content shown inside the options dropdown while items are loading.
+- `no-data` — scope: `{ query: string; focus: () => void; }` — Content shown when no options match the query or the list is empty.
+- `option` — scope: `BbSelectPopoverOptionSlotProps<Item>` — Replaces the default rendering of each option row in the dropdown.
+
+## See Also
+
+- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.
+- [BbPopover](./BbPopover.md) — Anchors floating content to reference elements.