react-native-livechart 4.20.0 → 4.21.0

package/src/components/ReferenceLineOverlay.tsx

@@ -20,6 +20,7 @@ import {
 import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
 import { referenceLineForm, resolveReferenceBadge } from "../math/referenceLines";
 import type { FontConfig, LiveChartPalette, ReferenceLine } from "../types";
+import { ReferenceLineSeriesOverlay } from "./ReferenceLineSeriesOverlay";
 
 /** Translucent fill alpha for value / time bands. */
 const BAND_FILL_OPACITY = 0.16;
@@ -33,9 +34,10 @@ const CONNECTOR_GAP = 4;
 const BADGE_EDGE_INSET = 2;
 
 /**
- * Renders one reference line or band into the chart canvas. Handles all three
- * `ReferenceLine` forms (horizontal line, horizontal value band, vertical time
- * band) plus the Form-A pill badge (in-range tag + off-screen chevron pin).
+ * Renders one reference line or band into the chart canvas. Handles all four
+ * `ReferenceLine` forms (horizontal line, time-varying line, horizontal value
+ * band, vertical time band) plus the Form-A pill badge (in-range tag +
+ * off-screen chevron pin).
  * Self-contained so callers can `.map()` over a variable-length array.
  */
 type ReferenceLineOverlayProps = {
@@ -94,7 +96,28 @@ type ReferenceLineOverlayProps = {
   gridEndGap?: number;
 };
 
-export function ReferenceLineOverlay({
+/**
+ * Dispatch to the series or scalar/band renderer without mixing their hook
+ * lifecycles. A stable `id` may therefore switch forms safely across renders.
+ */
+export function ReferenceLineOverlay(props: ReferenceLineOverlayProps) {
+  if (referenceLineForm(props.line) === "series") {
+    return (
+      <ReferenceLineSeriesOverlay
+        engine={props.engine}
+        padding={props.padding}
+        line={props.line}
+        palette={props.palette}
+        formatValue={props.formatValue}
+        font={props.font}
+        badgeLayer={props.badgeLayer ?? false}
+      />
+    );
+  }
+  return <ReferenceLineStaticOverlay {...props} />;
+}
+
+function ReferenceLineStaticOverlay({
   engine,
   padding,
   line,
@@ -117,6 +140,8 @@ export function ReferenceLineOverlay({
   const isBand = form === "value-band" || form === "time-band";
 
   const color = line.color ?? palette.refLine;
+  const fillColor = line.fillColor ?? color;
+  const strokeOpacity = Math.max(0, Math.min(1, line.strokeOpacity ?? 1));
 
   // Resolved badge appearance (badge config → fallback flat fields → theme).
   const badge = resolveReferenceBadge(line);
@@ -183,6 +208,8 @@ export function ReferenceLineOverlay({
       <ReferenceLineBasePass
         layout={layout}
         color={color}
+        fillColor={fillColor}
+        strokeOpacity={strokeOpacity}
         strokeWidth={strokeWidth}
         intervals={intervals}
         isBand={isBand}
@@ -221,6 +248,8 @@ export function ReferenceLineOverlay({
 function ReferenceLineBasePass({
   layout,
   color,
+  fillColor,
+  strokeOpacity,
   strokeWidth,
   intervals,
   isBand,
@@ -230,6 +259,8 @@ function ReferenceLineBasePass({
 }: {
   layout: SharedValue<ReferenceLineLayout>;
   color: string;
+  fillColor: string;
+  strokeOpacity: number;
   strokeWidth: number;
   intervals: [number, number];
   isBand: boolean;
@@ -282,20 +313,20 @@ function ReferenceLineBasePass({
   });
   const lineOpacity = useDerivedValue(() => {
     const l = layout.get();
-    return l.visible && l.drawLine && !isBand ? 1 : 0;
+    return l.visible && l.drawLine && !isBand ? strokeOpacity : 0;
   });
   const bandOpacity = useDerivedValue(() =>
     layout.get().visible && isBand ? bandFillOpacity : 0,
   );
   const bandBorderOpacity = useDerivedValue(() =>
-    layout.get().visible && hasBandBorder ? 1 : 0,
+    layout.get().visible && hasBandBorder ? strokeOpacity : 0,
   );
 
   return (
     <Group>
       {isBand && (
         <Group opacity={bandOpacity}>
-          <Path path={bandPath} style="fill" color={color} />
+          <Path path={bandPath} style="fill" color={fillColor} />
         </Group>
       )}
       {hasBandBorder && (

package/src/components/ReferenceLineSeriesOverlay.tsx

@@ -0,0 +1,141 @@
+import {
+  DashPathEffect,
+  Group,
+  Path,
+  Text as SkiaText,
+  type SkFont,
+} from "@shopify/react-native-skia";
+import { useDerivedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { usePathBuilder } from "../hooks/usePathBuilder";
+import { useReferenceLineSeries } from "../hooks/useReferenceLineSeries";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import { thresholdDashPhase } from "../math/threshold";
+import type { LiveChartPalette, ReferenceLine } from "../types";
+
+/**
+ * Draws Form-B `ReferenceLine.series` geometry. The base pass is a clipped Skia
+ * polyline behind the chart; the badge pass is the live-edge label above the
+ * chart fade, matching the existing two-pass reference-line layering.
+ */
+export function ReferenceLineSeriesOverlay({
+  engine,
+  padding,
+  line,
+  palette,
+  formatValue,
+  font,
+  badgeLayer,
+}: {
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  line: ReferenceLine;
+  palette: LiveChartPalette;
+  formatValue: (value: number) => string;
+  font: SkFont;
+  badgeLayer: boolean;
+}) {
+  const points = line.series ?? [];
+  const extendToNow = line.extendToNow ?? true;
+  const geometry = useReferenceLineSeries(
+    engine,
+    padding,
+    points,
+    extendToNow,
+  );
+  const color = line.color ?? palette.refLine;
+  const labelColor = line.labelColor ?? line.color ?? palette.refLabel;
+  const strokeOpacity = Math.max(0, Math.min(1, line.strokeOpacity ?? 1));
+  const strokeWidth = line.strokeWidth ?? 1;
+  const intervals = line.intervals ?? [4, 4];
+  const dashCycle = intervals[0] + intervals[1];
+
+  const builder = usePathBuilder();
+  const path = useDerivedValue(() => {
+    const b = builder.value;
+    const screen = geometry.screenPts.get();
+    if (geometry.visible.get() && screen.length >= 4) {
+      b.moveTo(screen[0], screen[1]);
+      for (let i = 2; i < screen.length; i += 2) {
+        b.lineTo(screen[i], screen[i + 1]);
+      }
+    }
+    return b.detach();
+  });
+  const pathOpacity = useDerivedValue(() =>
+    geometry.visible.get() ? strokeOpacity : 0,
+  );
+  const dashPhase = useDerivedValue(() =>
+    thresholdDashPhase(
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      padding.left,
+      engine.canvasWidth.get() - padding.right,
+      dashCycle,
+    ),
+  );
+  const plotClip = useDerivedValue(() => ({
+    x: padding.left,
+    y: padding.top,
+    width: Math.max(0, engine.canvasWidth.get() - padding.left - padding.right),
+    height: Math.max(
+      0,
+      engine.canvasHeight.get() - padding.top - padding.bottom,
+    ),
+  }));
+
+  const metrics = font.getMetrics();
+  const baselineOffset = (metrics.ascent + metrics.descent) / 2;
+  const labelText = useDerivedValue(() => {
+    const value = formatValue(geometry.currentValue.get());
+    if (line.label) return line.showValue ? `${line.label} ${value}` : line.label;
+    return value;
+  });
+  const labelX = useDerivedValue(() => {
+    const left = padding.left;
+    const right = engine.canvasWidth.get() - padding.right;
+    const position = line.labelPosition ?? "right";
+    if (position === "left") return left + 4;
+    if (position === "center") {
+      return (left + right) / 2 - measureFontTextWidth(font, labelText.get()) / 2;
+    }
+    return right + 4;
+  });
+  const labelY = useDerivedValue(
+    () => geometry.currentY.get() - baselineOffset,
+  );
+  const labelOpacity = useDerivedValue(() =>
+    geometry.currentVisible.get() ? 1 : 0,
+  );
+
+  if (badgeLayer) {
+    return (
+      <Group opacity={labelOpacity}>
+        <SkiaText
+          x={labelX}
+          y={labelY}
+          text={labelText}
+          font={font}
+          color={labelColor}
+        />
+      </Group>
+    );
+  }
+
+  return (
+    <Group clip={plotClip} opacity={pathOpacity}>
+      <Path
+        path={path}
+        style="stroke"
+        strokeWidth={strokeWidth}
+        strokeCap="round"
+        strokeJoin="round"
+        color={color}
+      >
+        <DashPathEffect intervals={intervals} phase={dashPhase} />
+      </Path>
+    </Group>
+  );
+}

package/src/core/liveChartEngineTick.ts

@@ -1,8 +1,9 @@
-import type { CandlePoint, LiveChartPoint } from "../types";
+import type { CandleGap, CandlePoint, LiveChartPoint } from "../types";
 
 import { MOTION_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
 import { thresholdRangeMinMax } from "../math/threshold";
+import { previousCandleCloseAtTime } from "../math/candleGaps";
 
 /** Scratch for the threshold range fold — only alive within one tick call. */
 const THRESHOLD_RANGE_SCRATCH: [number, number] = [0, 0];
@@ -131,6 +132,11 @@ export interface EngineTickInput {
   candles?: CandlePoint[];
   /** In-progress candle. Included in Y range when mode is `"candle"`. */
   liveCandle?: CandlePoint | null;
+  /** Explicit semantic gaps used only for previous-close range anchoring. */
+  candleGaps?: CandleGap[];
+  candleGapBridgeNoTrades?: boolean;
+  candleGapBridgeUnavailable?: boolean;
+  candleGapBridgeUnknown?: boolean;
 }
 
 /**
@@ -303,6 +309,33 @@ export function tickLiveChartEngineFrame(
   state.extremaMinTime = hasMin ? minTime : NaN;
   state.extremaMaxTime = hasMax ? maxTime : NaN;
 
+  // A previous-close bridge is presentation, not a traded observation: include
+  // its anchor in the fitted range (so a viewport parked wholly inside an outage
+  // stays framed correctly) only after snapshotting the real-data extrema above.
+  if (input.mode === "candle" && input.candleGaps) {
+    const cs = input.candles ?? [];
+    const lc = input.liveCandle ?? null;
+    for (let i = 0; i < input.candleGaps.length; i++) {
+      const gap = input.candleGaps[i];
+      if (gap.from >= state.timestamp || gap.to <= winStart) continue;
+      const bridge =
+        gap.kind === "no-trades"
+          ? input.candleGapBridgeNoTrades
+          : gap.kind === "unavailable"
+            ? input.candleGapBridgeUnavailable
+            : input.candleGapBridgeUnknown;
+      if (!bridge) continue;
+      const anchor = previousCandleCloseAtTime(
+        cs,
+        lc,
+        Math.min(gap.to, state.timestamp),
+      );
+      if (anchor === null) continue;
+      if (anchor < tMin) tMin = anchor;
+      if (anchor > tMax) tMax = anchor;
+    }
+  }
+
   // Keep the animated live tip inside the range — but only while it's actually
   // in the window. Scrolled back, the live value sits beyond the frozen right
   // edge; folding it in would pin the Y range to the live price and stop the

package/src/core/resolveConfig.ts

@@ -3,6 +3,12 @@ import type {
   AxisLabelConfig,
   BadgeConfig,
   BadgeVariant,
+  CandleGap,
+  CandleGapBandStyle,
+  CandleGapBridgeStyle,
+  CandleGapKind,
+  CandleGapLabelStyle,
+  CandleGapsConfig,
   DegenOptions,
   FontConfig,
   FontWeight,
@@ -114,6 +120,38 @@ export interface ResolvedVolumeConfig {
   opacity: number;
 }
 
+export interface ResolvedCandleGapBridgeStyle {
+  color: string | undefined;
+  opacity: number;
+  strokeWidth: number;
+  strokeCap: "butt" | "round" | "square";
+}
+
+export interface ResolvedCandleGapBandStyle {
+  fillColor: string | undefined;
+  fillOpacity: number;
+  borderColor: string | undefined;
+  borderOpacity: number;
+  borderWidth: number;
+  intervals: [number, number];
+}
+
+export interface ResolvedCandleGapLabelStyle {
+  color: string | undefined;
+  position: "left" | "right";
+}
+
+export interface ResolvedCandleGapStyle {
+  bridge: ResolvedCandleGapBridgeStyle | null;
+  band: ResolvedCandleGapBandStyle | null;
+  label: ResolvedCandleGapLabelStyle | null;
+}
+
+export interface ResolvedCandleGapsConfig {
+  gaps: CandleGap[];
+  styles: Record<CandleGapKind, ResolvedCandleGapStyle>;
+}
+
 /** Resolved straight-line styling (connector, etc.). `color: undefined` → caller default. */
 export interface ResolvedLineStyleConfig {
   color: string | undefined;
@@ -379,6 +417,8 @@ export interface ResolvedThresholdLineConfig {
   label: string | undefined;
   /** Label side; `"left"` sits inside the plot (clear of the y-axis gutter). */
   labelPosition: "left" | "right";
+  /** Series badge value/Y source; `"last"` preserves the live-edge default. */
+  labelAnchor: "first" | "last";
   /** undefined → use palette.refLine (line) / palette.refLabel (label) at render time. */
   color: string | undefined;
   intervals: [number, number];
@@ -415,6 +455,7 @@ export interface ResolvedThresholdConfig {
 const THRESHOLD_LINE_DEFAULTS: ResolvedThresholdLineConfig = {
   label: undefined,
   labelPosition: "left",
+  labelAnchor: "last",
   color: undefined,
   intervals: [4, 4],
   strokeWidth: 1,
@@ -535,6 +576,151 @@ export function resolveVolume(
   return resolveToggle(prop, VOLUME_DEFAULTS, false);
 }
 
+const CANDLE_GAP_BRIDGE_DEFAULTS: ResolvedCandleGapBridgeStyle = {
+  color: undefined,
+  opacity: 0.7,
+  strokeWidth: 2,
+  strokeCap: "round",
+};
+
+const CANDLE_GAP_BAND_DEFAULTS: ResolvedCandleGapBandStyle = {
+  fillColor: undefined,
+  fillOpacity: 0.12,
+  borderColor: undefined,
+  borderOpacity: 1,
+  borderWidth: 2,
+  intervals: [4, 4],
+};
+
+const CANDLE_GAP_LABEL_DEFAULTS: ResolvedCandleGapLabelStyle = {
+  color: undefined,
+  position: "left",
+};
+
+function clampOpacity(value: number): number {
+  return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+
+const CANDLE_GAP_STYLE_DEFAULTS: Record<CandleGapKind, ResolvedCandleGapStyle> = {
+  "no-trades": {
+    bridge: CANDLE_GAP_BRIDGE_DEFAULTS,
+    band: null,
+    label: null,
+  },
+  unavailable: {
+    bridge: { ...CANDLE_GAP_BRIDGE_DEFAULTS, opacity: 0.55 },
+    band: CANDLE_GAP_BAND_DEFAULTS,
+    label: CANDLE_GAP_LABEL_DEFAULTS,
+  },
+  unknown: {
+    bridge: null,
+    band: {
+      ...CANDLE_GAP_BAND_DEFAULTS,
+      fillOpacity: 0.08,
+      borderWidth: 1,
+    },
+    label: CANDLE_GAP_LABEL_DEFAULTS,
+  },
+};
+
+function resolveCandleGapBridge(
+  override: false | CandleGapBridgeStyle | undefined,
+  semanticDefault: ResolvedCandleGapBridgeStyle | null,
+): ResolvedCandleGapBridgeStyle | null {
+  if (override === false) return null;
+  if (override === undefined) {
+    return semanticDefault ? { ...semanticDefault } : null;
+  }
+  const base = semanticDefault ?? CANDLE_GAP_BRIDGE_DEFAULTS;
+  const strokeCap = override.strokeCap;
+  return {
+    color: override.color ?? base.color,
+    opacity: clampOpacity(override.opacity ?? base.opacity),
+    strokeWidth: Math.max(0, override.strokeWidth ?? base.strokeWidth),
+    strokeCap:
+      strokeCap === "butt" || strokeCap === "round" || strokeCap === "square"
+        ? strokeCap
+        : base.strokeCap,
+  };
+}
+
+function resolveCandleGapBand(
+  override: false | CandleGapBandStyle | undefined,
+  semanticDefault: ResolvedCandleGapBandStyle | null,
+): ResolvedCandleGapBandStyle | null {
+  if (override === false) return null;
+  if (override === undefined) {
+    return semanticDefault ? { ...semanticDefault } : null;
+  }
+  const base = semanticDefault ?? CANDLE_GAP_BAND_DEFAULTS;
+  return {
+    fillColor: override.fillColor ?? base.fillColor,
+    fillOpacity: clampOpacity(override.fillOpacity ?? base.fillOpacity),
+    borderColor: override.borderColor ?? base.borderColor,
+    borderOpacity: clampOpacity(override.borderOpacity ?? base.borderOpacity),
+    borderWidth: Math.max(0, override.borderWidth ?? base.borderWidth),
+    intervals: override.intervals ?? base.intervals,
+  };
+}
+
+function resolveCandleGapLabel(
+  override: false | CandleGapLabelStyle | undefined,
+  semanticDefault: ResolvedCandleGapLabelStyle | null,
+): ResolvedCandleGapLabelStyle | null {
+  if (override === false) return null;
+  if (override === undefined) {
+    return semanticDefault ? { ...semanticDefault } : null;
+  }
+  const base = semanticDefault ?? CANDLE_GAP_LABEL_DEFAULTS;
+  return {
+    color: override.color ?? base.color,
+    position:
+      override.position === "left" || override.position === "right"
+        ? override.position
+        : base.position,
+  };
+}
+
+/** Resolve and defensively normalize explicit candle-gap metadata. */
+export function resolveCandleGaps(
+  prop: CandleGap[] | CandleGapsConfig | undefined,
+): ResolvedCandleGapsConfig | null {
+  if (prop == null) return null;
+  const gaps = (Array.isArray(prop) ? prop : prop.gaps)
+    .filter(
+      (gap) =>
+        Number.isFinite(gap.from) &&
+        Number.isFinite(gap.to) &&
+        gap.to > gap.from &&
+        (gap.kind === "no-trades" ||
+          gap.kind === "unavailable" ||
+          gap.kind === "unknown"),
+    )
+    .slice()
+    .sort((a, b) => a.from - b.from || a.to - b.to);
+  if (gaps.length === 0) return null;
+
+  const overrides = Array.isArray(prop) ? undefined : prop.styles;
+  const resolveStyle = (kind: CandleGapKind): ResolvedCandleGapStyle => {
+    const base = CANDLE_GAP_STYLE_DEFAULTS[kind];
+    const override = overrides?.[kind];
+    return {
+      bridge: resolveCandleGapBridge(override?.bridge, base.bridge),
+      band: resolveCandleGapBand(override?.band, base.band),
+      label: resolveCandleGapLabel(override?.label, base.label),
+    };
+  };
+
+  return {
+    gaps,
+    styles: {
+      "no-trades": resolveStyle("no-trades"),
+      unavailable: resolveStyle("unavailable"),
+      unknown: resolveStyle("unknown"),
+    },
+  };
+}
+
 export interface ResolvedZoomConfig {
   /** Tightest window (max zoom-in), seconds. `undefined` → `timeWindow / 8`. */
   minTimeWindow: number | undefined;

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,