ai-qakit 1.0.0

package/templates/.claude/commands/devkit/frontend/create-form.md

@@ -0,0 +1,804 @@
+---
+description: Generate form component with validation following project patterns
+argument-hint: [form-description]
+allowed-tools: Read, Grep, Write, Edit, AskUserQuestion
+---
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Create Form
+
+Generate form for: $ARGUMENTS
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the request and show form design
+2. Display the form fields with validation rules
+3. Show all files that will be created
+4. Ask for confirmation before writing files
+5. Never create forms without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What fields should this form include?"
+- "What validation rules apply to each field?"
+- "Should this be a create form, edit form, or both?"
+- "What should happen on successful submission?"
+- "Does this form need multi-step wizard functionality?"
+- "Should I include loading states and error handling?"
+- "Are there any conditional fields (show/hide based on values)?"
+- "Should fields have default values for edit mode?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- Form library (React Hook Form, Formik, native)
+- Validation library (Zod, Yup, Joi)
+- UI components (shadcn/ui, MUI, custom)
+- Styling approach
+- Error display patterns
+- Toast/notification system
+- API integration patterns
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Parse Request
+
+Analyze "$ARGUMENTS" to determine:
+- Form name (UserForm, LoginForm, ProductForm)
+- Form type (create, edit, create/edit combined)
+- Fields required
+- Validation rules
+- Submission handler
+- Success/error handling
+
+**Common form types:**
+- `Login` - Authentication (email, password)
+- `Register` - User registration (name, email, password, confirm)
+- `Profile` - User profile edit
+- `Search` - Search/filter forms
+- `CRUD` - Create/Edit entity forms
+- `Wizard` - Multi-step forms
+- `Settings` - Configuration forms
+
+## Step 3: Review Existing Forms
+
+Find and analyze existing forms to detect:
+- Form library patterns
+- Field component usage
+- Validation approach
+- Error display style
+- Submit button patterns
+- Loading state handling
+- Form layout patterns
+
+## Step 4: Define Schema
+
+### With Zod
+
+```typescript
+// schemas/userSchema.ts
+import { z } from 'zod'
+
+export const createUserSchema = z.object({
+  name: z
+    .string()
+    .min(2, 'Name must be at least 2 characters')
+    .max(50, 'Name must be less than 50 characters'),
+  email: z
+    .string()
+    .email('Invalid email address'),
+  password: z
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Password must contain an uppercase letter')
+    .regex(/[0-9]/, 'Password must contain a number'),
+  confirmPassword: z.string(),
+  role: z.enum(['admin', 'user']).default('user'),
+  bio: z.string().max(500).optional(),
+  avatar: z.instanceof(File).optional(),
+}).refine((data) => data.password === data.confirmPassword, {
+  message: 'Passwords do not match',
+  path: ['confirmPassword'],
+})
+
+export const updateUserSchema = createUserSchema
+  .omit({ password: true, confirmPassword: true })
+  .partial()
+
+export type CreateUserInput = z.infer<typeof createUserSchema>
+export type UpdateUserInput = z.infer<typeof updateUserSchema>
+```
+
+### With Yup
+
+```typescript
+// schemas/userSchema.ts
+import * as yup from 'yup'
+
+export const createUserSchema = yup.object({
+  name: yup
+    .string()
+    .min(2, 'Name must be at least 2 characters')
+    .max(50, 'Name must be less than 50 characters')
+    .required('Name is required'),
+  email: yup
+    .string()
+    .email('Invalid email address')
+    .required('Email is required'),
+  password: yup
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .matches(/[A-Z]/, 'Password must contain an uppercase letter')
+    .matches(/[0-9]/, 'Password must contain a number')
+    .required('Password is required'),
+  confirmPassword: yup
+    .string()
+    .oneOf([yup.ref('password')], 'Passwords do not match')
+    .required('Please confirm your password'),
+  role: yup.string().oneOf(['admin', 'user']).default('user'),
+  bio: yup.string().max(500).optional(),
+})
+
+export type CreateUserInput = yup.InferType<typeof createUserSchema>
+```
+
+## Step 5: Generate Form Component
+
+### React Hook Form + Zod + shadcn/ui
+
+```typescript
+// components/forms/UserForm.tsx
+'use client'
+
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { createUserSchema, type CreateUserInput } from '@/schemas/userSchema'
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/ui/form'
+import { Input } from '@/components/ui/input'
+import { Button } from '@/components/ui/button'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import { Textarea } from '@/components/ui/textarea'
+import { Loader2 } from 'lucide-react'
+
+interface UserFormProps {
+  defaultValues?: Partial<CreateUserInput>
+  onSubmit: (data: CreateUserInput) => Promise<void>
+  isLoading?: boolean
+  submitLabel?: string
+}
+
+export function UserForm({
+  defaultValues,
+  onSubmit,
+  isLoading = false,
+  submitLabel = 'Submit',
+}: UserFormProps) {
+  const form = useForm<CreateUserInput>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: {
+      name: '',
+      email: '',
+      password: '',
+      confirmPassword: '',
+      role: 'user',
+      bio: '',
+      ...defaultValues,
+    },
+  })
+
+  const handleSubmit = form.handleSubmit(async (data) => {
+    try {
+      await onSubmit(data)
+      form.reset()
+    } catch (error) {
+      // Error handling done by parent
+    }
+  })
+
+  return (
+    <Form {...form}>
+      <form onSubmit={handleSubmit} className="space-y-6">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl>
+                <Input placeholder="John Doe" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input type="email" placeholder="john@example.com" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="password"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Password</FormLabel>
+              <FormControl>
+                <Input type="password" placeholder="••••••••" {...field} />
+              </FormControl>
+              <FormDescription>
+                Must be at least 8 characters with uppercase and number
+              </FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="confirmPassword"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Confirm Password</FormLabel>
+              <FormControl>
+                <Input type="password" placeholder="••••••••" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="role"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Role</FormLabel>
+              <Select onValueChange={field.onChange} defaultValue={field.value}>
+                <FormControl>
+                  <SelectTrigger>
+                    <SelectValue placeholder="Select a role" />
+                  </SelectTrigger>
+                </FormControl>
+                <SelectContent>
+                  <SelectItem value="user">User</SelectItem>
+                  <SelectItem value="admin">Admin</SelectItem>
+                </SelectContent>
+              </Select>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="bio"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Bio (Optional)</FormLabel>
+              <FormControl>
+                <Textarea
+                  placeholder="Tell us about yourself..."
+                  className="resize-none"
+                  {...field}
+                />
+              </FormControl>
+              <FormDescription>
+                Maximum 500 characters
+              </FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <Button type="submit" disabled={isLoading} className="w-full">
+          {isLoading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+          {submitLabel}
+        </Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+### React Hook Form + Yup + Custom Components
+
+```typescript
+// components/forms/UserForm.tsx
+'use client'
+
+import { useForm } from 'react-hook-form'
+import { yupResolver } from '@hookform/resolvers/yup'
+import { createUserSchema, type CreateUserInput } from '@/schemas/userSchema'
+import { Input } from '@/components/ui/Input'
+import { Select } from '@/components/ui/Select'
+import { Button } from '@/components/ui/Button'
+
+interface UserFormProps {
+  defaultValues?: Partial<CreateUserInput>
+  onSubmit: (data: CreateUserInput) => Promise<void>
+  isLoading?: boolean
+}
+
+export function UserForm({ defaultValues, onSubmit, isLoading }: UserFormProps) {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors },
+    reset,
+  } = useForm<CreateUserInput>({
+    resolver: yupResolver(createUserSchema),
+    defaultValues,
+  })
+
+  const onFormSubmit = handleSubmit(async (data) => {
+    await onSubmit(data)
+    reset()
+  })
+
+  return (
+    <form onSubmit={onFormSubmit} className="space-y-4">
+      <Input
+        label="Name"
+        error={errors.name?.message}
+        {...register('name')}
+      />
+
+      <Input
+        label="Email"
+        type="email"
+        error={errors.email?.message}
+        {...register('email')}
+      />
+
+      <Input
+        label="Password"
+        type="password"
+        error={errors.password?.message}
+        {...register('password')}
+      />
+
+      <Select
+        label="Role"
+        error={errors.role?.message}
+        options={[
+          { value: 'user', label: 'User' },
+          { value: 'admin', label: 'Admin' },
+        ]}
+        {...register('role')}
+      />
+
+      <Button type="submit" isLoading={isLoading}>
+        Submit
+      </Button>
+    </form>
+  )
+}
+```
+
+### Formik + Yup
+
+```typescript
+// components/forms/UserForm.tsx
+import { Formik, Form, Field, ErrorMessage } from 'formik'
+import { createUserSchema, type CreateUserInput } from '@/schemas/userSchema'
+import { Input } from '@/components/ui/Input'
+import { Button } from '@/components/ui/Button'
+
+interface UserFormProps {
+  initialValues?: Partial<CreateUserInput>
+  onSubmit: (data: CreateUserInput) => Promise<void>
+}
+
+const defaultInitialValues: CreateUserInput = {
+  name: '',
+  email: '',
+  password: '',
+  confirmPassword: '',
+  role: 'user',
+}
+
+export function UserForm({ initialValues, onSubmit }: UserFormProps) {
+  return (
+    <Formik
+      initialValues={{ ...defaultInitialValues, ...initialValues }}
+      validationSchema={createUserSchema}
+      onSubmit={async (values, { setSubmitting, resetForm }) => {
+        try {
+          await onSubmit(values)
+          resetForm()
+        } finally {
+          setSubmitting(false)
+        }
+      }}
+    >
+      {({ isSubmitting, errors, touched }) => (
+        <Form className="space-y-4">
+          <div>
+            <label htmlFor="name">Name</label>
+            <Field name="name" as={Input} />
+            <ErrorMessage name="name" component="span" className="text-red-500" />
+          </div>
+
+          <div>
+            <label htmlFor="email">Email</label>
+            <Field name="email" type="email" as={Input} />
+            <ErrorMessage name="email" component="span" className="text-red-500" />
+          </div>
+
+          <div>
+            <label htmlFor="password">Password</label>
+            <Field name="password" type="password" as={Input} />
+            <ErrorMessage name="password" component="span" className="text-red-500" />
+          </div>
+
+          <Button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? 'Submitting...' : 'Submit'}
+          </Button>
+        </Form>
+      )}
+    </Formik>
+  )
+}
+```
+
+## Step 6: Multi-Step Form (Wizard)
+
+```typescript
+// components/forms/RegistrationWizard.tsx
+'use client'
+
+import { useState } from 'react'
+import { useForm, FormProvider } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+import { Button } from '@/components/ui/button'
+import { Progress } from '@/components/ui/progress'
+
+const step1Schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+})
+
+const step2Schema = z.object({
+  firstName: z.string().min(2),
+  lastName: z.string().min(2),
+})
+
+const step3Schema = z.object({
+  company: z.string().optional(),
+  role: z.string(),
+})
+
+const fullSchema = step1Schema.merge(step2Schema).merge(step3Schema)
+type FormData = z.infer<typeof fullSchema>
+
+const steps = [
+  { title: 'Account', schema: step1Schema },
+  { title: 'Profile', schema: step2Schema },
+  { title: 'Details', schema: step3Schema },
+]
+
+export function RegistrationWizard({ onSubmit }: { onSubmit: (data: FormData) => Promise<void> }) {
+  const [currentStep, setCurrentStep] = useState(0)
+
+  const methods = useForm<FormData>({
+    resolver: zodResolver(steps[currentStep].schema),
+    mode: 'onChange',
+  })
+
+  const progress = ((currentStep + 1) / steps.length) * 100
+
+  const handleNext = async () => {
+    const isValid = await methods.trigger()
+    if (isValid && currentStep < steps.length - 1) {
+      setCurrentStep(currentStep + 1)
+    }
+  }
+
+  const handleBack = () => {
+    if (currentStep > 0) {
+      setCurrentStep(currentStep - 1)
+    }
+  }
+
+  const handleSubmit = methods.handleSubmit(async (data) => {
+    if (currentStep === steps.length - 1) {
+      await onSubmit(data)
+    } else {
+      handleNext()
+    }
+  })
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={handleSubmit} className="space-y-6">
+        <Progress value={progress} className="mb-4" />
+
+        <div className="flex justify-between mb-4">
+          {steps.map((step, index) => (
+            <span
+              key={step.title}
+              className={index <= currentStep ? 'text-primary' : 'text-muted'}
+            >
+              {step.title}
+            </span>
+          ))}
+        </div>
+
+        {currentStep === 0 && <Step1Fields />}
+        {currentStep === 1 && <Step2Fields />}
+        {currentStep === 2 && <Step3Fields />}
+
+        <div className="flex justify-between">
+          <Button
+            type="button"
+            variant="outline"
+            onClick={handleBack}
+            disabled={currentStep === 0}
+          >
+            Back
+          </Button>
+          <Button type="submit">
+            {currentStep === steps.length - 1 ? 'Submit' : 'Next'}
+          </Button>
+        </div>
+      </form>
+    </FormProvider>
+  )
+}
+```
+
+## Step 7: Conditional Fields
+
+```typescript
+// components/forms/ConditionalForm.tsx
+import { useFormContext, useWatch } from 'react-hook-form'
+
+function ConditionalFields() {
+  const { control } = useFormContext()
+  const accountType = useWatch({ control, name: 'accountType' })
+
+  return (
+    <>
+      <FormField
+        control={control}
+        name="accountType"
+        render={({ field }) => (
+          <FormItem>
+            <FormLabel>Account Type</FormLabel>
+            <Select onValueChange={field.onChange} defaultValue={field.value}>
+              <SelectTrigger>
+                <SelectValue placeholder="Select type" />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="personal">Personal</SelectItem>
+                <SelectItem value="business">Business</SelectItem>
+              </SelectContent>
+            </Select>
+          </FormItem>
+        )}
+      />
+
+      {accountType === 'business' && (
+        <>
+          <FormField
+            control={control}
+            name="companyName"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Company Name</FormLabel>
+                <FormControl>
+                  <Input {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+
+          <FormField
+            control={control}
+            name="taxId"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Tax ID</FormLabel>
+                <FormControl>
+                  <Input {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </>
+      )}
+    </>
+  )
+}
+```
+
+## Step 8: Generate Tests
+
+```typescript
+// components/forms/UserForm.test.tsx
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { UserForm } from './UserForm'
+
+describe('UserForm', () => {
+  const mockOnSubmit = vi.fn()
+
+  beforeEach(() => {
+    mockOnSubmit.mockClear()
+  })
+
+  it('renders all form fields', () => {
+    render(<UserForm onSubmit={mockOnSubmit} />)
+
+    expect(screen.getByLabelText(/name/i)).toBeInTheDocument()
+    expect(screen.getByLabelText(/email/i)).toBeInTheDocument()
+    expect(screen.getByLabelText(/password/i)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument()
+  })
+
+  it('shows validation errors for empty required fields', async () => {
+    const user = userEvent.setup()
+    render(<UserForm onSubmit={mockOnSubmit} />)
+
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+
+    await waitFor(() => {
+      expect(screen.getByText(/name is required/i)).toBeInTheDocument()
+    })
+  })
+
+  it('shows validation error for invalid email', async () => {
+    const user = userEvent.setup()
+    render(<UserForm onSubmit={mockOnSubmit} />)
+
+    await user.type(screen.getByLabelText(/email/i), 'invalid-email')
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+
+    await waitFor(() => {
+      expect(screen.getByText(/invalid email/i)).toBeInTheDocument()
+    })
+  })
+
+  it('submits form with valid data', async () => {
+    const user = userEvent.setup()
+    render(<UserForm onSubmit={mockOnSubmit} />)
+
+    await user.type(screen.getByLabelText(/name/i), 'John Doe')
+    await user.type(screen.getByLabelText(/email/i), 'john@example.com')
+    await user.type(screen.getByLabelText(/^password$/i), 'Password123')
+    await user.type(screen.getByLabelText(/confirm password/i), 'Password123')
+    await user.click(screen.getByRole('button', { name: /submit/i }))
+
+    await waitFor(() => {
+      expect(mockOnSubmit).toHaveBeenCalledWith({
+        name: 'John Doe',
+        email: 'john@example.com',
+        password: 'Password123',
+        confirmPassword: 'Password123',
+        role: 'user',
+        bio: '',
+      })
+    })
+  })
+
+  it('shows loading state during submission', async () => {
+    render(<UserForm onSubmit={mockOnSubmit} isLoading />)
+
+    expect(screen.getByRole('button', { name: /submit/i })).toBeDisabled()
+  })
+
+  it('populates default values in edit mode', () => {
+    render(
+      <UserForm
+        onSubmit={mockOnSubmit}
+        defaultValues={{ name: 'Jane Doe', email: 'jane@example.com' }}
+      />
+    )
+
+    expect(screen.getByLabelText(/name/i)).toHaveValue('Jane Doe')
+    expect(screen.getByLabelText(/email/i)).toHaveValue('jane@example.com')
+  })
+})
+```
+
+## Step 9: Show Generated Files
+
+Display:
+1. All file paths to create
+2. Full content for each file
+3. Form structure diagram:
+
+```
+┌─────────────────────────────────────┐
+│ Form: UserForm                      │
+├─────────────────────────────────────┤
+│ Library: React Hook Form + Zod     │
+│ UI: shadcn/ui                       │
+│ Mode: Create/Edit                   │
+├─────────────────────────────────────┤
+│ Fields:                             │
+│   - name (text, required)           │
+│   - email (email, required)         │
+│   - password (password, required)   │
+│   - confirmPassword (password)      │
+│   - role (select, default: user)    │
+│   - bio (textarea, optional)        │
+├─────────────────────────────────────┤
+│ Files:                              │
+│   - schemas/userSchema.ts           │
+│   - components/forms/UserForm.tsx   │
+│   - components/forms/UserForm.test.tsx │
+└─────────────────────────────────────┘
+```
+
+## Step 10: Usage Example
+
+```typescript
+import { UserForm } from '@/components/forms/UserForm'
+import { useCreateUser } from '@/hooks/users'
+import { toast } from 'sonner'
+
+function CreateUserPage() {
+  const createUser = useCreateUser()
+
+  const handleSubmit = async (data: CreateUserInput) => {
+    try {
+      await createUser.mutateAsync(data)
+      toast.success('User created successfully!')
+    } catch (error) {
+      toast.error('Failed to create user')
+    }
+  }
+
+  return (
+    <div className="max-w-md mx-auto">
+      <h1>Create User</h1>
+      <UserForm
+        onSubmit={handleSubmit}
+        isLoading={createUser.isPending}
+        submitLabel="Create User"
+      />
+    </div>
+  )
+}
+```
+
+Generate form now for: $ARGUMENTS