# Recharts Migration Design

## Goal

Replace the design system's hand-rolled SVG chart components (LineChart, AreaChart, BarChart) with Recharts-based implementations. The current custom charts have responsiveness issues (preserveAspectRatio distorting text), limited tooltip/axis formatting, and growing maintenance burden.

## Architecture

Add Recharts as a DS dependency. Replace the three custom chart components and `_chart-utils.ts` with a single `ThemedChart` wrapper component. Consumers compose Recharts elements (`<Line>`, `<Area>`, `<Bar>`, etc.) as children inside `<ThemedChart>`. The DS re-exports Recharts components so consumers don't need to add Recharts as a separate dependency.

Sparkline stays hand-rolled SVG (no axes, no tooltips — Recharts is overkill).

### What gets removed

- `composites/LineChart/` directory (LineChart.tsx, LineChart.module.css)
- `composites/AreaChart/` directory (AreaChart.tsx, AreaChart.module.css)
- `composites/BarChart/` directory (BarChart.tsx, BarChart.module.css)
- `composites/_chart-utils.ts`
- `ChartSeries` and `DataPoint` type exports

### What gets added

- `composites/ThemedChart/ThemedChart.tsx` — wrapper component
- `composites/ThemedChart/ChartTooltip.tsx` — internal themed tooltip
- `composites/ThemedChart/ThemedChart.module.css`
- Recharts re-exports from the DS barrel

### What stays unchanged

- `utils/rechartsTheme.ts` (now also used internally by ThemedChart)
- `CHART_COLORS`
- `primitives/Sparkline/`

## Data Format

Consumers use Recharts-native flat data format instead of the current `ChartSeries[]`:

```tsx
// Before (custom)
const series = [
  { label: 'CPU %', data: pts.map(p => ({ x: new Date(p.time), y: p.value * 100 })) }
]
<AreaChart series={series} height={160} yLabel="%" />

// After (Recharts-native)
const data = pts.map(p => ({ time: p.time, cpu: p.value * 100 }))
<ThemedChart data={data} height={160} xDataKey="time" yLabel="%">
  <Area dataKey="cpu" stroke={CHART_COLORS[0]} fill={CHART_COLORS[0]} fillOpacity={0.1} />
</ThemedChart>
```

This is a breaking change. The migration cost is bounded — only `AgentInstance.tsx` in the server repo uses these components.

## ThemedChart API

```tsx
interface ThemedChartProps {
  data: Record<string, any>[]
  height?: number                 // default 200
  xDataKey?: string               // default "time"
  xType?: 'number' | 'category'   // default "category"
  xTickFormatter?: (value: any) => string
  yTickFormatter?: (value: any) => string
  yLabel?: string
  children: React.ReactNode       // Recharts elements
  className?: string
}
```

ThemedChart renders internally:
- `ResponsiveContainer` (width 100%, height from prop)
- `ComposedChart` (supports mixing Line + Bar + Area in one chart)
- `CartesianGrid` with `rechartsTheme.cartesianGrid`
- `XAxis` with `rechartsTheme.xAxis` + formatter
- `YAxis` with `rechartsTheme.yAxis` + formatter + label
- `Tooltip` with custom `ChartTooltip` component

## Tooltip

ThemedChart provides a custom `ChartTooltip` component (internal, not exported) that:
- Shows the x-value formatted as date/time in a header row (mono font, subtle border separator)
- Shows each series with colored dot + label + formatted value
- Uses DS tokens for styling (surface bg, border, shadow, mono font)

Consumers can override by passing their own `<Tooltip content={...} />` as a child. Recharts uses the last Tooltip it finds, so a consumer-provided one replaces the default.

## DS Re-exports

Selected Recharts components re-exported so consumers don't need `recharts` in their own package.json:

```tsx
export { ThemedChart } from './ThemedChart/ThemedChart'
export {
  Line, Area, Bar, ReferenceLine, ReferenceArea,
  Legend, Brush, ComposedChart,
} from 'recharts'
```

More can be added on demand.

## Consumer Migration — Server UI

`AgentInstance.tsx` has 6 charts to migrate:

| Chart | Before | After |
|-------|--------|-------|
| CPU Usage | `<AreaChart series={cpuSeries} threshold={...}>` | `<ThemedChart><Area dataKey="cpu" /><ReferenceLine y={85} /></ThemedChart>` |
| Memory (Heap) | `<AreaChart series={heapSeries} threshold={...}>` | `<ThemedChart><Area dataKey="heap" /><ReferenceLine y={max} /></ThemedChart>` |
| Throughput | `<LineChart series={throughputSeries}>` | `<ThemedChart><Line dataKey="throughput" /></ThemedChart>` |
| Error Rate | `<LineChart series={errorSeries}>` | `<ThemedChart><Line dataKey="errorPct" /></ThemedChart>` |
| Thread Count | `<LineChart series={threadSeries}>` | `<ThemedChart><Line dataKey="threads" /></ThemedChart>` |
| GC Pauses | `<AreaChart series={gcSeries}>` | `<ThemedChart><Area dataKey="gc" /></ThemedChart>` |

Data prep changes from building `ChartSeries[]` arrays to flat objects with named keys.

## Not in Scope

- Sparkline migration (no responsiveness issues, no axes/tooltips)
- SaaS UI (no chart component usage)
- Dashboard tab (already uses Recharts directly with `rechartsTheme`)
- New chart types (treemap, radar, etc. — consumers compose these directly)