Initial Commit
This commit is contained in:
93
openspec/changes/enterprise-react-notifications/proposal.md
Normal file
93
openspec/changes/enterprise-react-notifications/proposal.md
Normal file
@@ -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
|
||||
```
|
||||
110
openspec/changes/enterprise-react-notifications/tasks.md
Normal file
110
openspec/changes/enterprise-react-notifications/tasks.md
Normal file
@@ -0,0 +1,110 @@
|
||||
# Tasks: enterprise-react-notifications
|
||||
|
||||
**Change ID**: enterprise-react-notifications
|
||||
**Package**: `@suaveplan/react-notifications`
|
||||
**Target path**: `react/ui/react-notifications`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/react-translate`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory tree per proposal layout.
|
||||
- [ ] Write `package.json` at `0.1.0` with `"sideEffects": ["**/*.css"]`, exports map (barrel + `./toast-manager` + `./styles/notifications.css`).
|
||||
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/react-translate workspace:^`, `class-variance-authority catalog:ui`, `clsx catalog:ui`, `lucide-react catalog:ui`, `tailwind-merge catalog:ui`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
|
||||
- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Error codes and types
|
||||
|
||||
- [ ] Define `NotificationError`; code: `NOTIFICATION_CONTEXT_MISSING`.
|
||||
- [ ] Define all types: `ToastVariant`, `ToastPosition`, `ToastOptions`, `ToastInstance`, `ToastManagerConfig`, `ToastEventType`, `ToastEvent`, `ToastEventListener`, `Notification`, `NotificationOptions`, `NotificationContextValue`, `NotificationProviderProps`.
|
||||
|
||||
---
|
||||
|
||||
## 3. ToastManager (pure TS)
|
||||
|
||||
- [ ] `createToastManager(config?): ToastManager` — event emitter; `show(options): string`, `dismiss(id)`, `dismissAll()`, `getAll(): ToastInstance[]`.
|
||||
- [ ] Auto-dismiss via `globalThis.setTimeout`; clears on `dismiss()`/`dismissAll()`.
|
||||
- [ ] Emits `ToastEvent` typed events.
|
||||
- [ ] Write `toast-manager.test.ts` (≤500 lines): show/dismiss/dismissAll, auto-dismiss fires, config TTL. `{ timeout: 10000 }`.
|
||||
- [ ] Write `toast-manager.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. NotificationProvider
|
||||
|
||||
- [ ] Wraps `ToastManager` + notification history array in context.
|
||||
- [ ] `useToastContext` throws `NotificationError(NOTIFICATION_CONTEXT_MISSING)` outside provider.
|
||||
- [ ] Write test + md.
|
||||
|
||||
---
|
||||
|
||||
## 5. Hooks
|
||||
|
||||
### `useToast`
|
||||
|
||||
- [ ] Returns `{ toast(options): string, dismiss(id): void, toasts: ToastInstance[] }` from context.
|
||||
- [ ] OTel `notification.show` span on `toast()` with `notification.variant` + `notification.position`.
|
||||
- [ ] Write `use-toast.test.ts`, stories (playground), md.
|
||||
|
||||
### `useNotifications`
|
||||
|
||||
- [ ] Returns persistent notification history + `markRead(id)`, `clearAll()`.
|
||||
- [ ] OTel `notification.dismiss` span on dismiss.
|
||||
- [ ] Write `use-notifications.test.ts`, md.
|
||||
|
||||
---
|
||||
|
||||
## 6. Components
|
||||
|
||||
### Toast
|
||||
|
||||
- [ ] CVA variants (`success`, `error`, `warning`, `info`, `default`); lucide-react icon per variant; dismiss button with `useTranslation("Close")`.
|
||||
- [ ] Write test, stories (all-variants, playground), md.
|
||||
|
||||
### ToastContainer
|
||||
|
||||
- [ ] Positions: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`. Renders active toasts; portal to `document.body`.
|
||||
- [ ] Write test, stories (all-positions), md.
|
||||
|
||||
### NotificationItem
|
||||
|
||||
- [ ] Read/unread state badge, timestamp, body. Write test, md.
|
||||
|
||||
### NotificationCenter
|
||||
|
||||
- [ ] Drawer/popover listing notification history; mark-read / clear-all actions.
|
||||
- [ ] Write test, stories (with-history, empty, playground), md.
|
||||
|
||||
---
|
||||
|
||||
## 7. CSS
|
||||
|
||||
- [ ] `src/styles/notifications.css` — toast animation (slide-in/out), `prefers-reduced-motion` disables animation.
|
||||
|
||||
---
|
||||
|
||||
## 8. E2E
|
||||
|
||||
- [ ] `e2e/notifications.spec.ts` — Playwright:
|
||||
- Call `toast({ message: 'Hello' })`, verify toast appears.
|
||||
- Wait for auto-dismiss TTL, verify toast gone.
|
||||
- Click dismiss button, verify immediate removal.
|
||||
- Open `NotificationCenter`, verify history entry.
|
||||
|
||||
---
|
||||
|
||||
## 9. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-notifications` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-notifications` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-notifications`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user