@rachelallyson/hero-hook-form 2.3.0 → 2.5.1

package/dist/react/index.d.ts

@@ -1,5 +1,5 @@
 import React$1, { ComponentProps } from 'react';
-import { Input, Textarea, Select, Checkbox, Switch, RadioGroup, Button, DateInput, Slider } from '@heroui/react';
+import { Input, Textarea, Select, Autocomplete, Checkbox, Switch, RadioGroup, Button, DateInput, Slider } 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';
 export { UseFormReturn, useFormContext } from 'react-hook-form';
@@ -38,11 +38,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;
@@ -420,6 +421,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.
  *
@@ -1110,7 +1232,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"),
  *         ],
  *       }}
@@ -1952,6 +2074,13 @@ declare class BasicFormBuilder<T extends FieldValues> {
         label: string;
         value: string | number;
     }[]): this;
+    /**
+     * Add an autocomplete field
+     */
+    autocomplete(name: Path<T>, label: string, items: {
+        label: string;
+        value: string | number;
+    }[], placeholder?: string): this;
     /**
      * Add a checkbox field
      */
@@ -1971,7 +2100,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
      */
@@ -2035,6 +2164,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")
+ *   ),
  * ];
  * ```
  *
@@ -2042,10 +2176,41 @@ 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")
+     * )
+     * ```
+     *
+     * @example
+     * With explicit type in condition function (similar to content helper pattern):
+     * ```tsx
+     * FormFieldHelpers.conditional(
+     *   "options",
+     *   (formData: Partial<z.infer<typeof fieldSchema>>) =>
+     *     formData.fieldType === 'DROPDOWN',
+     *   FormFieldHelpers.textarea("options", "Dropdown Options", "One per line")
+     * )
+     * ```
+     */
+    conditional: <T extends FieldValues = 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
      *
@@ -2087,7 +2252,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
      */
@@ -3063,4 +3228,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 };