import type { FormField, OptimizationConfig } from '@zod-to-form/core';
import { z } from 'zod';
import type { $ZodType } from 'zod/v4/core';
import type { input, output, ZodObject } from 'zod';
import type { FieldConfig, FormProcessor, ZodFormRegistry } from '@zod-to-form/core';
type UseZodFormOptions<TSchema extends ZodObject> = {
    defaultValues?: Partial<output<TSchema>>;
    /** Controlled external data — RHF re-renders on change. See react-hook-form `values` option. */
    values?: output<TSchema>;
    /** Pre-populated registry — when provided, `fields` is ignored entirely. */
    formRegistry?: ZodFormRegistry;
    /** Flat field config (from defineConfig / componentConfig). Auto-registers into a registry. */
    fields?: Record<string, FieldConfig>;
    processors?: Record<string, FormProcessor>;
    mode?: 'onSubmit' | 'onChange' | 'onBlur';
    /**
     * Controls when a field's validation error is surfaced to its field
     * template. `'always'` (default) shows the error as soon as
     * `formState.errors` has one, matching every prior release. `'afterTouched'`
     * suppresses the error until the field has been touched (blurred) or
     * dirtied (changed) — validation itself is unaffected: `formState.errors`,
     * `isValid`, and `onValueChange` metadata keep reporting the true state
     * regardless of this option, only the per-field displayed message is gated.
     */
    errorDisplay?: 'always' | 'afterTouched';
    /**
     * Fires on every field mutation (and on programmatic `form.reset()`).
     *
     * The first arg is the form's current data — it's `output<TSchema>` when
     * `meta.isValid` is true (schema parsed cleanly, coerced values applied)
     * or `input<TSchema>` when false (normalized raw values — strings from
     * `<input type=number>`, empty-string enums, partial entries mid-edit).
     * The union is honest about what you actually get: gate on `meta.isValid`
     * before treating a field as its coerced type.
     */
    onValueChange?: (values: output<TSchema> | input<TSchema>, meta: {
        isValid: boolean;
    }) => void;
    /** Validation optimization config. When set, skips zodResolver and uses per-field validation. */
    optimization?: OptimizationConfig;
};
/**
 * React Hook Form integration hook for Zod v4 schemas.
 *
 * Walks the schema to produce `FormField[]` and wires `useForm` with a
 * `zodResolver`. When `options.optimization` is set the `zodResolver` is
 * replaced by per-field validation (via `schemaLite`) and the resolver
 * import is tree-shaken in production builds.
 *
 * @param schema - The `z.object({...})` schema to generate the form from.
 * @param options - Optional hook configuration.
 * @returns `{ form, fields }` — the RHF `UseFormReturn` and the `FormField[]` array.
 *
 * @example
 * ```tsx
 * const { form, fields } = useZodForm(loginSchema);
 * return (
 *   <form onSubmit={form.handleSubmit(onSubmit)}>
 *     {fields.map((f) => <input key={f.key} {...form.register(f.key)} />)}
 *   </form>
 * );
 * ```
 *
 * @useWhen
 * - You need direct access to the RHF `form` instance (e.g. to call `form.setValue`)
 * - You are building a custom renderer on top of `FormField[]`
 * - You want to colocate form state management with your own layout logic
 *
 * @avoidWhen
 * - You just need a working form UI — use `<ZodForm>` instead; `useZodForm` returns `fields[]` and `form`, but rendering those fields requires wiring up each field component yourself
 *
 * @never
 * - NEVER pass a new schema object on every render — `walkSchema` is memoized by schema
 *   identity; an unstable reference causes re-walking on every render cycle; FIX: declare
 *   the schema outside the component or wrap in `useMemo`
 * - NEVER forget `normalizeFormValues()` before manually calling `schema.safeParse()` —
 *   the hook's internal resolver applies normalization, but manual calls do not; FIX:
 *   always call `schema.safeParse(normalizeFormValues(values))`
 * - NEVER mix `formRegistry` and `fields` options on the same call — when `formRegistry`
 *   is provided, `fields` is ignored entirely with no merge and no warning; FIX: pick one
 *   or merge field config into the registry manually before passing it
 *
 * @category Hooks
 */
export declare function useZodForm<TSchema extends ZodObject>(schema: TSchema, options?: UseZodFormOptions<TSchema>): {
    form: import("react-hook-form").UseFormReturn<output<TSchema>, any, output<TSchema>>;
    fields: FormField[];
    /** Non-null when walkSchema threw — lets consumers display the error instead of an empty form */
    schemaError: string | null;
    /** SchemaLite for submit-time validation (non-null when optimization is enabled and top-level effects exist) */
    schemaLite: $ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> | null;
};
export {};
//# sourceMappingURL=useZodForm.d.ts.map