@rachelallyson/hero-hook-form 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -2,49 +2,61 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.0.2] - 2025-01-27
 
-## [1.0.0] - 2024-08-23
+### Enhanced
+
+- **Font Picker Refactored**: Now uses native [HeroUI Autocomplete component](https://www.heroui.com/docs/components/autocomplete)
+- **Better Integration**: Perfect HeroUI design system integration with Autocomplete
+- **Enhanced Features**: Built-in search, filtering, keyboard navigation, and accessibility
+- **Sections Support**: Organized font categories with `AutocompleteSection`
+- **Improved Performance**: Leverages HeroUI's optimized Autocomplete implementation
+- **Better UX**: Native HeroUI animations, transitions, and responsive design
 
 ### Added
 
-- Initial release of Hero Hook Form
-- Complete form field components for HeroUI integration
-  - InputField
-  - TextareaField
-  - SelectField
-  - RadioGroupField
-  - CheckboxField
-  - SwitchField
-  - SliderField
-  - DateField
-  - FileField
-- ConfigurableForm component for rapid form development
-- FormProvider for form context management
-- ConfigProvider for global configuration defaults
-- SubmitButton component with loading states
-- Zod integration with ZodForm component
-- Dual entrypoint support (default and /react)
-- Comprehensive TypeScript support
-- Full documentation with examples
-- Cypress test suite for all components
-
-### Features
-
-- Strongly-typed field components
-- Multiple form layouts (vertical, horizontal, grid)
-- Global configuration system
-- Validation integration with React Hook Form
-- Optional Zod schema validation
-- Responsive design support
-- Accessibility features from HeroUI
-- Tree-shaking support for individual components
-
-### Technical
-
-- Built with TypeScript
-- ESM and CommonJS support
-- Dual entrypoint architecture
-- Comprehensive test coverage
-- Full documentation suite
+- **Google Fonts Integration**: Access to 1000+ Google Fonts with API key
+- **Automatic Font Loading**: Selected fonts are automatically loaded from Google Fonts
+- **Fallback Support**: Graceful fallback to local fonts if Google Fonts unavailable
+- **Font Previews**: Live font previews in the picker
+- **Accessibility Features**: Full ARIA support and keyboard navigation
+
+## [1.0.1] - 2024-12-19
+
+### Added
+
+- **`createZodFormConfig` function**: Missing utility function for creating Zod form configurations
+- **Font picker field**: Optional font picker field with `react-fontpicker-ts` integration
+- **Comprehensive documentation**: Complete guides for radio buttons, nested fields, and font picker
+- **Working examples**: Practical examples demonstrating proper usage
+
+### Fixed
+
+- **Default values handling**: Fixed type casting issues in `createZodFormConfig`
+- **Radio button configuration**: Clarified proper usage with `radioOptions` instead of `inputProps.options`
+- **Nested field names**: Documented proper schema structure for nested fields like "fonts.scale"
+- **Type safety**: Updated `ZodFormConfig` interface to make `schema` required
+
+### Documentation
+
+- [Quick Start Guide](./docs/quick-start.md) - Get started quickly with examples
+- [Radio Buttons Guide](./docs/radio-buttons-guide.md) - Complete guide for radio button configuration
+- [Nested Fields Guide](./docs/nested-fields-guide.md) - Working with nested field names
+- [Input Types Guide](./docs/input-types-guide.md) - Complete reference for all input types
+- [Font Picker Guide](./docs/font-picker-guide.md) - Optional font picker field
+- [Font Picker Styling](./docs/font-picker-styling.md) - HeroUI integration and styling
+- [Fixes Summary](./docs/fixes-summary.md) - Summary of all fixes implemented
+
+### Examples
+
+- `example-settings-form.tsx` - Complete settings form with nested fields and radio buttons
+- `example-nested-fields.tsx` - Demonstration of nested field names
+
+## [1.0.0] - 2024-12-18
+
+### Initial Release
+
+- Basic form components with HeroUI integration
+- Zod integration support
+- TypeScript support
+- Form validation and error handling

package/README.md

@@ -6,45 +6,76 @@
 [![React](https://img.shields.io/badge/React-18.2+-blue.svg)](https://reactjs.org/)
 [![HeroUI](https://img.shields.io/badge/HeroUI-2.x-purple.svg)](https://heroui.com/)
 
-> **Typed form helpers that combine React Hook Form and HeroUI components.**
+> **Type-safe form components that combine React Hook Form with HeroUI's design system.**
 
-Build beautiful, accessible forms with full TypeScript support, validation, and HeroUI's design system.
+Build beautiful, accessible forms with full TypeScript support, comprehensive validation, and HeroUI's modern design system. Perfect for React applications that need robust form handling with excellent developer experience.
 
 ## ✨ Features
 
-- 🎯 **Strongly-typed** field components for HeroUI + React Hook Form
-- 🏗️ **Single codebase, dual entrypoints**:
-  - Default entrypoint for individual HeroUI packages
-  - `/react` entrypoint for the aggregate `@heroui/react`
-- 📦 **Optional peers** so apps can install only what they need
-- 🔧 **Global configuration** system for consistent styling
-- ✅ **Zod integration** for schema-based validation
-- 🎨 **Multiple layouts** (vertical, horizontal, grid)
-- ♿ **Accessibility-first** with HeroUI's built-in features
+- 🎯 **Strongly-typed** field components with automatic TypeScript inference
+- 🏗️ **Dual entrypoints** for maximum flexibility:
+  - Default entrypoint for individual HeroUI packages (better tree-shaking)
+  - `/react` entrypoint for the aggregate `@heroui/react` (convenient single dependency)
+- 📦 **Optional dependencies** - install only what you need
+- 🔧 **Global configuration** system for consistent styling across your app
+- ✅ **Zod integration** for schema-based validation with type safety
+- 🎨 **Multiple layouts** (vertical, horizontal, grid) with responsive design
+- ♿ **Accessibility-first** with HeroUI's built-in ARIA support
 - 🌳 **Tree-shakeable** for optimal bundle sizes
+- 🚀 **Rapid prototyping** with ConfigurableForm component
+- 🎨 **Optional font picker** with Google Fonts integration
 
 ## 🚀 Quick Start
 
+### Option 1: All-in-One HeroUI Package (Recommended for Development)
+
+```bash
+npm install @rachelallyson/hero-hook-form @heroui/react react-hook-form zod
+```
+
+### Option 2: Individual HeroUI Packages (Recommended for Production)
+
+```bash
+npm install @rachelallyson/hero-hook-form react-hook-form zod
+npm install @heroui/button @heroui/input @heroui/select  # Only what you need
+```
+
+### Option 3: With Optional Font Picker
+
+For advanced font selection with Google Fonts integration:
+
 ```bash
-npm install @rachelallyson/hero-hook-form react-hook-form @heroui/react
+npm install @rachelallyson/hero-hook-form @rachelallyson/heroui-font-picker
 ```
 
+The `FontPickerField` will automatically use the font picker package if available, with a helpful fallback message if not installed.
+
+### Basic Usage
+
 ```tsx
-import { useForm } from "react-hook-form";
-import { Form, InputField, SubmitButton } from "@rachelallyson/hero-hook-form/react";
+import { ZodForm } from "@rachelallyson/hero-hook-form";
+import { z } from "zod";
+
+const schema = z.object({
+  email: z.string().email("Invalid email"),
+  name: z.string().min(1, "Name is required"),
+});
+
+const config = {
+  schema,
+  fields: [
+    { name: "name", type: "input", label: "Name" },
+    { name: "email", type: "input", label: "Email", inputProps: { type: "email" } },
+  ],
+};
 
 export function ContactForm() {
-  const methods = useForm();
-  
-  return (
-    <Form methods={methods} onSubmit={console.log}>
-      <InputField control={methods.control} label="Email" name="email" />
-      <SubmitButton>Send</SubmitButton>
-    </Form>
-  );
+  return <ZodForm config={config} onSubmit={console.log} />;
 }
 ```
 
+> 📚 **See [Installation Guide](./docs/installation.md) for detailed setup instructions and bundle optimization tips.**
+
 ## 📊 Why Hero Hook Form?
 
 | Feature | Manual Setup | Hero Hook Form |
@@ -58,39 +89,39 @@ export function ContactForm() {
 
 ## Requirements
 
-- react: >=18.2 <20
-- react-dom: >=18.2 <20
-- react-hook-form: >=7 <8
-- HeroUI: 2.x (either the aggregate or individual component packages)
+- **React**: >=18.2 <20
+- **React DOM**: >=18.2 <20  
+- **React Hook Form**: >=7 <8
+- **HeroUI**: >=2 <3 (either individual packages or `@heroui/react`)
 
-## Installation
+## Installation Options
 
-### Option A: Using individual HeroUI packages (default entrypoint)
+### Option A: Individual HeroUI Packages (Recommended for Production)
 
-Install the library, React Hook Form, and the HeroUI components you actually use. If you only use a subset, install just that subset.
+Install only the HeroUI components you actually use for optimal bundle size:
 
 ```bash
-# minimal set that covers all included fields
+# Minimal set that covers all included fields
 npm i @rachelallyson/hero-hook-form react-hook-form \
   @heroui/input @heroui/checkbox @heroui/radio @heroui/select \
   @heroui/switch @heroui/button @heroui/spinner
 ```
 
-Then import from the package root:
+Import from the package root:
 
 ```tsx
 import { InputField, SelectField, CheckboxField, RadioGroupField, SwitchField, TextareaField, SubmitButton } from "@rachelallyson/hero-hook-form";
 ```
 
-### Option B: Using the aggregate `@heroui/react` (react entrypoint)
+### Option B: Aggregate HeroUI Package (Recommended for Development)
 
-Install the library, React Hook Form, and the aggregate package:
+Install the all-in-one HeroUI package for convenience:
 
 ```bash
 npm i @rachelallyson/hero-hook-form react-hook-form @heroui/react
 ```
 
-Then import from the `/react` subpath:
+Import from the `/react` subpath:
 
 ```tsx
 import { InputField, SelectField, CheckboxField, RadioGroupField, SwitchField, TextareaField, SubmitButton } from "@rachelallyson/hero-hook-form/react";
@@ -210,185 +241,126 @@ const config = createZodFormConfig(contactSchema, [
 />
 ```
 
-### Zod Features
-
-- **Type Safety**: Full TypeScript support with automatic type inference
-- **Runtime Validation**: Comprehensive validation with custom error messages
-- **Schema Reusability**: Define schemas once and reuse across your app
-- **Complex Validation**: Support for enums, numbers, custom refinements, and more
-- **Optional Integration**: Only install Zod if you need it
-
-### Zod vs Standard Validation
+### Nested Fields and Radio Buttons
 
-| Feature | Standard Form | Zod Form |
-|---------|---------------|----------|
-| Validation Rules | In field config | In schema |
-| Type Safety | Manual types | Automatic inference |
-| Error Messages | Inline | In schema |
-| Reusability | Per field | Schema-wide |
-| Runtime Safety | Basic | Comprehensive |
-
-## Quick start
-
-A small form wired with React Hook Form using our typed field components.
+For nested field names and radio buttons:
 
 ```tsx
-import { useForm } from "react-hook-form";
-import { Form } from "@rachelallyson/hero-hook-form"; // or "/react"
-import { InputField, SelectField, CheckboxField, TextareaField, RadioGroupField, SwitchField, SubmitButton } from "@rachelallyson/hero-hook-form"; // or "/react"
-
-type Values = {
-  name: string;
-  email: string;
-  bio: string;
-  plan: "free" | "pro" | "team";
-  agree: boolean;
-  enabled: boolean;
-};
-
-export function ExampleForm() {
-  const methods = useForm<Values>({
-    defaultValues: {
-      name: "",
-      email: "",
-      bio: "",
-      plan: "free",
-      agree: false,
-      enabled: false,
-    },
-    mode: "onBlur",
-  });
+const settingsSchema = z.object({
+  fonts: z.object({
+    scale: z.enum(["small", "medium", "large"]).default("medium"),
+  }),
+  layout: z.object({
+    sidebarPosition: z.enum(["left", "right", "hidden"]).default("left"),
+  }),
+  style: z.object({
+    theme: z.enum(["light", "dark", "auto"]).default("auto"),
+  }),
+});
 
-  return (
-    <Form
-      className="flex flex-col gap-4"
-      methods={methods}
-      onSubmit={async (values) => {
-        // submit values to your API
-        await new Promise((r) => setTimeout(r, 300));
-        console.log(values);
-      }}
-    >
-      <InputField control={methods.control} label="Name" name="name" rules={{ required: "Enter your name" }} />
-      <InputField control={methods.control} label="Email" name="email" inputProps={{ type: "email" }} rules={{ required: "Enter your email" }} />
-
-      <TextareaField control={methods.control} label="Bio" name="bio" description="Tell us about yourself" />
-
-      <SelectField
-        control={methods.control}
-        label="Plan"
-        name="plan"
-        options={[
-          { label: "Free", value: "free" },
-          { label: "Pro", value: "pro" },
-          { label: "Team", value: "team" },
-        ]}
-      />
-
-      <RadioGroupField
-        control={methods.control}
-        label="Plan (radio)"
-        name="plan"
-        options={[
-          { label: "Free", value: "free" },
-          { label: "Pro", value: "pro" },
-          { label: "Team", value: "team" },
-        ]}
-      />
-
-      <CheckboxField control={methods.control} label="I agree to the terms" name="agree" rules={{ required: "You must agree" }} />
-      <SwitchField control={methods.control} label="Enable feature" name="enabled" />
-
-      <div className="flex justify-end">
-        <SubmitButton buttonProps={{ color: "primary" }}>Submit</SubmitButton>
-      </div>
-    </Form>
-  );
-}
+const config = createZodFormConfig(settingsSchema, [
+  {
+    name: "fonts.scale",
+    type: "radio",
+    label: "Font Scale",
+    radioOptions: [
+      { label: "Small", value: "small" },
+      { label: "Medium", value: "medium" },
+      { label: "Large", value: "large" },
+    ],
+  },
+  {
+    name: "layout.sidebarPosition",
+    type: "radio",
+    label: "Sidebar Position",
+    radioOptions: [
+      { label: "Left", value: "left" },
+      { label: "Right", value: "right" },
+      { label: "Hidden", value: "hidden" },
+    ],
+  },
+  {
+    name: "style.theme",
+    type: "radio",
+    label: "Theme",
+    radioOptions: [
+      { label: "Light", value: "light" },
+      { label: "Dark", value: "dark" },
+      { label: "Auto", value: "auto" },
+    ],
+  },
+], {
+  defaultValues: {
+    fonts: { scale: "large" },
+    layout: { sidebarPosition: "right" },
+    style: { theme: "auto" },
+  },
+});
 ```
 
-## API
-
-### Field components
-
-All field components are strongly typed over your form values and expose a `...Props` prop for passing through component props in a type-safe way. We derive prop types via `React.ComponentProps<typeof Component>` to avoid tight coupling to HeroUI’s internal type names.
-
-- `InputField<TFieldValues>`
-  - `inputProps?: Omit<ComponentProps<typeof Input>, "value" | "onValueChange" | "label" | "isInvalid" | "errorMessage" | "isDisabled">`
-  - `transform?: (value: string) => string` – modify the value before writing to the form state
-- `TextareaField<TFieldValues>`
-  - `textareaProps?: Omit<ComponentProps<typeof Textarea>, ...>`
-- `SelectField<TFieldValues, TValue extends string | number = string>`
-  - `options: readonly { label: string; value: TValue; description?: string; disabled?: boolean }[]`
-  - `selectProps?: Omit<ComponentProps<typeof Select>, "selectedKeys" | "onSelectionChange" | ...>`
-- `RadioGroupField<TFieldValues, TValue extends string | number = string>`
-  - `options: readonly { label: string; value: TValue; description?: string; disabled?: boolean }[]`
-  - `radioGroupProps?: Omit<ComponentProps<typeof RadioGroup>, "value" | "onValueChange" | "label">`
-- `CheckboxField<TFieldValues>`
-  - `checkboxProps?: Omit<ComponentProps<typeof Checkbox>, ...>`
-- `SwitchField<TFieldValues>`
-  - `switchProps?: Omit<ComponentProps<typeof Switch>, ...>`
-- `SubmitButton`
-  - `isLoading?: boolean` – if omitted, reflects RHF’s `formState.isSubmitting`
-  - `buttonProps?: Omit<ComponentProps<typeof Button>, "type" | "isLoading">`
-
-### Form provider
+### Zod Features
 
-- `Form<TFieldValues>` – light wrapper around RHF’s `FormProvider` that renders a `<form>` and wires `handleSubmit` safely.
+- **Type Safety**: Full TypeScript support with automatic type inference
+- **Nested Fields**: Support for nested field names like "fonts.scale"
+- **Default Values**: Proper handling of default values with nested structure
+- **Radio Buttons**: Easy configuration with `radioOptions`
 
-```tsx
-import { Form } from "@rachelallyson/hero-hook-form"; // or "/react"
+## 🎯 Examples
 
-<Form methods={methods} onSubmit={onSubmit} className="space-y-4">
-  {/* fields */}
-</Form>
-```
+Check out our [comprehensive demo](../example/app/comprehensive-demo/page.tsx) to see Hero Hook Form in action with all field types and layouts!
 
-### Server error helper
+## 📚 Documentation
 
-- `applyServerErrors(form, serverErrors)` – map API validation errors into RHF field errors.
+For comprehensive guides and examples, visit our [documentation](./docs/README.md):
 
-```ts
-import { applyServerErrors } from "@rachelallyson/hero-hook-form"; // or "/react"
+- [🚀 Getting Started](./docs/getting-started.md) - Installation, setup, and first form
+- [🧩 Components](./docs/components.md) - All available field components  
+- [⚙️ Configuration](./docs/configuration.md) - Global configuration and providers
+- [📝 Form Builder](./docs/form-builder.md) - ConfigurableForm component
+- [✅ Validation](./docs/validation.md) - Form validation patterns
+- [🔮 Zod Integration](./docs/zod-integration.md) - Schema-based validation with Zod
+- [🎨 Layouts](./docs/layouts.md) - Form layout options
+- [📖 API Reference](./docs/api-reference.md) - Complete API documentation
 
-try {
-  await api.save(values);
-} catch (e) {
-  applyServerErrors(methods, e.errors);
-}
-```
+## 🔧 API Overview
 
-## Choosing an entrypoint
+### Field Components
 
-- Use the default entrypoint if your app installs individual HeroUI packages.
-- Use `/react` if your app installs the aggregate `@heroui/react` and you prefer a single HeroUI dep.
+All field components are strongly typed and expose component-specific props:
 
-Peers are marked optional. Install only the set required by your chosen entrypoint.
+- **`InputField`** - Text inputs with validation
+- **`TextareaField`** - Multi-line text inputs  
+- **`SelectField`** - Dropdown selections
+- **`RadioGroupField`** - Radio button groups
+- **`CheckboxField`** - Single checkboxes
+- **`SwitchField`** - Toggle switches
+- **`SliderField`** - Range slider inputs
+- **`DateField`** - Date picker inputs
+- **`FileField`** - File upload inputs
+- **`FontPickerField`** - Optional font selection (requires `@rachelallyson/heroui-font-picker`)
 
-## Version compatibility
+### Form Components
 
-- HeroUI: `>=2 <3`
-- React: `>=18.2.0 <20`
-- react-hook-form: `>=7 <8`
+- **`Form`** - Light wrapper around React Hook Form's FormProvider
+- **`FormField`** - Generic field wrapper component
+- **`ZodForm`** - Schema-based forms with Zod validation
+- **`ConfigurableForm`** - Rapid form development with declarative config
 
-## 📚 Documentation
+### Utilities & Hooks
 
-For comprehensive documentation, examples, and guides, visit our [documentation](./docs/README.md).
+- **`applyServerErrors`** - Map API validation errors to form fields
+- **`HeroHookFormProvider`** - Global configuration for consistent styling
+- **`useHeroForm`** - Enhanced form hook with additional utilities
+- **`useFormHelper`** - Form helper utilities
 
-### Quick Links
+For complete API documentation, see [API Reference](./docs/api-reference.md).
 
-- [🚀 Getting Started](./docs/getting-started.md) - Installation, setup, and first form
-- [🧩 Components](./docs/components.md) - All available field components
-- [🏗️ Form Builder](./docs/form-builder.md) - ConfigurableForm component guide
-- [⚙️ Configuration](./docs/configuration.md) - Global configuration and providers
-- [✅ Validation](./docs/validation.md) - Form validation patterns
-- [🔒 Zod Integration](./docs/zod-integration.md) - Schema-based validation with Zod
-- [🎨 Layouts](./docs/layouts.md) - Form layout options
-- [📖 API Reference](./docs/api-reference.md) - Complete API documentation
+## 🎯 Entrypoint Selection
 
-## 🎯 Examples
+- **Default entrypoint**: For apps using individual HeroUI packages (better tree-shaking)
+- **`/react` entrypoint**: For apps using `@heroui/react` (convenient single dependency)
 
-Check out our [comprehensive demo](../example/app/comprehensive-demo/page.tsx) to see Hero Hook Form in action with all field types and layouts!
+Both entrypoints are fully tree-shakeable and support all features.
 
 ## ❓ FAQ