@chartts/core 0.1.0

package/dist/engine-CNukbv7k.d.cts

@@ -0,0 +1,426 @@
+/**
+ * Chartts type definitions.
+ *
+ * RULES:
+ * - This file contains ONLY type/interface declarations and string literal unions.
+ * - ZERO runtime code. No functions, no objects, no const values.
+ * - This file imports NOTHING from the project.
+ * - Every other module in the project can import from here without risk of cycles.
+ */
+/** A single data series */
+interface Series {
+    name: string;
+    values: number[];
+    color?: string;
+    style?: 'solid' | 'dashed' | 'dotted';
+    fill?: boolean;
+    fillOpacity?: number;
+    showPoints?: boolean;
+}
+/** Data shape users pass to any chart */
+interface ChartData {
+    labels?: string[] | number[] | Date[];
+    series: Series[];
+}
+/** Resolved data point for events and tooltips */
+interface DataPoint {
+    label: string | number | Date;
+    value: number;
+    index: number;
+    seriesIndex: number;
+    seriesName: string;
+}
+/** Validated + normalized data ready for rendering */
+interface PreparedData {
+    labels: (string | number | Date)[];
+    series: PreparedSeries[];
+    bounds: DataBounds;
+}
+interface PreparedSeries {
+    name: string;
+    values: number[];
+    color: string;
+    style: 'solid' | 'dashed' | 'dotted';
+    fill: boolean;
+    fillOpacity: number;
+    showPoints: boolean;
+    index: number;
+}
+interface DataBounds {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+}
+type LegendPosition = 'top' | 'bottom' | 'left' | 'right';
+type CurveType = 'linear' | 'monotone' | 'step';
+interface TooltipConfig {
+    enabled?: boolean;
+    format?: (point: DataPoint) => string;
+    render?: (point: DataPoint & {
+        color: string;
+    }) => string | HTMLElement;
+}
+interface CrosshairConfig {
+    enabled?: boolean;
+    /** Crosshair line direction. Default 'vertical'. */
+    mode?: 'vertical' | 'horizontal' | 'both';
+}
+/** User-facing chart options. Flat. Every field optional. */
+interface ChartOptions {
+    width?: number;
+    height?: number;
+    padding?: [number, number, number, number];
+    /** Rendering backend. Default 'svg'. 'canvas' for 1k-100k points. 'webgl' for 100k+. 'auto' selects based on data size. */
+    renderer?: 'svg' | 'canvas' | 'webgl' | 'auto';
+    /** Data decimation for large datasets. True enables auto LTTB. */
+    decimate?: boolean | {
+        algorithm?: 'lttb' | 'min-max';
+        threshold?: number;
+    };
+    theme?: 'light' | 'dark' | 'auto' | 'corporate' | 'saas' | 'startup' | 'editorial' | 'ocean' | (string & {}) | ThemeConfig;
+    xLabel?: string;
+    yLabel?: string;
+    xFormat?: (value: string | number | Date) => string;
+    yFormat?: (value: number) => string;
+    xGrid?: boolean;
+    yGrid?: boolean;
+    xAxis?: boolean;
+    yAxis?: boolean;
+    xTicks?: number;
+    yTicks?: number;
+    yMin?: number;
+    yMax?: number;
+    legend?: boolean | LegendPosition;
+    tooltip?: boolean | TooltipConfig;
+    animate?: boolean;
+    duration?: number;
+    zoom?: boolean;
+    pan?: boolean;
+    crosshair?: boolean | CrosshairConfig;
+    brush?: boolean;
+    colors?: string[];
+    fontFamily?: string;
+    fontSize?: number;
+    curve?: CurveType;
+    barRadius?: number;
+    barGap?: number;
+    ariaLabel?: string;
+    ariaDescription?: string;
+    onClick?: (point: DataPoint, event: MouseEvent) => void;
+    onHover?: (point: DataPoint | null, event: MouseEvent) => void;
+    className?: string;
+}
+/** Fully resolved options — no optional fields except forced y bounds */
+interface ResolvedOptions {
+    width: number;
+    height: number;
+    padding: [number, number, number, number];
+    renderer: 'svg' | 'canvas' | 'webgl' | 'auto';
+    theme: string | ThemeConfig;
+    xLabel: string;
+    yLabel: string;
+    xFormat: (value: string | number | Date) => string;
+    yFormat: (value: number) => string;
+    xGrid: boolean;
+    yGrid: boolean;
+    xAxis: boolean;
+    yAxis: boolean;
+    xTicks: number;
+    yTicks: number;
+    yMin: number | undefined;
+    yMax: number | undefined;
+    legend: false | LegendPosition;
+    tooltip: false | TooltipConfig;
+    animate: boolean;
+    duration: number;
+    zoom: boolean;
+    pan: boolean;
+    crosshair: false | CrosshairConfig;
+    brush: boolean;
+    colors: string[];
+    fontFamily: string;
+    fontSize: number;
+    curve: CurveType;
+    barRadius: number;
+    barGap: number;
+    ariaLabel: string;
+    ariaDescription: string;
+    onClick: ChartOptions['onClick'];
+    onHover: ChartOptions['onHover'];
+    className: string;
+}
+interface ThemeConfig {
+    colors: string[];
+    background: string;
+    textColor: string;
+    textMuted: string;
+    axisColor: string;
+    gridColor: string;
+    tooltipBackground: string;
+    tooltipText: string;
+    tooltipBorder: string;
+    fontFamily: string;
+    fontSize: number;
+    fontSizeSmall: number;
+    fontSizeLarge: number;
+    borderRadius: number;
+    gridStyle: 'solid' | 'dashed' | 'dotted';
+    gridWidth: number;
+    axisWidth: number;
+    pointRadius: number;
+    lineWidth: number;
+}
+interface Tick {
+    value: number | string | Date;
+    position: number;
+    label: string;
+}
+interface Scale {
+    map(value: number | string | Date): number;
+    invert(pixel: number): number;
+    ticks(count?: number): Tick[];
+    setDomain(min: number | string | Date, max: number | string | Date): void;
+    setRange(min: number, max: number): void;
+    getDomain(): [number | string | Date, number | string | Date];
+    getRange(): [number, number];
+    /** Band width for categorical scales. Returns 0 for continuous scales. */
+    bandwidth?(): number;
+}
+type ScaleType = 'linear' | 'categorical' | 'time' | 'log';
+type ScaleFactory = (config?: {
+    domain?: [number | string | Date, number | string | Date];
+    range?: [number, number];
+    nice?: boolean;
+    clamp?: boolean;
+    format?: (value: number | string | Date) => string;
+}) => Scale;
+interface RenderAttrs {
+    class?: string;
+    style?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    strokeDasharray?: string;
+    strokeOpacity?: number;
+    strokeLinecap?: 'butt' | 'round' | 'square';
+    strokeLinejoin?: 'miter' | 'round' | 'bevel';
+    fill?: string;
+    fillOpacity?: number;
+    opacity?: number;
+    transform?: string;
+    clipPath?: string;
+    filter?: string;
+    cursor?: string;
+    pointerEvents?: string;
+    role?: string;
+    ariaLabel?: string;
+    tabindex?: number;
+    [key: `data-${string}`]: string | number | undefined;
+}
+type RenderNode = {
+    type: 'group';
+    children: RenderNode[];
+    attrs?: RenderAttrs;
+} | {
+    type: 'path';
+    d: string;
+    attrs?: RenderAttrs;
+} | {
+    type: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx?: number;
+    ry?: number;
+    attrs?: RenderAttrs;
+} | {
+    type: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+    attrs?: RenderAttrs;
+} | {
+    type: 'line';
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    attrs?: RenderAttrs;
+} | {
+    type: 'text';
+    x: number;
+    y: number;
+    content: string;
+    attrs?: RenderAttrs & {
+        textAnchor?: 'start' | 'middle' | 'end';
+        dominantBaseline?: 'auto' | 'middle' | 'hanging' | 'central';
+        fontSize?: number;
+        fontFamily?: string;
+        fontWeight?: string | number;
+    };
+} | {
+    type: 'clipPath';
+    id: string;
+    children: RenderNode[];
+} | {
+    type: 'defs';
+    children: RenderNode[];
+};
+interface RendererRoot {
+    element: SVGElement | HTMLElement;
+}
+interface Renderer {
+    createRoot(target: HTMLElement, width: number, height: number, attrs?: RenderAttrs): RendererRoot;
+    render(root: RendererRoot, nodes: RenderNode[]): void;
+    update(root: RendererRoot, nodes: RenderNode[]): void;
+    clear(root: RendererRoot): void;
+    destroy(root: RendererRoot): void;
+}
+interface ChartArea {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface RenderContext {
+    data: PreparedData;
+    options: ResolvedOptions;
+    area: ChartArea;
+    xScale: Scale;
+    yScale: Scale;
+    theme: ThemeConfig;
+}
+interface ChartTypePlugin {
+    readonly type: string;
+    getScaleTypes(): {
+        x: ScaleType;
+        y: ScaleType;
+    };
+    prepareData(data: ChartData, options: ResolvedOptions): PreparedData;
+    render(ctx: RenderContext): RenderNode[];
+    hitTest(ctx: RenderContext, x: number, y: number): HitResult | null;
+}
+interface HitResult {
+    seriesIndex: number;
+    pointIndex: number;
+    distance: number;
+}
+interface ChartInstance {
+    setData(data: ChartData): void;
+    setOptions(options: Partial<ChartOptions>): void;
+    getData(): ChartData;
+    getOptions(): ResolvedOptions;
+    setLoading(loading?: boolean): void;
+    setError(message?: string): void;
+    setEmpty(message?: string): void;
+    toSVG(): string;
+    toPNG(options?: {
+        scale?: number;
+    }): Promise<Blob>;
+    toClipboard(): Promise<void>;
+    on(event: string, handler: (...args: unknown[]) => void): () => void;
+    resize(width: number, height: number): void;
+    /** Reset zoom/pan to initial state. */
+    resetZoom(): void;
+    destroy(): void;
+    readonly element: SVGElement | HTMLCanvasElement;
+    /** Event bus — used by linkCharts() and advanced consumers. */
+    readonly _bus: EventBus;
+}
+interface ChartEvents {
+    'data:change': {
+        previous: ChartData;
+        current: ChartData;
+    };
+    'resize': {
+        width: number;
+        height: number;
+    };
+    'theme:change': {
+        theme: string;
+    };
+    'point:enter': {
+        point: DataPoint;
+        event: MouseEvent;
+    };
+    'point:leave': {
+        event: MouseEvent;
+    };
+    'point:click': {
+        point: DataPoint;
+        event: MouseEvent;
+    };
+    'tooltip:show': {
+        point: DataPoint;
+        x: number;
+        y: number;
+    };
+    'tooltip:hide': void;
+    'crosshair:move': {
+        x: number;
+        label: string | number | Date;
+    };
+    'crosshair:hide': void;
+    'zoom:change': {
+        zoomX: number;
+        zoomY: number;
+        panX: number;
+        panY: number;
+    };
+    'zoom:reset': void;
+    'brush:end': {
+        startIndex: number;
+        endIndex: number;
+        startLabel: string | number | Date;
+        endLabel: string | number | Date;
+    };
+    'destroy': void;
+}
+type EventHandler<T> = (payload: T) => void;
+type Unsubscribe = () => void;
+interface EventBus {
+    on<K extends keyof ChartEvents>(event: K, handler: EventHandler<ChartEvents[K]>): Unsubscribe;
+    emit<K extends keyof ChartEvents>(event: K, payload: ChartEvents[K]): void;
+    off<K extends keyof ChartEvents>(event: K, handler: EventHandler<ChartEvents[K]>): void;
+    destroy(): void;
+}
+
+/** Extended options for createChart (includes debug flag) */
+interface CreateChartOptions extends ChartOptions {
+    debug?: boolean;
+}
+/**
+ * Create a chart instance.
+ * This is the core factory — all convenience functions (Line, Bar) call this.
+ */
+declare function createChart(target: string | HTMLElement, chartType: ChartTypePlugin, data: ChartData, options?: CreateChartOptions): ChartInstance;
+
+/**
+ * Render a chart to an SVG string. No DOM required — works in Node.js / SSR.
+ *
+ * @example
+ * ```ts
+ * import { renderToString, lineChartType } from '@chartts/core'
+ *
+ * const svg = renderToString(lineChartType, {
+ *   labels: ['Jan', 'Feb', 'Mar'],
+ *   series: [{ name: 'Sales', values: [10, 20, 15] }],
+ * }, { width: 600, height: 400 })
+ *
+ * // svg is a full <svg>...</svg> string
+ * ```
+ */
+declare function renderToString(chartType: ChartTypePlugin, data: ChartData, options?: ChartOptions & {
+    width?: number;
+    height?: number;
+}): string;
+
+declare function resolveTheme(theme: string | ThemeConfig): ThemeConfig;
+/**
+ * Apply theme as CSS custom properties on a DOM element.
+ * Every token becomes --chartts-* so users can override via CSS or Tailwind.
+ */
+declare function applyTheme(el: HTMLElement | SVGElement, theme: ThemeConfig): void;
+
+export { type ChartInstance as C, type DataBounds as D, type EventBus as E, type HitResult as H, type LegendPosition as L, type PreparedData as P, type RenderContext as R, type Series as S, type ThemeConfig as T, type Unsubscribe as U, type ChartData as a, type ChartOptions as b, type ChartTypePlugin as c, type RenderNode as d, applyTheme as e, createChart as f, resolveTheme as g, type ScaleType as h, type Renderer as i, type ChartArea as j, type Scale as k, type RenderAttrs as l, type ScaleFactory as m, type ChartEvents as n, type CrosshairConfig as o, type CurveType as p, type DataPoint as q, renderToString as r, type EventHandler as s, type PreparedSeries as t, type RendererRoot as u, type ResolvedOptions as v, type Tick as w, type TooltipConfig as x };