@rachelallyson/hero-hook-form 2.4.0 → 2.6.0

package/dist/react/index.js

@@ -123,6 +123,9 @@ function AutocompleteField(props) {
       name,
       render: ({ field: field2, fieldState }) => {
         const selectedKey = field2.value;
+        const hasSelectedValue = selectedKey != null && selectedKey !== "";
+        const allowsCustomValue = autocompleteProps?.allowsCustomValue ?? false;
+        const shouldShowInputValue = allowsCustomValue || !hasSelectedValue;
         return /* @__PURE__ */ React.createElement("div", { className }, /* @__PURE__ */ React.createElement(
           Autocomplete,
           {
@@ -133,18 +136,18 @@ function AutocompleteField(props) {
             isInvalid: Boolean(fieldState.error),
             label,
             placeholder,
-            selectedKey: selectedKey != null ? String(selectedKey) : void 0,
-            inputValue: selectedKey != null ? void 0 : field2.value ?? "",
+            selectedKey: allowsCustomValue ? void 0 : hasSelectedValue ? String(selectedKey) : void 0,
+            inputValue: shouldShowInputValue ? field2.value ?? "" : void 0,
             onSelectionChange: (key) => {
               const next = key ?? "";
               field2.onChange(next);
             },
             onInputChange: (value) => {
-              if (autocompleteProps?.allowsCustomValue) {
+              if (allowsCustomValue) {
                 field2.onChange(value);
               }
             },
-            defaultItems: items
+            items
           },
           children ? children : (item) => /* @__PURE__ */ React.createElement(
             AutocompleteItem,
@@ -2378,6 +2381,19 @@ var BasicFormBuilder = class {
     });
     return this;
   }
+  /**
+   * Add an autocomplete field
+   */
+  autocomplete(name, label, items, placeholder) {
+    this.fields.push({
+      autocompleteProps: placeholder ? { placeholder } : void 0,
+      label,
+      name,
+      options: items,
+      type: "autocomplete"
+    });
+    return this;
+  }
   /**
    * Add a checkbox field
    */
@@ -2428,9 +2444,27 @@ function createBasicFormBuilder() {
 var 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: (name, label, items, placeholder) => ({
-    autocompleteProps: placeholder ? { placeholder } : void 0,
+  autocomplete: (name, label, items, placeholder, autocompleteProps) => ({
+    autocompleteProps: {
+      ...placeholder && { placeholder },
+      ...autocompleteProps
+    },
     label,
     name,
     options: items,
@@ -2438,8 +2472,21 @@ var FormFieldHelpers = {
   }),
   /**
    * 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: (name, label) => ({
+  checkbox: (name, label, checkboxProps) => ({
+    checkboxProps,
     label,
     name,
     type: "checkbox"
@@ -2455,13 +2502,26 @@ var 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: (name, condition, field2) => ({
-    condition,
-    field: field2,
-    name,
-    type: "conditional"
-  }),
+  conditional: (name, condition, field2) => {
+    return {
+      condition,
+      field: field2,
+      name,
+      type: "conditional"
+    };
+  },
   /**
    * Create a content field for headers, questions, or custom content between fields
    *
@@ -2488,6 +2548,19 @@ var FormFieldHelpers = {
   },
   /**
    * 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: (name, label, dateProps) => ({
     dateProps,
@@ -2495,40 +2568,211 @@ var FormFieldHelpers = {
     name,
     type: "date"
   }),
+  /**
+   * 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: (name, label, options) => ({
+    accept: options?.accept,
+    fileProps: options?.fileProps,
+    label,
+    multiple: options?.multiple,
+    name,
+    type: "file"
+  }),
+  /**
+   * 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
+   * })
+   * ```
+   */
+  fontPicker: (name, label, fontPickerProps) => ({
+    fontPickerProps,
+    label,
+    name,
+    type: "fontPicker"
+  }),
   /**
    * 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: (name, label, type = "text") => ({
-    inputProps: { type },
+  input: (name, label, type, inputProps) => ({
+    inputProps: {
+      type: type || "text",
+      ...inputProps
+    },
     label,
     name,
     type: "input"
   }),
+  /**
+   * 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" }
+   * })
+   * ```
+   */
+  radio: (name, label, options, radioProps) => ({
+    label,
+    name,
+    radioOptions: options,
+    radioProps,
+    type: "radio"
+  }),
   /**
    * 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: (name, label, options) => ({
+  select: (name, label, options, selectProps) => ({
     label,
     name,
     options,
+    selectProps,
     type: "select"
   }),
+  /**
+   * 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: (name, label, sliderProps) => ({
+    label,
+    name,
+    sliderProps,
+    type: "slider"
+  }),
   /**
    * 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: (name, label, description) => ({
+  switch: (name, label, description, switchProps) => ({
     description,
     label,
     name,
+    switchProps,
     type: "switch"
   }),
   /**
    * 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: (name, label, placeholder) => ({
+  textarea: (name, label, placeholder, textareaProps) => ({
     label,
     name,
-    textareaProps: { placeholder },
+    textareaProps: {
+      ...placeholder && { placeholder },
+      ...textareaProps
+    },
     type: "textarea"
   })
 };
@@ -2669,11 +2913,10 @@ function sliderField(name, label, props) {
     type: "slider",
     ...props && {
       sliderProps: {
-        className: props.className || "",
-        disabled: props.isDisabled || false,
-        max: props.max || 100,
-        min: props.min || 0,
-        step: props.step || 1
+        className: props.className,
+        maxValue: props.max ?? 100,
+        minValue: props.min ?? 0,
+        step: props.step ?? 1
       }
     }
   };
@@ -2685,9 +2928,8 @@ function dateField(name, label, props) {
     type: "date",
     ...props && {
       dateProps: {
-        className: props.className || "",
-        disabled: props.isDisabled || false,
-        placeholder: props.placeholder || ""
+        className: props.className,
+        placeholder: props.placeholder
       }
     }
   };
@@ -2709,15 +2951,12 @@ function fileField(name, label, props) {
 }
 function fontPickerField(name, label, props) {
   return {
+    className: props?.className,
+    description: props?.description,
+    fontPickerProps: props?.fontPickerProps,
     label,
     name,
-    type: "fontPicker",
-    ...props && {
-      fontPickerProps: {
-        className: props.className || "",
-        disabled: props.isDisabled || false
-      }
-    }
+    type: "fontPicker"
   };
 }
 function contentField(title, description, options) {
@@ -3039,7 +3278,12 @@ var TypeInferredBuilder = class {
     this.formFields.push({
       label,
       name,
-      sliderProps: { max, min, step, ...fieldOptions },
+      sliderProps: {
+        maxValue: max,
+        minValue: min,
+        step,
+        ...fieldOptions
+      },
       type: "slider"
     });
     return this;

package/package.json

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