@radishcandy/h-charts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,568 @@
+import { default as default_2 } from 'highcharts';
+import * as Highcharts_2 from 'highcharts';
+
+export declare class AnnotationPlugin extends BasePlugin {
+    name: string;
+    private cursorPoint;
+    private labelFormatter;
+    private markerRadius;
+    private markerColor;
+    private marks;
+    private seq;
+    private draggingId;
+    private dragStart;
+    private onMouseMoveBound;
+    private onMouseUpBound;
+    private unbindRedraw;
+    constructor(options?: AnnotationPluginOptions);
+    init(chart: IHChart): void;
+    onCursorChange(point: Point): void;
+    enable(): void;
+    disable(): void;
+    private bindEvents;
+    private unbindEvents;
+    update(options: AnnotationPluginOptions): void;
+    markCurrentPoint(): void;
+    markPoint(point: Point): void;
+    clearMark(): void;
+    getMarkedPoint(): Point | null;
+    getMarkedPoints(): Point[];
+    private render;
+    private clearAllMarks;
+    private getMarkerAnnotationId;
+    private renderMark;
+    private drawMarker;
+    private ensureLabel;
+    private ensureConnector;
+    private updateAllPositions;
+    private updateMarkPosition;
+    private updateConnectorPosition;
+    private onLabelMouseDown;
+    private onLabelMouseMove;
+    private onLabelMouseUp;
+    private stopDragging;
+    destroy(): void;
+}
+
+export declare interface AnnotationPluginOptions {
+    enabled?: boolean;
+    labelFormatter?: (x: number, y: number) => string;
+    markerRadius?: number;
+    markerColor?: string;
+}
+
+export declare type AxisInternals = Highcharts_2.Axis & {
+    tickInterval?: number;
+    dataMin?: number;
+    dataMax?: number;
+    plotLinesAndBands: AxisPlotLine[];
+};
+
+/**
+ * Highcharts v12 的公开类型未声明下列运行时实例成员，这里做最小扩展，
+ * 以便插件在不引入 `any` 的前提下访问轴与注解的内部状态。
+ */
+export declare type AxisPlotLine = Highcharts_2.PlotLineOrBand & {
+    id?: string;
+};
+
+export declare abstract class BasePlugin implements IPlugin {
+    abstract name: string;
+    protected chart: IHChart | null;
+    protected enabled: boolean;
+    protected options: any;
+    constructor(options?: any);
+    init(chart: IHChart): void;
+    destroy(): void;
+    enable(): void;
+    disable(): void;
+    isEnabled(): boolean;
+    update(options: any): void;
+}
+
+export declare type ChartInternals = Highcharts_2.Chart & {
+    annotations?: Array<{
+        group?: {
+            css(styles: Highcharts_2.CSSObject): void;
+        };
+        labels?: Array<{
+            graphic?: {
+                css(styles: Highcharts_2.CSSObject): void;
+            };
+        }>;
+        shapes?: Array<{
+            graphic?: {
+                css(styles: Highcharts_2.CSSObject): void;
+            };
+        }>;
+    }>;
+};
+
+export declare type ContextMenuBuiltinId = 'sideband' | 'threshold_line' | 'band_count' | 'export';
+
+export declare type ContextMenuEntry = ContextMenuItem | ContextMenuBuiltinId;
+
+export declare interface ContextMenuItem {
+    label?: string;
+    pluginName?: string;
+    action?: (chart: IHChart, item?: ContextMenuItem) => void;
+    type?: 'builtin' | 'custom';
+    id?: string;
+    items?: ContextMenuItem[];
+    value?: string | number;
+    inputType?: 'text' | 'number';
+    min?: number;
+    max?: number;
+    onInput?: (value: string, chart: IHChart) => void;
+    fileName?: string | ((chart: IHChart) => string);
+    exportBackgroundColor?: string;
+    exportOptions?: Record<string, unknown>;
+    exportChartOptions?: Record<string, unknown>;
+}
+
+/** A framework-independent, extensible context menu for an HChart instance. */
+export declare class ContextMenuPlugin extends BasePlugin {
+    name: string;
+    private static readonly activeInstances;
+    private readonly items;
+    private readonly labels;
+    private readonly translate;
+    private menu;
+    private eventsBound;
+    private contextStart;
+    private readonly onContextMenuBound;
+    private readonly onMouseDownBound;
+    private readonly onDocumentClickBound;
+    static get BUILTIN_ITEMS(): Record<ContextMenuBuiltinId, ContextMenuItem>;
+    static get DEFAULT_ITEMS(): ContextMenuItem[];
+    constructor(options?: ContextMenuPluginOptions);
+    init(chart: IHChart): void;
+    enable(): void;
+    disable(): void;
+    destroy(): void;
+    private resolveItems;
+    private localizedBuiltinItems;
+    private addRequiredPlugins;
+    private createPlugin;
+    private createMenu;
+    private bindEvents;
+    private unbindEvents;
+    private onMouseDown;
+    private onContextMenu;
+    private showMenu;
+    private createMenuItem;
+    private createInputItem;
+    private createSubmenu;
+    private resolveInputValue;
+    private clampInputValue;
+    private handleItem;
+    private hideMenu;
+    private resolveZIndex;
+}
+
+export declare interface ContextMenuPluginOptions {
+    enabled?: boolean;
+    items?: ContextMenuEntry[];
+    zIndex?: number;
+    labels?: Partial<Record<ContextMenuBuiltinId, string>>;
+    translate?: (id: ContextMenuBuiltinId, fallback: string) => string;
+}
+
+/** Create a reusable guard object for one or more bidirectional cursor links. */
+export declare function createCursorSyncState(): CursorSyncState;
+
+/** Default envelope-analysis menu. */
+export declare function createEnvelopeContextMenuItems(): ContextMenuEntry[];
+
+/** Default spectrum-analysis menu, suitable as a host-level starting point. */
+export declare function createSpectrumContextMenuItems(): ContextMenuEntry[];
+
+/** Minimal time-waveform menu. */
+export declare function createWaveContextMenuItems(): ContextMenuEntry[];
+
+/**
+ * Framework-agnostic cursor bridge.
+ *
+ * The bridge forwards only `point.x`; the target chart resolves its own nearest
+ * point, which is important when two series use different sampling intervals.
+ */
+export declare class CursorLinkPlugin extends BasePlugin {
+    name: string;
+    private readonly target;
+    private readonly syncState;
+    constructor(options: CursorLinkPluginOptions);
+    onCursorChange(point: Point): void;
+}
+
+export declare interface CursorLinkPluginOptions {
+    enabled?: boolean;
+    /** Resolve the chart that should receive the source point's X value. */
+    target: () => IHChart | null | undefined;
+    /** Optional unique name when more than one link plugin is registered. */
+    name?: string;
+    /** Share this object between both directions of a bidirectional link. */
+    syncState?: CursorSyncState;
+}
+
+/**
+ * Cursor Plugin
+ *
+ * Provides an interactive cursor that snaps to data points.
+ * Features:
+ * - Snap to nearest point
+ * - Keyboard navigation (Left/Right arrow)
+ * - Draggable cursor (via hidden hit area)
+ * - Custom label formatting
+ */
+export declare class CursorPlugin extends BasePlugin {
+    name: string;
+    private cursorLabel;
+    private cursorHitLine;
+    private activePoint;
+    private onKeyDownBound;
+    private labelFormatter;
+    private onCursorMove;
+    private isDragging;
+    private hoverDebounceTimer;
+    private multiLine;
+    private draggable;
+    private pointerDown;
+    private pointerDragged;
+    private suppressClickUntil;
+    private eventsBound;
+    private unbindAfterSetExtremes;
+    private onPointerDownBound;
+    private onPointerMoveBound;
+    private onPointerUpBound;
+    private onContainerMouseMoveBound;
+    private onContainerMouseUpBound;
+    constructor(options?: CursorPluginOptions);
+    private onContainerMouseMove;
+    private onPointerDown;
+    private onPointerMove;
+    private trackPointerDrag;
+    private onPointerUp;
+    private shouldIgnoreChartClick;
+    private onContainerMouseUp;
+    init(chart: IHChart): void;
+    enable(): void;
+    disable(): void;
+    onCursorChange(point: any): void;
+    private bindEvents;
+    private unbindEvents;
+    private getNativeChart;
+    private getSeriesList;
+    private getXData;
+    private onKeyDown;
+    onChartClick(e: default_2.ChartClickEventObject | default_2.PointClickEventObject): void;
+    /**
+     * Update cursor position based on X value.
+     * Uses raw xData to ensure accuracy across zoom levels.
+     */
+    updateCursor(xValue: number): void;
+    /**
+     * Re-applies the cursor based on the last active point.
+     * Called after zoom/pan to ensure cursor stays on the correct data point.
+     */
+    private refreshCursor;
+    private drawCursor;
+    /** 边频/阈值线等可拖拽辅助线，需保留 pointer-events */
+    private isInteractivePlotLine;
+    private applyPassiveCursorLayer;
+    private buildCursorLabelText;
+    private formatXText;
+    private getOrderedSeries;
+    private getOrderedVisibleSeriesPointsAtX;
+    private getSeriesPointByX;
+    private scheduleSeriesHoverState;
+    private applySeriesHoverState;
+    destroy(): void;
+}
+
+export declare interface CursorPluginOptions {
+    enabled?: boolean;
+    multiLine?: boolean;
+    /** 是否允许拖拽光标线；关闭后仅点击图表移动光标，避免与框选放大冲突 */
+    draggable?: boolean;
+    /**
+     * Custom formatter for the cursor label.
+     * Return a string to be displayed (e.g. "x, y" or "x Hz, y mm/s").
+     */
+    labelFormatter?: (x: number, y: number) => string;
+    /** Called after cursor position updates (click / drag / keyboard). */
+    onCursorMove?: (point: {
+        x: number;
+        y: number;
+        index: number;
+    }) => void;
+}
+
+export declare interface CursorSyncState {
+    active: boolean;
+}
+
+/**
+ * HChart - Highcharts Wrapper Class
+ *
+ * Encapsulates Highcharts initialization, default configuration, and plugin management.
+ */
+export declare class HChart implements IHChart {
+    chart: Highcharts_2.Chart;
+    plugins: Map<string, IPlugin>;
+    container: HTMLElement;
+    activePoint: Point | null;
+    private resizeObserver;
+    private reflowFrame;
+    constructor(config: HChartConfig);
+    addPlugin(plugin: IPlugin): void;
+    getPlugin<T extends IPlugin>(name: string): T | undefined;
+    removePlugin(name: string): void;
+    /**
+     * Coalesce multiple size changes into one chart reflow in the next animation frame.
+     * ResizeObserver can fire repeatedly while split panes and cards are animating.
+     */
+    requestReflow(): void;
+    destroy(): void;
+    private onChartClick;
+    setCursor(point: Point): void;
+    /**
+     * Set cursor by X value (will snap to nearest point)
+     */
+    setCursorX(x: number): void;
+    /**
+     * Toggle a plugin by name
+     */
+    togglePlugin(name: string, enabled: boolean): void;
+    /** Update the underlying Highcharts options without recreating plugins. */
+    updateOptions(options: Highcharts_2.Options, redraw?: boolean): void;
+    /** Replace one series data set through the stable HChart API. */
+    setSeriesData(data: Highcharts_2.PointOptionsType[], seriesIndex?: number, redraw?: boolean): void;
+    getSeriesData(): number[][];
+    private resolveMarkerConfig;
+    /**
+     * Adds a static reference line (vertical or horizontal) to the chart.
+     * Useful for thresholds, limits, or markers.
+     *
+     * @param options Configuration for the reference line
+     * @returns The unique ID of the added line (use to remove later)
+     */
+    addReferenceLine(options: {
+        axis?: 'x' | 'y';
+        value: number;
+        color?: string;
+        text?: string;
+        width?: number;
+        dashStyle?: Highcharts_2.DashStyleValue;
+        zIndex?: number;
+    }): string;
+    removeReferenceLine(id: string, axis?: 'x' | 'y'): void;
+}
+
+export declare interface HChartConfig {
+    /**
+     * The ID of the container element or the element itself.
+     */
+    container: string | HTMLElement;
+    /**
+     * Standard Highcharts options to override defaults.
+     */
+    options?: Highcharts_2.Options;
+    /**
+     * List of plugins to initialize with the chart.
+     */
+    plugins?: IPlugin[];
+    /**
+     * Configuration for data point markers.
+     */
+    markerConfig?: {
+        /**
+         * Force enable/disable markers.
+         */
+        enabled?: boolean;
+        /**
+         * If true, markers are enabled based on data density (threshold).
+         */
+        auto?: boolean;
+        /**
+         * Maximum number of points to show markers in auto mode (default 50).
+         */
+        threshold?: number;
+    };
+    theme?: 'light' | 'dark';
+}
+
+export declare type HChartMarkerConfig = NonNullable<HChartConfig['markerConfig']>;
+
+export declare interface IHChart {
+    chart: Highcharts_2.Chart;
+    container: HTMLElement;
+    activePoint: Point | null;
+    addPlugin(plugin: IPlugin): void;
+    getPlugin<T extends IPlugin>(name: string): T | undefined;
+    removePlugin(name: string): void;
+    requestReflow(): void;
+    destroy(): void;
+    setCursor(point: Point): void;
+    setCursorX(x: number): void;
+    togglePlugin(name: string, enabled: boolean): void;
+    updateOptions?(options: Highcharts_2.Options, redraw?: boolean): void;
+    setSeriesData?(data: Highcharts_2.PointOptionsType[], seriesIndex?: number, redraw?: boolean): void;
+}
+
+export declare interface IPlugin {
+    name: string;
+    init(chart: IHChart): void;
+    destroy(): void;
+    enable(): void;
+    disable(): void;
+    update(options: any): void;
+    isEnabled?(): boolean;
+    onChartClick?(e: Highcharts_2.PointerEventObject): void;
+    onCursorChange?(point: Point): void;
+}
+
+/** plot line 运行时通过 addEvent 支持任意 DOM 事件，类型声明只覆盖了其中一部分。 */
+export declare type PlotLineEvents = Highcharts_2.XAxisPlotLinesEventsOptions & {
+    mousedown?: (e: PointerEvent) => void;
+};
+
+export declare interface Point {
+    x: number;
+    y: number;
+    index: number;
+    seriesIndex?: number;
+}
+
+export declare function shouldSuppressCursorClick(container: HTMLElement | null | undefined): boolean;
+
+export declare class SidebandPlugin extends BasePlugin {
+    name: string;
+    private delta;
+    private lineCount;
+    private lineIds;
+    private isDragging;
+    private draggedLineIndex;
+    private onDeltaChange;
+    private lineColor;
+    private dashStyle;
+    private labelOptions;
+    private directShow;
+    private xAxisUnit;
+    private onMouseUpBound;
+    private onContainerMouseMoveBound;
+    private eventsBound;
+    constructor(options?: SidebandPluginOptions);
+    setLineCount(count: number): void;
+    getLineCount(): number;
+    setDelta(delta: number): void;
+    getDelta(): number;
+    /** 边频标签：频谱图直接显示 Hz；时域图将 ms 间隔换算为 Hz */
+    private formatSidebandLabel;
+    isEnabled(): boolean;
+    setDirectShow(show: boolean): void;
+    init(chart: IHChart): void;
+    private bindEvents;
+    private unbindEvents;
+    private onMouseUp;
+    onCursorChange(point: Point): void;
+    enable(): void;
+    disable(): void;
+    private clearLines;
+    private renderSidebands;
+    private onContainerMouseMove;
+    destroy(): void;
+}
+
+export declare interface SidebandPluginOptions {
+    enabled?: boolean;
+    initialDelta?: number;
+    lineCount?: number;
+    directShow?: boolean;
+    color?: string;
+    dashStyle?: Highcharts_2.DashStyleValue;
+    labelColor?: string;
+    /** X 轴单位：时域 ms 需将间隔换算为 Hz 显示 */
+    xAxisUnit?: 'Hz' | 'ms' | string;
+    onDeltaChange?: (delta: number) => void;
+}
+
+/** 框选/拖拽后短暂禁止标点，避免与放大冲突 */
+export declare function suppressCursorClick(container: HTMLElement | null | undefined, ms?: number): void;
+
+export declare class ThresholdLinePlugin extends BasePlugin {
+    name: string;
+    private yValue;
+    private lineId;
+    private isDragging;
+    private annotationId;
+    private onContainerMouseMoveBound;
+    private onMouseUpBound;
+    private eventsBound;
+    constructor(options?: ThresholdLinePluginOptions);
+    init(chart: IHChart): void;
+    private bindEvents;
+    private unbindEvents;
+    destroy(): void;
+    private onMouseUp;
+    enable(): void;
+    disable(): void;
+    private clear;
+    setValue(v: number): void;
+    getValue(): number;
+    private clearMarkers;
+    private renderLine;
+    private getData;
+    private markPointsAboveThreshold;
+    private onContainerMouseMove;
+}
+
+export declare interface ThresholdLinePluginOptions {
+    enabled?: boolean;
+    initialValue?: number;
+}
+
+export declare class Utils {
+    /**
+     * Find the index of the data point closest to a given value using binary search.
+     * Assumes data is sorted in ascending order.
+     * @param value The value to search for (e.g., x-axis value)
+     * @param data The array of values to search in
+     * @returns The index of the nearest value
+     */
+    static getMostNearIndex(value: number, data: number[]): number;
+    /**
+     * Helper to format numbers with precision
+     */
+    static formatNumber(val: number, decimals?: number): string;
+}
+
+export declare class ZoomPlugin extends BasePlugin {
+    name: string;
+    private startX;
+    private onMouseDownBound;
+    private onMouseUpBound;
+    private onContextMenuBound;
+    private onMouseMoveBound;
+    private isPanning;
+    private lastX;
+    private rightMouseDown;
+    private panMoved;
+    private eventsBound;
+    constructor(options?: ZoomPluginOptions);
+    init(chart: IHChart): void;
+    private bindEvents;
+    private unbindEvents;
+    enable(): void;
+    disable(): void;
+    private onContextMenu;
+    private onMouseDown;
+    private onMouseMove;
+    private onMouseUp;
+    destroy(): void;
+}
+
+export declare interface ZoomPluginOptions {
+    enabled?: boolean;
+}
+
+export { }