react-native-livechart 4.19.0 → 4.21.0

package/src/hooks/useReferenceLineSeries.ts

@@ -0,0 +1,101 @@
+import { useRef } from "react";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { interpolateAtTime } from "../math/interpolate";
+import { buildReferenceLineSeriesPoints } from "../math/referenceLineSeries";
+import {
+  thresholdLineY,
+  thresholdSeriesVisible,
+  thresholdVisible,
+} from "../math/threshold";
+import type { LiveChartPoint } from "../types";
+
+export interface ReferenceLineSeriesGeometry {
+  /** Visible series polyline as `[x, y, …]` screen coordinates. */
+  screenPts: SharedValue<number[]>;
+  /** Whether any series segment crosses the visible plot. */
+  visible: SharedValue<boolean>;
+  /** Series value at the chart's current right edge. */
+  currentValue: SharedValue<number>;
+  /** Canvas Y coordinate of {@link currentValue}. */
+  currentY: SharedValue<number>;
+  /** Whether the current-value label belongs inside the visible plot. */
+  currentVisible: SharedValue<boolean>;
+}
+
+/**
+ * UI-thread geometry for a static historical reference-line series. Point
+ * buffers ping-pong so Reanimated observes a changed array reference each frame
+ * without allocating new intermediate arrays.
+ */
+export function useReferenceLineSeries(
+  engine: ChartEngineLayout,
+  padding: ChartPadding,
+  points: LiveChartPoint[],
+  extendToNow: boolean,
+): ReferenceLineSeriesGeometry {
+  const cacheRef = useRef<{
+    a: number[];
+    b: number[];
+    tick: boolean;
+  } | null>(null);
+  if (cacheRef.current === null) {
+    cacheRef.current = { a: [], b: [], tick: false };
+  }
+
+  const screenPts = useDerivedValue(() => {
+    const cache = cacheRef.current!;
+    cache.tick = !cache.tick;
+    return buildReferenceLineSeriesPoints(
+      points,
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasWidth.get(),
+      engine.canvasHeight.get(),
+      padding,
+      extendToNow,
+      cache.tick ? cache.a : cache.b,
+    );
+  });
+
+  const visible = useDerivedValue(() =>
+    thresholdSeriesVisible(
+      screenPts.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+
+  const currentValue = useDerivedValue(
+    () => interpolateAtTime(points, engine.timestamp.get()) ?? NaN,
+  );
+  const currentY = useDerivedValue(() =>
+    thresholdLineY(
+      currentValue.get(),
+      engine.displayMin.get(),
+      engine.displayMax.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    ),
+  );
+  const currentVisible = useDerivedValue(() => {
+    if (points.length === 0) return false;
+    if (!extendToNow && points[points.length - 1].time < engine.timestamp.get()) {
+      return false;
+    }
+    return thresholdVisible(
+      currentY.get(),
+      engine.canvasHeight.get(),
+      padding.top,
+      padding.bottom,
+    );
+  });
+
+  return { screenPts, visible, currentValue, currentY, currentVisible };
+}

package/src/hooks/useThreshold.ts

@@ -95,15 +95,15 @@ export interface ThresholdSeriesGeometry {
   samples: SharedValue<number[]>;
   /** Whether any of the polyline is on-screen (drives marker-line opacity). */
   visible: SharedValue<boolean>;
-  /** Threshold value at `now` (flat-extended past the last point) — the badge label. */
-  currentValue: SharedValue<number>;
-  /** Pixel-Y of `currentValue` — anchors the badge. */
-  currentLineY: SharedValue<number>;
-  /** Whether the badge should show: `currentLineY` on-plot AND, with
-   *  `extendToNow` off, "now" not past the series' last point. (`visible` can be
-   *  true for the polyline while the value-at-now sits outside the plot; the
-   *  badge must not draw into the gutters then.) */
-  currentVisible: SharedValue<boolean>;
+  /** Threshold value at the configured badge anchor: the visible window's
+   *  left edge (`"first"`) or its live/right edge (`"last"`). */
+  badgeValue: SharedValue<number>;
+  /** Pixel-Y of `badgeValue` — anchors the badge. */
+  badgeLineY: SharedValue<number>;
+  /** Whether the configured badge anchor is on-plot and belongs to a visible
+   *  part of the threshold. (`visible` can still be true when that one endpoint
+   *  is off-plot.) */
+  badgeVisible: SharedValue<boolean>;
   /** Pixel-X where the threshold ends: the last point's X with `extendToNow`
    *  off, else {@link THRESHOLD_NO_CLIP}. The shader paints its plain
    *  `restColor` right of it; the marker polyline stops there. */
@@ -118,9 +118,9 @@ const EMPTY_SAMPLES: number[] = new Array(THRESHOLD_SAMPLE_COUNT).fill(0);
  * Per-frame screen geometry for a **time-varying** threshold — a plain
  * `LiveChartPoint[]` `value` or a live `SharedValue<LiveChartPoint[]>` `series`
  * (which wins when both are given): the screen polyline (marker line +
- * fill-band bottom), the shader's pixel-Y `samples[]`, the current value/anchor
- * for the badge, and the `extendToNow` cutoff X. The array buffers ping-pong
- * (Reanimated only re-notifies subscribers when the returned reference
+ * fill-band bottom), the shader's pixel-Y `samples[]`, the configured endpoint
+ * value/anchor for the badge, and the `extendToNow` cutoff X. The array buffers
+ * ping-pong (Reanimated only re-notifies subscribers when the returned reference
  * changes). When the threshold is a constant `SharedValue<number>` every
  * worklet short-circuits cheaply and {@link useThreshold} drives the render
  * instead.
@@ -131,6 +131,7 @@ export function useThresholdSeries(
   value: ThresholdValue,
   series: SharedValue<LiveChartPoint[]> | null = null,
   extendToNow = true,
+  labelAnchor: "first" | "last" = "last",
 ): ThresholdSeriesGeometry {
   const cacheRef = useRef<{
     ptsA: number[];
@@ -238,15 +239,19 @@ export function useThresholdSeries(
     );
   });
 
-  const currentValue = useDerivedValue(() => {
+  const badgeValue = useDerivedValue(() => {
     const pts = series ? series.get() : Array.isArray(value) ? value : null;
     if (pts === null) return NaN;
-    return interpolateAtTime(pts, engine.timestamp.get()) ?? NaN;
+    const time =
+      labelAnchor === "first"
+        ? engine.timestamp.get() - engine.displayWindow.get()
+        : engine.timestamp.get();
+    return interpolateAtTime(pts, time) ?? NaN;
   });
 
-  const currentLineY = useDerivedValue(() =>
+  const badgeLineY = useDerivedValue(() =>
     thresholdLineY(
-      currentValue.get(),
+      badgeValue.get(),
       engine.displayMin.get(),
       engine.displayMax.get(),
       engine.canvasHeight.get(),
@@ -255,15 +260,19 @@ export function useThresholdSeries(
     ),
   );
 
-  const currentVisible = useDerivedValue(() => {
-    if (!extendToNow) {
+  const badgeVisible = useDerivedValue(() => {
+    if (labelAnchor === "first") {
+      // If the non-extended series ended before this window, there is no left
+      // endpoint to label even though interpolation can still clamp a value.
+      if (screenPts.get().length < 4) return false;
+    } else if (!extendToNow) {
       // The threshold ends at its last point — no badge past it.
       const pts = series ? series.get() : Array.isArray(value) ? value : null;
       if (pts === null || pts.length === 0) return false;
       if (pts[pts.length - 1].time < engine.timestamp.get()) return false;
     }
     return thresholdVisible(
-      currentLineY.get(),
+      badgeLineY.get(),
       engine.canvasHeight.get(),
       padding.top,
       padding.bottom,
@@ -274,9 +283,9 @@ export function useThresholdSeries(
     screenPts,
     samples,
     visible,
-    currentValue,
-    currentLineY,
-    currentVisible,
+    badgeValue,
+    badgeLineY,
+    badgeVisible,
     clipRightX,
   };
 }

package/src/hooks/useYAxis.ts

@@ -20,6 +20,7 @@ export function useYAxis(
   minGap = 36,
   gridMetrics: GridMetrics = GRID_METRICS_DEFAULTS,
   count = 0,
+  intervalScale = 1,
 ) {
   const prevInterval = useSharedValue(0);
   const labelAlphas = useSharedValue<Record<number, number>>({});
@@ -41,6 +42,7 @@ export function useYAxis(
       minGap,
       gridMetrics,
       count,
+      intervalScale,
     );
 
     prevInterval.set(result.interval);

package/src/index.ts

@@ -39,9 +39,23 @@ export type {
   BadgeMetrics,
   BadgeStyleConfig,
   BadgeVariant,
+  CandleGap,
+  CandleGapBandStyle,
+  CandleGapBridgeStyle,
+  CandleGapKind,
+  CandleGapLabelStyle,
+  CandleGapStyle,
+  CandleGapsConfig,
   CandleMetrics,
   CandlePoint,
   CanvasMode,
+  ChartGap,
+  ChartGapBandStyle,
+  ChartGapBridgeStyle,
+  ChartGapKind,
+  ChartGapLabelStyle,
+  ChartGapsConfig,
+  ChartGapStyle,
   ChartInsets,
   ChartOverlayContext,
   ChartPlotRect,
@@ -61,6 +75,7 @@ export type {
   LegendStyle,
   LineConfig,
   LiveChartCoreProps,
+  LiveChartHandle,
   LiveChartMetrics,
   LiveChartMetricsOverride,
   LiveChartPalette,
@@ -99,6 +114,7 @@ export type {
   SeriesConfig,
   ThemeMode,
   ThresholdConfig,
+  ThresholdBadgeRenderProps,
   ThresholdLineConfig,
   TooltipRenderProps,
   TradeEvent,

package/src/math/candleGaps.ts

@@ -0,0 +1,120 @@
+import type { CandleGap, CandleGapKind, CandlePoint } from "../types";
+
+/** Built-in, overridable copy for gap bands and scrub tooltips. */
+export function candleGapDefaultLabel(kind: CandleGapKind): string {
+  "worklet";
+  if (kind === "no-trades") return "No trades";
+  if (kind === "unavailable") return "Trading unavailable";
+  return "Data unavailable";
+}
+
+/** Find the explicit half-open gap containing `time`. Input must be start-sorted. */
+export function pickCandleGapAtTime(
+  gaps: CandleGap[],
+  time: number,
+): CandleGap | null {
+  "worklet";
+  let lo = 0;
+  let hi = gaps.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (gaps[mid].from <= time) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  if (hi < 0) return null;
+  const gap = gaps[hi];
+  return time >= gap.from && time < gap.to ? gap : null;
+}
+
+/** Latest real candle strictly before `time`, preferring a newer live candle. */
+export function previousCandleAtTime(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  time: number,
+): CandlePoint | null {
+  "worklet";
+  let lo = 0;
+  let hi = candles.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (candles[mid].time < time) lo = mid + 1;
+    else hi = mid;
+  }
+  let result = lo > 0 ? candles[lo - 1] : null;
+  if (
+    liveCandle &&
+    liveCandle.time < time &&
+    (!result || liveCandle.time > result.time)
+  ) {
+    result = liveCandle;
+  }
+  return result;
+}
+
+/** Previous observed close for a bridged gap; `null` when no anchor exists. */
+export function previousCandleCloseAtTime(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  time: number,
+): number | null {
+  "worklet";
+  return previousCandleAtTime(candles, liveCandle, time)?.close ?? null;
+}
+
+/** Whether a real candle starts in the bucket beginning at `bucketTime`. */
+export function candleAtBucketTime(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  bucketTime: number,
+  candleWidthSecs: number,
+): CandlePoint | null {
+  "worklet";
+  let lo = 0;
+  let hi = candles.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const t = candles[mid].time;
+    if (t < bucketTime) lo = mid + 1;
+    else if (t > bucketTime) hi = mid - 1;
+    else return candles[mid];
+  }
+  if (
+    liveCandle &&
+    Math.abs(liveCandle.time - bucketTime) < candleWidthSecs * 1e-6
+  ) {
+    return liveCandle;
+  }
+  return null;
+}
+
+/**
+ * Bucket start under `time`, aligned to the nearest preceding real candle.
+ * Returns `null` for a partial edge bucket, a bucket with real OHLC, or a gap
+ * without a previous-close anchor.
+ */
+export function candleGapBucketStartAtTime(
+  gap: CandleGap,
+  time: number,
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  candleWidthSecs: number,
+): number | null {
+  "worklet";
+  if (
+    candleWidthSecs <= 0 ||
+    time < gap.from ||
+    time >= gap.to ||
+    gap.kind !== "no-trades"
+  ) {
+    return null;
+  }
+  const previous = previousCandleAtTime(candles, liveCandle, time);
+  if (!previous) return null;
+  const steps = Math.floor((time - previous.time) / candleWidthSecs);
+  const bucket = previous.time + steps * candleWidthSecs;
+  if (bucket < gap.from || bucket + candleWidthSecs > gap.to) return null;
+  if (candleAtBucketTime(candles, liveCandle, bucket, candleWidthSecs)) {
+    return null;
+  }
+  return bucket;
+}

package/src/math/referenceLineSeries.ts

@@ -0,0 +1,83 @@
+import type { ChartPadding } from "../draw/line";
+import type { LiveChartPoint } from "../types";
+import { interpolateAtTime } from "./interpolate";
+import { thresholdLineY } from "./threshold";
+
+/**
+ * Project a historical reference-line series into screen-space `[x, y, …]`
+ * points for the visible time window. Window-edge values are interpolated so
+ * the path enters and leaves the plot cleanly. The series clamps to its first
+ * value on the left and, by default, to its last value at the live edge.
+ *
+ * Worklet-safe. When `out` is supplied it is cleared and reused.
+ */
+export function buildReferenceLineSeriesPoints(
+  points: LiveChartPoint[],
+  now: number,
+  windowSecs: number,
+  displayMin: number,
+  displayMax: number,
+  canvasWidth: number,
+  canvasHeight: number,
+  padding: ChartPadding,
+  extendToNow: boolean,
+  out?: number[],
+): number[] {
+  "worklet";
+  const result = out ?? [];
+  result.length = 0;
+
+  const plotLeft = padding.left;
+  const plotRight = canvasWidth - padding.right;
+  const plotWidth = plotRight - plotLeft;
+  const plotHeight = canvasHeight - padding.top - padding.bottom;
+  const valueRange = displayMax - displayMin;
+  if (
+    points.length === 0 ||
+    !(windowSecs > 0) ||
+    plotWidth <= 0 ||
+    plotHeight <= 0 ||
+    !(valueRange > 0)
+  ) {
+    return result;
+  }
+
+  const windowStart = now - windowSecs;
+  const lastTime = points[points.length - 1].time;
+  const endTime = extendToNow ? now : Math.min(now, lastTime);
+  if (endTime < windowStart) return result;
+
+  const startValue = interpolateAtTime(points, windowStart);
+  const endValue = interpolateAtTime(points, endTime);
+  if (
+    startValue === null ||
+    endValue === null ||
+    !Number.isFinite(startValue) ||
+    !Number.isFinite(endValue)
+  ) {
+    return result;
+  }
+
+  const toX = (time: number) =>
+    plotLeft + ((time - windowStart) / windowSecs) * plotWidth;
+  const toY = (value: number) =>
+    thresholdLineY(
+      value,
+      displayMin,
+      displayMax,
+      canvasHeight,
+      padding.top,
+      padding.bottom,
+    );
+
+  result.push(plotLeft, toY(startValue));
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i];
+    if (point.time <= windowStart) continue;
+    if (point.time >= endTime) break;
+    if (!Number.isFinite(point.time) || !Number.isFinite(point.value)) continue;
+    result.push(toX(point.time), toY(point.value));
+  }
+  result.push(toX(endTime), toY(endValue));
+  return result;
+}

package/src/math/referenceLines.ts

@@ -4,16 +4,22 @@ import type {
   ReferenceLineBadgeConfig,
 } from "../types";
 
-/** Which of the three reference-line forms a `ReferenceLine` resolves to. */
-export type ReferenceLineForm = "line" | "value-band" | "time-band" | "none";
+/** Which of the four reference-line forms a `ReferenceLine` resolves to. */
+export type ReferenceLineForm =
+  | "line"
+  | "series"
+  | "value-band"
+  | "time-band"
+  | "none";
 
 /**
- * Classify a `ReferenceLine` into one of its three forms, applying the
- * documented precedence A (line) > B (value band) > C (time band).
+ * Classify a `ReferenceLine` into one of its four forms, applying the
+ * documented precedence A (line) > B (series) > C (value band) > D (time band).
  */
 export function referenceLineForm(rl: ReferenceLine): ReferenceLineForm {
   "worklet";
   if (rl.value !== undefined) return "line";
+  if (rl.series !== undefined) return "series";
   if (rl.valueFrom !== undefined && rl.valueTo !== undefined) {
     return "value-band";
   }
@@ -24,7 +30,7 @@ export function referenceLineForm(rl: ReferenceLine): ReferenceLineForm {
 /**
  * Gather every Y value a set of reference lines should contribute to the
  * axis-range computation. Lines flagged `excludeFromRange` are skipped, as are
- * time bands (Form C) which constrain time, not value.
+ * time bands (Form D) which constrain time, not value.
  */
 export function collectReferenceValues(lines: ReferenceLine[]): number[] {
   const out: number[] = [];
@@ -35,6 +41,22 @@ export function collectReferenceValues(lines: ReferenceLine[]): number[] {
       case "line":
         out.push(rl.value as number);
         break;
+      case "series": {
+        const points = rl.series;
+        if (!points || points.length === 0) break;
+        let min = Infinity;
+        let max = -Infinity;
+        for (let j = 0; j < points.length; j++) {
+          const value = points[j].value;
+          if (!Number.isFinite(value)) continue;
+          if (value < min) min = value;
+          if (value > max) max = value;
+        }
+        // Only the extrema are needed by the engine, avoiding a per-frame scan
+        // through the full historical annotation series.
+        if (min !== Infinity) out.push(min, max);
+        break;
+      }
       case "value-band":
         out.push(rl.valueFrom as number, rl.valueTo as number);
         break;
@@ -56,7 +78,13 @@ export function referenceLineReactKeys(
   const occurrences = new Map<string, number>();
   const keys: string[] = [];
   for (const line of lines) {
-    const base = line.id ?? stableReferenceLineSignature(line);
+    // A series' samples are render data, not identity. Omitting their contents
+    // keeps a growing historical series from remounting its overlay every render.
+    const base =
+      line.id ??
+      stableReferenceLineSignature(
+        line.series === undefined ? line : { ...line, series: "series" },
+      );
     const occurrence = occurrences.get(base) ?? 0;
     occurrences.set(base, occurrence + 1);
     keys.push(`${base}:${occurrence}`);

package/src/math/spline.ts

@@ -56,16 +56,26 @@ export function drawSpline(
   /** Straight polyline (`lineTo` per point) instead of the monotone cubic — an
    *  angular, hard-edged line. The caller has already `moveTo`'d point 0. */
   linear = false,
+  /** First point index to draw (inclusive). The caller must moveTo this point. */
+  startPoint = 0,
+  /** Last point index to draw (exclusive). Defaults to the full array. */
+  endPoint = pts.length >> 1,
 ) {
   "worklet";
-  const n = pts.length >> 1;
+  const start = Math.max(0, startPoint);
+  const end = Math.min(pts.length >> 1, endPoint);
+  const n = end - start;
   if (n < 2) return;
   if (linear) {
-    for (let i = 1; i < n; i++) path.lineTo(pts[i * 2], pts[i * 2 + 1]);
+    for (let i = 1; i < n; i++) {
+      const point = (start + i) * 2;
+      path.lineTo(pts[point], pts[point + 1]);
+    }
     return;
   }
   if (n === 2) {
-    path.lineTo(pts[2], pts[3]);
+    const point = (start + 1) * 2;
+    path.lineTo(pts[point], pts[point + 1]);
     return;
   }
 
@@ -73,7 +83,7 @@ export function drawSpline(
   const delta: number[] = scratch ? scratch.delta : new Array(n - 1);
   const h: number[] = scratch ? scratch.h : new Array(n - 1);
   for (let i = 0; i < n - 1; i++) {
-    const i2 = i * 2;
+    const i2 = (start + i) * 2;
     const j2 = i2 + 2;
     h[i] = pts[j2] - pts[i2];
     delta[i] = h[i] === 0 ? 0 : (pts[j2 + 1] - pts[i2 + 1]) / h[i];
@@ -110,7 +120,7 @@ export function drawSpline(
 
   // 4. Draw bezier curves
   for (let i = 0; i < n - 1; i++) {
-    const i2 = i * 2;
+    const i2 = (start + i) * 2;
     const j2 = i2 + 2;
     const hi = h[i];
     path.cubicTo(