@rachelallyson/hero-hook-form 2.1.3 → 2.2.1

package/dist/index.d.ts

@@ -123,7 +123,19 @@ interface DynamicSectionConfig<TFieldValues extends FieldValues> extends BaseFor
     condition: (formData: Partial<TFieldValues>) => boolean;
     fields: ZodFormFieldConfig<TFieldValues>[];
 }
-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>;
+interface ContentFieldConfig<TFieldValues extends FieldValues> {
+    type: "content";
+    name?: Path<TFieldValues>;
+    title?: string;
+    description?: string;
+    render?: (field: {
+        form: UseFormReturn<TFieldValues>;
+        errors: FieldErrors<TFieldValues>;
+        isSubmitting: boolean;
+    }) => 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>;
 interface FormConfig<TFieldValues extends FieldValues> {
     fields: FormFieldConfig<TFieldValues>[];
     layout?: "vertical" | "horizontal" | "grid" | "custom";
@@ -137,7 +149,7 @@ 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">;
+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>;
 interface ZodFormConfig<TFieldValues extends FieldValues> extends UseFormProps<TFieldValues> {
     schema: zod.ZodSchema<TFieldValues>;
     fields: ZodFormFieldConfig<TFieldValues>[];
@@ -216,6 +228,11 @@ interface FormTestUtils<TFieldValues extends FieldValues> {
     triggerValidation: (name?: Path<TFieldValues>) => Promise<boolean>;
 }
 
+/**
+ * Props for the Form component.
+ *
+ * @template T - The form data type
+ */
 interface FormProps$1<T extends FieldValues> {
     className?: string;
     columns?: 1 | 2 | 3;
@@ -233,6 +250,57 @@ interface FormProps$1<T extends FieldValues> {
     title?: string;
     defaultValues?: Partial<T>;
 }
+/**
+ * Base form component for building forms without Zod validation.
+ *
+ * @description
+ * This component provides a flexible form solution using React Hook Form
+ * without requiring Zod schemas. It's useful when you need more control over
+ * validation or want to use React Hook Form's built-in validation rules.
+ *
+ * @template T - The form data type
+ *
+ * @param {FormProps<T>} props - Component props
+ * @param {FormFieldConfig<T>[]} props.fields - Array of field configurations
+ * @param {SubmitHandler<T>} props.onSubmit - Submit handler function
+ * @param {Partial<T>} [props.defaultValues] - Default form values
+ * @param {string} [props.title] - Optional form title
+ * @param {string} [props.subtitle] - Optional form subtitle
+ * @param {"vertical"|"horizontal"|"grid"} [props.layout="vertical"] - Form layout
+ * @param {1|2|3} [props.columns=1] - Number of columns for grid layout
+ * @param {"2"|"4"|"6"|"8"|"lg"} [props.spacing="4"] - Spacing between fields
+ * @param {string} [props.submitButtonText="Submit"] - Submit button text
+ * @param {boolean} [props.showResetButton=false] - Whether to show reset button
+ * @param {(error: FormValidationError) => void} [props.onError] - Error callback
+ * @param {(data: T) => void} [props.onSuccess] - Success callback
+ *
+ * @returns {JSX.Element} The rendered form component
+ *
+ * @example
+ * ```tsx
+ * import { ConfigurableForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * function MyForm() {
+ *   return (
+ *     <ConfigurableForm
+ *       fields={[
+ *         FormFieldHelpers.input("name", "Name"),
+ *         FormFieldHelpers.input("email", "Email", "email"),
+ *       ]}
+ *       defaultValues={{ name: "", email: "" }}
+ *       onSubmit={async (data) => {
+ *         console.log("Submitted:", data);
+ *       }}
+ *       title="Contact Form"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ZodForm} for Zod-integrated form with automatic validation
+ * @see {@link FormFieldHelpers} for field creation helpers
+ * @category Components
+ */
 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> {
@@ -277,11 +345,13 @@ interface ServerActionFormProps<T extends FieldValues> {
     title?: string;
 }
 /**
- * ServerActionForm - A form component compatible with Next.js Server Actions
+ * ServerActionForm - A form component compatible with Next.js Server Actions.
  *
+ * @description
  * This component works with Next.js authentication patterns by using native
  * HTML form submission with Server Actions, while still providing the
- * beautiful HeroUI field components.
+ * beautiful HeroUI field components. It uses React's useActionState hook
+ * to manage form state and handle server responses.
  *
  * **Validation Options:**
  * - **Server-side only (default)**: Form submits directly to Server Action
@@ -292,22 +362,77 @@ interface ServerActionFormProps<T extends FieldValues> {
  * - If your Server Action calls `redirect()`, success messages won't display
  *   (the page navigates away). Use URL params or cookies for success messages
  *   when redirecting.
+ * - Server Actions receive FormData, not JSON, so field values are strings
+ *
+ * @template T - The form data type
+ *
+ * @param {ServerActionFormProps<T>} props - Component props
+ * @param {ServerAction<ActionState, FormData>} props.action - Next.js Server Action function
+ * @param {FormFieldConfig<T>[]} props.fields - Array of field configurations
+ * @param {z.ZodSchema<T>} [props.clientValidationSchema] - Optional Zod schema for client-side validation
+ * @param {Partial<T>} [props.defaultValues] - Default form values
+ * @param {ActionState} [props.initialState] - Initial state for useActionState
+ * @param {string} [props.title] - Optional form title
+ * @param {string} [props.subtitle] - Optional form subtitle
+ * @param {"vertical"|"horizontal"|"grid"} [props.layout="vertical"] - Form layout style
+ * @param {1|2|3} [props.columns=1] - Number of columns for grid layout
+ * @param {"2"|"4"|"6"|"8"|"lg"} [props.spacing="4"] - Spacing between form fields
+ * @param {string} [props.submitButtonText="Submit"] - Text for the submit button
+ * @param {boolean} [props.showResetButton=false] - Whether to show a reset button
+ * @param {(error: {...}) => void} [props.onError] - Error callback
+ * @param {(data: FormData) => void} [props.onSuccess] - Success callback
+ *
+ * @returns {JSX.Element} The rendered form component
  *
  * @example
+ * Server-side only validation:
  * ```tsx
- * // Server-side only validation
+ * import { ServerActionForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ * import { signup } from "@/app/actions/auth";
+ *
  * <ServerActionForm
  *   action={signup}
- *   fields={[...]}
+ *   fields={[
+ *     FormFieldHelpers.input("name", "Name"),
+ *     FormFieldHelpers.input("email", "Email", "email"),
+ *     FormFieldHelpers.input("password", "Password", "password"),
+ *   ]}
  * />
+ * ```
+ *
+ * @example
+ * Client + Server validation:
+ * ```tsx
+ * import { ServerActionForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ * import { signup } from "@/app/actions/auth";
+ * import { z } from "zod";
+ *
+ * const signupSchema = z.object({
+ *   name: z.string().min(2),
+ *   email: z.string().email(),
+ *   password: z.string().min(8),
+ * });
  *
- * // Client + Server validation
  * <ServerActionForm
  *   action={signup}
  *   clientValidationSchema={signupSchema}
- *   fields={[...]}
+ *   fields={[
+ *     FormFieldHelpers.input("name", "Name"),
+ *     FormFieldHelpers.input("email", "Email", "email"),
+ *     FormFieldHelpers.input("password", "Password", "password"),
+ *   ]}
+ *   onError={(error) => {
+ *     console.error("Form errors:", error.errors);
+ *   }}
+ *   onSuccess={(data) => {
+ *     console.log("Form submitted:", data);
+ *   }}
  * />
  * ```
+ *
+ * @see {@link ZodForm} for client-side only forms with Zod validation
+ * @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;
 
@@ -341,10 +466,63 @@ type FontPickerFieldProps<TFieldValues extends FieldValues, TValue extends strin
 };
 declare function FontPickerField<TFieldValues extends FieldValues, TValue extends string = string>(props: FontPickerFieldProps<TFieldValues, TValue>): React$1.JSX.Element;
 
+/**
+ * Props for the InputField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 type InputFieldProps<TFieldValues extends FieldValues> = FieldBaseProps<TFieldValues, string> & WithControl<TFieldValues> & {
     inputProps?: Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
     transform?: (value: string) => string;
 };
+/**
+ * Input field component for text, email, password, tel, and number inputs.
+ *
+ * @description
+ * A memoized input field component that integrates with React Hook Form
+ * and HeroUI Input component. Supports all standard input types and
+ * includes automatic validation error display.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {InputFieldProps<TFieldValues>} props - Component props
+ * @param {Path<TFieldValues>} props.name - Field name path
+ * @param {string} [props.label] - Field label
+ * @param {string} [props.description] - Field description/help text
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {boolean} [props.isDisabled] - Whether field is disabled
+ * @param {RegisterOptions<TFieldValues>} [props.rules] - Validation rules
+ * @param {Partial<InputProps>} [props.inputProps] - Additional Input component props
+ * @param {(value: string) => string} [props.transform] - Value transformation function
+ *
+ * @returns {JSX.Element} The rendered input field
+ *
+ * @example
+ * ```tsx
+ * import { InputField } from "@rachelallyson/hero-hook-form";
+ * import { useForm, Controller } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const { control } = useForm();
+ *
+ *   return (
+ *     <InputField
+ *       name="email"
+ *       label="Email Address"
+ *       description="Enter your email address"
+ *       control={control}
+ *       inputProps={{
+ *         type: "email",
+ *         placeholder: "you@example.com",
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link FormFieldHelpers.input} for helper function to create input field config
+ * @category Fields
+ */
 declare const InputField: <TFieldValues extends FieldValues>(props: InputFieldProps<TFieldValues>) => React$1.JSX.Element;
 
 interface RadioOption<TValue extends string | number> {
@@ -388,6 +566,11 @@ type TextareaFieldProps<TFieldValues extends FieldValues> = FieldBaseProps<TFiel
 };
 declare function TextareaField<TFieldValues extends FieldValues>(props: TextareaFieldProps<TFieldValues>): React$1.JSX.Element;
 
+/**
+ * Options for the useFormHelper hook.
+ *
+ * @template T - The form data type
+ */
 interface UseFormHelperOptions<T extends FieldValues> {
     onError?: (error: FormValidationError) => void;
     onSubmit: SubmitHandler<T>;
@@ -395,6 +578,86 @@ interface UseFormHelperOptions<T extends FieldValues> {
     defaultValues?: Partial<T>;
     methods?: UseFormReturn<T>;
 }
+/**
+ * Hook for managing form state with enhanced features.
+ *
+ * @description
+ * Provides form state management with loading states, error handling,
+ * and submission tracking. Automatically handles form validation and
+ * provides callbacks for success and error cases. This hook wraps
+ * React Hook Form's useForm with additional state management.
+ *
+ * @template T - The form data type
+ *
+ * @param {UseFormHelperOptions<T>} options - Hook options
+ * @param {Partial<T>} [options.defaultValues] - Default form values
+ * @param {UseFormReturn<T>} [options.methods] - Optional existing form instance
+ * @param {SubmitHandler<T>} options.onSubmit - Submit handler function
+ * @param {(error: FormValidationError) => void} [options.onError] - Error handler callback
+ * @param {(data: T) => void} [options.onSuccess] - Success handler callback
+ *
+ * @returns {Object} Form helper with state and methods
+ * @returns {UseFormReturn<T>} form - React Hook Form instance
+ * @returns {() => Promise<void>} handleSubmit - Submit handler function
+ * @returns {() => void} resetForm - Reset form function
+ * @returns {boolean} isSubmitting - Whether form is currently submitting
+ * @returns {boolean} isSubmitted - Whether form has been submitted
+ * @returns {boolean} isSuccess - Whether last submission was successful
+ * @returns {string|undefined} error - Error message if submission failed
+ * @returns {FormSubmissionState} submissionState - Complete submission state object
+ *
+ * @example
+ * ```tsx
+ * import { useFormHelper } from "@rachelallyson/hero-hook-form";
+ *
+ * function MyForm() {
+ *   const { form, handleSubmit, isSubmitting, error } = useFormHelper({
+ *     defaultValues: { email: "", name: "" },
+ *     onSubmit: async (data) => {
+ *       await submitToServer(data);
+ *     },
+ *     onError: (error) => {
+ *       console.error("Validation errors:", error);
+ *     },
+ *     onSuccess: (data) => {
+ *       console.log("Success:", data);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <form onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}>
+ *       <button disabled={isSubmitting}>
+ *         {isSubmitting ? "Submitting..." : "Submit"}
+ *       </button>
+ *       {error && <div className="error">{error}</div>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Using with existing form instance:
+ * ```tsx
+ * import { useForm } from "react-hook-form";
+ * import { useFormHelper } from "@rachelallyson/hero-hook-form";
+ *
+ * function MyForm() {
+ *   const existingForm = useForm({ defaultValues: { email: "" } });
+ *   const { handleSubmit, isSubmitting } = useFormHelper({
+ *     methods: existingForm,
+ *     onSubmit: async (data) => {
+ *       await submitToServer(data);
+ *     },
+ *   });
+ *
+ *   // Use existingForm and handleSubmit together
+ * }
+ * ```
+ *
+ * @see {@link useHeroForm} for alternative hook with different API
+ * @see {@link ConfigurableForm} for component that uses this hook
+ * @category Hooks
+ */
 declare function useFormHelper<T extends FieldValues>({ defaultValues, methods, onError, onSubmit, onSuccess, }: UseFormHelperOptions<T>): {
     error: string | undefined;
     form: UseFormReturn<T>;
@@ -407,11 +670,19 @@ declare function useFormHelper<T extends FieldValues>({ defaultValues, methods,
 };
 
 /**
- * Enhanced hook that provides both form methods and styling defaults
+ * Enhanced hook that provides both form methods and styling defaults.
  *
+ * @description
  * This hook combines React Hook Form's useFormContext with Hero Hook Form's
  * styling defaults, giving you access to both form functionality and
- * component styling in one convenient hook.
+ * component styling in one convenient hook. Must be used within a FormProvider
+ * context (provided by ZodForm, ConfigurableForm, or manual FormProvider).
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @returns {Object} Enhanced form object with all React Hook Form methods and Hero Hook Form defaults
+ * @returns {UseFormReturn<TFieldValues>} All React Hook Form methods (formState, getValues, setValue, etc.)
+ * @returns {HeroHookFormDefaultsConfig} defaults - Hero Hook Form styling defaults
  *
  * @example
  * ```tsx
@@ -433,6 +704,10 @@ declare function useFormHelper<T extends FieldValues>({ defaultValues, methods,
  *   const buttonDefaults = defaults.submitButton;
  * }
  * ```
+ *
+ * @see {@link useFormHelper} for form state management with callbacks
+ * @see {@link useFormContext} from React Hook Form for base functionality
+ * @category Hooks
  */
 declare function useHeroForm<TFieldValues extends FieldValues>(): {
     defaults: Required<Pick<HeroHookFormDefaultsConfig, "input" | "textarea" | "select" | "switch" | "radioGroup" | "checkbox" | "slider" | "dateInput" | "submitButton">>;
@@ -507,6 +782,11 @@ interface FormProps<TFieldValues extends FieldValues> {
 }
 declare function FormProvider<TFieldValues extends FieldValues>(props: FormProps<TFieldValues>): React$1.JSX.Element;
 
+/**
+ * Enhanced form state with submission tracking and error management.
+ *
+ * @template T - The form data type
+ */
 interface EnhancedFormState<T extends FieldValues> {
     status: "idle" | "submitting" | "success" | "error";
     isSubmitting: boolean;
@@ -522,6 +802,11 @@ interface EnhancedFormState<T extends FieldValues> {
     handleError: (error: string) => void;
     reset: () => void;
 }
+/**
+ * Options for the useEnhancedFormState hook.
+ *
+ * @template T - The form data type
+ */
 interface UseEnhancedFormStateOptions<T extends FieldValues> {
     onSuccess?: (data: T) => void;
     onError?: (error: string) => void;
@@ -530,6 +815,81 @@ interface UseEnhancedFormStateOptions<T extends FieldValues> {
     autoReset?: boolean;
     resetDelay?: number;
 }
+/**
+ * Hook for managing enhanced form state with submission tracking.
+ *
+ * @description
+ * Provides advanced form state management including submission status,
+ * error tracking, touched/dirty field tracking, and automatic reset
+ * functionality. Useful for building forms with rich UI feedback.
+ *
+ * @template T - The form data type
+ *
+ * @param {UseFormReturn<T>} form - React Hook Form instance
+ * @param {UseEnhancedFormStateOptions<T>} [options] - Configuration options
+ * @param {(data: T) => void} [options.onSuccess] - Success callback
+ * @param {(error: string) => void} [options.onError] - Error callback
+ * @param {string} [options.successMessage] - Custom success message
+ * @param {string} [options.errorMessage] - Custom error message
+ * @param {boolean} [options.autoReset=true] - Automatically reset after success
+ * @param {number} [options.resetDelay=3000] - Delay before auto-reset (ms)
+ *
+ * @returns {EnhancedFormState<T>} Enhanced form state object
+ * @returns {"idle"|"submitting"|"success"|"error"} status - Current submission status
+ * @returns {boolean} isSubmitting - Whether form is currently submitting
+ * @returns {boolean} isSuccess - Whether last submission was successful
+ * @returns {boolean} isError - Whether last submission had an error
+ * @returns {string|undefined} error - Error message if submission failed
+ * @returns {T|undefined} submittedData - Data from last successful submission
+ * @returns {Set<Path<T>>} touchedFields - Set of touched field paths
+ * @returns {Set<Path<T>>} dirtyFields - Set of dirty field paths
+ * @returns {boolean} hasErrors - Whether form has validation errors
+ * @returns {number} errorCount - Number of validation errors
+ * @returns {(data: T) => void} handleSuccess - Function to mark submission as successful
+ * @returns {(error: string) => void} handleError - Function to mark submission as failed
+ * @returns {() => void} reset - Function to reset state to idle
+ *
+ * @example
+ * ```tsx
+ * import { useEnhancedFormState } from "@rachelallyson/hero-hook-form";
+ * import { useForm } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const form = useForm();
+ *   const state = useEnhancedFormState(form, {
+ *     onSuccess: (data) => {
+ *       console.log("Success:", data);
+ *     },
+ *     onError: (error) => {
+ *       console.error("Error:", error);
+ *     },
+ *     autoReset: true,
+ *     resetDelay: 3000,
+ *   });
+ *
+ *   const handleSubmit = async (data) => {
+ *     try {
+ *       await submitToServer(data);
+ *       state.handleSuccess(data);
+ *     } catch (error) {
+ *       state.handleError(error.message);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={form.handleSubmit(handleSubmit)}>
+ *       {/* form fields *\/}
+ *       {state.isSubmitting && <div>Submitting...</div>}
+ *       {state.isSuccess && <div>Success!</div>}
+ *       {state.error && <div>Error: {state.error}</div>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link ZodForm} which uses this hook internally
+ * @category Hooks
+ */
 declare function useEnhancedFormState<T extends FieldValues>(form: UseFormReturn<T>, options?: UseEnhancedFormStateOptions<T>): EnhancedFormState<T>;
 
 interface SubmitButtonProps {
@@ -543,15 +903,99 @@ interface SubmitButtonProps {
 }
 declare function SubmitButton(props: SubmitButtonProps): React$1.JSX.Element;
 
+/**
+ * Server field error structure.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface ServerFieldError<TFieldValues extends FieldValues> {
     path: Path<TFieldValues>;
     message: string;
     type?: string;
 }
+/**
+ * Server form error structure containing field errors.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface ServerFormError<TFieldValues extends FieldValues> {
     message?: string;
     fieldErrors?: readonly ServerFieldError<TFieldValues>[];
 }
+/**
+ * Applies server-side validation errors to a React Hook Form instance.
+ *
+ * @description
+ * Maps server-returned field errors to React Hook Form's error state.
+ * Useful for displaying validation errors from API responses. This function
+ * iterates through the field errors and sets them on the form using
+ * React Hook Form's setError function.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {UseFormSetError<TFieldValues>} setError - React Hook Form's setError function
+ * @param {ServerFormError<TFieldValues>} serverError - Server error containing field errors
+ *
+ * @example
+ * ```tsx
+ * import { applyServerErrors } from "@rachelallyson/hero-hook-form";
+ * import { useForm } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const form = useForm();
+ *
+ *   const handleSubmit = async (data) => {
+ *     try {
+ *       const response = await fetch("/api/submit", {
+ *         method: "POST",
+ *         body: JSON.stringify(data),
+ *       });
+ *
+ *       if (!response.ok) {
+ *         const errorData = await response.json();
+ *         applyServerErrors(form.setError, errorData);
+ *       }
+ *     } catch (error) {
+ *       console.error("Error:", error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <form onSubmit={form.handleSubmit(handleSubmit)}>
+ *       {/* form fields go here *\/}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With ZodForm error handling:
+ * ```tsx
+ * import { ZodForm, applyServerErrors } from "@rachelallyson/hero-hook-form";
+ *
+ * function MyForm() {
+ *   const form = useForm();
+ *
+ *   const handleSubmit = async (data) => {
+ *     try {
+ *       await submitToServer(data);
+ *     } catch (error) {
+ *       if (error.fieldErrors) {
+ *         applyServerErrors(form.setError, {
+ *           fieldErrors: error.fieldErrors,
+ *         });
+ *       }
+ *     }
+ *   };
+ *
+ *   return <ZodForm config={{ schema, fields }} onSubmit={handleSubmit} />;
+ * }
+ * ```
+ *
+ * @see {@link ServerFormError} for error structure
+ * @see {@link ServerFieldError} for field error structure
+ * @category Utilities
+ */
 declare function applyServerErrors<TFieldValues extends FieldValues>(setError: UseFormSetError<TFieldValues>, serverError: ServerFormError<TFieldValues>): void;
 
 /**
@@ -700,6 +1144,11 @@ declare const commonValidations: {
     url: z.ZodString;
 };
 
+/**
+ * Props for the ZodForm component.
+ *
+ * @template T - The form data type inferred from the Zod schema
+ */
 interface ZodFormProps<T extends FieldValues> {
     className?: string;
     columns?: 1 | 2 | 3;
@@ -724,6 +1173,101 @@ interface ZodFormProps<T extends FieldValues> {
         values: T;
     }) => React$1.ReactNode;
 }
+/**
+ * ZodForm component for building type-safe forms with Zod validation.
+ *
+ * @description
+ * This component provides a complete form solution with automatic validation,
+ * error handling, and type safety. It integrates React Hook Form with Zod
+ * schemas and HeroUI components. The form automatically validates inputs based
+ * on the provided Zod schema and displays error messages inline.
+ *
+ * @template T - The form data type inferred from the Zod schema
+ *
+ * @param {ZodFormProps<T>} props - Component props
+ * @param {ZodFormConfig<T>} props.config - Form configuration with schema and fields
+ * @param {SubmitHandler<T>} props.onSubmit - Submit handler function called with validated data
+ * @param {string} [props.title] - Optional form title displayed above the form
+ * @param {string} [props.subtitle] - Optional form subtitle displayed below the title
+ * @param {"vertical"|"horizontal"|"grid"} [props.layout="vertical"] - Form layout style
+ * @param {1|2|3} [props.columns=1] - Number of columns for grid layout (only applies when layout="grid")
+ * @param {"2"|"4"|"6"|"8"|"lg"} [props.spacing="4"] - Spacing between form fields
+ * @param {string} [props.submitButtonText="Submit"] - Text for the submit button
+ * @param {boolean} [props.showResetButton=false] - Whether to show a reset button
+ * @param {string} [props.resetButtonText="Reset"] - Text for the reset button
+ * @param {(error: FormValidationError) => void} [props.onError] - Error callback for validation errors
+ * @param {(data: T) => void} [props.onSuccess] - Success callback called after successful submission
+ * @param {(formState: {...}) => React.ReactNode} [props.render] - Custom render function for advanced use cases
+ *
+ * @returns {JSX.Element} The rendered form component with validation and error handling
+ *
+ * @example
+ * ```tsx
+ * import { ZodForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({
+ *   email: z.string().email("Please enter a valid email"),
+ *   name: z.string().min(2, "Name must be at least 2 characters"),
+ *   message: z.string().min(10, "Message must be at least 10 characters"),
+ * });
+ *
+ * function ContactForm() {
+ *   const handleSubmit = async (data) => {
+ *     console.log("Form submitted:", data);
+ *     // Handle form submission (e.g., API call)
+ *   };
+ *
+ *   return (
+ *     <ZodForm
+ *       config={{
+ *         schema,
+ *         fields: [
+ *           FormFieldHelpers.input("name", "Name"),
+ *           FormFieldHelpers.input("email", "Email", "email"),
+ *           FormFieldHelpers.textarea("message", "Message"),
+ *         ],
+ *       }}
+ *       onSubmit={handleSubmit}
+ *       title="Contact Us"
+ *       subtitle="Send us a message and we'll get back to you"
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Grid layout with multiple columns:
+ * ```tsx
+ * <ZodForm
+ *   config={{ schema, fields }}
+ *   layout="grid"
+ *   columns={2}
+ *   spacing="6"
+ * />
+ * ```
+ *
+ * @example
+ * Custom render function for advanced control:
+ * ```tsx
+ * <ZodForm
+ *   config={{ schema, fields }}
+ *   onSubmit={handleSubmit}
+ *   render={({ form, isSubmitting, errors, values }) => (
+ *     <div>
+ *       <button disabled={isSubmitting}>
+ *         {isSubmitting ? "Submitting..." : "Submit"}
+ *       </button>
+ *     </div>
+ *   )}
+ * />
+ * ```
+ *
+ * @see {@link Form} for the base form component without Zod
+ * @see {@link FormFieldHelpers} for field creation helpers
+ * @see {@link createBasicFormBuilder} for builder pattern alternative
+ * @category Components
+ */
 declare function ZodForm<T extends FieldValues>({ className, columns, config, layout, onError, onSubmit, onSuccess, render, resetButtonText, showResetButton, spacing, submitButtonProps, submitButtonText, subtitle, title, }: ZodFormProps<T>): React$1.JSX.Element;
 
 /**
@@ -736,8 +1280,34 @@ declare function useZodForm<TFieldValues extends FieldValues>(config: ZodFormCon
 declare function createZodFormConfig<TFieldValues extends FieldValues>(schema: z.ZodSchema<TFieldValues>, fields: ZodFormFieldConfig<TFieldValues>[], defaultValues?: Partial<TFieldValues>): ZodFormConfig<TFieldValues>;
 
 /**
- * Basic form field builder that eliminates "as const" assertions
- * Focuses on the most common use cases
+ * Basic form field builder for creating form field configurations.
+ *
+ * @description
+ * Provides a fluent API for building form field configurations. This builder
+ * focuses on the most common use cases and eliminates the need for "as const"
+ * assertions. Use this for simple forms with standard field types.
+ *
+ * @template T - The form data type
+ *
+ * @example
+ * ```tsx
+ * import { createBasicFormBuilder } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = createBasicFormBuilder()
+ *   .input("name", "Name")
+ *   .input("email", "Email", "email")
+ *   .textarea("message", "Message")
+ *   .select("country", "Country", [
+ *     { label: "US", value: "us" },
+ *     { label: "CA", value: "ca" },
+ *   ])
+ *   .checkbox("newsletter", "Subscribe to newsletter")
+ *   .build();
+ * ```
+ *
+ * @see {@link createAdvancedBuilder} for more advanced features
+ * @see {@link FormFieldHelpers} for helper function alternative
+ * @category Builders
  */
 declare class BasicFormBuilder<T extends FieldValues> {
     private fields;
@@ -760,6 +1330,18 @@ declare class BasicFormBuilder<T extends FieldValues> {
      * Add a checkbox field
      */
     checkbox(name: Path<T>, label: string): this;
+    /**
+     * Add a content field for headers, questions, or custom content between fields
+     */
+    content(title?: string | null, description?: string | null, options?: {
+        render?: (field: {
+            form: any;
+            errors: any;
+            isSubmitting: boolean;
+        }) => React$1.ReactNode;
+        className?: string;
+        name?: Path<T>;
+    }): this;
     /**
      * Add a switch field
      */
@@ -770,17 +1352,97 @@ declare class BasicFormBuilder<T extends FieldValues> {
     build(): ZodFormFieldConfig<T>[];
 }
 /**
- * Create a new simple form field builder
+ * Creates a basic form builder for simple form construction.
+ *
+ * @description
+ * Provides a fluent API for building form field configurations. Best for
+ * simple forms with standard field types. Returns a builder instance with
+ * chainable methods for adding fields.
+ *
+ * @template T - The form data type
+ *
+ * @returns {BasicFormBuilder<T>} Builder instance with chainable methods
+ *
+ * @example
+ * ```tsx
+ * import { createBasicFormBuilder } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = createBasicFormBuilder()
+ *   .input("name", "Name")
+ *   .input("email", "Email", "email")
+ *   .textarea("message", "Message")
+ *   .select("country", "Country", [
+ *     { label: "US", value: "us" },
+ *     { label: "CA", value: "ca" },
+ *   ])
+ *   .checkbox("newsletter", "Subscribe to newsletter")
+ *   .build();
+ *
+ * // Use with ZodForm
+ * <ZodForm config={{ schema, fields }} onSubmit={handleSubmit} />
+ * ```
+ *
+ * @see {@link createAdvancedBuilder} for more advanced features
+ * @see {@link FormFieldHelpers} for helper function alternative
+ * @see {@link defineInferredForm} for type-inferred forms
+ * @category Builders
  */
 declare function createBasicFormBuilder<T extends FieldValues>(): BasicFormBuilder<T>;
 /**
- * Simple helper functions for common field types
+ * Helper functions for creating form field configurations.
+ *
+ * @description
+ * Simple helper functions for common field types. This is the recommended
+ * approach for most use cases as it's straightforward and doesn't require
+ * method chaining. Each helper returns a field configuration object.
+ *
+ * @example
+ * ```tsx
+ * import { FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.input("name", "Name"),
+ *   FormFieldHelpers.input("email", "Email", "email"),
+ *   FormFieldHelpers.textarea("message", "Message"),
+ *   FormFieldHelpers.select("country", "Country", [
+ *     { label: "US", value: "us" },
+ *     { label: "CA", value: "ca" },
+ *   ]),
+ *   FormFieldHelpers.checkbox("newsletter", "Subscribe to newsletter"),
+ * ];
+ * ```
+ *
+ * @see {@link createBasicFormBuilder} for builder pattern alternative
+ * @category Builders
  */
 declare const FormFieldHelpers: {
     /**
      * Create a checkbox field
      */
     checkbox: <T extends FieldValues>(name: Path<T>, label: string) => ZodFormFieldConfig<T>;
+    /**
+     * Create a content field for headers, questions, or custom content between fields
+     *
+     * @example
+     * ```tsx
+     * // Simple header
+     * FormFieldHelpers.content("Personal Information", "Please provide your details")
+     *
+     * // Custom render
+     * FormFieldHelpers.content(null, null, {
+     *   render: () => <div>Custom content</div>
+     * })
+     * ```
+     */
+    content: <T extends FieldValues>(title?: string | null, description?: string | null, options?: {
+        render?: (field: {
+            form: any;
+            errors: any;
+            isSubmitting: boolean;
+        }) => React$1.ReactNode;
+        className?: string;
+        name?: Path<T>;
+    }) => ContentFieldConfig<T>;
     /**
      * Create a date field
      */
@@ -1189,15 +1851,115 @@ declare class FieldTemplateBuilder<T extends FieldValues> {
  */
 declare function createNestedPathBuilder<T extends FieldValues>(): NestedPathBuilder<T>;
 
+/**
+ * Options for the useDebouncedValidation hook.
+ */
 interface UseDebouncedValidationOptions {
     delay?: number;
     fields?: string[];
     enabled?: boolean;
 }
+/**
+ * Hook for debouncing form validation to improve performance.
+ *
+ * @description
+ * Delays validation until the user stops typing, reducing unnecessary
+ * validation calls and improving form performance. Useful for forms with
+ * expensive validation logic or many fields.
+ *
+ * @template T - The form data type
+ *
+ * @param {UseFormReturn<T>} form - React Hook Form instance
+ * @param {UseDebouncedValidationOptions} [options] - Configuration options
+ * @param {number} [options.delay=300] - Delay in milliseconds before validation
+ * @param {string[]} [options.fields] - Specific fields to watch (if not provided, watches all)
+ * @param {boolean} [options.enabled=true] - Whether debouncing is enabled
+ *
+ * @returns {Object} Debounced validation utilities
+ * @returns {() => void} debouncedTrigger - Function to trigger debounced validation
+ * @returns {boolean} isDebouncing - Whether validation is currently debouncing
+ *
+ * @example
+ * ```tsx
+ * import { useDebouncedValidation } from "@rachelallyson/hero-hook-form";
+ * import { useForm } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const form = useForm();
+ *   const { debouncedTrigger, isDebouncing } = useDebouncedValidation(form, {
+ *     delay: 500,
+ *     fields: ["email", "username"], // Only watch these fields
+ *   });
+ *
+ *   return (
+ *     <form>
+ *       <input
+ *         {...form.register("email")}
+ *         onChange={(e) => {
+ *           form.setValue("email", e.target.value);
+ *           debouncedTrigger();
+ *         }}
+ *       />
+ *       {isDebouncing && <span>Validating...</span>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useDebouncedFieldValidation} for single field debouncing
+ * @category Hooks
+ */
 declare function useDebouncedValidation<T extends Record<string, any>>(form: UseFormReturn<T>, options?: UseDebouncedValidationOptions): {
     debouncedTrigger: () => void;
     isDebouncing: boolean;
 };
+/**
+ * Hook for debouncing validation of a single field.
+ *
+ * @description
+ * Similar to useDebouncedValidation but optimized for a single field.
+ * Automatically triggers validation when the specified field changes.
+ *
+ * @template T - The form data type
+ *
+ * @param {UseFormReturn<T>} form - React Hook Form instance
+ * @param {keyof T} fieldName - Name of the field to debounce
+ * @param {Object} [options] - Configuration options
+ * @param {number} [options.delay=300] - Delay in milliseconds before validation
+ * @param {boolean} [options.enabled=true] - Whether debouncing is enabled
+ *
+ * @returns {Object} Debounced field validation utilities
+ * @returns {() => void} debouncedFieldTrigger - Function to trigger debounced validation for this field
+ * @returns {boolean} isDebouncing - Whether validation is currently debouncing
+ *
+ * @example
+ * ```tsx
+ * import { useDebouncedFieldValidation } from "@rachelallyson/hero-hook-form";
+ * import { useForm } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const form = useForm();
+ *   const { debouncedFieldTrigger, isDebouncing } = useDebouncedFieldValidation(
+ *     form,
+ *     "email",
+ *     { delay: 500 }
+ *   );
+ *
+ *   return (
+ *     <input
+ *       {...form.register("email")}
+ *       onChange={(e) => {
+ *         form.setValue("email", e.target.value);
+ *         debouncedFieldTrigger();
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useDebouncedValidation} for multiple fields
+ * @category Hooks
+ */
 declare function useDebouncedFieldValidation<T extends Record<string, any>>(form: UseFormReturn<T>, fieldName: keyof T, options?: {
     delay?: number;
     enabled?: boolean;
@@ -1206,6 +1968,11 @@ declare function useDebouncedFieldValidation<T extends Record<string, any>>(form
     isDebouncing: boolean;
 };
 
+/**
+ * Options for the useInferredForm hook.
+ *
+ * @template T - The form data type
+ */
 interface UseInferredFormOptions<T extends FieldValues> {
     defaultValues?: Partial<T>;
     mode?: "onChange" | "onBlur" | "onSubmit" | "onTouched" | "all";
@@ -1214,33 +1981,323 @@ interface UseInferredFormOptions<T extends FieldValues> {
     shouldUnregister?: boolean;
     delayError?: number;
 }
+/**
+ * Hook for creating a form instance from an inferred form configuration.
+ *
+ * @description
+ * Creates a React Hook Form instance with Zod validation resolver
+ * from a type-inferred form configuration. Automatically sets up
+ * validation based on the provided schema and fields.
+ *
+ * @template T - The form data type
+ *
+ * @param {any} schema - Zod schema for validation
+ * @param {ZodFormFieldConfig<T>[]} fields - Field configurations
+ * @param {UseInferredFormOptions<T>} [options] - Form options
+ * @param {Partial<T>} [options.defaultValues] - Default form values
+ * @param {"onChange"|"onBlur"|"onSubmit"|"onTouched"|"all"} [options.mode="onChange"] - Validation mode
+ * @param {"onChange"|"onBlur"|"onSubmit"} [options.reValidateMode="onChange"] - Re-validation mode
+ * @param {boolean} [options.shouldFocusError=true] - Focus first error field
+ * @param {boolean} [options.shouldUnregister=false] - Unregister fields on unmount
+ * @param {number} [options.delayError=0] - Delay before showing errors
+ *
+ * @returns {UseFormReturn<T>} React Hook Form instance
+ *
+ * @example
+ * ```tsx
+ * import { useInferredForm, defineInferredForm, field } from "@rachelallyson/hero-hook-form";
+ *
+ * const formConfig = defineInferredForm({
+ *   name: field.string("Name").min(2),
+ *   email: field.email("Email"),
+ * });
+ *
+ * function MyForm() {
+ *   const form = useInferredForm(
+ *     formConfig.schema,
+ *     formConfig.fields,
+ *     { mode: "onBlur" }
+ *   );
+ *
+ *   return (
+ *     <form onSubmit={form.handleSubmit(handleSubmit)}>
+ *       {/* form fields *\/}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link defineInferredForm} for creating type-inferred form configurations
+ * @see {@link useTypeInferredForm} for alternative API
+ * @category Hooks
+ */
 declare function useInferredForm<T extends FieldValues>(schema: any, fields: ZodFormFieldConfig<T>[], options?: UseInferredFormOptions<T>): UseFormReturn<T>;
 /**
- * Hook that works with type-inferred forms
+ * Hook that works with type-inferred form configurations.
+ *
+ * @description
+ * Alternative API for useInferredForm that accepts a form configuration
+ * object instead of separate schema and fields parameters. Useful when
+ * working with defineInferredForm results.
+ *
+ * @template T - The form data type
+ *
+ * @param {Object} formConfig - Form configuration object
+ * @param {any} formConfig.schema - Zod schema for validation
+ * @param {ZodFormFieldConfig<T>[]} formConfig.fields - Field configurations
+ * @param {UseInferredFormOptions<T>} [options] - Form options
+ *
+ * @returns {UseFormReturn<T>} React Hook Form instance
+ *
+ * @example
+ * ```tsx
+ * import { useTypeInferredForm, defineInferredForm, field } from "@rachelallyson/hero-hook-form";
+ *
+ * const formConfig = defineInferredForm({
+ *   name: field.string("Name").min(2),
+ *   email: field.email("Email"),
+ * });
+ *
+ * function MyForm() {
+ *   const form = useTypeInferredForm(formConfig);
+ *
+ *   return (
+ *     <form onSubmit={form.handleSubmit(handleSubmit)}>
+ *       {/* form fields *\/}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link useInferredForm} for direct schema/fields API
+ * @see {@link defineInferredForm} for creating type-inferred form configurations
+ * @category Hooks
  */
 declare function useTypeInferredForm<T extends FieldValues>(formConfig: {
     schema: any;
     fields: ZodFormFieldConfig<T>[];
 }, options?: UseInferredFormOptions<T>): UseFormReturn<T>;
 
+/**
+ * Props for the ConditionalField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface ConditionalFieldProps<TFieldValues extends FieldValues> {
     config: ConditionalFieldConfig<TFieldValues>;
     control: Control<TFieldValues>;
     className?: string;
 }
+/**
+ * Conditional field component that shows/hides fields based on form values.
+ *
+ * @description
+ * Renders a field only when a condition function returns true based on
+ * current form values. Useful for creating dynamic forms that adapt to
+ * user input. The field is completely removed from the DOM when hidden.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {ConditionalFieldProps<TFieldValues>} props - Component props
+ * @param {ConditionalFieldConfig<TFieldValues>} props.config - Conditional field configuration
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element|null} The rendered field or null if condition is not met
+ *
+ * @example
+ * ```tsx
+ * import { ConditionalField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.checkbox("hasPhone", "I have a phone number"),
+ *   ConditionalField({
+ *     config: {
+ *       name: "phone",
+ *       condition: (values) => values.hasPhone === true,
+ *       field: FormFieldHelpers.input("phone", "Phone Number", "tel"),
+ *     },
+ *     control: form.control,
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Multiple conditions:
+ * ```tsx
+ * ConditionalField({
+ *   config: {
+ *     name: "businessDetails",
+ *     condition: (values) =>
+ *       values.userType === "business" && values.isRegistered === true,
+ *     field: FormFieldHelpers.input("taxId", "Tax ID"),
+ *   },
+ *   control: form.control,
+ * }),
+ * ```
+ *
+ * @see {@link DynamicSectionField} for grouping multiple conditional fields
+ * @see {@link FieldArrayField} for repeating fields
+ * @category Fields
+ */
 declare function ConditionalField<TFieldValues extends FieldValues>({ className, config, control, }: ConditionalFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
+interface ContentFieldProps<TFieldValues extends FieldValues> {
+    config: ContentFieldConfig<TFieldValues>;
+    form: UseFormReturn<TFieldValues>;
+    submissionState: FormSubmissionState;
+}
+declare function ContentField<TFieldValues extends FieldValues>({ config, form, submissionState, }: ContentFieldProps<TFieldValues>): React$1.JSX.Element;
+
+/**
+ * Props for the FieldArrayField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
     config: FieldArrayConfig<TFieldValues>;
     className?: string;
 }
+/**
+ * Field array component for dynamic repeating field groups.
+ *
+ * @description
+ * 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.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {FieldArrayFieldProps<TFieldValues>} props - Component props
+ * @param {FieldArrayConfig<TFieldValues>} props.config - Field array configuration
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element} The rendered field array with add/remove controls
+ *
+ * @example
+ * ```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",
+ *     },
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * With validation:
+ * ```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"),
+ * });
+ * ```
+ *
+ * @see {@link ConditionalField} for conditional single fields
+ * @see {@link DynamicSectionField} for conditional field groups
+ * @category Fields
+ */
 declare function FieldArrayField<TFieldValues extends FieldValues>({ className, config, }: FieldArrayFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
+/**
+ * Props for the DynamicSectionField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface DynamicSectionFieldProps<TFieldValues extends FieldValues> {
     config: DynamicSectionConfig<TFieldValues>;
     control: Control<TFieldValues>;
     className?: string;
 }
+/**
+ * Dynamic section component that shows/hides groups of fields based on form values.
+ *
+ * @description
+ * Similar to ConditionalField but for groups of fields. Renders a section
+ * with title, description, and multiple fields when a condition is met.
+ * Useful for creating multi-step-like experiences or conditional form sections.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {DynamicSectionFieldProps<TFieldValues>} props - Component props
+ * @param {DynamicSectionConfig<TFieldValues>} props.config - Dynamic section configuration
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element|null} The rendered section or null if condition is not met
+ *
+ * @example
+ * ```tsx
+ * import { DynamicSectionField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.checkbox("hasEmergencyContact", "Has Emergency Contact"),
+ *   DynamicSectionField({
+ *     config: {
+ *       name: "emergencyContact",
+ *       title: "Emergency Contact Information",
+ *       description: "Please provide emergency contact details",
+ *       condition: (values) => values.hasEmergencyContact === true,
+ *       fields: [
+ *         FormFieldHelpers.input("name", "Contact Name"),
+ *         FormFieldHelpers.input("relationship", "Relationship"),
+ *         FormFieldHelpers.input("phone", "Phone Number", "tel"),
+ *         FormFieldHelpers.input("email", "Email", "email"),
+ *       ],
+ *     },
+ *     control: form.control,
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Nested dynamic sections:
+ * ```tsx
+ * DynamicSectionField({
+ *   config: {
+ *     name: "businessInfo",
+ *     title: "Business Information",
+ *     condition: (values) => values.accountType === "business",
+ *     fields: [
+ *       FormFieldHelpers.input("businessName", "Business Name"),
+ *       DynamicSectionField({
+ *         config: {
+ *           name: "billingAddress",
+ *           title: "Billing Address",
+ *           condition: (values) => values.businessName && values.taxId,
+ *           fields: [
+ *             FormFieldHelpers.input("street", "Street Address"),
+ *             FormFieldHelpers.input("city", "City"),
+ *           ],
+ *         },
+ *         control: form.control,
+ *       }),
+ *     ],
+ *   },
+ *   control: form.control,
+ * }),
+ * ```
+ *
+ * @see {@link ConditionalField} for single conditional fields
+ * @see {@link FieldArrayField} for repeating fields
+ * @category Fields
+ */
 declare function DynamicSectionField<TFieldValues extends FieldValues>({ className, config, control, }: DynamicSectionFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
 interface FormStatusProps<T extends Record<string, any>> {
@@ -1380,4 +2437,4 @@ declare const validationUtils: {
     }>;
 };
 
-export { AdvancedFieldBuilder, type BaseFormFieldConfig, BasicFormBuilder, type BooleanFieldConfig, type ButtonDefaults, type CheckboxDefaults, CheckboxField, type CheckboxFieldProps, type CommonFieldDefaults, CommonFields, ConditionalField, type ConditionalFieldConfig, type ConditionalFieldProps, type ConditionalValidation, ConfigurableForm, 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 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 };