bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.64

package/dist/ai/source/BbSelect.md

@@ -214,10 +214,10 @@
 												<slot
 													:deselect="() => onChipUnselected(item)"
 													:disabled="!canDeselectChips"
-													:item="item.item"
 													name="chip"
 													:text="item.text"
 													:value="item.value"
+													v-bind="slotRow(item.item)"
 												>
 													<BbBadge
 														class="bb-select__badge"
@@ -322,7 +322,11 @@
 	</CommonField>
 </template>
 
-<script setup lang="ts" generic="T = any">
+<script
+	setup
+	lang="ts"
+	generic="T = any, Known extends BbSelectKnownItems | undefined = undefined"
+>
 import { vAutofocus } from '@/utilities/misc/autofocus';
 import {
 	computed,
@@ -341,7 +345,9 @@ import BbBadge from '../BbBadge/BbBadge.vue';
 import BbSelectPopover from '../BbSelectPopover/BbSelectPopover.vue';
 import {
 	BB_SELECT_POPOVER_PT,
+	type BbSelectKnownItems,
 	type BbSelectResolvedOption,
+	type BbSelectSlotRow,
 } from '../BbSelectPopover/types';
 import { useMobile } from '@/composables/useMobile';
 import { useConfig } from '@/composables/useConfig';
@@ -351,6 +357,7 @@ import {
 	formControlPtActive,
 	SELECT_CONTROL_NATIVE_ATTRS,
 	usePassthrough,
+	variantPt,
 } from '@/composables/usePassthrough';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
@@ -375,8 +382,12 @@ import {
 	type BbSelectSlots,
 } from './types';
 
-defineOptions({ inheritAttrs: false });
-const declaredProps = withDefaults(defineProps<BbSelectProps<T>>(), {
+defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_SELECT_PT)],
+	inheritAttrs: false,
+});
+const declaredProps = withDefaults(defineProps<BbSelectProps<T, Known>>(), {
 	// `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
@@ -403,7 +414,7 @@ const declaredProps = withDefaults(defineProps<BbSelectProps<T>>(), {
 
 const declaredEmit = defineEmits<BbSelectEvents>();
 
-defineSlots<BbSelectSlots<T>>();
+defineSlots<BbSelectSlots<T, Known>>();
 // Inside a BbForm the field joins it (Q54.4): `props` / `emit` are bound.
 const {
 	props,
@@ -461,6 +472,11 @@ const passthrough = usePassthrough({
 		...formControlPtActive(props, () => hasValue.value),
 		open: () => open.value,
 	},
+	variant: {
+		...BB_SELECT_PT.variant,
+		// CommonFieldInput's default.
+		current: () => props.variant ?? 'outline',
+	},
 });
 
 /**
@@ -541,6 +557,17 @@ const knownItemsSource: KnownItemsSource = {
 	rows: () => props.knownItems,
 	prefill: () => props.prefill,
 };
+/**
+ * The `item` / `known` pair a chip slot gets (Q77.7); the popover reports
+ * which rows are known. Typed by whether this select binds `known-items`
+ * (`Known`), which runtime cannot see, so the one cast lives here.
+ */
+const slotRow = (item: T) =>
+	({
+		known: !!knownItemsSource.isKnown?.(item),
+		item,
+	}) as BbSelectSlotRow<T, Known>;
+
 const knownCoversModel = computed(() =>
 	knownRowsCover(
 		indexKnownRows(props.knownItems),
@@ -785,7 +812,12 @@ const popoverListeners = () =>
 ```ts
 import type { Responsive } from '@/types/ResponsiveSize';
 import type { BbSelectItemProps } from '@/types/ItemProps';
-import type { InputVariantType } from '@/types/InputVariant';
+import {
+	INPUT_VARIANTS,
+	type InputVariantBuiltIn,
+	type InputVariantRegistry,
+	type InputVariantType,
+} from '@/types/InputVariant';
 import type {
 	PtNoInfer,
 	FormControlPtState,
@@ -793,6 +825,7 @@ import type {
 	PtItemMap,
 	PtItemResult,
 	PtValue,
+	PtVariantAttrs,
 } from '@/types/passthrough';
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
 import type { FieldCrossAlign, FieldLayout } from '@/types/FieldLayout';
@@ -800,8 +833,9 @@ import type { ItemAccessor } from '@/types/ItemAccessor';
 import type { BbSelectItemsContext } from '@/types/ItemsProvider';
 import type { IconType } from '@/types/Icon';
 import type {
-	BbSelectKnownItem,
+	BbSelectKnownItems,
 	BbSelectResolvedOption,
+	BbSelectSlotRow,
 } from '../BbSelectPopover/types';
 import type { BbOffCanvasProps } from '../BbOffCanvas/types';
 import type { FormFieldProps } from '@/composables/useFormBinding';
@@ -911,6 +945,23 @@ export type BbSelectOptionPtPart =
  */
 export type BbSelectPtState = FormControlPtState | 'open' | 'selected';
 /** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
+/**
+ * The parts the input `variant` styles (Q76.7): the field, not the options
+ * surface — `input` is the search field there. Spelled flat (T20).
+ */
+export type BbSelectVariantPtPart =
+	| 'root'
+	| 'label'
+	| 'description'
+	| 'message'
+	| 'hint'
+	| 'box'
+	| 'activator'
+	| 'icon'
+	| 'spinner'
+	| 'prefix'
+	| 'suffix'
+	| 'clear';
 export const BB_SELECT_PT = {
 	parts: [
 		// The family's words with `activator` where the text controls say
@@ -951,436 +1002,489 @@ export const BB_SELECT_PT = {
 		'open',
 		'loading',
 	],
+	// The input `variant` is a state on the field's parts (Q76.7), below
+	// the real states; a picker's panel and rows are not the field's.
+	variant: {
+		names: INPUT_VARIANTS,
+		option: 'inputVariants',
+		parts: [
+			'root',
+			'label',
+			'description',
+			'message',
+			'hint',
+			'box',
+			'activator',
+			'icon',
+			'spinner',
+			'prefix',
+			'suffix',
+			'clear',
+		],
+	},
 } as const satisfies {
+	variant: {
+		names: readonly InputVariantBuiltIn[];
+		option: string;
+		parts: readonly BbSelectVariantPtPart[];
+	};
 	parts: readonly BbSelectPtPart[];
 	states: readonly BbSelectPtState[];
 };
 
-export type { BbSelectKnownItem } from '../BbSelectPopover/types';
+export type {
+	BbSelectKnownItem,
+	BbSelectKnownItems,
+	BbSelectSlotRow,
+} from '../BbSelectPopover/types';
 
 // 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> = {
+export type BbSelectProps<
+	T,
+	// The type alone (a wrapper's, a `pt` const's) is the bound case, as
+	// `BbSelectSlotRow<Row>` is: it cannot know where it lands (Q77.7). The
+	// component's own default is `undefined`.
+	Known extends BbSelectKnownItems | undefined = BbSelectKnownItems,
+> = {
 	[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.
-	 *
-	 * When unset, falls back to the global `config.adaptive`.
-	 * @defaultValue `config.adaptive` (`true`)
-	 */
-	adaptive?: boolean;
-
-	/**
-	 * Text between the label and the input. Unlike the hint it is always
-	 * visible; it joins the input's `aria-describedby` after any `errors` /
-	 * `warnings`, before the `hint`.
-	 */
-	description?: string;
-
-	/**
-	 * 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>;
-
-	/**
-	 * Hides the panel's search field: `true` everywhere, `'mobile'` /
-	 * `'desktop'` on that platform only. `'auto'` hides it, per open, for an
-	 * array `items` shorter than the plugin's `autoDisableWritingThreshold`
-	 * (6); never for a provider or with an `option:add` listener.
-	 *
-	 * @defaultValue `'auto'`
-	 */
-	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;
-
-	/**
-	 * Guides to the browser as to the type of information expected in the field.
-	 */
-	autocomplete?: InputHTMLAttributes['autocomplete'];
-
-	/**
-	 * Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.
-	 */
-	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;
-
-	/**
-	 * Compact density: the field uses the `-compact` twins of `--bb-input-h`,
-	 * `--bb-input-py` and `--bb-label-spacing-y`, so a `--bb-input-h` set on
-	 * the component is ignored while it is on. Size a compact field with
-	 * `--bb-input-h-compact` (and `--bb-input-py-compact`).
-	 */
-	compact?: boolean;
-
-	/**
-	 * The field box's look, with `BbButton`'s names and tokens. Colours only,
-	 * so a form never reflows; `'ghost'` has no border in any state, `'none'`
-	 * 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.
-	 */
-	dependencies?: unknown[];
-
-	/**
-	 * Timeout used to debounce response to changes to dependencies.
-	 *
-	 * @defaultValue `0`
-	 */
-	depsDebounceTime?: number;
-
-	/**
-	 * How label and input sit together: `'vertical'`, `'horizontal'` (50/50),
-	 * `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a
-	 * per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`).
-	 */
-	layout?: Responsive<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.
-	 */
-	inputAlign?: FieldCrossAlign;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * 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, `known-items` vouch until a parent change; a search or a
-	 * failed load never prunes.
-	 */
-	enforceCoherence?: boolean;
-
-	/**
-	 * Error messages under the field, a string or array, in an
-	 * `aria-live="polite"` region and first in the control's
-	 * `aria-describedby`, so they are re-read when it regains focus.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * What typing filters on: empty = the display text and description; item
-	 * paths = those fields (`['name', 'email']`); `false` = no filtering.
-	 * Use `false` when the provider matched the query on the server, or its
-	 * email/accent matches show as "No results".
-	 *
-	 * @defaultValue `[]`
-	 */
-	filterBy?: string[] | false;
-
-	/**
-	 * 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;
-
-	/**
-	 * Warning messages under the field, a string or array: amber, in their own
-	 * `aria-live` region and in the control's `aria-describedby` after the
-	 * errors. Non-empty turns on the warning state; errors win when both are
-	 * set.
-	 */
-	warnings?: string | string[];
-
-	/**
-	 * Define if the component should be in a warning state.
-	 * Same chrome as errors with `--bb-warn`; errors take priority.
-	 */
-	hasWarnings?: 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 `id` of the native control; the label's `for` and the description
-	 * and message ids derive from it. Generated when omitted.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * 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[] | ((context: BbSelectItemsContext) => T[] | Promise<T[]>);
-
-	/**
-	 * Height of group headers in the listbox (px). Defaults to 32px (24px
-	 * compact; 36px / 32px on mobile viewports). Only applies when `groupBy`
-	 * is set. An explicit value wins on every viewport.
-	 */
-	headerHeight?: number;
-
-	/**
-	 * Height of the options in the listbox (px). Defaults to 28px (24px
-	 * compact; 44px / 36px on mobile viewports). An explicit value wins on
-	 * every viewport.
-	 *
-	 * @defaultValue `28`
-	 */
-	itemHeight?: number;
-
-	/**
-	 * 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; 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>;
-
-	/**
-	 * `{ value, label }` rows naming the value the app already holds, whatever
-	 * the options' shape: no request until the first open (`prefill: true`
-	 * still loads). Not options; the options' accessors never run on them;
-	 * slots get the row as `item` until the list brings its own.
-	 */
-	knownItems?: Array<BbSelectKnownItem | null | undefined>;
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Label rendering mode.
-	 */
-	labelMode?: 'outside' | 'floating' | 'inside';
-
-	/**
-	 * 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.
-	 * 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;
-
-	/**
-	 * Timeout used to debounce response to changes to modelValue.
-	 *
-	 * @defaultValue `0`
-	 */
-	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.
-	 */
-	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.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * Text shown in the field while nothing is picked (an empty list has
-	 * `emptyText`).
-	 */
-	placeholder?: InputHTMLAttributes['placeholder'];
-
-	/**
-	 * 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'`
-	 */
-	prefill?: boolean | 'interaction';
-
-	/**
-	 * Name of the icon to be added at the start of the input.
-	 */
-
-	'prepend:icon'?: IconType;
-
-	/**
-	 * Sets the input as required.
-	 */
-	required?: boolean;
-
-	/**
-	 * Time to wait when the user stops writing in the input before querying data.
-	 *
-	 * @defaultValue `500`
-	 */
-	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;
-
-	/**
-	 * Defines whether options are selectable.
-	 * Can be a global boolean that affects all options or a function
-	 * that accepts an item and returns a boolean that only affects that item.
-	 * Non-selectable options are rendered disabled.
-	 * @defaultValue `true`
-	 */
-	selectable?: boolean | ((item: T) => boolean);
-
-	/**
-	 * Function that returns a string to be displayed when the number of selected labels
-	 * is greater than `maxSelectedLabels`.
-	 */
-	selectedLabelsFn?: (count: number) => string;
-
-	/**
-	 * 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>;
+		| `pt:${BbSelectPtPart}:${BbSelectPtState}`
+		| `pt:${BbSelectVariantPtPart}:${InputVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	BbSelectVariantPtPart,
+	keyof InputVariantRegistry
+> & {
+		// 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,
+						never,
+						BbSelectSlotRow<PtNoInfer<T>, PtNoInfer<Known>>
+					>
+			  ) => 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.
+		 */
+		/* eslint-disable @typescript-eslint/consistent-indexed-object-style -- mapped, never Record (T23) */
+		pt?: PtItemMap<
+			BbSelectPtPart,
+			BbSelectOptionPtPart,
+			BbSelectPtState,
+			PtNoInfer<T>,
+			never,
+			BbSelectSlotRow<PtNoInfer<T>, PtNoInfer<Known>>
+		> & {
+			[K in `${BbSelectVariantPtPart}:${InputVariantBuiltIn | keyof InputVariantRegistry}`]?: PtValue;
+		};
+		/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
+		/**
+		 * 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`.
+		 * @defaultValue `config.adaptive` (`true`)
+		 */
+		adaptive?: boolean;
+
+		/**
+		 * Text between the label and the input. Unlike the hint it is always
+		 * visible; it joins the input's `aria-describedby` after any `errors` /
+		 * `warnings`, before the `hint`.
+		 */
+		description?: string;
+
+		/**
+		 * 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>;
+
+		/**
+		 * Hides the panel's search field: `true` everywhere, `'mobile'` /
+		 * `'desktop'` on that platform only. `'auto'` hides it, per open, for an
+		 * array `items` shorter than the plugin's `autoDisableWritingThreshold`
+		 * (6); never for a provider or with an `option:add` listener.
+		 *
+		 * @defaultValue `'auto'`
+		 */
+		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;
+
+		/**
+		 * Guides to the browser as to the type of information expected in the field.
+		 */
+		autocomplete?: InputHTMLAttributes['autocomplete'];
+
+		/**
+		 * Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.
+		 */
+		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;
+
+		/**
+		 * Compact density: the field uses the `-compact` twins of `--bb-input-h`,
+		 * `--bb-input-py` and `--bb-label-spacing-y`, so a `--bb-input-h` set on
+		 * the component is ignored while it is on. Size a compact field with
+		 * `--bb-input-h-compact` (and `--bb-input-py-compact`).
+		 */
+		compact?: boolean;
+
+		/**
+		 * The field box's look, with `BbButton`'s names and tokens. Colours only,
+		 * so a form never reflows; `'ghost'` has no border in any state, `'none'`
+		 * 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.
+		 */
+		dependencies?: unknown[];
+
+		/**
+		 * Timeout used to debounce response to changes to dependencies.
+		 *
+		 * @defaultValue `0`
+		 */
+		depsDebounceTime?: number;
+
+		/**
+		 * How label and input sit together: `'vertical'`, `'horizontal'` (50/50),
+		 * `'auto'`, `'label-fill'`, `'input-fill'`, a ratio like `'xx xxxxx'`, or a
+		 * per-breakpoint map (`{ default: 'vertical', md: 'xx xxxxx' }`).
+		 */
+		layout?: Responsive<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.
+		 */
+		inputAlign?: FieldCrossAlign;
+
+		/**
+		 * Disables the component.
+		 */
+		disabled?: boolean;
+
+		/**
+		 * 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, `known-items` vouch until a parent change; a search or a
+		 * failed load never prunes.
+		 */
+		enforceCoherence?: boolean;
+
+		/**
+		 * Error messages under the field, a string or array, in an
+		 * `aria-live="polite"` region and first in the control's
+		 * `aria-describedby`, so they are re-read when it regains focus.
+		 */
+		errors?: string | string[];
+
+		/**
+		 * What typing filters on: empty = the display text and description; item
+		 * paths = those fields (`['name', 'email']`); `false` = no filtering.
+		 * Use `false` when the provider matched the query on the server, or its
+		 * email/accent matches show as "No results".
+		 *
+		 * @defaultValue `[]`
+		 */
+		filterBy?: string[] | false;
+
+		/**
+		 * 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;
+
+		/**
+		 * Warning messages under the field, a string or array: amber, in their own
+		 * `aria-live` region and in the control's `aria-describedby` after the
+		 * errors. Non-empty turns on the warning state; errors win when both are
+		 * set.
+		 */
+		warnings?: string | string[];
+
+		/**
+		 * Define if the component should be in a warning state.
+		 * Same chrome as errors with `--bb-warn`; errors take priority.
+		 */
+		hasWarnings?: 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 `id` of the native control; the label's `for` and the description
+		 * and message ids derive from it. Generated when omitted.
+		 */
+		id?: HTMLAttributes['id'];
+
+		/**
+		 * 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[] | ((context: BbSelectItemsContext) => T[] | Promise<T[]>);
+
+		/**
+		 * Height of group headers in the listbox (px). Defaults to 32px (24px
+		 * compact; 36px / 32px on mobile viewports). Only applies when `groupBy`
+		 * is set. An explicit value wins on every viewport.
+		 */
+		headerHeight?: number;
+
+		/**
+		 * Height of the options in the listbox (px). Defaults to 28px (24px
+		 * compact; 44px / 36px on mobile viewports). An explicit value wins on
+		 * every viewport.
+		 *
+		 * @defaultValue `28`
+		 */
+		itemHeight?: number;
+
+		/**
+		 * 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; 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>;
+
+		/**
+		 * `{ value, label }` rows naming the value the app already holds, whatever
+		 * the options' shape: no request until the first open (`prefill: true`
+		 * still loads). Not options; the options' accessors never run on them;
+		 * slots get the row as `item`, with `known: true`, until the list brings
+		 * its own.
+		 */
+		knownItems?: [Known] extends [undefined] ? BbSelectKnownItems : Known;
+
+		/**
+		 * Text content of the label of the element.
+		 */
+		label: string;
+
+		/**
+		 * Sets the text alignment of the label.
+		 */
+		labelPosition?: 'left' | 'center' | 'right';
+
+		/**
+		 * Label rendering mode.
+		 */
+		labelMode?: 'outside' | 'floating' | 'inside';
+
+		/**
+		 * 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.
+		 * 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;
+
+		/**
+		 * Timeout used to debounce response to changes to modelValue.
+		 *
+		 * @defaultValue `0`
+		 */
+		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.
+		 */
+		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.
+		 */
+		persistentHint?: boolean;
+
+		/**
+		 * Text shown in the field while nothing is picked (an empty list has
+		 * `emptyText`).
+		 */
+		placeholder?: InputHTMLAttributes['placeholder'];
+
+		/**
+		 * 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'`
+		 */
+		prefill?: boolean | 'interaction';
+
+		/**
+		 * Name of the icon to be added at the start of the input.
+		 */
+
+		'prepend:icon'?: IconType;
+
+		/**
+		 * Sets the input as required.
+		 */
+		required?: boolean;
+
+		/**
+		 * Time to wait when the user stops writing in the input before querying data.
+		 *
+		 * @defaultValue `500`
+		 */
+		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;
+
+		/**
+		 * Defines whether options are selectable.
+		 * Can be a global boolean that affects all options or a function
+		 * that accepts an item and returns a boolean that only affects that item.
+		 * Non-selectable options are rendered disabled.
+		 * @defaultValue `true`
+		 */
+		selectable?: boolean | ((item: T) => boolean);
+
+		/**
+		 * Function that returns a string to be displayed when the number of selected labels
+		 * is greater than `maxSelectedLabels`.
+		 */
+		selectedLabelsFn?: (count: number) => string;
+
+		/**
+		 * 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 = {
@@ -1436,7 +1540,10 @@ export type BbSelectLabelSlotProps = CommonFieldAsteriskSlotProps & {
 };
 
 /** Props exposed by the `option` slot. */
-export type BbSelectOptionSlotProps<T> = {
+export type BbSelectOptionSlotProps<
+	T,
+	Known extends BbSelectKnownItems | undefined = undefined,
+> = BbSelectSlotRow<T, Known> & {
 	/** Whether this option is disabled. */
 	disabled: boolean;
 	/** Whether this option currently has keyboard focus. */
@@ -1445,8 +1552,6 @@ export type BbSelectOptionSlotProps<T> = {
 	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. */
@@ -1477,9 +1582,10 @@ export type BbSelectGroupSlotProps<T> = {
  * 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;
+export type BbSelectChipSlotProps<
+	T,
+	Known extends BbSelectKnownItems | undefined = undefined,
+> = BbSelectSlotRow<T, Known> & {
 	/** The item's resolved display text (what the default badge prints). */
 	text: string;
 	/** The item's resolved value — what sits in the v-model. */
@@ -1510,7 +1616,10 @@ export type BbSelectPanelSlotProps = {
 	selectedOptions: BbSelectResolvedOption[];
 };
 
-export type BbSelectSlots<T> = {
+export type BbSelectSlots<
+	T,
+	Known extends BbSelectKnownItems | undefined = undefined,
+> = {
 	/**
 	 * Content pinned to the top of the options panel, above the search field.
 	 * Rendered in both the desktop popover and the adaptive sheet.
@@ -1556,9 +1665,12 @@ export type BbSelectSlots<T> = {
 	 */
 	empty?: (props: { query: string; focus: () => void; error: unknown }) => any;
 	/**
-	 * Replaces the default rendering of each option row in the dropdown.
+	 * Replaces the default rendering of each option row in the dropdown. With
+	 * `known-items` bound, a row the list has not brought yet is the known
+	 * `{ value, label }` row, `known: true`: check `known` before reading an
+	 * option field off `item`.
 	 */
-	option?: (props: BbSelectOptionSlotProps<T>) => any;
+	option?: (props: BbSelectOptionSlotProps<T, Known>) => any;
 	/**
 	 * Replaces the default group header rendered above grouped options.
 	 * Not called for rows with no group (`group-by` gives `null`/`undefined`,
@@ -1567,9 +1679,11 @@ export type BbSelectSlots<T> = {
 	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.
+	 * Not called in `comma` mode, nor for the collapsed "+N" summary. With
+	 * `known-items` bound, `item` is the known `{ value, label }` row
+	 * (`known: true`) until the list brings the real one.
 	 */
-	chip?: (props: BbSelectChipSlotProps<T>) => any;
+	chip?: (props: BbSelectChipSlotProps<T, Known>) => any;
 	/**
 	 * Content rendered as an inline prefix inside the input field.
 	 */