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

Tasks: enterprise-react-charts

Change ID: enterprise-react-charts Package: @suaveplan/react-charts Target path: react/ui/react-charts Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @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 per chart and component subpath.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/types workspace:^, @suaveplan/react-translate workspace:^, clsx 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 provider

• Define ChartError extending SuaveplanError; codes: CHART_INVALID_DATA, CHART_RENDER_FAILED, CHART_CANVAS_ERROR.
• Implement ChartProvider — context holding theme, color scheme, animation settings. Validates config via Zod on mount.
• Implement ChartContainer — sets up the three-layer (Canvas + SVG + HTML) DOM structure, handles resize via ResizeObserver, forwards ref.
• Implement useChartContext hook.
• Write tests + md for provider and container.

---

3. Headless hooks

For each hook (useChart, useScales, useCanvas, useTooltip, useAnimation, useZoomPan):

• Implement hook with full TypeScript generics.
• Write <hook-name>.test.ts (≤500 lines). { timeout: 5000 }.
• Write <hook-name>.md (≥200 words).

Notable requirements:

• useCanvas — manages devicePixelRatio scaling, returns ctx + clear() + resize().
• useZoomPan — wheel zoom + pointer pan with onZoom/onPan callbacks, reset().
• useAnimation — RAF-based progress ticker with easing functions; respects prefers-reduced-motion.

---

4. Shared UI components

For each (Axis, Grid, Legend, Tooltip, Crosshair, Brush, DataLabel, ReferenceArea, ReferenceLine):

• Implement SVG or HTML component with i18n via useTranslation.
• Legend — keyboard-navigable with focus ring; aria-label per series.
• Write test + md (no stories needed for these primitives; they are covered by chart stories).

---

5. Chart components (12)

For each chart:

• Implement chart component: Canvas data marks + SVG axes + HTML tooltip + Legend.
• Render accessible <title> + <desc> SVG elements with useTranslation copy.
• OTel chart.render span with chart.type and chart.data_points attributes.
• Write <chart>.test.tsx — renders with valid data, renders empty-data state, a11y attributes present. { timeout: 5000 }.
• Write <chart>.stories.tsx — default, animated, interactive-tooltip, dark-mode, a11y.
• Write <chart>.md (≥200 words).

---

6. Utility modules

• math/ — clamp, lerp, normalizeData, extent, linearScale, logScale. Tests + md.
• color/ — colorSchemes (categorical + sequential), interpolateColor, contrastColor. Tests + md.
• path/ — linePath, areaPath, arcPath, curveBasis. Tests + md.
• data/ — groupBy, stack (D3-like), bin, rollup. Tests + md.

---

7. CSS

• src/styles/charts.css — CSS custom property theme tokens (--chart-bg, --chart-grid, --chart-text), dark-mode overrides, @media (prefers-color-scheme: dark).

---

8. Integration and E2E

• tests/integration.test.tsx — LineChart with 1000 data points renders without error; PieChart shows all slices; Legend keyboard nav.
• e2e/charts.spec.ts — Playwright: render LineChart, hover tooltip appears, keyboard-focus legend items.

---

9. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-charts — green.
• bunx turbo test:coverage --filter=@suaveplan/react-charts — 100%.
• bun scripts/publish.ts --package @suaveplan/react-charts.
• Archive change folder.