scichart-engine 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 jigonzalez930209
+
+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/README.md

@@ -0,0 +1,81 @@
+# SciChart Engine 🚀
+
+A high-performance, WebGL-powered scientific charting engine built for precision, speed, and deep interactivity. Optimized for electrochemical and scientific data visualization.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NPM Version](https://img.shields.io/npm/v/scichart-engine.svg)](https://www.npmjs.com/package/scichart-engine)
+
+## ✨ Features
+
+-   **🚀 High Performance**: Render millions of data points at 60 FPS using a specialized raw WebGL renderer.
+-   **📈 Advanced Analysis**: Built-in peak detection, integration, baseline correction, and customizable curve fitting (linear/poly/exp).
+-   **📊 Specialized Series**: Support for Lines, Scatter (SDF symbols), Step charts, Band series, Area charts, **Candlesticks** (OHLC), and **Stacked Charts**.
+-   **↕️ Multi-Axis Engine**: Independent scales and units with axis-specific scrolling and zooming.
+-   **📏 Professional Tooling**: Real-time Statistics panel, Annotations (Lines/Shapes/Text), and **high-fidelity SVG/PNG export**.
+-   **🔌 Extensible**: **Plugin System** with lifecycle hooks for custom drawing and data analysis.
+-   **⚛️ Framework First**: Native React support via hooks and high-level components.
+-   **🎨 Dynamic Theming**: Sleek built-in themes (Light/Midnight) with support for custom CSS-based skins.
+-   **🏗️ Modular Core**: Built on a modern, decoupled architecture for maximum extendability.
+
+## 🛠️ Installation
+
+```bash
+npm install scichart-engine
+# or
+pnpm add scichart-engine
+```
+
+## 🚀 Quick Examples
+
+### React (Recommended)
+
+```tsx
+import { SciChart } from 'scichart-engine/react';
+
+function App() {
+  const data = {
+    x: new Float32Array([0, 1, 2, 3]),
+    y: new Float32Array([10, 20, 15, 25])
+  };
+
+  return (
+    <div style={{ width: '800px', height: '400px' }}>
+      <SciChart 
+        series={[{ id: 's1', ...data, color: '#00f2ff' }]}
+        xAxis={{ label: 'Time (s)' }}
+        yAxis={{ label: 'Voltage (V)' }}
+        showControls
+      />
+    </div>
+  );
+}
+```
+
+### Vanilla JavaScript
+
+```typescript
+import { createChart } from 'scichart-engine';
+
+const chart = createChart({
+  container: document.getElementById('chart-container'),
+  title: 'Real-time Signal'
+});
+
+chart.addSeries({
+  id: 'signal',
+  type: 'line',
+  data: { x: [...], y: [...] }
+});
+```
+
+## 📖 Documentation
+
+Visit [SciChart Engine Docs](https://jigonzalez930209.github.io/scichart-engine/) for:
+-   [Getting Started Guide](https://jigonzalez930209.github.io/scichart-engine/guide/)
+-   [Core Concepts](https://jigonzalez930209.github.io/scichart-engine/guide/concepts)
+-   [API Reference](https://jigonzalez930209.github.io/scichart-engine/api/chart)
+-   [Interactive Examples](https://jigonzalez930209.github.io/scichart-engine/examples/)
+
+## 📄 License
+
+MIT © [jigonzalez930209](https://github.com/jigonzalez930209)

package/dist/analysis/contours.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Contour Plot Generation (Marching Squares)
+ */
+export interface ContourPoint {
+    x: number;
+    y: number;
+}
+export interface ContourLine {
+    level: number;
+    points: ContourPoint[];
+}
+export interface ContourOptions {
+    levels?: number[];
+    numLevels?: number;
+}
+/**
+ * Generate contour lines from a 2D grid of values
+ * Values are assumed to be in row-major order: z = values[y * width + x]
+ */
+export declare function generateContours(z: Float32Array | number[], xValues: Float32Array | number[], yValues: Float32Array | number[], options?: ContourOptions): ContourLine[];

package/dist/analysis/fitting.d.ts

@@ -0,0 +1,24 @@
+export type FitType = 'linear' | 'polynomial' | 'exponential' | 'logarithmic' | 'power';
+export interface FitOptions {
+    /** Degree for polynomial fit (default: 2) */
+    degree?: number;
+    /** Custom label for the equation */
+    label?: string;
+    /** Number of decimals in equation string */
+    precision?: number;
+}
+export interface FitResult {
+    type: FitType;
+    /** Coefficients (a, b, c...) */
+    coefficients: number[];
+    /** Formatted equation string */
+    equation: string;
+    /** Coefficient of determination */
+    rSquared: number;
+    /** Function to calculate value at X */
+    predict: (x: number) => number;
+}
+/**
+ * Perform regression on a dataset
+ */
+export declare function fitData(x: number[] | Float32Array, y: number[] | Float32Array, type: FitType, options?: FitOptions): FitResult;

package/dist/analysis/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Data Analysis module exports
+ *
+ * General-purpose utilities for data formatting, cycle detection,
+ * peak detection, and data validation.
+ */
+export { formatWithPrefix, formatValue, formatScientific, getBestPrefix, detectCycles, generateCycleColors, detectPeaks, validateData, calculateStats, movingAverage, downsampleLTTB, subtractBaseline, } from './utils';
+export { solveLinearSystem, calculateR2, integrate, derivative, cumulativeIntegral, } from './math';
+export { fitData, } from './fitting';
+export type { CycleInfo, Peak, PrefixInfo, ValidationResult, DataStats, } from './utils';
+export type { FitType, FitOptions, FitResult, } from './fitting';
+export * from './contours';

package/dist/analysis/math.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Mathematical utilities for numerical analysis and regression.
+ */
+/**
+ * Solve a system of linear equations Ax = B using Gaussian elimination with partial pivoting.
+ *
+ * @param A - Matrix coefficients
+ * @param B - Right hand side vector
+ * @returns Solution vector x
+ */
+export declare function solveLinearSystem(A: number[][], B: number[]): number[];
+/**
+ * Calculate R² (coefficient of determination)
+ */
+export declare function calculateR2(x: number[] | Float32Array, y: number[] | Float32Array, fitFn: (x: number) => number): number;
+/**
+ * Numerical integration using the trapezoidal rule.
+ *
+ * @param x - X values (must be sorted)
+ * @param y - Y values
+ * @param xMin - Optional start of integration range
+ * @param xMax - Optional end of integration range
+ */
+export declare function integrate(x: number[] | Float32Array, y: number[] | Float32Array, xMin?: number, xMax?: number): number;
+/**
+ * Calculate numerical derivative dy/dx
+ */
+export declare function derivative(x: number[] | Float32Array, y: number[] | Float32Array): Float32Array;
+/**
+ * Calculate cumulative integral (area array)
+ */
+export declare function cumulativeIntegral(x: number[] | Float32Array, y: number[] | Float32Array): Float32Array;

package/dist/analysis/utils.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Data Analysis Utilities
+ *
+ * General-purpose utilities for scientific data formatting,
+ * cycle detection, peak detection, and data validation.
+ */
+type SIPrefix = 'p' | 'n' | 'µ' | 'm' | '' | 'k' | 'M' | 'G';
+export interface PrefixInfo {
+    symbol: SIPrefix;
+    factor: number;
+}
+/**
+ * Find the best SI prefix for a value
+ */
+export declare function getBestPrefix(value: number): PrefixInfo;
+/**
+ * Format a value with automatic SI prefix
+ *
+ * @example
+ * formatWithPrefix(0.000001, 'A') // "1.00 µA"
+ * formatWithPrefix(0.5, 'V')      // "500 mV"
+ * formatWithPrefix(1500, 'm')     // "1.50 km"
+ */
+export declare function formatWithPrefix(value: number, unit: string, decimals?: number): string;
+/**
+ * Format a numeric value with specified decimals
+ * Automatically switches to scientific notation for very large/small values
+ */
+export declare function formatValue(value: number, decimals?: number): string;
+/**
+ * Format value in scientific notation
+ */
+export declare function formatScientific(value: number, decimals?: number): string;
+export interface CycleInfo {
+    /** Cycle number (1-indexed) */
+    number: number;
+    /** Start index in data array */
+    startIndex: number;
+    /** End index in data array */
+    endIndex: number;
+    /** Direction at start: 1 = forward, -1 = reverse */
+    direction: 1 | -1;
+}
+/**
+ * Detect cycles in oscillating data
+ *
+ * A cycle is complete when the signal returns to its starting value
+ * after going through both sweep directions. Useful for:
+ * - Cyclic voltammetry data
+ * - Periodic signals
+ * - Oscillation analysis
+ *
+ * @param signal - The signal data (e.g., potential, position, etc.)
+ * @param tolerance - How close to starting value to consider a cycle complete
+ */
+export declare function detectCycles(signal: Float32Array | Float64Array | number[], tolerance?: number): CycleInfo[];
+/**
+ * Generate distinct colors for cycles/series
+ *
+ * Uses HSL color space to generate evenly distributed hues
+ */
+export declare function generateCycleColors(count: number): string[];
+export interface Peak {
+    /** Index in data array */
+    index: number;
+    /** X value at peak */
+    x: number;
+    /** Y value at peak */
+    y: number;
+    /** Peak type */
+    type: 'max' | 'min';
+    /** Prominence of the peak */
+    prominence: number;
+}
+/**
+ * Detect peaks (local maxima and minima) in data
+ *
+ * Uses simple local extrema detection with optional prominence filtering.
+ * Useful for:
+ * - Signal peak detection
+ * - Finding local maxima/minima
+ * - Feature extraction
+ *
+ * @param x - X values (independent variable)
+ * @param y - Y values (dependent variable)
+ * @param options - Detection options
+ */
+export declare function detectPeaks(x: Float32Array | Float64Array | number[], y: Float32Array | Float64Array | number[], options?: {
+    /** Minimum prominence to be considered a peak */
+    minProminence?: number;
+    /** Only return 'max' or 'min' peaks */
+    type?: 'max' | 'min' | 'both';
+}): Peak[];
+export interface ValidationResult {
+    /** Whether all data is valid */
+    valid: boolean;
+    /** Number of invalid values (NaN, Infinity, etc.) */
+    invalidCount: number;
+    /** Index of first invalid value (-1 if all valid) */
+    firstInvalidIndex: number;
+}
+/**
+ * Validate that data contains only finite numbers
+ *
+ * Checks for NaN, Infinity, and -Infinity values.
+ * Useful for data quality checks before rendering.
+ */
+export declare function validateData(data: Float32Array | Float64Array | number[]): ValidationResult;
+export interface DataStats {
+    min: number;
+    max: number;
+    mean: number;
+    stdDev: number;
+    count: number;
+}
+/**
+ * Calculate basic statistics for a dataset
+ */
+export declare function calculateStats(data: Float32Array | Float64Array | number[]): DataStats;
+/**
+ * Apply moving average smoothing to data
+ *
+ * @param data - Input data array
+ * @param windowSize - Number of points to average (must be odd)
+ */
+export declare function movingAverage(data: Float32Array | Float64Array | number[], windowSize: number): Float32Array;
+/**
+ * Downsample data using LTTB (Largest Triangle Three Buckets) algorithm
+ *
+ * Preserves visual characteristics while reducing point count.
+ * Ideal for rendering large datasets efficiently.
+ *
+ * @param x - X values
+ * @param y - Y values
+ * @param targetPoints - Desired number of output points
+ */
+export declare function downsampleLTTB(x: Float32Array | Float64Array, y: Float32Array | Float64Array, targetPoints: number): {
+    x: Float32Array;
+    y: Float32Array;
+};
+/**
+ * Subtract a linear baseline from data
+ *
+ * @param x - X data
+ * @param y - Y data
+ * @param x1 - Start of baseline segment
+ * @param x2 - End of baseline segment
+ */
+export declare function subtractBaseline(x: Float32Array | number[], y: Float32Array | number[], x1: number, x2: number): Float32Array;
+export {};

package/dist/core/Chart.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Chart - Main SciChart Engine Entry Point
+ *
+ * This file re-exports the chart API from the modular implementation.
+ * For the core implementation, see ./chart/ChartCore.ts
+ */
+export type { Chart, ExportOptions } from './chart/types';
+export { MARGINS } from './chart/types';
+export { createChart, ChartImpl } from './chart/ChartCore';
+export { exportToCSV, exportToJSON, exportToImage } from './chart/ChartExporter';
+export { applyZoom, applyPan } from './chart/ChartNavigation';
+export { autoScaleAll, handleBoxZoom } from './chart/ChartScaling';
+export type { NavigationContext } from './chart/ChartNavigation';
+export type { RenderContext } from './chart/ChartRenderer';
+export type { ChartOptions } from '../types';

package/dist/core/ChartControls.d.ts

@@ -0,0 +1,30 @@
+import { ChartTheme } from '../theme';
+
+export interface ChartControlsCallbacks {
+    onResetZoom: () => void;
+    onSetType: (type: "line" | "scatter" | "line+scatter") => void;
+    onToggleSmoothing: () => void;
+    onTogglePan: (active: boolean) => void;
+    onExport: () => void;
+    onAutoScale: () => void;
+    onToggleLegend: (visible: boolean) => void;
+}
+export declare class ChartControls {
+    private container;
+    private toolbar;
+    private callbacks;
+    private theme;
+    private isSmoothing;
+    private isPanMode;
+    private isLegendVisible;
+    private currentType;
+    constructor(parent: HTMLElement, theme: ChartTheme, callbacks: ChartControlsCallbacks);
+    private isDarkTheme;
+    private updateToolbarStyle;
+    private createButtons;
+    private enforceSVGVisibility;
+    private createButton;
+    private updateButtonStates;
+    updateTheme(theme: ChartTheme): void;
+    destroy(): void;
+}

package/dist/core/ChartLegend.d.ts

@@ -0,0 +1,35 @@
+import { ChartTheme } from '../theme';
+import { Series } from './Series';
+
+export interface ChartLegendCallbacks {
+    onMove: (x: number, y: number) => void;
+}
+export declare class ChartLegend {
+    private container;
+    private header;
+    private content;
+    private theme;
+    private series;
+    private callbacks;
+    private isDragging;
+    private startX;
+    private startY;
+    private initialX;
+    private initialY;
+    constructor(parent: HTMLElement, theme: ChartTheme, options: {
+        x?: number;
+        y?: number;
+    }, callbacks: ChartLegendCallbacks);
+    private updateStyle;
+    private initDragging;
+    update(series: Series[]): void;
+    private render;
+    /**
+     * Internal symbol drawing logic (shared with canvas export)
+     */
+    private drawSymbol;
+    draw(ctx: CanvasRenderingContext2D, dpr: number): void;
+    updateTheme(theme: ChartTheme): void;
+    setVisible(visible: boolean): void;
+    destroy(): void;
+}

package/dist/core/ChartStatistics.d.ts

@@ -0,0 +1,18 @@
+import { ChartTheme } from '../theme';
+import { Series } from './Series';
+import { Bounds } from '../types';
+
+export declare class ChartStatistics {
+    private container;
+    private content;
+    private theme;
+    private series;
+    private isExpanded;
+    constructor(parent: HTMLElement, theme: ChartTheme, series: Map<string, Series>);
+    private isDarkTheme;
+    private updateContainerStyle;
+    update(viewBounds: Bounds): void;
+    toggle(): void;
+    updateTheme(theme: ChartTheme): void;
+    destroy(): void;
+}

package/dist/core/EventEmitter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Type-safe event emitter for chart events
+ */
+export declare class EventEmitter<EventMap extends object> {
+    private listeners;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    /**
+     * Emit an event with data
+     */
+    emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void;
+    /**
+     * Subscribe to an event once
+     */
+    once<K extends keyof EventMap>(event: K, handler: (data: EventMap[K]) => void): void;
+    /**
+     * Remove all listeners
+     */
+    clear(): void;
+    /**
+     * Get listener count for an event
+     */
+    listenerCount(event: keyof EventMap): number;
+}

package/dist/core/InteractionManager.d.ts

@@ -0,0 +1,67 @@
+import { Bounds } from '../types';
+
+export interface AxisLayout {
+    id: string;
+    position: 'left' | 'right';
+    offset: number;
+}
+export interface InteractionCallbacks {
+    onZoom: (bounds: Bounds, axisId?: string) => void;
+    onPan: (deltaX: number, deltaY: number, axisId?: string) => void;
+    onBoxZoom: (rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null) => void;
+    onCursorMove: (x: number, y: number) => void;
+    onCursorLeave: () => void;
+}
+export interface PlotAreaGetter {
+    (): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface BoundsGetter {
+    (axisId?: string): Bounds;
+}
+export interface AxisLayoutGetter {
+    (): AxisLayout[];
+}
+export declare class InteractionManager {
+    private container;
+    private callbacks;
+    private getPlotArea;
+    private getBounds;
+    private getAxesLayout;
+    private isDragging;
+    private panningAxisId?;
+    private isBoxSelecting;
+    private selectionStart;
+    private lastMousePos;
+    private isPanMode;
+    private boundWheel;
+    private boundMouseDown;
+    private boundMouseMove;
+    private boundMouseUp;
+    private boundMouseLeave;
+    private boundTouchStart;
+    private boundTouchMove;
+    private boundTouchEnd;
+    constructor(container: HTMLElement, callbacks: InteractionCallbacks, getPlotArea: PlotAreaGetter, getBounds: BoundsGetter, getAxesLayout: AxisLayoutGetter);
+    private attachListeners;
+    private detachListeners;
+    setPanMode(enabled: boolean): void;
+    private handleWheel;
+    private handleMouseDown;
+    private handleMouseMove;
+    private handleMouseUp;
+    private handleMouseLeave;
+    private handleTouchStart;
+    private handleTouchMove;
+    private handleTouchEnd;
+    destroy(): void;
+}

package/dist/core/OverlayRenderer.d.ts

@@ -0,0 +1,67 @@
+import { Scale } from '../scales';
+import { ChartTheme } from '../theme';
+import { Series } from './Series';
+import { PlotArea, CursorState } from '../types';
+
+export declare class OverlayRenderer {
+    private ctx;
+    private theme;
+    constructor(ctx: CanvasRenderingContext2D, theme: ChartTheme);
+    /**
+     * Update the theme
+     */
+    setTheme(theme: ChartTheme): void;
+    /**
+     * Clear the overlay
+     */
+    clear(width: number, height: number): void;
+    /**
+     * Draw the grid
+     */
+    drawGrid(plotArea: PlotArea, xScale: Scale, yScale: Scale): void;
+    /**
+     * Draw X axis with ticks and labels
+     */
+    drawXAxis(plotArea: PlotArea, xScale: Scale, label?: string): void;
+    /**
+     * Draw Y axis with ticks and labels
+     */
+    drawYAxis(plotArea: PlotArea, yScale: Scale, label?: string, position?: "left" | "right", offset?: number): void;
+    /**
+     * Draw plot area border
+     */
+    drawPlotBorder(plotArea: PlotArea): void;
+    /**
+     * Draw legend
+     */
+    drawLegend(plotArea: PlotArea, series: Series[]): void;
+    /**
+     * Helper to draw a symbol in the legend
+     */
+    private drawLegendSymbol;
+    /**
+     * Draw cursor/crosshair
+     */
+    drawCursor(plotArea: PlotArea, cursor: CursorState): void;
+    /**
+     * Draw tooltip
+     */
+    private drawTooltip;
+    /**
+     * Draw selection rectangle (Box Zoom)
+     */
+    drawSelectionRect(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Draw error bars for a series
+     */
+    drawErrorBars(plotArea: PlotArea, series: Series, xScale: Scale, yScale: Scale): void;
+    private generateMinorTicks;
+    private formatXTick;
+    private formatYTick;
+    private toScientificUnicode;
+}

package/dist/core/Series.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Series Redirect
+ */
+export { Series } from './series/Series';

package/dist/core/annotations/AnnotationManager.d.ts

@@ -0,0 +1,57 @@
+import { Bounds } from '../../types';
+import { Annotation } from './types';
+
+export interface PlotArea {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare class AnnotationManager {
+    private annotations;
+    private idCounter;
+    /**
+     * Add a new annotation
+     * @returns The annotation ID
+     */
+    add(annotation: Annotation): string;
+    /**
+     * Remove an annotation by ID
+     */
+    remove(id: string): boolean;
+    /**
+     * Update an annotation
+     */
+    update(id: string, updates: Partial<Annotation>): void;
+    /**
+     * Get an annotation by ID
+     */
+    get(id: string): Annotation | undefined;
+    /**
+     * Get all annotations
+     */
+    getAll(): Annotation[];
+    /**
+     * Clear all annotations
+     */
+    clear(): void;
+    /**
+     * Get count of annotations
+     */
+    get count(): number;
+    /**
+     * Render all annotations
+     */
+    render(ctx: CanvasRenderingContext2D, plotArea: PlotArea, bounds: Bounds): void;
+    private renderAnnotation;
+    private dataToPixelX;
+    private dataToPixelY;
+    private renderHorizontalLine;
+    private renderVerticalLine;
+    private renderRectangle;
+    private renderBand;
+    private renderText;
+    private renderArrow;
+    private renderLineLabel;
+    private renderCenteredLabel;
+}

package/dist/core/annotations/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Annotations module exports
+ */
+export { AnnotationManager, type PlotArea } from './AnnotationManager';
+export type { Annotation, AnnotationType, BaseAnnotation, HorizontalLineAnnotation, VerticalLineAnnotation, RectangleAnnotation, BandAnnotation, TextAnnotation, ArrowAnnotation, AnnotationEvent, AnnotationDragEvent, } from './types';