ai-qakit 1.0.0

package/templates/.claude/skills/frontend-development/references/forms.md

@@ -0,0 +1,809 @@
+# Forms
+
+React Hook Form with Zod validation patterns for type-safe forms.
+
+---
+
+## Setup
+
+```bash
+npm install react-hook-form zod @hookform/resolvers
+```
+
+---
+
+## Basic Form Pattern
+
+```tsx
+// features/auth/ui/LoginForm.tsx
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Button } from '@/shared/ui/button';
+import { Input } from '@/shared/ui/input';
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  FormDescription,
+} from '@/shared/ui/form';
+
+// 1. Define schema with Zod
+const loginSchema = z.object({
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+});
+
+// 2. Infer type from schema
+type LoginFormData = z.infer<typeof loginSchema>;
+
+interface LoginFormProps {
+  onSubmit: (data: LoginFormData) => Promise<void>;
+  isLoading?: boolean;
+}
+
+export const LoginForm: React.FC<LoginFormProps> = ({ onSubmit, isLoading }) => {
+  // 3. Initialize form with resolver
+  const form = useForm<LoginFormData>({
+    resolver: zodResolver(loginSchema),
+    defaultValues: {
+      email: '',
+      password: '',
+    },
+  });
+
+  // 4. Handle submit
+  const handleSubmit = async (data: LoginFormData) => {
+    try {
+      await onSubmit(data);
+    } catch (error) {
+      form.setError('root', {
+        message: 'Invalid credentials',
+      });
+    }
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input
+                  type="email"
+                  placeholder="you@example.com"
+                  autoComplete="email"
+                  {...field}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="password"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Password</FormLabel>
+              <FormControl>
+                <Input
+                  type="password"
+                  autoComplete="current-password"
+                  {...field}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        {form.formState.errors.root && (
+          <p className="text-sm text-destructive">
+            {form.formState.errors.root.message}
+          </p>
+        )}
+
+        <Button type="submit" className="w-full" disabled={isLoading}>
+          {isLoading ? 'Logging in...' : 'Login'}
+        </Button>
+      </form>
+    </Form>
+  );
+};
+```
+
+---
+
+## Zod Schema Patterns
+
+### Basic Validations
+
+```tsx
+const userSchema = z.object({
+  // Required string
+  name: z.string().min(1, 'Name is required'),
+  
+  // Email
+  email: z.string().email('Invalid email'),
+  
+  // Password with requirements
+  password: z
+    .string()
+    .min(8, 'At least 8 characters')
+    .regex(/[A-Z]/, 'At least one uppercase letter')
+    .regex(/[a-z]/, 'At least one lowercase letter')
+    .regex(/[0-9]/, 'At least one number'),
+  
+  // Optional field
+  bio: z.string().optional(),
+  
+  // Number
+  age: z.coerce.number().min(18, 'Must be 18 or older'),
+  
+  // Boolean
+  acceptTerms: z.literal(true, {
+    errorMap: () => ({ message: 'You must accept the terms' }),
+  }),
+  
+  // Enum / Select
+  role: z.enum(['admin', 'user', 'moderator']),
+  
+  // Date
+  birthDate: z.coerce.date().max(new Date(), 'Cannot be in the future'),
+  
+  // URL
+  website: z.string().url('Invalid URL').optional().or(z.literal('')),
+  
+  // Phone
+  phone: z.string().regex(/^\+?[\d\s-()]+$/, 'Invalid phone number'),
+});
+```
+
+### Password Confirmation
+
+```tsx
+const registerSchema = z
+  .object({
+    email: z.string().email(),
+    password: z.string().min(8),
+    confirmPassword: z.string(),
+  })
+  .refine((data) => data.password === data.confirmPassword, {
+    message: 'Passwords do not match',
+    path: ['confirmPassword'],
+  });
+```
+
+### Conditional Validation
+
+```tsx
+const profileSchema = z
+  .object({
+    isCompany: z.boolean(),
+    companyName: z.string().optional(),
+    personalName: z.string().optional(),
+  })
+  .refine(
+    (data) => {
+      if (data.isCompany) return !!data.companyName;
+      return !!data.personalName;
+    },
+    {
+      message: 'Required field missing',
+      path: ['companyName'],
+    }
+  );
+```
+
+### Array Validation
+
+```tsx
+const orderSchema = z.object({
+  items: z
+    .array(
+      z.object({
+        productId: z.string(),
+        quantity: z.number().min(1),
+        price: z.number().positive(),
+      })
+    )
+    .min(1, 'At least one item required'),
+});
+```
+
+### Transform and Preprocess
+
+```tsx
+const formSchema = z.object({
+  // Transform to lowercase
+  username: z.string().transform((val) => val.toLowerCase()),
+  
+  // Preprocess empty string to undefined
+  middleName: z.preprocess(
+    (val) => (val === '' ? undefined : val),
+    z.string().optional()
+  ),
+  
+  // Parse number from string
+  price: z.coerce.number().positive(),
+});
+```
+
+---
+
+## Complex Form Pattern
+
+```tsx
+// features/users/create-user/ui/CreateUserForm.tsx
+import { useForm, useFieldArray } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import { Plus, Trash2 } from 'lucide-react';
+import { Button } from '@/shared/ui/button';
+import { Input } from '@/shared/ui/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/shared/ui/select';
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/shared/ui/form';
+
+const addressSchema = z.object({
+  street: z.string().min(1, 'Required'),
+  city: z.string().min(1, 'Required'),
+  country: z.string().min(1, 'Required'),
+  isPrimary: z.boolean().default(false),
+});
+
+const createUserSchema = z.object({
+  profile: z.object({
+    firstName: z.string().min(1, 'First name is required'),
+    lastName: z.string().min(1, 'Last name is required'),
+    email: z.string().email('Invalid email'),
+  }),
+  role: z.enum(['admin', 'user', 'moderator']),
+  addresses: z.array(addressSchema).min(1, 'At least one address required'),
+});
+
+type CreateUserFormData = z.infer<typeof createUserSchema>;
+
+interface CreateUserFormProps {
+  onSubmit: (data: CreateUserFormData) => Promise<void>;
+  defaultValues?: Partial<CreateUserFormData>;
+}
+
+export const CreateUserForm: React.FC<CreateUserFormProps> = ({
+  onSubmit,
+  defaultValues,
+}) => {
+  const form = useForm<CreateUserFormData>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: {
+      profile: {
+        firstName: '',
+        lastName: '',
+        email: '',
+      },
+      role: 'user',
+      addresses: [{ street: '', city: '', country: '', isPrimary: true }],
+      ...defaultValues,
+    },
+  });
+
+  const { fields, append, remove } = useFieldArray({
+    control: form.control,
+    name: 'addresses',
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+        {/* Nested Object Fields */}
+        <div className="space-y-4">
+          <h3 className="text-lg font-medium">Profile</h3>
+          
+          <div className="grid grid-cols-2 gap-4">
+            <FormField
+              control={form.control}
+              name="profile.firstName"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>First Name</FormLabel>
+                  <FormControl>
+                    <Input {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+            
+            <FormField
+              control={form.control}
+              name="profile.lastName"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>Last Name</FormLabel>
+                  <FormControl>
+                    <Input {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+          </div>
+
+          <FormField
+            control={form.control}
+            name="profile.email"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Email</FormLabel>
+                <FormControl>
+                  <Input type="email" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+        </div>
+
+        {/* Select Field */}
+        <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="moderator">Moderator</SelectItem>
+                  <SelectItem value="admin">Admin</SelectItem>
+                </SelectContent>
+              </Select>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        {/* Array Fields */}
+        <div className="space-y-4">
+          <div className="flex items-center justify-between">
+            <h3 className="text-lg font-medium">Addresses</h3>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={() =>
+                append({ street: '', city: '', country: '', isPrimary: false })
+              }
+            >
+              <Plus className="h-4 w-4 mr-2" />
+              Add Address
+            </Button>
+          </div>
+
+          {fields.map((field, index) => (
+            <div key={field.id} className="p-4 border rounded-lg space-y-4">
+              <div className="flex justify-between items-center">
+                <span className="text-sm font-medium">
+                  Address {index + 1}
+                </span>
+                {fields.length > 1 && (
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => remove(index)}
+                  >
+                    <Trash2 className="h-4 w-4" />
+                  </Button>
+                )}
+              </div>
+
+              <div className="grid grid-cols-3 gap-4">
+                <FormField
+                  control={form.control}
+                  name={`addresses.${index}.street`}
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Street</FormLabel>
+                      <FormControl>
+                        <Input {...field} />
+                      </FormControl>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+                <FormField
+                  control={form.control}
+                  name={`addresses.${index}.city`}
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>City</FormLabel>
+                      <FormControl>
+                        <Input {...field} />
+                      </FormControl>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+                <FormField
+                  control={form.control}
+                  name={`addresses.${index}.country`}
+                  render={({ field }) => (
+                    <FormItem>
+                      <FormLabel>Country</FormLabel>
+                      <FormControl>
+                        <Input {...field} />
+                      </FormControl>
+                      <FormMessage />
+                    </FormItem>
+                  )}
+                />
+              </div>
+            </div>
+          ))}
+        </div>
+
+        <Button
+          type="submit"
+          className="w-full"
+          disabled={form.formState.isSubmitting}
+        >
+          {form.formState.isSubmitting ? 'Creating...' : 'Create User'}
+        </Button>
+      </form>
+    </Form>
+  );
+};
+```
+
+---
+
+## Form State Management
+
+```tsx
+const form = useForm<FormData>({
+  resolver: zodResolver(schema),
+  defaultValues,
+  mode: 'onBlur', // Validation mode: 'onBlur' | 'onChange' | 'onSubmit' | 'onTouched' | 'all'
+});
+
+// Form state
+const {
+  formState: {
+    errors,       // Field errors
+    isValid,      // All fields valid
+    isDirty,      // Any field modified
+    isSubmitting, // Form is submitting
+    isSubmitted,  // Form has been submitted
+    dirtyFields,  // Object of dirty fields
+    touchedFields,// Object of touched fields
+  },
+} = form;
+
+// Methods
+form.reset();                    // Reset to defaults
+form.reset(newValues);           // Reset to new values
+form.setValue('field', 'value'); // Set single value
+form.setError('field', { message: 'Error' }); // Set error
+form.clearErrors('field');       // Clear errors
+form.trigger('field');           // Trigger validation
+form.watch('field');             // Watch field value
+form.getValues();                // Get all values
+```
+
+---
+
+## Watch Pattern
+
+```tsx
+export const DynamicForm: React.FC = () => {
+  const form = useForm<FormData>();
+  
+  // Watch single field
+  const userType = form.watch('userType');
+  
+  // Watch multiple fields
+  const [firstName, lastName] = form.watch(['firstName', 'lastName']);
+  
+  // Watch all fields
+  const allValues = form.watch();
+
+  return (
+    <Form {...form}>
+      <form>
+        <FormField
+          name="userType"
+          render={({ field }) => (
+            <Select onValueChange={field.onChange} value={field.value}>
+              {/* ... */}
+            </Select>
+          )}
+        />
+
+        {/* Conditional rendering based on watched value */}
+        {userType === 'business' && (
+          <FormField
+            name="companyName"
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>Company Name</FormLabel>
+                <FormControl>
+                  <Input {...field} />
+                </FormControl>
+              </FormItem>
+            )}
+          />
+        )}
+
+        {/* Display computed value */}
+        <p className="text-sm text-muted-foreground">
+          Full name: {firstName} {lastName}
+        </p>
+      </form>
+    </Form>
+  );
+};
+```
+
+---
+
+## Server-Side Validation
+
+```tsx
+export const RegistrationForm: React.FC = () => {
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = async (data: FormData) => {
+    try {
+      await api.register(data);
+    } catch (error) {
+      if (error instanceof ApiError) {
+        // Set field-specific errors from server
+        if (error.field === 'email') {
+          form.setError('email', {
+            type: 'server',
+            message: error.message,
+          });
+        }
+        
+        // Set root error for general errors
+        form.setError('root.serverError', {
+          type: 'server',
+          message: error.message,
+        });
+      }
+    }
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        {/* Display root server error */}
+        {form.formState.errors.root?.serverError && (
+          <Alert variant="destructive">
+            {form.formState.errors.root.serverError.message}
+          </Alert>
+        )}
+        {/* ... fields */}
+      </form>
+    </Form>
+  );
+};
+```
+
+---
+
+## Custom Input Components
+
+```tsx
+// Controlled input wrapper
+interface ControlledInputProps {
+  control: Control<any>;
+  name: string;
+  label: string;
+  type?: string;
+  placeholder?: string;
+  description?: string;
+}
+
+export const ControlledInput: React.FC<ControlledInputProps> = ({
+  control,
+  name,
+  label,
+  type = 'text',
+  placeholder,
+  description,
+}) => (
+  <FormField
+    control={control}
+    name={name}
+    render={({ field }) => (
+      <FormItem>
+        <FormLabel>{label}</FormLabel>
+        <FormControl>
+          <Input type={type} placeholder={placeholder} {...field} />
+        </FormControl>
+        {description && <FormDescription>{description}</FormDescription>}
+        <FormMessage />
+      </FormItem>
+    )}
+  />
+);
+
+// Usage
+<ControlledInput
+  control={form.control}
+  name="email"
+  label="Email"
+  type="email"
+  placeholder="you@example.com"
+/>
+```
+
+---
+
+## File Upload
+
+```tsx
+const fileSchema = z.object({
+  avatar: z
+    .instanceof(FileList)
+    .refine((files) => files.length > 0, 'File is required')
+    .refine(
+      (files) => files[0]?.size <= 5 * 1024 * 1024,
+      'Max file size is 5MB'
+    )
+    .refine(
+      (files) => ['image/jpeg', 'image/png'].includes(files[0]?.type),
+      'Only .jpg and .png files are accepted'
+    ),
+});
+
+export const AvatarUpload: React.FC = () => {
+  const form = useForm<z.infer<typeof fileSchema>>({
+    resolver: zodResolver(fileSchema),
+  });
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="avatar"
+          render={({ field: { onChange, value, ...field } }) => (
+            <FormItem>
+              <FormLabel>Avatar</FormLabel>
+              <FormControl>
+                <Input
+                  type="file"
+                  accept="image/jpeg,image/png"
+                  onChange={(e) => onChange(e.target.files)}
+                  {...field}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+      </form>
+    </Form>
+  );
+};
+```
+
+---
+
+## Form with Mutation
+
+```tsx
+// features/users/create-user/model/useCreateUser.ts
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: userApi.createUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+      toast.success('User created successfully');
+    },
+    onError: (error) => {
+      toast.error(error.message);
+    },
+  });
+}
+
+// Usage in form
+export const CreateUserForm: React.FC = () => {
+  const { mutateAsync, isPending } = useCreateUser();
+  const form = useForm<CreateUserFormData>({
+    resolver: zodResolver(createUserSchema),
+  });
+
+  const onSubmit = async (data: CreateUserFormData) => {
+    await mutateAsync(data);
+    form.reset();
+  };
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        {/* ... fields */}
+        <Button type="submit" disabled={isPending}>
+          {isPending ? 'Creating...' : 'Create'}
+        </Button>
+      </form>
+    </Form>
+  );
+};
+```
+
+---
+
+## FSD Organization
+
+```
+src/
+├── shared/
+│   ├── ui/
+│   │   ├── form.tsx         # shadcn Form components
+│   │   ├── input.tsx
+│   │   └── select.tsx
+│   └── lib/
+│       └── validations/
+│           ├── user.ts      # Shared user schemas
+│           └── common.ts    # Common validation patterns
+├── features/
+│   └── auth/
+│       ├── ui/
+│       │   └── LoginForm.tsx
+│       └── model/
+│           └── schemas.ts   # Feature-specific schemas
+└── entities/
+    └── user/
+        └── model/
+            └── types.ts     # Inferred types from schemas
+```
+
+---
+
+## Forms Checklist
+
+- [ ] Define Zod schema
+- [ ] Infer TypeScript type from schema
+- [ ] Use zodResolver
+- [ ] Set appropriate validation mode
+- [ ] Handle form submission errors
+- [ ] Display field-level errors
+- [ ] Handle loading states
+- [ ] Reset form after successful submission
+- [ ] Implement server-side error handling
+
+