hyperprop-charting-library 0.1.137 → 0.1.139

package/dist/index.d.cts

@@ -78,6 +78,9 @@ interface ChartOptions {
     pinOutOfRangeLines?: boolean;
     doubleClickEnabled?: boolean;
     doubleClickAction?: "reset" | "placeLimitOrder";
+    keyboard?: KeyboardOptions;
+    accessibility?: AccessibilityOptions;
+    downsampling?: DownsamplingOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -164,6 +167,36 @@ interface DrawingSelectEvent {
     pointIndex?: number;
     x: number;
     y: number;
+    /** On-screen box of the drawing, for anchoring a host toolbar to it. */
+    bounds?: DrawingBounds;
+}
+/** Canvas-pixel bounding box of a drawing, relative to the chart canvas. */
+interface DrawingBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    centerX: number;
+    centerY: number;
+}
+/**
+ * Emitted whenever the selected drawing's on-screen box moves — selection,
+ * deselection (payload `null`), drag, edit, pan, zoom or resize. Hosts render
+ * their own floating toolbar and position it from `bounds`, keeping it inside
+ * `plot`; the chart never has to draw toolbar chrome itself.
+ */
+interface DrawingSelectionChangeEvent {
+    drawing: DrawingObjectOptions;
+    bounds: DrawingBounds;
+    /** Plot rectangle, so a toolbar can be clamped inside the chart area. */
+    plot: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** True while the drawing is actively being dragged or resized. */
+    dragging: boolean;
 }
 interface DrawingHoverEvent {
     drawing: DrawingObjectOptions | null;
@@ -470,6 +503,106 @@ interface CrosshairPriceActionEvent {
     y: number;
     price: number;
 }
+/**
+ * What the pointer was over when the context menu was requested. Hosts switch
+ * on this to show the right menu instead of re-deriving it from coordinates.
+ */
+type ChartContextMenuRegion = "plot" | "drawing" | "indicator-pane" | "x-axis" | "y-axis";
+interface ChartContextMenuEvent {
+    region: ChartContextMenuRegion;
+    /** Canvas-relative position. */
+    x: number;
+    y: number;
+    /** Viewport position, ready to place a DOM menu without re-measuring. */
+    clientX: number;
+    clientY: number;
+    /** Price under the pointer (main pane regions only). */
+    price?: number;
+    index?: number;
+    time?: string;
+    point?: OhlcDataPoint;
+    /** Set for region "drawing"; the drawing is also selected by the chart. */
+    drawing?: DrawingObjectOptions;
+    drawingTarget?: "line" | "handle";
+    pointIndex?: number;
+    /** Set for region "indicator-pane". */
+    indicator?: {
+        id: string;
+        type: string;
+    };
+}
+/** Built-in keyboard actions, reported after the chart applies them. */
+type ChartKeyboardAction = "delete-drawing" | "cancel" | "pan-left" | "pan-right" | "pan-up" | "pan-down" | "zoom-in" | "zoom-out" | "reset-viewport" | "scroll-to-realtime";
+interface ChartKeyboardShortcutEvent {
+    action: ChartKeyboardAction;
+    /** The originating `KeyboardEvent.key`. */
+    key: string;
+    shiftKey: boolean;
+    /** The drawing that was removed, for "delete-drawing" (so hosts can undo). */
+    drawing?: DrawingObjectOptions;
+}
+interface KeyboardOptions {
+    /**
+     * Master switch for the built-in shortcuts. Shortcuts only fire while the
+     * chart canvas has focus, so they never swallow typing in host inputs.
+     * Default true.
+     */
+    enabled?: boolean;
+    /** Bars panned per arrow-key press (Shift multiplies by 10). Default 1. */
+    panBars?: number;
+    /** Delete/Backspace removes the selected drawing. Default true. */
+    deleteSelectedDrawing?: boolean;
+}
+/**
+ * Deep zoom-out rendering. Once bars are narrower than `thresholdPx`, several
+ * of them share a pixel column and drawing each one is wasted work, so the
+ * chart aggregates every column into one min/max bucket: path operations then
+ * scale with the chart's width instead of the number of bars. Extremes are
+ * preserved exactly (a spike never disappears), which is why this uses
+ * min/max rather than sampling.
+ */
+interface DownsamplingOptions {
+    /** Default true. */
+    enabled?: boolean;
+    /** Bar width in pixels below which columns are aggregated. Default 1.5. */
+    thresholdPx?: number;
+}
+/**
+ * An extra instrument overlaid on the main pane ("compare" in TradingView).
+ * The host owns the data and keeps it fresh; the chart aligns it to the main
+ * series by timestamp and draws it.
+ */
+interface CompareSeriesOptions {
+    id: string;
+    /** Shown on the right-axis tag, e.g. "NQ1!". */
+    label?: string;
+    /** Bars for the compared instrument; aligned to the main series by time. */
+    data: OhlcDataPoint[];
+    color?: string;
+    lineWidth?: number;
+    style?: "line" | "area";
+    /**
+     * "percent" (default) normalises both instruments to their first visible
+     * bar so shapes can be compared regardless of nominal price — the same
+     * thing TradingView does when you add a comparison. "price" plots the raw
+     * values on the main scale, which only makes sense for related instruments.
+     */
+    scale?: "percent" | "price";
+    visible?: boolean;
+    /** Let this series widen the price scale. Default true. */
+    includeInAutoScale?: boolean;
+}
+interface AccessibilityOptions {
+    /** aria-label on the canvas. Default "Price chart". */
+    label?: string;
+    /**
+     * Longer description exposed via aria-description, e.g. the symbol and
+     * interval currently shown.
+     */
+    description?: string;
+    /** Make the canvas focusable so keyboard users can reach it. Default true. */
+    focusable?: boolean;
+}
 interface TickerLineOptions {
     visible?: boolean;
     style?: "solid" | "dotted" | "dashed";
@@ -581,6 +714,29 @@ interface ChartInstance {
     onDrawingSelect: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingDoubleClick: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
+    /**
+     * Selection geometry stream for a host-rendered floating toolbar. Fires on
+     * select/deselect and on every frame where the selected drawing's box moves
+     * (drag, pan, zoom, resize), so the toolbar can track the shape instead of
+     * sitting in a fixed corner. Payload is `null` when nothing is selected.
+     */
+    onSelectionChange: (handler: ((event: DrawingSelectionChangeEvent | null) => void) | null) => void;
+    /** Current selection and its on-screen box, for imperative reads. */
+    getSelectedDrawing: () => {
+        drawing: DrawingObjectOptions;
+        bounds: DrawingBounds;
+    } | null;
+    /**
+     * Right-click (or long-press equivalent) with everything the host needs to
+     * open the correct menu: which region was hit, the price/bar under the
+     * pointer, and the drawing or indicator pane it landed on. The chart always
+     * suppresses the browser's native menu.
+     */
+    onContextMenu: (handler: ((event: ChartContextMenuEvent) => void) | null) => void;
+    /** Fires after a built-in keyboard shortcut is applied. */
+    onKeyboardShortcut: (handler: ((event: ChartKeyboardShortcutEvent) => void) | null) => void;
+    /** Focus the chart canvas so keyboard shortcuts apply to it. */
+    focus: () => void;
     setMagnetMode: (mode: "none" | "weak" | "strong") => void;
     getMagnetMode: () => "none" | "weak" | "strong";
     /**
@@ -592,6 +748,17 @@ interface ChartInstance {
      */
     setPriceScale: (options: Partial<PriceScaleOptions>) => void;
     getPriceScale: () => PriceScaleOptions;
+    /**
+     * Overlay other instruments on the main pane for comparison. Series are
+     * aligned to the main series by timestamp (last known value carries forward
+     * across gaps) and, by default, normalised to percent change from the first
+     * visible bar so differently-priced instruments stay comparable. Data is not
+     * part of `saveState()` — the host re-supplies it.
+     */
+    setCompareSeries: (series: CompareSeriesOptions[]) => void;
+    addCompareSeries: (series: CompareSeriesOptions) => void;
+    removeCompareSeries: (id: string) => void;
+    getCompareSeries: () => CompareSeriesOptions[];
     cancelDrawing: () => boolean;
     setTradeMarkers: (markers: TradeMarkerOptions[]) => void;
     onDrawingHover: (handler: ((event: DrawingHoverEvent) => void) | null) => void;
@@ -781,4 +948,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartOptions, type ChartSavedState, type ChartType, type CompareSeriesOptions, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DownsamplingOptions, type DrawingBounds, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingSelectionChangeEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type KeyboardOptions, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };

package/dist/index.d.ts

@@ -78,6 +78,9 @@ interface ChartOptions {
     pinOutOfRangeLines?: boolean;
     doubleClickEnabled?: boolean;
     doubleClickAction?: "reset" | "placeLimitOrder";
+    keyboard?: KeyboardOptions;
+    accessibility?: AccessibilityOptions;
+    downsampling?: DownsamplingOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -164,6 +167,36 @@ interface DrawingSelectEvent {
     pointIndex?: number;
     x: number;
     y: number;
+    /** On-screen box of the drawing, for anchoring a host toolbar to it. */
+    bounds?: DrawingBounds;
+}
+/** Canvas-pixel bounding box of a drawing, relative to the chart canvas. */
+interface DrawingBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    centerX: number;
+    centerY: number;
+}
+/**
+ * Emitted whenever the selected drawing's on-screen box moves — selection,
+ * deselection (payload `null`), drag, edit, pan, zoom or resize. Hosts render
+ * their own floating toolbar and position it from `bounds`, keeping it inside
+ * `plot`; the chart never has to draw toolbar chrome itself.
+ */
+interface DrawingSelectionChangeEvent {
+    drawing: DrawingObjectOptions;
+    bounds: DrawingBounds;
+    /** Plot rectangle, so a toolbar can be clamped inside the chart area. */
+    plot: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    };
+    /** True while the drawing is actively being dragged or resized. */
+    dragging: boolean;
 }
 interface DrawingHoverEvent {
     drawing: DrawingObjectOptions | null;
@@ -470,6 +503,106 @@ interface CrosshairPriceActionEvent {
     y: number;
     price: number;
 }
+/**
+ * What the pointer was over when the context menu was requested. Hosts switch
+ * on this to show the right menu instead of re-deriving it from coordinates.
+ */
+type ChartContextMenuRegion = "plot" | "drawing" | "indicator-pane" | "x-axis" | "y-axis";
+interface ChartContextMenuEvent {
+    region: ChartContextMenuRegion;
+    /** Canvas-relative position. */
+    x: number;
+    y: number;
+    /** Viewport position, ready to place a DOM menu without re-measuring. */
+    clientX: number;
+    clientY: number;
+    /** Price under the pointer (main pane regions only). */
+    price?: number;
+    index?: number;
+    time?: string;
+    point?: OhlcDataPoint;
+    /** Set for region "drawing"; the drawing is also selected by the chart. */
+    drawing?: DrawingObjectOptions;
+    drawingTarget?: "line" | "handle";
+    pointIndex?: number;
+    /** Set for region "indicator-pane". */
+    indicator?: {
+        id: string;
+        type: string;
+    };
+}
+/** Built-in keyboard actions, reported after the chart applies them. */
+type ChartKeyboardAction = "delete-drawing" | "cancel" | "pan-left" | "pan-right" | "pan-up" | "pan-down" | "zoom-in" | "zoom-out" | "reset-viewport" | "scroll-to-realtime";
+interface ChartKeyboardShortcutEvent {
+    action: ChartKeyboardAction;
+    /** The originating `KeyboardEvent.key`. */
+    key: string;
+    shiftKey: boolean;
+    /** The drawing that was removed, for "delete-drawing" (so hosts can undo). */
+    drawing?: DrawingObjectOptions;
+}
+interface KeyboardOptions {
+    /**
+     * Master switch for the built-in shortcuts. Shortcuts only fire while the
+     * chart canvas has focus, so they never swallow typing in host inputs.
+     * Default true.
+     */
+    enabled?: boolean;
+    /** Bars panned per arrow-key press (Shift multiplies by 10). Default 1. */
+    panBars?: number;
+    /** Delete/Backspace removes the selected drawing. Default true. */
+    deleteSelectedDrawing?: boolean;
+}
+/**
+ * Deep zoom-out rendering. Once bars are narrower than `thresholdPx`, several
+ * of them share a pixel column and drawing each one is wasted work, so the
+ * chart aggregates every column into one min/max bucket: path operations then
+ * scale with the chart's width instead of the number of bars. Extremes are
+ * preserved exactly (a spike never disappears), which is why this uses
+ * min/max rather than sampling.
+ */
+interface DownsamplingOptions {
+    /** Default true. */
+    enabled?: boolean;
+    /** Bar width in pixels below which columns are aggregated. Default 1.5. */
+    thresholdPx?: number;
+}
+/**
+ * An extra instrument overlaid on the main pane ("compare" in TradingView).
+ * The host owns the data and keeps it fresh; the chart aligns it to the main
+ * series by timestamp and draws it.
+ */
+interface CompareSeriesOptions {
+    id: string;
+    /** Shown on the right-axis tag, e.g. "NQ1!". */
+    label?: string;
+    /** Bars for the compared instrument; aligned to the main series by time. */
+    data: OhlcDataPoint[];
+    color?: string;
+    lineWidth?: number;
+    style?: "line" | "area";
+    /**
+     * "percent" (default) normalises both instruments to their first visible
+     * bar so shapes can be compared regardless of nominal price — the same
+     * thing TradingView does when you add a comparison. "price" plots the raw
+     * values on the main scale, which only makes sense for related instruments.
+     */
+    scale?: "percent" | "price";
+    visible?: boolean;
+    /** Let this series widen the price scale. Default true. */
+    includeInAutoScale?: boolean;
+}
+interface AccessibilityOptions {
+    /** aria-label on the canvas. Default "Price chart". */
+    label?: string;
+    /**
+     * Longer description exposed via aria-description, e.g. the symbol and
+     * interval currently shown.
+     */
+    description?: string;
+    /** Make the canvas focusable so keyboard users can reach it. Default true. */
+    focusable?: boolean;
+}
 interface TickerLineOptions {
     visible?: boolean;
     style?: "solid" | "dotted" | "dashed";
@@ -581,6 +714,29 @@ interface ChartInstance {
     onDrawingSelect: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingDoubleClick: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
     onDrawingEditText: (handler: ((event: DrawingSelectEvent) => void) | null) => void;
+    /**
+     * Selection geometry stream for a host-rendered floating toolbar. Fires on
+     * select/deselect and on every frame where the selected drawing's box moves
+     * (drag, pan, zoom, resize), so the toolbar can track the shape instead of
+     * sitting in a fixed corner. Payload is `null` when nothing is selected.
+     */
+    onSelectionChange: (handler: ((event: DrawingSelectionChangeEvent | null) => void) | null) => void;
+    /** Current selection and its on-screen box, for imperative reads. */
+    getSelectedDrawing: () => {
+        drawing: DrawingObjectOptions;
+        bounds: DrawingBounds;
+    } | null;
+    /**
+     * Right-click (or long-press equivalent) with everything the host needs to
+     * open the correct menu: which region was hit, the price/bar under the
+     * pointer, and the drawing or indicator pane it landed on. The chart always
+     * suppresses the browser's native menu.
+     */
+    onContextMenu: (handler: ((event: ChartContextMenuEvent) => void) | null) => void;
+    /** Fires after a built-in keyboard shortcut is applied. */
+    onKeyboardShortcut: (handler: ((event: ChartKeyboardShortcutEvent) => void) | null) => void;
+    /** Focus the chart canvas so keyboard shortcuts apply to it. */
+    focus: () => void;
     setMagnetMode: (mode: "none" | "weak" | "strong") => void;
     getMagnetMode: () => "none" | "weak" | "strong";
     /**
@@ -592,6 +748,17 @@ interface ChartInstance {
      */
     setPriceScale: (options: Partial<PriceScaleOptions>) => void;
     getPriceScale: () => PriceScaleOptions;
+    /**
+     * Overlay other instruments on the main pane for comparison. Series are
+     * aligned to the main series by timestamp (last known value carries forward
+     * across gaps) and, by default, normalised to percent change from the first
+     * visible bar so differently-priced instruments stay comparable. Data is not
+     * part of `saveState()` — the host re-supplies it.
+     */
+    setCompareSeries: (series: CompareSeriesOptions[]) => void;
+    addCompareSeries: (series: CompareSeriesOptions) => void;
+    removeCompareSeries: (id: string) => void;
+    getCompareSeries: () => CompareSeriesOptions[];
     cancelDrawing: () => boolean;
     setTradeMarkers: (markers: TradeMarkerOptions[]) => void;
     onDrawingHover: (handler: ((event: DrawingHoverEvent) => void) | null) => void;
@@ -781,4 +948,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-export { type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartInstance, type ChartOptions, type ChartSavedState, type ChartType, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartOptions, type ChartSavedState, type ChartType, type CompareSeriesOptions, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DownsamplingOptions, type DrawingBounds, type DrawingDefaults, type DrawingHoverEvent, type DrawingObjectOptions, type DrawingPoint, type DrawingSelectEvent, type DrawingSelectionChangeEvent, type DrawingToolType, FIB_DEFAULT_PALETTE, type GridOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type KeyboardOptions, type LabelsOptions, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, SCRIPT_SOURCE_INPUT_VALUES, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type TickerLineOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };