@uniform-ts/core 0.0.4 → 0.0.5

package/README.md

@@ -2,46 +2,15 @@
 
 > Headless React + Zod V4 form library. Zero styles — bring your own components.
 
-UniForm takes a Zod schema and automatically renders a fully customizable form. It handles introspection, validation, coercion, and layout — you provide the components and styling.
+UniForm takes a Zod schema and automatically renders a fully customizable form. It handles field introspection, validation, coercion, and layout — you provide the components and styling.
 
-## Features
-
-- **Schema-driven** — define your form once with Zod V4, get inputs, labels, validation, and types for free
-- **Headless** — zero CSS, zero opinions; bring your own design system
-- **Full Zod V4 support** — scalars, enums, objects, arrays, optionals, nullables, defaults, pipes/transforms, unions, discriminated unions
-- **react-hook-form** under the hood — performant, uncontrolled forms with `zodResolver`
-- **`createForm()` / `UniForm`** — type-safe form definition object that lives outside React; attach typed `setOnChange` handlers per field with access to all form methods
-- **Per-field `onChange` in `fields` prop** — react to individual field changes inline, with typed values and full form control methods
-- **Per-field custom components** — pass any `React.ComponentType<FieldProps>` directly as `meta.component` (inline, no registry) or register under a custom string key; direct components bypass the registry _and_ the default `ArrayField`/`ObjectField` routing, allowing fully custom multi-value widgets for `array`-typed fields
-- **Layout hooks** — `classNames`, `fieldWrapper`, `layout.formWrapper`, `layout.sectionWrapper`, `layout.submitButton`
-- **Section grouping** — group fields into named sections via `meta.section`; style or swap individual section wrappers via `layout.sections`
-- **Conditional fields** — show/hide fields based on form values with `meta.condition`; hidden fields automatically reset to their default value
-- **Field ordering** — control render order with `meta.order`
-- **`createAutoForm()` factory** — bake in your design system defaults once, use everywhere
-- **Deep field overrides** — dot-notated `fields` prop for nested object/array overrides
-- **Pluggable coercion** — automatic string→number, string→Date with customizable coercion map
-- **Custom validation messages** — global, per-field, and per-field-per-error-code message overrides
-- **Programmatic control via ref** — `reset()`, `submit()`, `setValues()`, `getValues()`, `setErrors()`, `clearErrors()`, `focus()`, `isSubmitting` via `AutoFormHandle`
-- **Form state persistence** — auto-save form values to `localStorage` (or custom storage) with configurable debounce; restored on mount, cleared on submit
-- **Enhanced array fields** — opt-in row reordering (move up/down), duplicate, collapsible object rows with summary, `minItems`/`maxItems` constraints from Zod `.min()`/`.max()`, via `movable`/`duplicable`/`collapsible` meta flags
-- **Array button styling** — `classNames.arrayAdd`, `arrayRemove`, `arrayMove`, `arrayDuplicate`, `arrayCollapse`
-- **Custom array row layout** — `layout.arrayRowLayout` lets you fully control button placement within each array row
-- **Field index & depth CSS vars** — `--field-index` and `--field-depth` on every field wrapper for advanced CSS targeting
-- **Value cascade** — `onValuesChange` fires on every change with the full form values; use with `ref.setValues()` to imperatively sync field values
-- **i18n / custom labels** — `labels` prop (and factory-level `labels` config) replaces every hard-coded UI string (`"Submit"`, `"Add"`, `"Remove"`, move/duplicate/collapse buttons) without touching layout slots
-- **Async `setOnChange`** — `UniForm.setOnChange` handlers can be `async`; use them to fetch dependent data (e.g. cascading dropdowns, availability checks) and apply the results via `ctx.setFieldMeta` / `ctx.setValue`
-- **Async `defaultValues`** — pass `() => Promise<Partial<TValues>>` as `defaultValues`; the form renders a `loadingFallback` while the promise is in flight, then resets with the loaded values
-- **Tree-shakeable** — ESM + CJS builds via tsup with `sideEffects: false`
-
-## Quick Start
-
-### Installation
+## Installation
 
 ```bash
 npm install @uniform-ts/core react react-hook-form zod
 ```
 
-### Basic Usage
+## Quick Start
 
 ```tsx
 import * as z from 'zod/v4'
@@ -50,12 +19,11 @@ import { createForm, AutoForm } from '@uniform-ts/core'
 const schema = z.object({
   name: z.string().min(1, 'Name is required'),
   email: z.email('Invalid email'),
-  age: z.number().min(0).optional(),
   role: z.enum(['user', 'admin', 'editor']),
   subscribe: z.boolean(),
 })
 
-// createForm wraps your schema — pass the result to <AutoForm form={...}>
+// createForm wraps your schema and holds typed onChange handlers
 const myForm = createForm(schema)
 
 function MyForm() {
@@ -63,1114 +31,70 @@ function MyForm() {
     <AutoForm
       form={myForm}
       defaultValues={{ role: 'user', subscribe: false }}
-      onSubmit={(values) => {
-        // values is fully typed as z.infer<typeof schema>
-        console.log(values)
-      }}
-    />
-  )
-}
-```
-
-That's it — UniForm introspects the schema, renders appropriate inputs, validates with Zod, and calls `onSubmit` with typed values.
-
-## API Reference
-
-### `<AutoForm>` Props
-
-| Prop              | Type                                                                      | Default               | Description                                                                                                          |
-| ----------------- | ------------------------------------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `form`            | `UniForm<TSchema>`                                                        | _required_            | A `UniForm` / `createForm` instance carrying the schema and setOnChange handlers                                     |
-| `onSubmit`        | `(values: z.infer<TSchema>) => void \| Promise<void>`                     | _required_            | Called with fully typed, validated values on successful submit                                                       |
-| `defaultValues`   | `Partial<z.infer<TSchema>>` or `() => Promise<Partial<z.infer<TSchema>>>` | `{}`                  | Pre-fill form fields. Pass an async function to load from an API (see [Async Default Values](#async-default-values)) |
-| `components`      | `ComponentRegistry`                                                       | `defaultRegistry`     | Override field type → component mapping                                                                              |
-| `fields`          | `Record<string, Partial<FieldOverride>>`                                  | `{}`                  | Per-field metadata overrides (supports dot-notated paths for nested fields)                                          |
-| `fieldWrapper`    | `React.ComponentType<FieldWrapperProps>`                                  | `DefaultFieldWrapper` | Wrap each scalar field in a custom container                                                                         |
-| `layout`          | `LayoutSlots`                                                             | `{}`                  | Replace form wrapper, section wrapper, submit button, array row layout, or `loadingFallback`                         |
-| `classNames`      | `FormClassNames`                                                          | `{}`                  | CSS class names for form, field wrappers, labels, errors, descriptions                                               |
-| `disabled`        | `boolean`                                                                 | `false`               | Disable all form fields and the submit button                                                                        |
-| `coercions`       | `CoercionMap`                                                             | `defaultCoercionMap`  | Custom per-type value coercion functions                                                                             |
-| `messages`        | `ValidationMessages`                                                      | `undefined`           | Custom validation error messages                                                                                     |
-| `ref`             | `React.Ref<AutoFormHandle>`                                               | `undefined`           | Imperative handle for programmatic control                                                                           |
-| `persistKey`      | `string`                                                                  | `undefined`           | When set, form values auto-save to storage under this key                                                            |
-| `persistDebounce` | `number`                                                                  | `300`                 | Debounce interval in ms for persistence writes                                                                       |
-| `persistStorage`  | `PersistStorage`                                                          | `localStorage`        | Custom storage adapter (must implement `getItem`/`setItem`/`removeItem`)                                             |
-| `onValuesChange`  | `(values: z.infer<TSchema>) => void`                                      | `undefined`           | Called on every field change with the full current form values                                                       |
-| `labels`          | `FormLabels`                                                              | `{}`                  | Override hard-coded UI text (submit button, array buttons) for i18n                                                  |
-
-### `createForm(schema)` / `UniForm`
-
-`createForm` wraps a Zod schema in a `UniForm` instance. Pass the result to `<AutoForm form={...}>`.
-
-The main reason to use `UniForm` over passing a bare schema is typed `setOnChange` handlers: you can react to individual field changes, read the new value (typed to the schema), and call any form method — all outside React.
-
-```tsx
-import { createForm, AutoForm } from '@uniform-ts/core'
-
-const addressForm = createForm(addressSchema)
-  .setOnChange('country', (value, ctx) => {
-    // value is typed as the 'country' field type
-    ctx.setFieldMeta('state', { hidden: value !== 'US' })
-    ctx.setValue('state', undefined)
-  })
-
-// In component:
-<AutoForm form={addressForm} onSubmit={handleSubmit} />
-```
-
-#### `UniForm.setOnChange(field, handler)`
-
-Set the typed onChange handler for a specific field. Returns `this` for chaining. Calling `setOnChange` again for the same field **replaces** the previous handler — only one handler per field is active at a time. This prevents accidental handler accumulation when called inside a React render cycle.
-
-**Handler receives:**
-
-- `value` — the new field value, typed to the schema
-- `ctx: UniFormContext` — all `FormMethods` plus `setFieldMeta`
-
-#### `UniFormContext`
-
-The context passed to every `setOnChange` handler. Extends `FormMethods` with:
-
-| Method                      | Description                                                                                                                                                                      |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `setFieldMeta(field, meta)` | Dynamically override per-field UI properties (`hidden`, `disabled`, `options`, `label`, `placeholder`, `description`). Pass `value` to immediately call `setValue` on the field. |
-
-All standard `FormMethods` are also available: `setValue`, `setValues`, `getValues`, `resetField`, `reset`, `setError`, `setErrors`, `clearErrors`, `submit`, `focus`.
-
-#### `UniForm.condition(field, predicate)`
-
-Attach a typed visibility condition for a specific field. The field is shown when `predicate(values)` returns `true`. Takes precedence over any `condition` set via the `fields` prop.
-
-```ts
-const form = createForm(schema).condition(
-  'companyName',
-  (values) => values.type === 'business',
-)
-```
-
-### `createAutoForm(config)`
-
-Factory function that returns a pre-configured `<AutoForm>` component with baked-in defaults.
-
-```tsx
-import { createAutoForm } from '@uniform-ts/core'
-
-const MyAutoForm = createAutoForm({
-  components: { string: MyTextInput, number: MyNumberInput },
-  fieldWrapper: MyFieldWrapper,
-  layout: { submitButton: MySubmitButton },
-  classNames: { form: 'my-form', label: 'my-label' },
-  disabled: false,
-  coercions: { number: (v) => (v === '' ? undefined : Number(v)) },
-  messages: { required: 'This field is required' },
-})
-
-// Use it — no need to pass components/layout/classNames every time
-<MyAutoForm form={myForm} onSubmit={handleSubmit} />
-
-// Instance props merge with and override factory defaults
-<MyAutoForm form={myForm} onSubmit={handleSubmit} classNames={{ form: 'override' }} />
-```
-
-**Config type:** `AutoFormConfig`
-
-| Key            | Type                                     | Merge behavior                                   |
-| -------------- | ---------------------------------------- | ------------------------------------------------ |
-| `components`   | `ComponentRegistry`                      | Deep merge (instance overrides specific keys)    |
-| `fieldWrapper` | `React.ComponentType<FieldWrapperProps>` | Instance replaces factory                        |
-| `layout`       | `LayoutSlots`                            | Shallow merge (except `sections` — deep-merged)  |
-| `classNames`   | `FormClassNames`                         | Shallow merge                                    |
-| `disabled`     | `boolean`                                | OR logic (either `true` → disabled)              |
-| `coercions`    | `CoercionMap`                            | Shallow merge                                    |
-| `messages`     | `ValidationMessages`                     | Shallow merge                                    |
-| `labels`       | `FormLabels`                             | Shallow merge (instance overrides specific keys) |
-
-### Types
-
-#### `FieldMeta`
-
-Metadata attached to each field, extracted from Zod's `.meta()` or set via the `fields` prop:
-
-```ts
-type FieldMeta = {
-  label?: string
-  placeholder?: string
-  description?: string
-  section?: string // Group field into a named section
-  order?: number // Control render order
-  span?: number // Grid column hint (set as --field-span CSS var)
-  hidden?: boolean // Hide the field
-  disabled?: boolean // Disable the field
-  options?: SelectOption[] // Override options for select fields
-  condition?: (values: Record<string, unknown>) => boolean // Show/hide conditionally
-  component?: string | React.ComponentType<FieldProps>
-  //          ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-  //          registry key        direct component (bypasses registry)
-  onChange?: (value: unknown, form: FormMethods) => void | Promise<void> // Per-field change handler (may be async)
-  [key: string]: unknown // Extensible
-}
-```
-
-#### `FieldOverride`
-
-The type for entries in the `fields` prop. Like `FieldMeta`, but with typed `condition` and `onChange`:
-
-```ts
-type FieldOverride<TSchema, TValue> = Partial<FieldMetaBase> & {
-  condition?: (values: z.infer<TSchema>) => boolean
-  onChange?: (
-    value: TValue,
-    form: FormMethods<z.infer<TSchema>>,
-  ) => void | Promise<void>
-  [key: string]: unknown
-}
-```
-
-#### `ComponentRegistry`
-
-Map field types to React components:
-
-```ts
-type ComponentRegistry = {
-  string?: React.ComponentType<FieldProps>
-  number?: React.ComponentType<FieldProps>
-  boolean?: React.ComponentType<FieldProps>
-  date?: React.ComponentType<FieldProps>
-  select?: React.ComponentType<FieldProps>
-  textarea?: React.ComponentType<FieldProps>
-  [key: string]: React.ComponentType<FieldProps> | undefined
-}
-```
-
-#### `FieldProps`
-
-Props received by every field component:
-
-```ts
-type FieldProps = {
-  name: string
-  value: unknown
-  onChange: (value: unknown) => void
-  onBlur: () => void
-  ref: RefCallBack // react-hook-form ref for DOM registration
-  label: string
-  placeholder?: string
-  description?: string
-  error?: string
-  required: boolean
-  disabled?: boolean
-  options?: SelectOption[] // For select fields
-  meta: FieldMeta
-}
-```
-
-#### `FieldWrapperProps`
-
-Props received by the field wrapper component:
-
-```ts
-type FieldWrapperProps = {
-  children: React.ReactNode
-  field: FieldConfig
-  error?: string
-  span?: number
-  index?: number // Zero-based render index → --field-index CSS var
-  depth?: number // Nesting depth (0 = top-level) → --field-depth CSS var
-}
-```
-
-#### `FormMethods`
-
-All programmatic form control methods — available on `UniFormContext`, in per-field `onChange` callbacks, and as `AutoFormHandle` via `ref`:
-
-```ts
-type FormMethods<TValues> = {
-  setValue: (name, value) => void
-  setValues: (values: Partial<TValues>) => void
-  getValues: () => TValues
-  watch: (() => TValues) & (<K extends keyof TValues>(name: K) => TValues[K])
-  resetField: (name) => void
-  reset: (values?: Partial<TValues>) => void
-  setError: (name, message: string) => void
-  setErrors: (errors: Partial<Record<string, string>>) => void
-  clearErrors: (names?) => void
-  submit: () => void
-  focus: (fieldName) => void
-}
-```
-
-#### `LayoutSlots`
-
-```ts
-type LayoutSlots = {
-  formWrapper?: React.ComponentType<{ children: React.ReactNode }>
-  sectionWrapper?: React.ComponentType<{
-    children: React.ReactNode
-    title: string
-    className?: string
-  }>
-  submitButton?: React.ComponentType<{ isSubmitting: boolean }>
-  arrayRowLayout?: React.ComponentType<ArrayRowLayoutProps>
-  /** Shown while async `defaultValues` are resolving. Default: `<p>Loading…</p>` */
-  loadingFallback?: React.ReactNode
-  /** Per-section styling / component overrides keyed by section title. */
-  sections?: Record<string, SectionConfig>
-}
-```
-
-#### `SectionConfig`
-
-```ts
-type SectionConfig = {
-  /** CSS class name forwarded to the section wrapper. */
-  className?: string
-  /** Replace the section wrapper component for this section only. */
-  component?: React.ComponentType<{
-    children: React.ReactNode
-    title: string
-    className?: string
-  }>
-}
-```
-
-> **Tip:** Since `loadingFallback` is part of `LayoutSlots`, you can set a global loading UI once in `createAutoForm({ layout: { loadingFallback: <AppSpinner /> } })` and every form using that factory will automatically use it.
-
-#### `ArrayRowLayoutProps`
-
-```ts
-type ArrayRowLayoutProps = {
-  children: React.ReactNode // The rendered form fields for this row
-  buttons: {
-    moveUp: React.ReactNode | null
-    moveDown: React.ReactNode | null
-    duplicate: React.ReactNode | null
-    remove: React.ReactNode
-    collapse: React.ReactNode | null
-  }
-  index: number
-  rowCount: number
-}
-```
-
-#### `FieldDependencyResult`
-
-Return type of `ctx.setFieldMeta()` inside UniForm `setOnChange` handlers. All fields are optional — return only what you want to override:
-
-```ts
-type FieldDependencyResult = {
-  options?: SelectOption[] // Override available options (for select fields)
-  hidden?: boolean // Show or hide the field
-  disabled?: boolean // Enable or disable the field
-  label?: string // Override the field label
-  placeholder?: string // Override the placeholder
-  description?: string // Override the description
-}
-```
-
-```ts
-type FormClassNames = {
-  form?: string
-  fieldWrapper?: string
-  label?: string
-  description?: string
-  error?: string
-  arrayAdd?: string
-  arrayRemove?: string
-  arrayMove?: string
-  arrayDuplicate?: string
-  arrayCollapse?: string
-}
-```
-
-#### `CoercionMap`
-
-```ts
-type CoercionMap = Record<string, (value: unknown) => unknown>
-```
-
-Default coercions: `number` (empty→`undefined`, else `Number()`), `date` (empty→`undefined`, else `new Date()`), `boolean` (`Boolean()`), `string` (`null`→`''`).
-
-#### `ValidationMessages`
-
-```ts
-type ValidationMessages = {
-  required?: string // Global required override
-  [fieldName: string]: string | Record<string, string> | undefined
-  //                   ^^^^^^   ^^^^^^^^^^^^^^^^^^^^^^
-  //                   catch-all  per-error-code map
-}
-```
-
-## Recipes
-
-### Custom Components
-
-Replace the default input for any field type:
-
-```tsx
-function MyTextInput(props: FieldProps) {
-  return (
-    <input
-      ref={props.ref}
-      id={props.name}
-      value={String(props.value ?? '')}
-      onChange={(e) => props.onChange(e.target.value)}
-      onBlur={props.onBlur}
-      placeholder={props.placeholder}
-      disabled={props.disabled}
-      className='my-input'
-    />
-  )
-}
-
-;<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  components={{ string: MyTextInput }}
-/>
-```
-
-### Per-field Custom Components
-
-You can override the component for a **single field** in two ways:
-
-#### Option 1 — Direct React component (inline, no registry needed)
-
-Pass a `React.ComponentType<FieldProps>` directly as `meta.component` — either in the Zod schema or via the `fields` prop:
-
-```tsx
-// In the Zod schema
-function StarRating(props: FieldProps) { /* ... */ }
-
-const schema = z.object({
-  title: z.string(),
-  rating: z.number().min(1).max(5).meta({ component: StarRating }),
-})
-
-<AutoForm form={createForm(schema)} onSubmit={handleSubmit} />
-```
-
-```tsx
-// Or via the fields prop (no schema change needed)
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  fields={{ rating: { component: StarRating } }}
-/>
-```
-
-The direct component **bypasses the registry entirely** and takes highest priority in the resolution chain.
-
-#### Array fields with a direct component
-
-A direct `meta.component` also bypasses the default `ArrayField` row-by-row UI. This lets you use a fully custom multi-value widget (e.g. a tag picker, multi-select) on a `z.array(z.string())` field — the component owns the whole array value:
-
-```tsx
-function TagPicker(props: FieldProps) {
-  const selected = Array.isArray(props.value) ? (props.value as string[]) : []
-  // ... render your chip UI, call props.onChange(newArray) on changes
-}
-
-const schema = z.object({
-  tags: z
-    .array(z.string())
-    .min(1, 'Pick at least one tag')
-    .meta({
-      component: TagPicker,
-      suggestions: ['React', 'TypeScript', 'Zod'],
-    }),
-})
-
-<AutoForm form={createForm(schema)} onSubmit={handleSubmit} />
-```
-
-Zod still validates the array (`.min(1)` etc.) — only the _render_ is taken over by your component.
-
-#### Option 2 — String field as select
-
-A `z.string()` field can be rendered as a select by setting `meta.component: 'select'` together with `meta.options`. UniForm treats it as type `"select"` during introspection:
-
-```ts
-const schema = z.object({
-  role: z.string().meta({
-    component: 'select',
-    options: [
-      { label: 'User', value: 'user' },
-      { label: 'Admin', value: 'admin' },
-      { label: 'Editor', value: 'editor' },
-    ],
-  }),
-})
-```
-
-This is an alternative to `z.enum(...)` — useful when the option list is dynamic or when you need a plain `string` output type rather than a union literal.
-
-#### Option 3 — Named key in the registry
-
-Register a component under a custom string key — either in `createAutoForm` or the `components` prop — then reference it with `meta.component: 'yourKey'`:
-
-```tsx
-// Register at factory level, available to all forms
-const AppAutoForm = createAutoForm({
-  components: {
-    colorpicker: ColorPicker,
-    autocomplete: AutocompleteInput,
-  },
-})
-
-const schema = z.object({
-  theme: z.string().meta({ component: 'colorpicker' }),
-  city: z.string().meta({ component: 'autocomplete' }),
-})
-
-<AppAutoForm form={createForm(schema)} onSubmit={handleSubmit} />
-```
-
-```tsx
-// Or register per-instance via the components prop
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  components={{ colorpicker: ColorPicker }}
-  fields={{ theme: { component: 'colorpicker' } }}
-/>
-```
-
-**Resolution priority** (highest → lowest):
-
-1. Direct React component in `meta.component`
-2. String key in `meta.component` → merged registry
-3. Field type key in merged registry (e.g. `string`, `number`)
-4. Field type key in default registry
-5. Warn + render nothing
-
-### Field onChange Handlers
-
-React to individual field changes — inline via the `fields` prop (typed to the schema), or statically via `UniForm.setOnChange`.
-
-#### Inline via `fields` prop
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  fields={{
-    country: {
-      onChange: (value, form) => {
-        // value is typed as the 'country' field type
-        // form provides setValue, setValues, getValues, reset, etc.
-        form.setValue('state', undefined)
-      },
-    },
-  }}
-/>
-```
-
-#### Statically via `createForm` / `UniForm` (outside the component)
-
-```tsx
-// Define once at module level — handlers are stable, no React rules apply
-const addressForm = createForm(addressSchema).setOnChange(
-  'country',
-  (value, ctx) => {
-    ctx.setFieldMeta('state', { hidden: value !== 'US' })
-    ctx.setValue('state', undefined)
-  },
-)
-
-function MyForm() {
-  return <AutoForm form={addressForm} onSubmit={handleSubmit} />
-}
-```
-
-`UniForm.setOnChange` also supports `ctx.setFieldMeta` for dynamic field overrides — not available in the inline `fields` version.
-
-#### Async handlers
-
-`setOnChange` handlers (both inline and on `UniForm`) can be `async`. This is useful for server-side lookups that update other fields:
-
-```tsx
-const productForm = createForm(productSchema).setOnChange(
-  'sku',
-  async (sku, ctx) => {
-    // Disable the derived field while loading
-    ctx.setFieldMeta('productName', { disabled: true, placeholder: 'Loading…' })
-
-    const { name } = await fetchProduct(sku)
-
-    ctx.setValue('productName', name)
-    ctx.setFieldMeta('productName', { disabled: false, placeholder: '' })
-  },
-)
-```
-
-Async handlers are **fire-and-forget** — the field value is already committed to RHF before the async work runs. Cancel in-flight requests yourself with `AbortController` if needed.
-
-### Grid Layout with `classNames` and `span`
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  classNames={{
-    form: 'grid grid-cols-12 gap-4',
-    fieldWrapper: 'p-2',
-    label: 'font-semibold block mb-1',
-    error: 'text-red-500 text-sm',
-  }}
-  fields={{
-    firstName: { span: 6 },
-    lastName: { span: 6 },
-    email: { span: 12 },
-  }}
-/>
-```
-
-The `span` value is set as `--field-span` CSS custom property on each field wrapper. Each wrapper also receives `--field-index` (zero-based render order) and `--field-depth` (nesting depth). Use CSS Grid to consume them:
-
-```css
-.grid > * {
-  grid-column: span var(--field-span, 12);
-}
-/* Style every other top-level field */
-.grid > *:nth-child(even) {
-  background: var(--field-index);
-}
-```
-
-### Section Grouping
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  fields={{
-    firstName: { section: 'Personal', order: 1 },
-    lastName: { section: 'Personal', order: 2 },
-    street: { section: 'Address', order: 3 },
-    city: { section: 'Address', order: 4 },
-  }}
-  layout={{
-    sectionWrapper: ({ children, title, className }) => (
-      <fieldset className={className}>
-        <legend>{title}</legend>
-        {children}
-      </fieldset>
-    ),
-  }}
-/>
-```
-
-Use `layout.sections` to style or swap the wrapper for individual sections:
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  layout={{
-    sections: {
-      Personal: { className: 'bg-blue-50 p-4 rounded' },
-      Address: { component: AddressCard }, // completely different component
-    },
-  }}
-/>
-```
-
-`className` is forwarded as a prop to the active wrapper (global `sectionWrapper` or the per-section `component`). Factory-level and instance-level `sections` are merged — instance wins on conflicts.
-
-### Conditional Fields
-
-Show a field only when another field has a specific value. Conditional fields are fully lifecycle-managed:
-
-- **Hidden → not submitted:** fields whose condition starts `false` are never pre-registered in the form store, so they don't appear in `onSubmit` data.
-- **Shown → hidden:** when a condition becomes `false` and the field unmounts, its value is discarded — it starts fresh the next time it appears.
-
-```tsx
-const schema = z.object({
-  type: z.enum(['personal', 'business']),
-  companyName: z.string().optional(),
-})
-
-const myForm = createForm(schema)
-  // Attach condition on the UniForm instance (takes precedence over fields prop):
-  .condition('companyName', (values) => values.type === 'business')
-
-// Or via the fields prop:
-<AutoForm
-  form={createForm(schema)}
-  onSubmit={handleSubmit}
-  fields={{
-    companyName: {
-      condition: (values) => values.type === 'business',
-    },
-  }}
-/>
-```
-
-### Discriminated Unions
-
-Pass a `z.discriminatedUnion` directly to `createForm` — no flat schema needed:
-
-```tsx
-import * as z from 'zod/v4'
-import { createForm, AutoForm } from '@uniform-ts/core'
-
-const notificationUnion = z.discriminatedUnion('channel', [
-  z.object({
-    channel: z.literal('email'),
-    recipientEmail: z.string().email('Must be a valid email'),
-    subject: z.string().min(1, 'Subject is required'),
-  }),
-  z.object({
-    channel: z.literal('sms'),
-    phoneNumber: z
-      .string()
-      .regex(/^\+?[1-9]\d{7,14}$/, 'Must be a valid phone number'),
-    messageBody: z.string().max(160, 'SMS body must be ≤ 160 chars'),
-  }),
-  z.object({
-    channel: z.literal('webhook'),
-    endpointUrl: z.string().url('Must be a valid URL'),
-    secret: z.string().min(16, 'Secret must be at least 16 characters'),
-  }),
-])
-
-const notificationForm = createForm(notificationUnion)
-
-function NotificationForm() {
-  return (
-    <AutoForm
-      form={notificationForm}
-      defaultValues={{ channel: 'email' }}
       onSubmit={(values) => console.log(values)}
     />
   )
 }
 ```
 
-**How it works:**
-
-- The discriminator field (`channel`) renders as a `select` with one option per variant
-- When the discriminator changes, AutoForm swaps to the matching variant and renders only that variant's fields
-- Validation uses the original union schema via `zodResolver` — only the active variant's fields are validated
-- **Shared fields** (same key in multiple variants) persist their values when switching variants, since react-hook-form retains unregistered field values by default
-- Variant-specific field values from a previous variant remain in the form store but are stripped by Zod during parsing
-
-### Custom Validation Messages
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  messages={{
-    required: 'This field is required', // Global
-    email: 'Please provide an email', // Per-field catch-all
-    age: { too_small: 'Must be at least 18' }, // Per-field per-code
-  }}
-/>
-```
-
-Resolution order: per-field per-code → per-field string → global `required` → Zod's original message.
-
-#### `AutoFormHandle`
-
-Imperative handle exposed via `ref`:
-
-```ts
-type AutoFormHandle<TSchema> = FormMethods<z.infer<TSchema>> & {
-  /** `true` while an async `onSubmit` handler is in flight. */
-  isSubmitting: boolean
-}
-// FormMethods: reset, submit, setValue, setValues, getValues, watch,
-//              resetField, setError, setErrors, clearErrors, focus
-```
-
-#### `PersistStorage`
-
-Adapter interface for form persistence (defaults to `localStorage`):
-
-```ts
-type PersistStorage = {
-  getItem: (key: string) => string | null
-  setItem: (key: string, value: string) => void
-  removeItem: (key: string) => void
-}
-```
-
-### Factory Pattern with `createAutoForm`
-
-```tsx
-import { createAutoForm, createForm } from '@uniform-ts/core'
-
-const AppAutoForm = createAutoForm({
-  components: {
-    string: MyTextInput,
-    number: MyNumberInput,
-    boolean: MyToggle,
-    select: MyDropdown,
-  },
-  fieldWrapper: MyFieldWrapper,
-  layout: { submitButton: MySubmitButton },
-  classNames: { form: 'app-form', label: 'app-label' },
-})
-
-// Then use it everywhere — no prop repetition
-<AppAutoForm form={createForm(userSchema)} onSubmit={saveUser} />
-<AppAutoForm form={createForm(settingsSchema)} onSubmit={saveSettings} />
-```
-
-### Deep Field Overrides
-
-Override metadata for nested fields using dot-notated paths:
-
-```tsx
-const schema = z.object({
-  address: z.object({
-    street: z.string(),
-    city: z.string(),
-    zip: z.string(),
-  }),
-})
-
-<AutoForm
-  form={createForm(schema)}
-  onSubmit={handleSubmit}
-  fields={{
-    'address.street': { placeholder: '123 Main St' },
-    'address.city': { label: 'City / Town' },
-    'address.zip': { span: 6 },
-  }}
-/>
-```
-
-### Programmatic Control via Ref
-
-Use `ref` to control the form from outside — ideal for wizards, external save buttons, and multi-step flows:
-
-```tsx
-import { useRef } from 'react'
-import { AutoForm } from '@uniform-ts/core'
-import type { AutoFormHandle } from '@uniform-ts/core'
-
-function WizardForm() {
-  const formRef = useRef<AutoFormHandle<typeof schema>>(null)
-
-  return (
-    <div>
-      <AutoForm ref={formRef} form={myForm} onSubmit={handleSubmit} />
-
-      <button onClick={() => formRef.current?.reset()}>Reset</button>
-      <button onClick={() => formRef.current?.submit()}>Save (external)</button>
-      <button onClick={() => formRef.current?.setValues({ name: 'Alice' })}>
-        Pre-fill
-      </button>
-    </div>
-  )
-}
-```
-
-All `AutoFormHandle` methods: `reset()`, `submit()`, `setValue()`, `setValues()`, `getValues()`, `watch()`, `resetField()`, `setError()`, `setErrors()`, `clearErrors()`, `focus()`, plus `isSubmitting` (boolean, `true` while async `onSubmit` is in flight).
-
-### Async Default Values
-
-Pass an async function as `defaultValues` to pre-fill the form from an API:
-
-```tsx
-async function loadProfile() {
-  const res = await fetch('/api/profile')
-  return res.json() // Returns Partial<ProfileValues>
-}
-
-function EditProfileForm() {
-  return (
-    <AutoForm
-      form={profileForm}
-      defaultValues={loadProfile} // async function — called once on mount
-      layout={{ loadingFallback: <ProfileSkeleton /> }} // shown while the promise is in flight
-      onSubmit={handleSubmit}
-    />
-  )
-}
-```
-
-- The form renders `loadingFallback` (or `<p>Loading…</p>` by default) until the promise resolves.
-- On resolve, the form resets with the loaded values and renders normally.
-- If you need to replay the loading state (e.g. when navigating between records), change the `key` prop on `<AutoForm>` to remount it.
-
-### Reading Live Values with `watch`
-
-`watch` reads the current live value of a field (or all fields) from outside the form. Unlike `getValues`, it subscribes to react-hook-form's render cycle, so it always reflects the latest value at call time.
-
-```tsx
-import { useRef } from 'react'
-import { AutoForm } from '@uniform-ts/core'
-import type { AutoFormHandle } from '@uniform-ts/core'
-
-const schema = z.object({
-  plan: z.enum(['free', 'pro', 'enterprise']),
-  seats: z.number().min(1),
-})
-
-const myForm = createForm(schema)
+UniForm introspects the schema, renders appropriate inputs, validates with Zod, and calls `onSubmit` with fully typed values.
 
-function PricingForm() {
-  const formRef = useRef<AutoFormHandle<typeof schema>>(null)
+## Key Concepts
 
-  return (
-    <div>
-      <AutoForm ref={formRef} form={myForm} onSubmit={handleSubmit} />
-
-      {/* Read a single field */}
-      <button
-        onClick={() => {
-          const plan = formRef.current?.watch('plan')
-          console.log('Current plan:', plan)
-        }}
-      >
-        Log current plan
-      </button>
-
-      {/* Read all fields */}
-      <button
-        onClick={() => {
-          const values = formRef.current?.watch()
-          console.log('All values:', values)
-        }}
-      >
-        Log all values
-      </button>
-    </div>
-  )
-}
-```
+**`createForm(schema)`** — creates a typed form definition outside React. Use `.setOnChange(field, handler)` to attach async field-level side effects (e.g. cascading dropdowns).
 
-> **Tip:** `watch` is most useful for reading values imperatively in event handlers. To react to changes as they happen, prefer `onValuesChange` or `UniForm.setOnChange`.
+**`createAutoForm(defaults)`** — factory that bakes in your design system defaults (components, classNames, fieldWrapper) once, so you don't repeat them on every form.
 
-### Form State Persistence
+**`components`** — a registry mapping Zod types (`string`, `number`, `boolean`, etc.) to your own input components. Pass a component directly on a field via `fields` for one-off overrides.
 
-Auto-save form values to storage so users don't lose progress on page reload:
+**`fields`** — per-field overrides using dot-notated paths. Control labels, descriptions, ordering, sections, conditions, and custom components without touching the schema.
 
 ```tsx
 <AutoForm
   form={myForm}
-  onSubmit={handleSubmit}
-  persistKey='my-form'
-  persistDebounce={500}
-/>
-```
-
-Values are restored on mount and cleared after a successful submit. Use `persistStorage` for a custom adapter (e.g. `sessionStorage`):
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  persistKey='my-form'
-  persistStorage={sessionStorage}
-/>
-```
-
-### Enhanced Array Fields
-
-Array fields support reordering, duplication, and collapsible rows — all **opt-in** via meta flags:
-
-```tsx
-const schema = z.object({
-  members: z.array(
-    z.object({
-      name: z.string().min(1),
-      email: z.string().email(),
-    }),
-  ).min(1).max(5), // Enforced: can't remove below 1, can't add above 5
-})
-
-<AutoForm
-  form={createForm(schema)}
-  onSubmit={handleSubmit}
+  components={{ string: MyTextInput, boolean: MyToggle }}
   fields={{
-    members: {
-      movable: true,      // Show ↑/↓ move buttons
-      duplicable: true,   // Show Duplicate button
-      collapsible: true,  // Show collapse/expand toggle (object items only)
-    },
+    email: { label: 'Work Email', description: 'We will never share it' },
+    role: { order: 0, section: 'Account' },
+    subscribe: { condition: (values) => values.role !== 'admin' },
   }}
-/>
-```
-
-- **`movable`**: Renders Move Up / Move Down buttons (only when >1 row)
-- **`duplicable`**: Renders a Duplicate button (hidden when at maxItems)
-- **`collapsible`**: Renders a collapse/expand toggle for object rows with summary text
-- **Add** and **Remove** are always shown
-- Constraints from `.min()` / `.max()` are enforced — "Add" is disabled at max, "Remove" is disabled at min
-
-Style the array buttons via `classNames`:
-
-```tsx
-<AutoForm
-  form={myForm}
   onSubmit={handleSubmit}
-  fields={{ members: { movable: true, duplicable: true, collapsible: true } }}
-  classNames={{
-    arrayAdd: 'btn btn-primary',
-    arrayRemove: 'btn btn-danger',
-    arrayMove: 'btn btn-secondary',
-    arrayDuplicate: 'btn btn-outline',
-    arrayCollapse: 'btn btn-ghost',
-  }}
 />
 ```
 
-### Custom Array Row Layout
+## Core Props
 
-Use `layout.arrayRowLayout` to control where buttons appear within each array row:
+| Prop            | Type                                     | Description                                                            |
+| --------------- | ---------------------------------------- | ---------------------------------------------------------------------- |
+| `form`          | `UniForm<TSchema>`                       | Schema + onChange handlers from `createForm()`                         |
+| `onSubmit`      | `(values) => void \| Promise<void>`      | Called with typed values after successful validation                   |
+| `defaultValues` | `Partial<...>` or `() => Promise<...>`   | Initial values; async function shows `loadingFallback`                 |
+| `components`    | `ComponentRegistry`                      | Map Zod types to your input components                                 |
+| `fields`        | `Record<string, FieldOverride>`          | Per-field label, description, order, section, condition                |
+| `fieldWrapper`  | `React.ComponentType<FieldWrapperProps>` | Custom wrapper around every scalar field                               |
+| `layout`        | `LayoutSlots`                            | Replace form/section/object/array wrappers, submit button, array rows  |
+| `classNames`    | `FormClassNames`                         | CSS classes for form, fields, labels, errors, fieldset/legend wrappers |
+| `ref`           | `React.Ref<AutoFormHandle>`              | Imperative `reset`, `submit`, `setValues`, `getValues`                 |
+| `persistKey`    | `string`                                 | Auto-save form state to `localStorage` under this key                  |
+| `labels`        | `FormLabels`                             | Override built-in UI strings for i18n                                  |
 
-```tsx
-import type { ArrayRowLayoutProps } from '@uniform-ts/core'
-
-function HorizontalRowLayout({
-  children,
-  buttons,
-  index,
-  rowCount,
-}: ArrayRowLayoutProps) {
-  return (
-    <div style={{ display: 'flex', gap: '0.5rem', alignItems: 'flex-start' }}>
-      <div style={{ display: 'flex', flexDirection: 'column' }}>
-        {buttons.moveUp}
-        {buttons.moveDown}
-      </div>
-      <div style={{ flex: 1 }}>{children}</div>
-      <div style={{ display: 'flex', gap: '0.25rem' }}>
-        {buttons.duplicate}
-        {buttons.remove}
-      </div>
-    </div>
-  )
-}
-
-;<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  fields={{ tasks: { movable: true, duplicable: true } }}
-  layout={{ arrayRowLayout: HorizontalRowLayout }}
-/>
-```
-
-The default layout renders collapse toggle, then children, then all action buttons in a row.
-
-### Customizing UI Text (i18n)
-
-Use the `labels` prop to replace every hard-coded string in the default UI — submit button, all array action buttons — without needing to replace entire layout slot components:
-
-```tsx
-<AutoForm
-  form={myForm}
-  onSubmit={handleSubmit}
-  labels={{
-    submit: 'Enviar',
-    arrayAdd: 'Agregar fila',
-    arrayRemove: 'Eliminar',
-    arrayMoveUp: '⬆ Subir',
-    arrayMoveDown: '⬇ Bajar',
-    arrayDuplicate: 'Duplicar',
-    arrayCollapse: '▼ Ocultar', // shown when row is expanded
-    arrayExpand: '▶ Mostrar', // shown when row is collapsed
-  }}
-/>
-```
-
-Set factory-level defaults with `labels` in `createAutoForm` — per-instance `labels` props shallow-merge and override:
-
-```tsx
-const AppAutoForm = createAutoForm({
-  labels: { submit: 'Save' },
-})
-
-// Uses factory default "Save"
-<AppAutoForm form={myForm} onSubmit={handleSubmit} />
-
-// Per-instance override wins → "Save & Close"
-<AppAutoForm form={myForm} onSubmit={handleSubmit} labels={{ submit: 'Save & Close' }} />
-```
-
-**`FormLabels` type reference:**
-
-```ts
-type FormLabels = {
-  submit?: string // default: "Submit"
-  arrayAdd?: string // default: "Add"
-  arrayRemove?: string // default: "Remove"
-  arrayMoveUp?: string // default: "↑"
-  arrayMoveDown?: string // default: "↓"
-  arrayDuplicate?: string // default: "Duplicate"
-  arrayCollapse?: string // shown when row is expanded (default: "▼")
-  arrayExpand?: string // shown when row is collapsed (default: "▶")
-}
-```
-
-All unspecified keys fall back to their built-in English defaults. `labels` only affects the **default** submit button and array controls — if you supply a custom `layout.submitButton` component, that component owns its own text.
-
-### Value Cascade (`onValuesChange`)
-
-Use `onValuesChange` together with a `ref` to set one field based on another:
-
-```tsx
-const formRef = useRef<AutoFormHandle<typeof schema>>(null)
-
-<AutoForm
-  ref={formRef}
-  form={myForm}
-  onSubmit={handleSubmit}
-  onValuesChange={(values) => {
-    const seats = { free: 1, starter: 5, pro: 20, enterprise: 100 }[values.plan]
-    if (seats !== undefined && values.seats !== seats) {
-      formRef.current?.setValues({ seats })
-    }
-  }}
-/>
-```
-
-**Always guard with an equality check** to prevent an infinite update loop.
-
-> **Tip:** For simple field-to-field reactions (resetting, toggling visibility), prefer `UniForm.setOnChange` or the `fields` prop `onChange` — they're more ergonomic and fully typed. Use `onValuesChange` when you need to observe the entire form state holistically.
-
-## Development
-
-```bash
-pnpm install       # Install dependencies
-pnpm build         # Build @uniform-ts/core
-pnpm test          # Run all tests
-pnpm dev           # Start the playground dev server
-```
-
-### Monorepo Structure
-
-```
-uniform/
-├── packages/
-│   └── core/          # The library (@uniform-ts/core)
-└── apps/
-    └── playground/    # Vite + React dev app
-```
-
-### Tech Stack
+## Features
 
-- **pnpm workspaces** — monorepo management
-- **tsup** — library bundler (ESM + CJS + `.d.ts`)
-- **Vite** — playground dev server
-- **Vitest** — unit and integration tests
-- **TypeScript** — strict mode throughout
-- **Zod V4** (`zod@>=3.25`, imported from `zod/v4`)
-- **react-hook-form** — form state management
-- **@hookform/resolvers** (`^5.2`) — Zod v4-aware resolver
+- **Full Zod V4 support** — scalars, enums, objects, arrays, optionals, defaults, unions, discriminated unions
+- **react-hook-form** under the hood — performant, uncontrolled forms with `zodResolver`
+- **Section grouping** — group fields into named sections via `meta.section`
+- **Conditional fields** — show/hide fields based on form values; hidden fields reset to default
+- **Array fields** — movable, duplicable, collapsible rows; `minItems`/`maxItems` from Zod schema
+- **Programmatic control** — `reset()`, `submit()`, `setValues()`, `getValues()`, `setErrors()`, `focus()` via ref
+- **Form persistence** — auto-save to `localStorage` (or custom storage) with configurable debounce
+- **Pluggable coercion** — automatic `string → number`, `string → Date` with customizable coercion map
+- **i18n** — override every hard-coded UI string via `labels` prop
+- **Tree-shakeable** — ESM + CJS builds via tsup
 
-## Contributing
+## Documentation
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Run tests (`pnpm test`) and ensure they pass
-4. Submit a pull request
+Full API reference, guides, and examples: **[uniformts.github.io/UniForm](https://uniformts.github.io/UniForm/)**
 
 ## License
 
-[MIT](LICENSE)
+MIT