bitboss-ui 2.1.134 → 3.0.0-alpha.1

package/dist/ai/BbRadio.md

@@ -1,255 +1,369 @@
 # BbRadio
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Represents a single choice in exclusive options.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbRadio.md](./source/BbRadio.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Almost always, **don't** — reach for `BbRadioGroup`. It wraps the same buttons in
+a real `<fieldset>` / `<legend>`, maps your `items`, wires the shared `name` +
+`v-model`, and gives you native arrow-key navigation for free. A lone `BbRadio`
+only earns its place as an escape hatch: when the options must be **interleaved
+with other markup** — a pricing card per option, a radio inside each table row —
+or when a single option needs **bespoke label content** (a badge, emphasis) that
+the group's uniform `items` mapping can't express.
+
+Match the choice to the component:
+
+- Exclusive choice from a small set, standard layout → `BbRadioGroup`.
+- Exclusive choice from a large/dynamic set → `BbSelect`.
+- Independent yes/no → `BbCheckbox`.
+- If you only reach for `BbRadio` to stack a few options in a box → that's
+  `BbRadioGroup`; use it instead.
+
+### Composing a group by hand
+
+Three things make a set of `BbRadio` behave as one exclusive group: a shared
+`name`, the same `v-model`, and a **distinct `value` per button**. Selecting one
+deselects the rest because they share the model, and because they are real native
+radios sharing a `name`, the browser gives you **roving focus** across them for
+free (Tab reaches the group once; arrow keys move focus and selection between the
+buttons, wrapping around). What you don't get for free is the grouping
+_semantics_ — you own the container, its `role="radiogroup"`, and its accessible
+name (see Accessibility).
+
+**Plan cards, one BbRadio each**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-radio"
-		:direction="direction"
-		:errors="errors"
-		:has-errors="hasErrors"
-		:hide-label="hideLabel"
-		:hint="hint"
-		:input-position="inputPosition"
-		:label="label"
-		:label-position="labelPosition"
-		:label-tag="'span'"
-		:name="name"
-		:reverse="reverse"
-		:show-hint="showHint"
-		:tag="'label'"
+	<div
+		aria-label="Workspace plan"
+		class="grid max-w-sm gap-2"
+		role="radiogroup"
 	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, name, hasErrors, ariaDescribedby }">
-			<BaseRadio
-				:id="id"
-				:aria-describedby="ariaDescribedby"
-				:autofocus="autofocus"
-				:checked="checked"
-				:color="color"
-				:disabled="disabled"
-				:has-errors="hasErrors"
-				:model-value="modelValue"
-				:name="name"
-				:readonly="readonly"
-				:required="required"
-				:value="value"
-				v-bind="eventListeners"
-				><template #icon="data"
-					><slot name="icon" v-bind="data" :text="label" /></template
-			></BaseRadio>
-		</template>
-	</BaseInputContainer>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Workspace plan</p>
+			<p class="text-xs text-gray-500">Billed monthly · cancel anytime</p>
+		</div>
+		<div
+			v-for="plan in plans"
+			:key="plan.value"
+			class="flex items-start justify-between gap-3 rounded-[var(--bb-radius)] border p-2.5"
+			:class="
+				selected === plan.value
+					? 'border-[color:var(--bb-primary)]'
+					: 'border-[color:var(--bb-border)]'
+			"
+		>
+			<BbRadio
+				v-model="selected"
+				:description="plan.description"
+				:label="plan.label"
+				name="plan"
+				:value="plan.value"
+			/>
+			<span class="shrink-0 pt-0.5 text-xs font-medium tabular-nums">
+				{{ plan.price }}
+			</span>
+		</div>
+		<p class="plan-summary text-xs text-gray-500">
+			Selected plan: {{ selected }}
+		</p>
+	</div>
 </template>
-
 <script setup lang="ts">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseRadio from '../BaseRadio/BaseRadio.vue';
-import { ref, computed } from 'vue';
-import type { BbRadioProps, BbRadioEvents, BbRadioSlots } from './types';
-
-const props = withDefaults(defineProps<BbRadioProps>(), {
-	direction: 'auto',
-	reverse: true,
-});
-
-const emit = defineEmits<BbRadioEvents>();
+import { ref } from 'vue';
+import { BbRadio } from 'bitboss-ui';
 
-defineSlots<BbRadioSlots>();
-
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
+type Plan = {
+	value: string;
+	label: string;
+	description: string;
+	price: string;
+};
 
-const eventListeners = {
-	onBlur: (event: FocusEvent) => {
-		active.value = false;
-		emit('blur', event);
+const plans: Plan[] = [
+	{
+		value: 'starter',
+		label: 'Starter',
+		description: 'For individuals getting started.',
+		price: 'Free',
 	},
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', event),
-	onFocus: (event: FocusEvent) => {
-		active.value = true;
-		emit('focus', event);
+	{
+		value: 'pro',
+		label: 'Pro',
+		description: 'For growing teams that need more.',
+		price: '$12/mo',
 	},
-	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': (value: any) => emit('update:modelValue', value),
-};
+	{
+		value: 'scale',
+		label: 'Scale',
+		description: 'Advanced controls and priority support.',
+		price: '$49/mo',
+	},
+];
+
+const selected = ref<string>('pro');
 </script>
+```
+
+`label`, `name` and `value` are all **required** on each button. `value` is what
+lands in the model when that button is chosen — any serializable value works
+(matched structurally), but prefer stable primitive ids.
+
+### States, hint and validation
+
+Each `BbRadio` carries the full form-field surface — `hint`, `description`,
+`errors` / `has-errors`, `readonly`, `disabled`, `required`. `description` is
+always-visible helper text; `hint` appears on focus unless you pin it with
+`persistent-hint`; both wire to the input via `aria-describedby`. A non-empty
+`errors` (string or array) puts the button in the error state on its own;
+`has-errors` styles the invalid state without messages. **`warnings`** is the
+amber counterpart of `errors` — a string or array rendered below the button in
+its own `aria-live="polite"` region for a valid-but-noteworthy value where a hard
+error would overstate the problem, 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" rather than an invalid state — and `has-errors` wins
+when both are set, suppressing the warning messages so the button never shows
+amber and red at once.
+
+**Readonly, error and disabled**
 
-<style lang="postcss">
-@import './index.css';
-</style>
+```vue
+<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+	<BbRadio
+		:model-value="'locked'"
+		value="locked"
+		label="SSO enforced"
+		name="r-ro"
+		readonly
+		description="Your organization requires single sign-on."
+	/>
+	<BbRadio
+		value="invalid"
+		label="Needs a valid choice"
+		name="r-err"
+		has-errors
+		errors="Please choose a merge method."
+	/>
+	<BbRadio
+		value="off"
+		label="Unavailable on free plan"
+		name="r-dis"
+		disabled
+	/>
+</div>
 ```
 
-## Types
-
-```ts
-import type { HTMLAttributes, InputHTMLAttributes } from 'vue';
-import type {
-	BaseRadioEvents,
-	BaseRadioIconSlotProps,
-} from '../BaseRadio/types';
-
-export type BbRadioProps = {
-	/**
-	 * Sets autofocus on page load.
-	 */
-	autofocus?: InputHTMLAttributes['autofocus'];
-
-	/**
-	 * Defines the input as checked.
-	 */
-	checked?: InputHTMLAttributes['checked'];
-
-	/**
-	 * Define a color for the component.
-	 *
-	 * Either a custom color or a coded color in common HEX, RGB, etc... format.
-	 */
-	color?: string;
-
-	/**
-	 * Direction of the layout of the component. Can either be a predefined value or a pattern separated by a space like `xx xxxxx`.
-	 *
-	 * @defaultValue `'auto'`
-	 */
-	direction?: 'horizontal' | 'vertical' | 'auto' | string;
-
-	/**
-	 * Disables the component.
-	 */
-	disabled?: 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;
-
-	/**
-	 * Text box to be displayed near the input, usually to indicate instructions.
-	 */
-	hint?: string;
-
-	/**
-	 * The identifier of the component.
-	 */
-	id?: HTMLAttributes['id'];
-
-	/**
-	 * Sets the alignment of the input. Since inputs are inline block they can be aligned just as text can.
-	 */
-	inputPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Text content of the label of the element.
-	 */
-	label: string;
+How the two locked states differ:
 
-	/**
-	 * Sets the text alignment of the label.
-	 */
-	labelPosition?: 'left' | 'center' | 'right';
-
-	/**
-	 * Used by v-model. Can be any serializable type.
-	 */
-	modelValue?: any;
-
-	/**
-	 * Defines the name of the input.
-	 */
-	name: InputHTMLAttributes['name'];
-
-	/**
-	 * 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.
-	 *
-	 * @defaultValue `true`
-	 */
-	reverse?: boolean;
-
-	/**
-	 * Defines the value of the radio input.
-	 * It can be any serializable value.
-	 */
-	value: any;
-};
+- `disabled` sets the **native** attribute: the button leaves the tab order and
+  its value never submits.
+- `readonly` does **not** set the native `disabled` attribute (radios have no
+  native readonly). The input stays focusable, exposes `aria-readonly` /
+  `aria-disabled`, still submits its value, and the component swallows every
+  change. Use it for a value the user may see and that must still post, but not
+  change.
 
-/** Re-export for consumers importing events type from BbRadio. */
-export type BbRadioEvents = BaseRadioEvents;
+### Forcing the state with `checked`
 
-/** Props exposed by the `label` slot. */
-export type BbRadioLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the radio is in an error state. */
-	hasErrors: boolean;
-};
+`checked` (booleanish: `true`/`false` or `'true'`/`'false'`) overrides the
+model-derived display: when set, the button shows that state regardless of
+`modelValue`, and re-syncs when the prop changes. Interaction still emits
+`update:modelValue`. Use it when the checked display is derived from elsewhere
+(server state, a parent aggregate) and you handle updates through events rather
+than `v-model`. `checked` + `v-model` fight each other — pick one source of
+truth.
 
-/** Props exposed by the `icon` slot. Extends BaseRadio icon slot with the label text. */
-export type BbRadioIconSlotProps = BaseRadioIconSlotProps & {
-	/** The `label` prop value. */
-	text: string;
-};
+### Custom label and dot visual
 
-export type BbRadioSlots = {
-	/**
-	 * Replaces the default label text rendered next to the radio button.
-	 */
-	label?: (props: BbRadioLabelSlotProps) => any;
-	/**
-	 * Replaces the default radio dot visual inside the radio container. Receives `BaseRadio`
-	 * slot attributes plus the label text.
-	 */
-	icon?: (props: BbRadioIconSlotProps) => any;
-};
-```
+The `label` slot (`{ text, hasErrors }`) replaces the label text — use it to
+append a `BbBadge` or emphasis while keeping the accessible name. Per-option
+label content is the other reason to hand-compose: `BbRadioGroup` maps uniform
+`items`, so the moment one option needs a "Recommended" badge you're back to
+individual `BbRadio` buttons.
 
-## Styles
+**Merge method with a Recommended badge**
 
-```css
-.bb-radio {
-	.bb-base-input-container {
-		cursor: pointer;
+```vue
+<template>
+	<div
+		aria-label="Merge method"
+		class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3"
+		role="radiogroup"
+	>
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Merge pull request #482</p>
+			<p class="text-xs text-gray-500">feature/invoice-export → main</p>
+		</div>
+		<BbRadio
+			v-model="strategy"
+			description="All commits from the branch are added via a merge commit."
+			label="Create a merge commit"
+			name="merge-method"
+			value="merge"
+		/>
+		<BbRadio
+			v-model="strategy"
+			description="Combine all commits into a single commit on the base branch."
+			label="Squash and merge"
+			name="merge-method"
+			value="squash"
+		>
+			<template #label="{ text }">
+				<span class="inline-flex items-center gap-1.5">
+					{{ text }}
+					<BbBadge size="xs" variant="secondary">Recommended</BbBadge>
+				</span>
+			</template>
+		</BbRadio>
+		<BbRadio
+			v-model="strategy"
+			description="Reapply each commit on the base branch, without a merge commit."
+			label="Rebase and merge"
+			name="merge-method"
+			value="rebase"
+		/>
+		<p class="merge-summary text-xs text-gray-500">
+			Pull request #482 will be merged via {{ labels[strategy] }}.
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbBadge, BbRadio } from 'bitboss-ui';
 
-		&--horizontal {
-			align-items: center;
-			display: flex;
-		}
+type MergeMethod = 'merge' | 'squash' | 'rebase';
 
-		.bb-base-input-container__input {
-			margin-bottom: -7px;
-		}
-	}
-}
+const labels: Record<MergeMethod, string> = {
+	merge: 'a merge commit',
+	squash: 'squash and merge',
+	rebase: 'rebase and merge',
+};
+
+const strategy = ref<MergeMethod>('squash');
+</script>
 ```
+
+The `icon` slot
+replaces the **entire radio-dot visual**; it receives the live state
+(`checked`, `focused`, `focusVisible`, `disabled`, `readonly`, `hasErrors`,
+`value`, `text`), so your slot must communicate selected/unselected and the focus
+ring itself.
+
+### Layout
+
+- `direction` defaults to `'auto'` (label and button size to content, one line);
+  `'horizontal'` / `'vertical'` / a pattern like `'xx xxxxx'` split them
+  proportionally.
+- `input-position` / `label-position` (`'left' | 'center' | 'right'`) align the
+  button and label text within their columns.
+- `hide-label` keeps the label for screen readers but hides it visually.
+- **`reverse` is inverted.** The prop is wired through an internal negation, so a
+  `BbRadio` is "reversed" by default and `:reverse="false"` is identical to
+  omitting it. Treat `reverse` as a swap-order switch you turn **on**, not a
+  boolean you can turn off. (Same quirk as standalone `BbCheckbox`; the _group_
+  components don't have it.)
+
+### Events and focus
+
+`update:modelValue` (the `v-model` channel) carries the selected `value` — the
+only selection-of-truth channel. The native `blur`, `change`, `click`, `focus`,
+`input`, `keydown`, `mousedown`, `mouseup` events re-emit with raw payloads;
+listen to them for side concerns only. `autofocus` focuses the input on mount.
+
+### Works well with
+
+- `BbRadioGroup` — the default you should reach for first; this is only the
+  interleaving escape hatch (`./BbRadioGroup.md`).
+- `BbCheckbox` — the independent-boolean sibling with the same field chrome.
+- `BbBadge` — via the `label` slot, to tag an option ("Popular", "Beta").
+
+### Gotchas and anti-patterns
+
+- Don't hand-compose a plain stacked group of `BbRadio` — that's `BbRadioGroup`,
+  which adds the fieldset, roving focus and item mapping.
+- A radio with no `value`, or one whose `name` differs from its siblings, won't
+  form an exclusive group — the browser treats them independently.
+- Hand-composed groups have **no** fieldset semantics on their own — wrap them in
+  a `role="radiogroup"` element with an accessible name (see Accessibility).
+- `reverse` is inverted (see Layout) — don't rely on `:reverse="false"` doing
+  anything.
+- `checked` + `v-model` together fight; pick one.
+- `readonly` still submits and stays focusable; use `disabled` when the value
+  must not post.
+
+### Accessibility
+
+- A radio must have a `value` and share its `name` with its siblings, or the
+  browser won't treat them as one exclusive group.
+- Hand-composed groups have **no** fieldset semantics on their own — wrap them in
+  an element with `role="radiogroup"` and an `aria-label` / `aria-labelledby`, or
+  just use `BbRadioGroup`, which does this for you.
+- `description`, `hint` and `errors` are wired via `aria-describedby`; error
+  messages live in an `aria-live="polite"` region.
+- `readonly` exposes `aria-readonly` and still submits its value; `disabled`
+  removes the option from the tab order entirely.
+- With a custom `icon` slot, all state styling is yours — keep `checked`,
+  `focusVisible` and `hasErrors` visually distinguishable.
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
+| `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` | `"auto"` |  | 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. |
+| `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. |
+| `hint` | `string \| undefined` |  |  | Text box to be displayed near the input, usually to indicate instructions. |
+| `id` | `string \| undefined` |  |  | The identifier of the component. |
+| `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. |
+| `label` | `string` |  | yes | Text content of the label of the element. |
+| `labelPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `modelValue` | `any` |  |  | Used by v-model. Can be any serializable type. |
+| `name` | `string \| undefined` |  | yes | Defines the name of the input. |
+| `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: in every direction the order of the label and the input is swapped from the standard arrangement. |
+| `value` | `any` |  | yes | Defines the value of the radio input. It can be any serializable value. |
+| `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
+
+- `blur` — `(event: "blur", event: FocusEvent): void`
+- `change` — `(event: "change", event: Event): void`
+- `click` — `(event: "click", event: MouseEvent): void`
+- `focus` — `(event: "focus", event: FocusEvent): void`
+- `input` — `(event: "input", event: Event): void`
+- `keydown` — `(event: "keydown", event: KeyboardEvent): void`
+- `mousedown` — `(event: "mousedown", event: MouseEvent): void`
+- `mouseup` — `(event: "mouseup", event: MouseEvent): void`
+- `update:modelValue` — `(event: "update:modelValue", value: any): void`
+
+## Slots
+
+- `icon` — scope: `BbRadioIconSlotProps` — Replaces the default radio dot visual inside the radio container. Receives `BaseRadio` slot attributes plus the label text.
+- `label` — scope: `BbRadioLabelSlotProps` — Replaces the default label text rendered next to the radio button.
+
+## See Also
+
+- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.
+- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.