@rachelallyson/hero-hook-form 2.6.0 → 2.7.0

package/dist/react/index.d.ts

@@ -1,10 +1,10 @@
 import React$1, { ComponentProps } from 'react';
 import { Input, Textarea, Select, Autocomplete, Checkbox, Switch, RadioGroup, Slider, DateInput, 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, Control, UseFormReturn, FieldErrors, UseFormProps, SubmitHandler, UseFormSetError, DefaultValues, ArrayPath, 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';
 
@@ -106,13 +106,74 @@ interface ConditionalFieldConfig<TFieldValues extends FieldValues> extends BaseF
     condition: (formData: Partial<TFieldValues>) => boolean;
     field: ZodFormFieldConfig<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 BaseFormFieldConfig<TFieldValues> {
     type: "fieldArray";
+    /** 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";
@@ -2023,6 +2084,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
  */
@@ -3153,6 +3291,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
  *
@@ -3163,42 +3302,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;
@@ -3342,6 +3540,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
  */
@@ -3425,4 +3774,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, 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 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, SimpleForm, type SimpleFormProps, 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, 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, serverValidation, shallowEqual, simulateFieldInput, simulateFormSubmission, syncArrays, throttle, useDebouncedFieldValidation, useDebouncedValidation, useEnhancedFormState, useFormHelper, useHeroForm, useHeroHookFormDefaults, useInferredForm, useMemoizedCallback, useMemoizedFieldProps, usePerformanceMonitor, useTypeInferredForm, useZodForm, validationPatterns, validationUtils, waitForFormState };