react-native-livechart 4.12.0 → 4.13.0

package/src/components/LiveChartSeries.tsx

@@ -55,6 +55,7 @@ import { useChartReveal } from "../hooks/useChartReveal";
 import { useChartOverlayContext } from "../hooks/useChartOverlayContext";
 import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
 import { useCrosshairSeries } from "../hooks/useCrosshairSeries";
+import { useCrosshairVisibleOpacity } from "../hooks/useCrosshairVisibleOpacity";
 import { useMarkers } from "../hooks/useMarkers";
 import { useMultiSeriesDegen } from "../hooks/useMultiSeriesDegen";
 import { useMultiSeriesLinePaths } from "../hooks/useMultiSeriesLinePaths";
@@ -463,6 +464,7 @@ function useLiveChartSeriesController({
           maxTime: tooltipMaxTime,
         }
       : undefined,
+    scrubCfg?.clampToPlot ?? false,
   );
 
   // Capture only the shared value in the worklets below. Referencing
@@ -712,6 +714,8 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             badge={false}
             seriesLabelInset={seriesLabelInset}
             gridStyle={gridStyleCfg}
+            labelRightMargin={yAxisCfg.labelRightMargin}
+            gridEndGap={yAxisCfg.gridEndGap}
           />
         </Group>
       )}
@@ -728,6 +732,9 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             palette={palette}
             formatValue={formatValue}
             font={skiaFont}
+            yAxisEntries={yAxisEntries}
+            labelRightMargin={yAxisCfg?.labelRightMargin}
+            gridEndGap={yAxisCfg?.gridEndGap}
           />
         ))}
       </Group>
@@ -888,6 +895,8 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
     palette,
     formatValue,
     skiaFont,
+    yAxisCfg,
+    yAxisEntries,
     degenShakeTransform,
     overlayScrubFade,
   } = model;
@@ -907,6 +916,9 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
           suppressTag={refLineCustom[i]}
           suppressTagWhenOffAxis={refLineOffAxisCustom[i]}
           customTagWidths={refLineCustomTagWidths}
+          yAxisEntries={yAxisEntries}
+          labelRightMargin={yAxisCfg?.labelRightMargin}
+          gridEndGap={yAxisCfg?.gridEndGap}
         />
       ))}
     </Group>
@@ -920,6 +932,53 @@ function SeriesCustomConsumerOverlay({ model }: { model: LiveChartSeriesModel })
   return <ChartOverlayLayer render={renderOverlay!} context={overlayContext} />;
 }
 
+/** Keeps the extra fade mapper opt-in with the per-series tooltip itself. */
+function SeriesTooltipLayer({
+  model,
+  config,
+}: {
+  model: LiveChartSeriesModel;
+  config: NonNullable<LiveChartSeriesModel["seriesTooltipCfg"]>;
+}) {
+  const {
+    crosshair,
+    engine,
+    effectivePadding,
+    scrubCfg,
+    skiaFont,
+    palette,
+    activeSeriesCount,
+  } = model;
+  const activeOpacity = useCrosshairVisibleOpacity(
+    crosshair.scrubX,
+    engine.canvasWidth,
+    effectivePadding.right,
+    crosshair.scrubActive,
+    scrubCfg?.crosshairFade ?? true,
+    scrubCfg?.crosshairFadeDistance ?? 4,
+  );
+  const scrubActive = crosshair.scrubActive;
+  const alwaysShow = config.alwaysShow;
+  const opacity = useDerivedValue(
+    () => (scrubActive.get() ? activeOpacity.get() : alwaysShow ? 1 : 0),
+    [scrubActive, activeOpacity, alwaysShow],
+  );
+
+  return (
+    <PerSeriesTooltipOverlay
+      layout={crosshair.tooltipLayout}
+      font={skiaFont}
+      palette={palette}
+      config={config}
+      seriesCount={activeSeriesCount}
+      opacity={opacity}
+      tooltipBackground={scrubCfg?.tooltipBackground}
+      tooltipColor={scrubCfg?.tooltipColor}
+      tooltipBorderColor={scrubCfg?.tooltipBorderColor}
+    />
+  );
+}
+
 export function LiveChartSeries(props: LiveChartSeriesProps) {
   const model = useLiveChartSeriesController(props);
   const {
@@ -962,8 +1021,6 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     refLineCustomTagWidths,
     overlayScrubFade,
     canvasMode,
-    activeSeriesCount,
-    skiaFont,
   } = model;
 
   // Mirror the Skia overlay fade onto the RN custom-marker sibling so
@@ -1065,7 +1122,14 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                   seriesTooltipCfg?.guideColor ??
                   scrubCfg.crosshairLineColor
                 }
-                crosshairLineWidth={seriesTooltipCfg?.guideWidth}
+                crosshairStrokeWidth={
+                  seriesTooltipCfg?.guideWidth ??
+                  scrubCfg.crosshairStrokeWidth
+                }
+                crosshairOvershoot={scrubCfg.crosshairOvershoot}
+                crosshairFade={scrubCfg.crosshairFade}
+                crosshairFadeDistance={scrubCfg.crosshairFadeDistance}
+                crosshairLineCap={scrubCfg.crosshairLineCap}
                 crosshairDash={
                   seriesTooltipCfg
                     ? seriesTooltipCfg.guideDashPattern
@@ -1079,19 +1143,6 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
             {/* Per-series value labels on top of the scrub dim so the dim never
                 clips them (they track each series' live value, not the scrub). */}
             <SeriesValueLabelLayer model={model} />
-
-            {seriesTooltipCfg && (
-              <PerSeriesTooltipOverlay
-                layout={crosshair.tooltipLayout}
-                font={skiaFont}
-                palette={palette}
-                config={seriesTooltipCfg}
-                seriesCount={activeSeriesCount}
-                tooltipBackground={scrubCfg?.tooltipBackground}
-                tooltipColor={scrubCfg?.tooltipColor}
-                tooltipBorderColor={scrubCfg?.tooltipBorderColor}
-              />
-            )}
           </Canvas>
 
           {/* RN labels floated over the canvas (sibling of <Canvas>, an RN
@@ -1153,6 +1204,22 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
             </Animated.View>
           )}
 
+          {/* A dedicated transparent Canvas keeps the UI-thread tooltip above
+              custom RN annotations. Rendering it in the primary Canvas would
+              put every post-Canvas `renderReferenceLine` sibling above it and
+              produce mixed stacking through translucent custom tags. */}
+          {seriesTooltipCfg && (
+            <View
+              testID="live-chart-series-tooltip-overlay"
+              pointerEvents="none"
+              style={StyleSheet.absoluteFill}
+            >
+              <Canvas style={StyleSheet.absoluteFill}>
+                <SeriesTooltipLayer model={model} config={seriesTooltipCfg} />
+              </Canvas>
+            </View>
+          )}
+
           {/* Custom consumer overlay — topmost RN sibling with the live plot
               rect, including this multi-series chart's resolved axis inset. */}
           {renderOverlay && <SeriesCustomConsumerOverlay model={model} />}

package/src/components/PerSeriesTooltipOverlay.tsx

@@ -232,6 +232,7 @@ export function PerSeriesTooltipOverlay({
   palette,
   config,
   seriesCount,
+  opacity,
   tooltipBackground,
   tooltipColor,
   tooltipBorderColor,
@@ -241,6 +242,8 @@ export function PerSeriesTooltipOverlay({
   palette: LiveChartPalette;
   config: ResolvedPerSeriesTooltipConfig;
   seriesCount: number;
+  /** Active crosshair opacity; idle `alwaysShow` pills stay fully visible. */
+  opacity?: SharedValue<number> | DerivedValue<number>;
   tooltipBackground?: string;
   tooltipColor?: string;
   tooltipBorderColor?: string;
@@ -258,7 +261,7 @@ export function PerSeriesTooltipOverlay({
     config.seriesPillBorderColor ?? tooltipBorderColor;
 
   return (
-    <Group>
+    <Group opacity={opacity}>
       <TimePill
         layout={layout}
         font={font}

package/src/components/ReferenceLineOverlay.tsx

@@ -9,6 +9,7 @@ import {
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { YAxisEntry } from "../draw/grid";
 import type { ChartPadding } from "../draw/line";
 import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
 import { usePathBuilder } from "../hooks/usePathBuilder";
@@ -85,6 +86,12 @@ type ReferenceLineOverlayProps = {
   dragValues?: SharedValue<number[]>;
   /** This line's index into {@link dragValues}. */
   index?: number;
+  /** Y-axis entries used to match a right-anchored grid endpoint. */
+  yAxisEntries?: SharedValue<YAxisEntry[]> | null;
+  /** Enables clipping to the right-anchored Y-axis label column. */
+  labelRightMargin?: number;
+  /** Gap between the drawn line endpoint and the label column. */
+  gridEndGap?: number;
 };
 
 export function ReferenceLineOverlay({
@@ -102,6 +109,9 @@ export function ReferenceLineOverlay({
   groupHidden,
   dragValues,
   index = 0,
+  yAxisEntries,
+  labelRightMargin,
+  gridEndGap,
 }: ReferenceLineOverlayProps) {
   const form = referenceLineForm(line);
   const isBand = form === "value-band" || form === "time-band";
@@ -141,6 +151,10 @@ export function ReferenceLineOverlay({
     badgeFont,
     dragValues,
     index,
+    yAxisEntries ?? undefined,
+    labelRightMargin,
+    gridEndGap,
+    font,
   );
 
   const labelColor =

package/src/components/YAxisOverlay.tsx

@@ -7,7 +7,10 @@ import {
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { BADGE_METRICS_DEFAULTS, MAX_Y_LABELS } from "../constants";
 import type { ResolvedGridStyleConfig } from "../core/resolveConfig";
-import type { YAxisEntry } from "../draw/grid";
+import {
+  rightAnchoredYAxisColumnLayout,
+  type YAxisEntry,
+} from "../draw/grid";
 import {
   badgeTailAndCap,
   gutterCenteredTextLeftX,
@@ -57,6 +60,8 @@ export function YAxisOverlay({
   gridStyle,
   variant = "all",
   float = false,
+  labelRightMargin,
+  gridEndGap = 0,
 }: {
   entries: SharedValue<YAxisEntry[]>;
   engine: ChartEngineLayout;
@@ -92,6 +97,10 @@ export function YAxisOverlay({
    * plot) instead of centering them in a reserved gutter. See {@link YAxisConfig.float}.
    */
   float?: boolean;
+  /** Fixed canvas-edge margin for a shared left-aligned label column. */
+  labelRightMargin?: number;
+  /** Gap between the grid-line end and the shared label column. */
+  gridEndGap?: number;
 }) {
   const gridColor = gridStyle?.color ?? palette.gridLine;
   const gridWidth = gridStyle?.strokeWidth ?? 1;
@@ -99,14 +108,26 @@ export function YAxisOverlay({
   const gridOpacity = gridStyle?.opacity ?? 1;
   const gridBuilder = usePathBuilder();
 
+  const rightAnchoredColumn = useDerivedValue(() => {
+    if (labelRightMargin === undefined) return null;
+    return rightAnchoredYAxisColumnLayout(
+      engine.canvasWidth.get(),
+      entries.get(),
+      font,
+      labelRightMargin,
+      gridEndGap,
+    );
+  });
+
   const gridLinesPath = useDerivedValue(() => {
     const b = gridBuilder.value;
     if (variant === "labels") return b.detach();
     const items = entries.get();
     const w = engine.canvasWidth.get();
+    const lineX2 = rightAnchoredColumn.get()?.gridEndX ?? w - padding.right;
     for (let i = 0; i < items.length; i++) {
       b.moveTo(padding.left, items[i].y);
-      b.lineTo(w - padding.right, items[i].y);
+      b.lineTo(lineX2, items[i].y);
     }
     return b.detach();
   });
@@ -120,6 +141,7 @@ export function YAxisOverlay({
     const w = engine.canvasWidth.get();
     const fm = font.getMetrics();
     const baselineOffset = (fm.ascent + fm.descent) / 2;
+    const columnX = rightAnchoredColumn.get()?.labelX;
     const labelHeight = fm.descent - fm.ascent;
     const badgeIsVisible = badgeOpacity === undefined || badgeOpacity.get() > 0;
     const resolvedBadgeCenterY = badgeCenterY && badgeIsVisible
@@ -133,13 +155,16 @@ export function YAxisOverlay({
     for (let i = 0; i < items.length; i++) {
       const e = items[i];
       const textW = measureFontTextWidth(font, e.label);
-      const x = float
-        ? gutterRightAlignedTextLeftX(w, textW, FLOAT_LABEL_RIGHT_MARGIN)
-        : badge
-          ? pillTextLeftX(w, padding.right, leftInset, textW, badgeMetrics)
-          : seriesLabelInset > 0
-            ? gutterRightAlignedTextLeftX(w, textW)
-            : gutterCenteredTextLeftX(w, padding.right, textW);
+      const x =
+        columnX !== undefined
+          ? columnX
+          : float
+            ? gutterRightAlignedTextLeftX(w, textW, FLOAT_LABEL_RIGHT_MARGIN)
+            : badge
+              ? pillTextLeftX(w, padding.right, leftInset, textW, badgeMetrics)
+              : seriesLabelInset > 0
+                ? gutterRightAlignedTextLeftX(w, textW)
+                : gutterCenteredTextLeftX(w, padding.right, textW);
       result.push({
         x,
         y: e.y - baselineOffset,

package/src/core/resolveConfig.ts

@@ -89,6 +89,10 @@ export interface ResolvedYAxisConfig {
   minGap: number;
   /** Fixed label count (≥ 2), or 0 for the dynamic nice-interval grid. */
   count: number;
+  /** undefined → keep the default centered-gutter label placement. */
+  labelRightMargin: number | undefined;
+  /** undefined → no gap; inert unless labelRightMargin is set. */
+  gridEndGap: number | undefined;
   /** Float the axis over a full-width plot (no reserved right gutter). */
   float: boolean;
 }
@@ -151,6 +155,16 @@ export interface ResolvedScrubConfig {
   dimOpacity: number;
   /** undefined → palette.crosshairLine */
   crosshairLineColor: string | undefined;
+  /** Vertical crosshair line width in px. */
+  crosshairStrokeWidth: number;
+  /** Extension past the plot's top and bottom edges in px. */
+  crosshairOvershoot: number;
+  /** Fade the crosshair near the live edge. */
+  crosshairFade: boolean;
+  /** Visible-crosshair fade distance near the live edge in px. */
+  crosshairFadeDistance: number;
+  /** undefined preserves the existing Skia line-cap default. */
+  crosshairLineCap: "butt" | "round" | "square" | undefined;
   /** Dash intervals `[on, off, …]` for the crosshair line; undefined → solid. */
   crosshairDash: number[] | undefined;
   /** undefined → palette.crosshairDim */
@@ -175,6 +189,8 @@ export interface ResolvedScrubConfig {
   panGestureDelay: number;
   /** Fade markers + reference lines out while scrubbing. */
   hideOverlaysOnScrub: boolean;
+  /** Reject outside plain-scrub starts and clamp active scrub X to the plot. */
+  clampToPlot: boolean;
 }
 
 export interface ResolvedPerSeriesTooltipConfig {
@@ -465,6 +481,8 @@ export function resolveBadge(
 const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
   minGap: 36,
   count: 0,
+  labelRightMargin: undefined,
+  gridEndGap: undefined,
   float: false,
 };
 
@@ -664,6 +682,11 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   seriesTooltip: null,
   dimOpacity: 0.3,
   crosshairLineColor: undefined,
+  crosshairStrokeWidth: 1,
+  crosshairOvershoot: 0,
+  crosshairFade: true,
+  crosshairFadeDistance: 4,
+  crosshairLineCap: undefined,
   crosshairDash: undefined,
   crosshairDimColor: undefined,
   tooltipBackground: undefined,
@@ -676,6 +699,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   tooltipShowTime: true,
   panGestureDelay: 0,
   hideOverlaysOnScrub: false,
+  clampToPlot: false,
 };
 
 const PER_SERIES_TOOLTIP_DEFAULTS: ResolvedPerSeriesTooltipConfig = {
@@ -743,6 +767,11 @@ export function resolveScrub(
     const seriesTooltip =
       typeof prop === "object" ? prop.seriesTooltip : undefined;
     resolved.seriesTooltip = resolvePerSeriesTooltip(seriesTooltip);
+    resolved.crosshairOvershoot = Math.max(0, resolved.crosshairOvershoot);
+    resolved.crosshairFadeDistance = Math.max(
+      0,
+      resolved.crosshairFadeDistance,
+    );
   }
   return resolved;
 }

package/src/draw/grid.ts

@@ -1,4 +1,6 @@
 import { GRID_METRICS_DEFAULTS, MAX_Y_LABELS } from "../constants";
+import type { SkFont } from "@shopify/react-native-skia";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import { lerp } from "../math/lerp";
 import type { GridMetrics } from "../types";
 
@@ -8,6 +10,37 @@ export interface YAxisEntry {
   alpha: number;
 }
 
+export interface RightAnchoredYAxisColumnLayout {
+  /** Shared left X for every label in the column. */
+  labelX: number;
+  /** Grid/reference-line end X immediately before the column gap. */
+  gridEndX: number;
+}
+
+/**
+ * Measure the widest Y-axis label and anchor the shared left-aligned column to
+ * a fixed canvas-edge margin. Shared by the axis and reference-line worklets so
+ * their right edges cannot drift apart.
+ */
+export function rightAnchoredYAxisColumnLayout(
+  canvasWidth: number,
+  entries: readonly YAxisEntry[],
+  font: SkFont,
+  labelRightMargin: number,
+  gridEndGap = 0,
+): RightAnchoredYAxisColumnLayout {
+  "worklet";
+  let maxTextW = 0;
+  for (let i = 0; i < entries.length; i++) {
+    maxTextW = Math.max(
+      maxTextW,
+      measureFontTextWidth(font, entries[i].label),
+    );
+  }
+  const labelX = canvasWidth - labelRightMargin - maxTextW;
+  return { labelX, gridEndX: labelX - gridEndGap };
+}
+
 /**
  * Fixed-count Y-axis: place exactly `count` price labels evenly **in pixels**
  * across the plot band — top = `displayMax`, bottom = `displayMin`. Values track

package/src/hooks/crosshairShared.ts

@@ -12,13 +12,87 @@ const TOOLTIP_LINE_GAP = 4;
 const TOOLTIP_OFFSET_X = 12;
 const TOOLTIP_EDGE_GAP = 4;
 const TOOLTIP_TOP_MARGIN = 8;
-const FADE_ZONE = 4;
 
 /** Horizontal travel required before a plain scrub claims the touch. */
 export const SCRUB_ACTIVATE_X_PX = 20;
 /** Vertical travel that fails a plain scrub so a parent scroll gesture can win. */
 export const SCRUB_FAIL_Y_PX = 10;
 
+/** Clamp an X pixel to the plot's horizontal bounds. */
+export function clampPlotX(
+  x: number,
+  padLeft: number,
+  canvasWidth: number,
+  padRight: number,
+): number {
+  "worklet";
+  return Math.min(canvasWidth - padRight, Math.max(padLeft, x));
+}
+
+export interface ScrubHitSlop {
+  left?: number;
+  right?: number;
+  bottom?: number;
+}
+
+/** Build touch-down bounds for a scrub recognizer. */
+export function resolveScrubHitSlop(
+  padding: ChartPadding,
+  clampToPlot: boolean,
+  bottomExclude = 0,
+): ScrubHitSlop | undefined {
+  if (!clampToPlot && bottomExclude <= 0) return undefined;
+  return {
+    ...(clampToPlot
+      ? { left: -padding.left, right: -padding.right }
+      : {}),
+    ...(bottomExclude > 0 ? { bottom: -bottomExclude } : {}),
+  };
+}
+
+interface ScrubGestureValue<T> {
+  get(): T;
+  set(value: T): void;
+}
+
+/** Start plain scrubbing; the recognizer gates out-of-plot touch origins. */
+export function startPlainScrub(
+  x: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  clampToPlot: boolean,
+  scrubX: ScrubGestureValue<number>,
+  scrubActive: ScrubGestureValue<boolean>,
+  gestureStarted: ScrubGestureValue<boolean>,
+): void {
+  "worklet";
+  if (clampToPlot) {
+    scrubX.set(clampPlotX(x, padding.left, canvasWidth, padding.right));
+  } else {
+    scrubX.set(x);
+  }
+  scrubActive.set(true);
+  gestureStarted.set(true);
+}
+
+/** Track plain scrubbing, clamping gestures accepted by the recognizer. */
+export function updatePlainScrub(
+  x: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  clampToPlot: boolean,
+  scrubX: ScrubGestureValue<number>,
+  scrubActive: ScrubGestureValue<boolean>,
+): void {
+  "worklet";
+  if (clampToPlot) {
+    if (!scrubActive.get()) return;
+    scrubX.set(clampPlotX(x, padding.left, canvasWidth, padding.right));
+  } else {
+    scrubX.set(x);
+  }
+}
+
 /** Measure rendered text so the pill and its content share the same centre. */
 function measureTooltipTextWidth(
   font: SkFont,
@@ -217,20 +291,23 @@ export function computeScrubTime(
 }
 
 /**
- * Crosshair opacity: fades 1→0 over FADE_ZONE px as the crosshair
- * approaches the live dot at the right chart edge.
+ * Crosshair opacity: fades 1→0 over `fadeDistance` px as the crosshair
+ * approaches the live dot at the right chart edge. A zero distance removes
+ * the ramp while keeping the crosshair hidden at and beyond the live edge.
  */
 export function computeCrosshairOpacity(
   scrubActive: boolean,
   scrubX: number,
   canvasWidth: number,
   paddingRight: number,
+  fadeDistance = 4,
 ): number {
   "worklet";
   if (!scrubActive) return 0;
   const dotX = canvasWidth - paddingRight;
   const dist = dotX - scrubX;
-  return Math.min(1, Math.max(0, dist / FADE_ZONE));
+  if (fadeDistance <= 0) return dist > 0 ? 1 : 0;
+  return Math.min(1, Math.max(0, dist / fadeDistance));
 }
 
 /**