@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

package/framework/standards/frontend/nextjs/naming-conventions.md

@@ -1,67 +1,71 @@
-# Next.js Naming Conventions Standard
-
-> **Scope:** frontend/nextjs/naming-conventions
-> **Layer:** 1 (always)
-> **Keywords:** naming, conventions, file names, component names, hooks, typescript
-> **Load When:** creating any new file in a Next.js project
-
-Consistent naming prevents filesystem bugs (Linux case-sensitivity) and keeps the codebase predictable.
-
-## Core Rules
-
-- ALWAYS use kebab-case for file names — never PascalCase or camelCase
-- ALWAYS use PascalCase for React component exports
-- ALWAYS use camelCase starting with `use` for hook exports
-- ALWAYS suffix schema files with `.schemas.ts` and type files with `.types.ts`
-- NEVER mix cases in the same category — no `UserCard.tsx` alongside `user-profile.tsx`
-
-## Complete Reference Table
-
-| Artifact | File Name | Export Name | Example |
-|----------|-----------|-------------|---------|
-| React Component | `user-card.tsx` | `UserCard` | `export function UserCard()` |
-| Client Component | `user-form.tsx` | `UserForm` | `export function UserForm()` + `'use client'` |
-| TanStack Query hook | `use-users.ts` | `useUsers` | `export function useUsers()` |
-| Mutation hook | `use-create-user.ts` | `useCreateUser` | `export function useCreateUser()` |
-| Utility hook | `use-debounce.ts` | `useDebounce` | `export function useDebounce()` |
-| Zod schema file | `user.schemas.ts` | `createUserSchema` | `export const createUserSchema = z.object(...)` |
-| TypeScript types | `user.types.ts` | `User`, `CreateUserInput` | `export type User = z.infer<typeof userSchema>` |
-| Feature index | `index.ts` | (re-exports) | `export { UserCard } from './components/user-card'` |
-| Page file | `page.tsx` | `default` | `export default function UsersPage()` |
-
-## Hook Naming Rules
-
-```
-GET list:    use-users.ts          → useUsers()
-GET single:  use-user.ts           → useUser(id: string)
-POST:        use-create-user.ts    → useCreateUser()
-PUT/PATCH:   use-update-user.ts    → useUpdateUser()
-DELETE:      use-delete-user.ts    → useDeleteUser()
-```
-
-## Schema and Type Naming Rules
-
-```typescript
-// user.schemas.ts
-export const userSchema = z.object({ id: z.string(), name: z.string() });
-export const createUserSchema = z.object({ name: z.string().min(2), email: z.string().email() });
-export const updateUserSchema = createUserSchema.partial();
-
-// user.types.ts — derive from schemas, don't duplicate
-export type User = z.infer<typeof userSchema>;
-export type CreateUserInput = z.infer<typeof createUserSchema>;
-export type UpdateUserInput = z.infer<typeof updateUserSchema>;
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| `UserCard.tsx` | `user-card.tsx` | Linux servers are case-sensitive |
-| `useUsers.ts` | `use-users.ts` | Inconsistent with Next.js file conventions |
-| `export default function UserCard` | `export function UserCard` | Named exports are more refactor-safe |
-| `type User = { id: string }` | `type User = z.infer<typeof userSchema>` | Single source of truth |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Next.js Naming Conventions Standard
+
+> **Scope:** frontend/nextjs/naming-conventions
+> **Layer:** 1 (always)
+> **Keywords:** naming, conventions, file names, component names, hooks, typescript
+> **Load When:** creating any new file in a Next.js project
+
+**Verified against:** Next.js 15 + Zod 4. Last-verified: 2026-05-20.
+
+---
+
+Consistent naming prevents filesystem bugs (Linux case-sensitivity) and keeps the codebase predictable.
+
+## Core Rules
+
+- ALWAYS use kebab-case for file names — never PascalCase or camelCase
+- ALWAYS use PascalCase for React component exports
+- ALWAYS use camelCase starting with `use` for hook exports
+- ALWAYS suffix schema files with `.schemas.ts` and type files with `.types.ts`
+- NEVER mix cases in the same category — no `UserCard.tsx` alongside `user-profile.tsx`
+
+## Complete Reference Table
+
+| Artifact | File Name | Export Name | Example |
+|----------|-----------|-------------|---------|
+| React Component | `user-card.tsx` | `UserCard` | `export function UserCard()` |
+| Client Component | `user-form.tsx` | `UserForm` | `export function UserForm()` + `'use client'` |
+| TanStack Query hook | `use-users.ts` | `useUsers` | `export function useUsers()` |
+| Mutation hook | `use-create-user.ts` | `useCreateUser` | `export function useCreateUser()` |
+| Utility hook | `use-debounce.ts` | `useDebounce` | `export function useDebounce()` |
+| Zod schema file | `user.schemas.ts` | `createUserSchema` | `export const createUserSchema = z.object(...)` |
+| TypeScript types | `user.types.ts` | `User`, `CreateUserInput` | `export type User = z.infer<typeof userSchema>` |
+| Feature index | `index.ts` | (re-exports) | `export { UserCard } from './components/user-card'` |
+| Page file | `page.tsx` | `default` | `export default function UsersPage()` |
+
+## Hook Naming Rules
+
+```
+GET list:    use-users.ts          → useUsers()
+GET single:  use-user.ts           → useUser(id: string)
+POST:        use-create-user.ts    → useCreateUser()
+PUT/PATCH:   use-update-user.ts    → useUpdateUser()
+DELETE:      use-delete-user.ts    → useDeleteUser()
+```
+
+## Schema and Type Naming Rules
+
+```typescript
+// user.schemas.ts
+export const userSchema = z.object({ id: z.string(), name: z.string() });
+export const createUserSchema = z.object({ name: z.string().min(2), email: z.email() });
+export const updateUserSchema = createUserSchema.partial();
+
+// user.types.ts — derive from schemas, don't duplicate
+export type User = z.infer<typeof userSchema>;
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+export type UpdateUserInput = z.infer<typeof updateUserSchema>;
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `UserCard.tsx` | `user-card.tsx` | Linux servers are case-sensitive |
+| `useUsers.ts` | `use-users.ts` | Inconsistent with Next.js file conventions |
+| `export default function UserCard` | `export function UserCard` | Named exports are more refactor-safe |
+| `type User = { id: string }` | `type User = z.infer<typeof userSchema>` | Single source of truth |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/nextjs-patterns.md

@@ -1,225 +1,229 @@
-# Next.js 15 Patterns Standard
-
-> **Scope:** nextjs-neon
-> **Layer:** 2 (on keyword)
-> **Keywords:** nextjs, react, app router, server component, client component
-> **Load When:** nextjs keywords detected
-
-Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
-
-## Core Rules
-
-- ALWAYS use App Router (not Pages Router)
-- Default to Server Components -- add `'use client'` only when needed
-- ALWAYS colocate loading.tsx and error.tsx with page.tsx
-- NEVER call the database directly from client -- use Route Handlers as BFF
-- ALWAYS validate inputs with Zod on both client and server
-- Use TypeScript strict mode (`"strict": true`)
-
-## Server vs Client Components
-
-| Aspect | Server Component (default) | Client Component (`'use client'`) |
-|--------|---------------------------|-----------------------------------|
-| Renders | Server only | Server SSR + Client hydration |
-| Access to | DB, env vars, fs, async/await | Browser APIs, useState, useEffect, events |
-| Bundle | Not included | Included in JS bundle |
-| Use when | Data fetching, static content | Interactivity, forms, real-time |
-
-Decision: Need useState/useEffect/onClick/browser APIs? Client Component. Otherwise Server Component.
-
-## File-Based Routing
-
-```
-app/
-  layout.tsx              # Root layout
-  page.tsx                # / (home)
-  loading.tsx / error.tsx # Loading UI / Error boundary
-  not-found.tsx           # 404
-  dashboard/
-    layout.tsx            # Nested layout
-    page.tsx              # /dashboard
-    loading.tsx
-  api/documents/
-    route.ts              # GET/POST /api/documents
-    [id]/route.ts         # GET/PUT/DELETE /api/documents/:id
-```
-
-## Layout and Error Boundaries
-
-```tsx
-export default function RootLayout({ children }: { children: React.ReactNode }) {
-  return <html lang="en"><body><Providers>{children}</Providers></body></html>;
-}
-
-// loading.tsx
-export default function Loading() { return <div className="animate-pulse">Loading...</div>; }
-
-// error.tsx — MUST be 'use client'
-'use client';
-export default function Error({ error, reset }: { error: Error; reset: () => void }) {
-  return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
-}
-```
-
-## Route Handlers (BFF Pattern)
-
-```ts
-// app/api/documents/route.ts — BFF pattern (delegates to .NET API)
-import { auth } from "@/lib/auth/server";
-import { NextResponse } from "next/server";
-import { z } from "zod";
-
-export const dynamic = "force-dynamic";
-
-const API_URL = process.env.API_URL!; // .NET backend
-
-const CreateSchema = z.object({
-  title: z.string().min(1).max(200),
-  content: z.string().min(1),
-});
-
-export async function GET() {
-  const { data: session } = await auth.getSession();
-  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-
-  const res = await fetch(`${API_URL}/api/documents`, {
-    headers: { Authorization: `Bearer ${session.session.access_token}` },
-  });
-  return NextResponse.json(await res.json());
-}
-
-export async function POST(request: Request) {
-  const { data: session } = await auth.getSession();
-  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-
-  const parsed = CreateSchema.safeParse(await request.json());
-  if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
-
-  const res = await fetch(`${API_URL}/api/documents`, {
-    method: "POST",
-    headers: { Authorization: `Bearer ${session.session.access_token}`, "Content-Type": "application/json" },
-    body: JSON.stringify(parsed.data),
-  });
-  return NextResponse.json(await res.json(), { status: res.status });
-}
-```
-
-> **Rule:** Route handlers act as BFF (Backend-For-Frontend) — they delegate to the .NET API. Database access lives in the .NET backend via EF Core, never in Next.js route handlers.
-
-## React Query + Neon
-
-```tsx
-// providers/query-provider.tsx
-'use client';
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { useState } from "react";
-
-export function QueryProvider({ children }: { children: React.ReactNode }) {
-  const [client] = useState(() => new QueryClient({
-    defaultOptions: { queries: { staleTime: 60_000, retry: 1 } },
-  }));
-  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
-}
-```
-
-```tsx
-// hooks/use-documents.ts
-export function useDocuments() {
-  return useQuery({
-    queryKey: ["documents"],
-    queryFn: async () => {
-      const res = await fetch("/api/documents");
-      if (!res.ok) throw new Error("Failed to fetch");
-      return res.json();
-    },
-  });
-}
-
-export function useCreateDocument() {
-  const qc = useQueryClient();
-  return useMutation({
-    mutationFn: async (data: { title: string; content: string }) => {
-      const res = await fetch("/api/documents", {
-        method: "POST", headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(data),
-      });
-      if (!res.ok) throw new Error("Failed to create");
-      return res.json();
-    },
-    onSuccess: () => qc.invalidateQueries({ queryKey: ["documents"] }),
-  });
-}
-```
-
-## Form Handling (react-hook-form + Zod)
-
-```tsx
-'use client';
-import { useForm } from "react-hook-form";
-import { zodResolver } from "@hookform/resolvers/zod";
-import { z } from "zod";
-
-const schema = z.object({
-  title: z.string().min(1, "Required").max(200),
-  content: z.string().min(1, "Required"),
-});
-
-export function DocumentForm() {
-  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<z.infer<typeof schema>>({
-    resolver: zodResolver(schema),
-  });
-  const create = useCreateDocument();
-  return (
-    <form onSubmit={handleSubmit((data) => create.mutateAsync(data))}>
-      <input {...register("title")} />
-      {errors.title && <span>{errors.title.message}</span>}
-      <textarea {...register("content")} />
-      {errors.content && <span>{errors.content.message}</span>}
-      <button type="submit" disabled={isSubmitting}>Save</button>
-    </form>
-  );
-}
-```
-
-## shadcn/ui
-
-Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog form`.
-Components are copied to `components/ui/` -- NOT an npm dependency, your code to customize.
-
-## TypeScript Strict Patterns
-
-| Pattern | Approach |
-|---------|----------|
-| API responses | Zod schema + `z.infer<typeof schema>` |
-| Props | Explicit interface, no `any` |
-| Event handlers | `React.ChangeEvent<HTMLInputElement>` |
-| Null safety | `?.` over type assertions, `if (!data) return null` |
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
-| Direct DB from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
-| `any` for API responses | Zod schema + infer | No runtime safety |
-| Missing loading.tsx | Colocate with page.tsx | Blank page during load |
-| `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
-| Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
-| shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |
-
-## TypeScript Strict Mode (Required)
-
-Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
-agent-assisted development because agents rely on compiler errors to self-correct.
-Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
-
-```json
-{
-  "compilerOptions": {
-    "strict": true,
-    "noUncheckedIndexedAccess": true
-  }
-}
-```
-
-Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.
+# Next.js 15 Patterns Standard
+
+> **Scope:** nextjs-neon
+> **Layer:** 2 (on keyword)
+> **Keywords:** nextjs, react, app router, server component, client component
+> **Load When:** nextjs keywords detected
+
+**Verified against:** Next.js 15 + TanStack Query 5 + Zod 4 + react-hook-form 7. Last-verified: 2026-05-20.
+
+---
+
+Stack: Next.js 15 + Neon PostgreSQL + .NET Backend
+
+## Core Rules
+
+- ALWAYS use App Router (not Pages Router)
+- Default to Server Components -- add `'use client'` only when needed
+- ALWAYS colocate loading.tsx and error.tsx with page.tsx
+- NEVER call the database directly from client -- use Route Handlers as BFF
+- ALWAYS validate inputs with Zod on both client and server
+- Use TypeScript strict mode (`"strict": true`)
+
+## Server vs Client Components
+
+| Aspect | Server Component (default) | Client Component (`'use client'`) |
+|--------|---------------------------|-----------------------------------|
+| Renders | Server only | Server SSR + Client hydration |
+| Access to | DB, env vars, fs, async/await | Browser APIs, useState, useEffect, events |
+| Bundle | Not included | Included in JS bundle |
+| Use when | Data fetching, static content | Interactivity, forms, real-time |
+
+Decision: Need useState/useEffect/onClick/browser APIs? Client Component. Otherwise Server Component.
+
+## File-Based Routing
+
+```
+app/
+  layout.tsx              # Root layout
+  page.tsx                # / (home)
+  loading.tsx / error.tsx # Loading UI / Error boundary
+  not-found.tsx           # 404
+  dashboard/
+    layout.tsx            # Nested layout
+    page.tsx              # /dashboard
+    loading.tsx
+  api/documents/
+    route.ts              # GET/POST /api/documents
+    [id]/route.ts         # GET/PUT/DELETE /api/documents/:id
+```
+
+## Layout and Error Boundaries
+
+```tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en"><body><Providers>{children}</Providers></body></html>;
+}
+
+// loading.tsx
+export default function Loading() { return <div className="animate-pulse">Loading...</div>; }
+
+// error.tsx — MUST be 'use client'
+'use client';
+export default function Error({ error, reset }: { error: Error; reset: () => void }) {
+  return <div><h2>Something went wrong</h2><button onClick={reset}>Try again</button></div>;
+}
+```
+
+## Route Handlers (BFF Pattern)
+
+```ts
+// app/api/documents/route.ts — BFF pattern (delegates to .NET API)
+import { auth } from "@/lib/auth/server";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+
+export const dynamic = "force-dynamic";
+
+const API_URL = process.env.API_URL!; // .NET backend
+
+const CreateSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+});
+
+export async function GET() {
+  const { data: session } = await auth.getSession();
+  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+
+  const res = await fetch(`${API_URL}/api/documents`, {
+    headers: { Authorization: `Bearer ${session.session.access_token}` },
+  });
+  return NextResponse.json(await res.json());
+}
+
+export async function POST(request: Request) {
+  const { data: session } = await auth.getSession();
+  if (!session?.user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+
+  const parsed = CreateSchema.safeParse(await request.json());
+  if (!parsed.success) return NextResponse.json({ error: parsed.error.flatten() }, { status: 400 });
+
+  const res = await fetch(`${API_URL}/api/documents`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${session.session.access_token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(parsed.data),
+  });
+  return NextResponse.json(await res.json(), { status: res.status });
+}
+```
+
+> **Rule:** Route handlers act as BFF (Backend-For-Frontend) — they delegate to the .NET API. Database access lives in the .NET backend via EF Core, never in Next.js route handlers.
+
+## React Query + Neon
+
+```tsx
+// providers/query-provider.tsx
+'use client';
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [client] = useState(() => new QueryClient({
+    defaultOptions: { queries: { staleTime: 60_000, retry: 1 } },
+  }));
+  return <QueryClientProvider client={client}>{children}</QueryClientProvider>;
+}
+```
+
+```tsx
+// hooks/use-documents.ts
+export function useDocuments() {
+  return useQuery({
+    queryKey: ["documents"],
+    queryFn: async () => {
+      const res = await fetch("/api/documents");
+      if (!res.ok) throw new Error("Failed to fetch");
+      return res.json();
+    },
+  });
+}
+
+export function useCreateDocument() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: async (data: { title: string; content: string }) => {
+      const res = await fetch("/api/documents", {
+        method: "POST", headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      if (!res.ok) throw new Error("Failed to create");
+      return res.json();
+    },
+    onSuccess: () => qc.invalidateQueries({ queryKey: ["documents"] }),
+  });
+}
+```
+
+## Form Handling (react-hook-form + Zod)
+
+```tsx
+'use client';
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const schema = z.object({
+  title: z.string().min(1, "Required").max(200),
+  content: z.string().min(1, "Required"),
+});
+
+export function DocumentForm() {
+  const { register, handleSubmit, formState: { errors, isSubmitting } } = useForm<z.infer<typeof schema>>({
+    resolver: zodResolver(schema),
+  });
+  const create = useCreateDocument();
+  return (
+    <form onSubmit={handleSubmit((data) => create.mutateAsync(data))}>
+      <input {...register("title")} />
+      {errors.title && <span>{errors.title.message}</span>}
+      <textarea {...register("content")} />
+      {errors.content && <span>{errors.content.message}</span>}
+      <button type="submit" disabled={isSubmitting}>Save</button>
+    </form>
+  );
+}
+```
+
+## shadcn/ui
+
+Install: `npx shadcn@latest init` then `npx shadcn@latest add button input card dialog form`.
+Components are copied to `components/ui/` -- NOT an npm dependency, your code to customize.
+
+## TypeScript Strict Patterns
+
+| Pattern | Approach |
+|---------|----------|
+| API responses | Zod schema + `z.infer<typeof schema>` |
+| Props | Explicit interface, no `any` |
+| Event handlers | `React.ChangeEvent<HTMLInputElement>` |
+| Null safety | `?.` over type assertions, `if (!data) return null` |
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `'use client'` on every component | Default to Server Components | Unnecessary JS bundle size |
+| Direct DB from client | Route Handler `/api/*` as BFF | Exposes queries, harder to secure |
+| `any` for API responses | Zod schema + infer | No runtime safety |
+| Missing loading.tsx | Colocate with page.tsx | Blank page during load |
+| `useEffect` for data fetching | React Query `useQuery` | No caching, race conditions |
+| Form validation on submit only | Zod resolver + react-hook-form | Delayed error feedback |
+| shadcn as npm package | `npx shadcn@latest add` | Copy-paste system, not a dependency |
+
+## TypeScript Strict Mode (Required)
+
+Always enable `"strict": true` in `tsconfig.json`. This is non-negotiable for
+agent-assisted development because agents rely on compiler errors to self-correct.
+Without strict mode, type/null errors only surface at runtime where agents cannot observe them.
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true
+  }
+}
+```
+
+Strict mode enables: `strictNullChecks`, `noImplicitAny`, `strictFunctionTypes`, `strictPropertyInitialization`.