radiant-charts-core 0.2.0

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "radiant-charts-core",
+  "version": "0.2.0",
+  "description": "Open-source, MIT-licensed core charting library for React — canvas-rendered, high performance",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.4"
+  }
+}

package/src/Declarative.tsx

@@ -0,0 +1,503 @@
+'use client';
+
+/**
+ * Radiant Charts — Declarative JSX API
+ *
+ * Provides a composable, JSX-first interface that React developers expect.
+ * Children register their configuration with the parent <Chart> via context;
+ * the parent assembles a standard RadiantChartOptions object and renders a
+ * single imperative RadiantChart under the hood.
+ *
+ * @example
+ * ```tsx
+ * import { Chart, Bar, Line, XAxis, YAxis, Title, Legend } from 'radiant-charts/Declarative';
+ *
+ * const data = [
+ *   { month: 'Jan', sales: 120, target: 100 },
+ *   { month: 'Feb', sales: 150, target: 130 },
+ *   { month: 'Mar', sales: 135, target: 140 },
+ * ];
+ *
+ * export default function Revenue() {
+ *   return (
+ *     <Chart data={data} theme="dark" height={400}>
+ *       <Title text="Monthly Revenue" />
+ *       <Legend position="bottom" />
+ *       <XAxis fontSize={11} rotation={-45} />
+ *       <YAxis show={false} />
+ *       <Bar xKey="month" yKey="sales" fill="#4e79a7" cornerRadius={4} />
+ *       <Line xKey="month" yKey="target" stroke="#e15759" />
+ *     </Chart>
+ *   );
+ * }
+ * ```
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useCallback,
+  useRef,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import RadiantChart, {
+  RadiantChartOptions,
+  AnimationOptions,
+  DataLabelOptions,
+  RadiantChartHandle,
+} from './RadiantChart';
+import type { TooltipOptions } from './tooltip/types';
+
+// ─── Internal Registration Types ──────────────────────────────────────────────
+
+/** Every series child resolves to one of these registration entries. */
+interface SeriesRegistration {
+  id: string;
+  /** The props as-is from the JSX component, minus React children. */
+  props: Record<string, any>;
+}
+
+interface AxisRegistration {
+  axis: 'x' | 'y' | 'y-right';
+  props: Record<string, any>;
+}
+
+interface TitleRegistration {
+  kind: 'title' | 'subtitle';
+  props: { text: string; fontSize?: number; fill?: string };
+}
+
+interface LegendRegistration {
+  enabled?: boolean;
+  position?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+interface ChartContextValue {
+  registerSeries: (id: string, props: Record<string, any>) => void;
+  unregisterSeries: (id: string) => void;
+  registerAxis: (id: string, axis: AxisRegistration) => void;
+  unregisterAxis: (id: string) => void;
+  registerTitle: (id: string, reg: TitleRegistration) => void;
+  unregisterTitle: (id: string) => void;
+  registerLegend: (id: string, reg: LegendRegistration) => void;
+  unregisterLegend: (id: string) => void;
+}
+
+const ChartContext = createContext<ChartContextValue | null>(null);
+
+function useChartContext(): ChartContextValue {
+  const ctx = useContext(ChartContext);
+  if (!ctx) throw new Error('Radiant declarative components must be children of <Chart>.');
+  return ctx;
+}
+
+// ─── ID Generator ─────────────────────────────────────────────────────────────
+
+let _nextId = 0;
+function useStableId(prefix: string): string {
+  const ref = useRef<string>('');
+  if (ref.current === '') ref.current = `${prefix}-${_nextId++}`;
+  return ref.current;
+}
+
+// ─── <Chart> ──────────────────────────────────────────────────────────────────
+
+export interface ChartProps {
+  /** The data array shared by all series children. */
+  data: readonly any[];
+  /** Color theme. Accepts 'light', 'dark', or 'system'. */
+  theme?: 'light' | 'dark' | 'system';
+  /** Chart width. Number = px, string = CSS value. Default '100%'. */
+  width?: number | string;
+  /** Chart height. Number = px, string = CSS value. Default '100%'. */
+  height?: number | string;
+  /** Global animation options applied to all series. */
+  animation?: AnimationOptions;
+  /** Padding around the plot area. */
+  padding?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+    inner?: number;
+  };
+  /** Crosshair configuration. */
+  crosshair?: { x?: boolean; y?: boolean };
+  /** Tooltip configuration. */
+  tooltip?: TooltipOptions;
+  /** Show the export toolbar in the top-right corner. */
+  showExport?: boolean;
+  /** Additional class name applied to the container. */
+  className?: string;
+  /** Inline style applied to the container. */
+  style?: React.CSSProperties;
+  /** Access the imperative chart handle (e.g. exportToPng). */
+  chartRef?: React.Ref<RadiantChartHandle>;
+  /** Declarative series, axis, title, legend, and annotation children. */
+  children?: React.ReactNode;
+}
+
+export const Chart: React.FC<ChartProps> = ({
+  data,
+  theme,
+  width,
+  height,
+  animation,
+  padding,
+  crosshair,
+  tooltip,
+  showExport,
+  className,
+  style,
+  chartRef,
+  children,
+}) => {
+  // ── Mutable registries (writes don't trigger re-render) ───────────────
+  const seriesMap   = useRef(new Map<string, Record<string, any>>());
+  const axisMap     = useRef(new Map<string, AxisRegistration>());
+  const titleMap    = useRef(new Map<string, TitleRegistration>());
+  const legendMap   = useRef(new Map<string, LegendRegistration>());
+  // Incremented to signal a rebuild of the options object.
+  const [rev, setRev] = useState(0);
+  const bump = useCallback(() => setRev(r => r + 1), []);
+
+  // ── Context value (stable across renders) ─────────────────────────────
+  const ctx = useMemo<ChartContextValue>(() => ({
+    registerSeries:       (id, props) => { seriesMap.current.set(id, props); bump(); },
+    unregisterSeries:     (id) =>        { seriesMap.current.delete(id);     bump(); },
+    registerAxis:         (id, a) =>     { axisMap.current.set(id, a);       bump(); },
+    unregisterAxis:       (id) =>        { axisMap.current.delete(id);       bump(); },
+    registerTitle:        (id, t) =>     { titleMap.current.set(id, t);      bump(); },
+    unregisterTitle:      (id) =>        { titleMap.current.delete(id);      bump(); },
+    registerLegend:       (id, l) =>     { legendMap.current.set(id, l);     bump(); },
+    unregisterLegend:     (id) =>        { legendMap.current.delete(id);     bump(); },
+  }), [bump]);
+
+  // ── Build RadiantChartOptions from all registrations ──────────────────
+  const options = useMemo<RadiantChartOptions>(() => {
+    // --- Series ---
+    const series: any[] = [];
+    seriesMap.current.forEach(props => {
+      series.push(props);
+    });
+    // Guarantee at least one series entry so the engine doesn't error.
+    if (series.length === 0) {
+      series.push({ type: 'bar', xKey: 'x', yKey: 'y' });
+    }
+
+    // --- Axes ---
+    let showXAxis: boolean | undefined;
+    let showYAxis: boolean | undefined;
+    let showYAxisRight: boolean | undefined;
+    let xAxisFontSize: number | undefined;
+    let xAxisFontFamily: string | undefined;
+    let xAxisRotation: number | undefined;
+    let xAxisLabelAlignment: 'start' | 'center' | 'end' | undefined;
+    let yAxisFontSize: number | undefined;
+    let yAxisFontFamily: string | undefined;
+    let yAxisRotation: number | undefined;
+    let yAxisLabelAlignment: 'start' | 'center' | 'end' | undefined;
+    let yAxisRightFontSize: number | undefined;
+    let yAxisRightFontFamily: string | undefined;
+    let yAxisRightRotation: number | undefined;
+    let yAxisRightLabelAlignment: 'start' | 'center' | 'end' | undefined;
+
+    axisMap.current.forEach(({ axis, props }) => {
+      if (axis === 'x') {
+        showXAxis = props.show ?? true;
+        xAxisFontSize = props.fontSize;
+        xAxisFontFamily = props.fontFamily;
+        xAxisRotation = props.rotation;
+        xAxisLabelAlignment = props.labelAlignment;
+      } else if (axis === 'y') {
+        showYAxis = props.show ?? true;
+        yAxisFontSize = props.fontSize;
+        yAxisFontFamily = props.fontFamily;
+        yAxisRotation = props.rotation;
+        yAxisLabelAlignment = props.labelAlignment;
+      } else if (axis === 'y-right') {
+        showYAxisRight = props.show ?? true;
+        yAxisRightFontSize = props.fontSize;
+        yAxisRightFontFamily = props.fontFamily;
+        yAxisRightRotation = props.rotation;
+        yAxisRightLabelAlignment = props.labelAlignment;
+      }
+    });
+
+    // --- Title / Subtitle ---
+    let title: RadiantChartOptions['title'];
+    let subtitle: RadiantChartOptions['subtitle'];
+    titleMap.current.forEach(t => {
+      if (t.kind === 'title') title = t.props;
+      else subtitle = t.props;
+    });
+
+    // --- Legend ---
+    let legend: RadiantChartOptions['legend'];
+    legendMap.current.forEach(l => {
+      legend = { enabled: l.enabled ?? true, position: l.position };
+    });
+
+    // --- Tooltip ---
+    // Scanned directly from the JSX children tree rather than the registry,
+    // because these are lightweight config markers — no mount side-effects needed.
+    let tooltipFromChild: TooltipOptions | undefined;
+    React.Children.forEach(children, (child) => {
+      if (React.isValidElement(child) && child.type === Tooltip) {
+        tooltipFromChild = child.props as TooltipOptions;
+      }
+    });
+
+    return {
+      data,
+      theme,
+      animation,
+      padding,
+      crosshair,
+      tooltip: tooltipFromChild ? { ...tooltip, ...tooltipFromChild } : tooltip,
+      toolbar: showExport ? { showExport: true } : undefined,
+      title,
+      subtitle,
+      legend,
+      showXAxis,
+      showYAxis,
+      showYAxisRight,
+      xAxisFontSize,
+      xAxisFontFamily,
+      xAxisRotation,
+      xAxisLabelAlignment,
+      yAxisFontSize,
+      yAxisFontFamily,
+      yAxisRotation,
+      yAxisLabelAlignment,
+      yAxisRightFontSize,
+      yAxisRightFontFamily,
+      yAxisRightRotation,
+      yAxisRightLabelAlignment,
+      series,
+    };
+    // rev is the rebuild signal — it isn't used in the body but must be in
+    // the dependency array so useMemo re-runs when children register/unregister.
+    // children is included so Tooltip prop changes are picked up immediately.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [data, theme, animation, padding, crosshair, tooltip, showExport, children, rev]);
+
+  return (
+    <ChartContext.Provider value={ctx}>
+      {/* Render children so their effects fire and register with ctx */}
+      {children}
+      <RadiantChart
+        ref={chartRef}
+        options={options}
+        width={width}
+        height={height}
+        className={className}
+        style={style}
+      />
+    </ChartContext.Provider>
+  );
+};
+
+// ─── Series Components ────────────────────────────────────────────────────────
+//
+// Each component is a "config-only" node: it renders nothing visible.
+// On mount it registers its props with the parent <Chart> context;
+// on unmount it unregisters. Prop changes trigger a re-registration.
+
+/** Shared props accepted by every series component. */
+interface CommonSeriesProps {
+  xKey?: string;
+  yKey?: string;
+  fill?: string;
+  stroke?: string;
+  strokeWidth?: number;
+  fillOpacity?: number;
+  cornerRadius?: number;
+  title?: string;
+  grouped?: boolean;
+  stacked?: boolean;
+  normalized?: boolean;
+  direction?: 'vertical' | 'horizontal';
+  interpolation?: 'linear' | 'step' | 'smooth';
+  marker?: { enabled?: boolean; size?: number; fill?: string };
+  labels?: DataLabelOptions;
+  animation?: AnimationOptions;
+  yAxisId?: 'left' | 'right';
+  /** Any additional props are forwarded verbatim to the engine. */
+  [key: string]: any;
+}
+
+function createSeriesComponent(seriesType: string, displayName: string) {
+  const Component: React.FC<CommonSeriesProps> = (props) => {
+    const id = useStableId(seriesType);
+    const ctx = useChartContext();
+
+    // Build the full props blob including `type`.
+    const blob = useMemo(
+      () => ({ type: seriesType, ...props }),
+      // Fast-path: serialise props to catch deep changes without a manual dep list.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [JSON.stringify(props)],
+    );
+
+    useEffect(() => {
+      ctx.registerSeries(id, blob);
+      return () => ctx.unregisterSeries(id);
+    }, [ctx, id, blob]);
+
+    return null; // Config-only — no DOM output
+  };
+  Component.displayName = displayName;
+  return Component;
+}
+
+// ── Primary series ────────────────────────────────────────────────────────────
+
+export const Bar         = createSeriesComponent('bar',         'Bar');
+export const Line        = createSeriesComponent('line',        'Line');
+export const Area        = createSeriesComponent('area',        'Area');
+export const Scatter     = createSeriesComponent('scatter',     'Scatter');
+export const Pie         = createSeriesComponent('pie',         'Pie');
+export const Donut       = createSeriesComponent('donut',       'Donut');
+
+
+// ─── Axis Components ──────────────────────────────────────────────────────────
+
+export interface AxisProps {
+  /** Show or hide this axis. Default: true. */
+  show?: boolean;
+  /** Font size for axis labels in px. */
+  fontSize?: number;
+  /** Font family for axis labels. */
+  fontFamily?: string;
+  /** Label rotation in degrees. */
+  rotation?: number;
+  /** Label alignment. */
+  labelAlignment?: 'start' | 'center' | 'end';
+}
+
+export const XAxis: React.FC<AxisProps> = (props) => {
+  const id = useStableId('x-axis');
+  const ctx = useChartContext();
+  const blob = useMemo(() => ({ axis: 'x' as const, props }), [JSON.stringify(props)]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    ctx.registerAxis(id, blob);
+    return () => ctx.unregisterAxis(id);
+  }, [ctx, id, blob]);
+  return null;
+};
+XAxis.displayName = 'XAxis';
+
+export const YAxis: React.FC<AxisProps> = (props) => {
+  const id = useStableId('y-axis');
+  const ctx = useChartContext();
+  const blob = useMemo(() => ({ axis: 'y' as const, props }), [JSON.stringify(props)]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    ctx.registerAxis(id, blob);
+    return () => ctx.unregisterAxis(id);
+  }, [ctx, id, blob]);
+  return null;
+};
+YAxis.displayName = 'YAxis';
+
+export const YAxisRight: React.FC<AxisProps> = (props) => {
+  const id = useStableId('y-axis-right');
+  const ctx = useChartContext();
+  const blob = useMemo(() => ({ axis: 'y-right' as const, props }), [JSON.stringify(props)]); // eslint-disable-line react-hooks/exhaustive-deps
+  useEffect(() => {
+    ctx.registerAxis(id, blob);
+    return () => ctx.unregisterAxis(id);
+  }, [ctx, id, blob]);
+  return null;
+};
+YAxisRight.displayName = 'YAxisRight';
+
+// ─── Title & Subtitle ─────────────────────────────────────────────────────────
+
+export interface TitleProps {
+  text: string;
+  fontSize?: number;
+  fill?: string;
+}
+
+export const Title: React.FC<TitleProps> = (props) => {
+  const id = useStableId('title');
+  const ctx = useChartContext();
+  const blob = useMemo(
+    () => ({ kind: 'title' as const, props }),
+    [JSON.stringify(props)], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+  useEffect(() => {
+    ctx.registerTitle(id, blob);
+    return () => ctx.unregisterTitle(id);
+  }, [ctx, id, blob]);
+  return null;
+};
+Title.displayName = 'Title';
+
+export const Subtitle: React.FC<TitleProps> = (props) => {
+  const id = useStableId('subtitle');
+  const ctx = useChartContext();
+  const blob = useMemo(
+    () => ({ kind: 'subtitle' as const, props }),
+    [JSON.stringify(props)], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+  useEffect(() => {
+    ctx.registerTitle(id, blob);
+    return () => ctx.unregisterTitle(id);
+  }, [ctx, id, blob]);
+  return null;
+};
+Subtitle.displayName = 'Subtitle';
+
+// ─── Legend ───────────────────────────────────────────────────────────────────
+
+export interface LegendProps {
+  /** Show or hide the legend. Default: true. */
+  enabled?: boolean;
+  /** Legend placement. */
+  position?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+export const Legend: React.FC<LegendProps> = (props) => {
+  const id = useStableId('legend');
+  const ctx = useChartContext();
+  const blob = useMemo(
+    () => ({ enabled: props.enabled, position: props.position }),
+    [props.enabled, props.position],
+  );
+  useEffect(() => {
+    ctx.registerLegend(id, blob);
+    return () => ctx.unregisterLegend(id);
+  }, [ctx, id, blob]);
+  return null;
+};
+Legend.displayName = 'Legend';
+
+// ─── Tooltip (declarative config-only component) ─────────────────────────────
+
+export interface TooltipProps extends TooltipOptions {}
+
+/**
+ * Configure the tooltip system declaratively as a child of `<Chart>`.
+ * This is a config-only component — it renders nothing.
+ * Props are passed through to the chart's tooltip options.
+ *
+ * @example
+ * <Chart data={data}>
+ *   <Tooltip
+ *     mode="shared"
+ *     snap
+ *     sticky
+ *     bulletShape="circle"
+ *     bodyTemplate="Revenue: ${revenue}"
+ *     footerTemplate="Source: ${source}"
+ *     style={{ background: '#1a1a2e', borderRadius: 12 }}
+ *   />
+ *   <Bar xKey="month" yKey="sales" />
+ * </Chart>
+ */
+export const Tooltip: React.FC<TooltipProps> = () => null;
+Tooltip.displayName = 'Tooltip';