react-native-livechart 4.20.0 → 4.21.0

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/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,

package/src/hooks/useCandleGapPaths.ts

@@ -0,0 +1,88 @@
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { ResolvedCandleGapsConfig } from "../core/resolveConfig";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import { buildCandleGapGeometry } from "../draw/candleGap";
+import type { ChartPadding } from "../draw/line";
+import type { CandleMetrics, CandlePoint } from "../types";
+import { usePathBuilder } from "./usePathBuilder";
+
+/** Batched neutral previous-close paths for each semantic candle-gap kind. */
+export function useCandleGapPaths(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  candles: SharedValue<CandlePoint[]>,
+  liveCandle: SharedValue<CandlePoint | null>,
+  displayCandleWidth: SharedValue<number>,
+  config: ResolvedCandleGapsConfig,
+  metrics: CandleMetrics,
+) {
+  const noTradesBuilder = usePathBuilder();
+  const unavailableBuilder = usePathBuilder();
+  const unknownBuilder = usePathBuilder();
+
+  /* istanbul ignore next -- worklet */
+  const geometry = useDerivedValue(() =>
+    buildCandleGapGeometry(
+      candles.get(),
+      liveCandle.get(),
+      config.gaps,
+      padding,
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get(),
+      engine.timestamp.get() - engine.displayWindow.get(),
+      engine.displayWindow.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      displayCandleWidth.get(),
+      config.styles["no-trades"].bridge !== null,
+      config.styles.unavailable.bridge !== null,
+      config.styles.unknown.bridge !== null,
+      metrics,
+    ),
+  );
+
+  /* istanbul ignore next -- worklet */
+  const noTradesPath = useDerivedValue(() => {
+    const b = noTradesBuilder.get();
+    const marks = geometry.get().marks;
+    for (let i = 0; i < marks.length; i++) {
+      const mark = marks[i];
+      if (mark.kind !== "no-trades") continue;
+      b.moveTo(mark.x1, mark.y);
+      b.lineTo(mark.x2, mark.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unavailablePath = useDerivedValue(() => {
+    const b = unavailableBuilder.get();
+    const marks = geometry.get().marks;
+    for (let i = 0; i < marks.length; i++) {
+      const mark = marks[i];
+      if (mark.kind !== "unavailable") continue;
+      b.moveTo(mark.x1, mark.y);
+      b.lineTo(mark.x2, mark.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unknownPath = useDerivedValue(() => {
+    const b = unknownBuilder.get();
+    const marks = geometry.get().marks;
+    for (let i = 0; i < marks.length; i++) {
+      const mark = marks[i];
+      if (mark.kind !== "unknown") continue;
+      b.moveTo(mark.x1, mark.y);
+      b.lineTo(mark.x2, mark.y);
+    }
+    return b.detach();
+  });
+
+  return {
+    noTradesPath,
+    unavailablePath,
+    unknownPath,
+  } as const;
+}