@rachelallyson/hero-hook-form 2.10.0 → 2.12.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.12.0] - 2026-01-28
+
+### Added
+
+- **Custom option layout for autocomplete (renderItem)** – `FormFieldHelpers.autocomplete()` and the builder chain accept an optional 6th param `options?: { renderItem?: (item) => ReactNode }` so each option can show custom content (e.g. name + email + phone). Config supports `renderItem`; `FormField`, `ServerActionForm`, and `AdvancedFormBuilder` pass it through; `AutocompleteField` wraps custom children in `AutocompleteItem` so HeroUI receives valid listbox items. Use with static options or with `getOptions` for dynamic items + custom layout.
+- **StringFieldConfig.renderItem** – Optional `renderItem?: (item: { label: string; value: string | number }) => ReactNode` for autocomplete fields.
+- **Component tests** – Autocomplete: `renderItem` config and render (static and getOptions + renderItem).
+
+### Fixed
+
+- **AutocompleteField custom children** – Custom `children` (renderItem) are now wrapped in `AutocompleteItem` before passing to HeroUI Autocomplete so the listbox receives valid items and the form renders correctly.
+
+## [2.11.0] - 2026-01-28
+
+### Added
+
+- **Dynamic options for autocomplete** – `FormFieldHelpers.autocomplete()` and the builder chain now accept either a static options array or a getter function `() => options`. Use a getter for API-driven autocomplete (e.g. PCO Person, search-as-you-type): the getter is called each render so items stay in sync with state. Config supports `getOptions`; `FormField`, `ServerActionForm`, and `AdvancedFormBuilder` resolve items from `getOptions()` when present, else `options`. No need for `FormFieldHelpers.custom` when you only need dynamic items.
+
+### Changed
+
+- **FormFieldHelpers.autocomplete** – Third parameter can be `options[]` or `() => options[]`; JSDoc documents dynamic usage with `onInputChange`.
+- **StringFieldConfig** – Added optional `getOptions?: () => { label: string; value: string | number }[]` for autocomplete fields.
+- **AutocompleteField JSDoc** – Notes dynamic options via getter + `onInputChange`.
+
 ## [2.10.0] - 2026-01-28
 
 ### Added

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React$1, { ComponentProps } from 'react';
+import React$1, { ComponentProps, ReactNode } 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, FieldPath, FieldArrayWithId } from 'react-hook-form';
@@ -80,10 +80,21 @@ interface StringFieldConfig<TFieldValues extends FieldValues> extends BaseFormFi
     textareaProps?: TextareaPassthroughProps;
     selectProps?: SelectPassthroughProps;
     autocompleteProps?: AutocompletePassthroughProps;
+    /** Static options for autocomplete/select. Omit when using getOptions for dynamic items. */
     options?: {
         label: string;
         value: string | number;
     }[];
+    /** Dynamic options for autocomplete: called each render to get current items (e.g. from API/state). */
+    getOptions?: () => {
+        label: string;
+        value: string | number;
+    }[];
+    /** Custom render for each autocomplete option (e.g. name + email + phone). When provided, used instead of default label-only. */
+    renderItem?: (item: {
+        label: string;
+        value: string | number;
+    }) => ReactNode;
 }
 interface BooleanFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "checkbox" | "switch";
@@ -635,7 +646,9 @@ type AutocompleteFieldProps<TFieldValues extends FieldValues, TValue extends str
  *
  * 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.
+ * and async loading via the items prop or children render function. For dynamic
+ * options (e.g. API search), use FormFieldHelpers.autocomplete with a getter:
+ * () => people.map(p => ({ label: p.name, value: p.id })) and onInputChange to fetch.
  *
  * @template TFieldValues - The form data type
  * @template TValue - The value type for the autocomplete field (string or number)
@@ -2424,12 +2437,21 @@ declare class BasicFormBuilder<T extends FieldValues> {
         value: string | number;
     }[]): this;
     /**
-     * Add an autocomplete field
+     * Add an autocomplete field (static options array or dynamic getOptions getter).
+     * Optional options.renderItem for custom option layout (e.g. name + email + phone).
      */
     autocomplete(name: Path<T>, label: string, items: {
         label: string;
         value: string | number;
-    }[], placeholder?: string): this;
+    }[] | (() => {
+        label: string;
+        value: string | number;
+    }[]), placeholder?: string, options?: {
+        renderItem?: (item: {
+            label: string;
+            value: string | number;
+        }) => React$1.ReactNode;
+    }): this;
     /**
      * Add a checkbox field
      */
@@ -2530,27 +2552,42 @@ declare function inputHelper<T extends FieldValues>(name: Path<T>, label: string
 declare function inputHelper<T extends FieldValues>(name: Path<T>, label: string, type: "text" | "email" | "tel" | "password", inputProps: InputPassthroughProps): ZodFormFieldConfig<T>;
 declare const FormFieldHelpers: {
     /**
-     * Create an autocomplete field
+     * Create an autocomplete field with static or dynamic options.
+     *
+     * Pass an array for a fixed list, or a getter function for dynamic/API-driven options
+     * (e.g. search-as-you-type). The getter is called each render so it sees current state;
+     * use with autocompleteProps.onInputChange to fetch options when the user types.
      *
      * @example
      * ```tsx
-     * // Simple autocomplete
-     * FormFieldHelpers.autocomplete("country", "Country", options)
+     * // Static
+     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", { allowsCustomValue: true })
      *
-     * // With placeholder
-     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries")
+     * // Dynamic (e.g. PCO Person)
+     * const [people, setPeople] = useState([]);
+     * FormFieldHelpers.autocomplete("personId", "Person", () => people.map(p => ({ label: p.name, value: p.id })), "Search people", {
+     *   onInputChange: (q) => fetchPeople(q).then(setPeople),
+     * })
      *
-     * // With full customization
-     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", {
-     *   classNames: { base: "custom-autocomplete" },
-     *   allowsCustomValue: true
+     * // Custom option layout (e.g. name + email + phone per option)
+     * FormFieldHelpers.autocomplete("personId", "Person", getOptions, "Search", undefined, {
+     *   renderItem: (item) => <div><strong>{item.label}</strong><br /><small>{getSubtitle(item.value)}</small></div>,
      * })
      * ```
      */
     autocomplete: <T extends FieldValues>(name: Path<T>, label: string, items: {
         label: string;
         value: string | number;
-    }[], placeholder?: string, autocompleteProps?: AutocompletePassthroughProps) => ZodFormFieldConfig<T>;
+    }[] | (() => {
+        label: string;
+        value: string | number;
+    }[]), placeholder?: string, autocompleteProps?: AutocompletePassthroughProps, options?: {
+        /** Custom render for each option (e.g. name + email + phone). When provided, used instead of default label-only. */
+        renderItem?: (item: {
+            label: string;
+            value: string | number;
+        }) => React$1.ReactNode;
+    }) => ZodFormFieldConfig<T>;
     /**
      * Create a checkbox field
      *
@@ -2988,11 +3025,19 @@ type FieldCreationParams<T extends FieldValues> = {
     type: "autocomplete";
     name: Path<T>;
     label: string;
-    options: {
+    options?: {
+        label: string;
+        value: string | number;
+    }[];
+    getOptions?: () => {
         label: string;
         value: string | number;
     }[];
     props?: Record<string, unknown>;
+    renderItem?: (item: {
+        label: string;
+        value: string | number;
+    }) => React$1.ReactNode;
 } | {
     type: "checkbox";
     name: Path<T>;

package/dist/index.js

@@ -338,7 +338,16 @@ function AutocompleteField(props) {
             inputValue: shouldShowInputValue ? field2.value ?? "" : void 0,
             items
           },
-          children ? children : (item) => /* @__PURE__ */ React.createElement(
+          children ? (item) => /* @__PURE__ */ React.createElement(
+            AutocompleteItem,
+            {
+              key: String(item.value),
+              textValue: String(item.value),
+              description: item.description,
+              isDisabled: item.disabled
+            },
+            children(item)
+          ) : (item) => /* @__PURE__ */ React.createElement(
             AutocompleteItem,
             {
               key: String(item.value),
@@ -2335,6 +2344,8 @@ function FormFieldComponent({
       );
     }
     case "autocomplete": {
+      const autocompleteOptions = "getOptions" in fieldConfig && typeof fieldConfig.getOptions === "function" ? fieldConfig.getOptions() : "options" in fieldConfig && fieldConfig.options ? fieldConfig.options : [];
+      const autocompleteRenderItem = "renderItem" in fieldConfig && typeof fieldConfig.renderItem === "function" ? (item) => /* @__PURE__ */ React19.createElement(React19.Fragment, null, fieldConfig.renderItem(item)) : void 0;
       return /* @__PURE__ */ React19.createElement(
         AutocompleteField,
         {
@@ -2342,11 +2353,12 @@ function FormFieldComponent({
           name: fieldConfig.name,
           control,
           defaultValue: "defaultValue" in fieldConfig ? fieldConfig.defaultValue : void 0,
-          items: ("options" in fieldConfig && fieldConfig.options ? fieldConfig.options : []).map((opt) => ({
+          items: autocompleteOptions.map((opt) => ({
             label: opt.label,
             value: String(opt.value)
           })),
-          autocompleteProps: "autocompleteProps" in fieldConfig ? fieldConfig.autocompleteProps : void 0
+          autocompleteProps: "autocompleteProps" in fieldConfig ? fieldConfig.autocompleteProps : void 0,
+          children: autocompleteRenderItem
         }
       );
     }
@@ -3120,10 +3132,11 @@ function ServerActionField({
     }
     case "autocomplete": {
       const stringConfig = fieldConfig;
-      const items = stringConfig.options?.map((opt) => ({
+      const rawItems = typeof stringConfig.getOptions === "function" ? stringConfig.getOptions() : stringConfig.options ?? [];
+      const items = rawItems.map((opt) => ({
         label: opt.label,
         value: String(opt.value)
-      })) || [];
+      }));
       return /* @__PURE__ */ React21.createElement(
         Autocomplete,
         {
@@ -3143,7 +3156,7 @@ function ServerActionField({
           onInputChange: setValue,
           items
         },
-        items.map((item) => /* @__PURE__ */ React21.createElement(AutocompleteItem, { key: String(item.value) }, item.label))
+        items.map((item) => /* @__PURE__ */ React21.createElement(AutocompleteItem, { key: String(item.value) }, typeof stringConfig.renderItem === "function" ? stringConfig.renderItem(item) : item.label))
       );
     }
     case "slider": {
@@ -4048,14 +4061,17 @@ var BasicFormBuilder = class {
     return this;
   }
   /**
-   * Add an autocomplete field
+   * Add an autocomplete field (static options array or dynamic getOptions getter).
+   * Optional options.renderItem for custom option layout (e.g. name + email + phone).
    */
-  autocomplete(name, label, items, placeholder) {
+  autocomplete(name, label, items, placeholder, options) {
+    const isGetter = typeof items === "function";
     this.fields.push({
       autocompleteProps: placeholder ? { placeholder } : void 0,
       label,
       name,
-      options: items,
+      ...isGetter ? { getOptions: items } : { options: items },
+      ...options?.renderItem && { renderItem: options.renderItem },
       type: "autocomplete"
     });
     return this;
@@ -4132,33 +4148,43 @@ function inputHelper(name, label, typeOrProps, inputProps) {
 }
 var FormFieldHelpers = {
   /**
-   * Create an autocomplete field
+   * Create an autocomplete field with static or dynamic options.
+   *
+   * Pass an array for a fixed list, or a getter function for dynamic/API-driven options
+   * (e.g. search-as-you-type). The getter is called each render so it sees current state;
+   * use with autocompleteProps.onInputChange to fetch options when the user types.
    *
    * @example
    * ```tsx
-   * // Simple autocomplete
-   * FormFieldHelpers.autocomplete("country", "Country", options)
+   * // Static
+   * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", { allowsCustomValue: true })
    *
-   * // With placeholder
-   * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries")
+   * // Dynamic (e.g. PCO Person)
+   * const [people, setPeople] = useState([]);
+   * FormFieldHelpers.autocomplete("personId", "Person", () => people.map(p => ({ label: p.name, value: p.id })), "Search people", {
+   *   onInputChange: (q) => fetchPeople(q).then(setPeople),
+   * })
    *
-   * // With full customization
-   * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", {
-   *   classNames: { base: "custom-autocomplete" },
-   *   allowsCustomValue: true
+   * // Custom option layout (e.g. name + email + phone per option)
+   * FormFieldHelpers.autocomplete("personId", "Person", getOptions, "Search", undefined, {
+   *   renderItem: (item) => <div><strong>{item.label}</strong><br /><small>{getSubtitle(item.value)}</small></div>,
    * })
    * ```
    */
-  autocomplete: (name, label, items, placeholder, autocompleteProps) => ({
-    autocompleteProps: {
-      ...placeholder && { placeholder },
-      ...autocompleteProps
-    },
-    label,
-    name,
-    options: items,
-    type: "autocomplete"
-  }),
+  autocomplete: (name, label, items, placeholder, autocompleteProps, options) => {
+    const isGetter = typeof items === "function";
+    return {
+      autocompleteProps: {
+        ...placeholder && { placeholder },
+        ...autocompleteProps
+      },
+      ...isGetter ? { getOptions: items } : { options: items },
+      ...options?.renderItem && { renderItem: options.renderItem },
+      label,
+      name,
+      type: "autocomplete"
+    };
+  },
   /**
    * Create a checkbox field
    *
@@ -4830,7 +4856,8 @@ function createFieldFromParams(params) {
         autocompleteProps: params.props,
         label: params.label,
         name: params.name,
-        options: params.options,
+        ...typeof params.getOptions === "function" ? { getOptions: params.getOptions } : { options: params.options },
+        ...params.renderItem && { renderItem: params.renderItem },
         type: "autocomplete"
       };
     case "content":

package/package.json

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