111 lines
3.9 KiB
Markdown
111 lines
3.9 KiB
Markdown
# 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
|
|
```
|