a7cc48a230
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>
64 lines
2.3 KiB
Markdown
64 lines
2.3 KiB
Markdown
---
|
|
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.
|