@uniform-ts/core 0.0.4 → 0.0.5

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import * as React from 'react';
+import * as React$1 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';
@@ -36,12 +36,7 @@ type DeepKeys<T> = T extends object ? {
  * // 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.
  */
@@ -51,18 +46,305 @@ type SelectOption = {
     /** 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.
+ * 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 FieldCondition<TValues = Record<string, unknown>> = (values: TValues) => boolean;
+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. */
+        remove: React$1.ReactNode;
+        /** 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;
+}
+/**
+ * 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. */
+    base?: React$1.ComponentType<ArrayButtonProps>;
+    /** Override for the add-row button only. */
+    add?: React$1.ComponentType<ArrayButtonProps>;
+    /** Override for the remove-row button only. */
+    remove?: React$1.ComponentType<ArrayButtonProps>;
+    /** Override for the move-up button only. */
+    moveUp?: React$1.ComponentType<ArrayButtonProps>;
+    /** Override for the move-down button only. */
+    moveDown?: React$1.ComponentType<ArrayButtonProps>;
+    /** Override for the duplicate-row button only. */
+    duplicate?: React$1.ComponentType<ArrayButtonProps>;
+    /**
+     * Override for the collapse/expand toggle button only.
+     * Receives `isCollapsed` in addition to standard `ArrayButtonProps`.
+     */
+    collapse?: React$1.ComponentType<ArrayCollapseButtonProps>;
+};
+/**
+ * Resolved button slots where every entry is guaranteed to be defined.
+ */
+type ResolvedArrayButtonSlots = {
+    base: React$1.ComponentType<ArrayButtonProps>;
+    add: React$1.ComponentType<ArrayButtonProps>;
+    remove: React$1.ComponentType<ArrayButtonProps>;
+    moveUp: React$1.ComponentType<ArrayButtonProps>;
+    moveDown: React$1.ComponentType<ArrayButtonProps>;
+    duplicate: React$1.ComponentType<ArrayButtonProps>;
+    collapse: React$1.ComponentType<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. */
+    submitButton?: React$1.ComponentType<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: React$1.ComponentType<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 TSchema - The Zod object schema that defines the form shape.
+ * @template TValues - The inferred shape of the form values.
  */
 type FormMethods<TValues extends FieldValues = FieldValues> = {
     /** Set a single field value programmatically */
@@ -85,12 +367,148 @@ type FormMethods<TValues extends FieldValues = FieldValues> = {
     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 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;
+};
+/**
+ * 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>>;
+/**
+ * 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 - 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$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;
+};
+
+/**
+ * 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
@@ -147,11 +565,14 @@ type FieldMetaBase = {
      * - **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>`.
+     * 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.ComponentType<any>;
+    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. */
@@ -160,6 +581,14 @@ type FieldMetaBase = {
     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
@@ -188,17 +617,6 @@ type FieldConfigBase = {
      * 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.
-     *
-     * @example
-     * function MyUnionInput({ field }: FieldProps) {
-     *   // Inspect the original schema for any edge case
-     *   const schema = field.schema
-     *   if (schema._zod.def.type === 'union') {
-     *     const variants = (schema._zod.def as z.$ZodUnionDef).options
-     *     // render a type-switcher using the raw Zod variants
-     *   }
-     *   return <input ... />
-     * }
      */
     schema: z.$ZodType;
 };
@@ -249,7 +667,7 @@ type FieldConfig = FieldConfigBase & ({
  * value, change/blur handlers, and all resolved UI metadata needed to render
  * a single field.
  */
-type FieldProps = {
+interface FieldProps {
     /** Dot-notated field path (e.g. `"address.street"`). */
     name: string;
     /** The current field value. */
@@ -282,166 +700,7 @@ type FieldProps = {
      * exposes — e.g. inspecting union variants, accessing custom Zod refinements, etc.
      */
     schema: z.$ZodType;
-};
-/**
- * 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;
-};
-/**
- * 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.ComponentType<{
-        children: React.ReactNode;
-        title: string;
-        className?: string;
-    }>;
-};
-/**
- * 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;
-        className?: 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;
-    /**
-     * 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.ComponentType<{
-        children: React.ReactNode;
-    }>;
-    sectionWrapper: React.ComponentType<{
-        children: React.ReactNode;
-        title: string;
-        className?: 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
@@ -454,131 +713,6 @@ type FieldOverride<TSchema extends z.$ZodObject = z.$ZodObject, TValue = unknown
     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' {
@@ -633,7 +767,7 @@ declare function introspectObjectSchema(schema: z.$ZodObject): FieldConfig[];
  * <AutoForm form={myForm} onSubmit={(values) => console.log(values)} />
  */
 declare function AutoForm<TSchema extends z.$ZodObject>(props: AutoFormProps<TSchema> & {
-    ref?: React.Ref<AutoFormHandle<TSchema>>;
+    ref?: React$1.Ref<AutoFormHandle<TSchema>>;
 }): react_jsx_runtime.JSX.Element;
 
 type FieldRendererProps = {
@@ -669,6 +803,18 @@ type DefaultSubmitButtonProps = {
 };
 declare function DefaultSubmitButton({ isSubmitting, }: DefaultSubmitButtonProps): react_jsx_runtime.JSX.Element;
 
+declare function DefaultArrayButton(props: ArrayButtonProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultArrayCollapseButton({ isCollapsed: _isCollapsed, ...props }: ArrayCollapseButtonProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultArrayFieldLayout({ rows, addButton, }: ArrayFieldLayoutProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultArrayRowLayout({ children, buttons, }: ArrayRowLayoutProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultObjectWrapper({ children, label, className, labelClassName, }: ObjectWrapperProps): react_jsx_runtime.JSX.Element;
+
+declare function DefaultArrayWrapper({ children, label, className, labelClassName, }: ArrayWrapperProps): react_jsx_runtime.JSX.Element;
+
 declare const defaultRegistry: ComponentRegistry;
 
 /**
@@ -708,7 +854,7 @@ declare function mergeRegistries(base: ComponentRegistry, overrides?: ComponentR
  */
 declare function createAutoForm(config: AutoFormConfig): {
     <TSchema extends z.$ZodObject>(props: AutoFormProps<TSchema> & {
-        ref?: React.Ref<AutoFormHandle<TSchema>>;
+        ref?: React$1.Ref<AutoFormHandle<TSchema>>;
     }): react_jsx_runtime.JSX.Element;
     displayName: string;
 };
@@ -890,7 +1036,7 @@ declare function useFormPersistence(options: {
 type AutoFormContextValue = {
     registry: ComponentRegistry;
     fieldOverrides: Record<string, unknown>;
-    fieldWrapper: React.ComponentType<FieldWrapperProps>;
+    fieldWrapper: React$1.ComponentType<FieldWrapperProps>;
     layout: ResolvedLayoutSlots;
     classNames: FormClassNames;
     disabled: boolean;
@@ -901,4 +1047,4 @@ type AutoFormContextValue = {
 };
 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 };
+export { type ArrayButtonProps, type ArrayButtonSlots, type ArrayCollapseButtonProps, type ArrayFieldLayoutProps, type ArrayRowLayoutProps, type ArrayWrapperProps, AutoForm, type AutoFormConfig, type AutoFormContextValue, type AutoFormHandle, type AutoFormProps, type CoercionMap$1 as CoercionMap, type ComponentRegistry, DefaultArrayButton, DefaultArrayCollapseButton, DefaultArrayFieldLayout, DefaultArrayRowLayout, DefaultArrayWrapper, DefaultCheckbox, DefaultFieldWrapper, DefaultInput, DefaultObjectWrapper, 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 FormWrapperProps, type LayoutSlots, type ObjectWrapperProps, type PersistStorage, type ResolvedArrayButtonSlots, type ResolvedLayoutSlots, type SectionConfig, type SectionGroup, type SectionWrapperProps, type SelectOption, type SubmitButtonProps, UniForm, type UniFormContext, type ValidationMessages, coerceValue, createAutoForm, createForm, defaultCoercionMap, defaultRegistry, introspectObjectSchema, introspectSchema, mergeRegistries, useAutoFormContext, useConditionalFields, useFormPersistence, useSectionGrouping };