@velkymx/vibeui 0.8.2 → 1.0.2

package/docs/forms/validation.md

@@ -1,599 +1,213 @@
 # Form Validation
 
-VibeUI provides a comprehensive validation system for all form components with support for both synchronous and asynchronous 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
 
-### Import
-
-```typescript
-import { validators } from '@velkymx/vibeui'
-```
-
-### Available Validators
-
-#### required()
-
-```typescript
-validators.required(message?: string)
-```
-
-Ensures the field has a value.
-
-```vue
-<script setup lang="ts">
+```ts
 import { validators } from '@velkymx/vibeui'
-
-const rules = [
-  validators.required('This field is required')
-]
-</script>
-```
-
-#### email()
-
-```typescript
-validators.email(message?: string)
-```
-
-Validates email format.
-
-```vue
-<script setup lang="ts">
-const rules = [
-  validators.email('Please enter a valid email address')
-]
-</script>
-```
-
-#### minLength()
-
-```typescript
-validators.minLength(min: number, message?: string)
-```
-
-Validates minimum string length.
-
-```vue
-<script setup lang="ts">
-const rules = [
-  validators.minLength(8, 'Password must be at least 8 characters')
-]
-</script>
-```
-
-#### maxLength()
-
-```typescript
-validators.maxLength(max: number, message?: string)
-```
-
-Validates maximum string length.
-
-```vue
-<script setup lang="ts">
-const rules = [
-  validators.maxLength(50, 'Username must not exceed 50 characters')
-]
-</script>
 ```
 
-#### min()
+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.
 
-```typescript
-validators.min(min: number, message?: string)
-```
-
-Validates minimum numeric value.
-
-```vue
-<script setup lang="ts">
-const rules = [
-  validators.min(18, 'You must be at least 18 years old')
-]
-</script>
-```
-
-#### max()
-
-```typescript
-validators.max(max: number, message?: string)
-```
-
-Validates maximum numeric value.
-
-```vue
-<script setup lang="ts">
-const rules = [
-  validators.max(120, 'Please enter a valid age')
-]
-</script>
-```
-
-#### pattern()
-
-```typescript
-validators.pattern(regex: RegExp, message?: string)
-```
-
-Validates against a custom regex pattern.
+| 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>`. |
 
-```vue
-<script setup lang="ts">
-const rules = [
-  validators.pattern(/^\d{5}$/, 'ZIP code must be 5 digits'),
-  validators.pattern(/^[A-Z]/, 'Must start with uppercase letter')
-]
-</script>
-```
-
-#### url()
-
-```typescript
-validators.url(message?: string)
-```
-
-Validates URL format.
-
-```vue
-<script setup lang="ts">
+```ts
 const rules = [
-  validators.url('Please enter a valid URL')
+  validators.required('Email is required'),
+  validators.email()
 ]
-</script>
-```
-
-#### async()
-
-```typescript
-validators.async(validatorFn: (value: any) => Promise<boolean | string>)
 ```
 
-Creates a custom async validator for API validation.
+## Custom Rules
 
-```vue
-<script setup lang="ts">
-const checkUsername = validators.async(async (value) => {
-  const response = await fetch(`/api/check-username?username=${value}`)
-  const data = await response.json()
-  return data.available || 'Username is already taken'
-})
+A rule is `{ validator, message? }`. The validator may be sync or async.
 
-const rules = [
-  validators.required(),
-  checkUsername
-]
-</script>
-```
-
-## Custom Validators
-
-### Simple Custom Validator
-
-```vue
-<script setup lang="ts">
-const customValidator = {
-  validator: (value) => {
-    return value === 'correct' || 'Value must be "correct"'
-  },
-  message: 'Value must be "correct"'
+```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 = [customValidator]
-</script>
+const rules = [validators.required(), validators.minLength(8), passwordStrength]
 ```
 
-### Complex Custom Validator
-
-```vue
-<script setup lang="ts">
-const passwordStrengthValidator = {
-  validator: (value) => {
-    if (!value) return true
-
-    const hasUpperCase = /[A-Z]/.test(value)
-    const hasLowerCase = /[a-z]/.test(value)
-    const hasNumber = /\d/.test(value)
-    const hasSpecialChar = /[!@#$%^&*]/.test(value)
-
-    if (!hasUpperCase) return 'Password must contain an uppercase letter'
-    if (!hasLowerCase) return 'Password must contain a lowercase letter'
-    if (!hasNumber) return 'Password must contain a number'
-    if (!hasSpecialChar) return 'Password must contain a special character'
+## Single-field validation: `useFormValidation`
 
-    return true
-  },
-  message: 'Password does not meet requirements'
-}
+```ts
+import { useFormValidation } from '@velkymx/vibeui'
 
-const rules = [
-  validators.required(),
-  validators.minLength(8),
-  passwordStrengthValidator
-]
-</script>
+const field = useFormValidation('')   // initial value
 ```
 
-## Using the Validation Composable
+Returns:
 
-### Basic Usage
+| 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('Email is required'),
-    validators.email('Please enter a valid email')
-  ])
-}
+const validateEmail = () =>
+  email.validate([validators.required(), validators.email()])
 </script>
 
 <template>
-  <VibeFormInput
-    v-model="email.value"
-    id="email"
-    type="email"
+  <VibeFormGroup
     label="Email"
     :validation-state="email.validationState"
     :validation-message="email.validationMessage"
-    @validate="validateEmail"
-  />
+  >
+    <VibeFormInput v-model="email.value" type="email" @validate="validateEmail" />
+  </VibeFormGroup>
 </template>
 ```
 
-### Composable API
-
-```typescript
-const field = useFormValidation(initialValue)
-
-// Properties
-field.value                // The field value
-field.validationState      // 'valid' | 'invalid' | null
-field.validationMessage    // Validation message
-field.isDirty             // Has the value changed
-field.isTouched           // Has the field been focused
-field.isValidating        // Is validation in progress
-field.isValid             // Computed: validationState === 'valid'
-field.isInvalid           // Computed: validationState === 'invalid'
-
-// Methods
-await field.validate(rules)  // Run validation
-field.reset()                // Reset to initial value
-field.markAsTouched()        // Mark as touched
-field.markAsDirty()          // Mark as dirty
-```
-
-## Validation Patterns
+Editing an invalid field clears its `invalid` state automatically until you re-validate.
 
-### Validate on Blur
+## Whole-form validation: `useForm`
 
-```vue
-<template>
-  <VibeFormInput
-    v-model="email"
-    id="email"
-    @validate="validateEmail"
-    validate-on="blur"
-  />
-</template>
-```
-
-### Validate on Change
+```ts
+import { useForm } from '@velkymx/vibeui'
 
-```vue
-<template>
-  <VibeFormInput
-    v-model="password"
-    id="password"
-    @validate="validatePassword"
-    validate-on="change"
-  />
-</template>
+const form = useForm({ username: '', email: '', age: 0 })
 ```
 
-### Validate on Input
-
-```vue
-<template>
-  <VibeFormInput
-    v-model="username"
-    id="username"
-    @validate="validateUsername"
-    validate-on="input"
-  />
-</template>
-```
+Returns:
 
-### Manual Validation
+| 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">
-const email = ref('')
-const validationState = ref(null)
-const validationMessage = ref('')
-
-const validateEmail = async () => {
-  const rules = [validators.required(), validators.email()]
-
-  for (const rule of rules) {
-    const result = await rule.validator(email.value)
-    if (result !== true) {
-      validationState.value = 'invalid'
-      validationMessage.value = typeof result === 'string' ? result : rule.message
-      return
-    }
-  }
-
-  validationState.value = 'valid'
-  validationMessage.value = ''
-}
+import { useForm, validators } from '@velkymx/vibeui'
 
-const handleSubmit = async () => {
-  await validateEmail()
+const form = useForm({ username: '', email: '', password: '' })
 
-  if (validationState.value === 'valid') {
-    // Submit form
-  }
+const rules = {
+  username: [validators.required(), validators.minLength(3)],
+  email: [validators.required(), validators.email()],
+  password: [validators.required(), validators.minLength(8)]
 }
-</script>
-```
-
-## API Validation
-
-### Check Username Availability
 
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { validators } from '@velkymx/vibeui'
-
-const username = ref('')
-const validationState = ref(null)
-const validationMessage = ref('')
-const isChecking = ref(false)
-
-const checkUsernameAvailability = validators.async(async (value) => {
-  isChecking.value = true
-
-  try {
-    const response = await fetch(`/api/users/check-username`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ username: value })
-    })
-
-    const data = await response.json()
-
-    if (!data.available) {
-      return data.message || 'Username is already taken'
-    }
-
-    return true
-  } catch (error) {
-    return 'Error checking username availability'
-  } finally {
-    isChecking.value = false
-  }
-})
-
-const validateUsername = async () => {
-  const rules = [
-    validators.required('Username is required'),
-    validators.minLength(3, 'Username must be at least 3 characters'),
-    validators.maxLength(20, 'Username must not exceed 20 characters'),
-    validators.pattern(/^[a-zA-Z0-9_]+$/, 'Username can only contain letters, numbers, and underscores'),
-    checkUsernameAvailability
-  ]
-
-  for (const rule of rules) {
-    const result = await rule.validator(username.value)
-    if (result !== true) {
-      validationState.value = 'invalid'
-      validationMessage.value = typeof result === 'string' ? result : rule.message
-      return
-    }
-  }
-
-  validationState.value = 'valid'
-  validationMessage.value = 'Username is available!'
+const onSubmit = async () => {
+  const { valid } = await form.validate(rules)
+  if (valid) console.log('submit', form.values.value)
 }
 </script>
 
 <template>
-  <VibeFormInput
-    v-model="username"
-    id="username"
-    label="Username"
-    :validation-state="validationState"
-    :validation-message="validationMessage"
-    @validate="validateUsername"
-    validate-on="blur"
-    :disabled="isChecking"
-  >
-    <template v-if="isChecking">
-      <VibeSpinner size="sm" class="position-absolute end-0 top-50 translate-middle-y me-3" />
-    </template>
-  </VibeFormInput>
+  <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>
 ```
 
-### Debounced API Validation
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { validators } from '@velkymx/vibeui'
+## When validation runs: `validateOn`
 
-// Debounce helper
-function debounce(fn, delay) {
-  let timeout
-  return (...args) => {
-    clearTimeout(timeout)
-    return new Promise((resolve) => {
-      timeout = setTimeout(() => resolve(fn(...args)), delay)
-    })
-  }
-}
+Form controls emit `validate` based on `validateOn`:
 
-const email = ref('')
-const validationState = ref(null)
-const validationMessage = ref('')
-
-const checkEmailDebounced = debounce(async (value) => {
-  const response = await fetch(`/api/check-email?email=${value}`)
-  const data = await response.json()
-  return data.available || 'Email is already registered'
-}, 500)
-
-const checkEmail = validators.async(checkEmailDebounced)
-
-const validateEmail = async () => {
-  const rules = [
-    validators.required(),
-    validators.email(),
-    checkEmail
-  ]
-
-  for (const rule of rules) {
-    const result = await rule.validator(email.value)
-    if (result !== true) {
-      validationState.value = 'invalid'
-      validationMessage.value = typeof result === 'string' ? result : rule.message
-      return
-    }
-  }
+- Text-like controls (input, textarea, datepicker, spinbutton, wysiwyg): `'input' \| 'blur' \| 'change'`, default `'blur'`.
+- Choice controls (checkbox, radio, switch, select): `'change' \| 'blur'`, default `'change'`.
 
-  validationState.value = 'valid'
-  validationMessage.value = 'Email is available!'
-}
-</script>
+Wire `@validate` to your validation call:
 
-<template>
-  <VibeFormInput
-    v-model="email"
-    id="email"
-    type="email"
-    label="Email"
-    :validation-state="validationState"
-    :validation-message="validationMessage"
-    @validate="validateEmail"
-    validate-on="input"
-  />
-</template>
+```vue
+<VibeFormInput v-model="field.value" validate-on="input" @validate="run" />
 ```
 
-## Form-Level Validation
+## 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 { ref, reactive } from 'vue'
-import { validators } from '@velkymx/vibeui'
+import { useFormValidation, validators } from '@velkymx/vibeui'
 
-const form = reactive({
-  username: '',
-  email: '',
-  password: '',
-  confirmPassword: ''
-})
+const username = useFormValidation('')
 
-const validation = reactive({
-  username: { state: null, message: '' },
-  email: { state: null, message: '' },
-  password: { state: null, message: '' },
-  confirmPassword: { state: null, message: '' }
+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 isFormValid = ref(false)
-
-const validateField = async (field, rules) => {
-  for (const rule of rules) {
-    const result = await rule.validator(form[field])
-    if (result !== true) {
-      validation[field].state = 'invalid'
-      validation[field].message = typeof result === 'string' ? result : rule.message
-      return false
-    }
-  }
-
-  validation[field].state = 'valid'
-  validation[field].message = ''
-  return true
-}
-
-const validateForm = async () => {
-  const results = await Promise.all([
-    validateField('username', [validators.required(), validators.minLength(3)]),
-    validateField('email', [validators.required(), validators.email()]),
-    validateField('password', [validators.required(), validators.minLength(8)]),
-    validateField('confirmPassword', [
-      validators.required(),
-      {
-        validator: (value) => value === form.password || 'Passwords do not match',
-        message: 'Passwords do not match'
-      }
-    ])
-  ])
-
-  isFormValid.value = results.every(result => result === true)
-  return isFormValid.value
-}
-
-const handleSubmit = async () => {
-  if (await validateForm()) {
-    console.log('Form is valid, submitting...', form)
-  }
-}
+const validateUsername = () =>
+  username.validate([validators.required(), validators.minLength(3), isAvailable])
 </script>
 
 <template>
-  <form @submit.prevent="handleSubmit">
-    <VibeFormInput
-      v-model="form.username"
-      id="username"
-      label="Username"
-      :validation-state="validation.username.state"
-      :validation-message="validation.username.message"
-      @validate="validateField('username', [validators.required(), validators.minLength(3)])"
-    />
-
-    <VibeFormInput
-      v-model="form.email"
-      id="email"
-      type="email"
-      label="Email"
-      :validation-state="validation.email.state"
-      :validation-message="validation.email.message"
-      @validate="validateField('email', [validators.required(), validators.email()])"
-    />
-
-    <VibeFormInput
-      v-model="form.password"
-      id="password"
-      type="password"
-      label="Password"
-      :validation-state="validation.password.state"
-      :validation-message="validation.password.message"
-      @validate="validateField('password', [validators.required(), validators.minLength(8)])"
-    />
-
-    <VibeFormInput
-      v-model="form.confirmPassword"
-      id="confirmPassword"
-      type="password"
-      label="Confirm Password"
-      :validation-state="validation.confirmPassword.state"
-      :validation-message="validation.confirmPassword.message"
-      @validate="validateField('confirmPassword', [
-        validators.required(),
-        { validator: (v) => v === form.password || 'Passwords do not match', message: 'Passwords do not match' }
-      ])"
-    />
-
-    <VibeButton type="submit" variant="primary">Register</VibeButton>
-  </form>
+  <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.