docs(dialog): inspector-mode formaliseren in patroon-spec

§ 4a beschrijft hybrid detail+inline-edit dialogen met dynamische
footer en blur-save: bv. TaskDetailDialog. Maakt expliciet wanneer je
deze variant kiest, welke § 4-eisen blijven gelden en welke vervallen
(geen dirty-guard, geen Cmd+Enter, geen full-record schema).

Profiel docs/specs/dialogs/task-detail.md verwijst nu naar § 4a en
documenteert de layout-keuzes (sticky header, scrollable body,
flex-wrap footer met job-status, plan-textarea max-h-[40vh]).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser 2026-05-04 08:47:45 +02:00
parent 61b3db195c
commit d09ec7e77e
2 changed files with 60 additions and 9 deletions

View file

@ -23,7 +23,7 @@ Voor entity-specifieke afwijkingen of velden: schrijf één begeleidende doc per
|---|---|---|
| 1.1 | Bouw op `components/ui/dialog.tsx` (de bestaande shadcn/`@base-ui/react`-wrapper). **Geen** directe imports van dialog-primitives uit `@base-ui/react`. | Voorkomt twee parallelle dialog-implementaties met inconsistente animatie/focus-trap/theming |
| 1.2 | Gebruik composition via de **`render`-prop** (zie `CLAUDE.md` "UI Library Conventions"). Nooit Radix' `asChild`. | Project gebruikt `@base-ui/react`, niet Radix |
| 1.3 | Mode (`create` vs `edit` vs `detail`) wordt afgeleid uit één input — een prop, een `state`-object of een `searchParam`. **Niet** twee aparte componenten. | Voorkomt code-duplicatie en inconsistente labels/footer-layouts |
| 1.3 | Mode (`create` vs `edit` vs `detail` vs `inspector`) wordt afgeleid uit één input — een prop, een `state`-object of een `searchParam`. **Niet** twee aparte componenten. Voor `inspector`: zie § 4a. | Voorkomt code-duplicatie en inconsistente labels/footer-layouts |
| 1.4 | Auth-scoping op elke server action via `productAccessFilter(userId)` (of het scope-helper-equivalent). Cross-tenant writes mogen onmogelijk zijn. | `CLAUDE.md` "Toegangsmodel" + `docs/patterns/server-action.md` |
| 1.5 | **Drielaagse demo-policy** (verplicht — zie § 6) op elke write-actie. | `CLAUDE.md` "Demo-check" + `docs/architecture.md#demo-user-policy` |
| 1.6 | Validatie via één gedeeld zod-schema (`lib/schemas/<entity>.ts`) — gebruikt door zowel form als server action. | `CLAUDE.md` "Validatie" |
@ -99,6 +99,49 @@ Verplicht:
---
## 4a — Inspector-mode (hybrid detail + inline-edit)
Een inspector-dialog is een **detail-overlay met inline-bewerkbare velden** voor een lopend record (typisch een taak, run of job). Onderscheidt zich op drie punten van create/edit/detail:
| Aspect | Create/Edit/Detail | Inspector |
|---|---|---|
| Persistence | submit-knop in footer roept één Server Action aan | per-veld blur-save via Route Handler (`PATCH`) of fine-grained Server Actions |
| Footer | statisch (`Annuleren` + `Opslaan`/`Aanmaken`/`Verwijderen`) | dynamisch — bevat status-indicatoren en context-knoppen (bv. "Voer uit", "Annuleer agent", "Open PR") afhankelijk van een job/run-status |
| Body | sequentieel form (één entiteit invullen) | gegroepeerde secties: read-only metadata + bewerkbare controls + activity-status |
| Dirty-guard | verplicht (§8.1) | n.v.t. — wijzigingen worden direct gepersisteerd |
| Submit-shortcut | Cmd/Ctrl+Enter verplicht (§8.2) | n.v.t. — geen submit |
| Validatie | 422-fieldErrors in form | toast bij PATCH-fout, optimistisch terugdraaien |
**Wanneer kiezen voor inspector i.p.v. detail-mode?**
- Het record is "actief" (bv. agent draait erop) en meta-edits moeten direct effect hebben zonder save-cycle
- Verschillende velden gaan naar verschillende endpoints en willen niet gebundeld worden
- De footer toont liveness-info (job-status) i.p.v. acties op het hele record
**Layout-eisen (verplicht, gelijk aan §4):**
- Bouw op `components/ui/dialog.tsx`
- `<DialogContent className={entityDialogContentClasses}>`
- Sticky header met `entityDialogHeaderClasses` of equivalent (`shrink-0` + `border-b border-outline-variant`)
- Body in `entityDialogBodyClasses` (`flex-1 overflow-y-auto px-6 py-6 space-y-6`)
- Footer in `entityDialogFooterClasses` + extra modifiers voor wrap-gedrag bij dynamische knoppen (`flex flex-wrap items-center gap-2`)
**Wat blijft hetzelfde als bij andere modi:**
- Drielaagse demo-policy (§6) — proxy-guard, server/route-handler `session.isDemo`-check, `<DemoTooltip>` rond bewerkbare controls
- MD3-tokens (§9), motion (§8.4), backdrop (§8.5), focus return (§8.3)
- Auth-scoping op elke write (§1.4)
- Eén entity-profile in `docs/specs/dialogs/<entity>.md`
**Wat je expliciet niet doet in inspector-mode:**
- ❌ Geen `useDirtyCloseGuard` (geen dirty-state) — Esc/backdrop sluit direct
- ❌ Geen `useDialogSubmitShortcut` (geen submit)
- ❌ Geen verplichte `lib/schemas/<entity>.ts` voor het hele record — wél schema's per PATCH-veld of per fine-grained action
- ❌ Geen footer met statische save/cancel-knoppen — die suggereren bundle-save
**Voorbeeld in deze codebase:** `components/solo/task-detail-dialog.tsx` — opent een lopende solo-taak, plan-textarea slaat op blur op via `PATCH /api/tasks/:id`, verify-toggles direct via dezelfde route, footer toont job-status met context-acties (Voer uit / Wacht op agent / Annuleer / Open PR / Mislukt).
Profiel: `docs/specs/dialogs/task-detail.md`.
---
## 5 — Validatie & foutcodes
### 5.1 zod-schema