@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/framework/standards/frontend/nextjs/components.md

@@ -1,132 +1,136 @@
-# Next.js Component Standards
-
-> **Scope:** frontend/nextjs/components
-> **Layer:** 2 (on keyword)
-> **Keywords:** component, shadcn, reusable, shared, ui, three-tier
-> **Load When:** creating or editing React components
-
-Three-tier component hierarchy. `components/ui/` is shadcn primitives (never edit). `components/` is composed shared (no business logic). `features/*/components/` is feature-scoped.
-
-## Core Rules
-
-- NEVER edit files in `components/ui/` — they are regenerated by shadcn CLI
-- NEVER import from `features/` inside `components/` — components know nothing about domain
-- ALWAYS compose shadcn primitives in `components/` instead of editing them
-- ALWAYS add `'use client'` only if the component uses hooks, events, or browser APIs
-- NEVER pass raw API data directly to a component — transform to props first
-
-## Three-Tier Hierarchy
-
-```
-Tier 1: components/ui/         ← shadcn/ui CLI output (DO NOT EDIT)
-           ↓ composed into
-Tier 2: components/            ← shared project components (no business logic)
-           ↓ used by
-Tier 3: features/*/components/ ← feature-scoped (knows about users, billing, etc.)
-```
-
-## Tier 1 — shadcn/ui Primitives
-
-```bash
-# Add shadcn components via CLI — never write them manually
-npx shadcn@latest add button card dialog form input table
-```
-
-If you need to change a shadcn component's behavior, wrap it — do not edit the source file.
-
-## Tier 2 — Shared Composed Components
-
-```tsx
-// components/data-table.tsx — composes shadcn Table + TanStack Table
-'use client';
-
-import {
-  Table, TableBody, TableCell, TableHead, TableHeader, TableRow
-} from '@/components/ui/table';
-import {
-  type ColumnDef, flexRender, getCoreRowModel, useReactTable
-} from '@tanstack/react-table';
-
-interface DataTableProps<TData> {
-  columns: ColumnDef<TData>[];
-  data: TData[];
-}
-
-export function DataTable<TData>({ columns, data }: DataTableProps<TData>) {
-  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
-  return (
-    <Table>
-      <TableHeader>
-        {table.getHeaderGroups().map((hg) => (
-          <TableRow key={hg.id}>
-            {hg.headers.map((h) => (
-              <TableHead key={h.id}>
-                {flexRender(h.column.columnDef.header, h.getContext())}
-              </TableHead>
-            ))}
-          </TableRow>
-        ))}
-      </TableHeader>
-      <TableBody>
-        {table.getRowModel().rows.map((row) => (
-          <TableRow key={row.id}>
-            {row.getVisibleCells().map((cell) => (
-              <TableCell key={cell.id}>
-                {flexRender(cell.column.columnDef.cell, cell.getContext())}
-              </TableCell>
-            ))}
-          </TableRow>
-        ))}
-      </TableBody>
-    </Table>
-  );
-}
-```
-
-## Tier 3 — Feature Components
-
-```tsx
-// features/users/components/user-list.tsx
-'use client';
-
-import { DataTable } from '@/components/data-table';
-import { useUsers } from '@/features/users/hooks/use-users';
-import type { ColumnDef } from '@tanstack/react-table';
-import type { User } from '@/features/users/types/user.types';
-
-const columns: ColumnDef<User>[] = [
-  { accessorKey: 'name', header: 'Name' },
-  { accessorKey: 'email', header: 'Email' },
-];
-
-export function UserList() {
-  const { data: users = [], isLoading } = useUsers();
-  if (isLoading) return <div>Loading...</div>;
-  return <DataTable columns={columns} data={users} />;
-}
-```
-
-## Component Props Conventions
-
-```tsx
-interface UserCardProps {
-  user: User;
-  onEdit?: (id: string) => void;
-  className?: string; // Always allow className for Tailwind override
-}
-
-export function UserCard({ user, onEdit, className }: UserCardProps) {}
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| Edit `components/ui/button.tsx` | Wrap in `components/action-button.tsx` | shadcn CLI overwrites it |
-| `import { useUsers } from '@/features/users'` in `components/` | Move to a feature component | Breaks tier isolation |
-| `'use client'` on all components | Only on interactive ones | Unnecessary client JS |
-| Pass raw fetch response as prop | Type and validate with Zod first | Runtime type safety |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Next.js Component Standards
+
+> **Scope:** frontend/nextjs/components
+> **Layer:** 2 (on keyword)
+> **Keywords:** component, shadcn, reusable, shared, ui, three-tier
+> **Load When:** creating or editing React components
+
+**Verified against:** Next.js 15 + shadcn/ui CLI + TanStack Table 8. Last-verified: 2026-05-20.
+
+---
+
+Three-tier component hierarchy. `components/ui/` is shadcn primitives (never edit). `components/` is composed shared (no business logic). `features/*/components/` is feature-scoped.
+
+## Core Rules
+
+- NEVER edit files in `components/ui/` — they are regenerated by shadcn CLI
+- NEVER import from `features/` inside `components/` — components know nothing about domain
+- ALWAYS compose shadcn primitives in `components/` instead of editing them
+- ALWAYS add `'use client'` only if the component uses hooks, events, or browser APIs
+- NEVER pass raw API data directly to a component — transform to props first
+
+## Three-Tier Hierarchy
+
+```
+Tier 1: components/ui/         ← shadcn/ui CLI output (DO NOT EDIT)
+           ↓ composed into
+Tier 2: components/            ← shared project components (no business logic)
+           ↓ used by
+Tier 3: features/*/components/ ← feature-scoped (knows about users, billing, etc.)
+```
+
+## Tier 1 — shadcn/ui Primitives
+
+```bash
+# Add shadcn components via CLI — never write them manually
+npx shadcn@latest add button card dialog form input table
+```
+
+If you need to change a shadcn component's behavior, wrap it — do not edit the source file.
+
+## Tier 2 — Shared Composed Components
+
+```tsx
+// components/data-table.tsx — composes shadcn Table + TanStack Table
+'use client';
+
+import {
+  Table, TableBody, TableCell, TableHead, TableHeader, TableRow
+} from '@/components/ui/table';
+import {
+  type ColumnDef, flexRender, getCoreRowModel, useReactTable
+} from '@tanstack/react-table';
+
+interface DataTableProps<TData> {
+  columns: ColumnDef<TData>[];
+  data: TData[];
+}
+
+export function DataTable<TData>({ columns, data }: DataTableProps<TData>) {
+  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+  return (
+    <Table>
+      <TableHeader>
+        {table.getHeaderGroups().map((hg) => (
+          <TableRow key={hg.id}>
+            {hg.headers.map((h) => (
+              <TableHead key={h.id}>
+                {flexRender(h.column.columnDef.header, h.getContext())}
+              </TableHead>
+            ))}
+          </TableRow>
+        ))}
+      </TableHeader>
+      <TableBody>
+        {table.getRowModel().rows.map((row) => (
+          <TableRow key={row.id}>
+            {row.getVisibleCells().map((cell) => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+## Tier 3 — Feature Components
+
+```tsx
+// features/users/components/user-list.tsx
+'use client';
+
+import { DataTable } from '@/components/data-table';
+import { useUsers } from '@/features/users/hooks/use-users';
+import type { ColumnDef } from '@tanstack/react-table';
+import type { User } from '@/features/users/types/user.types';
+
+const columns: ColumnDef<User>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+];
+
+export function UserList() {
+  const { data: users = [], isLoading } = useUsers();
+  if (isLoading) return <div>Loading...</div>;
+  return <DataTable columns={columns} data={users} />;
+}
+```
+
+## Component Props Conventions
+
+```tsx
+interface UserCardProps {
+  user: User;
+  onEdit?: (id: string) => void;
+  className?: string; // Always allow className for Tailwind override
+}
+
+export function UserCard({ user, onEdit, className }: UserCardProps) {}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| Edit `components/ui/button.tsx` | Wrap in `components/action-button.tsx` | shadcn CLI overwrites it |
+| `import { useUsers } from '@/features/users'` in `components/` | Move to a feature component | Breaks tier isolation |
+| `'use client'` on all components | Only on interactive ones | Unnecessary client JS |
+| Pass raw fetch response as prop | Type and validate with Zod first | Runtime type safety |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/data-fetching.md

@@ -1,126 +1,130 @@
-# Next.js Data Fetching Standard
-
-> **Scope:** frontend/nextjs/data-fetching
-> **Layer:** 2 (on keyword)
-> **Keywords:** data fetching, tanstack query, react query, server component, fetch, api, useQuery, useMutation
-> **Load When:** fetching data from .NET API
-
-Server Components for initial page load. TanStack Query for client mutations and interactive data. Never `useEffect` for fetching.
-
-## Core Rules
-
-- ALWAYS use Server Components for initial data that doesn't require interactivity
-- ALWAYS use TanStack Query (`useQuery`, `useMutation`) for client-side data needs
-- NEVER use `useEffect(() => { fetch(...) }, [])` — this is the old pattern
-- ALWAYS validate API responses with Zod before using them
-- ALWAYS use query key factories for consistent cache invalidation
-
-## TanStack Query Setup
-
-```tsx
-// lib/query-client.tsx
-'use client';
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { useState } from 'react';
-
-export function QueryProvider({ children }: { children: React.ReactNode }) {
-  const [queryClient] = useState(() => new QueryClient({
-    defaultOptions: { queries: { staleTime: 60 * 1000, retry: 1 } },
-  }));
-  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
-}
-```
-
-## Query Key Factory Pattern
-
-```ts
-// features/users/hooks/query-keys.ts
-export const userKeys = {
-  all: ['users'] as const,
-  lists: () => [...userKeys.all, 'list'] as const,
-  list: (filters: Record<string, unknown>) => [...userKeys.lists(), filters] as const,
-  details: () => [...userKeys.all, 'detail'] as const,
-  detail: (id: string) => [...userKeys.details(), id] as const,
-};
-```
-
-## useQuery Hook Pattern
-
-```ts
-// features/users/hooks/use-users.ts
-import { useQuery } from '@tanstack/react-query';
-import { userKeys } from './query-keys';
-import { z } from 'zod';
-import { userSchema } from '@/features/users/types/user.schemas';
-
-const usersResponseSchema = z.array(userSchema);
-
-export function useUsers() {
-  return useQuery({
-    queryKey: userKeys.lists(),
-    queryFn: async () => {
-      const res = await fetch('/api/proxy/users');
-      if (!res.ok) throw new Error('Failed to fetch users');
-      return usersResponseSchema.parse(await res.json());
-    },
-  });
-}
-```
-
-## useMutation Hook Pattern
-
-```ts
-// features/users/hooks/use-create-user.ts
-import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { userKeys } from './query-keys';
-import type { CreateUserInput } from '@/features/users/types/user.types';
-
-export function useCreateUser() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: async (input: CreateUserInput) => {
-      const res = await fetch('/api/proxy/users', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(input),
-      });
-      if (!res.ok) throw new Error('Failed to create user');
-      return res.json();
-    },
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
-    },
-  });
-}
-```
-
-## Server Component + TanStack Query Handoff
-
-```tsx
-// app/(dashboard)/users/page.tsx — Server Component: initial fetch
-export default async function UsersPage() {
-  const initialUsers = await fetch(`${process.env.API_URL}/api/users`).then(r => r.json());
-  return <UserListClient initialData={initialUsers} />;
-}
-
-// features/users/components/user-list-client.tsx — Client Component
-'use client';
-export function UserListClient({ initialData }: { initialData: User[] }) {
-  const { data: users = initialData } = useUsers();
-  // mutations, filtering, etc.
-}
-```
-
-## Common Mistakes
-
-| Wrong | Right | Why |
-|-------|-------|-----|
-| `useEffect(() => { fetch(...) }, [])` | `useQuery(...)` | Two renders, no cache, no SSR |
-| No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
-| Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
-| `queryClient.invalidateQueries(['users'])` | `{ queryKey: userKeys.lists() }` | Object syntax required in v5 |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# Next.js Data Fetching Standard
+
+> **Scope:** frontend/nextjs/data-fetching
+> **Layer:** 2 (on keyword)
+> **Keywords:** data fetching, tanstack query, react query, server component, fetch, api, useQuery, useMutation
+> **Load When:** fetching data from .NET API
+
+**Verified against:** Next.js 15 + TanStack Query 5 + Zod 4. Last-verified: 2026-05-20.
+
+---
+
+Server Components for initial page load. TanStack Query for client mutations and interactive data. Never `useEffect` for fetching.
+
+## Core Rules
+
+- ALWAYS use Server Components for initial data that doesn't require interactivity
+- ALWAYS use TanStack Query (`useQuery`, `useMutation`) for client-side data needs
+- NEVER use `useEffect(() => { fetch(...) }, [])` — this is the old pattern
+- ALWAYS validate API responses with Zod before using them
+- ALWAYS use query key factories for consistent cache invalidation
+
+## TanStack Query Setup
+
+```tsx
+// lib/query-client.tsx
+'use client';
+
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useState } from 'react';
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: { queries: { staleTime: 60 * 1000, retry: 1 } },
+  }));
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}
+```
+
+## Query Key Factory Pattern
+
+```ts
+// features/users/hooks/query-keys.ts
+export const userKeys = {
+  all: ['users'] as const,
+  lists: () => [...userKeys.all, 'list'] as const,
+  list: (filters: Record<string, unknown>) => [...userKeys.lists(), filters] as const,
+  details: () => [...userKeys.all, 'detail'] as const,
+  detail: (id: string) => [...userKeys.details(), id] as const,
+};
+```
+
+## useQuery Hook Pattern
+
+```ts
+// features/users/hooks/use-users.ts
+import { useQuery } from '@tanstack/react-query';
+import { userKeys } from './query-keys';
+import { z } from 'zod';
+import { userSchema } from '@/features/users/types/user.schemas';
+
+const usersResponseSchema = z.array(userSchema);
+
+export function useUsers() {
+  return useQuery({
+    queryKey: userKeys.lists(),
+    queryFn: async () => {
+      const res = await fetch('/api/proxy/users');
+      if (!res.ok) throw new Error('Failed to fetch users');
+      return usersResponseSchema.parse(await res.json());
+    },
+  });
+}
+```
+
+## useMutation Hook Pattern
+
+```ts
+// features/users/hooks/use-create-user.ts
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { userKeys } from './query-keys';
+import type { CreateUserInput } from '@/features/users/types/user.types';
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async (input: CreateUserInput) => {
+      const res = await fetch('/api/proxy/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(input),
+      });
+      if (!res.ok) throw new Error('Failed to create user');
+      return res.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+    },
+  });
+}
+```
+
+## Server Component + TanStack Query Handoff
+
+```tsx
+// app/(dashboard)/users/page.tsx — Server Component: initial fetch
+export default async function UsersPage() {
+  const initialUsers = await fetch(`${process.env.API_URL}/api/users`).then(r => r.json());
+  return <UserListClient initialData={initialUsers} />;
+}
+
+// features/users/components/user-list-client.tsx — Client Component
+'use client';
+export function UserListClient({ initialData }: { initialData: User[] }) {
+  const { data: users = initialData } = useUsers();
+  // mutations, filtering, etc.
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `useEffect(() => { fetch(...) }, [])` | `useQuery(...)` | Two renders, no cache, no SSR |
+| No Zod on API response | `schema.parse(await res.json())` | Type safety at runtime |
+| Hardcoded query keys: `['users']` | Key factory: `userKeys.lists()` | Consistent invalidation |
+| `queryClient.invalidateQueries(['users'])` | `{ queryKey: userKeys.lists() }` | Object syntax required in v5 |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*