Phase 2 — Normalize file naming (#59)
* docs(naming): drop scrum4me- prefix from doc filenames Rename 10 docs/scrum4me-*.md files to unprefixed kebab-case names. Update every internal link in docs/, CLAUDE.md, AGENTS.md, README.md. * docs(naming): lowercase API.md and MD3 filenames Rename docs/API.md → docs/api.md and docs/MD3_Color_Scheme_Documentation.md → docs/md3-color-scheme.md. Update all internal links across 7 files. * docs(naming): rename plan file to kebab-case ASCII Rename "docs/plans/Tweede Claude Agent — Planning Agent.md" → docs/plans/tweede-claude-agent-planning.md. No external links needed updating. * docs(naming): rename middleware.md to proxy.md (next 16) docs/patterns/middleware.md → docs/patterns/proxy.md following the Next.js 16 proxy.ts rename. Update link in CLAUDE.md. * docs(naming): polish CLAUDE.md doc-index after renames Fix doubled scrum4me-scrum4me-mcp repo references (cascade from prior sed) in CLAUDE.md, docs/architecture.md, backlog.md, agent-instruction-audit.md, and plans/ST-1109. Update 'Middleware' label to 'Proxy middleware' in patterns table.
This commit is contained in:
Janpeter Visser
GitHub
parent
dc3832ad54
commit
e10f8f81bc
27 changed files with 101 additions and 101 deletions
120
docs/pbi-dialog.md
Normal file
120
docs/pbi-dialog.md
Normal file
|
|
@ -0,0 +1,120 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue