From d09ec7e77ec93194368d3796d5373d1a8026d621 Mon Sep 17 00:00:00 2001 From: Madhura68 Date: Mon, 4 May 2026 08:47:45 +0200 Subject: [PATCH] docs(dialog): inspector-mode formaliseren in patroon-spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit § 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) --- docs/patterns/dialog.md | 45 ++++++++++++++++++++++++++++++- docs/specs/dialogs/task-detail.md | 24 +++++++++++------ 2 files changed, 60 insertions(+), 9 deletions(-) diff --git a/docs/patterns/dialog.md b/docs/patterns/dialog.md index 751dfaf..cf5afd5 100644 --- a/docs/patterns/dialog.md +++ b/docs/patterns/dialog.md @@ -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/.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` +- `` +- 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, `` 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/.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/.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 diff --git a/docs/specs/dialogs/task-detail.md b/docs/specs/dialogs/task-detail.md index a5aba2f..e3c686e 100644 --- a/docs/specs/dialogs/task-detail.md +++ b/docs/specs/dialogs/task-detail.md @@ -8,9 +8,9 @@ last_updated: 2026-05-04 # TaskDetailDialog Profiel -> Volgt `docs/patterns/dialog.md`. Dit document beschrijft alleen de Solo-specifieke afwijkingen. +> Volgt `docs/patterns/dialog.md` § 4a — **inspector-mode**. Dit document beschrijft alleen de Solo-specifieke invulling. -> **Niet te verwarren met `TaskDialog`** (`app/_components/tasks/task-dialog.tsx`) — dat is de classic create/edit-dialog voor backlog-taken. **`TaskDetailDialog`** is een solo-board-specifieke detail+edit-overlay die een lopende taak laat zien terwijl de Claude-agent eraan werkt. +> **Niet te verwarren met `TaskDialog`** (`app/_components/tasks/task-dialog.tsx`) — dat is de classic create/edit-dialog voor backlog-taken. **`TaskDetailDialog`** is een solo-board-specifieke inspector-dialog die een lopende taak laat zien terwijl de Claude-agent eraan werkt. ## Doel @@ -49,14 +49,22 @@ Dit valt buiten de standaard "Server Action met form" flow van `docs/patterns/di ## Layout -Gebruikt `entityDialogContentClasses` voor responsive sizing (§4 spec). Body-layout intern is custom (gegroepeerde secties in plaats van form-fields) want het is een hybride detail+edit-view, niet een klassiek form. +Volgt §4 + §4a inspector-layout: +- `` voor de outer (responsive breakpoints, max-h, flex column) +- Sticky header met `shrink-0 + px-6 pt-5 pb-4 + border-b border-outline-variant` +- Body in `entityDialogBodyClasses` (`flex-1 overflow-y-auto px-6 py-6 space-y-6`) — secties: Beschrijving, Implementatieplan, verify-only toggle, verify-gate select +- Footer in `entityDialogFooterClasses + flex flex-wrap items-center gap-2` — bevat dynamische job-status en context-knoppen (Voer uit / Wacht op agent / Annuleer / Open PR / Open op GitHub / Verify-result) +- Plan-textarea krijgt `max-h-[40vh]` zodat een groot plan niet meteen het hele body-gebied claimt; body kan dan scrollen langs de overige secties -## Bewust NIET in v1 +## Inspector-mode-vinkjes -- ❌ **Klassiek save-dan-sluit-form** — blur-save is bewust gekozen omdat de gebruiker tussendoor de plan-tekst herziet terwijl Claude bezig is. -- ❌ **Dirty-close-guard** — niet relevant zonder klassiek submit-form; wijzigingen worden direct gepersisteerd. -- ❌ **Cmd/Ctrl+Enter shortcut** — geen submit, dus n.v.t. -- ❌ **422-fieldErrors** — fine-grained PATCH-route geeft simpele 200/400/403; geen veldgewijze rendering nodig in deze UX. +Volgens § 4a: +- ✓ Geen `useDirtyCloseGuard` — wijzigingen direct gepersisteerd +- ✓ Geen `useDialogSubmitShortcut` — geen submit +- ✓ Geen full-record `lib/schemas/.ts` — fine-grained PATCH per veld +- ✓ Dynamische footer met liveness-info (job-status) +- ✓ Drielaagse demo-policy aanwezig (zie boven) +- ✓ MD3-tokens, motion, backdrop, focus-return uit § 8.4-8.5 erven via `` ## Gerelateerde bestanden