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

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.