Janpeter Visser d292e445d9

* 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>

2026-05-09 22:46:29 +02:00

3.6 KiB

Raw Blame History

title

status

audience

language

last_updated

when_to_read

Debug-labels: BEM data-debug-id patroon

active

ai-agent

contributor

2026-05-09

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:

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:

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

3.6 KiB Raw Blame History