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

package/dist/ai/source/BbSmoothHeight.md

@@ -18,10 +18,11 @@
 		:style="{
 			'--transition-duration': `${props.transitionDuration}ms`,
 		}"
+		v-bind="passthrough.rootAttrs"
 	>
 		<!-- The inner measuring element mirrors `tag`, so the pair is always
 		div-in-div or span-in-span — both valid. `.bb-smooth-height__content`
-		forces `display: block`, so a span measures the same as a div. This is
+		forces `display: flow-root`, so a span measures the same as a div. This is
 		why `tag` is limited to those two: any element with a restricted content
 		model would nest invalidly inside itself. -->
 		<component :is="props.tag" ref="content" class="bb-smooth-height__content">
@@ -32,10 +33,16 @@
 
 <script setup lang="ts">
 import { transitions } from '@/utilities/misc/transitions';
-import type { BbSmoothHeightProps, BbSmoothHeightSlots } from './types';
+import {
+	BB_SMOOTH_HEIGHT_PT,
+	type BbSmoothHeightProps,
+	type BbSmoothHeightSlots,
+} from './types';
+import { usePassthrough } from '@/composables/usePassthrough';
 export type { BbSmoothHeightProps, BbSmoothHeightSlots };
-import { ref, onMounted, onBeforeUnmount, watch } from 'vue';
+import { onBeforeUnmount, onMounted, ref, useAttrs, watch } from 'vue';
 
+defineOptions({ inheritAttrs: false });
 const props = withDefaults(defineProps<BbSmoothHeightProps>(), {
 	transitionDuration: transitions.medium,
 	disabled: false,
@@ -46,6 +53,18 @@ const props = withDefaults(defineProps<BbSmoothHeightProps>(), {
 
 defineSlots<BbSmoothHeightSlots>();
 
+/**
+ * Passthrough (plans/passthrough/BbSmoothHeight.md). `root` only — the component is one element and everything it paints is configuration, not state.
+ */
+const passthrough = usePassthrough({
+	component: 'BbSmoothHeight',
+	attrs: useAttrs(),
+	props,
+	parts: BB_SMOOTH_HEIGHT_PT.parts,
+	states: BB_SMOOTH_HEIGHT_PT.states,
+	active: {},
+});
+
 const container = ref<HTMLElement | null>(null);
 const content = ref<HTMLElement | null>(null);
 const observer = ref<ResizeObserver | MutationObserver | null>(null);
@@ -187,8 +206,35 @@ onBeforeUnmount(() => {
 
 ```ts
 import type { LayoutElementTag } from '@/types/CommonProps';
+import type { PtMap, PtValue } from '@/types/passthrough';
+
+/**
+ * Passthrough parts of `BbSmoothHeight` (plans/passthrough/BbSmoothHeight.md). `root` is the animating box. Nothing it paints is a state.
+ *
+ * @part root - The box whose height animates.
+ */
+export type BbSmoothHeightPtPart = 'root';
+/** The runtime lists the resolver is wired with — no states: nothing this component paints is a state. */
+export const BB_SMOOTH_HEIGHT_PT = {
+	parts: ['root'],
+	states: [],
+} as const satisfies {
+	parts: readonly BbSmoothHeightPtPart[];
+	states: readonly never[];
+};
 
+// Spelled INLINE with this component's own union (Vue's SFC type resolver
+// does not substitute a generic alias's type parameters — PASSTHROUGH.md T20).
+// No state axis: a `never` state does not resolve to finite keys.
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export type BbSmoothHeightProps = {
+	[K in `pt:${BbSmoothHeightPtPart}`]?: PtValue;
+} & {
+	/**
+	 * Passthrough, object form: the same keys as the `pt:*` attributes
+	 * without the prefix. See the `pt:<part>` row.
+	 */
+	pt?: PtMap<BbSmoothHeightPtPart, never>;
 	/**
 	 * Disable smooth-height behavior and allow natural content height.
 	 *
@@ -235,6 +281,11 @@ export type BbSmoothHeightSlots = {
 /* @inherit --transition-duration — set inline by the component */
 .bb-smooth-height {
 	display: block;
+	/* The reset's `interpolate-size: allow-keywords` would make the first px
+	height (set at mount, from `auto`) a real transition: every mount animated,
+	and anything measured in that window read a box mid-way (Q61.17). Only
+	px → px changes animate. */
+	interpolate-size: numeric-only;
 	/* Clip only the vertical axis so height can animate without hiding content
 	that legitimately overflows horizontally (shadows, focus rings, tooltips,
 	popovers). `visible` paired with `clip` is the one mix the spec leaves
@@ -252,8 +303,12 @@ export type BbSmoothHeightSlots = {
 		transition: none;
 	}
 
+	/* `flow-root`, not `block`: a new formatting context CONTAINS the slot's
+	vertical margins. As a plain block, a child's margin collapsed through it,
+	`scrollHeight` left the margin out and the clip cut off whatever sat in
+	it (Q56.18). It is still block-level, so a span measures like a div. */
 	&__content {
-		display: block;
+		display: flow-root;
 	}
 }
 

package/dist/ai/source/BbSpinner.md

@@ -7,22 +7,49 @@
 ```vue
 <template>
 	<span v-if="label" role="status">
-		<BbIcon class="bb-spinner" :icon="spinnerSvg" :size="size" />
-		<span class="sr-only">{{ label }}</span>
+		<BbIcon
+			class="bb-spinner"
+			:icon="spinnerSvg"
+			:size="size"
+			v-bind="passthrough.rootAttrs"
+		/>
+		<span class="bb-sr-only">{{ label }}</span>
 	</span>
-	<BbIcon v-else class="bb-spinner" :icon="spinnerSvg" :size="size" />
+	<BbIcon
+		v-else
+		class="bb-spinner"
+		:icon="spinnerSvg"
+		:size="size"
+		v-bind="passthrough.rootAttrs"
+	/>
 </template>
 
 <script setup lang="ts">
 import spinnerSvg from '@/assets/svgs/spinner.svg?raw';
 import { removedPropsFor } from '@/deprecation/removedProps';
 import { warnRemovedAttrs } from '@/utilities/functions/warnRemovedAttrs';
-import type { BbSpinnerProps } from './types';
+import { BB_SPINNER_PT, type BbSpinnerProps } from './types';
+import { usePassthrough } from '@/composables/usePassthrough';
 import BbIcon from '../BbIcon/BbIcon.vue';
+import { useAttrs } from 'vue';
 
-withDefaults(defineProps<BbSpinnerProps>(), {
+defineOptions({ inheritAttrs: false });
+const props = withDefaults(defineProps<BbSpinnerProps>(), {
 	size: 'md',
 });
+/**
+ * Passthrough (plans/passthrough/BbSpinner.md). `root` is the glyph in both
+ * branches, and so is everything bound on the component — a `class` included —
+ * so a labelled spinner styles the same node as a bare one.
+ */
+const passthrough = usePassthrough({
+	component: 'BbSpinner',
+	attrs: useAttrs(),
+	props,
+	parts: BB_SPINNER_PT.parts,
+	states: BB_SPINNER_PT.states,
+	active: {},
+});
 
 if (process.env.NODE_ENV !== 'production')
 	warnRemovedAttrs('BbSpinner', removedPropsFor('BbSpinner'));
@@ -37,6 +64,7 @@ if (process.env.NODE_ENV !== 'production')
 
 ```ts
 import type { BbIconProps, BbIconSize as IconSize } from '../BbIcon/types';
+import type { PtMap, PtValue } from '@/types/passthrough';
 
 /**
  * Maps size key strings to pixel dimensions. Re-exported for consumers that
@@ -44,10 +72,38 @@ import type { BbIconProps, BbIconSize as IconSize } from '../BbIcon/types';
  */
 export type Size = IconSize;
 
+/**
+ * Passthrough parts of `BbSpinner` (plans/passthrough/BbSpinner.md). Nothing it
+ * paints is a state.
+ *
+ * @part root - The spinning glyph. With a `label`, the status wrapper around
+ *   it is not a part.
+ */
+export type BbSpinnerPtPart = 'root';
+/** The runtime lists the resolver is wired with — no states: nothing this component paints is a state. */
+export const BB_SPINNER_PT = {
+	parts: ['root'],
+	states: [],
+} as const satisfies {
+	parts: readonly BbSpinnerPtPart[];
+	states: readonly never[];
+};
+
+// Spelled INLINE with this component's own union (Vue's SFC type resolver
+// does not substitute a generic alias's type parameters — PASSTHROUGH.md T20).
+// No state axis: a `never` state does not resolve to finite keys.
+// eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style
 export type BbSpinnerProps = Pick<BbIconProps, 'size'> & {
+	[K in `pt:${BbSpinnerPtPart}`]?: PtValue;
+} & {
+	/**
+	 * Passthrough, object form: the same keys as the `pt:*` attributes
+	 * without the prefix. See the `pt:<part>` row.
+	 */
+	pt?: PtMap<BbSpinnerPtPart, never>;
 	/**
 	 * Accessible loading announcement. When set, the spinner is wrapped in a
-	 * `role="status"` element containing this text rendered `sr-only`, so
+	 * `role="status"` element containing this text rendered `bb-sr-only`, so
 	 * screen readers announce the loading state. When omitted the markup is
 	 * unchanged and the spinner is purely decorative.
 	 */

package/dist/ai/source/BbSwitch.md

@@ -6,97 +6,315 @@
 
 ```vue
 <template>
-	<BaseInputContainer
+	<CommonField
 		:id="id"
 		class="bb-switch"
+		:compact="compact"
 		:description="description"
-		:direction="direction"
-		:errors="errors"
+		:disabled="disabled"
+		:errors="fieldErrors"
 		:has-errors="hasErrors"
-		:has-warning="hasWarning"
+		:has-warnings="hasWarnings"
 		:hide-label="hideLabel"
 		:hint="hint"
+		:input-align="inputAlign"
 		:input-position="inputPosition"
 		:label="label"
+		:label-align="labelAlign"
 		:label-position="labelPosition"
 		label-tag="span"
+		:layout="layout"
 		:name="name"
+		:passthrough="passthrough"
+		:readonly="fieldReadonly"
 		:reverse="reverse"
+		:show-asterisk="showAsterisk"
 		:show-hint="showHint"
 		tag="label"
 		:warnings="warnings"
+		v-bind="passthrough.forwardAttrs"
 	>
 		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, hasWarning, ariaDescribedby }">
-			<BaseSwitch
-				:id="id"
-				:aria-describedby="ariaDescribedby"
-				:autofocus="autofocus"
-				:checked="checked"
-				:disabled="disabled"
-				:false-value="falseValue"
-				:has-errors="hasErrors"
-				:has-warning="hasWarning"
-				:indeterminate="indeterminate"
-				:model-value="modelValue"
-				:name="name"
-				:readonly="readonly"
-				:required="required"
-				:submit-when-false="submitWhenFalse"
-				:true-value="trueValue"
-				v-bind="eventListeners"
+		<template v-if="$slots.description" #description="data"
+			><slot name="description" v-bind="data"></slot
+		></template>
+		<template
+			#input="{
+				id: fieldId,
+				hasErrors: fieldHasErrors,
+				hasWarnings: fieldHasWarnings,
+				ariaDescribedby,
+				ariaLabelledby,
+			}"
+		>
+			<input
+				v-if="!paintedChecked && submitWhenFalse && !arrayModel"
+				v-bind="
+					hiddenSubmitAttrs({ disabled, falseValue: resolvedFalseValue, name })
+				"
+			/>
+			<input
+				ref="switchInput"
+				v-bind="inputAttrs(fieldId, ariaDescribedby, ariaLabelledby)"
+			/>
+			<slot
+				name="icon"
+				v-bind="iconSlotProps(fieldId, fieldHasErrors, fieldHasWarnings)"
+				:text="label"
 			>
-				<template #icon="data"
-					><slot name="icon" v-bind="data" :text="label"
-				/></template>
-			</BaseSwitch>
+				<!-- eslint-disable vue/attributes-order -- `pt:icon` binds LAST (PASSTHROUGH.md T17) -->
+				<BbBaseSwitchIcon
+					:checked="paintedChecked"
+					:disabled="!!disabled"
+					:focus-visible="focusVisible"
+					:focused="focused"
+					:has-errors="!!fieldHasErrors"
+					:has-warnings="!!fieldHasWarnings && !fieldHasErrors"
+					:indeterminate="!!indeterminate"
+					:readonly="!!fieldReadonly"
+					v-bind="passthrough.icon"
+				/>
+				<!-- eslint-enable vue/attributes-order -->
+			</slot>
 		</template>
-	</BaseInputContainer>
+	</CommonField>
 </template>
 
 <script setup lang="ts">
-import BaseInputContainer from '../BbBaseInputContainer/BbBaseInputContainer.vue';
-import BaseSwitch from '../BbBaseSwitch/BbBaseSwitch.vue';
-import { computed, ref } from 'vue';
-import type { BbSwitchProps, BbSwitchEvents, BbSwitchSlots } from './types';
+import CommonField from '../CommonField/CommonField.vue';
+import BbBaseSwitchIcon from '../BbBaseSwitchIcon/BbBaseSwitchIcon.vue';
+import {
+	formControlPtActive,
+	pickActive,
+	usePassthrough,
+} from '@/composables/usePassthrough';
+import {
+	usePaintedChecked,
+	useToggleFocus,
+} from '@/composables/useToggleInput';
+import { isEqual } from '@/utilities/functions/isEqual';
+import {
+	hiddenSubmitAttrs,
+	preventReadonlyClick,
+	preventReadonlyKeydown,
+	revertReadonlyChange,
+	syncCheckedToData,
+	syncIndeterminate,
+	toggleInputAttrs,
+	toggleInputValue,
+	isMembershipModel,
+	toggleModelChecked,
+	nextToggleModel,
+} from '@/utilities/functions/toggleInput';
+import { computed, ref, useAttrs } from 'vue';
+import {
+	BB_SWITCH_PT,
+	type BbSwitchIconSlotProps,
+	type BbSwitchProps,
+	type BbSwitchEvents,
+	type BbSwitchSlots,
+} from './types';
+import { useFormBinding } from '@/composables/useFormBinding';
 export type { BbSwitchProps, BbSwitchEvents, BbSwitchSlots };
 
-const props = withDefaults(defineProps<BbSwitchProps>(), {
+defineOptions({ inheritAttrs: false });
+const declaredProps = withDefaults(defineProps<BbSwitchProps>(), {
 	// booleanish `checked` — default: undefined so an unset prop isn't coerced to
-	// `false` and forwarded down; lets BaseSwitch derive it from `modelValue`.
+	// `false`; the checked state then derives from `modelValue`.
 	checked: undefined,
-	direction: 'auto',
+	layout: 'auto',
 	// Control-first: always left-align, like BbCheckbox/BbRadio (never right, even
 	// in a horizontal layout).
 	inputPosition: 'left',
 });
 
-const emit = defineEmits<BbSwitchEvents>();
-
+const declaredEmit = defineEmits<BbSwitchEvents>();
 defineSlots<BbSwitchSlots>();
+// Inside a BbForm the field joins it (Q54.4): `props` / `emit` are bound.
+const {
+	props,
+	emit,
+	showAsterisk,
+	errors: fieldErrors,
+	ariaRequired: fieldAriaRequired,
+	readonly: fieldReadonly,
+} = useFormBinding(declaredProps, declaredEmit, {
+	componentName: 'BbSwitch',
+	identifierFallback: () => declaredProps.label,
+	leaveOn: 'blur',
+	commits: true,
+});
+/**
+ * `trueValue` / `falseValue` default to `true` / `false`, applied where they
+ * are read rather than in `withDefaults`: a literal `true` default there would
+ * make the `true-value` attribute shorthand a silent no-op (check-api's
+ * boolean-default-true rule). `=== undefined` is exactly when Vue would have
+ * applied a default.
+ */
+const resolvedTrueValue = computed(() =>
+	props.trueValue === undefined ? true : props.trueValue
+);
+const resolvedFalseValue = computed(() =>
+	props.falseValue === undefined ? false : props.falseValue
+);
 
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
+const switchInput = ref<HTMLInputElement | null>(null);
+
+/** The native input's focus, and whether it is keyboard-visible — the glyph draws its ring from these. */
+const { focused, focusVisible, onFocus, onBlur } = useToggleFocus();
+const showHint = computed(() => props.persistentHint || focused.value);
 // We use the negative to avoid the awkward syntax of :reverse="false" from outside
 const reverse = computed(() => !props.reverse);
 
-const eventListeners = {
+/**
+ * The checked state the control PAINTS. Controlled (a `modelValue` or
+ * `checked` is passed), it is exactly what the data says: a click emits the
+ * change and the control moves only when the parent applies it. Uncontrolled
+ * (neither is passed — a plain form field), the control keeps the click
+ * itself, as a native input does.
+ */
+const toggleValues = computed(() => ({
+	trueValue: resolvedTrueValue.value,
+	falseValue: resolvedFalseValue.value,
+}));
+/** An array model with scalar values: one member of a list, like Vue's native checkbox (Q56.28). */
+const arrayModel = computed(() =>
+	isMembershipModel(props.modelValue, toggleValues.value)
+);
+
+const controlled = computed(
+	() => props.checked !== undefined || props.modelValue !== undefined
+);
+const paintedChecked = usePaintedChecked(
+	() =>
+		props.checked !== undefined
+			? props.checked
+			: toggleModelChecked(props.modelValue, toggleValues.value, isEqual),
+	{ indeterminate: () => props.indeterminate, input: switchInput }
+);
+
+/**
+ * Passthrough (plans/passthrough/BbSwitch.md). Resolved here, where the states
+ * are known, and handed DOWN as bindings to the container and the glyph.
+ * `checked` is the checked state the switch paints; `focused` is the native
+ * input's focus (any focus — T19).
+ */
+const passthrough = usePassthrough({
+	component: 'BbSwitch',
+	attrs: useAttrs(),
+	props,
+	parts: BB_SWITCH_PT.parts,
+	states: BB_SWITCH_PT.states,
+	active: {
+		...pickActive(formControlPtActive(props), [
+			'errors',
+			'warnings',
+			'disabled',
+			'readonly',
+		]),
+		checked: () => paintedChecked.value,
+		focused: () => focused.value,
+		focusVisible: () => focusVisible.value,
+		indeterminate: () => !!props.indeterminate,
+	},
+});
+
+const inputListeners = {
 	onBlur: (event: FocusEvent) => {
-		active.value = false;
+		onBlur();
 		emit('blur', event);
 	},
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', event),
+	onChange: (event: Event) => {
+		if (!(event.target instanceof HTMLInputElement)) return;
+		if (
+			revertReadonlyChange(event.target, props.readonly, paintedChecked.value)
+		) {
+			syncIndeterminate(switchInput.value, props.indeterminate);
+			return;
+		}
+		if (!controlled.value) paintedChecked.value = event.target.checked;
+		syncIndeterminate(switchInput.value, props.indeterminate);
+		emit('change', event);
+		emit(
+			'update:modelValue',
+			nextToggleModel(
+				props.modelValue,
+				event.target.checked,
+				toggleValues.value,
+				isEqual
+			)
+		);
+		if (controlled.value) {
+			syncCheckedToData(
+				() => switchInput.value,
+				() => paintedChecked.value,
+				() => props.indeterminate
+			);
+		}
+	},
 	onFocus: (event: FocusEvent) => {
-		active.value = true;
+		onFocus(event);
 		emit('focus', event);
 	},
+	onClick: (event: MouseEvent) => {
+		preventReadonlyClick(event, props.readonly);
+		emit('click', event);
+	},
 	onInput: (event: Event) => emit('input', event),
-	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
+	onKeydown: (event: KeyboardEvent) => {
+		preventReadonlyKeydown(event, props.readonly);
+		emit('keydown', event);
+	},
 	onMousedown: (event: MouseEvent) => emit('mousedown', event),
 	onMouseup: (event: MouseEvent) => emit('mouseup', event),
-	'onUpdate:modelValue': (value: any) => emit('update:modelValue', value),
 };
+
+/** The native input: the frame's resolved id and ARIA wiring, our state, our listeners. */
+const inputAttrs = (
+	fieldId: string,
+	ariaDescribedby: string | undefined,
+	ariaLabelledby: string | undefined
+) => ({
+	...toggleInputAttrs('switch', {
+		ariaDescribedby,
+		ariaLabelledby,
+		autofocus: props.autofocus,
+		checked: paintedChecked.value,
+		disabled: props.disabled,
+		id: fieldId,
+		indeterminate: props.indeterminate,
+		name: props.name,
+		readonly: props.readonly,
+		required: props.required,
+		ariaRequired: fieldAriaRequired.value,
+		value: resolvedTrueValue.value,
+	}),
+	...inputListeners,
+});
+
+/** The `icon` slot payload (the label text is added in the template). */
+const iconSlotProps = (
+	fieldId: string,
+	fieldHasErrors: boolean,
+	fieldHasWarnings: boolean
+): Omit<BbSwitchIconSlotProps, 'text'> => ({
+	checked: paintedChecked.value,
+	disabled: !!props.disabled,
+	falseValue: resolvedFalseValue.value,
+	focused: focused.value,
+	focusVisible: focusVisible.value,
+	hasErrors: !!fieldHasErrors,
+	hasWarnings: Boolean(fieldHasWarnings) && !fieldHasErrors,
+	id: fieldId,
+	indeterminate: props.indeterminate,
+	name: props.name,
+	parsedValue: toggleInputValue('switch', resolvedTrueValue.value),
+	readonly: !!props.readonly,
+	trueValue: resolvedTrueValue.value,
+	value: paintedChecked.value
+		? resolvedTrueValue.value
+		: resolvedFalseValue.value,
+});
 </script>
 
 <style lang="postcss">
@@ -107,8 +325,15 @@ const eventListeners = {
 ## Types
 
 ```ts
-import type { BaseCheckboxIconSlotProps } from '../BbBaseCheckbox/types';
-import type { BbCheckboxEvents, BbCheckboxProps } from '../BbCheckbox/types';
+import {
+	BB_CHECKBOX_PT,
+	type BbCheckboxEvents,
+	type BbCheckboxIconSlotProps,
+	type BbCheckboxProps,
+} from '../BbCheckbox/types';
+
+/** `BbSwitch` shares `BbCheckbox`'s passthrough vocabulary (its props are the same type). */
+export const BB_SWITCH_PT = BB_CHECKBOX_PT;
 
 /** Re-export of BbCheckboxProps for the switch variant. */
 export type BbSwitchProps = BbCheckboxProps;
@@ -116,6 +341,16 @@ export type BbSwitchProps = BbCheckboxProps;
 /** Re-export for consumers importing events type from BbSwitch. */
 export type BbSwitchEvents = BbCheckboxEvents;
 
+/** Props exposed by the `description` slot. */
+export type BbSwitchDescriptionSlotProps = {
+	/** The `description` prop value (empty when only the slot is provided). */
+	text: string;
+	/** Whether the field is in an error state. */
+	hasErrors: boolean;
+	/** Whether the field is in a warning state (suppressed when errors win). */
+	hasWarnings: boolean;
+};
+
 /** Props exposed by the `label` slot. */
 export type BbSwitchLabelSlotProps = {
 	/** The `label` prop value. */
@@ -123,14 +358,11 @@ export type BbSwitchLabelSlotProps = {
 	/** Whether the switch is in an error state. */
 	hasErrors: boolean;
 	/** Whether the switch is in a warning state (suppressed when errors). */
-	hasWarning: boolean;
+	hasWarnings: boolean;
 };
 
-/** Props exposed by the `icon` slot. Extends BaseSwitch icon slot with the label text. */
-export type BbSwitchIconSlotProps = BaseCheckboxIconSlotProps & {
-	/** The `label` prop value. */
-	text: string;
-};
+/** Props exposed by the `icon` slot: the switch state plus the label text (the same payload as BbCheckbox's). */
+export type BbSwitchIconSlotProps = BbCheckboxIconSlotProps;
 
 export type BbSwitchSlots = {
 	/**
@@ -138,8 +370,13 @@ export type BbSwitchSlots = {
 	 */
 	label?: (props: BbSwitchLabelSlotProps) => any;
 	/**
-	 * Replaces the default toggle track visual inside the switch. Receives `BaseSwitch` slot
-	 * attributes plus the label text.
+	 * Replaces the description text. Provided alone (no `description` prop) it still
+	 * renders the description region and wires it into `aria-describedby`.
+	 */
+	description?: (props: BbSwitchDescriptionSlotProps) => any;
+	/**
+	 * Replaces the default toggle track visual inside the switch. Receives the
+	 * switch state plus the label text.
 	 */
 	icon?: (props: BbSwitchIconSlotProps) => any;
 };
@@ -149,7 +386,15 @@ export type BbSwitchSlots = {
 
 ```css
 .bb-switch {
-	.bb-base-input-container__layout {
+	/* `grid-auto-flow: column` keeps a multi-node `icon` slot in ONE row (the
+	   glyph and a badge beside it sit side by side, not stacked). The column
+	   stays a grid because `justify-items` is the only `input-position` lever
+	   (see the described-row note below, Q20.2). */
+	.bb-field__input-wrapper {
+		grid-auto-flow: column;
+	}
+
+	.bb-field__layout {
 		cursor: pointer;
 
 		&--horizontal {
@@ -160,13 +405,30 @@ export type BbSwitchSlots = {
 
 	/* With a description the label block spans two lines: align the switch with
 	   the first line (the label text) instead of centering on the block. */
-	&.bb-base-input-container--description {
-		.bb-base-input-container__layout--horizontal {
+	&.bb-field--description {
+		/* Only while neither `labelAlign` nor `inputAlign` is set (Q56.45):
+		   either prop aims the columns itself, and the pin would hold the
+		   control on the first line against it. */
+		.bb-field__layout--horizontal:not(.bb-field__layout--aligned) {
 			align-items: flex-start;
 
-			.bb-base-input-container__control {
+			/*
+			 * `align-items` + `min-height` are what pin the control to the
+			 * LABEL'S FIRST LINE instead of the block centre — measured: with a
+			 * 4-line label the control's mid sits exactly on the first line's
+			 * mid, and 28px above the block centre.
+			 *
+			 * There used to be a `display: inline-flex` here too, and it was
+			 * doing none of that vertical work — but it silently killed
+			 * `input-position`, whose only lever is `justify-items` (a grid
+			 * property, inert on a flex container). So a described row with
+			 * `input-position="right"` painted its control at the START of the
+			 * column: 166px out on a 198px column (Q20.2). Removing the one
+			 * declaration restores left/center/right and leaves the vertical
+			 * geometry byte-identical.
+			 */
+			.bb-field__input-wrapper {
 				align-items: center;
-				display: inline-flex;
 				min-height: var(--bb-label-lh);
 			}
 		}