@rachelallyson/hero-hook-form 2.10.0 → 2.11.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [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

@@ -80,10 +80,16 @@ 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;
+    }[];
 }
 interface BooleanFieldConfig<TFieldValues extends FieldValues> extends BaseFormFieldConfig<TFieldValues> {
     type: "checkbox" | "switch";
@@ -635,7 +641,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 +2432,15 @@ 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).
      */
     autocomplete(name: Path<T>, label: string, items: {
         label: string;
         value: string | number;
-    }[], placeholder?: string): this;
+    }[] | (() => {
+        label: string;
+        value: string | number;
+    }[]), placeholder?: string): this;
     /**
      * Add a checkbox field
      */
@@ -2530,27 +2541,31 @@ 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)
-     *
-     * // With placeholder
-     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries")
+     * // Static
+     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", { allowsCustomValue: true })
      *
-     * // With full customization
-     * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", {
-     *   classNames: { base: "custom-autocomplete" },
-     *   allowsCustomValue: true
+     * // 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),
      * })
      * ```
      */
     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) => ZodFormFieldConfig<T>;
     /**
      * Create a checkbox field
      *
@@ -2988,7 +3003,11 @@ 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;
     }[];

package/dist/index.js

@@ -2335,6 +2335,7 @@ function FormFieldComponent({
       );
     }
     case "autocomplete": {
+      const autocompleteOptions = "getOptions" in fieldConfig && typeof fieldConfig.getOptions === "function" ? fieldConfig.getOptions() : "options" in fieldConfig && fieldConfig.options ? fieldConfig.options : [];
       return /* @__PURE__ */ React19.createElement(
         AutocompleteField,
         {
@@ -2342,7 +2343,7 @@ 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)
           })),
@@ -3120,10 +3121,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,
         {
@@ -4048,14 +4050,15 @@ var BasicFormBuilder = class {
     return this;
   }
   /**
-   * Add an autocomplete field
+   * Add an autocomplete field (static options array or dynamic getOptions getter).
    */
   autocomplete(name, label, items, placeholder) {
+    const isGetter = typeof items === "function";
     this.fields.push({
       autocompleteProps: placeholder ? { placeholder } : void 0,
       label,
       name,
-      options: items,
+      ...isGetter ? { getOptions: items } : { options: items },
       type: "autocomplete"
     });
     return this;
@@ -4132,33 +4135,37 @@ 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")
-   *
-   * // With full customization
-   * FormFieldHelpers.autocomplete("country", "Country", options, "Search countries", {
-   *   classNames: { base: "custom-autocomplete" },
-   *   allowsCustomValue: true
+   * // 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),
    * })
    * ```
    */
-  autocomplete: (name, label, items, placeholder, autocompleteProps) => ({
-    autocompleteProps: {
-      ...placeholder && { placeholder },
-      ...autocompleteProps
-    },
-    label,
-    name,
-    options: items,
-    type: "autocomplete"
-  }),
+  autocomplete: (name, label, items, placeholder, autocompleteProps) => {
+    const isGetter = typeof items === "function";
+    return {
+      autocompleteProps: {
+        ...placeholder && { placeholder },
+        ...autocompleteProps
+      },
+      ...isGetter ? { getOptions: items } : { options: items },
+      label,
+      name,
+      type: "autocomplete"
+    };
+  },
   /**
    * Create a checkbox field
    *
@@ -4830,7 +4837,7 @@ 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 },
         type: "autocomplete"
       };
     case "content":

package/package.json

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