bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/source/BbBaseInputContainer.md

@@ -0,0 +1,1210 @@
+# BbBaseInputContainer — Implementation Source
+
+> Full implementation for deep dives. For everyday usage read the typed contract: [../BbBaseInputContainer.md](../BbBaseInputContainer.md).
+>
+> Safety level: **Reference Only - Internal** — do not use in consumer-facing code unless explicitly requested.
+
+## Template & Script
+
+```vue
+<template>
+	<div
+		class="bb-base-input-container"
+		:class="{
+			'bb-base-input-container--clearable': props.clearable,
+			'bb-base-input-container--description': !!props.description,
+			'bb-base-input-container--disabled': props.disabled,
+			'bb-base-input-container--errors': hasErrors,
+			'bb-base-input-container--warnings': showWarning,
+			'bb-base-input-container--has-value': props.hasValue,
+			'bb-base-input-container--hint': showHint,
+			'bb-base-input-container--loading': props.loading,
+			'bb-base-input-container--mobile': props.mobile,
+			'bb-base-input-container--compact': props.compact,
+			'bb-base-input-container--floating-label': props.labelMode === 'floating',
+			'bb-base-input-container--inside-label': props.labelMode === 'inside',
+			'bb-base-input-container--readonly': props.readonly,
+		}"
+	>
+		<component :is="tag" v-bind="containerAttributes">
+			<component :is="labelTag" v-bind="labelAttributes">
+				<slot
+					name="label"
+					v-bind="{ text: label, hasErrors, hasWarning: showWarning }"
+					>{{ label }}</slot
+				>
+				<span
+					v-if="description && !overlayLabelMode"
+					:id="descriptionId"
+					class="bb-base-input-container__description"
+					>{{ description }}</span
+				>
+			</component>
+			<!-- In floating/inside modes the label is an absolutely positioned chip,
+			     so the description renders as a layout sibling instead of inside it. -->
+			<span
+				v-if="description && overlayLabelMode"
+				:id="descriptionId"
+				class="bb-base-input-container__description"
+				>{{ description }}</span
+			>
+			<span v-bind="inputAttributes">
+				<slot
+					name="input"
+					v-bind="{
+						id,
+						name,
+						hasErrors,
+						hasWarning: showWarning,
+						ariaDescribedby,
+					}"
+				></slot>
+			</span>
+		</component>
+		<Transition name="hint">
+			<span
+				v-show="showHint"
+				:id="hintId"
+				class="bb-base-input-container__hint-wrap"
+			>
+				<span class="bb-base-input-container__hint-text">{{ hint }}</span>
+			</span>
+		</Transition>
+		<Transition name="errors">
+			<!-- Always mounted by design: height is animated via the watcher below,
+			     not by toggling the element in and out of the DOM. -->
+			<!-- eslint-disable-next-line vue/require-toggle-inside-transition -->
+			<div
+				ref="errorsWrap"
+				aria-live="polite"
+				class="bb-base-input-container__errors-wrap"
+			>
+				<!-- The id lives on the CONTENT node, never on the `-wrap`: the wrap is a
+				     `height: 0; overflow: hidden` animation shell, so describing it would
+				     point assistive tech at the animation rather than at the copy. -->
+				<div
+					:id="errorsId"
+					ref="errorsContent"
+					class="bb-base-input-container__errors"
+				>
+					<span
+						v-for="error in computedErrors"
+						:key="error"
+						class="bb-base-input-container__error"
+						>{{ error }}</span
+					>
+				</div>
+			</div>
+		</Transition>
+		<Transition name="errors">
+			<!-- Warning message channel — mirrors the error channel but in amber,
+			     and collapses to zero height while the error state wins. -->
+			<!-- eslint-disable-next-line vue/require-toggle-inside-transition -->
+			<div
+				ref="warningsWrap"
+				aria-live="polite"
+				class="bb-base-input-container__warnings-wrap"
+			>
+				<!-- Same rule as the error channel: id on the content node, not the shell. -->
+				<div
+					:id="warningsId"
+					ref="warningsContent"
+					class="bb-base-input-container__warnings"
+				>
+					<span
+						v-for="warning in displayedWarnings"
+						:key="warning"
+						class="bb-base-input-container__warning"
+						>{{ warning }}</span
+					>
+				</div>
+			</div>
+		</Transition>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref, watch, type Ref } from 'vue';
+import { deburr } from '@/utilities/functions/deburr';
+import { getAsPercentage } from '@/utilities/functions/percentage';
+import { noop } from '@/utilities/functions/noop';
+import { useId } from '@/composables/useId';
+import { useLogger } from '@/composables/useLogger';
+import type { BaseInputContainerProps, BaseInputContainerSlots } from './types';
+
+const props = withDefaults(defineProps<BaseInputContainerProps>(), {
+	direction: 'vertical',
+	// inputPosition is intentionally NOT defaulted here — see resolvedInputPosition:
+	// inputs align left by default and right only when the direction is horizontal.
+	labelPosition: 'left',
+	labelTag: 'label',
+	reverse: false,
+	tag: 'span',
+});
+
+defineSlots<BaseInputContainerSlots>();
+
+const logger = useLogger();
+
+// Always provide an id so that inputs can be focussed by clicking oin the label
+const id = props.id || useId().id.value;
+
+/**
+ * Hint management
+ */
+const hintId = computed(() => (props.hint ? `hint_${id}` : undefined));
+const showHint = computed(() => props.showHint && !!props.hint);
+
+/**
+ * Description management. The description renders below the label (above the
+ * field), is always visible (unlike the hint) and is announced together with
+ * the hint via aria-describedby.
+ */
+const descriptionId = computed(() =>
+	props.description ? `description_${id}` : undefined
+);
+/**
+ * Message-channel ids. These sit on the inner CONTENT nodes
+ * (`__errors` / `__warnings`), not on the `-wrap` animation shells, so that
+ * `aria-describedby` resolves to the actual message text.
+ */
+const errorsId = `errors_${id}`;
+const warningsId = `warnings_${id}`;
+
+/** Label modes where the label overlays the field instead of sitting above it. */
+const overlayLabelMode = computed(
+	() => props.labelMode === 'floating' || props.labelMode === 'inside'
+);
+// Floating/inside labels are embedded in the field, so those modes force a
+// vertical layout. An 'outside' (or unset) label honors `direction`.
+const resolvedDirection = computed<
+	NonNullable<BaseInputContainerProps['direction']>
+>(() => (overlayLabelMode.value ? 'vertical' : props.direction));
+
+// A horizontal split (either the `horizontal` keyword or a two-token ratio like
+// `"1 2"`) sits the label and input side-by-side.
+const isHorizontalDirection = computed(() => {
+	const d = resolvedDirection.value;
+	return d === 'horizontal' || /^[\S]+\s[\S]+$/g.test(d);
+});
+// Inputs align LEFT by default; in a horizontal layout they align RIGHT (next to
+// the left-hand label). An explicit `inputPosition` always wins. Control-first
+// widgets (checkbox/radio/switch/rating) pass `inputPosition: 'left'` to stay left.
+const resolvedInputPosition = computed(
+	() => props.inputPosition ?? (isHorizontalDirection.value ? 'right' : 'left')
+);
+
+// If no name is passed use a normalized version of the label
+const name = computed(() => {
+	if (props.name) return props.name;
+	const noAccents = deburr(props.label);
+	const nospace = noAccents.replace(/\s+/g, '');
+	return nospace.toLowerCase();
+});
+
+const containerAttributes = computed(() => {
+	const initial: Record<string, any> = {
+		class: {
+			'bb-base-input-container__layout': true,
+			'bb-base-input-container__layout--hidden-label': props.reverse,
+			'bb-base-input-container__layout--horizontal':
+				resolvedDirection.value !== 'vertical',
+			'bb-base-input-container__layout--reverse': props.reverse,
+			'bb-base-input-container__layout--vertical':
+				resolvedDirection.value === 'vertical',
+		},
+	};
+	if (props.tag === 'label') initial.for = id;
+	return initial;
+});
+
+const labelAttributes = computed(() => {
+	const initial: Record<string, any> = {
+		class: {
+			'bb-base-input-container__label': true,
+			'bb-base-input-container__label--hidden': props.hideLabel,
+			[`bb-base-input-container__label--${props.labelPosition}`]:
+				props.labelPosition,
+		},
+		id: `${id}__label`,
+		style: {
+			width: widths.value.label,
+		},
+	};
+	if (props.labelTag === 'label') initial.for = id;
+	return initial;
+});
+
+const inputAttributes = computed(() => {
+	const initial: Record<string, any> = {
+		class: {
+			'bb-base-input-container__control': true,
+			[`bb-base-input-container__control--${resolvedInputPosition.value}`]: true,
+		},
+		style: {
+			width: widths.value.input,
+		},
+	};
+	return initial;
+});
+
+const widths = computed(() => {
+	const initial: Record<string, string> = {
+		label: 'auto',
+		input: 'auto',
+	};
+	if (resolvedDirection.value === 'auto') {
+		noop();
+	} else if (resolvedDirection.value === 'vertical') {
+		initial.label = initial.input = 100 + '%';
+	} else if (resolvedDirection.value === 'horizontal') {
+		initial.label = initial.input = 50 + '%';
+	} else if (/^[\S]+\s[\S]+$/g.test(resolvedDirection.value)) {
+		const [firstLength, secondLength] = resolvedDirection.value
+			.split(/\s+/)
+			.map((string) => string.length);
+		const first =
+			getAsPercentage(firstLength, firstLength + secondLength) + '%';
+		const second =
+			getAsPercentage(secondLength, secondLength + firstLength) + '%';
+		if (props.reverse) {
+			initial.label = second;
+			initial.input = first;
+		} else {
+			initial.label = first;
+			initial.input = second;
+		}
+	} else {
+		logger.warn(
+			`Invalid direction: "${resolvedDirection.value}". Expected 'auto', 'vertical', 'horizontal', or a two-token ratio like '1 2'. Falling back to 'auto'.`
+		);
+		// `initial` is already the auto shape (label/input: 'auto'), so falling
+		// through here leaves the layout at the safe default.
+	}
+	return initial;
+});
+
+const computedErrors = computed(() => {
+	return props.errors ? ([] as string[]).concat(props.errors) : [];
+});
+const hasErrors = computed(
+	() => Boolean(computedErrors.value.length) || props.hasErrors
+);
+const computedWarnings = computed(() => {
+	return props.warnings ? ([] as string[]).concat(props.warnings) : [];
+});
+/**
+ * Warning chrome/messages yield to errors when both are requested. A non-empty
+ * `warnings` list implies the warning state, mirroring how `errors` implies the
+ * error state.
+ */
+const showWarning = computed(
+	() =>
+		(Boolean(props.hasWarning) || Boolean(computedWarnings.value.length)) &&
+		!hasErrors.value
+);
+/** Warning messages are suppressed while the field shows the error state. */
+const displayedWarnings = computed(() =>
+	showWarning.value ? computedWarnings.value : []
+);
+
+/**
+ * `aria-describedby` for the inner control, in spoken order:
+ *
+ *   errors → warnings → description → hint
+ *
+ * Assistive tech reads the referenced nodes in the order listed, so the list is
+ * ordered by urgency for the returning user. Someone who tabs back to a field
+ * they already failed needs "must be a valid address" before they need the
+ * standing description or the on-focus hint; the messages that changed state are
+ * what is new information. Warnings sit second for the same reason (and can only
+ * be present when errors are absent — errors suppress them). Description before
+ * hint preserves the pre-existing order between those two.
+ *
+ * A channel is referenced ONLY while it actually has copy:
+ * - errors/warnings: gated on a non-empty message list. `hasErrors` /
+ *   `hasWarning` alone force the *chrome* without producing text, so referencing
+ *   the (empty) node would describe the control with nothing.
+ * - hint: gated on `showHint` — the hint is `v-show`'d (`display: none` when
+ *   hidden), so describing it while hidden would point at an
+ *   a11y-tree-detached node.
+ *
+ * Reactive throughout so it tracks messages, hint and description changes.
+ *
+ * The `-wrap` elements keep their `aria-live="polite"`. describedby (read on
+ * focus) and live (read on mutation) are separate channels and carrying both is
+ * the standard pattern, not a duplicate.
+ */
+const ariaDescribedby = computed(
+	() =>
+		[
+			computedErrors.value.length ? errorsId : undefined,
+			displayedWarnings.value.length ? warningsId : undefined,
+			descriptionId.value,
+			showHint.value ? hintId.value : undefined,
+		]
+			.filter(Boolean)
+			.join(' ') || undefined
+);
+
+/**
+ * Smooth height transition for the message containers
+ */
+const errorsWrap = ref<HTMLElement | null>(null);
+const errorsContent = ref<HTMLElement | null>(null);
+const warningsWrap = ref<HTMLElement | null>(null);
+const warningsContent = ref<HTMLElement | null>(null);
+
+// Re-measure when the message list changes; immediate + post flush matches the
+// previous watchPostEffect timing.
+// Deref INSIDE nextTick: on the immediate run the template refs are still null
+// (component not mounted yet), so we must read them after the DOM flush.
+const animateHeight = (
+	containerRef: Ref<HTMLElement | null>,
+	contentRef: Ref<HTMLElement | null>
+) => {
+	nextTick(() => {
+		const container = containerRef.value;
+		const content = contentRef.value;
+		if (container && content) {
+			const min = Math.min(content.clientHeight, content.scrollHeight);
+			container.style.height = `${min}px`;
+		}
+	});
+};
+
+watch(computedErrors, () => animateHeight(errorsWrap, errorsContent), {
+	immediate: true,
+	flush: 'post',
+});
+watch(displayedWarnings, () => animateHeight(warningsWrap, warningsContent), {
+	immediate: true,
+	flush: 'post',
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
+import type { InputDirection } from '@/types/InputDirection';
+import type { ContainerTag, LabelTag } from '@/types/CommonProps';
+
+/**
+ * Wrapper responsible for aligning labels, inputs, hints, and error messages consistently across form controls.
+ */
+export type BaseInputContainerProps = {
+	/**
+	 * Whether the inner control exposes a clear action.
+	 */
+	clearable?: boolean;
+
+	/**
+	 * Apply the compact density variant to the container.
+	 */
+	compact?: boolean;
+
+	/**
+	 * Always-visible descriptive text rendered below the label and above the input, in muted foreground color.
+	 * When present, its id is exposed to the input slot via `ariaDescribedby`, after any error/warning
+	 * ids and before the hint id.
+	 * In `floating` label mode it renders as a single line above the field and the label floats past it;
+	 * in `inside` label mode it renders as a second single line under the label, growing the field.
+	 */
+	description?: string;
+
+	/**
+	 * Whether the inner control is disabled.
+	 */
+	disabled?: boolean;
+
+	/**
+	 * Controls label/input layout.
+	 * Accepts `'vertical'`, `'horizontal'`, `'auto'`, or a two-token ratio pattern
+	 * such as `"xx xxxxx"` that sizes the label/input columns by token length.
+	 * An unrecognized value warns and falls back to `'auto'`.
+	 * @defaultValue `'vertical'`
+	 */
+	direction?: InputDirection;
+
+	/**
+	 * Messages displayed beneath the input. Accepts a string or array; values are rendered one per line.
+	 * They render in an `aria-live="polite"` region (announced when they appear) and, while the list is
+	 * non-empty, their container id is also exposed to the input slot via `ariaDescribedby` — first in
+	 * the list — so the reason the field is invalid is re-read whenever the control regains focus.
+	 */
+	errors?: string | string[];
+
+	/**
+	 * Forces the error state independently of `errors`, useful to pre-style the container.
+	 */
+	hasErrors?: boolean;
+
+	/**
+	 * Warning messages displayed beneath the input, in their own `aria-live`
+	 * region. Accepts a string or array; values are rendered one per line, in
+	 * `--bb-warn` amber. A non-empty list implies the warning state (mirroring
+	 * how `errors` implies the error state); errors suppress warning messages
+	 * when both are set. While displayed, the container id is also exposed to the
+	 * input slot via `ariaDescribedby` (after any errors, before description/hint).
+	 */
+	warnings?: string | string[];
+
+	/**
+	 * Forces the warning state independently of `warnings`. Same chrome as
+	 * errors but with `--bb-warn`; errors take priority when both are set.
+	 */
+	hasWarning?: boolean;
+
+	/**
+	 * Hide the visual label while keeping it available to assistive technology.
+	 */
+	hideLabel?: boolean;
+
+	/**
+	 * Hint text rendered below the input. While shown, its id is exposed to the input slot via
+	 * `ariaDescribedby` — last in the list, after any error/warning ids and the description id.
+	 */
+	hint?: string;
+
+	/**
+	 * Explicit id for the container and associated input. Falls back to an auto-generated id when omitted.
+	 */
+	id?: HTMLAttributes['id'];
+
+	/**
+	 * Horizontal alignment of the input column when direction is horizontal or custom.
+	 * Unset, it follows the layout: `'right'` in a horizontal/ratio split (beside
+	 * the left-hand label), `'left'` otherwise — and `direction` is `'vertical'`
+	 * by default, so the effective default is `'left'`.
+	 * @defaultValue `'left'`
+	 */
+	inputPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Visible label text for the field. Also used to derive a fallback name.
+	 */
+	label: string;
+
+	/**
+	 * Horizontal alignment for the label column.
+	 * @defaultValue `'left'`
+	 */
+	labelPosition?: 'left' | 'center' | 'right';
+
+	/**
+	 * Label rendering mode.
+	 */
+	labelMode?: 'outside' | 'floating' | 'inside';
+
+	/**
+	 * Whether the inner control currently contains a value.
+	 */
+	hasValue?: boolean;
+
+	/**
+	 * Whether the inner control is in a loading state.
+	 */
+	loading?: boolean;
+
+	/**
+	 * Whether the inner control is in mobile viewport mode.
+	 */
+	mobile?: boolean;
+
+	/**
+	 * Element used for the label: `label` (default), `legend` inside a
+	 * `fieldset` container, or `span` when the text must not steal the click
+	 * because the control already carries its own label.
+	 * @defaultValue `'label'`
+	 */
+	labelTag?: LabelTag;
+
+	/**
+	 * Explicit name attribute forwarded to the input. When omitted, a slug derived from `label` is used.
+	 */
+	name?: InputHTMLAttributes['name'];
+
+	/**
+	 * Swap the label and input columns.
+	 * @defaultValue `false`
+	 */
+	reverse?: boolean;
+
+	/**
+	 * Whether the inner control is readonly.
+	 */
+	readonly?: boolean;
+
+	/**
+	 * Keep the hint permanently visible, regardless of focus.
+	 */
+	showHint?: boolean;
+
+	/**
+	 * Element used for the inner wrapper: `span` (default) to remain inline,
+	 * `div` for a block wrapper, `fieldset` for grouped controls (pair it with
+	 * `labelTag="legend"`), or `label` to make the whole wrapper activate the
+	 * control.
+	 * @defaultValue `'span'`
+	 */
+	tag?: ContainerTag;
+};
+
+/**
+ * Props exposed by the `input` slot.
+ */
+export type BaseInputContainerInputSlotProps = {
+	/**
+	 * The resolved `id` for the input element; matches the `for` attribute on the label.
+	 */
+	id: string;
+	/**
+	 * The resolved `name` for the input, derived from the `label` prop when not set explicitly.
+	 */
+	name: string;
+	/**
+	 * Whether the container is in an error state (from `errors` or `hasErrors` props).
+	 */
+	hasErrors: boolean;
+	/**
+	 * Whether the container is in a warning state (from `warnings` or
+	 * `hasWarning`, suppressed when `hasErrors` is true).
+	 */
+	hasWarning: boolean;
+	/**
+	 * Space-separated ids of every message node that currently has copy, in
+	 * spoken order: errors, warnings, description, hint. Pass as
+	 * `aria-describedby` to the inner input. A channel is listed only while it
+	 * actually has content, so a field with no messages and no description/hint
+	 * yields `undefined`.
+	 */
+	ariaDescribedby: string | undefined;
+};
+
+/**
+ * Props exposed by the `label` slot.
+ */
+export type BaseInputContainerLabelSlotProps = {
+	/**
+	 * The `label` prop value.
+	 */
+	text: string;
+	/**
+	 * Whether the container is in an error state.
+	 */
+	hasErrors: boolean;
+	/**
+	 * Whether the container is in a warning state (suppressed when errors win).
+	 */
+	hasWarning: boolean;
+};
+
+export type BaseInputContainerSlots = {
+	/**
+	 * The form control to render, positioned in the input column. Receives pre-computed
+	 * wiring attributes so the inner input can be correctly associated with the label and hint.
+	 */
+	input?: (props: BaseInputContainerInputSlotProps) => any;
+	/**
+	 * Replaces the default label text. The outer label element and its `for` association are always rendered.
+	 */
+	label?: (props: BaseInputContainerLabelSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-base-input-container {
+	/*
+	 * BaseInputContainer stylesheet
+	 * -------------------------------------------------------------------------
+	 * This file coordinates the entire field wrapper behavior:
+	 * - layout orchestration (vertical/horizontal/reverse/custom-width patterns)
+	 * - label modes (outside/inside/floating)
+	 * - control alignment and width propagation
+	 * - hint + error visual containers and transitions
+	 *
+	 * Label-specific responsibilities:
+	 * - default outside label mode
+	 * - inside label mode
+	 * - floating label mode
+	 *
+	 * Key principle:
+	 * Label positioning is solved with CSS custom-property "offset accumulators".
+	 * Each optional UI piece (prefix, suffix, icons, clear button, etc.) can add
+	 * to left/right offsets. The final offsets drive:
+	 * - label `left` / `translate`
+	 * - label `max-width` clamp
+	 *
+	 * Why this approach:
+	 * - keeps logic in CSS (no runtime measurements)
+	 * - allows mode-specific precedence rules
+	 * - makes stress cases predictable and composable
+	 *
+	 * Important:
+	 * - This stylesheet intentionally consumes state classes emitted at the
+	 *   outermost container level (e.g. `bb-base-input-container--errors`).
+	 * - Inner controls inherit behavior through descendant selectors so we keep
+	 *   behavioral flags centralized.
+	 */
+	display: flex;
+	flex-direction: column;
+
+	/*
+	 * Compact mode
+	 * -----------------------------------------------------------------
+	 * Only remaps spacing/size tokens. Structural behavior remains identical.
+	 */
+	&.bb-base-input-container--compact {
+		/* Swap in the pre-derived compact token (base − 2px). Deriving inline here
+		   would reference this same property on the same element — a CSS custom-
+		   property cycle that resolves to invalid, silently killing the tweak. */
+		--bb-label-spacing-y: var(--bb-label-spacing-y-compact);
+	}
+
+	&.bb-base-input-container--inside-label {
+		/*
+		 * INSIDE LABEL MODE
+		 * -----------------------------------------------------------------
+		 * Product rule:
+		 * - account for left padding + prefix + suffix
+		 * - ignore icons / clearable / loading / error indicators
+		 *   because they render visually below this label row.
+		 */
+		position: relative;
+		--inside-label-offset-l-prefix: 0px;
+		--inside-label-offset-r-suffix: 0px;
+		--inside-label-edge-l: var(--bb-input-px);
+		--inside-label-edge-r: var(--bb-input-px);
+		--inside-label-offset-l: calc(
+			var(--inside-label-edge-l) + var(--inside-label-offset-l-prefix)
+		);
+		--inside-label-offset-r: calc(
+			var(--inside-label-edge-r) + var(--inside-label-offset-r-suffix)
+		);
+
+		&:has(.common-input-wrapper__prefix:not(:empty)) {
+			/* Prefix neutralizes inner edge padding via negative margins. */
+			--inside-label-edge-l: 0px;
+			--inside-label-offset-l-prefix: calc(
+				var(--bb-input-prefix-w) + var(--bb-input-spacing)
+			);
+		}
+		&:has(.common-input-wrapper__suffix:not(:empty)) {
+			/* Suffix follows same edge-cancel pattern on the right side. */
+			--inside-label-edge-r: 0px;
+			--inside-label-offset-r-suffix: calc(
+				var(--bb-input-prefix-w) + var(--bb-input-spacing)
+			);
+		}
+
+		&.bb-checkbox-group,
+		&.bb-radio-group,
+		&.bb-switch-group {
+			/*
+			 * Group controls (checkbox/radio/switch groups) don't have a native
+			 * input box in inside-label mode, so the layout wrapper becomes the
+			 * visual container and anchor for the absolute label.
+			 */
+			.bb-base-input-container__layout {
+				border: var(--bb-border-w) solid var(--bb-border);
+				border-radius: var(--bb-radius);
+				padding: var(--bb-input-px);
+				padding-top: calc(var(--bb-label-fs-sm) + var(--bb-input-px));
+				position: relative;
+			}
+
+			.bb-base-input-container__label {
+				left: var(--bb-input-px);
+				top: 5px;
+			}
+
+			.bb-base-input-container__control {
+				translate: 0 5px;
+			}
+
+			&.bb-base-input-container--errors {
+				.bb-base-input-container__layout {
+					border-color: var(--bb-danger);
+				}
+			}
+
+			&.bb-base-input-container--warnings {
+				.bb-base-input-container__layout {
+					border-color: var(--bb-warn);
+				}
+			}
+		}
+
+		/* Label styles */
+		.bb-base-input-container__label {
+			-webkit-box-orient: vertical;
+			/* Keep inside labels single-line and clipped in crowded layouts. */
+			display: -webkit-box;
+			font-size: var(--bb-label-fs-sm);
+			left: var(--inside-label-offset-l);
+			-webkit-line-clamp: 1;
+			line-height: var(--bb-label-lh-sm);
+			max-width: calc(
+				100% - var(--inside-label-offset-l) - var(--inside-label-offset-r)
+			);
+			overflow: hidden;
+			position: absolute;
+			text-overflow: ellipsis;
+			top: 5px;
+			z-index: 2;
+		}
+	}
+
+	&.bb-base-input-container--floating-label {
+		/*
+		 * FLOATING LABEL MODE
+		 * -----------------------------------------------------------------
+		 * Label rests centered in the input row, offset to avoid the prefix,
+		 * prepend-icon, suffix, and any right-side icon.
+		 * On focus or when a value is present the label rises to the top border.
+		 *
+		 * Accumulator pattern:
+		 *   --fl-edge-l / --fl-over-edge-l  left inner padding (resting vs. over)
+		 *   --fl-edge-r                     right inner padding
+		 *   --fl-prefix / --fl-suffix       prefix/suffix clearances
+		 *   --fl-prepend-icon               prepend-icon clearance (resting only)
+		 *   --fl-icon-r                     right icon-slot clearance (resting only)
+		 *   --fl-h                          input height for vertical centering
+		 *   --fl-nudge                      x nudge for the top-border chip
+		 */
+		--fl-edge-l: var(--bb-input-px);
+		--fl-over-edge-l: var(--bb-input-px);
+		--fl-edge-r: var(--bb-input-px);
+		--fl-prefix: 0px;
+		--fl-prepend-icon: 0px;
+		--fl-suffix: 0px;
+		--fl-icon-r: 0px;
+		--fl-h: var(--bb-input-h);
+		--fl-nudge: 2px;
+
+		--fl-rest-l: calc(
+			var(--fl-edge-l) + var(--fl-prefix) + var(--fl-prepend-icon)
+		);
+		--fl-rest-r: calc(var(--fl-edge-r) + var(--fl-suffix) + var(--fl-icon-r));
+		--fl-over-l: calc(var(--fl-over-edge-l) + var(--fl-prefix));
+		--fl-over-r: calc(var(--fl-edge-r) + var(--fl-suffix));
+
+		/* Prepend icon: the icon has margin-left: -input-px * 0.4, so the icon
+		   starts at input-px * 0.6 from the left edge. Match that for the label
+		   so it aligns with the visible text start regardless of input-px value. */
+		&:has(.common-input-wrapper__prepend-icon) {
+			--fl-edge-l: calc(var(--bb-input-px) * 0.6);
+			--fl-prepend-icon: calc(var(--bb-input-icon) + var(--bb-input-spacing));
+		}
+
+		/* Prefix: cancel the inner padding; prefix carries its own clearance.
+		   Declared after prepend-icon so it wins when both are present. */
+		&:has(.common-input-wrapper__prefix:not(:empty)) {
+			--fl-edge-l: 0px;
+			--fl-over-edge-l: 0px;
+			--fl-prefix: calc(var(--bb-input-prefix-w) + var(--bb-input-spacing));
+		}
+
+		/* Suffix: cancel the right inner padding; suffix carries its own clearance. */
+		&:has(.common-input-wrapper__suffix:not(:empty)) {
+			--fl-edge-r: 0px;
+			--fl-suffix: calc(var(--bb-input-prefix-w) + var(--bb-input-spacing));
+		}
+
+		/* Right icon slot: CommonInputWrapper shows one icon at a time via a
+		   single fixed-width slot — no mutual exclusion needed, just reserve it
+		   when any icon source is active. */
+		&.bb-base-input-container--clearable,
+		&.bb-base-input-container--errors,
+		&.bb-base-input-container--warnings,
+		&.bb-base-input-container--loading,
+		&:has(.common-input-wrapper__icon-spacer:not(:empty)) {
+			--fl-icon-r: calc(var(--bb-input-icon) + var(--bb-input-spacing));
+		}
+
+		/* Compact: override input height so vertical centering uses compact value. */
+		&.bb-base-input-container--compact {
+			--fl-h: var(--bb-input-h-compact);
+		}
+
+		.bb-base-input-container__layout {
+			position: relative;
+
+			.bb-base-input-container__label {
+				background-color: transparent;
+				display: inline-block;
+				/* At rest the label mimics a placeholder: normal label size.
+				   It shrinks to the small size only when it rises to the border. */
+				font-size: var(--bb-label-fs);
+				font-weight: var(--bb-label-weight);
+				left: 0;
+				line-height: 1;
+				max-width: calc(100% - var(--fl-rest-l) - var(--fl-rest-r));
+				opacity: 0.6;
+				overflow: hidden;
+				position: absolute;
+				text-overflow: ellipsis;
+				top: 0;
+				transition:
+					translate var(--bb-transition-medium) var(--bb-ease),
+					font-size var(--bb-transition-medium) var(--bb-ease),
+					opacity var(--bb-transition-medium) var(--bb-ease);
+				translate: calc(var(--fl-rest-l) + var(--fl-nudge))
+					calc(var(--fl-h) / 2 - 50%);
+				white-space: nowrap;
+				width: fit-content !important;
+				z-index: 1;
+			}
+		}
+
+		/* Active: label rises to sit on the top border */
+		.bb-base-input-container__layout:focus-within
+			.bb-base-input-container__label,
+		&.bb-base-input-container--has-value .bb-base-input-container__label {
+			background-color: var(--bb-panel);
+			font-size: var(--bb-label-fs-sm);
+			max-width: calc(100% - var(--fl-over-l) - var(--fl-over-r));
+			opacity: 1;
+			translate: calc(var(--fl-over-l) + var(--fl-nudge)) -50%;
+		}
+	}
+
+	/*
+	 * Fieldset spacing guard
+	 * -----------------------------------------------------------------
+	 * Fieldset behaves differently in some flex contexts. This keeps vertical
+	 * rhythm consistent with other wrapper tags.
+	 */
+	fieldset.bb-base-input-container__layout {
+		> :not(:last-child) {
+			margin-bottom: var(--bb-label-spacing-y);
+		}
+	}
+
+	.bb-base-input-container__layout {
+		/*
+		 * Layout engine
+		 * -----------------------------------------------------------------
+		 * This node controls geometric relationship between label and control.
+		 * Direction and reverse classes are computed in Vue and mapped here.
+		 */
+		column-gap: var(--bb-label-spacing-x);
+		display: flex;
+		margin-bottom: 0;
+		row-gap: var(--bb-label-spacing-y);
+		transition: margin-bottom var(--bb-transition-fast) var(--bb-ease);
+
+		&--vertical {
+			flex-direction: column;
+			&.bb-base-input-container__layout--reverse {
+				& > *:first-child {
+					order: 2;
+				}
+			}
+		}
+		&--horizontal {
+			&.bb-base-input-container__layout--reverse {
+				& > *:first-child {
+					order: 2;
+				}
+			}
+		}
+	}
+
+	&__label {
+		/*
+		 * Label base typography and alignment variants.
+		 * Mode-specific overrides (inside/floating) are applied above.
+		 */
+		color: var(--bb-text);
+		display: inline-block;
+		font-size: var(--bb-label-fs);
+		font-weight: var(--bb-label-weight);
+		line-height: var(--bb-label-lh);
+		transition-duration: 150ms;
+		transition-property: color;
+		transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+
+		&--left {
+			text-align: left;
+		}
+		&--center {
+			text-align: center;
+		}
+		&--right {
+			text-align: right;
+		}
+		&--hidden {
+			border-width: 0 !important;
+			clip: rect(0, 0, 0, 0) !important;
+			height: 1px !important;
+			margin: -1px !important;
+			overflow: hidden !important;
+			padding: 0 !important;
+			position: absolute !important;
+			white-space: nowrap !important;
+			width: 1px !important;
+		}
+	}
+	&__control {
+		/*
+		 * Control column wrapper.
+		 * Width is injected by Vue-computed inline styles based on direction rules.
+		 */
+		display: grid;
+
+		&--left {
+			justify-items: flex-start;
+		}
+		&--center {
+			justify-items: center;
+		}
+		&--right {
+			justify-items: flex-end;
+		}
+	}
+
+	&__description {
+		/*
+		 * Description channel
+		 * -----------------------------------------------------------------
+		 * Always-visible field description rendered inside the label/legend
+		 * element, below the label text and above the field. It resets the
+		 * label typography and shares the muted-foreground treatment of the
+		 * hint, but never animates in/out.
+		 */
+		color: var(--bb-text-muted);
+		display: block;
+		font-size: 14px;
+		font-weight: 400;
+		line-height: 18px;
+		margin-top: 2px;
+		position: relative;
+	}
+
+	/*
+	 * FLOATING LABEL + DESCRIPTION
+	 * -----------------------------------------------------------------
+	 * The description renders as a single in-flow line above the field, and
+	 * the layout reserves one extra label line above it. The label rests
+	 * inside the input (translated down past the reserved line, description
+	 * and row gap) and floats up to the reserved line — the usual float
+	 * distance plus one description line of leading.
+	 */
+	&.bb-base-input-container--floating-label.bb-base-input-container--description {
+		/* Sized for the full label font: above the description the floated
+		   label acts as an outside label and keeps its normal size. */
+		--fl-label-line: calc(var(--bb-label-fs) + 4px);
+		--fl-desc-lh: 18px;
+
+		.bb-base-input-container__layout {
+			padding-top: var(--fl-label-line);
+		}
+
+		.bb-base-input-container__description {
+			line-height: var(--fl-desc-lh);
+			margin-top: 0;
+			overflow: hidden;
+			text-overflow: ellipsis;
+			white-space: nowrap;
+		}
+
+		.bb-base-input-container__layout .bb-base-input-container__label {
+			translate: calc(var(--fl-rest-l) + var(--fl-nudge))
+				calc(
+					var(--fl-label-line) + var(--fl-desc-lh) + var(--bb-label-spacing-y) +
+						var(--fl-h) / 2 - 50%
+				);
+		}
+
+		/* Floated: rises past the description into the reserved top line, where
+		   it reads as an outside label — normal font size, no masking chip
+		   background (free space, not the input border). */
+		.bb-base-input-container__layout:focus-within
+			.bb-base-input-container__label,
+		&.bb-base-input-container--has-value .bb-base-input-container__label {
+			background-color: transparent;
+			font-size: var(--bb-label-fs);
+			/* Left-aligned with the description, like an outside label — not
+			   indented to the border-chip offset. */
+			translate: 0 0;
+		}
+	}
+
+	/*
+	 * INSIDE LABEL + DESCRIPTION
+	 * -----------------------------------------------------------------
+	 * The description renders as a second single-line overlay right under
+	 * the inside label; the field's clearance grows to two label lines (see
+	 * CommonInputWrapper). Anchored like the label: to the container root
+	 * for plain inputs, to the bordered layout for group controls.
+	 */
+	&.bb-base-input-container--inside-label.bb-base-input-container--description {
+		.bb-base-input-container__description {
+			font-size: 12px;
+			left: var(--inside-label-offset-l);
+			line-height: var(--bb-label-lh-sm);
+			margin-top: 0;
+			max-width: calc(
+				100% - var(--inside-label-offset-l) - var(--inside-label-offset-r)
+			);
+			overflow: hidden;
+			position: absolute;
+			text-overflow: ellipsis;
+			top: calc(5px + var(--bb-label-lh-sm));
+			white-space: nowrap;
+			z-index: 2;
+		}
+
+		/* Group controls: grow the bordered wrapper by the description line. */
+		&.bb-checkbox-group,
+		&.bb-radio-group,
+		&.bb-switch-group {
+			.bb-base-input-container__layout {
+				padding-top: calc(
+					var(--bb-label-fs-sm) + var(--bb-label-lh-sm) + var(--bb-input-px)
+				);
+			}
+		}
+
+		/* A hidden label collapses the clearance — hide the description too. */
+		&:has(.bb-base-input-container__label--hidden)
+			.bb-base-input-container__description {
+			display: none;
+		}
+	}
+	&__hint-wrap {
+		/*
+		 * Hint channel
+		 * -----------------------------------------------------------------
+		 * Vue controls mount/unmount, CSS handles the visual treatment.
+		 */
+		color: var(--bb-text-muted);
+		font-size: 14px;
+		line-height: 18px;
+		margin-top: 6px;
+		position: relative;
+	}
+	&__errors-wrap {
+		/*
+		 * Error channel container
+		 * -----------------------------------------------------------------
+		 * Height animation is driven via inline height updates from Vue logic;
+		 * CSS provides transition behavior and spacing contract.
+		 */
+		display: block;
+		height: 0;
+		overflow: hidden;
+		transition: height 300ms cubic-bezier(0.4, 0, 0.2, 1);
+		width: 100%;
+		&.bb-base-input-container__errors-wrap--active {
+			margin-top: 6px;
+		}
+
+		&:not(.bb-base-input-container__errors-wrap--active) {
+			margin-top: 0;
+		}
+	}
+	&__errors {
+		/* Error text stack root */
+		color: var(--bb-danger);
+		display: block;
+		font-size: 14px;
+		line-height: 18px;
+		position: relative;
+		width: 100%;
+	}
+	&__error {
+		/* Each error takes a full row */
+		display: inline-block;
+		width: 100%;
+	}
+	&__warnings-wrap {
+		/*
+		 * Warning channel container — mirrors the error channel; height is
+		 * animated via inline updates from Vue logic and collapses to 0 while
+		 * the error state wins.
+		 */
+		display: block;
+		height: 0;
+		overflow: hidden;
+		transition: height 300ms cubic-bezier(0.4, 0, 0.2, 1);
+		width: 100%;
+	}
+	&__warnings {
+		/* Warning text stack root */
+		color: var(--bb-warn);
+		display: block;
+		font-size: 14px;
+		line-height: 18px;
+		position: relative;
+		width: 100%;
+	}
+	&__warning {
+		/* Each warning takes a full row */
+		display: inline-block;
+		width: 100%;
+	}
+
+	/*
+	 * Hint transition primitives
+	 * -----------------------------------------------------------------
+	 * Grid-row animation avoids abrupt auto-height jumps and keeps opacity sync.
+	 */
+	.hint-enter-active,
+	.hint-leave-active {
+		display: grid;
+		grid-template-rows: 1fr;
+		overflow: hidden;
+		transition:
+			grid-template-rows 200ms ease,
+			opacity 300ms ease,
+			margin-top 200ms ease;
+	}
+
+	.hint-enter-from,
+	.hint-leave-to {
+		grid-template-rows: 0fr;
+		margin-top: 0;
+		opacity: 0;
+	}
+
+	.hint-enter-active > *,
+	.hint-leave-active > * {
+		min-height: 0;
+		transition: opacity 300ms ease;
+	}
+
+	.hint-enter-from > *,
+	.hint-leave-to > * {
+		opacity: 0;
+	}
+
+	/*
+	 * Error content transition primitives
+	 * -----------------------------------------------------------------
+	 * Opacity + slight vertical motion for error text. Container height itself
+	 * is animated separately by wrapper logic.
+	 */
+	.errors-content-enter-active,
+	.errors-content-leave-active {
+		transition:
+			opacity 200ms cubic-bezier(0.4, 0, 0.2, 1),
+			transform 200ms cubic-bezier(0.4, 0, 0.2, 1);
+	}
+
+	.errors-content-enter-from,
+	.errors-content-leave-to {
+		opacity: 0;
+		transform: translateY(-2px);
+	}
+}
+```