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

@suaveplan/error-backed ChartError — codes: CHART_INVALID_DATA, CHART_RENDER_FAILED, CHART_CANVAS_ERROR.
Zod chart config schemas — LineChartConfigSchema, BarChartConfigSchema, etc. validated in ChartProvider.
Accessible charts — every chart renders <title> + <desc> SVG elements; keyboard-navigable legend with focus ring.
OTel chart.render span — attributes: chart.type, chart.data_points.
Stories — every chart type with default, animated, interactive-tooltip, dark-mode, and a11y stories.
CSS custom property theming — prefers-color-scheme auto-detection; .dark class override.

File layout

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

3.9 KiB Raw Blame History