@macrulez/vue-form-schema 0.1.1 → 0.1.6

package/README.md

@@ -1,6 +1,15 @@
-# vue-form-schema
-
-Reactive forms from a declarative schema (JSON, Zod, or Yup) for Vue 3. A headless, SSR-compatible alternative to VeeValidate / FormKit for forms that are generated dynamically or driven from the server.
+<div align="center" style="background:#111827;border-radius:20px;padding:28px 20px 20px;margin-bottom:32px">
+  <h1 style="color:#f9fafb;margin:0 0 32px;font-size:2.2em;letter-spacing:-0.03em;font-weight:700;font-family:sans-serif">
+    @macrulez/vue-form-schema
+  </h1>
+  <img
+    src="https://s3.twcstorage.ru/c9a2cc89-780f97fd-311d-4a1a-b86f-c25665c9dc46/images/npm/vue-form-schema.webp"
+    alt="vue-virtual-scroller-kit"
+    style="max-width:100%;width:auto;height:300px;border-radius:12px"
+  />
+</div>
+
+Reactive forms from a declarative schema (JSON, Zod, Yup, or Valibot) for Vue 3. A headless, SSR-compatible alternative to VeeValidate / FormKit for forms that are generated dynamically or driven from the server.
 
 ---
 
@@ -17,13 +26,27 @@ Reactive forms from a declarative schema (JSON, Zod, or Yup) for Vue 3. A headle
   - [JSON schema](#json-schema)
   - [Zod](#zod)
   - [Yup](#yup)
+  - [Valibot](#valibot)
 - [Built-in validators](#built-in-validators)
 - [Custom validators](#custom-validators)
+- [Cross-field validation](#cross-field-validation)
 - [Conditional fields](#conditional-fields)
+- [Dynamic options](#dynamic-options)
+- [Dynamic array fields](#dynamic-array-fields)
+- [Multi-step forms](#multi-step-forms)
+- [Field transform & parse](#field-transform--parse)
+- [File upload field](#file-upload-field)
+- [Custom field components](#custom-field-components)
+- [Component registry](#component-registry)
 - [Input masking](#input-masking)
+- [Schema composition](#schema-composition)
+- [TypeScript inference](#typescript-inference)
+- [Persisted forms](#persisted-forms)
+- [Debug mode](#debug-mode)
 - [FormRenderer UI component](#formrenderer-ui-component)
+- [Tailwind UI theme](#tailwind-ui-theme)
+- [Accessibility](#accessibility)
 - [SSR compatibility](#ssr-compatibility)
-- [TypeScript generics](#typescript-generics)
 - [Architecture](#architecture)
 - [Bundle size & peer dependencies](#bundle-size--peer-dependencies)
 
@@ -31,52 +54,69 @@ Reactive forms from a declarative schema (JSON, Zod, or Yup) for Vue 3. A headle
 
 ## Features
 
-- **Any schema source** — define fields as a plain JSON array, a Zod object, or a Yup object
+- **Any schema source** — `FieldDefinition[]`, JSON array, Zod, Yup, or Valibot
 - **Headless by default** — zero UI dependencies in the core; bring your own components
-- **Reactive conditions** — `visible`, `disabled`, and `required` accept a boolean, a function, or a string expression evaluated against live form values
-- **Validation** — sync and async validators, built-in rules (`required`, `email`, `minLength`, …), cross-field access
-- **Input masking** — phone (RU/EU), date, IBAN, INN, and custom `#`/`A` patterns; no external dependencies
-- **SSR-safe** — no direct browser APIs in the core; validation and state work on the server
-- **Tree-shakeable** — Zod/Yup adapters are separate entry points; the UI subpackage is optional
-- **TypeScript 5+** — generic type inference flows from schema to `values`
+- **Reactive conditions** — `visible`, `disabled` accept a boolean, function, or string expression
+- **Dynamic options** — sync and async `options` functions with dependency tracking (`optionsDeps`)
+- **Dynamic array fields** — `type: 'array'` with `useFieldArray` composable (append / remove / move / swap)
+- **Multi-step wizard** — `useMultiStepForm` with per-step validation and `MultiStepFormRenderer`
+- **Validation** — sync + async validators, `validateMode: 'first' | 'all'`, `validateOn: 'eager'`
+- **Cross-field** — `sameAs` validator; validators receive all current values as second argument
+- **Transform & parse** — `transform` runs on every `setField`; `parse` runs at submit time
+- **File upload** — `type: 'file'` with `fileType`, `fileSize`, `fileCount` validators; drag-and-drop UI
+- **Custom components** — `field.component` + per-app and per-subtree component registry
+- **Input masking** — phone (RU/EU), date, IBAN, INN, custom `#`/`A` patterns; no external deps
+- **Schema composition** — `mergeSchemas`, `omitFields`, `pickFields`, `extendField`
+- **TypeScript inference** — `InferValues<T>` maps schema literals to typed values
+- **Persisted forms** — `persist: 'local' | 'session'` with SSR-safe storage
+- **Debug mode** — `debug: true` logs state changes; `useFormDebug` returns a reactive snapshot
+- **Tailwind UI theme** — `vue-form-schema/ui/tailwind` subentry with utility-class components
+- **Accessibility** — `aria-required`, `aria-invalid`, `aria-describedby`, `fieldset`/`legend` for radio
+- **SSR-safe** — no direct browser APIs in the core
+- **Tree-shakeable** — Zod/Yup/Valibot adapters and UI are separate entry points
 
 ---
 
 ## Demo
 
-A local interactive demo covers all major features of the library. Clone the repo and run:
-
 ```bash
 npm install
 npm run demo
 ```
 
-Opens at **http://localhost:5174** with the following examples:
+Opens at **http://localhost:5174**:
 
 | Page | What it shows |
 |---|---|
-| **Basic form** | `FieldDefinition[]` with built-in validators — `required`, `minLength`, `email`, `min/max` |
-| **JSON schema** | Server-driven schema with rule-based validators (`{ rule: 'minLength', value: 3 }`) |
-| **Zod schema** | `z.object()` → `parseZod()`, type inference, `.describe()` for labels |
-| **Yup schema** | `yup.object()` → `parseYup()`, Yup constraints delegated to `validateSync` |
-| **Conditional fields** | `visible` as a function and as a string expression; `clearOnHide` behaviour |
-| **Input masking** | All presets + custom `#`/`A` patterns; standalone `applyMask` / `removeMask` playground |
-| **FormRenderer** | Out-of-the-box rendering; slot overrides (`#field-{name}`, `#submit`); custom component map |
+| **Basic form** | `FieldDefinition[]` with built-in validators |
+| **JSON schema** | Server-driven schema with rule-based validators |
+| **Zod schema** | `parseZod()` with type inference |
+| **Yup schema** | `parseYup()` with Yup constraints |
+| **Conditional fields** | `visible` / `disabled` as function and string expression |
+| **Input masking** | All presets + custom patterns |
+| **FormRenderer** | Slot overrides, custom component map |
+| **Array fields** | `type: 'array'` + `useFieldArray` API |
+| **Multi-step wizard** | `useMultiStepForm` + step progress |
+| **Dependent fields** | Sync/async function options, `defaultValue` as function |
+| **Custom registry** | `provideRegistry` replaces built-in checkbox with PillToggle |
+| **File upload** | Drag-and-drop, `fileType`/`fileSize`/`fileCount` validators |
+| **Tailwind theme** | Default `FormRenderer` vs `TailwindFormRenderer` side by side |
+| **Accessibility** | `aria-*` attributes, `fieldset`/`legend` for radio groups |
 
 ---
 
 ## Installation
 
 ```bash
-npm install vue-form-schema
+npm install @macrulez/vue-form-schema
 ```
 
-Peer dependencies:
+Optional peer dependencies:
 
 ```bash
-npm install vue          # required
-npm install zod          # optional — only if you use the Zod adapter
-npm install yup          # optional — only if you use the Yup adapter
+npm install zod       # Zod adapter
+npm install yup       # Yup adapter
+npm install valibot   # Valibot adapter
 ```
 
 ---
@@ -85,8 +125,8 @@ npm install yup          # optional — only if you use the Yup adapter
 
 ```vue
 <script setup lang="ts">
-import { useForm } from 'vue-form-schema'
-import type { FieldDefinition } from 'vue-form-schema'
+import { useForm } from '@macrulez/vue-form-schema'
+import type { FieldDefinition } from '@macrulez/vue-form-schema'
 
 const schema: FieldDefinition[] = [
   { type: 'text',  name: 'name',  label: 'Full name', required: true },
@@ -130,19 +170,32 @@ const { values, errors, touched, isValid, isSubmitting, submit, setField } = use
 </template>
 ```
 
+Or use `FormRenderer` for zero-markup rendering:
+
+```vue
+<script setup lang="ts">
+import { useForm } from '@macrulez/vue-form-schema'
+import { FormRenderer } from '@macrulez/vue-form-schema/ui'
+
+const form = useForm({ schema, onSubmit })
+</script>
+
+<template>
+  <FormRenderer :form="form" submit-label="Save" />
+</template>
+```
+
 ---
 
 ## FieldDefinition reference
 
-Every field in your schema is described by a `FieldDefinition` object.
-
 ```ts
 interface FieldDefinition {
   // ─── Required ─────────────────────────────────────────────────────────────
   type: 'text' | 'number' | 'email' | 'select' | 'checkbox'
-      | 'radio' | 'textarea' | 'date' | 'array' | 'group'
+      | 'radio' | 'textarea' | 'date' | 'array' | 'group' | 'file'
 
-  /** Flat dot-path key used in the values object, e.g. "address.city" */
+  /** Flat dot-path key in the values object, e.g. "address.city" */
   name: string
 
   // ─── Display ──────────────────────────────────────────────────────────────
@@ -150,20 +203,14 @@ interface FieldDefinition {
   placeholder?: string
 
   // ─── Initial value ────────────────────────────────────────────────────────
-  defaultValue?: unknown   // set on mount and after reset()
+  /** Static value or a function called at init with already-resolved partial values */
+  defaultValue?: unknown | ((values: Record<string, unknown>) => unknown)
 
   // ─── Constraints ──────────────────────────────────────────────────────────
   required?: boolean
-
-  /** Static boolean, or a function receiving all current values */
   disabled?: boolean | ((values: Record<string, unknown>) => boolean)
-
-  /**
-   * Static boolean, a function, or a string expression.
-   * String expressions have access to the `values` variable and support
-   * arithmetic, comparison, logical operators.  Unsafe calls are blocked.
-   */
-  visible?: boolean | string | ((values: Record<string, unknown>) => boolean)
+  /** Boolean, function, or string expression evaluated against live values */
+  visible?:  boolean | string | ((values: Record<string, unknown>) => boolean)
 
   // ─── Validation ───────────────────────────────────────────────────────────
   validators?:      ValidatorFn[]
@@ -172,41 +219,41 @@ interface FieldDefinition {
   // ─── Masking ──────────────────────────────────────────────────────────────
   mask?: string | MaskConfig
 
-  // ─── select / radio ───────────────────────────────────────────────────────
-  options?: { label: string; value: unknown }[]
+  // ─── select / radio options ───────────────────────────────────────────────
+  /** Static array, sync function, or async function */
+  options?: FieldOption[]
+          | ((values: Record<string, unknown>) => FieldOption[])
+          | ((values: Record<string, unknown>) => Promise<FieldOption[]>)
+  /** Field names that trigger async options re-fetch when their values change */
+  optionsDeps?: string[]
 
   // ─── group / array ────────────────────────────────────────────────────────
   fields?: FieldDefinition[]
-}
-```
-
-### Nested fields
 
-Use `type: 'group'` to create a named group of fields. Child field names must use dot-path notation so values are properly scoped.
-
-```ts
-const schema: FieldDefinition[] = [
-  {
-    type: 'group',
-    name: 'address',
-    label: 'Address',
-    fields: [
-      { type: 'text', name: 'address.city',    label: 'City',    required: true },
-      { type: 'text', name: 'address.country', label: 'Country', required: true },
-    ],
-  },
-]
+  // ─── transform / parse ────────────────────────────────────────────────────
+  /** Applied on every setField call — use for trim, coercion, formatting */
+  transform?: (value: unknown, values: Record<string, unknown>) => unknown
+  /** Applied at submit time to produce the final payload value */
+  parse?: (raw: unknown) => unknown
+
+  // ─── Custom component ─────────────────────────────────────────────────────
+  /** Vue component or registered name; receives FormFieldProps */
+  component?: Component | string
+
+  // ─── File field options ───────────────────────────────────────────────────
+  accept?:   string   // passed to <input accept>
+  multiple?: boolean
+  maxSize?:  number   // bytes (informational; use fileSize validator to enforce)
+  maxFiles?: number   // informational; use fileCount validator to enforce
+}
 ```
 
-The resulting `values` object will be `{ 'address.city': '...', 'address.country': '...' }`.
-
 ---
 
 ## useForm composable
 
 ```ts
-import { useForm } from 'vue-form-schema'
-
+import { useForm } from '@macrulez/vue-form-schema'
 const form = useForm(config)
 ```
 
@@ -216,43 +263,34 @@ const form = useForm(config)
 |---|---|---|---|
 | `schema` | `FieldDefinition[] \| JSONSchema` | — | Field definitions |
 | `initialValues` | `Partial<T>` | `{}` | Seed values (override field defaults) |
-| `validateOn` | `'input' \| 'blur' \| 'submit'` | `'blur'` | When sync validation is triggered |
-| `clearOnHide` | `boolean` | `false` | Reset a field's value when it becomes hidden |
+| `validateOn` | `'input' \| 'blur' \| 'submit' \| 'eager'` | `'blur'` | When validation fires |
+| `validateMode` | `'first' \| 'all'` | `'first'` | Return first error only, or all errors |
+| `clearOnHide` | `boolean` | `false` | Reset field value when it becomes hidden |
 | `onSubmit` | `(values: T) => void \| Promise<void>` | — | Called after successful validation |
+| `persist` | `false \| 'session' \| 'local'` | `false` | Persist values to sessionStorage / localStorage |
+| `persistKey` | `string` | auto | Storage key prefix |
+| `debug` | `boolean` | `false` | Log state changes to `console.group` |
 
 ### Return value
 
 | Property | Type | Description |
 |---|---|---|
-| `fields` | `ComputedRef<FieldDefinition[]>` | Field list after conditions are evaluated |
-| `values` | `Ref<T>` | Current form values (reactive) |
+| `fields` | `ComputedRef<FieldDefinition[]>` | Fields after conditions are evaluated |
+| `values` | `Ref<T>` | Current form values |
 | `errors` | `Ref<Record<string, string[]>>` | Validation errors keyed by field name |
-| `touched` | `Ref<Record<string, boolean>>` | Whether a field has been interacted with |
-| `isDirty` | `ComputedRef<boolean>` | `true` when values differ from the initial state |
+| `touched` | `Ref<Record<string, boolean>>` | Fields that have been blurred |
+| `optionsLoading` | `Ref<Record<string, boolean>>` | Async options loading state per field |
+| `isDirty` | `ComputedRef<boolean>` | `true` when values differ from initial state |
 | `isValid` | `ComputedRef<boolean>` | `true` when all visible fields pass validation |
 | `isSubmitting` | `Ref<boolean>` | `true` while `onSubmit` is running |
 | `submit()` | `() => Promise<void>` | Touch all fields, validate, call `onSubmit` |
-| `reset(values?)` | `(values?: Partial<T>) => void` | Restore initial state (or supply new values) |
-| `setField(path, value)` | `(path: string, value: unknown) => void` | Programmatically set a value |
-| `getField(path)` | `(path: string) => unknown` | Read a value by dot-path |
+| `reset(values?)` | — | Restore initial state or supply new values |
+| `setField(path, value)` | — | Set a value by dot-path |
+| `getField(path)` | — | Read a value by dot-path |
 
-### Example — programmatic control
-
-```ts
-const { setField, getField, reset } = useForm({ schema })
+### `validateOn: 'eager'`
 
-// Set a nested field
-setField('address.city', 'Berlin')
-
-// Read it back
-console.log(getField('address.city')) // 'Berlin'
-
-// Reset to schema defaults
-reset()
-
-// Reset to specific values
-reset({ name: 'Alice', email: 'alice@example.com' })
-```
+With `'eager'`, validation runs on input — but only after the field has been blurred at least once. This avoids showing errors while the user is still typing for the first time.
 
 ---
 
@@ -260,30 +298,24 @@ reset({ name: 'Alice', email: 'alice@example.com' })
 
 ### FieldDefinition array
 
-The native format — an array of `FieldDefinition` objects, usually created from the parser functions or manually:
-
 ```ts
-import type { FieldDefinition } from 'vue-form-schema'
+import type { FieldDefinition } from '@macrulez/vue-form-schema'
 
 const schema: FieldDefinition[] = [
   { type: 'text', name: 'username', required: true },
 ]
-
 useForm({ schema })
 ```
 
 ### JSON schema
 
-A serialisable array format useful when the schema arrives from an API. Validators are expressed as named rules instead of functions. Pass directly to `useForm` or call `parseJSON` explicitly.
+A serialisable format for server-driven schemas. Pass directly to `useForm` (auto-detected) or call `parseJSON` explicitly.
 
 ```ts
-import { parseJSON } from 'vue-form-schema'
-
 const raw = [
   {
     type: 'text',
     name: 'username',
-    label: 'Username',
     default: '',
     required: true,
     validators: [
@@ -291,44 +323,21 @@ const raw = [
       { rule: 'maxLength', value: 20 },
     ],
   },
-  {
-    type: 'email',
-    name: 'email',
-    validators: [{ rule: 'email' }],
-  },
 ]
 
-// Option A — pass directly to useForm (auto-detected)
-useForm({ schema: raw })
-
-// Option B — parse explicitly
+useForm({ schema: raw })            // auto-detected
+// or
+import { parseJSON } from '@macrulez/vue-form-schema'
 const fields = parseJSON(raw)
-useForm({ schema: fields })
 ```
 
-**Supported JSON validator rules:**
-
-| Rule | Parameter | Example |
-|---|---|---|
-| `required` | — | `{ rule: 'required' }` |
-| `minLength` | `value: number` | `{ rule: 'minLength', value: 2 }` |
-| `maxLength` | `value: number` | `{ rule: 'maxLength', value: 100 }` |
-| `min` | `value: number` | `{ rule: 'min', value: 0 }` |
-| `max` | `value: number` | `{ rule: 'max', value: 9999 }` |
-| `pattern` | `value: string` (regex) | `{ rule: 'pattern', value: '^[a-z]+$' }` |
-| `email` | — | `{ rule: 'email' }` |
-| `url` | — | `{ rule: 'url' }` |
-
-All rules accept an optional `message` string to override the default error text.
+**Supported JSON validator rules:** `required`, `minLength`, `maxLength`, `min`, `max`, `pattern`, `email`, `url`. All accept an optional `message` override.
 
 ### Zod
 
-Install Zod and import the adapter from `vue-form-schema/zod`:
-
 ```ts
 import { z } from 'zod'
-import { parseZod } from 'vue-form-schema/zod'
-import { useForm } from 'vue-form-schema'
+import { parseZod } from '@macrulez/vue-form-schema/zod'
 
 const schema = z.object({
   name:  z.string().min(2).describe('Full name'),
@@ -338,40 +347,16 @@ const schema = z.object({
 })
 
 const fields = parseZod(schema)
-
-const { values, submit } = useForm({ schema: fields })
+const { values } = useForm({ schema: fields })
 ```
 
-Type inference is preserved — `values` will be typed as the Zod schema's output type when you supply it explicitly:
-
-```ts
-type FormData = z.infer<typeof schema>
-
-const { values } = useForm<FormData>({ schema: fields })
-// values.value.name is string
-```
-
-**Zod type mapping:**
-
-| Zod type | Field type |
-|---|---|
-| `z.string()` | `text` |
-| `z.number()` | `number` |
-| `z.boolean()` | `checkbox` |
-| `z.enum(...)` | `select` |
-| `z.array(...)` | `array` |
-| `z.object(...)` | `group` |
-
-Use `.describe('label text')` on any field to set the `label`.
+**Zod → field type mapping:** `z.string()` → `text`, `z.number()` → `number`, `z.boolean()` → `checkbox`, `z.enum()` → `select`, `z.array()` → `array`, `z.object()` → `group`. Use `.describe('label')` to set the field label.
 
 ### Yup
 
-Install Yup and import the adapter from `vue-form-schema/yup`:
-
 ```ts
 import { object, string, number } from 'yup'
-import { parseYup } from 'vue-form-schema/yup'
-import { useForm } from 'vue-form-schema'
+import { parseYup } from '@macrulez/vue-form-schema/yup'
 
 const schema = object({
   name:  string().required().label('Full name'),
@@ -380,275 +365,634 @@ const schema = object({
 })
 
 const fields = parseYup(schema)
+const { values } = useForm({ schema: fields })
+```
+
+### Valibot
 
-const { values, submit } = useForm({ schema: fields })
+```ts
+import * as v from 'valibot'
+import { parseValibot } from '@macrulez/vue-form-schema/valibot'
+
+const schema = v.object({
+  name:  v.pipe(v.string(), v.minLength(2)),
+  email: v.pipe(v.string(), v.email()),
+  age:   v.optional(v.number()),
+  role:  v.picklist(['admin', 'user']),
+})
+
+const fields = parseValibot(schema)
+const { values } = useForm({ schema: fields })
 ```
 
-**Yup type mapping:**
+**Valibot → field type mapping:** `v.string()` → `text`, `v.number()` → `number`, `v.boolean()` → `checkbox`, `v.picklist()` / `v.enum()` → `select`, `v.array()` → `array`, `v.object()` → `group`. `v.pipe(v.string(), v.email())` → `type: 'email'`. `v.optional()` / `v.nullable()` → `required: false`.
 
-| Yup type | Field type |
+---
+
+## Built-in validators
+
+```ts
+import {
+  required, minLength, maxLength, min, max, pattern, email, url,
+  sameAs,
+  fileType, fileSize, fileCount,
+} from '@macrulez/vue-form-schema'
+```
+
+| Function | Description |
 |---|---|
-| `string()` | `text` |
-| `number()` | `number` |
-| `boolean()` | `checkbox` |
-| `array()` | `array` |
-| `object()` | `group` |
+| `required` | Fails for `null`, `undefined`, `''`, or empty array |
+| `minLength(n, msg?)` | Min length for string or array |
+| `maxLength(n, msg?)` | Max length for string or array |
+| `min(n, msg?)` | Numeric minimum |
+| `max(n, msg?)` | Numeric maximum |
+| `pattern(re, msg?)` | Regex match |
+| `email` | Basic email format |
+| `url` | Valid URL (`new URL()`) |
+| `sameAs(field, msg?)` | Value must equal another field |
+| `fileType(types[], msg?)` | File MIME type or extension whitelist |
+| `fileSize(bytes, msg?)` | Max file size |
+| `fileCount(n, msg?)` | Max number of files |
 
 ---
 
-## Built-in validators
+## Custom validators
 
-Import standalone validator functions when building a `FieldDefinition` array manually:
+### Sync
 
 ```ts
-import {
-  required,
-  minLength,
-  maxLength,
-  min,
-  max,
-  pattern,
-  email,
-  url,
-} from 'vue-form-schema'
-```
-
-| Function | Signature | Description |
-|---|---|---|
-| `required` | `ValidatorFn` | Fails for `null`, `undefined`, `''`, or empty array |
-| `minLength(n, msg?)` | `(n: number) => ValidatorFn` | Min length for string or array |
-| `maxLength(n, msg?)` | `(n: number) => ValidatorFn` | Max length for string or array |
-| `min(n, msg?)` | `(n: number) => ValidatorFn` | Numeric minimum |
-| `max(n, msg?)` | `(n: number) => ValidatorFn` | Numeric maximum |
-| `pattern(re, msg?)` | `(re: RegExp) => ValidatorFn` | Regex match |
-| `email` | `ValidatorFn` | Basic email format check |
-| `url` | `ValidatorFn` | Valid URL (uses `new URL()`) |
+import type { ValidatorFn } from '@macrulez/vue-form-schema'
+
+const noSpaces: ValidatorFn = (value) =>
+  typeof value === 'string' && value.includes(' ') ? 'No spaces allowed' : null
+```
+
+### Async
+
+Async validators are debounced (300 ms). Errors are merged into `errors` after resolution.
 
 ```ts
-import { minLength, maxLength, email } from 'vue-form-schema'
+import type { AsyncValidatorFn } from '@macrulez/vue-form-schema'
+
+const uniqueUsername: AsyncValidatorFn = async (value) => {
+  const { taken } = await fetch(`/api/check?q=${value}`).then((r) => r.json())
+  return taken ? 'Username is taken' : null
+}
+```
+
+### Multiple errors per field (`validateMode`)
+
+```ts
+useForm({
+  schema,
+  validateMode: 'all',   // collect all errors per field (default: 'first')
+})
+```
+
+---
+
+## Cross-field validation
+
+Use `sameAs` for password confirmation or write a custom validator — all validators receive `allValues` as the second argument.
+
+```ts
+import { sameAs } from '@macrulez/vue-form-schema'
 
 const schema: FieldDefinition[] = [
+  { type: 'text', name: 'password', label: 'Password', required: true },
   {
     type: 'text',
-    name: 'username',
+    name: 'confirm',
+    label: 'Confirm password',
+    validators: [sameAs('password', 'Passwords must match')],
+  },
+]
+```
+
+---
+
+## Conditional fields
+
+`visible` and `disabled` can be a boolean, a reactive function, or a safe string expression.
+
+```ts
+const schema: FieldDefinition[] = [
+  { type: 'checkbox', name: 'hasCompany', label: 'I represent a company' },
+  {
+    type: 'text',
+    name: 'companyName',
+    label: 'Company name',
+    visible: (values) => values['hasCompany'] === true,
     required: true,
-    validators: [
-      minLength(3, 'At least 3 characters'),
-      maxLength(20),
-    ],
   },
+  // string expression — has access to the `values` variable
   {
-    type: 'email',
-    name: 'email',
-    validators: [email],
+    type: 'select',
+    name: 'drink',
+    label: 'Drink',
+    visible: 'values.age >= 18',
+    options: [{ label: 'Beer', value: 'beer' }, { label: 'Water', value: 'water' }],
   },
 ]
 ```
 
----
+Set `clearOnHide: true` in `useForm` to automatically reset a hidden field's value.
 
-## Custom validators
+---
 
-### Sync validator
+## Dynamic options
 
-A `ValidatorFn` receives the field's current value and all form values. Return a string on failure, or `null` on success.
+`options` can be a static array, a **sync function**, or an **async function**.
 
 ```ts
-import type { ValidatorFn } from 'vue-form-schema'
+// Sync — re-evaluated on every values change
+{
+  type: 'select',
+  name: 'city',
+  options: (values) => citiesByCountry[values['country'] as string] ?? [],
+}
 
-const noSpaces: ValidatorFn = (value) => {
-  if (typeof value === 'string' && value.includes(' ')) return 'No spaces allowed'
-  return null
+// Async — fetched on mount and re-fetched when optionsDeps change
+{
+  type: 'select',
+  name: 'framework',
+  optionsDeps: ['language'],
+  options: async (values) => {
+    const res = await fetch(`/api/frameworks?lang=${values['language']}`)
+    return res.json()
+  },
 }
+```
+
+While loading, `optionsLoading.value['framework']` is `true` and the select is disabled in `FormRenderer`. Access the loading state directly via `form.optionsLoading`.
+
+### Computed `defaultValue`
 
-// Cross-field: confirm password
-const matchesPassword: ValidatorFn = (value, allValues) => {
-  if (value !== allValues['password']) return 'Passwords do not match'
-  return null
+`defaultValue` can also be a function evaluated at form initialisation with already-resolved partial values as context:
+
+```ts
+{
+  type: 'text',
+  name: 'displayName',
+  defaultValue: (values) => `${values.firstName} ${values.lastName}`,
 }
+```
 
+---
+
+## Dynamic array fields
+
+### Schema definition
+
+```ts
 const schema: FieldDefinition[] = [
-  { type: 'text', name: 'password', label: 'Password' },
   {
-    type: 'text',
-    name: 'confirmPassword',
-    label: 'Confirm password',
-    validators: [matchesPassword],
+    type: 'array',
+    name: 'members',
+    label: 'Team members',
+    fields: [
+      { type: 'text',  name: 'members.name',  label: 'Name',  required: true },
+      { type: 'email', name: 'members.email', label: 'Email', required: true },
+    ],
   },
 ]
 ```
 
-### Async validator
+`FormRenderer` renders an `ArrayField` automatically with Add / Remove buttons.
 
-An `AsyncValidatorFn` returns a `Promise<string | null>`. Async validators are debounced (300 ms by default) so they don't fire on every keystroke.
+### `useFieldArray` composable
 
 ```ts
-import type { AsyncValidatorFn } from 'vue-form-schema'
+import { useFieldArray } from '@macrulez/vue-form-schema'
 
-const uniqueUsername: AsyncValidatorFn = async (value) => {
-  const res = await fetch(`/api/check-username?q=${value}`)
-  const { taken } = await res.json()
-  return taken ? 'This username is already taken' : null
-}
+const { rows, count, append, prepend, remove, move, swap, replace } =
+  useFieldArray(form, 'members')
+```
+
+| Method | Description |
+|---|---|
+| `append(defaults?)` | Add a row at the end |
+| `prepend(defaults?)` | Add a row at the beginning |
+| `remove(index)` | Remove a row |
+| `move(from, to)` | Move a row |
+| `swap(a, b)` | Swap two rows |
+| `replace(index, defaults?)` | Replace a row with fresh defaults |
+
+`rows` is a `ComputedRef<FieldArrayRow[]>`. Each row exposes `index`, `key`, and `fields` — the nested `FieldDefinition[]` with prefixed paths for that row.
+
+---
+
+## Multi-step forms
+
+```ts
+import { useMultiStepForm } from '@macrulez/vue-form-schema'
+
+const wizard = useMultiStepForm(
+  [
+    { title: 'Account', schema: accountFields },
+    { title: 'Profile', schema: profileFields },
+    { title: 'Confirm', schema: confirmFields },
+  ],
+  async (allValues) => {
+    await api.register(allValues)
+  },
+)
+```
 
+| Property / Method | Description |
+|---|---|
+| `currentStep` | `Ref<number>` — 0-based index |
+| `totalSteps` | Number of steps |
+| `isFirstStep` / `isLastStep` | `ComputedRef<boolean>` |
+| `form` | `UseFormReturn` for the current step |
+| `values` | All values across all steps merged |
+| `next()` | Validate current step then advance (returns `false` if invalid) |
+| `back()` | Go to previous step |
+| `goTo(n)` | Jump to step `n` |
+| `submit()` | Validate all steps then call `onSubmit` |
+
+### `MultiStepFormRenderer`
+
+```vue
+import { MultiStepFormRenderer } from '@macrulez/vue-form-schema/ui'
+
+<MultiStepFormRenderer :wizard="wizard" />
+```
+
+Renders the current step's fields and Back / Next / Submit navigation buttons.
+
+---
+
+## Field transform & parse
+
+```ts
 const schema: FieldDefinition[] = [
   {
     type: 'text',
     name: 'username',
-    required: true,
-    asyncValidators: [uniqueUsername],
+    // trim on every keystroke
+    transform: (value) => (typeof value === 'string' ? value.trim() : value),
+  },
+  {
+    type: 'text',
+    name: 'tags',
+    defaultValue: 'vue,react',
+    // split into array at submit time — values.tags is still a string
+    parse: (raw) => String(raw).split(',').map((s) => s.trim()),
   },
 ]
 ```
 
----
-
-## Conditional fields
+`transform` mutates `values` immediately. `parse` runs only at submit time and does not mutate `values`.
 
-`visible` and `disabled` can be a static boolean, a reactive function, or a safe string expression.
+---
 
-### Function condition
+## File upload field
 
 ```ts
+import { fileType, fileSize, fileCount } from '@macrulez/vue-form-schema'
+
 const schema: FieldDefinition[] = [
   {
-    type: 'checkbox',
-    name: 'hasCompany',
-    label: 'I represent a company',
-  },
-  {
-    type: 'text',
-    name: 'companyName',
-    label: 'Company name',
-    required: true,
-    // shown only when hasCompany is checked
-    visible: (values) => values['hasCompany'] === true,
+    type: 'file',
+    name: 'avatar',
+    label: 'Profile photo',
+    accept: 'image/*',
+    validators: [
+      fileType(['image/'], 'Only images are accepted'),
+      fileSize(2 * 1024 * 1024, 'Max 2 MB'),
+    ],
   },
   {
-    type: 'text',
-    name: 'vat',
-    label: 'VAT number',
-    // disabled unless company name is entered
-    disabled: (values) => !values['companyName'],
+    type: 'file',
+    name: 'attachments',
+    label: 'Attachments',
+    multiple: true,
+    validators: [fileCount(5, 'Up to 5 files')],
   },
 ]
 ```
 
-### String expression
+`values['avatar']` is `File | null`; `values['attachments']` is `File[] | null`.
+
+`FormRenderer` automatically renders `FileField` with a drag-and-drop zone and a file list with remove buttons.
+
+---
+
+## Custom field components
+
+A custom component is a pure **presentation layer** — it receives pre-computed validation state as props and signals changes back to the form. No validation logic lives inside the component itself.
+
+### How validation flows
+
+```
+useForm
+  ├─ validators / asyncValidators / required  ← defined in the schema
+  ├─ errors.value['fieldName'] = ['Too short'] ← computed internally
+  └─ passes to your component via props:
+        error:   string[]   — list of error messages
+        touched: boolean    — whether the field has been blurred
+```
+
+Your component's only job:
+
+| What | How |
+|---|---|
+| Report a value change | `emit('update:modelValue', newValue)` |
+| Trigger validation | `emit('blur')` — fires validation when `validateOn` is `'blur'` or `'eager'` |
+| Show errors | Read `props.error` / `props.touched` (or use `useFormField`) |
 
-String expressions have access to a `values` variable. Arithmetic, comparison, and logical operators are supported. Potentially unsafe calls (`fetch`, `eval`, etc.) are rejected by a whitelist check.
+### The `FormFieldProps` contract
+
+Every component that plugs into the library must declare these props and two emits:
 
 ```ts
+import type { FormFieldProps } from '@macrulez/vue-form-schema'
+
+// props
+const props = defineProps<FormFieldProps>()
+// {
+//   field:       FieldDefinition  — the full field config (validators, label, …)
+//   modelValue:  unknown          — current value from form state
+//   error:       string[]         — validation errors (empty when valid)
+//   touched:     boolean          — true after first blur
+// }
+
+// emits
+const emit = defineEmits<{
+  'update:modelValue': [value: unknown]
+  blur: []
+}>()
+```
+
+### Complete example — custom phone input
+
+```vue
+<!-- MyPhoneInput.vue -->
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useFormField } from '@macrulez/vue-form-schema'
+import type { FormFieldProps } from '@macrulez/vue-form-schema'
+
+const props = defineProps<FormFieldProps>()
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  blur: []
+}>()
+
+const { hasError, errorMessage, isRequired } = useFormField(props)
+
+// strip non-digits for storage, display formatted
+const display = computed(() =>
+  String(props.modelValue ?? '').replace(/\D/g, '').replace(/(\d{3})(\d{3})(\d{4})/, '($1) $2-$3'),
+)
+</script>
+
+<template>
+  <div class="field">
+    <label :for="field.name">
+      {{ field.label }}
+      <span v-if="isRequired" aria-hidden="true">*</span>
+    </label>
+
+    <input
+      :id="field.name"
+      type="tel"
+      :value="display"
+      :aria-invalid="hasError ? 'true' : 'false'"
+      :aria-describedby="hasError ? `${field.name}-error` : undefined"
+      @input="emit('update:modelValue', ($event.target as HTMLInputElement).value.replace(/\D/g, ''))"
+      @blur="emit('blur')"
+    />
+
+    <p v-if="hasError" :id="`${field.name}-error`" role="alert">
+      {{ errorMessage }}
+    </p>
+  </div>
+</template>
+```
+
+### Attach to a field via `field.component`
+
+```ts
+import MyPhoneInput from './MyPhoneInput.vue'
+import { minLength, pattern } from '@macrulez/vue-form-schema'
+
 const schema: FieldDefinition[] = [
-  { type: 'number', name: 'age', label: 'Age' },
   {
-    type: 'select',
-    name: 'alcoholChoice',
-    label: 'Drink preference',
-    visible: 'values.age >= 18',         // string expression
-    options: [
-      { label: 'Beer',  value: 'beer'  },
-      { label: 'Wine',  value: 'wine'  },
-      { label: 'Water', value: 'water' },
+    type: 'text',
+    name: 'phone',
+    label: 'Phone number',
+    component: MyPhoneInput,          // ← your component renders instead of TextField
+    required: true,
+    validators: [
+      minLength(10, 'Enter a full phone number'),
+      pattern(/^\d{10}$/, 'Digits only, 10 characters'),
     ],
   },
 ]
 ```
 
-### clearOnHide
+### Using without `FormRenderer` (manual wiring)
 
-When `clearOnHide: true` is set in `useForm`, hiding a field resets its value back to `defaultValue` (or `null`).
+If you render fields yourself — without `FormRenderer` — wire errors and the touch handler directly:
+
+```vue
+<script setup lang="ts">
+import { useForm } from '@macrulez/vue-form-schema'
+import MyPhoneInput from './MyPhoneInput.vue'
+
+const form = useForm({ schema, validateOn: 'blur' })
+const touchField = (form as any).touchField   // exposed internally
+</script>
+
+<template>
+  <form @submit.prevent="form.submit()">
+    <MyPhoneInput
+      :field="form.fields.value[0]"
+      :model-value="form.values.value.phone"
+      :error="form.errors.value.phone ?? []"
+      :touched="form.touched.value.phone ?? false"
+      @update:model-value="form.setField('phone', $event)"
+      @blur="touchField('phone')"
+    />
+    <button type="submit">Save</button>
+  </form>
+</template>
+```
+
+### `useFormField` helper — computed shortcuts
 
 ```ts
-useForm({
-  schema,
-  clearOnHide: true,
-})
+import { useFormField } from '@macrulez/vue-form-schema'
+
+const props = defineProps<FormFieldProps>()
+const {
+  hasError,      // ComputedRef<boolean>  — touched && error.length > 0
+  errorMessage,  // ComputedRef<string | null>  — first error, or null
+  allErrors,     // ComputedRef<string[]>  — all errors when touched, else []
+  isRequired,    // ComputedRef<boolean>
+  isDisabled,    // ComputedRef<boolean>
+} = useFormField(props)
+```
+
+---
+
+## Component registry
+
+Replace all instances of a field type across a subtree — useful for integrating UI libraries.
+
+### App-level (Vue plugin)
+
+```ts
+import { createApp } from 'vue'
+import { createFormRegistry } from '@macrulez/vue-form-schema'
+import { ElInput, ElSelect } from 'element-plus'
+
+createApp(App)
+  .use(createFormRegistry({ text: ElInput, select: ElSelect }))
+  .mount('#app')
 ```
 
+### Subtree-level
+
+```ts
+import { provideRegistry } from '@macrulez/vue-form-schema'
+
+// Inside a component's setup()
+provideRegistry({ checkbox: MyToggle })
+```
+
+Component priority: `field.component` > `FormRenderer :components` prop > registry > built-in defaults.
+
 ---
 
 ## Input masking
 
-Masks format user input in real time. They are applied automatically inside `FormRenderer` and can be used standalone via the `applyMask` / `removeMask` / `bindMask` functions.
+Masks format user input in real time. Applied automatically in `FormRenderer`; also usable standalone.
 
-### Mask presets
+### Presets
 
-| Preset | Pattern | Example output |
-|---|---|---|
-| `phone-ru` | `+7 (###) ###-##-##` | `+7 (916) 123-45-67` |
-| `phone-eu` | `+## (##) ###-##-##` | `+49 (30) 123-45-67` |
-| `date` | `##.##.####` | `01.01.2024` |
-| `inn` | `############` | `123456789012` |
-| `iban` | `AA## #### #### #### #### #### ####` | `GB29 NWBK 6016 ...` |
+| Preset | Example output |
+|---|---|
+| `phone-ru` | `+7 (916) 123-45-67` |
+| `phone-eu` | `+49 (30) 123-45-67` |
+| `date` | `01.01.2024` |
+| `inn` | `123456789012` |
+| `iban` | `GB29 NWBK 6016 1331 9268 19` |
 
 ```ts
-// Using a preset
-const field: FieldDefinition = {
-  type: 'text',
-  name: 'phone',
-  label: 'Phone',
-  mask: { preset: 'phone-ru' },
-}
+{ type: 'text', name: 'phone', mask: { preset: 'phone-ru' } }
 ```
 
 ### Custom patterns
 
-- `#` — matches a single digit (0–9)
-- `A` — matches a single letter (a–z, A–Z); output is uppercased
-- Any other character — treated as a fixed literal
+`#` = digit, `A` = letter (uppercased), anything else = literal.
 
 ```ts
-// Postcode: two letters + four digits
-const field: FieldDefinition = {
-  type: 'text',
-  name: 'postcode',
-  label: 'Postcode',
-  mask: { pattern: 'AA####' },  // e.g. AB1234
-}
+{ type: 'text', name: 'postcode', mask: { pattern: 'AA####' } }  // AB1234
+```
+
+### Standalone API
+
+```ts
+import { applyMask, removeMask, bindMask } from '@macrulez/vue-form-schema'
+
+applyMask('9161234567', { preset: 'phone-ru' })   // '+7 (916) 123-45-67'
+removeMask('+7 (916) 123-45-67', { preset: 'phone-ru' })  // '9161234567'
+
+const cleanup = bindMask(inputEl, { preset: 'date' })
+onUnmounted(cleanup)
+```
+
+---
+
+## Schema composition
+
+```ts
+import { mergeSchemas, omitFields, pickFields, extendField } from '@macrulez/vue-form-schema'
+
+const base = [
+  { type: 'text' as const, name: 'firstName' },
+  { type: 'text' as const, name: 'lastName' },
+  { type: 'email' as const, name: 'email' },
+]
+
+// Combine — later schemas win on name collision
+const extended = mergeSchemas(base, [{ type: 'text' as const, name: 'phone' }])
+
+// Remove fields
+const noEmail = omitFields(base, ['email'])
+
+// Keep only specific fields
+const nameOnly = pickFields(base, ['firstName', 'lastName'])
+
+// Non-mutating patch
+const required = extendField(base, 'email', { required: true, label: 'Email address' })
 ```
 
-### Standalone mask API
+---
+
+## TypeScript inference
+
+`InferValues<T>` maps a `readonly FieldDefinition[]` literal to a typed values object.
 
 ```ts
-import { applyMask, removeMask, bindMask } from 'vue-form-schema'
+import { defineSchema } from '@macrulez/vue-form-schema'
+import type { InferValues } from '@macrulez/vue-form-schema'
 
-// Format a raw value
-applyMask('9161234567', { preset: 'phone-ru' })
-// → '+7 (916) 123-45-67'
+const schema = defineSchema([
+  { type: 'text'     as const, name: 'username' as const },
+  { type: 'number'   as const, name: 'age'      as const },
+  { type: 'checkbox' as const, name: 'agreed'   as const },
+] as const)
 
-// Strip mask literals from a formatted value
-removeMask('+7 (916) 123-45-67', { preset: 'phone-ru' })
-// → '9161234567'
+type Values = InferValues<typeof schema>
+// { username: string; age: number; agreed: boolean }
 
-// Attach to a native <input> element (returns cleanup fn)
-const cleanup = bindMask(inputElement, { preset: 'date' })
-// call cleanup() in onUnmounted
+const { values } = useForm<Values>({ schema })
+// values.value.username is string ✓
 ```
 
+**Type mapping:** `checkbox` → `boolean`, `number` → `number`, `array` → `unknown[]`, everything else → `string`.
+
 ---
 
-## FormRenderer UI component
+## Persisted forms
+
+```ts
+useForm({
+  schema,
+  persist: 'local',       // or 'session'
+  persistKey: 'checkout', // optional — defaults to a hash of field names
+})
+```
 
-`FormRenderer` is in the optional `vue-form-schema/ui` subpackage. It renders fields automatically from the schema and delegates display to built-in or custom components.
+Values are restored from storage on `onMounted`. `reset()` clears the stored value. SSR-safe: the storage read is guarded by `typeof window !== 'undefined'`.
+
+---
+
+## Debug mode
 
 ```ts
-import { FormRenderer } from 'vue-form-schema/ui'
+// Log every values change to console.group
+useForm({ schema, debug: true })
 ```
 
-### Basic usage
+```ts
+// Reactive snapshot of all form state
+import { useFormDebug } from '@macrulez/vue-form-schema'
 
-```vue
-<script setup lang="ts">
-import { useForm } from 'vue-form-schema'
-import { FormRenderer } from 'vue-form-schema/ui'
+const { snapshot } = useFormDebug(form)
+// snapshot.value = { values, errors, touched, isDirty, isValid, isSubmitting }
+```
 
-const form = useForm({ schema, onSubmit })
-</script>
+---
 
-<template>
-  <FormRenderer :form="form" submit-label="Save" />
-</template>
+## FormRenderer UI component
+
+```ts
+import { FormRenderer } from '@macrulez/vue-form-schema/ui'
 ```
 
 ### Props
@@ -663,50 +1007,16 @@ const form = useForm({ schema, onSubmit })
 
 | Slot | Scope | Description |
 |---|---|---|
-| `#field-{name}` | `{ field, value, error, touched, setValue, touch }` | Replace the entire field |
-| `#label-{name}` | `{ field }` | Replace the field label |
-| `#error-{name}` | `{ field, error }` | Replace the error display |
+| `#field-{name}` | `{ field, value, error, touched, setValue, touch }` | Replace an entire field |
+| `#label-{name}` | `{ field }` | Replace a label |
+| `#error-{name}` | `{ field, error }` | Replace error display |
 | `#submit` | `{ isSubmitting, isValid }` | Replace the submit button |
 
-### Custom field renderers
-
-Pass a `components` map to swap built-in inputs with your own (e.g. Element Plus, Naive UI):
-
-```vue
-<script setup lang="ts">
-import { ElInput, ElSelect } from 'element-plus'
-
-const myComponents = { text: ElInput, select: ElSelect }
-</script>
-
-<template>
-  <FormRenderer :form="form" :components="myComponents" />
-</template>
-```
-
-### Per-field slot override
-
-```vue
-<template>
-  <FormRenderer :form="form">
-    <!-- replace the "avatar" field entirely -->
-    <template #field-avatar="{ value, setValue }">
-      <AvatarUploader :model-value="value" @update:model-value="setValue" />
-    </template>
-
-    <!-- custom submit -->
-    <template #submit="{ isSubmitting }">
-      <MyButton type="submit" :loading="isSubmitting">Save profile</MyButton>
-    </template>
-  </FormRenderer>
-</template>
-```
-
 ### Built-in field components
 
-The following components are exported from `vue-form-schema/ui` and can be used independently:
+All exported individually from `vue-form-schema/ui`:
 
-| Component | Types |
+| Component | Field types |
 |---|---|
 | `TextField` | `text`, `email` |
 | `NumberField` | `number` |
@@ -715,56 +1025,55 @@ The following components are exported from `vue-form-schema/ui` and can be used
 | `CheckboxField` | `checkbox` |
 | `RadioField` | `radio` |
 | `DateField` | `date` |
+| `ArrayField` | `array` |
+| `FileField` | `file` |
 
 ---
 
-## SSR compatibility
+## Tailwind UI theme
 
-The core package (`useForm`, validators, parsers, `ConditionEvaluator`) does not use any browser-specific APIs. State management and validation work on the server.
+A drop-in replacement for `FormRenderer` using Tailwind utility classes — no custom CSS needed in your app. Requires Tailwind CSS installed and configured to scan library source files.
 
-`bindMask` and `FormRenderer` use DOM APIs (`HTMLInputElement`, event listeners) and should only be called or mounted on the client side. Gate them with `onMounted` or Vue's `<ClientOnly>` wrapper as needed.
-
----
+```ts
+import { TailwindFormRenderer } from '@macrulez/vue-form-schema/ui/tailwind'
+```
 
-## TypeScript generics
+```vue
+<!-- Same form, same schema — just swap the renderer -->
+<TailwindFormRenderer :form="form" submit-label="Save" />
+```
 
-`useForm` is generic over the shape of the values object. Supply the type explicitly to get full inference on `values.value`:
+All field components are also exported individually:
 
 ```ts
-interface UserForm {
-  name: string
-  email: string
-  age: number | null
-  role: 'admin' | 'user'
-}
+import {
+  TwTextField, TwSelectField, TwCheckboxField,
+  TwRadioField, TwFileField, TwArrayField,
+  // …
+} from '@macrulez/vue-form-schema/ui/tailwind'
+```
 
-const { values, submit } = useForm<UserForm>({
-  schema,
-  onSubmit: (data) => {
-    // data is typed as UserForm
-    console.log(data.name)
-  },
-})
+---
 
-// values.value is Ref<UserForm>
-```
+## Accessibility
 
-### Validator function types
+All built-in field components include full a11y attributes:
 
-```ts
-import type { ValidatorFn, AsyncValidatorFn } from 'vue-form-schema'
+| Feature | How |
+|---|---|
+| `aria-required` | Set to `"true"` on required inputs, selects, textareas, fieldsets |
+| `aria-invalid` | Set to `"true"` when the field is touched and has errors |
+| `aria-describedby` | Points to `"{name}-error"` when errors are present |
+| `role="alert"` + `aria-live="polite"` | Error lists are announced by screen readers on appearance |
+| `label[for]` + `input[id]` | All inputs have matching label and id |
+| `fieldset` + `legend` | Radio groups use semantic grouping |
+| `aria-checked` | Checkboxes reflect boolean state explicitly |
 
-// Sync: (value, allValues) => string | null
-const myValidator: ValidatorFn = (value, allValues) => {
-  return String(value).length > 0 ? null : 'Required'
-}
+---
 
-// Async: (value, allValues) => Promise<string | null>
-const myAsyncValidator: AsyncValidatorFn = async (value) => {
-  const ok = await checkServer(value)
-  return ok ? null : 'Not available'
-}
-```
+## SSR compatibility
+
+The core (`useForm`, validators, parsers, `ConditionEvaluator`) does not use browser APIs. `bindMask` and `FormRenderer` use DOM APIs — wrap them in `onMounted` or `<ClientOnly>` when needed.
 
 ---
 
@@ -773,40 +1082,25 @@ const myAsyncValidator: AsyncValidatorFn = async (value) => {
 ```
 useForm
   │
-  ├── SchemaParser (json / zod / yup)
+  ├── Schema normalisation (json / zod / yup / valibot)
   │     └── FieldDefinition[]
   │
   ├── ConditionEvaluator
-  │     reactive watchEffect → resolves visible / disabled per field
+  │     watchEffect → resolves visible / disabled / options per field
   │
   ├── ValidationEngine
   │     sync validators   → errors Record<path, string[]>
-  │     async validators  → debounced, merged into errors
+  │     async validators  → debounced 300ms
   │
   ├── MaskEngine (standalone)
   │     applyMask / removeMask / bindMask
   │
-  └── (optional) FormRenderer [/ui]
-        renders FieldDefinition[] → input components
-        slots: #field-{name}, #label-{name}, #error-{name}, #submit
-```
-
-**Module dependency graph:**
-
-```
-index.ts
-├── core/types.ts
-├── core/useForm.ts
-│   ├── core/ValidationEngine.ts
-│   ├── core/ConditionEvaluator.ts
-│   └── parsers/json.ts
-├── core/MaskEngine.ts
-├── parsers/zod.ts  ← vue-form-schema/zod
-└── parsers/yup.ts  ← vue-form-schema/yup
-
-ui/index.ts         ← vue-form-schema/ui
-├── ui/FormRenderer.vue
-└── ui/fields/*.vue
+  └── (optional) UI subpackages
+        FormRenderer             [/ui]
+        TailwindFormRenderer     [/ui/tailwind]
+        useFieldArray            [core]
+        useMultiStepForm         [core]
+        useFormDebug             [core]
 ```
 
 ---
@@ -815,10 +1109,12 @@ ui/index.ts         ← vue-form-schema/ui
 
 | Entry point | Peer deps | Notes |
 |---|---|---|
-| `vue-form-schema` | `vue ^3.3` | Core ≤ 8 KB gzip |
-| `vue-form-schema/zod` | `zod ^3` | Lazy — zero cost if unused |
-| `vue-form-schema/yup` | `yup ^1` | Lazy — zero cost if unused |
-| `vue-form-schema/ui` | `vue ^3.3` | Optional UI layer |
+| `vue-form-schema` | `vue ^3.3` | Core — headless, no UI |
+| `vue-form-schema/zod` | `zod ^3` | Optional adapter |
+| `vue-form-schema/yup` | `yup ^1` | Optional adapter |
+| `vue-form-schema/valibot` | `valibot ^1` | Optional adapter |
+| `vue-form-schema/ui` | `vue ^3.3` | BEM-styled built-in components |
+| `vue-form-schema/ui/tailwind` | `vue ^3.3`, Tailwind CSS | Tailwind utility-class components |
 
 All entry points are tree-shakeable ESM + CJS dual builds.