# 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

```ts
// 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

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

---

## File layout

```text
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
```