react-native-livechart 4.11.0 → 4.12.0

package/src/components/LiveChartSeries.tsx

@@ -28,7 +28,6 @@ import {
   lineStyleSignatureFromArray,
   resolveMultiSeriesLineColorsSnapshot,
   resolveMultiSeriesLineStylesSnapshot,
-  type SeriesLineStyle,
 } from "../core/multiSeriesLayout";
 import {
   resolveAxisLabel,
@@ -53,6 +52,7 @@ import { pulseRadialOutset } from "../draw/line";
 import { resolveChartLayout } from "../hooks/resolveChartLayout";
 import { useCanvasLayout } from "../hooks/useCanvasLayout";
 import { useChartReveal } from "../hooks/useChartReveal";
+import { useChartOverlayContext } from "../hooks/useChartOverlayContext";
 import { useChartSkiaFont } from "../hooks/useChartSkiaFont";
 import { useCrosshairSeries } from "../hooks/useCrosshairSeries";
 import { useMarkers } from "../hooks/useMarkers";
@@ -70,7 +70,10 @@ import {
 } from "../lib/format";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import { MONO_FONT_FAMILY } from "../lib/monoFontFamily";
-import { collectReferenceValues } from "../math/referenceLines";
+import {
+  collectReferenceValues,
+  referenceLineReactKeys,
+} from "../math/referenceLines";
 import {
   applyPaletteOverride,
   leftEdgeFadeColorsFromBgRgb,
@@ -78,6 +81,7 @@ import {
 } from "../theme";
 import type { LiveChartSeriesProps, Marker, SeriesConfig } from "../types";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
+import { ChartOverlayLayer } from "./ChartOverlayLayer";
 import {
   ExtremaConnectorOverlay,
   labelConnector,
@@ -96,6 +100,7 @@ import { MultiSeriesDots } from "./MultiSeriesDots";
 import { MultiSeriesStroke } from "./MultiSeriesStroke";
 import { MultiSeriesValueLabels } from "./MultiSeriesValueLabels";
 import { MultiSeriesValueLines } from "./MultiSeriesValueLines";
+import { PerSeriesTooltipOverlay } from "./PerSeriesTooltipOverlay";
 import { ReferenceLineOverlay } from "./ReferenceLineOverlay";
 import { SeriesToggleChips } from "./SeriesToggleChips";
 import { XAxisOverlay } from "./XAxisOverlay";
@@ -177,7 +182,9 @@ function useLiveChartSeriesController({
   markerHitRadius = 16,
   markerCluster,
   renderMarker,
+  renderOverlay,
   renderReferenceLine,
+  renderOffAxisReferenceLine,
   leftEdgeFade = true,
 }: LiveChartSeriesProps) {
   const emptyMarkers = useSharedValue<Marker[]>([]);
@@ -190,6 +197,10 @@ function useLiveChartSeriesController({
   const bottomLabelCfg = resolveAxisLabel(bottomLabel);
   const scrubCfg = resolveScrub(scrub);
   const scrubEnabled = scrubCfg !== null;
+  // Opt-in and subordinate to the existing master `tooltip` switch. Keeping
+  // this null by default preserves LiveChartSeries' historical guide-only scrub.
+  const seriesTooltipCfg =
+    scrubCfg?.tooltip === true ? scrubCfg.seriesTooltip : null;
 
   // Time-scroll + pinch-zoom (mirrors LiveChart). LiveChartSeries has no static
   // mode, so these gate on the props alone. `holdToScrub` requires the scrub
@@ -216,8 +227,8 @@ function useLiveChartSeriesController({
 
   // Multi-series defaults the scrub selection dot OFF: it can only track one
   // line (the leading series), which reads as a bug next to the other series.
-  // The crosshair line + per-series tooltip stack already mark the scrub point.
-  // Passing `selectionDot` explicitly (true / config) still opts it in.
+  // The crosshair line (and the opt-in tooltip's per-series intersection dots)
+  // mark the scrub point. Passing `selectionDot` explicitly still opts it in.
   const selectionDotCfg = resolveSelectionDot(selectionDot ?? false);
   const gridStyleCfg = resolveGridStyle(gridStyle);
   const dotCfg = resolveMultiSeriesDot(dotProp);
@@ -237,6 +248,17 @@ function useLiveChartSeriesController({
     allRefLines,
     renderReferenceLine,
   );
+  // A full custom tag owns both states, so it takes precedence over an
+  // off-axis-only renderer for the same line.
+  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[]>([]);
 
   const palette = applyPaletteOverride(
     resolveTheme(accentColor, theme),
@@ -266,6 +288,7 @@ function useLiveChartSeriesController({
     // render scope for memoization, which trips Reanimated's strict-mode warning;
     // it leaves the `.get()` method call inside the effect.
     // 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
     setSeriesSnapshot(series.get().slice());
   }, [series]);
 
@@ -407,6 +430,20 @@ function useLiveChartSeriesController({
     skiaFont,
   );
 
+  // 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);
+  // `liveEdge` includes the optional right breathing-room buffer. The time pill
+  // must clamp against the real "now" anchor so its live bucket never ends in
+  // that future buffer.
+  const tooltipMaxTime = useDerivedValue(
+    () => engine.liveEdge.get() - windowBuffer * timeWindow,
+  );
+
   const crosshair = useCrosshairSeries(
     engine,
     effectivePadding,
@@ -415,6 +452,17 @@ function useLiveChartSeriesController({
     scrubHoldMs,
     onGestureStart,
     onGestureEnd,
+    scrollActive,
+    seriesTooltipCfg
+      ? {
+          config: seriesTooltipCfg,
+          formatValue,
+          formatTime,
+          font: skiaFont,
+          colors: lineColors,
+          maxTime: tooltipMaxTime,
+        }
+      : undefined,
   );
 
   // Capture only the shared value in the worklets below. Referencing
@@ -458,6 +506,10 @@ function useLiveChartSeriesController({
     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,
     onScrollStart: () => {
       "worklet";
       crosshairScrubActive.set(false);
@@ -535,6 +587,7 @@ function useLiveChartSeriesController({
     yAxisCfg,
     xAxisCfg,
     scrubCfg,
+    seriesTooltipCfg,
     gridStyleCfg,
     dotCfg,
     dotOuterRadius,
@@ -542,7 +595,10 @@ function useLiveChartSeriesController({
     degenCfg,
     metricsCfg,
     allRefLines,
+    refLineKeys,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     leftEdgeFadeCfg,
     // theme / layout / fonts
     palette,
@@ -580,7 +636,9 @@ function useLiveChartSeriesController({
     markerGroupOpacity,
     overlayScrubFade,
     renderMarker,
+    renderOverlay,
     renderReferenceLine,
+    renderOffAxisReferenceLine,
     // selection dot: resolved config + fallback color (the leading series' color)
     selectionDot: selectionDotCfg,
     selectionColor: lineColors[0],
@@ -638,6 +696,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     loadingSpeed,
     canvasMode,
     activeSeriesCount,
+    refLineKeys,
   } = model;
 
   return (
@@ -657,15 +716,12 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
         </Group>
       )}
 
-      {/* Reference lines are index-addressed throughout the drag/press API, and
-          duplicate working orders may share all visible content. Positional keys
-          keep both orders mounted without collapsing them to one React child.
-          Fade group lets `scrub.hideOverlaysOnScrub` ease the lines out. */}
+      {/* Fade group lets `scrub.hideOverlaysOnScrub` ease the lines out. Explicit
+          ids keep each reference line mounted when the caller reorders it. */}
       <Group opacity={overlayScrubFade}>
         {allRefLines.map((rl, i) => (
-          /* react-doctor-disable-next-line react-doctor/no-array-index-as-key */
           <ReferenceLineOverlay
-            key={i}
+            key={refLineKeys[i]}
             engine={engine}
             padding={effectivePadding}
             line={rl}
@@ -823,7 +879,10 @@ function SeriesValueLabelLayer({ model }: { model: LiveChartSeriesModel }) {
 function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
   const {
     allRefLines,
+    refLineKeys,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     engine,
     effectivePadding,
     palette,
@@ -831,15 +890,13 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
     skiaFont,
     degenShakeTransform,
     overlayScrubFade,
-    canvasMode,
   } = model;
   if (allRefLines.length === 0) return null;
   return (
     <Group transform={degenShakeTransform} opacity={overlayScrubFade}>
       {allRefLines.map((rl, i) => (
-        /* react-doctor-disable-next-line react-doctor/no-array-index-as-key */
         <ReferenceLineOverlay
-          key={i}
+          key={refLineKeys[i]}
           engine={engine}
           padding={effectivePadding}
           line={rl}
@@ -848,12 +905,21 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
           font={skiaFont}
           badgeLayer
           suppressTag={refLineCustom[i]}
+          suppressTagWhenOffAxis={refLineOffAxisCustom[i]}
+          customTagWidths={refLineCustomTagWidths}
         />
       ))}
     </Group>
   );
 }
 
+/** Owns the price/time projection worklets for the multi-series custom overlay. */
+function SeriesCustomConsumerOverlay({ model }: { model: LiveChartSeriesModel }) {
+  const { engine, effectivePadding, renderOverlay } = model;
+  const overlayContext = useChartOverlayContext(engine, effectivePadding);
+  return <ChartOverlayLayer render={renderOverlay!} context={overlayContext} />;
+}
+
 export function LiveChartSeries(props: LiveChartSeriesProps) {
   const model = useLiveChartSeriesController(props);
   const {
@@ -871,6 +937,7 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     effectivePadding,
     engine,
     scrubCfg,
+    seriesTooltipCfg,
     crosshair,
     palette,
     dotCfg,
@@ -886,11 +953,17 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     markersSV,
     markerClusterCfg,
     renderMarker,
+    renderOverlay,
     renderReferenceLine,
+    renderOffAxisReferenceLine,
     allRefLines,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     overlayScrubFade,
     canvasMode,
+    activeSeriesCount,
+    skiaFont,
   } = model;
 
   // Mirror the Skia overlay fade onto the RN custom-marker sibling so
@@ -988,8 +1061,16 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                 selectionColor={selectionColor}
                 dimOpacity={scrubCfg.dimOpacity}
                 liveDotExtent={liveDotExtent}
-                crosshairLineColor={scrubCfg.crosshairLineColor}
-                crosshairDash={scrubCfg.crosshairDash}
+                crosshairLineColor={
+                  seriesTooltipCfg?.guideColor ??
+                  scrubCfg.crosshairLineColor
+                }
+                crosshairLineWidth={seriesTooltipCfg?.guideWidth}
+                crosshairDash={
+                  seriesTooltipCfg
+                    ? seriesTooltipCfg.guideDashPattern
+                    : scrubCfg.crosshairDash
+                }
                 crosshairDimColor={scrubCfg.crosshairDimColor}
                 opaqueCanvas={canvasMode === "opaque"}
               />
@@ -998,6 +1079,19 @@ 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
@@ -1017,7 +1111,8 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
               above the left-edge fade and scrub overlay. The box-none fade wrapper
               keeps `scrub.hideOverlaysOnScrub` behavior aligned with Skia. */}
           {((markersActive && renderMarker) ||
-            (renderReferenceLine && allRefLines.length > 0)) && (
+            ((renderReferenceLine || renderOffAxisReferenceLine) &&
+              allRefLines.length > 0)) && (
             <Animated.View
               pointerEvents="box-none"
               style={[StyleSheet.absoluteFill, overlayFadeStyle]}
@@ -1040,10 +1135,27 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                   engine={engine}
                   padding={effectivePadding}
                   formatValue={formatValue}
+                  tagWidths={refLineCustomTagWidths}
+                />
+              )}
+              {renderOffAxisReferenceLine && allRefLines.length > 0 && (
+                <CustomReferenceLineOverlay
+                  lines={allRefLines}
+                  renderReferenceLine={renderOffAxisReferenceLine}
+                  custom={refLineOffAxisCustom}
+                  engine={engine}
+                  padding={effectivePadding}
+                  formatValue={formatValue}
+                  tagWidths={refLineCustomTagWidths}
+                  offAxisOnly
                 />
               )}
             </Animated.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} />}
         </View>
       </GestureDetector>
       {legendCfg.position === "bottom" ? legend : null}

package/src/components/PerSeriesTooltipOverlay.tsx

@@ -0,0 +1,287 @@
+import {
+  Circle,
+  Group,
+  RoundedRect,
+  Text as SkiaText,
+  type SkFont,
+} from "@shopify/react-native-skia";
+import {
+  useDerivedValue,
+  type DerivedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import type { ResolvedPerSeriesTooltipConfig } from "../core/resolveConfig";
+import type { TooltipLayout } from "../hooks/crosshairShared";
+import type { LiveChartPalette } from "../types";
+
+type TooltipLayoutValue =
+  | SharedValue<TooltipLayout>
+  | DerivedValue<TooltipLayout>;
+
+function TimePill({
+  layout,
+  font,
+  palette,
+  config,
+  background,
+  color,
+  borderColor,
+}: {
+  layout: TooltipLayoutValue;
+  font: SkFont;
+  palette: LiveChartPalette;
+  config: ResolvedPerSeriesTooltipConfig;
+  background?: string;
+  color?: string;
+  borderColor?: string;
+}) {
+  const opacity = useDerivedValue(() =>
+    layout.value.perSeries?.timePill ? 1 : 0,
+  );
+  const x = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.x ?? -400,
+  );
+  const y = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.y ?? 0,
+  );
+  const w = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.w ?? 0,
+  );
+  const h = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.h ?? 0,
+  );
+  const text = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.text ?? "",
+  );
+  const textX = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.textX ?? -400,
+  );
+  const baselineY = useDerivedValue(
+    () => layout.value.perSeries?.timePill?.baselineY ?? 0,
+  );
+  const clip = useDerivedValue(() => ({
+    x: layout.value.perSeries?.timePill?.x ?? -400,
+    y: layout.value.perSeries?.timePill?.y ?? 0,
+    width: layout.value.perSeries?.timePill?.w ?? 0,
+    height: layout.value.perSeries?.timePill?.h ?? 0,
+  }));
+
+  return (
+    <Group opacity={opacity}>
+      <RoundedRect
+        x={x}
+        y={y}
+        width={w}
+        height={h}
+        r={config.timePillRadius}
+        color={background ?? palette.tooltipBg}
+      />
+      <RoundedRect
+        x={x}
+        y={y}
+        width={w}
+        height={h}
+        r={config.timePillRadius}
+        color={borderColor ?? palette.tooltipBorder}
+        style="stroke"
+        strokeWidth={1}
+      />
+      <Group clip={clip}>
+        <SkiaText
+          x={textX}
+          y={baselineY}
+          text={text}
+          font={font}
+          color={color ?? palette.tooltipText}
+        />
+      </Group>
+    </Group>
+  );
+}
+
+function SeriesPill({
+  index,
+  layout,
+  font,
+  palette,
+  config,
+  background,
+  labelColor,
+  valueColor,
+  borderColor,
+}: {
+  index: number;
+  layout: TooltipLayoutValue;
+  font: SkFont;
+  palette: LiveChartPalette;
+  config: ResolvedPerSeriesTooltipConfig;
+  background?: string;
+  labelColor?: string;
+  valueColor?: string;
+  borderColor?: string;
+}) {
+  const opacity = useDerivedValue(() => {
+    const pills = layout.value.perSeries?.pills;
+    return pills && index < pills.length ? 1 : 0;
+  });
+  const x = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.x ?? -400,
+  );
+  const y = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.y ?? 0,
+  );
+  const w = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.w ?? 0,
+  );
+  const h = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.h ?? 0,
+  );
+  const anchorX = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.anchorX ?? -400,
+  );
+  const anchorY = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.anchorY ?? -400,
+  );
+  const dotX = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.dotX ?? -400,
+  );
+  const dotY = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.dotY ?? -400,
+  );
+  const dotColor = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.color ?? palette.tooltipText,
+  );
+  const label = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.label ?? "",
+  );
+  const labelX = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.labelX ?? -400,
+  );
+  const value = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.value ?? "",
+  );
+  const valueX = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.valueX ?? -400,
+  );
+  const baselineY = useDerivedValue(
+    () => layout.value.perSeries?.pills[index]?.baselineY ?? 0,
+  );
+  const clip = useDerivedValue(() => ({
+    x: layout.value.perSeries?.pills[index]?.x ?? -400,
+    y: layout.value.perSeries?.pills[index]?.y ?? 0,
+    width: layout.value.perSeries?.pills[index]?.w ?? 0,
+    height: layout.value.perSeries?.pills[index]?.h ?? 0,
+  }));
+
+  return (
+    <Group opacity={opacity}>
+      <Circle
+        cx={anchorX}
+        cy={anchorY}
+        r={config.intersectionDotSize / 2}
+        color={dotColor}
+      />
+      <RoundedRect
+        x={x}
+        y={y}
+        width={w}
+        height={h}
+        r={config.seriesPillRadius}
+        color={background ?? palette.tooltipBg}
+      />
+      <RoundedRect
+        x={x}
+        y={y}
+        width={w}
+        height={h}
+        r={config.seriesPillRadius}
+        color={borderColor ?? palette.tooltipBorder}
+        style="stroke"
+        strokeWidth={1}
+      />
+      <Group clip={clip}>
+        <Circle
+          cx={dotX}
+          cy={dotY}
+          r={config.seriesPillDotSize / 2}
+          color={dotColor}
+        />
+        <SkiaText
+          x={labelX}
+          y={baselineY}
+          text={label}
+          font={font}
+          color={labelColor ?? palette.tooltipText}
+        />
+        <SkiaText
+          x={valueX}
+          y={baselineY}
+          text={value}
+          font={font}
+          color={valueColor ?? labelColor ?? palette.tooltipText}
+        />
+      </Group>
+    </Group>
+  );
+}
+
+/** Skia-only per-series tooltip renderer; every position is SharedValue-driven. */
+export function PerSeriesTooltipOverlay({
+  layout,
+  font,
+  palette,
+  config,
+  seriesCount,
+  tooltipBackground,
+  tooltipColor,
+  tooltipBorderColor,
+}: {
+  layout: TooltipLayoutValue;
+  font: SkFont;
+  palette: LiveChartPalette;
+  config: ResolvedPerSeriesTooltipConfig;
+  seriesCount: number;
+  tooltipBackground?: string;
+  tooltipColor?: string;
+  tooltipBorderColor?: string;
+}) {
+  const timeBackground =
+    config.timePillBackground ?? tooltipBackground;
+  const timeColor = config.timePillColor ?? tooltipColor;
+  const timeBorder =
+    config.timePillBorderColor ?? tooltipBorderColor;
+  const seriesBackground =
+    config.seriesPillBackground ?? tooltipBackground;
+  const seriesLabelColor =
+    config.seriesPillLabelColor ?? tooltipColor;
+  const seriesBorder =
+    config.seriesPillBorderColor ?? tooltipBorderColor;
+
+  return (
+    <Group>
+      <TimePill
+        layout={layout}
+        font={font}
+        palette={palette}
+        config={config}
+        background={timeBackground}
+        color={timeColor}
+        borderColor={timeBorder}
+      />
+      {Array.from({ length: seriesCount }, (_, index) => (
+        <SeriesPill
+          key={index}
+          index={index}
+          layout={layout}
+          font={font}
+          palette={palette}
+          config={config}
+          background={seriesBackground}
+          labelColor={seriesLabelColor}
+          valueColor={config.seriesPillValueColor}
+          borderColor={seriesBorder}
+        />
+      ))}
+    </Group>
+  );
+}