@minhduydev/mdpi 0.4.1 → 0.6.0

package/dist/template/.pi/skills/react-compiler/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: react-compiler
+description: Use when enabling, debugging, or optimizing with the React Compiler. Covers what it auto-memoizes, what it can't optimize, ESLint plugin, migration guide, and React DevTools debugging. MUST load before enabling the compiler or diagnosing memoization issues.
+---
+
+# React Compiler (React 19+)
+
+## When to Use
+
+- Enabling the React Compiler in a project
+- Understanding what the compiler does and doesn't optimize
+- Debugging why a component didn't get memoized
+- Diagnosing unexpected re-renders in a compiler-enabled project
+- Deciding between manual `useMemo`/`useCallback` vs letting the compiler handle it
+
+## When NOT to Use
+
+- Non-React projects
+- Debugging runtime rendering issues unrelated to memoization
+- Choosing component architecture (use `react-best-practices` or `deep-module-design`)
+
+## What the React Compiler Does
+
+The React Compiler **auto-memoizes** components and hooks at build time. It eliminates the need for manual `useMemo`, `useCallback`, and `memo()` in most cases.
+
+```tsx
+// Before compiler — manual memoization
+function ExpensiveList({ items }: { items: Item[] }) {
+  const filtered = useMemo(
+    () => items.filter(i => i.active),
+    [items]
+  )
+
+  const handleClick = useCallback((id: string) => {
+    onSelect(id)
+  }, [onSelect])
+
+  return filtered.map(item => (
+    <Item key={item.id} item={item} onClick={handleClick} />
+  ))
+}
+
+// With compiler — writes itself
+function ExpensiveList({ items }: { items: Item[] }) {
+  const filtered = items.filter(i => i.active)
+
+  return filtered.map(item => (
+    <Item key={item.id} item={item} onClick={() => onSelect(item.id)} />
+  ))
+}
+```
+
+## What the Compiler CAN Optimize
+
+| Pattern | How |
+|---------|-----|
+| Components | Auto-wraps with `memo()` equivalent |
+| Props & dependencies | Auto-generates dependency arrays for `useMemo`, `useCallback`, `useEffect` |
+| Inline functions | Auto-memoizes `() => {}` passed as props |
+| Computed values | Auto-wraps expensive computations in `useMemo` |
+| Context reads | Tracks granular context reads — only re-renders when specific field changes |
+| useRef stability | Stabilizes `useRef` references |
+
+## What the Compiler CANNOT Optimize
+
+| Limitation | What to Do |
+|-----------|------------|
+| **Side effects in render** | Fix — compiler bails out on impure renders |
+| **Mutating state directly** | Fix — use setState functions |
+| **Dynamic `key` values from `Math.random()`** | Fix — use stable keys |
+| **Third-party libraries that break Rules of React** | Wait for library updates |
+| **Components with `ref` + mutating `ref.current` in render** | Move mutation to event handler or effect |
+| **Deeply nested context that's read broadly** | Split context or use selectors (Zustand) |
+| **Extremely large dependency arrays (100+ items)** | Restructure: split component or function |
+| **Code using `eval()` or `new Function()`** | Remove dynamic code evaluation |
+
+## Enabling the Compiler
+
+### Next.js (15+)
+
+```bash
+npm install babel-plugin-react-compiler
+```
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  experimental: {
+    reactCompiler: true,
+  },
+}
+```
+
+### Vite (React)
+
+```bash
+npm install babel-plugin-react-compiler
+```
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: [['babel-plugin-react-compiler', { target: '19' }]],
+      },
+    }),
+  ],
+})
+```
+
+## ESLint Plugin
+
+```bash
+npm install eslint-plugin-react-compiler
+```
+
+```json
+// .eslintrc.json
+{
+  "plugins": ["react-compiler"],
+  "rules": {
+    "react-compiler/react-compiler": "error"
+  }
+}
+```
+
+The ESLint plugin detects **Rules of React violations** that would cause the compiler to bail out — catches issues at lint time before they become runtime problems.
+
+## React DevTools Integration
+
+With the compiler enabled, React DevTools shows:
+
+- **"Memo ✨"** badge on auto-memoized components
+- Components that **failed** to compile — shown with a warning badge
+- Why it failed: hover the badge for explanation
+
+Open React DevTools → Components tab → look for ✨ beside component names.
+
+## Migration Guide
+
+### Phase 1: ESLint First (No Compiler)
+
+```bash
+npm install eslint-plugin-react-compiler
+```
+
+Enable only the ESLint rule. Fix all violations. This ensures your code follows Rules of React — a prerequisite for the compiler.
+
+### Phase 2: Enable Compiler on CI
+
+```ts
+// next.config.ts — enable on CI/staging first
+reactCompiler: process.env.CI === 'true'
+```
+
+Run your test suite. Check for behavioral changes.
+
+### Phase 3: Remove Manual Memoization
+
+Once the compiler is stable in production:
+
+```tsx
+// Remove these — compiler handles them:
+// - useMemo for computed values
+// - useCallback for event handlers
+// - React.memo() wrapping
+
+// Keep these — they serve semantic purposes:
+// - useMemo for expensive computations the compiler can't prove
+// - useRef for mutable values
+// - useEffect for synchronization
+```
+
+### Phase 4: Full Production Enable
+
+```ts
+reactCompiler: true
+```
+
+## Gradual Adoption
+
+Enable per-directory via compiler directive comments:
+
+```tsx
+// Opt-in specific files:
+'use memo'
+
+// Opt-out specific files:
+'use no memo'
+```
+
+Use `'use memo'` at the top of a file to enable the compiler for that file only, even if the project-level config is off.
+
+## When to Keep Manual Memoization
+
+Even with the compiler, keep manual memoization for:
+
+- **Truly expensive computations**: The compiler is conservative — if you know something is heavy, `useMemo` makes it explicit
+- **Custom hooks with object returns**: `useMemo` on the return value ensures referential stability
+- **Third-party integration**: When passing objects to non-React libraries that do shallow comparisons
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Side effects during render (console.log, date, random) | Move to event handlers or effects |
+| Mutating props or state in render | Use immutable updates |
+| Assuming compiler fixes all performance | Compiler handles memoization only — waterfalls, bundle size, SSR still need attention |
+| Leaving manual memoization everywhere | Remove redundant `useMemo`/`useCallback` — they add noise with no benefit |
+| Not running ESLint plugin before enabling | Run ESLint first and fix all violations — this is the #1 source of compiler bailouts |
+| `useMemo` with empty dependency for object identity | Compiler handles this — remove unless it's truly expensive |
+
+## Integration with Other Skills
+
+| Skill | How Compiler Changes It |
+|-------|------------------------|
+| `react-best-practices` | `rerender-memo`, `rerender-functional-setstate` become unnecessary with compiler |
+| `react-server-actions` | No change — Server Actions don't use compiler |
+| `zustand` | Selective subscriptions still recommended — compiler doesn't replace selectors |
+| `tanstack-query` | No change — data fetching patterns unchanged |
+
+## Verification
+
+- [ ] ESLint plugin enabled and passing with zero violations
+- [ ] Compiler enabled in `next.config.ts` or `vite.config.ts`
+- [ ] React DevTools shows ✨ on auto-memoized components
+- [ ] No unexpected re-renders after enabling (profile with DevTools)
+- [ ] Test suite passes with compiler enabled
+- [ ] Manual `useMemo`/`useCallback` removed where compiler handles them
+- [ ] No side effects in render (build warnings if any)

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`