bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbSwitchGroup.md

@@ -1,236 +1,543 @@
 # BbSwitchGroup
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Manages grouped switch options with shared behavior.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbSwitchGroup.md](./source/BbSwitchGroup.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Use `BbSwitchGroup` for a set of related settings that each take effect on their
+own, the moment they flip — notification channels, editor features, privacy
+options. It renders a `<fieldset>` / `<legend>` and binds an **array** of the
+enabled values, mapping each switch from your `items`.
+
+Same visual family as its siblings, different promise — choose by what the flip
+means:
+
+- `BbSwitchGroup` — each row is the on/off **state of a thing**. "Turn things on
+  and off." Usually a live panel, but equally valid inside a submit-gated form
+  (`bitboss-ui/validated` ships `BbSwitchGroup` for exactly that).
+- `BbCheckboxGroup` — the selections are **answers or picks** in a form.
+  "Pick some options." Identical items API.
+
+Choose on what the flip _means_, not on whether a Save button exists.
+
+- `BbSwitch` — a single standalone toggle, not part of a set.
+- `BbRadioGroup` — exactly one exclusive choice.
+
+A switch says _something happens now_; a checkbox says _this will be saved with
+the form_. If a "Save" button applies the changes, use `BbCheckboxGroup`.
+
+### Items are your domain objects
+
+`BbSwitchGroup` is items-driven and shares the checkbox group's mapping API.
+Pass your domain objects straight to `items` and resolve the display text and
+stored value with `item-text` / `item-value` — never pre-map into
+`{ label, value }` arrays. `v-model` then holds an array of the resolved values
+(here, ids), which is what you persist. See the
+[options & items playbook](../../ai/guides/options-items-playbook.md).
+
+**Notification channels (object items)**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-switch-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'"
-	>
-		<template #label="data"><slot name="legend" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseSwitchGroup
-				: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="items"
-				:loading-text="loadingText"
-				:max="max"
-				:model-value="modelValue"
-				:model-value-debounce-time="modelValueDebounceTime"
-				:name="name"
-				:no-data-text="noDataText"
-				:readonly="readonly"
-				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>
-			</BaseSwitchGroup>
-		</template>
-	</BaseInputContainer>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+		<BbSwitchGroup
+			v-model="channels"
+			compact
+			description="Each channel applies the moment you flip it."
+			item-text="label"
+			item-value="id"
+			:items="options"
+			legend="Where should we reach you?"
+			name="workspace-notifications"
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="summary">
+			{{ channels.length }} channel{{ channels.length === 1 ? '' : 's' }} active
+		</p>
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitchGroup } from 'bitboss-ui';
 
-<script setup lang="ts" generic="T = any">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseSwitchGroup from '../BaseSwitchGroup/BaseSwitchGroup.vue';
-import { computed, ref } from 'vue';
-import type {
-	BbSwitchGroupProps,
-	BbSwitchGroupEvents,
-	BbSwitchGroupSlots,
-} from './types';
-
-const props = withDefaults(defineProps<BbSwitchGroupProps<T>>(), {
-	inputPosition: 'left',
-});
-
-const emit = defineEmits<BbSwitchGroupEvents>();
-
-defineSlots<BbSwitchGroupSlots<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>
+type Channel = { id: string; label: string };
 
-<style lang="postcss">
-@import './index.css';
-</style>
+const options: Channel[] = [
+	{ id: 'email', label: 'Email' },
+	{ id: 'sms', label: 'SMS' },
+	{ id: 'push', label: 'Push notifications' },
+	{ id: 'slack', label: 'Slack' },
+];
+
+const channels = ref<string[]>(['email', 'push']);
+</script>
 ```
 
-## Types
+The mapping grammar:
+
+- **Primitive `items`** (`string[]` / `number[]`): omit both props; the value is
+  the primitive.
+- **Dot path**: `item-value="id"`, `item-text="profile.fullName"`.
+- **Extractor function** for anything a path can't express.
+
+Values are matched by **deep equality** (structural, not by reference), and two
+items resolving to the same `item-value` collapse to one switch (first wins), so
+keep values unique — prefer stable primitive ids.
+
+### The array model is mandatory
+
+Like `BbCheckboxGroup`, `multiple` defaults to **`true`**, so `modelValue`
+**must be an array** — seed `ref([])`. A non-array model **throws at setup**;
+that's deliberate, to surface the mis-binding immediately.
 
 ```ts
-import type { BaseCheckboxIconSlotProps } from '../BaseCheckbox/types';
-import type {
-	BbCheckboxGroupEvents,
-	BbCheckboxGroupProps,
-} from '../BbCheckboxGroup/types';
-
-/** Re-export of BbCheckboxGroupProps for the switch-group variant. */
-export type BbSwitchGroupProps<T = any> = BbCheckboxGroupProps<T>;
-
-/** Re-export for consumers importing events type from BbSwitchGroup. */
-export type BbSwitchGroupEvents = BbCheckboxGroupEvents;
-
-/** Props exposed by the `legend` slot. */
-export type BbSwitchGroupLegendSlotProps = {
-	/** The `legend` prop value. */
-	text: string;
-	/** Whether the group is in an error state. */
-	hasErrors: boolean;
-};
+const enabled = ref<string[]>(['email']); // correct
+const enabled = ref(); // throws at setup
+```
 
-/** Props exposed by the `option:prepend` and `option:append` slots. */
-export type BbSwitchGroupOptionAffixSlotProps<T> = {
-	/** Whether this option is currently selected. */
-	checked: boolean;
-	/** Whether this option is currently disabled. */
-	disabled: boolean;
-	/** Generated id for the underlying switch input, when available. */
-	id?: string;
-	/** Original source item for this option. */
-	item: T;
-	/** Resolved display text for this option. */
-	text: string;
-};
+Flipping a switch on appends its value; flipping off removes it. The whole array
+is re-emitted every change — treat `v-model` as immutable. Each switch is
+independent, so the panel reads as "things that are on or off", not "options to
+pick".
 
-/** Props exposed by the `icon` slot. Extends BaseCheckbox icon slot with item and label text. */
-export type BbSwitchGroupIconSlotProps<T> = BaseCheckboxIconSlotProps & {
-	/** Original source item for this option. */
-	item: T;
-	/** Resolved display text for this option. */
-	text: string;
-};
+### Cap how many can be on with `max`
 
-/** Props exposed by the `label` slot for each option. */
-export type BbSwitchGroupLabelSlotProps<T> = {
-	/** Original source item for this option. */
-	item: T;
-	/** Resolved display text for this option. */
-	text: string;
-	/** Whether this option is currently selected. */
-	checked: boolean;
-};
+`max` caps how many switches may be **on** at once. At the cap the remaining
+**off** switches disable automatically, while switches already **on** stay
+toggleable so the user can trade one for another. Pair it with a `hint` that
+explains the limit.
 
-export type BbSwitchGroupSlots<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 switch.
-	 */
-	'option:prepend'?: (props: BbSwitchGroupOptionAffixSlotProps<T>) => any;
-	/**
-	 * Replaces the default switch track visual for each option. Receives all `BaseSwitch` slot
-	 * attributes plus the source item and its display text.
-	 */
-	icon?: (props: BbSwitchGroupIconSlotProps<T>) => any;
-	/**
-	 * Replaces the default label text for each option.
-	 */
-	label?: (props: BbSwitchGroupLabelSlotProps<T>) => any;
-	/**
-	 * Content rendered after each option's switch and label.
-	 */
-	'option:append'?: (props: BbSwitchGroupOptionAffixSlotProps<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: BbSwitchGroupLegendSlotProps) => any;
-};
+**At most two channels on**
+
+```vue
+<template>
+	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
+		<BbSwitchGroup
+			v-model="channels"
+			compact
+			hint="Choose up to two channels."
+			:items="['Email', 'SMS', 'Push', 'Slack']"
+			legend="Alert channels"
+			:max="2"
+			name="alert-channels"
+			persistent-hint
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitchGroup } from 'bitboss-ui';
+
+// Two channels already on: the remaining off switches disable at the cap,
+// while these stay toggleable so the user can trade one for another.
+const channels = ref<string[]>(['Email', 'Push']);
+</script>
 ```
 
-## Styles
+`max` gates _how many_; to gate _which_ switches can be flipped,
+use `selectable`: a boolean (`false` disables every switch) or a predicate
+`(item) => boolean` — options it rejects render disabled (e.g.
+`:selectable="(feature) => feature.enabledForPlan"`). A `disabled` field on the
+item object itself has no effect — it is plain domain data; feed it to the
+predicate instead. To make the whole group non-interactive use the `disabled`
+prop; when a dead row adds nothing, filter the item out of `items`.
 
-```css
-.bb-switch-group {
-	.bb-base-input-container--horizontal {
-		.bb-base-input-container__label {
-			float: left;
-		}
-	}
+### Layout and density
 
-	.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;
-		}
+- `input-direction` (`'horizontal' | 'vertical'`) lays the switches in a row or
+  a stack.
+- `compact` tightens spacing so a group of quick toggles fits inline.
+- `direction` splits the legend against the options block (`'auto'`,
+  `'horizontal'`, `'vertical'`, or a pattern like `'xx xxxxxx'`).
+- `input-position` / `legend-position` align the switches and legend within
+  their columns; `reverse` swaps legend and options order (a plain swap here, not
+  inverted).
+- `hide-legend` hides the legend visually but keeps it for assistive tech. Keep
+  density consistent with the surrounding form.
+
+**Horizontal, compact toggles**
+
+```vue
+<template>
+	<div class="max-w-sm rounded-[var(--bb-radius)] border p-3">
+		<BbSwitchGroup
+			v-model="enabled"
+			compact
+			hint="Applies to the current file only."
+			input-direction="horizontal"
+			:items="['Word wrap', 'Minimap', 'Line numbers']"
+			legend="Editor"
+			name="editor-toggles"
+			persistent-hint
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitchGroup } from 'bitboss-ui';
+
+const enabled = ref<string[]>(['Word wrap', 'Line numbers']);
+</script>
+```
+
+### Legend, description and validation
+
+The `legend` names the group — always set it. `description` is always-visible
+helper text; `hint` shows on focus (`persistent-hint` to pin it); both are wired
+via `aria-describedby`. `errors` (string or array) renders messages and puts the
+group in the error state; `has-errors` toggles error styling alone — rare for a
+settings panel, but available when a toggle is rejected. `legend-mode` places
+the legend `'outside'` (default) or `'inside'` the border. There is **no
+`required` prop** (a switch panel isn't a required field).
+
+### Saving instantly
+
+This is the pattern for a **live** panel — one with no Save button behind it
+(inside a submit-gated form, do none of this and let the form commit). Wire
+persistence to the change, not to a submit button:
+bind `:model-value` + `@update:model-value`, apply optimistically,
+and revert on failure; set `readonly` while a request is in flight so the user
+can't queue conflicting toggles. In production, confirm the outcome with
+`useToast` so feedback doesn't depend on nearby text, and gate destructive
+toggles (e.g. disabling backups) with `useConfirm`.
+
+In this feature-flags panel every flip saves immediately; the simulated API
+rejects turning "Usage analytics" off, so that flip reverts and the message
+explains why:
+
+**Feature flags with optimistic save**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-3">
+		<BbSwitchGroup
+			compact
+			item-text="label"
+			item-value="id"
+			:items="flags"
+			legend="Feature flags"
+			:model-value="enabled"
+			name="feature-flags"
+			:readonly="saving"
+			@update:model-value="onSave"
+		/>
+		<p
+			v-if="error"
+			class="text-xs text-[color:var(--bb-danger)]"
+			data-testid="flags-error"
+		>
+			{{ error }}
+		</p>
+		<p
+			class="text-xs text-[color:var(--bb-text-muted)]"
+			data-testid="flags-status"
+		>
+			{{ saving ? 'Saving…' : `${enabled.length} of ${flags.length} flags on` }}
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitchGroup } from 'bitboss-ui';
+
+type FeatureFlag = { id: string; label: string };
+
+const flags: FeatureFlag[] = [
+	{ id: 'command-palette', label: 'Command palette' },
+	{ id: 'ai-review', label: 'AI code review' },
+	{ id: 'usage-analytics', label: 'Usage analytics' },
+];
+
+const enabled = ref<string[]>(['command-palette', 'usage-analytics']);
+const saving = ref(false);
+const error = ref('');
+
+/** Simulated API — retention policy forbids turning usage analytics off. */
+const persist = (next: string[]) =>
+	new Promise<void>((resolve, reject) => {
+		setTimeout(
+			() =>
+				next.includes('usage-analytics')
+					? resolve()
+					: reject(new Error('Retention policy requires usage analytics')),
+			200
+		);
+	});
+
+/** Optimistic flip; reverts and surfaces an error when the API rejects. */
+const onSave = async (next: string[]) => {
+	const previous = enabled.value;
+	enabled.value = next;
+	error.value = '';
+	saving.value = true;
+	try {
+		await persist(next);
+	} catch {
+		enabled.value = previous;
+		error.value = 'Could not save — usage analytics was restored.';
+	} finally {
+		saving.value = false;
 	}
-}
+};
+</script>
+```
+
+### Async items, loading and coherence
+
+`items` also accepts a provider function (`(prefill, modelValue) => T[] |
+Promise<T[]>`) for options fetched from an API. The group calls it on mount and
+on every dependency-driven refetch with `prefill = true` — groups have no search
+field, so `prefill` is never `false` here. While it resolves, `loading-text` (or
+the `#loading` slot) shows; `no-data-text` (or `#no-data`) covers the empty
+result. Loading and race protection are built in — don't wrap the provider in
+your own `loading` ref or debounce.
+
+Tie the option set to external state with `dependencies` (debounced by
+`deps-debounce-time`) instead of a manual watcher, and set `enforce-coherence`
+so any model entry that no longer matches an available option is dropped
+automatically after a reload. Here the channel list depends on the workspace
+plan: changing plan re-runs the provider (`prefill = true`) and
+`enforce-coherence` flips off any channel the new plan doesn't include —
+downgrade from Pro to Free and watch Slack turn off on its own, no watchers
+involved. See the [fetch-items](../../ai/guides/fetch-items-playbook.md) and
+[coherence](../../ai/guides/coherence-playbook.md) playbooks.
+
+**Alert channels constrained by plan (fetch + coherence)**
+
+```vue
+<template>
+	<div
+		class="flex max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-3"
+	>
+		<BbRadioGroup
+			v-model="plan"
+			compact
+			input-direction="horizontal"
+			item-text="label"
+			item-value="id"
+			:items="plans"
+			legend="Workspace plan"
+			name="workspace-plan"
+		/>
+		<BbSwitchGroup
+			v-model="enabled"
+			compact
+			:dependencies="[plan]"
+			:deps-debounce-time="150"
+			enforce-coherence
+			hint="Channels outside the current plan turn off automatically."
+			item-text="label"
+			item-value="id"
+			:items="loadChannels"
+			legend="Alert channels"
+			loading-text="Loading channels…"
+			name="alert-channels-by-plan"
+			persistent-hint
+		/>
+		<p class="channel-summary text-xs text-[color:var(--bb-text-muted)]">
+			{{ enabled.length }} channel{{ enabled.length === 1 ? '' : 's' }} on
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbRadioGroup, BbSwitchGroup } from 'bitboss-ui';
+
+type Plan = 'free' | 'pro' | 'business';
+
+type Channel = {
+	id: string;
+	label: string;
+	plans: Plan[];
+};
+
+const plans: Array<{ id: Plan; label: string }> = [
+	{ id: 'free', label: 'Free' },
+	{ id: 'pro', label: 'Pro' },
+	{ id: 'business', label: 'Business' },
+];
+
+const allChannels: Channel[] = [
+	{ id: 'email', label: 'Email', plans: ['free', 'pro', 'business'] },
+	{ id: 'slack', label: 'Slack', plans: ['pro', 'business'] },
+	{ id: 'webhook', label: 'Webhooks', plans: ['pro', 'business'] },
+	{ id: 'sms', label: 'SMS', plans: ['business'] },
+];
+
+const plan = ref<Plan>('pro');
+const enabled = ref<string[]>(['email', 'slack']);
+
+// 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 loadChannels = (
+	_prefill: boolean,
+	_modelValue?: string[]
+): Promise<Channel[]> =>
+	new Promise((resolve) => {
+		setTimeout(
+			() =>
+				resolve(
+					allChannels.filter((channel) => channel.plans.includes(plan.value))
+				),
+			300
+		);
+	});
+</script>
 ```
+
+### Slots
+
+`#label` replaces an option's text (`{ item, text, checked }`); `#icon` replaces
+the **entire track-and-thumb visual** for that switch — the native input keeps
+`role="switch"` and its state, so accessibility is unaffected, but you own the
+checked/focus styling. `#legend` replaces the fieldset legend; `#prepend` /
+`#append` inject content inside the options container.
+
+### Events and focus
+
+`update:modelValue` carries the full array — the only selection-of-truth
+channel. Native `blur`, `change`, `click`, `focus`, `input`, `keydown`,
+`mousedown`, `mouseup` re-emit with raw payloads, plus `inactive` when focus
+leaves the group. `autofocus` focuses the first switch on mount.
+
+### Config, platform and pairings
+
+No plugin options change `BbSwitchGroup` behavior, and it renders SSR-safe static
+markup in Nuxt and Inertia apps.
+
+Works well with:
+
+- `BbSwitch` — a single standalone toggle with the same on/off API.
+- `BbCheckboxGroup` — swap to it when the rows are answers or picks rather than
+  states (identical items API).
+- `useToast` — confirm or report the outcome of an instant setting change.
+- `useConfirm` — gate a destructive toggle before applying it.
+
+### Gotchas and anti-patterns
+
+- Don't mix commit models on one surface. A group whose toggles already saved
+  themselves must not sit under a "Save" button implying they had not. Pick one:
+  either the panel is live (no Save), or the whole form commits on submit (Save,
+  and no optimistic write on toggle). A switch group inside a submit-gated form
+  is fine; one that saves itself _and_ has a Save button is not.
+- Don't seed the `v-model` ref with a non-array in multiple mode — it **throws**.
+  Use `ref([])`.
+- Don't listen to `@change`/`@click` to compute the next array yourself —
+  `update:modelValue` already delivers it.
+- At `max`, on-switches stay enabled so the user can trade — don't disable them.
+- A `disabled` field on an item object does nothing — it is inert data. Gate
+  options with the `selectable` predicate, or disable the whole group with
+  `disabled`.
+- Don't pre-map `items` into `{ label, value }` — pass raw rows and resolve with
+  `item-text` / `item-value`.
+
+### Accessibility
+
+- `legend` is required and names the group; use `hide-legend` (not omission) if a
+  visible heading already labels it.
+- Each switch exposes `role="switch"` and derives its accessible name from its
+  item text — keep item labels human-readable.
+- The group is a real `<fieldset>`; don't nest it inside another label.
+- `errors`, `warnings` and `description` are all wired to the group through
+  `aria-describedby`, in that order: the reason the field is invalid is spoken
+  first when it regains focus, and a channel is referenced only while it
+  actually has copy. Messages _also_ render in an `aria-live="polite"` region,
+  so they are announced the moment they appear — announced on change, re-read
+  on focus. Keep messages meaningful, not decorative.
+- Prefer `readonly` (focusable, discoverable, still submits) with a nearby
+  explanation over a silent `disabled`.
+- With a custom `#icon` slot you own the visual state — keep `checked` and
+  `focusVisible` distinct.
+
+## v-model
+
+- `v-model` — type: `any`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
+| `compact` | `boolean \| undefined` |  |  | Displays the component in a compact version. |
+| `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` (after any `errors` / `warnings`, before the `hint`). |
+| `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. They render in an `aria-live="polite"` region (announced when they appear) and, while the list is non-empty, are referenced FIRST from the control's `aria-describedby… |
+| `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 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. |
+| `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 checkbox groups. |
+| `legendPosition` | `"left" \| "center" \| "right" \| undefined` |  |  | Sets the text alignment of the label. |
+| `loadingText` | `string \| undefined` |  |  | String displayed while items are being loaded. |
+| `max` | `number \| undefined` |  |  | Maximum number of selected items. |
+| `modelValue` | `any` |  | yes | Used by v-model. Can be an array of any serializable type. |
+| `modelValueDebounceTime` | `number \| undefined` |  |  | Timeout used to debounce response to changes to modelValue. |
+| `multiple` | `boolean \| undefined` | `true` |  | Enables multi-selection behavior. When true, `modelValue` must be an array. When false, `modelValue` should be a single value. |
+| `name` | `string \| undefined` |  |  | 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. |
+| `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. While displayed they are also… |
+
+## 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 checkbox inputs loses focus. Forwards the original DOM `FocusEvent`.
+- `change` — `(e: "change", event: Event): void` — Emitted when a checkbox option is toggled. Forwards the original DOM `Event` from the checkbox input.
+- `click` — `(e: "click", event: MouseEvent): void` — Emitted when one of the generated checkbox inputs is clicked. Forwards the original DOM `MouseEvent`.
+- `focus` — `(e: "focus", event: FocusEvent): void` — Emitted when one of the generated checkbox 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 checkbox inputs. Forwards the original DOM `Event`.
+- `keydown` — `(e: "keydown", event: KeyboardEvent): void` — Emitted for keyboard interaction on generated checkbox inputs. Forwards the original DOM `KeyboardEvent`.
+- `mousedown` — `(e: "mousedown", event: MouseEvent): void` — Emitted when a pointing device button is pressed over a checkbox input. Forwards the original DOM `MouseEvent`.
+- `mouseup` — `(e: "mouseup", event: MouseEvent): void` — Emitted when a pointing device button is released over a checkbox input. Forwards the original DOM `MouseEvent`.
+- `update:modelValue` — `(e: "update:modelValue", value: any): void` — Emitted with the coherent next selection array whenever selection changes.
+
+## Slots
+
+- `append` — scope: `object` — Content rendered after the last option, inside the options container.
+- `icon` — scope: `BbSwitchGroupIconSlotProps<T>` — Replaces the default switch track visual for each option. Receives all `BaseSwitch` slot attributes plus the source item and its display text.
+- `label` — scope: `BbSwitchGroupLabelSlotProps<T>` — Replaces the default label text for each option.
+- `legend` — scope: `BbSwitchGroupLegendSlotProps` — 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 (see `ValidatedFieldProps.validateOn` for the timing vocabulary). |
+| `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
+
+- [BbSwitch](./BbSwitch.md) — Toggles two-state values with switch semantics.
+- [BbCheckboxGroup](./BbCheckboxGroup.md) — Manages multiple checkbox options as a group.
+- [BbRadioGroup](./BbRadioGroup.md) — Coordinates exclusive selection among radio options.