velo-plot 1.11.1

package/dist/plugins/tools/delta-tool/index.d.ts

@@ -0,0 +1,159 @@
+import { DeltaMeasurement, Bounds } from '../../../types';
+import { AnimationEngine } from '../../../core/animation';
+
+export interface DeltaToolOptions {
+    /** Line color for measurement (default: '#ff6b6b') */
+    lineColor?: string;
+    /** Line width in pixels (default: 2) */
+    lineWidth?: number;
+    /** Show labels at measurement points (default: true) */
+    showLabels?: boolean;
+    /** Label font size (default: 12) */
+    labelFontSize?: number;
+    /** Label background color (default: 'rgba(0,0,0,0.8)') */
+    labelBackground?: string;
+    /** Label text color (default: '#ffffff') */
+    labelColor?: string;
+    /** Show delta values inline (default: true) */
+    showDelta?: boolean;
+    /** Number precision for values (default: 4) */
+    precision?: number;
+    /** Show slope value (default: true) */
+    showSlope?: boolean;
+    /** Show distance value (default: true) */
+    showDistance?: boolean;
+    /** Custom CSS class for overlay elements */
+    className?: string;
+    /** Point highlight size when hovering (default: 10) */
+    highlightSize?: number;
+    /** Point highlight color (default: '#00f2ff') */
+    highlightColor?: string;
+    /** Snap radius in pixels for detecting nearby points (default: 20) */
+    snapRadius?: number;
+}
+/** Data point with series information */
+export interface DataPoint {
+    x: number;
+    y: number;
+    seriesId: string;
+    yAxisId?: string;
+    index: number;
+    pixelX: number;
+    pixelY: number;
+}
+export interface DeltaToolState {
+    /** Whether the tool is enabled */
+    enabled: boolean;
+    /** Selection state: 'idle' | 'waitingSecond' | 'complete' */
+    selectionState: 'idle' | 'waitingSecond' | 'complete';
+    /** First selected point */
+    point1: DataPoint | null;
+    /** Second selected point */
+    point2: DataPoint | null;
+    /** Currently hovered point (for highlighting) */
+    hoveredPoint: DataPoint | null;
+    /** Last completed measurement */
+    lastMeasurement: DeltaMeasurement | null;
+}
+export interface SeriesData {
+    id: string;
+    x: Float32Array | Float64Array | number[];
+    y: Float32Array | Float64Array | number[];
+    yAxisId?: string;
+}
+export interface DeltaToolContext {
+    container: HTMLElement;
+    getPlotArea: () => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    getViewBounds: () => Bounds;
+    getYBounds?: (yAxisId?: string) => {
+        yMin: number;
+        yMax: number;
+    };
+    requestRender: () => void;
+    getSeries?: () => SeriesData[];
+    onMeasure?: (measurement: DeltaMeasurement) => void;
+    animationEngine?: AnimationEngine;
+}
+export declare class DeltaTool {
+    private ctx;
+    private options;
+    private state;
+    private overlayCanvas;
+    private overlayCtx;
+    private labelOffset;
+    private isDraggingLabel;
+    private labelBounds;
+    private dragStart;
+    private crosshairPosition;
+    private boundMouseMove;
+    private boundClick;
+    private boundKeyDown;
+    private boundMouseDown;
+    private boundMouseUp;
+    private boundResize;
+    constructor(context: DeltaToolContext, options?: DeltaToolOptions);
+    /**
+     * Enable the delta measurement tool
+     */
+    enable(): void;
+    /**
+     * Disable the delta measurement tool
+     */
+    disable(): void;
+    /**
+     * Toggle the tool on/off
+     */
+    toggle(): void;
+    /**
+     * Check if tool is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the current state
+     */
+    getState(): DeltaToolState;
+    /**
+     * Get the last completed measurement
+     */
+    getMeasurement(): DeltaMeasurement | null;
+    /**
+     * Clear the current measurement
+     */
+    clear(): void;
+    /**
+     * Destroy the tool and cleanup
+     */
+    destroy(): void;
+    /**
+     * Recalculate measurements (useful if data changes)
+     */
+    recalculate(): void;
+    private createOverlay;
+    private resizeOverlay;
+    private destroyOverlay;
+    private attachListeners;
+    private detachListeners;
+    private handleMouseMove;
+    private handleLabelMouseDown;
+    private handleLabelMouseUp;
+    private handleClick;
+    private handleKeyDown;
+    private findNearestPoint;
+    private calculateMeasurement;
+    renderOverlay(): void;
+    private drawPointTooltip;
+    private drawPointLabel;
+    private drawMeasurementLabel;
+    private drawStatusIndicator;
+    private roundRect;
+    private formatValue;
+}
+/**
+ * Create a delta tool for a chart context
+ */
+export declare function createDeltaTool(context: DeltaToolContext, options?: DeltaToolOptions): DeltaTool;

package/dist/plugins/tools/index.d.ts

@@ -0,0 +1,21 @@
+import { DeltaTool } from './delta-tool';
+import { PeakTool } from './peak-tool';
+import { TooltipManager } from './tooltip';
+import { ChartPlugin } from '../types';
+
+export interface PluginToolsConfig {
+    /** Enable Delta measurement tool */
+    enableDeltaTool?: boolean;
+    /** Enable Peak detection tool */
+    enablePeakTool?: boolean;
+    /** Use advanced tooltip manager */
+    useEnhancedTooltips?: boolean;
+}
+/**
+ * SciPlot Tools Plugin
+ *
+ * Adds specialized tools for scientific data analysis and interaction.
+ */
+export declare function PluginTools(_config?: PluginToolsConfig): ChartPlugin<PluginToolsConfig>;
+export { DeltaTool, PeakTool, TooltipManager };
+export default PluginTools;

package/dist/plugins/tools/peak-tool/index.d.ts

@@ -0,0 +1,159 @@
+import { PeakMeasurement, Bounds } from '../../../types';
+import { AnimationEngine } from '../../../core/animation';
+
+export interface PeakToolOptions {
+    /** Line color for measurement (default: '#ff6b6b') */
+    lineColor?: string;
+    /** Line width in pixels (default: 2) */
+    lineWidth?: number;
+    /** Show labels at measurement points (default: true) */
+    showLabels?: boolean;
+    /** Label font size (default: 12) */
+    labelFontSize?: number;
+    /** Label background color (default: 'rgba(0,0,0,0.8)') */
+    labelBackground?: string;
+    /** Label text color (default: '#ffffff') */
+    labelColor?: string;
+    /** Show peak values inline (default: true) */
+    showPeak?: boolean;
+    /** Number precision for values (default: 4) */
+    precision?: number;
+    /** Custom CSS class for overlay elements */
+    className?: string;
+    /** Number of points to use for baseline regression (default: 10) */
+    baselineWindow?: number;
+    /** Area fill color (default: 'rgba(255, 107, 107, 0.3)') */
+    areaFill?: string;
+    /** Point highlight size when hovering (default: 10) */
+    highlightSize?: number;
+    /** Point highlight color (default: '#00f2ff') */
+    highlightColor?: string;
+    /** Snap radius in pixels for detecting nearby points (default: 20) */
+    snapRadius?: number;
+}
+/** Data point with series information */
+export interface DataPoint {
+    x: number;
+    y: number;
+    seriesId: string;
+    yAxisId?: string;
+    index: number;
+    pixelX: number;
+    pixelY: number;
+}
+export interface PeakToolState {
+    /** Whether the tool is enabled */
+    enabled: boolean;
+    /** Selection state: 'idle' | 'waitingSecond' | 'complete' */
+    selectionState: 'idle' | 'waitingSecond' | 'complete';
+    /** First selected point */
+    point1: DataPoint | null;
+    /** Second selected point */
+    point2: DataPoint | null;
+    /** Currently hovered point (for highlighting) */
+    hoveredPoint: DataPoint | null;
+    /** Last completed measurement */
+    lastMeasurement: PeakMeasurement | null;
+}
+export interface SeriesData {
+    id: string;
+    x: Float32Array | Float64Array | number[];
+    y: Float32Array | Float64Array | number[];
+    yAxisId?: string;
+}
+export interface PeakToolContext {
+    container: HTMLElement;
+    getPlotArea: () => {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    getViewBounds: () => Bounds;
+    getYBounds?: (yAxisId?: string) => {
+        yMin: number;
+        yMax: number;
+    };
+    requestRender: () => void;
+    getSeries?: () => SeriesData[];
+    onMeasure?: (measurement: PeakMeasurement) => void;
+    animationEngine?: AnimationEngine;
+}
+export declare class PeakTool {
+    private ctx;
+    private options;
+    private state;
+    private overlayCanvas;
+    private overlayCtx;
+    private labelOffset;
+    private isDraggingLabel;
+    private labelBounds;
+    private dragStart;
+    private crosshairPosition;
+    private boundMouseMove;
+    private boundClick;
+    private boundKeyDown;
+    private boundMouseDown;
+    private boundMouseUp;
+    private boundResize;
+    constructor(context: PeakToolContext, options?: PeakToolOptions);
+    /**
+     * Enable the peak measurement tool
+     */
+    enable(): void;
+    /**
+     * Disable the peak measurement tool
+     */
+    disable(): void;
+    /**
+     * Toggle the tool on/off
+     */
+    toggle(): void;
+    /**
+     * Check if tool is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Get the current state
+     */
+    getState(): PeakToolState;
+    /**
+     * Get the last completed measurement
+     */
+    getMeasurement(): PeakMeasurement | null;
+    /**
+     * Clear the current measurement
+     */
+    clear(): void;
+    /**
+     * Destroy the tool and cleanup
+     */
+    destroy(): void;
+    /**
+     * Recalculate measurements (useful if data changes)
+     */
+    recalculate(): void;
+    private createOverlay;
+    private resizeOverlay;
+    private destroyOverlay;
+    private attachListeners;
+    private detachListeners;
+    private handleMouseMove;
+    private handleLabelMouseDown;
+    private handleLabelMouseUp;
+    private handleClick;
+    private handleKeyDown;
+    private findNearestPoint;
+    private calculateMeasurement;
+    renderOverlay(): void;
+    private drawPointTooltip;
+    private drawPointLabel;
+    private drawMeasurementLabel;
+    private drawStatusIndicator;
+    private roundRect;
+    private formatValue;
+}
+/**
+ * Create a peak tool for a chart context
+ */
+export declare function createPeakTool(context: PeakToolContext, options?: PeakToolOptions): PeakTool;

package/dist/plugins/tools/tooltip/TooltipManager.d.ts

@@ -0,0 +1,213 @@
+import { PlotArea, Bounds } from '../../../types';
+import { Scale } from '../../../scales';
+import { Series } from '../../../core/Series';
+import { TooltipData, TooltipOptions, TooltipTheme, TooltipTemplate, ShowTooltipOptions, TooltipEventMap } from './types';
+import { ChartTheme } from '../../../theme';
+
+export interface TooltipManagerConfig {
+    /** Canvas 2D context for rendering */
+    overlayCtx: CanvasRenderingContext2D;
+    /** Chart theme (for auto-selecting tooltip theme) */
+    chartTheme: ChartTheme;
+    /** Function to get current plot area */
+    getPlotArea: () => PlotArea;
+    /** Function to get all series */
+    getSeries: () => Series[];
+    /** Function to convert pixel X to data X */
+    pixelToDataX: (px: number) => number;
+    /** Function to convert pixel Y to data Y */
+    pixelToDataY: (py: number) => number;
+    /** Function to get X scale */
+    getXScale: () => Scale;
+    /** Function to get Y scales */
+    getYScales: () => Map<string, Scale>;
+    /** Function to get view bounds */
+    getViewBounds: () => Bounds;
+    /** Initial options */
+    options?: TooltipOptions;
+}
+export declare class TooltipManager {
+    private ctx;
+    private getPlotArea;
+    private getSeries;
+    private pixelToDataX;
+    private pixelToDataY;
+    private getXScale;
+    private getYScales;
+    private options;
+    private theme;
+    private positioner;
+    private renderer;
+    private templates;
+    private events;
+    private activeTooltips;
+    private tooltipIdCounter;
+    private showTimeoutId;
+    private hideTimeoutId;
+    private lastCursorX;
+    private lastCursorY;
+    private hoveredSeriesId;
+    private hoveredDataIndex;
+    private cachedNearestResult;
+    private snapMode;
+    private largeDatasetThreshold;
+    private lastKnownDataSize;
+    private hysteresisRatio;
+    private suspended;
+    constructor(config: TooltipManagerConfig);
+    /**
+     * Register built-in templates
+     */
+    private registerBuiltinTemplates;
+    /**
+     * Configure tooltip options
+     */
+    configure(options: TooltipOptions): void;
+    /**
+     * Get current options
+     */
+    getOptions(): TooltipOptions;
+    /**
+     * Enable/disable tooltips
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if tooltips are enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Suspend tooltip display (used during drag operations)
+     * When suspended, tooltips are immediately hidden and cursor movements are ignored
+     */
+    setSuspended(suspended: boolean): void;
+    /**
+     * Check if tooltips are suspended
+     */
+    isSuspended(): boolean;
+    /**
+     * Set tooltip theme
+     */
+    setTheme(theme: TooltipTheme | string): void;
+    /**
+     * Update theme based on chart theme
+     */
+    updateChartTheme(chartTheme: ChartTheme): void;
+    /**
+     * Get current theme
+     */
+    getTheme(): TooltipTheme;
+    /**
+     * Register a custom template
+     */
+    registerTemplate<T extends TooltipData>(template: TooltipTemplate<T>): void;
+    /**
+     * Get a template by ID
+     */
+    getTemplate(id: string): TooltipTemplate<TooltipData> | undefined;
+    /**
+     * Handle cursor movement - main entry point for hover detection
+     * Optimized with hysteresis to prevent jumping between nearby points
+     */
+    handleCursorMove(pixelX: number, pixelY: number): void;
+    /**
+     * Handle cursor leave
+     */
+    handleCursorLeave(): void;
+    /**
+     * Get total number of data points across all visible series
+     */
+    private getTotalDataPoints;
+    /**
+     * Determine the effective snap mode based on configuration and data size
+     */
+    private getEffectiveSnapMode;
+    /**
+     * Perform tooltip update with hysteresis to prevent jumping.
+     * The tooltip "sticks" to the current point unless the cursor is
+     * significantly closer to a new point.
+     */
+    private performTooltipUpdateWithHysteresis;
+    /**
+     * Handle heatmap and crosshair tooltip types (fallback)
+     */
+    private performFallbackTooltipUpdate;
+    /**
+     * Find data point by X coordinate only (O(log n) - fastest method)
+     * Best for very large datasets where precision is less important than speed
+     */
+    private findDataPointByXOnly;
+    /**
+     * Optimized nearest data point finder
+     */
+    private findNearestDataPointOptimized;
+    /**
+     * Find heatmap cell under cursor
+     */
+    private findHeatmapCell;
+    /**
+     * Binary search for closest value
+     */
+    private binarySearchClosest;
+    /**
+     * Build crosshair tooltip data
+     */
+    private buildCrosshairTooltip;
+    /**
+     * Schedule showing a tooltip
+     */
+    private scheduleShow;
+    /**
+     * Schedule hiding tooltips
+     */
+    private scheduleHide;
+    private clearShowTimeout;
+    private clearHideTimeout;
+    /**
+     * Show a tooltip with the given data
+     */
+    private showTooltip;
+    /**
+     * Update tooltip position
+     */
+    private updateTooltipPosition;
+    /**
+     * Get template ID for a tooltip type
+     */
+    private getTemplateIdForType;
+    /**
+     * Show a tooltip programmatically
+     */
+    show(data: TooltipData, options?: ShowTooltipOptions): string;
+    /**
+     * Hide a specific tooltip
+     */
+    hide(tooltipId: string): void;
+    /**
+     * Hide all tooltips immediately
+     */
+    hideAll(): void;
+    /**
+     * Render all active tooltips
+     */
+    render(): void;
+    /**
+     * Check if any tooltip is currently visible
+     */
+    hasActiveTooltip(): boolean;
+    /**
+     * Subscribe to tooltip events
+     */
+    on<K extends keyof TooltipEventMap>(event: K, handler: (data: TooltipEventMap[K]) => void): void;
+    /**
+     * Unsubscribe from tooltip events
+     */
+    off<K extends keyof TooltipEventMap>(event: K, handler: (data: TooltipEventMap[K]) => void): void;
+    /**
+     * Destroy the tooltip manager
+     */
+    destroy(): void;
+}
+/**
+ * Create a tooltip manager
+ */
+export declare function createTooltipManager(config: TooltipManagerConfig): TooltipManager;

package/dist/plugins/tools/tooltip/TooltipPositioner.d.ts

@@ -0,0 +1,83 @@
+import { PlotArea } from '../../../types';
+import { TooltipPosition, TooltipMeasurement, TooltipPlacement } from './types';
+
+export interface PositionerConfig {
+    /** Offset from target point */
+    offset: {
+        x: number;
+        y: number;
+    };
+    /** Preferred placement */
+    preferredPosition: TooltipPlacement;
+    /** Keep within plot area */
+    constrainToPlotArea: boolean;
+    /** Keep within container */
+    constrainToContainer: boolean;
+    /** Flip if not enough space */
+    autoFlip: boolean;
+    /** Show arrow pointing to target */
+    showArrow: boolean;
+    /** Arrow size */
+    arrowSize: number;
+}
+export declare const DEFAULT_POSITIONER_CONFIG: PositionerConfig;
+/**
+ * TooltipPositioner calculates optimal tooltip positions
+ */
+export declare class TooltipPositioner {
+    private config;
+    private containerWidth;
+    private containerHeight;
+    private plotArea;
+    constructor(config?: Partial<PositionerConfig>);
+    /**
+     * Update container dimensions
+     */
+    setContainerSize(width: number, height: number): void;
+    /**
+     * Update plot area bounds
+     */
+    setPlotArea(plotArea: PlotArea): void;
+    /**
+     * Update configuration
+     */
+    configure(config: Partial<PositionerConfig>): void;
+    /**
+     * Calculate optimal tooltip position
+     *
+     * @param targetX - Target X coordinate (where tooltip points to)
+     * @param targetY - Target Y coordinate
+     * @param measurement - Tooltip dimensions
+     * @returns Calculated position with arrow configuration
+     */
+    calculatePosition(targetX: number, targetY: number, measurement: TooltipMeasurement): TooltipPosition;
+    /**
+     * Determine best position based on available space
+     */
+    private determinePosition;
+    /**
+     * Calculate tooltip coordinates for a given position
+     */
+    private calculateCoordinates;
+    /**
+     * Get the opposite position for flipping
+     */
+    private flipPosition;
+    /**
+     * Check if tooltip fits within bounds
+     */
+    private fitsInBounds;
+    /**
+     * Constrain position to stay within bounds
+     */
+    private constrainToBounds;
+    /**
+     * Get the bounds to constrain tooltip within
+     */
+    private getConstraintBounds;
+    /**
+     * Calculate position for crosshair tooltip (follows cursor vertically)
+     */
+    calculateCrosshairPosition(cursorX: number, cursorY: number, measurement: TooltipMeasurement): TooltipPosition;
+}
+export declare function createTooltipPositioner(config?: Partial<PositionerConfig>): TooltipPositioner;

package/dist/plugins/tools/tooltip/TooltipRenderer.d.ts

@@ -0,0 +1,64 @@
+import { TooltipData, TooltipPosition, TooltipTheme, TooltipTemplate } from './types';
+
+/**
+ * TooltipRenderer handles all Canvas 2D rendering for tooltips
+ */
+export declare class TooltipRenderer {
+    private ctx;
+    private theme;
+    constructor(ctx: CanvasRenderingContext2D, theme: TooltipTheme);
+    /**
+     * Update the theme
+     */
+    setTheme(theme: TooltipTheme): void;
+    /**
+     * Render a tooltip with the given template
+     */
+    render<T extends TooltipData>(data: T, position: TooltipPosition, template: TooltipTemplate<T>): void;
+    /**
+     * Draw tooltip background with all effects
+     */
+    private drawBackground;
+    /**
+     * Draw arrow pointing to target
+     */
+    private drawArrow;
+    /**
+     * Draw a rounded rectangle path
+     */
+    private roundRect;
+    /**
+     * Draw a horizontal separator line
+     */
+    drawSeparator(x: number, y: number, width: number): void;
+    /**
+     * Draw a series color indicator (small circle or square)
+     */
+    drawSeriesIndicator(x: number, y: number, color: string): void;
+    /**
+     * Measure text width
+     */
+    measureText(text: string, fontSize: number, fontWeight?: number | string): number;
+    /**
+     * Draw text with theme styling
+     */
+    drawText(text: string, x: number, y: number, options?: {
+        fontSize?: number;
+        fontWeight?: number | string;
+        color?: string;
+        align?: CanvasTextAlign;
+        baseline?: CanvasTextBaseline;
+    }): void;
+    /**
+     * Draw a label-value pair
+     */
+    drawLabelValue(x: number, y: number, label: string, value: string, maxWidth: number): void;
+    /**
+     * Get theme for external use
+     */
+    getTheme(): TooltipTheme;
+}
+/**
+ * Create a tooltip renderer
+ */
+export declare function createTooltipRenderer(ctx: CanvasRenderingContext2D, theme: TooltipTheme): TooltipRenderer;