@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/forms/autocomplete.md

@@ -0,0 +1,96 @@
+# VibeAutocomplete
+
+Search-as-you-type input backed by an array or async source, with keyboard navigation. Generic over the item type `T`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string` | `''` | The text value of the input (v-model). |
+| `source` | `T[] \| (query: string) => T[] \| Promise<T[]>` | — (required) | Array to filter, or a function returning matches (sync or async). |
+| `itemText` | `(item: T) => string` | `undefined` | Maps an item to its display/filter text. Defaults to the string form of the item. |
+| `minChars` | `number` | `1` | Minimum characters before searching. |
+| `debounce` | `number` | `200` | Debounce in ms before running a query (`0` disables debouncing). |
+| `maxResults` | `number` | `10` | Maximum number of results shown. |
+| `placeholder` | `string` | `''` | Placeholder text. |
+| `label` | `string` | `undefined` | Label text. |
+| `id` | `string` | auto-generated | Element id. |
+| `disabled` | `boolean` | `false` | Disable the input. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `string` | Emitted as the user types and when an item is selected. |
+| `select` | `T` | Emitted with the chosen item when a result is selected. |
+
+## Slots
+
+| Slot | Scope | Description |
+|------|-------|-------------|
+| `item` | `{ item: T, index: number, label: string }` | Custom rendering for each result row. |
+| `empty` | — | Content shown when there are no results. Defaults to "No results". |
+
+## Usage
+
+### Array source
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const query = ref('')
+const fruits = ['Apple', 'Apricot', 'Banana', 'Cherry', 'Mango']
+</script>
+
+<template>
+  <VibeAutocomplete v-model="query" :source="fruits" label="Fruit" />
+</template>
+```
+
+### Async source with typed items
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+
+interface User { id: number; name: string }
+const value = ref('')
+
+const search = async (q: string): Promise<User[]> => {
+  const res = await fetch(`/api/users?q=${encodeURIComponent(q)}`)
+  return res.json()
+}
+
+const onSelect = (user: User) => console.log('picked', user.id)
+</script>
+
+<template>
+  <VibeAutocomplete
+    v-model="value"
+    :source="search"
+    :item-text="(u) => u.name"
+    :min-chars="2"
+    label="Assignee"
+    @select="onSelect"
+  >
+    <template #item="{ item }">
+      <strong>{{ item.name }}</strong> <small class="text-muted">#{{ item.id }}</small>
+    </template>
+    <template #empty>No users found</template>
+  </VibeAutocomplete>
+</template>
+```
+
+## Important Notes
+
+- **Async race-safety:** in-flight async queries are token-guarded, so only the latest query's results are applied.
+- **Keyboard support:** Arrow Up/Down move the highlight, Enter selects, Escape closes the menu. The combobox exposes `aria-expanded`, `aria-controls`, and `aria-activedescendant`.
+- **Selection text:** selecting an item sets the input to the item's `itemText` (or string) value and emits both `update:modelValue` and `select`.
+- **Outside click:** clicking outside the component closes the menu.
+
+## Bootstrap CSS Classes
+
+- `.form-control`
+- `.form-label`
+
+The dropdown menu, items, and empty state use VibeUI's own `.vibe-autocomplete*` classes (styled with Bootstrap CSS variables).

package/docs/forms/file-input.md

@@ -0,0 +1,97 @@
+# VibeFileInput
+
+File attachment input with optional drag-and-drop zone. `v-model` exposes the selected files as `File[]`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `File[]` | `[]` | The accepted files (v-model). |
+| `id` | `string` | auto-generated | Element id. |
+| `label` | `string` | `undefined` | Label text. |
+| `multiple` | `boolean` | `false` | Allow selecting multiple files. |
+| `accept` | `string` | `undefined` | Comma-separated MIME types and/or extensions (e.g. `image/*,.pdf`). Used both as the native filter and for rejection. |
+| `maxSize` | `number` | `undefined` | Maximum file size in bytes; larger files are rejected. |
+| `dragDrop` | `boolean` | `false` | Render a drag-and-drop zone instead of the native control. |
+| `disabled` | `boolean` | `false` | Disable the input. |
+| `size` | `'sm' \| 'lg'` | `undefined` | Control size (native control only). |
+| `helpText` | `string` | `undefined` | Help text below the input. |
+| `dropzoneText` | `string` | `'Drag files here or click to browse'` | Text shown inside the drop zone. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `File[]` | Emitted with the accepted files. |
+| `change` | `File[]` | Emitted with the accepted files (mirrors `update:modelValue`). |
+| `invalid` | `File[]` | Emitted with files rejected by `accept` or `maxSize`. |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `dropzone` | Custom content for the drop zone (only when `dragDrop` is set). |
+
+## Exposed methods
+
+| Method | Description |
+|--------|-------------|
+| `clearFiles()` | Clears the native input and emits an empty selection. |
+
+## Usage
+
+### Native input
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const files = ref<File[]>([])
+</script>
+
+<template>
+  <VibeFileInput
+    v-model="files"
+    label="Attachment"
+    accept="image/*,.pdf"
+    :max-size="5 * 1024 * 1024"
+    help-text="Images or PDF, up to 5 MB."
+  />
+</template>
+```
+
+### Drag-and-drop with rejection handling
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const files = ref<File[]>([])
+
+const onInvalid = (rejected: File[]) => {
+  console.warn('Rejected:', rejected.map((f) => f.name))
+}
+</script>
+
+<template>
+  <VibeFileInput
+    v-model="files"
+    multiple
+    drag-drop
+    accept="image/*"
+    :max-size="2 * 1024 * 1024"
+    @invalid="onInvalid"
+  />
+</template>
+```
+
+## Important Notes
+
+- **Same-file reselection:** the native input is reset after each change so picking the same file again still fires `change`.
+- **Rejection:** files failing `accept` or exceeding `maxSize` are excluded from the model and reported via the `invalid` event.
+- **Drag safety:** a document-level fallback resets the dragging state if a drag ends or drops outside the zone.
+
+## Bootstrap CSS Classes
+
+- `.form-control`, `.form-control-{sm|lg}`
+- `.form-label`, `.form-text`
+
+The drop zone uses VibeUI's own `.vibe-file-input-dropzone*` classes.

package/docs/forms/form-checkbox.md

@@ -1,8 +1,44 @@
 # VibeFormCheckbox
 
-Checkbox component for single boolean values or multiple selections.
+Checkbox for a single boolean value or as part of a grouped multi-select (array model).
 
-## Basic Usage
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `boolean \| string \| number \| (string \| number \| boolean)[]` | `false` | v-model. A boolean (or `value`/`uncheckedValue`) for single checkboxes; an array for grouped checkboxes. |
+| `value` | `string \| number \| boolean` | `true` | Value emitted/added to the array when checked. |
+| `uncheckedValue` | `string \| number \| boolean` | `false` | Value emitted when unchecked (non-array model only). |
+| `id` | `string` | auto-generated | Element id. Auto-generated, or inherited from a parent `VibeFormGroup`. |
+| `label` | `string` | `undefined` | Checkbox label text. |
+| `disabled` | `boolean` | `false` | Disable the checkbox. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `inline` | `boolean` | `false` | Render inline (`.form-check-inline`). |
+| `indeterminate` | `boolean` | `false` | Show the indeterminate (mixed) state. |
+| `reverse` | `boolean` | `false` | Place the label before the checkbox (`.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 checkbox. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `update:modelValue` | `boolean \| string \| number \| (string \| number \| boolean)[]` | Emitted on toggle. Array result when the model is an array. |
+| `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
+
+### Single checkbox
 
 ```vue
 <script setup lang="ts">
@@ -10,41 +46,55 @@ import { ref } from 'vue'
 const agreed = ref(false)
 </script>
 
+<template>
+  <VibeFormCheckbox v-model="agreed" label="I accept the terms" />
+</template>
+```
+
+### Custom checked / unchecked values
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const status = ref('off')
+</script>
+
 <template>
   <VibeFormCheckbox
-    v-model="agreed"
-    label="I agree to the terms"
+    v-model="status"
+    value="on"
+    unchecked-value="off"
+    label="Enable feature"
   />
 </template>
 ```
 
-## Props
+### Grouped checkboxes (array model)
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `modelValue` | `any` | `false` | The checked state (v-model) |
-| `value` | `any` | `true` | Value when checked |
-| `id` | `String` | `Auto-generated` | Unique identifier |
-| `label` | `String` | `undefined` | Label text |
-| `disabled` | `Boolean` | `false` | Disable the checkbox |
-| `required` | `Boolean` | `false` | Mark as required |
-| `inline` | `Boolean` | `false` | Display inline |
-| `indeterminate` | `Boolean` | `false` | Set indeterminate state |
-| `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 selected = ref<string[]>([])
+</script>
 
-## Important Notes
+<template>
+  <VibeFormGroup label="Interests">
+    <VibeFormCheckbox v-model="selected" value="vue" label="Vue" />
+    <VibeFormCheckbox v-model="selected" value="ts" label="TypeScript" />
+    <VibeFormCheckbox v-model="selected" value="css" label="CSS" />
+  </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.
+- **Array vs. single model:** if `modelValue` is an array, checking adds `value` and unchecking removes it. Otherwise the model toggles between `value` and `uncheckedValue`.
+- **Indeterminate:** purely visual; it does not change the checked value and is reset once the user toggles.
+- **Group linking:** in a grouped layout, the first checkbox consumes the `VibeFormGroup` id; subsequent checkboxes 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-datepicker.md

@@ -1,50 +1,80 @@
 # VibeFormDatepicker
 
-Date and time input component using native browser pickers.
+Date, time, and datetime input using the native browser pickers, with built-in validation and accessibility.
 
-## Basic Usage
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `modelValue` | `string` | `''` | The value (v-model) as an ISO-style string matching the chosen `type` (e.g. `2026-05-28`). |
+| `type` | `'date' \| 'time' \| 'datetime-local' \| 'month' \| 'week'` | `'date'` | Native picker type. |
+| `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 input. |
+| `readonly` | `boolean` | `false` | Make the input read-only. |
+| `required` | `boolean` | `false` | Mark as required. |
+| `min` | `string` | `undefined` | Minimum allowed value. |
+| `max` | `string` | `undefined` | Maximum allowed value. |
+| `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 input. |
+
+## 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 date = ref('')
+const startDate = ref('')
 </script>
 
 <template>
-  <VibeFormDatepicker
-    v-model="date"
-    label="Choose a date"
-  />
+  <VibeFormGroup label="Start Date">
+    <VibeFormDatepicker v-model="startDate" type="date" min="2026-01-01" />
+  </VibeFormGroup>
 </template>
 ```
 
-## Props
+### Standalone
 
-| 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 |
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const meetingTime = ref('')
+</script>
 
-## Important Notes
+<template>
+  <VibeFormDatepicker v-model="meetingTime" label="Meeting Time" type="datetime-local" />
+</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.
+- **String model only:** `modelValue` must be a string. When using a validation composable, bind to `.value` (e.g. `v-model="field.value"`), not the field object — a dev-mode warning is logged otherwise.
+- **Native pickers:** rendering and locale formatting come from the browser's native input, so the on-screen appearance varies by platform.
+- **Group linking:** wrapped in a `VibeFormGroup`, the input 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`

package/docs/forms/form-group.md

@@ -1,10 +1,39 @@
 # VibeFormGroup
 
-Form group container component for organizing form fields with labels, help text, and validation feedback.
+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.
 
-## Basic Usage
+## How it works
 
-VibeFormGroup automatically links its label to the child VibeUI form component using automatic ID injection.
+`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` | Append a `*` to the label. |
+| `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">
@@ -13,68 +42,74 @@ 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 label="Email" help-text="We'll never share it.">
+    <VibeFormInput v-model="email" type="email" />
   </VibeFormGroup>
 </template>
 ```
 
-## Floating Labels
+### 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="Email Address"
-    floating
+    label="Name"
+    required
+    :validation-state="name.validationState"
+    :validation-message="name.validationMessage"
   >
-    <VibeFormInput
-      v-model="email"
-      type="email"
-      placeholder="name@example.com"
-    />
+    <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>
 ```
 
-## Horizontal Layout
+### Floating label
 
 ```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const city = ref('')
+</script>
+
 <template>
-  <VibeFormGroup
-    label="Email"
-    row
-    :label-cols="3"
-    label-align="end"
-  >
-    <VibeFormInput v-model="email" type="email" />
+  <VibeFormGroup label="City" floating>
+    <VibeFormInput v-model="city" placeholder="City" />
   </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.
+- **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.
 
-## Props
+## Bootstrap CSS Classes
 
-| 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 |
+- `.mb-3`, `.row`
+- `.form-floating`
+- `.form-label`, `.col-form-label`, `.col-sm-{n}`, `.text-{start|center|end}`
+- `.form-text`
+- `.valid-feedback`, `.invalid-feedback`