hyperprop-charting-library 0.1.142 → 0.1.144

package/dist/hyperprop-charting-library.d.ts

@@ -83,9 +83,23 @@ interface ChartOptions {
     downsampling?: DownsamplingOptions;
     touch?: TouchOptions;
     datafeedOptions?: DatafeedOptions;
+    dataLine?: DataLineOptions;
+    animation?: AnimationOptions;
+    indicatorUpdate?: IndicatorUpdateOptions;
+    /**
+     * Zone every timestamp is rendered in: an IANA id ("America/New_York"),
+     * "utc", or "local" (default). Affects axis labels, the crosshair tag, the
+     * data line and day boundaries — never the underlying data.
+     */
+    timezone?: ChartTimezone;
+    /** Clock style for rendered times. Default "24h". */
+    timeFormat?: TimeFormat;
+    session?: SessionOptions;
+    history?: HistoryOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
+    alerts?: AlertOptions[];
     priceLines?: PriceLineOptions[];
     orderLines?: OrderLineOptions[];
     tickerLine?: TickerLineOptions;
@@ -547,7 +561,7 @@ interface ChartContextMenuEvent {
     };
 }
 /** 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";
+type ChartKeyboardAction = "delete-drawing" | "cancel" | "undo" | "redo" | "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`. */
@@ -567,6 +581,8 @@ interface KeyboardOptions {
     panBars?: number;
     /** Delete/Backspace removes the selected drawing. Default true. */
     deleteSelectedDrawing?: boolean;
+    /** Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z (or Ctrl+Y). Default true. */
+    undoRedo?: boolean;
 }
 /**
  * Deep zoom-out rendering. Once bars are narrower than `thresholdPx`, several
@@ -636,6 +652,67 @@ interface ChartTheme {
     labelBackground: string;
 }
 type ChartThemeName = "midnight" | "light" | "brand" | "dark" | "high-contrast";
+/**
+ * The symbol/OHLC line drawn inside the top-left of the plot, like
+ * TradingView's data line. Values follow the crosshair while hovering and fall
+ * back to the latest bar otherwise. Opt-in, because hosts that already render
+ * their own DOM overlay shouldn't suddenly get two.
+ */
+interface DataLineOptions {
+    /** Default false. */
+    visible?: boolean;
+    /** e.g. "NQU6" — drawn first, in the emphasis color. */
+    symbol?: string;
+    /** e.g. "1h". */
+    interval?: string;
+    /** e.g. "CME". */
+    exchange?: string;
+    /** O/H/L/C values for the hovered (or latest) bar. Default true. */
+    showOhlc?: boolean;
+    /** Absolute and percent change of that bar, colored by direction. Default true. */
+    showChange?: boolean;
+    /** Bar volume. Default false. */
+    showVolume?: boolean;
+    /**
+     * Extra chips after the values — session, currency, a "Closed" badge. Each
+     * renders as `label value` with an optional color and pill background.
+     */
+    details?: Array<{
+        label?: string;
+        value: string;
+        color?: string;
+        background?: string;
+    }>;
+    /** Colored dot before the symbol, e.g. green when the market is open. */
+    statusColor?: string;
+    fontSize?: number;
+    /** Symbol color. Defaults to the axis text color. */
+    symbolColor?: string;
+    /** Everything after the symbol. Defaults to the indicator legend color. */
+    textColor?: string;
+}
+interface IndicatorUpdateOptions {
+    /**
+     * While only the forming bar is ticking, recompute indicator series at most
+     * this often (ms) rather than on every frame. Values are always exact — this
+     * changes how often the live bar's output refreshes, not how it's computed,
+     * and anything structural (a bar closing, history loading, inputs changing)
+     * recomputes immediately. Default 80; set 0 to recompute every frame.
+     */
+    liveThrottleMs?: number;
+}
+interface AnimationOptions {
+    /**
+     * Ease the big viewport jumps — reset, fit-all, scroll-to-realtime — instead
+     * of teleporting, so it stays obvious which way the chart moved. Continuous
+     * gestures (drag, wheel, pinch) are never animated; they already follow the
+     * hand. Default true, and always skipped when the OS asks for reduced
+     * motion.
+     */
+    viewportTransitions?: boolean;
+    /** Transition length in ms. Default 260. */
+    durationMs?: number;
+}
 /** Touch ergonomics. Fingers are blunter than a mouse cursor. */
 interface TouchOptions {
     /**
@@ -913,6 +990,80 @@ interface ChartInstance {
         type?: "image/png" | "image/jpeg";
         quality?: number;
     }) => string;
+    /**
+     * Render every timestamp in another zone — "America/New_York" for CME
+     * futures, "utc", "local", any IANA id. Data is untouched; only labels,
+     * the crosshair tag and day/session boundaries move. Unknown ids fall back
+     * to local time rather than throwing.
+     */
+    setTimezone: (timezone: ChartTimezone) => void;
+    getTimezone: () => ChartTimezone;
+    /** Switch rendered clock times between 24-hour and 12-hour. */
+    setTimeFormat: (format: TimeFormat) => void;
+    getTimeFormat: () => TimeFormat;
+    /**
+     * Teach the chart the instrument's trading hours. Session starts then get
+     * their own separators (a futures day opening at 18:00 ET is one session,
+     * not two calendar days) and out-of-session bars can be tinted.
+     */
+    setSession: (session: SessionOptions | SessionSpec | SessionPresetName | null) => void;
+    getSession: () => SessionOptions;
+    /**
+     * Step back through drawing edits — create, move, restyle, delete, clear.
+     * Returns false when there is nothing left to undo. Viewport changes are
+     * deliberately not recorded (panning is not an edit), and neither are bulk
+     * host syncs through `setDrawings`, so a host echoing state back never
+     * pollutes the stack.
+     */
+    undo: () => boolean;
+    redo: () => boolean;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    /** Current stack state, for enabling/labelling host buttons. */
+    getUndoRedoState: () => UndoRedoState;
+    onUndoRedoStateChange: (handler: ((state: UndoRedoState) => void) | null) => void;
+    /** Drop both stacks, e.g. after loading a different symbol. */
+    clearHistory: () => void;
+    /**
+     * Hide every bar after a chosen point and reveal them one at a time, so a
+     * setup can be re-traded without lookahead. Indicators, drawings and the
+     * price scale all see only the revealed bars. Live bars arriving while
+     * replay runs are buffered, not shown, and `stopReplay()` restores the full
+     * series.
+     */
+    startReplay: (options?: ReplayStartOptions) => void;
+    stopReplay: () => void;
+    /** Reveal `bars` more bars (negative rewinds). Default 1. */
+    replayStep: (bars?: number) => void;
+    replayPlay: (speed?: number) => void;
+    replayPause: () => void;
+    /** Bars revealed per second. */
+    setReplaySpeed: (speed: number) => void;
+    getReplayState: () => ReplayState;
+    onReplayStateChange: (handler: ((state: ReplayState) => void) | null) => void;
+    /**
+     * Horizontal watch levels with a bell tag on the price axis. The chart
+     * draws them, lets the user drag them, and fires `onAlertTrigger` when
+     * price satisfies the condition — delivery (push, email, sound) is the
+     * host's job.
+     */
+    setAlerts: (alerts: AlertOptions[]) => void;
+    addAlert: (alert: AlertOptions) => string;
+    updateAlert: (id: string, patch: Partial<AlertOptions>) => void;
+    removeAlert: (id: string) => void;
+    getAlerts: () => AlertOptions[];
+    onAlertTrigger: (handler: ((event: AlertTriggerEvent) => void) | null) => void;
+    /** Drag, delete-button and click interactions on an alert line. */
+    onAlertAction: (handler: ((event: AlertActionEvent) => void) | null) => void;
+    /** Badges pinned to bars (earnings, releases, your own annotations). */
+    setBarMarks: (marks: BarMarkOptions[]) => void;
+    getBarMarks: () => BarMarkOptions[];
+    /** Badges on the time axis, for date-anchored events. */
+    setTimescaleMarks: (marks: TimescaleMarkOptions[]) => void;
+    getTimescaleMarks: () => TimescaleMarkOptions[];
+    onMarkClick: (handler: ((event: MarkClickEvent) => void) | null) => void;
+    /** Fires with the hovered mark, and with null when the pointer leaves it. */
+    onMarkHover: (handler: ((event: MarkHoverEvent | null) => void) | null) => void;
     resize: (width?: number, height?: number) => void;
     destroy: () => void;
 }
@@ -953,12 +1104,182 @@ interface ChartSavedState {
     /** Optional for backward compatibility with pre-0.1.137 blobs. */
     priceScale?: PriceScaleOptions;
     drawingDefaults: Partial<Record<DrawingToolType, DrawingDefaults>>;
+    /** Added in 0.1.144. */
+    alerts?: AlertOptions[];
+    timezone?: ChartTimezone;
+    timeFormat?: TimeFormat;
 }
 type PriceScaleMode = "linear" | "log" | "percent";
 interface PriceScaleOptions {
     mode: PriceScaleMode;
     inverted: boolean;
 }
+/** IANA zone id, or the shorthands "local" (default) and "utc". */
+type ChartTimezone = "local" | "utc" | (string & {});
+type TimeFormat = "24h" | "12h";
+/** One continuous trading window in wall-clock time, e.g. 09:30 → 16:00. */
+interface SessionSegment {
+    /** "HH:MM" in the session's own zone. */
+    start: string;
+    /** "HH:MM". Earlier than `start` means the window runs past midnight. */
+    end: string;
+}
+interface SessionSpec {
+    /** Zone the segment times are quoted in. Defaults to the machine zone. */
+    timezone?: string;
+    /**
+     * Days the session *opens*, 0 = Sunday. Defaults to Monday–Friday. For a
+     * window that runs past midnight this is the evening side: CME futures open
+     * Sunday–Thursday (`[0,1,2,3,4]`) and trade into Monday–Friday morning, so
+     * Friday evening is correctly closed for the weekend.
+     */
+    days?: number[];
+    /** Defaults to a single all-day window. */
+    segments?: SessionSegment[];
+}
+type SessionPresetName = "cme-futures" | "cme-rth" | "us-equities" | "us-equities-extended" | "24x7";
+/**
+ * Trading-hours awareness. Without a spec the chart falls back to calendar
+ * days for separators and shades nothing — the behavior of earlier versions.
+ */
+interface SessionOptions {
+    /** A preset name or your own spec. null disables session handling. */
+    spec?: SessionSpec | SessionPresetName | null;
+    /** Vertical rule at each session start. Default true when a spec is set. */
+    separators?: boolean;
+    /**
+     * Tint bars that fall outside the session (overnight/extended hours), the
+     * way TradingView greys pre/post market. Default false.
+     */
+    highlightOutOfSession?: boolean;
+    outOfSessionColor?: string;
+}
+interface HistoryOptions {
+    /** Default true. */
+    enabled?: boolean;
+    /** Steps kept before the oldest is dropped. Default 100. */
+    limit?: number;
+}
+interface UndoRedoState {
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Human label of the step `undo()` would reverse, e.g. "Move drawing". */
+    undoLabel: string | null;
+    redoLabel: string | null;
+}
+interface ReplayStartOptions {
+    /** Bar to resume from. Ignored when `fromTimeMs` is given. */
+    fromIndex?: number;
+    /** Resume from the bar at (or just before) this timestamp. */
+    fromTimeMs?: number;
+    /** Bars revealed per second while playing. Default 1. */
+    speed?: number;
+    /** Start playing immediately instead of waiting for `replayPlay()`. */
+    play?: boolean;
+}
+interface ReplayState {
+    active: boolean;
+    playing: boolean;
+    /** Bars per second. */
+    speed: number;
+    /** Index of the last revealed bar within the full series. */
+    index: number;
+    /** Length of the full series. */
+    total: number;
+    /** True once every bar has been revealed. */
+    atEnd: boolean;
+    /** Timestamp of the last revealed bar. */
+    timeMs: number | null;
+}
+/**
+ * "crossing" fires in either direction; the directional variants only fire on
+ * the matching side; "greater"/"less" fire as soon as price is on that side,
+ * including immediately if it already is.
+ */
+type AlertCondition = "crossing" | "crossing-up" | "crossing-down" | "greater" | "less";
+interface AlertOptions {
+    id?: string;
+    price: number;
+    /** Default "crossing". */
+    condition?: AlertCondition;
+    /** Extra text on the axis pill, after the price. */
+    label?: string;
+    color?: string;
+    /** Armed and watching. Default true. */
+    active?: boolean;
+    /** Set by the chart when the condition is met; dims the line. */
+    triggered?: boolean;
+    /** Disarm after the first trigger. Default true. */
+    once?: boolean;
+    /** Let the user drag the line to a new price. Default true. */
+    draggable?: boolean;
+}
+interface AlertTriggerEvent {
+    alert: AlertOptions;
+    /** Price that satisfied the condition. */
+    price: number;
+    timeMs: number;
+    /** Bar index the trigger was detected on. */
+    index: number;
+}
+interface AlertActionEvent {
+    alert: AlertOptions;
+    action: "move" | "remove" | "click";
+    /** New price for "move". */
+    price?: number;
+    /** True for intermediate updates while the line is still being dragged. */
+    dragging?: boolean;
+}
+type MarkShape = "circle" | "square" | "diamond" | "flag";
+/**
+ * A small badge pinned to one bar — earnings, a news headline, an economic
+ * release, a rule window. The chart resolves `time` to the bar it falls on.
+ */
+interface BarMarkOptions {
+    id?: string;
+    /** Epoch ms or ISO string. */
+    time: number | string;
+    /** Default "below". Ignored when `price` is set. */
+    position?: "above" | "below";
+    /** Pin at an exact price instead of the bar's high/low. */
+    price?: number;
+    /** One or two characters drawn inside the badge, e.g. "E" or "FOMC"[0]. */
+    label?: string;
+    /** Tooltip text shown on hover. */
+    text?: string;
+    color?: string;
+    textColor?: string;
+    /** Badge radius in px. Default 7. */
+    size?: number;
+    shape?: MarkShape;
+}
+/** A badge on the time axis, for date-anchored events. */
+interface TimescaleMarkOptions {
+    id?: string;
+    time: number | string;
+    label?: string;
+    text?: string;
+    color?: string;
+    textColor?: string;
+    shape?: MarkShape;
+}
+interface MarkClickEvent {
+    kind: "bar" | "timescale";
+    mark: BarMarkOptions | TimescaleMarkOptions;
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+}
+interface MarkHoverEvent {
+    kind: "bar" | "timescale";
+    mark: BarMarkOptions | TimescaleMarkOptions;
+    /** Canvas coordinates of the badge center. */
+    x: number;
+    y: number;
+    clientX: number;
+    clientY: number;
+}
 
 interface ScriptIndicatorInputDef {
     key: string;
@@ -1076,6 +1397,15 @@ declare const compileScriptIndicator: (definition: ScriptIndicatorDefinition) =>
 declare const CHART_THEMES: Record<ChartThemeName, ChartTheme>;
 declare const CHART_THEME_NAMES: ChartThemeName[];
 
+/** True when the runtime accepts the zone id, so a typo can't break the chart. */
+declare const isValidTimeZone: (timeZone: string) => boolean;
+/**
+ * Ready-made session definitions. `cme-futures` is the full electronic
+ * session (Sunday 18:00 ET through Friday 17:00 ET with the daily 17:00–18:00
+ * maintenance break); `cme-rth` is the US index pit-equivalent day session.
+ */
+declare const SESSION_PRESETS: Record<SessionPresetName, SessionSpec>;
+
 declare function createChart(element: HTMLElement, options?: ChartOptions): ChartInstance;
 
-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 };
+export { type AccessibilityOptions, type AlertActionEvent, type AlertCondition, type AlertOptions, type AlertTriggerEvent, type AnimationOptions, type AxisOptions, type BarMarkOptions, 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 ChartTimezone, type ChartType, type CompareSeriesOptions, type CrosshairMoveEvent, type CrosshairOptions, type CrosshairPriceActionEvent, type DashPatternOptions, type DataLineOptions, 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 HistoryOptions, type IndicatorInstanceOptions, type IndicatorPane, type IndicatorPaneActionEvent, type IndicatorPaneAxisOptions, type IndicatorPaneGuideLine, type IndicatorPaneHeightChangeEvent, type IndicatorPaneRenderInfo, type IndicatorPaneValue, type IndicatorPaneValueLabel, type IndicatorPlugin, type IndicatorRenderContext, type IndicatorUpdateOptions, type KeyboardOptions, type LabelsOptions, type MarkClickEvent, type MarkHoverEvent, type MarkShape, type OhlcDataPoint, type OrderActionButton, type OrderActionEvent, type OrderLineOptions, POSITION_DEFAULT_COLORS, type PriceLineOptions, type PriceScaleMode, type PriceScaleOptions, type ReplayStartOptions, type ReplayState, SCRIPT_SOURCE_INPUT_VALUES, SESSION_PRESETS, type ScriptComputeResult, type ScriptIndicatorDefinition, type ScriptIndicatorInputDef, type ScriptInputHelper, type ScriptInputOptions, type ScriptPlotSpec, type SessionOptions, type SessionPresetName, type SessionSegment, type SessionSpec, type TickerLineOptions, type TimeFormat, type TimescaleMarkOptions, type TouchOptions, type TradeMarkerOptions, type UndoRedoState, type ViewportState, type WatermarkOptions, compileScriptIndicator, createChart, extractScriptInputs, isValidTimeZone, validateScriptSource };