@rachelallyson/hero-hook-form 1.2.0 โ 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +96 -0
- package/README.md +115 -351
- package/dist/cypress/index.d.ts +141 -0
- package/dist/cypress/index.js +897 -0
- package/dist/index.d.ts +789 -15
- package/dist/index.js +2414 -422
- package/dist/react/index.d.ts +789 -15
- package/dist/react/index.js +2414 -422
- package/package.json +65 -33
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,102 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [2.1.0] - 2025-01-28
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
#### Next.js Server Actions Support
|
|
10
|
+
|
|
11
|
+
- **ServerActionForm Component**: New component for seamless integration with Next.js Server Actions
|
|
12
|
+
- **Native Form Submission**: Uses native HTML form submission with `FormData` for Server Actions
|
|
13
|
+
- **Optional Client-Side Validation**: Can combine client-side Zod validation with server-side validation
|
|
14
|
+
- **HeroUI Integration**: Full HeroUI component support with controlled components and hidden inputs
|
|
15
|
+
- **Error Handling**: Comprehensive error display for both client and server validation errors
|
|
16
|
+
- **Success Messages**: Built-in success message display (with redirect handling documentation)
|
|
17
|
+
- **Callbacks**: `onError` and `onSuccess` callbacks for custom handling
|
|
18
|
+
- **Default Values**: Support for pre-filling form fields with default values
|
|
19
|
+
- **Documentation**: Complete guide at `docs/guides/nextjs-server-actions.md`
|
|
20
|
+
|
|
21
|
+
## [2.0.0] - 2025-01-27
|
|
22
|
+
|
|
23
|
+
### ๐ Major Release - Enhanced Form Experience
|
|
24
|
+
|
|
25
|
+
This is a major release with significant new features, performance improvements, and some breaking changes. See the [Migration Guide](./docs/migration-v2.md) for upgrade instructions.
|
|
26
|
+
|
|
27
|
+
### Added
|
|
28
|
+
|
|
29
|
+
#### Dynamic Form Sections
|
|
30
|
+
|
|
31
|
+
- **Conditional Fields**: Show/hide fields based on form data with `ConditionalField` component
|
|
32
|
+
- **Field Arrays**: Dynamic repeating field groups with `FieldArrayField` component
|
|
33
|
+
- **Dynamic Sections**: Grouped conditional fields with `DynamicSectionField` component
|
|
34
|
+
- Builder methods: `conditionalField()`, `fieldArray()`, `dynamicSection()`
|
|
35
|
+
|
|
36
|
+
#### Enhanced Form State Management
|
|
37
|
+
|
|
38
|
+
- **Enhanced Form State Hook**: `useEnhancedFormState` with comprehensive state tracking
|
|
39
|
+
- **Form Status Component**: `FormStatus` with loading, success, and error states
|
|
40
|
+
- **Automatic State Management**: Built-in loading indicators and success feedback
|
|
41
|
+
- **Toast Notifications**: Optional toast notifications with `FormToast` component
|
|
42
|
+
|
|
43
|
+
#### Performance Optimizations
|
|
44
|
+
|
|
45
|
+
- **Memoized Components**: All field components now use `React.memo` for better performance
|
|
46
|
+
- **Debounced Validation**: `useDebouncedValidation` hook for configurable validation delays
|
|
47
|
+
- **Performance Utilities**: `usePerformanceMonitor`, `useBatchedFieldUpdates`, and optimization helpers
|
|
48
|
+
- **Memory Optimization**: Better memory usage with proper cleanup and memoization
|
|
49
|
+
|
|
50
|
+
#### Type-Inferred Forms (Alternative API)
|
|
51
|
+
|
|
52
|
+
- **Type-Inferred Builder**: `TypeInferredBuilder` for automatic schema and field generation
|
|
53
|
+
- **Define Inferred Form**: `defineInferredForm` function for single-call form definition
|
|
54
|
+
- **Field Type Builders**: Individual field builders with proper type inference
|
|
55
|
+
- **Auto-Generated Schemas**: Automatic Zod schema generation from field definitions
|
|
56
|
+
|
|
57
|
+
#### Enhanced Validation Patterns
|
|
58
|
+
|
|
59
|
+
- **Cross-Field Validation**: Password confirmation, date ranges, conditional requirements
|
|
60
|
+
- **Validation Patterns**: Common patterns for emails, phones, passwords, credit cards
|
|
61
|
+
- **Async Validation**: Server-side validation integration with `asyncValidation` helpers
|
|
62
|
+
- **Validation Utilities**: Comprehensive validation utilities and error message helpers
|
|
63
|
+
|
|
64
|
+
#### New Hooks and Utilities
|
|
65
|
+
|
|
66
|
+
- `useEnhancedFormState`: Comprehensive form state management
|
|
67
|
+
- `useDebouncedValidation`: Debounced field validation
|
|
68
|
+
- `useInferredForm`: Type-inferred form hook
|
|
69
|
+
- `usePerformanceMonitor`: Performance monitoring utilities
|
|
70
|
+
- `useBatchedFieldUpdates`: Batched field updates for better performance
|
|
71
|
+
|
|
72
|
+
### Changed
|
|
73
|
+
|
|
74
|
+
#### Breaking Changes
|
|
75
|
+
|
|
76
|
+
- **Field Props**: `isDisabled` โ `disabled` for consistency with HeroUI
|
|
77
|
+
- **Form State**: Enhanced form state structure with additional properties and methods
|
|
78
|
+
- **Field Configuration**: `FormFieldConfig` โ `ZodFormFieldConfig` (removed `rules` property)
|
|
79
|
+
- **Type Definitions**: Updated type definitions for better TypeScript support
|
|
80
|
+
|
|
81
|
+
#### API Improvements
|
|
82
|
+
|
|
83
|
+
- **Consistent Naming**: Standardized prop names across all components
|
|
84
|
+
- **Better Type Safety**: Enhanced TypeScript support with better type inference
|
|
85
|
+
- **Simplified API**: Cleaner, more intuitive API design
|
|
86
|
+
- **Performance**: Significant performance improvements across all components
|
|
87
|
+
|
|
88
|
+
### Fixed
|
|
89
|
+
|
|
90
|
+
- **Memory Leaks**: Fixed potential memory leaks in form components
|
|
91
|
+
- **Type Safety**: Resolved TypeScript compilation issues
|
|
92
|
+
- **Build Process**: Improved build process and bundle optimization
|
|
93
|
+
- **Component Re-renders**: Reduced unnecessary re-renders with proper memoization
|
|
94
|
+
|
|
95
|
+
### Removed
|
|
96
|
+
|
|
97
|
+
- **Deprecated APIs**: Removed deprecated field prop names
|
|
98
|
+
- **Legacy Code**: Cleaned up legacy code and unused utilities
|
|
99
|
+
- **Redundant Types**: Simplified type definitions by removing redundant types
|
|
100
|
+
|
|
5
101
|
## [1.0.2] - 2025-01-27
|
|
6
102
|
|
|
7
103
|
### Enhanced
|
package/README.md
CHANGED
|
@@ -1,412 +1,176 @@
|
|
|
1
1
|
# Hero Hook Form
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://opensource.org/licenses/ISC)
|
|
5
|
-
[](https://www.typescriptlang.org/)
|
|
6
|
-
[](https://reactjs.org/)
|
|
7
|
-
[](https://heroui.com/)
|
|
3
|
+
**Typed form helpers that combine React Hook Form and HeroUI components.**
|
|
8
4
|
|
|
9
|
-
|
|
5
|
+
Hero Hook Form provides a comprehensive solution for building accessible, performant forms in React applications. It combines the power of React Hook Form with HeroUI's beautiful design system, offering type-safe form building with minimal boilerplate.
|
|
10
6
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## โจ Features
|
|
14
|
-
|
|
15
|
-
- ๐ฏ **Strongly-typed** field components with automatic TypeScript inference
|
|
16
|
-
- ๐๏ธ **Dual entrypoints** for maximum flexibility:
|
|
17
|
-
- Default entrypoint for individual HeroUI packages (better tree-shaking)
|
|
18
|
-
- `/react` entrypoint for the aggregate `@heroui/react` (convenient single dependency)
|
|
19
|
-
- ๐ฆ **Optional dependencies** - install only what you need
|
|
20
|
-
- ๐ง **Global configuration** system for consistent styling across your app
|
|
21
|
-
- โ
**Zod integration** for schema-based validation with type safety
|
|
22
|
-
- ๐จ **Multiple layouts** (vertical, horizontal, grid) with responsive design
|
|
23
|
-
- โฟ **Accessibility-first** with HeroUI's built-in ARIA support
|
|
24
|
-
- ๐ณ **Tree-shakeable** for optimal bundle sizes
|
|
25
|
-
- ๐ **Rapid prototyping** with ConfigurableForm component
|
|
26
|
-
- ๐จ **Optional font picker** with Google Fonts integration
|
|
27
|
-
|
|
28
|
-
## ๐ Quick Start
|
|
29
|
-
|
|
30
|
-
### Option 1: All-in-One HeroUI Package (Recommended for Development)
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
npm install @rachelallyson/hero-hook-form @heroui/react react-hook-form zod
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
### Option 2: Individual HeroUI Packages (Recommended for Production)
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
npm install @rachelallyson/hero-hook-form react-hook-form zod
|
|
40
|
-
npm install @heroui/button @heroui/input @heroui/select # Only what you need
|
|
41
|
-
```
|
|
7
|
+
## ๐ Documentation
|
|
42
8
|
|
|
43
|
-
|
|
9
|
+
**Full documentation available at: [https://rachelallyson.github.io/hero-hook-form/](https://rachelallyson.github.io/hero-hook-form/)**
|
|
44
10
|
|
|
45
|
-
|
|
11
|
+
## Installation
|
|
46
12
|
|
|
47
13
|
```bash
|
|
48
|
-
npm install @rachelallyson/hero-hook-form
|
|
14
|
+
npm install @rachelallyson/hero-hook-form
|
|
49
15
|
```
|
|
50
16
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
### Basic Usage
|
|
17
|
+
## Quick Start
|
|
54
18
|
|
|
55
19
|
```tsx
|
|
56
|
-
import { ZodForm } from "@rachelallyson/hero-hook-form";
|
|
20
|
+
import { ZodForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
|
|
57
21
|
import { z } from "zod";
|
|
58
22
|
|
|
59
23
|
const schema = z.object({
|
|
60
|
-
email: z.string().email(
|
|
61
|
-
name: z.string().min(
|
|
24
|
+
email: z.string().email(),
|
|
25
|
+
name: z.string().min(2),
|
|
62
26
|
});
|
|
63
27
|
|
|
64
|
-
const config = {
|
|
65
|
-
schema,
|
|
66
|
-
fields: [
|
|
67
|
-
{ name: "name", type: "input", label: "Name" },
|
|
68
|
-
{ name: "email", type: "input", label: "Email", inputProps: { type: "email" } },
|
|
69
|
-
],
|
|
70
|
-
};
|
|
71
|
-
|
|
72
28
|
export function ContactForm() {
|
|
73
|
-
return <ZodForm config={config} onSubmit={console.log} />;
|
|
74
|
-
}
|
|
75
|
-
```
|
|
76
|
-
|
|
77
|
-
> ๐ **See [Installation Guide](./docs/installation.md) for detailed setup instructions and bundle optimization tips.**
|
|
78
|
-
|
|
79
|
-
## ๐ Why Hero Hook Form?
|
|
80
|
-
|
|
81
|
-
| Feature | Manual Setup | Hero Hook Form |
|
|
82
|
-
|---------|--------------|----------------|
|
|
83
|
-
| TypeScript | โ Manual types | โ
Automatic inference |
|
|
84
|
-
| Validation | โ Complex setup | โ
Built-in + Zod |
|
|
85
|
-
| Styling | โ Inconsistent | โ
Global defaults |
|
|
86
|
-
| Accessibility | โ Manual work | โ
HeroUI built-in |
|
|
87
|
-
| Bundle size | โ Large | โ
Tree-shakeable |
|
|
88
|
-
| Development | โ Slow | โ
Rapid prototyping |
|
|
89
|
-
|
|
90
|
-
## Requirements
|
|
91
|
-
|
|
92
|
-
- **React**: >=18.2 <20
|
|
93
|
-
- **React DOM**: >=18.2 <20
|
|
94
|
-
- **React Hook Form**: >=7 <8
|
|
95
|
-
- **HeroUI**: >=2 <3 (either individual packages or `@heroui/react`)
|
|
96
|
-
|
|
97
|
-
## Installation Options
|
|
98
|
-
|
|
99
|
-
### Option A: Individual HeroUI Packages (Recommended for Production)
|
|
100
|
-
|
|
101
|
-
Install only the HeroUI components you actually use for optimal bundle size:
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
# Minimal set that covers all included fields
|
|
105
|
-
npm i @rachelallyson/hero-hook-form react-hook-form \
|
|
106
|
-
@heroui/input @heroui/checkbox @heroui/radio @heroui/select \
|
|
107
|
-
@heroui/switch @heroui/button @heroui/spinner
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
Import from the package root:
|
|
111
|
-
|
|
112
|
-
```tsx
|
|
113
|
-
import { InputField, SelectField, CheckboxField, RadioGroupField, SwitchField, TextareaField, SubmitButton } from "@rachelallyson/hero-hook-form";
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
### Option B: Aggregate HeroUI Package (Recommended for Development)
|
|
117
|
-
|
|
118
|
-
Install the all-in-one HeroUI package for convenience:
|
|
119
|
-
|
|
120
|
-
```bash
|
|
121
|
-
npm i @rachelallyson/hero-hook-form react-hook-form @heroui/react
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
Import from the `/react` subpath:
|
|
125
|
-
|
|
126
|
-
```tsx
|
|
127
|
-
import { InputField, SelectField, CheckboxField, RadioGroupField, SwitchField, TextareaField, SubmitButton } from "@rachelallyson/hero-hook-form/react";
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
## Setup (recommended)
|
|
131
|
-
|
|
132
|
-
Most HeroUI apps wrap the app with the `HeroUIProvider` from `@heroui/system` and typically set up theming via `next-themes` or similar. Example (Next.js):
|
|
133
|
-
|
|
134
|
-
```tsx
|
|
135
|
-
import { HeroUIProvider } from "@heroui/system";
|
|
136
|
-
import { ThemeProvider } from "next-themes";
|
|
137
|
-
|
|
138
|
-
export function Providers({ children }: { children: React.ReactNode }) {
|
|
139
|
-
return (
|
|
140
|
-
<HeroUIProvider>
|
|
141
|
-
<ThemeProvider attribute="class" defaultTheme="dark">
|
|
142
|
-
{children}
|
|
143
|
-
</ThemeProvider>
|
|
144
|
-
</HeroUIProvider>
|
|
145
|
-
);
|
|
146
|
-
}
|
|
147
|
-
```
|
|
148
|
-
|
|
149
|
-
## Global configuration (defaults)
|
|
150
|
-
|
|
151
|
-
Set global defaults for all fields with `HeroHookFormProvider`. You can set a `common` bucket (applies to all supported components) and/or per-component buckets. Per-instance props always win.
|
|
152
|
-
|
|
153
|
-
Import the provider from the entrypoint you use (root or `/react`):
|
|
154
|
-
|
|
155
|
-
```tsx
|
|
156
|
-
import { HeroHookFormProvider } from "@rachelallyson/hero-hook-form"; // or "/react"
|
|
157
|
-
|
|
158
|
-
export function AppProviders({ children }: { children: React.ReactNode }) {
|
|
159
29
|
return (
|
|
160
|
-
<
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
variant: "faded",
|
|
168
|
-
radius: "sm",
|
|
169
|
-
labelPlacement: "outside",
|
|
170
|
-
},
|
|
171
|
-
// Component-specific defaults override 'common' for that component
|
|
172
|
-
input: { variant: "underlined" },
|
|
173
|
-
select: { variant: "flat" },
|
|
174
|
-
submitButton: { color: "secondary" },
|
|
30
|
+
<ZodForm
|
|
31
|
+
config={{
|
|
32
|
+
schema,
|
|
33
|
+
fields: [
|
|
34
|
+
FormFieldHelpers.input("name", "Name"),
|
|
35
|
+
FormFieldHelpers.input("email", "Email", "email"),
|
|
36
|
+
],
|
|
175
37
|
}}
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
</HeroHookFormProvider>
|
|
38
|
+
onSubmit={(data) => console.log(data)}
|
|
39
|
+
/>
|
|
179
40
|
);
|
|
180
41
|
}
|
|
181
42
|
```
|
|
182
43
|
|
|
183
|
-
|
|
184
|
-
1) `defaults.common`
|
|
185
|
-
2) `defaults.{component}` (e.g., `input`, `select`, `checkbox`, `radioGroup`, `switch`, `textarea`, `submitButton`)
|
|
186
|
-
3) Per-instance props (e.g., `inputProps`, `selectProps`, `checkboxProps`, etc.)
|
|
187
|
-
|
|
188
|
-
- Supported `common` keys (strongly typed and intersected across text-like controls):
|
|
189
|
-
- `color`, `size`, `variant`, `radius`, `labelPlacement`
|
|
190
|
-
- For toggles (`checkbox`, `radioGroup`, `switch`) and `submitButton`, only `color` and `size` are applied.
|
|
191
|
-
|
|
192
|
-
- Example instance override:
|
|
193
|
-
|
|
194
|
-
```tsx
|
|
195
|
-
<InputField
|
|
196
|
-
control={methods.control}
|
|
197
|
-
label="Name"
|
|
198
|
-
name="name"
|
|
199
|
-
inputProps={{ color: "danger" }} // overrides global defaults for this field
|
|
200
|
-
/>
|
|
201
|
-
```
|
|
44
|
+
## Key Features
|
|
202
45
|
|
|
203
|
-
-
|
|
46
|
+
- **๐ฏ Type Safety** - Full TypeScript support with automatic type inference
|
|
47
|
+
- **๐จ HeroUI Integration** - Beautiful, accessible components out of the box
|
|
48
|
+
- **โก Performance** - Optimized with React.memo and debounced validation
|
|
49
|
+
- **๐ง Flexible APIs** - Multiple form building patterns to suit your needs
|
|
50
|
+
- **๐ Zod Integration** - Seamless schema validation with Zod
|
|
51
|
+
- **๐ Dynamic Forms** - Conditional fields, field arrays, and dynamic sections
|
|
52
|
+
- **๐งช Testing Ready** - Built-in testing utilities for Cypress
|
|
53
|
+
- **๐ Next.js Server Actions** - Compatible with Next.js authentication patterns
|
|
204
54
|
|
|
205
|
-
##
|
|
55
|
+
## Form Building Patterns
|
|
206
56
|
|
|
207
|
-
|
|
57
|
+
### 1. Helper Functions (Recommended)
|
|
208
58
|
|
|
209
|
-
```
|
|
210
|
-
|
|
59
|
+
```tsx
|
|
60
|
+
const fields = [
|
|
61
|
+
FormFieldHelpers.input("name", "Name"),
|
|
62
|
+
FormFieldHelpers.textarea("message", "Message"),
|
|
63
|
+
FormFieldHelpers.select("country", "Country", options),
|
|
64
|
+
];
|
|
211
65
|
```
|
|
212
66
|
|
|
213
|
-
|
|
67
|
+
### 2. Builder Pattern
|
|
214
68
|
|
|
215
69
|
```tsx
|
|
216
|
-
import {
|
|
217
|
-
import { ZodForm, createZodFormConfig } from "@rachelallyson/hero-hook-form";
|
|
218
|
-
|
|
219
|
-
// Define your schema
|
|
220
|
-
const contactSchema = z.object({
|
|
221
|
-
firstName: z.string().min(2, "First name must be at least 2 characters"),
|
|
222
|
-
email: z.string().email("Please enter a valid email address"),
|
|
223
|
-
message: z.string().min(10, "Message must be at least 10 characters"),
|
|
224
|
-
terms: z.boolean().refine((val) => val === true, "You must agree to the terms"),
|
|
225
|
-
});
|
|
70
|
+
import { createBasicFormBuilder } from "@rachelallyson/hero-hook-form";
|
|
226
71
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
{ name: "terms", type: "checkbox", label: "I agree to the terms" },
|
|
233
|
-
]);
|
|
234
|
-
|
|
235
|
-
// Use in your component
|
|
236
|
-
<ZodForm
|
|
237
|
-
config={config}
|
|
238
|
-
onSubmit={handleSubmit}
|
|
239
|
-
title="Contact Form"
|
|
240
|
-
showResetButton={true}
|
|
241
|
-
/>
|
|
72
|
+
const fields = createBasicFormBuilder()
|
|
73
|
+
.input("name", "Name")
|
|
74
|
+
.textarea("message", "Message")
|
|
75
|
+
.select("country", "Country", options)
|
|
76
|
+
.build();
|
|
242
77
|
```
|
|
243
78
|
|
|
244
|
-
###
|
|
245
|
-
|
|
246
|
-
For nested field names and radio buttons:
|
|
79
|
+
### 3. Type-Inferred Forms
|
|
247
80
|
|
|
248
81
|
```tsx
|
|
249
|
-
|
|
250
|
-
fonts: z.object({
|
|
251
|
-
scale: z.enum(["small", "medium", "large"]).default("medium"),
|
|
252
|
-
}),
|
|
253
|
-
layout: z.object({
|
|
254
|
-
sidebarPosition: z.enum(["left", "right", "hidden"]).default("left"),
|
|
255
|
-
}),
|
|
256
|
-
style: z.object({
|
|
257
|
-
theme: z.enum(["light", "dark", "auto"]).default("auto"),
|
|
258
|
-
}),
|
|
259
|
-
});
|
|
82
|
+
import { defineInferredForm, field } from "@rachelallyson/hero-hook-form";
|
|
260
83
|
|
|
261
|
-
const
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
label: "Font Scale",
|
|
266
|
-
radioOptions: [
|
|
267
|
-
{ label: "Small", value: "small" },
|
|
268
|
-
{ label: "Medium", value: "medium" },
|
|
269
|
-
{ label: "Large", value: "large" },
|
|
270
|
-
],
|
|
271
|
-
},
|
|
272
|
-
{
|
|
273
|
-
name: "layout.sidebarPosition",
|
|
274
|
-
type: "radio",
|
|
275
|
-
label: "Sidebar Position",
|
|
276
|
-
radioOptions: [
|
|
277
|
-
{ label: "Left", value: "left" },
|
|
278
|
-
{ label: "Right", value: "right" },
|
|
279
|
-
{ label: "Hidden", value: "hidden" },
|
|
280
|
-
],
|
|
281
|
-
},
|
|
282
|
-
{
|
|
283
|
-
name: "style.theme",
|
|
284
|
-
type: "radio",
|
|
285
|
-
label: "Theme",
|
|
286
|
-
radioOptions: [
|
|
287
|
-
{ label: "Light", value: "light" },
|
|
288
|
-
{ label: "Dark", value: "dark" },
|
|
289
|
-
{ label: "Auto", value: "auto" },
|
|
290
|
-
],
|
|
291
|
-
},
|
|
292
|
-
], {
|
|
293
|
-
defaultValues: {
|
|
294
|
-
fonts: { scale: "large" },
|
|
295
|
-
layout: { sidebarPosition: "right" },
|
|
296
|
-
style: { theme: "auto" },
|
|
297
|
-
},
|
|
84
|
+
const form = defineInferredForm({
|
|
85
|
+
name: field.string("Name"),
|
|
86
|
+
email: field.email("Email"),
|
|
87
|
+
age: field.number("Age"),
|
|
298
88
|
});
|
|
299
89
|
```
|
|
300
90
|
|
|
301
|
-
###
|
|
302
|
-
|
|
303
|
-
- **Type Safety**: Full TypeScript support with automatic type inference
|
|
304
|
-
- **Nested Fields**: Support for nested field names like "fonts.scale"
|
|
305
|
-
- **Default Values**: Proper handling of default values with nested structure
|
|
306
|
-
- **Radio Buttons**: Easy configuration with `radioOptions`
|
|
307
|
-
|
|
308
|
-
## ๐ฏ Examples
|
|
91
|
+
### 4. Next.js Server Actions
|
|
309
92
|
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
- [๐จ Layouts](./docs/layouts.md) - Form layout options
|
|
323
|
-
- [๐ API Reference](./docs/api-reference.md) - Complete API documentation
|
|
324
|
-
|
|
325
|
-
## ๐ง API Overview
|
|
326
|
-
|
|
327
|
-
### Field Components
|
|
328
|
-
|
|
329
|
-
All field components are strongly typed and expose component-specific props:
|
|
330
|
-
|
|
331
|
-
- **`InputField`** - Text inputs with validation
|
|
332
|
-
- **`TextareaField`** - Multi-line text inputs
|
|
333
|
-
- **`SelectField`** - Dropdown selections
|
|
334
|
-
- **`RadioGroupField`** - Radio button groups
|
|
335
|
-
- **`CheckboxField`** - Single checkboxes
|
|
336
|
-
- **`SwitchField`** - Toggle switches
|
|
337
|
-
- **`SliderField`** - Range slider inputs
|
|
338
|
-
- **`DateField`** - Date picker inputs
|
|
339
|
-
- **`FileField`** - File upload inputs
|
|
340
|
-
- **`FontPickerField`** - Optional font selection (requires `@rachelallyson/heroui-font-picker`)
|
|
341
|
-
|
|
342
|
-
### Form Components
|
|
343
|
-
|
|
344
|
-
- **`Form`** - Light wrapper around React Hook Form's FormProvider
|
|
345
|
-
- **`FormField`** - Generic field wrapper component
|
|
346
|
-
- **`ZodForm`** - Schema-based forms with Zod validation
|
|
347
|
-
- **`ConfigurableForm`** - Rapid form development with declarative config
|
|
348
|
-
|
|
349
|
-
### Utilities & Hooks
|
|
350
|
-
|
|
351
|
-
- **`applyServerErrors`** - Map API validation errors to form fields
|
|
352
|
-
- **`HeroHookFormProvider`** - Global configuration for consistent styling
|
|
353
|
-
- **`useHeroForm`** - Enhanced form hook with additional utilities
|
|
354
|
-
- **`useFormHelper`** - Form helper utilities
|
|
355
|
-
|
|
356
|
-
For complete API documentation, see [API Reference](./docs/api-reference.md).
|
|
357
|
-
|
|
358
|
-
## ๐ฏ Entrypoint Selection
|
|
359
|
-
|
|
360
|
-
- **Default entrypoint**: For apps using individual HeroUI packages (better tree-shaking)
|
|
361
|
-
- **`/react` entrypoint**: For apps using `@heroui/react` (convenient single dependency)
|
|
362
|
-
|
|
363
|
-
Both entrypoints are fully tree-shakeable and support all features.
|
|
364
|
-
|
|
365
|
-
## โ FAQ
|
|
366
|
-
|
|
367
|
-
<details>
|
|
368
|
-
<summary><strong>Do I need to wrap with HeroUIProvider?</strong></summary>
|
|
369
|
-
|
|
370
|
-
Recommended for proper styling and navigation integration. Most HeroUI apps already do this.
|
|
93
|
+
```tsx
|
|
94
|
+
import { ServerActionForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
|
|
95
|
+
import { signup } from "@/app/actions/auth";
|
|
96
|
+
|
|
97
|
+
<ServerActionForm
|
|
98
|
+
action={signup}
|
|
99
|
+
fields={[
|
|
100
|
+
FormFieldHelpers.input("name", "Name"),
|
|
101
|
+
FormFieldHelpers.input("email", "Email", { type: "email" }),
|
|
102
|
+
]}
|
|
103
|
+
/>
|
|
104
|
+
```
|
|
371
105
|
|
|
372
|
-
|
|
106
|
+
## What's Included
|
|
373
107
|
|
|
374
|
-
|
|
375
|
-
|
|
108
|
+
- **Components**: `Form`, `FormField`, `ZodForm`, `ServerActionForm`, field components, `FormStatus`
|
|
109
|
+
- **Hooks**: `useFormHelper`, `useHeroForm`, `useEnhancedFormState`, `useDebouncedValidation`, `useInferredForm`
|
|
110
|
+
- **Builders**: `createBasicFormBuilder`, `createAdvancedBuilder`, `createTypeInferredBuilder`
|
|
111
|
+
- **Utils**: `applyServerErrors`, validation helpers, performance utilities, testing utilities
|
|
112
|
+
- **Zod Integration**: `ZodForm` component with automatic schema validation
|
|
113
|
+
- **Next.js Support**: `ServerActionForm` for Next.js Server Actions and authentication
|
|
376
114
|
|
|
377
|
-
|
|
115
|
+
## Setup
|
|
378
116
|
|
|
379
|
-
|
|
117
|
+
1. **Install the package**:
|
|
380
118
|
|
|
381
|
-
|
|
382
|
-
|
|
119
|
+
```bash
|
|
120
|
+
npm install @rachelallyson/hero-hook-form
|
|
121
|
+
```
|
|
383
122
|
|
|
384
|
-
|
|
123
|
+
2. **Set up your provider**:
|
|
385
124
|
|
|
386
|
-
|
|
125
|
+
```tsx
|
|
126
|
+
import { HeroHookFormProvider } from "@rachelallyson/hero-hook-form";
|
|
127
|
+
|
|
128
|
+
function App() {
|
|
129
|
+
return (
|
|
130
|
+
<HeroHookFormProvider>
|
|
131
|
+
<YourForms />
|
|
132
|
+
</HeroHookFormProvider>
|
|
133
|
+
);
|
|
134
|
+
}
|
|
135
|
+
```
|
|
387
136
|
|
|
388
|
-
|
|
389
|
-
<summary><strong>What's the difference between the two entrypoints?</strong></summary>
|
|
137
|
+
3. **Create your first form**:
|
|
390
138
|
|
|
391
|
-
|
|
392
|
-
|
|
139
|
+
```tsx
|
|
140
|
+
import { ZodForm, FormFieldHelpers } from "@rachelallyson/hero-hook-form";
|
|
141
|
+
```
|
|
393
142
|
|
|
394
|
-
|
|
143
|
+
## Documentation Links
|
|
395
144
|
|
|
396
|
-
|
|
145
|
+
- **Quick Start Guide**: [https://rachelallyson.github.io/hero-hook-form/guides/quickstart](https://rachelallyson.github.io/hero-hook-form/guides/quickstart)
|
|
146
|
+
- **API Reference**: [https://rachelallyson.github.io/hero-hook-form/api/README](https://rachelallyson.github.io/hero-hook-form/api/README)
|
|
147
|
+
- **Next.js Server Actions**: [Next.js Authentication Guide](./docs/guides/nextjs-server-actions.md) - Use with Next.js auth forms
|
|
148
|
+
- **Dynamic Forms**: [https://rachelallyson.github.io/hero-hook-form/guides/dynamic-forms](https://rachelallyson.github.io/hero-hook-form/guides/dynamic-forms)
|
|
149
|
+
- **Error Handling**: [https://rachelallyson.github.io/hero-hook-form/guides/error-handling](https://rachelallyson.github.io/hero-hook-form/guides/error-handling)
|
|
150
|
+
- **Testing Guide**: [https://rachelallyson.github.io/hero-hook-form/guides/testing-guide](https://rachelallyson.github.io/hero-hook-form/guides/testing-guide)
|
|
151
|
+
- **Live Demos**: [https://rachelallyson.github.io/hero-hook-form/demo](https://rachelallyson.github.io/hero-hook-form/demo)
|
|
397
152
|
|
|
398
|
-
|
|
153
|
+
## What's New in v2.0
|
|
399
154
|
|
|
400
|
-
|
|
155
|
+
- **Dynamic Form Sections** - Conditional fields and field arrays
|
|
156
|
+
- **Enhanced Performance** - Memoized components and debounced validation
|
|
157
|
+
- **Type-Inferred Forms** - Alternative API with automatic schema generation
|
|
158
|
+
- **Form State Management** - Enhanced state tracking and status components
|
|
159
|
+
- **Validation Patterns** - Cross-field validation and common patterns
|
|
401
160
|
|
|
402
|
-
|
|
161
|
+
## Requirements
|
|
403
162
|
|
|
404
|
-
|
|
163
|
+
- React >= 18.2.0
|
|
164
|
+
- React Hook Form >= 7
|
|
165
|
+
- Zod >= 4
|
|
166
|
+
- HeroUI components (peer dependencies)
|
|
405
167
|
|
|
406
|
-
|
|
168
|
+
## License
|
|
407
169
|
|
|
408
|
-
|
|
170
|
+
ISC License - see [LICENSE](LICENSE) for details.
|
|
409
171
|
|
|
410
|
-
|
|
172
|
+
## Community
|
|
411
173
|
|
|
412
|
-
|
|
174
|
+
- **GitHub**: [rachelallyson/hero-hook-form](https://github.com/rachelallyson/hero-hook-form)
|
|
175
|
+
- **Issues**: [Report bugs or request features](https://github.com/rachelallyson/hero-hook-form/issues)
|
|
176
|
+
- **Documentation**: [https://rachelallyson.github.io/hero-hook-form/](https://rachelallyson.github.io/hero-hook-form/)
|