Sprint: Verbeteren debug mode (#179)
* feat(PBI-49): add debugProps helper + Vitest test
Adds lib/debug.ts with debugProps(id, component, file) that returns
data-debug-id and data-debug-label attrs in dev mode, empty object in
production. Adds __tests__/lib/debug.test.ts covering both modes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(PBI-49): add debug-id pattern doc + CLAUDE.md reference
Adds docs/patterns/debug-id.md documenting the named-component boundary
rule (6 punten), helper-voorbeeld, skip-criteria en motivatie voor
handmatige pad-argumenten. Voegt verwijzing toe aan CLAUDE.md
patterns-tabel.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(PBI-49): migrate 17 shared/ components to debugProps helper
Replace hardcoded data-debug-id + data-debug-label attribute pairs with
{...debugProps(id, component, file)} spread in all 17 components/shared/
files. Existing debug-ids preserved unchanged.
* feat(PBI-49): add debugProps to backlog/, sprint/, solo/ components
* feat(PBI-49): add debugProps to jobs/ + ideas/ components
* feat(PBI-49): add debugProps to products/ + settings/ + notifications/ components
* feat(PBI-49): add debugProps to admin/ + dashboard/ + dialogs/ + mobile/ + split-pane/
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix(PBI-49): use attr(data-debug-id) for debug tooltip in globals.css
* refactor(PBI-49): remove data-debug-label from debugProps helper + test
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* refactor(PBI-49): strip unused component/file args from debugProps in shared/
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to StatusBar, NavBar, PanelNavBar
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to components/sprint/*
- new-sprint-dialog: __submit on submit button
- sprint-backlog: __list on SprintBacklogLeft + SprintBacklogRight scroll areas
- sprint-board-client: root wrapper div (display:contents) + __drag-overlay
- sprint-header: __title on goal button, __dates on dates button, __actions on action cluster
- sprint-run-controls: root on controls div, __start/__cancel on action buttons; __blockers-dialog on dialog content
- start-sprint-button: root on trigger button, __dialog on dialog content, __submit on submit button
- sync-active-sprint-cookie: no debug-id (returns null, side-effect only), comment added
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to components/backlog/*
* feat(PBI-49): add BEM sub-element data-debug-id to components/ideas/*
* feat(PBI-49): add BEM sub-element data-debug-id to components/dashboard/* + components/markdown.tsx
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to new-product-button
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to components/solo/*
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-elements to nav-status-indicators
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to components/jobs/*
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to components/products/*
* feat(PBI-49): add BEM sub-element data-debug-id to components/notifications/*
- answer-modal: __content (scroll area), __submit (footer)
- notifications-bridge: skip comment (bridge, non-rendering wrapper)
- notifications-realtime-mount: skip comment (returns null)
- notifications-sheet: __header, __items (questions list)
- push-toggle: __switch (button), __label (button text) on subscribed/unsubscribed states
* feat(PBI-49): add BEM sub-element data-debug-id to components/settings/*
- leave-product-button: root only (single-button component)
- min-quota-editor: __input (number input), __save (save button)
- profile-editor: __username (bio/short-description input), __save (submit)
- role-manager: __roles (checkbox list), __add (save button)
- token-manager: __tokens (active tokens list), __generate (create button)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* feat(PBI-49): add BEM sub-element data-debug-id to admin, auth, dialogs, entity-dialog, mobile, split-pane
* docs(PBI-49): add debug-labels BEM pattern doc + CLAUDE.md entry
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Janpeter Visser
GitHub
parent
ce43f7720a
commit
d292e445d9
93 changed files with 600 additions and 218 deletions
64
docs/patterns/debug-id.md
Normal file
64
docs/patterns/debug-id.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
---
|
||||
title: "Debug-id op component-root"
|
||||
status: active
|
||||
audience: [ai-agent, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-09
|
||||
when_to_read: "Wanneer je een named-component aanmaakt of aanpast."
|
||||
---
|
||||
|
||||
# Patroon: Debug-id op component-root
|
||||
|
||||
## Regel: named-component boundary
|
||||
|
||||
Elk named-component plaatst `data-debug-id` en `data-debug-label` via de
|
||||
`debugProps`-helper op zijn root JSX-element. Zes concrete regels:
|
||||
|
||||
1. **Import** `debugProps` uit `@/lib/debug` — geen inline attribuut schrijven.
|
||||
2. **Spread** het resultaat op het root element: `{...debugProps(id, component, file)}`.
|
||||
3. **`id`** is kebab-case van de componentnaam, bijv. `sprint-board`.
|
||||
4. **`component`** is de PascalCase naam zoals die geëxporteerd wordt, bijv. `SprintBoard`.
|
||||
5. **`file`** is het relatieve pad vanaf de repo-root, bijv. `components/sprint/sprint-board.tsx`.
|
||||
6. **Root = het buitenste JSX-element** dat de component rendert — niet een wrapper div die je extra toevoegt.
|
||||
|
||||
In productie (`NODE_ENV=production`) retourneert `debugProps` een leeg object `{}`
|
||||
zodat er geen debug-attributen in de gebundelde HTML staan.
|
||||
|
||||
## Helper-voorbeeld
|
||||
|
||||
```tsx
|
||||
import { debugProps } from '@/lib/debug'
|
||||
|
||||
export function SprintBoard({ ... }: SprintBoardProps) {
|
||||
return (
|
||||
<div
|
||||
className="..."
|
||||
{...debugProps('sprint-board', 'SprintBoard', 'components/sprint/sprint-board.tsx')}
|
||||
>
|
||||
{/* inhoud */}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Skip-criteria
|
||||
|
||||
Voeg **geen** `debugProps` toe aan:
|
||||
|
||||
| Categorie | Reden |
|
||||
|---|---|
|
||||
| `components/ui/*` | shadcn-primitives — ongebrand, niet onze componenten |
|
||||
| Bridges / mounts | Niet-renderende wrappers zoals `notifications-bridge`, `realtime-bridge`, `sync-active-sprint-cookie` |
|
||||
| Hooks-only files | Files die alleen hooks exporteren en niets renderen |
|
||||
|
||||
## Motivatie: geen build-time injectie van pad
|
||||
|
||||
Een alternatief is het bestandspad automatisch injecteren via een Babel/SWC-plugin
|
||||
of een ESLint-codefixin. Dit is bewust **niet** gekozen omdat:
|
||||
|
||||
- de plugin afhankelijk wordt van de build-toolchain-configuratie (Next.js, Turbopack),
|
||||
- bij rename/move van een bestand de injectie verouderd raakt zonder dat de compiler waarschuwt,
|
||||
- expliciete argumenten in de broncode reviewbaar en grep-baar zijn.
|
||||
|
||||
Het handmatig meegeven van `id`, `component` en `file` maakt de intentie zichtbaar
|
||||
en voorkomt verborgen afhankelijkheden.
|
||||
114
docs/patterns/debug-labels.md
Normal file
114
docs/patterns/debug-labels.md
Normal file
|
|
@ -0,0 +1,114 @@
|
|||
---
|
||||
title: "Debug-labels: BEM data-debug-id patroon"
|
||||
status: active
|
||||
audience: [ai-agent, contributor]
|
||||
language: nl
|
||||
last_updated: 2026-05-09
|
||||
when_to_read: "Wanneer je een component aanmaakt of aanpast en debug-ids wilt toevoegen aan sub-elementen."
|
||||
---
|
||||
|
||||
# Patroon: Debug-labels (BEM data-debug-id)
|
||||
|
||||
## Doel
|
||||
|
||||
`data-debug-id` geeft Claude (en ontwikkelaars) een ondubbelzinnige naam voor elk
|
||||
DOM-element. In plaats van "de blauwe knop rechtsonder" zeg je `status-bar__build-info`
|
||||
— uniek, herleidbaar naar de broncode, en grep-baar.
|
||||
|
||||
## Toggle
|
||||
|
||||
Een `{ }`-knop verschijnt alleen in development (`NODE_ENV !== 'production'`) in de
|
||||
`StatusBar`. De knop beheert `localStorage['scrum4me:debug-mode']` via
|
||||
`stores/debug-store.ts` en zet de klasse `debug-mode` op `<body>`.
|
||||
|
||||
In `app/globals.css` activeren de regels onder `body.debug-mode [data-debug-id]`:
|
||||
- een dashed outline rondom elk geïnstrumenteerd element,
|
||||
- een hover-tooltip die de waarde van `data-debug-id` toont.
|
||||
|
||||
In productie worden geen `data-debug-id`-attributen gerenderd — `debugProps()` retourneert
|
||||
een leeg object wanneer `NODE_ENV === 'production'`.
|
||||
|
||||
## Patroon
|
||||
|
||||
### Root-element
|
||||
|
||||
De root van elke named-component gebruikt `debugProps()` uit `@/lib/debug`:
|
||||
|
||||
```tsx
|
||||
import { debugProps } from '@/lib/debug'
|
||||
|
||||
export function StatusBar() {
|
||||
return (
|
||||
<footer
|
||||
className="..."
|
||||
{...debugProps('status-bar')}
|
||||
>
|
||||
{/* inhoud */}
|
||||
</footer>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
`debugProps(id)` plaatst `data-debug-id={id}` in development en `{}` in productie.
|
||||
De `id` is de kebab-case variant van de bestandsnaam, bijv. `status-bar` voor
|
||||
`components/shared/status-bar.tsx`.
|
||||
|
||||
### Sub-elementen (BEM)
|
||||
|
||||
Interactieve of significante sub-elementen krijgen een inline `data-debug-id` met
|
||||
BEM-notatie: `<root>__<sub>`. Sub-elementen schrijven het attribuut **direct** (niet
|
||||
via `debugProps`), want ze zijn altijd genest binnen het root-element en zichtbaar
|
||||
alleen samen met de root:
|
||||
|
||||
```tsx
|
||||
export function StatusBar() {
|
||||
return (
|
||||
<footer
|
||||
className="..."
|
||||
{...debugProps('status-bar')}
|
||||
>
|
||||
<span data-debug-id="status-bar__copyright">
|
||||
© {new Date().getFullYear()} Scrum4Me
|
||||
</span>
|
||||
<span data-debug-id="status-bar__build-info">
|
||||
v{version} · gebouwd op {buildDate}
|
||||
{isDev && <DebugToggle />}
|
||||
</span>
|
||||
</footer>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Welke sub-elementen instrumenteren
|
||||
|
||||
| Instrumenteer | Voorbeelden |
|
||||
|---|---|
|
||||
| Interactieve elementen | `<button>`, triggers, links, tabs |
|
||||
| Sectie-headers | `<h1>` t/m `<h6>` |
|
||||
| Primaire inhoudstitels of -tekst | hoofdtitel van een kaart, badge-label |
|
||||
|
||||
Bij twijfel: **skip**. Liever te weinig dan ruis.
|
||||
|
||||
## Wat NIET instrumenteren
|
||||
|
||||
| Categorie | Reden |
|
||||
|---|---|
|
||||
| `components/ui/*` | shadcn-primitives — herbruikt op te veel plekken, id zou clashen |
|
||||
| `app/(...)/page.tsx` | v1 scope is alleen `components/` |
|
||||
| Bridges / mounts | Niet-renderende wrappers (`notifications-bridge`, `realtime-bridge`, …) |
|
||||
| Hooks-only files | Files die alleen hooks exporteren en niets renderen |
|
||||
|
||||
## Geen `data-debug-label`
|
||||
|
||||
Het attribuut heet uitsluitend `data-debug-id`. Er bestaat geen `data-debug-label`.
|
||||
De `app/globals.css` tooltip leest `attr(data-debug-id)` — een tweede attribuut
|
||||
zou alleen verwarring geven.
|
||||
|
||||
## Gerelateerde bestanden
|
||||
|
||||
| Bestand | Rol |
|
||||
|---|---|
|
||||
| `lib/debug.ts` | `debugProps()`-helper; retourneert `{}` in productie |
|
||||
| `stores/debug-store.ts` | Zustand-store voor `debugMode`-state en `toggleDebugMode` |
|
||||
| `components/shared/status-bar-debug-toggle.tsx` | `{ }`-knop — synchroniseert localStorage en `body.debug-mode` |
|
||||
| `app/globals.css` | `body.debug-mode [data-debug-id]` — outline + hover-tooltip |
|
||||
Loading…
Add table
Add a link
Reference in a new issue