@rachelallyson/hero-hook-form 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.6.0] - 2026-01-13
+
+### Added
+
+- **Complete Prop Support for All FormFieldHelpers**: All field helpers now accept full component props for complete customization
+  - `input()` - Added `inputProps` parameter for full Input component customization
+  - `textarea()` - Added `textareaProps` parameter (placeholder still works as shorthand)
+  - `select()` - Added `selectProps` parameter
+  - `checkbox()` - Added `checkboxProps` parameter
+  - `switch()` - Added `switchProps` parameter (description still works as shorthand)
+  - `autocomplete()` - Added `autocompleteProps` parameter (placeholder still works as shorthand)
+  - `date()` - Improved with proper `DateInput` component typing
+  - `slider()` - Improved with proper `Slider` component typing
+  - `file()` - Improved with proper `Input` component typing for file inputs
+  - `fontPicker()` - Added helper with proper `FontPickerProps` interface typing
+
+- **New Field Helpers**: Added missing helpers for complete coverage
+  - `radio()` - Radio group field helper with `radioProps` support
+  - `slider()` - Slider field helper with `sliderProps` support
+  - `file()` - File upload field helper with `fileProps` support
+  - `fontPicker()` - Font picker field helper with `fontPickerProps` support
+
+### Enhanced
+
+- **Improved Type Safety**: Replaced all `Record<string, string | number | boolean>` types with proper component types
+  - All helpers now use `Omit<ComponentProps<typeof Component>, ...>` for full type safety
+  - Removed all type assertions (`as Record`) - now using proper component types
+  - Full IntelliSense support for all component props
+  - Type-safe exclusions for form-managed props (value, onChange, label, etc.)
+
+- **Consistent API Pattern**: All helpers now follow the same pattern
+  - Simple API for basic cases: `FormFieldHelpers.input("email", "Email", "email")`
+  - Full customization when needed: `FormFieldHelpers.input("email", "Email", "email", { classNames: {...}, startContent: <Icon /> })`
+  - Backward compatible - all existing code continues to work
+
+### Fixed
+
+- **AdvancedFormBuilder**: Updated to use correct prop names (`maxValue`/`minValue` instead of `max`/`min` for Slider)
+- **TypeInferredBuilder**: Updated slider props to use correct prop names
+- **FontPicker Types**: Improved type safety with proper `FontPickerProps` interface instead of `Record`
+
+## [2.5.1] - 2026-01-13
+
+### Fixed
+
+- **Conditional Field Helper TypeScript Types**: Fixed type inference issues in `FormFieldHelpers.conditional()`
+  - Added default generic type parameter `= FieldValues` for better type compatibility
+  - Updated to use type assertion pattern similar to `FormFieldHelpers.content()` for consistency
+  - Improved type safety and compatibility with explicit type annotations in condition functions
+  - When TypeScript can't infer the type from `Partial<T>`, explicitly specify: `FormFieldHelpers.conditional<YourType>(...)`
+  - Removed unused `ConditionalFieldConfig` import
+
+## [2.5.0] - 2026-01-13
+
+### Added
+
+- **AutocompleteField Component**: New autocomplete field component with full React Hook Form integration
+  - Supports static option lists via `items` prop
+  - Supports async loading via custom `children` render function
+  - Handles custom values with `allowsCustomValue` prop
+  - Full validation and error handling support
+  - Integrated with `FormFieldHelpers.autocomplete()` helper
+  - Integrated with `BasicFormBuilder.autocomplete()` method
+  - Comprehensive test coverage (10/10 tests passing)
+  - Example: `FormFieldHelpers.autocomplete("country", "Country", options, "Search for a country")`
+
+### Dependencies
+
+- Added `@heroui/autocomplete` as optional peer dependency and dev dependency
+- Updated UI exports to include Autocomplete and AutocompleteItem components
+
 ## [2.4.0] - 2026-01-13
 
 ### Added

package/dist/index.d.ts

@@ -9,13 +9,13 @@ import * as _internationalized_date from '@internationalized/date';
 import { CalendarDate } from '@internationalized/date';
 import { Autocomplete } from '@heroui/autocomplete';
 import { Checkbox } from '@heroui/checkbox';
+import { DateInput } from '@heroui/date-input';
 import { Input, Textarea } from '@heroui/input';
 import { RadioGroup } from '@heroui/radio';
 import { Select } from '@heroui/select';
+import { Slider } from '@heroui/slider';
 import { Switch } from '@heroui/switch';
 import { Button as Button$1 } from '@heroui/button';
-import { DateInput } from '@heroui/date-input';
-import { Slider } from '@heroui/slider';
 
 interface FieldBaseProps<TFieldValues extends FieldValues, TValue> {
     name: Path<TFieldValues>;
@@ -76,24 +76,29 @@ interface RadioFieldConfig<TFieldValues extends FieldValues> extends BaseFormFie
 interface SliderFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "slider";
     defaultValue?: number;
-    sliderProps?: Record<string, string | number | boolean>;
+    sliderProps?: Omit<ComponentProps<typeof Slider>, "value" | "onChange" | "label" | "isDisabled">;
 }
 interface DateFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "date";
     defaultValue?: _internationalized_date.CalendarDate | null;
-    dateProps?: Record<string, string | number | boolean>;
+    dateProps?: Omit<ComponentProps<typeof DateInput>, "value" | "onChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
 }
 interface FileFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "file";
     defaultValue?: FileList | null;
-    fileProps?: Record<string, string | number | boolean>;
+    fileProps?: Omit<ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled" | "type">;
     multiple?: boolean;
     accept?: string;
 }
 interface FontPickerFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "fontPicker";
     defaultValue?: string;
-    fontPickerProps?: Record<string, string | number | boolean>;
+    fontPickerProps?: {
+        showFontPreview?: boolean;
+        loadAllVariants?: boolean;
+        onFontsLoaded?: (loaded: boolean) => void;
+        fontsLoadedTimeout?: number;
+    };
 }
 interface CustomFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "custom";
@@ -2083,6 +2088,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
      */
@@ -2180,15 +2192,42 @@ declare function createBasicFormBuilder<T extends FieldValues>(): BasicFormBuild
 declare const FormFieldHelpers: {
     /**
      * Create an autocomplete field
+     *
+     * @example
+     * ```tsx
+     * // Simple autocomplete
+     * FormFieldHelpers.autocomplete("country", "Country", options)
+     *
+     * // With placeholder
+     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries")
+     *
+     * // With full customization
+     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", {
+     *   classNames: { base: "custom-autocomplete" },
+     *   allowsCustomValue: true
+     * })
+     * ```
      */
     autocomplete: <T extends FieldValues>(name: Path<T>, label: string, items: {
         label: string;
         value: string | number;
-    }[], placeholder?: string) => ZodFormFieldConfig<T>;
+    }[], placeholder?: string, autocompleteProps?: Omit<React$1.ComponentProps<typeof Autocomplete>, "selectedKey" | "onSelectionChange" | "inputValue" | "onInputChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled" | "children" | "items">) => ZodFormFieldConfig<T>;
     /**
      * Create a checkbox field
+     *
+     * @example
+     * ```tsx
+     * // Simple checkbox
+     * FormFieldHelpers.checkbox("newsletter", "Subscribe to newsletter")
+     *
+     * // With full customization
+     * FormFieldHelpers.checkbox("newsletter", "Subscribe to newsletter", {
+     *   classNames: { base: "custom-checkbox" },
+     *   size: "lg"
+     * })
+     * ```
      */
-    checkbox: <T extends FieldValues>(name: Path<T>, label: string) => ZodFormFieldConfig<T>;
+    checkbox: <T extends FieldValues>(name: Path<T>, label: string, checkboxProps?: Omit<React$1.ComponentProps<typeof Checkbox>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
     /**
      * Create a conditional field that shows/hides based on form data
      *
@@ -2200,8 +2239,19 @@ declare const FormFieldHelpers: {
      *   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>(name: Path<T>, condition: (formData: Partial<T>) => boolean, field: ZodFormFieldConfig<T>) => ZodFormFieldConfig<T>;
+    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
      *
@@ -2227,27 +2277,192 @@ declare const FormFieldHelpers: {
     }) => ZodFormFieldConfig<T>;
     /**
      * Create a date field
+     *
+     * @example
+     * ```tsx
+     * // Simple date field
+     * FormFieldHelpers.date("birthDate", "Birth Date")
+     *
+     * // With full customization
+     * FormFieldHelpers.date("birthDate", "Birth Date", {
+     *   label: "Select your birth date",
+     *   granularity: "day",
+     *   minValue: new CalendarDate(1900, 1, 1)
+     * })
+     * ```
+     */
+    date: <T extends FieldValues>(name: Path<T>, label: string, dateProps?: Omit<React$1.ComponentProps<typeof DateInput>, "value" | "onChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
+    /**
+     * Create a file upload field
+     *
+     * @example
+     * ```tsx
+     * // Simple file field
+     * FormFieldHelpers.file("avatar", "Profile Picture")
+     *
+     * // With accept and multiple
+     * FormFieldHelpers.file("avatar", "Profile Picture", {
+     *   accept: "image/*",
+     *   multiple: true
+     * })
+     *
+     * // With full customization
+     * FormFieldHelpers.file("avatar", "Profile Picture", {
+     *   accept: "image/*",
+     *   multiple: false,
+     *   fileProps: { className: "custom-file-input" }
+     * })
+     * ```
+     */
+    file: <T extends FieldValues>(name: Path<T>, label: string, options?: {
+        accept?: string;
+        fileProps?: Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled" | "type">;
+        multiple?: boolean;
+    }) => ZodFormFieldConfig<T>;
+    /**
+     * Create a font picker field
+     *
+     * @example
+     * ```tsx
+     * // Simple font picker
+     * FormFieldHelpers.fontPicker("font", "Choose Font")
+     *
+     * // With full customization
+     * FormFieldHelpers.fontPicker("font", "Choose Font", {
+     *   showFontPreview: true,
+     *   loadAllVariants: false,
+     *   fontsLoadedTimeout: 5000
+     * })
+     * ```
      */
-    date: <T extends FieldValues>(name: Path<T>, label: string, dateProps?: Record<string, string | number | boolean>) => ZodFormFieldConfig<T>;
+    fontPicker: <T extends FieldValues>(name: Path<T>, label: string, fontPickerProps?: {
+        showFontPreview?: boolean;
+        loadAllVariants?: boolean;
+        onFontsLoaded?: (loaded: boolean) => void;
+        fontsLoadedTimeout?: number;
+    }) => ZodFormFieldConfig<T>;
     /**
      * Create an input field
+     *
+     * @example
+     * ```tsx
+     * // Simple input
+     * FormFieldHelpers.input("name", "Name")
+     *
+     * // With type
+     * FormFieldHelpers.input("email", "Email", "email")
+     *
+     * // With full customization
+     * FormFieldHelpers.input("email", "Email", "email", {
+     *   placeholder: "Enter your email",
+     *   classNames: { input: "custom-input" },
+     *   startContent: <MailIcon />,
+     *   description: "We'll never share your email"
+     * })
+     * ```
+     */
+    input: <T extends FieldValues>(name: Path<T>, label: string, type?: "text" | "email" | "tel" | "password", inputProps?: Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
+    /**
+     * Create a radio group field
+     *
+     * @example
+     * ```tsx
+     * // Simple radio group
+     * FormFieldHelpers.radio("gender", "Gender", [
+     *   { label: "Male", value: "male" },
+     *   { label: "Female", value: "female" }
+     * ])
+     *
+     * // With full customization
+     * FormFieldHelpers.radio("gender", "Gender", options, {
+     *   orientation: "horizontal",
+     *   classNames: { base: "custom-radio" }
+     * })
+     * ```
      */
-    input: <T extends FieldValues>(name: Path<T>, label: string, type?: "text" | "email" | "tel" | "password") => ZodFormFieldConfig<T>;
+    radio: <T extends FieldValues>(name: Path<T>, label: string, options: {
+        label: string;
+        value: string | number;
+    }[], radioProps?: Omit<React$1.ComponentProps<typeof RadioGroup>, "value" | "onValueChange" | "label">) => ZodFormFieldConfig<T>;
     /**
      * Create a select field
+     *
+     * @example
+     * ```tsx
+     * // Simple select
+     * FormFieldHelpers.select("country", "Country", options)
+     *
+     * // With full customization
+     * FormFieldHelpers.select("country", "Country", options, {
+     *   placeholder: "Select a country",
+     *   classNames: { trigger: "custom-select" },
+     *   selectionMode: "multiple"
+     * })
+     * ```
      */
     select: <T extends FieldValues>(name: Path<T>, label: string, options: {
         label: string;
         value: string | number;
-    }[]) => ZodFormFieldConfig<T>;
+    }[], selectProps?: Omit<React$1.ComponentProps<typeof Select>, "selectedKeys" | "onSelectionChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
+    /**
+     * Create a slider field
+     *
+     * @example
+     * ```tsx
+     * // Simple slider
+     * FormFieldHelpers.slider("rating", "Rating")
+     *
+     * // With full customization
+     * FormFieldHelpers.slider("rating", "Rating", {
+     *   minValue: 1,
+     *   maxValue: 5,
+     *   step: 1,
+     *   showSteps: true,
+     *   classNames: { base: "custom-slider" }
+     * })
+     * ```
+     */
+    slider: <T extends FieldValues>(name: Path<T>, label: string, sliderProps?: Omit<React$1.ComponentProps<typeof Slider>, "value" | "onChange" | "label" | "isDisabled">) => ZodFormFieldConfig<T>;
     /**
      * Create a switch field
+     *
+     * @example
+     * ```tsx
+     * // Simple switch
+     * FormFieldHelpers.switch("notifications", "Enable notifications")
+     *
+     * // With description
+     * FormFieldHelpers.switch("notifications", "Enable notifications", "Receive email notifications")
+     *
+     * // With full customization
+     * FormFieldHelpers.switch("notifications", "Enable notifications", "Receive email notifications", {
+     *   classNames: { base: "custom-switch" },
+     *   size: "lg",
+     *   color: "primary"
+     * })
+     * ```
      */
-    switch: <T extends FieldValues>(name: Path<T>, label: string, description?: string) => ZodFormFieldConfig<T>;
+    switch: <T extends FieldValues>(name: Path<T>, label: string, description?: string, switchProps?: Omit<React$1.ComponentProps<typeof Switch>, "isSelected" | "onValueChange" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
     /**
      * Create a textarea field
+     *
+     * @example
+     * ```tsx
+     * // Simple textarea
+     * FormFieldHelpers.textarea("message", "Message")
+     *
+     * // With placeholder
+     * FormFieldHelpers.textarea("message", "Message", "Enter your message")
+     *
+     * // With full customization
+     * FormFieldHelpers.textarea("message", "Message", "Enter your message", {
+     *   classNames: { input: "custom-textarea" },
+     *   minRows: 3,
+     *   maxRows: 10
+     * })
+     * ```
      */
-    textarea: <T extends FieldValues>(name: Path<T>, label: string, placeholder?: string) => ZodFormFieldConfig<T>;
+    textarea: <T extends FieldValues>(name: Path<T>, label: string, placeholder?: string, textareaProps?: Omit<React$1.ComponentProps<typeof Textarea>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">) => ZodFormFieldConfig<T>;
 };
 /**
  * Common field collections