Initial Commit
This commit is contained in:
105
openspec/changes/enterprise-react-campaigns/proposal.md
Normal file
105
openspec/changes/enterprise-react-campaigns/proposal.md
Normal file
@@ -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
|
||||
```
|
||||
117
openspec/changes/enterprise-react-campaigns/tasks.md
Normal file
117
openspec/changes/enterprise-react-campaigns/tasks.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user