hyperprop-charting-library 0.1.138 → 0.1.140

package/dist/index.d.cts

@@ -80,6 +80,9 @@ interface ChartOptions {
     doubleClickAction?: "reset" | "placeLimitOrder";
     keyboard?: KeyboardOptions;
     accessibility?: AccessibilityOptions;
+    downsampling?: DownsamplingOptions;
+    touch?: TouchOptions;
+    datafeedOptions?: DatafeedOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -502,6 +505,19 @@ interface CrosshairPriceActionEvent {
     y: number;
     price: number;
 }
+/** Press-and-hold on touch; also fired while the finger scrubs afterwards. */
+interface ChartLongPressEvent {
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+    price?: number;
+    index?: number;
+    time?: string;
+    point?: OhlcDataPoint;
+    /** False for the initial press, true for subsequent scrub updates. */
+    scrubbing: boolean;
+}
 /**
  * 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.
@@ -552,6 +568,100 @@ interface KeyboardOptions {
     /** 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;
+}
+/** Touch ergonomics. Fingers are blunter than a mouse cursor. */
+interface TouchOptions {
+    /**
+     * Multiplier applied to drawing/handle/divider hit tolerances for touch and
+     * pen input, so grabbing a line doesn't demand pixel accuracy. Mouse input
+     * is unaffected. Default 2.2 (≈16px handles become ≈35px targets).
+     */
+    hitToleranceScale?: number;
+    /** Press-and-hold on the plot shows an OHLC tooltip. Default true. */
+    longPressTooltip?: boolean;
+    /** How long the finger must rest before the tooltip appears. Default 400ms. */
+    longPressMs?: number;
+}
+/** Bar window the chart is asking a datafeed for. */
+interface DatafeedBarsRequest {
+    /** Start of the wanted window in epoch ms (hint; `countBack` is authoritative). */
+    fromMs: number;
+    /** End of the wanted window in epoch ms, exclusive. */
+    toMs: number;
+    /** Roughly how many bars to return, counting back from `toMs`. */
+    countBack: number;
+    /** True for the initial load, false for older-history backfills. */
+    firstRequest: boolean;
+}
+/**
+ * Optional pull-based data source, shaped after TradingView's datafeed. Supply
+ * one and the chart loads its own history — including fetching older bars as
+ * the user scrolls left — instead of the host pushing everything through
+ * `setData`. `setData`/`upsertBar` keep working and take precedence, so this
+ * can be adopted one host at a time.
+ */
+interface ChartDatafeed {
+    /** Awaited once before the first `getBars`, like TradingView's onReady. */
+    onReady?: () => Promise<void> | void;
+    /**
+     * Return bars for the requested window, oldest first. Return an empty array
+     * to signal there is no more history — the chart stops asking.
+     */
+    getBars: (request: DatafeedBarsRequest) => Promise<OhlcDataPoint[]> | OhlcDataPoint[];
+    /** Stream live updates; return a teardown function. */
+    subscribeBars?: (onBar: (bar: OhlcDataPoint) => void) => (() => void) | void;
+    /** Called when `getBars` rejects; the chart just stops that request. */
+    onError?: (error: unknown, request: DatafeedBarsRequest) => void;
+}
+interface DatafeedOptions {
+    /**
+     * Start fetching older bars when fewer than this many remain to the left of
+     * the viewport. Default 150.
+     */
+    prefetchThresholdBars?: number;
+    /** Minimum gap between backfill requests. Default 1200ms. */
+    cooldownMs?: number;
+    /** Bars requested per backfill. Default 1500. */
+    chunkBars?: number;
+}
 interface AccessibilityOptions {
     /** aria-label on the canvas. Default "Price chart". */
     label?: string;
@@ -708,6 +818,26 @@ 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.
+     */
+    /**
+     * Attach (or clear with `null`) a pull-based datafeed. The chart loads the
+     * initial window, subscribes to live bars, and fetches older history as the
+     * user scrolls left. Returns a promise that resolves once the first batch is
+     * on screen.
+     */
+    setDatafeed: (datafeed: ChartDatafeed | null) => Promise<void>;
+    /** Fires when press-and-hold inspects a bar on touch. */
+    onLongPress: (handler: ((event: ChartLongPressEvent) => void) | null) => void;
+    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;
@@ -897,4 +1027,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-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 CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, 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 };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartDatafeed, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartLongPressEvent, type ChartOptions, type ChartSavedState, type ChartType, type CompareSeriesOptions, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DatafeedBarsRequest, type DatafeedOptions, 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 TouchOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };

package/dist/index.d.ts

@@ -80,6 +80,9 @@ interface ChartOptions {
     doubleClickAction?: "reset" | "placeLimitOrder";
     keyboard?: KeyboardOptions;
     accessibility?: AccessibilityOptions;
+    downsampling?: DownsamplingOptions;
+    touch?: TouchOptions;
+    datafeedOptions?: DatafeedOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -502,6 +505,19 @@ interface CrosshairPriceActionEvent {
     y: number;
     price: number;
 }
+/** Press-and-hold on touch; also fired while the finger scrubs afterwards. */
+interface ChartLongPressEvent {
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+    price?: number;
+    index?: number;
+    time?: string;
+    point?: OhlcDataPoint;
+    /** False for the initial press, true for subsequent scrub updates. */
+    scrubbing: boolean;
+}
 /**
  * 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.
@@ -552,6 +568,100 @@ interface KeyboardOptions {
     /** 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;
+}
+/** Touch ergonomics. Fingers are blunter than a mouse cursor. */
+interface TouchOptions {
+    /**
+     * Multiplier applied to drawing/handle/divider hit tolerances for touch and
+     * pen input, so grabbing a line doesn't demand pixel accuracy. Mouse input
+     * is unaffected. Default 2.2 (≈16px handles become ≈35px targets).
+     */
+    hitToleranceScale?: number;
+    /** Press-and-hold on the plot shows an OHLC tooltip. Default true. */
+    longPressTooltip?: boolean;
+    /** How long the finger must rest before the tooltip appears. Default 400ms. */
+    longPressMs?: number;
+}
+/** Bar window the chart is asking a datafeed for. */
+interface DatafeedBarsRequest {
+    /** Start of the wanted window in epoch ms (hint; `countBack` is authoritative). */
+    fromMs: number;
+    /** End of the wanted window in epoch ms, exclusive. */
+    toMs: number;
+    /** Roughly how many bars to return, counting back from `toMs`. */
+    countBack: number;
+    /** True for the initial load, false for older-history backfills. */
+    firstRequest: boolean;
+}
+/**
+ * Optional pull-based data source, shaped after TradingView's datafeed. Supply
+ * one and the chart loads its own history — including fetching older bars as
+ * the user scrolls left — instead of the host pushing everything through
+ * `setData`. `setData`/`upsertBar` keep working and take precedence, so this
+ * can be adopted one host at a time.
+ */
+interface ChartDatafeed {
+    /** Awaited once before the first `getBars`, like TradingView's onReady. */
+    onReady?: () => Promise<void> | void;
+    /**
+     * Return bars for the requested window, oldest first. Return an empty array
+     * to signal there is no more history — the chart stops asking.
+     */
+    getBars: (request: DatafeedBarsRequest) => Promise<OhlcDataPoint[]> | OhlcDataPoint[];
+    /** Stream live updates; return a teardown function. */
+    subscribeBars?: (onBar: (bar: OhlcDataPoint) => void) => (() => void) | void;
+    /** Called when `getBars` rejects; the chart just stops that request. */
+    onError?: (error: unknown, request: DatafeedBarsRequest) => void;
+}
+interface DatafeedOptions {
+    /**
+     * Start fetching older bars when fewer than this many remain to the left of
+     * the viewport. Default 150.
+     */
+    prefetchThresholdBars?: number;
+    /** Minimum gap between backfill requests. Default 1200ms. */
+    cooldownMs?: number;
+    /** Bars requested per backfill. Default 1500. */
+    chunkBars?: number;
+}
 interface AccessibilityOptions {
     /** aria-label on the canvas. Default "Price chart". */
     label?: string;
@@ -708,6 +818,26 @@ 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.
+     */
+    /**
+     * Attach (or clear with `null`) a pull-based datafeed. The chart loads the
+     * initial window, subscribes to live bars, and fetches older history as the
+     * user scrolls left. Returns a promise that resolves once the first batch is
+     * on screen.
+     */
+    setDatafeed: (datafeed: ChartDatafeed | null) => Promise<void>;
+    /** Fires when press-and-hold inspects a bar on touch. */
+    onLongPress: (handler: ((event: ChartLongPressEvent) => void) | null) => void;
+    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;
@@ -897,4 +1027,4 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-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 CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, 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 };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartDatafeed, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartLongPressEvent, type ChartOptions, type ChartSavedState, type ChartType, type CompareSeriesOptions, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DatafeedBarsRequest, type DatafeedOptions, 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 TouchOptions, type TradeMarkerOptions, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, validateScriptSource };