Initial Commit

openspec/changes/enterprise-react-charts/proposal.md

@@ -0,0 +1,110 @@
+# OpenSpec Change: enterprise-react-charts
+
+- **Change ID**: enterprise-react-charts
+- **Package**: `@suaveplan/react-charts`
+- **Category**: react
+- **Target path**: `react/ui/react-charts`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-charts.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-charts` on genesis from scratch at enterprise quality. A hybrid SVG+Canvas+HTML React charting library: Canvas carries data marks (high-DPI via `devicePixelRatio`), SVG carries crisp axes/grid/crosshair, HTML overlay handles pointer events and renders tooltip + legend. Ships twelve chart types (line, bar, area, pie, scatter, composed, funnel, gauge, heatmap, radar, radial-bar, treemap), headless hooks (`useChart`, `useScales`, `useCanvas`, `useTooltip`, `useAnimation`, `useZoomPan`), shared UI components (axes, grid, legend, tooltip, crosshair, brush, data-label, reference-area, reference-line), `ChartProvider`/`ChartContainer`, OTel instrumentation, and 100% test + docs coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `ChartError` base class |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike` |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n for axis/legend labels |
+| `zod` (`catalog:forms`) | Chart config schemas |
+| `@opentelemetry/api` (`catalog:observability`) | `chart.render` span |
+
+External: `clsx catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+### Chart components
+
+`LineChart`, `BarChart`, `AreaChart`, `PieChart`, `ScatterChart`, `ComposedChart`, `FunnelChart`, `GaugeChart`, `HeatmapChart`, `RadarChart`, `RadialBarChart`, `TreemapChart`
+
+### Shared UI
+
+`Axis` (X + Y), `Grid`, `Legend`, `Tooltip`, `Crosshair`, `Brush`, `DataLabel`, `ReferenceArea`, `ReferenceLine`, `ChartContainer`, `ChartProvider`, `useChartContext`
+
+### Hooks
+
+`useChart`, `useScales`, `useCanvas`, `useTooltip`, `useAnimation`, `useZoomPan`
+
+### Utils
+
+Math utilities (`clamp`, `lerp`, `normalizeData`), color utilities (`colorSchemes`, `interpolateColor`), path utilities (`linePath`, `areaPath`, `arcPath`), data utilities (`groupBy`, `stack`, `bin`)
+
+---
+
+## New additions for genesis
+
+1. **`@suaveplan/error`-backed `ChartError`** — codes: `CHART_INVALID_DATA`, `CHART_RENDER_FAILED`, `CHART_CANVAS_ERROR`.
+2. **Zod chart config schemas** — `LineChartConfigSchema`, `BarChartConfigSchema`, etc. validated in `ChartProvider`.
+3. **Accessible charts** — every chart renders `<title>` + `<desc>` SVG elements; keyboard-navigable legend with focus ring.
+4. **OTel `chart.render` span** — attributes: `chart.type`, `chart.data_points`.
+5. **Stories** — every chart type with default, animated, interactive-tooltip, dark-mode, and a11y stories.
+6. **CSS custom property theming** — `prefers-color-scheme` auto-detection; `.dark` class override.
+
+---
+
+## File layout
+
+```text
+react/ui/react-charts/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    provider/
+      chart-provider/ (tsx + types + md + test + index)
+      chart-container/ (tsx + types + md + test + index)
+    charts/
+      line-chart/ (tsx + types + md + test + stories + index)
+      bar-chart/ ...
+      area-chart/ ...
+      pie-chart/ ...
+      scatter-chart/ ...
+      composed-chart/ ...
+      funnel-chart/ ...
+      gauge-chart/ ...
+      heatmap-chart/ ...
+      radar-chart/ ...
+      radial-bar-chart/ ...
+      treemap-chart/ ...
+    components/
+      axis/ (tsx + types + md + test + index)
+      grid/ legend/ tooltip/ crosshair/ brush/ data-label/
+      reference-area/ reference-line/
+    hooks/
+      use-chart/ use-scales/ use-canvas/ use-tooltip/
+      use-animation/ use-zoom-pan/
+    utils/
+      math/ color/ path/ data/
+    styles/
+      charts.css
+  tests/
+    integration.test.tsx
+  e2e/
+    charts.spec.ts
+```

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

@@ -0,0 +1,101 @@
+# 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.