hyperprop-charting-library 0.1.142 → 0.1.143

package/dist/hyperprop-charting-library.cjs

@@ -369,26 +369,45 @@ var getSeriesFingerprint = (data) => {
 var withCachedSeries = (key, data, compute) => {
   const fingerprint = getSeriesFingerprint(data);
   const existing = builtInSeriesCache.get(key);
-  if (existing && existing.fingerprint === fingerprint) {
-    return existing.values;
+  const shape = getSeriesShape(data);
+  if (existing) {
+    const unchanged = existing.fingerprint === fingerprint;
+    const liveTickWithinThrottle = !unchanged && indicatorLiveThrottleMs > 0 && existing.shape === shape && Date.now() - existing.computedAt < indicatorLiveThrottleMs;
+    if (unchanged || liveTickWithinThrottle) {
+      return existing.values;
+    }
   }
   const values = compute();
-  builtInSeriesCache.set(key, { fingerprint, values });
+  builtInSeriesCache.set(key, { fingerprint, values, shape, computedAt: Date.now() });
   return values;
 };
 var builtInComputationCache = /* @__PURE__ */ new Map();
+var indicatorLiveThrottleMs = 80;
+var setIndicatorLiveThrottleMs = (ms) => {
+  indicatorLiveThrottleMs = Math.max(0, ms);
+};
+var getSeriesShape = (data) => {
+  const length = data.length;
+  const last = length > 0 ? data[length - 1] : void 0;
+  return last ? `${length}|${last.time.getTime()}` : "empty";
+};
 var COMPUTATION_CACHE_MAX_ENTRIES = 128;
 var withCachedComputation = (key, data, compute) => {
   const fingerprint = getSeriesFingerprint(data);
   const existing = builtInComputationCache.get(key);
-  if (existing && existing.fingerprint === fingerprint) {
-    builtInComputationCache.delete(key);
-    builtInComputationCache.set(key, existing);
-    return existing.value;
+  const shape = getSeriesShape(data);
+  if (existing) {
+    const unchanged = existing.fingerprint === fingerprint;
+    const liveTickWithinThrottle = !unchanged && indicatorLiveThrottleMs > 0 && existing.shape === shape && Date.now() - existing.computedAt < indicatorLiveThrottleMs;
+    if (unchanged || liveTickWithinThrottle) {
+      builtInComputationCache.delete(key);
+      builtInComputationCache.set(key, existing);
+      return existing.value;
+    }
   }
   const value = compute();
   builtInComputationCache.delete(key);
-  builtInComputationCache.set(key, { fingerprint, value });
+  builtInComputationCache.set(key, { fingerprint, value, shape, computedAt: Date.now() });
   while (builtInComputationCache.size > COMPUTATION_CACHE_MAX_ENTRIES) {
     const oldest = builtInComputationCache.keys().next().value;
     if (oldest === void 0) break;
@@ -2958,7 +2977,23 @@ var DEFAULT_OPTIONS = {
   accessibility: { label: "Price chart", description: "", focusable: true },
   downsampling: { enabled: true, thresholdPx: 1.5 },
   touch: { hitToleranceScale: 2.2, longPressTooltip: true, longPressMs: 400 },
+  dataLine: {
+    visible: false,
+    symbol: "",
+    interval: "",
+    exchange: "",
+    showOhlc: true,
+    showChange: true,
+    showVolume: false,
+    details: [],
+    statusColor: "",
+    fontSize: 0,
+    symbolColor: "",
+    textColor: ""
+  },
   datafeedOptions: { prefetchThresholdBars: 150, cooldownMs: 1200, chunkBars: 1500 },
+  animation: { viewportTransitions: true, durationMs: 260 },
+  indicatorUpdate: { liveThrottleMs: 80 },
   crosshair: DEFAULT_CROSSHAIR_OPTIONS,
   grid: DEFAULT_GRID_OPTIONS,
   watermark: DEFAULT_WATERMARK_OPTIONS,
@@ -3017,6 +3052,18 @@ var mergeChartOptions = (baseOptions, options = {}) => ({
     ...baseOptions.touch,
     ...options.touch ?? {}
   },
+  dataLine: {
+    ...baseOptions.dataLine,
+    ...options.dataLine ?? {}
+  },
+  animation: {
+    ...baseOptions.animation,
+    ...options.animation ?? {}
+  },
+  indicatorUpdate: {
+    ...baseOptions.indicatorUpdate,
+    ...options.indicatorUpdate ?? {}
+  },
   datafeedOptions: {
     ...baseOptions.datafeedOptions,
     ...options.datafeedOptions ?? {}
@@ -3276,6 +3323,7 @@ function createChart(element, options = {}) {
   let crosshairPoint = null;
   let doubleClickEnabled = mergedOptions.doubleClickEnabled;
   let doubleClickAction = mergedOptions.doubleClickAction;
+  setIndicatorLiveThrottleMs(mergedOptions.indicatorUpdate?.liveThrottleMs ?? 80);
   let noOverlappingLineLabels = DEFAULT_LABELS_OPTIONS.noOverlapping;
   let rightAxisLabelSlots = [];
   let plotLabelSlots = [];
@@ -3517,21 +3565,69 @@ function createChart(element, options = {}) {
       Math.min(highCenter, count + maxPanBars)
     );
   };
-  const fitXViewport = () => {
-    const count = data.length;
-    if (count === 0) {
-      xCenter = 0;
-      xSpan = 60;
-      return;
+  let viewportTweenRaf = null;
+  const cancelViewportTween = () => {
+    if (viewportTweenRaf !== null) {
+      cancelAnimationFrame(viewportTweenRaf);
+      viewportTweenRaf = null;
+    }
+  };
+  const prefersReducedMotion = () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const animateViewportTo = (targetCenter, targetSpan, onComplete) => {
+    const animation = mergedOptions.animation ?? DEFAULT_OPTIONS.animation;
+    const duration = Math.max(0, animation?.durationMs ?? 260);
+    const startCenter = xCenter;
+    const startSpan = xSpan;
+    const centerDelta = targetCenter - startCenter;
+    const spanRatio = startSpan > 0 ? targetSpan / startSpan : 1;
+    const negligible = Math.abs(centerDelta) < 0.5 && Math.abs(spanRatio - 1) < 0.01;
+    if (animation?.viewportTransitions === false || duration === 0 || negligible || prefersReducedMotion() || typeof requestAnimationFrame !== "function") {
+      xCenter = targetCenter;
+      xSpan = targetSpan;
+      clampXViewport();
+      onComplete?.();
+      emitViewportChange();
+      scheduleDraw();
+      return false;
     }
+    cancelViewportTween();
+    const startedAt = performance.now();
+    const step = (now) => {
+      const t = clamp((now - startedAt) / duration, 0, 1);
+      const eased = 1 - Math.pow(1 - t, 3);
+      xCenter = startCenter + centerDelta * eased;
+      xSpan = startSpan * Math.pow(spanRatio, eased);
+      clampXViewport();
+      scheduleDraw();
+      if (t < 1) {
+        viewportTweenRaf = requestAnimationFrame(step);
+        return;
+      }
+      viewportTweenRaf = null;
+      xCenter = targetCenter;
+      xSpan = targetSpan;
+      clampXViewport();
+      onComplete?.();
+      emitViewportChange();
+      scheduleDraw();
+    };
+    viewportTweenRaf = requestAnimationFrame(step);
+    return true;
+  };
+  const getFitXTarget = () => {
+    const count = data.length;
+    if (count === 0) return { center: 0, span: 60 };
     const maxSpan = Math.min(maxVisibleBars, Math.max(minVisibleBars, count + maxPanBars * 2));
-    const requestedVisibleBars = clamp(Math.floor(mergedOptions.initialVisibleBars), minVisibleBars, maxSpan);
-    xSpan = requestedVisibleBars;
-    if (mergedOptions.initialViewport === "center") {
-      xCenter = count / 2;
-    } else {
-      xCenter = count - xSpan / 2 + rightEdgePaddingBars;
-    }
+    const span = clamp(Math.floor(mergedOptions.initialVisibleBars), minVisibleBars, maxSpan);
+    return {
+      center: mergedOptions.initialViewport === "center" ? count / 2 : count - span / 2 + rightEdgePaddingBars,
+      span
+    };
+  };
+  const fitXViewport = () => {
+    const target = getFitXTarget();
+    xSpan = target.span;
+    xCenter = target.center;
     clampXViewport();
   };
   const getYBounds = () => {
@@ -6928,6 +7024,73 @@ function createChart(element, options = {}) {
     for (const orderLine of orderLines) {
       drawOrderLine(orderLine, yFromPrice, chartLeft, chartTop, chartRight, chartBottom);
     }
+    let dataLineBottom = chartTop;
+    const dataLine = mergedOptions.dataLine;
+    if (dataLine?.visible && data.length > 0) {
+      const hoverIndex = crosshairPoint && getHitRegion(crosshairPoint.x, crosshairPoint.y) === "plot" ? indexFromCanvasX(crosshairPoint.x) : null;
+      const barIndex = hoverIndex !== null && hoverIndex >= 0 && hoverIndex < data.length ? hoverIndex : data.length - 1;
+      const bar = data[barIndex];
+      if (bar) {
+        const prevFont = ctx.font;
+        const fontSize = Math.max(9, dataLine.fontSize || axis.fontSize);
+        ctx.font = `${fontSize}px ${mergedOptions.fontFamily}`;
+        ctx.textBaseline = "top";
+        ctx.textAlign = "left";
+        const symbolColor = dataLine.symbolColor || axis.textColor;
+        const textColor = dataLine.textColor || labels.indicatorTextColor;
+        const changeAbs = bar.c - bar.o;
+        const changeColor = changeAbs >= 0 ? mergedOptions.upColor : mergedOptions.downColor;
+        const rowY = chartTop + 6;
+        let cursorX = chartLeft + 10;
+        if (dataLine.statusColor) {
+          const dotRadius = Math.max(2.5, fontSize / 4);
+          ctx.fillStyle = dataLine.statusColor;
+          ctx.beginPath();
+          ctx.arc(cursorX + dotRadius, rowY + fontSize / 2, dotRadius, 0, Math.PI * 2);
+          ctx.fill();
+          cursorX += dotRadius * 2 + 6;
+        }
+        const headline = [dataLine.symbol, dataLine.interval, dataLine.exchange].filter((part) => part && part.length > 0).join(" \xB7 ");
+        if (headline) {
+          ctx.fillStyle = symbolColor;
+          ctx.fillText(headline, cursorX, rowY);
+          cursorX += measureTextWidth(headline) + 10;
+        }
+        if (dataLine.showOhlc !== false) {
+          const ohlc = `O${formatPrice(bar.o)} H${formatPrice(bar.h)} L${formatPrice(bar.l)} C${formatPrice(bar.c)}`;
+          ctx.fillStyle = changeColor;
+          ctx.fillText(ohlc, cursorX, rowY);
+          cursorX += measureTextWidth(ohlc) + 8;
+        }
+        if (dataLine.showChange !== false) {
+          const pct = bar.o !== 0 ? changeAbs / bar.o * 100 : 0;
+          const changeText = `${changeAbs >= 0 ? "+" : ""}${formatPrice(changeAbs)} (${changeAbs >= 0 ? "+" : ""}${pct.toFixed(2)}%)`;
+          ctx.fillStyle = changeColor;
+          ctx.fillText(changeText, cursorX, rowY);
+          cursorX += measureTextWidth(changeText) + 10;
+        }
+        if (dataLine.showVolume && bar.v !== void 0) {
+          const volumeText = `Vol ${bar.v >= 1e6 ? `${(bar.v / 1e6).toFixed(2)}M` : bar.v >= 1e3 ? `${(bar.v / 1e3).toFixed(1)}K` : String(Math.round(bar.v))}`;
+          ctx.fillStyle = textColor;
+          ctx.fillText(volumeText, cursorX, rowY);
+          cursorX += measureTextWidth(volumeText) + 10;
+        }
+        for (const detail of dataLine.details ?? []) {
+          const text = detail.label ? `${detail.label} ${detail.value}` : detail.value;
+          const width2 = measureTextWidth(text);
+          if (cursorX + width2 > chartRight - 4) break;
+          if (detail.background) {
+            ctx.fillStyle = detail.background;
+            fillRoundedRect(cursorX - 4, rowY - 2, width2 + 8, fontSize + 4, 3);
+          }
+          ctx.fillStyle = detail.color || textColor;
+          ctx.fillText(text, cursorX, rowY);
+          cursorX += width2 + 12;
+        }
+        dataLineBottom = rowY + fontSize + 4;
+        ctx.font = prevFont;
+      }
+    }
     if (labels.visible && (labels.showIndicatorNames || labels.showIndicatorValues)) {
       const isLegendInputValue = (value) => {
         if (typeof value === "number" || typeof value === "boolean") {
@@ -6956,7 +7119,7 @@ function createChart(element, options = {}) {
         const isRight = position === "top-right" || position === "bottom-right";
         const isBottom = position === "bottom-left" || position === "bottom-right";
         const legendX = isRight ? chartRight - offsetX : chartLeft + offsetX;
-        const legendY = isBottom ? chartBottom - offsetY : chartTop + offsetY;
+        const legendY = isBottom ? chartBottom - offsetY : Math.max(chartTop + offsetY, dataLineBottom);
         drawText(legendText, legendX, legendY, isRight ? "right" : "left", isBottom ? "bottom" : "top", labels.indicatorTextColor);
         ctx.font = prevFont;
       }
@@ -7497,27 +7660,24 @@ function createChart(element, options = {}) {
     scheduleDraw();
   };
   const fitContent = () => {
-    fitXViewport();
-    updateFollowLatest(true);
-    emitViewportChange();
-    scheduleDraw();
+    const target = getFitXTarget();
+    animateViewportTo(target.center, target.span, () => updateFollowLatest(true));
   };
   const resetViewport = () => {
     cancelKineticPan();
-    fitXViewport();
+    const target = getFitXTarget();
     resetYViewport();
-    updateFollowLatest(true);
-    emitViewportChange();
-    scheduleDraw();
+    animateViewportTo(target.center, target.span, () => updateFollowLatest(true));
   };
   const isFollowingLatest = () => followLatest;
   const setFollowingLatest = (follow) => {
     if (follow && data.length > 0) {
       cancelKineticPan();
-      xCenter = data.length - xSpan / 2 + rightEdgePaddingBars;
-      clampXViewport();
-      updateFollowLatest(true);
-      scheduleDraw();
+      animateViewportTo(
+        data.length - xSpan / 2 + rightEdgePaddingBars,
+        xSpan,
+        () => updateFollowLatest(true)
+      );
     } else {
       updateFollowLatest(follow);
     }
@@ -8800,6 +8960,7 @@ function createChart(element, options = {}) {
       canvas.focus({ preventScroll: true });
     }
     cancelKineticPan();
+    cancelViewportTween();
     panVelocitySamples.length = 0;
     magnetModifierActive = event.metaKey || event.ctrlKey;
     shiftKeyActive = event.shiftKey;
@@ -9464,6 +9625,7 @@ function createChart(element, options = {}) {
       return;
     }
     cancelKineticPan();
+    cancelViewportTween();
     const point = getCanvasPoint(event);
     const region = getHitRegion(point.x, point.y);
     if (region === "outside") {
@@ -9741,6 +9903,7 @@ function createChart(element, options = {}) {
     resetRightMarginCache();
     doubleClickEnabled = mergedOptions.doubleClickEnabled;
     doubleClickAction = mergedOptions.doubleClickAction;
+    setIndicatorLiveThrottleMs(mergedOptions.indicatorUpdate?.liveThrottleMs ?? 80);
     applyAccessibilityAttributes();
     const isTickerSmoothingEnabled = mergedOptions.tickerLine?.smoothing ?? false;
     if (!isTickerSmoothingEnabled) {
@@ -10219,6 +10382,7 @@ function createChart(element, options = {}) {
     return canvas.toDataURL(options2.type ?? "image/png", options2.quality);
   };
   const destroy = () => {
+    cancelViewportTween();
     cancelLongPressTimer();
     datafeedUnsubscribe?.();
     datafeedUnsubscribe = null;

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

@@ -83,6 +83,9 @@ interface ChartOptions {
     downsampling?: DownsamplingOptions;
     touch?: TouchOptions;
     datafeedOptions?: DatafeedOptions;
+    dataLine?: DataLineOptions;
+    animation?: AnimationOptions;
+    indicatorUpdate?: IndicatorUpdateOptions;
     crosshair?: CrosshairOptions;
     grid?: GridOptions;
     watermark?: WatermarkOptions;
@@ -636,6 +639,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 {
     /**
@@ -1078,4 +1142,4 @@ declare const CHART_THEME_NAMES: ChartThemeName[];
 
 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 AnimationOptions, 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 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 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 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 };