form-generator-rhf-zod

What this skill does

# Form Generator with React Hook Form & Zod

Generate production-ready React forms using React Hook Form, Zod validation schemas, and accessible shadcn/ui form controls. This skill creates forms with client-side and server-side validation, proper TypeScript types, and consistent error handling.

## When to Use This Skill

Apply this skill when:
- Creating forms for entities (characters, locations, items, factions)
- Building data entry interfaces with validation requirements
- Generating forms with complex field types and conditional logic
- Setting up forms that need both client and server validation
- Creating accessible forms with proper ARIA attributes
- Building forms with multi-step or wizard patterns

## Resources Available

### Scripts

**scripts/generate_form.py** - Generates form component, Zod schema, and server action from field specifications.

Usage:
```bash
python scripts/generate_form.py --name CharacterForm --fields fields.json --output components/forms
```

**scripts/generate_zod_schema.py** - Converts field specifications to Zod schema with validation rules.

Usage:
```bash
python scripts/generate_zod_schema.py --fields fields.json --output lib/schemas
```

### References

**references/rhf-patterns.md** - React Hook Form patterns, hooks, and best practices
**references/zod-validation.md** - Zod schema patterns, refinements, and custom validators
**references/shadcn-form-controls.md** - shadcn/ui form component usage and examples
**references/server-actions.md** - Server action patterns for form submission

### Assets

**assets/form-template.tsx** - Base form component template with RHF setup
**assets/field-templates/** - Individual field component templates (Input, Textarea, Select, Checkbox, etc.)
**assets/validation-schemas.ts** - Common Zod validation patterns
**assets/form-utils.ts** - Form utility functions (formatters, transformers, validators)

## Form Generation Process

### Step 1: Define Field Specifications

Create a field specification file describing form fields, types, validation rules, and UI properties.

Field specification format:
```json
{
  "fields": [
    {
      "name": "characterName",
      "label": "Character Name",
      "type": "text",
      "required": true,
      "validation": {
        "minLength": 2,
        "maxLength": 100,
        "pattern": "^[a-zA-Z\\s'-]+$"
      },
      "placeholder": "Enter character name",
      "helpText": "The character's full name as it appears in your world"
    },
    {
      "name": "age",
      "label": "Age",
      "type": "number",
      "required": false,
      "validation": {
        "min": 0,
        "max": 10000
      }
    },
    {
      "name": "faction",
      "label": "Faction",
      "type": "select",
      "required": true,
      "options": "dynamic",
      "optionsSource": "api.getFactions()"
    },
    {
      "name": "biography",
      "label": "Biography",
      "type": "textarea",
      "required": false,
      "validation": {
        "maxLength": 5000
      },
      "rows": 8
    }
  ],
  "formOptions": {
    "submitLabel": "Create Character",
    "resetLabel": "Clear Form",
    "showReset": true,
    "successMessage": "Character created successfully",
    "errorMessage": "Failed to create character"
  }
}
```

### Step 2: Generate Zod Schema

Use scripts/generate_zod_schema.py to create type-safe validation schema:

```bash
python scripts/generate_zod_schema.py --fields character-fields.json --output lib/schemas/character.ts
```

Generated schema includes:
- Field-level validation rules
- Custom refinements and transformations
- Type inference for TypeScript
- Error message customization
- Server-side validation support

### Step 3: Generate Form Component

Use scripts/generate_form.py to create React Hook Form component:

```bash
python scripts/generate_form.py --name CharacterForm --fields character-fields.json --output components/forms
```

Generated component includes:
- React Hook Form setup with useForm hook
- Zod schema resolver integration
- shadcn/ui FormField components
- Proper TypeScript types inferred from schema
- Accessible form controls with ARIA labels
- Error display with FormMessage components
- Form submission handler with loading states
- Success/error toast notifications

### Step 4: Create Server Action

Generate server action for form submission with server-side validation:

```typescript
'use server'

import { z } from 'zod'
import { characterSchema } from '@/lib/schemas/character'
import { createCharacter } from '@/lib/db/characters'

export async function createCharacterAction(data: z.infer<typeof characterSchema>) {
  // Server-side validation
  const validated = characterSchema.safeParse(data)

  if (!validated.success) {
    return {
      success: false,
      errors: validated.error.flatten().fieldErrors
    }
  }

  // Database operation
  const character = await createCharacter(validated.data)

  return {
    success: true,
    data: character
  }
}
```

### Step 5: Integrate Form into Page

Import and use generated form component in page or parent component:

```tsx
import { CharacterForm } from '@/components/forms/CharacterForm'

export default function CreateCharacterPage() {
  return (
    <div className="container max-w-2xl py-8">
      <h1 className="text-3xl font-bold mb-6">Create New Character</h1>
      <CharacterForm />
    </div>
  )
}
```

## Field Type Support

Supported field types and their shadcn/ui mappings:

- **text** → Input (type="text")
- **email** → Input (type="email")
- **password** → Input (type="password")
- **number** → Input (type="number")
- **tel** → Input (type="tel")
- **url** → Input (type="url")
- **textarea** → Textarea
- **select** → Select with SelectTrigger/SelectContent
- **multiselect** → MultiSelect custom component
- **checkbox** → Checkbox
- **radio** → RadioGroup with RadioGroupItem
- **switch** → Switch
- **date** → DatePicker (Popover + Calendar)
- **datetime** → DateTimePicker custom component
- **file** → Input (type="file")
- **combobox** → Combobox (Command + Popover)
- **tags** → TagInput custom component
- **slider** → Slider
- **color** → ColorPicker custom component

## Validation Patterns

Common validation patterns using Zod:

### String Validation
```typescript
// Required with length constraints
z.string().min(2, "Too short").max(100, "Too long")

// Email
z.string().email("Invalid email")

// URL
z.string().url("Invalid URL")

// Pattern matching
z.string().regex(/^[a-zA-Z]+$/, "Letters only")

// Trimmed strings
z.string().trim().min(1)

// Custom transformation
z.string().transform(val => val.toLowerCase())
```

### Number Validation
```typescript
// Range validation
z.number().min(0).max(100)

// Integer only
z.number().int("Must be whole number")

// Positive numbers
z.number().positive("Must be positive")

// Custom refinement
z.number().refine(val => val % 5 === 0, "Must be multiple of 5")
```

### Array Validation
```typescript
// Array with min/max items
z.array(z.string()).min(1, "Select at least one").max(5, "Too many")

// Non-empty array
z.array(z.string()).nonempty("Required")
```

### Object Validation
```typescript
// Nested objects
z.object({
  address: z.object({
    street: z.string(),
    city: z.string(),
    zipCode: z.string().regex(/^\d{5}$/)
  })
})
```

### Conditional Validation
```typescript
// Refine with cross-field validation
z.object({
  password: z.string().min(8),
  confirmPassword: z.string()
}).refine(data => data.password === data.confirmPassword, {
  message: "Passwords must match",
  path: ["confirmPassword"]
})
```

### Optional and Nullable Fields
```typescript
// Optional (can be undefined)
z.string().optional()

// Nullable (can be null)
z.string().nullable()

// Optional with default
z.string().default("default value")
```

## Form Patterns

### Basic Form Structure

```tsx
'use client'

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { z } from 'zod'
import