reactive-ui-state-with-delegated-event-routing

name	reactive-ui-state-with-delegated-event-routing
description	Use when building or reviewing a single-page/component UI that re-renders on state change and needs a clean way to wire click/interaction handlers, or when a component must react to system preferences like prefers-color-scheme/prefers-reduced-motion in a testable way.
status	active
version	"2026-07-05T00:00:00.000Z"

Reactive UI State with Delegated Event Routing

When to use

• A view is re-rendered on every state change (vanilla JS SPA, or a React tree with repeated child components) and you need one consistent place to interpret user interactions instead of re-attaching listeners per render.
• Multiple layouts (e.g. grid view + card view) need to invoke the exact same action, and you want to avoid duplicating event-wiring logic per layout.
• A component's behavior should depend on a system/media preference (prefers-color-scheme, prefers-reduced-motion) and that behavior needs to be unit-testable, not just visually verified.

Method

1. Delegate DOM events through data attributes (vanilla JS / re-rendered DOM). Attach a single click handler on a stable ancestor (e.g. document or the app root) rather than per-element listeners. Encode intent in data-* attributes on interactive elements: data-action, data-task-id, etc. The handler reads event.target.closest('[data-action]') and dispatches based on those attributes. Because listeners live on a node that survives re-renders, freshly rendered DOM automatically works with no re-binding step. Pair this with a strict one-way data flow: every mutation goes through setState(newState) → render(newState), so the delegated handler is always interpreting the current DOM.

2. Thread callbacks down instead of letting children own event emission (React / component trees). Keep a single callback (e.g. onCardAction(id, action)) defined at the state-owning level, and pass it down to every child component/layout that needs to trigger it — rather than each component independently emitting or managing its own events. This keeps all state mutation in one place, makes the data-flow direction obvious top-down, and means wiring a new layout (e.g. adding a list view alongside grid/card) only requires invoking the same callback, not re-deriving the action logic.

3. Read system preferences in JS, not only via CSS, when behavior (not just style) depends on them. @media (prefers-color-scheme) / (prefers-reduced-motion) CSS queries are invisible to jsdom and to any test that asserts on component behavior rather than computed style. Instead:

• Build a custom hook using useSyncExternalStore subscribed to window.matchMedia('(prefers-reduced-motion: reduce)') (or the color-scheme equivalent).
• Have the component conditionally apply classes/props based on the hook's return value.
• In test setup, shim window.matchMedia (jsdom doesn't implement it) so tests can flip the preference and assert the resulting classes/behavior deterministically.

Gotchas

• Delegated handlers must match on the closest ancestor carrying the data-action, not event.target directly — a click can land on a child SVG/span inside the button.
• If you skip the shared-callback pattern in React and let each layout own its own handler, you will end up wiring the same action twice and one copy will silently drift out of sync.
• Without a matchMedia shim, tests that assert on preference-driven classes will pass vacuously (the hook will throw or default, hiding real regressions) — always verify the test actually fails when the implementation is reverted.
• CSS-only media queries are fine for pure styling; only escalate to the JS hook when the preference gates component behavior (e.g. skipping an animation entirely) that needs to be asserted in tests.