@minhduydev/mdpi 0.4.1 → 0.5.0

package/dist/template/.pi/skills/react-hook-form/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: react-hook-form
+description: Use when building forms with React Hook Form v7 and Zod v3. Covers useForm, controlled vs uncontrolled, zodResolver, conditional fields, field arrays, Server Actions integration. MUST load before any form implementation.
+---
+
+# React Hook Form + Zod
+
+## When to Use
+
+- Building complex forms with many fields and validation rules
+- Integrating Zod schemas for type-safe form validation
+- Handling conditional fields and dynamic field arrays
+- Optimizing form performance (uncontrolled inputs, minimal re-renders)
+- Integrating forms with Server Actions in Next.js
+- Field-level and form-level validation with custom error messages
+
+## When NOT to Use
+
+- Simple forms with 1-2 fields (use plain Server Actions)
+- Read-only data display (no form needed)
+- Forms that must work without JavaScript (use progressive enhancement Server Actions)
+
+## Setup
+
+```bash
+npm install react-hook-form @hookform/resolvers zod
+```
+
+## Basic Form
+
+```tsx
+'use client'
+
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email address'),
+  age: z.coerce.number().min(18, 'Must be 18 or older'),
+})
+
+type FormData = z.infer<typeof schema>
+
+export function SignupForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+  } = useForm<FormData>({
+    resolver: zodResolver(schema),
+    defaultValues: { name: '', email: '', age: 0 },
+  })
+
+  const onSubmit = async (data: FormData) => {
+    await createUser(data)  // Server Action or API call
+  }
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <div>
+        <input {...register('name')} placeholder="Name" />
+        {errors.name && <p className="text-red-500">{errors.name.message}</p>}
+      </div>
+
+      <div>
+        <input {...register('email')} placeholder="Email" />
+        {errors.email && <p className="text-red-500">{errors.email.message}</p>}
+      </div>
+
+      <div>
+        <input type="number" {...register('age')} placeholder="Age" />
+        {errors.age && <p className="text-red-500">{errors.age.message}</p>}
+      </div>
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Submitting...' : 'Sign Up'}
+      </button>
+    </form>
+  )
+}
+```
+
+## Controlled Components (shadcn/ui + Zod)
+
+React Hook Form is uncontrolled by default. Use `Controller` for controlled UI libraries:
+
+```tsx
+import { useForm, Controller } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+
+const schema = z.object({
+  plan: z.enum(['free', 'pro', 'enterprise']),
+})
+
+export function PlanForm() {
+  const { control, handleSubmit } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="plan"
+        control={control}
+        render={({ field }) => (
+          <Select onValueChange={field.onChange} value={field.value}>
+            <SelectTrigger>
+              <SelectValue placeholder="Select a plan" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="free">Free</SelectItem>
+              <SelectItem value="pro">Pro</SelectItem>
+              <SelectItem value="enterprise">Enterprise</SelectItem>
+            </SelectContent>
+          </Select>
+        )}
+      />
+    </form>
+  )
+}
+```
+
+## Zod Schema Patterns
+
+```tsx
+// Refinement — cross-field validation
+const schema = z.object({
+  password: z.string().min(8),
+  confirmPassword: z.string(),
+}).refine((data) => data.password === data.confirmPassword, {
+  message: "Passwords don't match",
+  path: ['confirmPassword'],  // Attach error to confirmPassword field
+})
+
+// SuperRefine — complex logic
+const schema = z.object({
+  email: z.string().email(),
+  username: z.string().min(3),
+}).superRefine((data, ctx) => {
+  if (data.email === data.username) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'Email and username must be different',
+      path: ['username'],
+    })
+  }
+})
+
+// Coercion — convert string inputs
+z.coerce.number()    // "42" → 42
+z.coerce.boolean()   // "true" → true
+z.coerce.date()      // "2024-01-01" → Date
+
+// Preprocess — custom coercion
+z.preprocess((val) => {
+  if (typeof val === 'string') return val.trim()
+  return val
+}, z.string().min(1))
+```
+
+## Conditional Fields
+
+```tsx
+const schema = z.discriminatedUnion('accountType', [
+  z.object({
+    accountType: z.literal('personal'),
+    name: z.string().min(2),
+  }),
+  z.object({
+    accountType: z.literal('business'),
+    companyName: z.string().min(2),
+    vatNumber: z.string().regex(/^[A-Z]{2}\d{8,12}$/),
+  }),
+])
+
+type FormData = z.infer<typeof schema>
+
+export function AccountForm() {
+  const { register, watch, handleSubmit } = useForm<FormData>({
+    resolver: zodResolver(schema),
+  })
+
+  const accountType = watch('accountType')
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <select {...register('accountType')}>
+        <option value="personal">Personal</option>
+        <option value="business">Business</option>
+      </select>
+
+      {accountType === 'personal' && (
+        <input {...register('name')} />
+      )}
+      {accountType === 'business' && (
+        <>
+          <input {...register('companyName')} />
+          <input {...register('vatNumber')} />
+        </>
+      )}
+    </form>
+  )
+}
+```
+
+## Field Arrays (Dynamic Fields)
+
+```tsx
+import { useFieldArray } from 'react-hook-form'
+
+const schema = z.object({
+  emails: z.array(
+    z.object({ value: z.string().email() })
+  ).min(1, 'At least one email required'),
+})
+
+export function EmailListForm() {
+  const { register, control, handleSubmit } = useForm({
+    resolver: zodResolver(schema),
+    defaultValues: { emails: [{ value: '' }] },
+  })
+
+  const { fields, append, remove } = useFieldArray({
+    control,
+    name: 'emails',
+  })
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      {fields.map((field, index) => (
+        <div key={field.id}>
+          <input {...register(`emails.${index}.value`)} placeholder="Email" />
+          <button type="button" onClick={() => remove(index)}>Remove</button>
+        </div>
+      ))}
+      <button type="button" onClick={() => append({ value: '' })}>
+        Add Email
+      </button>
+    </form>
+  )
+}
+```
+
+## Integration with Server Actions
+
+React Hook Form can delegate submission to a Server Action:
+
+```tsx
+'use client'
+
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { createUser } from './actions'
+import { useActionState } from 'react'
+
+const schema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+})
+
+export function UserForm() {
+  const [serverState, formAction] = useActionState(createUser, null)
+
+  const { register, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form action={formAction}>
+      <input {...register('name')} />
+      {errors.name?.message || serverState?.errors?.name?.[0]}
+
+      <input {...register('email')} />
+      {errors.email?.message || serverState?.errors?.email?.[0]}
+
+      <button type="submit">Create</button>
+    </form>
+  )
+}
+```
+
+**Decision guide:**
+- **Plain Server Actions** → Simple forms, progressive enhancement needed
+- **React Hook Form** → Complex forms, dynamic fields, client-side validation UX
+- **Combined** → RHF for client UX + Server Action for submission
+
+## Form State Reference
+
+```tsx
+const { formState } = useForm()
+
+formState.isDirty       // User modified any field
+formState.isValid       // All fields pass validation
+formState.isSubmitting  // Currently submitting
+formState.isSubmitted   // Form was submitted at least once
+formState.isSubmitSuccessful  // Last submit succeeded
+formState.errors        // Field-level errors object
+formState.dirtyFields   // Which fields were modified
+formState.touchedFields // Which fields gained and lost focus
+```
+
+## Performance: `useForm` Options
+
+```tsx
+const { register } = useForm({
+  mode: 'onBlur',          // Validate on blur (default: onSubmit)
+  reValidateMode: 'onChange', // Re-validate after first submit
+  shouldFocusError: true,  // Focus first field with error after submit
+  criteriaMode: 'all',     // Show all validation errors per field
+  delayError: 500,         // Delay error display (ms) for async validation
+})
+```
+
+## Debounced Validation (Async)
+
+```tsx
+const schema = z.object({
+  username: z.string().min(3).refine(
+    async (username) => {
+      const available = await checkUsername(username)
+      return available
+    },
+    { message: 'Username is already taken' }
+  ),
+})
+
+// React Hook Form debounces the refine call
+// Add throttle via watch + useEffect if needed
+```
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Mixing `register` and `Controller` for same field | Pick one — use `Controller` for UI libraries, `register` for native inputs |
+| Forgetting `defaultValues` shape | `defaultValues` must match schema shape — otherwise fields are undefined |
+| `watch` in render causing loops | Use `watch` sparingly; prefer `getValues()` in callbacks |
+| `setValue` without `shouldDirty`/`shouldValidate` | `setValue('field', val, { shouldDirty: true, shouldValidate: true })` |
+| Zod `refine` on field that doesn't exist yet | Use `superRefine` and `addIssue` with explicit `path` |
+| Not forwarding `ref` in custom components | Use `React.forwardRef` or Controller for custom inputs |
+| `handleSubmit` not wrapping async handler | Always `async (data) => { await ... }` — unhandled promise rejections crash |
+| `useFieldArray` `key` using index | Always use `field.id` as key (not index) — stable across add/remove |
+
+## When to Use React Hook Form vs Server Actions Only
+
+| React Hook Form | Server Actions Only |
+|-----------------|-------------------|
+| Complex validation UX (real-time errors) | Simple forms (2-3 fields) |
+| Dynamic field arrays | Progressive enhancement required |
+| Conditional fields that affect validation | No client-side validation needed |
+| Multi-step wizards | Static forms that rarely change |
+| shadcn Select/DatePicker/Combobox | Native inputs only |
+| Field-level async validation (username check) | Server-only validation |
+
+## Verification
+
+- [ ] `zodResolver(schema)` configured — links Zod to RHF
+- [ ] `defaultValues` match the schema structure
+- [ ] All controlled components use `Controller` or `useController`
+- [ ] `useFieldArray` keys use `field.id` (not index)
+- [ ] Conditional fields use `watch` with `z.discriminatedUnion` or `z.union`
+- [ ] `handleSubmit` wraps async function
+- [ ] Field-level errors displayed via `formState.errors`
+- [ ] `isSubmitting` disables submit button during submission
+- [ ] Cross-field validation uses `.refine()` or `.superRefine()` with `path`

package/dist/template/.pi/skills/react-server-actions/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: react-server-actions
+description: Use when building forms, mutations, or data writes in React 19 + Next.js. Covers Server Actions, useActionState, useOptimistic, useFormStatus, progressive enhancement, Zod validation, error handling. MUST load before any form or mutation implementation.
+---
+
+# React Server Actions & Forms (React 19)
+
+## When to Use
+
+- Building forms that submit data to the server
+- Handling mutations (create, update, delete) in React 19
+- Adding optimistic updates to improve perceived performance
+- Integrating Zod validation with Server Actions
+- Migrating from API routes or tRPC to Server Actions
+- Implementing progressive enhancement (forms work without JS)
+
+## When NOT to Use
+
+- Read-only data fetching (use Server Components, `use()`, or TanStack Query)
+- Client-only state management (use Zustand or context)
+- Non-Next.js React projects without Server Action support
+
+## Core Pattern: Server Action + useActionState
+
+```tsx
+// app/actions.ts
+'use server'
+
+import { z } from 'zod'
+import { revalidatePath } from 'next/cache'
+
+const schema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+})
+
+export async function createUser(prevState: unknown, formData: FormData) {
+  // 1. Parse and validate
+  const raw = Object.fromEntries(formData)
+  const parsed = schema.safeParse(raw)
+
+  if (!parsed.success) {
+    return { error: parsed.error.flatten().fieldErrors }
+  }
+
+  // 2. Mutate (database call)
+  await db.user.create({ data: parsed.data })
+
+  // 3. Revalidate and redirect
+  revalidatePath('/users')
+  return { success: true }
+}
+```
+
+```tsx
+// app/new/page.tsx
+'use client'
+
+import { useActionState } from 'react'
+import { useFormStatus } from 'react-dom'
+import { createUser } from './actions'
+
+function SubmitButton() {
+  const { pending } = useFormStatus()
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Creating...' : 'Create User'}
+    </button>
+  )
+}
+
+export default function NewUserForm() {
+  const [state, formAction] = useActionState(createUser, null)
+
+  return (
+    <form action={formAction}>
+      <input name="name" required />
+      {state?.error?.name && <p>{state.error.name[0]}</p>}
+
+      <input name="email" type="email" required />
+      {state?.error?.email && <p>{state.error.email[0]}</p>}
+
+      <SubmitButton />
+      {state?.success && <p className="text-green-600">User created!</p>}
+    </form>
+  )
+}
+```
+
+## Hook Reference
+
+### `useActionState(action, initialState, permalink?)`
+
+```tsx
+const [state, formAction, isPending] = useActionState(action, null)
+```
+
+- Replaces `useFormState` (deprecated in React 19)
+- `state` — return value from your Server Action
+- `formAction` — pass as `<form action={formAction}>`
+- `isPending` — convenient boolean for loading state
+- `permalink` — optional URL for progressive enhancement fallback
+
+### `useFormStatus()`
+
+```tsx
+const { pending, data, method, action } = useFormStatus()
+```
+
+- **Must be used inside a `<form>` child component** — not in the component that renders `<form>`
+- Extract `<SubmitButton>` as a separate component
+- `pending` — true while form is submitting
+- `data` — the FormData being submitted
+
+### `useOptimistic(initialValue, reducer)`
+
+```tsx
+const [optimisticTodos, addOptimistic] = useOptimistic(
+  todos,
+  (state, newTodo: Todo) => [...state, newTodo]
+)
+
+// In event handler:
+addOptimistic({ id: crypto.randomUUID(), text, pending: true })
+await addTodoOnServer(formData)
+```
+
+- Shows UI change immediately, reverts on error
+- `reducer` signature: `(currentState, optimisticValue) => newState`
+- Good for: like counters, comment posting, toggle states
+
+## Zod Integration
+
+```tsx
+'use server'
+
+import { z } from 'zod'
+
+const SignupSchema = z.object({
+  email: z.string().email('Invalid email'),
+  password: z.string().min(8, 'Min 8 characters'),
+  age: z.coerce.number().min(18, 'Must be 18+'),
+  plan: z.enum(['free', 'pro', 'enterprise']),
+})
+
+export async function signup(prev: unknown, formData: FormData) {
+  const result = SignupSchema.safeParse(Object.fromEntries(formData))
+
+  if (!result.success) {
+    // Return flattened errors keyed by field
+    return {
+      errors: result.error.flatten().fieldErrors,
+      inputs: Object.fromEntries(formData) // preserve user input
+    }
+  }
+
+  await createAccount(result.data)
+  return { success: true }
+}
+```
+
+## Progressive Enhancement
+
+Server Actions support HTML form fallback — forms work without JavaScript:
+
+```tsx
+// The form works even if JS fails to load:
+<form action={createUser}>
+  <input name="name" required />
+  <button type="submit">Submit</button>
+</form>
+```
+
+For the JS-enhanced version, use `useActionState` which wraps the same Server Action.
+
+**Requirements for progressive enhancement:**
+- Use native `<form>` and `<button type="submit">`
+- Use `required` attribute for client-side validation
+- All form fields must have `name` attributes
+- Server Action must accept `FormData` as second argument
+
+## Error Handling Pattern
+
+```tsx
+type ActionState = {
+  error?: string              // General error
+  errors?: Record<string, string[]>  // Field-level errors
+  success?: boolean           // Success flag
+  data?: unknown              // Return data on success
+}
+
+// In Server Action:
+try {
+  await db.user.create({ data: parsed.data })
+  return { success: true }
+} catch (err) {
+  if (err instanceof PrismaClientKnownRequestError && err.code === 'P2002') {
+    return { errors: { email: ['Email already registered'] } }
+  }
+  return { error: 'Something went wrong. Please try again.' }
+}
+```
+
+## Redirect After Success
+
+```tsx
+'use server'
+
+import { redirect } from 'next/navigation'
+
+export async function createPost(prev: unknown, formData: FormData) {
+  const post = await db.post.create({ data: { title: formData.get('title') } })
+  revalidatePath('/posts')
+  redirect(`/posts/${post.id}`)
+}
+```
+
+**Important**: `redirect()` throws a `NEXT_REDIRECT` error — call it after all mutations. Cannot be inside try/catch.
+
+## Avoiding Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| `useFormStatus()` in the form component itself | Extract `<SubmitButton>` to its own component |
+| Not calling `revalidatePath` after mutation | Always revalidate the affected path |
+| Using `redirect()` inside try/catch | Move redirect outside try/catch |
+| Passing sensitive data as hidden inputs | Validate on server — never trust client data |
+| Server Action not at top of file | `'use server'` directive must be first line |
+| Mutating in Server Components | Server Components are read-only; use `'use client'` + action |
+| Zod `safeParse` then ignoring errors | Always return errors to the form |
+| Multiple forms on one page sharing action | Each form gets its own action or use a field to discriminate |
+
+## Multiple Actions Per Form
+
+```tsx
+<form>
+  <button formAction={saveDraft}>Save Draft</button>
+  <button formAction={publish}>Publish</button>
+</form>
+```
+
+Each button can have its own `formAction` pointing to a different Server Action.
+
+## Non-Form Mutations (Calling Actions Programmatically)
+
+```tsx
+// For button clicks, toggles, etc. — import and call:
+'use client'
+
+import { toggleLike } from './actions'
+
+function LikeButton({ postId }: { postId: string }) {
+  const [optimistic, addOptimistic] = useOptimistic(
+    false,
+    (_, liked: boolean) => liked
+  )
+
+  return (
+    <button
+      onClick={async () => {
+        addOptimistic(!optimistic)
+        await toggleLike(postId)
+      }}
+    >
+      {optimistic ? '❤️' : '🤍'}
+    </button>
+  )
+}
+```
+
+## Integration with Other Skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `react-hook-form` | Alternative form approach (client-side state) — use when you need complex field interactions or field arrays |
+| `nextjs-cache` | After mutation, `revalidatePath` / `revalidateTag` to invalidate cache |
+| `nextjs-app-router` | Form pages use App Router conventions (loading.tsx for submit state) |
+| `tanstack-query` | For GET/read operations — Server Actions are for mutations only |
+
+## When to Use Server Actions vs API Routes
+
+| Use Server Actions for | Use API Routes for |
+|-----------------------|-------------------|
+| Forms with progressive enhancement | Public APIs consumed by external clients |
+| Mutations tightly coupled to UI | Webhooks / third-party callbacks |
+| When you want co-located data flow | When you need cache headers, CORS, streaming |
+| Optimistic updates | File uploads (use `multipart/form-data`) |
+
+## Verification
+
+- [ ] `'use server'` is the first line of the action file
+- [ ] Server Action accepts `(prevState, formData)` matching `useActionState` signature
+- [ ] `useFormStatus` is in a child component (not the form itself)
+- [ ] All form fields have `name` attributes (for FormData extraction)
+- [ ] Zod validation returns field-level errors
+- [ ] `revalidatePath` / `revalidateTag` called after mutations
+- [ ] `redirect()` outside try/catch blocks
+- [ ] Progressive enhancement: form works with JS disabled
+- [ ] Optimistic updates use `useOptimistic` with clean revert on error