hyperprop-charting-library 0.1.139 → 0.1.141

package/dist/index.d.cts

@@ -81,6 +81,8 @@ interface ChartOptions {
     keyboard?: KeyboardOptions;
     accessibility?: AccessibilityOptions;
     downsampling?: DownsamplingOptions;
+    touch?: TouchOptions;
+    datafeedOptions?: DatafeedOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -503,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.
@@ -592,6 +607,90 @@ interface CompareSeriesOptions {
     /** Let this series widen the price scale. Default true. */
     includeInAutoScale?: boolean;
 }
+/**
+ * A complete chart palette. Hosts otherwise configure a dozen colors one by
+ * one and re-push them on every light/dark toggle; a theme is that same set as
+ * one object, so `setTheme` is a single call.
+ */
+interface ChartTheme {
+    name: string;
+    background: string;
+    upColor: string;
+    downColor: string;
+    /** Line/area/baseline series color. */
+    lineColor: string;
+    gridColor: string;
+    gridOpacity: number;
+    axisTextColor: string;
+    axisLineColor: string;
+    crosshairColor: string;
+    crosshairLabelBackground: string;
+    crosshairLabelText: string;
+    crosshairLabelBorder: string;
+    watermarkColor: string;
+    /** Indicator names/values drawn inside the plot and pane legends. */
+    indicatorTextColor: string;
+    /** Text drawn on colored order/preview pills. */
+    labelTextColor: string;
+    /** Background for preview labels and pills. */
+    labelBackground: string;
+}
+type ChartThemeName = "dark" | "light" | "midnight" | "high-contrast";
+/** 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;
@@ -748,6 +847,15 @@ interface ChartInstance {
      */
     setPriceScale: (options: Partial<PriceScaleOptions>) => void;
     getPriceScale: () => PriceScaleOptions;
+    /**
+     * Apply a whole palette at once — a built-in preset name or your own
+     * `ChartTheme`. Replaces the per-color `updateOptions` juggling hosts do on
+     * every light/dark toggle. Anything the theme doesn't cover (order-line
+     * colors, drawing defaults) is left alone.
+     */
+    setTheme: (theme: ChartThemeName | ChartTheme) => void;
+    /** Name of the last applied theme, or null if colors were set by hand. */
+    getTheme: () => string | null;
     /**
      * Overlay other instruments on the main pane for comparison. Series are
      * aligned to the main series by timestamp (last known value carries forward
@@ -755,6 +863,15 @@ interface ChartInstance {
      * 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;
@@ -946,6 +1063,19 @@ declare const validateScriptSource: (source: string) => string | null;
  */
 declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) => IndicatorPlugin;
 
+/**
+ * Built-in palettes.
+ *
+ * `dark` and `light` mirror TradingView's own chart colors (sampled from their
+ * rendered canvas), which is what most traders' eyes are calibrated to: the
+ * candle colors stay the same across both and only the surface changes.
+ * `midnight` is Hyperprop's long-standing default, kept as a named preset so
+ * existing setups have something to go back to. `high-contrast` trades
+ * prettiness for legibility on projectors and for low-vision users.
+ */
+declare const CHART_THEMES: Record<ChartThemeName, ChartTheme>;
+declare const CHART_THEME_NAMES: ChartThemeName[];
+
 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 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 };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, CHART_THEMES, CHART_THEME_NAMES, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartDatafeed, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartLongPressEvent, type ChartOptions, type ChartSavedState, type ChartTheme, type ChartThemeName, 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

@@ -81,6 +81,8 @@ interface ChartOptions {
     keyboard?: KeyboardOptions;
     accessibility?: AccessibilityOptions;
     downsampling?: DownsamplingOptions;
+    touch?: TouchOptions;
+    datafeedOptions?: DatafeedOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -503,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.
@@ -592,6 +607,90 @@ interface CompareSeriesOptions {
     /** Let this series widen the price scale. Default true. */
     includeInAutoScale?: boolean;
 }
+/**
+ * A complete chart palette. Hosts otherwise configure a dozen colors one by
+ * one and re-push them on every light/dark toggle; a theme is that same set as
+ * one object, so `setTheme` is a single call.
+ */
+interface ChartTheme {
+    name: string;
+    background: string;
+    upColor: string;
+    downColor: string;
+    /** Line/area/baseline series color. */
+    lineColor: string;
+    gridColor: string;
+    gridOpacity: number;
+    axisTextColor: string;
+    axisLineColor: string;
+    crosshairColor: string;
+    crosshairLabelBackground: string;
+    crosshairLabelText: string;
+    crosshairLabelBorder: string;
+    watermarkColor: string;
+    /** Indicator names/values drawn inside the plot and pane legends. */
+    indicatorTextColor: string;
+    /** Text drawn on colored order/preview pills. */
+    labelTextColor: string;
+    /** Background for preview labels and pills. */
+    labelBackground: string;
+}
+type ChartThemeName = "dark" | "light" | "midnight" | "high-contrast";
+/** 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;
@@ -748,6 +847,15 @@ interface ChartInstance {
      */
     setPriceScale: (options: Partial<PriceScaleOptions>) => void;
     getPriceScale: () => PriceScaleOptions;
+    /**
+     * Apply a whole palette at once — a built-in preset name or your own
+     * `ChartTheme`. Replaces the per-color `updateOptions` juggling hosts do on
+     * every light/dark toggle. Anything the theme doesn't cover (order-line
+     * colors, drawing defaults) is left alone.
+     */
+    setTheme: (theme: ChartThemeName | ChartTheme) => void;
+    /** Name of the last applied theme, or null if colors were set by hand. */
+    getTheme: () => string | null;
     /**
      * Overlay other instruments on the main pane for comparison. Series are
      * aligned to the main series by timestamp (last known value carries forward
@@ -755,6 +863,15 @@ interface ChartInstance {
      * 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;
@@ -946,6 +1063,19 @@ declare const validateScriptSource: (source: string) => string | null;
  */
 declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) => IndicatorPlugin;
 
+/**
+ * Built-in palettes.
+ *
+ * `dark` and `light` mirror TradingView's own chart colors (sampled from their
+ * rendered canvas), which is what most traders' eyes are calibrated to: the
+ * candle colors stay the same across both and only the surface changes.
+ * `midnight` is Hyperprop's long-standing default, kept as a named preset so
+ * existing setups have something to go back to. `high-contrast` trades
+ * prettiness for legibility on projectors and for low-vision users.
+ */
+declare const CHART_THEMES: Record<ChartThemeName, ChartTheme>;
+declare const CHART_THEME_NAMES: ChartThemeName[];
+
 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 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 };
+export { type AccessibilityOptions, type AxisOptions, type BuiltInIndicatorInfo, CHART_THEMES, CHART_THEME_NAMES, type ChartClickEvent, type ChartContextMenuEvent, type ChartContextMenuRegion, type ChartDatafeed, type ChartInstance, type ChartKeyboardAction, type ChartKeyboardShortcutEvent, type ChartLongPressEvent, type ChartOptions, type ChartSavedState, type ChartTheme, type ChartThemeName, 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 };