@rachelallyson/hero-hook-form 2.7.2 → 2.9.0

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.9.0] - 2026-01-22
+
+### Added
+
+- **Documentation: Memory-Safe Forms Guide**: Comprehensive guide for preventing Cypress memory leaks
+  - Complete migration guide from problematic to memory-safe conditional field arrays
+  - Working code examples and best practices
+  - Troubleshooting section for memory issues
+  - Performance optimization recommendations
+
+- **Examples: Question Form Demo**: Working demonstration of memory-safe conditional field arrays
+  - Interactive example showing MULTIPLE_CHOICE question types
+  - Before/after code comparisons
+  - Real-world implementation patterns
+  - Cypress e2e test coverage
+
+- **Enhanced Testing**: Additional test coverage and refinements
+  - Question form e2e tests demonstrating memory safety
+  - Updated Cypress test patterns for memory optimization
+  - Comprehensive validation of conditional field array behavior
+
+### Fixed
+
+- **Test File Naming**: Corrected Cypress test file extensions (`.cy.ts` vs `.spec.ts`)
+- **Conditional Rendering**: Improved formatting and error handling in conditional field components
+
+## [2.8.0] - 2026-01-22
+
+### Added
+
+- **Field Array Memory Leak Fixes**: Comprehensive solution for Cypress Electron renderer memory issues
+  - `FormFieldHelpers.conditionalFieldArray()` - Memory-safe conditional field arrays that prevent register/unregister cycles
+  - `alwaysRegistered` prop for `FieldArrayField` - Keeps fields registered but conditionally renders UI
+  - `useLazyFieldRegistration` and `useLazyFieldArrayRegistration` hooks - Lazy registration for better initial memory usage
+  - `fieldArrayMemory` utilities - Memory cleanup helpers with garbage collection hints
+  - Cypress memory optimizations - `experimentalMemoryManagement` and reduced memory retention
+
+- **Performance Monitoring**: Enhanced field array performance tracking
+  - Memory usage monitoring for field array operations
+  - Performance metrics collection for long-running tests
+  - Garbage collection suggestions for memory-intensive operations
+
+### Fixed
+
+- **Critical Bug Fix: Input Name Attributes**: Fixed missing `name` prop forwarding in `InputField` component
+  - `CoercedInput` now properly passes `name={field.name}` to HeroUI Input components
+  - Fixes accessibility issues where form inputs had no name attribute in DOM
+  - Critical for form automation tools, accessibility compliance, and proper form submission
+  - Affects all input types (text, email, password, tel, number, etc.) in ZodForm
+
+### Internal
+
+- **Architecture Cleanup: Simplified HeroUI Integration**: Removed redundant dual-build system and `/react` subpath
+  - Eliminated duplicate `react/fields/` components and `tsconfig.react.json`
+  - Streamlined to single `#ui` alias approach that works with both individual `@heroui/*` packages and `@heroui/react`
+  - `@heroui/react` re-exports all components, making separate configurations unnecessary
+  - Cleaner codebase with same functionality and flexibility for users
+
 ## [2.7.2] - 2026-01-21
 
 ### Fixed

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import React$1, { ComponentProps } from 'react';
 import { Button } from '@heroui/react';
 import * as react_hook_form from 'react-hook-form';
-import { FieldValues, Path, RegisterOptions, ArrayPath, Control, UseFormReturn, FieldErrors, UseFormProps, SubmitHandler, DefaultValues, UseFormSetError, FieldArrayWithId } from 'react-hook-form';
+import { FieldValues, Path, RegisterOptions, ArrayPath, Control, UseFormReturn, FieldErrors, UseFormProps, SubmitHandler, DefaultValues, UseFormSetError, FieldPath, FieldArrayWithId } from 'react-hook-form';
 export { UseFormReturn, useFormContext } from 'react-hook-form';
 import * as zod from 'zod';
 import { z, ZodSchema } from 'zod';
@@ -197,6 +197,8 @@ interface FieldArrayConfig<TFieldValues extends FieldValues> extends Omit<BaseFo
     };
     /** Function to create default item when adding new array item */
     defaultItem?: () => any;
+    /** Whether this field array should always be registered (for conditional rendering) */
+    alwaysRegistered?: boolean;
     /** Custom render function for array items */
     renderItem?: (props: {
         /** Item index (0-based) */
@@ -2597,6 +2599,41 @@ declare const FormFieldHelpers: {
      * ```
      */
     conditional: <T extends FieldValues = FieldValues>(name: Path<T>, condition: (formData: Partial<T>) => boolean, field: ZodFormFieldConfig<T>) => ZodFormFieldConfig<T>;
+    /**
+     * Create a conditional field array that avoids memory leaks in Cypress tests.
+     *
+     * This helper creates a field array that is always registered but conditionally
+     * rendered, preventing the register/unregister cycles that cause memory
+     * accumulation in Cypress Electron renderer.
+     *
+     * @param name - The field array name
+     * @param condition - Function that determines if the field array should be visible
+     * @param label - Display label for the field array
+     * @param fields - Field configurations for array items
+     * @param options - Additional field array options
+     *
+     * @example
+     * ```tsx
+     * // Memory-safe conditional field array for multiple choice options
+     * FormFieldHelpers.conditionalFieldArray(
+     *   "choices",
+     *   (data) => data.questionType === 'MULTIPLE_CHOICE',
+     *   "Answer Choices",
+     *   [
+     *     FormFieldHelpers.input("text", "Choice Text"),
+     *     FormFieldHelpers.checkbox("isCorrect", "Correct Answer"),
+     *   ]
+     * )
+     * ```
+     */
+    conditionalFieldArray: <T extends FieldValues = FieldValues>(name: ArrayPath<T>, condition: (formData: Partial<T>) => boolean, label: string, fields: ZodFormFieldConfig<T>[], options?: {
+        min?: number;
+        max?: number;
+        addButtonText?: string;
+        removeButtonText?: string;
+        enableReordering?: boolean;
+        defaultItem?: () => any;
+    }) => ZodFormFieldConfig<T>;
     /**
      * Create a content field for headers, questions, or custom content between fields
      *
@@ -3639,6 +3676,33 @@ declare function useTypeInferredForm<T extends FieldValues>(formConfig: {
     fields: ZodFormFieldConfig<T>[];
 }, options?: UseInferredFormOptions<T>): UseFormReturn<T>;
 
+/**
+ * Hook for lazy field registration to reduce initial memory usage.
+ *
+ * This hook registers fields only when they become active (e.g., when a condition is met),
+ * preventing the memory overhead of always-registered fields while avoiding
+ * register/unregister cycles that cause memory leaks in Cypress.
+ *
+ * @param fieldName - The field name to potentially register
+ * @param shouldRegister - Function that determines if the field should be registered
+ * @param defaultValue - Default value for the field when registered
+ * @param rules - Validation rules for the field
+ */
+declare function useLazyFieldRegistration<TFieldValues extends FieldValues>(fieldName: FieldPath<TFieldValues>, shouldRegister: () => boolean, defaultValue?: any, rules?: any): {
+    currentValue: undefined;
+    isRegistered: boolean;
+};
+/**
+ * Hook for lazy field array registration.
+ *
+ * Similar to useLazyFieldRegistration but specifically for field arrays,
+ * which have more complex registration requirements.
+ */
+declare function useLazyFieldArrayRegistration<TFieldValues extends FieldValues>(arrayName: FieldPath<TFieldValues>, shouldRegister: () => boolean, defaultValue?: any[]): {
+    currentValue: any;
+    isRegistered: boolean;
+};
+
 /**
  * Props for the ConditionalField component.
  *
@@ -3718,6 +3782,8 @@ declare function ContentField<TFieldValues extends FieldValues>({ config, form,
 interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
     config: FieldArrayConfig<TFieldValues>;
     className?: string;
+    /** Whether this field array should always be registered (for conditional rendering) */
+    alwaysRegistered?: boolean;
 }
 /**
  * Field array component for dynamic repeating field groups.
@@ -3834,7 +3900,7 @@ interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
  * @see {@link createFieldArrayCustomConfig} for advanced custom rendering
  * @category Fields
  */
-declare function FieldArrayField<TFieldValues extends FieldValues>({ className, config, }: FieldArrayFieldProps<TFieldValues>): React$1.JSX.Element | null;
+declare function FieldArrayField<TFieldValues extends FieldValues>({ alwaysRegistered, className, config, }: FieldArrayFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
 /**
  * Props for the DynamicSectionField component.
@@ -4126,6 +4192,40 @@ interface CreateFieldArrayCustomConfigOptions<TFieldValues extends FieldValues>
  */
 declare function createFieldArrayCustomConfig<TFieldValues extends FieldValues>(options: CreateFieldArrayCustomConfigOptions<TFieldValues>): CustomFieldConfig<TFieldValues>;
 
+/**
+ * Memory management utilities for field arrays to prevent memory leaks
+ * in Cypress tests and long-running applications.
+ */
+/**
+ * Hook to clean up field array memory when component unmounts.
+ * Helps prevent memory accumulation in Cypress Electron renderer.
+ */
+declare function useFieldArrayMemoryCleanup<TFieldValues extends FieldValues>(arrayName: FieldPath<TFieldValues>): {
+    cleanup: () => void;
+};
+/**
+ * Utility to force garbage collection hints for Cypress tests.
+ * Only effective when experimentalMemoryManagement is enabled.
+ */
+declare function suggestGarbageCollection(): void;
+/**
+ * Memory-safe field array operations that include cleanup hints.
+ */
+declare const memorySafeFieldArray: {
+    /**
+     * Add items to a field array with memory management.
+     */
+    addItems: <TFieldValues extends FieldValues>(append: (value: any) => void, items: any[], onProgress?: (addedCount: number) => void) => void;
+    /**
+     * Clear entire field array with memory cleanup.
+     */
+    clearArray: <TFieldValues extends FieldValues>(setValue: (name: FieldPath<TFieldValues>, value: any) => void, arrayName: FieldPath<TFieldValues>) => void;
+    /**
+     * Remove items from a field array with memory cleanup.
+     */
+    removeItems: <TFieldValues extends FieldValues>(remove: (index: number) => void, indices: number[]) => void;
+};
+
 /**
  * Common validation patterns for forms
  */
@@ -4209,4 +4309,4 @@ declare const validationUtils: {
     }>;
 };
 
-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 };
+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, memorySafeFieldArray, pathToString, serverValidation, shallowEqual, simulateFieldInput, simulateFormSubmission, suggestGarbageCollection, syncArrays, throttle, useDebouncedFieldValidation, useDebouncedValidation, useEnhancedFormState, useFieldArrayMemoryCleanup, useFormHelper, useHeroForm, useHeroHookFormDefaults, useInferredForm, useLazyFieldArrayRegistration, useLazyFieldRegistration, useMemoizedCallback, useMemoizedFieldProps, usePerformanceMonitor, useTypeInferredForm, useZodForm, validationPatterns, validationUtils, waitForFormState };

package/dist/index.js

@@ -400,22 +400,30 @@ function ConditionalField({
   const form = useFormContext();
   const formValues = useWatch({ control });
   const shouldShow = condition(formValues);
-  if (!shouldShow) {
+  const isAlwaysRegisteredFieldArray = field2 && typeof field2 === "object" && "type" in field2 && field2.type === "fieldArray" && "alwaysRegistered" in field2 && field2.alwaysRegistered === true;
+  if (!shouldShow && !isAlwaysRegisteredFieldArray) {
     return null;
   }
-  return /* @__PURE__ */ React5.createElement("div", { className }, /* @__PURE__ */ React5.createElement(
-    FormField,
+  return /* @__PURE__ */ React5.createElement(
+    "div",
     {
-      config: field2,
-      form,
-      submissionState: {
-        error: void 0,
-        isSubmitted: false,
-        isSubmitting: false,
-        isSuccess: false
+      className,
+      style: !shouldShow && isAlwaysRegisteredFieldArray ? { display: "none" } : void 0
+    },
+    /* @__PURE__ */ React5.createElement(
+      FormField,
+      {
+        config: field2,
+        form,
+        submissionState: {
+          error: void 0,
+          isSubmitted: false,
+          isSubmitting: false,
+          isSuccess: false
+        }
       }
-    }
-  ));
+    )
+  );
 }
 
 // src/fields/ContentField.tsx
@@ -530,6 +538,7 @@ import React9 from "react";
 import { useFieldArray, useFormContext as useFormContext3 } from "react-hook-form";
 import { Button as Button2 } from "@heroui/react";
 function FieldArrayField({
+  alwaysRegistered = false,
   className,
   config
 }) {
@@ -557,6 +566,9 @@ function FieldArrayField({
   });
   const canAdd = fields.length < max;
   const canRemove = fields.length > min;
+  if (alwaysRegistered && fields.length === 0) {
+    return null;
+  }
   const getFieldPath = (fieldName, itemIndex) => {
     return `${String(name)}.${itemIndex}.${fieldName}`;
   };
@@ -1359,8 +1371,13 @@ function FormFieldComponent({
       );
     }
   }
+  let shouldRenderConditionalField = true;
   if ("condition" in fieldConfig && fieldConfig.condition && !fieldConfig.condition(watchedValues)) {
-    return null;
+    if ("field" in fieldConfig && fieldConfig.field && typeof fieldConfig.field === "object" && "type" in fieldConfig.field && fieldConfig.field.type === "fieldArray" && "alwaysRegistered" in fieldConfig.field && fieldConfig.field.alwaysRegistered === true) {
+      shouldRenderConditionalField = true;
+    } else {
+      return null;
+    }
   }
   if ("dependsOn" in fieldConfig && fieldConfig.dependsOn) {
     const dependentValue = get(watchedValues, fieldConfig.dependsOn);
@@ -1614,7 +1631,8 @@ function FormFieldComponent({
         FieldArrayField,
         {
           config: fieldArrayConfig,
-          className: fieldArrayConfig.className
+          className: fieldArrayConfig.className,
+          alwaysRegistered: "alwaysRegistered" in fieldConfig ? fieldConfig.alwaysRegistered : false
         }
       );
     }
@@ -3256,6 +3274,57 @@ var FormFieldHelpers = {
     };
     return config;
   },
+  /**
+   * Create a conditional field array that avoids memory leaks in Cypress tests.
+   *
+   * This helper creates a field array that is always registered but conditionally
+   * rendered, preventing the register/unregister cycles that cause memory
+   * accumulation in Cypress Electron renderer.
+   *
+   * @param name - The field array name
+   * @param condition - Function that determines if the field array should be visible
+   * @param label - Display label for the field array
+   * @param fields - Field configurations for array items
+   * @param options - Additional field array options
+   *
+   * @example
+   * ```tsx
+   * // Memory-safe conditional field array for multiple choice options
+   * FormFieldHelpers.conditionalFieldArray(
+   *   "choices",
+   *   (data) => data.questionType === 'MULTIPLE_CHOICE',
+   *   "Answer Choices",
+   *   [
+   *     FormFieldHelpers.input("text", "Choice Text"),
+   *     FormFieldHelpers.checkbox("isCorrect", "Correct Answer"),
+   *   ]
+   * )
+   * ```
+   */
+  conditionalFieldArray: (name, condition, label, fields, options) => {
+    const fieldArrayConfig = {
+      addButtonText: options?.addButtonText ?? "Add Item",
+      alwaysRegistered: true,
+      defaultItem: options?.defaultItem,
+      enableReordering: options?.enableReordering ?? false,
+      fields,
+      label,
+      max: options?.max ?? 10,
+      // This prevents register/unregister cycles
+      min: options?.min ?? 0,
+      name,
+      removeButtonText: options?.removeButtonText ?? "Remove",
+      type: "fieldArray"
+    };
+    const config = {
+      condition,
+      field: fieldArrayConfig,
+      name,
+      // ArrayPath extends Path, so this is safe
+      type: "conditional"
+    };
+    return config;
+  },
   /**
    * Create a content field for headers, questions, or custom content between fields
    *
@@ -4475,8 +4544,74 @@ function useTypeInferredForm(formConfig, options = {}) {
   return useInferredForm(formConfig.schema, formConfig.fields, options);
 }
 
+// src/hooks/useLazyFieldRegistration.ts
+import { useEffect as useEffect3, useRef as useRef2, useState as useState4 } from "react";
+import { useFormContext as useFormContext6 } from "react-hook-form";
+function useLazyFieldRegistration(fieldName, shouldRegister, defaultValue, rules) {
+  const { register, setValue, unregister, watch } = useFormContext6();
+  const [isRegistered, setIsRegistered] = useState4(false);
+  const hasCheckedRegistration = useRef2(false);
+  const conditionMet = shouldRegister();
+  useEffect3(() => {
+    if (conditionMet && !isRegistered) {
+      register(fieldName, rules);
+      if (defaultValue !== void 0) {
+        setValue(fieldName, defaultValue);
+      }
+      setIsRegistered(true);
+      hasCheckedRegistration.current = true;
+    } else if (!conditionMet && isRegistered && hasCheckedRegistration.current) {
+      unregister(fieldName);
+      setIsRegistered(false);
+    }
+  }, [
+    conditionMet,
+    fieldName,
+    register,
+    unregister,
+    setValue,
+    rules,
+    defaultValue,
+    isRegistered
+  ]);
+  return {
+    currentValue: isRegistered ? watch(fieldName) : void 0,
+    isRegistered
+  };
+}
+function useLazyFieldArrayRegistration(arrayName, shouldRegister, defaultValue = []) {
+  const { setValue, watch } = useFormContext6();
+  const [isRegistered, setIsRegistered] = useState4(false);
+  const hasCheckedRegistration = useRef2(false);
+  const conditionMet = shouldRegister();
+  const currentValue = watch(arrayName);
+  useEffect3(() => {
+    if (conditionMet && !isRegistered) {
+      if (!currentValue || !Array.isArray(currentValue)) {
+        setValue(arrayName, defaultValue);
+      }
+      setIsRegistered(true);
+      hasCheckedRegistration.current = true;
+    } else if (!conditionMet && isRegistered && hasCheckedRegistration.current) {
+      setValue(arrayName, []);
+      setIsRegistered(false);
+    }
+  }, [
+    conditionMet,
+    arrayName,
+    setValue,
+    defaultValue,
+    isRegistered,
+    currentValue
+  ]);
+  return {
+    currentValue: isRegistered ? currentValue : [],
+    isRegistered
+  };
+}
+
 // src/utils/performance.ts
-import { useCallback as useCallback3, useMemo as useMemo2, useRef as useRef2 } from "react";
+import { useCallback as useCallback3, useMemo as useMemo2, useRef as useRef3 } from "react";
 function debounce(func, delay) {
   let timeoutId;
   return (...args) => {
@@ -4495,7 +4630,7 @@ function throttle(func, limit) {
   };
 }
 function useMemoizedCallback(callback, deps) {
-  const callbackRef = useRef2(callback);
+  const callbackRef = useRef3(callback);
   callbackRef.current = callback;
   return useCallback3(
     ((...args) => callbackRef.current(...args)),
@@ -4541,8 +4676,8 @@ function deepEqual(prevProps, nextProps) {
   return true;
 }
 function usePerformanceMonitor(componentName, enabled = process.env.NODE_ENV === "development") {
-  const renderCountRef = useRef2(0);
-  const lastRenderTimeRef = useRef2(Date.now());
+  const renderCountRef = useRef3(0);
+  const lastRenderTimeRef = useRef3(Date.now());
   if (enabled) {
     renderCountRef.current += 1;
     const now = Date.now();
@@ -4702,6 +4837,76 @@ function createFieldArrayCustomConfig(options) {
   };
 }
 
+// src/utils/fieldArrayMemory.ts
+import { useFormContext as useFormContext7 } from "react-hook-form";
+function useFieldArrayMemoryCleanup(arrayName) {
+  const { reset, unregister } = useFormContext7();
+  const cleanup = () => {
+    try {
+      reset((formValues) => ({
+        ...formValues,
+        [arrayName]: []
+      }));
+      setTimeout(() => {
+        try {
+          unregister(arrayName);
+        } catch (error) {
+          console.debug("Field array cleanup unregister failed:", error);
+        }
+      }, 0);
+    } catch (error) {
+      console.debug("Field array cleanup failed:", error);
+    }
+  };
+  return { cleanup };
+}
+function suggestGarbageCollection() {
+  if (typeof window !== "undefined" && "gc" in window) {
+    try {
+      window.gc();
+    } catch (error) {
+    }
+  }
+}
+var memorySafeFieldArray = {
+  /**
+   * Add items to a field array with memory management.
+   */
+  addItems: (append, items, onProgress) => {
+    let addedCount = 0;
+    const batchSize = 10;
+    for (let i = 0; i < items.length; i += batchSize) {
+      const batch = items.slice(i, i + batchSize);
+      batch.forEach((item) => {
+        append(item);
+        addedCount++;
+      });
+      if (addedCount % batchSize === 0) {
+        suggestGarbageCollection();
+        onProgress?.(addedCount);
+      }
+    }
+    suggestGarbageCollection();
+  },
+  /**
+   * Clear entire field array with memory cleanup.
+   */
+  clearArray: (setValue, arrayName) => {
+    setValue(arrayName, []);
+    suggestGarbageCollection();
+  },
+  /**
+   * Remove items from a field array with memory cleanup.
+   */
+  removeItems: (remove, indices) => {
+    const sortedIndices = [...indices].sort((a, b) => b - a);
+    sortedIndices.forEach((index) => {
+      remove(index);
+    });
+    suggestGarbageCollection();
+  }
+};
+
 // src/builders/validation-helpers.ts
 import { z as z4 } from "zod";
 var validationPatterns = {
@@ -4922,21 +5127,26 @@ export {
   getFormErrors,
   hasFieldError,
   hasFormErrors,
+  memorySafeFieldArray,
   pathToString,
   serverValidation,
   shallowEqual,
   simulateFieldInput,
   simulateFormSubmission,
+  suggestGarbageCollection,
   syncArrays,
   throttle,
   useDebouncedFieldValidation,
   useDebouncedValidation,
   useEnhancedFormState,
+  useFieldArrayMemoryCleanup,
   useFormContext5 as useFormContext,
   useFormHelper,
   useHeroForm,
   useHeroHookFormDefaults,
   useInferredForm,
+  useLazyFieldArrayRegistration,
+  useLazyFieldRegistration,
   useMemoizedCallback,
   useMemoizedFieldProps,
   usePerformanceMonitor,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rachelallyson/hero-hook-form",
-  "version": "2.7.2",
+  "version": "2.9.0",
   "description": "Typed form helpers that combine React Hook Form and HeroUI components.",
   "author": "Rachel Higley",
   "homepage": "https://rachelallyson.github.io/hero-hook-form/",