@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/standards/frontend/admin-app/feedback.md

@@ -0,0 +1,236 @@
+# Admin App — Confirmation Dialogs and Toast Messages
+
+> **Scope:** frontend/admin-app
+> **Layer:** 2 (on keyword)
+> **Keywords:** confirmation dialog, confirm, alert dialog, destructive action, delete confirmation, undo, toast, sonner, notification, feedback message, message catalog
+> **Load When:** an admin screen deletes, archives or bulk-changes records, or reports the outcome of an action
+
+**Verified against:** shadcn 4 `AlertDialog` (Radix) + sonner 2 + TanStack Query 5 (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
+
+---
+
+Two decisions every admin action makes, and that each screen used to make on its own: **does this need a confirmation?** and **what does the user read when it finishes?** Six hand-made modals and a dozen ad-hoc toast strings is what "each screen decides" produces. This standard fixes one confirmation component and one message catalog.
+
+## Core Rules
+
+- ONE `components/confirm-dialog.tsx`. No hand-made modal for "are you sure?".
+- Confirm only what is **destructive and not undoable**, what acts on **many records**, or what **discards unsaved work**. A reversible action gets an "Desfazer" toast instead of a question.
+- The confirm button names the verb and the object ("Excluir produto"), never "OK"/"Sim".
+- The dialog stays open while the action runs and **stays open on failure**, showing why — it never closes first and fails silently behind the user.
+- EVERY toast string comes from the catalog (`lib/toast-messages.ts` + `features/*/messages.ts`). No string literal in `toast()` calls.
+- Field validation never goes to a toast — it belongs on the field (`admin-app/forms.md`).
+
+## When to Confirm
+
+| Action | Confirmation | After |
+|---|---|---|
+| Delete one record, reversible (soft delete / archive) | none | toast with **Desfazer** |
+| Delete one record, irreversible | `ConfirmDialog`, destructive | toast "excluído" |
+| Bulk action on the selected rows | `ConfirmDialog` stating the count | toast with the count |
+| Action on "everything matching the filter" (server-side) | `ConfirmDialog` + **type the count** to enable the button | toast with the count |
+| Close a dirty form | `ConfirmDialog` "Descartar alterações?" | — |
+| Save, create, toggle a flag | none | toast (or silence for a toggle whose new state is visible) |
+
+## The Confirmation Dialog (Tier 2)
+
+Controlled, so it can await the mutation: the confirm button is a plain `Button`, not `AlertDialogAction` — the Radix action closes the dialog on click, before the result is known.
+
+```tsx
+// components/confirm-dialog.tsx
+'use client';
+
+import { useState } from 'react';
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@/components/ui/alert-dialog';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+
+export interface ConfirmDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: string;
+  description: string;
+  confirmLabel: string;
+  destructive?: boolean;
+  /** When set, the user must type this exact text to enable the button. */
+  typeToConfirm?: string;
+  onConfirm: () => Promise<void>;
+}
+
+export function ConfirmDialog(props: ConfirmDialogProps) {
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [typed, setTyped] = useState('');
+  const blocked = props.typeToConfirm !== undefined && typed !== props.typeToConfirm;
+
+  async function confirm() {
+    setPending(true);
+    setError(null);
+    try {
+      await props.onConfirm();
+      props.onOpenChange(false);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : 'Não foi possível concluir. Tente de novo.');
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <AlertDialog
+      open={props.open}
+      onOpenChange={(open) => {
+        if (pending) return;
+        if (!open) { setTyped(''); setError(null); }
+        props.onOpenChange(open);
+      }}
+    >
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>{props.title}</AlertDialogTitle>
+          <AlertDialogDescription>{props.description}</AlertDialogDescription>
+        </AlertDialogHeader>
+        {props.typeToConfirm !== undefined && (
+          <Input
+            aria-label={`Digite ${props.typeToConfirm} para confirmar`}
+            value={typed}
+            onChange={(e) => setTyped(e.target.value)}
+            autoComplete="off"
+          />
+        )}
+        {error && <p role="alert" className="text-sm text-destructive">{error}</p>}
+        <AlertDialogFooter>
+          <AlertDialogCancel disabled={pending}>Cancelar</AlertDialogCancel>
+          <Button
+            variant={props.destructive ? 'destructive' : 'default'}
+            disabled={pending || blocked}
+            onClick={confirm}
+          >
+            {pending ? 'Aguarde…' : props.confirmLabel}
+          </Button>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
+```
+
+Writing the dialog's text:
+
+- **Title** is the question, naming the object: *Excluir o produto "Camiseta azul"?* — for bulk, the count: *Excluir 12 produtos?*
+- **Description** is the consequence, in one sentence: *Ele sai do catálogo e dos pedidos em aberto. Não dá para desfazer.*
+- **Confirm label** repeats the verb: *Excluir produto* / *Excluir 12 produtos*.
+
+## The Toast Catalog
+
+Messages are data, reviewed in one place, and never built from a server's raw error text.
+
+```ts
+// lib/toast-messages.ts — the shape every entity follows, plus the generic outcomes
+export interface EntityMessages {
+  created: (name: string) => string;
+  updated: (name: string) => string;
+  deleted: (count: number) => string;
+  archived: (count: number) => string;
+}
+
+export const genericMessages = {
+  saveFailed: 'Não foi possível salvar. Tente de novo.',
+  loadFailed: 'Não foi possível carregar os dados.',
+  network: 'Sem conexão com o servidor. Verifique a rede e tente de novo.',
+  forbidden: 'Você não tem permissão para esta ação.',
+  conflict: 'Outra pessoa alterou este registro. Recarregue para ver a versão atual.',
+  undone: 'Ação desfeita.',
+} as const;
+```
+
+```ts
+// features/products/messages.ts
+import type { EntityMessages } from '@/lib/toast-messages';
+
+export const productMessages: EntityMessages = {
+  created: (name) => `Produto "${name}" criado.`,
+  updated: (name) => `Produto "${name}" salvo.`,
+  deleted: (count) => (count === 1 ? 'Produto excluído.' : `${count} produtos excluídos.`),
+  archived: (count) => (count === 1 ? 'Produto arquivado.' : `${count} produtos arquivados.`),
+};
+```
+
+Per-entity functions, not one generic `created(entity)`: Portuguese agrees in gender and number (*produto criado*, *categoria criada*), and a template that concatenates the noun gets it wrong half the time.
+
+Showing them — sonner's API, always with a catalog string:
+
+```ts
+// features/products/hooks/use-archive-products.ts
+'use client';
+
+import { useMutation } from '@tanstack/react-query';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+import { throwIfNotOk } from '@/lib/api/api-error';
+import { PROXY_API_PREFIX } from '@/lib/api/prefixes';
+import { genericMessages } from '@/lib/toast-messages';
+import { productMessages } from '@/features/products/messages';
+
+export function useArchiveProducts() {
+  const router = useRouter();
+  return useMutation({
+    mutationFn: async (ids: string[]) => {
+      await throwIfNotOk(await fetch(`${PROXY_API_PREFIX}/products/archive`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ ids }),
+      }));
+      return ids;
+    },
+    onSuccess: (ids) => {
+      router.refresh();
+      toast.success(productMessages.archived(ids.length), {
+        id: 'products-archive',
+        action: { label: 'Desfazer', onClick: () => void restore(ids).then(() => router.refresh()) },
+      });
+    },
+    onError: () => toast.error(genericMessages.saveFailed, { id: 'products-archive', duration: 8000 }),
+  });
+}
+
+async function restore(ids: string[]) {
+  await throwIfNotOk(await fetch(`${PROXY_API_PREFIX}/products/restore`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ ids }),
+  }));
+  toast(genericMessages.undone);
+}
+```
+
+## Toast Rules
+
+- **Success:** short, past tense, names the object or the count. Default duration.
+- **Error:** says what failed and what to do next; longer `duration` so it can be read. Map by status: 403 → `forbidden`, 409 → `conflict`, network failure → `network`, anything else → `saveFailed`/`loadFailed`.
+- **One toast per action:** pass an `id` so a retried action replaces its toast instead of stacking a second one.
+- **Undo** lives in the toast's `action`, and only where the backend can really undo (archive/restore, soft delete). A "Desfazer" that cannot undo is worse than none.
+- **Silence is an answer** for a toggle whose new state is already visible in the row.
+- The `<Toaster />` (shadcn `sonner`) is mounted once, in the root admin layout.
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|---|---|---|
+| A new modal per screen | `ConfirmDialog` | Six modals, six behaviours for pending and failure |
+| `AlertDialogAction` running the async delete | Plain `Button` in a controlled dialog | The action closes the dialog before the result exists |
+| "Tem certeza?" / "OK" | Question naming the object + verb on the button | The user confirms without reading what |
+| Confirm on every action | Confirm only destructive/bulk/discard; undo toast for the reversible | Confirmation fatigue makes people click through the one that matters |
+| `toast.error(err.message)` | Catalog message by status | Server text leaks internals and is not written for the user |
+| `toast('Salvo!')` literal in the component | `productMessages.updated(name)` | Wording drifts screen by screen, and nobody reviews it |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/admin-app/forms.md

@@ -0,0 +1,232 @@
+# Admin App — Forms
+
+> **Scope:** frontend/admin-app
+> **Layer:** 2 (on keyword)
+> **Keywords:** admin form, crud form, server validation, field error, setError, ValidationProblemDetails, dirty guard, unsaved changes, dialog form, sheet form, edit form, submit state
+> **Load When:** designing or building a create/edit form in an admin panel or CRUD screen
+
+**Verified against:** react-hook-form 7 + @hookform/resolvers 5 + Zod 4 + TanStack Query 5 + shadcn 4 `Field` (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
+
+---
+
+An admin app has **one** form pattern. It is the base pattern of `nextjs/forms.md` — Zod schema first, `zodResolver`, react-hook-form `Controller` + shadcn `Field`/`FieldError`, submission through `useMutation` — and this standard adds only what a CRUD form needs on top of it: the server's validation errors shown **on the field they belong to**, where the form lives, when it validates, what the submit button does while saving, and the guard against losing unsaved changes. Nothing here repeats the base pattern; read it first.
+
+## Why This Pattern and Not Another
+
+- **The Zod schema is shared.** The same schema types the form, validates it, and parses the API response (`admin-app/data-table.md` parses the list query with Zod too). One source of truth per entity.
+- **react-hook-form keeps inputs uncontrolled** — a 30-field form does not re-render on every keystroke, which is what `useState` per field does.
+- **shadcn's current form docs are written around it** (`Field`, `FieldLabel`, `FieldError` + `Controller`).
+- **Coexisting styles are the defect this rule exists for.** Measured in a real admin app: three form styles side by side (react-hook-form in some screens, hand-rolled `useState` in others) — three validation behaviours for one product, and a redesign that changed none of them. A screen that needs something the pattern cannot do registers the exception in `decisions.md`; it does not start a fourth style.
+
+## Core Rules
+
+- ALWAYS follow `nextjs/forms.md` for the base: schema → `z.infer`/`z.input`, `zodResolver`, `Controller` + `Field`, `useMutation`.
+- ALWAYS map the server's validation errors onto the fields with `setError` — a 400/422 is never a generic toast when the server said which field is wrong.
+- ALWAYS `mode: 'onTouched'`: a field validates after the user leaves it, then on every change. Never shout at an untouched form.
+- NEVER disable the submit button because the form is invalid — pressing it is how the user finds the errors. Disable it only while saving.
+- ALWAYS guard unsaved changes when the form can be dismissed (dialog, sheet, route change).
+- ALWAYS reuse the create schema for edit (`.partial()` / `.extend()`), never a second hand-written one.
+
+## Server Errors on the Field
+
+The .NET backend answers validation failures with `ValidationProblemDetails` (`{ title, status, errors: { "Name": ["..."] } }` — keys are the property names, PascalCase). One helper maps that onto the form; what does not match a field lands in the form-level error.
+
+```ts
+// lib/api/api-error.ts
+export class ApiError extends Error {
+  constructor(public readonly status: number, public readonly body: unknown) {
+    super(`HTTP ${status}`);
+  }
+}
+
+export async function throwIfNotOk(res: Response): Promise<Response> {
+  if (res.ok) return res;
+  const body: unknown = await res.json().catch(() => null);
+  throw new ApiError(res.status, body);
+}
+```
+
+```ts
+// lib/forms/apply-server-errors.ts
+import type { FieldValues, Path, UseFormSetError } from 'react-hook-form';
+import { z } from 'zod';
+import { ApiError } from '@/lib/api/api-error';
+
+const validationProblemSchema = z.object({
+  title: z.string().optional(),
+  errors: z.record(z.string(), z.array(z.string())).optional(),
+});
+
+/**
+ * Puts each server validation message on its field. Returns false when the
+ * error is not a validation problem — the caller then shows the generic toast.
+ */
+export function applyServerErrors<T extends FieldValues>(
+  error: unknown,
+  setError: UseFormSetError<T>,
+  fields: ReadonlyArray<Path<T>>,
+): boolean {
+  if (!(error instanceof ApiError) || (error.status !== 400 && error.status !== 422)) return false;
+  const problem = validationProblemSchema.safeParse(error.body);
+  if (!problem.success) return false;
+
+  const unmatched: string[] = [];
+  let focused = false;
+  for (const [key, messages] of Object.entries(problem.data.errors ?? {})) {
+    const name = key.charAt(0).toLowerCase() + key.slice(1);
+    const field = fields.find((f) => f === name);
+    if (field && messages[0]) {
+      setError(field, { type: 'server', message: messages[0] }, { shouldFocus: !focused });
+      focused = true;
+    } else {
+      unmatched.push(...messages);
+    }
+  }
+  if (unmatched.length > 0 || !focused) {
+    setError('root.serverError', {
+      type: 'server',
+      message: unmatched.join(' ') || problem.data.title || 'Revise os campos destacados.',
+    });
+  }
+  return true;
+}
+```
+
+A server error set on a field clears itself the next time that field passes validation — the user fixes the value and the message goes away, with no `clearErrors` bookkeeping.
+
+## The Form, With the Deltas
+
+```tsx
+// features/products/components/product-form.tsx
+'use client';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Controller, useForm } from 'react-hook-form';
+import { toast } from 'sonner';
+import { Button } from '@/components/ui/button';
+import { Field, FieldError, FieldGroup, FieldLabel } from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { applyServerErrors } from '@/lib/forms/apply-server-errors';
+import { genericMessages } from '@/lib/toast-messages';
+import { productMessages } from '@/features/products/messages';
+import { useSaveProduct } from '@/features/products/hooks/use-save-product';
+import {
+  productInputSchema,
+  type ProductInput,
+  type ProductInputRaw,
+} from '@/features/products/types/product.schemas';
+
+const FIELDS = ['name', 'sku', 'price'] as const;
+
+export function ProductForm({ initial, onSaved }: { initial?: ProductInput & { id: string }; onSaved: () => void }) {
+  const form = useForm<ProductInputRaw, unknown, ProductInput>({
+    resolver: zodResolver(productInputSchema),
+    mode: 'onTouched',
+    defaultValues: initial ?? { name: '', sku: '', price: 0 },
+  });
+  const save = useSaveProduct(initial?.id);
+
+  function onSubmit(values: ProductInput) {
+    save.mutate(values, {
+      onSuccess: () => {
+        form.reset(values);
+        toast.success(initial ? productMessages.updated(values.name) : productMessages.created(values.name));
+        onSaved();
+      },
+      onError: (error) => {
+        if (!applyServerErrors(error, form.setError, FIELDS)) toast.error(genericMessages.saveFailed);
+      },
+    });
+  }
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} noValidate>
+      <FieldGroup>
+        <Controller
+          name="name"
+          control={form.control}
+          render={({ field, fieldState }) => (
+            <Field data-invalid={fieldState.invalid}>
+              <FieldLabel htmlFor={field.name}>Nome</FieldLabel>
+              <Input {...field} id={field.name} aria-invalid={fieldState.invalid} />
+              {fieldState.invalid && <FieldError errors={[fieldState.error]} />}
+            </Field>
+          )}
+        />
+        {/* sku and price follow the same shape */}
+        {form.formState.errors.root?.serverError && (
+          <p role="alert" className="text-sm text-destructive">
+            {form.formState.errors.root.serverError.message}
+          </p>
+        )}
+        <Button type="submit" disabled={save.isPending}>
+          {save.isPending ? 'Salvando…' : 'Salvar'}
+        </Button>
+      </FieldGroup>
+    </form>
+  );
+}
+```
+
+Numeric inputs arrive as strings, so the schema coerces — and a schema whose input and output types differ needs the **three** generics of `useForm` (`z.input` / `unknown` / `z.output`), or `handleSubmit` hands you the wrong type:
+
+```ts
+// features/products/types/product.schemas.ts
+import { z } from 'zod';
+
+export const productInputSchema = z.object({
+  name: z.string().trim().min(2, 'Informe ao menos 2 caracteres.'),
+  sku: z.string().trim().regex(/^[A-Z0-9-]{3,20}$/, 'Use de 3 a 20 letras maiúsculas, números ou hífen.'),
+  price: z.coerce.number().positive('O preço precisa ser maior que zero.'),
+});
+
+export type ProductInputRaw = z.input<typeof productInputSchema>;
+export type ProductInput = z.output<typeof productInputSchema>;
+```
+
+`form.reset(values)` after a successful save is what makes `isDirty` false again — without it the unsaved-changes guard fires on a form that was just saved.
+
+## Where the Form Lives
+
+| The form has… | Put it in | Why |
+|---|---|---|
+| ≤ 4 fields, no dependency between them | `Dialog` over the list | Quick create/edit without losing the list |
+| 5–12 fields | `Sheet` (side panel) or its own page | Keeps the list in view; long enough to need scrolling |
+| > 12 fields, or distinct sections | Its own page (`/products/[id]/edit`), sections or tabs (`page-structure.md`) | A modal that scrolls is a page in disguise |
+| Steps that depend on earlier answers | Wizard (`page-structure.md`) | One screen cannot show a field whose meaning depends on a later one |
+
+## Validation Timing and Messages
+
+- `mode: 'onTouched'` (see Core Rules). On submit, react-hook-form focuses the first invalid field — keep `shouldFocusError` at its default.
+- Messages say **what to do**, in the product's language: "Informe ao menos 2 caracteres." — never "Invalid input" or the Zod default.
+- Mark the exception, not the rule: in admin forms most fields are required, so label the optional ones "(opcional)" instead of an asterisk on everything.
+- Errors of a **field** stay on the field. A toast is for the outcome of the whole save (`feedback.md`), never for one field's validation.
+
+## Unsaved Changes
+
+- Dialog or sheet: intercept `onOpenChange(false)` while `form.formState.isDirty` and ask with the confirmation dialog of `feedback.md` ("Descartar alterações?").
+- Own page: a `beforeunload` listener while dirty covers reload and tab close. In-app navigation (a sidebar link) goes through the same confirmation, triggered from the link's click handler.
+- Never guard a form that was just saved — see `form.reset(values)` above.
+
+## Layout and Density
+
+- One column by default; two columns only for short, related pairs (city/state, start/end).
+- Labels above inputs; help text with `FieldDescription`; the error right below its input.
+- Primary action at the end of the form, aligned with the fields; "Cancelar" next to it, never a destructive action beside "Salvar".
+- Read-only values in an edit form render as text, not as disabled inputs the user tries to click.
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|---|---|---|
+| `useState` per field / hand-rolled validation | The `nextjs/forms.md` pattern | Three form styles = three validation behaviours in one product |
+| `toast.error(error.message)` on a 400 | `applyServerErrors` → message on the field | The user cannot see which field the server rejected |
+| Submit disabled while the form is invalid | Disabled only while `isPending` | Pressing submit is how errors become visible |
+| `useForm<ProductInput>` with `z.coerce` fields | `useForm<z.input, unknown, z.output>` | Input and output types differ; one generic lies about one of them |
+| No `form.reset(values)` after save | Reset to the saved values | `isDirty` stays true and the guard nags after a successful save |
+| Modal with 20 fields and a scrollbar | Dedicated page | A dialog is for a glance-sized task |
+| A second, edit-only schema | `createSchema.partial()` / `.extend()` | Two schemas drift on the first new field |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/admin-app/page-structure.md

@@ -0,0 +1,203 @@
+# Admin App — Page Structure: Tabs, Long Pages and Wizards
+
+> **Scope:** frontend/admin-app
+> **Layer:** 2 (on keyword)
+> **Keywords:** tabs, long page, detail page, section navigation, wizard, multi-step form, stepper, page layout, admin layout
+> **Load When:** designing or building a detail page, a settings page, or a flow longer than one form
+
+**Verified against:** Next.js 16 App Router + shadcn 4 `Tabs` (Radix) + react-hook-form 7 + Zod 4 (the code blocks typecheck under `tsc --strict`). Last-verified: 2026-09-24.
+
+---
+
+A record with six kinds of related data rendered as one scroll becomes a 13 000 px page nobody can navigate; the same data split into tabs that each need the others becomes a hunt. The choice between **tabs**, a **long page with section navigation** and a **wizard** is a design decision per screen — the `morph-uiux` checklist asks it ("Abas") — and this standard is how to make it.
+
+## Core Rules
+
+- Decide per screen with the table below, and write the decision in the mockup's checklist.
+- The active tab lives in the URL (`?tab=`): the back button and a pasted link reopen the same tab.
+- Only the **active** tab's data is fetched. A tab strip that loads six tabs up front is a long page with extra clicks.
+- A tab never hides a validation error: one save spanning several tabs is a long page, not tabs.
+- A wizard keeps **one** form across its steps and validates each step before advancing; going back never loses what was typed.
+
+## Tabs, Long Page or Wizard
+
+| The screen… | Use | Why |
+|---|---|---|
+| Has ≥ 3 independent sections, each read or edited on its own (Dados, Variantes, Histórico, Acessos) | **Tabs** | The user works in one at a time; each loads alone |
+| Has sections read together, or one save covering all of them | **Long page + section nav** | Hiding half of what one save changes is how errors go unseen |
+| Has ≤ 2 short sections | **Plain page** | Tabs for two short blocks cost a click for nothing |
+| Is a flow where later fields depend on earlier answers, or needs a review before committing | **Wizard** | One screen cannot show a field whose meaning a later step decides |
+| Holds a list that can grow without bound (history, logs, accesses) | **Its own tab or page, paged** (`admin-app/data-table.md`) | An unbounded list at the bottom of a detail page is where the 13 000 px came from |
+
+## Tabs in the URL
+
+The page reads `tab` from `searchParams` and renders only that tab's content on the server; the client strip only writes the URL.
+
+```tsx
+// app/(admin)/products/[id]/page.tsx
+import { ProductTabs, PRODUCT_TABS, type ProductTab } from '@/features/products/components/product-tabs';
+import { ProductDetailsTab } from '@/features/products/components/product-details-tab';
+import { ProductVariantsTab } from '@/features/products/components/product-variants-tab';
+import { ProductHistoryTab } from '@/features/products/components/product-history-tab';
+
+export default async function ProductPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ id: string }>;
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const { id } = await params;
+  const raw = (await searchParams).tab;
+  const tab: ProductTab = PRODUCT_TABS.find((t) => t === raw) ?? 'dados';
+
+  return (
+    <ProductTabs active={tab}>
+      {tab === 'dados' && <ProductDetailsTab id={id} />}
+      {tab === 'variantes' && <ProductVariantsTab id={id} />}
+      {tab === 'historico' && <ProductHistoryTab id={id} />}
+    </ProductTabs>
+  );
+}
+```
+
+```tsx
+// features/products/components/product-tabs.tsx
+'use client';
+
+import type { ReactNode } from 'react';
+import { usePathname, useRouter, useSearchParams } from 'next/navigation';
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs';
+
+export const PRODUCT_TABS = ['dados', 'variantes', 'historico'] as const;
+export type ProductTab = (typeof PRODUCT_TABS)[number];
+
+const LABELS: Record<ProductTab, string> = { dados: 'Dados', variantes: 'Variantes', historico: 'Histórico' };
+
+export function ProductTabs({ active, children }: { active: ProductTab; children: ReactNode }) {
+  const router = useRouter();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  function select(value: string) {
+    const params = new URLSearchParams(searchParams.toString());
+    params.set('tab', value);
+    for (const key of ['page', 'sort', 'dir', 'q']) params.delete(key); // list state belongs to the tab being left
+    router.replace(`${pathname}?${params.toString()}`, { scroll: false });
+  }
+
+  return (
+    <Tabs value={active} onValueChange={select}>
+      <TabsList>
+        {PRODUCT_TABS.map((t) => (
+          <TabsTrigger key={t} value={t}>{LABELS[t]}</TabsTrigger>
+        ))}
+      </TabsList>
+      <div className="pt-4">{children}</div>
+    </Tabs>
+  );
+}
+```
+
+Changing tab drops the list params of the tab being left: a `?page=4` that belonged to "Histórico" would otherwise open "Variantes" on page 4.
+
+## Detail Page Anatomy
+
+1. **Header:** the record's name, its status, and at most two primary actions (the rest in a `…` menu). It stays visible across tabs.
+2. **Tabs or sections** per the decision table.
+3. **Related lists** inside a tab are full `DataTable`s with their own URL state — never a capped preview.
+
+## Long Page With Section Navigation
+
+- A sticky side (desktop) or top (mobile) nav with one anchor per section; each section has an `h2` with an `id`.
+- One save for the page, at the end **and** pinned while scrolling when the form is longer than the viewport.
+- Collapse a section only if it is optional for most records — collapsing required fields hides errors.
+
+## Wizard for Long Flows
+
+One react-hook-form instance holds every step; each step lists its fields; "Próximo" validates only them with `trigger`; the final submit validates the whole schema. The step index is local UI state (`nextjs/state-management.md`): a reload loses the typed data anyway, so the URL would only lie about where the user is.
+
+```tsx
+// features/products/components/product-wizard.tsx
+'use client';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useState } from 'react';
+import { useForm, type Path } from 'react-hook-form';
+import { Button } from '@/components/ui/button';
+import {
+  productInputSchema,
+  type ProductInput,
+  type ProductInputRaw,
+} from '@/features/products/types/product.schemas';
+
+type Step = { id: string; title: string; fields: ReadonlyArray<Path<ProductInputRaw>> };
+
+const STEPS: ReadonlyArray<Step> = [
+  { id: 'identificacao', title: 'Identificação', fields: ['name', 'sku'] },
+  { id: 'preco', title: 'Preço', fields: ['price'] },
+  { id: 'revisao', title: 'Revisão', fields: [] },
+];
+
+export function ProductWizard({ onSubmit }: { onSubmit: (values: ProductInput) => void }) {
+  const [current, setCurrent] = useState(0);
+  const form = useForm<ProductInputRaw, unknown, ProductInput>({
+    resolver: zodResolver(productInputSchema),
+    mode: 'onTouched',
+    defaultValues: { name: '', sku: '', price: 0 },
+  });
+  const step = STEPS[current];
+  const isLast = current === STEPS.length - 1;
+
+  async function next() {
+    if (!step) return;
+    const ok = await form.trigger([...step.fields], { shouldFocus: true });
+    if (ok) setCurrent((c) => Math.min(c + 1, STEPS.length - 1));
+  }
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)} noValidate>
+      <ol className="mb-6 flex gap-4 text-sm" aria-label="Etapas">
+        {STEPS.map((s, i) => (
+          <li key={s.id} aria-current={i === current ? 'step' : undefined}
+              className={i === current ? 'font-semibold' : 'text-muted-foreground'}>
+            {i + 1}. {s.title}
+          </li>
+        ))}
+      </ol>
+      {/* render the fields of `step` here, with the Controller + Field shape of nextjs/forms.md */}
+      <div className="mt-6 flex justify-between">
+        <Button type="button" variant="outline" disabled={current === 0} onClick={() => setCurrent((c) => c - 1)}>
+          Voltar
+        </Button>
+        {isLast
+          ? <Button type="submit">Concluir</Button>
+          : <Button type="button" onClick={next}>Próximo</Button>}
+      </div>
+    </form>
+  );
+}
+```
+
+Wizard rules:
+
+- Show every step by name and where the user is (`aria-current="step"`); never a bare "Passo 2".
+- "Voltar" never validates and never clears; "Próximo" validates only the current step.
+- The last step is a **review** of everything typed, with a link back to each step — the commit happens there, not on a middle step.
+- A flow long enough to be abandoned halfway (> ~5 steps, or one that needs data the user has to go look up) saves a **server-side draft** per step; the local form alone loses it on reload.
+- Leaving a dirty wizard asks first (`admin-app/feedback.md`).
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|---|---|---|
+| Every related list stacked on the detail page | A tab (or page) per unbounded list, paged | The 13 000 px page |
+| Tab state in `useState` | `?tab=` in the URL | Back button and shared links land on the wrong tab |
+| All tabs fetched up front | Only the active tab renders and fetches | Tabs that cost as much as the long page they replaced |
+| One form, one save, split across tabs | Long page with section nav | The error sits on a tab the user is not looking at |
+| One `useForm` per wizard step | One form, `trigger(stepFields)` per step | Going back loses data; the final submit cannot validate the whole |
+| Committing on a middle step | Review step commits | The user never sees what is being saved |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*