@velkymx/vibeui 0.9.0 → 1.1.0

package/docs/directives/v-tooltip.md

@@ -0,0 +1,58 @@
+# v-vibe-tooltip
+
+Inline tooltip directive. Equivalent to `<VibeTooltip>` but applied directly to the element, without a wrapper. Useful when adding tooltips to existing markup or many small elements (icons, button labels) where wrapping each is noisy.
+
+Registered globally by `app.use(VibeUI)`.
+
+## Usage
+
+```vue
+<template>
+  <!-- String binding: tooltip title -->
+  <button v-vibe-tooltip="'Save changes'">
+    <VibeIcon name="save" />
+  </button>
+
+  <!-- Options object -->
+  <span v-vibe-tooltip="{ title: 'New tab', placement: 'right' }">
+    <VibeIcon name="external-link" />
+  </span>
+</template>
+```
+
+## Binding values
+
+| Type | Behavior |
+|------|----------|
+| `string` | Sets the tooltip `title` |
+| `{ title, placement, trigger }` | Full options |
+| `undefined` | Renders nothing useful, but does not throw |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `title` | `string` | — | Tooltip body. Aliases: `text`, `content` (whichever is set first wins) |
+| `placement` | `TooltipPlacement` | `'top'` | Bootstrap placement |
+| `trigger` | `string` | `'hover focus'` | Auto-swaps to `'click'` on touch devices |
+
+> Tooltip content is always rendered as plain text (`html: false`). HTML in `title` is escaped; there is no `html` option on this directive.
+
+## Direct import
+
+For component-local registration without the plugin:
+
+```ts
+import { vTooltip } from '@velkymx/vibeui'
+
+export default {
+  directives: { 'vibe-tooltip': vTooltip }
+}
+```
+
+## When to use the component instead
+
+`<VibeTooltip>` is better when:
+- You want the tooltip body to come from a slot (rich content rather than a string).
+- The triggering element is itself a slot of another component and you can't access it to bind a directive.
+- You need imperative show/hide via the component's escape-hatch instance (`_unsafe_bsInstance`).

package/docs/forms/README.md

@@ -0,0 +1,87 @@
+# VibeUI Form Components
+
+Form controls with built-in validation, accessibility, and Bootstrap 5.3 styling.
+
+## Overview
+
+VibeUI form controls integrate with Bootstrap and include validation and accessibility out of the box.
+
+### Features
+
+- **Bootstrap 5.3 styling** via native classes
+- **Zero-boilerplate ids** — `id` props are optional and auto-generated
+- **Accessible by default** — `VibeFormGroup` auto-links labels, help text, and feedback to its first child control
+- **Two-way binding** with `v-model` on every control
+- **Validation** — `useFormValidation`, `useForm`, and built-in `validators`
+- **Fully typed** props, events, and APIs
+
+## Recommended pattern: VibeFormGroup
+
+Wrap a control in `VibeFormGroup` to auto-generate the id and wire the `<label>`, `aria-describedby`, help text, and validation feedback. The first child control consumes the group id (single-consumer rule).
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const email = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Email Address" help-text="We'll never share it.">
+    <VibeFormInput v-model="email" type="email" placeholder="Enter email" />
+  </VibeFormGroup>
+</template>
+```
+
+## Components
+
+### Inputs
+
+| Component | Description | Docs |
+|-----------|-------------|------|
+| VibeFormInput | Text, email, password, number, and other input types | [form-input.md](./form-input.md) |
+| VibeInputGroup | Prepend/append text, buttons, or elements | [input-group.md](./input-group.md) |
+| VibeFormTextarea | Multi-line text with optional char count | [form-textarea.md](./form-textarea.md) |
+| VibeFormSelect | Single and multiple selection | [form-select.md](./form-select.md) |
+| VibeFormSpinbutton | Number input with increment/decrement | [form-spinbutton.md](./form-spinbutton.md) |
+| VibeFormDatepicker | Date, time, and datetime inputs | [form-datepicker.md](./form-datepicker.md) |
+| VibeAutocomplete | Search-as-you-type with array/async source | [autocomplete.md](./autocomplete.md) |
+| VibeFileInput | File picker with optional drag-and-drop | [file-input.md](./file-input.md) |
+
+### Choice controls
+
+| Component | Description | Docs |
+|-----------|-------------|------|
+| VibeFormCheckbox | Single checkbox or checkbox group | [form-checkbox.md](./form-checkbox.md) |
+| VibeFormRadio | Radio button groups | [form-radio.md](./form-radio.md) |
+| VibeFormSwitch | Toggle switch | [form-switch.md](./form-switch.md) |
+
+### Advanced
+
+| Component | Description | Docs |
+|-----------|-------------|------|
+| VibeFormWysiwyg | Rich-text editor (requires `quill` + `dompurify`) | [form-wysiwyg.md](./form-wysiwyg.md) |
+| VibeFormGroup | Layout + automatic label/id/feedback linking | [form-group.md](./form-group.md) |
+
+## Validation
+
+See the [Validation Guide](./validation.md) for `useFormValidation`, `useForm`, the built-in `validators`, and async/API 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>
+```

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

@@ -0,0 +1,100 @@
+# VibeFormCheckbox
+
+Checkbox for a single boolean value or as part of a grouped multi-select (array model).
+
+## 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">
+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="status"
+    value="on"
+    unchecked-value="off"
+    label="Enable feature"
+  />
+</template>
+```
+
+### Grouped checkboxes (array model)
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const selected = ref<string[]>([])
+</script>
+
+<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>
+```
+
+## Important Notes
+
+- **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-inline`, `.form-check-reverse`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-datepicker.md

@@ -0,0 +1,80 @@
+# VibeFormDatepicker
+
+Date, time, and datetime input using the native browser pickers, with built-in validation and accessibility.
+
+## 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 startDate = ref('')
+</script>
+
+<template>
+  <VibeFormGroup label="Start Date">
+    <VibeFormDatepicker v-model="startDate" type="date" min="2026-01-01" />
+  </VibeFormGroup>
+</template>
+```
+
+### Standalone
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+const meetingTime = ref('')
+</script>
+
+<template>
+  <VibeFormDatepicker v-model="meetingTime" label="Meeting Time" type="datetime-local" />
+</template>
+```
+
+## Important Notes
+
+- **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-{sm|lg}`
+- `.is-valid`, `.is-invalid`

package/docs/forms/form-error-summary.md

@@ -0,0 +1,96 @@
+# VibeFormErrorSummary
+
+Top-of-form error summary that lists all field errors in one place with links to the offending fields. Satisfies WCAG 3.3.1 (Error Identification) for forms with multiple validation errors.
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `errors` | `Record<string, string>` | yes | Map of field name → error message. Entries with an empty string are ignored. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `focus` | `string` | Emitted when the user clicks an error link. Payload is the field key. Use it to programmatically focus the field. |
+
+## Slots
+
+None.
+
+## Usage
+
+### Basic
+
+```vue
+<script setup lang="ts">
+import { reactive } from 'vue'
+
+const errors = reactive<Record<string, string>>({
+  email: '',
+  password: '',
+})
+
+function handleSubmit() {
+  errors.email = ''
+  errors.password = ''
+  if (!form.email) errors.email = 'Email is required.'
+  if (!form.password) errors.password = 'Password must be at least 8 characters.'
+}
+
+function focusField(key: string) {
+  document.getElementById(`field-${key}`)?.focus()
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <VibeFormErrorSummary :errors="errors" @focus="focusField" />
+
+    <VibeFormGroup label="Email" required :validation-state="errors.email ? 'invalid' : null" :validation-message="errors.email">
+      <VibeFormInput id="field-email" v-model="form.email" type="email" autocomplete="email" />
+    </VibeFormGroup>
+
+    <VibeFormGroup label="Password" required :validation-state="errors.password ? 'invalid' : null" :validation-message="errors.password">
+      <VibeFormInput id="field-password" v-model="form.password" type="password" autocomplete="current-password" />
+    </VibeFormGroup>
+
+    <VibeButton type="submit" variant="primary">Sign in</VibeButton>
+  </form>
+</template>
+```
+
+### With useForm
+
+```vue
+<script setup lang="ts">
+import { useForm, validators } from '@velkymx/vibeui'
+
+const { fields, errors, handleSubmit } = useForm({
+  email: { value: '', rules: [validators.required(), validators.email()] },
+  password: { value: '', rules: [validators.required(), validators.minLength(8)] },
+})
+
+function focusField(key: string) {
+  document.getElementById(`field-${key}`)?.focus()
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <VibeFormErrorSummary :errors="errors" @focus="focusField" />
+    <!-- fields … -->
+  </form>
+</template>
+```
+
+## Important Notes
+
+- **Anchor convention:** error links use `href="#field-{key}"`. Set `:id="\`field-${key}\`"` on each input so the links resolve (and so `focusField` can look them up). The component itself does not set these ids — you control the field ids.
+- **`role="alert"` (WCAG 4.1.3):** the container carries `role="alert" aria-live="polite"` so screen readers announce the error list automatically when errors appear, without requiring focus.
+- **Auto-hides when clean:** when all `errors` values are empty strings the summary renders nothing. No need to conditionally mount it.
+- **`@focus` vs native anchor:** the `@click.prevent` on each link suppresses the default scroll-to-anchor jump and lets you implement the focus strategy (e.g. scroll + focus, or open a collapsed section first).
+
+## Bootstrap CSS Classes
+
+- `.alert`, `.alert-danger`