Initial Commit

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

@@ -0,0 +1,105 @@
+# OpenSpec Change: enterprise-react-campaigns
+
+- **Change ID**: enterprise-react-campaigns
+- **Package**: `@suaveplan/react-campaigns`
+- **Category**: react
+- **Target path**: `react/platform/react-campaigns`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-campaigns.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-campaigns` on genesis from scratch at enterprise quality. React UI layer on top of `@suaveplan/campaigns`: five-step `CampaignBuilder` wizard (basics → audience → template → schedule → review), `CampaignList`, `CampaignDetail`, `CampaignAnalytics`, `CampaignStatusBadge`, `AudienceSelector`, and three hooks (`useCampaign`, `useCampaignList`, `useCampaignStats`). Genesis fixes the `useCampaign.update` contract (main branch re-fetched instead of calling engine update), removes the module-scoped default engine in favour of `CampaignEngineProvider`, splits `campaign-builder.tsx` past the 300-line limit into per-step subcomponents, and adds missing tests for `campaign-builder`, `campaign-detail`, and `use-campaign-stats`.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `CampaignUiError` |
+| `@suaveplan/campaigns` (`workspace:^`) | Campaign engine, schemas, store |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n for all UI strings |
+| `@suaveplan/react-error-boundary` (`workspace:^`) | `CampaignsErrorBoundary` |
+| `@opentelemetry/api` (`catalog:observability`) | `campaign.*` counters + spans |
+| `zod` (`catalog:forms`) | Boundary validation |
+| `tslib` (`catalog:build`) | TS helpers |
+
+External: React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+// Provider
+CampaignEngineProvider, useCampaignEngine
+
+// Components
+CampaignBuilder, CampaignList, CampaignDetail,
+CampaignAnalytics, CampaignStatusBadge, AudienceSelector,
+CampaignsErrorBoundary
+
+// Hooks
+useCampaign, useCampaignList, useCampaignStats
+
+// Types
+AudienceGroup, CampaignBuilderProps, CampaignListProps,
+CampaignDetailProps, CampaignAnalyticsProps, CampaignStatusBadgeProps,
+AudienceSelectorProps, UseCampaignOptions, UseCampaignReturn,
+UseCampaignListOptions, UseCampaignListReturn,
+UseCampaignStatsOptions, UseCampaignStatsReturn
+```
+
+---
+
+## New additions for genesis
+
+1. **`CampaignUiError`** — codes: `CAMPAIGN_ENGINE_MISSING`, `CAMPAIGN_UPDATE_FAILED`, `CAMPAIGN_SEND_FAILED`.
+2. **`CampaignEngineProvider`** — React context replacing module-scoped `defaultEngine`; every hook resolves engine via context or throws `CampaignUiError(CAMPAIGN_ENGINE_MISSING)` in dev.
+3. **`useCampaign.update` fix** — calls real engine update path (main branch re-fetched instead of updating).
+4. **`CampaignBuilder` split** — per-step subcomponents in `steps/` keeping top-level file under 250 lines.
+5. **`CampaignsErrorBoundary`** — exported wrapper via `@suaveplan/react-error-boundary`.
+6. **Missing tests** — `campaign-builder`, `campaign-detail`, `use-campaign-stats` all fully covered.
+7. **OTel counters** — `campaign.created`, `campaign.sent`, `campaign.cancelled`, `campaign.duplicated`.
+8. **Draft auto-save** — debounced save in `CampaignBuilder` with local restore on mount.
+9. **Playwright E2E** — wizard happy path, list filter + pagination, keyboard-only, mobile viewport.
+
+---
+
+## File layout
+
+```text
+react/platform/react-campaigns/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    types/
+    provider/
+      campaign-engine-provider/ (tsx + md + test + index)
+    components/
+      campaign-builder/
+        campaign-builder.tsx + types + md + test + stories + index
+        steps/
+          basics.tsx audience.tsx template.tsx schedule.tsx review.tsx
+      campaign-list/ (tsx + types + md + test + stories + index)
+      campaign-detail/ (tsx + types + md + test + stories + index)
+      campaign-analytics/ (tsx + types + md + test + stories + index)
+      campaign-status-badge/ (tsx + types + md + test + stories + index)
+      audience-selector/ (tsx + types + md + test + stories + index)
+    hooks/
+      use-campaign/ use-campaign-list/ use-campaign-stats/
+  e2e/
+    campaigns.spec.ts
+```