# 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.