npm - @polymorphism-tech/morph-spec - Versions diffs - 4.7.1 → 4.7.2 - Mend

@polymorphism-tech/morph-spec 4.7.1 → 4.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (232) hide show

package/.morph/framework/standards/frontend/nextjs/nextjs-patterns.md ADDED Viewed

@@ -0,0 +1,215 @@
+# Next.js 15 Patterns Standard
+> **Scope:** nextjs-supabase
+> **Layer:** 2 (on keyword)
+> **Keywords:** nextjs, react, app router, server component, client component
+> **Load When:** nextjs keywords detected
+Stack: Next.js 15 + Supabase + .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 Supabase 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
+import { createClient } from "@/lib/supabase/server";
+import { NextResponse } from "next/server";
+import { z } from "zod";
+const CreateSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().min(1),
+});
+export async function GET() {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!user) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  const { data, error } = await supabase.from("documents").select("*");
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+  return NextResponse.json(data);
+}
+export async function POST(request: Request) {
+  const supabase = await createClient();
+  const { data: { user } } = await supabase.auth.getUser();
+  if (!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 { data, error } = await supabase
+    .from("documents").insert({ ...parsed.data, user_id: user.id }).select().single();
+  if (error) return NextResponse.json({ error: error.message }, { status: 500 });
+  return NextResponse.json(data, { status: 201 });
+}
+```
+## React Query + Supabase
+```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 Supabase 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`.

package/.morph/framework/standards/frontend/nextjs/project-structure.md ADDED Viewed

@@ -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/.morph/framework/standards/frontend/nextjs/state-management.md ADDED Viewed

@@ -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/.morph/framework/standards/frontend/nextjs/testing.md ADDED Viewed

@@ -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*