aplance-ui 1.0.1

package/registry/components/ui/chart/chart.tsx

@@ -0,0 +1,1293 @@
+import { useEffect, useId, useRef, useState } from "react";
+import clsx from "clsx";
+import {
+  Area,
+  AreaChart as RechartsAreaChart,
+  Bar,
+  BarChart as RechartsBarChart,
+  CartesianGrid,
+  Cell,
+  ComposedChart as RechartsComposedChart,
+  Line,
+  LineChart as RechartsLineChart,
+  Pie,
+  PieChart,
+  PolarAngleAxis,
+  RadialBar,
+  RadialBarChart as RechartsRadialBarChart,
+  ReferenceLine,
+  ResponsiveContainer,
+  Scatter as RechartsScatter,
+  ScatterChart as RechartsScatterChart,
+  Tooltip,
+  XAxis,
+  YAxis,
+  ZAxis,
+} from "recharts";
+import type { ReactNode } from "react";
+import s from "./chart.module.css";
+import { Loader } from "../loader/loader";
+import type {
+  AreaChartProps,
+  AxisFormatter,
+  BarChartProps,
+  ChartDatum,
+  ChartProps,
+  ChartSeries,
+  ChartSeriesType,
+  ComposedChartProps,
+  DonutChartProps,
+  LineChartProps,
+  RadialBarChartProps,
+  ReferenceLineConfig,
+  ScatterChartProps,
+  TooltipLabelFormatter,
+  TooltipValueFormatter,
+} from "./types";
+import {
+  createChartPalette,
+  pickSeriesColor,
+  resolveColorToken,
+  toLookupKey,
+  type ChartPalette,
+} from "./utils";
+
+export { CHART_COLOR_TOKENS } from "./types";
+export type {
+  AreaChartProps,
+  AxisFormatter,
+  BarChartProps,
+  ChartColorMap,
+  ChartColorTokenName,
+  ChartDatum,
+  ChartProps,
+  ChartSeries,
+  ChartSeriesType,
+  ComposedChartProps,
+  DonutChartProps,
+  LineChartProps,
+  RadialBarChartProps,
+  ReferenceLineConfig,
+  ScatterChartProps,
+  ScatterSeries,
+  TooltipLabelFormatter,
+  TooltipValueFormatter,
+} from "./types";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const DEFAULT_CHART_HEIGHT = 260;
+// left is intentionally negative: pulls Y-axis labels into the card's padding
+// so the visible whitespace on both sides feels balanced.
+const CARTESIAN_MARGIN = { top: 10, right: 10, bottom: 10, left: -8 } as const;
+const YAXIS_WIDTH = 56;
+const YAXIS_WIDTH_HORIZONTAL = 80;
+const BAR_TOP_RADIUS: [number, number, number, number] = [6, 6, 0, 0];
+const BAR_RIGHT_RADIUS: [number, number, number, number] = [0, 6, 6, 0];
+const BAR_FLAT_RADIUS: [number, number, number, number] = [0, 0, 0, 0];
+const DEFAULT_MAX_BAR_SIZE = 44;
+const AXIS_TICK_FONT_SIZE = 11;
+const AXIS_TICK_MARGIN = 10;
+const DEFAULT_LINE_CURVE = "monotone";
+const DEFAULT_AREA_FILL_OPACITY = 0.24;
+const DOT_PROPS = { r: 3, strokeWidth: 2 } as const;
+
+// ─── Internal types ───────────────────────────────────────────────────────────
+
+type TooltipValue = string | number | null | undefined;
+
+type TooltipPayloadItem = {
+  name?: string | number;
+  value?: TooltipValue;
+  color?: string;
+  dataKey?: string | number;
+  payload?: Record<string, unknown>;
+};
+
+type ChartTooltipProps = {
+  active?: boolean;
+  payload?: TooltipPayloadItem[];
+  label?: string | number;
+  valueFormatter?: TooltipValueFormatter;
+  labelFormatter?: TooltipLabelFormatter;
+  // For charts whose Recharts series has no per-cell name (e.g. RadialBar uses
+  // a single dataKey across all sectors), read the row label from the original
+  // datum at this key so the tooltip shows "Aarav" instead of the dataKey.
+  nameKey?: string;
+};
+
+type CartesianRenderOptions = {
+  showGrid?: boolean;
+  showXAxis?: boolean;
+  showYAxis?: boolean;
+  showTooltip?: boolean;
+  showLegend?: boolean;
+  allowDecimals?: boolean;
+  xTickFormatter?: AxisFormatter;
+  yTickFormatter?: AxisFormatter;
+  tooltipValueFormatter?: TooltipValueFormatter;
+  tooltipLabelFormatter?: TooltipLabelFormatter;
+  referenceLines?: ReferenceLineConfig[];
+};
+
+type PreparedSeries = {
+  key: string;
+  label: string;
+  color: string;
+  type: ChartSeriesType;
+  stackId?: string;
+  yAxisId: "left" | "right";
+  strokeWidth: number;
+  fillOpacity: number;
+  dot: boolean;
+  connectNulls: boolean;
+};
+
+type AxisRenderConfig = {
+  showLeftAxis: boolean;
+  showRightAxis: boolean;
+};
+
+type TooltipCursor = {
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  strokeDasharray?: string;
+};
+
+type LegendItem = { key: string; label: string; color: string };
+
+const toLegendItems = (series: PreparedSeries[]): LegendItem[] =>
+  series.map(({ key, label, color }) => ({ key, label, color }));
+
+// ─── Option resolution ────────────────────────────────────────────────────────
+
+const resolveCartesianOptions = (opts: CartesianRenderOptions) => ({
+  showGrid: opts.showGrid ?? true,
+  showXAxis: opts.showXAxis ?? true,
+  showYAxis: opts.showYAxis ?? true,
+  showTooltip: opts.showTooltip ?? true,
+  showLegend: opts.showLegend ?? false,
+  allowDecimals: opts.allowDecimals ?? false,
+  xTickFormatter: opts.xTickFormatter,
+  yTickFormatter: opts.yTickFormatter,
+  tooltipValueFormatter: opts.tooltipValueFormatter,
+  tooltipLabelFormatter: opts.tooltipLabelFormatter,
+  referenceLines: opts.referenceLines ?? [],
+});
+
+type ResolvedCartesianOptions = ReturnType<typeof resolveCartesianOptions>;
+
+type CartesianContext = {
+  options: ResolvedCartesianOptions;
+  preparedSeries: PreparedSeries[];
+  axisConfig: AxisRenderConfig;
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+const resolveAxisRenderConfig = (series: PreparedSeries[]): AxisRenderConfig => ({
+  showLeftAxis: series.some((s) => s.yAxisId !== "right"),
+  showRightAxis: series.some((s) => s.yAxisId === "right"),
+});
+
+const resolveStackTopSeriesKeys = (series: PreparedSeries[]): Set<string> => {
+  const topByStack = new Map<string, string>();
+  for (const item of series) {
+    if (!item.stackId || item.type !== "bar") continue;
+    topByStack.set(`${item.yAxisId}:${item.stackId}`, item.key);
+  }
+  return new Set(topByStack.values());
+};
+
+const resolveBarRadius = (
+  item: PreparedSeries,
+  topStackSeriesKeys: Set<string>,
+  orientation: "vertical" | "horizontal" = "vertical",
+): [number, number, number, number] => {
+  const leadingRadius = orientation === "horizontal" ? BAR_RIGHT_RADIUS : BAR_TOP_RADIUS;
+  if (!item.stackId) return leadingRadius;
+  return topStackSeriesKeys.has(item.key) ? leadingRadius : BAR_FLAT_RADIUS;
+};
+
+const prepareSeries = ({
+  dataKey,
+  series,
+  defaultType,
+  palette,
+  colors,
+  color,
+  seriesLabel,
+  defaultDot = false,
+  defaultConnectNulls = false,
+}: {
+  dataKey?: string;
+  series?: ChartSeries[];
+  defaultType: ChartSeriesType;
+  palette: ChartPalette;
+  colors?: Record<string, string>;
+  color?: string;
+  seriesLabel?: string;
+  defaultDot?: boolean;
+  defaultConnectNulls?: boolean;
+}): PreparedSeries[] => {
+  if (series && series.length > 0) {
+    return series.map((item, index) => {
+      const mappedColor = colors?.[toLookupKey(item.key)];
+      return {
+        key: item.key,
+        label: item.label ?? item.key,
+        color: resolveColorToken(item.color ?? mappedColor, pickSeriesColor(palette, index)),
+        type: item.type ?? defaultType,
+        stackId: item.stackId,
+        yAxisId: item.yAxisId ?? "left",
+        strokeWidth: item.strokeWidth ?? 2,
+        fillOpacity: item.fillOpacity ?? DEFAULT_AREA_FILL_OPACITY,
+        dot: item.dot ?? defaultDot,
+        connectNulls: item.connectNulls ?? defaultConnectNulls,
+      };
+    });
+  }
+
+  if (!dataKey) return [];
+
+  return [
+    {
+      key: dataKey,
+      label: seriesLabel ?? dataKey,
+      color: resolveColorToken(color ?? colors?.[toLookupKey(dataKey)], palette.primary),
+      type: defaultType,
+      yAxisId: "left",
+      strokeWidth: 2,
+      fillOpacity: DEFAULT_AREA_FILL_OPACITY,
+      dot: defaultDot,
+      connectNulls: defaultConnectNulls,
+    },
+  ];
+};
+
+const prepareCartesianContext = ({
+  palette,
+  dataKey,
+  series,
+  defaultType,
+  color,
+  colors,
+  seriesLabel,
+  defaultDot,
+  defaultConnectNulls,
+  ...renderOptions
+}: CartesianRenderOptions & {
+  palette: ChartPalette;
+  dataKey?: string;
+  series?: ChartSeries[];
+  defaultType: ChartSeriesType;
+  color?: string;
+  colors?: Record<string, string>;
+  seriesLabel?: string;
+  defaultDot?: boolean;
+  defaultConnectNulls?: boolean;
+}): CartesianContext => {
+  const options = resolveCartesianOptions(renderOptions);
+  const preparedSeries = prepareSeries({
+    dataKey,
+    series,
+    defaultType,
+    palette,
+    color,
+    colors,
+    seriesLabel,
+    defaultDot,
+    defaultConnectNulls,
+  });
+  return { options, preparedSeries, axisConfig: resolveAxisRenderConfig(preparedSeries) };
+};
+
+// ─── Tooltip ──────────────────────────────────────────────────────────────────
+
+const formatTooltipValue = (value: TooltipValue): string => {
+  if (value === null || value === undefined || value === "") return "-";
+  if (typeof value === "number") return new Intl.NumberFormat().format(value);
+  return String(value);
+};
+
+const formatTooltipEntryValue = (
+  value: TooltipValue,
+  valueFormatter: TooltipValueFormatter | undefined,
+  meta: { name?: string | number; dataKey?: string | number },
+): string => {
+  if (valueFormatter && (typeof value === "number" || typeof value === "string")) {
+    return valueFormatter(value, meta);
+  }
+  return formatTooltipValue(value);
+};
+
+const formatTooltipLabel = (
+  label: string | number | undefined,
+  labelFormatter: TooltipLabelFormatter | undefined,
+): string => {
+  if (label === undefined || label === "") return "";
+  if (labelFormatter) return labelFormatter(label);
+  return String(label);
+};
+
+function ChartTooltip({
+  active,
+  payload,
+  label,
+  valueFormatter,
+  labelFormatter,
+  nameKey,
+}: ChartTooltipProps) {
+  if (!active || !payload?.length) return null;
+
+  const tooltipLabel = formatTooltipLabel(label, labelFormatter);
+
+  return (
+    <div className={s.tooltip}>
+      {tooltipLabel && <div className={s.tooltip_label}>{tooltipLabel}</div>}
+      {payload.map((entry, index) => {
+        const fromPayload = nameKey ? entry.payload?.[nameKey] : undefined;
+        const rowName = fromPayload ?? entry.name ?? entry.dataKey ?? "Value";
+        return (
+          <div
+            key={`${entry.dataKey ?? entry.name ?? "value"}-${index}`}
+            className={s.tooltip_row}
+          >
+            <span className={s.tooltip_dot} style={{ backgroundColor: entry.color }} />
+            <span>{String(rowName)}</span>
+            <span className={s.tooltip_value}>
+              {formatTooltipEntryValue(entry.value, valueFormatter, {
+                name: entry.name,
+                dataKey: entry.dataKey,
+              })}
+            </span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+// ─── Shared legend ────────────────────────────────────────────────────────────
+
+function ChartLegend({ items }: { items: LegendItem[] }) {
+  return (
+    <div className={s.legend}>
+      {items.map((item) => (
+        <div key={item.key} className={s.legend_item}>
+          <span className={s.legend_dot} style={{ backgroundColor: item.color }} />
+          <span>{item.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ─── Cartesian frame ──────────────────────────────────────────────────────────
+// Returns an array so Recharts' React.Children.toArray scan finds XAxis/YAxis
+// directly - Fragments are opaque to that scan, arrays are not.
+
+const renderCartesianFrame = ({
+  categoryKey,
+  palette,
+  options,
+  axisConfig,
+  tooltipCursor,
+  orientation = "vertical",
+}: {
+  categoryKey: string;
+  palette: ChartPalette;
+  options: ResolvedCartesianOptions;
+  axisConfig: AxisRenderConfig;
+  tooltipCursor: TooltipCursor;
+  orientation?: "vertical" | "horizontal";
+}): ReactNode[] => {
+  const isHorizontal = orientation === "horizontal";
+
+  const items: ReactNode[] = [
+    options.showGrid ? (
+      <CartesianGrid
+        key="grid"
+        strokeDasharray="3 3"
+        vertical={isHorizontal}
+        horizontal={!isHorizontal}
+        stroke={palette.grid}
+      />
+    ) : null,
+
+    // X axis - category axis (vertical layout) or value axis (horizontal layout)
+    options.showXAxis ? (
+      isHorizontal ? (
+        <XAxis
+          key="x-axis"
+          type="number"
+          tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+          tickMargin={AXIS_TICK_MARGIN}
+          tickLine={false}
+          axisLine={{ stroke: palette.grid }}
+          allowDecimals={options.allowDecimals}
+          tickFormatter={options.yTickFormatter}
+        />
+      ) : (
+        <XAxis
+          key="x-axis"
+          dataKey={categoryKey}
+          tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+          tickMargin={AXIS_TICK_MARGIN}
+          minTickGap={16}
+          tickLine={false}
+          axisLine={{ stroke: palette.grid }}
+          tickFormatter={options.xTickFormatter}
+        />
+      )
+    ) : null,
+
+    // Left Y axis - value axis (vertical) or category axis (horizontal)
+    options.showYAxis && axisConfig.showLeftAxis ? (
+      isHorizontal ? (
+        <YAxis
+          key="y-axis-left"
+          yAxisId="left"
+          type="category"
+          dataKey={categoryKey}
+          width={YAXIS_WIDTH_HORIZONTAL}
+          tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+          tickMargin={AXIS_TICK_MARGIN}
+          tickLine={false}
+          axisLine={{ stroke: palette.grid }}
+          tickFormatter={options.xTickFormatter}
+        />
+      ) : (
+        <YAxis
+          key="y-axis-left"
+          yAxisId="left"
+          width={YAXIS_WIDTH}
+          tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+          tickMargin={AXIS_TICK_MARGIN}
+          tickLine={false}
+          axisLine={{ stroke: palette.grid }}
+          allowDecimals={options.allowDecimals}
+          tickFormatter={options.yTickFormatter}
+        />
+      )
+    ) : null,
+
+    // Right Y axis - only for vertical orientation with dual-axis series
+    options.showYAxis && axisConfig.showRightAxis && !isHorizontal ? (
+      <YAxis
+        key="y-axis-right"
+        yAxisId="right"
+        orientation="right"
+        width={YAXIS_WIDTH}
+        tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+        tickMargin={AXIS_TICK_MARGIN}
+        tickLine={false}
+        axisLine={{ stroke: palette.grid }}
+        allowDecimals={options.allowDecimals}
+        tickFormatter={options.yTickFormatter}
+      />
+    ) : null,
+
+    options.showTooltip ? (
+      <Tooltip
+        key="tooltip"
+        content={
+          <ChartTooltip
+            valueFormatter={options.tooltipValueFormatter}
+            labelFormatter={options.tooltipLabelFormatter}
+          />
+        }
+        cursor={tooltipCursor}
+      />
+    ) : null,
+  ];
+
+  for (const [i, rl] of options.referenceLines.entries()) {
+    items.push(
+      <ReferenceLine
+        key={`rl-${i}`}
+        {...(rl.axis === "x"
+          ? { x: rl.value }
+          : {
+              y: rl.value,
+              yAxisId: options.showYAxis ? (rl.yAxisId ?? "left") : undefined,
+            })}
+        stroke={resolveColorToken(rl.color, palette.muted)}
+        strokeDasharray={rl.strokeDasharray ?? "4 4"}
+        strokeWidth={1}
+        label={
+          rl.label
+            ? {
+                value: rl.label,
+                fontSize: AXIS_TICK_FONT_SIZE,
+                fill: palette.muted,
+                position: "insideTopLeft",
+              }
+            : undefined
+        }
+      />,
+    );
+  }
+
+  return items;
+};
+
+// ─── Bar chart ────────────────────────────────────────────────────────────────
+
+function BarChartRenderer({
+  data,
+  dataKey,
+  categoryKey,
+  colors,
+  series,
+  maxBarSize,
+  height,
+  showGrid,
+  showXAxis,
+  showYAxis,
+  showTooltip,
+  showLegend,
+  allowDecimals,
+  xTickFormatter,
+  yTickFormatter,
+  tooltipValueFormatter,
+  tooltipLabelFormatter,
+  referenceLines,
+  orientation = "vertical",
+  barCategoryGap,
+}: BarChartProps & { height: number }) {
+  const palette = createChartPalette();
+  const { options, preparedSeries, axisConfig } = prepareCartesianContext({
+    palette,
+    dataKey,
+    series,
+    defaultType: "bar",
+    colors,
+    showGrid,
+    showXAxis,
+    showYAxis,
+    showTooltip,
+    showLegend,
+    allowDecimals,
+    xTickFormatter,
+    yTickFormatter,
+    tooltipValueFormatter,
+    tooltipLabelFormatter,
+    referenceLines,
+  });
+  const topStackSeriesKeys = resolveStackTopSeriesKeys(preparedSeries);
+  const usesCategoryColorMap =
+    preparedSeries.length === 1 && !series?.length && Boolean(colors);
+  const legendItems = toLegendItems(preparedSeries);
+  const isHorizontal = orientation === "horizontal";
+
+  return (
+    <>
+      <ResponsiveContainer width="100%" height={height}>
+        <RechartsBarChart
+          data={data}
+          layout={isHorizontal ? "vertical" : "horizontal"}
+          margin={CARTESIAN_MARGIN}
+          {...(barCategoryGap !== undefined ? { barCategoryGap } : {})}
+        >
+          {renderCartesianFrame({
+            categoryKey,
+            palette,
+            options,
+            axisConfig,
+            tooltipCursor: { fill: palette.cursor },
+            orientation,
+          })}
+
+          {preparedSeries.map((item) => (
+            <Bar
+              key={item.key}
+              dataKey={item.key}
+              name={item.label}
+              radius={resolveBarRadius(item, topStackSeriesKeys, orientation)}
+              maxBarSize={maxBarSize ?? DEFAULT_MAX_BAR_SIZE}
+              fill={item.color}
+              stackId={item.stackId}
+              yAxisId={options.showYAxis ? item.yAxisId : undefined}
+            >
+              {usesCategoryColorMap &&
+                data.map((entry, index) => {
+                  const key = toLookupKey(entry[categoryKey]);
+                  const fill = resolveColorToken(colors?.[key], item.color);
+                  return <Cell key={`${item.key}-${key}-${index}`} fill={fill} />;
+                })}
+            </Bar>
+          ))}
+        </RechartsBarChart>
+      </ResponsiveContainer>
+      {options.showLegend && legendItems.length > 0 && (
+        <ChartLegend items={legendItems} />
+      )}
+    </>
+  );
+}
+
+// ─── Area chart ───────────────────────────────────────────────────────────────
+
+function AreaChartRenderer({
+  data,
+  dataKey,
+  categoryKey,
+  series,
+  color,
+  seriesLabel,
+  height,
+  showGrid,
+  showXAxis,
+  showYAxis,
+  showTooltip,
+  showLegend,
+  allowDecimals,
+  xTickFormatter,
+  yTickFormatter,
+  tooltipValueFormatter,
+  tooltipLabelFormatter,
+  referenceLines,
+  showDots,
+  connectNulls,
+}: AreaChartProps & { height: number }) {
+  const palette = createChartPalette();
+  const { options, preparedSeries, axisConfig } = prepareCartesianContext({
+    palette,
+    dataKey,
+    series,
+    defaultType: "area",
+    color,
+    seriesLabel,
+    defaultDot: showDots,
+    defaultConnectNulls: connectNulls,
+    showGrid,
+    showXAxis,
+    showYAxis,
+    showTooltip,
+    showLegend,
+    allowDecimals,
+    xTickFormatter,
+    yTickFormatter,
+    tooltipValueFormatter,
+    tooltipLabelFormatter,
+    referenceLines,
+  });
+  const idSeed = useId().replace(/:/g, "");
+  const gradients = preparedSeries.map((item, index) => ({
+    ...item,
+    gradientId: `chart-area-${idSeed}-${index}`,
+  }));
+  const legendItems = toLegendItems(preparedSeries);
+
+  return (
+    <>
+      <ResponsiveContainer width="100%" height={height}>
+        <RechartsAreaChart data={data} margin={CARTESIAN_MARGIN}>
+          <defs>
+            {gradients.map((item) => (
+              <linearGradient
+                key={item.gradientId}
+                id={item.gradientId}
+                x1="0"
+                y1="0"
+                x2="0"
+                y2="1"
+              >
+                <stop offset="0%" stopColor={item.color} stopOpacity={item.fillOpacity} />
+                <stop offset="95%" stopColor={item.color} stopOpacity={0} />
+              </linearGradient>
+            ))}
+          </defs>
+
+          {renderCartesianFrame({
+            categoryKey,
+            palette,
+            options,
+            axisConfig,
+            tooltipCursor: { stroke: palette.cursor, strokeWidth: 1 },
+          })}
+
+          {gradients.map((item) => (
+            <Area
+              key={item.key}
+              type={DEFAULT_LINE_CURVE}
+              dataKey={item.key}
+              name={item.label}
+              stroke={item.color}
+              strokeWidth={item.strokeWidth}
+              fill={`url(#${item.gradientId})`}
+              dot={item.dot ? DOT_PROPS : false}
+              activeDot={{ r: 4 }}
+              connectNulls={item.connectNulls}
+              yAxisId={options.showYAxis ? item.yAxisId : undefined}
+              stackId={item.stackId}
+            />
+          ))}
+        </RechartsAreaChart>
+      </ResponsiveContainer>
+      {options.showLegend && legendItems.length > 0 && (
+        <ChartLegend items={legendItems} />
+      )}
+    </>
+  );
+}
+
+// ─── Line chart ───────────────────────────────────────────────────────────────
+
+function LineChartRenderer({
+  data,
+  dataKey,
+  categoryKey,
+  series,
+  color,
+  seriesLabel,
+  curveType,
+  height,
+  showGrid,
+  showXAxis,
+  showYAxis,
+  showTooltip,
+  showLegend,
+  allowDecimals,
+  xTickFormatter,
+  yTickFormatter,
+  tooltipValueFormatter,
+  tooltipLabelFormatter,
+  referenceLines,
+  showDots,
+  connectNulls,
+}: LineChartProps & { height: number }) {
+  const palette = createChartPalette();
+  const { options, preparedSeries, axisConfig } = prepareCartesianContext({
+    palette,
+    dataKey,
+    series,
+    defaultType: "line",
+    color,
+    seriesLabel,
+    defaultDot: showDots,
+    defaultConnectNulls: connectNulls,
+    showGrid,
+    showXAxis,
+    showYAxis,
+    showTooltip,
+    showLegend,
+    allowDecimals,
+    xTickFormatter,
+    yTickFormatter,
+    tooltipValueFormatter,
+    tooltipLabelFormatter,
+    referenceLines,
+  });
+  const legendItems = toLegendItems(preparedSeries);
+
+  return (
+    <>
+      <ResponsiveContainer width="100%" height={height}>
+        <RechartsLineChart data={data} margin={CARTESIAN_MARGIN}>
+          {renderCartesianFrame({
+            categoryKey,
+            palette,
+            options,
+            axisConfig,
+            tooltipCursor: { stroke: palette.cursor, strokeWidth: 1 },
+          })}
+
+          {preparedSeries.map((item) => (
+            <Line
+              key={item.key}
+              type={curveType ?? DEFAULT_LINE_CURVE}
+              dataKey={item.key}
+              name={item.label}
+              stroke={item.color}
+              strokeWidth={item.strokeWidth}
+              dot={item.dot ? DOT_PROPS : false}
+              activeDot={{ r: 4 }}
+              connectNulls={item.connectNulls}
+              yAxisId={options.showYAxis ? item.yAxisId : undefined}
+            />
+          ))}
+        </RechartsLineChart>
+      </ResponsiveContainer>
+      {options.showLegend && legendItems.length > 0 && (
+        <ChartLegend items={legendItems} />
+      )}
+    </>
+  );
+}
+
+// ─── Composed chart ───────────────────────────────────────────────────────────
+
+function ComposedChartRenderer({
+  data,
+  categoryKey,
+  series,
+  height,
+  showGrid,
+  showXAxis,
+  showYAxis,
+  showTooltip,
+  showLegend,
+  allowDecimals,
+  xTickFormatter,
+  yTickFormatter,
+  tooltipValueFormatter,
+  tooltipLabelFormatter,
+  referenceLines,
+}: ComposedChartProps & { height: number }) {
+  const palette = createChartPalette();
+  const { options, preparedSeries, axisConfig } = prepareCartesianContext({
+    palette,
+    series,
+    defaultType: "bar",
+    showGrid,
+    showXAxis,
+    showYAxis,
+    showTooltip,
+    showLegend,
+    allowDecimals,
+    xTickFormatter,
+    yTickFormatter,
+    tooltipValueFormatter,
+    tooltipLabelFormatter,
+    referenceLines,
+  });
+  const idSeed = useId().replace(/:/g, "");
+  const topStackSeriesKeys = resolveStackTopSeriesKeys(preparedSeries);
+  const areaSeries = preparedSeries.filter((s) => s.type === "area");
+  const gradientMap = new Map(
+    areaSeries.map((item, index) => [item.key, `chart-composed-${idSeed}-${index}`]),
+  );
+  const legendItems = toLegendItems(preparedSeries);
+
+  return (
+    <>
+      <ResponsiveContainer width="100%" height={height}>
+        <RechartsComposedChart data={data} margin={CARTESIAN_MARGIN}>
+          {areaSeries.length > 0 && (
+            <defs>
+              {areaSeries.map((item) => {
+                const id = gradientMap.get(item.key)!;
+                return (
+                  <linearGradient key={id} id={id} x1="0" y1="0" x2="0" y2="1">
+                    <stop offset="0%" stopColor={item.color} stopOpacity={item.fillOpacity} />
+                    <stop offset="95%" stopColor={item.color} stopOpacity={0} />
+                  </linearGradient>
+                );
+              })}
+            </defs>
+          )}
+
+          {renderCartesianFrame({
+            categoryKey,
+            palette,
+            options,
+            axisConfig,
+            tooltipCursor: { stroke: palette.cursor, strokeWidth: 1 },
+          })}
+
+          {preparedSeries.map((item) => {
+            if (item.type === "line") {
+              return (
+                <Line
+                  key={item.key}
+                  type={DEFAULT_LINE_CURVE}
+                  dataKey={item.key}
+                  name={item.label}
+                  stroke={item.color}
+                  strokeWidth={item.strokeWidth}
+                  dot={item.dot ? DOT_PROPS : false}
+                  activeDot={{ r: 4 }}
+                  connectNulls={item.connectNulls}
+                  yAxisId={options.showYAxis ? item.yAxisId : undefined}
+                />
+              );
+            }
+
+            if (item.type === "area") {
+              const gradientId = gradientMap.get(item.key);
+              return (
+                <Area
+                  key={item.key}
+                  type={DEFAULT_LINE_CURVE}
+                  dataKey={item.key}
+                  name={item.label}
+                  stroke={item.color}
+                  strokeWidth={item.strokeWidth}
+                  fill={gradientId ? `url(#${gradientId})` : item.color}
+                  fillOpacity={gradientId ? 1 : item.fillOpacity}
+                  dot={item.dot ? DOT_PROPS : false}
+                  activeDot={{ r: 4 }}
+                  connectNulls={item.connectNulls}
+                  yAxisId={options.showYAxis ? item.yAxisId : undefined}
+                  stackId={item.stackId}
+                />
+              );
+            }
+
+            return (
+              <Bar
+                key={item.key}
+                dataKey={item.key}
+                name={item.label}
+                radius={resolveBarRadius(item, topStackSeriesKeys)}
+                maxBarSize={DEFAULT_MAX_BAR_SIZE}
+                fill={item.color}
+                stackId={item.stackId}
+                yAxisId={options.showYAxis ? item.yAxisId : undefined}
+              />
+            );
+          })}
+        </RechartsComposedChart>
+      </ResponsiveContainer>
+      {options.showLegend && legendItems.length > 0 && (
+        <ChartLegend items={legendItems} />
+      )}
+    </>
+  );
+}
+
+// ─── Donut chart ──────────────────────────────────────────────────────────────
+
+function DonutChartRenderer({
+  data,
+  dataKey,
+  nameKey,
+  colors,
+  centerContent,
+  showLegend = true,
+  innerRadius,
+  outerRadius,
+  paddingAngle,
+  tooltipValueFormatter,
+  tooltipLabelFormatter,
+  height,
+}: DonutChartProps & { height: number }) {
+  const palette = createChartPalette();
+
+  const chartData = data.map((entry) => ({
+    ...entry,
+    __chartValue:
+      typeof entry[dataKey] === "number"
+        ? (entry[dataKey] as number)
+        : Number(entry[dataKey] ?? 0) || 0,
+  }));
+
+  const legendItems: LegendItem[] = data.map((entry, index) => {
+    const rawLabel = entry[nameKey];
+    const label =
+      rawLabel !== undefined && rawLabel !== null && tooltipLabelFormatter
+        ? tooltipLabelFormatter(rawLabel as string | number)
+        : String(rawLabel ?? `Item ${index + 1}`);
+    const lookup = toLookupKey(rawLabel);
+    return {
+      key: label,
+      label,
+      // Fix: use series color rotation, not palette.muted, for uncolored segments
+      color: resolveColorToken(colors?.[lookup], pickSeriesColor(palette, index)),
+    };
+  });
+
+  const resolvedOuterRadius = Math.max(outerRadius ?? Math.max(height * 0.34, 88), 36);
+  const resolvedInnerRadius = Math.max(
+    16,
+    Math.min(innerRadius ?? Math.max(height * 0.22, 56), resolvedOuterRadius - 12),
+  );
+  const resolvedCenterSize = Math.max(resolvedInnerRadius * 2 - 12, 56);
+  const resolvedPaddingAngle = paddingAngle ?? (chartData.length > 5 ? 2 : 3);
+
+  return (
+    <>
+      <div className={s.canvas}>
+        <ResponsiveContainer width="100%" height={height}>
+          <PieChart>
+            <Pie
+              data={chartData}
+              cx="50%"
+              cy="50%"
+              innerRadius={resolvedInnerRadius}
+              outerRadius={resolvedOuterRadius}
+              paddingAngle={resolvedPaddingAngle}
+              dataKey="__chartValue"
+              nameKey={nameKey}
+              stroke="var(--color-background)"
+              strokeWidth={2}
+            >
+              {legendItems.map((item, index) => (
+                <Cell key={`${item.key}-${index}`} fill={item.color} />
+              ))}
+            </Pie>
+            <Tooltip
+              content={
+                <ChartTooltip
+                  valueFormatter={tooltipValueFormatter}
+                  labelFormatter={tooltipLabelFormatter}
+                />
+              }
+            />
+          </PieChart>
+        </ResponsiveContainer>
+
+        {centerContent && (
+          <div
+            className={s.center_overlay}
+            style={{ width: resolvedCenterSize, height: resolvedCenterSize }}
+          >
+            {centerContent}
+          </div>
+        )}
+      </div>
+
+      {showLegend && legendItems.length > 0 && <ChartLegend items={legendItems} />}
+    </>
+  );
+}
+
+// ─── Radial bar chart ─────────────────────────────────────────────────────────
+
+function RadialBarChartRenderer({
+  data,
+  dataKey,
+  nameKey,
+  colors,
+  showLegend = true,
+  maxValue,
+  tooltipValueFormatter,
+  tooltipLabelFormatter,
+  height,
+}: RadialBarChartProps & { height: number }) {
+  const palette = createChartPalette();
+
+  const chartData = data.map((entry, index) => {
+    const rawLabel = entry[nameKey];
+    const lookup = toLookupKey(rawLabel);
+    const color = resolveColorToken(colors?.[lookup], pickSeriesColor(palette, index));
+    const value =
+      typeof entry[dataKey] === "number"
+        ? (entry[dataKey] as number)
+        : Number(entry[dataKey] ?? 0) || 0;
+    return {
+      ...entry,
+      __value: value,
+      __color: color,
+      __label: String(rawLabel ?? `Item ${index + 1}`),
+    };
+  });
+
+  const legendItems: LegendItem[] = chartData.map((item) => ({
+    key: item.__label,
+    label: item.__label,
+    color: item.__color,
+  }));
+
+  const domainMax = maxValue ?? Math.max(...chartData.map((d) => d.__value), 1);
+
+  return (
+    <>
+      <div className={s.canvas}>
+        <ResponsiveContainer width="100%" height={height}>
+          <RechartsRadialBarChart
+            data={chartData}
+            innerRadius="20%"
+            outerRadius="90%"
+            barSize={12}
+            startAngle={90}
+            endAngle={-270}
+          >
+            <PolarAngleAxis type="number" domain={[0, domainMax]} tick={false} />
+            <RadialBar
+              dataKey="__value"
+              cornerRadius={6}
+              background={{ fill: palette.grid }}
+            >
+              {chartData.map((item, index) => (
+                <Cell key={index} fill={item.__color} />
+              ))}
+            </RadialBar>
+            <Tooltip
+              content={
+                <ChartTooltip
+                  valueFormatter={tooltipValueFormatter}
+                  labelFormatter={tooltipLabelFormatter}
+                  nameKey={nameKey}
+                />
+              }
+            />
+          </RechartsRadialBarChart>
+        </ResponsiveContainer>
+      </div>
+      {showLegend && legendItems.length > 0 && <ChartLegend items={legendItems} />}
+    </>
+  );
+}
+
+// ─── Scatter chart ────────────────────────────────────────────────────────────
+
+function ScatterChartRenderer({
+  series,
+  xKey,
+  yKey,
+  zKey,
+  showGrid,
+  showXAxis,
+  showYAxis,
+  showTooltip,
+  showLegend,
+  allowDecimals,
+  xTickFormatter,
+  yTickFormatter,
+  tooltipValueFormatter,
+  height,
+}: ScatterChartProps & { height: number }) {
+  const palette = createChartPalette();
+
+  const prepared = series.map((s, index) => ({
+    ...s,
+    color: resolveColorToken(s.color, pickSeriesColor(palette, index)),
+    label: s.label ?? s.key,
+  }));
+
+  const legendItems: LegendItem[] = prepared.map((s) => ({
+    key: s.key,
+    label: s.label,
+    color: s.color,
+  }));
+
+  const resolvedShowGrid = showGrid ?? true;
+  const resolvedShowXAxis = showXAxis ?? true;
+  const resolvedShowYAxis = showYAxis ?? true;
+  const resolvedShowTooltip = showTooltip ?? true;
+  const resolvedAllowDecimals = allowDecimals ?? false;
+
+  return (
+    <>
+      <ResponsiveContainer width="100%" height={height}>
+        <RechartsScatterChart margin={CARTESIAN_MARGIN}>
+          {resolvedShowGrid && (
+            <CartesianGrid strokeDasharray="3 3" stroke={palette.grid} />
+          )}
+          {resolvedShowXAxis && (
+            <XAxis
+              dataKey={xKey}
+              type="number"
+              name={xKey}
+              tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+              tickMargin={AXIS_TICK_MARGIN}
+              tickLine={false}
+              axisLine={{ stroke: palette.grid }}
+              allowDecimals={resolvedAllowDecimals}
+              tickFormatter={xTickFormatter}
+            />
+          )}
+          {resolvedShowYAxis && (
+            <YAxis
+              dataKey={yKey}
+              type="number"
+              name={yKey}
+              width={YAXIS_WIDTH}
+              tick={{ fontSize: AXIS_TICK_FONT_SIZE, fill: palette.muted }}
+              tickMargin={AXIS_TICK_MARGIN}
+              tickLine={false}
+              axisLine={{ stroke: palette.grid }}
+              allowDecimals={resolvedAllowDecimals}
+              tickFormatter={yTickFormatter}
+            />
+          )}
+          {zKey && <ZAxis dataKey={zKey} range={[40, 400]} />}
+          {resolvedShowTooltip && (
+            <Tooltip
+              content={<ChartTooltip valueFormatter={tooltipValueFormatter} />}
+              cursor={{ strokeDasharray: "3 3" }}
+            />
+          )}
+          {prepared.map((s) => (
+            <RechartsScatter
+              key={s.key}
+              name={s.label}
+              data={s.data}
+              fill={s.color}
+              fillOpacity={0.8}
+            />
+          ))}
+        </RechartsScatterChart>
+      </ResponsiveContainer>
+      {showLegend && prepared.length > 1 && <ChartLegend items={legendItems} />}
+    </>
+  );
+}
+
+// ─── Public Chart component ───────────────────────────────────────────────────
+
+// Grace period after `isLoading` flips false before committing to the empty
+// state. Eliminates the flash when consumers set isLoading=false a render
+// before populating data - without delaying the genuinely-empty case enough
+// to feel sluggish.
+const EMPTY_STATE_GRACE_MS = 150;
+
+export function Chart(props: ChartProps) {
+  const { title, description, className, emptyMessage, isLoading = false } = props;
+  const height = props.height ?? DEFAULT_CHART_HEIGHT;
+
+  const isEmpty =
+    props.type === "scatter"
+      ? !props.series.length || props.series.every((s) => !s.data.length)
+      : !(props as { data?: ChartDatum[] }).data?.length;
+
+  // Defer the empty state by one tick after a loading→idle transition so the
+  // loader doesn't flicker into "no data" for one paint before data lands.
+  const [showEmptyState, setShowEmptyState] = useState(() => !isLoading && isEmpty);
+  const wasLoadingRef = useRef(isLoading);
+
+  useEffect(() => {
+    const wasLoading = wasLoadingRef.current;
+    wasLoadingRef.current = isLoading;
+
+    if (isLoading || !isEmpty) {
+      setShowEmptyState(false);
+      return;
+    }
+    if (wasLoading) {
+      const id = window.setTimeout(
+        () => setShowEmptyState(true),
+        EMPTY_STATE_GRACE_MS,
+      );
+      return () => window.clearTimeout(id);
+    }
+    setShowEmptyState(true);
+  }, [isLoading, isEmpty]);
+
+  // While loading OR while bridging the loading→empty grace window, show loader.
+  const showLoader = isLoading || (isEmpty && !showEmptyState);
+  const showEmpty = !showLoader && isEmpty;
+
+  return (
+    <section className={clsx(s.card, className)} aria-label={title}>
+      <header className={s.header}>
+        <h3 className={s.title}>{title}</h3>
+        {description && <p className={s.description}>{description}</p>}
+      </header>
+
+      {showLoader ? (
+        <div className={s.loading_state} style={{ height }}>
+          <Loader variant="dots" size="md" color="var(--color-muted-foreground)" />
+        </div>
+      ) : showEmpty ? (
+        <div className={s.empty_state} style={{ height }}>
+          {emptyMessage ?? "No data available"}
+        </div>
+      ) : (
+        <div className={s.plot}>
+          {props.type === "bar" && <BarChartRenderer {...props} height={height} />}
+          {props.type === "area" && <AreaChartRenderer {...props} height={height} />}
+          {props.type === "line" && <LineChartRenderer {...props} height={height} />}
+          {props.type === "composed" && <ComposedChartRenderer {...props} height={height} />}
+          {props.type === "donut" && <DonutChartRenderer {...props} height={height} />}
+          {props.type === "radialbar" && <RadialBarChartRenderer {...props} height={height} />}
+          {props.type === "scatter" && <ScatterChartRenderer {...props} height={height} />}
+        </div>
+      )}
+    </section>
+  );
+}