Scrum4Me/docs/pbi-dialog.md

# PbiDialog Profiel

> Volgt **`docs/patterns/dialog.md`** (de generieke spec voor élke entity-dialog in Scrum4Me).
> Dit document beschrijft alleen de PBI-specifieke afwijkingen en keuzes — alle gedeelde regels (layout, motion, demo-policy, foutcodes, validatie, theming, dialog-gedrag) staan in de generieke spec en worden hier niet herhaald.

> **Belangrijk:** als een regel in dit profiel botst met de generieke spec, wint de generieke spec. Documenteer hier de afwijking + reden, of pas de generieke spec aan.

---

## Velden

| Veld | Type | Mode | Validatie |
|---|---|---|---|
| `code` | `string \| null` | beide | optional, max 30 chars, mono-font, placeholder `auto` op create (server kent dan zelf een code toe) |
| `title` | `string` (required) | beide | trim, 1-200 chars |
| `priority` | `int` (1-4, P1 = hoogste) | beide | int 1-4, default 2 (kan via `defaultPriority`-prop bij create) |
| `status` | `PbiStatusApi` enum | beide | enum, default `'ready'` |
| `description` | `string \| null` | beide | optional, max 2000 chars, plain textarea (geen markdown rendering binnen de dialog) |

`PbiStatusApi` enum (lowercase, mapped via `lib/task-status.ts`): zie `<PbiStatusSelect>` voor de waarden.

### Veld-specifiek gedrag

- **Code + Titel** in één rij (`grid-cols-[6rem_1fr]`)
- **Prioriteit + Status** in één rij (`grid-cols-2`)
- **Prioriteit** via `<PrioritySelect>` (gedeelde primitive, géén segmented buttons in deze dialog)
- **Status** via `<PbiStatusSelect>` (PBI-specifieke wrapper rond gedeelde select)
- **Description** is `<Textarea rows={3} resize-none>` — géén auto-grow, géén markdown-hint, géén char-counter (afwijking van generieke spec; rationale: PBI-descriptions zijn doorgaans kort en richtinggevend)

---

## URL- of state-pattern

- **Gekozen:** state-based (`state: PbiDialogState | null` prop, gerendeerd binnen `PbiList`)
- **Reden:** PBI-dialog leeft altijd binnen `PbiList` op de product-backlog-pagina; deep-linking is niet vereist en zou een tweede edit-flow toevoegen.
- **State-shape:**
  ```ts
  type PbiDialogState =
    | { mode: 'create'; productId: string; defaultPriority?: number }
    | { mode: 'edit'; pbi: PbiDialogPbi; productId: string }
  ```
- **Sluiten:** `onClose()` callback uit de parent — `setState(null)` in `PbiList`.

---

## Status-veld

- **Default bij create:** `'ready'` (PBI-default state)
- **Geen verberging in create-mode** — anders dan TaskDialog wordt status hier wél getoond bij create, omdat een PBI zonder expliciete status onhandig is voor backlog-grooming

---

## Server actions

| Actie | Locatie | Form-binding | Revalidatie |
|---|---|---|---|
| `createPbiAction` | `actions/pbis.ts` | via `useActionState` + `<form action>` (FormData) | server-side `revalidatePath` op product-backlog |
| `updatePbiAction` | `actions/pbis.ts` | idem | idem |
| ~~`deletePbiAction`~~ | **(ontbreekt)** | n.v.t. | n.v.t. |

Beide acties moeten de drielaagse demo-policy volgen (zie § Bekende gaps).

---

## Speciale gedragingen

### Form-state via `useActionState`

PbiDialog gebruikt het `useActionState` + `useFormStatus`-patroon (Server Actions / native React), niet `react-hook-form`. Dit is een toegestaan alternatief volgens de generieke spec § 2. Field-errors worden gemapt via een lokale `fieldError(field)`-helper die `result.error` als `Record<string, string[]>` interpreteert wanneer 'm geen string is.

### `key`-prop op `<form>`

Het `<form>`-element heeft `key={isEdit ? pbi!.id : 'create'}` — dit reset native form-state (defaultValues) wanneer de dialog tussen create en edit wisselt of wanneer een ander record bewerkt wordt.

### Hidden inputs voor server-binding

`priority` en `status` worden via `<input type="hidden">` doorgegeven aan de Server Action (de UI-controls zijn JS-state, niet directe form-fields).

---

## Triggers

- **Create-trigger:** `+ PBI`-knop in `PanelNavBar` van `PbiList` → `setPbiDialogState({ mode: 'create', ... })`
- **Edit-trigger:** edit-icoon op een PBI-rij in `PbiList` → `setPbiDialogState({ mode: 'edit', pbi, ... })`

---

## Bekende gaps t.o.v. generieke spec

> Deze items wijken af van `docs/patterns/dialog.md` en horen in een vervolg-PR rechtgezet (niet onderdeel van de huidige docs-introductie).

- ❌ **Geen `<DemoTooltip>`** rond submit-knop — laag 3 van de drielaagse demo-policy ontbreekt voor PBI-create/update. Dat betekent dat een demo-user de knop kan klikken; de server action blokkeert nog steeds (laag 2), maar de UX is suboptimaal.
- ❌ **Geen delete-knop / `deletePbiAction`** — alleen create + update. Of dat bewust is (PBI's worden nooit verwijderd, alleen status veranderd) of een gat, moet expliciet worden besloten en in dit profiel vastgelegd.
- ❌ **Geen dirty-close-guard** — Esc / backdrop / Cancel sluiten direct, ook met onopgeslagen wijzigingen. Generieke spec § 8.1 vereist een AlertDialog bij `isDirty`.
- ❌ **Geen Cmd/Ctrl+Enter shortcut** — alleen klik op submit-knop.
- ❌ **Geen char-counter / markdown-hint** op description — bewust weggelaten omdat PBI-descriptions kort zijn, maar verdient expliciete bevestiging.
- ⚠️ **Layout wijkt af** van de generieke responsive-tabel: `sm:max-w-md` i.p.v. de `max-w-[50vw]` / `90vw` / full-screen-progressie uit § 4.

---

## Bewust NIET in v1

Specifiek voor PbiDialog (boven op de algemene out-of-scope-lijst in `docs/patterns/dialog.md` § 13):

- ❌ Inline aanmaken van child-stories binnen de PBI-dialog (gebeurt via StoryDialog vanuit `StoryPanel`)
- ❌ Bulk-status-update over meerdere PBI's
- ❌ PBI-templates / kopiëren

---

## Referenties

- `components/backlog/pbi-dialog.tsx` — implementatie
- `actions/pbis.ts` — server actions
- `components/shared/priority-select.tsx` — gedeelde priority-control
- `components/shared/pbi-status-select.tsx` — PBI-status-select
- `lib/task-status.ts` — `PbiStatusApi`-mapper
- `docs/patterns/dialog.md` — generieke spec (bron-of-truth)
- `docs/architecture.md` — datamodel `Pbi`
- `docs/styling.md` — MD3-tokens, status- en priority-kleuren