@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/forms/form-group.md

@@ -0,0 +1,118 @@
+# VibeFormGroup
+
+Wrapper that owns a form control's label, help text, validation feedback, and id. It is the recommended way to make any VibeUI form control accessible.
+
+## How it works
+
+`VibeFormGroup` generates a single id and provides it (plus its label/help/validation flags) to descendant controls. The **first** child control consumes the group id and renders against it; the group renders the `<label>` (linked via `for`), `help-text`, and validation feedback so the child does not duplicate them. This auto-wires `for`/`id` and `aria-describedby` with no manual ids.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `undefined` | Label text rendered for the first child control. |
+| `labelFor` | `string` | `undefined` | Explicit id to use instead of the auto-generated one. |
+| `required` | `boolean` | `false` | `true` appends a red `*` (aria-hidden) and a visually-hidden "required" span to the label. `false` (default) appends a gray "(optional)" label (aria-hidden). Omit on the child control — the group renders the indicator. |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Render valid/invalid feedback. |
+| `validationMessage` | `string` | `undefined` | Feedback message text. |
+| `helpText` | `string` | `undefined` | Help text rendered below the control. |
+| `floating` | `boolean` | `false` | Use Bootstrap floating-label layout (`.form-floating`). |
+| `row` | `boolean` | `false` | Use a horizontal (grid row) layout. |
+| `labelCols` | `number \| string` | `undefined` | Label column width (`col-sm-{n}`) in row layout. |
+| `labelAlign` | `'start' \| 'center' \| 'end'` | `undefined` | Label text alignment in row layout. |
+
+## Events
+
+None.
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| default | The form control(s) to wrap. |
+
+## Usage
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const email = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Email" help-text="We'll never share it.">
+    <VibeFormInput v-model="email" type="email" />
+  </VibeFormGroup>
+</template>
+```
+
+### With validation
+
+```vue
+<script setup lang="ts">
+import { useFormValidation, validators } from '@velkymx/vibeui'
+
+const name = useFormValidation('')
+const validateName = () => name.validate([validators.required()])
+</script>
+
+<template>
+  <VibeFormGroup
+    label="Name"
+    required
+    :validation-state="name.validationState"
+    :validation-message="name.validationMessage"
+  >
+    <VibeFormInput v-model="name.value" @validate="validateName" />
+  </VibeFormGroup>
+</template>
+```
+
+### Horizontal (row) layout
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const username = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Username" row :label-cols="3" label-align="end">
+    <VibeFormInput v-model="username" />
+  </VibeFormGroup>
+</template>
+```
+
+### Floating label
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const city = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="City" floating>
+    <VibeFormInput v-model="city" placeholder="City" />
+  </VibeFormGroup>
+</template>
+```
+
+## Important Notes
+
+- **Single-consumer rule:** only the first child control consumes the group id. With multiple controls (e.g. a checkbox or radio group), subsequent controls generate their own ids — the group's label still describes the set.
+- **Don't double up:** when the group provides `label`, `helpText`, or validation, omit those same props on the child control; the child suppresses its own copies to avoid duplicates.
+- **Floating labels** require the label to render after the control, which the group handles automatically; pair it with a `placeholder` on the input.
+- **Required/optional indicator (WCAG 3.3.2):** the `required` prop renders both a visual indicator (`*` / "(optional)") and a visually-hidden text node for screen readers. The visual spans carry `aria-hidden="true"` so the screen-reader announcement comes from the hidden span, not the symbol.
+- **`aria-describedby` (WCAG 1.3.1):** `helpText` and `validationMessage` elements are assigned stable ids; the child control's `aria-describedby` is wired automatically — no manual id plumbing needed.
+- **Live error region (WCAG 4.1.3):** the invalid-feedback div carries `role="alert"` so new errors are announced by screen readers without requiring the user to re-focus the field.
+
+## Bootstrap CSS Classes
+
+- `.mb-3`, `.row`
+- `.form-floating`
+- `.form-label`, `.col-form-label`, `.col-sm-{n}`, `.text-{start|center|end}`
+- `.form-text`
+- `.valid-feedback`, `.invalid-feedback`

package/docs/forms/form-input.md

@@ -0,0 +1,140 @@
+# VibeFormInput
+
+Single-line text input supporting all standard HTML input types, with built-in validation and accessibility.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string \| number` | `''` | The input value (v-model). Coerced to a number when `type="number"`. |
+| `type` | `InputType` | `'text'` | HTML input type (`text`, `email`, `password`, `number`, `tel`, `url`, `search`, `date`, `time`, `datetime-local`, `month`, `week`, `color`). |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Standalone label text (omit when inside a `VibeFormGroup`). |
+| `placeholder` | `string` | `undefined` | Placeholder text. |
+| `disabled` | `boolean` | `false` | Disable the input. |
+| `readonly` | `boolean` | `false` | Make the input read-only. |
+| `required` | `boolean` | `false` | Mark as required (renders a `*` next to a standalone label). |
+| `size` | `'sm' \| 'lg'` | `undefined` | Control size. |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Visual validation state. |
+| `validationMessage` | `string` | `undefined` | Feedback message shown for the current `validationState`. |
+| `validationRules` | `ValidationRule[] \| ValidatorFunction` | `undefined` | Rules carried for use with a validation composable. |
+| `validateOn` | `'input' \| 'blur' \| 'change'` | `'blur'` | When the `validate` event fires. |
+| `helpText` | `string` | `undefined` | Help text below the input. |
+| `plaintext` | `boolean` | `false` | Render as read-only plain text (`.form-control-plaintext`). |
+| `noWrapper` | `boolean` | `false` | Render only the `<input>` (no wrapper/label/feedback). Use inside `VibeInputGroup`. |
+| `focusRing` | `boolean` | `false` | Add the Bootstrap 5.3 `.focus-ring` helper. |
+| `showToggle` | `boolean` | `false` | Show a show/hide password toggle button. Only applies when `type="password"`. |
+| `showPasswordStrength` | `boolean` | `false` | Show a 4-segment strength meter and `aria-live` strength label below the input. Only applies when `type="password"`. |
+| `autocomplete` | `AutocompleteType` | auto-detected | HTML `autocomplete` attribute. Auto-detected: `type="email"` → `"email"`. Set `"off"` to disable. |
+| `inputmode` | `InputMode` | auto-detected | Mobile keyboard hint. Auto-detected: `number` → `decimal`, `email` → `email`, `tel` → `tel`, `url` → `url`, `search` → `search`. Override explicitly when needed. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string \| number` | Emitted on input (number-coerced for `type="number"`). |
+| `input` | `Event` | Native input event. |
+| `change` | `Event` | Native change event. |
+| `blur` | `FocusEvent` | Emitted on blur. |
+| `focus` | `FocusEvent` | Emitted on focus. |
+| `validate` | — | Emitted when the `validateOn` trigger occurs. |
+
+## Slots
+
+None.
+
+## Usage
+
+### Recommended: inside a VibeFormGroup
+
+`VibeFormGroup` generates the id, links the `<label>`, and wires `aria-describedby`, help text, and validation feedback for the first child control.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const name = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Full Name" help-text="As it appears on your ID.">
+    <VibeFormInput v-model="name" placeholder="Jane Doe" />
+  </VibeFormGroup>
+</template>
+```
+
+### With validation
+
+```vue
+<script setup lang="ts">
+import { useFormValidation, validators } from '@velkymx/vibeui'
+
+const email = useFormValidation('')
+const validateEmail = () =>
+  email.validate([validators.required(), validators.email()])
+</script>
+
+<template>
+  <VibeFormGroup
+    label="Email"
+    :validation-state="email.validationState"
+    :validation-message="email.validationMessage"
+  >
+    <VibeFormInput
+      v-model="email.value"
+      type="email"
+      @validate="validateEmail"
+    />
+  </VibeFormGroup>
+</template>
+```
+
+### Standalone
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const search = ref('')
+</script>
+
+<template>
+  <VibeFormInput v-model="search" label="Search" type="search" />
+</template>
+```
+
+### Password field with toggle and strength meter
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const password = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Password" required>
+    <VibeFormInput
+      v-model="password"
+      type="password"
+      autocomplete="new-password"
+      show-toggle
+      show-password-strength
+    />
+  </VibeFormGroup>
+</template>
+```
+
+## Important Notes
+
+- **Automatic ID & label linking:** when wrapped in a `VibeFormGroup`, the first child control consumes the group id, so the group's `<label>`, help text, and feedback are linked automatically. Do not also set `label`/`helpText` on the input in that case — the group renders them.
+- **Number coercion:** with `type="number"`, an empty field emits `''`; otherwise the emitted value is a `number`.
+- **Plain text:** `plaintext` forces the control read-only.
+- **Placeholder contrast (WCAG 1.4.3):** placeholder text is rendered at full opacity using `--bs-secondary-color`, overriding the browser-default ~0.6 alpha that drops contrast below 3:1.
+- **`autocomplete` auto-detection:** the component sets `autocomplete="email"` automatically for `type="email"` inputs. For password fields, set `autocomplete="current-password"` (login) or `autocomplete="new-password"` (registration) explicitly — the component cannot infer intent from type alone.
+- **`inputmode` auto-detection:** overrides only apply when the prop is not set. Pass an explicit `inputmode` to override (e.g. `inputmode="numeric"` for a 4-digit PIN field that uses `type="text"`).
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.form-control-{sm|lg}`
+- `.form-control-plaintext`
+- `.is-valid`, `.is-invalid`
+- `.focus-ring`

package/docs/forms/form-radio.md

@@ -0,0 +1,82 @@
+# VibeFormRadio
+
+Radio button for exclusive selection within a named group.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string \| number \| boolean` | `''` | Selected value shared across the group (v-model). |
+| `value` | `string \| number \| boolean` | — (required) | This radio's value. |
+| `name` | `string` | — (required) | Group name; all radios in a group share the same `name`. |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Radio label text. |
+| `disabled` | `boolean` | `false` | Disable the radio. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `inline` | `boolean` | `false` | Render inline (`.form-check-inline`). |
+| `reverse` | `boolean` | `false` | Place the label before the radio (`.form-check-reverse`). |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Visual validation state. |
+| `validationMessage` | `string` | `undefined` | Feedback message for the current state. |
+| `validationRules` | `ValidationRule[] \| ValidatorFunction` | `undefined` | Rules carried for use with a validation composable. |
+| `validateOn` | `'change' \| 'blur'` | `'change'` | When the `validate` event fires. |
+| `helpText` | `string` | `undefined` | Help text below the radio. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string \| number \| boolean` | Emitted with this radio's `value` when selected. |
+| `change` | `Event` | Native change event. |
+| `blur` | `FocusEvent` | Emitted on blur. |
+| `focus` | `FocusEvent` | Emitted on focus. |
+| `validate` | — | Emitted when the `validateOn` trigger occurs. |
+
+## Slots
+
+None.
+
+## Usage
+
+### Recommended: a group inside VibeFormGroup
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const plan = ref('free')
+</script>
+
+<template>
+  <VibeFormGroup label="Plan">
+    <VibeFormRadio v-model="plan" name="plan" value="free" label="Free" />
+    <VibeFormRadio v-model="plan" name="plan" value="pro" label="Pro" />
+    <VibeFormRadio v-model="plan" name="plan" value="team" label="Team" />
+  </VibeFormGroup>
+</template>
+```
+
+### Inline
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const size = ref('m')
+</script>
+
+<template>
+  <VibeFormRadio v-model="size" name="size" value="s" label="Small" inline />
+  <VibeFormRadio v-model="size" name="size" value="m" label="Medium" inline />
+  <VibeFormRadio v-model="size" name="size" value="l" label="Large" inline />
+</template>
+```
+
+## Important Notes
+
+- **Shared `name`:** every radio in the same logical group must share a `name` so the browser enforces exclusivity.
+- **Group linking:** the first radio in a `VibeFormGroup` consumes the group id; subsequent radios generate their own ids.
+
+## Bootstrap CSS Classes
+
+- `.form-check`
+- `.form-check-input`, `.form-check-label`
+- `.form-check-inline`, `.form-check-reverse`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-select.md

@@ -0,0 +1,98 @@
+# VibeFormSelect
+
+Single or multiple selection dropdown driven by an `options` array, with built-in validation and accessibility.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `FormSelectOptionValue \| FormSelectOptionValue[]` | `''` | Selected value(s). An array when `multiple` is set. `FormSelectOptionValue` is `string \| number \| boolean \| null \| undefined`. |
+| `options` | `FormSelectOption[]` | `[]` | Options to render: `{ value, text, disabled? }`. |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Standalone label text. |
+| `multiple` | `boolean` | `false` | Allow multiple selection (model becomes an array). |
+| `selectSize` | `number` | `undefined` | Number of visible rows (native `size`). |
+| `htmlSize` | `number` | `undefined` | Number of visible rows (native `size`); takes precedence over `selectSize`. |
+| `placeholder` | `string` | `undefined` | Disabled placeholder option (single-select only). |
+| `disabled` | `boolean` | `false` | Disable the select. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `size` | `'sm' \| 'lg'` | `undefined` | Control size (`.form-select-sm/lg`). |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Visual validation state. |
+| `validationMessage` | `string` | `undefined` | Feedback message for the current state. |
+| `validationRules` | `ValidationRule[] \| ValidatorFunction` | `undefined` | Rules carried for use with a validation composable. |
+| `validateOn` | `'change' \| 'blur'` | `'change'` | When the `validate` event fires. |
+| `helpText` | `string` | `undefined` | Help text below the select. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `FormSelectOptionValue \| FormSelectOptionValue[]` | Emitted on selection. Array when `multiple`. |
+| `change` | `Event` | Native change event. |
+| `blur` | `FocusEvent` | Emitted on blur. |
+| `focus` | `FocusEvent` | Emitted on focus. |
+| `validate` | — | Emitted when the `validateOn` trigger occurs. |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| default | Override the auto-rendered `<option>` list (provide your own `<option>` / `<optgroup>` elements). |
+
+## Usage
+
+### Recommended: inside a VibeFormGroup
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { FormSelectOption } from '@velkymx/vibeui'
+
+const country = ref('')
+const options: FormSelectOption[] = [
+  { value: 'us', text: 'United States' },
+  { value: 'ca', text: 'Canada' },
+  { value: 'mx', text: 'Mexico' }
+]
+</script>
+
+<template>
+  <VibeFormGroup label="Country">
+    <VibeFormSelect v-model="country" :options="options" placeholder="Choose…" />
+  </VibeFormGroup>
+</template>
+```
+
+### Multiple selection
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { FormSelectOption } from '@velkymx/vibeui'
+
+const tags = ref<string[]>([])
+const options: FormSelectOption[] = [
+  { value: 'vue', text: 'Vue' },
+  { value: 'ts', text: 'TypeScript' },
+  { value: 'bs', text: 'Bootstrap' }
+]
+</script>
+
+<template>
+  <VibeFormGroup label="Tags">
+    <VibeFormSelect v-model="tags" :options="options" multiple :select-size="5" />
+  </VibeFormGroup>
+</template>
+```
+
+## Important Notes
+
+- **Non-string values preserved:** option values keep their original type (`number`, `boolean`, etc.). The component encodes options by index internally, so `v-model` round-trips the exact value — you do not have to stringify.
+- **Placeholder:** only applies to single-select; it renders a disabled empty-value option.
+- **Group linking:** wrapped in a `VibeFormGroup`, the select consumes the group id so the label and feedback link automatically.
+
+## Bootstrap CSS Classes
+
+- `.form-select`
+- `.form-select-{sm|lg}`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-spinbutton.md

@@ -0,0 +1,94 @@
+# VibeFormSpinbutton
+
+Numeric input flanked by increment and decrement buttons, with clamping, stepping, and built-in validation.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `number` | `0` | The numeric value (v-model). |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Standalone label text. |
+| `disabled` | `boolean` | `false` | Disable the control. |
+| `readonly` | `boolean` | `false` | Make the input read-only (buttons are also disabled). |
+| `required` | `boolean` | `false` | Mark as required. |
+| `min` | `number` | `undefined` | Minimum value (clamped on change/blur). |
+| `max` | `number` | `undefined` | Maximum value (clamped on change/blur). |
+| `step` | `number` | `1` | Increment/decrement step. Must be greater than 0. |
+| `wrap` | `boolean` | `false` | Wrap from max back to min (and vice versa) at the bounds. |
+| `vertical` | `boolean` | `false` | Stack the buttons vertically. |
+| `size` | `'sm' \| 'lg'` | `undefined` | Control size. |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Visual validation state. |
+| `validationMessage` | `string` | `undefined` | Feedback message for the current state. |
+| `validationRules` | `ValidationRule[] \| ValidatorFunction` | `undefined` | Rules carried for use with a validation composable. |
+| `validateOn` | `'input' \| 'blur' \| 'change'` | `'blur'` | When the `validate` event fires from typing. |
+| `helpText` | `string` | `undefined` | Help text below the control. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `number` | Emitted whenever the value changes. |
+| `increment` | `number` | Emitted with the new value after the increment button is pressed. |
+| `decrement` | `number` | Emitted with the new value after the decrement button is pressed. |
+| `input` | `Event` | Native input event (typing). |
+| `change` | `Event` | Native change event. |
+| `blur` | `FocusEvent` | Emitted on blur. |
+| `focus` | `FocusEvent` | Emitted on focus. |
+| `validate` | — | Emitted on each button press and on the `validateOn` typing trigger. |
+
+## Slots
+
+None.
+
+## Usage
+
+### Recommended: inside a VibeFormGroup
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const quantity = ref(1)
+</script>
+
+<template>
+  <VibeFormGroup label="Quantity">
+    <VibeFormSpinbutton v-model="quantity" :min="1" :max="10" />
+  </VibeFormGroup>
+</template>
+```
+
+### Stepping and wrapping
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const rating = ref(0)
+const onIncrement = (value: number) => console.log('new value', value)
+</script>
+
+<template>
+  <VibeFormSpinbutton
+    v-model="rating"
+    :min="0"
+    :max="5"
+    :step="0.5"
+    wrap
+    @increment="onIncrement"
+  />
+</template>
+```
+
+## Important Notes
+
+- **`step` must be greater than 0.** Decimal steps are snapped to the step's precision (e.g. `step="0.5"` keeps one decimal place).
+- **Clamping:** typed values are clamped to `min`/`max` on `change` and `blur`; an empty field is treated as `0`.
+- **`increment` / `decrement` payload:** both events carry the resulting numeric value, so you do not need to read `modelValue` separately.
+- **Number model only:** when using a validation composable, bind to `.value` (a dev-mode warning fires if an object is passed).
+
+## Bootstrap CSS Classes
+
+- `.input-group`, `.input-group-{sm|lg}`
+- `.form-control`, `.form-control-{sm|lg}`
+- `.btn`, `.btn-outline-secondary`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-switch.md

@@ -0,0 +1,75 @@
+# VibeFormSwitch
+
+Toggle switch for boolean values, rendered as an accessible `role="switch"` control.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `boolean` | `false` | The toggle state (v-model). |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Switch label text. |
+| `disabled` | `boolean` | `false` | Disable the switch. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `inline` | `boolean` | `false` | Render inline (`.form-check-inline`). |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Visual validation state. |
+| `validationMessage` | `string` | `undefined` | Feedback message for the current state. |
+| `validationRules` | `ValidationRule[] \| ValidatorFunction` | `undefined` | Rules carried for use with a validation composable. |
+| `validateOn` | `'change' \| 'blur'` | `'change'` | When the `validate` event fires. |
+| `helpText` | `string` | `undefined` | Help text below the switch. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `boolean` | Emitted on toggle. |
+| `change` | `Event` | Native change event. |
+| `blur` | `FocusEvent` | Emitted on blur. |
+| `focus` | `FocusEvent` | Emitted on focus. |
+| `validate` | — | Emitted when the `validateOn` trigger occurs. |
+
+## Slots
+
+None.
+
+## Usage
+
+### Standalone
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const notifications = ref(true)
+</script>
+
+<template>
+  <VibeFormSwitch v-model="notifications" label="Email notifications" />
+</template>
+```
+
+### Inside a VibeFormGroup
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const darkMode = ref(false)
+</script>
+
+<template>
+  <VibeFormGroup label="Appearance">
+    <VibeFormSwitch v-model="darkMode" label="Dark mode" />
+  </VibeFormGroup>
+</template>
+```
+
+## Important Notes
+
+- **Accessibility:** the underlying input is a checkbox with `role="switch"` and Bootstrap's `.form-switch` styling.
+- **Group linking:** wrapped in a `VibeFormGroup`, the switch consumes the group id so the label and feedback link automatically.
+
+## Bootstrap CSS Classes
+
+- `.form-check`, `.form-switch`
+- `.form-check-input`, `.form-check-label`
+- `.form-check-inline`
+- `.is-valid`, `.is-invalid`