react-native-livechart 4.20.0 → 4.21.1

package/src/hooks/useDegen.ts

@@ -13,6 +13,32 @@ import type { SingleEngineState } from "../core/useLiveChartEngine";
 import { computeShake, spawnBurst, tickParticles } from "../math/degenTick";
 import type { DegenShakePayload, Momentum } from "../types";
 
+function resolveDegenSettings(
+  config: ResolvedDegenConfig | null,
+  hasShakeListener: boolean,
+) {
+  return {
+    off: config === null,
+    scale: config?.scale ?? 1,
+    down: config?.downMomentum ?? false,
+    shake: config?.shake ?? true,
+    shakeIntensity: config?.shakeIntensity ?? 1,
+    shakeDurationSec: config?.shakeDurationSec ?? 0.45,
+    slotCount: config?.particleSlotCount ?? 60,
+    burstParticleCount: config?.burstParticleCount ?? 20,
+    particleBurstDurationSec: config?.particleBurstDurationSec ?? 1,
+    drag: config?.drag ?? 0.95,
+    sizeMin: config?.particleSizeMin ?? 1,
+    sizeMax: config?.particleSizeMax ?? 2.2,
+    spreadAngle: config?.spreadAngle ?? Math.PI * 1.2,
+    jitterX: config?.positionJitterX ?? 24,
+    jitterY: config?.positionJitterY ?? 8,
+    speedMin: config?.speedMin ?? 60,
+    speedMax: config?.speedMax ?? 160,
+    hasShakeListener,
+  };
+}
+
 export function useDegen(
   engine: SingleEngineState,
   dotX: SharedValue<number>,
@@ -65,23 +91,26 @@ export function useDegen(
     onShakeRef.current?.({ direction });
   };
 
-  const degenOff = cfg === null;
-  const resolvedScale = cfg?.scale ?? 1;
-  const resolvedDown = cfg?.downMomentum ?? false;
-  const resolvedShake = cfg?.shake ?? true;
-  const resolvedShakeIntensity = cfg?.shakeIntensity ?? 1;
-  const resolvedShakeDurationSec = cfg?.shakeDurationSec ?? 0.45;
-  const resolvedSlotCount = cfg?.particleSlotCount ?? 60;
-  const resolvedBurstParticleCount = cfg?.burstParticleCount ?? 20;
-  const resolvedParticleBurstDurationSec = cfg?.particleBurstDurationSec ?? 1.0;
-  const resolvedDrag = cfg?.drag ?? 0.95;
-  const resolvedSizeMin = cfg?.particleSizeMin ?? 1;
-  const resolvedSizeMax = cfg?.particleSizeMax ?? 2.2;
-  const resolvedSpreadAngle = cfg?.spreadAngle ?? Math.PI * 1.2;
-  const resolvedJitterX = cfg?.positionJitterX ?? 24;
-  const resolvedJitterY = cfg?.positionJitterY ?? 8;
-  const resolvedSpeedMin = cfg?.speedMin ?? 60;
-  const resolvedSpeedMax = cfg?.speedMax ?? 160;
+  const {
+    off,
+    scale,
+    down,
+    shake,
+    shakeIntensity,
+    shakeDurationSec,
+    slotCount,
+    burstParticleCount,
+    particleBurstDurationSec,
+    drag,
+    sizeMin,
+    sizeMax,
+    spreadAngle,
+    jitterX,
+    jitterY,
+    speedMin,
+    speedMax,
+    hasShakeListener,
+  } = resolveDegenSettings(cfg, onShake != null);
 
   useEffect(() => {
     // Mirror the resolved config into SharedValues for the UI-thread worklet.
@@ -90,43 +119,43 @@ export function useDegen(
     // is off, enabledSV is 0 and the frame worklet early-returns (zeroing the
     // particle buffer and shake itself), so the remaining values are inert; the
     // resolved* defaults already stand in for the null-config case.
-    enabledSV.set(degenOff ? 0 : 1);
-    shakeEnabledSV.set(!degenOff && resolvedShake ? 1 : 0);
-    hasOnShakeListenerSV.set(!degenOff && onShake != null ? 1 : 0);
-    scaleSV.set(resolvedScale);
-    downSV.set(resolvedDown ? 1 : 0);
-    shakeIntensitySV.set(resolvedShakeIntensity);
-    shakeDurationSecSV.set(resolvedShakeDurationSec);
-    slotCountSV.set(resolvedSlotCount);
-    burstParticleCountSV.set(resolvedBurstParticleCount);
-    particleBurstDurationSecSV.set(resolvedParticleBurstDurationSec);
-    dragSV.set(resolvedDrag);
-    sizeMinSV.set(resolvedSizeMin);
-    sizeMaxSV.set(resolvedSizeMax);
-    spreadAngleSV.set(resolvedSpreadAngle);
-    jitterXSV.set(resolvedJitterX);
-    jitterYSV.set(resolvedJitterY);
-    speedMinSV.set(resolvedSpeedMin);
-    speedMaxSV.set(resolvedSpeedMax);
+    enabledSV.set(off ? 0 : 1);
+    shakeEnabledSV.set(!off && shake ? 1 : 0);
+    hasOnShakeListenerSV.set(!off && hasShakeListener ? 1 : 0);
+    scaleSV.set(scale);
+    downSV.set(down ? 1 : 0);
+    shakeIntensitySV.set(shakeIntensity);
+    shakeDurationSecSV.set(shakeDurationSec);
+    slotCountSV.set(slotCount);
+    burstParticleCountSV.set(burstParticleCount);
+    particleBurstDurationSecSV.set(particleBurstDurationSec);
+    dragSV.set(drag);
+    sizeMinSV.set(sizeMin);
+    sizeMaxSV.set(sizeMax);
+    spreadAngleSV.set(spreadAngle);
+    jitterXSV.set(jitterX);
+    jitterYSV.set(jitterY);
+    speedMinSV.set(speedMin);
+    speedMaxSV.set(speedMax);
   }, [
-    degenOff,
-    onShake,
-    resolvedScale,
-    resolvedDown,
-    resolvedShake,
-    resolvedShakeIntensity,
-    resolvedShakeDurationSec,
-    resolvedSlotCount,
-    resolvedBurstParticleCount,
-    resolvedParticleBurstDurationSec,
-    resolvedDrag,
-    resolvedSizeMin,
-    resolvedSizeMax,
-    resolvedSpreadAngle,
-    resolvedJitterX,
-    resolvedJitterY,
-    resolvedSpeedMin,
-    resolvedSpeedMax,
+    off,
+    scale,
+    down,
+    shake,
+    shakeIntensity,
+    shakeDurationSec,
+    slotCount,
+    burstParticleCount,
+    particleBurstDurationSec,
+    drag,
+    sizeMin,
+    sizeMax,
+    spreadAngle,
+    jitterX,
+    jitterY,
+    speedMin,
+    speedMax,
+    hasShakeListener,
     // SharedValue refs are stable (useSharedValue), so listing them satisfies
     // exhaustive-deps without ever re-running the effect.
     enabledSV,

package/src/hooks/useLineGapPaths.ts

@@ -0,0 +1,76 @@
+import { useDerivedValue } from "react-native-reanimated";
+import type { ResolvedCandleGapsConfig } from "../core/resolveConfig";
+import type { SingleEngineState } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { buildLineGapGeometry } from "../draw/lineGap";
+import { usePathBuilder } from "./usePathBuilder";
+
+/** Batched flat previous-value bridge paths for each semantic line-gap kind. */
+export function useLineGapPaths(
+  engine: SingleEngineState,
+  padding: ChartPadding,
+  config: ResolvedCandleGapsConfig,
+) {
+  const noTradesBuilder = usePathBuilder();
+  const unavailableBuilder = usePathBuilder();
+  const unknownBuilder = usePathBuilder();
+
+  /* istanbul ignore next -- worklet */
+  const geometry = useDerivedValue(() =>
+    buildLineGapGeometry(
+      engine.data.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(),
+      config.styles["no-trades"].bridge !== null,
+      config.styles.unavailable.bridge !== null,
+      config.styles.unknown.bridge !== null,
+    ),
+  );
+
+  /* istanbul ignore next -- worklet */
+  const noTradesPath = useDerivedValue(() => {
+    const b = noTradesBuilder.get();
+    const bridges = geometry.get().bridges;
+    for (let i = 0; i < bridges.length; i++) {
+      const bridge = bridges[i];
+      if (bridge.kind !== "no-trades") continue;
+      b.moveTo(bridge.x1, bridge.y);
+      b.lineTo(bridge.x2, bridge.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unavailablePath = useDerivedValue(() => {
+    const b = unavailableBuilder.get();
+    const bridges = geometry.get().bridges;
+    for (let i = 0; i < bridges.length; i++) {
+      const bridge = bridges[i];
+      if (bridge.kind !== "unavailable") continue;
+      b.moveTo(bridge.x1, bridge.y);
+      b.lineTo(bridge.x2, bridge.y);
+    }
+    return b.detach();
+  });
+
+  /* istanbul ignore next -- worklet */
+  const unknownPath = useDerivedValue(() => {
+    const b = unknownBuilder.get();
+    const bridges = geometry.get().bridges;
+    for (let i = 0; i < bridges.length; i++) {
+      const bridge = bridges[i];
+      if (bridge.kind !== "unknown") continue;
+      b.moveTo(bridge.x1, bridge.y);
+      b.lineTo(bridge.x2, bridge.y);
+    }
+    return b.detach();
+  });
+
+  return { noTradesPath, unavailablePath, unknownPath } as const;
+}

package/src/hooks/useLiveChartHasData.ts

@@ -1,9 +1,13 @@
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import {
+  hasCandleChartData,
+  hasLineChartData,
+} from "../core/chartDataPresence";
 import type { CandlePoint, LiveChartPoint } from "../types";
 
 /**
- * Data presence for {@link LiveChart}: line mode needs ≥2 points;
- * candle mode needs ≥2 committed candles (`liveCandle` alone does not count).
+ * Data presence for {@link LiveChart}: line mode needs ≥1 point;
+ * candle mode needs ≥1 committed candle (`liveCandle` alone does not count).
  *
  * {@link useChartReveal} seeds its first-paint state off `hasData` directly (in a
  * layout effect), so no JS-thread snapshot is read during render here.
@@ -22,9 +26,9 @@ export function useLiveChartHasData({
   const hasData = useDerivedValue(() => {
     "worklet";
     if (isCandle) {
-      return (candles?.value.length ?? 0) >= 2;
+      return hasCandleChartData(candles?.value);
     }
-    return data.value.length >= 2;
+    return hasLineChartData(data.value);
   });
 
   return { hasData };

package/src/hooks/useReferenceLine.ts

@@ -279,9 +279,10 @@ export function computeReferenceBadgeRect(
 
 /**
  * Derives screen-space layout for a single reference line or band. Supports all
- * three `ReferenceLine` forms (horizontal line, horizontal value band, vertical
- * time band) plus the pill badge for a Form-A value (in-range tag + off-screen
- * chevron pin).
+ * three scalar/band `ReferenceLine` forms (horizontal line, horizontal value
+ * band, vertical time band) plus the pill badge for a Form-A value (in-range tag
+ * + off-screen chevron pin). The series form is handled by
+ * `ReferenceLineSeriesOverlay`.
  */
 export function useReferenceLine(
   engine: ChartEngineLayout,
@@ -344,7 +345,7 @@ export function useReferenceLine(
     const fm = font.getMetrics();
     const baselineOffset = (fm.ascent + fm.descent) / 2;
 
-    // ── Form C — vertical time band (independent of the value range) ─────────
+    // ── Form D — vertical time band (independent of the value range) ─────────
     if (form === "time-band") {
       if (line.from === undefined || line.to === undefined) return INVISIBLE;
       const now = engine.timestamp.value;
@@ -392,7 +393,7 @@ export function useReferenceLine(
     if (valRange <= 0) return INVISIBLE;
     const toY = (v: number) => chartTop + ((dMax - v) / valRange) * chartH;
 
-    // ── Form B — horizontal value band ───────────────────────────────────────
+    // ── Form C — horizontal value band ───────────────────────────────────────
     if (form === "value-band") {
       if (line.valueFrom === undefined || line.valueTo === undefined) {
         return INVISIBLE;

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/useReverseMorphEngineInputs.ts

@@ -3,6 +3,11 @@ import {
   useSharedValue,
   type SharedValue,
 } from "react-native-reanimated";
+import {
+  hasCandleChartData,
+  hasLineChartData,
+  hasMultiSeriesChartData,
+} from "../core/chartDataPresence";
 import type { CandlePoint, LiveChartPoint, SeriesConfig } from "../types";
 
 const STASH_MORPH_EPS = 0.01;
@@ -42,20 +47,19 @@ export function useSingleChartReverseMorphInputs({
       has: hasData.get(),
       m: morphT.get(),
       d: data.get(),
-      cLen: candles?.get().length ?? 0,
       c: candles?.get(),
       lc: liveCandle?.get() ?? null,
     }),
     (curr) => {
       "worklet";
       if (!curr.candle) {
-        if (curr.has && curr.d.length >= 2) {
+        if (curr.has && hasLineChartData(curr.d)) {
           lineStash.set(curr.d.slice());
           lineEngineData.set(curr.d);
         } else if (
           !curr.has &&
           curr.m > STASH_MORPH_EPS &&
-          lineStash.get().length >= 2
+          hasLineChartData(lineStash.get())
         ) {
           lineEngineData.set(lineStash.get());
         } else {
@@ -65,14 +69,14 @@ export function useSingleChartReverseMorphInputs({
       }
 
       const cArr = curr.c;
-      if (curr.has && curr.cLen >= 2 && cArr) {
+      if (curr.has && hasCandleChartData(cArr) && cArr) {
         candleStash.set(cArr.slice());
         candlesEngine.set(cArr);
         liveEngine.set(curr.lc);
       } else if (
         !curr.has &&
         curr.m > STASH_MORPH_EPS &&
-        candleStash.get().length >= 2
+        hasCandleChartData(candleStash.get())
       ) {
         candlesEngine.set(candleStash.get());
         liveEngine.set(null);
@@ -118,27 +122,14 @@ export function useMultiSeriesReverseMorphInputs({
     (curr) => {
       "worklet";
       const live = curr.live;
-
-      let anyReady = false;
-      for (let i = 0; i < live.length; i++) {
-        if (live[i].data.length >= 2) {
-          anyReady = true;
-          break;
-        }
-      }
+      const anyReady = hasMultiSeriesChartData(live);
 
       if (curr.has && anyReady) {
         seriesStash.set(snapshotSeriesWorklet(live));
         effectiveSeries.set(live);
       } else {
-        let stashReady = false;
         const stash = seriesStash.get();
-        for (let i = 0; i < stash.length; i++) {
-          if (stash[i].data.length >= 2) {
-            stashReady = true;
-            break;
-          }
-        }
+        const stashReady = hasMultiSeriesChartData(stash);
 
         if (!curr.has && curr.m > STASH_MORPH_EPS && stashReady) {
           effectiveSeries.set(seriesStash.get());

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/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,
@@ -100,6 +114,7 @@ export type {
   SeriesConfig,
   ThemeMode,
   ThresholdConfig,
+  ThresholdBadgeRenderProps,
   ThresholdLineConfig,
   TooltipRenderProps,
   TradeEvent,