bitboss-ui 3.0.0-beta.5 → 3.0.0-beta.51

package/dist/ai/source/BbSelect.md

@@ -6,152 +6,404 @@
 
 ```vue
 <template>
-	<BaseInputContainer
+	<CommonField
 		:id="id"
 		class="bb-select"
 		:clearable="isClearable"
 		:compact="compact"
 		:description="description"
-		:direction="direction"
 		:disabled="disabled"
-		:errors="errors"
+		:errors="fieldErrors"
 		:has-errors="hasErrors"
 		:has-value="hasValue"
-		:has-warning="hasWarning"
+		:has-warnings="hasWarnings"
 		:hide-label="hideLabel"
 		:hint="hint"
+		:input-align="inputAlign"
 		:label="label"
+		:label-align="labelAlign"
 		:label-mode="resolvedLabelMode"
 		:label-position="labelPosition"
+		:layout="layout"
 		:loading="loading"
 		:mobile="isMobile"
-		:model-value="modelValue"
 		:name="name"
-		:readonly="readonly"
+		:passthrough="passthrough"
+		:readonly="fieldReadonly"
 		:reverse="reverse"
+		:show-asterisk="showAsterisk"
 		:show-hint="showHint"
 		:warnings="warnings"
+		v-bind="passthrough.forwardAttrs"
 	>
 		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
-			<BaseSelect
-				:id="id"
+		<template v-if="$slots.description" #description="data"
+			><slot name="description" v-bind="data"></slot
+		></template>
+		<template
+			#input="{
+				id: fieldId,
+				hasErrors: fieldHasErrors,
+				hasWarnings: fieldHasWarnings,
+				ariaDescribedby,
+			}"
+		>
+			<BbSelectPopover
+				:id="fieldId"
 				:adaptive="adaptive"
-				:append:icon="props['append:icon']"
+				:anchor="wrapperRef"
 				:aria-describedby="ariaDescribedby"
+				:aria-invalid="fieldHasErrors || undefined"
 				:autocomplete="autocomplete"
-				:autofocus="autofocus"
-				:clearable="clearable"
-				:comma="comma"
 				:compact="compact"
 				:dependencies="dependencies"
 				:deps-debounce-time="depsDebounceTime"
 				:disable-writing="disableWriting"
 				:disabled="disabled"
+				:empty-text="emptyText"
 				:enforce-coherence="enforceCoherence"
+				:failed-text="failedText"
 				:filter-by="Array.isArray(filterBy) ? filterBy : undefined"
 				:group-by="groupBy"
-				:has-errors="hasErrors"
-				:has-warning="hasWarning"
 				:header-height="headerHeight"
 				:item-height="itemHeight"
+				:item-props="itemProps"
 				:item-text="itemText"
 				:item-value="itemValue"
 				:items="items"
 				:loading="loading"
 				:loading-text="loadingText"
 				:max="max"
-				:max-selected-labels="maxSelectedLabels"
-				:model-value="modelValue"
+				:model-value="fieldModel"
 				:model-value-debounce-time="modelValueDebounceTime"
 				:multiple="multiple"
-				:name="name"
-				:no-data-text="noDataText"
-				:off-canvas-props="offCanvasProps"
-				:placeholder="placeholder"
-				:prefill="prefill"
-				:prepend:icon="props['prepend:icon']"
+				:off-canvas-props="resolvedOffCanvasProps"
+				:prefill="computedPrefill"
+				:pt="popoverPt()"
 				:query-debounce-time="queryDebounceTime"
-				:readonly="readonly"
-				:required="required"
+				:readonly="fieldReadonly"
 				:selectable="selectable"
-				:selected-labels-fn="selectedLabelsFn"
 				:stash="stash"
 				:transition-duration="transitionDuration"
-				v-bind="eventListeners"
+				width="100%"
+				v-bind="popoverListeners()"
 			>
+				<template
+					#activator="{
+						props: activatorProps,
+						shown,
+						loading: activatorLoading,
+						text,
+						selectedOptions,
+						clear,
+						query,
+						focus,
+						close,
+						toggle,
+					}"
+				>
+					<CommonFieldInput
+						ref="wrapperRef"
+						:active="shown"
+						:append:icon="appendIcon"
+						class="bb-select__field"
+						:class="{
+							'bb-select__field--shown': shown,
+							'bb-select__field--disabled': disabled,
+							'bb-select__field--readonly': fieldReadonly,
+						}"
+						:clearable="clearable"
+						:compact="compact"
+						:disabled="disabled"
+						:has-errors="fieldHasErrors"
+						:has-value="hasValue"
+						:has-warnings="fieldHasWarnings"
+						:loading="activatorLoading"
+						:passthrough="boxRowPassthrough(activatorLoading)"
+						:prepend:icon="declaredProps['prepend:icon']"
+						:readonly="fieldReadonly"
+						:variant="variant"
+						@click:clear="
+							() => {
+								clear();
+								nextTick(refocusActivator);
+							}
+						"
+						@container:click="toggle"
+					>
+						<!-- The activator input is a transparent overlay: its own value stays
+						empty (the visible face is this span), so the resolved selection must
+						reach AT through the name — label + selection node (below), the
+						button-select labelling pattern. aria-valuetext is not supported on
+						the combobox role, so it cannot be the value channel. -->
+						<span
+							:id="`${fieldId}__value`"
+							ref="valueRef"
+							class="bb-select__value"
+						>
+							<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
+							<input
+								:id="fieldId"
+								:aria-labelledby="`${fieldId}__label ${fieldId}__selection`"
+								:aria-readonly="fieldReadonly || undefined"
+								:aria-required="activatorAriaRequired"
+								:autofocus="autofocus"
+								class="bb-select__activator"
+								:disabled="disabled"
+								type="button"
+								v-bind="
+									mergeProps(
+										activatorProps,
+										passthrough.part('activator', { loading: activatorLoading })
+									)
+								"
+							/>
+							<!-- eslint-enable vue/attributes-order -->
+
+							<template v-if="multiple">
+								<span
+									v-if="usesOverflowCollapse || !isCollapsed"
+									ref="chipsContainerRef"
+									class="bb-select__chips-row"
+									:class="{
+										'bb-select__chips-row--hidden': isCollapsed,
+										'bb-select__chips-row--chips':
+											!comma && !!selectedOptions.length,
+									}"
+								>
+									<template v-if="comma">
+										<!-- eslint-disable vue/attributes-order -- `pt` binds LAST so a consumer listener runs after ours (PASSTHROUGH.md T17) -->
+										<span
+											v-for="item in selectedOptions"
+											:key="hash(item.value)"
+											class="bb-select__comma"
+											v-bind="passthrough.part('comma', {}, item.item)"
+										>
+											<!-- eslint-enable vue/attributes-order -->
+											{{ item.text }}
+										</span>
+									</template>
+									<!-- One badge per selection: removable (clearable) when
+									deselection is allowed, non-removable otherwise. The `chip`
+									slot replaces the badge outright (the badge below is its
+									fallback), so a consumer can render their own chip — a colored
+									tag, an avatar row — without reaching for `prepend`. No wrapper
+									element around it: the row itself supplies the spacing (see
+									`--chips` in index.css), so custom content needs none of our
+									class names to sit correctly. -->
+									<template v-else>
+										<!-- `v-for` on a `<template>`, not on the `<slot>` itself: a
+										`key` bound on a slot outlet is passed through as a slot
+										PROP. The template renders no element of its own. -->
+										<template
+											v-for="item in selectedOptions"
+											:key="hash(item.value)"
+										>
+											<slot
+												:deselect="() => onChipUnselected(item)"
+												:disabled="!canDeselectChips"
+												:item="item.item"
+												name="chip"
+												:text="item.text"
+												:value="item.value"
+											>
+												<BbBadge
+													class="bb-select__badge"
+													:clearable="canDeselectChips"
+													size="lg"
+													variant="secondary"
+													v-bind="passthrough.part('badge', {}, item.item)"
+													@click:clear.stop="onChipUnselected(item)"
+												>
+													{{ item.text }}
+												</BbBadge>
+											</slot>
+										</template>
+									</template>
+								</span>
+								<span v-if="isCollapsed" class="bb-select__max-reached">
+									{{ collapsedSummaryText }}
+								</span>
+								<!-- Nothing picked: the placeholder, in chips and comma mode alike,
+								gone with the first pick (owner ruling Q53.4, 2026-09-24). -->
+								<span
+									v-if="!selectedOptions.length && placeholder"
+									class="bb-select__display-value bb-select__placeholder"
+								>
+									{{ placeholder }}
+								</span>
+							</template>
+							<span
+								v-else
+								class="bb-select__display-value"
+								:class="[{ 'bb-select__placeholder': !text }]"
+							>
+								{{ text || placeholder }}
+							</span>
+						</span>
+						<!-- The value half of the activator's accessible name. A node of its
+						own, OUTSIDE `__value`, for two reasons. (1) Correctness: every node an
+						aria-labelledby chain points at is flattened with name-from-content,
+						which descends into nested interactive content — pointing at `__value`
+						swept up each chip's ✕ button aria-label, so a three-pick select
+						announced "Country Italy Remove France Remove Spain Remove" on every
+						focus. (2) `__value` stays the *visible* face and nothing else: it is
+						read back as the resolved label (innerText) by the fixture e2e specs,
+						so a visually-hidden copy nested inside it would double every reading.
+						The chips keep their ✕ buttons — those are real tab stops and must stay
+						named; the activator's name just stops reading them. `hidden`, not
+						bb-sr-only (Q63.2): read through aria-labelledby (accname 2B), never
+						a second, page-text copy of the visible value in browse mode. -->
+						<span :id="`${fieldId}__selection`" hidden>{{
+							accessibleSelectionText(text)
+						}}</span>
+						<template #append:outer
+							><slot name="append:outer" v-bind="{ query, close }"
+						/></template>
+						<template #append
+							><slot name="append" v-bind="{ query, focus, close }"
+						/></template>
+						<template v-if="$slots.prefix" #prefix
+							><slot name="prefix"
+						/></template>
+						<template v-if="$slots.suffix" #suffix
+							><slot name="suffix"
+						/></template>
+						<template #prepend
+							><slot name="prepend" v-bind="{ query, focus, close }"
+						/></template>
+						<template #prepend:outer
+							><slot name="prepend:outer" v-bind="{ query, close }"
+						/></template>
+					</CommonFieldInput>
+
+					<!-- The value channel: `form` (the one native attribute a hidden input
+					reads) routes here from the consumer's attributes. -->
+					<input
+						v-for="input in hiddenInputs"
+						:key="input.value"
+						v-bind="mergeProps(input, passthrough.controlAttrs)"
+					/>
+				</template>
+
 				<template v-if="$slots.header" #header="data">
 					<slot name="header" v-bind="data" />
 				</template>
 				<template v-if="$slots.footer" #footer="data">
 					<slot name="footer" v-bind="data" />
 				</template>
-				<template #append-outer="data">
-					<slot name="append-outer" v-bind="data" />
-				</template>
-				<template #append="data">
-					<slot name="append" v-bind="data" />
-				</template>
-				<template v-if="$slots.prefix" #prefix>
-					<slot name="prefix" />
-				</template>
-				<template v-if="$slots.suffix" #suffix>
-					<slot name="suffix" />
-				</template>
-				<template #prepend="data">
-					<slot name="prepend" v-bind="data" />
-				</template>
-				<template #prepend-outer="data">
-					<slot name="prepend-outer" v-bind="data" />
-				</template>
 				<template #loading="data">
 					<slot name="loading" v-bind="data" />
 				</template>
-				<template #no-data="data">
-					<slot name="no-data" v-bind="data" />
+				<template #empty="data">
+					<slot name="empty" v-bind="data" />
 				</template>
-				<template #option="data">
-					<slot name="option" v-bind="data" />
+				<template v-if="$slots.option" #option="data">
+					<slot :has-errors="fieldHasErrors" name="option" v-bind="data" />
 				</template>
 				<template #group="data">
 					<slot name="group" v-bind="data" />
 				</template>
-			</BaseSelect>
+			</BbSelectPopover>
 		</template>
-	</BaseInputContainer>
+	</CommonField>
 </template>
 
 <script setup lang="ts" generic="T = any">
-import { computed, ref } from 'vue';
-import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
-import BaseSelect from '../BbBaseSelect/BbBaseSelect.vue';
+import {
+	computed,
+	getCurrentInstance,
+	mergeProps,
+	nextTick,
+	onMounted,
+	onUnmounted,
+	ref,
+	useAttrs,
+	watch,
+} from 'vue';
+import CommonField from '../CommonField/CommonField.vue';
+import CommonFieldInput from '../CommonFieldInput/CommonFieldInput.vue';
+import BbBadge from '../BbBadge/BbBadge.vue';
+import BbSelectPopover from '../BbSelectPopover/BbSelectPopover.vue';
+import {
+	BB_SELECT_POPOVER_PT,
+	type BbSelectResolvedOption,
+} from '../BbSelectPopover/types';
 import { useMobile } from '@/composables/useMobile';
-import { config } from 'virtual:bitboss-ui/config';
+import { useConfig } from '@/composables/useConfig';
+import { useFormBinding } from '@/composables/useFormBinding';
+import { useLocale } from '@/composables/useLocale';
+import {
+	formControlPtActive,
+	SELECT_CONTROL_NATIVE_ATTRS,
+	usePassthrough,
+} from '@/composables/usePassthrough';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
+import { hasVnodeListener } from '@/utilities/functions/hasVnodeListener';
 import { isNotEmpty } from '@/utilities/functions/isNotEmpty';
-import type { BbSelectProps, BbSelectEvents, BbSelectSlots } from './types';
-
-// `adaptive` is declared with a `undefined` default (not omitted) so it stays
-// three-state when forwarded to BaseSelect: it disables Vue's absent→`false`
-// Boolean cast (which would forward an explicit `false` and defeat the global
-// `config.adaptive`), while keeping the Boolean type so the valueless `adaptive`
-// shorthand still resolves to `true`.
-const props = withDefaults(defineProps<BbSelectProps<T>>(), {
+import { throttle } from '@/utilities/functions/throttle';
+import { when } from '@/utilities/functions/when';
+import { hash } from '@/utilities/functions/hash';
+import { reject } from '@/utilities/functions/reject';
+import chevronDownSvg from '@/assets/svgs/chevron_down.svg?raw';
+import { provideSheetChipAttrs } from '../BbSelectPopover/sheetChipAttrs';
+import {
+	BB_SELECT_PT,
+	type BbSelectProps,
+	type BbSelectEvents,
+	type BbSelectSlots,
+} from './types';
+
+defineOptions({ inheritAttrs: false });
+const declaredProps = withDefaults(defineProps<BbSelectProps<T>>(), {
+	// `undefined` (declared, not omitted) keeps `adaptive` three-state all the
+	// way to BbSelectPopover: it disables Vue's absent→`false` Boolean cast
+	// (which would pass an explicit `false` and defeat the global
+	// `config.adaptive`), while keeping the Boolean type so the valueless
+	// `adaptive` shorthand still resolves to `true`.
 	adaptive: undefined,
+	// Same three-state reason as `adaptive`: an absent `disable-writing` must
+	// reach the popover as `undefined` so it can mean `'auto'` there; the
+	// valueless shorthand still casts to `true`.
+	disableWriting: undefined,
 	// Same three-state reason as `adaptive`: `prefill` is typed
 	// `boolean | 'interaction'`, so leaving it out lets Vue's absent→`false`
-	// Boolean cast forward an explicit `false` and defeat BaseSelect's
-	// `'interaction'` default — which is how every BbSelect silently ran with
-	// `prefill: false`. Harmless while `false` behaved like `'interaction'`;
-	// load-bearing now that `false` means search-first.
+	// Boolean cast turn "not set" into an explicit `false` — which is how every
+	// BbSelect once silently ran with `prefill: false`. Harmless while `false`
+	// behaved like `'interaction'`; load-bearing now that `false` means
+	// search-first. Unset resolves to `'interaction'` in `computedPrefill`.
 	prefill: undefined,
 	selectable: true,
 });
 
-const emit = defineEmits<BbSelectEvents>();
+const declaredEmit = defineEmits<BbSelectEvents>();
 
 defineSlots<BbSelectSlots<T>>();
+// Inside a BbForm the field joins it (Q54.4): `props` / `emit` are bound.
+const {
+	props,
+	emit,
+	showAsterisk,
+	errors: fieldErrors,
+	ariaRequired: fieldAriaRequired,
+	required: fieldRequired,
+	model: fieldModel,
+	readonly: fieldReadonly,
+} = useFormBinding(declaredProps, declaredEmit, {
+	componentName: 'BbSelect',
+	identifierFallback: () => declaredProps.label,
+	leaveOn: 'inactive',
+});
+// Outside a form the binding leaves `required` to the native attribute, but
+// the combobox is an `input type="button"` overlay and `required` only lands
+// on the hidden form inputs: say it to AT on the combobox itself.
+const activatorAriaRequired = computed(
+	() => fieldAriaRequired.value ?? (fieldRequired.value ? true : undefined)
+);
+
+const config = useConfig();
+const { t } = useLocale();
 
 if (process.env.NODE_ENV !== 'production')
 	warnRemovedAttrs('BbSelect', removedPropsFor('BbSelect'));
@@ -159,16 +411,301 @@ if (process.env.NODE_ENV !== 'production')
 const active = ref(false);
 const { isMobile } = useMobile();
 const showHint = computed(() => props.persistentHint || active.value);
-const isClearable = computed(
-	() => Boolean(props.clearable) && isNotEmpty(props.modelValue)
-);
 const hasValue = computed(() => isNotEmpty(props.modelValue));
+const isClearable = computed(() => Boolean(props.clearable) && hasValue.value);
 const resolvedLabelMode = computed(
 	() => props.labelMode ?? config.defaultInputLabelMode
 );
 
 /**
- * These events are just propagated
+ * Whether the options surface is showing: on from the popover's `show` to its
+ * `hide`. The `active` event also fires on plain focus, so it cannot stand in.
+ */
+const open = ref(false);
+
+/**
+ * Passthrough (plans/passthrough/BbSelect.md). `panel` and `option` are the popover's: their raw entries are forwarded to it under the same words (`panel` → its `panel`, the painted bubble), so `option:selected` is resolved per option where the selection is known.
+ */
+const passthrough = usePassthrough({
+	component: 'BbSelect',
+	attrs: useAttrs(),
+	controlAttrs: SELECT_CONTROL_NATIVE_ATTRS,
+	props,
+	parts: BB_SELECT_PT.parts,
+	states: BB_SELECT_PT.states,
+	active: {
+		...formControlPtActive(props, () => hasValue.value),
+		open: () => open.value,
+	},
+});
+
+/**
+ * The popover's `pt`. The option rows go with every popover state: it
+ * resolves `disabled` per option (and every option is disabled when this
+ * control is). The surface (`panel`, `sheet`, `input`, `list`) goes WITHOUT `disabled`:
+ * the popover has no component-level `disabled`, so an entry handed over
+ * under its own word never resolved there — left out of the child's states,
+ * it is resolved here, from this control's `disabled` (a family state,
+ * component-wide on every part).
+ */
+// The phone sheet lists the selection as chips too; they take `pt:badge`
+// exactly as the field's chips do (Q56.13).
+provideSheetChipAttrs((item) => passthrough.part('badge', {}, item));
+
+const popoverPt = () => ({
+	...passthrough.forward(
+		['panel', 'sheet', 'header', 'footer', 'input', 'list'],
+		BB_SELECT_POPOVER_PT.states.filter((state) => state !== 'disabled')
+	),
+	...passthrough.forward(
+		['option', 'itemText', 'itemIcon', 'itemDescription'],
+		BB_SELECT_POPOVER_PT.states
+	),
+});
+
+/**
+ * The box row's parts inside the activator slot, where the popover's own fetch
+ * is known: `loading` there is the `loading` prop OR the items the popover is
+ * fetching, so `pt:box:loading` / `pt:spinner:loading` / … follow the spinner.
+ * The frame (`root`, `label`, `hint`, `message`) sits outside the slot and
+ * follows the `loading` prop only — the popover's internal fetch is not public
+ * state. `part()` caches one binding per state combination.
+ */
+const BOX_ROW_PARTS = [
+	'box',
+	'icon',
+	'spinner',
+	'clear',
+	'prefix',
+	'suffix',
+] as const;
+const boxRowPassthrough = (activatorLoading: boolean) =>
+	Object.fromEntries(
+		BOX_ROW_PARTS.map((part) => [
+			part,
+			passthrough.part(part, { loading: activatorLoading }),
+		])
+	);
+
+/**
+ * Sheet chrome: default the adaptive off-canvas title to the field label.
+ * Consumer `offCanvasProps` spread last so an explicit `title` (or any other
+ * sheet prop) still wins — same shape as BbSelectPopover's `offcanvasBindings`.
+ */
+const resolvedOffCanvasProps = computed(() => ({
+	title: props.label,
+	...props.offCanvasProps,
+}));
+
+/** The chevron unless the consumer sets their own append icon. */
+const appendIcon = computed(() =>
+	props['append:icon'] === undefined ? chevronDownSvg : props['append:icon']
+);
+
+/** No cap on the chip labels unless `maxSelectedLabels` is set. */
+const resolvedMaxSelectedLabels = computed(() =>
+	props.maxSelectedLabels === undefined ? Infinity : props.maxSelectedLabels
+);
+
+/**
+ * A select with a value always prefills (the popover resolves the labels of
+ * the selection); without one it follows `prefill`, `'interaction'` unless set.
+ */
+const computedPrefill = computed(() => {
+	if (hasValue.value) return true;
+	return props.prefill ?? 'interaction';
+});
+
+const wrapperRef = ref<InstanceType<typeof CommonFieldInput>>();
+const valueRef = ref<HTMLElement>();
+const chipsContainerRef = ref<HTMLElement>();
+
+const selectedCount = computed(() => {
+	if (!props.multiple) return 0;
+	if (!Array.isArray(props.modelValue)) return props.modelValue != null ? 1 : 0;
+	return props.modelValue.length;
+});
+
+const usesCountLimit = computed(
+	() => resolvedMaxSelectedLabels.value !== Infinity
+);
+const usesOverflowCollapse = computed(() => !usesCountLimit.value);
+const isOverflowing = ref(false);
+const chipsLeftInsetCompensation = ref(0);
+const hasMeasuredChipsInsetCompensation = ref(false);
+const isCollapsed = computed(() => {
+	if (selectedCount.value <= 1) return false;
+	if (usesCountLimit.value) {
+		return selectedCount.value > resolvedMaxSelectedLabels.value;
+	}
+	return isOverflowing.value;
+});
+
+const canDeselectChips = computed(() => !props.disabled && !props.readonly);
+
+const onChipUnselected = (option: BbSelectResolvedOption) => {
+	if (!canDeselectChips.value) return;
+	if (props.multiple) {
+		const valueToEmit = reject(props.modelValue, option.value);
+		emit('update:modelValue', valueToEmit);
+	} else {
+		emit('update:modelValue', null);
+	}
+};
+
+const refocusActivator = () => {
+	(wrapperRef.value?.$el as HTMLElement | undefined)
+		?.querySelector<HTMLButtonElement>('.bb-select__activator')
+		?.focus();
+};
+
+const collapsedSummaryText = computed(() => {
+	if (props.selectedLabelsFn) {
+		return props.selectedLabelsFn(selectedCount.value);
+	}
+	return t('select.multipleMaxReached', selectedCount.value).value;
+});
+
+/**
+ * The selection half of the activator's accessible name, mirroring what the
+ * control visually shows — `text` is already the ", "-joined display text of
+ * every selection (single or multiple), a collapsed row shows its summary
+ * instead, and a single select falls back to the placeholder exactly like
+ * `__display-value` does. Multiple with nothing picked shows the placeholder
+ * too (Q53.4), so it names the empty state the same way.
+ */
+const accessibleSelectionText = (text: string) => {
+	if (props.multiple && isCollapsed.value) return collapsedSummaryText.value;
+	return text || props.placeholder || '';
+};
+
+const resetChipsInsetCompensation = () => {
+	hasMeasuredChipsInsetCompensation.value = false;
+	chipsLeftInsetCompensation.value = 0;
+};
+
+const updateChipsInsetCompensation = () => {
+	if (hasMeasuredChipsInsetCompensation.value || !chipsContainerRef.value) {
+		return;
+	}
+	const chipsStyles = getComputedStyle(chipsContainerRef.value);
+	const chipsMarginLeft = Number.parseFloat(chipsStyles.marginLeft || '0');
+	chipsLeftInsetCompensation.value = Math.max(0, -chipsMarginLeft);
+	hasMeasuredChipsInsetCompensation.value = true;
+};
+
+const checkOverflow = () => {
+	if (
+		!usesOverflowCollapse.value ||
+		!chipsContainerRef.value ||
+		!valueRef.value ||
+		selectedCount.value <= 1
+	) {
+		isOverflowing.value = false;
+		return;
+	}
+	updateChipsInsetCompensation();
+	const availableWidth =
+		valueRef.value.clientWidth + chipsLeftInsetCompensation.value;
+	// clientWidth/scrollWidth are integer-rounded while availableWidth is
+	// fractional (the negative chips margin is sub-pixel), so compare with a 1px
+	// tolerance — otherwise rounding alone reports a phantom overflow and the row
+	// collapses to the summary even with plenty of room.
+	isOverflowing.value =
+		chipsContainerRef.value.scrollWidth > availableWidth + 1;
+};
+
+const scheduleOverflowCheck = throttle(checkOverflow, 100, {
+	leading: true,
+	trailing: true,
+});
+
+let resizeObserver: ResizeObserver | null = null;
+
+/**
+ * Overflow collapsing is only in play while `maxSelectedLabels` is `Infinity`
+ * (otherwise the count limit decides), so the observer follows that flag rather
+ * than being wired once at mount: a select that mounts with a finite limit and
+ * later has it raised to `Infinity` would otherwise never get an observer at
+ * all, leaving `isOverflowing` false forever and the chips row spilling out of
+ * the control until the component remounts.
+ */
+const syncOverflowObserver = () => {
+	resizeObserver?.disconnect();
+	resizeObserver = null;
+	if (!usesOverflowCollapse.value) return;
+
+	resizeObserver = new ResizeObserver(scheduleOverflowCheck);
+	if (valueRef.value) resizeObserver.observe(valueRef.value);
+	nextTick(() => {
+		scheduleOverflowCheck();
+	});
+};
+
+onMounted(syncOverflowObserver);
+watch(usesOverflowCollapse, syncOverflowObserver, { flush: 'post' });
+
+onUnmounted(() => {
+	resizeObserver?.disconnect();
+	scheduleOverflowCheck.cancel();
+});
+
+watch(
+	() => [props.modelValue, resolvedMaxSelectedLabels.value] as const,
+	() => {
+		if (!usesOverflowCollapse.value) return;
+		nextTick(() => {
+			scheduleOverflowCheck();
+		});
+	}
+);
+
+watch(
+	() => [props.compact, props.comma, props['prepend:icon']] as const,
+	() => {
+		if (!usesOverflowCollapse.value) return;
+		resetChipsInsetCompensation();
+		nextTick(() => {
+			scheduleOverflowCheck();
+		});
+	}
+);
+
+const makeInputValue = when(
+	(item: unknown) => typeof item !== 'string',
+	JSON.stringify
+);
+
+// Empty selection (null/undefined/[]) posts NO field — mirroring a native
+// <select multiple> with nothing chosen — instead of the literal "null".
+// Note `required` on input[type=hidden] is barred from constraint validation
+// by the HTML spec; it is kept for form-introspection only.
+const hiddenInputs = computed(() =>
+	(props.multiple
+		? ([] as any[]).concat(props.modelValue ?? [])
+		: [props.modelValue]
+	)
+		.filter((current) => current !== null && current !== undefined)
+		.map((current) => ({
+			disabled: props.disabled,
+			name: props.name,
+			required: props.required,
+			type: 'hidden',
+			value: makeInputValue(current),
+		}))
+);
+
+/**
+ * The popover's events, re-emitted; focus / active drive the hint and
+ * show / hide drive `open`.
+ *
+ * `option:add` is the exception: forwarded ONLY when the consumer bound it on
+ * this select. The popover decides `disable-writing="auto"` off its own vnode
+ * props — a creatable select keeps its search field — so an unconditional
+ * forward would make every BbSelect look creatable to it. Read at render
+ * (`popoverListeners()`), so a conditionally bound listener is seen as it is
+ * now; the two objects are prebuilt so the popover's props keep their identity
+ * across renders.
  */
 const eventListeners = {
 	onBlur: (event: FocusEvent) => {
@@ -177,7 +714,6 @@ const eventListeners = {
 	},
 	onChange: (event: Event) => emit('change', event),
 	onClick: (event: MouseEvent) => emit('click', event),
-	'onOption:add': (text: string) => emit('option:add', text),
 	onFocus: (event: FocusEvent) => {
 		active.value = true;
 		emit('focus', event);
@@ -186,6 +722,16 @@ const eventListeners = {
 		active.value = true;
 		emit('active');
 	},
+	onShow: () => {
+		open.value = true;
+		emit('show');
+	},
+	onShown: () => emit('shown'),
+	onHide: () => {
+		open.value = false;
+		emit('hide');
+	},
+	onHidden: () => emit('hidden'),
 	onInactive: () => {
 		active.value = false;
 		emit('inactive');
@@ -193,6 +739,15 @@ const eventListeners = {
 	onInput: (event: Event) => emit('input', event),
 	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
 };
+const eventListenersWithAdd = {
+	...eventListeners,
+	'onOption:add': (text: string) => emit('option:add', text),
+};
+const instance = getCurrentInstance();
+const popoverListeners = () =>
+	hasVnodeListener(instance, 'option:add')
+		? eventListenersWithAdd
+		: eventListeners;
 </script>
 
 <style lang="postcss">
@@ -203,15 +758,201 @@ const eventListeners = {
 ## Types
 
 ```ts
+import type { BbSelectItemProps } from '@/types/ItemProps';
+import type { InputVariantType } from '@/types/InputVariant';
+import type {
+	PtNoInfer,
+	FormControlPtState,
+	PtItemCtx,
+	PtItemMap,
+	PtItemResult,
+	PtValue,
+} from '@/types/passthrough';
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { InputDirection } from '@/types/InputDirection';
+import type { FieldCrossAlign, FieldLayout } from '@/types/FieldLayout';
 import type { ItemAccessor } from '@/types/ItemAccessor';
+import type { BbSelectItemsContext } from '@/types/ItemsProvider';
 import type { IconType } from '@/types/Icon';
-import type { BaseSelectEvents } from '../BbBaseSelect/types';
 import type { BbSelectResolvedOption } from '../BbSelectPopover/types';
 import type { BbOffCanvasProps } from '../BbOffCanvas/types';
+import type { FormFieldProps } from '@/composables/useFormBinding';
+
+/**
+ * Passthrough parts of `BbSelect` (plans/passthrough/BbSelect.md): the text-
+ * control family parts, plus the options surface's, forwarded to its
+ * `BbSelectPopover`.
+ *
+ * Per-item functions: on the instance, an option part (`option`, `itemText`, `itemIcon`, `itemDescription`) and a selection part (`badge`, `comma` — called here, per selected value, with its raw item) also accept `({ item, selected, … }) => PtValue | false | null | undefined` — `item` is the raw item of that option, and every state a boolean beside it, on for it (`selected`, `disabled`, …) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). The function travels to the popover with the part and is called there, per option; its result is merged last, after every state entry, through the same deduper; a falsy result leaves the option as it was. See the passthrough guide, _Per-item functions_.
+ *
+ * @describedBy BbSelectPopoverPtPart
+ * @describedBy TextControlPtPart
+ * @part root - The field's outer container: the label, the box and the lines
+ *   under it; a `class` on the component lands here. (The options surface is
+ *   `panel`.)
+ * @part clear - The ✕ in the field that empties the selection (`clearable`) —
+ *   one node, never a chip's own ✕.
+ * @part activator - The button you act on to open the options — the field's
+ *   control (not a text field: `data-test` fits here, `autocomplete` does
+ *   not). The chevron is chrome. It is `activator`, not the family's `input`:
+ *   the field itself is a button (the date / time inputs' trigger is the same
+ *   word).
+ * @part input - The search field inside the options surface, when it shows
+ *   one (see `disable-writing`) — handed to the `BbSelectPopover` as its own
+ *   `pt:input`. Its ✕ is chrome.
+ * @part panel - The options surface — the popover's painted bubble on
+ *   desktop, the sheet itself on a phone.
+ * @part sheet - The bottom sheet the options open in on a phone only.
+ * @part header - The band around your `#header` slot: at the top of the
+ *   flyout on desktop, the sheet's header on a phone.
+ * @part footer - The band around your `#footer` slot: at the bottom of the
+ *   flyout on desktop, the sheet's footer on a phone.
+ * @part badge - Each selected value's `BbBadge` root with `multiple` — a
+ *   broadcast resolved per value, on the field's chips and on the phone
+ *   sheet's. The badge's own ✕ is chrome, never `clear`. In the field, not
+ *   rendered when the `#chip` slot replaces it, nor in `comma` mode; the
+ *   sheet's chips are always badges.
+ * @part comma - Each selected value with `multiple` and `comma` — a broadcast
+ *   resolved per value.
+ */
+export type BbSelectPtPart =
+	| 'root'
+	| 'label'
+	| 'description'
+	| 'message'
+	| 'hint'
+	| 'box'
+	| 'activator'
+	| 'input'
+	| 'icon'
+	| 'spinner'
+	| 'prefix'
+	| 'suffix'
+	| 'clear'
+	| 'panel'
+	| 'sheet'
+	| 'header'
+	| 'footer'
+	| 'list'
+	| 'option'
+	| 'itemText'
+	| 'itemIcon'
+	| 'itemDescription'
+	| 'badge'
+	| 'comma';
+/** The field and surface parts — they take a `PtValue` only. */
+export type BbSelectFieldPtPart =
+	| 'root'
+	| 'label'
+	| 'description'
+	| 'message'
+	| 'hint'
+	| 'box'
+	| 'activator'
+	| 'input'
+	| 'icon'
+	| 'spinner'
+	| 'prefix'
+	| 'suffix'
+	| 'clear'
+	| 'panel'
+	| 'sheet'
+	| 'header'
+	| 'footer'
+	| 'list';
+/**
+ * The option parts and the selection parts — broadcasts resolved per option
+ * or per selected value; their base key also takes a per-item function.
+ */
+export type BbSelectOptionPtPart =
+	| 'option'
+	| 'itemText'
+	| 'itemIcon'
+	| 'itemDescription'
+	| 'badge'
+	| 'comma';
+/**
+ * Passthrough states of `BbSelect`, true while the matching `--` modifier is on.
+ *
+ * @state selected - Per node, on `option` and its `item-*` parts: a chosen
+ *   option.
+ * @state disabled - Component-wide while the select is `disabled`; also per
+ *   node, on `option` and its `item-*` parts: an option that is disabled.
+ * @state open - Component-wide: the options surface is showing.
+ */
+export type BbSelectPtState = FormControlPtState | 'open' | 'selected';
+/** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
+export const BB_SELECT_PT = {
+	parts: [
+		// The family's words with `activator` where the text controls say
+		// `input` — BbSelect's control is a button that opens the options;
+		// its `input` is the popover's search field.
+		'root',
+		'label',
+		'description',
+		'message',
+		'hint',
+		'box',
+		'activator',
+		'input',
+		'icon',
+		'spinner',
+		'prefix',
+		'suffix',
+		'clear',
+		'panel',
+		'sheet',
+		'header',
+		'footer',
+		'list',
+		'option',
+		'itemText',
+		'itemIcon',
+		'itemDescription',
+		'badge',
+		'comma',
+	],
+	states: [
+		'hasValue',
+		'selected',
+		'readonly',
+		'disabled',
+		'warnings',
+		'errors',
+		'open',
+		'loading',
+	],
+} as const satisfies {
+	parts: readonly BbSelectPtPart[];
+	states: readonly BbSelectPtState[];
+};
 
+// Spelled INLINE with this component's own unions (Vue's SFC type resolver
+// does not substitute a generic alias's type parameters — PASSTHROUGH.md T20).
+// Two mapped types, never `Partial<Record<…>>`: the lint autofix rewrites one
+// into the other and the SFC resolver reads only the mapped spelling (T23).
+/* eslint-disable @typescript-eslint/consistent-indexed-object-style */
 export type BbSelectProps<T> = {
+	[K in
+		| `pt:${BbSelectFieldPtPart}`
+		| `pt:${BbSelectPtPart}:${BbSelectPtState}`]?: PtValue;
+} & {
+	// The option parts also take a per-item function, typed on this select's
+	// item — a literal function type, not `PtItemFn` (T23).
+	[K in `pt:${BbSelectOptionPtPart}`]?:
+		| PtValue
+		| ((ctx: PtItemCtx<PtNoInfer<T>, BbSelectPtState>) => PtItemResult);
+} & {
+	/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
+	/**
+	 * Passthrough, object form: the same keys as the `pt:*` attributes
+	 * without the prefix. See the `pt:<part>` row.
+	 */
+	pt?: PtItemMap<
+		BbSelectPtPart,
+		BbSelectOptionPtPart,
+		BbSelectPtState,
+		PtNoInfer<T>
+	>;
 	/**
 	 * When `true`, the options panel opens as a bottom off-canvas sheet on mobile
 	 * viewports instead of a floating popover; on desktop it stays a popover.
@@ -229,21 +970,27 @@ export type BbSelectProps<T> = {
 	description?: string;
 
 	/**
-	 * Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile.
+	 * Props for the phone sheet (the `BbOffCanvas` that `adaptive` renders on
+	 * mobile), spread over its defaults. A `pt` inside it styles only the sheet
+	 * (passthrough guide § Inside the sheet).
 	 */
 	offCanvasProps?: Partial<BbOffCanvasProps>;
 
 	/**
-	 * Controls whether the search input is shown inside the dropdown panel.
-	 * Use `'mobile'` / `'desktop'` to hide it on that platform only.
-	 * @defaultValue `false`
+	 * Hides the panel's search field: `true` everywhere, `'mobile'` /
+	 * `'desktop'` on that platform only. `'auto'` hides it for an array `items`
+	 * shorter than the plugin's `autoDisableWritingThreshold` (6), decided per
+	 * open; never for a provider, nor with an `option:add` listener.
+	 *
+	 * @defaultValue `'auto'`
 	 */
-	disableWriting?: boolean | 'mobile' | 'desktop';
+	disableWriting?: boolean | 'mobile' | 'desktop' | 'auto';
 
 	/**
 	 * Name of the icon to be added at the end of the input.
+	 *
+	 * @defaultValue the chevron-down glyph
 	 */
-
 	'append:icon'?: IconType;
 
 	/**
@@ -268,10 +1015,24 @@ export type BbSelectProps<T> = {
 	comma?: boolean;
 
 	/**
-	 * Sets the component in a compact mode.
+	 * Compact density. Swaps `--bb-input-h`, `--bb-input-py` and
+	 * `--bb-label-spacing-y` for their `-compact` twins on the field, so a
+	 * `--bb-input-h` you set on the component is ignored while `compact` is on:
+	 * size a compact field with `--bb-input-h-compact` (and
+	 * `--bb-input-py-compact`) instead.
 	 */
 	compact?: boolean;
 
+	/**
+	 * Visual variant of the field box, with the `BbButton` names and tokens.
+	 * Colours only, so a form never reflows; `'ghost'` has no border in any
+	 * state, and `'none'` takes no look at all (you own hover, focus and the
+	 * states). Register more with the plugin's `inputVariants`.
+	 *
+	 * @defaultValue `'outline'`
+	 */
+	variant?: InputVariantType;
+
 	/**
 	 * Defines an array of dependencies that will trigger actions in the component upon change.
 	 */
@@ -279,14 +1040,32 @@ export type BbSelectProps<T> = {
 
 	/**
 	 * Timeout used to debounce response to changes to dependencies.
+	 *
+	 * @defaultValue `0`
 	 */
 	depsDebounceTime?: number;
 
 	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a
-	 * pattern separated by a space like `xx xxxxx`.
+	 * How the label and the input sit together: `'vertical'`, `'horizontal'` (50/50),
+	 * `'auto'`, `'label-fill'` (the label takes the free space, the input keeps
+	 * its size), `'input-fill'` (the other way round), or a two-word ratio
+	 * pattern like `'xx xxxxx'`.
+	 */
+	layout?: FieldLayout;
+
+	/**
+	 * Vertical position of the label block in a side-by-side row; not
+	 * `labelPosition`, the horizontal one. Omitted, the label's first line
+	 * meets the control's.
+	 */
+	labelAlign?: FieldCrossAlign;
+
+	/**
+	 * Vertical position of the control in a side-by-side row; not
+	 * `inputPosition`, the horizontal one. Omitted, the control's first line
+	 * meets the label's.
 	 */
-	direction?: InputDirection;
+	inputAlign?: FieldCrossAlign;
 
 	/**
 	 * Disables the component.
@@ -294,25 +1073,23 @@ export type BbSelectProps<T> = {
 	disabled?: boolean;
 
 	/**
-	 * If coherence is enforced the input cannot have a modelValue that is incoherent
-	 * with its current items. modelValue will be reset upon incoherence.
+	 * After every successful load that is not a search, removes the picks the
+	 * fetched rows do not contain (a single model resets to `null`). A `stash`
+	 * does not count; a search or a failed load never prunes.
 	 */
 	enforceCoherence?: boolean;
 
 	/**
-	 * Can be a string or an array of string containing the messages to display.
-	 * They render in an `aria-live="polite"` region (announced when they appear)
-	 * and, while the list is non-empty, are referenced FIRST from the control's
-	 * `aria-describedby`, so the reason the field is invalid is re-read whenever
-	 * the control regains focus.
+	 * Error messages under the field, a string or string array. They render in
+	 * an `aria-live="polite"` region and are referenced first from the
+	 * control's `aria-describedby`, so they are re-read when it regains focus.
 	 */
 	errors?: string | string[];
 
 	/**
-	 * Property paths used to filter options when the user types in the search input.
-	 * When empty (default) options are matched against their display text.
-	 * When non-empty the provided paths are searched instead of the display text.
-	 * To disable filtering entirely set `disableWriting` so the user cannot type a query.
+	 * Item paths searched instead of the display text when the user types
+	 * (empty: the display text). To turn filtering off, hide the field with
+	 * `disableWriting`.
 	 *
 	 * @defaultValue `[]`
 	 */
@@ -330,11 +1107,10 @@ export type BbSelectProps<T> = {
 	hasErrors?: boolean;
 
 	/**
-	 * Warning messages to display beneath the field, in their own `aria-live`
-	 * region and amber (`--bb-text-warn`). A string or array; a non-empty list
-	 * implies the warning state. Errors suppress warnings when both are set.
-	 * While displayed they are also referenced from the control's
-	 * `aria-describedby`, after any errors and before the description/hint.
+	 * Warning messages under the field, a string or string array: amber, in
+	 * their own `aria-live` region, and in the control's `aria-describedby`
+	 * after the errors. A non-empty list implies the warning state; errors win
+	 * when both are set.
 	 */
 	warnings?: string | string[];
 
@@ -342,7 +1118,7 @@ export type BbSelectProps<T> = {
 	 * Define if the component should be in a warning state.
 	 * Same chrome as errors with `--bb-warn`; errors take priority.
 	 */
-	hasWarning?: boolean;
+	hasWarnings?: boolean;
 
 	/**
 	 * Visually hides the label of the input while maintaining accessibility.
@@ -355,17 +1131,18 @@ export type BbSelectProps<T> = {
 	hint?: string;
 
 	/**
-	 * The identifier of the component.
+	 * The `id` of the native control; the label's `for` and the description
+	 * and message ids derive from it. Generated when omitted.
 	 */
 	id?: HTMLAttributes['id'];
 
 	/**
-	 * Used to retrieve items; can be an array or a function.
+	 * The options: an array, or a provider called with a
+	 * ``BbSelectItemsContext`` (`query`, `reason`, `modelValue`, `signal`),
+	 * sync or async. Branch on `reason !== 'search'` to resolve the selection
+	 * by id. A provider fails by THROWING, never by returning `[]`.
 	 */
-	items:
-		| T[]
-		| ((query: string, prefill: boolean, modelValue: any) => Promise<T[]>)
-		| ((query: string, prefill: boolean, modelValue: any) => T[]);
+	items: T[] | ((context: BbSelectItemsContext) => T[] | Promise<T[]>);
 
 	/**
 	 * Height of group headers in the listbox (px). Defaults to 32px (24px
@@ -386,12 +1163,28 @@ export type BbSelectProps<T> = {
 	/**
 	 * Defines a path that returns a property of the object to use as text or a function
 	 * that returns a string.
+	 *
+	 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
+	 *
+	 * @defaultValue own `label`, else `text`, else `JSON.stringify(item)`
 	 */
 	itemText?: ItemAccessor<T, string>;
 
+	/**
+	 * ADDITIONAL row fields, never the text or value: `description` (a muted
+	 * line under the label), `prepend:icon`, `append:icon`. An object of paths
+	 * or getters per field, or a function of the item. Nothing is read
+	 * implicitly, and none shows in the trigger or the chips.
+	 */
+	itemProps?: BbSelectItemProps<T>;
+
 	/**
 	 * Defines a path that returns a property of the object to use as value or a function
 	 * that returns any value.
+	 *
+	 * Unset: own `value`, even `null`.
+	 *
+	 * @defaultValue own `value`, else the whole item
 	 */
 	itemValue?: ItemAccessor<T>;
 
@@ -427,16 +1220,21 @@ export type BbSelectProps<T> = {
 
 	/**
 	 * Maximum number of labels shown before collapsing to a count summary.
+	 * Unset, the labels collapse only when they overflow the field.
+	 *
+	 * @defaultValue `Infinity`
 	 */
 	maxSelectedLabels?: number;
 
 	/**
 	 * Used by v-model. Can be any serializable type.
 	 */
-	modelValue: any;
+	modelValue?: any;
 
 	/**
 	 * Timeout used to debounce response to changes to modelValue.
+	 *
+	 * @defaultValue `0`
 	 */
 	modelValueDebounceTime?: number;
 
@@ -453,7 +1251,15 @@ export type BbSelectProps<T> = {
 	/**
 	 * String displayed when there are no items to display.
 	 */
-	noDataText?: string;
+	emptyText?: string;
+
+	/**
+	 * String displayed in the empty state while the latest load FAILED (the
+	 * provider threw): the twin of `emptyText` for that case.
+	 *
+	 * @defaultValue the localized `common.failedText` ("Couldn't load items")
+	 */
+	failedText?: string;
 
 	/**
 	 * Keeps the hint displayed.
@@ -461,21 +1267,16 @@ export type BbSelectProps<T> = {
 	persistentHint?: boolean;
 
 	/**
-	 * String displayed when there's no data.
+	 * Text shown in the field while nothing is picked (an empty list has
+	 * `emptyText`).
 	 */
 	placeholder?: InputHTMLAttributes['placeholder'];
 
 	/**
-	 * Controls when items are pre-loaded.
-	 * `'interaction'` loads on the first user interaction, `true` loads
-	 * immediately on mount, `false` is *search-first*: with a provider, nothing
-	 * is fetched until the user types — opening alone does not load, and the
-	 * panel shows a "search to begin" hint meanwhile.
-	 *
-	 * `false` falls back to loading on open when the user could not otherwise
-	 * reach the options: array `items` (resolved on mount regardless), or
-	 * `disable-writing` (no search field to type into). When the input has a
-	 * value, it always loads immediately so the selection's text can render.
+	 * When the options first load: `'interaction'` on first open, `true` on
+	 * mount, `false` only once the user types (on open with
+	 * `disable-writing`). An array `items` or a seeded model always loads at
+	 * once.
 	 *
 	 * @defaultValue `'interaction'`
 	 */
@@ -494,6 +1295,8 @@ export type BbSelectProps<T> = {
 
 	/**
 	 * Time to wait when the user stops writing in the input before querying data.
+	 *
+	 * @defaultValue `500`
 	 */
 	queryDebounceTime?: number;
 
@@ -524,18 +1327,63 @@ export type BbSelectProps<T> = {
 	selectedLabelsFn?: (count: number) => string;
 
 	/**
-	 * Adds a stash to accumulate selected values across searches.
+	 * Keeps picked options named across searches: a pick stays resolvable (its
+	 * chip keeps its text) when a later search or a failed load no longer
+	 * returns it. It follows the model, and does not keep a pick valid:
+	 * `enforce-coherence` still prunes it.
 	 */
 	stash?: boolean;
 
 	/**
 	 * How long the transition has to last in milliseconds.
+	 *
+	 * @defaultValue `250`
 	 */
 	transitionDuration?: number;
-};
+} & FormFieldProps<any>;
 
 /** Re-export for consumers importing events type from BbSelect. */
-export type BbSelectEvents = BaseSelectEvents;
+export type BbSelectEvents = {
+	/** Emitted as soon as the options surface starts to open (the popover, or the sheet on a phone). */
+	(e: 'show'): void;
+	/** Emitted once the options surface is open and its open transition has finished. */
+	(e: 'shown'): void;
+	/** Emitted as soon as the options surface starts to close. */
+	(e: 'hide'): void;
+	/** Emitted once the options surface has finished closing. */
+	(e: 'hidden'): void;
+	/** Emitted when the activator loses focus. Forwards the original DOM `FocusEvent`. */
+	(e: 'blur', event: FocusEvent): void;
+	/** Emitted on the native `change` event. Forwards the original DOM `Event`. */
+	(e: 'change', event: Event): void;
+	/** Emitted when the select becomes active (focus enters it). */
+	(e: 'active'): void;
+	/** Emitted when the activator is clicked. Forwards the original DOM `MouseEvent`. */
+	(e: 'click', event: MouseEvent): void;
+	/** Emitted when the activator receives focus. Forwards the original DOM `FocusEvent`. */
+	(e: 'focus', event: FocusEvent): void;
+	/** Emitted when focus moves outside the whole select after it was active. */
+	(e: 'inactive'): void;
+	/** Emitted on native `input` events from the search field. Forwards the DOM `Event`. */
+	(e: 'input', event: Event): void;
+	(e: 'update:modelValue', value: any): void;
+	/**
+	 * Emitted with the typed text when the user confirms a value that is not in
+	 * the list (Enter in the search field). Binding it keeps the search field
+	 * writable, which makes the select creatable.
+	 */
+	(e: 'option:add', text: string): void;
+};
+
+/** Props exposed by the `description` slot. */
+export type BbSelectDescriptionSlotProps = {
+	/** The `description` prop value (empty when only the slot is provided). */
+	text: string;
+	/** Whether the field is in an error state. */
+	hasErrors: boolean;
+	/** Whether the field is in a warning state (suppressed when errors win). */
+	hasWarnings: boolean;
+};
 
 /** Props exposed by the `label` slot. */
 export type BbSelectLabelSlotProps = {
@@ -544,7 +1392,7 @@ export type BbSelectLabelSlotProps = {
 	/** Whether the input is in an error state. */
 	hasErrors: boolean;
 	/** Whether the input is in a warning state (suppressed when errors win). */
-	hasWarning: boolean;
+	hasWarnings: boolean;
 };
 
 /** Props exposed by the `option` slot. */
@@ -567,6 +1415,8 @@ export type BbSelectOptionSlotProps<T> = {
 	text: string;
 	/** The resolved value for this option. */
 	value: any;
+	/** The resolved `itemProps.description` for this option, when it has one. */
+	description: string | undefined;
 };
 
 /** Props exposed by the `group` slot. */
@@ -583,6 +1433,26 @@ export type BbSelectGroupSlotProps<T> = {
 	disabled: boolean;
 };
 
+/**
+ * Props exposed by the `chip` slot — called once per selected value in
+ * `multiple` mode, in place of the default badge.
+ */
+export type BbSelectChipSlotProps<T> = {
+	/** The selected item, exactly as it was supplied in `items`. */
+	item: T;
+	/** The item's resolved display text (what the default badge prints). */
+	text: string;
+	/** The item's resolved value — what sits in the v-model. */
+	value: any;
+	/**
+	 * `true` while the select is disabled or readonly: the chip must not offer a
+	 * way to remove itself, and `deselect` is a no-op.
+	 */
+	disabled: boolean;
+	/** Drops this value from the selection. No-op while `disabled`. */
+	deselect: () => void;
+};
+
 /**
  * Props exposed by the `header` / `footer` panel slots — identical whether the
  * select renders as a desktop popover or an adaptive bottom sheet.
@@ -622,7 +1492,7 @@ export type BbSelectSlots<T> = {
 	/**
 	 * Content appended outside the input field wrapper.
 	 */
-	'append-outer'?: (props: {
+	'append:outer'?: (props: {
 		query: string;
 		close: () => Promise<void>;
 	}) => any;
@@ -630,14 +1500,21 @@ export type BbSelectSlots<T> = {
 	 * Replaces the default label text rendered above the input.
 	 */
 	label?: (props: BbSelectLabelSlotProps) => any;
+	/**
+	 * Replaces the description text. Provided alone (no `description` prop) it still
+	 * renders the description region and wires it into `aria-describedby`.
+	 */
+	description?: (props: BbSelectDescriptionSlotProps) => 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.
+	 * `error` is what the latest failed load threw, untouched (`null` when
+	 * none).
 	 */
-	'no-data'?: (props: { query: string; focus: () => void }) => any;
+	empty?: (props: { query: string; focus: () => void; error: unknown }) => any;
 	/**
 	 * Replaces the default rendering of each option row in the dropdown.
 	 */
@@ -646,6 +1523,11 @@ export type BbSelectSlots<T> = {
 	 * Replaces the default group header rendered above grouped options.
 	 */
 	group?: (props: BbSelectGroupSlotProps<T>) => any;
+	/**
+	 * Replaces the default badge rendered for each selection in `multiple` mode.
+	 * Not called in `comma` mode, nor for the collapsed "+N" summary.
+	 */
+	chip?: (props: BbSelectChipSlotProps<T>) => any;
 	/**
 	 * Content rendered as an inline prefix inside the input field.
 	 */
@@ -661,7 +1543,7 @@ export type BbSelectSlots<T> = {
 	/**
 	 * Content prepended outside the input field wrapper.
 	 */
-	'prepend-outer'?: (props: {
+	'prepend:outer'?: (props: {
 		query: string;
 		close: () => Promise<void>;
 	}) => any;
@@ -676,13 +1558,147 @@ export type BbSelectSlots<T> = {
 
 ```css
 .bb-select {
-	/* Fill the grid control column (which sizes children to content). */
-	.bb-base-select {
-		width: 100%;
+	/* The box row of the select: the activator overlay, the value face and the
+	   chips row live inside it. */
+	&__field {
+		color: var(--bb-text);
+		font-size: var(--bb-input-fs);
+		user-select: none;
+		/* Fraction of the shell's inner padding the chips row is pulled back by
+		   when no prepend icon precedes it (see the negative margin below). */
+		--compensation-multiplier: 0.3;
+
+		&.bb-field-input--compact {
+			--compensation-multiplier: 0.5;
+		}
+
+		&--disabled {
+			color: var(--bb-text-muted);
+
+			.bb-select__activator {
+				cursor: not-allowed;
+			}
+		}
+
+		&--readonly {
+			.bb-select__activator {
+				cursor: default;
+			}
+		}
+
+		/* If there is no prepend icon, add a negative margin to the chips row so
+		   it smoothly couples with the border */
+		&:not(:has(.bb-field-input__prepend-icon)) {
+			.bb-select__chips-row--chips {
+				margin-inline-start: calc(
+					var(--bb-input-px) * var(--compensation-multiplier) * -1
+				);
+			}
+		}
+	}
+
+	&__activator {
+		background: none;
+		border: none;
+		cursor: pointer;
+		inset: 0;
+		padding: 0;
+		position: absolute;
+
+		&:focus-visible {
+			outline: 2px solid transparent;
+		}
+	}
+
+	&__value {
+		align-items: center;
+		align-self: stretch;
+		display: flex;
+		flex: 1 1 auto;
+		flex-wrap: nowrap;
+		gap: 0.25rem;
+		min-width: 0;
+		pointer-events: none;
+		position: relative;
+		text-align: start;
+
+		& input[type='button'] {
+			pointer-events: auto;
+		}
+	}
+
+	&__chips-row {
+		align-items: center;
+		bottom: 0;
+		display: flex;
+		flex: 1 1 auto;
+		flex-wrap: nowrap;
+		inset-inline-end: 0;
+		inset-inline-start: 0;
+		min-width: 0;
+		overflow: hidden;
+		/* Sits above the absolute activator overlay (later in DOM), so re-enable
+		hit-testing: chip ✕ buttons become clickable, and clicks on the empty gaps
+		bubble to CommonFieldInput's container:click to still toggle the popover.
+		The activator stays behind purely as the keyboard/focus target. */
+		pointer-events: auto;
+		position: absolute;
+		top: 0;
+
+		&--hidden {
+			pointer-events: none;
+			visibility: hidden;
+		}
+
+		/* Chips mode with at least one selection — never comma mode, which
+		   separates with its own `,` and wants no gap. The `chip` slot lets a
+		   consumer render their own element in place of our badge, so the layout
+		   a chip needs (no shrinking, the gap between chips, and the negative
+		   inset coupling above) lives HERE, on the row, rather than on a
+		   `__chip` class custom content would have to know to apply. */
+		&--chips {
+			gap: 0.25rem;
+
+			> * {
+				flex-shrink: 0;
+			}
+		}
+	}
+
+	&__comma {
+		flex-shrink: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+
+		&:not(:last-child)::after {
+			content: ',\00a0';
+		}
+	}
+
+	&__display-value {
+		flex: 1 1 auto;
+		min-width: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	&__placeholder {
+		color: var(--bb-text-muted);
+		opacity: 1;
+		transition: opacity var(--bb-transition-fast) var(--bb-ease);
+	}
+
+	&__max-reached {
+		flex: 1 1 auto;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
 	}
 
-	&.bb-base-input-container--floating-label:not(:focus-within) {
-		.bb-base-select__placeholder {
+	&.bb-field--floating-label:not(:focus-within) {
+		.bb-select__placeholder {
 			opacity: 0;
 		}
 	}