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/app-router.md ADDED Viewed

@@ -0,0 +1,123 @@
+# Next.js App Router Standard
+> **Scope:** frontend/nextjs/app-router
+> **Layer:** 2 (on keyword)
+> **Keywords:** next.js, app router, server component, client component, page, layout, route
+> **Load When:** editing files in `app/` or `features/` directories
+Next.js App Router with TypeScript strict mode. Server Components by default, Client Components only when interactivity is required.
+## Core Rules
+- ALWAYS default to Server Components — add `'use client'` only when needed
+- ALWAYS keep `app/` directory for routing only — no business logic in page files
+- NEVER put data fetching in Client Components when a Server Component can do it
+- NEVER use `useEffect` to fetch data — use Server Components or TanStack Query
+- ALWAYS co-locate loading/error UI: `loading.tsx`, `error.tsx` next to `page.tsx`
+- ALWAYS use TypeScript — no `.js` or `.jsx` files in the project
+## Server vs Client Components
+| Use Server Component | Use Client Component |
+|---------------------|---------------------|
+| Fetching from .NET API on load | onClick, onChange, form submit |
+| Rendering static or user-specific data | useState, useEffect, useRef |
+| Accessing backend environment variables | Browser APIs (localStorage, geolocation) |
+| SEO-critical content | TanStack Query hooks |
+| No interactivity needed | shadcn/ui interactive components |
+## Decision Tree
+```
+Does this component need user interaction (click, input, hover state)?
+  YES → 'use client'
+  NO  → Does it fetch data?
+          YES → Server Component (fetch directly)
+          NO  → Server Component (static)
+```
+## App Directory Structure
+```
+src/app/
+├── (auth)/
+│   ├── login/
+│   │   └── page.tsx           # Server Component — renders login form
+│   └── register/
+│       └── page.tsx
+├── (dashboard)/
+│   ├── layout.tsx             # Shared layout for dashboard routes
+│   ├── page.tsx               # Dashboard home
+│   └── users/
+│       ├── page.tsx           # User list (Server Component)
+│       ├── [id]/
+│       │   └── page.tsx       # User detail
+│       ├── loading.tsx        # Suspense fallback
+│       └── error.tsx          # Error boundary
+└── layout.tsx                 # Root layout — providers, fonts, metadata
+```
+## File Conventions
+| File | Purpose | Type |
+|------|---------|------|
+| `page.tsx` | Route segment UI | Server Component (default) |
+| `layout.tsx` | Shared UI wrapper | Server Component |
+| `loading.tsx` | Suspense fallback | Server Component |
+| `error.tsx` | Error boundary | **Must be Client Component** |
+| `not-found.tsx` | 404 page | Server Component |
+| `route.ts` | API route (avoid — use .NET API) | — |
+## Server Component Data Fetch Pattern
+```tsx
+// app/(dashboard)/users/page.tsx
+import { UserList } from '@/features/users/components/user-list';
+async function getUsers(): Promise<User[]> {
+  const res = await fetch(`${process.env.API_URL}/api/users`, {
+    next: { revalidate: 60 },
+  });
+  if (!res.ok) throw new Error('Failed to fetch users');
+  return res.json();
+}
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialUsers={users} />;
+}
+```
+## Root Layout — Required Providers
+```tsx
+// app/layout.tsx
+import { QueryProvider } from '@/lib/query-client';
+import { Toaster } from '@/components/ui/sonner';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR">
+      <body>
+        <QueryProvider>
+          {children}
+          <Toaster />
+        </QueryProvider>
+      </body>
+    </html>
+  );
+}
+```
+## Common Mistakes
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `'use client'` on every component | Only add when needed | Kills SSR benefits, bloats JS bundle |
+| `useEffect(() => { fetch(...) }, [])` | Server Component fetch or TanStack Query | Two renders, no caching, no SSR |
+| Business logic in `page.tsx` | Move to `features/` | pages are routes, not controllers |
+| `fetch` without error handling | Always check `res.ok` | Silent failures in production |
+---
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/frontend/nextjs/components.md ADDED Viewed

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

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

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

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

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