react-native-livechart 4.10.0 → 4.12.0

package/src/components/LiveChart.tsx

@@ -1,10 +1,4 @@
-import {
-  useEffect,
-  useLayoutEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import Animated, {
@@ -27,6 +21,7 @@ import {
   Group,
   LinearGradient,
   Path,
+  Rect,
   vec,
 } from "@shopify/react-native-skia";
 
@@ -63,7 +58,11 @@ import {
   resolveYAxis,
 } from "../core/resolveConfig";
 import type { ResolvedThresholdConfig } from "../core/resolveConfig";
-import { resolveSegment } from "../core/resolveSegment";
+import {
+  liveIndicatorScrollOpacity,
+  resolveHideLiveOnScrollBack,
+} from "../core/liveIndicatorVisibility";
+import { resolveSegment, type ResolvedSegment } from "../core/resolveSegment";
 import { useLiveChartEngine } from "../core/useLiveChartEngine";
 import { pulseRadialOutset } from "../draw/line";
 import { resolveChartLayout } from "../hooks/resolveChartLayout";
@@ -83,7 +82,10 @@ import { useMarkers } from "../hooks/useMarkers";
 import { useReferenceDrag } from "../hooks/useReferenceDrag";
 import { useReferenceLinePress } from "../hooks/useReferenceLinePress";
 import { useModeBlend } from "../hooks/useModeBlend";
-import { useMomentum } from "../hooks/useMomentum";
+import {
+  resolveMomentumProp,
+  useMomentum,
+} from "../hooks/useMomentum";
 import { AXIS_GRAB_MIN_PX, usePanScroll } from "../hooks/usePanScroll";
 import { usePinchZoom } from "../hooks/usePinchZoom";
 import { useVisibleRange } from "../hooks/useVisibleRange";
@@ -110,6 +112,7 @@ import {
 import {
   collectReferenceValues,
   referenceLineForm,
+  referenceLineReactKeys,
   resolveReferenceGroupBadge,
 } from "../math/referenceLines";
 import {
@@ -253,6 +256,7 @@ function useLiveChartController({
   font: fontProp,
   insets,
   style,
+  canvasMode = "transparent",
 
   // ── Candlestick ─────────────────────────────────────────────────────────
   mode = "line",
@@ -315,6 +319,7 @@ function useLiveChartController({
   renderTooltip,
   renderOverlay,
   renderReferenceLine,
+  renderOffAxisReferenceLine,
   referenceLineGrouping,
   leftEdgeFade = true,
 
@@ -391,18 +396,18 @@ function useLiveChartController({
   const seededRef = useRef<(number | undefined)[]>([]);
   const refValueSig = allRefLines.map((l) => l.value ?? "_").join(",");
   useEffect(() => {
-    const active = dragActive.value;
-    const cur = dragValues.value;
+    const active = dragActive.get();
+    const cur = dragValues.get();
     const seeded = seededRef.current;
-    dragValues.value = allRefLines.map((l, i) => {
+    dragValues.set(allRefLines.map((l, i) => {
       const prop = l.value ?? 0;
       if (active[i]) return cur[i] ?? prop; // mid-drag → keep the dragged value
       if (l.value !== seeded[i]) return prop; // prop changed → adopt (controlled)
       return cur[i] ?? prop; // unchanged → keep current (uncontrolled persist)
-    });
+    }));
     seededRef.current = allRefLines.map((l) => l.value);
-    if (dragActive.value.length !== allRefLines.length) {
-      dragActive.value = allRefLines.map((_, i) => active[i] ?? false);
+    if (dragActive.get().length !== allRefLines.length) {
+      dragActive.set(allRefLines.map((_, i) => active[i] ?? false));
     }
     // allRefLines is rebuilt every render; key off the value signature + length.
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -414,6 +419,17 @@ function useLiveChartController({
     allRefLines,
     renderReferenceLine,
   );
+  // An off-axis renderer replaces only the edge-pinned tag. A full custom tag
+  // takes precedence for the same line to avoid mounting two native tags.
+  const refLineOffAxisCustom = customReferenceLineFlags(
+    allRefLines,
+    renderOffAxisReferenceLine,
+    "off-axis",
+  ).map((custom, index) => custom && !refLineCustom[index]);
+  const refLineKeys = referenceLineReactKeys(allRefLines);
+  // RN custom tags report their measured widths here so the Skia connector can
+  // start after the native badge instead of the hidden built-in pill.
+  const refLineCustomTagWidths = useSharedValue<number[]>([]);
 
   // Live Y values of the *draggable* Form-A lines, folded into the engine's
   // axis-range fit so dragging a line toward / past the visible edge expands the
@@ -425,13 +441,17 @@ function useLiveChartController({
   // contributes its live value; a series contributes its window min/max
   // (respecting `extendToNow`), so an off-range break-even expands the axis and
   // stays on-plot like a reference line would.
-  const draggableRefIdx = allRefLines
-    .map((l, i) =>
-      l.draggable && !l.excludeFromRange && referenceLineForm(l) === "line"
-        ? i
-        : -1,
-    )
-    .filter((i) => i >= 0);
+  const draggableRefIdx: number[] = [];
+  for (let i = 0; i < allRefLines.length; i++) {
+    const line = allRefLines[i];
+    if (
+      line.draggable &&
+      !line.excludeFromRange &&
+      referenceLineForm(line) === "line"
+    ) {
+      draggableRefIdx.push(i);
+    }
+  }
   const thresholdInRange = thresholdCfg?.includeInRange === true;
   // Constant benchmark → its live value rides this channel. A series threshold
   // is folded inside the engine tick instead (`thresholdRangePoints`), which
@@ -576,6 +596,7 @@ function useLiveChartController({
   // react-doctor-disable-next-line react-doctor/no-derived-state-effect -- Reanimated: must read the SharedValue off the render path
   useLayoutEffect(() => {
     // react-doctor-disable-next-line react-hooks-js/set-state-in-effect -- Reanimated: seeding from a SharedValue off render is the warning-free path
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- Reanimated: seed from the SharedValue outside render to avoid strict-mode access warnings
     setValueLayoutSample(value.get());
   }, [value]);
 
@@ -725,7 +746,7 @@ function useLiveChartController({
       if (
         referenceLineForm(l) !== "line" ||
         l.value === undefined ||
-        refLineCustom[i]
+        refLineCustom[i] || refLineOffAxisCustom[i]
       ) {
         ys.push(-1);
         continue;
@@ -870,11 +891,8 @@ function useLiveChartController({
     // polyline passed as the last arg below).
     thresholdCfg?.fill && !thresholdIsSeries ? thresholdGeom.lineY : undefined,
     lineIsLinear,
-    // Tip the line at the view-edge price (not the live value) while scrolled,
-    // matching the live dot — so the right edge doesn't drop to the off-screen
-    // live value when `followViewEdge` tracks the scrolled-back window.
-    engine.edgeValue,
-    badgeCfg?.followViewEdge ?? false,
+    // The plotted line independently selects the visible edge while historical;
+    // badge/live-indicator options affect overlays only.
     // Match the standalone loading squiggle's wave during the reveal morph.
     loadingCfg?.amplitude,
     loadingCfg?.speed,
@@ -910,6 +928,15 @@ function useLiveChartController({
   );
 
   const momentumSV = useMomentum(engine, momentum);
+  // A follow-edge badge must derive its color from the same historical point
+  // as its value and position. While following live, reuse the normal momentum
+  // result; while scrolled back, detect against the data prefix ending at the
+  // visible right-edge timestamp so incoming live ticks cannot change the pill.
+  const badgeMomentumSV = useDerivedValue(() =>
+    badgeCfg?.followViewEdge && engine.viewEnd.value !== null
+      ? resolveMomentumProp(momentum, engine.data.value, engine.timestamp.value)
+      : momentumSV.value,
+  );
 
   // ── Overlay hooks ─────────────────────────────────────────────────────
   // Scrub/crosshair must see the same stash-backed candles as the engine.
@@ -1001,6 +1028,14 @@ function useLiveChartController({
       ? (timeScrollHoldMs ?? (scrubCfg?.panGestureDelay || HOLD_TO_SCRUB_MS))
       : (scrubCfg?.panGestureDelay ?? 0);
 
+  // Cross-gesture arbitration for the one-finger touch. `Gesture.Race` below is
+  // NOT arbitration — RNGH's Race adds no relation between its children, so both
+  // pans recognize independently and each can activate while the other already
+  // owns the touch. This latch (written by the scroll pan, read by the scrub's
+  // long-press guard) makes "the scroll already won" a hard fact; `scrubActive`
+  // (written by the crosshair, read by the scroll pan) is the mirror image.
+  const scrollActive = useSharedValue(false);
+
   const crosshair = useCrosshair(
     engine,
     effectivePadding,
@@ -1030,6 +1065,7 @@ function useLiveChartController({
     timeScrollEnabled && scrollGestureMode === "axisDrag"
       ? Math.max(effectivePadding.bottom, AXIS_GRAB_MIN_PX)
       : 0,
+    scrollActive,
   );
 
   // Capture only the shared value in the worklets below. Referencing
@@ -1052,6 +1088,10 @@ function useLiveChartController({
     minTime: scrollMinTime,
     enabled: timeScrollEnabled,
     mode: scrollGestureMode,
+    scrollActive,
+    // Once a scrub is engaged the chart is locked: scrolling goes inert so the
+    // finger only moves the price indicator across a fixed window.
+    scrubActive: crosshairScrubActive,
     // Clear any live crosshair when a scroll drag takes over.
     onScrollStart: () => {
       "worklet";
@@ -1176,10 +1216,40 @@ function useLiveChartController({
   // point instead — otherwise both dots show at once. Applies on static charts
   // too, now that they're scrubbable.
   const selectionDotDuringScrub = scrubCfg !== null && selectionDotCfg !== null;
+  // While scrolled back, the badge, dot, and value line still point at the live
+  // price even though the window is showing history. Hide that live-priced group
+  // together. `badge.followViewEdge` opts back in because all three then track
+  // the visible edge price; `hideLiveOnScrollBack: false` keeps the legacy group.
+  const hideLiveOnScrollBack = resolveHideLiveOnScrollBack(
+    timeScroll,
+    badgeCfg?.followViewEdge ?? false,
+  );
   const liveDotOpacity = useDerivedValue(
     () =>
       reveal.dotOpacity.value *
-      (selectionDotDuringScrub && crosshairScrubActive.value ? 0 : 1),
+      (selectionDotDuringScrub && crosshairScrubActive.value ? 0 : 1) *
+      liveIndicatorScrollOpacity(
+        hideLiveOnScrollBack,
+        engine.viewEnd.value,
+      ),
+  );
+  // Same scrolled-back gating for the value line: it would draw a dashed line
+  // at the live value's Y — a price that isn't in the scrolled-back view.
+  const valueLineOpacity = useDerivedValue(
+    () =>
+      reveal.lineOpacity.value *
+      liveIndicatorScrollOpacity(
+        hideLiveOnScrollBack,
+        engine.viewEnd.value,
+      ),
+  );
+  const liveBadgeOpacity = useDerivedValue(
+    () =>
+      reveal.badgeOpacity.value *
+      liveIndicatorScrollOpacity(
+        hideLiveOnScrollBack,
+        engine.viewEnd.value,
+      ),
   );
 
   // Fade the annotation overlays (markers + reference lines) out while scrubbing
@@ -1204,6 +1274,7 @@ function useLiveChartController({
   return {
     // passthrough props the render needs
     style,
+    canvasMode,
     accessibilityLabel,
     accessibilityRole,
     emptyText,
@@ -1238,10 +1309,14 @@ function useLiveChartController({
     leftEdgeFadeCfg,
     metricsCfg,
     allRefLines,
+    refLineKeys,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     dragValues,
     dragActive,
     renderReferenceLine,
+    renderOffAxisReferenceLine,
     refGroupingActive: refGroupingRadius != null,
     refGroupResult,
     groupHidden,
@@ -1314,9 +1389,12 @@ function useLiveChartController({
     dotX,
     dotY,
     liveDotOpacity,
+    valueLineOpacity,
+    liveBadgeOpacity,
     overlayScrubFade,
     markerGroupOpacity,
     momentumSV,
+    badgeMomentumSV,
     onDegenShake,
     crosshair,
     rootGesture,
@@ -1362,9 +1440,7 @@ function ChartWithDegen({
     onDegenShake,
     isStatic,
   );
-  return (
-    <ChartView model={model} yAxisEntries={yAxisEntries} degen={state} />
-  );
+  return <ChartView model={model} yAxisEntries={yAxisEntries} degen={state} />;
 }
 
 /**
@@ -1419,6 +1495,7 @@ function ChartYAxisLayer({
     metricsCfg,
     gridStyleCfg,
     yAxisFloat,
+    liveBadgeOpacity,
   } = model;
   return (
     <Group opacity={reveal.yAxisOpacity}>
@@ -1436,6 +1513,7 @@ function ChartYAxisLayer({
         badgeCenterY={badgeUsesRightGutter ? dotY : undefined}
         badgeFontSize={badgeUsesRightGutter ? badgeFont.getSize() : undefined}
         badgeOffsetY={badgeCfg?.offsetY ?? 0}
+        badgeOpacity={badgeUsesRightGutter ? liveBadgeOpacity : undefined}
         gridStyle={gridStyleCfg}
       />
     </Group>
@@ -1675,8 +1753,10 @@ function ChartStack({
     fontProp,
     badgeCfg,
     valueLineCfg,
+    valueLineOpacity,
     dotY,
     allRefLines,
+    refLineKeys,
     dragValues,
     resolvedSegments,
     hasRecolorSegments,
@@ -1721,14 +1801,15 @@ function ChartStack({
     loadingStrokeWidth,
     loadingAmplitude,
     loadingSpeed,
+    canvasMode,
   } = model;
   return (
     <Group transform={degen?.shakeTransform}>
       {/* Segment dividers + labels (behind the line). The scrub-focus emphasis is
           painted on the line stroke itself, below — this overlay draws no fill. */}
-      {resolvedSegments.map((seg, i) => (
+      {resolvedSegments.map((seg) => (
         <SegmentDividerOverlay
-          key={`seg-${seg.from ?? "start"}-${seg.to ?? "end"}-${i}`}
+          key={segmentReactKey(seg)}
           engine={engine}
           padding={effectivePadding}
           segment={seg}
@@ -1738,7 +1819,7 @@ function ChartStack({
 
       {/* Value line + reference line (behind chart line) */}
       {valueLineCfg && (
-        <Group opacity={reveal.lineOpacity}>
+        <Group opacity={valueLineOpacity}>
           <ValueLineOverlay
             dotY={dotY}
             engine={engine}
@@ -1750,14 +1831,12 @@ function ChartStack({
         </Group>
       )}
 
-      {/* Index keys: reference lines are a positional array and two may share
-          value + label (e.g. duplicate working orders at the same price), which a
-          content-derived key would collapse to one. Wrapped in a fade group so
-          `scrub.hideOverlaysOnScrub` can ease the lines out while scrubbing. */}
+      {/* Wrapped in a fade group so `scrub.hideOverlaysOnScrub` can ease lines
+          out while scrubbing. Explicit ids keep lines stable when reordered. */}
       <Group opacity={overlayScrubFade}>
         {allRefLines.map((rl, i) => (
           <ReferenceLineOverlay
-            key={i}
+            key={refLineKeys[i]}
             engine={engine}
             padding={effectivePadding}
             line={rl}
@@ -1861,7 +1940,6 @@ function ChartStack({
             dotX={dotX}
             dotY={dotY}
             palette={palette}
-            engine={engine}
             pulse={pulseCfg}
             radius={dotCfg.radius}
             ring={dotCfg.ring}
@@ -1939,6 +2017,7 @@ function ChartStack({
         lineStrokeWidth={loadingStrokeWidth}
         waveAmplitude={loadingAmplitude}
         waveSpeed={loadingSpeed}
+        opaqueCanvas={canvasMode === "opaque"}
       />
     </Group>
   );
@@ -2003,6 +2082,7 @@ function ChartScrubLayer({
     selectionDot,
     selectionColor,
     renderTooltip,
+    canvasMode,
   } = model;
   // A custom tooltip is an RN overlay (sibling of <Canvas>), so the built-in
   // Skia tooltip is suppressed here while it's active — the line pill in line
@@ -2047,6 +2127,7 @@ function ChartScrubLayer({
           tooltipBorderRadius={scrubCfg.tooltipBorderRadius}
           tooltipShowValue={scrubCfg.tooltipShowValue}
           tooltipShowTime={scrubCfg.tooltipShowTime}
+          opaqueCanvas={canvasMode === "opaque"}
         >
           {/* Candle charts render a multi-line OHLC tooltip; the line
               chart falls back to CrosshairOverlay's default value/time
@@ -2065,6 +2146,19 @@ function ChartScrubLayer({
   );
 }
 
+/** A segment's time range and presentation uniquely identify its divider view. */
+function segmentReactKey(segment: ResolvedSegment): string {
+  return [
+    "seg",
+    segment.from ?? "start",
+    segment.to ?? "end",
+    segment.divider,
+    segment.dividerColor,
+    segment.label ?? "",
+    segment.labelPosition,
+  ].join(":");
+}
+
 /** Live-value text drawn as its own canvas layer, above both the area gradient
  *  and the left-edge fade, so the large number stays crisp at the left edge
  *  instead of being washed out by the fade's `dstOut` blend. */
@@ -2116,14 +2210,14 @@ function ChartBadgeLayer({
 }) {
   const {
     badgeFont,
-    reveal,
     engine,
     effectivePadding,
     palette,
     formatValue,
-    momentumSV,
+    badgeMomentumSV,
     metricsCfg,
     yAxisFloat,
+    liveBadgeOpacity,
   } = model;
   const badgeCfg = model.badgeCfg!;
   const badgeData = useBadge(
@@ -2134,7 +2228,7 @@ function ChartBadgeLayer({
     badgeFont,
     badgeCfg.variant,
     badgeCfg.tail,
-    momentumSV,
+    badgeMomentumSV,
     badgeCfg.position,
     badgeCfg.background,
     metricsCfg.badge,
@@ -2147,7 +2241,7 @@ function ChartBadgeLayer({
   );
   return (
     <Group transform={degen?.shakeTransform}>
-      <Group opacity={reveal.badgeOpacity}>
+      <Group opacity={liveBadgeOpacity}>
         <BadgeOverlay
           badge={badgeData}
           font={badgeFont}
@@ -2174,7 +2268,10 @@ function ChartRefBadgeLayer({
 }) {
   const {
     allRefLines,
+    refLineKeys,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     dragValues,
     groupHidden,
     refGroupResult,
@@ -2195,7 +2292,7 @@ function ChartRefBadgeLayer({
     <Group transform={degen?.shakeTransform} opacity={overlayScrubFade}>
       {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
-          key={i}
+          key={refLineKeys[i]}
           engine={engine}
           padding={effectivePadding}
           line={rl}
@@ -2207,6 +2304,8 @@ function ChartRefBadgeLayer({
           dragValues={dragValues}
           index={i}
           suppressTag={refLineCustom[i]}
+          suppressTagWhenOffAxis={refLineOffAxisCustom[i]}
+          customTagWidths={refLineCustomTagWidths}
           groupHidden={refGroupingActive ? groupHidden : undefined}
         />
       ))}
@@ -2277,8 +2376,11 @@ function ChartCustomAnnotations({ model }: { model: LiveChartModel }) {
     markerClusterCfg,
     renderMarker,
     renderReferenceLine,
+    renderOffAxisReferenceLine,
     allRefLines,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     dragValues,
     dragActive,
     engine,
@@ -2317,6 +2419,21 @@ function ChartCustomAnnotations({ model }: { model: LiveChartModel }) {
           formatValue={formatValue}
           dragValues={dragValues}
           dragActive={dragActive}
+          tagWidths={refLineCustomTagWidths}
+        />
+      )}
+      {renderOffAxisReferenceLine && allRefLines.length > 0 && (
+        <CustomReferenceLineOverlay
+          lines={allRefLines}
+          renderReferenceLine={renderOffAxisReferenceLine}
+          custom={refLineOffAxisCustom}
+          engine={engine}
+          padding={effectivePadding}
+          formatValue={formatValue}
+          dragValues={dragValues}
+          dragActive={dragActive}
+          tagWidths={refLineCustomTagWidths}
+          offAxisOnly
         />
       )}
     </Animated.View>
@@ -2358,12 +2475,14 @@ function ChartView({
     renderTooltip,
     renderOverlay,
     renderReferenceLine,
+    renderOffAxisReferenceLine,
     allRefLines,
     scrubCfg,
     crosshair,
     extremaTimeOffset,
     topConnector,
     bottomConnector,
+    canvasMode,
   } = model;
 
   return (
@@ -2375,7 +2494,21 @@ function ChartView({
         accessibilityLabel={accessibilityLabel}
         accessibilityRole={accessibilityRole}
       >
-        <Canvas style={{ flex: 1 }}>
+        {/* Skia chooses TextureView vs SurfaceView when the native Canvas mounts. */}
+        <Canvas
+          key={canvasMode}
+          style={{ flex: 1 }}
+          opaque={canvasMode === "opaque"}
+        >
+          {canvasMode === "opaque" && (
+            <Rect
+              x={0}
+              y={0}
+              width={engine.canvasWidth}
+              height={engine.canvasHeight}
+              color={backgroundColor}
+            />
+          )}
           {/* Background fills first, then the left-edge fade (a canvas-space sibling
               so dstOut blends correctly), then the line stack on top — so the fade
               softens only the fills and the line stays crisp at the left edge. */}
@@ -2392,15 +2525,14 @@ function ChartView({
               startColor={leftEdgeFadeCfg.startColor}
               endColor={leftEdgeFadeCfg.endColor}
               engine={engine}
+              opaqueBackgroundRgb={
+                canvasMode === "opaque" ? palette.bgRgb : undefined
+              }
             />
           )}
 
           {/* Line stack above the fade so the line stays crisp at the left edge. */}
-          <ChartStack
-            model={model}
-            yAxisEntries={yAxisEntries}
-            degen={degen}
-          />
+          <ChartStack model={model} yAxisEntries={yAxisEntries} degen={degen} />
 
           {/* "extrema-edge" connector lines (dot → edge readout), above the chart
               content so the dashed guide reads over the line / candles. */}
@@ -2453,7 +2585,8 @@ function ChartView({
             Skia markers (the wrapper is full-bleed; children keep their own
             absolute positions). */}
         {((markersActive && renderMarker) ||
-          (renderReferenceLine && allRefLines.length > 0)) && (
+          ((renderReferenceLine || renderOffAxisReferenceLine) &&
+            allRefLines.length > 0)) && (
           <ChartCustomAnnotations model={model} />
         )}