react-native-livechart 4.11.0 → 4.13.0

package/src/components/CrosshairOverlay.tsx

@@ -11,6 +11,7 @@ import type { ReactNode } from "react";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { type ChartPadding } from "../draw/line";
 import { type TooltipLayout } from "../hooks/crosshairShared";
+import { useCrosshairVisibleOpacity } from "../hooks/useCrosshairVisibleOpacity";
 import type { LiveChartPalette } from "../types";
 import type { ResolvedSelectionDotConfig } from "../core/resolveConfig";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
@@ -35,6 +36,11 @@ export function CrosshairOverlay({
   dimOpacity = 0.3,
   liveDotExtent = 0,
   crosshairLineColor,
+  crosshairStrokeWidth = 1,
+  crosshairOvershoot = 0,
+  crosshairFade = true,
+  crosshairFadeDistance = 4,
+  crosshairLineCap,
   crosshairDash,
   crosshairDimColor,
   tooltipBackground,
@@ -70,7 +76,7 @@ export function CrosshairOverlay({
   /** Scrub intersection Y in canvas px (the value the dot marks); -1 hides it. */
   selectionY?: SharedValue<number>;
   /** Whether scrubbing is active (passed through to a custom dot). */
-  scrubActive?: SharedValue<number> | SharedValue<boolean>;
+  scrubActive: SharedValue<number> | SharedValue<boolean>;
   /** Fallback selection-dot color (accent / leading-series color), used when the
    *  config's own `color` is unset. */
   selectionColor?: string;
@@ -83,6 +89,16 @@ export function CrosshairOverlay({
    *  reserves beyond it. Default 0. */
   liveDotExtent?: number;
   crosshairLineColor?: string;
+  /** Vertical crosshair line width in px. Default 1. */
+  crosshairStrokeWidth?: number;
+  /** Resolved extension past the top and bottom plot edges in px. Default 0. */
+  crosshairOvershoot?: number;
+  /** Fade the crosshair near the live edge. Default true. */
+  crosshairFade?: boolean;
+  /** Visible-crosshair fade distance near the live edge in px. Default 4. */
+  crosshairFadeDistance?: number;
+  /** Cap style for the vertical crosshair line. */
+  crosshairLineCap?: "butt" | "round" | "square";
   /** Dash intervals `[on, off, …]` for the crosshair line; omit → solid. */
   crosshairDash?: number[];
   crosshairDimColor?: string;
@@ -104,21 +120,27 @@ 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 - crosshairOvershoot,
+      };
+    },
+    [scrubX, padding.top, lineTop, crosshairOvershoot],
+  );
   const p2 = useDerivedValue(
     () => ({
       x: scrubX.value,
-      y: engine.canvasHeight.value - padding.bottom,
+      y:
+        engine.canvasHeight.value -
+        padding.bottom +
+        crosshairOvershoot,
     }),
-    [scrubX, engine.canvasHeight, padding.bottom],
+    [scrubX, engine.canvasHeight, padding.bottom, crosshairOvershoot],
   );
 
   const dimWidth = useDerivedValue(() => {
@@ -159,6 +181,17 @@ export function CrosshairOverlay({
   );
   const backgroundColor = `rgb(${palette.bgRgb[0]},${palette.bgRgb[1]},${palette.bgRgb[2]})`;
 
+  // Keep the trailing dim on its original edge fade. Only the visible
+  // crosshair group (line, dot, tooltip) uses the configurable distance.
+  const visibleOpacity = useCrosshairVisibleOpacity(
+    scrubX,
+    engine.canvasWidth,
+    padding.right,
+    scrubActive,
+    crosshairFade,
+    crosshairFadeDistance,
+  );
+
   return (
     <>
       {crosshairDimColor !== undefined ? (
@@ -195,12 +228,13 @@ export function CrosshairOverlay({
         </Group>
       ) : null}
 
-      <Group opacity={crosshairOpacity}>
+      <Group opacity={visibleOpacity}>
         <Line
           p1={p1}
           p2={p2}
           color={crosshairLineColor ?? palette.crosshairLine}
-          strokeWidth={1}
+          strokeWidth={crosshairStrokeWidth}
+          strokeCap={crosshairLineCap}
         >
           {crosshairDash ? <DashPathEffect intervals={crosshairDash} /> : null}
         </Line>
@@ -212,7 +246,7 @@ export function CrosshairOverlay({
           x={scrubX}
           y={selectionY}
           active={scrubActive}
-          opacity={crosshairOpacity}
+          opacity={visibleOpacity}
           color={selectionColor ?? palette.line}
         />
 

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;
@@ -101,6 +110,10 @@ function CustomReferenceLineView({
   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;
 
@@ -147,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);
@@ -155,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;
@@ -195,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,
@@ -208,6 +228,8 @@ export function CustomReferenceLineOverlay({
   formatValue,
   dragValues,
   dragActive,
+  tagWidths,
+  offAxisOnly = false,
 }: {
   lines: ReferenceLine[];
   renderReferenceLine: (
@@ -226,13 +248,18 @@ export function CustomReferenceLineOverlay({
   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}
@@ -241,6 +268,8 @@ export function CustomReferenceLineOverlay({
         formatValue={formatValue}
         dragValues={dragValues}
         dragActive={dragActive}
+        tagWidths={tagWidths}
+        offAxisOnly={offAxisOnly}
       />,
     );
   }

package/src/components/CustomTooltipOverlay.tsx

@@ -9,6 +9,7 @@ import Animated, {
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import type { TooltipLayout } from "../hooks/crosshairShared";
+import { resolveCrosshairVisibleOpacity } from "../hooks/useCrosshairVisibleOpacity";
 import type { CandlePoint, TooltipRenderProps } from "../types";
 
 // Mirror the Skia tooltip's offsets (see crosshairShared.ts) so a custom pill
@@ -41,12 +42,13 @@ export function CustomTooltipOverlay({
   scrubTime,
   scrubActive,
   scrubCandle,
-  crosshairOpacity,
   tooltipLayout,
   engine,
   padding,
   placement,
   margin = 8,
+  crosshairFade = true,
+  crosshairFadeDistance = 4,
   lineTop,
   scrubDotY,
 }: {
@@ -57,13 +59,16 @@ export function CustomTooltipOverlay({
   scrubActive: SharedValue<boolean>;
   /** OHLC candle under the crosshair (candle mode); omitted/`null` in line mode. */
   scrubCandle?: SharedValue<CandlePoint | null>;
-  crosshairOpacity: SharedValue<number>;
   tooltipLayout: SharedValue<TooltipLayout>;
   engine: ChartEngineLayout;
   padding: ChartPadding;
   placement: "side" | "top" | "bottom" | "point";
   /** Gap (px) between the pill and the plot edge it's pinned to. Default 8. */
   margin?: number;
+  /** Fade the tooltip near the live edge. Default true. */
+  crosshairFade?: boolean;
+  /** Tooltip fade distance near the live edge in px. Default 4. */
+  crosshairFadeDistance?: number;
   /** When `placement` is `"top"`, the overlay publishes the label's bottom edge
    *  (canvas Y) here so {@link CrosshairOverlay} can stop the crosshair line at
    *  the label instead of running through it; -1 when not top-pinned/active. */
@@ -154,7 +159,14 @@ export function CustomTooltipOverlay({
     }
 
     return {
-      opacity: active ? crosshairOpacity.get() : 0,
+      opacity: resolveCrosshairVisibleOpacity(
+        active,
+        sx,
+        cw,
+        padding.right,
+        crosshairFade,
+        crosshairFadeDistance,
+      ),
       transform: [{ translateX: x }, { translateY: y }],
     };
   });

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);