react-native-livechart 4.19.0 → 4.21.0

package/src/components/LiveChartSeries.tsx

@@ -5,7 +5,12 @@
  * @see https://github.com/benjitaylor/liveline
  */
 import { Canvas, Group, Rect } from "@shopify/react-native-skia";
-import { useLayoutEffect, useState } from "react";
+import {
+  forwardRef,
+  useImperativeHandle,
+  useLayoutEffect,
+  useState,
+} from "react";
 import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import Animated, {
@@ -16,7 +21,7 @@ import Animated, {
   withTiming,
   type SharedValue,
 } from "react-native-reanimated";
-import { scheduleOnRN } from "react-native-worklets";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
 import {
   DEFAULT_ACCENT_COLOR,
   HOLD_TO_SCRUB_MS,
@@ -62,7 +67,7 @@ import { useMarkers } from "../hooks/useMarkers";
 import { useMultiSeriesDegen } from "../hooks/useMultiSeriesDegen";
 import { useMultiSeriesLinePaths } from "../hooks/useMultiSeriesLinePaths";
 import { usePanScroll } from "../hooks/usePanScroll";
-import { usePinchZoom } from "../hooks/usePinchZoom";
+import { resetPinchZoom, usePinchZoom } from "../hooks/usePinchZoom";
 import { useMultiSeriesReverseMorphInputs } from "../hooks/useReverseMorphEngineInputs";
 import {
   SERIES_INDICATOR_FADE_MS,
@@ -86,7 +91,12 @@ import {
   leftEdgeFadeColorsFromBgRgb,
   resolveTheme,
 } from "../theme";
-import type { LiveChartSeriesProps, Marker, SeriesConfig } from "../types";
+import type {
+  LiveChartHandle,
+  LiveChartSeriesProps,
+  Marker,
+  SeriesConfig,
+} from "../types";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
 import { ChartOverlayLayer } from "./ChartOverlayLayer";
 import {
@@ -450,6 +460,7 @@ function useLiveChartSeriesController({
     yAxisCfg?.minGap ?? 36,
     metricsCfg.grid,
     yAxisCfg?.count ?? 0,
+    yAxisCfg?.intervalScale ?? 1,
   );
 
   const { xAxisEntries } = useXAxis(
@@ -1026,8 +1037,19 @@ function SeriesTooltipLayer({
   );
 }
 
-export function LiveChartSeries(props: LiveChartSeriesProps) {
+export const LiveChartSeries = forwardRef<
+  LiveChartHandle,
+  LiveChartSeriesProps
+>(function LiveChartSeries(props, ref) {
   const model = useLiveChartSeriesController(props);
+  const { viewEnd, viewWindow } = model.engine;
+  useImperativeHandle(
+    ref,
+    () => ({
+      resetZoom: () => scheduleOnUI(resetPinchZoom, { viewEnd, viewWindow }),
+    }),
+    [viewEnd, viewWindow],
+  );
   const {
     rootGesture,
     backgroundColor,
@@ -1273,4 +1295,4 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
       {legendCfg.position === "bottom" ? legend : null}
     </View>
   );
-}
+});

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,
@@ -89,6 +95,8 @@ export interface ResolvedBadgeConfig {
 
 export interface ResolvedYAxisConfig {
   minGap: number;
+  /** Multiplier used to choose and align representable dynamic nice intervals. */
+  intervalScale: number;
   /** Fixed label count (≥ 2), or 0 for the dynamic nice-interval grid. */
   count: number;
   /** undefined → keep the default centered-gutter label placement. */
@@ -112,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;
@@ -377,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];
@@ -413,6 +455,7 @@ export interface ResolvedThresholdConfig {
 const THRESHOLD_LINE_DEFAULTS: ResolvedThresholdLineConfig = {
   label: undefined,
   labelPosition: "left",
+  labelAnchor: "last",
   color: undefined,
   intervals: [4, 4],
   strokeWidth: 1,
@@ -486,6 +529,7 @@ export function resolveBadge(
 
 const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
   minGap: 36,
+  intervalScale: 1,
   count: 0,
   labelRightMargin: undefined,
   gridEndGap: undefined,
@@ -503,7 +547,14 @@ export function resolveYAxis(
 ): ResolvedYAxisConfig | null {
   const resolved = resolveToggle(prop, Y_AXIS_DEFAULTS, false);
   if (resolved === null) return null;
-  return { ...resolved, count: Math.max(0, Math.floor(resolved.count)) };
+  return {
+    ...resolved,
+    count: Math.max(0, Math.floor(resolved.count)),
+    intervalScale:
+      Number.isFinite(resolved.intervalScale) && resolved.intervalScale > 0
+        ? resolved.intervalScale
+        : 1,
+  };
 }
 
 const VOLUME_DEFAULTS: ResolvedVolumeConfig = {
@@ -525,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;