@rachelallyson/hero-hook-form 2.6.0 → 2.7.2

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import React$1, { ComponentProps } from 'react';
 import { Button } from '@heroui/react';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, Path, RegisterOptions, Control, UseFormReturn, FieldErrors, UseFormProps, SubmitHandler, UseFormSetError } from 'react-hook-form';
+import { FieldValues, Path, RegisterOptions, ArrayPath, Control, UseFormReturn, FieldErrors, UseFormProps, SubmitHandler, DefaultValues, UseFormSetError, FieldArrayWithId } from 'react-hook-form';
 export { UseFormReturn, useFormContext } from 'react-hook-form';
 import * as zod from 'zod';
-import { z } from 'zod';
+import { z, ZodSchema } from 'zod';
 import * as _internationalized_date from '@internationalized/date';
 import { CalendarDate } from '@internationalized/date';
 import { Autocomplete } from '@heroui/autocomplete';
@@ -17,6 +17,19 @@ import { Slider } from '@heroui/slider';
 import { Switch } from '@heroui/switch';
 import { Button as Button$1 } from '@heroui/button';
 
+/**
+ * All supported field types that can be used in form builders
+ * This type is used throughout the codebase to ensure consistency
+ */
+type FormFieldType = "input" | "textarea" | "select" | "autocomplete" | "checkbox" | "switch" | "radio" | "slider" | "date" | "file" | "fontPicker" | "stringArray";
+/**
+ * Helper to convert a Path<T>, ArrayPath<T>, or string to a string for use in React keys and DOM operations.
+ * Path<T> and ArrayPath<T> are branded string types, so this is safe - it's just removing the brand.
+ *
+ * @param path - The path to convert (can be Path<T>, ArrayPath<T>, string, or undefined)
+ * @returns The path as a plain string, or empty string if undefined
+ */
+declare function pathToString<T extends FieldValues>(path: Path<T> | ArrayPath<T> | string | undefined): string;
 interface FieldBaseProps<TFieldValues extends FieldValues, TValue> {
     name: Path<TFieldValues>;
     label?: string;
@@ -30,7 +43,7 @@ interface FieldBaseProps<TFieldValues extends FieldValues, TValue> {
     isDisabled?: boolean;
 }
 interface WithControl<TFieldValues extends FieldValues> {
-    control: Control<TFieldValues>;
+    control: Control<TFieldValues, any>;
 }
 interface BaseFormFieldConfig<TFieldValues extends FieldValues> {
     name: Path<TFieldValues>;
@@ -73,6 +86,16 @@ interface RadioFieldConfig<TFieldValues extends FieldValues> extends BaseFormFie
         value: string | number;
     }[];
 }
+interface CheckboxGroupFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
+    type: "checkboxGroup";
+    defaultValue?: (string | number)[];
+    checkboxGroupOptions?: {
+        label: string;
+        value: string | number;
+    }[];
+    checkboxProps?: Omit<React.ComponentProps<typeof Checkbox>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled" | "name">;
+    orientation?: "vertical" | "horizontal";
+}
 interface SliderFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "slider";
     defaultValue?: number;
@@ -100,10 +123,35 @@ interface FontPickerFieldConfig<TFieldValues extends FieldValues> extends BaseFo
         fontsLoadedTimeout?: number;
     };
 }
-interface CustomFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
+interface StringArrayFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
+    type: "stringArray";
+    defaultValue?: string[];
+    stringArrayProps?: {
+        /** Placeholder text for the input */
+        placeholder?: string;
+        /** Maximum number of items allowed */
+        maxItems?: number;
+        /** Minimum number of items required */
+        minItems?: number;
+        /** Allow duplicate values */
+        allowDuplicates?: boolean;
+        /** Custom validation function for each item */
+        validateItem?: (item: string) => string | true;
+        /** Transform item before adding (e.g., trim whitespace) */
+        transformItem?: (item: string) => string;
+        /** Custom chip render function */
+        renderChip?: (item: string, onRemove: () => void) => React.ReactNode;
+        /** Custom add button text */
+        addButtonText?: string;
+        /** Whether to show add button or use enter key */
+        showAddButton?: boolean;
+    };
+}
+interface CustomFieldConfig<TFieldValues extends FieldValues> extends Omit<BaseFormFieldConfig<TFieldValues>, "name"> {
     type: "custom";
+    name: Path<TFieldValues> | ArrayPath<TFieldValues>;
     render: (field: {
-        name: Path<TFieldValues>;
+        name: Path<TFieldValues> | ArrayPath<TFieldValues>;
         control: Control<TFieldValues>;
         form: UseFormReturn<TFieldValues>;
         errors: FieldErrors<TFieldValues>;
@@ -115,13 +163,76 @@ interface ConditionalFieldConfig<TFieldValues extends FieldValues> extends BaseF
     condition: (formData: Partial<TFieldValues>) => boolean;
     field: ZodFormFieldConfig<TFieldValues>;
 }
-interface FieldArrayConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
+/**
+ * Field array config for dynamic repeating field groups.
+ *
+ * @description
+ * Configuration for field arrays that support reordering, custom rendering,
+ * default values, and conditional fields within array items.
+ *
+ * @template TFieldValues - The form data type
+ */
+interface FieldArrayConfig<TFieldValues extends FieldValues> extends Omit<BaseFormFieldConfig<TFieldValues>, "name"> {
     type: "fieldArray";
+    /** Field array name - must be an ArrayPath (points to an array field) */
+    name: ArrayPath<TFieldValues>;
+    /** Field configurations for each array item */
     fields: ZodFormFieldConfig<TFieldValues>[];
+    /** Minimum number of items (default: 0) */
     min?: number;
+    /** Maximum number of items (default: 10) */
     max?: number;
+    /** Add button text (default: "Add Item") */
     addButtonText?: string;
+    /** Remove button text (default: "Remove") */
     removeButtonText?: string;
+    /** Enable reordering of array items with up/down buttons (default: false) */
+    enableReordering?: boolean;
+    /** Custom text for reorder buttons */
+    reorderButtonText?: {
+        /** Text for move up button (default: "↑") */
+        up?: string;
+        /** Text for move down button (default: "↓") */
+        down?: string;
+    };
+    /** Function to create default item when adding new array item */
+    defaultItem?: () => any;
+    /** Custom render function for array items */
+    renderItem?: (props: {
+        /** Item index (0-based) */
+        index: number;
+        /** Field array item with id */
+        field: {
+            id: string;
+            [key: string]: any;
+        };
+        /** All fields in the array */
+        fields: {
+            id: string;
+            [key: string]: any;
+        }[];
+        /** Rendered field elements */
+        children: React.ReactNode;
+        /** Remove this item */
+        onRemove: () => void;
+        /** Move item up */
+        onMoveUp: () => void;
+        /** Move item down */
+        onMoveDown: () => void;
+        /** Whether item can be removed */
+        canRemove: boolean;
+        /** Whether item can move up */
+        canMoveUp: boolean;
+        /** Whether item can move down */
+        canMoveDown: boolean;
+    }) => React.ReactNode;
+    /** Custom render function for add button */
+    renderAddButton?: (props: {
+        /** Add new item */
+        onAdd: () => void;
+        /** Whether new item can be added */
+        canAdd: boolean;
+    }) => React.ReactNode;
 }
 interface DynamicSectionConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "dynamicSection";
@@ -132,7 +243,7 @@ interface DynamicSectionConfig<TFieldValues extends FieldValues> extends BaseFor
 }
 interface ContentFieldConfig<TFieldValues extends FieldValues = FieldValues> {
     type: "content";
-    name?: string;
+    name?: Path<TFieldValues>;
     title?: string;
     description?: string;
     render?: (field: {
@@ -142,7 +253,7 @@ interface ContentFieldConfig<TFieldValues extends FieldValues = FieldValues> {
     }) => React.ReactNode;
     className?: string;
 }
-type FormFieldConfig<TFieldValues extends FieldValues> = StringFieldConfig<TFieldValues> | BooleanFieldConfig<TFieldValues> | RadioFieldConfig<TFieldValues> | SliderFieldConfig<TFieldValues> | DateFieldConfig<TFieldValues> | FileFieldConfig<TFieldValues> | FontPickerFieldConfig<TFieldValues> | CustomFieldConfig<TFieldValues> | ConditionalFieldConfig<TFieldValues> | FieldArrayConfig<TFieldValues> | DynamicSectionConfig<TFieldValues> | ContentFieldConfig<TFieldValues>;
+type FormFieldConfig<TFieldValues extends FieldValues> = StringFieldConfig<TFieldValues> | BooleanFieldConfig<TFieldValues> | RadioFieldConfig<TFieldValues> | CheckboxGroupFieldConfig<TFieldValues> | SliderFieldConfig<TFieldValues> | DateFieldConfig<TFieldValues> | FileFieldConfig<TFieldValues> | FontPickerFieldConfig<TFieldValues> | StringArrayFieldConfig<TFieldValues> | CustomFieldConfig<TFieldValues> | ConditionalFieldConfig<TFieldValues> | FieldArrayConfig<TFieldValues> | DynamicSectionConfig<TFieldValues> | ContentFieldConfig<TFieldValues>;
 interface FormConfig<TFieldValues extends FieldValues> {
     fields: FormFieldConfig<TFieldValues>[];
     layout?: "vertical" | "horizontal" | "grid" | "custom";
@@ -156,10 +267,12 @@ interface FormConfig<TFieldValues extends FieldValues> {
     className?: string;
     defaultValues?: Partial<TFieldValues>;
 }
-type ZodFormFieldConfig<TFieldValues extends FieldValues> = Omit<StringFieldConfig<TFieldValues>, "rules"> | Omit<BooleanFieldConfig<TFieldValues>, "rules"> | Omit<RadioFieldConfig<TFieldValues>, "rules"> | Omit<SliderFieldConfig<TFieldValues>, "rules"> | Omit<DateFieldConfig<TFieldValues>, "rules"> | Omit<FileFieldConfig<TFieldValues>, "rules"> | Omit<FontPickerFieldConfig<TFieldValues>, "rules"> | Omit<CustomFieldConfig<TFieldValues>, "rules"> | Omit<ConditionalFieldConfig<TFieldValues>, "rules"> | Omit<FieldArrayConfig<TFieldValues>, "rules"> | Omit<DynamicSectionConfig<TFieldValues>, "rules"> | ContentFieldConfig<TFieldValues>;
+type ZodFormFieldConfig<TFieldValues extends FieldValues> = Omit<StringFieldConfig<TFieldValues>, "rules"> | Omit<BooleanFieldConfig<TFieldValues>, "rules"> | Omit<RadioFieldConfig<TFieldValues>, "rules"> | Omit<CheckboxGroupFieldConfig<TFieldValues>, "rules"> | Omit<SliderFieldConfig<TFieldValues>, "rules"> | Omit<DateFieldConfig<TFieldValues>, "rules"> | Omit<FileFieldConfig<TFieldValues>, "rules"> | Omit<FontPickerFieldConfig<TFieldValues>, "rules"> | Omit<StringArrayFieldConfig<TFieldValues>, "rules"> | Omit<CustomFieldConfig<TFieldValues>, "rules"> | Omit<ConditionalFieldConfig<TFieldValues>, "rules"> | Omit<FieldArrayConfig<TFieldValues>, "rules"> | Omit<DynamicSectionConfig<TFieldValues>, "rules"> | ContentFieldConfig<TFieldValues>;
 interface ZodFormConfig<TFieldValues extends FieldValues> extends UseFormProps<TFieldValues> {
     schema: zod.ZodSchema<TFieldValues>;
-    fields: ZodFormFieldConfig<TFieldValues>[];
+    fields: (ZodFormFieldConfig<TFieldValues> | (Omit<ZodFormFieldConfig<FieldValues>, "name"> & {
+        name: Path<TFieldValues>;
+    }))[];
     onError?: (errors: FieldErrors<TFieldValues>) => void;
     errorDisplay?: "inline" | "toast" | "modal" | "none";
 }
@@ -247,7 +360,7 @@ interface FormProps$1<T extends FieldValues> {
     submitButtonText?: string;
     subtitle?: string;
     title?: string;
-    defaultValues?: Partial<T>;
+    defaultValues?: DefaultValues<T>;
 }
 /**
  * Base form component for building forms without Zod validation.
@@ -303,11 +416,16 @@ interface FormProps$1<T extends FieldValues> {
 declare function ConfigurableForm<T extends FieldValues>({ className, columns, defaultValues, fields, layout, onError, onSubmit, onSuccess, resetButtonText, showResetButton, spacing, submitButtonProps, submitButtonText, subtitle, title, }: FormProps$1<T>): React$1.JSX.Element;
 
 interface FormFieldProps<TFieldValues extends FieldValues> {
-    config: FormFieldConfig<TFieldValues>;
+    config: FormFieldConfig<TFieldValues> | ZodFormFieldConfig<TFieldValues> | (Omit<FormFieldConfig<FieldValues>, "name"> & {
+        name: Path<TFieldValues>;
+    }) | (Omit<ZodFormFieldConfig<FieldValues>, "name"> & {
+        name: Path<TFieldValues>;
+    });
     form: UseFormReturn<TFieldValues>;
     submissionState: FormSubmissionState;
 }
-declare const FormField: <TFieldValues extends FieldValues>(props: FormFieldProps<TFieldValues>) => React$1.JSX.Element;
+declare function FormFieldComponent<TFieldValues extends FieldValues>({ config, form, submissionState, }: FormFieldProps<TFieldValues>): string | number | bigint | boolean | Iterable<React$1.ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode> | null | undefined> | React$1.JSX.Element | null | undefined;
+declare const FormField: typeof FormFieldComponent;
 
 type ServerAction<TState = unknown, TFormData = FormData> = (state: TState | undefined, formData: TFormData) => Promise<TState>;
 interface ActionState {
@@ -323,8 +441,12 @@ interface ServerActionFormProps<T extends FieldValues> {
     className?: string;
     columns?: 1 | 2 | 3;
     /** Default values for form fields */
-    defaultValues?: Partial<T>;
-    fields: FormFieldConfig<T>[];
+    defaultValues?: Partial<T> | Record<string, unknown>;
+    fields: (FormFieldConfig<T> | FormFieldConfig<any> | ZodFormFieldConfig<any> | (Omit<FormFieldConfig<FieldValues>, "name"> & {
+        name: Path<T>;
+    }) | (Omit<ZodFormFieldConfig<FieldValues>, "name"> & {
+        name: Path<T>;
+    }))[];
     /** Initial state for useActionState */
     initialState?: ActionState;
     layout?: "vertical" | "horizontal" | "grid";
@@ -433,7 +555,7 @@ interface ServerActionFormProps<T extends FieldValues> {
  * @see {@link ConfigurableForm} for forms without Server Actions
  * @category Components
  */
-declare function ServerActionForm<T extends FieldValues>({ action, className, clientValidationSchema, columns, defaultValues, fields, initialState, layout, onError, onSuccess, resetButtonText, showResetButton, spacing, submitButtonProps, submitButtonText, subtitle, title, }: ServerActionFormProps<T>): React$1.JSX.Element;
+declare function ServerActionForm<T extends FieldValues = FieldValues>({ action, className, clientValidationSchema, columns, defaultValues, fields, initialState, layout, onError, onSuccess, resetButtonText, showResetButton, spacing, submitButtonProps, submitButtonText, subtitle, title, }: ServerActionFormProps<T>): React$1.JSX.Element;
 
 /**
  * Configuration for an autocomplete option.
@@ -637,6 +759,119 @@ type CheckboxFieldProps<TFieldValues extends FieldValues> = FieldBaseProps<TFiel
  */
 declare function CheckboxField<TFieldValues extends FieldValues>(props: CheckboxFieldProps<TFieldValues>): React$1.JSX.Element;
 
+/**
+ * Configuration for a checkbox option in a checkbox group.
+ *
+ * @template TValue - The value type for the option
+ */
+interface CheckboxOption<TValue extends string | number> {
+    /** Display label for the option */
+    label: string;
+    /** Value of the option */
+    value: TValue;
+    /** Optional description text */
+    description?: string;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+}
+/**
+ * Props for the CheckboxGroupField component.
+ *
+ * @template TFieldValues - The form data type
+ * @template TValue - The value type for the checkbox group (string or number)
+ *
+ * @example
+ * ```tsx
+ * import { CheckboxGroupField } from "@rachelallyson/hero-hook-form";
+ * import { useForm } from "react-hook-form";
+ *
+ * const form = useForm({
+ *   defaultValues: { interests: [] },
+ * });
+ *
+ * const options = [
+ *   { label: "Reading", value: "reading" },
+ *   { label: "Sports", value: "sports" },
+ *   { label: "Music", value: "music" },
+ * ];
+ *
+ * <CheckboxGroupField
+ *   control={form.control}
+ *   name="interests"
+ *   label="Interests"
+ *   options={options}
+ * />
+ * ```
+ */
+type CheckboxGroupFieldProps<TFieldValues extends FieldValues, TValue extends string | number = string> = FieldBaseProps<TFieldValues, TValue[]> & WithControl<TFieldValues> & {
+    /** Array of checkbox options */
+    options: readonly CheckboxOption<TValue>[];
+    /** Additional props to pass to individual Checkbox components */
+    checkboxProps?: Omit<React$1.ComponentProps<typeof Checkbox>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled" | "name">;
+    /** Layout orientation for the checkboxes */
+    orientation?: "vertical" | "horizontal";
+};
+/**
+ * A checkbox group field component that integrates React Hook Form with HeroUI Checkbox.
+ *
+ * This component provides a type-safe checkbox group field with validation support,
+ * error handling, and accessibility features. Multiple options can be selected,
+ * and the value is stored as an array of selected option values.
+ *
+ * @template TFieldValues - The form data type
+ * @template TValue - The value type for the checkbox group (string or number)
+ *
+ * @param props - The checkbox group field props
+ * @returns The rendered checkbox group field component
+ *
+ * @example
+ * ```tsx
+ * import { ZodForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({
+ *   interests: z.array(z.string()).min(1, "Please select at least one interest"),
+ * });
+ *
+ * const options = [
+ *   { label: "Reading", value: "reading" },
+ *   { label: "Sports", value: "sports" },
+ *   { label: "Music", value: "music" },
+ * ];
+ *
+ * function MyForm() {
+ *   return (
+ *     <ZodForm
+ *       config={{
+ *         schema,
+ *         fields: [
+ *           FormFieldHelpers.checkboxGroup("interests", "Interests", options),
+ *         ],
+ *       }}
+ *       onSubmit={(data) => console.log(data)}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling and horizontal layout
+ * <CheckboxGroupField
+ *   control={form.control}
+ *   name="interests"
+ *   label="Interests"
+ *   options={options}
+ *   orientation="horizontal"
+ *   checkboxProps={{
+ *     color: "primary",
+ *     size: "lg",
+ *   }}
+ * />
+ * ```
+ */
+declare function CheckboxGroupField<TFieldValues extends FieldValues, TValue extends string | number = string>(props: CheckboxGroupFieldProps<TFieldValues, TValue>): React$1.JSX.Element;
+
 /**
  * Props for the DateField component.
  *
@@ -1362,7 +1597,7 @@ interface UseFormHelperOptions<T extends FieldValues> {
     onError?: (error: FormValidationError) => void;
     onSubmit: SubmitHandler<T>;
     onSuccess?: (data: T) => void;
-    defaultValues?: Partial<T>;
+    defaultValues?: DefaultValues<T>;
     methods?: UseFormReturn<T>;
 }
 /**
@@ -1497,7 +1732,7 @@ declare function useFormHelper<T extends FieldValues>({ defaultValues, methods,
  * @category Hooks
  */
 declare function useHeroForm<TFieldValues extends FieldValues>(): {
-    defaults: Required<Pick<HeroHookFormDefaultsConfig, "input" | "textarea" | "select" | "switch" | "radioGroup" | "checkbox" | "slider" | "dateInput" | "submitButton">>;
+    defaults: Required<Pick<HeroHookFormDefaultsConfig, "input" | "textarea" | "select" | "checkbox" | "switch" | "slider" | "radioGroup" | "dateInput" | "submitButton">>;
     watch: react_hook_form.UseFormWatch<TFieldValues>;
     getValues: react_hook_form.UseFormGetValues<TFieldValues>;
     getFieldState: react_hook_form.UseFormGetFieldState<TFieldValues>;
@@ -1940,6 +2175,7 @@ interface ZodFormProps<T extends FieldValues> {
     className?: string;
     columns?: 1 | 2 | 3;
     config: ZodFormConfig<T>;
+    errorDisplay?: "inline" | "toast" | "modal" | "none";
     layout?: "vertical" | "horizontal" | "grid";
     onError?: (error: FormValidationError) => void;
     onSubmit: SubmitHandler<T>;
@@ -2032,6 +2268,83 @@ interface ZodFormProps<T extends FieldValues> {
  */
 declare function ZodForm<T extends FieldValues>({ className, columns, config, layout, onError, onSubmit, onSuccess, resetButtonText, showResetButton, spacing, submitButtonProps, submitButtonText, subtitle, title, }: ZodFormProps<T>): React$1.JSX.Element;
 
+/**
+ * Props for the SimpleForm component.
+ *
+ * @template TFieldValues - The form data type
+ */
+interface SimpleFormProps<TFieldValues extends FieldValues> {
+    /** Zod schema for validation */
+    schema: ZodSchema<TFieldValues>;
+    /** Single field configuration */
+    field: ZodFormFieldConfig<TFieldValues>;
+    /** Submit handler */
+    onSubmit: (data: TFieldValues) => Promise<void> | void;
+    /** Optional custom submit button */
+    submitButton?: React$1.ReactNode;
+    /** Optional form title */
+    title?: string;
+    /** Optional form subtitle */
+    subtitle?: string;
+    /** Optional className */
+    className?: string;
+    /** Optional default values */
+    defaultValues?: DefaultValues<TFieldValues>;
+    /** Optional error callback */
+    onError?: (error: FormValidationError) => void;
+    /** Optional success callback */
+    onSuccess?: (data: TFieldValues) => void;
+    /** Hide default submit button (use custom submitButton instead) */
+    hideSubmitButton?: boolean;
+}
+/**
+ * Simple form component for single-field forms.
+ *
+ * @description
+ * A simplified API for forms with a single field. Provides the same validation
+ * and error handling as ZodForm but with a simpler configuration.
+ * Useful for simple inputs like search bars, message inputs, or single-field forms.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {SimpleFormProps<TFieldValues>} props - Component props
+ * @returns {JSX.Element} The rendered form
+ *
+ * @example
+ * ```tsx
+ * import { SimpleForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ * import { z } from "zod";
+ *
+ * const messageSchema = z.object({
+ *   message: z.string().min(1, "Message cannot be empty"),
+ * });
+ *
+ * function MessageInput() {
+ *   return (
+ *     <SimpleForm
+ *       schema={messageSchema}
+ *       field={FormFieldHelpers.input("message", "", {
+ *         placeholder: "Add a note...",
+ *         endContent: (
+ *           <Button type="submit" isIconOnly>
+ *             <SendIcon />
+ *           </Button>
+ *         ),
+ *       })}
+ *       onSubmit={async (data) => {
+ *         await sendMessage(data.message);
+ *       }}
+ *       hideSubmitButton
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ZodForm} for multi-field forms
+ * @category Components
+ */
+declare function SimpleForm<TFieldValues extends FieldValues>({ className, defaultValues, field, hideSubmitButton, onError, onSubmit, onSuccess, schema, submitButton, subtitle, title, }: SimpleFormProps<TFieldValues>): React$1.JSX.Element;
+
 /**
  * Hook for using Zod validation with React Hook Form
  */
@@ -2039,7 +2352,7 @@ declare function useZodForm<TFieldValues extends FieldValues>(config: ZodFormCon
 /**
  * Helper function to create Zod form configurations
  */
-declare function createZodFormConfig<TFieldValues extends FieldValues>(schema: z.ZodSchema<TFieldValues>, fields: ZodFormFieldConfig<TFieldValues>[], defaultValues?: Partial<TFieldValues>): ZodFormConfig<TFieldValues>;
+declare function createZodFormConfig<TFieldValues extends FieldValues>(schema: z.ZodSchema<TFieldValues>, fields: ZodFormFieldConfig<TFieldValues>[], defaultValues?: DefaultValues<TFieldValues>): ZodFormConfig<TFieldValues>;
 
 /**
  * Basic form field builder for creating form field configurations.
@@ -2189,6 +2502,11 @@ declare function createBasicFormBuilder<T extends FieldValues>(): BasicFormBuild
  * @see {@link createBasicFormBuilder} for builder pattern alternative
  * @category Builders
  */
+type InputPropsType = Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
+declare function inputHelper<T extends FieldValues>(name: Path<T>, label: string): ZodFormFieldConfig<T>;
+declare function inputHelper<T extends FieldValues>(name: Path<T>, label: string, type: "text" | "email" | "tel" | "password"): ZodFormFieldConfig<T>;
+declare function inputHelper<T extends FieldValues>(name: Path<T>, label: string, inputProps: InputPropsType): ZodFormFieldConfig<T>;
+declare function inputHelper<T extends FieldValues>(name: Path<T>, label: string, type: "text" | "email" | "tel" | "password", inputProps: InputPropsType): ZodFormFieldConfig<T>;
 declare const FormFieldHelpers: {
     /**
      * Create an autocomplete field
@@ -2228,6 +2546,33 @@ declare const FormFieldHelpers: {
      * ```
      */
     checkbox: <T extends FieldValues>(name: Path<T>, label: string, checkboxProps?: Omit<React$1.ComponentProps<typeof Checkbox>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
+    /**
+     * Create a checkbox group field (multiple checkboxes saving to an array)
+     *
+     * @example
+     * ```tsx
+     * // Simple checkbox group
+     * FormFieldHelpers.checkboxGroup("interests", "Interests", [
+     *   { label: "Reading", value: "reading" },
+     *   { label: "Sports", value: "sports" },
+     *   { label: "Music", value: "music" },
+     * ])
+     *
+     * // With horizontal layout and custom styling
+     * FormFieldHelpers.checkboxGroup("interests", "Interests", options, {
+     *   orientation: "horizontal",
+     *   checkboxProps: { color: "primary", size: "lg" }
+     * })
+     * ```
+     */
+    checkboxGroup: <T extends FieldValues>(name: Path<T>, label: string, options: {
+        label: string;
+        value: string | number;
+    }[], config?: {
+        checkboxProps?: Omit<React$1.ComponentProps<typeof Checkbox>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled" | "name">;
+        orientation?: "vertical" | "horizontal";
+        description?: string;
+    }) => ZodFormFieldConfig<T>;
     /**
      * Create a conditional field that shows/hides based on form data
      *
@@ -2273,7 +2618,34 @@ declare const FormFieldHelpers: {
             isSubmitting: boolean;
         }) => React$1.ReactNode;
         className?: string;
-        name?: string;
+        name?: Path<T>;
+    }) => ZodFormFieldConfig<T>;
+    /**
+     * Create a custom field with full control over rendering
+     *
+     * @example
+     * ```tsx
+     * // Custom field with render function
+     * FormFieldHelpers.custom<FormData>(
+     *   "skills",
+     *   "Skills",
+     *   ({ form, control }) => {
+     *     // Custom rendering logic
+     *     return <div>...</div>;
+     *   }
+     * )
+     * ```
+     */
+    custom: <T extends FieldValues>(name: Path<T> | ArrayPath<T>, label: string, render: (field: {
+        name: Path<T> | ArrayPath<T>;
+        control: Control<T>;
+        form: UseFormReturn<T>;
+        errors: FieldErrors<T>;
+        isSubmitting: boolean;
+    }) => React$1.ReactNode, options?: {
+        description?: string;
+        className?: string;
+        isDisabled?: boolean;
     }) => ZodFormFieldConfig<T>;
     /**
      * Create a date field
@@ -2352,7 +2724,10 @@ declare const FormFieldHelpers: {
      * // With type
      * FormFieldHelpers.input("email", "Email", "email")
      *
-     * // With full customization
+     * // With props only (no type)
+     * FormFieldHelpers.input("name", "Name", { placeholder: "Enter name" })
+     *
+     * // With type and props
      * FormFieldHelpers.input("email", "Email", "email", {
      *   placeholder: "Enter your email",
      *   classNames: { input: "custom-input" },
@@ -2361,7 +2736,25 @@ declare const FormFieldHelpers: {
      * })
      * ```
      */
-    input: <T extends FieldValues>(name: Path<T>, label: string, type?: "text" | "email" | "tel" | "password", inputProps?: Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
+    input: typeof inputHelper;
+    /**
+     * Create a radio group field
+     *
+     * @example
+     * ```tsx
+     * // Simple radio group
+     * FormFieldHelpers.radio("gender", "Gender", [
+     *   { label: "Male", value: "male" },
+     *   { label: "Female", value: "female" }
+     * ])
+     *
+     * // With full customization
+     * FormFieldHelpers.radio("gender", "Gender", options, {
+     *   orientation: "horizontal",
+     *   classNames: { base: "custom-radio" }
+     * })
+     * ```
+     */
     /**
      * Create a radio group field
      *
@@ -2466,6 +2859,26 @@ declare const FormFieldHelpers: {
 };
 /**
  * Common field collections
+ *
+ * These helpers provide reusable field sets for common form patterns.
+ * The `as Path<T>` assertions are necessary because TypeScript cannot prove
+ * that string literals like "street" or "email" are valid paths in an arbitrary
+ * form type `T`. These helpers are designed to work with any form type that
+ * happens to have these fields - the type safety is enforced when you use them
+ * with a specific form schema.
+ *
+ * @example
+ * ```tsx
+ * const schema = z.object({
+ *   street: z.string(),
+ *   city: z.string(),
+ *   // ... other fields
+ * });
+ *
+ * const fields = [
+ *   ...CommonFields.address<z.infer<typeof schema>>(),
+ * ];
+ * ```
  */
 declare const CommonFields: {
     /**
@@ -2483,10 +2896,163 @@ declare const CommonFields: {
 };
 
 /**
- * Unified field creation function
- * Takes field type as first argument and delegates to appropriate helper
+ * Discriminated union types for field creation parameters
+ * This eliminates the need for 'unknown' types and type assertions
  */
-declare function createField<T extends FieldValues>(type: string, name: Path<T>, label: string, optionsOrProps?: any, props?: any): ZodFormFieldConfig<T>;
+type FieldCreationParams<T extends FieldValues> = {
+    type: "input";
+    name: Path<T>;
+    label: string;
+    props?: {
+        type?: "text" | "email" | "tel" | "password" | "number" | "url";
+        placeholder?: string;
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "textarea";
+    name: Path<T>;
+    label: string;
+    props?: {
+        placeholder?: string;
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+        rows?: number;
+    };
+} | {
+    type: "select";
+    name: Path<T>;
+    label: string;
+    options: {
+        label: string;
+        value: string | number;
+    }[];
+} | {
+    type: "autocomplete";
+    name: Path<T>;
+    label: string;
+    options: {
+        label: string;
+        value: string | number;
+    }[];
+    props?: Record<string, unknown>;
+} | {
+    type: "checkbox";
+    name: Path<T>;
+    label: string;
+    props?: {
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "switch";
+    name: Path<T>;
+    label: string;
+    props?: {
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "radio";
+    name: Path<T>;
+    label: string;
+    options: {
+        label: string;
+        value: string | number;
+    }[];
+    props?: {
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+        orientation?: "horizontal" | "vertical";
+    };
+} | {
+    type: "slider";
+    name: Path<T>;
+    label: string;
+    props?: {
+        min?: number;
+        max?: number;
+        step?: number;
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "date";
+    name: Path<T>;
+    label: string;
+    props?: {
+        placeholder?: string;
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "file";
+    name: Path<T>;
+    label: string;
+    props?: {
+        accept?: string;
+        multiple?: boolean;
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "fontPicker";
+    name: Path<T>;
+    label: string;
+    props?: {
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+        fontPickerProps?: {
+            showFontPreview?: boolean;
+            loadAllVariants?: boolean;
+            onFontsLoaded?: (loaded: boolean) => void;
+            fontsLoadedTimeout?: number;
+        };
+    };
+} | {
+    type: "stringArray";
+    name: Path<T>;
+    label: string;
+    props?: {
+        placeholder?: string;
+        maxItems?: number;
+        minItems?: number;
+        allowDuplicates?: boolean;
+        validateItem?: (item: string) => string | true;
+        transformItem?: (item: string) => string;
+        addButtonText?: string;
+        showAddButton?: boolean;
+        description?: string;
+        isDisabled?: boolean;
+        className?: string;
+    };
+} | {
+    type: "content";
+    name?: Path<T>;
+    label?: string;
+    title?: string | null;
+    description?: string | null;
+    render?: (field: {
+        form: UseFormReturn<T>;
+        errors: FieldErrors<T>;
+        isSubmitting: boolean;
+    }) => React$1.ReactNode;
+    className?: string;
+};
+/**
+ * Unified field creation function using discriminated union types
+ * This provides full type safety without complex overloads
+ */
+declare function createField<T extends FieldValues>(params: FieldCreationParams<T>): ZodFormFieldConfig<T>;
 /**
  * Builder pattern for advanced field creation
  */
@@ -2495,21 +3061,7 @@ declare class AdvancedFieldBuilder<T extends FieldValues> {
     /**
      * Add any field type using the unified API
      */
-    field(type: "input", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
-    field(type: "textarea", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
-    field(type: "select", name: Path<T>, label: string, options: {
-        label: string;
-        value: string | number;
-    }[], props?: Parameters<typeof createField<T>>[4]): this;
-    field(type: "checkbox", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
-    field(type: "switch", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
-    field(type: "radio", name: Path<T>, label: string, options: {
-        label: string;
-        value: string | number;
-    }[], props?: Parameters<typeof createField<T>>[4]): this;
-    field(type: "slider", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
-    field(type: "date", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
-    field(type: "file", name: Path<T>, label: string, props?: Parameters<typeof createField<T>>[3]): this;
+    field(params: FieldCreationParams<T>): this;
     /**
      * Add a conditional field that shows/hides based on form data
      */
@@ -2517,7 +3069,7 @@ declare class AdvancedFieldBuilder<T extends FieldValues> {
     /**
      * Add a field array for dynamic repeating field groups
      */
-    fieldArray(name: Path<T>, label: string, fields: ZodFormFieldConfig<any>[], options?: {
+    fieldArray(name: ArrayPath<T>, label: string, fields: ZodFormFieldConfig<T>[], options?: {
         min?: number;
         max?: number;
         addButtonText?: string;
@@ -2543,22 +3095,7 @@ declare class FieldArrayItemBuilder<TItem extends FieldValues> {
     /**
      * Add any field type using the unified API for array items
      */
-    field(type: "input", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "textarea", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "select", name: Path<TItem>, label: string, options: {
-        label: string;
-        value: string | number;
-    }[], props?: Parameters<typeof createField<TItem>>[4]): this;
-    field(type: "checkbox", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "switch", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "radio", name: Path<TItem>, label: string, options: {
-        label: string;
-        value: string | number;
-    }[], props?: Parameters<typeof createField<TItem>>[4]): this;
-    field(type: "slider", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "date", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "file", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
-    field(type: "fontPicker", name: Path<TItem>, label: string, props?: Parameters<typeof createField<TItem>>[3]): this;
+    field(params: FieldCreationParams<TItem>): this;
     /**
      * Build the field array item configuration
      */
@@ -2575,8 +3112,8 @@ declare class FieldArrayBuilder<T extends FieldValues, TArrayName extends Path<T
     private arrayName;
     private fields;
     constructor(arrayName: TArrayName);
-    field(type: string, name: string, label: string, optionsOrProps?: any, props?: any): this;
-    build(): ZodFormFieldConfig<any>[];
+    field(params: FieldCreationParams<Record<string, any>>): this;
+    build(): ZodFormFieldConfig<T>[];
 }
 /**
  * Create a field array builder that constructs proper paths for array items
@@ -2745,17 +3282,32 @@ declare const field: {
     textarea: <T extends FieldValues>(name: Path<T>, label: string, options?: Parameters<TypeInferredBuilder<T>["textarea"]>[2]) => TypeInferredBuilder<T>;
 };
 
+/**
+ * Helper type to construct a nested path from a base path and sub-path.
+ * Attempts to construct the path and falls back to Path<T> if TypeScript
+ * can't verify the nested structure at compile time.
+ *
+ * @example
+ * type T = { user: { name: string } };
+ * type Nested = ConstructNestedPath<T, "user", "name">; // "user.name"
+ */
+type ConstructNestedPath<T extends FieldValues, TBasePath extends Path<T>, TSubPath extends string> = `${TBasePath}.${TSubPath}` extends Path<T> ? `${TBasePath}.${TSubPath}` : Path<T>;
 /**
  * Enhanced nested path builder with better syntax for complex nested structures
  * Provides multiple approaches for handling nested field paths
  */
 declare class NestedPathBuilder<T extends FieldValues> {
-    private fields;
+    fields: ZodFormFieldConfig<T>[];
     /**
      * Create a nested object path builder
      * Usage: builder.nest("address").field("street", "Street Address")
+     *
+     * @param path - A path in the form data structure. When called from root level,
+     *               accepts Path<T>. When called after .end() from a nested context,
+     *               accepts any string for nested paths under sections.
+     * @returns A builder for nested paths under the specified path
      */
-    nest<TPath extends Path<T>>(path: TPath): NestedObjectBuilder<T, TPath>;
+    nest(path: string & {}): NestedObjectBuilder<T, Path<T>>;
     /**
      * Create a section-based path builder
      * Usage: builder.section("shipping").field("street", "Street Address")
@@ -2763,14 +3315,14 @@ declare class NestedPathBuilder<T extends FieldValues> {
     section<TPath extends Path<T>>(path: TPath): SectionBuilder<T, TPath>;
     /**
      * Add a field with single path
-     * Usage: builder.field("firstName", "First Name")
+     * Usage: builder.field({ type: "input", name: "firstName", label: "First Name" })
      */
-    field(name: Path<T>, label: string, type?: string, props?: any): this;
+    field(params: FieldCreationParams<T> | FieldCreationParams<Record<string, any>>): this;
     /**
      * Add a field with path segments
-     * Usage: builder.fieldPath(["user", "profile", "name"], "Full Name")
+     * Usage: builder.fieldPath({ type: "input", name: path.join("."), label: "Full Name" })
      */
-    fieldPath(path: string[], label: string, type?: string, props?: any): this;
+    fieldPath(params: FieldCreationParams<T>): this;
     /**
      * Add a field with template literal path
      * Usage: builder.field`user.profile.name`("Full Name")
@@ -2792,11 +3344,16 @@ declare class NestedObjectBuilder<T extends FieldValues, TPath extends Path<T>>
     /**
      * Add a field to the current nested path
      */
-    field<FName extends string>(fieldName: FName, label: string, type?: string, props?: any): NestedObjectBuilder<T, TPath>;
+    field(params: FieldCreationParams<Record<string, any>>): NestedObjectBuilder<T, TPath>;
     /**
      * Nest deeper into the object
+     *
+     * @param subPath - A string representing a nested path under the current path.
+     *                  The parameter accepts any string; TypeScript validates the constructed
+     *                  path (basePath.subPath) in the return type.
+     * @returns A builder for the nested path
      */
-    nest<SubPath extends string>(subPath: SubPath): NestedObjectBuilder<T, TPath>;
+    nest<SubPath extends string>(subPath: SubPath): NestedObjectBuilder<T, ConstructNestedPath<T, TPath, SubPath>>;
     /**
      * Return to the parent builder
      */
@@ -2812,20 +3369,25 @@ declare class SectionBuilder<T extends FieldValues, TPath extends Path<T>> {
     /**
      * Add a field to the current section
      */
-    field<FName extends string>(fieldName: FName, label: string, type?: string, props?: any): SectionBuilder<T, TPath>;
+    field(params: FieldCreationParams<Record<string, any>>): SectionBuilder<T, TPath>;
     /**
      * Add multiple fields to the section
      */
     fields(fieldDefinitions: {
         name: string;
         label: string;
-        type?: string;
-        props?: any;
+        type?: FormFieldType;
+        props?: Record<string, unknown>;
     }[]): SectionBuilder<T, TPath>;
     /**
      * Nest deeper into the section
+     *
+     * @param subPath - A string representing a nested path under the current section path.
+     *                  The parameter accepts any string; TypeScript validates the constructed
+     *                  path (basePath.subPath) in the return type.
+     * @returns A builder for the nested path
      */
-    nest<SubPath extends string>(subPath: SubPath): NestedObjectBuilder<T, TPath>;
+    nest<SubPath extends string = string>(subPath: SubPath): NestedObjectBuilder<T, ConstructNestedPath<T, TPath, string>>;
     /**
      * Return to the parent builder
      */
@@ -2841,7 +3403,9 @@ declare class FieldTemplateBuilder<T extends FieldValues> {
     /**
      * Complete the field definition
      */
-    complete(label: string, type?: string, props?: any): NestedPathBuilder<T>;
+    complete(params: Omit<FieldCreationParams<Record<string, any>>, "name"> & {
+        name?: string;
+    }): NestedPathBuilder<T>;
 }
 /**
  * Factory function for creating the nested path builder
@@ -2851,9 +3415,9 @@ declare function createNestedPathBuilder<T extends FieldValues>(): NestedPathBui
 /**
  * Options for the useDebouncedValidation hook.
  */
-interface UseDebouncedValidationOptions {
+interface UseDebouncedValidationOptions<T extends FieldValues = FieldValues> {
     delay?: number;
-    fields?: string[];
+    fields?: Path<T>[];
     enabled?: boolean;
 }
 /**
@@ -2906,7 +3470,7 @@ interface UseDebouncedValidationOptions {
  * @see {@link useDebouncedFieldValidation} for single field debouncing
  * @category Hooks
  */
-declare function useDebouncedValidation<T extends Record<string, any>>(form: UseFormReturn<T>, options?: UseDebouncedValidationOptions): {
+declare function useDebouncedValidation<T extends FieldValues>(form: UseFormReturn<T>, options?: UseDebouncedValidationOptions<T>): {
     debouncedTrigger: () => void;
     isDebouncing: boolean;
 };
@@ -2957,7 +3521,7 @@ declare function useDebouncedValidation<T extends Record<string, any>>(form: Use
  * @see {@link useDebouncedValidation} for multiple fields
  * @category Hooks
  */
-declare function useDebouncedFieldValidation<T extends Record<string, any>>(form: UseFormReturn<T>, fieldName: keyof T, options?: {
+declare function useDebouncedFieldValidation<T extends FieldValues>(form: UseFormReturn<T>, fieldName: Path<T>, options?: {
     delay?: number;
     enabled?: boolean;
 }): {
@@ -2971,7 +3535,7 @@ declare function useDebouncedFieldValidation<T extends Record<string, any>>(form
  * @template T - The form data type
  */
 interface UseInferredFormOptions<T extends FieldValues> {
-    defaultValues?: Partial<T>;
+    defaultValues?: DefaultValues<T>;
     mode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
     reValidateMode?: "onChange" | "onBlur" | "onSubmit";
     shouldFocusError?: boolean;
@@ -3162,6 +3726,7 @@ interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
  * Allows users to add and remove multiple instances of a field group.
  * Useful for forms with repeating data like addresses, items, or contacts.
  * Automatically manages field array state and provides add/remove buttons.
+ * Supports reordering, custom item rendering, default values, and conditional fields within items.
  *
  * @template TFieldValues - The form data type
  *
@@ -3172,42 +3737,101 @@ interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
  * @returns {JSX.Element} The rendered field array with add/remove controls
  *
  * @example
+ * Basic usage:
  * ```tsx
  * import { FieldArrayField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
  *
  * const fields = [
  *   FormFieldHelpers.input("name", "Name"),
- *   FieldArrayField({
- *     config: {
- *       name: "addresses",
- *       label: "Address",
- *       fields: [
- *         FormFieldHelpers.input("street", "Street Address"),
- *         FormFieldHelpers.input("city", "City"),
- *         FormFieldHelpers.input("zipCode", "ZIP Code"),
- *       ],
- *       min: 1,
- *       max: 5,
- *       addButtonText: "Add Address",
- *       removeButtonText: "Remove Address",
- *     },
- *   }),
+ *   {
+ *     type: "fieldArray",
+ *     name: "addresses",
+ *     label: "Address",
+ *     fields: [
+ *       FormFieldHelpers.input("street", "Street Address"),
+ *       FormFieldHelpers.input("city", "City"),
+ *       FormFieldHelpers.input("zipCode", "ZIP Code"),
+ *     ],
+ *     min: 1,
+ *     max: 5,
+ *     addButtonText: "Add Address",
+ *     removeButtonText: "Remove Address",
+ *   },
  * ];
  * ```
  *
  * @example
- * With validation:
+ * With reordering:
  * ```tsx
- * const schema = z.object({
- *   addresses: z.array(z.object({
- *     street: z.string().min(1, "Street is required"),
- *     city: z.string().min(1, "City is required"),
- *   })).min(1, "At least one address is required"),
- * });
+ * {
+ *   type: "fieldArray",
+ *   name: "slots",
+ *   label: "Question Slots",
+ *   enableReordering: true,
+ *   reorderButtonText: { up: "↑", down: "↓" },
+ *   fields: [
+ *     FormFieldHelpers.select("slotType", "Slot Type", options),
+ *   ],
+ * }
+ * ```
+ *
+ * @example
+ * With custom item rendering:
+ * ```tsx
+ * {
+ *   type: "fieldArray",
+ *   name: "items",
+ *   renderItem: ({ index, children, onMoveUp, onMoveDown, onRemove }) => (
+ *     <Card className="p-4">
+ *       <div className="flex justify-between">
+ *         <span>Item {index + 1}</span>
+ *         <Button onPress={onRemove}>Remove</Button>
+ *       </div>
+ *       {children}
+ *     </Card>
+ *   ),
+ *   fields: [...],
+ * }
+ * ```
+ *
+ * @example
+ * With default item:
+ * ```tsx
+ * {
+ *   type: "fieldArray",
+ *   name: "slots",
+ *   defaultItem: () => ({
+ *     order: 0,
+ *     slotType: "STATIC",
+ *     staticQuestionId: "",
+ *   }),
+ *   fields: [...],
+ * }
+ * ```
+ *
+ * @example
+ * With conditional fields within items:
+ * ```tsx
+ * {
+ *   type: "fieldArray",
+ *   name: "slots",
+ *   fields: [
+ *     FormFieldHelpers.select("slotType", "Slot Type", [
+ *       { label: "Static", value: "STATIC" },
+ *       { label: "Dynamic", value: "DYNAMIC" },
+ *     ]),
+ *     {
+ *       ...FormFieldHelpers.select("staticQuestionId", "Question", questions),
+ *       dependsOn: "slotType",
+ *       dependsOnValue: "STATIC",
+ *     },
+ *   ],
+ * }
  * ```
  *
  * @see {@link ConditionalField} for conditional single fields
  * @see {@link DynamicSectionField} for conditional field groups
+ * @see {@link createFieldArrayCustomConfig} for advanced custom rendering
  * @category Fields
  */
 declare function FieldArrayField<TFieldValues extends FieldValues>({ className, config, }: FieldArrayFieldProps<TFieldValues>): React$1.JSX.Element | null;
@@ -3323,7 +3947,7 @@ declare function throttle<T extends (...args: any[]) => any>(func: T, limit: num
 /**
  * Memoization helper for expensive computations
  */
-declare function useMemoizedCallback<T extends (...args: any[]) => any>(callback: T, deps: React.DependencyList): T;
+declare function useMemoizedCallback<T extends (...args: unknown[]) => unknown>(callback: T, deps: React.DependencyList): T;
 /**
  * Shallow comparison for React.memo
  */
@@ -3351,6 +3975,157 @@ declare function createOptimizedFieldHandler<T>(onChange: (value: T) => void, op
  */
 declare function useMemoizedFieldProps<T extends Record<string, any>>(props: T, deps: React.DependencyList): T;
 
+/**
+ * Options for syncing arrays
+ *
+ * @template TItem - The item type in the arrays
+ */
+interface ArraySyncOptions<TItem> {
+    /** Existing items (from database/API) */
+    existing: TItem[];
+    /** Current items (from form) */
+    current: TItem[];
+    /** Function to extract ID from an item */
+    getId: (item: TItem) => string | number | undefined;
+}
+/**
+ * Result of array sync operation
+ *
+ * @template TItem - The item type in the arrays
+ */
+interface ArraySyncResult<TItem> {
+    /** Items that should be deleted (exist in existing but not in current) */
+    toDelete: TItem[];
+    /** Items that should be updated (exist in both, may have changed) */
+    toUpdate: {
+        existing: TItem;
+        current: TItem;
+    }[];
+    /** Items that should be created (exist in current but not in existing) */
+    toCreate: TItem[];
+}
+/**
+ * Sync arrays to determine what items to delete, update, and create.
+ *
+ * @description
+ * Compares existing items (from database) with current items (from form)
+ * to determine which items need to be deleted, updated, or created.
+ * Useful for edit forms where you need to sync array changes.
+ *
+ * @template TItem - The item type in the arrays
+ *
+ * @param {ArraySyncOptions<TItem>} options - Sync options
+ * @returns {ArraySyncResult<TItem>} Result with items to delete, update, and create
+ *
+ * @example
+ * ```tsx
+ * const { toDelete, toUpdate, toCreate } = syncArrays({
+ *   existing: slots,
+ *   current: data.slots,
+ *   getId: (slot) => slot.id,
+ * });
+ *
+ * // Delete removed slots
+ * await Promise.all(toDelete.map(slot => deleteSlot(slot.id)));
+ *
+ * // Update existing slots
+ * await Promise.all(
+ *   toUpdate.map(({ existing, current }) =>
+ *     updateSlot(existing.id, current)
+ *   )
+ * );
+ *
+ * // Create new slots
+ * await Promise.all(toCreate.map(slot => createSlot(slot)));
+ * ```
+ *
+ * @category Utilities
+ */
+declare function syncArrays<TItem>(options: ArraySyncOptions<TItem>): ArraySyncResult<TItem>;
+
+/**
+ * Options for creating a custom field array config
+ *
+ * @template TFieldValues - The form data type
+ */
+interface CreateFieldArrayCustomConfigOptions<TFieldValues extends FieldValues> {
+    /** Field array name */
+    name: ArrayPath<TFieldValues>;
+    /** Optional label for the field array */
+    label?: string;
+    /** Render function for each array item */
+    renderItem: (props: {
+        index: number;
+        field: FieldArrayWithId<TFieldValues, ArrayPath<TFieldValues>>;
+        fields: FieldArrayWithId<TFieldValues, ArrayPath<TFieldValues>>[];
+        form: UseFormReturn<TFieldValues>;
+        control: Control<TFieldValues>;
+        errors: FieldErrors<TFieldValues>;
+        canMoveUp: boolean;
+        canMoveDown: boolean;
+        onMoveUp: () => void;
+        onMoveDown: () => void;
+        onRemove: () => void;
+    }) => React$1.ReactNode;
+    /** Optional render function for add button */
+    renderAddButton?: (props: {
+        onAdd: () => void;
+        canAdd: boolean;
+    }) => React$1.ReactNode;
+    /** Function to create default item when adding new array item */
+    defaultItem?: () => any;
+    /** Minimum number of items */
+    min?: number;
+    /** Maximum number of items */
+    max?: number;
+    /** Enable reordering of array items */
+    enableReordering?: boolean;
+    /** Optional className */
+    className?: string;
+}
+/**
+ * Create a CustomFieldConfig for field arrays with full control over rendering.
+ *
+ * @description
+ * This helper creates a CustomFieldConfig that uses useFieldArray internally,
+ * giving you full control over the UI while still being integrated with the form.
+ * Useful when you need custom layouts, reordering, or complex item rendering
+ * that FieldArrayConfig doesn't support.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {CreateFieldArrayCustomConfigOptions<TFieldValues>} options - Configuration options
+ * @returns {CustomFieldConfig<TFieldValues>} Custom field config for field arrays
+ *
+ * @example
+ * ```tsx
+ * const slotsConfig = createFieldArrayCustomConfig("slots", {
+ *   label: "Question Slots",
+ *   enableReordering: true,
+ *   renderItem: ({ index, field, form, control, onMoveUp, onMoveDown, onRemove }) => (
+ *     <div className="border rounded-lg p-4">
+ *       <div className="flex justify-between">
+ *         <span>Slot {index + 1}</span>
+ *         <div className="flex gap-2">
+ *           <Button onPress={onMoveUp}>↑</Button>
+ *           <Button onPress={onMoveDown}>↓</Button>
+ *           <Button onPress={onRemove}>Remove</Button>
+ *         </div>
+ *       </div>
+ *       <SelectField
+ *         name={`slots.${index}.slotType`}
+ *         control={control}
+ *         // ...
+ *       />
+ *     </div>
+ *   ),
+ * });
+ * ```
+ *
+ * @category Utilities
+ */
+declare function createFieldArrayCustomConfig<TFieldValues extends FieldValues>(options: CreateFieldArrayCustomConfigOptions<TFieldValues>): CustomFieldConfig<TFieldValues>;
+
 /**
  * Common validation patterns for forms
  */
@@ -3434,4 +4209,4 @@ declare const validationUtils: {
     }>;
 };
 
-export { AdvancedFieldBuilder, AutocompleteField, type AutocompleteFieldProps, type AutocompleteOption, type BaseFormFieldConfig, BasicFormBuilder, type BooleanFieldConfig, type ButtonDefaults, type CheckboxDefaults, CheckboxField, type CheckboxFieldProps, type CommonFieldDefaults, CommonFields, ConditionalField, type ConditionalFieldConfig, type ConditionalFieldProps, type ConditionalValidation, ConfigurableForm, ContentField, type ContentFieldConfig, type CustomFieldConfig, DateField, type DateFieldConfig, type DateFieldProps, type DateInputDefaults, type DynamicSectionConfig, DynamicSectionField, type DynamicSectionFieldProps, type EnhancedFormState, FieldArrayBuilder, type FieldArrayConfig, FieldArrayField, type FieldArrayFieldProps, FieldArrayItemBuilder, type FieldBaseProps, type FieldGroup, FileField, type FileFieldConfig, type FileFieldProps, FontPickerField, type FontPickerFieldConfig, type FontPickerFieldProps, type FormConfig, FormField, type FormFieldConfig, FormFieldHelpers, type FormProps, FormProvider, FormStatus, type FormStatusProps, type FormStep, type FormSubmissionState, type FormTestUtils, FormToast, type FormToastProps, type FormValidationError, type HeroHookFormDefaultsConfig, HeroHookFormProvider, type HeroHookFormProviderProps, type InputDefaults, InputField, type InputFieldProps, type RadioFieldConfig, type RadioGroupDefaults, RadioGroupField, type RadioGroupFieldProps, type SelectDefaults, SelectField, type SelectFieldProps, ServerActionForm, type ServerFieldError, type ServerFormError, type SliderDefaults, SliderField, type SliderFieldConfig, type SliderFieldProps, type StringFieldConfig, SubmitButton, type SubmitButtonProps, type SwitchDefaults, SwitchField, type SwitchFieldProps, type TextareaDefaults, TextareaField, type TextareaFieldProps, TypeInferredBuilder, type UseDebouncedValidationOptions, type UseEnhancedFormStateOptions, type UseInferredFormOptions, type ValidationUtils, type WithControl, type WizardFormConfig, ZodForm, type ZodFormConfig, type ZodFormFieldConfig, applyServerErrors, asyncValidation, commonValidations, createAdvancedBuilder, createBasicFormBuilder, createDateSchema, createEmailSchema, createField, createFieldArrayBuilder, createFieldArrayItemBuilder, createFileSchema, createFormTestUtils, createFutureDateSchema, createMaxLengthSchema, createMinLengthSchema, createMockFormData, createMockFormErrors, createNestedPathBuilder, createNumberRangeSchema, createOptimizedFieldHandler, createPasswordSchema, createPastDateSchema, createPhoneSchema, createRequiredCheckboxSchema, createRequiredSchema, createTypeInferredBuilder, createUrlSchema, createZodFormConfig, crossFieldValidation, debounce, deepEqual, defineInferredForm, errorMessages, field, getFieldError, getFormErrors, hasFieldError, hasFormErrors, serverValidation, shallowEqual, simulateFieldInput, simulateFormSubmission, throttle, useDebouncedFieldValidation, useDebouncedValidation, useEnhancedFormState, useFormHelper, useHeroForm, useHeroHookFormDefaults, useInferredForm, useMemoizedCallback, useMemoizedFieldProps, usePerformanceMonitor, useTypeInferredForm, useZodForm, validationPatterns, validationUtils, waitForFormState };
+export { AdvancedFieldBuilder, type ArraySyncOptions, type ArraySyncResult, AutocompleteField, type AutocompleteFieldProps, type AutocompleteOption, type BaseFormFieldConfig, BasicFormBuilder, type BooleanFieldConfig, type ButtonDefaults, type CheckboxDefaults, CheckboxField, type CheckboxFieldProps, CheckboxGroupField, type CheckboxGroupFieldConfig, type CheckboxGroupFieldProps, type CommonFieldDefaults, CommonFields, ConditionalField, type ConditionalFieldConfig, type ConditionalFieldProps, type ConditionalValidation, ConfigurableForm, ContentField, type ContentFieldConfig, type CreateFieldArrayCustomConfigOptions, type CustomFieldConfig, DateField, type DateFieldConfig, type DateFieldProps, type DateInputDefaults, type DynamicSectionConfig, DynamicSectionField, type DynamicSectionFieldProps, type EnhancedFormState, FieldArrayBuilder, type FieldArrayConfig, FieldArrayField, type FieldArrayFieldProps, FieldArrayItemBuilder, type FieldBaseProps, type FieldCreationParams, type FieldGroup, FileField, type FileFieldConfig, type FileFieldProps, FontPickerField, type FontPickerFieldConfig, type FontPickerFieldProps, type FormConfig, FormField, type FormFieldConfig, FormFieldHelpers, type FormFieldType, type FormProps, FormProvider, FormStatus, type FormStatusProps, type FormStep, type FormSubmissionState, type FormTestUtils, FormToast, type FormToastProps, type FormValidationError, type HeroHookFormDefaultsConfig, HeroHookFormProvider, type HeroHookFormProviderProps, type InputDefaults, InputField, type InputFieldProps, type RadioFieldConfig, type RadioGroupDefaults, RadioGroupField, type RadioGroupFieldProps, type SelectDefaults, SelectField, type SelectFieldProps, ServerActionForm, type ServerFieldError, type ServerFormError, SimpleForm, type SimpleFormProps, type SliderDefaults, SliderField, type SliderFieldConfig, type SliderFieldProps, type StringArrayFieldConfig, type StringFieldConfig, SubmitButton, type SubmitButtonProps, type SwitchDefaults, SwitchField, type SwitchFieldProps, type TextareaDefaults, TextareaField, type TextareaFieldProps, TypeInferredBuilder, type UseDebouncedValidationOptions, type UseEnhancedFormStateOptions, type UseInferredFormOptions, type ValidationUtils, type WithControl, type WizardFormConfig, ZodForm, type ZodFormConfig, type ZodFormFieldConfig, applyServerErrors, asyncValidation, commonValidations, createAdvancedBuilder, createBasicFormBuilder, createDateSchema, createEmailSchema, createField, createFieldArrayBuilder, createFieldArrayCustomConfig, createFieldArrayItemBuilder, createFileSchema, createFormTestUtils, createFutureDateSchema, createMaxLengthSchema, createMinLengthSchema, createMockFormData, createMockFormErrors, createNestedPathBuilder, createNumberRangeSchema, createOptimizedFieldHandler, createPasswordSchema, createPastDateSchema, createPhoneSchema, createRequiredCheckboxSchema, createRequiredSchema, createTypeInferredBuilder, createUrlSchema, createZodFormConfig, crossFieldValidation, debounce, deepEqual, defineInferredForm, errorMessages, field, getFieldError, getFormErrors, hasFieldError, hasFormErrors, pathToString, serverValidation, shallowEqual, simulateFieldInput, simulateFormSubmission, syncArrays, throttle, useDebouncedFieldValidation, useDebouncedValidation, useEnhancedFormState, useFormHelper, useHeroForm, useHeroHookFormDefaults, useInferredForm, useMemoizedCallback, useMemoizedFieldProps, usePerformanceMonitor, useTypeInferredForm, useZodForm, validationPatterns, validationUtils, waitForFormState };