Initial Commit

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

@@ -0,0 +1,117 @@
+# Tasks: enterprise-react-campaigns
+
+**Change ID**: enterprise-react-campaigns
+**Package**: `@suaveplan/react-campaigns`
+**Target path**: `react/platform/react-campaigns`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/campaigns`, `@suaveplan/react-translate`, `@suaveplan/react-error-boundary`
+
+---
+
+## 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. Write `package.json` at `0.1.0`, `tsconfig.json`, `vitest.config.ts`, scripts.
+- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/campaigns workspace:^`, `@suaveplan/react-translate workspace:^`, `@suaveplan/react-error-boundary workspace:^`, `@opentelemetry/api catalog:observability`, `zod catalog:forms`, `tslib catalog:build`.
+
+---
+
+## 2. Error codes and types
+
+- [ ] Define `CampaignUiError`; codes: `CAMPAIGN_ENGINE_MISSING`, `CAMPAIGN_UPDATE_FAILED`, `CAMPAIGN_SEND_FAILED`.
+- [ ] Define all prop types: `CampaignBuilderProps`, `CampaignListProps`, `CampaignDetailProps`, `CampaignAnalyticsProps`, `CampaignStatusBadgeProps`, `AudienceSelectorProps`, `AudienceGroup`, `UseCampaignOptions`, `UseCampaignReturn`, `UseCampaignListOptions`, `UseCampaignListReturn`, `UseCampaignStatsOptions`, `UseCampaignStatsReturn`.
+
+---
+
+## 3. Provider
+
+### CampaignEngineProvider
+
+- [ ] Provides injected `CampaignEngine` + OTel sink via React context. Throws `CampaignUiError(CAMPAIGN_ENGINE_MISSING)` in dev when hooks called outside provider.
+- [ ] `useCampaignEngine()` to consume context.
+- [ ] Write test + md.
+
+---
+
+## 4. Hooks
+
+### useCampaign
+
+- [ ] CRUD + lifecycle (send/pause/cancel/duplicate). `update(id, updates)` calls real engine update path. OTel spans: `campaign.created`, `campaign.sent`, `campaign.cancelled`, `campaign.duplicated`. Draft auto-save: debounced 500ms with `localStorage` restore.
+- [ ] Write `use-campaign.test.ts` (≤500 lines): CRUD, update calls engine not re-fetch, error propagation, draft auto-save, lifecycle transitions. `{ timeout: 10000 }`.
+- [ ] Write `use-campaign.md`.
+
+### useCampaignList
+
+- [ ] Paginated list with filter. OTel `campaign.list.load` span.
+- [ ] Write test + md.
+
+### useCampaignStats
+
+- [ ] Loads `CampaignStats` counts; computes open/click/bounce/delivery rates. Optionally subscribes to events stream for realtime delta updates.
+- [ ] Write `use-campaign-stats.test.ts` (≤500 lines): rates computed correctly, realtime delta applied. `{ timeout: 10000 }`.
+- [ ] Write `use-campaign-stats.md`.
+
+---
+
+## 5. Components
+
+### CampaignStatusBadge
+
+- [ ] Styled status chip for campaign lifecycle states. All labels via `useTranslation`.
+- [ ] Write test, stories (all-states, playground), md.
+
+### AudienceSelector
+
+- [ ] Group-based targeting selector with estimated recipient count via `useAudienceCount`. All labels via `useTranslation`.
+- [ ] Write test, stories (default, with-groups, empty, playground), md.
+
+### CampaignAnalytics
+
+- [ ] Rates dashboard (open/click/bounce/delivery). `aria-live` region on refresh. All labels via `useTranslation`.
+- [ ] Write test, stories (default, zero-sends, high-engagement, playground), md.
+
+### CampaignList
+
+- [ ] Filterable paginated list with `CampaignStatusBadge`. Bulk select + bulk actions (pause/cancel/duplicate).
+- [ ] Write test, stories (default, filtered, bulk-select, empty, playground), md.
+
+### CampaignDetail
+
+- [ ] Full campaign view with stats, audience, schedule, template preview.
+- [ ] Write `campaign-detail.test.tsx` (≤500 lines): renders all sections, edit triggers useCampaign.update. `{ timeout: 5000 }`.
+- [ ] Write stories (default, sending, completed, playground), md.
+
+### CampaignBuilder (+ steps)
+
+- [ ] Top-level wizard ≤250 lines. Step subcomponents in `steps/`: `basics.tsx`, `audience.tsx`, `template.tsx`, `schedule.tsx`, `review.tsx`. Keyboard step navigation, focus trap per step, ARIA progress indicator.
+- [ ] Write `campaign-builder.test.tsx` (≤500 lines): renders each step, next/back navigation, Zod validation prevents advance on invalid data, review step shows summary, submit calls useCampaign.create. `{ timeout: 10000 }`.
+- [ ] Write stories (default, step-2, step-5-review, validation-errors, playground), md.
+
+### CampaignsErrorBoundary
+
+- [ ] Wrapper via `@suaveplan/react-error-boundary`; displays localised error message + retry button.
+- [ ] Write test + md.
+
+---
+
+## 6. E2E
+
+- [ ] `e2e/campaigns.spec.ts` — Playwright:
+  - Complete wizard happy path (fill all 5 steps, submit); verify campaign appears in list.
+  - Filter campaign list; verify pagination.
+  - Navigate wizard using keyboard only (Tab/Enter/Shift+Tab).
+  - Verify mobile viewport renders single-column layout.
+
+---
+
+## 7. Verify and publish
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-campaigns` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-campaigns` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/react-campaigns`.
+- [ ] Archive change folder.