@velkymx/vibeui 0.8.1 → 0.8.2

package/docs/forms/form-datepicker.md

@@ -0,0 +1,50 @@
+# VibeFormDatepicker
+
+Date and time input component using native browser pickers.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const date = ref('')
+</script>
+
+<template>
+  <VibeFormDatepicker
+    v-model="date"
+    label="Choose a date"
+  />
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `String` | `''` | The date string (v-model) |
+| `id` | `String` | `Auto-generated` | Unique identifier |
+| `label` | `String` | `undefined` | Label text |
+| `disabled` | `Boolean` | `false` | Disable the picker |
+| `readonly` | `Boolean` | `false` | Make readonly |
+| `required` | `Boolean` | `false` | Mark as required |
+| `min` | `String` | `undefined` | Minimum date |
+| `max` | `String` | `undefined` | Maximum date |
+| `size` | `'sm' \| 'lg'` | `undefined` | Picker size |
+| `type` | `String` | `'date'` | Type: `'date'`, `'time'`, `'datetime-local'`, etc. |
+| `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.
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.form-control-{size}`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-group.md

@@ -0,0 +1,80 @@
+# VibeFormGroup
+
+Form group container component for organizing form fields with labels, help text, and validation feedback.
+
+## Basic Usage
+
+VibeFormGroup automatically links its label to the child VibeUI form component using automatic ID injection.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const email = ref('')
+</script>
+
+<template>
+  <VibeFormGroup
+    label="Email Address"
+    help-text="We'll never share your email with anyone else."
+  >
+    <VibeFormInput
+      v-model="email"
+      type="email"
+      placeholder="Enter email"
+    />
+  </VibeFormGroup>
+</template>
+```
+
+## Floating Labels
+
+```vue
+<template>
+  <VibeFormGroup
+    label="Email Address"
+    floating
+  >
+    <VibeFormInput
+      v-model="email"
+      type="email"
+      placeholder="name@example.com"
+    />
+  </VibeFormGroup>
+</template>
+```
+
+## Horizontal Layout
+
+```vue
+<template>
+  <VibeFormGroup
+    label="Email"
+    row
+    :label-cols="3"
+    label-align="end"
+  >
+    <VibeFormInput v-model="email" type="email" />
+  </VibeFormGroup>
+</template>
+```
+
+## Important Notes
+
+**Automatic ID Injection:** VibeFormGroup uses Vue's provide/inject to share a unique ID with its child VibeUI components (like `VibeFormInput`, `VibeFormSelect`, etc.). This ensures that labels and ARIA attributes are correctly linked without requiring manual `id` or `label-for` props.
+
+**Manual Linking:** If you are using native HTML elements instead of VibeUI components inside the group, you must still provide a `label-for` on the group and a matching `id` on your element.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `String` | `undefined` | Label text |
+| `labelFor` | `String` | `Auto-generated` | ID of the form control |
+| `required` | `Boolean` | `false` | Show required asterisk |
+| `validationState` | `'valid' \| 'invalid' \| null` | `null` | Validation state |
+| `validationMessage` | `String` | `undefined` | Validation message |
+| `helpText` | `String` | `undefined` | Help text |
+| `floating` | `Boolean` | `false` | Use floating label layout |
+| `row` | `Boolean` | `false` | Use horizontal row layout |
+| `labelCols` | `Number \| String` | `undefined` | Number of columns for label (1-12) |
+| `labelAlign` | `'start' \| 'center' \| 'end'` | `undefined` | Label text alignment |

package/docs/forms/form-input.md

@@ -0,0 +1,55 @@
+# VibeFormInput
+
+Text input component with built-in validation support for various input types.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const name = ref('')
+</script>
+
+<template>
+  <VibeFormInput
+    v-model="name"
+    label="Full Name"
+    placeholder="Enter your name"
+  />
+</template>
+```
+
+## Props
+
+| 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 |
+
+## 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.
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.form-control-{size}`
+- `.is-valid`, `.is-invalid`
+- `.form-control-plaintext`
+- `.focus-ring`

package/docs/forms/form-radio.md

@@ -0,0 +1,58 @@
+# VibeFormRadio
+
+Radio button component for exclusive selection within a group.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const picked = ref('one')
+</script>
+
+<template>
+  <VibeFormRadio
+    v-model="picked"
+    name="myGroup"
+    value="one"
+    label="Option One"
+  />
+  <VibeFormRadio
+    v-model="picked"
+    name="myGroup"
+    value="two"
+    label="Option Two"
+  />
+</template>
+```
+
+## Props
+
+| 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 |
+
+## 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.
+
+## Bootstrap CSS Classes
+
+- `.form-check`
+- `.form-check-input`
+- `.form-check-label`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-select.md

@@ -0,0 +1,54 @@
+# VibeFormSelect
+
+Custom select component with support for single and multiple selection.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const selected = ref('')
+const options = [
+  { value: '1', text: 'Option 1' },
+  { value: '2', text: 'Option 2' }
+]
+</script>
+
+<template>
+  <VibeFormSelect
+    v-model="selected"
+    label="Choose an option"
+    :options="options"
+  />
+</template>
+```
+
+## Props
+
+| 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 |
+
+## 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.
+
+## Bootstrap CSS Classes
+
+- `.form-select`
+- `.form-select-{size}`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-spinbutton.md

@@ -0,0 +1,55 @@
+# VibeFormSpinbutton
+
+Numeric input component with increment and decrement buttons.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const count = ref(0)
+</script>
+
+<template>
+  <VibeFormSpinbutton
+    v-model="count"
+    label="Quantity"
+    :min="0"
+    :max="10"
+  />
+</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.
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.input-group`
+- `.btn`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-switch.md

@@ -0,0 +1,47 @@
+# VibeFormSwitch
+
+Toggle switch component for boolean values.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const isEnabled = ref(false)
+</script>
+
+<template>
+  <VibeFormSwitch
+    v-model="isEnabled"
+    label="Enable notifications"
+  />
+</template>
+```
+
+## Props
+
+| 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 |
+
+## 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.
+
+## Bootstrap CSS Classes
+
+- `.form-check`, `.form-switch`
+- `.form-check-input`
+- `.form-check-label`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-textarea.md

@@ -0,0 +1,51 @@
+# VibeFormTextarea
+
+Multi-line text input component.
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const text = ref('')
+</script>
+
+<template>
+  <VibeFormTextarea
+    v-model="text"
+    label="Comments"
+    placeholder="Enter your comments here..."
+  />
+</template>
+```
+
+## Props
+
+| 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 |
+
+## 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.
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.form-control-{size}`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-wysiwyg.md

@@ -0,0 +1,64 @@
+# VibeFormWysiwyg
+
+WYSIWYG (What You See Is What You Get) editor component powered by QuillJS.
+
+## Installation
+
+First, install Quill as a dependency:
+
+```bash
+npm install quill
+```
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const content = ref('')
+</script>
+
+<template>
+  <VibeFormWysiwyg
+    v-model="content"
+    label="Content"
+    placeholder="Write something amazing..."
+  />
+</template>
+```
+
+## Props
+
+| 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 |
+
+## Important Notes
+
+**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.
+
+**Lifecycle Management:** VibeFormWysiwyg automatically cleans up its internal Quill instance and removes orphaned toolbar elements from the DOM on unmount to prevent memory leaks.
+
+**Automatic ID Injection:** When used inside a `VibeFormGroup`, this component will automatically inherit the group's ID for proper label association.
+
+## Bootstrap CSS Classes
+
+- `.vibe-wysiwyg-container`
+- `.is-valid`
+- `.is-invalid`
+- Uses native Quill CSS classes internally.

package/docs/forms/input-group.md

@@ -0,0 +1,51 @@
+# 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>
+```
+
+## 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 |
+
+## 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 |
+
+## Advanced Example
+
+```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>
+```
+
+## 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.