Notification Events

Notification Events — Waste Plus Frontend

Overview

The frontend uses a React-managed notification event pipeline for user-facing messages. This pipeline replaces the previous useSendEvent naming and the older DOM-oriented event bus mental model.

The current design keeps notification flow lightweight:

• NotificationProvider is the runtime source of truth.
• useNotificationEvents is the component-facing hook for publish/subscribe.
• useScopedNotification exposes page-scoped inline notifications.
• eventBridge.ts is the only adapter for publishers outside the React tree.

This keeps notifications inside the application architecture without adding a separate state-management library.

Responsibilities

Element	File	Responsibility
Notification context contract	src/context/notification/NotificationContext.tsx	Defines toast display and notification event APIs
Notification provider	src/context/notification/NotificationProvider.tsx	Manages listener registry, queueing, dedupe, and toast rendering
External bridge	src/context/notification/eventBridge.ts	Queues notifications until the provider is mounted
Notification hook	src/hooks/useNotificationEvents/index.tsx	Exposes sendEvent, sendToastEvent, sendInlineEvent, subscribe, unsubscribe, and clearEvents
Scoped hook	src/hooks/useNotificationEvents/useScopedNotification.ts	Tracks the latest scoped inline notification for a page
Event helpers	src/hooks/useNotificationEvents/eventHandler.ts	sendEvent, sendToastEvent, sendInlineEvent, and clearEvents for publishers outside the React tree

Delivery Modes

Every GlobalEvent carries an optional displayMode: 'toast' | 'inline' field that declares how the notification should be rendered.

Explicit Mode

When displayMode is set, NotificationProvider respects it unconditionally:

• 'toast' — enqueues a Carbon ToastNotification, even if eventTarget is also set.
• 'inline' — routes the event to listeners only; no toast is rendered.

Legacy Fallback

When displayMode is absent, the provider uses the original implicit rule for backward compatibility:

• Events with eventTarget → inline (handled by useScopedNotification).
• Events without eventTarget → toast.

Global Toast Notifications

App-wide messages — service worker registration, PWA lifecycle updates — use displayMode: 'toast' (or sendToastEvent). They are rendered by NotificationProvider as a queued, deduplicated Carbon toast.

Page-Scoped Inline Notifications

Page-local errors — search failures, client list errors — use displayMode: 'inline' with an eventTarget string. They are consumed by useScopedNotification and rendered as an inline banner on the matching page. The scoped hook ignores any event whose mode is explicitly 'toast'.

Clear Semantics

clearEvents(target?) emits a synthetic info event with title clear-events and displayMode: 'inline'. This signals useScopedNotification to clear its banner without triggering a toast.

Event Sources

Source	Pattern	Example
Shared TanStack Query hooks	notificationTarget option triggers scoped error notification emission	useSearchReportingUnitsQuery(..., { notificationTarget: 'waste-search' })
Components	useNotificationEvents()	Search and client listing pages clear scoped notifications before refetching
Outside React tree	sendEvent() helper via eventBridge.ts	registerServiceWorker.ts publishes offline and refresh messages

Flow

sequenceDiagram
  participant Producer as Producer
  participant Bridge as eventBridge.ts
  participant Provider as NotificationProvider
  participant Scoped as useScopedNotification
  participant Toast as Carbon Toast

  Producer->>Bridge: sendToastEvent / sendInlineEvent / sendEvent
  Bridge->>Provider: dispatchNotificationEvent(event)
  Provider->>Scoped: notify all listeners for the event type
  alt displayMode === 'toast' (or no eventTarget)
    Provider->>Toast: enqueue toast notification
  else displayMode === 'inline' (or eventTarget set)
    Scoped-->>Producer: page-scoped inline notification state updates
  end

Loading

API Reference

Inside the React tree

const { sendToastEvent, sendInlineEvent, sendEvent, clearEvents } = useNotificationEvents();

Helper	When to use
sendToastEvent(event)	App-wide status messages, PWA lifecycle, one-off confirmations
sendInlineEvent(event)	Page-scoped errors or warnings displayed as inline banners
sendEvent(event)	Advanced use or when displayMode must be set dynamically
clearEvents(target?)	Dismiss the active inline banner for a given page scope

Outside the React tree

Same helpers are available as direct imports from the event handler module:

import { sendToastEvent, sendInlineEvent, sendEvent, clearEvents } from '@/hooks/useNotificationEvents/eventHandler';

These route through eventBridge.ts and queue events before the provider mounts.

Design Constraints

• Do not reintroduce a DOM CustomEvent bus for application notifications.
• Keep server-state concerns in TanStack Query; use notification events only for user-facing messaging.
• Prefer sendToastEvent or sendInlineEvent over raw sendEvent at call sites to make rendering intent explicit.
• Prefer scoped notifications for feature-local errors and toasts for app-wide status changes.
• Keep external publishers isolated behind eventBridge.ts.