@velkymx/vibeui 0.9.0 → 1.1.0

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.

package/docs/forms/input-group.md

@@ -0,0 +1,70 @@
+# VibeInputGroup
+
+Wraps a control with prepended/appended text, buttons, or other elements using Bootstrap's input-group.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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 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). |
+
+## Usage
+
+### Text prepend / append
+
+```vue
+<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>
+```
+
+### 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`

package/docs/forms/validation.md

@@ -0,0 +1,213 @@
+# Form Validation
+
+VibeUI ships a validation system for all form components, supporting synchronous and asynchronous rules. Use it with the `useFormValidation` composable (single field), the `useForm` composable (whole form), or by passing rule results directly.
+
+## Built-in Validators
+
+```ts
+import { validators } from '@velkymx/vibeui'
+```
+
+Each validator returns a `ValidationRule`. A validator function returns `true` for valid, `false` to use the rule's `message`, or a non-empty `string` as the error message. Most validators skip empty values — pair them with `required()` to make a field mandatory.
+
+| Validator | Signature | Description |
+|-----------|-----------|-------------|
+| `required` | `(message?)` | Non-empty value (also checks array length). |
+| `email` | `(message?)` | Valid email format. |
+| `minLength` | `(min, message?)` | String length ≥ `min`. |
+| `maxLength` | `(max, message?)` | String length ≤ `max`. |
+| `min` | `(min, message?)` | Numeric value ≥ `min`. |
+| `max` | `(max, message?)` | Numeric value ≤ `max`. |
+| `pattern` | `(regex, message?)` | Matches the regex. |
+| `url` | `(message?)` | Parses as a valid URL. |
+| `async` | `(fn)` | Wraps an async validator `(value) => Promise<boolean \| string>`. |
+
+```ts
+const rules = [
+  validators.required('Email is required'),
+  validators.email()
+]
+```
+
+## Custom Rules
+
+A rule is `{ validator, message? }`. The validator may be sync or async.
+
+```ts
+const passwordStrength = {
+  validator: (value: unknown) => {
+    const v = String(value ?? '')
+    if (!v) return true
+    if (!/[A-Z]/.test(v)) return 'Needs an uppercase letter'
+    if (!/\d/.test(v)) return 'Needs a number'
+    return true
+  }
+}
+
+const rules = [validators.required(), validators.minLength(8), passwordStrength]
+```
+
+## Single-field validation: `useFormValidation`
+
+```ts
+import { useFormValidation } from '@velkymx/vibeui'
+
+const field = useFormValidation('')   // initial value
+```
+
+Returns:
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `value` | `Ref` | The field value (bind with `v-model="field.value"`). |
+| `validationState` | `Ref<'valid' \| 'invalid' \| null>` | Current state. |
+| `validationMessage` | `Ref<string>` | Current message. |
+| `isDirty` | `Ref<boolean>` | Set via `markAsDirty()`. |
+| `isTouched` | `Ref<boolean>` | Set via `markAsTouched()`. |
+| `isValidating` | `Ref<boolean>` | True while an async rule is running. |
+| `isValid` | `ComputedRef<boolean>` | `validationState === 'valid'`. |
+| `isInvalid` | `ComputedRef<boolean>` | `validationState === 'invalid'`. |
+| `validate(rules)` | `(rules) => Promise<FormValidationResult>` | Runs rules; concurrency-safe (only the latest call wins). |
+| `reset()` | `() => void` | Reset to initial value and clear state. |
+| `markAsTouched()` / `markAsDirty()` | `() => void` | Manual flag setters. |
+
+```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>
+```
+
+Editing an invalid field clears its `invalid` state automatically until you re-validate.
+
+## Whole-form validation: `useForm`
+
+```ts
+import { useForm } from '@velkymx/vibeui'
+
+const form = useForm({ username: '', email: '', age: 0 })
+```
+
+Returns:
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `fields` | reactive `T` | Form values; bind with `v-model="form.fields.x"`. |
+| `errors` | reactive map | Per-field error messages (`''` when valid). |
+| `touched` | reactive map | Per-field touched flags. |
+| `isDirty` | `ComputedRef<boolean>` | True once any field differs from its initial value. |
+| `isValid` | `ComputedRef<boolean>` | **`false` until the first `validate()`/`validateField()` call**, then reflects whether all errors are empty. |
+| `values` | `ComputedRef<T>` | Snapshot copy of `fields`. |
+| `validate(rules)` | `(rules) => Promise<{ valid, errors }>` | Validate the listed fields. |
+| `validateField(key, rule)` | `(key, rule) => Promise<string>` | Validate one field; returns its message. |
+| `reset()` | `() => void` | Restore initial values and clear errors/touched/validated state. |
+| `markTouched(key)` / `markAllTouched()` | — | Touched flag setters. |
+| `setField(key, value)` | — | Programmatically set a field. |
+
+```vue
+<script setup lang="ts">
+import { useForm, validators } from '@velkymx/vibeui'
+
+const form = useForm({ username: '', email: '', password: '' })
+
+const rules = {
+  username: [validators.required(), validators.minLength(3)],
+  email: [validators.required(), validators.email()],
+  password: [validators.required(), validators.minLength(8)]
+}
+
+const onSubmit = async () => {
+  const { valid } = await form.validate(rules)
+  if (valid) console.log('submit', form.values.value)
+}
+</script>
+
+<template>
+  <form @submit.prevent="onSubmit">
+    <VibeFormGroup label="Username" :validation-message="form.errors.username"
+      :validation-state="form.errors.username ? 'invalid' : null">
+      <VibeFormInput v-model="form.fields.username"
+        @validate="form.validateField('username', rules.username)" />
+    </VibeFormGroup>
+
+    <VibeFormGroup label="Email" :validation-message="form.errors.email"
+      :validation-state="form.errors.email ? 'invalid' : null">
+      <VibeFormInput v-model="form.fields.email" type="email"
+        @validate="form.validateField('email', rules.email)" />
+    </VibeFormGroup>
+
+    <VibeFormGroup label="Password" :validation-message="form.errors.password"
+      :validation-state="form.errors.password ? 'invalid' : null">
+      <VibeFormInput v-model="form.fields.password" type="password"
+        @validate="form.validateField('password', rules.password)" />
+    </VibeFormGroup>
+
+    <VibeButton type="submit" variant="primary" :disabled="!form.isValid">
+      Register
+    </VibeButton>
+  </form>
+</template>
+```
+
+## When validation runs: `validateOn`
+
+Form controls emit `validate` based on `validateOn`:
+
+- Text-like controls (input, textarea, datepicker, spinbutton, wysiwyg): `'input' \| 'blur' \| 'change'`, default `'blur'`.
+- Choice controls (checkbox, radio, switch, select): `'change' \| 'blur'`, default `'change'`.
+
+Wire `@validate` to your validation call:
+
+```vue
+<VibeFormInput v-model="field.value" validate-on="input" @validate="run" />
+```
+
+## Async / API Validation
+
+`validators.async` runs an async check (e.g. uniqueness). Because `useFormValidation.validate` is concurrency-safe, only the latest call applies its result.
+
+```vue
+<script setup lang="ts">
+import { useFormValidation, validators } from '@velkymx/vibeui'
+
+const username = useFormValidation('')
+
+const isAvailable = validators.async(async (value) => {
+  const res = await fetch(`/api/check-username?u=${encodeURIComponent(String(value))}`)
+  const data = await res.json()
+  return data.available || 'Username is already taken'
+})
+
+const validateUsername = () =>
+  username.validate([validators.required(), validators.minLength(3), isAvailable])
+</script>
+
+<template>
+  <VibeFormGroup
+    label="Username"
+    :validation-state="username.validationState"
+    :validation-message="username.validationMessage"
+  >
+    <VibeFormInput v-model="username.value" @validate="validateUsername" />
+  </VibeFormGroup>
+</template>
+```
+
+## Notes
+
+- **`useForm.isValid` starts `false`** and only becomes meaningful after the first validation runs — safe to use for disabling a submit button before any input.
+- **Editing clears `invalid`** (in `useFormValidation`) so messages don't linger while the user fixes the field.
+- **Empty-value skipping:** most validators pass on empty values; add `required()` to enforce presence.

package/docs/getting-started/starter-template.md

@@ -0,0 +1,136 @@
+# Starter Template
+
+A complete, copy-pasteable minimal VibeUI app showing the recommended setup and patterns. Everything below runs as-is — no placeholders.
+
+## Install
+
+```bash
+npm install @velkymx/vibeui bootstrap
+```
+
+### Optional peer dependencies
+
+Install these only if you use the components that need them:
+
+- `bootstrap-icons` — required by `VibeIcon`.
+- `quill` + `dompurify` — required by `VibeFormWysiwyg`.
+
+```bash
+npm install bootstrap-icons         # for VibeIcon
+npm install quill dompurify         # for VibeFormWysiwyg
+```
+
+## `main.ts`
+
+Register the plugin, import Bootstrap's CSS, and restore the saved color-mode preference **before** mounting so the theme is correct on first paint.
+
+```ts
+import { createApp } from 'vue'
+import VibeUI, { useColorMode } from '@velkymx/vibeui'
+import 'bootstrap/dist/css/bootstrap.min.css'
+import App from './App.vue'
+
+// Restore the saved light/dark/auto preference and attach the OS-theme listener.
+useColorMode().initColorMode()
+
+createApp(App).use(VibeUI).mount('#app')
+```
+
+> **Do NOT import Bootstrap JS — VibeUI manages it.** Importing `bootstrap` (the JS bundle) yourself can create duplicate component instances and event conflicts. VibeUI loads and disposes Bootstrap's JS internally. You only import Bootstrap's **CSS**.
+
+## `App.vue`
+
+Mount `<VibeToastHost />` once at the root so `useToast()` works anywhere. The example below wires `useForm` validation into a `<VibeFormGroup>` + `<VibeFormInput>`, shows a confirmation in a `<VibeModal v-model>`, and fires a toast on submit.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { useForm, useToast, validators } from '@velkymx/vibeui'
+
+const toast = useToast()
+
+const { fields, errors, validate, reset } = useForm({
+  name: '',
+  email: '',
+})
+
+const showConfirm = ref(false)
+
+const onSubmit = async () => {
+  const result = await validate({
+    name: [validators.required('Name is required')],
+    email: [validators.required('Email is required'), validators.email()],
+  })
+  if (!result.valid) return
+  showConfirm.value = true
+}
+
+const confirm = () => {
+  showConfirm.value = false
+  toast.success(`Welcome, ${fields.name}!`)
+  reset()
+}
+</script>
+
+<template>
+  <VibeContainer class="py-4" style="max-width: 480px;">
+    <h1 class="mb-4">Sign up</h1>
+
+    <form @submit.prevent="onSubmit">
+      <VibeFormGroup label="Name">
+        <VibeFormInput
+          v-model="fields.name"
+          placeholder="Jane Doe"
+          :validation-state="errors.name ? 'invalid' : null"
+          :validation-message="errors.name"
+        />
+      </VibeFormGroup>
+
+      <VibeFormGroup label="Email" class="mt-3">
+        <VibeFormInput
+          v-model="fields.email"
+          type="email"
+          placeholder="jane@example.com"
+          :validation-state="errors.email ? 'invalid' : null"
+          :validation-message="errors.email"
+        />
+      </VibeFormGroup>
+
+      <VibeButton type="submit" variant="primary" class="mt-4">
+        Create account
+      </VibeButton>
+    </form>
+
+    <VibeModal v-model="showConfirm" title="Confirm details" centered>
+      <p>Create an account for <strong>{{ fields.email }}</strong>?</p>
+      <template #footer>
+        <VibeButton variant="secondary" @click="showConfirm = false">Cancel</VibeButton>
+        <VibeButton variant="primary" @click="confirm">Confirm</VibeButton>
+      </template>
+    </VibeModal>
+
+    <!-- Mount once at the app root; renders the global toast queue. -->
+    <VibeToastHost />
+  </VibeContainer>
+</template>
+```
+
+> `isValid` is `false` until the first `validate()` call, so gate submit on the `validate()` result (as above) rather than disabling the button by `isValid` alone.
+
+## Recommended project structure
+
+```
+src/
+  main.ts            # createApp + plugin + initColorMode (before mount)
+  App.vue            # app shell; mounts <VibeToastHost /> once
+  components/        # your reusable components
+  composables/       # app-specific composables (useForm wrappers, etc.)
+  views/             # route-level pages (if using vue-router)
+```
+
+Keep cross-app concerns at the root: `<VibeToastHost />` belongs in `App.vue`, and `initColorMode()` belongs in `main.ts` — both should appear exactly once.
+
+## Coming from BootstrapVue?
+
+The mental model is familiar — component-per-feature, data-driven `items` arrays, `v-model` for visibility/value, and props-based styling (`variant`, `size`) — but VibeUI is **not** a drop-in port. Component and prop names differ (`Vibe*` prefix), Bootstrap JS is managed for you, and interactive components lean on `v-model`. Use the [component docs](../README.md#components) to map features rather than expecting identical APIs.
+```