@minhduydev/mdpi 0.4.0 → 0.5.0

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

package/dist/template/.pi/skills/shadcn-ui/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: shadcn-ui
+description: Use when adding, configuring, or managing shadcn/ui components. Covers CLI v4, visual styles (Vega/Nova/Maia/Lyra/Mira), preset system, GitHub Registries, shadcn/skills AI prompt files, MCP registry, and component management. NOT a replacement for component API docs — see frontend-design's shadcn references for that.
+---
+
+# shadcn/ui
+
+## When to Use
+
+- Adding shadcn/ui components to a project (`npx shadcn add`)
+- Initializing shadcn/ui in a new project (`npx shadcn init` / `npx shadcn create`)
+- Choosing a visual style (Vega, Nova, Maia, Lyra, Mira)
+- Configuring via the preset system or `components.json`
+- Using shadcn/skills for AI-driven component generation
+- Inspecting installed components (`shadcn info --json`)
+- Previewing component changes before applying (`--dry-run`, `--diff`, `--view`)
+- Setting up custom component registries
+
+## When NOT to Use
+
+- When you need component API documentation (use `frontend-design` → `./references/shadcn/*.md`)
+- When theming with CSS variables (use `frontend-design` → `./references/shadcn/theming.md`)
+- When building plain UI without shadcn/ui components
+- When the task is about v0 generation (use the `v0` skill instead)
+
+## Relationship to `frontend-design` References
+
+This skill covers **shadcn/ui tooling and workflow** — CLI commands, presets, registries, skills, and configuration management.
+
+For **component API documentation** (Button props, Card subcomponents, Dialog patterns, Select usage), see:
+- `frontend-design` → `./references/shadcn/setup.md` — Installation, visual styles, component list
+- `frontend-design` → `./references/shadcn/core-components.md` — Button, Card, Dialog, Select, Tabs, Toast, Command, Sidebar, Table
+- `frontend-design` → `./references/shadcn/form-components.md` — Form, Field, InputGroup
+- `frontend-design` → `./references/shadcn/theming.md` — CSS variables, OKLCH, dark mode
+- `frontend-design` → `./references/shadcn/accessibility.md` — ARIA, keyboard, screen reader
+
+## CLI v4 (current: shadcn@4.11.0)
+
+### Starting Projects
+
+```bash
+# Interactive project creation (recommended)
+npx shadcn create
+
+# This walks through:
+# - Framework (Next.js, Vite, Remix, etc.)
+# - Visual style (Vega, Nova, Maia, Lyra, Mira)
+# - Component library backend (Radix UI or Base UI)
+# - Icon library (including Phosphor)
+# - TypeScript, Tailwind CSS, CSS variables setup
+```
+
+### Adding Components to Existing Projects
+
+```bash
+# Initialize shadcn in existing project
+npx shadcn@latest init
+
+# Add specific components
+npx shadcn@latest add button card dialog
+
+# Add all components
+npx shadcn@latest add --all
+
+# Add from GitHub Registry
+npx shadcn@latest add <username>/<repo>/<item>
+```
+
+### Safety & Inspection
+
+```bash
+# Preview what will change (no writes)
+npx shadcn@latest add button dialog --dry-run
+
+# Show exact diff for a component
+npx shadcn@latest add button --diff
+
+# Open component in browser for review
+npx shadcn@latest add button --view
+
+# Inspect installed components as JSON
+npx shadcn info --json
+
+# Check version
+npx shadcn --version
+```
+
+### `shadcn info --json`
+
+Outputs structured data about installed components, useful for CI and tooling:
+
+```json
+{
+  "version": "4.11.0",
+  "components": [
+    {
+      "name": "button",
+      "installed": true,
+      "version": "4.11.0",
+      "path": "components/ui/button.tsx",
+      "dependencies": ["@radix-ui/react-slot"],
+      "registrySource": "default"
+    }
+  ],
+  "style": "vega",
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "utils": "@/lib/utils"
+  }
+}
+```
+
+## Visual Styles
+
+| Style | Vibe | Use Case |
+|-------|------|----------|
+| **Vega** | Classic shadcn — balanced, familiar | Default. Good for most projects. |
+| **Nova** | Compact, reduced padding | Data-heavy dashboards, admin panels |
+| **Maia** | Soft, rounded, generous padding | Consumer apps, marketing sites |
+| **Lyra** | Boxy, sharp corners, monospace fonts | Developer tools, technical interfaces |
+| **Mira** | Dense, efficient, minimal chrome | Internal tools, complex workflows |
+
+Set during `npx shadcn create` or override per-component with `--style <name>`.
+
+## Preset System
+
+Presets pack your entire design system config into a reproducible short code:
+
+```bash
+# Export your design system as a preset code
+npx shadcn preset export
+
+# Init a new project with a preset
+npx shadcn init --preset a1Dg5eFl
+```
+
+A preset captures: visual style (Vega/Nova/Maia/Lyra/Mira), component library (Radix/Base UI), colors, theme, icons, fonts, radius, spacing — everything needed to reproduce the exact design system.
+
+## GitHub Registries (June 2026)
+
+Any public GitHub repo with a `registry.json` can be a component registry.
+
+```bash
+# Pull from a GitHub registry
+npx shadcn@latest add <username>/<repo>/<item>
+
+# Example
+npx shadcn@latest add shadcn-ui/ui/data-table
+```
+
+No build step needed — CLI reads `registry.json` directly. Distribute: components, hooks, utilities, design tokens, feature kits, project conventions, CI workflows, templates.
+
+### Registry Structure
+
+```json
+// registry.json (in any GitHub repo root)
+{
+  "name": "my-components",
+  "items": [
+    {
+      "name": "data-table",
+      "type": "registry:component",
+      "files": [{ "path": "components/data-table.tsx" }],
+      "dependencies": ["@tanstack/react-table"]
+    }
+  ]
+}
+```
+
+## MCP Registry Server
+
+Connect AI editors to your custom shadcn/ui registry:
+
+```json
+{
+  "mcpServers": {
+    "shadcn": {
+      "command": "npx",
+      "args": ["-y", "shadcn@canary", "registry:mcp"],
+      "env": {
+        "REGISTRY_URL": "https://your-registry.vercel.app/r/registry.json"
+      }
+    }
+  }
+}
+```
+
+This allows AI agents (Cursor, Windsurf, Claude Desktop) to query and pull components from your custom design system registry.
+
+## shadcn/skills — AI Agent Prompt File
+
+A machine-readable skills file that gives AI coding agents accurate, project-aware context about shadcn/ui.
+
+### Setup
+
+```bash
+npx skills add shadcn/ui
+```
+
+Creates `.shadcn/skills.md` — automatically injected into AI agent context.
+
+### What It Provides
+
+- **Project context** — framework, aliases, installed components (via `shadcn info --json`)
+- **CLI commands** — all flags, smart merge, presets, templates
+- **Theming** — CSS vars, OKLCH, dark mode, Tailwind v3/v4
+- **Registry authoring** — `registry.json` format, item types, dependencies
+- **Pattern enforcement** — `FieldGroup` for forms, `ToggleGroup` for options, semantic colors
+
+### Measured Impact
+
+| Metric | Before Skills | After Skills |
+|--------|--------------|-------------|
+| API errors | 34% | 3% |
+| Correct variants | 61% | 98% |
+| First-try success | 45% | 89% |
+
+### Critical Workflows
+
+```bash
+# Install
+npx skills add shadcn/ui
+
+# Regenerate after adding components (CRITICAL!)
+npx shadcn skills generate
+
+# Update monthly to stay current
+npx shadcn skills update
+```
+
+### Pitfalls
+
+| Mistake | Fix |
+|---------|-----|
+| Not regenerating after adding components | Add `shadcn skills generate` to post-install script |
+| Skills getting cut off from context limit | Reference file path; don't paste contents |
+| Using outdated skills (3+ months old) | Run `shadcn skills update` monthly |
+| Ignoring the preset system | Use presets; customize through Tailwind config, not per-component CSS |
+
+## Components (2026)
+
+### New in 2026
+
+| Component | Description |
+|-----------|-------------|
+| **Field** | Form field wrapper with label, description, error message |
+| **InputGroup** | Grouped inputs with addons (prefix/suffix) |
+| **Spinner** | Loading spinner with size variants |
+| **Kbd** | Keyboard shortcut display |
+| **ButtonGroup** | Grouped button toolbar |
+| **Item** | Generic list item with icon, text, and actions |
+| **Empty** | Empty state with illustration, text, and action |
+
+### Component Installation
+
+```bash
+npx shadcn@latest add field input-group spinner kbd button-group item empty
+```
+
+### Quick Reference — New Components
+
+#### Field
+
+```tsx
+import { Field, FieldLabel, FieldDescription, FieldError } from "@/components/ui/field"
+
+<Field>
+  <FieldLabel>Email</FieldLabel>
+  <Input placeholder="you@example.com" />
+  <FieldDescription>We'll never share your email.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+```
+
+#### InputGroup
+
+```tsx
+import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupAddon>https://</InputGroupAddon>
+  <Input placeholder="example.com" />
+  <InputGroupAddon>.com</InputGroupAddon>
+</InputGroup>
+```
+
+#### Spinner
+
+```tsx
+import { Spinner } from "@/components/ui/spinner"
+
+<Spinner />
+<Spinner size="sm" />
+<Spinner className="text-primary" />
+```
+
+#### Kbd
+
+```tsx
+import { Kbd } from "@/components/ui/kbd"
+
+<Kbd>⌘K</Kbd>
+<Kbd variant="outline">Ctrl + S</Kbd>
+```
+
+#### ButtonGroup
+
+```tsx
+import { ButtonGroup } from "@/components/ui/button-group"
+import { Button } from "@/components/ui/button"
+
+<ButtonGroup>
+  <Button variant="outline">Day</Button>
+  <Button variant="outline">Week</Button>
+  <Button variant="outline">Month</Button>
+</ButtonGroup>
+```
+
+#### Item
+
+```tsx
+import { Item, ItemIcon, ItemText, ItemAction } from "@/components/ui/item"
+
+<Item>
+  <ItemIcon><SettingsIcon /></ItemIcon>
+  <ItemText primary="Settings" secondary="Manage preferences" />
+  <ItemAction><ChevronRight /></ItemAction>
+</Item>
+```
+
+#### Empty
+
+```tsx
+import { Empty } from "@/components/ui/empty"
+
+<Empty
+  title="No results"
+  description="Try adjusting your filters."
+  action={<Button>Clear filters</Button>}
+/>
+```
+
+## Configuration
+
+### `components.json`
+
+The central configuration file:
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "app/globals.css",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "utils": "@/lib/utils",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide",
+  "registries": [
+    {
+      "name": "team",
+      "url": "gh:my-org/shadcn-registry"
+    }
+  ]
+}
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why | Correct |
+|---|---|---|
+| Manually editing component primitives | Upstream updates become impossible to merge | Extend with wrapper components instead |
+| Importing from shadcn as a package | shadcn/ui is copy-paste, not an npm package | Components live in your `components/ui/` directory |
+| Adding `--all` without reviewing | Installs 50+ components, most unused | Only install what you need |
+| Using hard-coded Tailwind values | Breaks theming and dark mode | Reference CSS variable tokens |
+| Overriding `@theme` without preserving shadcn tokens | Breaks component styling | Extend `@theme`, don't replace it |
+| Editing CSS variables inline | Hard to maintain theme switching | Define variables once, reference by semantic name |
+
+## Verification
+
+After working with shadcn/ui:
+
+- [ ] `components.json` exists and is configured correctly
+- [ ] Only needed components are installed (no `--all` waste)
+- [ ] CSS variables are used for colors (no hard-coded hex/rgb in components)
+- [ ] Dark mode works via CSS variable overrides
+- [ ] Components compile with TypeScript strict mode
+- [ ] `npx shadcn info --json` shows expected installed components
+- [ ] Preset saved if project has custom styling
+- [ ] `shadcn/skills/` directory exists if project has custom conventions
+- [ ] Aliases match project structure (`@/components/ui/`, `@/lib/utils`)
+- [ ] No manually edited primitives that would conflict with updates