bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbRadioGroup.md

@@ -1,372 +1,445 @@
 # BbRadioGroup
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Coordinates exclusive selection among radio options.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbRadioGroup.md](./source/BbRadioGroup.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbRadioGroup` when the user must pick **exactly one** option from a short,
+fixed list that's worth showing in full — billing cycle, shipping speed, a plan.
+It renders one `<fieldset>` / `<legend>`, binds a **single** value, and maps each
+button from your `items`.
+
+Choose by shape:
+
+- Several **non-exclusive** choices → `BbCheckboxGroup`.
+- A large or dynamic/async option set → `BbSelect` (adds search + fetch); radios
+  past ~6 options become a wall to scan.
+- Radios that must be interleaved with other markup, with no container that fits
+  → the standalone `BbRadio` escape hatch. For a plain stacked group, stay here.
+- A single independent yes/no → `BbCheckbox`.
+
+### Items and value mapping
+
+Pass domain objects to `items` and resolve the display text and stored value
+with `item-text` / `item-value` — a dot-path or a function. The bound model
+holds only the mapped value (an id), which is what you persist. Primitive
+`items` (`string[]`) need no mapping and bind to the string itself. Values match
+by **deep equality**, and duplicate `item-value`s collapse to one button (first
+wins) — see the
+[options & items playbook](../../ai/guides/options-items-playbook.md).
+
+**Plan selection from objects**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-radio-group"
-		:compact="compact"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLegend"
-		:hint="hint"
-		:input-position="inputPosition"
-		:label="legend"
-		:label-position="labelPosition"
-		:label-tag="'legend'"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-		:tag="'fieldset'"
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
 	>
-		<template #label="data"><slot name="legend" v-bind="data"></slot></template>
-		<template #input="{ id, name, hasErrors, ariaDescribedby }">
-			<BaseRadioGroup
-				:id="id"
-				:aria-describedby="ariaDescribedby"
-				:autofocus="autofocus"
-				:color="color"
-				:dependencies="dependencies"
-				:deps-debounce-time="depsDebounceTime"
-				:direction="inputDirection"
-				:disabled="disabled"
-				:enforce-coherence="enforceCoherence"
-				:has-errors="hasErrors"
-				:hide-label="hideLabel"
-				:item-text="<any>itemText"
-				:item-value="<any>itemValue"
-				:items="<any>items"
-				:loading-text="loadingText"
-				:model-value="modelValue"
-				:model-value-debounce-time="modelValueDebounceTime"
-				:name="name"
-				:no-data-text="noDataText"
-				:readonly="readonly"
-				:required="required"
-				v-bind="eventListeners"
-			>
-				<template #prepend="data"
-					><slot name="prepend" v-bind="data"></slot></template
-				><template #loading="data"
-					><slot name="loading" v-bind="data"></slot></template
-				><template #no-data="data"
-					><slot name="no-data" v-bind="data"></slot></template
-				><template #option:prepend="data"
-					><slot name="option:prepend" v-bind="data"></slot></template
-				><template #icon="data"
-					><slot name="icon" v-bind="data"></slot></template
-				><template #label="data"
-					><slot name="label" v-bind="data"></slot></template
-				><template #option:append="data"
-					><slot name="option:append" v-bind="data"></slot></template
-				><template #append="data"
-					><slot name="append" v-bind="data"></slot
-				></template>
-			</BaseRadioGroup>
-		</template>
-	</BaseInputContainer>
+		<BbRadioGroup
+			v-model="plan"
+			compact
+			description="Switch or cancel anytime from settings."
+			:item-text="planLabel"
+			item-value="id"
+			:items="plans"
+			legend="Subscription plan"
+			name="plan"
+		/>
+		<p class="plan-summary text-xs text-[var(--bb-text-muted)]">
+			Selected: {{ plan }}
+		</p>
+	</div>
 </template>
-
-<script setup lang="ts" generic="T = any">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseRadioGroup from '../BaseRadioGroup/BaseRadioGroup.vue';
-import { ref, computed } from 'vue';
-import type {
-	BbRadioGroupProps,
-	BbRadioGroupEvents,
-	BbRadioGroupSlots,
-} from './types';
-
-const props = withDefaults(defineProps<BbRadioGroupProps<T>>(), {
-	inputPosition: 'left',
-});
-
-const emit = defineEmits<BbRadioGroupEvents>();
-
-defineSlots<BbRadioGroupSlots<T>>();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
-
-const eventListeners = {
-	onBlur: (event: FocusEvent) => emit('blur', event),
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', event),
-	onFocus: (event: FocusEvent) => {
-		active.value = true;
-		emit('focus', event);
-	},
-	onInactive: () => {
-		active.value = false;
-		emit('inactive');
-	},
-	onInput: (event: Event) => emit('input', event),
-	onKeydown: (event: KeyboardEvent) => emit('keydown', event),
-	onMousedown: (event: MouseEvent) => emit('mousedown', event),
-	onMouseup: (event: MouseEvent) => emit('mouseup', event),
-	'onUpdate:modelValue': (event: any) => emit('update:modelValue', event),
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+type Plan = {
+	id: string;
+	label: string;
+	price: string;
 };
-</script>
 
-<style lang="postcss">
-@import './index.css';
-</style>
+const plans: Plan[] = [
+	{ id: 'starter', label: 'Starter', price: 'Free' },
+	{ id: 'pro', label: 'Pro', price: '$12/mo' },
+	{ id: 'scale', label: 'Scale', price: '$49/mo' },
+];
+
+/** Formats each plan as "Label — price" for the option text. */
+const planLabel = (plan: Plan) => `${plan.label} — ${plan.price}`;
+
+const plan = ref<string>('pro');
+</script>
 ```
 
-## Types
+### The model is a single value
+
+Unlike the checkbox and switch groups, `BbRadioGroup` is **single-only** — there
+is no `multiple` prop. Seed the ref with `null` (or a default option's value),
+**not** an array:
 
 ```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type { NestedKeyOf } from '@/types/NestedKeyOf';
-import type { BaseRadioGroupEvents } from '../BaseRadioGroup/types';
-import type {
-	BaseRadioGroupOptionAffixSlotProps,
-	BaseRadioGroupLabelSlotProps,
-	BaseRadioGroupIconSlotProps,
-} from '../BaseRadioGroup/types';
-
-export type BbRadioGroupProps<T> = {
-	/**
-	 * Sets autofocus on page load.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Define a color for the component.
-	 *
-	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
-	 */
-	color?: string;
-
-	/**
-	 * Sets the component in a compact state.
-	 */
-	compact?: boolean;
-
-	/**
-	 * Defines an array of dependencies that will trigger actions in the component upon change.
-	 */
-	dependencies?: any[];
-
-	/**
-	 * Timeout used to debounce response to changes to dependencies.
-	 */
-	depsDebounceTime?: number;
-
-	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
-	 */
-	direction?: 'horizontal' | 'vertical' | 'auto' | string;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: boolean;
-
-	/**
-	 * If coherence is enforced the input cannot have a modelValue that is incoherent with its current items.
-	 *
-	 * e.g. You cannot set v-model to a user that is not present in the items passed.
-	 *
-	 * modelValue will be reset upon incoherence.
-	 */
-	enforceCoherence?: boolean;
-
-	/**
-	 * Can be a string or an array of string containing the messages to display.
-	 */
-	errors?: string | string[];
-
-	/**
-	 * Define if the component should be in an error state.
-	 * It usually attaches a CSS class for styling purposes.
-	 */
-	hasErrors?: boolean;
-
-	/**
-	 * Visually hides the label of the input while maintaining accessibility.
-	 */
-	hideLabel?: boolean;
-
-	/**
-	 * 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;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Defines the direction of the inputs in the fieldset.
-	 */
-	inputDirection?: 'horizontal' | 'vertical';
-
-	/**
-	 * 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';
-
-	/**
-	 * Used to retrieve items; can be an array or a function.
-	 */
-	items:
-		| T[]
-		| ((prefill: boolean, modelValue?: any[]) => Promise<T[]>)
-		| ((prefill: boolean, modelValue?: any[]) => T[]);
-
-	/**
-	 * Defines a path that returns a property of the object to use as text or a function that returns a string.
-	 */
-	itemText?: T extends object
-		? NestedKeyOf<T> | ((item: T) => string)
-		: ((item: T) => string) | undefined;
-
-	/**
-	 * Defines a path that returns a property of the object to use as value or a function that returns any value.
-	 */
-	itemValue?: T extends object
-		? NestedKeyOf<T> | ((item: T) => string)
-		: ((item: T) => any) | undefined;
-
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Text content of the legend.
-	 */
-	legend: string;
-
-	/**
-	 * 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;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name: InputHTMLAttributes['name'];
-
-	/**
-	 * String displayed when there are no items to display.
-	 */
-	noDataText?: string;
-
-	/**
-	 * Keeps the hint displayed.
-	 */
-	persistentHint?: boolean;
-
-	/**
-	 * 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;
-};
+const plan = ref<string | null>(null); // correct
+const plan = ref<string[]>([]); // wrong — radio groups don't bind arrays
+```
 
-/** Re-export for consumers importing events type from BbRadioGroup. */
-export type BbRadioGroupEvents = BaseRadioGroupEvents;
+Picking an option **replaces** the value; a radio group can't be emptied by the
+user (there's no uncheck). If "none" is a legitimate answer, add an explicit
+option for it rather than expecting a cleared model.
 
-/** Props exposed by the `legend` slot. */
-export type BbRadioGroupLegendSlotProps = {
-	/** The `legend` prop value. */
-	text: string;
-	/** Whether the group is in an error state. */
-	hasErrors: boolean;
-};
+### Layout and density
 
-export type BbRadioGroupSlots<T> = {
-	/**
-	 * Content rendered before the first option, inside the options container.
-	 */
-	prepend?: (props: object) => any;
-	/**
-	 * Content shown while options are loading (replaces the default loading text).
-	 */
-	loading?: (props: object) => any;
-	/**
-	 * Content shown when no options are available (replaces the default "no data" text).
-	 */
-	'no-data'?: (props: object) => any;
-	/**
-	 * Content rendered before each option's radio button.
-	 */
-	'option:prepend'?: (props: BaseRadioGroupOptionAffixSlotProps<T>) => any;
-	/**
-	 * Replaces the default radio dot icon for each option. Receives all `BaseRadio`
-	 * slot attributes plus the source item and its display text.
-	 */
-	icon?: (props: BaseRadioGroupIconSlotProps<T>) => any;
-	/**
-	 * Replaces the default label text for each option.
-	 */
-	label?: (props: BaseRadioGroupLabelSlotProps<T>) => any;
-	/**
-	 * Content rendered after each option's radio button and label.
-	 */
-	'option:append'?: (props: BaseRadioGroupOptionAffixSlotProps<T>) => any;
-	/**
-	 * Content rendered after the last option, inside the options container.
-	 */
-	append?: (props: object) => any;
-	/**
-	 * Replaces the default fieldset legend text for the group.
-	 */
-	legend?: (props: BbRadioGroupLegendSlotProps) => any;
-};
+`input-direction="horizontal"` lays options in a row for segmented-style
+choices (shipping speed, billing cycle); the default stacks them. `compact`
+tightens spacing. Because a radio group binds a single value, it drives cleanly
+from `v-model` inline.
+
+**Horizontal shipping speed**
+
+```vue
+<template>
+	<div class="max-w-sm rounded-[var(--bb-radius)] border p-4">
+		<BbRadioGroup
+			v-model="speed"
+			compact
+			hint="Express arrives in 1–2 business days."
+			input-direction="horizontal"
+			:items="['Standard', 'Express', 'Overnight']"
+			legend="Shipping speed"
+			name="shipping-speed"
+			persistent-hint
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+const speed = ref<string>('Standard');
+</script>
 ```
 
-## Styles
-
-```css
-.bb-radio-group {
-	.bb-base-input-container--horizontal {
-		.bb-base-input-container__label {
-			float: left;
-		}
-	}
-
-	.bb-base-input-container__input--right {
-		.bb-cr-container__container {
-			justify-content: flex-end;
-		}
-	}
-	.bb-base-input-container__input--center {
-		.bb-cr-container__container {
-			justify-content: center;
-		}
-	}
-}
+`direction` splits the legend against the options block (`'auto'`,
+`'horizontal'`, `'vertical'`, or a pattern like `'xx xxxxxx'`);
+`input-position` / `legend-position` align options and legend within their
+columns; `reverse` swaps legend and options order (a plain swap here, not
+inverted); `hide-legend` hides the legend visually while keeping it for
+assistive tech.
+
+### Legend, validation and required
+
+The `legend` names the group — always set it. `description` is always-visible
+helper text; `hint` shows on focus (`persistent-hint` to pin it); both wire to
+the group via `aria-describedby`. `errors` (string or array) renders messages
+and puts the group in the error state; `has-errors` toggles the invalid styling
+alone. **`warnings`** (string or array) is the amber counterpart of `errors` —
+rendered below the group in its own `aria-live="polite"` region for a
+valid-but-noteworthy choice (unusual, near a limit, soft-flagged), and a
+non-empty `warnings` implies the warning state just as `errors` implies the error
+state; **`has-warning`** forces that amber chrome without a message. Unlike
+`has-errors`, neither sets `aria-invalid` — a soft "needs a second look", not an
+invalid value — and `has-errors` wins when both are set, suppressing the warning
+messages so the group never shows amber and red at once. `required` marks the group as required — because these are native radios,
+it participates in native form validation. `legend-mode` places the legend
+`'outside'` (default) or `'inside'` the fieldset border.
+
+**Required billing cycle with an error**
+
+```vue
+<template>
+	<div class="max-w-sm rounded-[var(--bb-radius)] border p-4">
+		<BbRadioGroup
+			v-model="cycle"
+			compact
+			description="Yearly billing saves 20% over monthly."
+			:errors="cycleError"
+			:has-errors="!cycle"
+			:items="['Monthly', 'Yearly']"
+			legend="Billing cycle"
+			legend-mode="inside"
+			name="billing-cycle"
+			required
+		/>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+// Seed with null: a radio group binds a single value, never an array.
+const cycle = ref<string | null>(null);
+
+/** Error clears the moment a valid option is picked. */
+const cycleError = computed(() =>
+	cycle.value ? undefined : 'Pick a billing cycle to continue.'
+);
+</script>
 ```
+
+### Keyboard model
+
+The options are real native `<input type="radio">` sharing one `name`, so the
+group uses the browser's native **roving focus**, no custom JS:
+
+- The whole group is a **single Tab stop**. Tab enters it on the checked option
+  (or the first option when nothing is checked yet) and one more Tab leaves the
+  group entirely.
+- **Arrow keys** move focus **and** selection together to the adjacent option —
+  Down/Right to the next, Up/Left to the previous — wrapping around the ends.
+  This is why a radio group is one exclusive choice: moving focus selects.
+- Disabled options are skipped during arrow navigation.
+
+Keep the set short enough that arrow-cycling stays quick; past ~6 options prefer
+`BbSelect`.
+
+### Async items, loading and coherence
+
+`items` accepts a provider function for options fetched from an API;
+`loading-text` / `#loading` and `no-data-text` / `#no-data` cover the loading
+and empty states, `dependencies` (+ `deps-debounce-time`) trigger re-fetches,
+and `enforce-coherence` resets the model to `null` when the current value no
+longer matches an available option. See the
+[fetch-items](../../ai/guides/fetch-items-playbook.md) and
+[coherence](../../ai/guides/coherence-playbook.md) playbooks.
+
+The classic shape is a pair of tied fields: below, the merge strategies a
+repository allows depend on the target branch. The provider uses the non-query
+group signature `(prefill, modelValue)` — `prefill` is `true` on every fetch
+the group starts itself (mount load and dependency-driven refetches alike).
+`prefill === false` means the user typed, and a group has no search field, so
+it always passes `true`. Switch the branch to `main` while "Create a merge
+commit" is selected and the refetched options no longer contain it, so
+coherence resets the model. Because the model is a single value there is no
+array to filter — enforcement resolves to `null`, so treat `null` as "nothing
+valid yet" and gate the submit on it.
+
+**Merge strategy constrained by branch rules**
+
+```vue
+<template>
+	<div
+		class="flex max-w-md flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<BbRadioGroup
+			v-model="branch"
+			compact
+			input-direction="horizontal"
+			item-text="label"
+			item-value="id"
+			:items="branches"
+			legend="Target branch"
+			name="merge-branch"
+		/>
+		<BbRadioGroup
+			v-model="strategy"
+			compact
+			:dependencies="[branch]"
+			:deps-debounce-time="150"
+			enforce-coherence
+			hint="Protected branches require a linear history."
+			item-text="label"
+			item-value="id"
+			:items="loadStrategies"
+			legend="Merge strategy"
+			loading-text="Checking branch rules…"
+			name="merge-strategy"
+			persistent-hint
+		/>
+		<p class="strategy-summary text-xs text-[var(--bb-text-muted)]">
+			Strategy: {{ strategy ?? 'none selected' }}
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup } from 'bitboss-ui';
+
+type BranchId = 'develop' | 'main';
+
+type Strategy = {
+	id: 'merge' | 'squash' | 'rebase';
+	label: string;
+	branches: BranchId[];
+};
+
+const branches: Array<{ id: BranchId; label: string }> = [
+	{ id: 'develop', label: 'develop' },
+	{ id: 'main', label: 'main (protected)' },
+];
+
+const allStrategies: Strategy[] = [
+	{ id: 'merge', label: 'Create a merge commit', branches: ['develop'] },
+	{ id: 'squash', label: 'Squash and merge', branches: ['develop', 'main'] },
+	{ id: 'rebase', label: 'Rebase and merge', branches: ['develop', 'main'] },
+];
+
+const branch = ref<BranchId>('develop');
+const strategy = ref<string | null>('merge');
+
+// Group provider signature: (prefill, modelValue). `prefill` is true on every
+// fetch the group starts itself — the mount load and dependency-driven
+// refetches alike; only a user-typed query reads false, and a group has no
+// search field.
+const loadStrategies = (
+	_prefill: boolean,
+	_modelValue?: string | null
+): Promise<Strategy[]> =>
+	new Promise((resolve) => {
+		setTimeout(
+			() =>
+				resolve(
+					allStrategies.filter((item) => item.branches.includes(branch.value))
+				),
+			300
+		);
+	});
+</script>
+```
+
+### Slots
+
+`#label` replaces an option's text (`{ item, text }`); `#icon` replaces the
+default radio-dot visual for each option (you then own its selected/focus
+styling). `#legend` replaces the fieldset legend (`{ text, hasErrors }`);
+`#prepend` / `#append` inject content inside the options container.
+
+### Events and focus
+
+`update:modelValue` (the `v-model` channel) carries the single selected value —
+the only source of selection truth. Native `blur`, `change`, `click`, `focus`,
+`input`, `keydown`, `mousedown`, `mouseup` re-emit with raw payloads, plus
+`inactive` when focus leaves the group; use them for side effects, never to
+compute selection. `autofocus` focuses the first option on mount.
+
+### Works well with
+
+- `BbRadio` — the escape hatch when options must be interleaved with other
+  markup (`./BbRadio.md`).
+- `BbCheckboxGroup` — the multi-select sibling with the same items API.
+- `BbSelect` — swap to it when the option set grows past a scannable list.
+- `BbButton` — gate a form submit's `disabled` on the bound value.
+
+### Gotchas and anti-patterns
+
+- Don't seed the model with an array — radio groups bind a single value; seed
+  `null`.
+- Don't expect the user to clear the selection; add an explicit "none" option if
+  that's a valid answer.
+- Don't reach for standalone `BbRadio` just to stack a few options in a box —
+  that's this component (fieldset + roving focus + item mapping for free).
+- A `disabled` field on an item object does nothing — it is inert data. Gate
+  options with the `selectable` prop (a boolean, or a predicate
+  `(item) => boolean` that disables the options it rejects — e.g.
+  `:selectable="(plan) => plan.available"`), or disable the whole group with
+  `disabled`; filter unavailable choices out of `items` when a dead row adds
+  nothing.
+- `readonly` still submits its value and stays focusable; use `disabled` only
+  when the whole choice doesn't apply.
+- Don't pre-map `items` into `{ label, value }` — pass raw rows and resolve with
+  `item-text` / `item-value`.
+
+### Accessibility
+
+- Always provide a `legend` — it's the group's accessible name. Use `hide-legend`
+  (not omission) when a visible heading already labels it.
+- The component is a real `<fieldset>`; don't wrap it in another label or nest it
+  inside a `BbRadio`.
+- Arrow keys move between options natively (see Keyboard model); keep the set
+  short enough to scan.
+- `description` and `errors` are announced via `aria-describedby`.
+- `readonly` exposes `aria-readonly` and still submits; prefer it (with a nearby
+  explanation) over a silent `disabled`.
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `compact` | `boolean \| undefined` |  |  | Sets the component in a compact state. |
+| `dependencies` | `unknown[] \| undefined` |  |  | Defines an array of dependencies that will trigger actions in the component upon change. |
+| `depsDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to dependencies. |
+| `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby`. |
+| `direction` | `InputDirection \| undefined` |  |  | Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component. |
+| `enforceCoherence` | `boolean \| undefined` |  |  | If coherence is enforced the input cannot have a modelValue that is incoherent with its current items. e.g. You cannot set v-model to a user that is not present in the items passed. modelValue will be reset upon incoherence. |
+| `errors` | `string \| string[] \| undefined` |  |  | Can be a string or an array of string containing the messages to display. |
+| `hasErrors` | `boolean \| undefined` |  |  | Define if the component should be in an error state. It usually attaches a CSS class for styling purposes. |
+| `hasWarning` | `boolean \| undefined` |  |  | Define if the component should be in a warning state. Same chrome as errors with `--bb-warn`; errors take priority. |
+| `hideLabel` | `boolean \| undefined` |  |  | Visually hides the label of the input while maintaining accessibility. |
+| `hideLegend` | `boolean \| undefined` |  |  | Visually hides the legend of the fieldset while maintaining accessibility. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `inputDirection` | `"horizontal" \| "vertical" \| undefined` |  |  | Defines the direction of the inputs in the fieldset. |
+| `inputPosition` | `"left" \| "center" \| "right" \| undefined` | `"left"` |  | Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can. |
+| `items` | `T[] \| ((prefill: boolean, modelValue?: any) => T[] \| Promise<T[]>)` |  | yes | Used to retrieve items; can be an array or a function. |
+| `itemText` | `ItemAccessor<T, string> \| undefined` |  |  | Defines a path that returns a property of the object to use as text or a function that returns a string. |
+| `itemValue` | `ItemAccessor<T> \| undefined` |  |  | Defines a path that returns a property of the object to use as value or a function that returns any value. |
+| `legend` | `string` |  | yes | Text content of the legend. |
+| `legendMode` | `"outside" \| "inside" \| undefined` |  |  | 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. |
+| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
+| `modelValue` | `any` |  | yes | Used by v-model. Can be any serializable type. |
+| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
+| `name` | `string \| undefined` |  | yes | Defines the name of the input. |
+| `noDataText` | `string \| undefined` |  |  | String displayed when there are no items to display. |
+| `persistentHint` | `boolean \| undefined` |  |  | Keeps the hint displayed. |
+| `readonly` | `boolean \| undefined` |  |  | Sets the input in a readonly state. |
+| `required` | `boolean \| undefined` |  |  | Sets the input as required. |
+| `reverse` | `boolean \| undefined` |  |  | Reverses the layout. Applicable in every direction the order of the label and the input is swapped. |
+| `selectable` | `boolean \| ((item: T) => boolean) \| undefined` | `true` |  | Defines whether options are selectable. Can be a global boolean that affects all options or a function that accepts an item and returns a boolean that only affects that item. Non-selectable options are rendered disabled. |
+| `warnings` | `string \| string[] \| undefined` |  |  | Warning messages to display beneath the field, in their own `aria-live` region and amber (`--bb-warn`). A string or array; a non-empty list implies the warning state. Errors suppress warnings when both are set. |
+
+## Events
+
+- `active` — `(e: "active"): void` — Emitted when the group becomes active (focus/click enters it).
+- `blur` — `(e: "blur", event: FocusEvent): void` — Emitted when one of the generated radio inputs loses focus. Forwards the original DOM `FocusEvent`.
+- `change` — `(e: "change", event: Event): void` — Emitted when a radio option is selected. Forwards the original DOM `Event` from the radio input.
+- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated radio inputs is clicked. Forwards the original DOM `MouseEvent`.
+- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated radio inputs receives focus. Forwards the original DOM `FocusEvent`.
+- `inactive` — `(e: "inactive"): void` — Emitted when focus/click moves outside the group after it was active. Useful for validation-on-blur flows at group level.
+- `input` — `(e: "input", event: Event): void` — Emitted on native input events from generated radio inputs. Forwards the original DOM `Event`.
+- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated radio inputs. Forwards the original DOM `KeyboardEvent`.
+- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a radio input. Forwards the original DOM `MouseEvent`.
+- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a radio input. Forwards the original DOM `MouseEvent`.
+- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the newly selected value when the selection changes.
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the last option, inside the options container.
+- `icon` — scope: `BaseRadioGroupIconSlotProps<T>` — Replaces the default radio dot icon for each option. Receives all `BaseRadio` slot attributes plus the source item and its display text.
+- `label` — scope: `BaseRadioGroupLabelSlotProps<T>` — Replaces the default label text for each option.
+- `legend` — scope: `BbRadioGroupLegendSlotProps` — Replaces the default fieldset legend text for the group.
+- `loading` — scope: `object` — Content shown while options are loading (replaces the default loading text).
+- `no-data` — scope: `object` — Content shown when no options are available (replaces the default "no data" text).
+- `prepend` — scope: `object` — Content rendered before the first option, inside the options container.
+
+## Validated variant
+
+Importing this component from `bitboss-ui/validated` instead of `bitboss-ui` binds it to a vee-validate field. Same props, same events, same slots — plus the ones below. Requires the `vee-validate` peer dependency and a `<BbForm>` (or `useForm()`) ancestor. Full guide: [validated-forms](./guides/validated-forms.md).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `rules` | `RuleExpression<any>` | vee-validate rules for this field. |
+| `validateOn` | `ValidateTiming[] \| undefined` | Which interactions trigger validation. Defaults are per-control (e.g. `['blur']` for text inputs, `['inactive']` for pickers/groups). |
+| `vid` | `string \| undefined` | Explicit vee-validate field name. **Usually omit it** — the name is derived automatically from the control's `label`/`legend`. Only set `vid` when that derivation wouldn't be unique (e.g. v-for rows, or array `v-model`s that share a label).… |
+
+## See Also
+
+- [BbRadio](./BbRadio.md) — Represents a single choice in exclusive options.
+- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
+- [BbSwitchGroup](./BbSwitchGroup.md) — Manages grouped switch options with shared behavior.
+- [BbSelect](./BbSelect.md) — Selects one or many options from structured data.