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:

  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