Initial Commit

openspec/changes/enterprise-react-notifications/proposal.md

@@ -0,0 +1,93 @@
+# 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
+```