@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -43,7 +43,7 @@ Skipping this chain is the most common cause of a page whose images do not feel
 
 ```javascript
 // Generate a new image
-mcp__gemini_image_mcp__generate_image({
+mcp__gemini-image-mcp__generate_image({
   prompt: string,           // Text description (max 5000 chars, narrative style)
   aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "9:16" | "16:9",
   outputPath?: string,      // File path to save (e.g., "public/images/feature/hero.png")
@@ -51,25 +51,25 @@ mcp__gemini_image_mcp__generate_image({
 })
 
 // Edit an existing image
-mcp__gemini_image_mcp__edit_image({
+mcp__gemini-image-mcp__edit_image({
   imageSource: string,      // Path to image or image ID
   prompt: string,           // Short, targeted edit instructions (1-2 sentences)
   outputPath?: string,
 })
 
 // Continue editing last image
-mcp__gemini_image_mcp__continue_editing({
+mcp__gemini-image-mcp__continue_editing({
   prompt: string,           // One adjustment at a time
 })
 
 // List generated images
-mcp__gemini_image_mcp__list_images({
+mcp__gemini-image-mcp__list_images({
   type?: "generated" | "edited" | "all",
   limit?: number,
 })
 
 // Get image details
-mcp__gemini_image_mcp__get_image_info({
+mcp__gemini-image-mcp__get_image_info({
   imageId?: string,         // Defaults to last image
 })
 ```

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

@@ -5,7 +5,7 @@
 > **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.
+**Verified against:** Next.js 16 + shadcn 4 CLI (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
 
 ---
 
@@ -33,83 +33,62 @@ Tier 3: features/*/components/ ← feature-scoped (knows about users, billing, e
 
 ```bash
 # Add shadcn components via CLI — never write them manually
-npx shadcn@latest add button card dialog form input table
+npx shadcn@latest add button card dialog field 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
 
+Composes shadcn primitives and knows nothing about the domain.
+
 ```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[];
+// components/page-header.tsx
+import type { ReactNode } from 'react';
+import { cn } from '@/lib/utils';
+
+interface PageHeaderProps {
+  title: string;
+  description?: string;
+  actions?: ReactNode;
+  className?: string;
 }
 
-export function DataTable<TData>({ columns, data }: DataTableProps<TData>) {
-  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+export function PageHeader({ title, description, actions, className }: PageHeaderProps) {
   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>
+    <div className={cn('flex items-start justify-between gap-4', className)}>
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+        {description && <p className="text-sm text-muted-foreground">{description}</p>}
+      </div>
+      {actions && <div className="flex gap-2">{actions}</div>}
+    </div>
   );
 }
 ```
 
+**The shared data table has one home: `admin-app/data-table.md`.** It is the Tier 2 component with the most rules — pagination, sorting and filtering on the server, the three states, selection — so it is specified there, once. Do not write a second `components/data-table.tsx` from this page.
+
 ## 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} />;
+// features/users/components/users-page-header.tsx
+import { PageHeader } from '@/components/page-header';
+import { Button } from '@/components/ui/button';
+
+export function UsersPageHeader({ canInvite }: { canInvite: boolean }) {
+  return (
+    <PageHeader
+      title="Users"
+      description="People with access to this workspace."
+      actions={canInvite ? <Button>Invite user</Button> : null}
+    />
+  );
 }
 ```
 
+A feature **list** is a Tier 3 component too: the feature owns the columns and the URL ⇄ table mapping, the shared table owns the rendering — `admin-app/data-table.md` → "The Feature Table".
+
 ## Component Props Conventions
 
 ```tsx

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

@@ -18,6 +18,7 @@ Server Components for initial page load. TanStack Query for client mutations and
 - 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
+- NEVER fetch a whole collection to page, sort or filter it in the browser — a list is paged on the server, with the query in the URL (`admin-app/data-table.md`)
 
 ## TanStack Query Setup
 

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

@@ -2,20 +2,22 @@
 
 > **Scope:** frontend/nextjs/forms
 > **Layer:** 2 (on keyword)
-> **Keywords:** form, react-hook-form, zod, validation, input, submit, zodResolver
+> **Keywords:** form, react-hook-form, zod, validation, input, submit, zodResolver, Controller, Field, FieldError
 > **Load When:** implementing any form in Next.js
 
-**Verified against:** Next.js 15 + react-hook-form 7 + Zod 4 + @hookform/resolvers 3. Last-verified: 2026-05-20.
+**Verified against:** Next.js 16 + react-hook-form 7 + Zod 4 + @hookform/resolvers 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
 
 ---
 
-react-hook-form + Zod + shadcn Form components. Schema defines both validation rules and TypeScript types.
+react-hook-form + Zod + shadcn `Field` components, wired through react-hook-form's `Controller`. The schema defines both the validation rules and the TypeScript types.
+
+**Admin app / CRUD screen?** This is the base pattern; `admin-app/forms.md` adds what a CRUD form needs on top of it — server validation errors on the field, where the form lives (dialog, sheet, page), validation timing and the unsaved-changes guard.
 
 ## Core Rules
 
-- ALWAYS define the Zod schema first — derive the TypeScript type from it with `z.infer<>`
+- ALWAYS define the Zod schema first — derive the TypeScript type from it with `z.infer<>` (or `z.input<>`/`z.output<>` when the schema coerces)
 - ALWAYS use `zodResolver` to connect schema to react-hook-form
-- ALWAYS use shadcn `<Form>`, `<FormField>`, `<FormItem>`, `<FormMessage>` for consistent UI
+- ALWAYS render fields with `Controller` + shadcn `<Field>`, `<FieldLabel>`, `<FieldError>` for consistent UI and accessible errors
 - NEVER use `useState` for form field values — react-hook-form handles this
 - ALWAYS use `useMutation` from TanStack Query for form submission
 
@@ -38,11 +40,9 @@ export type CreateUserInput = z.infer<typeof createUserSchema>;
 // features/users/components/create-user-form.tsx
 'use client';
 
-import { useForm } from 'react-hook-form';
+import { Controller, useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import {
-  Form, FormControl, FormField, FormItem, FormLabel, FormMessage
-} from '@/components/ui/form';
+import { Field, FieldError, FieldGroup, FieldLabel } from '@/components/ui/field';
 import { Input } from '@/components/ui/input';
 import { Button } from '@/components/ui/button';
 import { useCreateUser } from '@/features/users/hooks/use-create-user';
@@ -64,28 +64,28 @@ export function CreateUserForm({ onSuccess }: { onSuccess?: () => void }) {
   }
 
   return (
-    <Form {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
-        <FormField
-          control={form.control}
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      <FieldGroup>
+        <Controller
           name="name"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Name</FormLabel>
-              <FormControl><Input placeholder="John Doe" {...field} /></FormControl>
-              <FormMessage />
-            </FormItem>
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <Field data-invalid={fieldState.invalid}>
+              <FieldLabel htmlFor={field.name}>Name</FieldLabel>
+              <Input {...field} id={field.name} aria-invalid={fieldState.invalid} placeholder="John Doe" />
+              {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
+            </Field>
           )}
         />
-        <FormField
-          control={form.control}
+        <Controller
           name="email"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel>Email</FormLabel>
-              <FormControl><Input type="email" {...field} /></FormControl>
-              <FormMessage />
-            </FormItem>
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <Field data-invalid={fieldState.invalid}>
+              <FieldLabel htmlFor={field.name}>Email</FieldLabel>
+              <Input {...field} id={field.name} type="email" aria-invalid={fieldState.invalid} />
+              {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
+            </Field>
           )}
         />
         {form.formState.errors.root && (
@@ -94,8 +94,8 @@ export function CreateUserForm({ onSuccess }: { onSuccess?: () => void }) {
         <Button type="submit" disabled={isPending}>
           {isPending ? 'Creating...' : 'Create User'}
         </Button>
-      </form>
-    </Form>
+      </FieldGroup>
+    </form>
   );
 }
 ```
@@ -123,11 +123,12 @@ export const updateUserSchema = createUserSchema.partial();
 | 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 |
+| Manual error display | `<FieldError errors={[fieldState.error]} />` | Consistent UI, wired to the field's own error |
 | `fetch` in submit handler | `useMutation` | Loading state, error handling, cache invalidation |
 | Type written manually | `z.infer<typeof schema>` | Single source of truth |
 | `z.string().email()` | `z.email()` | Zod 4 moved format checks to top-level functions |
 | `{ required_error: '...' }` | `{ error: '...' }` | Zod 4 unified error customization on one `error` param |
+| Legacy shadcn `<Form>`/`<FormField>`/`<FormMessage>` in a new screen | `Controller` + `<Field>`/`<FieldError>` | shadcn's forms docs are written around `Field`; a screen still on the legacy wrapper is migrated when it is next touched, never extended |
 
 ---
 

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

@@ -14,7 +14,8 @@ Server state (API data) lives in TanStack Query. UI state lives in React. No glo
 ## 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)
+- ALWAYS use `useState` for local UI state (modal open, form step)
+- ALWAYS keep a list's page, sort and filters, and a page's active tab, in the URL (`searchParams`) — never in `useState`: a refresh or a shared link must reopen the same view (`admin-app/data-table.md`, `admin-app/page-structure.md`)
 - 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

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

@@ -101,6 +101,24 @@ export function QueryClientWrapper({ children }: { children: React.ReactNode })
 }
 ```
 
+## Test Budget
+
+The plan (`morph-plan`) gives each task a budget: **one test per postcondition, plus one
+regression test per bug fixed**. Going above it takes a one-line justification in the task. The
+happy path + one error path per component above is that budget applied to a component.
+
+- **Table before copy.** Scenarios of the same behavior — edge cases included — are rows of one
+  `it.each`/`test.each`, never N `it()` blocks that differ by one value.
+- **No test that only pins text.** Finding an element by its text to assert what the user can do
+  is fine; a test whose only assertion is the presence or absence of a copy string (a dash, a
+  word, a tenant name) proves the file's version, not behavior. That rule belongs in a lint rule or
+  a publish-time validation, outside the suite count.
+- **Shared helpers by default.** Reuse the existing wrappers (`test/helpers.tsx`), MSW handlers and
+  factories. Before writing a new one, look for it (`morph-spec graph explain <Name>`; fallback
+  without a graph: `grep -rn`).
+- **TDD where it pays:** a bug gets its regression test first, and so does pure logic (formatters,
+  reducers, schema). Component and integration tests may come after the code.
+
 ## Common Mistakes
 
 | Wrong | Right | Why |