@velkymx/vibeui 0.9.0 → 1.0.2

package/docs/forms/form-input.md

@@ -0,0 +1,112 @@
+# 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. |
+
+## 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>
+```
+
+## 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-{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`

package/docs/forms/form-textarea.md

@@ -0,0 +1,82 @@
+# VibeFormTextarea
+
+Multi-line text input with optional character counting, built-in validation, and accessibility.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string` | `''` | The textarea value (v-model). |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Standalone label text. |
+| `placeholder` | `string` | `undefined` | Placeholder text. |
+| `rows` | `number \| string` | `3` | Number of visible text rows. |
+| `maxlength` | `number \| string` | `undefined` | Maximum character count (also shown in the counter when `showCharCount` is set). |
+| `disabled` | `boolean` | `false` | Disable the textarea. |
+| `readonly` | `boolean` | `false` | Make the textarea read-only. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `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. |
+| `helpText` | `string` | `undefined` | Help text below the textarea. |
+| `noResize` | `boolean` | `false` | Disable manual resizing (`resize: none`). |
+| `showCharCount` | `boolean` | `false` | Show a character counter (`count` or `count / maxlength`). |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string` | Emitted on input. |
+| `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
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const bio = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Bio">
+    <VibeFormTextarea v-model="bio" :rows="5" :maxlength="280" show-char-count />
+  </VibeFormGroup>
+</template>
+```
+
+### Standalone
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const notes = ref('')
+</script>
+
+<template>
+  <VibeFormTextarea v-model="notes" label="Notes" no-resize />
+</template>
+```
+
+## Important Notes
+
+- **Character counter:** `showCharCount` renders inside the help-text row. When inside a `VibeFormGroup` that provides its own help text, the counter is suppressed (the group owns help rendering).
+- **Group linking:** wrapped in a `VibeFormGroup`, the textarea consumes the group id so the label and feedback link automatically.
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.form-control-{sm|lg}`
+- `.is-valid`, `.is-invalid`
+- `.form-text`

package/docs/forms/form-wysiwyg.md

@@ -0,0 +1,99 @@
+# VibeFormWysiwyg
+
+Rich-text editor powered by Quill. HTML is sanitized with DOMPurify on the way in and on the way out (XSS defense-in-depth).
+
+## Peer dependencies
+
+This component requires two optional peers — install both:
+
+```bash
+npm install quill dompurify
+```
+
+Quill and DOMPurify are loaded lazily on mount. If `quill` is missing, the component shows a warning alert and emits a `component-error` event instead of crashing.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string` | `''` | HTML content (v-model). Sanitized with DOMPurify before being rendered. |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Label text. |
+| `placeholder` | `string` | `'Write something...'` | Placeholder shown when empty. |
+| `disabled` | `boolean` | `false` | Disable editing. |
+| `readonly` | `boolean` | `false` | Make the editor read-only. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `theme` | `'snow' \| 'bubble'` | `'snow'` | Quill theme. |
+| `toolbar` | `unknown[] \| string \| boolean` | `undefined` | Toolbar config: a Quill toolbar array, a preset name (`'minimal'`, `'standard'`, `'full'`), `false` to hide, or omit for the default toolbar. |
+| `mobileToolbar` | `unknown[] \| string \| boolean` | `undefined` | Toolbar used at mobile breakpoints (same value forms as `toolbar`). |
+| `height` | `string` | `'200px'` | Minimum editor height. Must be a valid CSS length; invalid values fall back to `200px`. |
+| `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'` | `'blur'` | When the `validate` event fires. |
+| `helpText` | `string` | `undefined` | Help text below the editor. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string` | Emitted with sanitized HTML as content changes. |
+| `change` | — | Emitted on content change. |
+| `blur` | — | Emitted on blur. |
+| `focus` | — | Emitted on focus. |
+| `validate` | — | Emitted when the `validateOn` trigger occurs. |
+| `ready` | `unknown` | Emitted with the Quill instance once initialized. |
+| `component-error` | `ComponentError` | Emitted if Quill fails to load (e.g. peer not installed). |
+
+## Slots
+
+None.
+
+## Usage
+
+### Recommended: inside a VibeFormGroup
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const content = ref('<p>Hello <strong>world</strong></p>')
+</script>
+
+<template>
+  <VibeFormGroup label="Description">
+    <VibeFormWysiwyg v-model="content" toolbar="standard" height="300px" />
+  </VibeFormGroup>
+</template>
+```
+
+### Handling a missing peer
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { ComponentError } from '@velkymx/vibeui'
+
+const content = ref('')
+const onError = (err: ComponentError) => console.error(err.message)
+</script>
+
+<template>
+  <VibeFormWysiwyg v-model="content" @component-error="onError" />
+</template>
+```
+
+## Important Notes
+
+- **Sanitization:** incoming `modelValue` HTML is sanitized before it is rendered, and the emitted HTML is sanitized too. Unsafe tags and attributes (e.g. `<script>`, inline event handlers) are stripped. Do not rely on the editor to preserve dangerous markup.
+- **Both peers required:** `dompurify` is needed for sanitization and `quill` for the editor; install them together.
+- **`height` is validated:** only CSS length values are accepted; anything else falls back to `200px`.
+- **Responsive toolbar:** at mobile breakpoints `mobileToolbar` (or a compact default) is used, and the editor re-initializes while preserving content.
+- **Group linking:** wrapped in a `VibeFormGroup`, the editor consumes the group id so the label and feedback link automatically.
+
+## Bootstrap CSS Classes
+
+- `.form-label`, `.form-text`
+- `.alert`, `.alert-warning` (load-failure message)
+- `.valid-feedback`, `.invalid-feedback`
+
+The editor shell uses VibeUI's own `.vibe-wysiwyg-container` class plus Quill's `.ql-*` classes.