bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbSwitch.md

@@ -1,150 +1,604 @@
 # BbSwitch
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Selection**
+- Description: Toggles two-state values with switch semantics.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbSwitch.md](./source/BbSwitch.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbSwitch` when the control is the **on/off state of a thing**: dark
+mode, notifications, a beta flag, "anyone with the link can view", auto-renew.
+The switch says _this thing is on or off right now_.
+
+Prefer `BbCheckbox` when the control is an **answer or a selection** rather than
+a state — accepting terms, ticking "also send me a copy", selecting a row. For a
+set of related on/off settings bound to one array, use `BbSwitchGroup`.
+
+**The commit model does not decide this.** A switch is equally correct as a live
+toggle and as a field inside a form that commits on Save or Next: the library
+ships `BbSwitch` from `bitboss-ui/validated` for exactly that, its own fixtures
+put one inside `<BbForm>`, and its wizard recipes put one behind a Next button.
+Do not downgrade a state toggle to a checkbox just because a Save button exists.
+What matters is that a surface picks **one** commit model — see
+[Gotchas and anti-patterns](#gotchas-and-anti-patterns).
+
+### Binding on/off
+
+`v-model` holds the value and updates on every toggle (click, or Space/Enter on
+the focused control). `description` is always-visible helper text tied to the
+control via `aria-describedby`; `hint` is transient guidance that appears while
+the switch has focus — pin it open with `persistent-hint`.
+
+**Instant-effect settings**
 
 ```vue
 <template>
-	<BaseInputContainer
-		:id="id"
-		class="bb-switch"
-		: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'"
-	>
-		<template #label="data"><slot name="label" v-bind="data"></slot></template>
-		<template #input="{ id, hasErrors, ariaDescribedby }">
-			<BaseSwitch
-				:id="id"
-				:aria-describedby="ariaDescribedby"
-				:autofocus="autofocus"
-				:checked="checked"
-				:color="color"
-				:disabled="disabled"
-				:false-value="falseValue"
-				:has-errors="hasErrors"
-				:indeterminate="indeterminate"
-				:model-value="modelValue"
-				:name="name"
-				:readonly="readonly"
-				:required="required"
-				:submit-when-false="submitWhenFalse"
-				:true-value="trueValue"
-				v-bind="eventListeners"
-			>
-				<template #icon="data"
-					><slot name="icon" v-bind="data" :text="label"
-				/></template>
-			</BaseSwitch>
-		</template>
-	</BaseInputContainer>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Account security</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Preferences take effect as soon as you flip them.
+			</p>
+		</div>
+		<div class="grid gap-3">
+			<BbSwitch
+				v-model="twoFactor"
+				description="Require a one-time code at every sign-in."
+				label="Two-factor authentication"
+				name="2fa"
+			/>
+			<BbSwitch
+				v-model="digest"
+				hint="Sent every Monday morning."
+				label="Weekly digest email"
+				name="digest"
+				persistent-hint
+			/>
+		</div>
+	</div>
 </template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitch } from 'bitboss-ui';
+
+const twoFactor = ref(true);
+const digest = ref(false);
+</script>
+```
+
+Besides `update:modelValue` the switch re-emits the native interaction events
+(`change`, `click`, `input`, `focus`, `blur`, `keydown`, `mousedown`,
+`mouseup`) — listen to those for analytics or side effects, never to derive the
+value: the value is what `v-model` gives you.
 
+### Custom on/off values
+
+The bound value does not have to be a boolean. Set `true-value` /
+`false-value` — any serializable value works (strings, numbers, arrays,
+objects; equality is structural) — and `v-model` stores whichever the current
+state maps to. Handy when the switch drives an enum-like setting.
+
+**Custom on/off values**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Profile visibility</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Stores an enum string instead of a boolean.
+			</p>
+		</div>
+		<BbSwitch
+			v-model="visibility"
+			false-value="private"
+			label="Public profile"
+			name="visibility"
+			true-value="public"
+		/>
+		<p class="text-xs text-[color:var(--bb-text-muted)]">
+			Stored value: <code>{{ visibility }}</code>
+		</p>
+	</div>
+</template>
 <script setup lang="ts">
-import BaseInputContainer from '../BaseInputContainer/BaseInputContainer.vue';
-import BaseSwitch from '../BaseSwitch/BaseSwitch.vue';
-import { computed, ref } from 'vue';
-import type { BbSwitchProps, BbSwitchEvents, BbSwitchSlots } from './types';
+import { ref } from 'vue';
+import { BbSwitch } from 'bitboss-ui';
+
+const visibility = ref<'public' | 'private'>('private');
+</script>
+```
 
-const props = withDefaults(defineProps<BbSwitchProps>(), {
-	direction: 'auto',
-	reverse: true,
-});
+For classic (non-AJAX) form posts the checked switch submits `true-value`
+under `name` (non-string values are JSON-encoded). An unchecked checkbox
+normally submits nothing — set `submit-when-false` to also send `false-value`
+via a hidden input, so the server always receives the field.
 
-const emit = defineEmits<BbSwitchEvents>();
+### Saving instantly — and reverting on failure
 
-defineSlots<BbSwitchSlots>();
+This is the pattern for a **live** switch — one with no Save button behind it
+(inside a submit-gated form, do none of this and let the form commit). Wire the
+save to the toggle itself: bind
+`:model-value` + `@update:model-value`, apply the change optimistically, and
+revert if the request fails. Set `readonly` while the request is in flight so
+the user cannot queue conflicting toggles.
 
-const active = ref(false);
-const showHint = computed(() => props.persistentHint || active.value);
+**Async toggle with revert**
 
-const eventListeners = {
-	onBlur: (event: FocusEvent) => {
-		active.value = false;
-		emit('blur', event);
-	},
-	onChange: (event: Event) => emit('change', event),
-	onClick: (event: MouseEvent) => emit('click', event),
-	onFocus: (event: FocusEvent) => {
-		active.value = true;
-		emit('focus', event);
-	},
-	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),
+```vue
+<template>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Workspace</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Northwind Billing — flips save immediately and revert on failure.
+			</p>
+		</div>
+		<BbSwitch
+			description="Visitors see a status page while enabled."
+			label="Maintenance mode"
+			:model-value="maintenance"
+			name="maintenance"
+			:readonly="saving"
+			@update:model-value="onSave"
+		/>
+		<p v-if="error" class="text-xs text-red-600" data-testid="error">
+			{{ error }}
+		</p>
+		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="status">
+			{{ saving ? 'Saving…' : maintenance ? 'Enabled' : 'Disabled' }}
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitch } from 'bitboss-ui';
+
+const maintenance = ref(false);
+const saving = ref(false);
+const error = ref('');
+
+/** Simulated API: enabling succeeds; disabling is rejected mid-deploy. */
+const persist = (value: boolean) =>
+	new Promise<void>((resolve, reject) => {
+		setTimeout(
+			() => (value ? resolve() : reject(new Error('Deployment in progress'))),
+			120
+		);
+	});
+
+const onSave = async (value: boolean) => {
+	error.value = '';
+	saving.value = true;
+	maintenance.value = value; // optimistic
+	try {
+		await persist(value);
+	} catch {
+		maintenance.value = !value; // revert
+		error.value = 'Could not save — the setting was restored.';
+	} finally {
+		saving.value = false;
+	}
 };
 </script>
+```
+
+In this demo enabling succeeds and disabling is rejected by the "server" — flip
+it off to see the revert. Pair the failure path with `useToast` in a real app
+so the feedback doesn't depend on nearby text.
+
+### Passive state: checked and indeterminate
+
+Two props override the visual state without touching `v-model`:
+
+- `checked` (booleanish: `true`/`false`/`'true'`/`'false'`) forces the checked
+  visual regardless of the model — useful when the state is owned elsewhere and
+  the switch is display-driven. Leave it unset to let `modelValue` drive.
+- `indeterminate` shows the "partially on" thumb position — e.g. a master
+  switch whose children disagree. It is a visual flag only; the model keeps its
+  value, and the component re-asserts it after clicks (the DOM resets
+  indeterminate natively).
+
+**Master switch with mixed children**
+
+```vue
+<BbSwitch
+	label="All notifications"
+	:checked="true"
+	indeterminate
+	readonly
+	name="master"
+	hint="Some channels are on, some off."
+	persistent-hint
+/>
+```
+
+### Custom toggle visual
+
+The `icon` slot replaces the **entire track-and-thumb visual** (not just a
+glyph inside it) — the native input keeps carrying `role="switch"` and the
+state, so accessibility is unaffected. The slot receives the live state to
+render from: `checked`, `focused`, `focusVisible`, `disabled`, `readonly`,
+`indeterminate`, `hasErrors`, `value`/`trueValue`/`falseValue`, and `text` (the
+label). When you replace the visual, you own its checked/unchecked styling and
+its focus ring (style against `focusVisible`).
+
+**A glyph that tracks state**
+
+```vue
+<template>
+	<div class="grid max-w-sm gap-2 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Appearance</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				The icon slot replaces the whole track — style checked state yourself.
+			</p>
+		</div>
+		<BbSwitch v-model="dark" label="Dark mode" name="theme">
+			<template #icon="{ checked, focusVisible }">
+				<span
+					class="glyph inline-flex h-6 w-6 items-center justify-center rounded-full"
+					:class="{
+						'glyph--on': checked,
+						'glyph--focus': focusVisible,
+					}"
+				>
+					<BbIcon :icon="checked ? 'lucide:moon' : 'lucide:sun'" size="xs" />
+				</span>
+			</template>
+		</BbSwitch>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitch, BbIcon } from 'bitboss-ui';
+
+const dark = ref(true);
+</script>
 
-<style lang="postcss">
-@import './index.css';
+<style scoped>
+.glyph {
+	background: var(--bb-muted);
+	color: var(--bb-text-muted);
+	transition:
+		background var(--bb-transition-fast) var(--bb-ease),
+		color var(--bb-transition-fast) var(--bb-ease);
+}
+.glyph--on {
+	background: var(--bb-primary);
+	color: var(--bb-primary-fg);
+}
+.glyph--focus {
+	box-shadow:
+		0 0 0 2px var(--bb-panel),
+		0 0 0 4px var(--bb-ring);
+}
 </style>
 ```
 
-## Types
+The `label` slot (`{ text, hasErrors }`) replaces the label text instead — use
+it to append a `BbBadge` ("Beta") or emphasis without giving up the accessible
+name. The classic case is a feature-flags panel where experimental flags carry
+a stage pill next to the flag name:
 
-```ts
-import type { BaseCheckboxIconSlotProps } from '../BaseCheckbox/types';
-import type { BbCheckboxEvents, BbCheckboxProps } from '../BbCheckbox/types';
+**Feature flags with a Beta badge**
 
-/** Re-export of BbCheckboxProps for the switch variant. */
-export type BbSwitchProps = BbCheckboxProps;
+```vue
+<template>
+	<div class="grid max-w-sm gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Feature flags</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Workspace experiments for Northwind Billing.
+			</p>
+		</div>
+		<div class="grid gap-3">
+			<BbSwitch
+				v-model="newEditor"
+				description="Block-based editing with slash commands."
+				label="New editor"
+				name="new-editor"
+			>
+				<template #label="{ text }">
+					<span class="inline-flex items-center gap-1.5">
+						{{ text }}
+						<BbBadge size="sm" variant="soft-amber">Beta</BbBadge>
+					</span>
+				</template>
+			</BbSwitch>
+			<BbSwitch
+				v-model="aiSummaries"
+				description="Summarize long invoice threads automatically."
+				label="AI thread summaries"
+				name="ai-summaries"
+			/>
+			<BbSwitch
+				v-model="usageAnalytics"
+				description="Anonymized product usage for the retention policy."
+				label="Usage analytics"
+				name="usage-analytics"
+			/>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitch, BbBadge } from 'bitboss-ui';
 
-/** Re-export for consumers importing events type from BbSwitch. */
-export type BbSwitchEvents = BbCheckboxEvents;
+const newEditor = ref(true);
+const aiSummaries = ref(false);
+const usageAnalytics = ref(true);
+</script>
 
-/** Props exposed by the `label` slot. */
-export type BbSwitchLabelSlotProps = {
-	/** The `label` prop value. */
-	text: string;
-	/** Whether the switch is in an error state. */
-	hasErrors: boolean;
-};
+<!-- Non-scoped on purpose: styles the child badge's soft variant (scoped CSS
+     can't reach it without :deep). Canonical palette:
+     ai/guides/design-language.md § Using color. -->
+<style>
+.bb-badge.bb-badge--soft-amber {
+	--accent: #d97706;
+	--bg: color-mix(in oklab, var(--accent) 15%, var(--bb-panel));
+	--color: color-mix(in oklab, var(--accent) 80%, var(--bb-text));
+	--border-width: 1px;
+	--border-color: color-mix(in oklab, var(--accent) 25%, var(--bb-panel));
+	--ring: color-mix(in oklab, var(--accent) 45%, transparent);
+}
+</style>
+```
 
-/** Props exposed by the `icon` slot. Extends BaseSwitch icon slot with the label text. */
-export type BbSwitchIconSlotProps = BaseCheckboxIconSlotProps & {
-	/** The `label` prop value. */
-	text: string;
-};
+### Label, layout and density
 
-export type BbSwitchSlots = {
-	/**
-	 * Replaces the default label text rendered next to the switch.
-	 */
-	label?: (props: BbSwitchLabelSlotProps) => any;
-	/**
-	 * Replaces the default toggle track visual inside the switch. Receives `BaseSwitch` slot
-	 * attributes plus the label text.
-	 */
-	icon?: (props: BbSwitchIconSlotProps) => any;
-};
+- `label` is required; `hide-label` keeps it for assistive tech only.
+- `direction` arranges label vs control: `'horizontal'`, `'vertical'`, the
+  default `'auto'`, or a proportional pattern like `'xx xxxxxx'` (label 25% /
+  control 75%).
+- `reverse` swaps the label/control order in whichever direction is active.
+- `label-position` / `input-position` (`left | center | right`) align the two
+  parts within their tracks.
+
+**Row layout for settings lists**
+
+```vue
+<template>
+	<div class="grid max-w-md gap-2 rounded-[var(--bb-radius)] border p-3">
+		<div class="flex flex-col gap-0.5 pb-1">
+			<p class="text-sm font-medium">Playback</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Label-heavy rows with the control pinned to the trailing edge.
+			</p>
+		</div>
+		<BbSwitch
+			v-model="autoplay"
+			direction="xxxxxx xx"
+			label="Autoplay videos"
+			name="autoplay"
+		/>
+		<BbSwitch
+			v-model="captions"
+			direction="xxxxxx xx"
+			label="Always show captions"
+			name="captions"
+		/>
+	</div>
+</template>
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbSwitch } from 'bitboss-ui';
+
+const autoplay = ref(true);
+const captions = ref(false);
+</script>
 ```
 
-## Styles
+### A panel of switches
 
-```css
-.bb-switch {
-	.bb-base-input-container {
-		cursor: pointer;
+Bind each switch to its own field of a typed settings object. The example below
+is a **live** panel: every toggle applies on change, so there is no Save button
+and none is wanted. The same markup inside a `<BbForm>` with a Save button is
+equally valid — it is then a submit-gated form and no toggle writes on its own.
+What a panel must not do is both.
 
-		&--horizontal {
-			align-items: center;
-			display: flex;
-		}
+**Notification preferences**
 
-		.bb-base-input-container__input {
-			margin-bottom: -7px;
-		}
-	}
-}
+```vue
+<template>
+	<div class="grid max-w-md gap-3 rounded-[var(--bb-radius)] border p-4">
+		<div class="flex flex-col gap-0.5">
+			<p class="text-sm font-medium">Email notifications</p>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Sent to alex@northwind.io — changes apply immediately.
+			</p>
+		</div>
+		<div class="grid gap-3">
+			<BbSwitch
+				v-for="pref in preferences"
+				:key="pref.key"
+				v-model="pref.enabled"
+				:description="pref.description"
+				:label="pref.label"
+				:name="pref.key"
+			/>
+		</div>
+		<p class="text-xs text-[color:var(--bb-text-muted)]" data-testid="summary">
+			{{ enabledCount }} of {{ preferences.length }} notifications on
+		</p>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, reactive } from 'vue';
+import { BbSwitch } from 'bitboss-ui';
+
+type Preference = {
+	key: string;
+	label: string;
+	description: string;
+	enabled: boolean;
+};
+
+const preferences = reactive<Preference[]>([
+	{
+		key: 'product',
+		label: 'Product updates',
+		description: 'New features, changelog notes, and roadmap posts.',
+		enabled: true,
+	},
+	{
+		key: 'security',
+		label: 'Security alerts',
+		description: 'Sign-ins from unrecognised devices and API key changes.',
+		enabled: true,
+	},
+	{
+		key: 'marketing',
+		label: 'Marketing emails',
+		description: 'Occasional offers, webinars, and partner news.',
+		enabled: false,
+	},
+]);
+
+const enabledCount = computed(
+	() => preferences.filter((pref) => pref.enabled).length
+);
+</script>
 ```
+
+### Disabled, readonly and errors
+
+- `disabled` sets the native attribute: the switch leaves the tab order and
+  greys out.
+- `readonly` blocks changes (pointer and Space/Enter) but stays focusable and
+  exposes `aria-disabled`/`aria-readonly` — prefer it over `disabled` for
+  admin-locked settings, with a nearby explanation. Note it does **not** set
+  the native `disabled` attribute, so don't target `:disabled` in CSS or tests
+  for readonly switches (`.bb-base-switch--readonly` is the styling hook).
+- `errors` (string or array) renders messages below the control and
+  `has-errors` toggles error styling alone — rare for switches, but available
+  when a toggle is rejected by validation.
+- `warnings` (string or array) is the amber counterpart of `errors`, rendered
+  below the control in its own `aria-live="polite"` region (also referenced
+  from `aria-describedby` while displayed) for a
+  valid-but-noteworthy toggle; a non-empty `warnings` implies the warning state
+  just as `errors` implies the error state, while `has-warning` forces that amber
+  chrome without a message. Unlike `has-errors`, neither sets `aria-invalid` — a
+  soft flag, not an invalid state — and `has-errors` takes priority when both are
+  set, suppressing the warning messages so the switch never shows amber and red
+  at once.
+
+### Config, platform and pairings
+
+No plugin options change `BbSwitch` behavior (it has no i18n strings, no
+teleport, no variant registry) and it renders SSR-safe static markup in Nuxt
+and Inertia apps.
+
+Works well with:
+
+- `BbSwitchGroup` — the same toggle bound to one array of enabled values.
+- `BbCheckbox` — identical API, for answers and selections rather than states.
+- `bitboss-ui/validated` — the vee-validate-bound `BbSwitch` for a switch that
+  commits with the form (see
+  [validated forms](../../ai/guides/validated-forms.md)).
+- `useToast` — confirm or report the outcome of an instant setting change.
+- `useConfirm` — gate a destructive toggle (e.g. disabling backups) before
+  applying it.
+
+### Gotchas and anti-patterns
+
+- Don't mix commit models on one surface. Switches that already applied the
+  moment they were flipped must not sit under a "Save" button implying they had
+  not — the user cannot tell what is already live. Pick one: either the panel is
+  live (no Save), or every field commits on submit (Save, and no optimistic
+  write on toggle). A switch inside a submit-gated form is fine; a switch that
+  saves itself _and_ has a Save button is not.
+- Don't listen to `@click`/`@change` to compute the next value yourself —
+  `v-model` (or `@update:model-value`) already delivers the mapped
+  `true-value`/`false-value`.
+- Don't pass `:checked` together with `v-model` expecting them to sync;
+  `checked` overrides the derived state and wins until unset.
+- The `icon` slot replaces the whole toggle visual — supplying just a bare icon
+  removes the track. Wrap it in your own styled container as shown above.
+
+### Accessibility
+
+- Always provide a `label` — it is the switch's accessible name. Use
+  `hide-label` only when an adjacent element already labels it.
+- The control exposes `role="switch"` with its checked state automatically; do
+  not add your own ARIA.
+- `errors`, `warnings` and `description` are all wired to the control 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) 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. |
+| `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` (after any `errors` / `warnings`, before the `hint`). |
+| `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. 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… |
+| `falseValue` | `any` |  |  | Value of the input when unchecked. It handles any kind of serializable object. |
+| `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. |
+| `indeterminate` | `boolean \| undefined` |  |  | Sets the input in an indeterminate state. |
+| `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` |  |  | 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. |
+| `submitWhenFalse` | `boolean \| undefined` |  |  | Will submit "falseValue" if the input is not checked. Otherwise "trueValue" will be submitted. |
+| `trueValue` | `any` |  |  | Value of the input when checked. It handles any kind of serializable object. |
+| `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
+
+- `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: `BbSwitchIconSlotProps` — Replaces the default toggle track visual inside the switch. Receives `BaseSwitch` slot attributes plus the label text.
+- `label` — scope: `BbSwitchLabelSlotProps` — Replaces the default label text rendered next to the switch.
+
+## 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
+
+- [BbSwitchGroup](./BbSwitchGroup.md) — Manages grouped switch options with shared behavior.
+- [BbCheckbox](./BbCheckbox.md) — Toggles a single boolean option.