@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/forms/form-textarea.md

@@ -1,51 +1,82 @@
 # VibeFormTextarea
 
-Multi-line text input component.
+Multi-line text input with optional character counting, built-in validation, and accessibility.
 
-## Basic Usage
+## 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 text = ref('')
+const bio = ref('')
 </script>
 
 <template>
-  <VibeFormTextarea
-    v-model="text"
-    label="Comments"
-    placeholder="Enter your comments here..."
-  />
+  <VibeFormGroup label="Bio">
+    <VibeFormTextarea v-model="bio" :rows="5" :maxlength="280" show-char-count />
+  </VibeFormGroup>
 </template>
 ```
 
-## Props
+### Standalone
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `String` | `''` | The textarea value (v-model) |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `placeholder` | `String` | `undefined` | Placeholder text |
-| `rows` | `Number \| String` | `3` | Number of visible rows |
-| `disabled` | `Boolean` | `false` | Disable the textarea |
-| `readonly` | `Boolean` | `false` | Make readonly |
-| `required` | `Boolean` | `false` | Mark as required |
-| `size` | `'sm' \| 'lg'` | `undefined` | Textarea 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 |
-| `noResize` | `Boolean` | `false` | Disable resizing |
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const notes = ref('')
+</script>
 
-## Important Notes
+<template>
+  <VibeFormTextarea v-model="notes" label="Notes" no-resize />
+</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.
+- **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-{size}`
+- `.form-control-{sm|lg}`
 - `.is-valid`, `.is-invalid`
+- `.form-text`

package/docs/forms/form-wysiwyg.md

@@ -1,64 +1,99 @@
 # VibeFormWysiwyg
 
-WYSIWYG (What You See Is What You Get) editor component powered by QuillJS.
+Rich-text editor powered by Quill. HTML is sanitized with DOMPurify on the way in and on the way out (XSS defense-in-depth).
 
-## Installation
+## Peer dependencies
 
-First, install Quill as a dependency:
+This component requires two optional peers — install both:
 
 ```bash
-npm install quill
+npm install quill dompurify
 ```
 
-## Basic Usage
+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('')
+const content = ref('<p>Hello <strong>world</strong></p>')
 </script>
 
 <template>
-  <VibeFormWysiwyg
-    v-model="content"
-    label="Content"
-    placeholder="Write something amazing..."
-  />
+  <VibeFormGroup label="Description">
+    <VibeFormWysiwyg v-model="content" toolbar="standard" height="300px" />
+  </VibeFormGroup>
 </template>
 ```
 
-## Props
+### Handling a missing peer
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `String` | `''` | The HTML content (v-model) |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `placeholder` | `String` | `'Write something...'` | Placeholder text |
-| `disabled` | `Boolean` | `false` | Disable the editor |
-| `readonly` | `Boolean` | `false` | Make readonly |
-| `required` | `Boolean` | `false` | Mark as required |
-| `theme` | `'snow' \| 'bubble'` | `'snow'` | Quill theme |
-| `toolbar` | `Array \| String \| Boolean` | default toolbar | Full toolbar configuration |
-| `mobileToolbar` | `Array \| String \| Boolean` | default mobile toolbar | Simplified toolbar for small screens |
-| `height` | `String` | `'200px'` | Minimum height |
-| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
-| `validationMessage` | `String` | `undefined` | Validation message |
-| `validationRules` | `ValidationRule[] \| ValidatorFunction` | `undefined` | Validation rules |
-| `validateOn` | `'change' \| 'blur'` | `'blur'` | When to validate |
-| `helpText` | `String` | `undefined` | Help text |
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import type { ComponentError } from '@velkymx/vibeui'
 
-## Important Notes
+const content = ref('')
+const onError = (err: ComponentError) => console.error(err.message)
+</script>
 
-**Automatic Initialization:** This component dynamically imports Quill and initializes it when mounted. If Quill is not installed in your project, it will display a helpful error message.
+<template>
+  <VibeFormWysiwyg v-model="content" @component-error="onError" />
+</template>
+```
 
-**Lifecycle Management:** VibeFormWysiwyg automatically cleans up its internal Quill instance and removes orphaned toolbar elements from the DOM on unmount to prevent memory leaks.
+## Important Notes
 
-**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID for proper label association.
+- **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
 
-- `.vibe-wysiwyg-container`
-- `.is-valid`
-- `.is-invalid`
-- Uses native Quill CSS classes internally.
+- `.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.

package/docs/forms/input-group.md

@@ -1,51 +1,70 @@
 # VibeInputGroup
 
-Input groups allow you to prepend or append text, buttons, or other elements to your input fields.
-
-## Basic Usage
-
-```vue
-<VibeInputGroup prepend="@">
-  <VibeFormInput noWrapper v-model="username" placeholder="Username" />
-</VibeInputGroup>
-
-<VibeInputGroup append=".00">
-  <VibeFormInput noWrapper v-model="price" placeholder="Price" />
-</VibeInputGroup>
-```
+Wraps a control with prepended/appended text, buttons, or other elements using Bootstrap's input-group.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `prepend` | `String` | `undefined` | Shorthand for prepending text |
-| `append` | `String` | `undefined` | Shorthand for appending text |
-| `size` | `'sm' \| 'lg'` | `undefined` | Size of the input group |
-| `tag` | `String` | `'div'` | HTML tag to use for the container |
+| `size` | `'sm' \| 'lg'` | `undefined` | Input-group size. |
+| `prepend` | `string` | `undefined` | Convenience text rendered before the control as `.input-group-text`. |
+| `append` | `string` | `undefined` | Convenience text rendered after the control as `.input-group-text`. |
+| `tag` | `Tag` | `'div'` | Root element tag. |
+
+## Events
+
+None.
 
 ## Slots
 
 | Slot | Description |
 |------|-------------|
-| `default` | The main content, usually a `VibeFormInput` with the `noWrapper` prop |
-| `prepend` | Slot for complex prepend content (e.g., icons or buttons) |
-| `append` | Slot for complex append content |
+| default | The control to wrap (typically a `VibeFormInput` with `no-wrapper`). |
+| `prepend` | Custom prepended content (overrides the `prepend` prop). |
+| `append` | Custom appended content (overrides the `append` prop). |
 
-## Advanced Example
+## Usage
+
+### Text prepend / append
 
 ```vue
-<VibeInputGroup>
-  <template #prepend>
-    <VibeButton variant="outline-secondary">Search</VibeButton>
-  </template>
-  <VibeFormInput noWrapper v-model="query" />
-  <template #append>
-    <span class="input-group-text">
-      <VibeIcon name="search" />
-    </span>
-  </template>
-</VibeInputGroup>
+<script setup lang="ts">
+import { ref } from 'vue'
+const price = ref('')
+</script>
+
+<template>
+  <VibeInputGroup prepend="$" append=".00">
+    <VibeFormInput v-model="price" type="number" no-wrapper />
+  </VibeInputGroup>
+</template>
 ```
 
-## Mobile Note
-Input groups work seamlessly with the `noWrapper` prop on `VibeFormInput`, ensuring that the Bootstrap `.input-group` classes apply correctly without extra wrapping divs breaking the layout.
+### Custom slots with a button
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const term = ref('')
+</script>
+
+<template>
+  <VibeInputGroup>
+    <VibeFormInput v-model="term" placeholder="Search" no-wrapper />
+    <template #append>
+      <VibeButton variant="primary">Go</VibeButton>
+    </template>
+  </VibeInputGroup>
+</template>
+```
+
+## Important Notes
+
+- **Use `no-wrapper` on the input:** pass `no-wrapper` to `VibeFormInput` so it renders just the `<input>` and Bootstrap can style it as part of the group.
+- **Slots override props:** providing the `prepend`/`append` slots replaces the corresponding text props.
+
+## Bootstrap CSS Classes
+
+- `.input-group`
+- `.input-group-{sm|lg}`
+- `.input-group-text`