@uniform-ts/core 0.0.0

package/dist/index.d.mts

@@ -0,0 +1,857 @@
+import * as React from 'react';
+import { FieldValues, FieldPath, FieldPathValue, RefCallBack, Control } from 'react-hook-form';
+import * as z from 'zod/v4/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Extracts the element type of an array type.
+ * e.g. `ArrayItem<{ name: string }[]>` → `{ name: string }`
+ */
+type ArrayItem<T> = T extends (infer U)[] ? U : never;
+/**
+ * Recursively produces all valid `fields` prop keys for a given schema shape:
+ *
+ * - Scalar fields  → just their key (e.g. `"name"`)
+ * - Object fields  → their key + all dot-notated child paths
+ *                    (e.g. `"address"` | `"address.street"`)
+ * - Array fields   → their key + the unprefixed keys of the item object, so
+ *                    you can target every row's sub-field uniformly
+ *                    (e.g. `"items"` | `"items.name"` | `"items.qty"`)
+ *                    Index-based paths like `"items.0.name"` are intentionally
+ *                    excluded — row count is dynamic at runtime.
+ *
+ * @example
+ * // Given { name: string; address: { street: string }; items: { qty: number }[] }
+ * // DeepKeys produces:
+ * //   "name" | "address" | "address.street" | "items" | "items.qty"
+ */
+type DeepKeys<T> = T extends object ? {
+    [K in keyof T & string]: T[K] extends unknown[] ? ArrayItem<T[K]> extends object ? K | `${K}.${DeepKeys<ArrayItem<T[K]>>}` : K : T[K] extends object ? K | `${K}.${DeepKeys<T[K]>}` : K;
+}[keyof T & string] : never;
+/**
+ * Resolves the value type at a dot-notated path within a type `T`.
+ * Array fields use the unprefixed child path (matching `DeepKeys` convention).
+ *
+ * @example
+ * // DeepFieldValue<{ name: string; items: { qty: number }[] }, 'items.qty'> → number
+ */
+type DeepFieldValue<T, K extends string> = K extends keyof T ? T[K] : K extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? T[Head] extends (infer Item)[] ? DeepFieldValue<NonNullable<Item>, Tail> : DeepFieldValue<NonNullable<T[Head]>, Tail> : unknown : unknown;
+/**
+ * The resolved primitive or structural type of a schema field, as determined
+ * by introspecting the Zod schema. Used internally to decide which field
+ * component to render.
+ */
+type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'select' | 'object' | 'array' | 'union' | 'unknown';
+/**
+ * A single option entry used in `select` / enum fields.
+ */
+type SelectOption = {
+    /** Human-readable text displayed in the dropdown. */
+    label: string;
+    /** The underlying value submitted with the form. */
+    value: string | number;
+};
+/**
+ * A predicate function that receives the current form values and returns
+ * `true` when the field should be visible, `false` when it should be hidden.
+ *
+ * @template TValues - The shape of the form values object.
+ */
+type FieldCondition<TValues = Record<string, unknown>> = (values: TValues) => boolean;
+/**
+ * All programmatic form control methods, shared by both the field `onChange`
+ * callback and the imperative ref handle.
+ *
+ * @template TSchema - The Zod object schema that defines the form shape.
+ */
+type FormMethods<TValues extends FieldValues = FieldValues> = {
+    /** Set a single field value programmatically */
+    setValue: <K extends FieldPath<TValues>>(name: K, value: FieldPathValue<TValues, K>) => void;
+    /** Set multiple field values at once */
+    setValues: (values: Partial<TValues>) => void;
+    /** Get the current form values */
+    getValues: () => TValues;
+    /** Reset a single field to its default value */
+    resetField: (name: FieldPath<TValues>) => void;
+    /** Reset the entire form, optionally to new values */
+    reset: (values?: Partial<TValues>) => void;
+    /** Set a validation error on a specific field */
+    setError: (name: FieldPath<TValues>, message: string) => void;
+    /** Set validation errors on multiple fields at once */
+    setErrors: (errors: Partial<Record<FieldPath<TValues>, string>>) => void;
+    /** Clear validation errors (all fields, or specific ones) */
+    clearErrors: (names?: FieldPath<TValues> | FieldPath<TValues>[]) => void;
+    /** Programmatically trigger form submission */
+    submit: () => void;
+    /** Focus a specific field by name (dot-notated for nested fields) */
+    focus: (fieldName: FieldPath<TValues>) => void;
+    /** Get the current value of a field (or all values if no name provided) */
+    watch: {
+        (): TValues;
+        <K extends FieldPath<TValues>>(name: K): FieldPathValue<TValues, K>;
+    };
+};
+/**
+ * Dynamic field property overrides passed to `ctx.setFieldMeta()` inside a
+ * UniForm onChange handler. Each key is optional — only the properties you
+ * provide will be applied; omitted keys leave the current field state unchanged.
+ */
+type FieldDependencyResult = {
+    /** Override the available options for select fields */
+    options?: SelectOption[];
+    /** Dynamically show or hide the field */
+    hidden?: boolean;
+    /** Dynamically enable or disable the field */
+    disabled?: boolean;
+    /** Override the field label */
+    label?: string;
+    /** Override the placeholder text */
+    placeholder?: string;
+    /** Override the description text */
+    description?: string;
+};
+/**
+ * The base set of per-field UI metadata that can be provided via the `fields`
+ * prop or through Zod schema extensions (`.meta()`).
+ *
+ * `FieldMeta` extends this type with an index signature to allow arbitrary
+ * extra keys for custom component use-cases.
+ */
+type FieldMetaBase = {
+    /** Human-readable label rendered above the field. Falls back to a derived label from the field name. */
+    label?: string;
+    /** Placeholder text rendered inside the input when it has no value. */
+    placeholder?: string;
+    /** Helper text rendered below the field to provide additional context. */
+    description?: string;
+    /** Static list of options for `select` / enum fields. */
+    options?: SelectOption[];
+    /** Group the field under a named section in the form layout. */
+    section?: string;
+    /** Explicit render order within the form or section (lower numbers render first). */
+    order?: number;
+    /** Grid column span for multi-column layouts (e.g. `1`–`12`). */
+    span?: number;
+    /** When `true`, the field is not rendered. */
+    hidden?: boolean;
+    /** When `true`, the field is rendered but not interactive. */
+    disabled?: boolean;
+    /** Conditionally show or hide the field based on the current form values. */
+    condition?: FieldCondition;
+    /**
+     * Override the component used to render this field.
+     *
+     * - **string** — a key registered in the `ComponentRegistry` (e.g. `'autocomplete'`
+     *   registered via `createAutoForm({ components: { autocomplete: MyComp } })` or the
+     *   `components` prop).
+     * - **React component** — a `FieldProps`-compatible component passed inline,
+     *   bypassing the registry entirely (e.g. `component: MyCustomInput`).
+     *
+     * Note: typed as `React.ComponentType<any>` here to avoid a circular type
+     * reference through `FieldProps → FieldMeta → component → FieldProps`.
+     * The `ComponentRegistry` keeps the stricter `React.ComponentType<FieldProps>`.
+     */
+    component?: string | React.ComponentType<any>;
+    /** Called when this field's value changes. Receives the new value and form control methods. May be async. */
+    onChange?: (value: unknown, form: FormMethods) => void | Promise<void>;
+    /** When `true`, rows in an array field can be reordered via move-up/move-down buttons. */
+    movable?: boolean;
+    /** When `true`, rows in an array field can be duplicated. */
+    duplicable?: boolean;
+    /** When `true`, rows in an array field can be individually collapsed. */
+    collapsible?: boolean;
+};
+/**
+ * Per-field UI metadata with an open index signature, allowing arbitrary
+ * extra keys for custom component use-cases. Extends `FieldMetaBase` with
+ * all the standard metadata properties.
+ */
+type FieldMeta = FieldMetaBase & {
+    [key: string]: unknown;
+};
+/**
+ * Common properties shared by every field variant.
+ */
+type FieldConfigBase = {
+    /** Dot-notated field path (e.g. `"address.street"`). */
+    name: string;
+    /** Display label for the field. */
+    label: string;
+    /** Whether the field is required by the schema. */
+    required: boolean;
+    /** Merged UI metadata for the field. */
+    meta: FieldMeta;
+};
+/**
+ * The fully resolved configuration for a single form field, produced by
+ * introspecting the Zod schema and merging any `fields` prop overrides.
+ * Consumed internally by field renderer components.
+ *
+ * This is a discriminated union on the `type` field — narrow on `type` to
+ * access the fields that are only present for specific field kinds (e.g.
+ * `children` for `"object"`, `itemConfig` for `"array"`, etc.).
+ */
+type FieldConfig = FieldConfigBase & ({
+    type: 'string';
+} | {
+    type: 'number';
+} | {
+    type: 'boolean';
+} | {
+    type: 'date';
+} | {
+    type: 'select';
+    /** Resolved options for `select` / enum fields. */
+    options: SelectOption[];
+} | {
+    type: 'object';
+    /** Child field configs for nested object fields. */
+    children: FieldConfig[];
+} | {
+    type: 'array';
+    /** Item field config describing a single row's shape. */
+    itemConfig: FieldConfig;
+    /** Minimum number of items (from `z.array().min(...)`). */
+    minItems?: number;
+    /** Maximum number of items (from `z.array().max(...)`). */
+    maxItems?: number;
+} | {
+    type: 'union';
+    /** Variant configs for each union member. */
+    unionVariants: FieldConfig[];
+    /** Discriminator key for discriminated unions. */
+    discriminatorKey?: string;
+} | {
+    type: 'unknown';
+});
+/**
+ * The props passed to every field renderer component. Provides the current
+ * value, change/blur handlers, and all resolved UI metadata needed to render
+ * a single field.
+ */
+type FieldProps = {
+    /** Dot-notated field path (e.g. `"address.street"`). */
+    name: string;
+    /** The current field value. */
+    value: unknown;
+    /** Callback to update the field value. */
+    onChange: (value: unknown) => void;
+    /** Callback fired when the field loses focus. */
+    onBlur: () => void;
+    /** Ref callback for registering the DOM element with `react-hook-form`. */
+    ref: RefCallBack;
+    /** Resolved display label for the field. */
+    label: string;
+    /** Placeholder text for the input. */
+    placeholder?: string;
+    /** Helper text rendered below the field. */
+    description?: string;
+    /** Validation error message for the field. */
+    error?: string;
+    /** Whether the field is required by the schema. */
+    required: boolean;
+    /** When `true`, the field is rendered but not interactive. */
+    disabled?: boolean;
+    /** Resolved options for `select` / enum fields. */
+    options?: SelectOption[];
+    /** Full field metadata, including any custom keys. */
+    meta: FieldMeta;
+};
+/**
+ * A map of field type keys to React components used to render them.
+ * Built-in keys (`string`, `number`, `boolean`, `date`, `select`, `textarea`)
+ * are pre-typed. Additional custom keys can be added via the index signature
+ * and registered through `createAutoForm` or the `components` prop.
+ */
+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;
+};
+/**
+ * Props passed to the field wrapper component that surrounds every rendered
+ * field. Used to render the label, description, error message, and grid span.
+ */
+type FieldWrapperProps = {
+    /** The field input component to wrap. */
+    children: React.ReactNode;
+    /** The fully resolved field configuration. */
+    field: FieldConfig;
+    /** Validation error message for the field. */
+    error?: string;
+    /** Grid column span override (takes precedence over `field.meta.span`). */
+    span?: number;
+    /**
+     * Zero-based render index of this field within its parent container
+     * (form root or section). Exposed as the `--field-index` CSS custom property.
+     */
+    index?: number;
+    /**
+     * Nesting depth of this field (0 = top-level, 1 = inside object, etc.).
+     * Exposed as the `--field-depth` CSS custom property.
+     */
+    depth?: number;
+};
+/**
+ * Props passed to the component that renders a single row inside an array field,
+ * including the row's content and action buttons (move, duplicate, remove, collapse).
+ */
+type ArrayRowLayoutProps = {
+    /** The rendered fields for this array item. */
+    children: React.ReactNode;
+    /** Action button nodes for the row. */
+    buttons: {
+        /** Button to move the row up, or `null` if already first. */
+        moveUp: React.ReactNode | null;
+        /** Button to move the row down, or `null` if already last. */
+        moveDown: React.ReactNode | null;
+        /** Button to duplicate the row, or `null` if at max items. */
+        duplicate: React.ReactNode | null;
+        /** Button to remove the row. */
+        remove: React.ReactNode;
+        /** Button to collapse/expand the row, or `null` if collapsing is disabled. */
+        collapse: React.ReactNode | null;
+    };
+    /** Zero-based index of this row within the array. */
+    index: number;
+    /** Total number of rows currently in the array. */
+    rowCount: number;
+};
+/**
+ * Optional layout slot overrides for top-level structural components of the
+ * form. Provide only the slots you want to replace; omitted slots fall back
+ * to the built-in defaults.
+ */
+type LayoutSlots = {
+    /** Wrapper rendered around the entire form. */
+    formWrapper?: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+    /** Wrapper rendered around each named field section. */
+    sectionWrapper?: React.ComponentType<{
+        children: React.ReactNode;
+        title: string;
+    }>;
+    /** Custom submit button component. */
+    submitButton?: React.ComponentType<{
+        isSubmitting: boolean;
+        label: string;
+    }>;
+    /** Custom layout component for individual rows in array fields. */
+    arrayRowLayout?: React.ComponentType<ArrayRowLayoutProps>;
+    /**
+     * Content rendered while async `defaultValues` are loading.
+     * Defaults to a simple `<p>Loading…</p>` when not provided.
+     */
+    loadingFallback?: React.ReactNode;
+};
+/**
+ * The resolved version of `LayoutSlots` used internally, where all slots are
+ * guaranteed to be defined (falling back to built-in defaults).
+ */
+type ResolvedLayoutSlots = {
+    formWrapper: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+    sectionWrapper: React.ComponentType<{
+        children: React.ReactNode;
+        title: string;
+    }>;
+    submitButton: React.ComponentType<{
+        isSubmitting: boolean;
+        label: string;
+    }>;
+    arrayRowLayout: React.ComponentType<ArrayRowLayoutProps>;
+    loadingFallback: React.ReactNode;
+};
+/**
+ * CSS class name overrides for the various structural elements of the form.
+ * Only the keys you provide will be applied; omitted keys use the built-in
+ * default class names (or none, if the default components don't apply any).
+ */
+type FormClassNames = {
+    /** Class applied to the `<form>` element. */
+    form?: string;
+    /** Class applied to each field wrapper. */
+    fieldWrapper?: string;
+    /** Class applied to each field label. */
+    label?: string;
+    /** Class applied to each field description. */
+    description?: string;
+    /** Class applied to each field error message. */
+    error?: string;
+    /** Class applied to the "add item" button in array fields. */
+    arrayAdd?: string;
+    /** Class applied to the "remove item" button in array fields. */
+    arrayRemove?: string;
+    /** Class applied to the "move item" buttons in array fields. */
+    arrayMove?: string;
+    /** Class applied to the "duplicate item" button in array fields. */
+    arrayDuplicate?: string;
+    /** Class applied to the "collapse item" button in array fields. */
+    arrayCollapse?: string;
+};
+/**
+ * A per-field override entry used in the AutoFormProps `fields` prop.
+ * The `onChange` callback is typed to the specific schema's inferred value
+ * type, providing full IDE autocomplete.
+ */
+type FieldOverride<TSchema extends z.$ZodObject = z.$ZodObject, TValue = unknown> = Partial<FieldMetaBase> & {
+    /** Conditionally show or hide the field based on the current form values. */
+    condition?: FieldCondition<z.infer<TSchema>>;
+    /** Called when this field's value changes. Receives the new value and form control methods. May be async. */
+    onChange?: (value: TValue, form: FormMethods<z.infer<TSchema>>) => void | Promise<void>;
+    [key: string]: unknown;
+};
+type FormLabels = {
+    /** Submit button text — default: "Submit" */
+    submit?: string;
+    /** Array "Add item" button — default: "Add" */
+    arrayAdd?: string;
+    /** Array "Remove row" button — default: "Remove" */
+    arrayRemove?: string;
+    /** Array "Move row up" button — default: "↑" */
+    arrayMoveUp?: string;
+    /** Array "Move row down" button — default: "↓" */
+    arrayMoveDown?: string;
+    /** Array "Duplicate row" button — default: "Duplicate" */
+    arrayDuplicate?: string;
+    /** Array row toggle shown when the row is expanded (clicking collapses it) — default: "▼" */
+    arrayCollapse?: string;
+    /** Array row toggle shown when the row is collapsed (clicking expands it) — default: "▶" */
+    arrayExpand?: string;
+};
+/**
+ * A map of field names to coercion functions. Each function receives the raw
+ * field value and returns the coerced value before Zod validation is applied.
+ * Useful for transforming string inputs (e.g. from native `<input>`) into the
+ * types expected by the schema (e.g. numbers, dates).
+ */
+type CoercionMap$1 = Record<string, (value: unknown) => unknown>;
+/**
+ * Custom validation error message overrides. Use `required` to override the
+ * global "required field" message, or provide a field name key to override
+ * messages for a specific field (supports nested dot-notated paths).
+ */
+type ValidationMessages = {
+    required?: string;
+    [fieldName: string]: string | Record<string, string> | undefined;
+};
+/**
+ * A minimal storage adapter interface compatible with `localStorage` and
+ * `sessionStorage`. Provide a custom implementation to persist form values
+ * to any backing store (e.g. IndexedDB, AsyncStorage).
+ */
+type PersistStorage = {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+};
+/**
+ * The imperative handle exposed via `ref` on `<AutoForm>`. Provides methods
+ * to programmatically control the form from a parent component.
+ *
+ * @template TSchema - The Zod object schema that defines the form shape.
+ */
+type AutoFormHandle<TSchema extends z.$ZodObject = z.$ZodObject> = FormMethods<z.infer<TSchema>> & {
+    /** `true` while an async `onSubmit` handler is in flight. */
+    isSubmitting: boolean;
+};
+/**
+ * Static configuration provided to `createAutoForm`. These options become the
+ * default for every form instance created by the factory, and can be
+ * overridden per-instance via the corresponding `<AutoForm>` props.
+ */
+type AutoFormConfig = {
+    /** Default component registry for all form instances. */
+    components?: ComponentRegistry;
+    /** Default field wrapper component for all form instances. */
+    fieldWrapper?: React.ComponentType<FieldWrapperProps>;
+    /** Default layout slot overrides for all form instances. */
+    layout?: LayoutSlots;
+    /** Default CSS class name overrides for all form instances. */
+    classNames?: FormClassNames;
+    /** When `true`, all fields in every form instance are disabled by default. */
+    disabled?: boolean;
+    /** Default coercion map applied to all form instances. */
+    coercions?: CoercionMap$1;
+    /** Default validation message overrides for all form instances. */
+    messages?: ValidationMessages;
+    /** Default label strings; overridden per-instance by the `labels` prop */
+    labels?: FormLabels;
+};
+/**
+ * Props for the `<AutoForm>` component. Drives schema introspection, field
+ * rendering, validation, and submission.
+ *
+ * @template TSchema - The Zod object schema that defines the form shape.
+ */
+type AutoFormProps<TSchema extends z.$ZodObject> = {
+    /** A UniForm instance carrying the schema and typed onChange handlers. */
+    form: {
+        readonly schema: TSchema;
+    };
+    /** Called with the validated form values when the form is submitted successfully. */
+    onSubmit: (values: z.infer<TSchema>) => void | Promise<void>;
+    /**
+     * Initial values to pre-populate the form with.
+     * When an async function is provided, the form shows `loadingFallback` until the
+     * promise resolves, then resets the form with the loaded values.
+     */
+    defaultValues?: Partial<z.infer<TSchema>> | (() => Promise<Partial<z.infer<TSchema>>>);
+    /** Component registry overrides for this form instance. */
+    components?: ComponentRegistry;
+    /** Per-field UI metadata overrides (label, placeholder, options, etc.). */
+    fields?: {
+        [K in DeepKeys<z.infer<TSchema>>]?: FieldOverride<TSchema, DeepFieldValue<z.infer<TSchema>, K>>;
+    };
+    /** Field wrapper component override for this form instance. */
+    fieldWrapper?: React.ComponentType<FieldWrapperProps>;
+    /** Layout slot overrides for this form instance. */
+    layout?: LayoutSlots;
+    /** CSS class name overrides for this form instance. */
+    classNames?: FormClassNames;
+    /** When `true`, all fields are rendered in a disabled (non-interactive) state. */
+    disabled?: boolean;
+    /** Coercion map applied before Zod validation for this form instance. */
+    coercions?: CoercionMap$1;
+    /** Validation message overrides for this form instance. */
+    messages?: ValidationMessages;
+    /** When set, form values are auto-saved to storage under this key */
+    persistKey?: string;
+    /** Debounce interval in ms for persistence writes (default: 300) */
+    persistDebounce?: number;
+    /** Custom storage adapter (default: localStorage) */
+    persistStorage?: PersistStorage;
+    /** Called on every value change with the current form values */
+    onValuesChange?: (values: z.infer<TSchema>) => void;
+    /** Customize hard-coded UI text (submit button, array buttons, etc.) */
+    labels?: FormLabels;
+};
+
+// zod@3.25+ — import from 'zod/v4'
+declare module 'zod/v4/core' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface GlobalMeta extends FieldMetaBase {}
+}
+
+// zod@4.x — import from 'zod'
+declare module 'zod' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface GlobalMeta extends FieldMetaBase {}
+}
+
+/**
+ * Recursively introspects a Zod schema and returns a {@link FieldConfig}
+ * describing the field's type, label, validation constraints, and UI metadata.
+ *
+ * Transparent wrappers (`optional`, `nullable`, `default`, `pipe`) are
+ * unwrapped before inspection. Unknown/unsupported types fall back to
+ * `type: 'unknown'` rather than throwing.
+ *
+ * @param schema - The Zod schema to introspect.
+ * @param name - The field key within its parent object (used for label derivation).
+ * @param parentPath - The dot-notated path of the parent (used to build `field.name`).
+ */
+declare function introspectSchema(schema: z.$ZodType, name?: string, parentPath?: string): FieldConfig;
+/**
+ * Introspects all fields of a top-level `ZodObject` schema and returns an
+ * ordered array of {@link FieldConfig} objects, one per key in `schema.shape`.
+ *
+ * This is the entry point used by `<AutoForm>` to derive the field list from
+ * the provided schema.
+ *
+ * @param schema - The top-level `ZodObject` schema to introspect.
+ */
+declare function introspectObjectSchema(schema: z.$ZodObject): FieldConfig[];
+
+/**
+ * The core auto-form component. Introspects the provided Zod `schema`,
+ * renders the appropriate field components, validates on submit using
+ * `zodResolver`, and calls `onSubmit` with the fully-typed, validated values.
+ *
+ * Supports: conditional fields, dynamic field meta via UniForm onChange
+ * handlers, section grouping, form persistence, imperative handle via `ref`,
+ * and full layout/component customisation.
+ *
+ * @template TSchema - A `ZodObject` schema that defines the form shape.
+ *
+ * @example
+ * const myForm = new UniForm(z.object({ name: z.string(), age: z.number() }))
+ *
+ * <AutoForm form={myForm} onSubmit={(values) => console.log(values)} />
+ */
+declare function AutoForm<TSchema extends z.$ZodObject>(props: AutoFormProps<TSchema> & {
+    ref?: React.Ref<AutoFormHandle<TSchema>>;
+}): react_jsx_runtime.JSX.Element;
+
+type FieldRendererProps = {
+    field: FieldConfig;
+    control: Control;
+    namePrefix?: string;
+    /** Zero-based render index within the parent container (form root / section / object). */
+    index?: number;
+    /** Nesting depth (0 = top-level, 1 = inside object, etc.). */
+    depth?: number;
+    /** When `true`, unregisters the field's value on unmount so it resets to its default when reshown.
+     *  Auto-set for conditional fields; propagated to object children. */
+    shouldUnregister?: boolean;
+};
+/**
+ * Renders a single form field by delegating to the appropriate field component
+ * based on `field.type`. Object and array fields manage their own layout and
+ * skip the field wrapper; all other fields are wrapped in the configured
+ * `FieldWrapper` with their resolved error message.
+ */
+declare function FieldRenderer({ field, control, namePrefix, index, depth, shouldUnregister, }: FieldRendererProps): react_jsx_runtime.JSX.Element | null;
+
+declare function DefaultInput(props: FieldProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultCheckbox(props: FieldProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultSelect(props: FieldProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultFieldWrapper({ children, field, error, span, index, depth, }: FieldWrapperProps): react_jsx_runtime.JSX.Element;
+
+type DefaultSubmitButtonProps = {
+    isSubmitting: boolean;
+};
+declare function DefaultSubmitButton({ isSubmitting, }: DefaultSubmitButtonProps): react_jsx_runtime.JSX.Element;
+
+declare const defaultRegistry: ComponentRegistry;
+
+/**
+ * Merges two {@link ComponentRegistry} objects, with `overrides` taking
+ * precedence over `base` for any keys that appear in both.
+ *
+ * Returns `base` unchanged when `overrides` is `undefined`.
+ *
+ * @param base - The default registry (typically the factory-level registry).
+ * @param overrides - Optional per-instance registry to merge on top.
+ */
+declare function mergeRegistries(base: ComponentRegistry, overrides?: ComponentRegistry): ComponentRegistry;
+
+/**
+ * Factory that creates a pre-configured `<AutoForm>` component with a fixed
+ * set of defaults baked in.
+ *
+ * All options passed to `createAutoForm` become the baseline for every form
+ * instance produced by the returned component. Any prop passed directly to the
+ * returned component is **deep-merged** on top of those defaults (instance
+ * props win on conflicts).
+ *
+ * Merged items: `components`, `layout`, `classNames`, `coercions`, `messages`.
+ * Replaced items: `fieldWrapper`, `disabled` (OR-ed with the factory default).
+ *
+ * @param config - Factory-level defaults applied to every form instance.
+ * @returns A `<AutoForm>`-compatible component with the provided defaults applied.
+ *
+ * @example
+ * const AutoForm = createAutoForm({
+ *   components: { string: MyTextInput },
+ *   classNames: { form: 'my-form' },
+ * })
+ *
+ * // Later:
+ * <AutoForm form={myUniForm} onSubmit={handleSubmit} />
+ */
+declare function createAutoForm(config: AutoFormConfig): {
+    <TSchema extends z.$ZodObject>(props: AutoFormProps<TSchema> & {
+        ref?: React.Ref<AutoFormHandle<TSchema>>;
+    }): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+type CoercionMap = Record<string, (value: unknown) => unknown>;
+/**
+ * Built-in coercion functions for the primitive field types. Each function
+ * converts the raw string value that comes from an HTML `<input>` into the
+ * type expected by the Zod schema before validation is applied.
+ *
+ * - `number` — converts to `Number`; returns `undefined` for empty/null inputs.
+ * - `date` — converts to `Date`; returns `undefined` for empty/null inputs.
+ * - `boolean` — converts to `Boolean`.
+ * - `string` — converts `null` / `undefined` to `''`, otherwise `String(value)`.
+ */
+declare const defaultCoercionMap: CoercionMap;
+/**
+ * Coerces `value` to the type expected by `type`, using `customCoercions` first
+ * and falling back to {@link defaultCoercionMap}.
+ *
+ * Returns the value unchanged when no coercion function is found for the given type.
+ *
+ * @param type - The field type string (e.g. `'number'`, `'date'`).
+ * @param value - The raw value to coerce.
+ * @param customCoercions - Optional per-instance overrides that take precedence
+ *   over the built-in coercion map.
+ */
+declare function coerceValue(type: string, value: unknown, customCoercions?: CoercionMap): unknown;
+
+/**
+ * Context passed to UniForm `setOnChange` handlers. Extends `FormMethods` with
+ * `setFieldMeta`, which lets handlers dynamically override per-field UI
+ * properties (hidden, disabled, options, label, etc.).
+ *
+ * @template TSchema - The Zod object schema that defines the form shape.
+ */
+type UniFormContext<TSchema extends z.$ZodObject = z.$ZodObject> = FormMethods<z.infer<TSchema>> & {
+    /**
+     * Dynamically override per-field UI metadata from inside a setOnChange handler.
+     * Changes are applied synchronously and trigger a re-render.
+     *
+     * Meta keys are stored and merged into the rendered field config.
+     */
+    setFieldMeta: <K extends DeepKeys<z.infer<TSchema>>>(field: K, meta: Partial<FieldDependencyResult>) => void;
+};
+type Handler<TSchema extends z.$ZodObject, TValue> = (value: TValue, ctx: UniFormContext<TSchema>) => void | Promise<void>;
+type Condition<TSchema extends z.$ZodObject> = (values: z.infer<TSchema>) => boolean;
+/**
+ * A type-safe form definition that lives outside React components.
+ * Wraps a Zod schema and lets you attach typed `setOnChange` callbacks that fire
+ * whenever a specific field's value changes.
+ *
+ * Callbacks receive the new field value (typed to the schema) and a
+ * `UniFormContext` that provides all standard form methods plus `setFieldMeta`
+ * for dynamic field overrides.
+ *
+ * @template TSchema - The Zod object schema that defines the form shape.
+ * @template TRegistered - Union of field keys that already have a `setOnChange`
+ *   handler registered. Attempting to call `setOnChange` for a key in this set
+ *   produces a compile-time error, preventing silent handler replacement.
+ *
+ * @example
+ * const addressForm = new UniForm(addressSchema)
+ *   .setOnChange('country', (value, ctx) => {
+ *     ctx.setFieldMeta('state', { hidden: value !== 'US' })
+ *   })
+ *
+ * // In component:
+ * <AutoForm form={addressForm} onSubmit={handleSubmit} />
+ */
+declare class UniForm<TSchema extends z.$ZodObject, TRegistered extends string = never> {
+    readonly schema: TSchema;
+    private readonly _handlers;
+    private readonly _conditions;
+    constructor(schema: TSchema);
+    /**
+     * Set the typed onChange handler for a specific field.
+     * Replaces any previously registered handler for that field — only one
+     * handler per field is kept. This prevents accidental handler accumulation
+     * when called inside a React render cycle.
+     * Returns `this` for fluent chaining.
+     */
+    setOnChange<K extends Exclude<DeepKeys<z.infer<TSchema>>, TRegistered>>(field: K, handler: Handler<TSchema, DeepFieldValue<z.infer<TSchema>, K>>): UniForm<TSchema, TRegistered | K>;
+    /**
+     * Attach a typed condition for a specific field.
+     * The field is shown when the predicate returns `true`, hidden when `false`.
+     * Composes with any `condition` set via the `fields` prop (UniForm takes precedence).
+     * Returns `this` for fluent chaining.
+     */
+    setCondition<K extends DeepKeys<z.infer<TSchema>>>(field: K, predicate: Condition<TSchema>): this;
+    /** @internal Called by AutoForm to fire the handler registered for a field. */
+    _fireHandler(field: string, value: unknown, ctx: UniFormContext<TSchema>): void | Promise<void>;
+    /** @internal Returns all field names that have registered onChange handlers. */
+    _getWatchedFields(): string[];
+    /** @internal Returns a copy of the conditions map for AutoForm to inject into field meta. */
+    _getConditions(): Map<string, Condition<TSchema>>;
+}
+/**
+ * Creates a new `UniForm` instance for the given Zod object schema.
+ */
+declare function createForm<TSchema extends z.$ZodObject>(schema: TSchema): UniForm<TSchema>;
+/**
+ * Creates a `UniForm` directly from a `z.discriminatedUnion` schema.
+ *
+ * `AutoForm` automatically flattens the variant fields and attaches show/hide
+ * conditions based on the discriminator value — no manual `.condition()` calls
+ * needed. The union schema is used by `zodResolver` for strict per-variant
+ * validation on submit.
+ *
+ * @example
+ * const notificationForm = createForm(
+ *   z.discriminatedUnion('channel', [
+ *     z.object({ channel: z.literal('email'), email: z.string().email() }),
+ *     z.object({ channel: z.literal('sms'), phone: z.string() }),
+ *   ])
+ * )
+ */
+declare function createForm(schema: z.$ZodDiscriminatedUnion): UniForm<z.$ZodObject>;
+
+/**
+ * Filters and sorts a list of field configs based on the current form values.
+ *
+ * - Fields with `meta.hidden === true` are always excluded.
+ * - Fields with a `meta.condition` function are included only when the
+ *   function returns `true` for the current values.
+ * - Remaining fields are sorted ascending by `meta.order` (fields without an
+ *   order appear last).
+ *
+ * Re-evaluates reactively whenever the watched form values change.
+ *
+ * @param fields - The full list of field configs to filter and sort.
+ * @param control - The RHF `control` object from the parent form.
+ * @returns The filtered and ordered subset of `fields`.
+ */
+declare function useConditionalFields(fields: FieldConfig[], control: Control): FieldConfig[];
+
+type SectionGroup = {
+    title: string | null;
+    fields: FieldConfig[];
+};
+/**
+ * Groups a flat list of field configs into ordered section groups based on
+ * each field's `meta.section` value.
+ *
+ * - Fields without a `meta.section` (or with a non-string value) are placed
+ *   in an "ungrouped" section with `title: null`, rendered first.
+ * - Named sections appear in the order their first member is encountered.
+ * - The returned array is memoized and only recomputed when `fields` changes.
+ *
+ * @param fields - The ordered list of (already filtered/sorted) field configs.
+ * @returns An array of {@link SectionGroup} objects ready to be rendered.
+ */
+declare function useSectionGrouping(fields: FieldConfig[]): SectionGroup[];
+
+/**
+ * Persists form values to a storage adapter and restores them on mount.
+ *
+ * - On mount, reads `key` from `storage` and calls `reset` with the merged
+ *   stored + default values, so the form starts with any previously saved data.
+ * - On every value change, writes the current form values to `storage` after a
+ *   `debounceMs` delay to avoid thrashing the storage layer.
+ * - When `key` is `undefined`, persistence is entirely disabled.
+ * - Falls back to `sessionStorage` when no custom `storage` adapter is provided.
+ *
+ * @returns An object with `clearPersistedData` — call this after a successful
+ *   submission to remove the persisted draft.
+ */
+declare function useFormPersistence(options: {
+    control: Control;
+    key: string | undefined;
+    debounceMs: number;
+    storage?: PersistStorage;
+    reset: (values: Record<string, unknown>) => void;
+    defaultValues: Record<string, unknown>;
+}): {
+    clearPersistedData: () => void;
+};
+
+type AutoFormContextValue = {
+    registry: ComponentRegistry;
+    fieldOverrides: Record<string, unknown>;
+    fieldWrapper: React.ComponentType<FieldWrapperProps>;
+    layout: ResolvedLayoutSlots;
+    classNames: FormClassNames;
+    disabled: boolean;
+    coercions?: CoercionMap$1;
+    messages?: ValidationMessages;
+    labels: FormLabels;
+    formMethods: FormMethods;
+};
+declare function useAutoFormContext(): AutoFormContextValue;
+
+export { type ArrayRowLayoutProps, AutoForm, type AutoFormConfig, type AutoFormContextValue, type AutoFormHandle, type AutoFormProps, type CoercionMap$1 as CoercionMap, type ComponentRegistry, DefaultCheckbox, DefaultFieldWrapper, DefaultInput, DefaultSelect, DefaultSubmitButton, type FieldCondition, type FieldConfig, type FieldDependencyResult, type FieldMeta, type FieldMetaBase, type FieldOverride, type FieldProps, FieldRenderer, type FieldType, type FieldWrapperProps, type FormClassNames, type FormLabels, type FormMethods, type LayoutSlots, type PersistStorage, type ResolvedLayoutSlots, type SectionGroup, type SelectOption, UniForm, type UniFormContext, type ValidationMessages, coerceValue, createAutoForm, createForm, defaultCoercionMap, defaultRegistry, introspectObjectSchema, introspectSchema, mergeRegistries, useAutoFormContext, useConditionalFields, useFormPersistence, useSectionGrouping };