@rachelallyson/hero-hook-form 2.2.0 → 2.2.1

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.1] - 2026-01-13
+
+### Fixed
+
+- **Type Safety**: Improved type inference for `FormFieldHelpers.content()` to fix TypeScript "unsafe call" errors
+  - Changed return type from `ZodFormFieldConfig<T>` to `ContentFieldConfig<T>` for better type inference
+  - Fixes TypeScript compilation errors when using the content helper function
+
 ## [2.2.0] - 2026-01-13
 
 ### Added

package/dist/index.d.ts

@@ -466,10 +466,63 @@ type FontPickerFieldProps<TFieldValues extends FieldValues, TValue extends strin
 };
 declare function FontPickerField<TFieldValues extends FieldValues, TValue extends string = string>(props: FontPickerFieldProps<TFieldValues, TValue>): React$1.JSX.Element;
 
+/**
+ * Props for the InputField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 type InputFieldProps<TFieldValues extends FieldValues> = FieldBaseProps<TFieldValues, string> & WithControl<TFieldValues> & {
     inputProps?: Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
     transform?: (value: string) => string;
 };
+/**
+ * Input field component for text, email, password, tel, and number inputs.
+ *
+ * @description
+ * A memoized input field component that integrates with React Hook Form
+ * and HeroUI Input component. Supports all standard input types and
+ * includes automatic validation error display.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {InputFieldProps<TFieldValues>} props - Component props
+ * @param {Path<TFieldValues>} props.name - Field name path
+ * @param {string} [props.label] - Field label
+ * @param {string} [props.description] - Field description/help text
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {boolean} [props.isDisabled] - Whether field is disabled
+ * @param {RegisterOptions<TFieldValues>} [props.rules] - Validation rules
+ * @param {Partial<InputProps>} [props.inputProps] - Additional Input component props
+ * @param {(value: string) => string} [props.transform] - Value transformation function
+ *
+ * @returns {JSX.Element} The rendered input field
+ *
+ * @example
+ * ```tsx
+ * import { InputField } from "@rachelallyson/hero-hook-form";
+ * import { useForm, Controller } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const { control } = useForm();
+ *
+ *   return (
+ *     <InputField
+ *       name="email"
+ *       label="Email Address"
+ *       description="Enter your email address"
+ *       control={control}
+ *       inputProps={{
+ *         type: "email",
+ *         placeholder: "you@example.com",
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link FormFieldHelpers.input} for helper function to create input field config
+ * @category Fields
+ */
 declare const InputField: <TFieldValues extends FieldValues>(props: InputFieldProps<TFieldValues>) => React$1.JSX.Element;
 
 interface RadioOption<TValue extends string | number> {
@@ -1389,7 +1442,7 @@ declare const FormFieldHelpers: {
         }) => React$1.ReactNode;
         className?: string;
         name?: Path<T>;
-    }) => ZodFormFieldConfig<T>;
+    }) => ContentFieldConfig<T>;
     /**
      * Create a date field
      */
@@ -2025,11 +2078,68 @@ declare function useTypeInferredForm<T extends FieldValues>(formConfig: {
     fields: ZodFormFieldConfig<T>[];
 }, options?: UseInferredFormOptions<T>): UseFormReturn<T>;
 
+/**
+ * Props for the ConditionalField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface ConditionalFieldProps<TFieldValues extends FieldValues> {
     config: ConditionalFieldConfig<TFieldValues>;
     control: Control<TFieldValues>;
     className?: string;
 }
+/**
+ * Conditional field component that shows/hides fields based on form values.
+ *
+ * @description
+ * Renders a field only when a condition function returns true based on
+ * current form values. Useful for creating dynamic forms that adapt to
+ * user input. The field is completely removed from the DOM when hidden.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {ConditionalFieldProps<TFieldValues>} props - Component props
+ * @param {ConditionalFieldConfig<TFieldValues>} props.config - Conditional field configuration
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element|null} The rendered field or null if condition is not met
+ *
+ * @example
+ * ```tsx
+ * import { ConditionalField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.checkbox("hasPhone", "I have a phone number"),
+ *   ConditionalField({
+ *     config: {
+ *       name: "phone",
+ *       condition: (values) => values.hasPhone === true,
+ *       field: FormFieldHelpers.input("phone", "Phone Number", "tel"),
+ *     },
+ *     control: form.control,
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Multiple conditions:
+ * ```tsx
+ * ConditionalField({
+ *   config: {
+ *     name: "businessDetails",
+ *     condition: (values) =>
+ *       values.userType === "business" && values.isRegistered === true,
+ *     field: FormFieldHelpers.input("taxId", "Tax ID"),
+ *   },
+ *   control: form.control,
+ * }),
+ * ```
+ *
+ * @see {@link DynamicSectionField} for grouping multiple conditional fields
+ * @see {@link FieldArrayField} for repeating fields
+ * @category Fields
+ */
 declare function ConditionalField<TFieldValues extends FieldValues>({ className, config, control, }: ConditionalFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
 interface ContentFieldProps<TFieldValues extends FieldValues> {
@@ -2039,17 +2149,155 @@ interface ContentFieldProps<TFieldValues extends FieldValues> {
 }
 declare function ContentField<TFieldValues extends FieldValues>({ config, form, submissionState, }: ContentFieldProps<TFieldValues>): React$1.JSX.Element;
 
+/**
+ * Props for the FieldArrayField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
     config: FieldArrayConfig<TFieldValues>;
     className?: string;
 }
+/**
+ * Field array component for dynamic repeating field groups.
+ *
+ * @description
+ * 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.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {FieldArrayFieldProps<TFieldValues>} props - Component props
+ * @param {FieldArrayConfig<TFieldValues>} props.config - Field array configuration
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element} The rendered field array with add/remove controls
+ *
+ * @example
+ * ```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",
+ *     },
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * With validation:
+ * ```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"),
+ * });
+ * ```
+ *
+ * @see {@link ConditionalField} for conditional single fields
+ * @see {@link DynamicSectionField} for conditional field groups
+ * @category Fields
+ */
 declare function FieldArrayField<TFieldValues extends FieldValues>({ className, config, }: FieldArrayFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
+/**
+ * Props for the DynamicSectionField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface DynamicSectionFieldProps<TFieldValues extends FieldValues> {
     config: DynamicSectionConfig<TFieldValues>;
     control: Control<TFieldValues>;
     className?: string;
 }
+/**
+ * Dynamic section component that shows/hides groups of fields based on form values.
+ *
+ * @description
+ * Similar to ConditionalField but for groups of fields. Renders a section
+ * with title, description, and multiple fields when a condition is met.
+ * Useful for creating multi-step-like experiences or conditional form sections.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {DynamicSectionFieldProps<TFieldValues>} props - Component props
+ * @param {DynamicSectionConfig<TFieldValues>} props.config - Dynamic section configuration
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element|null} The rendered section or null if condition is not met
+ *
+ * @example
+ * ```tsx
+ * import { DynamicSectionField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.checkbox("hasEmergencyContact", "Has Emergency Contact"),
+ *   DynamicSectionField({
+ *     config: {
+ *       name: "emergencyContact",
+ *       title: "Emergency Contact Information",
+ *       description: "Please provide emergency contact details",
+ *       condition: (values) => values.hasEmergencyContact === true,
+ *       fields: [
+ *         FormFieldHelpers.input("name", "Contact Name"),
+ *         FormFieldHelpers.input("relationship", "Relationship"),
+ *         FormFieldHelpers.input("phone", "Phone Number", "tel"),
+ *         FormFieldHelpers.input("email", "Email", "email"),
+ *       ],
+ *     },
+ *     control: form.control,
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Nested dynamic sections:
+ * ```tsx
+ * DynamicSectionField({
+ *   config: {
+ *     name: "businessInfo",
+ *     title: "Business Information",
+ *     condition: (values) => values.accountType === "business",
+ *     fields: [
+ *       FormFieldHelpers.input("businessName", "Business Name"),
+ *       DynamicSectionField({
+ *         config: {
+ *           name: "billingAddress",
+ *           title: "Billing Address",
+ *           condition: (values) => values.businessName && values.taxId,
+ *           fields: [
+ *             FormFieldHelpers.input("street", "Street Address"),
+ *             FormFieldHelpers.input("city", "City"),
+ *           ],
+ *         },
+ *         control: form.control,
+ *       }),
+ *     ],
+ *   },
+ *   control: form.control,
+ * }),
+ * ```
+ *
+ * @see {@link ConditionalField} for single conditional fields
+ * @see {@link FieldArrayField} for repeating fields
+ * @category Fields
+ */
 declare function DynamicSectionField<TFieldValues extends FieldValues>({ className, config, control, }: DynamicSectionFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
 interface FormStatusProps<T extends Record<string, any>> {

package/dist/react/index.d.ts

@@ -458,10 +458,63 @@ type FontPickerFieldProps<TFieldValues extends FieldValues, TValue extends strin
 };
 declare function FontPickerField<TFieldValues extends FieldValues, TValue extends string = string>(props: FontPickerFieldProps<TFieldValues, TValue>): React$1.JSX.Element;
 
+/**
+ * Props for the InputField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 type InputFieldProps<TFieldValues extends FieldValues> = FieldBaseProps<TFieldValues, string> & WithControl<TFieldValues> & {
     inputProps?: Omit<React$1.ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">;
     transform?: (value: string) => string;
 };
+/**
+ * Input field component for text, email, password, tel, and number inputs.
+ *
+ * @description
+ * A memoized input field component that integrates with React Hook Form
+ * and HeroUI Input component. Supports all standard input types and
+ * includes automatic validation error display.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {InputFieldProps<TFieldValues>} props - Component props
+ * @param {Path<TFieldValues>} props.name - Field name path
+ * @param {string} [props.label] - Field label
+ * @param {string} [props.description] - Field description/help text
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {boolean} [props.isDisabled] - Whether field is disabled
+ * @param {RegisterOptions<TFieldValues>} [props.rules] - Validation rules
+ * @param {Partial<InputProps>} [props.inputProps] - Additional Input component props
+ * @param {(value: string) => string} [props.transform] - Value transformation function
+ *
+ * @returns {JSX.Element} The rendered input field
+ *
+ * @example
+ * ```tsx
+ * import { InputField } from "@rachelallyson/hero-hook-form";
+ * import { useForm, Controller } from "react-hook-form";
+ *
+ * function MyForm() {
+ *   const { control } = useForm();
+ *
+ *   return (
+ *     <InputField
+ *       name="email"
+ *       label="Email Address"
+ *       description="Enter your email address"
+ *       control={control}
+ *       inputProps={{
+ *         type: "email",
+ *         placeholder: "you@example.com",
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link FormFieldHelpers.input} for helper function to create input field config
+ * @category Fields
+ */
 declare const InputField: <TFieldValues extends FieldValues>(props: InputFieldProps<TFieldValues>) => React$1.JSX.Element;
 
 interface RadioOption<TValue extends string | number> {
@@ -1381,7 +1434,7 @@ declare const FormFieldHelpers: {
         }) => React$1.ReactNode;
         className?: string;
         name?: Path<T>;
-    }) => ZodFormFieldConfig<T>;
+    }) => ContentFieldConfig<T>;
     /**
      * Create a date field
      */
@@ -2017,11 +2070,68 @@ declare function useTypeInferredForm<T extends FieldValues>(formConfig: {
     fields: ZodFormFieldConfig<T>[];
 }, options?: UseInferredFormOptions<T>): UseFormReturn<T>;
 
+/**
+ * Props for the ConditionalField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface ConditionalFieldProps<TFieldValues extends FieldValues> {
     config: ConditionalFieldConfig<TFieldValues>;
     control: Control<TFieldValues>;
     className?: string;
 }
+/**
+ * Conditional field component that shows/hides fields based on form values.
+ *
+ * @description
+ * Renders a field only when a condition function returns true based on
+ * current form values. Useful for creating dynamic forms that adapt to
+ * user input. The field is completely removed from the DOM when hidden.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {ConditionalFieldProps<TFieldValues>} props - Component props
+ * @param {ConditionalFieldConfig<TFieldValues>} props.config - Conditional field configuration
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element|null} The rendered field or null if condition is not met
+ *
+ * @example
+ * ```tsx
+ * import { ConditionalField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.checkbox("hasPhone", "I have a phone number"),
+ *   ConditionalField({
+ *     config: {
+ *       name: "phone",
+ *       condition: (values) => values.hasPhone === true,
+ *       field: FormFieldHelpers.input("phone", "Phone Number", "tel"),
+ *     },
+ *     control: form.control,
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Multiple conditions:
+ * ```tsx
+ * ConditionalField({
+ *   config: {
+ *     name: "businessDetails",
+ *     condition: (values) =>
+ *       values.userType === "business" && values.isRegistered === true,
+ *     field: FormFieldHelpers.input("taxId", "Tax ID"),
+ *   },
+ *   control: form.control,
+ * }),
+ * ```
+ *
+ * @see {@link DynamicSectionField} for grouping multiple conditional fields
+ * @see {@link FieldArrayField} for repeating fields
+ * @category Fields
+ */
 declare function ConditionalField<TFieldValues extends FieldValues>({ className, config, control, }: ConditionalFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
 interface ContentFieldProps<TFieldValues extends FieldValues> {
@@ -2031,17 +2141,155 @@ interface ContentFieldProps<TFieldValues extends FieldValues> {
 }
 declare function ContentField<TFieldValues extends FieldValues>({ config, form, submissionState, }: ContentFieldProps<TFieldValues>): React$1.JSX.Element;
 
+/**
+ * Props for the FieldArrayField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface FieldArrayFieldProps<TFieldValues extends FieldValues> {
     config: FieldArrayConfig<TFieldValues>;
     className?: string;
 }
+/**
+ * Field array component for dynamic repeating field groups.
+ *
+ * @description
+ * 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.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {FieldArrayFieldProps<TFieldValues>} props - Component props
+ * @param {FieldArrayConfig<TFieldValues>} props.config - Field array configuration
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element} The rendered field array with add/remove controls
+ *
+ * @example
+ * ```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",
+ *     },
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * With validation:
+ * ```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"),
+ * });
+ * ```
+ *
+ * @see {@link ConditionalField} for conditional single fields
+ * @see {@link DynamicSectionField} for conditional field groups
+ * @category Fields
+ */
 declare function FieldArrayField<TFieldValues extends FieldValues>({ className, config, }: FieldArrayFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
+/**
+ * Props for the DynamicSectionField component.
+ *
+ * @template TFieldValues - The form data type
+ */
 interface DynamicSectionFieldProps<TFieldValues extends FieldValues> {
     config: DynamicSectionConfig<TFieldValues>;
     control: Control<TFieldValues>;
     className?: string;
 }
+/**
+ * Dynamic section component that shows/hides groups of fields based on form values.
+ *
+ * @description
+ * Similar to ConditionalField but for groups of fields. Renders a section
+ * with title, description, and multiple fields when a condition is met.
+ * Useful for creating multi-step-like experiences or conditional form sections.
+ *
+ * @template TFieldValues - The form data type
+ *
+ * @param {DynamicSectionFieldProps<TFieldValues>} props - Component props
+ * @param {DynamicSectionConfig<TFieldValues>} props.config - Dynamic section configuration
+ * @param {Control<TFieldValues>} props.control - React Hook Form control
+ * @param {string} [props.className] - Additional CSS class name
+ *
+ * @returns {JSX.Element|null} The rendered section or null if condition is not met
+ *
+ * @example
+ * ```tsx
+ * import { DynamicSectionField, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
+ *
+ * const fields = [
+ *   FormFieldHelpers.checkbox("hasEmergencyContact", "Has Emergency Contact"),
+ *   DynamicSectionField({
+ *     config: {
+ *       name: "emergencyContact",
+ *       title: "Emergency Contact Information",
+ *       description: "Please provide emergency contact details",
+ *       condition: (values) => values.hasEmergencyContact === true,
+ *       fields: [
+ *         FormFieldHelpers.input("name", "Contact Name"),
+ *         FormFieldHelpers.input("relationship", "Relationship"),
+ *         FormFieldHelpers.input("phone", "Phone Number", "tel"),
+ *         FormFieldHelpers.input("email", "Email", "email"),
+ *       ],
+ *     },
+ *     control: form.control,
+ *   }),
+ * ];
+ * ```
+ *
+ * @example
+ * Nested dynamic sections:
+ * ```tsx
+ * DynamicSectionField({
+ *   config: {
+ *     name: "businessInfo",
+ *     title: "Business Information",
+ *     condition: (values) => values.accountType === "business",
+ *     fields: [
+ *       FormFieldHelpers.input("businessName", "Business Name"),
+ *       DynamicSectionField({
+ *         config: {
+ *           name: "billingAddress",
+ *           title: "Billing Address",
+ *           condition: (values) => values.businessName && values.taxId,
+ *           fields: [
+ *             FormFieldHelpers.input("street", "Street Address"),
+ *             FormFieldHelpers.input("city", "City"),
+ *           ],
+ *         },
+ *         control: form.control,
+ *       }),
+ *     ],
+ *   },
+ *   control: form.control,
+ * }),
+ * ```
+ *
+ * @see {@link ConditionalField} for single conditional fields
+ * @see {@link FieldArrayField} for repeating fields
+ * @category Fields
+ */
 declare function DynamicSectionField<TFieldValues extends FieldValues>({ className, config, control, }: DynamicSectionFieldProps<TFieldValues>): React$1.JSX.Element | null;
 
 interface FormStatusProps<T extends Record<string, any>> {

package/package.json

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