@polymorphism-tech/morph-spec 4.6.0 → 4.7.0

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

@@ -0,0 +1,126 @@
+# 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*

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

@@ -0,0 +1,128 @@
+# Next.js Forms Standard
+
+> **Scope:** frontend/nextjs/forms
+> **Layer:** 2 (on keyword)
+> **Keywords:** form, react-hook-form, zod, validation, input, submit, zodResolver
+> **Load When:** implementing any form in Next.js
+
+react-hook-form + Zod + shadcn Form components. Schema defines both validation rules and TypeScript types.
+
+## Core Rules
+
+- ALWAYS define the Zod schema first — derive the TypeScript type from it with `z.infer<>`
+- ALWAYS use `zodResolver` to connect schema to react-hook-form
+- ALWAYS use shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormMessage>` for consistent UI
+- NEVER use `useState` for form field values — react-hook-form handles this
+- ALWAYS use `useMutation` from TanStack Query for form submission
+
+## Complete Form Pattern
+
+```tsx
+// features/users/types/user.schemas.ts
+import { z } from 'zod';
+
+export const createUserSchema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email address'),
+  role: z.enum(['admin', 'user'], { required_error: 'Role is required' }),
+});
+
+export type CreateUserInput = z.infer<typeof createUserSchema>;
+```
+
+```tsx
+// features/users/components/create-user-form.tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import {
+  Form, FormControl, FormField, FormItem, FormLabel, FormMessage
+} from '@/components/ui/form';
+import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import { useCreateUser } from '@/features/users/hooks/use-create-user';
+import { createUserSchema, type CreateUserInput } from '@/features/users/types/user.schemas';
+
+export function CreateUserForm({ onSuccess }: { onSuccess?: () => void }) {
+  const form = useForm<CreateUserInput>({
+    resolver: zodResolver(createUserSchema),
+    defaultValues: { name: '', email: '', role: 'user' },
+  });
+
+  const { mutate: createUser, isPending } = useCreateUser();
+
+  function onSubmit(values: CreateUserInput) {
+    createUser(values, {
+      onSuccess: () => { form.reset(); onSuccess?.(); },
+      onError: (error) => form.setError('root', { message: error.message }),
+    });
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl><Input placeholder="John Doe" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl><Input type="email" {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        {form.formState.errors.root && (
+          <p className="text-sm text-destructive">{form.formState.errors.root.message}</p>
+        )}
+        <Button type="submit" disabled={isPending}>
+          {isPending ? 'Creating...' : 'Create User'}
+        </Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## Edit Form Pattern
+
+```tsx
+// Edit forms reuse the same schema with partial()
+const form = useForm<UpdateUserInput>({
+  resolver: zodResolver(updateUserSchema),
+  defaultValues: { name: user.name, email: user.email },
+});
+```
+
+## Schema Composition
+
+```ts
+export const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string() });
+export const createUserSchema = userSchema.omit({ id: true });
+export const updateUserSchema = createUserSchema.partial();
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `useState` for each field | `useForm` | Unnecessary re-renders on every keystroke |
+| Manual error display | `<FormMessage />` | Consistent UI, auto-connects to field errors |
+| `fetch` in submit handler | `useMutation` | Loading state, error handling, cache invalidation |
+| Type written manually | `z.infer<typeof schema>` | Single source of truth |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

@@ -0,0 +1,67 @@
+# 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*

package/framework/standards/frontend/nextjs/project-structure.md

@@ -0,0 +1,102 @@
+# Next.js Project Structure Standard
+
+> **Scope:** frontend/nextjs/project-structure
+> **Layer:** 2 (on keyword)
+> **Keywords:** project structure, folder structure, feature folder, src layout
+> **Load When:** creating new files or features
+
+Feature-based architecture with a shared core. Features are self-contained; shared code is explicit.
+
+## Core Rules
+
+- ALWAYS use feature-based folders: `features/{feature-name}/`
+- ALWAYS keep `app/` for routing only — import from `features/`, not the other way
+- NEVER import from one feature into another — extract to `components/` or `lib/` if shared
+- ALWAYS use `src/` directory (configured in `tsconfig.json` with `@/` alias)
+- NEVER put business logic in `components/` — it is presentation only
+
+## Canonical Folder Tree
+
+```
+src/
+├── app/                                  # Next.js App Router — routes only
+│   ├── layout.tsx                        # Root layout + providers
+│   ├── page.tsx                          # Home page
+│   └── (dashboard)/
+│       ├── layout.tsx
+│       ├── users/
+│       │   ├── page.tsx
+│       │   ├── loading.tsx
+│       │   └── error.tsx
+│       └── billing/
+│           └── page.tsx
+│
+├── features/                             # Domain features
+│   └── {feature-name}/
+│       ├── components/                   # Feature-specific UI components
+│       │   ├── user-list.tsx
+│       │   └── user-card.tsx
+│       ├── hooks/                        # TanStack Query hooks for this feature
+│       │   ├── use-users.ts
+│       │   └── use-create-user.ts
+│       ├── types/
+│       │   ├── user.types.ts             # TypeScript types
+│       │   └── user.schemas.ts           # Zod schemas + z.infer<> types
+│       └── index.ts                      # Public API — only export what's needed
+│
+├── components/                           # Shared UI — no business logic
+│   ├── ui/                               # shadcn/ui — never edit directly
+│   │   ├── button.tsx
+│   │   └── card.tsx
+│   ├── data-table.tsx
+│   ├── page-header.tsx
+│   └── empty-state.tsx
+│
+├── hooks/                                # Shared utility hooks — no API calls
+│   ├── use-debounce.ts
+│   └── use-media-query.ts
+│
+├── lib/
+│   ├── api-client.ts                     # Typed fetch wrapper for .NET API
+│   └── query-client.tsx                  # TanStack Query client + provider
+│
+├── types/
+│   ├── api.ts                            # Shared API shapes: PaginatedResponse<T>, ApiError
+│   └── env.d.ts
+│
+└── env.mjs                               # Zod-validated env vars
+```
+
+## Feature Index Pattern
+
+```ts
+// features/users/index.ts — explicit public API
+export { UserList } from './components/user-list';
+export { UserCard } from './components/user-card';
+export { useUsers } from './hooks/use-users';
+export { useCreateUser } from './hooks/use-create-user';
+export type { User, CreateUserInput } from './types/user.types';
+```
+
+Import from the index, not deep paths:
+```ts
+// GOOD
+import { UserList, useUsers } from '@/features/users';
+
+// BAD
+import { UserList } from '@/features/users/components/user-list';
+```
+
+## Feature Boundary Rule
+
+```
+app/              → imports from features/ ✓
+features/users/   → imports from components/ and lib/ ✓
+features/users/   → imports from features/billing/ ✗ (extract shared instead)
+components/       → imports from components/ui/ ✓
+components/       → imports from features/ ✗
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/state-management.md

@@ -0,0 +1,72 @@
+# Next.js State Management Standard
+
+> **Scope:** frontend/nextjs/state-management
+> **Layer:** 2 (on keyword)
+> **Keywords:** state, zustand, context, redux, client state, server state, useState
+> **Load When:** deciding how to manage state in Next.js
+
+Server state (API data) lives in TanStack Query. UI state lives in React. No global state library unless genuinely needed.
+
+## Core Rules
+
+- ALWAYS use TanStack Query for anything that comes from the .NET API
+- ALWAYS use `useState` for local UI state (modal open, selected tab, form step)
+- NEVER install Zustand or Redux without first exhausting Server Components + TanStack Query
+- NEVER use React Context for server state — Context does not cache or deduplicate
+- ALWAYS derive state from server data rather than syncing it to local state
+
+## State Decision Tree
+
+```
+Is this data from the .NET API?
+  YES → TanStack Query (useQuery / useMutation)
+
+Is this local UI state (open/closed, selected, current step)?
+  YES → useState in the component that needs it
+
+Does multiple components need this UI state?
+  YES — is it parent-child?     → prop drilling (2-3 levels is fine)
+  YES — is it truly global?     → React Context (theme, auth user, locale)
+  YES — complex with many actions? → Consider Zustand (last resort)
+```
+
+## Server State (TanStack Query)
+
+```ts
+// GOOD — server state in TanStack Query
+const { data: users } = useUsers(); // cached, deduplicated, background-refetched
+
+// BAD — copying server state to useState
+const [users, setUsers] = useState([]);
+useEffect(() => { fetchUsers().then(setUsers); }, []);
+```
+
+## Local UI State (useState)
+
+```tsx
+function UserList() {
+  const [isCreateDialogOpen, setIsCreateDialogOpen] = useState(false);
+  const [selectedUserId, setSelectedUserId] = useState<string | null>(null);
+}
+```
+
+## When Zustand Is Justified
+
+Only add Zustand if ALL of these are true:
+1. State is needed in 5+ unrelated components
+2. State has complex update logic (not just toggle/set)
+3. Context causes measurable re-render performance issues
+4. State is not from the server
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `useEffect` + `useState` for API data | TanStack Query | Stale data, no cache, double-render |
+| Global store for user list | `useUsers()` | TanStack Query handles sync/cache |
+| Context for everything | useState + prop drilling first | Context causes all consumers to re-render |
+| Zustand by default | Start with useState | YAGNI — most state is local |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

@@ -0,0 +1,111 @@
+# Next.js Testing Standard
+
+> **Scope:** frontend/nextjs/testing
+> **Layer:** 2 (on keyword)
+> **Keywords:** testing, jest, vitest, testing-library, msw, component test, unit test
+> **Load When:** writing tests for Next.js components or hooks
+
+Jest + React Testing Library for component tests. MSW for API mocking. Co-locate tests with the code they test.
+
+## Core Rules
+
+- ALWAYS co-locate test files: `user-card.test.tsx` next to `user-card.tsx`
+- ALWAYS use `@testing-library/user-event` for interactions — not `fireEvent`
+- ALWAYS mock the API layer with MSW — never mock `fetch` directly
+- NEVER test implementation details — test what the user sees
+- ALWAYS test the happy path + one error path per component
+
+## Test File Co-location
+
+```
+features/users/
+├── components/
+│   ├── user-card.tsx
+│   ├── user-card.test.tsx      ← co-located
+│   ├── user-list.tsx
+│   └── user-list.test.tsx
+├── hooks/
+│   ├── use-users.ts
+│   └── use-users.test.ts       ← co-located
+```
+
+## Component Test Pattern
+
+```tsx
+// features/users/components/user-card.test.tsx
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { UserCard } from './user-card';
+
+const mockUser = { id: '1', name: 'João Silva', email: 'joao@example.com', role: 'user' as const };
+
+describe('UserCard', () => {
+  it('renders user name and email', () => {
+    render(<UserCard user={mockUser} />);
+    expect(screen.getByText('João Silva')).toBeInTheDocument();
+    expect(screen.getByText('joao@example.com')).toBeInTheDocument();
+  });
+
+  it('calls onEdit with user id when edit button clicked', async () => {
+    const onEdit = vi.fn();
+    render(<UserCard user={mockUser} onEdit={onEdit} />);
+    await userEvent.click(screen.getByRole('button', { name: /edit/i }));
+    expect(onEdit).toHaveBeenCalledWith('1');
+  });
+});
+```
+
+## Hook Test with MSW
+
+```ts
+// features/users/hooks/use-users.test.ts
+import { renderHook, waitFor } from '@testing-library/react';
+import { http, HttpResponse } from 'msw';
+import { server } from '@/test/msw-server';
+import { QueryClientWrapper } from '@/test/helpers';
+import { useUsers } from './use-users';
+
+describe('useUsers', () => {
+  it('returns users from API', async () => {
+    server.use(
+      http.get('/api/proxy/users', () =>
+        HttpResponse.json([{ id: '1', name: 'João', email: 'j@ex.com' }])
+      )
+    );
+    const { result } = renderHook(() => useUsers(), { wrapper: QueryClientWrapper });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data).toHaveLength(1);
+  });
+
+  it('returns error state when API fails', async () => {
+    server.use(http.get('/api/proxy/users', () => new HttpResponse(null, { status: 500 })));
+    const { result } = renderHook(() => useUsers(), { wrapper: QueryClientWrapper });
+    await waitFor(() => expect(result.current.isError).toBe(true));
+  });
+});
+```
+
+## Test Helper Setup
+
+```tsx
+// test/helpers.tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+export function QueryClientWrapper({ children }: { children: React.ReactNode }) {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `fireEvent.click(button)` | `await userEvent.click(button)` | userEvent simulates real browser events |
+| Mock `global.fetch` | Mock with MSW | MSW intercepts at network level |
+| `expect(component).toMatchSnapshot()` | `expect(screen.getByText(...))` | Snapshots break on any change |
+| Test file in `__tests__/` folder | Co-locate with source | Easier to find, deleted with the component |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*