react-native-livechart 4.10.0 → 4.12.0

package/src/components/CrosshairOverlay.tsx

@@ -43,6 +43,7 @@ export function CrosshairOverlay({
   tooltipBorderRadius = 5,
   tooltipShowValue = true,
   tooltipShowTime = true,
+  opaqueCanvas = false,
 }: {
   scrubX: SharedValue<number>;
   crosshairOpacity: SharedValue<number>;
@@ -94,6 +95,8 @@ export function CrosshairOverlay({
   tooltipShowValue?: boolean;
   /** Draw the time row of the default tooltip body. Default true. */
   tooltipShowTime?: boolean;
+  /** Paint the owned background instead of erasing destination alpha. */
+  opaqueCanvas?: boolean;
 }) {
   // Explicit dependency arrays: with React Compiler enabled, Reanimated's
   // auto-detected worklet dependencies can change array size between renders
@@ -101,18 +104,15 @@ export function CrosshairOverlay({
   // React's "final argument changed size between renders" error. Listing the
   // captured plain values keeps the dependency array a constant size. SharedValue
   // reads stay reactive regardless of this list.
-  const p1 = useDerivedValue(
-    () => {
-      // A top-pinned custom tooltip pushes the line's start down to its measured
-      // bottom (lineTop) so the line stops at the label; -1 → no top tooltip.
-      const lt = lineTop?.value ?? -1;
-      return {
-        x: scrubX.value,
-        y: lt >= 0 ? lt : padding.top,
-      };
-    },
-    [scrubX, padding.top, lineTop],
-  );
+  const p1 = useDerivedValue(() => {
+    // A top-pinned custom tooltip pushes the line's start down to its measured
+    // bottom (lineTop) so the line stops at the label; -1 → no top tooltip.
+    const lt = lineTop?.value ?? -1;
+    return {
+      x: scrubX.value,
+      y: lt >= 0 ? lt : padding.top,
+    };
+  }, [scrubX, padding.top, lineTop]);
   const p2 = useDerivedValue(
     () => ({
       x: scrubX.value,
@@ -153,6 +153,11 @@ export function CrosshairOverlay({
     () => `rgba(0,0,0,${(1 - dimOpacity) * crosshairOpacity.value})`,
     [dimOpacity, crosshairOpacity],
   );
+  const opaqueDimOpacity = useDerivedValue(
+    () => (1 - dimOpacity) * crosshairOpacity.value,
+    [dimOpacity, crosshairOpacity],
+  );
+  const backgroundColor = `rgb(${palette.bgRgb[0]},${palette.bgRgb[1]},${palette.bgRgb[2]})`;
 
   return (
     <>
@@ -167,6 +172,15 @@ export function CrosshairOverlay({
             color={crosshairDimColor}
           />
         </Group>
+      ) : dimOpacity < 1 && opaqueCanvas ? (
+        <Rect
+          x={scrubX}
+          y={padding.top}
+          width={dimWidth}
+          height={dimHeight}
+          color={backgroundColor}
+          opacity={opaqueDimOpacity}
+        />
       ) : dimOpacity < 1 ? (
         // Erase the trailing content's alpha so it fades to the real background
         // (works on any background color, unlike a colored mask).
@@ -203,29 +217,28 @@ export function CrosshairOverlay({
         />
 
         {showTooltip && (
-        <>
-          <RoundedRect
-            x={tipX}
-            y={tipY}
-            width={tipW}
-            height={tipH}
-            r={tooltipBorderRadius}
-            color={tooltipBackground ?? palette.tooltipBg}
-          />
+          <>
+            <RoundedRect
+              x={tipX}
+              y={tipY}
+              width={tipW}
+              height={tipH}
+              r={tooltipBorderRadius}
+              color={tooltipBackground ?? palette.tooltipBg}
+            />
 
-          <RoundedRect
-            x={tipX}
-            y={tipY}
-            width={tipW}
-            height={tipH}
-            r={tooltipBorderRadius}
-            color={tooltipBorderColor ?? palette.tooltipBorder}
-            style="stroke"
-            strokeWidth={1}
-          />
+            <RoundedRect
+              x={tipX}
+              y={tipY}
+              width={tipW}
+              height={tipH}
+              r={tooltipBorderRadius}
+              color={tooltipBorderColor ?? palette.tooltipBorder}
+              style="stroke"
+              strokeWidth={1}
+            />
 
-          {children ??
-            renderTooltip?.() ?? (
+            {children ?? renderTooltip?.() ?? (
               <Group>
                 {tooltipShowValue && (
                   <SkiaText
@@ -247,8 +260,8 @@ export function CrosshairOverlay({
                 )}
               </Group>
             )}
-        </>
-      )}
+          </>
+        )}
       </Group>
     </>
   );

package/src/components/CustomReferenceLineOverlay.tsx

@@ -12,6 +12,7 @@ import { computeScrubDotY } from "../hooks/crosshairShared";
 import {
   classifyReferenceEdge,
   referenceLineForm,
+  referenceLineReactKeys,
   resolveReferenceBadge,
 } from "../math/referenceLines";
 import type { ReferenceLine, ReferenceLineRenderProps } from "../types";
@@ -39,20 +40,24 @@ function stub<T>(v: T): SharedValue<T> {
   return { value: v, get: () => v } as unknown as SharedValue<T>;
 }
 
+/** Whether a custom tag owns every state or only an off-axis tag. */
+export type CustomReferenceLineMode = "always" | "off-axis";
+
 /**
- * Which Form-A reference lines a `renderReferenceLine` returns an element for —
- * the set whose built-in Skia tag is suppressed (so there's no double-draw). The
- * render fn is probed with placeholder SharedValues; it must decide null-ness from
- * `line` / `index`, not from live values (mirrors how `renderMarker` is probed for
- * the marker-atlas exclusion set). Index-aligned with `lines`.
+ * Which Form-A reference lines a custom renderer returns an element for. This
+ * initial probe determines a line's static eligibility only; `"off-axis"` still
+ * switches the built-in tag and the RN tag on the UI thread as the edge changes.
+ * Index-aligned with `lines`.
  */
 export function customReferenceLineFlags(
   lines: ReferenceLine[],
   render?: (
     ctx: ReferenceLineRenderProps,
   ) => React.ReactElement | null | undefined,
+  mode: CustomReferenceLineMode = "always",
 ): boolean[] {
   if (!render) return lines.map(() => false);
+  const offAxisOnly = mode === "off-axis";
   return lines.map((line, index) => {
     if (referenceLineForm(line) !== "line") return false;
     return (
@@ -62,8 +67,10 @@ export function customReferenceLineFlags(
         value: stub(line.value ?? 0),
         valueStr: stub(""),
         y: stub(-1),
-        inRange: stub(true),
-        edge: stub<"above" | "in" | "below">("in"),
+        inRange: stub(!offAxisOnly),
+        edge: stub<"above" | "in" | "below">(
+          offAxisOnly ? "above" : "in",
+        ),
         dragging: stub(false),
       }) != null
     );
@@ -88,6 +95,8 @@ function CustomReferenceLineView({
   formatValue,
   dragValues,
   dragActive,
+  tagWidths,
+  offAxisOnly,
 }: {
   line: ReferenceLine;
   index: number;
@@ -97,14 +106,20 @@ function CustomReferenceLineView({
   engine: ChartEngineLayout;
   padding: ChartPadding;
   formatValue: (v: number) => string;
-  dragValues: SharedValue<number[]>;
-  dragActive: SharedValue<boolean[]>;
+  /** Optional live overrides used by draggable single-series lines. */
+  dragValues?: SharedValue<number[]>;
+  /** Optional drag state used by draggable single-series lines. */
+  dragActive?: SharedValue<boolean[]>;
+  /** Measured custom-tag widths, index-aligned for the Skia connector. */
+  tagWidths?: SharedValue<number[]>;
+  /** Show this custom tag only while its line is pinned above or below the plot. */
+  offAxisOnly: boolean;
 }) {
   const staticValue = line.value ?? 0;
 
   // Live value: a drag override (if present) else the static prop value.
   const value = useDerivedValue<number>(() => {
-    const dv = dragValues.get()[index];
+    const dv = dragValues?.get()[index];
     return dv != null ? dv : staticValue;
   });
   const valueStr = useDerivedValue(() => formatValue(value.get()));
@@ -116,12 +131,18 @@ function CustomReferenceLineView({
     ),
   );
   const inRange = useDerivedValue(() => edge.get() === "in");
-  const dragging = useDerivedValue(() => dragActive.get()[index] === true);
+  const dragging = useDerivedValue(
+    () => dragActive?.get()[index] === true,
+  );
 
   // Canvas Y of the value (the element's vertical center). Off-screen values pin
   // to the nearest plot edge (inset), matching the built-in off-axis badge.
   const y = useDerivedValue(() => {
     const ch = engine.canvasHeight.get();
+    // `computeScrubDotY` also returns negative values for legitimate prices above
+    // the visible range, so use the layout dimensions—not the projected Y—to
+    // distinguish an unmeasured canvas from an off-axis line.
+    if (ch - padding.top - padding.bottom <= 0) return -1;
     const raw = computeScrubDotY(
       value.get(),
       engine.displayMin.get(),
@@ -130,7 +151,6 @@ function CustomReferenceLineView({
       padding.top,
       padding.bottom,
     );
-    if (raw < 0) return -1;
     const top = padding.top + EDGE_INSET;
     const bottom = ch - padding.bottom - EDGE_INSET;
     return Math.min(bottom, Math.max(top, raw));
@@ -140,7 +160,14 @@ function CustomReferenceLineView({
   const size = useSharedValue({ width: 0, height: 0 });
   const onLayout = (e: LayoutChangeEvent) => {
     const { width, height } = e.nativeEvent.layout;
-    size.value = { width, height };
+    size.set({ width, height });
+    if (tagWidths) {
+      const previous = tagWidths.get();
+      if (previous[index] === width) return;
+      const widths = previous.slice();
+      widths[index] = width;
+      tagWidths.set(widths);
+    }
   };
 
   const anchor = resolveAnchor(line);
@@ -148,7 +175,7 @@ function CustomReferenceLineView({
     const yy = y.get();
     const s = size.get();
     const w = engine.canvasWidth.get();
-    const visible = yy >= 0 && w > 0;
+    const visible = yy >= 0 && w > 0 && (!offAxisOnly || edge.get() !== "in");
     const x1 = padding.left;
     const x2 = w - padding.right;
     let tx: number;
@@ -188,9 +215,9 @@ function CustomReferenceLineView({
  * React Native overlay (NOT Skia) that floats `renderReferenceLine` elements over
  * the canvas, one per Form-A line the consumer customizes. Rendered as a sibling
  * of `<Canvas>` (like {@link CustomMarkerOverlay}) so the tags can be any RN view
- * and stay crisp at native resolution. Lines whose render returns an element have
- * their built-in Skia tag suppressed upstream (see {@link customReferenceLineFlags}),
- * so there's no double-draw.
+ * and stay crisp at native resolution. Lines whose render returns an element hide
+ * their built-in pill / label upstream (see {@link customReferenceLineFlags}); a
+ * badged line's Skia connector remains, measured against the native tag's width.
  */
 export function CustomReferenceLineOverlay({
   lines,
@@ -201,6 +228,8 @@ export function CustomReferenceLineOverlay({
   formatValue,
   dragValues,
   dragActive,
+  tagWidths,
+  offAxisOnly = false,
 }: {
   lines: ReferenceLine[];
   renderReferenceLine: (
@@ -215,15 +244,22 @@ export function CustomReferenceLineOverlay({
   engine: ChartEngineLayout;
   padding: ChartPadding;
   formatValue: (v: number) => string;
-  dragValues: SharedValue<number[]>;
-  dragActive: SharedValue<boolean[]>;
+  /** Optional live overrides used by draggable single-series lines. */
+  dragValues?: SharedValue<number[]>;
+  /** Optional drag state used by draggable single-series lines. */
+  dragActive?: SharedValue<boolean[]>;
+  /** Measured custom-tag widths, index-aligned for the Skia connector. */
+  tagWidths?: SharedValue<number[]>;
+  /** Keep the built-in in-range tag and show this RN tag only off-axis. */
+  offAxisOnly?: boolean;
 }) {
   const children: React.ReactElement[] = [];
+  const lineKeys = referenceLineReactKeys(lines);
   for (let i = 0; i < lines.length; i++) {
     if (!custom[i]) continue;
     children.push(
       <CustomReferenceLineView
-        key={i}
+        key={lineKeys[i]}
         line={lines[i]}
         index={i}
         render={renderReferenceLine}
@@ -232,6 +268,8 @@ export function CustomReferenceLineOverlay({
         formatValue={formatValue}
         dragValues={dragValues}
         dragActive={dragActive}
+        tagWidths={tagWidths}
+        offAxisOnly={offAxisOnly}
       />,
     );
   }

package/src/components/DegenParticlesOverlay.tsx

@@ -5,6 +5,7 @@ import {
   type SkRSXform,
   type SkRect,
 } from "@shopify/react-native-skia";
+import { useRef } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import {
   buildParticleInstances,
@@ -63,14 +64,46 @@ export function DegenParticlesOverlay({
   // memoizes this on `colorList`.
   const colorRgb = colorList.map((c) => parseColorRgb(c));
 
+  const poolRef = useRef<{
+    a: { transforms: SkRSXform[]; sprites: SkRect[]; colors: SkColor[] };
+    b: { transforms: SkRSXform[]; sprites: SkRect[]; colors: SkColor[] };
+    tick: boolean;
+    instances: ReturnType<typeof buildParticleInstances>;
+    instancePool: ReturnType<typeof buildParticleInstances>;
+    spriteRect: SkRect;
+  } | null>(null);
+  if (poolRef.current === null) {
+    const instancePool = Array.from({ length: particleSlotCount }, () => ({
+      x: 0,
+      y: 0,
+      scale: 0,
+      alpha: 0,
+      colorIndex: 0,
+    }));
+    poolRef.current = {
+      a: { transforms: [], sprites: [], colors: [] },
+      b: { transforms: [], sprites: [], colors: [] },
+      tick: false,
+      instances: [],
+      instancePool,
+      spriteRect: Skia.XYWHRect(0, 0, sprite.size, sprite.size),
+    };
+  }
+
   // Single per-frame worklet. Reads `packRevision` so it re-runs each frame
   // while a burst is alive (the pack buffer is mutated in place, so its
   // reference is stable and wouldn't otherwise re-notify).
   const atlasData = useDerivedValue(() => {
     const rev = packRevision.get();
-    const transforms: SkRSXform[] = [];
-    const sprites: SkRect[] = [];
-    const colorsOut: SkColor[] = [];
+    const pool = poolRef.current!;
+    pool.tick = !pool.tick;
+    const frame = pool.tick ? pool.a : pool.b;
+    const transforms = frame.transforms;
+    const sprites = frame.sprites;
+    const colorsOut = frame.colors;
+    transforms.length = 0;
+    sprites.length = 0;
+    colorsOut.length = 0;
     if (rev >= 0) {
       const instances = buildParticleInstances(
         pack.get(),
@@ -79,6 +112,8 @@ export function DegenParticlesOverlay({
         particleBurstDurationSec,
         particleOpacity,
         sprite.radius,
+        pool.instances,
+        pool.instancePool,
       );
       const half = sprite.size / 2;
       for (let i = 0; i < instances.length; i++) {
@@ -92,12 +127,12 @@ export function DegenParticlesOverlay({
             inst.y - inst.scale * half,
           ),
         );
-        sprites.push(Skia.XYWHRect(0, 0, sprite.size, sprite.size));
+        sprites.push(pool.spriteRect);
         const [r, g, b] = colorRgb[inst.colorIndex % colorRgb.length];
         colorsOut.push(Skia.Color(`rgba(${r}, ${g}, ${b}, ${inst.alpha})`));
       }
     }
-    return { transforms, sprites, colors: colorsOut };
+    return frame;
   }, [
     pack,
     packRevision,

package/src/components/DotOverlay.tsx

@@ -1,11 +1,16 @@
+import { useEffect } from "react";
 import { Circle, Group } from "@shopify/react-native-skia";
-import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import {
+  useDerivedValue,
+  useFrameCallback,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
 import type {
   ResolvedDotRingConfig,
   ResolvedPulseConfig,
 } from "../core/resolveConfig";
 import type { LiveChartPalette } from "../types";
-import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 
 const MIN_PULSE_RADIUS = 9;
 
@@ -19,7 +24,6 @@ export function DotOverlay({
   dotX,
   dotY,
   palette,
-  engine,
   pulse,
   radius,
   ring,
@@ -29,7 +33,6 @@ export function DotOverlay({
   dotX: SharedValue<number>;
   dotY: SharedValue<number>;
   palette: LiveChartPalette;
-  engine: ChartEngineLayout;
   pulse: ResolvedPulseConfig | null;
   /** Radius of the color-filled dot in pixels. */
   radius: number;
@@ -39,17 +42,30 @@ export function DotOverlay({
   color: string | undefined;
   /**
    * Time-scroll right edge (`null` = following live). While scrolled back the
-   * pulse is suppressed — it's driven by the (now frozen) view timestamp, so it
-   * would stick or flicker, and a "live" heartbeat on a historical point is wrong.
+   * pulse is suppressed because a "live" heartbeat on a historical point is
+   * misleading.
    */
   viewEnd?: SharedValue<number | null>;
 }) {
   const dotColor = color ?? palette.line;
 
+  // Pulse clock: wall time, not `engine.timestamp` — a `nowOverride` freezes
+  // the engine clock between data updates, which freezes the pulse with it.
+  // Runs only while a pulse is configured (resolvePulse returns null when the
+  // chart is static, so a suspended chart burns no frames here).
+  const pulseClockMs = useSharedValue(0);
+  /* istanbul ignore next -- frame-callback worklet runs on the UI thread, not in Jest */
+  const pulseClock = useFrameCallback((frame) => {
+    pulseClockMs.value = frame.timestamp;
+  }, pulse != null);
+  useEffect(() => {
+    pulseClock.setActive(pulse != null);
+  }, [pulse, pulseClock]);
+
   const pulseRadius = useDerivedValue(() => {
     if (!pulse) return 0;
     if (viewEnd?.value != null) return 0; // scrolled back — no live pulse
-    const nowMs = engine.timestamp.value * 1000;
+    const nowMs = pulseClockMs.value;
     const t = (nowMs % pulse.interval) / pulse.duration;
     if (t >= 1) return 0;
     return MIN_PULSE_RADIUS + t * (pulse.maxRadius - MIN_PULSE_RADIUS);
@@ -58,7 +74,7 @@ export function DotOverlay({
   const pulseOpacity = useDerivedValue(() => {
     if (!pulse) return 0;
     if (viewEnd?.value != null) return 0; // scrolled back — no live pulse
-    const nowMs = engine.timestamp.value * 1000;
+    const nowMs = pulseClockMs.value;
     const t = (nowMs % pulse.interval) / pulse.duration;
     if (t >= 1) return 0;
     return pulse.opacity * (1 - t);

package/src/components/LeftEdgeFade.tsx

@@ -2,6 +2,7 @@ import { Group, LinearGradient, Rect, vec } from "@shopify/react-native-skia";
 
 import { useDerivedValue } from "react-native-reanimated";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import { parseColorRgba } from "../theme";
 
 export function LeftEdgeFade({
   paddingLeft,
@@ -9,27 +10,32 @@ export function LeftEdgeFade({
   startColor,
   endColor,
   engine,
+  opaqueBackgroundRgb,
 }: {
   paddingLeft: number;
   fadeWidth: number;
   startColor: string;
   endColor: string;
   engine: ChartEngineLayout;
+  /** When set, paint the owned background instead of erasing destination alpha. */
+  opaqueBackgroundRgb?: [number, number, number];
 }) {
   const rectWidth = paddingLeft + fadeWidth;
   const height = useDerivedValue(() => engine.canvasHeight.value);
 
   const gStart = vec(paddingLeft, 0);
   const gEnd = vec(paddingLeft + fadeWidth, 0);
+  const colors = opaqueBackgroundRgb
+    ? [
+        `rgba(${opaqueBackgroundRgb[0]},${opaqueBackgroundRgb[1]},${opaqueBackgroundRgb[2]},${parseColorRgba(startColor)[3]})`,
+        `rgba(${opaqueBackgroundRgb[0]},${opaqueBackgroundRgb[1]},${opaqueBackgroundRgb[2]},${parseColorRgba(endColor)[3]})`,
+      ]
+    : [startColor, endColor];
 
   return (
-    <Group blendMode="dstOut">
+    <Group blendMode={opaqueBackgroundRgb ? undefined : "dstOut"}>
       <Rect x={0} y={0} width={rectWidth} height={height}>
-        <LinearGradient
-          start={gStart}
-          end={gEnd}
-          colors={[startColor, endColor]}
-        />
+        <LinearGradient start={gStart} end={gEnd} colors={colors} />
       </Rect>
     </Group>
   );