OpenSpec Change: enterprise-react-notifications

Change ID: enterprise-react-notifications
Package: @suaveplan/react-notifications
Category: react
Target path: react/ui/react-notifications
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-notifications.md

Summary

Deliver @suaveplan/react-notifications on genesis from scratch at enterprise quality. A headless-first toast and notification-center system: pure-TS ToastManager, React bindings (NotificationProvider, useToast, useNotifications), styled components (Toast, ToastContainer, NotificationCenter, NotificationItem) with CVA variants. Styles published as ./styles/notifications.css. Fully tree-shakeable via preserveModules. Genesis adds Playwright E2E, OTel instrumentation, and 100% coverage.

Current-state audit (genesis)

Package does not exist on genesis — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`NotificationError`
`@suaveplan/react-translate` (`workspace:^`)	i18n for dismiss/close labels
`zod` (`catalog:forms`)	Option schemas
`@opentelemetry/api` (`catalog:observability`)	`notification.show` / `notification.dismiss` span

External: class-variance-authority catalog:ui, clsx catalog:ui, lucide-react catalog:ui, tailwind-merge catalog:ui, tslib catalog:build. React 18 peer.

Preserved public API surface

// Headless
ToastManager, createToastManager

// React
NotificationContext, NotificationProvider
useToast, useNotifications

// Components
Toast, toastVariants, ToastContainer
NotificationCenter, NotificationItem

// Types
ToastEvent, ToastEventListener, ToastEventType, ToastInstance, ToastManagerConfig,
ToastOptions, ToastPosition, ToastVariant, Notification, NotificationContextValue,
NotificationOptions, NotificationProviderProps, ...component prop types

New additions for genesis

NotificationError — codes: NOTIFICATION_CONTEXT_MISSING.
OTel notification.show / notification.dismiss span events — attributes: notification.variant, notification.position.
Playwright E2E — toast appears, auto-dismisses, manual dismiss, notification center open/close.
Stories — Toast (all variants), ToastContainer (all positions), NotificationCenter (with history), playground.

File layout

react/ui/react-notifications/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    toast-manager/ (ts + types + md + test + index)
    notification-provider/ (tsx + types + md + test + index)
    hooks/
      use-toast/ (ts + types + md + test + stories + index)
      use-notifications/ (ts + types + md + test + index)
    toast/ (tsx + types + md + test + stories + index)
    toast-container/ (tsx + types + md + test + stories + index)
    notification-center/ (tsx + types + md + test + stories + index)
    notification-item/ (tsx + types + md + test + index)
    utils/
      cn.ts
    styles/
      notifications.css
  e2e/
    notifications.spec.ts

3.1 KiB Raw Blame History