@rachelallyson/hero-hook-form 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.4.0] - 2026-01-13
+
+### Added
+
+- **Switch Field Description Support**: Added optional `description` parameter to `FormFieldHelpers.switch()` and `BasicFormBuilder.switch()`
+  - Allows adding help text to switch fields for better UX
+  - Description is rendered below the switch component
+  - Backward compatible - existing code without description continues to work
+  - Example: `FormFieldHelpers.switch("notifications", "Enable notifications", "Receive email notifications")`
+
+- **Conditional Field Helper**: Added `FormFieldHelpers.conditional()` helper function for creating conditional fields
+  - Simplifies creating fields that show/hide based on form data
+  - Works seamlessly with all form types
+  - Example: `FormFieldHelpers.conditional("phone", (values) => values.hasPhone === true, FormFieldHelpers.input("phone", "Phone Number", "tel"))`
+
+### Fixed
+
+- **AdvancedFormBuilder Switch Field**: Fixed bug in `AdvancedFormBuilder.switchField()` where:
+  - `description` parameter was accepted but not included in the returned config
+  - `isDisabled` was incorrectly placed in `switchProps.disabled` instead of at the top level
+  - Both properties are now correctly placed at the top level of the field config
+
+### Testing
+
+- Added comprehensive test coverage for switch field description functionality
+- Added tests for `FormFieldHelpers.switch()` with and without description
+- Added tests for `BasicFormBuilder.switch()` with description
+- All tests passing (8/8 tests in SwitchField.cy.tsx)
+
 ## [2.3.0] - 2026-01-13
 
 ### Removed

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import * as zod from 'zod';
 import { z } from 'zod';
 import * as _internationalized_date from '@internationalized/date';
 import { CalendarDate } from '@internationalized/date';
+import { Autocomplete } from '@heroui/autocomplete';
 import { Checkbox } from '@heroui/checkbox';
 import { Input, Textarea } from '@heroui/input';
 import { RadioGroup } from '@heroui/radio';
@@ -46,11 +47,12 @@ interface BaseFormFieldConfig<TFieldValues extends FieldValues> {
     ariaDescribedBy?: string;
 }
 interface StringFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
-    type: "input" | "textarea" | "select";
+    type: "input" | "textarea" | "select" | "autocomplete";
     defaultValue?: string;
     inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
     textareaProps?: Omit<ComponentProps<typeof Textarea>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
     selectProps?: Omit<ComponentProps<typeof Select>, "selectedKeys" | "onSelectionChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
+    autocompleteProps?: Omit<ComponentProps<typeof Autocomplete>, "selectedKey" | "onSelectionChange" | "inputValue" | "onInputChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled" | "children" | "items">;
     options?: {
         label: string;
         value: string | number;
@@ -428,6 +430,127 @@ interface ServerActionFormProps<T extends FieldValues> {
  */
 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;
 
+/**
+ * Configuration for an autocomplete option.
+ *
+ * @template TValue - The value type for the option
+ */
+interface AutocompleteOption<TValue extends string | number> {
+    /** Display label for the option */
+    label: string;
+    /** Value of the option */
+    value: TValue;
+    /** Optional description text */
+    description?: string;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+}
+/**
+ * Props for the AutocompleteField component.
+ *
+ * @template TFieldValues - The form data type
+ * @template TValue - The value type for the autocomplete field (string or number)
+ *
+ * @example
+ * ```tsx
+ * import { AutocompleteField } from "@rachelallyson/hero-hook-form";
+ * import { useForm } from "react-hook-form";
+ *
+ * const form = useForm({
+ *   defaultValues: { country: "" },
+ * });
+ *
+ * const options = [
+ *   { label: "United States", value: "us" },
+ *   { label: "Canada", value: "ca" },
+ *   { label: "Mexico", value: "mx" },
+ * ];
+ *
+ * <AutocompleteField
+ *   control={form.control}
+ *   name="country"
+ *   label="Country"
+ *   items={options}
+ *   placeholder="Search for a country"
+ * />
+ * ```
+ */
+type AutocompleteFieldProps<TFieldValues extends FieldValues, TValue extends string | number = string> = FieldBaseProps<TFieldValues, TValue> & WithControl<TFieldValues> & {
+    /** Array of autocomplete options (for static lists) */
+    items?: readonly AutocompleteOption<TValue>[];
+    /** Placeholder text when no option is selected */
+    placeholder?: string;
+    /** Additional props to pass to the underlying Autocomplete component */
+    autocompleteProps?: Omit<React$1.ComponentProps<typeof Autocomplete>, "selectedKey" | "onSelectionChange" | "inputValue" | "onInputChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled" | "children" | "items" | "defaultItems">;
+    /** Custom render function for items (for async loading) */
+    children?: (item: AutocompleteOption<TValue>) => React$1.JSX.Element;
+};
+/**
+ * An autocomplete field component that integrates React Hook Form with HeroUI Autocomplete.
+ *
+ * This component provides a type-safe autocomplete field with validation support,
+ * error handling, and accessibility features. It supports both static option lists
+ * and async loading via the items prop or children render function.
+ *
+ * @template TFieldValues - The form data type
+ * @template TValue - The value type for the autocomplete field (string or number)
+ *
+ * @param props - The autocomplete field props
+ * @returns The rendered autocomplete field component
+ *
+ * @example
+ * ```tsx
+ * import { ZodForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ * import { z } from "zod";
+ *
+ * const schema = z.object({
+ *   country: z.string().min(1, "Please select a country"),
+ * });
+ *
+ * const options = [
+ *   { label: "United States", value: "us" },
+ *   { label: "Canada", value: "ca" },
+ * ];
+ *
+ * function MyForm() {
+ *   return (
+ *     <ZodForm
+ *       config={{
+ *         schema,
+ *         fields: [
+ *           FormFieldHelpers.autocomplete("country", "Country", options, "Search for a country"),
+ *         ],
+ *       }}
+ *       onSubmit={(data) => console.log(data)}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With async loading
+ * <AutocompleteField
+ *   control={form.control}
+ *   name="country"
+ *   label="Country"
+ *   placeholder="Search for a country"
+ *   autocompleteProps={{
+ *     allowsCustomValue: true,
+ *     onInputChange={(value) => {
+ *       // Load options asynchronously based on input
+ *       loadOptions(value);
+ *     }},
+ *   }}
+ * >
+ *   {(item) => (
+ *     <AutocompleteItem key={item.value}>{item.label}</AutocompleteItem>
+ *   )}
+ * </AutocompleteField>
+ * ```
+ */
+declare function AutocompleteField<TFieldValues extends FieldValues, TValue extends string | number = string>(props: AutocompleteFieldProps<TFieldValues, TValue>): React$1.JSX.Element;
+
 /**
  * Props for the CheckboxField component.
  *
@@ -1118,7 +1241,7 @@ type SwitchFieldProps<TFieldValues extends FieldValues> = FieldBaseProps<TFieldV
  *       config={{
  *         schema,
  *         fields: [
- *           FormFieldHelpers.switch("notifications", "Enable notifications"),
+ *           FormFieldHelpers.switch("notifications", "Enable notifications", "Receive email notifications"),
  *           FormFieldHelpers.switch("darkMode", "Dark mode"),
  *         ],
  *       }}
@@ -1979,7 +2102,7 @@ declare class BasicFormBuilder<T extends FieldValues> {
     /**
      * Add a switch field
      */
-    switch(name: Path<T>, label: string): this;
+    switch(name: Path<T>, label: string, description?: string): this;
     /**
      * Build the final field configuration array
      */
@@ -2043,6 +2166,11 @@ declare function createBasicFormBuilder<T extends FieldValues>(): BasicFormBuild
  *     { label: "CA", value: "ca" },
  *   ]),
  *   FormFieldHelpers.checkbox("newsletter", "Subscribe to newsletter"),
+ *   FormFieldHelpers.conditional(
+ *     "phone",
+ *     (values) => values.hasPhone === true,
+ *     FormFieldHelpers.input("phone", "Phone Number", "tel")
+ *   ),
  * ];
  * ```
  *
@@ -2050,10 +2178,30 @@ declare function createBasicFormBuilder<T extends FieldValues>(): BasicFormBuild
  * @category Builders
  */
 declare const FormFieldHelpers: {
+    /**
+     * Create an autocomplete field
+     */
+    autocomplete: <T extends FieldValues>(name: Path<T>, label: string, items: {
+        label: string;
+        value: string | number;
+    }[], placeholder?: string) => ZodFormFieldConfig<T>;
     /**
      * Create a checkbox field
      */
     checkbox: <T extends FieldValues>(name: Path<T>, label: string) => ZodFormFieldConfig<T>;
+    /**
+     * Create a conditional field that shows/hides based on form data
+     *
+     * @example
+     * ```tsx
+     * FormFieldHelpers.conditional(
+     *   "phone",
+     *   (values) => values.hasPhone === true,
+     *   FormFieldHelpers.input("phone", "Phone Number", "tel")
+     * )
+     * ```
+     */
+    conditional: <T extends FieldValues>(name: Path<T>, condition: (formData: Partial<T>) => boolean, field: ZodFormFieldConfig<T>) => ZodFormFieldConfig<T>;
     /**
      * Create a content field for headers, questions, or custom content between fields
      *
@@ -2095,7 +2243,7 @@ declare const FormFieldHelpers: {
     /**
      * Create a switch field
      */
-    switch: <T extends FieldValues>(name: Path<T>, label: string) => ZodFormFieldConfig<T>;
+    switch: <T extends FieldValues>(name: Path<T>, label: string, description?: string) => ZodFormFieldConfig<T>;
     /**
      * Create a textarea field
      */
@@ -3071,4 +3219,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, 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, 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 };