@alphinex/charts

Theme-aware chart components built on Recharts, sharing one set of design tokens (chartTokens.ts) so every chart in the platform renders with the same grid, axis, tooltip, and 8-slot categorical palette regardless of which chart type it is. Series colors, chrome (grid/axis ink), and status colors all come from CSS variables set by @alphinex/theme's ThemeProvider, so charts repaint automatically on theme/mode change without re-rendering.

Cartesian charts: LineChart, BarChart, AreaChart, ComboChart

LineChart, BarChart, and AreaChart all share the same BaseChartProps<TData> shape: data, a series array of { dataKey, name?, color? }, and xKey naming the field used for the x-axis. Legend is shown automatically once there's more than one series (override with showLegend). ComboChart is the odd one out — its series entries also carry a kind: "bar" | "line" | "area" so you can mix marks (e.g. actuals as bars, target as a line) sharing one x-axis:

import { BarChart, ComboChart, type ChartSeriesConfig } from "@alphinex/charts";

const data = [
  { month: "Jan", revenue: 42000, target: 40000 },
  { month: "Feb", revenue: 45500, target: 42000 },
  { month: "Mar", revenue: 51000, target: 44000 },
];

function RevenueChart() {
  return (
    <BarChart
      data={data}
      series={[{ dataKey: "revenue", name: "Revenue" }]}
      xKey="month"
      height={280}
    />
  );
}

function RevenueVsTargetChart() {
  return (
    <ComboChart
      data={data}
      series={[
        { dataKey: "revenue", name: "Revenue", kind: "bar" },
        { dataKey: "target", name: "Target", kind: "line" },
      ]}
      xKey="month"
      annotations={[{ id: "goal", value: 50000, label: "Q1 goal" }]}
    />
  );
}

annotations (a ChartAnnotation[]) draws reference lines/points over any Cartesian chart — thresholds, targets, or events — independent of the data series themselves.

PieChart, ScatterChart, RadarChart, Sparkline

The remaining chart types don't fit the series/xKey shape and take their own props:

| Component | Props | Notes | | -------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | PieChart | data, dataKey, nameKey, showLegend?, height? | One ring, categorical colors assigned per slice by index. | | ScatterChart | series: ScatterSeriesConfig[] (each with data: ScatterPoint[]), xLabel?, yLabel?, annotations? | A point's optional z renders as bubble radius (bubble chart). | | RadarChart | Same BaseChartProps shape as the Cartesian charts (minus annotations) | xKey names the per-axis subject field for the polar comparison. | | Sparkline | data, dataKey, variant?: "line" \| "area", color?, height? (default 32), width? | Chrome-less — no axes/grid/legend/tooltip. Built for inline use in a StatCard or table cell, not as a standalone chart. |

import { PieChart, Sparkline } from "@alphinex/charts";

<PieChart
  data={[
    { channel: "Organic", visits: 4200 },
    { channel: "Paid", visits: 1800 },
    { channel: "Referral", visits: 900 },
  ]}
  dataKey="visits"
  nameKey="channel"
/>

<Sparkline data={last7Days} dataKey="orders" variant="area" height={28} />

ChartTooltip

ChartTooltip replaces Recharts' unstyled default tooltip with one that uses the platform's surface/border/text tokens. Every chart component in this package already wires it in via <Tooltip content={<ChartTooltip />} /> — you only need it directly if you're composing raw Recharts primitives into a custom chart:

import { Tooltip } from "recharts";
import { ChartTooltip } from "@alphinex/charts";

<Tooltip content={<ChartTooltip />} />;

useChartTheme

Exposes the same token bundle every chart component renders with — the categorical series colors, status colors, and chrome colors — for building a custom chart that still matches the platform's palette:

import { useChartTheme } from "@alphinex/charts";

function CustomChart() {
  const theme = useChartTheme();
  const firstSeriesColor = theme.getSeriesColor(0);
  const warningColor = theme.status.warning;
  // ...pass into your own Recharts composition
}

useChartExport

Exports a chart's own rendered SVG as a .svg or .png download, using native XMLSerializer/canvas APIs (no DOM-to-image dependency — see ADR-0010). Attach chartRef to the <div> wrapper every chart component in this package already renders:

import { useChartExport, LineChart } from "@alphinex/charts";

function ExportableChart() {
  const { chartRef, exportAsPng, exportAsSvg } = useChartExport<HTMLDivElement>({
    fileName: "monthly-revenue",
  });

  return (
    <div ref={chartRef}>
      <LineChart data={data} series={[{ dataKey: "revenue" }]} xKey="month" />
      <button onClick={() => exportAsPng(2)}>Export PNG</button>
      <button onClick={exportAsSvg}>Export SVG</button>
    </div>
  );
}

exportAsPng(scale?) multiplies the SVG's own pixel dimensions for higher-resolution output (defaults to 2).

Chart tokens

CHART_SERIES_VARS (the 8-slot categorical color order — never reorder it, it's the CVD-safety mechanism), CHART_STATUS_COLORS (fixed literal hex for good/warning/serious/critical, deliberately not theme tokens so a status color never impersonates a series), CHART_CHROME (grid/axis/tick/ink/ surface, reusing @alphinex/theme semantic tokens), and getSeriesColor(index) (the index % 8 fallback every chart component uses internally) are all exported for building custom charts or legends that need to match:

import { getSeriesColor, CHART_STATUS_COLORS } from "@alphinex/charts";

const seriesColor = getSeriesColor(2);
const criticalColor = CHART_STATUS_COLORS.critical;

See documentation/ARCHITECTURE.md for the full package contract, dependency rules, and roadmap placement.