@uniform-ts/core 0.0.6 → 0.0.8

package/dist/field-KKjnXn-d.d.mts

@@ -0,0 +1,748 @@
+import * as React$1 from 'react';
+import { FieldValues, FieldPath, FieldPathValue, RefCallBack } from 'react-hook-form';
+import * as z from 'zod/v4/core';
+
+/**
+ * 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;
+/**
+ * Resolves the values type that a `setCondition` predicate receives for a
+ * given field key `K` within form values type `TValues`.
+ *
+ * - **Array item fields** (e.g. `"tasks.note"`): the predicate receives the
+ *   array item type (`{ title, priority, note }`), enabling row-local sibling
+ *   conditions like `(row) => row.priority === 'high'`.
+ * - **All other fields**: the predicate receives the full form values type.
+ *
+ * @example
+ * // ConditionValues<{ name: string; tasks: { priority: string; note: string }[] }, 'tasks.note'>
+ * // → { priority: string; note: string }
+ *
+ * // ConditionValues<{ name: string; address: { street: string } }, 'address.street'>
+ * // → { name: string; address: { street: string } }   (full form — not an array)
+ */
+type ConditionValues<TValues, K extends string> = K extends `${infer Head}.${string}` ? Head extends keyof TValues ? TValues[Head] extends readonly (infer Item)[] ? Item : TValues : TValues : TValues;
+
+/**
+ * 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 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$1.ComponentType<FieldProps>;
+    number?: React$1.ComponentType<FieldProps>;
+    boolean?: React$1.ComponentType<FieldProps>;
+    date?: React$1.ComponentType<FieldProps>;
+    select?: React$1.ComponentType<FieldProps>;
+    textarea?: React$1.ComponentType<FieldProps>;
+    [key: string]: React$1.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.
+ */
+interface FieldWrapperProps {
+    /** The field input component to wrap. */
+    children: React$1.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 for a generic array action button. Compatible with standard design
+ * system button components — pass your own via the `arrayButton` layout slot
+ * and it will be used for all array buttons (add, remove, move, duplicate).
+ */
+interface ArrayButtonProps {
+    onClick?: React$1.MouseEventHandler<HTMLButtonElement>;
+    disabled?: boolean;
+    /** Always `"button"` — prevents accidental form submission. */
+    type?: 'button' | 'submit' | 'reset';
+    /** Accessible label describing the specific action and target row. */
+    'aria-label'?: string;
+    /** CSS class name forwarded from `classNames.arrayAdd` / `arrayRemove` / etc. */
+    className?: string;
+    children?: React$1.ReactNode;
+}
+/**
+ * Props for the collapse/expand toggle button on an array row.
+ * Extends `ArrayButtonProps` with collapse state so custom components
+ * can apply directional styling (e.g. rotating a chevron icon).
+ */
+interface ArrayCollapseButtonProps extends ArrayButtonProps {
+    /** Whether the row is currently collapsed. */
+    isCollapsed: boolean;
+}
+/**
+ * Props for the component that wraps the entire array field body,
+ * controlling the relative position of the rows and the add button.
+ */
+interface ArrayFieldLayoutProps {
+    /** The rendered list of array rows. */
+    rows: React$1.ReactNode;
+    /** The rendered "add row" button. */
+    addButton: React$1.ReactNode;
+    /** Total number of rows currently in the array. */
+    rowCount: number;
+    /** Whether adding another row is permitted (respects `maxItems`). */
+    canAdd: boolean;
+}
+/**
+ * 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).
+ */
+interface ArrayRowLayoutProps {
+    /** The rendered fields for this array item. */
+    children: React$1.ReactNode;
+    /** Action button nodes for the row. */
+    buttons: {
+        /** Button to move the row up, or `null` if already first. */
+        moveUp: React$1.ReactNode | null;
+        /** Button to move the row down, or `null` if already last. */
+        moveDown: React$1.ReactNode | null;
+        /** Button to duplicate the row, or `null` if at max items. */
+        duplicate: React$1.ReactNode | null;
+        /** Button to remove the row, or `null` when omitted via layout slot. */
+        remove: React$1.ReactNode | null;
+        /** Button to collapse/expand the row, or `null` if collapsing is disabled. */
+        collapse: React$1.ReactNode | null;
+    };
+    /** Zero-based index of this row within the array. */
+    index: number;
+    /** Total number of rows currently in the array. */
+    rowCount: number;
+}
+/** Props received by the `layout.formWrapper` component. */
+interface FormWrapperProps {
+    children: React$1.ReactNode;
+}
+/** Props received by the `layout.sectionWrapper` component (and per-section `SectionConfig.component`). */
+interface SectionWrapperProps {
+    children: React$1.ReactNode;
+    title: string;
+    className?: string;
+}
+/**
+ * Props received by the `layout.objectWrapper` component.
+ * Replaces the default `<fieldset>` / `<legend>` wrapper rendered around
+ * nested object fields.
+ */
+interface ObjectWrapperProps {
+    /** The rendered child fields. */
+    children: React$1.ReactNode;
+    /** The field label (used as the legend / heading). May be undefined. */
+    label: string | undefined;
+    /** CSS class name forwarded from `classNames.objectFieldset`. */
+    className?: string;
+    /** CSS class name forwarded from `classNames.objectLegend` for the label element. */
+    labelClassName?: string;
+}
+/**
+ * Props received by the `layout.arrayWrapper` component.
+ * Replaces the default `<fieldset>` / `<legend>` wrapper rendered around
+ * array fields.
+ */
+interface ArrayWrapperProps {
+    /** The rendered array field body (rows + add button). */
+    children: React$1.ReactNode;
+    /** The field label (used as the legend / heading). May be undefined. */
+    label: string | undefined;
+    /** CSS class name forwarded from `classNames.arrayFieldset`. */
+    className?: string;
+    /** CSS class name forwarded from `classNames.arrayLegend` for the label element. */
+    labelClassName?: string;
+}
+/** Props received by the `layout.submitButton` component. */
+interface SubmitButtonProps {
+    isSubmitting: boolean;
+    label: string;
+}
+type OptionalSlotComponent<TProps> = React$1.ComponentType<TProps> | null;
+/**
+ * Per-section styling overrides forwarded to the `sectionWrapper` component.
+ * Keys are section titles; values control how that section wrapper is styled.
+ */
+type SectionConfig = {
+    /** CSS class name(s) applied to the section wrapper. */
+    className?: string;
+    /** Replaces the section wrapper component entirely for this section. */
+    component?: React$1.ComponentType<SectionWrapperProps>;
+};
+/**
+ * Button component overrides for array fields. Set `base` to swap in your
+ * design system's button everywhere; use the specific keys to override
+ * individual actions on top of that. All keys fall back to `base`, which
+ * itself falls back to a plain `<button>`.
+ */
+type ArrayButtonSlots = {
+    /** Used for every array button that has no specific override. Set to `null` to omit all unspecified buttons. */
+    base?: OptionalSlotComponent<ArrayButtonProps>;
+    /** Override for the add-row button only. Set to `null` to omit. */
+    add?: OptionalSlotComponent<ArrayButtonProps>;
+    /** Override for the remove-row button only. Set to `null` to omit. */
+    remove?: OptionalSlotComponent<ArrayButtonProps>;
+    /** Override for the move-up button only. Set to `null` to omit. */
+    moveUp?: OptionalSlotComponent<ArrayButtonProps>;
+    /** Override for the move-down button only. Set to `null` to omit. */
+    moveDown?: OptionalSlotComponent<ArrayButtonProps>;
+    /** Override for the duplicate-row button only. Set to `null` to omit. */
+    duplicate?: OptionalSlotComponent<ArrayButtonProps>;
+    /**
+     * Override for the collapse/expand toggle button only.
+     * Receives `isCollapsed` in addition to standard `ArrayButtonProps`.
+     */
+    collapse?: OptionalSlotComponent<ArrayCollapseButtonProps>;
+};
+/**
+ * Resolved button slots where every entry is guaranteed to be defined.
+ */
+type ResolvedArrayButtonSlots = {
+    base: OptionalSlotComponent<ArrayButtonProps>;
+    add: OptionalSlotComponent<ArrayButtonProps>;
+    remove: OptionalSlotComponent<ArrayButtonProps>;
+    moveUp: OptionalSlotComponent<ArrayButtonProps>;
+    moveDown: OptionalSlotComponent<ArrayButtonProps>;
+    duplicate: OptionalSlotComponent<ArrayButtonProps>;
+    collapse: OptionalSlotComponent<ArrayCollapseButtonProps>;
+};
+/**
+ * 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$1.ComponentType<FormWrapperProps>;
+    /** Wrapper rendered around each named field section. */
+    sectionWrapper?: React$1.ComponentType<SectionWrapperProps>;
+    /** Custom submit button component. Set to `null` to omit rendering it. */
+    submitButton?: OptionalSlotComponent<SubmitButtonProps>;
+    /** Custom layout component for individual rows in array fields. */
+    arrayRowLayout?: React$1.ComponentType<ArrayRowLayoutProps>;
+    /**
+     * Controls the layout of the entire array field body — position the rows
+     * and add button relative to each other (e.g. add button above rows).
+     */
+    arrayFieldLayout?: React$1.ComponentType<ArrayFieldLayoutProps>;
+    /**
+     * Replaces the `<fieldset>` / `<legend>` wrapper rendered around nested
+     * object fields. Receives `label`, `className`, and `labelClassName` props.
+     */
+    objectWrapper?: React$1.ComponentType<ObjectWrapperProps>;
+    /**
+     * Replaces the `<fieldset>` / `<legend>` wrapper rendered around array
+     * fields. Receives `label`, `className`, and `labelClassName` props.
+     */
+    arrayWrapper?: React$1.ComponentType<ArrayWrapperProps>;
+    /**
+     * Button component overrides for array fields. Set `base` to use your
+     * design system's button everywhere; use specific keys to override
+     * individual actions.
+     */
+    arrayButtons?: ArrayButtonSlots;
+    /**
+     * Content rendered while async `defaultValues` are loading.
+     * Defaults to a simple `<p>Loading…</p>` when not provided.
+     */
+    loadingFallback?: React$1.ReactNode;
+    /**
+     * Per-section config keyed by section title.
+     * Forwarded to the `sectionWrapper` component as a `className` prop.
+     */
+    sections?: Record<string, SectionConfig>;
+};
+/**
+ * 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$1.ComponentType<FormWrapperProps>;
+    sectionWrapper: React$1.ComponentType<SectionWrapperProps>;
+    submitButton: OptionalSlotComponent<SubmitButtonProps>;
+    arrayRowLayout: React$1.ComponentType<ArrayRowLayoutProps>;
+    arrayFieldLayout: React$1.ComponentType<ArrayFieldLayoutProps>;
+    objectWrapper: React$1.ComponentType<ObjectWrapperProps>;
+    arrayWrapper: React$1.ComponentType<ArrayWrapperProps>;
+    arrayButtons: ResolvedArrayButtonSlots;
+    loadingFallback: React$1.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;
+    /** Class applied to the `<fieldset>` wrapper around nested object fields. */
+    objectFieldset?: string;
+    /** Class applied to the `<legend>` label inside nested object fields. */
+    objectLegend?: string;
+    /** Class applied to the `<fieldset>` wrapper around array fields. */
+    arrayFieldset?: string;
+    /** Class applied to the `<legend>` label inside array fields. */
+    arrayLegend?: string;
+};
+
+/**
+ * All programmatic form control methods, shared by both the field `onChange`
+ * callback and the imperative ref handle.
+ *
+ * @template TValues - The inferred shape of the form values.
+ */
+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;
+    /** Watch field values reactively */
+    watch: {
+        (): TValues;
+        <K extends FieldPath<TValues>>(name: K): FieldPathValue<TValues, K>;
+    };
+};
+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;
+    /** Collapsed row summary fallback — default: (i) => `Item ${i + 1}` */
+    arrayItemSummary?: (index: number) => string;
+    /** Aria label for the expand toggle — default: (i) => `Expand item ${i + 1}` */
+    arrayAriaExpand?: (index: number) => string;
+    /** Aria label for the collapse toggle — default: (i) => `Collapse item ${i + 1}` */
+    arrayAriaCollapse?: (index: number) => string;
+    /** Aria label for the move-up button — default: (i) => `Move item ${i + 1} up` */
+    arrayAriaMoveUp?: (index: number) => string;
+    /** Aria label for the move-down button — default: (i) => `Move item ${i + 1} down` */
+    arrayAriaMoveDown?: (index: number) => string;
+    /** Aria label for the duplicate button — default: (i) => `Duplicate item ${i + 1}` */
+    arrayAriaDuplicate?: (index: number) => string;
+    /** Aria label for the remove button — default: (i) => `Remove item ${i + 1}` */
+    arrayAriaRemove?: (index: number) => 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 = 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>>;
+/**
+ * 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;
+    /** 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 - A `ZodObject` 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;
+    /** 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;
+};
+
+/**
+ * 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 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;
+/**
+ * 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`).
+     *
+     * Uses `React.ComponentType<never>` as the type parameter rather than
+     * `React.ComponentType<FieldProps>` to avoid both a circular inference error
+     * (FieldProps → FieldMeta → component → FieldProps) and a contravariance
+     * error when components typed as `(props: FieldProps) => JSX.Element` are
+     * assigned via Zod's `.meta()`, whose return type widens `meta` to `any`.
+     * `ComponentType<never>` is the widest possible assignable supertype.
+     */
+    component?: string | React$1.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;
+    /**
+     * Override the wrapper component rendered around this specific object or array field.
+     * Takes precedence over the global `layout.objectWrapper` / `layout.arrayWrapper` slots.
+     *
+     * The component receives the same `ObjectWrapperProps` / `ArrayWrapperProps` as the
+     * global slot — `children`, `label`, `className`, and `labelClassName`.
+     */
+    wrapper?: React$1.ComponentType<ObjectWrapperProps | ArrayWrapperProps>;
+};
+/**
+ * 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 original Zod schema for this field, after transparent wrappers
+     * (`optional`, `nullable`, `default`, `pipe`) have been stripped.
+     *
+     * This is a general escape hatch for custom components that need to inspect
+     * the raw schema — for example, to read union variants, access custom Zod
+     * metadata not captured by introspection, or build schema-aware validation UI.
+     */
+    schema: z.$ZodType;
+};
+/**
+ * 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.
+ */
+interface FieldProps<Value = unknown> {
+    /** Dot-notated field path (e.g. `"address.street"`). */
+    name: string;
+    /** The current field value. */
+    value: Value;
+    /** Callback to update the field value. */
+    onChange: (value: Value) => 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;
+    /**
+     * The original Zod schema for this field (after transparent wrappers are stripped).
+     * Use this as an escape hatch when you need capabilities beyond what `FieldConfig`
+     * exposes — e.g. inspecting union variants, accessing custom Zod refinements, etc.
+     */
+    schema: z.$ZodType;
+}
+/**
+ * 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;
+};
+
+export type { AutoFormProps as A, SubmitButtonProps as B, ComponentRegistry as C, DeepKeys as D, FieldMetaBase as F, LayoutSlots as L, ObjectWrapperProps as O, PersistStorage as P, ResolvedLayoutSlots as R, SectionConfig as S, ValidationMessages as V, FieldConfig as a, AutoFormHandle as b, FieldProps as c, FieldWrapperProps as d, ArrayButtonProps as e, ArrayCollapseButtonProps as f, ArrayFieldLayoutProps as g, ArrayRowLayoutProps as h, ArrayWrapperProps as i, AutoFormConfig as j, FormMethods as k, FieldDependencyResult as l, DeepFieldValue as m, ConditionValues as n, FormClassNames as o, CoercionMap as p, FormLabels as q, ArrayButtonSlots as r, FieldCondition as s, FieldMeta as t, FieldOverride as u, FieldType as v, FormWrapperProps as w, ResolvedArrayButtonSlots as x, SectionWrapperProps as y, SelectOption as z };