128 lines
6.1 KiB
Markdown
128 lines
6.1 KiB
Markdown
---
|
|
title: "PbiDialog Profiel"
|
|
status: active
|
|
audience: [ai-agent, contributor]
|
|
language: nl
|
|
last_updated: 2026-05-03
|
|
---
|
|
|
|
# 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/design/styling.md` — MD3-tokens, status- en priority-kleuren
|