@polymorphism-tech/morph-spec 6.0.0 → 7.1.0

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

@@ -1,102 +1,106 @@
-# 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*
+# 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
+
+**Verified against:** Next.js 15 (App Router, `src/` layout). Last-verified: 2026-05-20.
+
+---
+
+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

@@ -1,72 +1,76 @@
-# 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*
+# 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
+
+**Verified against:** Next.js 15 + TanStack Query 5 + Zustand 5. Last-verified: 2026-05-20.
+
+---
+
+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

@@ -1,111 +1,115 @@
-# 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*
+# Next.js Testing Standard
+
+> **Scope:** frontend/nextjs/testing
+> **Layer:** 2 (on keyword)
+> **Keywords:** testing, vitest, jest, testing-library, msw, component test, unit test
+> **Load When:** writing tests for Next.js components or hooks
+
+**Verified against:** Vitest 3 + React Testing Library 16 + MSW 2. Last-verified: 2026-05-20.
+
+---
+
+Vitest + 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*