@velkymx/vibeui 0.9.0 → 1.0.2

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.
+```