@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/forms/form-input.md

@@ -1,8 +1,49 @@
 # VibeFormInput
 
-Text input component with built-in validation support for various input types.
+Single-line text input supporting all standard HTML input types, with built-in validation and accessibility.
 
-## Basic Usage
+## 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. |
+
+## 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">
@@ -11,45 +52,61 @@ const name = ref('')
 </script>
 
 <template>
-  <VibeFormInput
-    v-model="name"
-    label="Full Name"
-    placeholder="Enter your name"
-  />
+  <VibeFormGroup label="Full Name" help-text="As it appears on your ID.">
+    <VibeFormInput v-model="name" placeholder="Jane Doe" />
+  </VibeFormGroup>
 </template>
 ```
 
-## Props
+### With validation
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `String \| Number` | `''` | The input value (v-model) |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `type` | `InputType` | `'text'` | HTML input type |
-| `placeholder` | `String` | `undefined` | Placeholder text |
-| `disabled` | `Boolean` | `false` | Disable the input |
-| `readonly` | `Boolean` | `false` | Make the input readonly |
-| `required` | `Boolean` | `false` | Mark as required |
-| `size` | `'sm' \| 'lg'` | `undefined` | Input size |
-| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
-| `validationMessage` | `String` | `undefined` | Validation message |
-| `validateOn` | `'input' \| 'blur' \| 'change'` | `'blur'` | When to validate |
-| `helpText` | `String` | `undefined` | Help text |
-| `plaintext` | `Boolean` | `false` | Display as plain text |
-| `noWrapper` | `Boolean` | `false` | Removes the wrapping div, label, and feedback. Useful inside `VibeInputGroup`. |
-| `focusRing` | `Boolean` | `false` | Enable the Bootstrap 5.3 focus-ring helper |
+```vue
+<script setup lang="ts">
+import { useFormValidation, validators } from '@velkymx/vibeui'
 
-## Important Notes
+const email = useFormValidation('')
+const validateEmail = () =>
+  email.validate([validators.required(), validators.email()])
+</script>
 
-**Automatic ID Generation:** This component automatically generates a unique ID if one is not provided.
+<template>
+  <VibeFormGroup
+    label="Email"
+    :validation-state="email.validationState"
+    :validation-message="email.validationMessage"
+  >
+    <VibeFormInput
+      v-model="email.value"
+      type="email"
+      @validate="validateEmail"
+    />
+  </VibeFormGroup>
+</template>
+```
 
-**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID to ensure proper label association and accessibility.
+### Standalone
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const search = ref('')
+</script>
+
+<template>
+  <VibeFormInput v-model="search" label="Search" type="search" />
+</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.
 
 ## Bootstrap CSS Classes
 
 - `.form-control`
-- `.form-control-{size}`
-- `.is-valid`, `.is-invalid`
+- `.form-control-{sm|lg}`
 - `.form-control-plaintext`
+- `.is-valid`, `.is-invalid`
 - `.focus-ring`

package/docs/forms/form-radio.md

@@ -1,58 +1,82 @@
 # VibeFormRadio
 
-Radio button component for exclusive selection within a group.
+Radio button for exclusive selection within a named group.
 
-## Basic Usage
+## 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 picked = ref('one')
+const plan = ref('free')
 </script>
 
 <template>
-  <VibeFormRadio
-    v-model="picked"
-    name="myGroup"
-    value="one"
-    label="Option One"
-  />
-  <VibeFormRadio
-    v-model="picked"
-    name="myGroup"
-    value="two"
-    label="Option Two"
-  />
+  <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>
 ```
 
-## Props
+### Inline
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `any` | `''` | The picked value (v-model) |
-| `value` | `any` | Required | Value of this radio |
-| `name` | `String` | Required | Shared name for the radio group |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `disabled` | `Boolean` | `false` | Disable the radio |
-| `required` | `Boolean` | `false` | Mark as required |
-| `inline` | `Boolean` | `false` | Display inline |
-| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
-| `validationMessage` | `String` | `undefined` | Validation message |
-| `validateOn` | `'change' \| 'blur'` | `'change'` | When to validate |
-| `helpText` | `String` | `undefined` | Help text |
-| `reverse` | `Boolean` | `false` | Reverse label and input |
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const size = ref('m')
+</script>
 
-## Important Notes
+<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>
+```
 
-**Automatic ID Generation:** This component automatically generates a unique ID if one is not provided.
+## Important Notes
 
-**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID to ensure proper label association and accessibility.
+- **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-input`, `.form-check-label`
+- `.form-check-inline`, `.form-check-reverse`
 - `.is-valid`, `.is-invalid`

package/docs/forms/form-select.md

@@ -1,54 +1,98 @@
 # VibeFormSelect
 
-Custom select component with support for single and multiple selection.
+Single or multiple selection dropdown driven by an `options` array, with built-in validation and accessibility.
 
-## Basic Usage
+## 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'
-const selected = ref('')
-const options = [
-  { value: '1', text: 'Option 1' },
-  { value: '2', text: 'Option 2' }
+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>
-  <VibeFormSelect
-    v-model="selected"
-    label="Choose an option"
-    :options="options"
-  />
+  <VibeFormGroup label="Country">
+    <VibeFormSelect v-model="country" :options="options" placeholder="Choose…" />
+  </VibeFormGroup>
 </template>
 ```
 
-## Props
+### Multiple selection
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `any` | `''` | Selected value (v-model) |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `options` | `FormSelectOption[]` | `[]` | Array of options |
-| `multiple` | `Boolean` | `false` | Enable multiple selection |
-| `selectSize` | `Number` | `undefined` | Visible rows |
-| `disabled` | `Boolean` | `false` | Disable the select |
-| `required` | `Boolean` | `false` | Mark as required |
-| `size` | `'sm' \| 'lg'` | `undefined` | Select size |
-| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
-| `validationMessage` | `String` | `undefined` | Validation message |
-| `validateOn` | `'change' \| 'blur'` | `'change'` | When to validate |
-| `helpText` | `String` | `undefined` | Help text |
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { FormSelectOption } from '@velkymx/vibeui'
 
-## Important Notes
+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>
+```
 
-**Automatic ID Generation:** This component automatically generates a unique ID if one is not provided.
+## Important Notes
 
-**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID to ensure proper label association and accessibility.
+- **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-{size}`
+- `.form-select-{sm|lg}`
 - `.is-valid`, `.is-invalid`

package/docs/forms/form-spinbutton.md

@@ -1,55 +1,94 @@
 # VibeFormSpinbutton
 
-Numeric input component with increment and decrement buttons.
+Numeric input flanked by increment and decrement buttons, with clamping, stepping, and built-in validation.
 
-## Basic Usage
+## 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 count = ref(0)
+const rating = ref(0)
+const onIncrement = (value: number) => console.log('new value', value)
 </script>
 
 <template>
   <VibeFormSpinbutton
-    v-model="count"
-    label="Quantity"
+    v-model="rating"
     :min="0"
-    :max="10"
+    :max="5"
+    :step="0.5"
+    wrap
+    @increment="onIncrement"
   />
 </template>
 ```
 
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `Number` | `0` | The numeric value (v-model) |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `disabled` | `Boolean` | `false` | Disable the spinbutton |
-| `readonly` | `Boolean` | `false` | Make readonly |
-| `required` | `Boolean` | `false` | Mark as required |
-| `min` | `Number` | `undefined` | Minimum value |
-| `max` | `Number` | `undefined` | Maximum value |
-| `step` | `Number` | `1` | Increment/decrement step |
-| `size` | `'sm' \| 'lg'` | `undefined` | Button and input size |
-| `wrap` | `Boolean` | `false` | Wrap around when min/max reached |
-| `vertical` | `Boolean` | `false` | Stack buttons vertically |
-| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
-| `validationMessage` | `String` | `undefined` | Validation message |
-| `validateOn` | `'input' \| 'blur' \| 'change'` | `'blur'` | When to validate |
-| `helpText` | `String` | `undefined` | Help text |
-
 ## Important Notes
 
-**Automatic ID Generation:** This component automatically generates a unique ID if one is not provided.
-
-**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID to ensure proper label association and accessibility.
+- **`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
 
-- `.form-control`
-- `.input-group`
-- `.btn`
+- `.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

@@ -1,47 +1,75 @@
 # VibeFormSwitch
 
-Toggle switch component for boolean values.
+Toggle switch for boolean values, rendered as an accessible `role="switch"` control.
 
-## Basic Usage
+## 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 isEnabled = ref(false)
+const notifications = ref(true)
 </script>
 
 <template>
-  <VibeFormSwitch
-    v-model="isEnabled"
-    label="Enable notifications"
-  />
+  <VibeFormSwitch v-model="notifications" label="Email notifications" />
 </template>
 ```
 
-## Props
+### Inside a VibeFormGroup
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `Boolean` | `false` | The toggle state (v-model) |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `disabled` | `Boolean` | `false` | Disable the switch |
-| `required` | `Boolean` | `false` | Mark as required |
-| `inline` | `Boolean` | `false` | Display inline |
-| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
-| `validationMessage` | `String` | `undefined` | Validation message |
-| `validateOn` | `'change' \| 'blur'` | `'change'` | When to validate |
-| `helpText` | `String` | `undefined` | Help text |
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const darkMode = ref(false)
+</script>
 
-## Important Notes
+<template>
+  <VibeFormGroup label="Appearance">
+    <VibeFormSwitch v-model="darkMode" label="Dark mode" />
+  </VibeFormGroup>
+</template>
+```
 
-**Automatic ID Generation:** This component automatically generates a unique ID if one is not provided.
+## Important Notes
 
-**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID to ensure proper label association and accessibility.
+- **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-input`, `.form-check-label`
+- `.form-check-inline`
 - `.is-valid`, `.is-invalid`