radiant-charts-core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RadiantCharts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 RadiantCharts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,431 @@
+import React from 'react';
+
+type TooltipTrigger = 'hover' | 'none';
+type TooltipMode = 'shared' | 'item';
+type TooltipPositionMode = 'follow-pointer' | 'snap-to-data' | 'fixed';
+interface TooltipDatumEntry {
+    seriesIndex: number;
+    seriesId: string;
+    seriesType: string;
+    title: string;
+    color: string;
+    datum: Record<string, any>;
+    dataIndex: number;
+    xValue: any;
+    yValue: any;
+}
+interface TooltipState {
+    active: boolean;
+    /** Raw mouse position — viewport-relative (clientX/Y) */
+    pointerX: number;
+    pointerY: number;
+    /** Snapped data-point position — viewport-relative, used as portal anchor */
+    anchorX: number;
+    anchorY: number;
+    /** Chart-local coordinates (relative to container top-left) */
+    localX: number;
+    localY: number;
+    /** Active data entries */
+    entries: TooltipDatumEntry[];
+    /** Shared X-axis label (for shared mode) */
+    sharedLabel: string | null;
+}
+interface TooltipOptions {
+    enabled?: boolean;
+    trigger?: TooltipTrigger;
+    mode?: TooltipMode;
+    positionMode?: TooltipPositionMode;
+    delay?: {
+        show?: number;
+        hide?: number;
+    };
+    offset?: {
+        x?: number;
+        y?: number;
+    };
+    snap?: boolean;
+    shared?: boolean;
+}
+
+interface DataLabelOptions {
+    readonly enabled?: boolean;
+    /** 'top' | 'bottom' | 'left' | 'right' | 'inside' | 'center' | 'outside' */
+    readonly position?: string;
+    readonly fontSize?: number;
+    readonly fontFamily?: string;
+    readonly fill?: string;
+    readonly fontWeight?: string;
+    readonly rotation?: number;
+}
+interface AnimationOptions {
+    readonly enabled?: boolean;
+    readonly duration?: number;
+    readonly easing?: 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'bounce' | 'elastic' | 'back';
+    readonly type?: 'grow' | 'fade' | 'slide' | 'pop' | 'draw' | 'radial';
+    readonly delay?: number;
+}
+interface DropShadow {
+    readonly enabled?: boolean;
+    readonly color?: string;
+    readonly xOffset?: number;
+    readonly yOffset?: number;
+    readonly blur?: number;
+}
+type MarkerShape = 'circle' | 'square' | 'cross' | 'diamond' | 'triangle' | 'plus';
+interface MarkerOptions {
+    readonly enabled?: boolean;
+    readonly shape?: MarkerShape;
+    readonly size?: number;
+    readonly fill?: string;
+    readonly stroke?: string;
+    readonly strokeWidth?: number;
+}
+interface RadiantChartOptions {
+    readonly data: readonly any[];
+    readonly animation?: AnimationOptions;
+    readonly title?: {
+        text: string;
+        fontSize?: number;
+        fill?: string;
+    };
+    readonly subtitle?: {
+        text: string;
+        fontSize?: number;
+        fill?: string;
+    };
+    readonly legend?: {
+        readonly enabled?: boolean;
+        readonly position?: 'top' | 'bottom' | 'left' | 'right';
+        readonly type?: 'discrete';
+        readonly listeners?: {
+            readonly legendItemClick?: (event: {
+                seriesId: string;
+                visible: boolean;
+            }) => void;
+            readonly legendItemDoubleClick?: (event: {
+                seriesId: string;
+                isolated: boolean;
+            }) => void;
+        };
+    };
+    /**
+     * Node-level pointer event callbacks. Triggered when the user interacts with
+     * an individual data point (bar / marker / sector / etc).
+     */
+    readonly listeners?: {
+        readonly nodeClick?: (event: {
+            seriesId: string;
+            datum: any;
+            xKey?: string;
+            yKey?: string;
+            type?: string;
+        }) => void;
+        readonly nodeDoubleClick?: (event: {
+            seriesId: string;
+            datum: any;
+            xKey?: string;
+            yKey?: string;
+            type?: string;
+        }) => void;
+    };
+    readonly showXAxis?: boolean;
+    readonly showYAxis?: boolean;
+    readonly showYAxisRight?: boolean;
+    readonly xAxisFontSize?: number;
+    readonly xAxisFontFamily?: string;
+    readonly xAxisRotation?: number;
+    readonly xAxisLabelAlignment?: 'start' | 'center' | 'end';
+    readonly yAxisFontSize?: number;
+    readonly yAxisFontFamily?: string;
+    readonly yAxisRotation?: number;
+    readonly yAxisLabelAlignment?: 'start' | 'center' | 'end';
+    readonly yAxisRightFontSize?: number;
+    readonly yAxisRightFontFamily?: string;
+    readonly yAxisRightRotation?: number;
+    readonly yAxisRightLabelAlignment?: 'start' | 'center' | 'end';
+    readonly series: readonly {
+        readonly type?: 'bar' | 'line' | 'pie' | 'donut' | 'area' | 'scatter';
+        readonly animation?: AnimationOptions;
+        readonly yAxisId?: 'left' | 'right';
+        readonly xAxisKey?: string;
+        readonly yAxisKey?: string;
+        readonly xKey?: string;
+        readonly yKey?: string;
+        readonly angleKey?: string;
+        readonly labelKey?: string;
+        readonly shadow?: DropShadow;
+        readonly connectMissingData?: boolean;
+        readonly sizeKey?: string;
+        readonly markerSize?: number;
+        readonly title?: string;
+        readonly fill?: string;
+        readonly stroke?: string;
+        readonly strokeWidth?: number;
+        readonly fills?: readonly string[];
+        readonly innerRadius?: number;
+        readonly outerRadius?: number;
+        readonly startAngle?: number;
+        readonly endAngle?: number;
+        readonly padAngle?: number;
+        readonly fillOpacity?: number;
+        readonly cornerRadius?: number;
+        readonly grouped?: boolean;
+        readonly stacked?: boolean;
+        readonly normalized?: boolean;
+        readonly direction?: 'vertical' | 'horizontal';
+        readonly interpolation?: 'linear' | 'step' | 'smooth';
+        /** @deprecated use interpolation:'step' */
+        readonly step?: boolean;
+        readonly marker?: MarkerOptions;
+        readonly jitter?: number;
+        readonly labels?: DataLabelOptions;
+    }[];
+    theme?: 'light' | 'dark' | 'system';
+    padding?: {
+        readonly top?: number;
+        readonly right?: number;
+        readonly bottom?: number;
+        readonly left?: number;
+        readonly inner?: number;
+    };
+    crosshair?: {
+        readonly x?: boolean;
+        readonly y?: boolean;
+    };
+    tooltip?: TooltipOptions;
+    toolbar?: {
+        readonly showExport?: boolean;
+    };
+    /**
+     * Callback triggered when keyboard navigation moves the internal focus index.
+     * Used for synchronizing the virtualized accessibility table.
+     */
+    readonly onFocusChange?: (index: number | null) => void;
+}
+interface RadiantChartHandle {
+    /**
+     * Exports the current chart as a PNG and triggers a browser download.
+     * @param filename  Download filename. Defaults to 'chart.png'.
+     */
+    exportToPng(filename?: string): void;
+}
+interface RadiantChartProps {
+    options: RadiantChartOptions;
+    /**
+     * Explicit width for the chart container. Number = px, string = CSS value.
+     * Defaults to '100%'. For responsive sizing wrap with ResponsiveContainer.
+     */
+    width?: number | string;
+    /**
+     * Explicit height for the chart container. Number = px, string = CSS value.
+     * Defaults to '100%'. When using '100%' the parent must have a defined height,
+     * or wrap with ResponsiveContainer which handles this automatically.
+     */
+    height?: number | string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare const RadiantChart: React.ForwardRefExoticComponent<RadiantChartProps & React.RefAttributes<RadiantChartHandle>>;
+
+interface ResponsiveContainerProps {
+    /**
+     * Width of the container. Number = pixels, string = CSS value (e.g. '100%').
+     * Default: '100%'
+     */
+    width?: number | string;
+    /**
+     * Height of the container. Number = pixels, string = CSS value (e.g. '100%').
+     * When '100%' the container observes its parent and fills it.
+     * Default: 300
+     */
+    height?: number | string;
+    /** Minimum height in px applied as a CSS floor. Default: 100 */
+    minHeight?: number;
+    /** Minimum width in px applied as a CSS floor. Default: 0 */
+    minWidth?: number;
+    /**
+     * Aspect ratio (width ÷ height). When set, height is derived from the
+     * measured container width and this ratio. Overrides `height`.
+     */
+    aspect?: number;
+    /**
+     * Debounce resize callbacks by N ms to avoid excessive re-renders.
+     * Default: 0 (no debounce)
+     */
+    debounce?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+declare const ResponsiveContainer: React.FC<ResponsiveContainerProps>;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+
+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;
+}
+declare const Chart: React.FC<ChartProps>;
+/** 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;
+}
+declare const Bar: React.FC<CommonSeriesProps>;
+declare const Line: React.FC<CommonSeriesProps>;
+declare const Area: React.FC<CommonSeriesProps>;
+declare const Scatter: React.FC<CommonSeriesProps>;
+declare const Pie: React.FC<CommonSeriesProps>;
+declare const Donut: React.FC<CommonSeriesProps>;
+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';
+}
+declare const XAxis: React.FC<AxisProps>;
+declare const YAxis: React.FC<AxisProps>;
+declare const YAxisRight: React.FC<AxisProps>;
+interface TitleProps {
+    text: string;
+    fontSize?: number;
+    fill?: string;
+}
+declare const Title: React.FC<TitleProps>;
+declare const Subtitle: React.FC<TitleProps>;
+interface LegendProps {
+    /** Show or hide the legend. Default: true. */
+    enabled?: boolean;
+    /** Legend placement. */
+    position?: 'top' | 'bottom' | 'left' | 'right';
+}
+declare const Legend: React.FC<LegendProps>;
+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>
+ */
+declare const Tooltip: React.FC<TooltipProps>;
+
+interface ChartTooltipContext {
+    active: boolean;
+    entries: TooltipDatumEntry[];
+    sharedLabel: string | null;
+    pointerX: number;
+    pointerY: number;
+    anchorX: number;
+    anchorY: number;
+    localX: number;
+    localY: number;
+    hide: () => void;
+}
+declare function useChartTooltip(): ChartTooltipContext;
+
+export { type AnimationOptions, Area, type AxisProps, Bar, Chart, type ChartProps, type ChartTooltipContext, type DataLabelOptions, Donut, type DropShadow, Legend, type LegendProps, Line, type MarkerOptions, type MarkerShape, Pie, RadiantChart, type RadiantChartHandle, type RadiantChartOptions, ResponsiveContainer, Scatter, Subtitle, Title, type TitleProps, Tooltip, type TooltipDatumEntry, type TooltipMode, type TooltipOptions, type TooltipPositionMode, type TooltipProps, type TooltipState, type TooltipTrigger, XAxis, YAxis, YAxisRight, useChartTooltip };