bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbSelect.md

@@ -1,567 +1,1430 @@
 # BbSelect
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Selects one or many options from structured data.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbSelect.md](./source/BbSelect.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbSelect` when the user picks from a list that is **large, dynamic,
+or searchable**, and you want a labelled form control with hint, error and
+loading states baked in. It is the default choice for country/city pickers,
+assignee fields, tag inputs and any async-backed lookup.
+
+Prefer a sibling when the shape is simpler:
+
+- Small, static, exclusive choice (≤6 options, always visible) → `BbRadioGroup`.
+- Small, static, multi-choice → `BbCheckboxGroup` / `BbSwitchGroup`.
+- You need a **custom trigger** (a status pill, an avatar stack, a badge) rather
+  than an inline input → `BbSelectPopover`, the popover-anchored sibling that
+  shares this component's search and option engine.
+- Values the user _invents_ (open vocabulary) → `BbTag`; if values come from a
+  known set, `BbSelect` in multiple mode is the right tool.
+
+`label` is required — it is the accessible name. Hide it visually with
+`hide-label` when the surrounding UI already labels the field.
+
+### Map options with `item-text` and `item-value`
+
+Pass your domain objects to `items` **as they are** and tell the component which
+field is the display text and which is the stored value with `item-text` /
+`item-value` (dot-paths or extractor functions). Never pre-map `items` into
+`{ label, value }` objects — matching is hash-based, so component-native
+extraction stays robust. The `v-model` holds the resolved _value_, not the whole
+object.
+
+**Single select mapped from domain objects**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-select"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLabel"
-		:hint="hint"
-		:label="label"
-		:label-position="labelPosition"
-		:model-value="modelValue"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseSelect
-				:id="id"
-				:allow-writing="allowWriting"
-				:append:icon="props['append:icon']"
-				:aria-describedby="ariaDescribedby"
-				:autocomplete="autocomplete"
-				:autofocus="autofocus"
-				:clearable="clearable"
-				:comma="comma"
-				:compact="compact"
-				:dependencies="dependencies"
-				:deps-debounce-time="depsDebounceTime"
-				:disabled="disabled"
-				:enforce-coherence="enforceCoherence"
-				:filter-by="filterBy"
-				:group-by="groupBy"
-				:has-errors="hasErrors"
-				:header-height="headerHeight"
-				:item-height="itemHeight"
-				:item-text="<any>itemText"
-				:item-value="<any>itemValue"
-				:items="items"
-				:loading="loading"
-				:loading-text="loadingText"
-				:max="max"
-				:max-selected-labels="maxSelectedLabels"
-				:model-value="modelValue"
-				:model-value-debounce-time="modelValueDebounceTime"
-				:multiple="multiple"
-				:name="name"
-				:no-data-text="noDataText"
-				:placeholder="placeholder"
-				:prefill="prefill"
-				:prepend:icon="props['prepend:icon']"
-				:query-debounce-time="queryDebounceTime"
-				:readonly="readonly"
-				:required="required"
-				:selected-labels-fn="selectedLabelsFn"
-				:show-chevron="showChevron"
-				:stash="stash"
-				:transition-duration="transitionDuration"
-				:update-on-animation-frame="updateOnAnimationFrame"
-				v-bind="eventListeners"
-			>
-				<template #append-outer="data"
-					><slot name="append-outer" v-bind="data"
-				/></template>
-				<template #append="data"><slot name="append" v-bind="data" /></template>
-				<template #prefix="data"><slot name="prefix" v-bind="data" /></template>
-				<template #chevron="data"
-					><slot name="chevron" 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>
-				<template #option="data"><slot name="option" v-bind="data" /></template>
-				<template #group="data"><slot name="group" v-bind="data" /></template>
-				<template #options:append="data"
-					><slot name="options:append" v-bind="data"
-				/></template>
-				<template #options:append:outer="data"
-					><slot name="options:append:outer" v-bind="data"
-				/></template>
-				<template #options:prepend="data"
-					><slot name="options:prepend" v-bind="data"
-				/></template>
-				<template #options:prepend:outer="data"
-					><slot name="options:prepend:outer" v-bind="data"
-				/></template>
-				<template #prepend-outer="data"
-					><slot name="prepend-outer" v-bind="data"
-				/></template>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"
-				/></template>
-				<template #suffix="data"><slot name="suffix" v-bind="data" /></template>
-			</BaseSelect>
-		</template>
-	</BaseInputContainer>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div class="flex items-baseline justify-between gap-2">
+			<h3 class="text-sm font-medium">ISSUE-1842</h3>
+			<span class="text-xs text-[color:var(--bb-text-muted)]">In progress</span>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Wire invoice PDF export for the Milan office.
+		</p>
+		<BbSelect
+			v-model="assignee"
+			clearable
+			compact
+			item-text="fullName"
+			item-value="id"
+			:items="teammates"
+			label="Assignee"
+			placeholder="Choose a teammate"
+		/>
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type Teammate = {
+	id: string;
+	fullName: string;
+	role: string;
+};
 
-<script setup lang="ts" generic="T = any">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseSelect from '../BaseSelect/BaseSelect.vue';
-import { ref, computed } from 'vue';
-import type { BbSelectProps, BbSelectEvents, BbSelectSlots } from './types';
-
-const props = withDefaults(defineProps<BbSelectProps<T>>(), {
-	allowWriting: true,
-	filterBy: () => [],
-	prefill: 'focus',
-	showChevron: true,
-});
+// Raw domain objects — passed straight to `items`, never pre-mapped.
+const teammates: Teammate[] = [
+	{ id: 'ada', fullName: 'Ada Lovelace', role: 'Engineering' },
+	{ id: 'grace', fullName: 'Grace Hopper', role: 'Engineering' },
+	{ id: 'maggie', fullName: 'Margaret Hamilton', role: 'Flight Systems' },
+	{ id: 'katherine', fullName: 'Katherine Johnson', role: 'Mathematics' },
+];
 
-const emit = defineEmits<BbSelectEvents>();
-defineSlots<BbSelectSlots<T>>();
+// The model holds the resolved value (id), not the whole object.
+const assignee = ref<string | null>(null);
+</script>
+```
 
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
+Value-identity rules (shared with every items-driven component — see the
+Options and Items playbook):
+
+- For primitive `items` (`string[]` / `number[]`) omit both mapping props — the
+  value is the primitive itself. For object items always set both: the defaults
+  are the whole item as value and `JSON.stringify(item)` as text.
+- Matching compares **value hashes** (deep structural equality, not reference
+  identity), so object values survive refetches — but prefer primitive ids:
+  stable, unique, cheap to submit.
+- Options resolving to a **duplicate value are silently dropped** (first wins).
+- Per-option gating goes through `selectable`: a boolean (`false` disables every
+  option) or a predicate `(item) => boolean` — rejected options render disabled
+  and keyboard navigation skips them (e.g. `:selectable="(u) => u.active"`). A
+  `disabled` field on the item object itself is inert domain data — feed it to
+  the predicate. Alternatives: filter unavailable choices out of `items`, cap
+  with `max`, or disable the whole control with `disabled`.
+
+### The field around the control
+
+`BbSelect` is a complete form field. Everything here is declarative — no custom
+markup needed:
+
+- **Label**: `label` (required), `hide-label`, `label-position`
+  (`left`/`center`/`right`), and `label-mode` — `outside` (the default via
+  global config `defaultInputLabelMode`), `floating`, or `inside`. `reverse`
+  swaps the order of label and control.
+- **Guidance**: `description` renders always-visible helper text linked via
+  `aria-describedby`; `hint` shows contextual guidance while the field is
+  active (add `persistent-hint` to keep it visible).
+- **Validation**: `has-errors` switches error styling; `errors` (string or
+  array) renders the messages, associated with the field for assistive tech.
+  `warnings` (string or array) is the amber counterpart of `errors` — the same
+  messages rendered below the field in their own `aria-live="polite"` region —
+  and referenced from `aria-describedby` while displayed — in
+  amber (`--bb-warn`), with a warning icon in the append stack, for a
+  valid-but-noteworthy selection; a non-empty `warnings` implies the warning
+  state, so `has-warning` just forces that chrome without a message. Unlike
+  `errors` it sets no `aria-invalid` — a soft "needs a second look" state. When
+  both are set the error state wins and the warning messages are suppressed, so
+  the field never shows amber while it has an error.
+- **Form participation**: `name` renders hidden inputs carrying the selection
+  (one per value; non-string values are JSON-stringified), so the select posts
+  in a plain HTML form; `required` adds a visually-hidden sentinel input so
+  native constraint validation fires. `autocomplete` / `autofocus` forward to
+  the control.
+- **Affixes**: `prepend:icon` / `append:icon` place icons in the control —
+  `append:icon` replaces the default chevron (there is no `#chevron` slot).
+- **Value display**: `placeholder` shows when a _single-mode_ select is empty.
+  In multiple mode the placeholder is never rendered — use `description` /
+  `hint` for guidance instead.
+
+**A complete form field**
 
-const eventListeners = {
-	onBlur: (event: FocusEvent) => emit('blur', event),
-	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);
-	},
-	onInactive: () => {
-		active.value = false;
-		emit('inactive');
-	},
-	onInput: (event: Event) => emit('input', event),
-	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
-};
+```vue
+<div class="max-w-sm">
+	<BbSelect
+		v-model="state.plan"
+		label="Plan"
+		description="You can change plan at any time."
+		hint="Yearly billing saves 20%"
+		placeholder="Choose a plan"
+		prepend:icon="lucide:credit-card"
+		required
+		clearable
+		:items="['Starter', 'Growth', 'Enterprise']"
+	/>
+</div>
+```
+
+**Error state**
+
+```vue
+<div class="max-w-sm">
+	<BbSelect
+		v-model="state.country"
+		label="Country"
+		placeholder="Required for invoicing"
+		has-errors
+		errors="Pick a country to continue"
+		:items="['Italy', 'Germany', 'Portugal']"
+	/>
+</div>
+```
+
+### Multiple selection and how it displays
+
+Add `multiple` for multi-select; the model becomes an array and **must be seeded
+as one** (`ref<string[]>([])`) — a non-array model throws at setup. Cap the
+count with `max`: at the cap, unselected options auto-disable while selected
+options never do, so the user can always deselect.
+
+Selected values render as removable chips inside the control. When they no
+longer fit the row, it collapses into a count summary ("N items selected", from
+the active locale). You can steer that display:
+
+- `max-selected-labels` collapses by **count** instead of by overflow width.
+- `selected-labels-fn` customises the summary text (`(count) => string`).
+- `comma` renders a plain comma-separated string instead of chips — values can
+  then only be deselected from the panel.
+- Under `disabled` / `readonly`, chips become non-removable badges.
+
+`clearable` shows a clear affix once there is a value; clearing resets the
+model to `[]` (or `null` in single mode).
+
+**Multi-select with a maximum and collapsed labels**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Warehouse coverage</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Cap at 3 hubs for the pilot route.
+			</p>
+		</div>
+		<BbSelect
+			v-model="cities"
+			clearable
+			compact
+			hint="Pick up to 3 cities"
+			item-text="label"
+			item-value="value"
+			:items="options"
+			label="Cities"
+			:max="3"
+			:max-selected-labels="2"
+			multiple
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+const options = [
+	{ label: 'Amsterdam', value: 'ams' },
+	{ label: 'Berlin', value: 'ber' },
+	{ label: 'Copenhagen', value: 'cph' },
+	{ label: 'Lisbon', value: 'lis' },
+	{ label: 'Milan', value: 'mil' },
+];
+
+// `multiple` requires the model to be an array from the start.
+const cities = ref<string[]>(['ber', 'mil']);
 </script>
+```
+
+**Comma display for dense forms**
 
-<style lang="postcss">
-@import './index.css';
-</style>
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Email digests</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Who gets the Monday summary?
+			</p>
+		</div>
+		<BbSelect
+			v-model="recipients"
+			comma
+			compact
+			item-text="name"
+			item-value="id"
+			:items="team"
+			label="Weekly digest recipients"
+			multiple
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+const team = [
+	{ id: 'ada', name: 'Ada Lovelace' },
+	{ id: 'grace', name: 'Grace Hopper' },
+	{ id: 'alan', name: 'Alan Turing' },
+	{ id: 'maggie', name: 'Margaret Hamilton' },
+];
+
+// `comma` renders the selection as plain comma-separated text: values can only
+// be deselected from the panel, not removed from the control itself.
+const recipients = ref<string[]>(['ada', 'grace']);
+</script>
 ```
 
-## Types
+### Panel actions: header, footer and select-all
 
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { NestedKeyOf } from '@/types/NestedKeyOf';
-import type { IconType } from '@/types/Icon';
-import type { BaseSelectEvents } from '../BaseSelect/types';
-
-export type BbSelectProps<T = any> = {
-	/**
-	 * Allows typing into the input.
-	 */
-	allowWriting?: boolean | 'not-mobile';
-
-	/**
-	 * Name of the icon to be added at the end of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'append:icon'?: IconType;
-
-	/**
-	 * Guides to the browser as to the type of information expected in the field.
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-
-	/**
-	 * Sets autofocus on page load.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Displays a clear button when the input has a value and is being interacted with.
-	 */
-	clearable?: boolean;
-
-	/**
-	 * Sets the display model for selected values to a list of comma separated string.
-	 * In this mode the user cannot deselect an option by pressing the close button.
-	 */
-	comma?: boolean;
-
-	/**
-	 * Sets the component in a compact mode.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Defines an array of dependencies that will trigger actions in the component upon change.
-	 */
-	dependencies?: any[];
-
-	/**
-	 * Timeout used to debounce response to changes to dependencies.
-	 */
-	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`.
-	 */
-	direction?: 'horizontal' | 'vertical' | 'auto' | string;
-
-	/**
-	 * Disables the component.
-	 */
-	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.
-	 */
-	enforceCoherence?: boolean;
-
-	/**
-	 * Can be a string or an array of string containing the messages to display.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * Defines how the filtering should work.
-	 */
-	filterBy?:
-		| string
-		| string[]
-		| false
-		| 'not_stashed'
-		| ((value: any, item: T, query: string | null) => boolean)
-		| null;
-
-	/**
-	 * Path to item property for grouping options.
-	 */
-	groupBy?: string | ((item: T) => string | number | symbol);
-
-	/**
-	 * Define if the component should be in an error state.
-	 * It usually attaches a CSS class for styling purposes.
-	 */
-	hasErrors?: boolean;
-
-	/**
-	 * Visually hides the label of the input while maintaining accessibility.
-	 */
-	hideLabel?: boolean;
-
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Used to retrieve items; can be an array or a function.
-	 */
-	items:
-		| T[]
-		| ((query: string, prefill: boolean, modelValue: any) => Promise<T[]>)
-		| ((query: string, prefill: boolean, modelValue: any) => T[]);
-
-	/**
-	 * Height of group headers in the listbox (px). Defaults to 24px (compact) or 32px.
-	 * Only applies when `groupBy` is set.
-	 */
-	headerHeight?: number;
-
-	/**
-	 * Height of the options in the listbox. By default it will be 32px for the compact
-	 * variant and 40px for the regular variant.
-	 *
-	 * @defaultValue `40`
-	 */
-	itemHeight?: number;
-
-	/**
-	 * Defines a path that returns a property of the object to use as text or a function
-	 * that returns a string.
-	 */
-	itemText?: T extends object
-		? NestedKeyOf<T> | ((item: T) => string)
-		: ((item: T) => string) | undefined;
-
-	/**
-	 * Defines a path that returns a property of the object to use as value or a function
-	 * that returns any value.
-	 */
-	itemValue?: T extends object
-		? NestedKeyOf<T> | ((item: T) => any)
-		: ((item: T) => any) | undefined;
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
+The `#header` and `#footer` slots pin content above the search field and below
+the options list — the same markup renders in the desktop popover and the
+mobile adaptive sheet. Both receive `{ close, clear, focus, query,
+selectedOptions }`: `close()` closes the panel, `clear()` empties the
+selection, `focus()` refocuses the search input, and `selectedOptions` are the
+resolved selected options (`.text` / `.value` / raw `.item`).
+
+Select-all is not built in — it is a one-liner in a panel slot, because the
+v-model is yours:
+
+**Select all + done in the footer**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Incident alerts</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Where should paging go when severity is high?
+			</p>
+		</div>
+		<BbSelect
+			v-model="channels"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="options"
+			label="Notify via"
+			:max-selected-labels="2"
+			multiple
+			:selected-labels-fn="(count) => `${count} channels`"
+		>
+			<template #footer="{ close, clear, selectedOptions }">
+				<div class="flex w-full items-center gap-1.5">
+					<BbButton
+						size="xs"
+						variant="ghost"
+						@click="channels = options.map((option) => option.value)"
+					>
+						Select all
+					</BbButton>
+					<BbButton size="xs" variant="ghost" @click="clear">Clear</BbButton>
+					<BbButton class="ml-auto" size="xs" variant="primary" @click="close">
+						Done ({{ selectedOptions.length }})
+					</BbButton>
+				</div>
+			</template>
+		</BbSelect>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect, BbButton } from 'bitboss-ui';
+
+const options = [
+	{ label: 'Email', value: 'email' },
+	{ label: 'SMS', value: 'sms' },
+	{ label: 'Push notification', value: 'push' },
+	{ label: 'Slack', value: 'slack' },
+];
+
+const channels = ref<string[]>(['email']);
+</script>
+```
+
+The `#header` slot is the mirror image: pin context above the search field — a
+live summary of the selection, computed from your own model since the v-model
+is yours:
+
+**A pinned header with a live summary**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Lisbon half-day</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Build a route under about four hours.
+			</p>
+		</div>
+		<BbSelect
+			v-model="stops"
+			compact
+			hint="A half-day tour fits roughly 4 hours"
+			item-text="name"
+			item-value="id"
+			:items="catalog"
+			label="Tour stops"
+			:max-selected-labels="2"
+			multiple
+		>
+			<template #header="{ clear }">
+				<div
+					class="flex w-full items-center justify-between gap-2 px-1 text-xs text-[color:var(--bb-text-muted)]"
+				>
+					<span>{{ summary }}</span>
+					<BbButton
+						:disabled="!stops.length"
+						size="xs"
+						variant="ghost"
+						@click="clear"
+					>
+						Reset
+					</BbButton>
+				</div>
+			</template>
+		</BbSelect>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbSelect, BbButton } from 'bitboss-ui';
+
+type Stop = { id: string; name: string; durationMin: number };
+
+const catalog: Stop[] = [
+	{ id: 'belem', name: 'Belém Tower', durationMin: 45 },
+	{ id: 'jeronimos', name: 'Jerónimos Monastery', durationMin: 60 },
+	{ id: 'alfama', name: 'Alfama walking tour', durationMin: 90 },
+	{ id: 'tram28', name: 'Tram 28 ride', durationMin: 40 },
+	{ id: 'oceanario', name: 'Oceanário aquarium', durationMin: 120 },
+	{ id: 'lxfactory', name: 'LX Factory market', durationMin: 60 },
+];
+
+const stops = ref<string[]>(['belem', 'alfama']);
+
+// The panel slots also expose `selectedOptions`, but the v-model is ours —
+// deriving the summary from it keeps the header logic on plain typed data.
+const summary = computed(() => {
+	if (!stops.value.length) return 'No stops yet';
+	const total = stops.value.reduce(
+		(sum, id) =>
+			sum + (catalog.find((stop) => stop.id === id)?.durationMin ?? 0),
+		0
+	);
+	const hours = Math.floor(total / 60);
+	const minutes = total % 60;
+	return `${stops.value.length} stops · ~${hours}h${minutes ? ` ${minutes}m` : ''}`;
+});
+</script>
+```
+
+### Search and filtering semantics
+
+The panel carries a search field (role `searchbox`). How typing filters depends
+on your setup:
+
+- **Array `items`**: typing filters locally — a case-insensitive **substring**
+  match against each option's display text.
+- **`filter-by: ['path', ...]`**: the listed item paths are searched **instead
+  of** the display text (no fallback union with the text). Every path must
+  exist on every item, or matching throws. Use it to also match a city by its
+  country, a member by email.
+- **Provider `items`**: the provider re-runs with the query (next section) —
+  and the local text filter **still applies on top of the response**. Results
+  whose display text (or `filter-by` paths) don't contain the query substring
+  are hidden, so fuzzy or synonym-based server matches can vanish. Keep server
+  search substring-compatible, or point `filter-by` at a field the server
+  guarantees to match.
+- **Single-mode exception**: when the query equals the selected option's text
+  (as right after picking), the list shows unfiltered.
+- **`disable-writing`** removes the search field entirely (`true`, or
+  `'mobile'` / `'desktop'` to remove it on one platform only) — this is also
+  the supported way to disable filtering; there is no "falsy `filter-by`"
+  escape hatch.
+
+**Match on fields other than the display text**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Shipping destination</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Search by city or country name.
+			</p>
+		</div>
+		<BbSelect
+			v-model="city"
+			compact
+			:filter-by="['label', 'country']"
+			item-text="label"
+			item-value="id"
+			:items="cities"
+			label="City"
+			placeholder="Search city or country"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type City = { label: string; country: string; id: string };
+
+// `filter-by` searches these item paths instead of the display text, so a
+// city matches by its country too — every listed path must exist on every item.
+const cities: City[] = [
+	{ label: 'Milan', country: 'Italy', id: 'mil' },
+	{ label: 'Rome', country: 'Italy', id: 'rom' },
+	{ label: 'Lisbon', country: 'Portugal', id: 'lis' },
+	{ label: 'Porto', country: 'Portugal', id: 'por' },
+];
+
+const city = ref<string | null>(null);
+</script>
+```
+
+### Fetch options with a provider
+
+When options come from a backend, pass a **function** to `items` instead of an
+array. It receives `(query, prefill, modelValue)` and returns `T[]` or a
+`Promise<T[]>` — the full call matrix lives in the Fetch Items playbook. The
+short version:
+
+- `prefill === false` means exactly one thing: **the user typed**. Search then.
+- Every component-initiated call (first load, dependency change, external model
+  update) passes `prefill === true` and expects the current selection to stay
+  resolvable in the response — return the selected items (by id) so chosen
+  values are never orphaned.
+- `modelValue` is your v-model as-is (array in multiple mode, the raw model
+  value — possibly `null` — otherwise); the prop declares it `any`, so annotate
+  it `any` or your own model type.
+
+**Async, debounced member search**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Pull request reviewers</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Search the directory; picks stay pinned.
+			</p>
+		</div>
+		<BbSelect
+			v-model="reviewers"
+			clearable
+			compact
+			hint="Type a name to search"
+			item-text="name"
+			item-value="id"
+			:items="searchMembers"
+			label="Reviewers"
+			loading-text="Searching…"
+			multiple
+			no-data-text="No members match your search"
+			persistent-hint
+			:query-debounce-time="300"
+			stash
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
 
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Sets the component in a loading state, usually triggering some visual styles.
-	 */
-	loading?: boolean;
-
-	/**
-	 * String displayed while items are being loaded.
-	 */
-	loadingText?: string;
-
-	/**
-	 * Maximum number of selectable items when the multiple flag is set.
-	 */
-	max?: number;
-
-	/**
-	 * Maximum number of labels shown before collapsing to a count summary.
-	 */
-	maxSelectedLabels?: number;
-
-	/**
-	 * Used by v-model. Can be any serializable type.
-	 */
-	modelValue: any;
-
-	/**
-	 * Timeout used to debounce response to changes to modelValue.
-	 */
-	modelValueDebounceTime?: number;
-
-	/**
-	 * Allows the selection of multiple items.
-	 */
-	multiple?: boolean;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name?: InputHTMLAttributes['name'];
-
-	/**
-	 * String displayed when there are no items to display.
-	 */
-	noDataText?: string;
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * String displayed when there's no data.
-	 */
-	placeholder?: InputHTMLAttributes['placeholder'];
-
-	/**
-	 * Defines the prefill strategy for the input. By default the input will prefill
-	 * on focus. It can also always prefill with `true` and only prefill on search with `false`.
-	 *
-	 * @defaultValue `'focus'`
-	 */
-	prefill?: boolean | 'focus';
-
-	/**
-	 * Name of the icon to be added at the start of the input.
-	 */
-	// eslint-disable-next-line vue/prop-name-casing
-	'prepend:icon'?: IconType;
-
-	/**
-	 * Sets the input as required.
-	 */
-	required?: boolean;
-
-	/**
-	 * Time to wait when the user stops writing in the input before querying data.
-	 */
-	queryDebounceTime?: number;
-
-	/**
-	 * Sets the input in a readonly state.
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Reverses the layout. Applicable in every direction the order of the label and
-	 * the input is swapped.
-	 */
-	reverse?: boolean;
-
-	/**
-	 * Function that returns a string to be displayed when the number of selected labels
-	 * is greater than `maxSelectedLabels`.
-	 */
-	selectedLabelsFn?: (count: number) => string;
-
-	/**
-	 * If true, the chevron will be shown.
-	 *
-	 * @defaultValue `true`
-	 */
-	showChevron?: boolean;
-
-	/**
-	 * Adds a stash to accumulate selected values across searches.
-	 */
-	stash?: boolean;
-
-	/**
-	 * How long the transition has to last in milliseconds.
-	 */
-	transitionDuration?: number;
-
-	/**
-	 * Pass `true` if the dropdown is not updating following movement in the UI, like in modals.
-	 * Very expensive so use with care.
-	 */
-	updateOnAnimationFrame?: boolean;
+type Member = {
+	id: string;
+	name: string;
 };
 
-/** Re-export for consumers importing events type from BbSelect. */
-export type BbSelectEvents = BaseSelectEvents;
+// Stand-in for a real API. In a product this is `api.members.search(...)`.
+const directory: Member[] = [
+	{ id: 'ada', name: 'Ada Lovelace' },
+	{ id: 'alan', name: 'Alan Turing' },
+	{ id: 'grace', name: 'Grace Hopper' },
+	{ id: 'katherine', name: 'Katherine Johnson' },
+	{ id: 'ken', name: 'Ken Thompson' },
+	{ id: 'maggie', name: 'Margaret Hamilton' },
+];
+
+const fetchFromApi = (predicate: (member: Member) => boolean) =>
+	new Promise<Member[]>((resolve) => {
+		setTimeout(() => resolve(directory.filter(predicate)), 250);
+	});
+
+// With `stash`, picked options stay resolvable across later searches, so the
+// provider only ever answers the current query — no need to merge the selected
+// members back into every response.
+const searchMembers = (
+	query: string,
+	_prefill: boolean,
+	_modelValue: string[]
+): Promise<Member[]> => {
+	const q = query.trim().toLowerCase();
+	if (!q) return Promise.resolve([]);
+	return fetchFromApi((member) => member.name.toLowerCase().includes(q));
+};
 
-/** Props exposed by the `label` slot. */
-export type BbSelectLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the input is in an error state. */
-	hasErrors: boolean;
+const reviewers = ref<string[]>([]);
+</script>
+```
+
+```ts
+const searchMembers = async (
+	query: string,
+	prefill: boolean,
+	modelValue: string[]
+): Promise<Member[]> => {
+	// Component-initiated: keep the current selection resolvable.
+	if (prefill && modelValue.length) {
+		return api.members.byIds(modelValue);
+	}
+	if (!query.trim()) return []; // project-defined idle behavior
+	return api.members.search({ query });
 };
+```
+
+Runtime guarantees you should not re-implement:
+
+- **Debouncing**: typing is debounced by `query-debounce-time` (default 500ms);
+  dependency reloads by `deps-debounce-time` (default 0); external model-change
+  reloads by `model-value-debounce-time` (default 0).
+- **Race protection**: out-of-order responses are discarded — only the latest
+  request writes items.
+- **Loading**: in-flight requests set the loading state automatically — the
+  `loading` prop is only for _external_ pending state (e.g. the parent form).
+- **Errors**: a rejected provider is logged (`console.error`) and the previous
+  items are kept; surface failures yourself (e.g. `useToast`) if the user must
+  know.
+- **Panel states**: `loading-text` / `no-data-text` (locale defaults
+  "Loading..." / "No data to display") or the `#loading` / `#no-data` slots —
+  both receive `{ query }`, `#no-data` also a `focus()` callback.
+
+Enable `stash` to accumulate picked options across searches: selected values
+stay resolvable (chips keep their text, coherence keeps passing) even when
+later responses don't include them — no need to merge them into every response.
+
+### Laziness and prefill
+
+`prefill` controls **when the first load happens**:
+
+- `'interaction'` (default) — on the first open.
+- `true` — immediately on mount, and during SSR (`onServerPrefetch`), so the
+  panel is warm on hydration.
+- `false` — **search-first**: nothing loads until the user types. Opening is not
+  a search, so the panel opens empty and shows a _"search to begin"_ hint until
+  the first query. Use it when the result set is too big or too costly to browse
+  and the query is the only sensible entry point.
+
+When the model already has a value, `BbSelect` upgrades to immediate prefill
+regardless of the setting, so the selection can render its text right away — so
+`false` never strands a seeded value. **Array `items` are never lazy either** —
+there is no request to defer, so they resolve on mount whatever `prefill` says.
+
+Search-first also needs a search field to exist, so `disable-writing` (which
+hides it) falls back to loading on open — otherwise the user would face an empty
+panel with no way to fill it.
+
+That upgrade reads "has a value" as "is not empty", and `null` counts as
+**empty** — which is the one case where you must ask for the load yourself (see
+the next section).
+
+Laziness also gates coherence: an untouched `prefill: 'interaction'` select — or
+an un-searched `prefill: false` one — with a **provider** and an **empty** model
+ignores `dependencies` and external model changes until its first load. Don't
+"fix" the quiet period with eager watchers: there is nothing on screen to keep
+coherent yet, and the first load reads the current dependencies anyway. The user's
+first search counts as that load, so a search-first select tracks `dependencies`
+from then on.
+
+### An "All" / "Any" option (`null` as a real value)
+
+Distinct from the [select-all footer button](#panel-actions-header-footer-and-select-all)
+above: that fills a `multiple` array with every option. This is a **single**
+select where one option means _"everything"_ — the "no filter" row at the top of
+a location or status filter.
+
+Model it as a real option whose value is `null`, returned by your provider (or
+present in your array) like any other. It resolves and renders as the selection.
+
+**The one requirement: with a provider, set `prefill: true`.** `null` is also the
+value the library reads as _nothing selected_, so the automatic
+model-has-a-value upgrade does **not** fire for it. Nothing loads, there is no
+text to show, and the field falls back to the **placeholder** — greyed, and
+indistinguishable from an empty select, while your model holds a real choice.
+The library cannot tell that `null` means "All" in your app without loading the
+options to look, so you have to say so:
+
+**An 'All locations' filter (provider + prefill)**
 
-/** Props exposed by the `option` slot. */
-export type BbSelectOptionSlotProps<T> = {
-	/** 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;
-	/** Whether the select is in an error state. */
-	hasErrors?: boolean;
-	/** The raw item from the `items` prop. */
-	item: T;
-	/** 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;
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Invoice filters</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Office location, or every office.
+			</p>
+		</div>
+		<BbSelect
+			v-model="location"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="loadLocations"
+			label="Location"
+			placeholder="Select location…"
+			prefill
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Filtering by:
+			<strong>{{ location === null ? 'All locations' : location }}</strong>
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type Location = { label: string; value: string | null };
+
+const pool: Location[] = [
+	{ label: 'Milan', value: 'milan' },
+	{ label: 'Rome', value: 'rome' },
+	{ label: 'Berlin', value: 'berlin' },
+];
+
+/**
+ * "Everything" is modelled as a real option whose value is `null`, sitting at
+ * the top of the list next to the concrete ones. Returned by the provider like
+ * any other option — the component does not synthesise it.
+ */
+const ALL: Location = { label: 'All locations', value: null };
+
+// `null` is the seeded value, and here it means "All locations" — not "empty".
+const location = ref<string | null>(null);
+
+const loadLocations = (
+	query: string,
+	prefill: boolean
+): Promise<Location[]> => {
+	const q = query.trim().toLowerCase();
+	const matches =
+		prefill || !q
+			? pool
+			: pool.filter((l) => l.label.toLowerCase().includes(q));
+	// "All" always leads the list; it is not filtered out by a search.
+	return new Promise((resolve) =>
+		setTimeout(() => resolve([ALL, ...matches]), 200)
+	);
 };
+</script>
+```
+
+With an **array** you need nothing at all — arrays are never lazy, so "All
+locations" renders from the first paint:
+
+**The same thing with array items — no prefill needed**
+
+```vue
+<BbSelect
+	v-model="state.location"
+	item-text="label"
+	item-value="value"
+	:items="[
+		{ label: 'All locations', value: null },
+		{ label: 'Milan', value: 'milan' },
+		{ label: 'Rome', value: 'rome' },
+	]"
+	label="Location"
+	placeholder="Select location…"
+/>
+```
+
+Know what else you inherit by overloading `null`, because the component cannot
+distinguish the two meanings:
 
-/** Props exposed by the `group` slot. */
-export type BbSelectGroupSlotProps<T> = {
-	/** The display text for this group. */
-	text: string;
-	/** The raw group item. */
-	item: T;
-	/** 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;
+- **`clear` selects "All".** The clear button emits `null`, which is now a
+  choice, not an absence.
+- **`enforce-coherence` never prunes it** — an empty selection is always
+  coherent, so the "All" value is never questioned.
+- **A prune of some _other_ stale value widens to "All"**, because enforcement
+  emits `null` in single mode. A dead filter value becomes "show everything"
+  rather than "show nothing".
+
+If "everything" and "nothing" must stay distinct — a required field, or a filter
+where widening is unsafe — use a **sentinel** instead (`value: 'all'`). Then
+`null` keeps meaning empty, but the sentinel must appear in **every** provider
+response or `enforce-coherence` will prune it, and it counts as a value, so it
+triggers the eager-prefill upgrade on its own.
+
+### Dependent fields and enforced coherence
+
+When one select constrains another, list the upstream value in `dependencies`:
+the component re-runs its `items` provider whenever a dependency changes
+(value-hash compared, so array identity churn doesn't refetch), debounced by
+`deps-debounce-time`. Add `enforce-coherence` so a now-invalid selection is
+cleaned up automatically. Details in the Coherence playbook.
+
+**Region drives the city options**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Shipping address</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				City options follow the chosen region.
+			</p>
+		</div>
+		<BbSelect
+			v-model="region"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="regions"
+			label="Region"
+			placeholder="Pick a region"
+		/>
+		<BbSelect
+			v-model="city"
+			compact
+			:dependencies="[region]"
+			:deps-debounce-time="150"
+			enforce-coherence
+			item-text="label"
+			item-value="value"
+			:items="loadCities"
+			label="City"
+			:placeholder="region ? 'Pick a city' : 'Select a region first'"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type Region = { label: string; value: string };
+type City = { label: string; value: string; region: string };
+
+const regions: Region[] = [
+	{ label: 'Italy', value: 'it' },
+	{ label: 'Germany', value: 'de' },
+	{ label: 'Portugal', value: 'pt' },
+];
+
+const cityPool: City[] = [
+	{ label: 'Rome', value: 'rome', region: 'it' },
+	{ label: 'Milan', value: 'milan', region: 'it' },
+	{ label: 'Berlin', value: 'berlin', region: 'de' },
+	{ label: 'Munich', value: 'munich', region: 'de' },
+	{ label: 'Lisbon', value: 'lisbon', region: 'pt' },
+	{ label: 'Porto', value: 'porto', region: 'pt' },
+];
+
+// Single-mode enforcement resolves to `null` — seed the models accordingly.
+const region = ref<string | null>(null);
+const city = ref<string | null>(null);
+
+// The provider reads the selected region; the component re-runs it whenever
+// `region` changes because it is listed in `dependencies`. Component-initiated
+// calls (`prefill === true`) return the region's whole pool so a still-valid
+// city stays resolvable; `enforce-coherence` clears one that no longer fits.
+const loadCities = (query: string, prefill: boolean): Promise<City[]> => {
+	const pool = cityPool.filter((c) => c.region === region.value);
+	const q = query.trim().toLowerCase();
+	const matches =
+		prefill || !q
+			? pool
+			: pool.filter((c) => c.label.toLowerCase().includes(q));
+	return new Promise((resolve) => setTimeout(() => resolve(matches), 200));
 };
+</script>
+```
+
+What enforcement emits when a reload leaves the model incoherent:
+
+- multiple → `update:modelValue` with the **filtered array** (still-valid
+  entries survive);
+- single → `update:modelValue` with **`null`** — seed single models as
+  `ref<T | null>(null)` and treat `null` as "nothing valid" in submit logic;
+- an empty selection is always coherent, so nothing fires.
+
+In multiple mode the pruning shows up as a filtered chip row. Here switching
+the project keeps reviewers who belong to the new team and drops the rest —
+no watcher, no manual reset:
+
+**Project change prunes reviewers**
 
-export type BbSelectSlots<T> = {
-	/**
-	 * Content appended inside the input field, after the value area.
-	 */
-	append?: (props: { query: string; focus: () => void }) => any;
-	/**
-	 * Content appended outside the input field wrapper.
-	 */
-	'append-outer'?: (props: { query: string }) => any;
-	/**
-	 * Replaces the default dropdown chevron icon.
-	 */
-	chevron?: (props: { loading: boolean; shown: boolean }) => any;
-	/**
-	 * Replaces the default label text rendered above the input.
-	 */
-	label?: (props: BbSelectLabelSlotProps) => 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: BbSelectOptionSlotProps<T>) => any;
-	/**
-	 * Replaces the default group header rendered above grouped options.
-	 */
-	group?: (props: BbSelectGroupSlotProps<T>) => any;
-	/**
-	 * Content appended inside the options list, after the last option.
-	 */
-	'options:append'?: (props: {
-		focus: () => void;
-		close: () => Promise<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;
-		close: () => Promise<void>;
-	}) => any;
-	/**
-	 * Content prepended outside the options list container.
-	 */
-	'options:prepend:outer'?: (props: { focus: () => void }) => any;
-	/**
-	 * Content rendered as an inline prefix inside the input field.
-	 */
-	prefix?: (props: object) => any;
-	/**
-	 * Content prepended inside the input field, before the value area.
-	 */
-	prepend?: (props: { query: string; focus: () => void }) => any;
-	/**
-	 * Content prepended outside the input field wrapper.
-	 */
-	'prepend-outer'?: (props: { query: string }) => any;
-	/**
-	 * Content rendered as an inline suffix inside the input field.
-	 */
-	suffix?: (props: object) => any;
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Review request</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Reviewers must belong to the selected project.
+			</p>
+		</div>
+		<BbSelect
+			v-model="project"
+			compact
+			item-text="name"
+			item-value="id"
+			:items="projects"
+			label="Project"
+		/>
+		<BbSelect
+			v-model="reviewers"
+			compact
+			:dependencies="[project]"
+			:deps-debounce-time="150"
+			enforce-coherence
+			hint="Only members of the selected project can review"
+			item-text="name"
+			item-value="id"
+			:items="loadReviewers"
+			label="Reviewers"
+			multiple
+			name="reviewers"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type Project = { id: string; name: string };
+type Member = { id: string; name: string; projects: string[] };
+
+const projects: Project[] = [
+	{ id: 'web', name: 'Web app' },
+	{ id: 'mobile', name: 'Mobile app' },
+];
+
+const members: Member[] = [
+	{ id: 'ada', name: 'Ada Lovelace', projects: ['web', 'mobile'] },
+	{ id: 'grace', name: 'Grace Hopper', projects: ['web'] },
+	{ id: 'alan', name: 'Alan Turing', projects: ['mobile'] },
+	{ id: 'maggie', name: 'Margaret Hamilton', projects: ['web', 'mobile'] },
+];
+
+const project = ref<string>('web');
+// A seeded selection upgrades the select to immediate prefill, so the
+// dependency watcher is armed from the first render.
+const reviewers = ref<string[]>(['ada', 'grace']);
+
+// Query-aware provider: `prefill === false` only when the user typed. On
+// component-initiated calls (mount, project change) return the project's full
+// member pool, so a still-valid selection stays resolvable — switching to
+// "Mobile app" keeps Ada and prunes Grace.
+const loadReviewers = (query: string, prefill: boolean): Promise<Member[]> => {
+	const pool = members.filter((member) =>
+		member.projects.includes(project.value)
+	);
+	const q = query.trim().toLowerCase();
+	const matches =
+		prefill || !q
+			? pool
+			: pool.filter((member) => member.name.toLowerCase().includes(q));
+	return new Promise((resolve) => setTimeout(() => resolve(matches), 200));
 };
+</script>
 ```
 
-## Styles
+Because enforcement checks the merged result (fetched + stashed), a provider
+that returns `[]` on a `prefill: true` call **will wipe a valid selection** —
+always resolve the current selection on component-initiated calls (or enable
+`stash`).
 
-```css
-.bb-select {
-	.bb-base-input-container {
-		.bb-base-input-container__input {
-			.bb-base-select {
-				display: flex;
-			}
-		}
+### 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 `''` — guard). The component
+does not create anything itself: append the new item to `items` and select it.
+This is the idiomatic pattern for closed-but-growable vocabularies.
+
+**Create a label by pressing Enter**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Issue labels</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Add from the list, or invent one with Enter.
+			</p>
+		</div>
+		<BbSelect
+			v-model="labels"
+			clearable
+			compact
+			item-text="name"
+			item-value="id"
+			:items="available"
+			label="Labels"
+			multiple
+			no-data-text="No matching label — press Enter to create it"
+			@option:add="createLabel"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type Label = { id: string; name: string };
+
+const available = ref<Label[]>([
+	{ id: 'bug', name: 'Bug' },
+	{ id: 'docs', name: 'Documentation' },
+	{ id: 'design', name: 'Design' },
+]);
+
+const labels = ref<string[]>(['bug']);
+
+// `option:add` fires with the trimmed query when the user presses Enter and no
+// option is highlighted. It can fire with '' (Enter on an empty query) — guard.
+const createLabel = (text: string) => {
+	const name = text.trim();
+	if (!name) return;
+	const id = name.toLowerCase().replace(/\s+/g, '-');
+	if (!available.value.some((label) => label.id === id)) {
+		// Mutating `items` re-runs the options pipeline, so the new label is
+		// immediately matchable — no manual refresh needed.
+		available.value = [...available.value, { id, name }];
+	}
+	if (!labels.value.includes(id)) {
+		labels.value = [...labels.value, id];
 	}
-}
+};
+</script>
+```
+
+### Group related options
+
+Set `group-by` to a field path (or a function) to bucket options under headers.
+The `#group` slot styles the header and receives
+`{ text, item, index, length, disabled }` — `length` is the number of options
+in the group, `index` the list index of its first option.
+
+**Options grouped by department**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div>
+			<h3 class="text-sm font-medium">Invite teammate</h3>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Roles grouped by department.
+			</p>
+		</div>
+		<BbSelect
+			v-model="role"
+			clearable
+			compact
+			group-by="department"
+			item-text="label"
+			item-value="value"
+			:items="roles"
+			label="Role"
+			placeholder="Pick a role"
+		>
+			<template #group="{ text, length }">
+				<div
+					class="flex items-center justify-between px-2 text-xs font-semibold text-[color:var(--bb-text-muted)]"
+				>
+					<span>{{ text }}</span>
+					<span>{{ length }}</span>
+				</div>
+			</template>
+		</BbSelect>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSelect } from 'bitboss-ui';
+
+type Role = { label: string; value: string; department: string };
+
+// `group-by` buckets options under headers by this field path; the `#group`
+// slot styles each header and receives the group `text` and `length`.
+const roles: Role[] = [
+	{ label: 'Frontend', value: 'fe', department: 'Engineering' },
+	{ label: 'Backend', value: 'be', department: 'Engineering' },
+	{ label: 'Brand', value: 'br', department: 'Design' },
+	{ label: 'Product', value: 'pr', department: 'Design' },
+];
+
+const role = ref<string | null>(null);
+</script>
 ```
+
+### Custom option rows
+
+The `#option` slot replaces the default row rendering — use it for avatars,
+secondary text or metadata. It exposes the raw `item`, the resolved `text` and
+`value`, plus `selected` / `focused` / `disabled` / `loading` / `hasErrors`
+flags and the row `index`. Rows are fixed-height (the list is virtualized): if
+your markup is taller than the default 40px (32px compact), set `item-height`
+to match — and `header-height` for grouped headers (defaults 32px / 24px
+compact).
+
+**Rich option rows with an avatar chip**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-3">
+		<div class="flex items-baseline justify-between gap-2">
+			<h3 class="text-sm font-medium">Code review</h3>
+			<span class="text-xs text-[color:var(--bb-text-muted)]">PR #842</span>
+		</div>
+		<BbSelect
+			v-model="assignee"
+			compact
+			item-text="label"
+			item-value="value"
+			:items="teammates"
+			label="Assignee"
+			placeholder="Choose a teammate"
+		>
+			<template #option="{ item, text }">
+				<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>
+					<span class="shrink-0 text-xs text-[color:var(--bb-text-muted)]">{{
+						item.role
+					}}</span>
+				</span>
+			</template>
+		</BbSelect>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbAvatar, BbSelect } from 'bitboss-ui';
+
+type Teammate = {
+	label: string;
+	value: string;
+	initials: string;
+	role: string;
+};
+
+// The `#option` slot replaces the default row rendering — here a BbAvatar
+// initials fallback next to the resolved display `text`.
+const teammates: Teammate[] = [
+	{
+		label: 'Ada Lovelace',
+		value: 'ada',
+		initials: 'AL',
+		role: 'Platform',
+	},
+	{
+		label: 'Grace Hopper',
+		value: 'grace',
+		initials: 'GH',
+		role: 'Backend',
+	},
+	{
+		label: 'Margaret Hamilton',
+		value: 'maggie',
+		initials: 'MH',
+		role: 'Flight',
+	},
+];
+
+const assignee = ref<string | null>(null);
+</script>
+```
+
+### Slots around the input
+
+Beyond the panel slots, the field itself is extensible:
+
+- `#label` replaces the label text; receives `{ text, hasErrors }`.
+- `#prefix` / `#suffix` render inline adornments inside the field (no scope) —
+  currency symbols, units.
+- `#prepend` / `#append` render inside the field wrapper, before/after the
+  value area; both receive `{ query, focus, close }`.
+- `#prepend-outer` / `#append-outer` render outside the field wrapper; both
+  receive `{ query, close }` — e.g. a companion button acting on the field.
+
+Prefer the icon props (`prepend:icon` / `append:icon`) over slots when an icon
+is all you need.
+
+### States
+
+- `disabled` — control inert, chips become badges, hidden form inputs disabled.
+- `readonly` — the value is visible and focusable but **the panel never
+  opens**; chips become non-removable badges. Use it for review screens, not
+  for fields whose options the user might still need to browse (they can't).
+- `loading` — external loading state: shows the control spinner and suspends
+  keyboard opening. Fetch-driven loading is automatic; don't mirror it here.
+- `clearable` — clear affix when a value exists; emits `null` / `[]`.
+- Empty panel — `no-data-text` or `#no-data`.
+
+### Events and v-model
+
+- `update:modelValue` — the resolved value (single) or array (multiple), on
+  pick, chip removal, clear and coherence enforcement.
+- `option:add` — Enter on a query with no highlighted option (see above).
+- `focus` / `blur` — the control gaining/losing focus; `input` / `change` —
+  native events from the panel search field.
+- `inactive` — focus has fully left the component (control **and** panel).
+  Because focus legitimately moves into the panel, validate on `inactive`, not
+  on `blur`.
+
+### Keyboard model
+
+Shipped behavior — never reimplement it:
+
+- Closed, control focused: `ArrowDown` opens and focuses the first selected
+  option, `ArrowUp` opens and focuses the last selected, `Enter` opens and
+  focuses the selection or the search field.
+- Open: typing searches; `ArrowDown` / `ArrowUp` move the highlighted option
+  while DOM focus stays in the search field (conveyed via
+  `aria-activedescendant`); `Enter` confirms the highlighted option — or emits
+  `option:add` when none is highlighted; `Esc` closes and returns focus to the
+  control.
+- Picking in single mode closes the panel and refocuses the control; in
+  multiple mode the panel stays open and focus returns to the search field.
+- Clicks or focus outside the control and panel close it.
+- `disabled`, `readonly` and `loading` suppress the open/navigate bindings
+  (`Esc` still closes an open panel).
+
+### Sizing and layout
+
+- `compact` — denser control and panel (32px options, 24px group headers).
+- The panel width always matches the control; the control fills its container,
+  so size it with layout classes on a wrapper (`class="max-w-xs"` etc.).
+- `direction` works whenever the resolved label mode is `'outside'` (the
+  library default) — `direction="horizontal"` gives a label-beside-field row.
+  Only `floating`/`inside` label modes force the vertical layout, since they
+  embed the label in the field itself.
+
+### 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 chips row of the current selection above the
+search field. 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`, …).
+- `disable-writing="'mobile'"` hides the search on the sheet only — common when
+  the list is short.
+- Set `:adaptive="false"` to keep a floating popover everywhere.
+
+### Global config and platforms
+
+From the vite/nuxt plugin options:
+
+- `config.adaptive` — default for `adaptive` (see above).
+- `config.mobileMaxWidth` — the viewport threshold for "mobile".
+- `config.defaultInputLabelMode` — default `label-mode`.
+- `config.locale` (`'en'` / `'it'`) — built-in strings: the collapsed-chips
+  summary ("N items selected") and the panel loading/no-data defaults.
+
+Platform notes:
+
+- **SSR / Nuxt**: `prefill: true` providers also run in `onServerPrefetch`, so
+  server-rendered pages hydrate with options loaded. Keep providers isomorphic
+  (no `window` access).
+- **Plain HTML forms / Inertia form posts**: give the select a `name` — hidden
+  inputs carry the values (JSON-stringified when not strings), and `required`
+  participates in native validation.
+- The desktop panel is anchored to the control; the mobile sheet manages its
+  own backdrop, Escape and focus.
+
+### Works well with
+
+- `BbSelectPopover` — the same engine on a custom trigger (status pills,
+  table-cell chips, toolbars).
+- `BbTable` — selects as column filters: list their models in the table
+  provider's `dependencies`.
+- `useToast` — surface provider failures (the component only logs them).
+- `BbRadioGroup` / `BbCheckboxGroup` — swap to these when the option set turns
+  out small and static; the `items` contract is identical, so migration is
+  cheap.
+- `BbTag` — open vocabularies typed by the user; `BbSelect` + `option:add`
+  covers "known set, occasionally growable".
+
+### Gotchas and constraints
+
+- **Clicking the selected option does not clear a single select** — it re-picks
+  it and closes the panel. Add `clearable` for an explicit clear button; a
+  required status field should not empty itself because someone clicked twice.
+  Multiple mode still toggles a selected option off.
+- `multiple` with a non-array model **throws at setup** — seed `ref([])`.
+- `placeholder` renders only in single mode; an empty multiple select shows
+  nothing.
+- **A `null` "All" option needs `prefill: true` when `items` is a provider.**
+  Modelling "everything" as `{ label: 'All locations', value: null }` works — the
+  row resolves and renders as the selection — but `null` is also the value the
+  component reads as _nothing selected_, so it never upgrades to an eager
+  prefill. With a provider that means nothing loads, there is no text, and the
+  field renders the **placeholder** — greyed, indistinguishable from an empty
+  select, while the model holds a real choice. Set `prefill: true` so the label
+  can resolve. Array `items` need nothing: they are never lazy. (Note `clear`
+  then also produces `null`, i.e. it selects "All" — use a sentinel like `'all'`
+  if the two must stay distinct.)
+- The local substring filter also applies to provider results — server matches
+  whose text doesn't contain the query are hidden (see Search semantics).
+- `filter-by` is `string[]` only (no function, no bare string) and matches
+  exclusively those paths; each path must exist on every item or matching
+  throws.
+- `prefill: false` still fetches once when the panel first opens.
+- `readonly` prevents the panel from opening at all.
+- `enforce-coherence` + a provider that drops the selection on `prefill: true`
+  calls = wiped model. Resolve the selection, or enable `stash`.
+- The flip side: `stash` keeps every previously fetched option resolvable, so
+  on a select with `dependencies` it also keeps _stale_ picks coherent —
+  enforcement will never prune them. When an upstream change must clear
+  now-invalid values, skip `stash` and resolve the selection in the provider
+  instead.
+- `direction` is honored with `'outside'` labels (the default); it is ignored
+  only under `floating`/`inside` label modes.
+- No `#chevron` slot — customise the trailing icon via `append:icon`.
+- The multiple-mode search query persists after picking an option (it clears on
+  close).
+- `option:add` can fire with an empty string — trim and guard in the handler.
+
+### Anti-patterns
+
+- Pre-mapping items to `{ label, value }`, or storing whole objects in the
+  model when an id is enough.
+- `watch(filter, refetch)` when `dependencies` exists; blind `model = null`
+  resets when `enforce-coherence` would preserve still-valid values.
+- Hand-rolled debounce or loading refs around the provider.
+- Rebuilding chips, counts or select-all outside the component when `max`,
+  `max-selected-labels`, `selected-labels-fn` and the panel slots cover it.
+- Expecting a `disabled` field on items to disable options — it is inert data;
+  use the `selectable` predicate or filter unavailable options out.
+- Using `BbSelect` for three static options (that's `BbRadioGroup`), or as an
+  actions menu (that's `BbDropdown`).
+
+### Accessibility
+
+- `label` is mandatory and is the accessible name; use `hide-label` (not an
+  empty label) to hide it visually. The activator is announced as a combobox
+  with `aria-expanded`, `aria-controls` and the selected text exposed as
+  `aria-valuetext`.
+- `errors`, `warnings`, `description` and `hint` are all wired to the trigger through
+  `aria-describedby`, in that order: the reason the field is invalid is spoken
+  first when it regains focus, and a channel is referenced only while it
+  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
+  so they are announced the moment they appear — announced on change, re-read
+  on focus. The error state also sets `aria-invalid`.
+- The panel manages listbox roles, `aria-activedescendant` and the full
+  keyboard model (see Keyboard model) for you — do not rebuild any of it.
+- The in-panel search field ships an accessible name ("Search options").
+- Chip removal affordances only render when removal is actually possible (not
+  under `disabled` / `readonly` / `comma`).
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `adaptive` | `boolean \| undefined` | `undefined` |  | 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. When unset, falls back to the global `config.adaptive`. |
+| `append:icon` | `string \| undefined` |  |  | Name of the icon to be added at the end of the input. |
+| `autocomplete` | `string \| undefined` |  |  | Guides to the browser as to the type of information expected in the field. |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `clearable` | `boolean \| undefined` |  |  | Displays a clear button when the input has a value and is being interacted with. |
+| `comma` | `boolean \| undefined` |  |  | Sets the display model for selected values to a list of comma separated string. In this mode the user cannot deselect an option by pressing the close button. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact mode. |
+| `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
+| `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
+| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
+| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `disableWriting` | `boolean \| "mobile" \| "desktop" \| undefined` |  |  | Controls whether the search input is shown inside the dropdown panel. Use `'mobile'` / `'desktop'` to hide it on that platform only. |
+| `enforceCoherence` | `boolean \| undefined` |  |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. modelValue will be reset upon incoherence. |
+| `errors` | `string \| string[] \| undefined` |  |  | 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… |
+| `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: T) => string \| number \| symbol) \| undefined` |  |  | Path to item property for grouping options. |
+| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `headerHeight` | `number \| undefined` |  |  | Height of group headers in the listbox (px). Defaults to 24px (compact) or 32px. Only applies when `groupBy` is set. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `itemHeight` | `number \| undefined` |  |  | Height of the options in the listbox. By default it will be 32px for the compact variant and 40px for the regular variant. |
+| `items` | `T[] \| ((query: string, prefill: boolean, modelValue: any) => Promise<T[]>) \| ((query: string, prefill: boolean, modelValue: any) => T[])` |  | yes | Used to retrieve items; can be an array or a function. |
+| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
+| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelMode` | `"floating" \| "outside" \| "inside" \| undefined` |  |  | Label rendering mode. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loading` | `boolean \| undefined` |  |  | Sets the component in a loading state, usually triggering some visual styles. |
+| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
+| `max` | `number \| undefined` |  |  | Maximum number of selectable items when the multiple flag is set. |
+| `maxSelectedLabels` | `number \| undefined` |  |  | Maximum number of labels shown before collapsing to a count summary. |
+| `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
+| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
+| `multiple` | `boolean \| undefined` |  |  | Allows the selection of multiple items. |
+| `name` | `string \| undefined` |  |  | Defines the name of the input. |
+| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
+| `offCanvasProps` | `Partial<BbOffCanvasProps> \| undefined` |  |  | Extra props forwarded to the `BbOffCanvas` sheet when `adaptive` is active on mobile. |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `placeholder` | `string \| undefined` |  |  | String displayed when there's no data. |
+| `prefill` | `boolean \| "interaction" \| undefined` | `undefined` |  | 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, a… |
+| `prepend:icon` | `string \| undefined` |  |  | Name of the icon to be added at the start of the input. |
+| `queryDebounceTime` | `number \| undefined` |  |  | Time to wait when the user stops writing in the input before querying data. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `selectable` | `boolean \| ((item: T) => 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. |
+| `selectedLabelsFn` | `((count: number) => string) \| undefined` |  |  | Function that returns a string to be displayed when the number of selected labels is greater than `maxSelectedLabels`. |
+| `stash` | `boolean \| undefined` |  |  | Adds a stash to accumulate selected values across searches. |
+| `transitionDuration` | `number \| undefined` |  |  | How long the transition has to last in milliseconds. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-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… |
+
+## Events
+
+- `active` — `(e: "active"): void`
+- `blur` — `(e: "blur", event: FocusEvent): void`
+- `change` — `(e: "change", event: Event): void`
+- `click` — `(e: "click", event: MouseEvent): void`
+- `focus` — `(e: "focus", event: FocusEvent): void`
+- `inactive` — `(e: "inactive"): void`
+- `input` — `(e: "input", event: Event): void`
+- `option:add` — `(e: "option:add", text: string): void`
+- `update:modelValue` — `(e: "update:modelValue", value: any): void`
+
+## Slots
+
+- `append` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content appended inside the input field, after the value area.
+- `append-outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content appended outside the input field wrapper.
+- `footer` — scope: `BbSelectPanelSlotProps` — Content pinned to the bottom of the options panel, below the options list. Rendered in both the desktop popover and the adaptive sheet.
+- `group` — scope: `BbSelectGroupSlotProps<T>` — Replaces the default group header rendered above grouped options.
+- `header` — scope: `BbSelectPanelSlotProps` — Content pinned to the top of the options panel, above the search field. Rendered in both the desktop popover and the adaptive sheet.
+- `label` — scope: `BbSelectLabelSlotProps` — Replaces the default label text rendered above the input.
+- `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: `BbSelectOptionSlotProps<T>` — Replaces the default rendering of each option row in the dropdown.
+- `prefix` — scope: `object` — Content rendered as an inline prefix inside the input field.
+- `prepend` — scope: `{ query: string; focus: () => void; close: () => Promise<void>; }` — Content prepended inside the input field, before the value area.
+- `prepend-outer` — scope: `{ query: string; close: () => Promise<void>; }` — Content prepended outside the input field wrapper.
+- `suffix` — scope: `object` — Content rendered as an inline suffix inside the input field.
+
+## Validated variant
+
+Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
+| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+
+## See Also
+
+- [BbSelectPopover](./BbSelectPopover.md) — Provides popover-driven option selection and search.
+- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
+- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.