react-native-livechart 4.19.0 → 4.21.0

package/src/core/useLiveChartEngine.ts

@@ -17,7 +17,12 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 import { MS_PER_FRAME_60FPS, RETURN_TO_LIVE_MS } from "../constants";
-import type { CandlePoint, LiveChartPoint, SeriesConfig } from "../types";
+import type {
+  CandleGap,
+  CandlePoint,
+  LiveChartPoint,
+  SeriesConfig,
+} from "../types";
 import {
   tickLiveChartEngineFrame,
   type EngineTickInput,
@@ -95,6 +100,10 @@ export interface EngineConfig {
   mode?: "line" | "candle";
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
+  candleGaps?: CandleGap[];
+  candleGapBridgeNoTrades?: boolean;
+  candleGapBridgeUnavailable?: boolean;
+  candleGapBridgeUnknown?: boolean;
 }
 
 /** Canvas, time window, and Y-range — shared by single- and multi-series engines. */
@@ -238,6 +247,10 @@ export interface EngineFrameRefs {
   modeSV: SharedValue<"line" | "candle">;
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
+  candleGapsSV?: SharedValue<CandleGap[] | undefined>;
+  candleGapBridgeNoTradesSV?: SharedValue<boolean>;
+  candleGapBridgeUnavailableSV?: SharedValue<boolean>;
+  candleGapBridgeUnknownSV?: SharedValue<boolean>;
   extremaMinValue: SharedValue<number>;
   extremaMaxValue: SharedValue<number>;
   extremaMinTime: SharedValue<number>;
@@ -359,6 +372,12 @@ export function applyLiveChartEngineFrame(
   input.mode = sv.modeSV.value;
   input.candles = sv.candles?.value;
   input.liveCandle = sv.liveCandle?.value;
+  input.candleGaps = sv.candleGapsSV?.value;
+  input.candleGapBridgeNoTrades =
+    sv.candleGapBridgeNoTradesSV?.value ?? false;
+  input.candleGapBridgeUnavailable =
+    sv.candleGapBridgeUnavailableSV?.value ?? false;
+  input.candleGapBridgeUnknown = sv.candleGapBridgeUnknownSV?.value ?? false;
   tickLiveChartEngineFrame(state, input);
   sv.displayValue.value = state.displayValue;
   sv.displayMin.value = state.displayMin;
@@ -452,6 +471,16 @@ export function useLiveChartEngine(
     () => config.returnToLiveMs ?? RETURN_TO_LIVE_MS,
   );
   const modeSV = useDerivedValue(() => config.mode ?? "line");
+  const candleGapsSV = useDerivedValue(() => config.candleGaps);
+  const candleGapBridgeNoTradesSV = useDerivedValue(
+    () => config.candleGapBridgeNoTrades ?? false,
+  );
+  const candleGapBridgeUnavailableSV = useDerivedValue(
+    () => config.candleGapBridgeUnavailable ?? false,
+  );
+  const candleGapBridgeUnknownSV = useDerivedValue(
+    () => config.candleGapBridgeUnknown ?? false,
+  );
 
   // Animation state (mutated on UI thread each frame)
   const displayValue = useSharedValue(0);
@@ -548,15 +577,18 @@ export function useLiveChartEngine(
     modeSV,
     candles,
     liveCandle,
+    candleGapsSV,
+    candleGapBridgeNoTradesSV,
+    candleGapBridgeUnavailableSV,
+    candleGapBridgeUnknownSV,
     extremaMinValue,
     extremaMaxValue,
     extremaMinTime,
     extremaMaxTime,
   };
-  const frameScratchRef = useRef<EngineFrameScratch | null>(null);
-  if (frameScratchRef.current === null) {
-    frameScratchRef.current = makeEngineFrameScratch();
-  }
+  const [frameScratchRef] = useState(() => ({
+    current: makeEngineFrameScratch(),
+  }));
 
   // `autostart=false` registers the frame callback without running it — the live
   // loop is fully inert in static mode (the invariant that makes this worth it).

package/src/draw/candle.ts

@@ -80,7 +80,7 @@ function candleValueToY(
  * repainting only the selected body and wick without building another SkPath.
  */
 export function computeCandleFocusClip(
-  candle: CandlePoint | null,
+  candle: { time: number } | null,
   padding: ChartPadding,
   canvasW: number,
   canvasH: number,

package/src/draw/candleGap.ts

@@ -0,0 +1,132 @@
+import { CANDLE_METRICS_DEFAULTS } from "../constants";
+import {
+  candleAtBucketTime,
+  previousCandleAtTime,
+  previousCandleCloseAtTime,
+} from "../math/candleGaps";
+import type {
+  CandleGap,
+  CandleGapKind,
+  CandleMetrics,
+  CandlePoint,
+} from "../types";
+import type { ChartPadding } from "./line";
+
+export interface CandleGapMark {
+  x1: number;
+  x2: number;
+  y: number;
+  kind: CandleGapKind;
+}
+
+export interface CandleGapGeometry {
+  marks: CandleGapMark[];
+}
+
+/** Pure worklet geometry for neutral previous-close marks in explicit gaps. */
+export function buildCandleGapGeometry(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  gaps: CandleGap[],
+  padding: ChartPadding,
+  canvasW: number,
+  canvasH: number,
+  winStart: number,
+  windowSecs: number,
+  displayMin: number,
+  displayMax: number,
+  candleWidthSecs: number,
+  bridgeNoTrades: boolean,
+  bridgeUnavailable: boolean,
+  bridgeUnknown: boolean,
+  metrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+): CandleGapGeometry {
+  "worklet";
+  const chartW = canvasW - padding.left - padding.right;
+  const chartH = canvasH - padding.top - padding.bottom;
+  const valueRange = displayMax - displayMin;
+  if (
+    chartW <= 0 ||
+    chartH <= 0 ||
+    valueRange <= 0 ||
+    windowSecs <= 0 ||
+    candleWidthSecs <= 0
+  ) {
+    return { marks: [] };
+  }
+
+  const slotPx = (candleWidthSecs / windowSecs) * chartW;
+  const bodyW = Math.max(
+    1,
+    Math.min(
+      slotPx * metrics.bodyWidthRatio,
+      slotPx - metrics.minGapPx,
+      metrics.maxBodyPx,
+    ),
+  );
+  const winEnd = winStart + windowSecs;
+  const chartLeft = padding.left;
+  const chartRight = canvasW - padding.right;
+  const marks: CandleGapMark[] = [];
+
+  for (let gi = 0; gi < gaps.length; gi++) {
+    const gap = gaps[gi];
+    if (gap.from >= winEnd || gap.to <= winStart) continue;
+    const bridge =
+      gap.kind === "no-trades"
+        ? bridgeNoTrades
+        : gap.kind === "unavailable"
+          ? bridgeUnavailable
+          : bridgeUnknown;
+    if (!bridge) continue;
+
+    const seedTime = Math.max(gap.from, winStart - candleWidthSecs);
+    const previous = previousCandleAtTime(candles, liveCandle, seedTime);
+    const origin =
+      previous?.time ?? candles[0]?.time ?? liveCandle?.time ?? gap.from;
+    let bucket =
+      origin +
+      Math.ceil((gap.from - origin) / candleWidthSecs - 1e-9) *
+        candleWidthSecs;
+    if (bucket < gap.from) bucket += candleWidthSecs;
+    if (bucket + candleWidthSecs < winStart) {
+      bucket +=
+        Math.floor((winStart - bucket) / candleWidthSecs) * candleWidthSecs;
+      while (bucket + candleWidthSecs < winStart) bucket += candleWidthSecs;
+    }
+
+    for (
+      ;
+      bucket + candleWidthSecs <= gap.to && bucket <= winEnd;
+      bucket += candleWidthSecs
+    ) {
+      if (
+        candleAtBucketTime(candles, liveCandle, bucket, candleWidthSecs) !== null
+      ) {
+        continue;
+      }
+      const close = previousCandleCloseAtTime(candles, liveCandle, bucket);
+      if (close === null) continue;
+
+      const centerTime = bucket + candleWidthSecs / 2;
+      const centerX =
+        padding.left + ((centerTime - winStart) / windowSecs) * chartW;
+      if (
+        centerX < chartLeft - bodyW / 2 ||
+        centerX > chartRight + bodyW / 2
+      ) {
+        continue;
+      }
+      const y =
+        padding.top + ((displayMax - close) / valueRange) * chartH;
+      marks.push({
+        x1: Math.max(chartLeft, centerX - bodyW / 2),
+        x2: Math.min(chartRight, centerX + bodyW / 2),
+        y,
+        kind: gap.kind,
+      });
+    }
+  }
+
+  return { marks };
+}

package/src/draw/grid.ts

@@ -89,6 +89,7 @@ export function pickInterval(
   prev: number,
 ): number {
   "worklet";
+  if (!Number.isFinite(valRange) || !Number.isFinite(pxPerUnit)) return 0;
   if (prev > 0) {
     const px = prev * pxPerUnit;
     if (px >= minGap * 0.5 && px <= minGap * 4) return prev;
@@ -103,6 +104,9 @@ export function pickInterval(
   for (let s = 0; s < divisorSets.length; s++) {
     const divs = divisorSets[s];
     let span = Math.pow(10, Math.ceil(Math.log10(valRange)));
+    // `10 ** ceil(log10(Number.MAX_VALUE))` overflows even though the input is
+    // finite. Starting from the range itself preserves a finite upper bound.
+    if (!Number.isFinite(span) && valRange > 0) span = valRange;
     let i = 0;
     while ((span / divs[i % 3]) * pxPerUnit >= minGap) {
       span /= divs[i % 3];
@@ -165,6 +169,7 @@ export function computeGridEntries(
   minGap = 36,
   grid: GridMetrics = GRID_METRICS_DEFAULTS,
   count = 0,
+  intervalScale = 1,
 ): { entries: YAxisEntry[]; interval: number } {
   "worklet";
   const chartH = canvasHeight - padTop - padBottom;
@@ -194,7 +199,29 @@ export function computeGridEntries(
 
   const pxPerUnit = chartH / valRange;
 
-  const coarse = pickInterval(valRange, pxPerUnit, minGap, prevInterval);
+  let appliedIntervalScale = intervalScale;
+  let scaledRange = valRange * appliedIntervalScale;
+  let pxPerScaledUnit = pxPerUnit / appliedIntervalScale;
+  // A positive finite multiplier can still overflow/underflow when combined
+  // with the live range. Fall back to source-unit interval selection so an
+  // unrepresentable display range cannot poison or freeze this UI worklet.
+  if (
+    !Number.isFinite(scaledRange) ||
+    scaledRange <= 0 ||
+    !Number.isFinite(pxPerScaledUnit) ||
+    pxPerScaledUnit <= 0
+  ) {
+    appliedIntervalScale = 1;
+    scaledRange = valRange;
+    pxPerScaledUnit = pxPerUnit;
+  }
+  const interval = pickInterval(
+    scaledRange,
+    pxPerScaledUnit,
+    minGap,
+    appliedIntervalScale === intervalScale ? prevInterval : 0,
+  );
+  const coarse = interval / appliedIntervalScale;
   const fine = coarse / 2;
   const finePx = fine * pxPerUnit;
   const fineTarget = fineLineTargetAlpha(finePx, minGap);
@@ -227,7 +254,10 @@ export function computeGridEntries(
       fromEdge >= fadeZone ? 1 : fromEdge <= 0 ? 0 : fromEdge / fadeZone;
 
     const target = (isCoarse ? 1 : fineTarget) * edgeAlpha;
-    const key = Math.round(val * 1e10);
+    // Snap to the exact fine-grid multiple. Unlike a fixed decimal precision,
+    // this keeps adjacent sub-1e-10 source values distinct while remaining
+    // stable when the same line is recomputed on later frames.
+    const key = Math.round(val / fine) * fine;
     targets[key] = target;
   }
 
@@ -265,12 +295,12 @@ export function computeGridEntries(
     const key = Number(allKeys[i]);
     const alpha = labelAlphas[key];
     if (alpha < 0.02) continue;
-    const val = key / 1e10;
+    const val = key;
     const y = gridValueToY(val, displayMax, valRange, padTop, chartH);
     /* istanbul ignore next -- vertical clip; y stays in-band when val comes from tracked keys */
     if (y < padTop - 10 || y > canvasHeight - padBottom + 10) continue;
     entries.push({ y, label: formatValue(val), alpha });
   }
 
-  return { entries, interval: coarse };
+  return { entries, interval };
 }

package/src/draw/lineGap.ts

@@ -0,0 +1,180 @@
+import type { CandleGap, CandleGapKind, LiveChartPoint } from "../types";
+import type { ChartPadding } from "./line";
+
+export interface LineGapBridge {
+  x1: number;
+  x2: number;
+  y: number;
+  kind: CandleGapKind;
+}
+
+export interface LineGapGeometry {
+  bridges: LineGapBridge[];
+}
+
+/** Whether an explicit gap conflicts with at least one real line sample. */
+export function lineGapContainsData(
+  data: LiveChartPoint[],
+  gap: CandleGap,
+): boolean {
+  "worklet";
+  let lo = 0;
+  let hi = data.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (data[mid].time < gap.from) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo < data.length && data[lo].time < gap.to;
+}
+
+/** Latest observed line value strictly before `time`. */
+export function previousLineValueAtTime(
+  data: LiveChartPoint[],
+  time: number,
+): number | null {
+  "worklet";
+  let lo = 0;
+  let hi = data.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (data[mid].time < time) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo > 0 ? data[lo - 1].value : null;
+}
+
+/**
+ * Contiguous point ranges that may be drawn without interpolating across an
+ * explicit empty interval. Each pair is `[startPoint, endPointExclusive]`.
+ * Real samples inside a declared gap make that gap inert, matching the candle
+ * contract that observed market data always wins over presentation metadata.
+ */
+export function buildLineGapSegmentRanges(
+  points: number[],
+  data: LiveChartPoint[],
+  gaps: CandleGap[],
+  winStart: number,
+  windowSecs: number,
+  plotLeft: number,
+  plotWidth: number,
+  out?: number[],
+  gapXsOut?: number[],
+): number[] {
+  "worklet";
+  const ranges = out ?? [];
+  if (out) out.length = 0;
+  const count = points.length >> 1;
+  if (count < 2 || windowSecs <= 0 || plotWidth <= 0) return ranges;
+  if (gaps.length === 0) {
+    ranges.push(0, count);
+    return ranges;
+  }
+
+  const winEnd = winStart + windowSecs;
+  const xScale = plotWidth / windowSecs;
+  const gapXs = gapXsOut ?? [];
+  if (gapXsOut) gapXsOut.length = 0;
+  for (let gi = 0; gi < gaps.length; gi++) {
+    const gap = gaps[gi];
+    if (
+      gap.from >= gap.to ||
+      gap.from >= winEnd ||
+      gap.to <= winStart ||
+      lineGapContainsData(data, gap)
+    ) {
+      continue;
+    }
+    gapXs.push(
+      plotLeft + (gap.from - winStart) * xScale,
+      plotLeft + (gap.to - winStart) * xScale,
+    );
+  }
+  if (gapXs.length === 0) {
+    ranges.push(0, count);
+    return ranges;
+  }
+
+  let segmentStart = 0;
+
+  for (let i = 1; i < count; i++) {
+    const previousX = points[(i - 1) * 2];
+    const currentX = points[i * 2];
+    let breaksHere = false;
+    for (let gi = 0; gi < gapXs.length; gi += 2) {
+      const gapStartX = gapXs[gi];
+      const gapEndX = gapXs[gi + 1];
+      if (previousX <= gapStartX && currentX >= gapEndX) {
+        breaksHere = true;
+        break;
+      }
+    }
+    if (!breaksHere) continue;
+    if (i - segmentStart >= 2) ranges.push(segmentStart, i);
+    segmentStart = i;
+  }
+
+  if (count - segmentStart >= 2) ranges.push(segmentStart, count);
+  return ranges;
+}
+
+/** Pure worklet geometry for flat previous-value bridges in line gaps. */
+export function buildLineGapGeometry(
+  data: LiveChartPoint[],
+  gaps: CandleGap[],
+  padding: ChartPadding,
+  canvasW: number,
+  canvasH: number,
+  winStart: number,
+  windowSecs: number,
+  displayMin: number,
+  displayMax: number,
+  bridgeNoTrades: boolean,
+  bridgeUnavailable: boolean,
+  bridgeUnknown: boolean,
+): LineGapGeometry {
+  "worklet";
+  const plotWidth = canvasW - padding.left - padding.right;
+  const plotHeight = canvasH - padding.top - padding.bottom;
+  const valueRange = displayMax - displayMin;
+  if (plotWidth <= 0 || plotHeight <= 0 || valueRange <= 0 || windowSecs <= 0) {
+    return { bridges: [] };
+  }
+
+  const winEnd = winStart + windowSecs;
+  const plotRight = canvasW - padding.right;
+  const bridges: LineGapBridge[] = [];
+  for (let i = 0; i < gaps.length; i++) {
+    const gap = gaps[i];
+    const bridge =
+      gap.kind === "no-trades"
+        ? bridgeNoTrades
+        : gap.kind === "unavailable"
+          ? bridgeUnavailable
+          : bridgeUnknown;
+    if (
+      !bridge ||
+      gap.from >= gap.to ||
+      gap.from >= winEnd ||
+      gap.to <= winStart ||
+      lineGapContainsData(data, gap)
+    ) {
+      continue;
+    }
+    const previousValue = previousLineValueAtTime(data, gap.from);
+    if (previousValue === null) continue;
+
+    const from = Math.max(gap.from, winStart);
+    const to = Math.min(gap.to, winEnd);
+    const x1 = padding.left + ((from - winStart) / windowSecs) * plotWidth;
+    const x2 = padding.left + ((to - winStart) / windowSecs) * plotWidth;
+    if (x2 <= padding.left || x1 >= plotRight || x2 <= x1) continue;
+    bridges.push({
+      x1: Math.max(padding.left, x1),
+      x2: Math.min(plotRight, x2),
+      y: padding.top + ((displayMax - previousValue) / valueRange) * plotHeight,
+      kind: gap.kind,
+    });
+  }
+  return { bridges };
+}

package/src/hooks/crosshairShared.ts

@@ -4,8 +4,13 @@ import type { DerivedValue, SharedValue } from "react-native-reanimated";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import { type ChartPadding } from "../draw/line";
 import { interpolateAtTime } from "../math/interpolate";
+import {
+  candleGapBucketStartAtTime,
+  candleGapDefaultLabel,
+  pickCandleGapAtTime,
+} from "../math/candleGaps";
 import { pickCandleAtTime } from "../math/pickCandle";
-import type { CandlePoint } from "../types";
+import type { CandleGap, CandlePoint } from "../types";
 
 const TOOLTIP_PAD_X = 8;
 const TOOLTIP_PAD_Y = 6;
@@ -187,6 +192,8 @@ export interface CrosshairState {
    *  inactive) — single-series `useCrosshair` only; undefined on the multi-series
    *  crosshair. Surfaced for a custom candle `renderTooltip`. */
   scrubCandle?: SharedValue<CandlePoint | null>;
+  /** Explicit line or candle gap under the crosshair; single-series only. */
+  scrubGap?: SharedValue<CandleGap | null>;
   /** Canvas-Y where the crosshair line should start so it stops at a top-pinned
    *  custom tooltip's bottom edge instead of running up through it. Written by
    *  {@link CustomTooltipOverlay} (the label's measured bottom) when
@@ -307,6 +314,7 @@ export function snapScrubXToCandleCenter(
   canvasWidth: number,
   timestamp: number,
   windowSecs: number,
+  gaps: CandleGap[] = [],
 ): number {
   "worklet";
   const chartW = canvasWidth - padding.left - padding.right;
@@ -314,7 +322,22 @@ export function snapScrubXToCandleCenter(
   const winStart = timestamp - windowSecs;
   const t = winStart + ((x - padding.left) / chartW) * windowSecs;
   const candle = pickCandleAtTime(candles, liveCandle, t, candleWidthSecs);
-  if (!candle) return x;
+  if (!candle) {
+    const gap = pickCandleGapAtTime(gaps, t);
+    if (!gap) return x;
+    const bucket = candleGapBucketStartAtTime(
+      gap,
+      t,
+      candles,
+      liveCandle,
+      candleWidthSecs,
+    );
+    if (bucket === null) return x;
+    return (
+      padding.left +
+      ((bucket + candleWidthSecs / 2 - winStart) / windowSecs) * chartW
+    );
+  }
   return (
     padding.left +
     ((candle.time + candleWidthSecs / 2 - winStart) / windowSecs) * chartW
@@ -559,16 +582,29 @@ export function computeCandleTooltipLayout(
   formatTime: (t: number) => string,
   font: SkFont,
   monoCharWidth = 0,
+  gap: CandleGap | null = null,
+  gapValue: number | null = null,
 ): TooltipLayout {
   "worklet";
-  if (!scrubActive || !candle) return HIDDEN_TOOLTIP;
-  const lines: { text: string; dim: boolean }[] = [
-    { text: `O ${formatValue(candle.open)}`, dim: false },
-    { text: `H ${formatValue(candle.high)}`, dim: false },
-    { text: `L ${formatValue(candle.low)}`, dim: false },
-    { text: `C ${formatValue(candle.close)}`, dim: false },
-    { text: formatTime(scrubTime), dim: true },
-  ];
+  if (!scrubActive || (!candle && !gap)) return HIDDEN_TOOLTIP;
+  const lines: { text: string; dim: boolean }[] = candle
+    ? [
+        { text: `O ${formatValue(candle.open)}`, dim: false },
+        { text: `H ${formatValue(candle.high)}`, dim: false },
+        { text: `L ${formatValue(candle.low)}`, dim: false },
+        { text: `C ${formatValue(candle.close)}`, dim: false },
+        { text: formatTime(scrubTime), dim: true },
+      ]
+    : [
+        {
+          text: gap?.label ?? candleGapDefaultLabel(gap!.kind),
+          dim: false,
+        },
+        ...(gapValue === null
+          ? []
+          : [{ text: `Last ${formatValue(gapValue)}`, dim: false }]),
+        { text: formatTime(scrubTime), dim: true },
+      ];
   const layout = computeTooltipLayoutMulti(
     scrubActive,
     scrubX,
@@ -582,11 +618,56 @@ export function computeCandleTooltipLayout(
   // OHLC stack renders `stackedLines`, but a custom `renderTooltip` reads
   // `valueStr` / `timeStr` off the layout (same as line mode) — so a custom
   // candle tooltip gets a ready-made close + time without its own formatter.
-  layout.valueStr = formatValue(candle.close);
+  layout.valueStr = candle
+    ? formatValue(candle.close)
+    : gapValue === null
+      ? ""
+      : formatValue(gapValue);
   layout.timeStr = formatTime(scrubTime);
   return layout;
 }
 
+/** Two-row line-mode tooltip for an explicit semantic gap. */
+export function computeLineGapTooltipLayout(
+  scrubActive: boolean,
+  scrubX: number,
+  gap: CandleGap | null,
+  scrubTime: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  formatTime: (t: number) => string,
+  font: SkFont,
+  monoCharWidth = 0,
+  placement: "side" | "top" | "bottom" | "point" = "side",
+  showLabel = true,
+  showTime = true,
+  canvasHeight = 0,
+  margin = TOOLTIP_TOP_MARGIN,
+  scrubDotY = -1,
+): TooltipLayout {
+  "worklet";
+  if (!gap) return HIDDEN_TOOLTIP;
+  const label = gap.label ?? candleGapDefaultLabel(gap.kind);
+  return computeTooltipLayout(
+    scrubActive,
+    scrubX,
+    0,
+    scrubTime,
+    padding,
+    canvasWidth,
+    () => label,
+    formatTime,
+    font,
+    monoCharWidth,
+    placement,
+    showLabel,
+    showTime,
+    canvasHeight,
+    margin,
+    scrubDotY,
+  );
+}
+
 /** Single-series scrub value at window time — extracted for tests. */
 export function deriveScrubValueSingle(
   scrubActive: boolean,