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

package/dist/ai/source/BbRadioGroup.md

@@ -62,6 +62,7 @@
 				:has-errors="fieldHasErrors"
 				:has-warnings="fieldHasWarnings"
 				:hide-label="hideLabel"
+				:indicator-ready="indicatorReady"
 				:item-input-align="itemInputAlign"
 				:item-label-align="itemLabelAlign"
 				:item-layout="itemLayout"
@@ -72,8 +73,22 @@
 				:options="options"
 				:passthrough="passthrough"
 				:role="hasLegend() ? 'radiogroup' : undefined"
+				:variant="variant"
 			>
-				<template #prepend><slot name="prepend"></slot></template>
+				<template #prepend>
+					<!-- The `variant` indicators (Q76.11 d): first in the list, so the
+					     positioned rows paint over them; hidden from the tree (the
+					     checked state is the inputs'). -->
+					<span
+						v-for="box in indicatorBoxes"
+						:key="box.key"
+						aria-hidden="true"
+						class="bb-radio-group__indicator"
+						:style="indicatorStyle(box)"
+						v-bind="passthrough.indicator"
+					></span>
+					<slot name="prepend"></slot>
+				</template>
 				<template #loading><slot name="loading"></slot></template>
 				<template #empty="data"
 					><slot name="empty" v-bind="data"></slot
@@ -138,6 +153,7 @@ import {
 	formControlPtActive,
 	pickActive,
 	usePassthrough,
+	variantPt,
 } from '@/composables/usePassthrough';
 import {
 	type ComponentPublicInstance,
@@ -161,6 +177,7 @@ import {
 	toggleInputValue,
 } from '@/utilities/functions/toggleInput';
 import { useToggleListFocus } from '@/composables/useToggleInput';
+import { useChoiceIndicator } from '@/composables/useChoiceIndicator';
 import { useItemsGetter } from '@/composables/useItemsGetter';
 import { usePrefill } from '@/composables/usePrefill';
 import { useIndexById } from '../../composables/useIndexById';
@@ -182,7 +199,11 @@ import {
 import { useFormBinding } from '@/composables/useFormBinding';
 export type { BbRadioGroupProps, BbRadioGroupEvents, BbRadioGroupSlots };
 
-defineOptions({ inheritAttrs: false });
+defineOptions({
+	// An app's own variants as declared `pt:<part>:<name>` props (Q76.7).
+	mixins: [variantPt(BB_RADIO_GROUP_PT)],
+	inheritAttrs: false,
+});
 const declaredProps = withDefaults(defineProps<BbRadioGroupProps<T>>(), {
 	inputPosition: 'left',
 	selectable: true,
@@ -400,6 +421,7 @@ const passthrough = usePassthrough({
 	props,
 	parts: BB_RADIO_GROUP_PT.parts,
 	states: BB_RADIO_GROUP_PT.states,
+	variant: { ...BB_RADIO_GROUP_PT.variant, current: () => props.variant },
 	active: {
 		...pickActive(
 			formControlPtActive(props, () => passthroughHasValue.value),
@@ -408,6 +430,28 @@ const passthrough = usePassthrough({
 		loading: () => loading.value,
 	},
 });
+/**
+ * BbTabs' look (`variant`, Q76.11 d): the indicators under the checked rows,
+ * measured on the list. One that slides from row to row.
+ */
+/** `list-layout="vertical"` / `"vertical-stretch"` stack the strip into a column. */
+const stripVertical = computed(
+	() =>
+		props.listLayout === 'vertical' || props.listLayout === 'vertical-stretch'
+);
+const {
+	boxes: indicatorBoxes,
+	ready: indicatorReady,
+	styleOf: indicatorStyle,
+} = useChoiceIndicator({
+	kind: 'radio',
+	variant: () => props.variant,
+	vertical: () => stripVertical.value,
+	list: () => optionsElement.value,
+	rows: () => options.value,
+	rowClass: 'bb-radio-group__item',
+});
+
 /** The container names the heading `label`; this group names it `legend`, after its props. */
 const containerPassthrough = aliasParts(passthrough, { label: 'legend' });
 
@@ -468,7 +512,7 @@ const rowListeners = (option: Option) => ({
 	onMouseup: (event: MouseEvent) => emit('mouseup', event),
 });
 
-/** One row's native radio: named by its text when described, described by the group then its own description. */
+/** One row's native radio: named by its text alone, described by the group then its own description. */
 const rowInputAttrs = (
 	option: Option,
 	index: number,
@@ -522,18 +566,25 @@ const rowIconSlotProps = (
 
 ```ts
 import type { Responsive } from '@/types/ResponsiveSize';
+import {
+	RADIO_VARIANTS,
+	type RadioVariantBuiltIn,
+	type RadioVariantRegistry,
+	type RadioVariantType,
+} from '@/types/RadioVariant';
 import type { BbOptionGroupItemProps } from '@/types/ItemProps';
 import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
 import {
-	GROUP_PT_PARTS,
+	CHOICE_PT_PARTS,
+	type PtVariantAttrs,
 	GROUP_PT_STATES,
 	GROUP_ROW_PT_PARTS,
 	GROUP_ROW_PT_STATES,
-	type GroupFieldPtPart,
-	type GroupPtMap,
+	type ChoiceFieldPtPart,
+	type ChoicePtMap,
+	type ChoicePtPart,
 	type GroupRowPtPart,
 	type GroupWidePtState,
-	type GroupPtPart,
 	type GroupPtState,
 	type PtItemCtx,
 	type PtNoInfer,
@@ -556,21 +607,24 @@ import type { CommonFieldAsteriskSlotProps } from '../CommonField/types';
  *
  * Per-item functions: on the instance, a row part (`item`, `icon`, `label`, `itemDescription`) also accepts `({ item, checked, … }) => PtValue | false | null | undefined` — `item` is the raw item of that row, and every state a boolean beside it, on for it (`checked`, `disabled`, …) — in the `pt` object or the `:pt:<part>` attribute, never on a `<part>:<state>` key and never in the global map or a scope (they ship as JSON). Its result is merged last, after every state entry, through the same deduper; a falsy result leaves the row as it was. See the passthrough guide, _Per-item functions_.
  */
-export type BbRadioGroupPtPart = GroupPtPart;
+export type BbRadioGroupPtPart = ChoicePtPart;
 /** Passthrough states of `BbRadioGroup`, true while the matching `--` modifier is on. */
 export type BbRadioGroupPtState = GroupPtState;
 /** The runtime lists the resolver is wired with — kept next to the types so the two cannot drift. */
 export const BB_RADIO_GROUP_PT = {
-	parts: GROUP_PT_PARTS,
+	parts: CHOICE_PT_PARTS,
 	states: GROUP_PT_STATES,
 	/** `rowStates` are declared on `rowParts` only — the field parts never have them. */
 	rowParts: GROUP_ROW_PT_PARTS,
 	rowStates: GROUP_ROW_PT_STATES,
+	// The `variant` is a state on every part (Q76.7).
+	variant: { names: RADIO_VARIANTS, option: 'radioVariants' },
 } as const satisfies {
 	parts: readonly BbRadioGroupPtPart[];
 	states: readonly BbRadioGroupPtState[];
 	rowParts: readonly GroupRowPtPart[];
 	rowStates: readonly BbRadioGroupPtState[];
+	variant: { names: readonly RadioVariantBuiltIn[]; option: string };
 };
 
 // Spelled INLINE with this component's own unions (Vue's SFC type resolver
@@ -580,294 +634,315 @@ export const BB_RADIO_GROUP_PT = {
 /* eslint-disable @typescript-eslint/consistent-indexed-object-style */
 export type BbRadioGroupProps<T> = {
 	[K in
-		| `pt:${GroupFieldPtPart}`
-		| `pt:${GroupFieldPtPart}:${GroupWidePtState}`
-		| `pt:${GroupRowPtPart}:${BbRadioGroupPtState}`]?: PtValue;
-} & {
-	// The row parts also take a per-item function, typed on this group's
-	// item — a literal function type, not `PtItemFn<T, …>` (T23).
-	[K in `pt:${GroupRowPtPart}`]?:
-		| PtValue
-		| ((ctx: PtItemCtx<PtNoInfer<T>, BbRadioGroupPtState>) => 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?: GroupPtMap<PtNoInfer<T>>;
-	/**
-	 * Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Compact density. Swaps `--bb-label-spacing-y` for
-	 * `--bb-label-spacing-y-compact`, so tune a compact group's label gap with
-	 * the `-compact` token, not the base one.
-	 */
-	compact?: boolean;
-
-	/**
-	 * 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.
-	 */
-	depsDebounceTime?: number;
-
-	/**
-	 * 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;
-
-	/**
-	 * 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 applied, successful load (an empty one included), drops the
-	 * model values the options no longer contain (a single value resets to
-	 * `null`). 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[];
-
-	/**
-	 * 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 each option's label text (the text rendered next to every
-	 * input) while keeping it accessible to screen readers.
-	 * Does not affect the fieldset legend — use `hideLegend` for that.
-	 */
-	hideLabel?: boolean;
-
-	/**
-	 * Visually hides the legend of the fieldset while maintaining accessibility.
-	 */
-	hideLegend?: boolean;
-
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * Prefix for the ids of each option's input and of the label, description
-	 * and message. Generated when omitted.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
-	 *
-	 * @defaultValue `'left'`
-	 */
-	inputPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * The options: an array, or a provider called with a
-	 * `BbRadioGroupItemsContext` (`reason`, `modelValue`, `signal`), sync or
-	 * async. A provider fails by THROWING, never by returning `[]`: the rows
-	 * clear and `#empty` gets the `error`.
-	 */
-	items: T[] | ((context: BbRadioGroupItemsContext) => T[] | Promise<T[]>);
-
-	/**
-	 * Defines a path that returns a property of the object to use as text or a function that returns a string.
-	 *
-	 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
-	 *
-	 * @defaultValue own `label`, else `text`, else `JSON.stringify(item)`
-	 */
-	itemText?: ItemAccessor<T, string>;
-
-	/**
-	 * 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>;
-
-	/**
-	 * ADDITIONAL row fields, never the text or value: `description`, a muted
-	 * line under the label (it may wrap; announced as the option's
-	 * description). An object of paths or getters, or a function of the item;
-	 * nothing is read implicitly.
-	 */
-	itemProps?: BbOptionGroupItemProps<T>;
-
-	/**
-	 * How each row's input and label sit together, in the `layout` keywords:
-	 * `'auto'`, `'vertical'`, `'horizontal'`, `'label-fill'`, `'input-fill'`,
-	 * or a two-word ratio pattern like `'xx xxxxx'`.
-	 *
-	 * @defaultValue `'auto'`
-	 */
-	itemLayout?: FieldLayout;
-
-	/**
-	 * Swaps each row's input and label from their natural order (input first),
-	 * in every `item-layout`. `reverse` swaps the legend and the options instead.
-	 */
-	itemReverse?: boolean;
-
-	/**
-	 * Vertical position of each option's label in its row. Omitted, it stays
-	 * as it is.
-	 */
-	itemLabelAlign?: FieldCrossAlign;
-
-	/**
-	 * Vertical position of each option's control in its row; `'center'` is
-	 * the middle of the label plus its description. Omitted, it sits on the
-	 * label's first line.
-	 */
-	itemInputAlign?: FieldCrossAlign;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	legendPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Text content of the legend.
-	 */
-	legend: string;
-
-	/**
-	 * Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow;
-	 * `'inside'` overlays the legend inside the fieldset border.
-	 * Floating mode is not supported for radio groups.
-	 */
-	legendMode?: 'outside' | 'inside';
-
-	/**
-	 * How the rows sit in the list: `'horizontal'` (on a line, wrapping),
-	 * `'vertical'` (stacked), `'vertical-stretch'` (stacked, as wide as the
-	 * list) or `'tiles'` (equal boxes; `--tile-min-width` on `pt:list` sets the
-	 * narrowest). Layout only: the cards are `pt` (guide § Radio cards).
-	 *
-	 * @defaultValue `'horizontal'`
-	 */
-	listLayout?: ListLayout;
-
-	/**
-	 * String displayed while items are being loaded.
-	 */
-	loadingText?: string;
-
-	/**
-	 * Used by v-model. Can be any serializable type.
-	 */
-	modelValue?: any;
-
-	/**
-	 * Timeout used to debounce response to changes to modelValue.
-	 */
-	modelValueDebounceTime?: number;
-
-	/**
-	 * Name of the option inputs. Optional: a generated one, unique per group
-	 * and stable, groups them. Pass one only when a native (non-JS) form post
-	 * must submit the value under a known key.
-	 */
-	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
-	 * `items` 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;
-
-	/**
-	 * Sets the input in a readonly state.
-	 */
-	readonly?: boolean;
-
-	/**
-	 * Sets the input as required.
-	 */
-	required?: 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);
-} & FormFieldProps<any>;
+		| `pt:${ChoiceFieldPtPart}`
+		| `pt:${ChoiceFieldPtPart}:${GroupWidePtState}`
+		| `pt:${ChoiceFieldPtPart}:${RadioVariantBuiltIn}`
+		| `pt:${GroupRowPtPart}:${BbRadioGroupPtState}`
+		| `pt:${GroupRowPtPart}:${RadioVariantBuiltIn}`]?: PtValue;
+} & /* @vue-ignore */ PtVariantAttrs<
+	ChoicePtPart,
+	keyof RadioVariantRegistry
+> & {
+		// The row parts also take a per-item function, typed on this group's
+		// item — a literal function type, not `PtItemFn<T, …>` (T23).
+		[K in `pt:${GroupRowPtPart}`]?:
+			| PtValue
+			| ((
+					ctx: PtItemCtx<
+						PtNoInfer<T>,
+						BbRadioGroupPtState,
+						RadioVariantBuiltIn | keyof RadioVariantRegistry
+					>
+			  ) => PtItemResult);
+	} & {
+		/**
+		 * Passthrough, object form: the same keys as the `pt:*` attributes
+		 * without the prefix. See the `pt:<part>` row.
+		 */
+		pt?: ChoicePtMap<PtNoInfer<T>> & {
+			[K in `${ChoicePtPart}:${RadioVariantBuiltIn | keyof RadioVariantRegistry}`]?: PtValue;
+		};
+		/* eslint-enable @typescript-eslint/consistent-indexed-object-style */
+		/**
+		 * Focuses the field when it mounts (a dialog already open included), unless the user is typing in another field.
+		 */
+		autofocus?: InputHTMLAttributes['autofocus'];
+
+		/**
+		 * Compact density. Swaps `--bb-label-spacing-y` for
+		 * `--bb-label-spacing-y-compact`, so tune a compact group's label gap with
+		 * the `-compact` token, not the base one.
+		 */
+		compact?: boolean;
+
+		/**
+		 * 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.
+		 */
+		depsDebounceTime?: number;
+
+		/**
+		 * 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;
+
+		/**
+		 * 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 applied, successful load (an empty one included), drops the
+		 * model values the options no longer contain (a single value resets to
+		 * `null`). 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[];
+
+		/**
+		 * 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 each option's label text (the text rendered next to every
+		 * input) while keeping it accessible to screen readers.
+		 * Does not affect the fieldset legend — use `hideLegend` for that.
+		 */
+		hideLabel?: boolean;
+
+		/**
+		 * Visually hides the legend of the fieldset while maintaining accessibility.
+		 */
+		hideLegend?: boolean;
+
+		/**
+		 * Text box to be displayed near the input, usually to indicate instructions.
+		 */
+		hint?: string;
+
+		/**
+		 * Prefix for the ids of each option's input and of the label, description
+		 * and message. Generated when omitted.
+		 */
+		id?: HTMLAttributes['id'];
+
+		/**
+		 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
+		 *
+		 * @defaultValue `'left'`
+		 */
+		inputPosition?: 'left' | 'center' | 'right';
+
+		/**
+		 * The options: an array, or a provider called with a
+		 * `BbRadioGroupItemsContext` (`reason`, `modelValue`, `signal`), sync or
+		 * async. A provider fails by THROWING, never by returning `[]`: the rows
+		 * clear and `#empty` gets the `error`.
+		 */
+		items: T[] | ((context: BbRadioGroupItemsContext) => T[] | Promise<T[]>);
+
+		/**
+		 * Defines a path that returns a property of the object to use as text or a function that returns a string.
+		 *
+		 * Unset: own `label`, else `text` (`{ label, value }` needs no accessor).
+		 *
+		 * @defaultValue own `label`, else `text`, else `JSON.stringify(item)`
+		 */
+		itemText?: ItemAccessor<T, string>;
+
+		/**
+		 * 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>;
+
+		/**
+		 * ADDITIONAL row fields, never the text or value: `description`, a muted
+		 * line under the label (it may wrap; announced as the option's
+		 * description). An object of paths or getters, or a function of the item;
+		 * nothing is read implicitly.
+		 */
+		itemProps?: BbOptionGroupItemProps<T>;
+
+		/**
+		 * How each row's input and label sit together, in the `layout` keywords:
+		 * `'auto'`, `'vertical'`, `'horizontal'`, `'label-fill'`, `'input-fill'`,
+		 * or a two-word ratio pattern like `'xx xxxxx'`.
+		 *
+		 * @defaultValue `'auto'`
+		 */
+		itemLayout?: FieldLayout;
+
+		/**
+		 * Swaps each row's input and label from their natural order (input first),
+		 * in every `item-layout`. `reverse` swaps the legend and the options instead.
+		 */
+		itemReverse?: boolean;
+
+		/**
+		 * Vertical position of each option's label in its row. Omitted, it stays
+		 * as it is.
+		 */
+		itemLabelAlign?: FieldCrossAlign;
+
+		/**
+		 * Vertical position of each option's control in its row; `'center'` is
+		 * the middle of the label plus its description. Omitted, it sits on the
+		 * label's first line.
+		 */
+		itemInputAlign?: FieldCrossAlign;
+
+		/**
+		 * Sets the text alignment of the label.
+		 */
+		legendPosition?: 'left' | 'center' | 'right';
+
+		/**
+		 * Text content of the legend.
+		 */
+		legend: string;
+
+		/**
+		 * Legend rendering mode. `'outside'` renders the legend above the fieldset in the normal flow;
+		 * `'inside'` overlays the legend inside the fieldset border.
+		 * Floating mode is not supported for radio groups.
+		 */
+		legendMode?: 'outside' | 'inside';
+
+		/**
+		 * A tab-strip look (Q76.11 d): `'pill'` (a raised pill under the pick) or
+		 * `'line'` (a bar on a baseline); the indicator slides like a tab strip's.
+		 * `list-layout="vertical"` stacks it. Register more with `radioVariants`.
+		 * Unset: the group's own rows.
+		 */
+		variant?: RadioVariantType;
+
+		/**
+		 * How the rows sit in the list: `'horizontal'` (on a line, wrapping),
+		 * `'vertical'` (stacked), `'vertical-stretch'` (stacked, as wide as the
+		 * list) or `'tiles'` (equal boxes; `--tile-min-width` on `pt:list` sets the
+		 * narrowest). Layout only: the cards are `pt` (guide § Radio cards).
+		 *
+		 * @defaultValue `'horizontal'`
+		 */
+		listLayout?: ListLayout;
+
+		/**
+		 * String displayed while items are being loaded.
+		 */
+		loadingText?: string;
+
+		/**
+		 * Used by v-model. Can be any serializable type.
+		 */
+		modelValue?: any;
+
+		/**
+		 * Timeout used to debounce response to changes to modelValue.
+		 */
+		modelValueDebounceTime?: number;
+
+		/**
+		 * Name of the option inputs. Optional: a generated one, unique per group
+		 * and stable, groups them. Pass one only when a native (non-JS) form post
+		 * must submit the value under a known key.
+		 */
+		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
+		 * `items` 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;
+
+		/**
+		 * Sets the input in a readonly state.
+		 */
+		readonly?: boolean;
+
+		/**
+		 * Sets the input as required.
+		 */
+		required?: 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);
+	} & FormFieldProps<any>;
 
 export type BbRadioGroupEvents = {
 	/**
@@ -1027,6 +1102,8 @@ export type BbRadioGroupSlots<T> = {
 ## Styles
 
 ```css
+@import '../OptionsContainer/choice-strip.css';
+
 .bb-radio-group {
 	.bb-field__layout--horizontal {
 		.bb-field__label {
@@ -1343,6 +1420,19 @@ export type BbRadioGroupSlots<T> = {
 	}
 }
 
+/* A side hidden with the library's or Tailwind's hiding classes takes its gap
+   with it (ATT-11 e): `hideLabel` / `pt:label="sr-only"` (out of flow) or
+   `pt:icon="hidden"` would leave an empty track AND the gap beside it (the
+   row gap in a `vertical` item, Q76.11 c), and the side still shown sat
+   off-centre. `:where` keeps the rule at the row's
+   one class, so a consumer `gap-*` on `pt:item` still wins. */
+.bb-radio-group__item:where(
+	:has(> .bb-radio-group__label:is(.bb-sr-only, .sr-only)),
+	:has(> .bb-toggle-input + :is(.hidden, .sr-only, .bb-sr-only))
+) {
+	gap: 0;
+}
+
 .bb-radio-group__label {
 	color: var(--bb-text);
 	font-size: var(--bb-label-fs);
@@ -1375,6 +1465,32 @@ export type BbRadioGroupSlots<T> = {
 	user-select: none;
 }
 
+/*
+ * `tiles` (ATT-11 d): the invisible native input covers the WHOLE tile,
+ * padding included, not only the glyph's cell, so a click, a hover tooltip on
+ * the input and a test runner's hit-target check land on it anywhere on the
+ * tile. `grid-area: auto` is load-bearing: an absolutely positioned grid child
+ * is sized against its grid area, so `inset: 0` would still be the glyph
+ * cell. A link or a button inside a tile sits above the input and keeps its
+ * own click. List rows keep the cell overlay.
+ */
+.bb-radio-group__list--tiles > .bb-radio-group__item {
+	position: relative;
+
+	> .bb-toggle-input {
+		border-radius: inherit;
+		grid-area: auto;
+		inset: 0;
+		position: absolute;
+		z-index: 1;
+	}
+
+	:is(a, button) {
+		position: relative;
+		z-index: 2;
+	}
+}
+
 /* ---- Touch targets (Q44.19) -------------------------------------------
  * A row is one label line (`--bb-label-lh`, 18px) and the rows sit
  * `--row-gap` (10px) apart. On a coarse pointer only, each row gets an