react-native-livechart 4.11.0 → 4.13.0

package/src/components/LiveChartSeries.tsx

@@ -28,7 +28,6 @@ import {
   lineStyleSignatureFromArray,
   resolveMultiSeriesLineColorsSnapshot,
   resolveMultiSeriesLineStylesSnapshot,
-  type SeriesLineStyle,
 } from "../core/multiSeriesLayout";
 import {
   resolveAxisLabel,
@@ -53,8 +52,10 @@ 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 { useCrosshairVisibleOpacity } from "../hooks/useCrosshairVisibleOpacity";
 import { useMarkers } from "../hooks/useMarkers";
 import { useMultiSeriesDegen } from "../hooks/useMultiSeriesDegen";
 import { useMultiSeriesLinePaths } from "../hooks/useMultiSeriesLinePaths";
@@ -70,7 +71,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 +82,7 @@ import {
 } from "../theme";
 import type { LiveChartSeriesProps, Marker, SeriesConfig } from "../types";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
+import { ChartOverlayLayer } from "./ChartOverlayLayer";
 import {
   ExtremaConnectorOverlay,
   labelConnector,
@@ -96,6 +101,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 +183,9 @@ function useLiveChartSeriesController({
   markerHitRadius = 16,
   markerCluster,
   renderMarker,
+  renderOverlay,
   renderReferenceLine,
+  renderOffAxisReferenceLine,
   leftEdgeFade = true,
 }: LiveChartSeriesProps) {
   const emptyMarkers = useSharedValue<Marker[]>([]);
@@ -190,6 +198,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 +228,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 +249,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 +289,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 +431,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 +453,18 @@ function useLiveChartSeriesController({
     scrubHoldMs,
     onGestureStart,
     onGestureEnd,
+    scrollActive,
+    seriesTooltipCfg
+      ? {
+          config: seriesTooltipCfg,
+          formatValue,
+          formatTime,
+          font: skiaFont,
+          colors: lineColors,
+          maxTime: tooltipMaxTime,
+        }
+      : undefined,
+    scrubCfg?.clampToPlot ?? false,
   );
 
   // Capture only the shared value in the worklets below. Referencing
@@ -458,6 +508,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 +589,7 @@ function useLiveChartSeriesController({
     yAxisCfg,
     xAxisCfg,
     scrubCfg,
+    seriesTooltipCfg,
     gridStyleCfg,
     dotCfg,
     dotOuterRadius,
@@ -542,7 +597,10 @@ function useLiveChartSeriesController({
     degenCfg,
     metricsCfg,
     allRefLines,
+    refLineKeys,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     leftEdgeFadeCfg,
     // theme / layout / fonts
     palette,
@@ -580,7 +638,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 +698,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     loadingSpeed,
     canvasMode,
     activeSeriesCount,
+    refLineKeys,
   } = model;
 
   return (
@@ -653,25 +714,27 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             badge={false}
             seriesLabelInset={seriesLabelInset}
             gridStyle={gridStyleCfg}
+            labelRightMargin={yAxisCfg.labelRightMargin}
+            gridEndGap={yAxisCfg.gridEndGap}
           />
         </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}
             palette={palette}
             formatValue={formatValue}
             font={skiaFont}
+            yAxisEntries={yAxisEntries}
+            labelRightMargin={yAxisCfg?.labelRightMargin}
+            gridEndGap={yAxisCfg?.gridEndGap}
           />
         ))}
       </Group>
@@ -823,23 +886,26 @@ function SeriesValueLabelLayer({ model }: { model: LiveChartSeriesModel }) {
 function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
   const {
     allRefLines,
+    refLineKeys,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     engine,
     effectivePadding,
     palette,
     formatValue,
     skiaFont,
+    yAxisCfg,
+    yAxisEntries,
     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 +914,71 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
           font={skiaFont}
           badgeLayer
           suppressTag={refLineCustom[i]}
+          suppressTagWhenOffAxis={refLineOffAxisCustom[i]}
+          customTagWidths={refLineCustomTagWidths}
+          yAxisEntries={yAxisEntries}
+          labelRightMargin={yAxisCfg?.labelRightMargin}
+          gridEndGap={yAxisCfg?.gridEndGap}
         />
       ))}
     </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} />;
+}
+
+/** 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 {
@@ -871,6 +996,7 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     effectivePadding,
     engine,
     scrubCfg,
+    seriesTooltipCfg,
     crosshair,
     palette,
     dotCfg,
@@ -886,9 +1012,13 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     markersSV,
     markerClusterCfg,
     renderMarker,
+    renderOverlay,
     renderReferenceLine,
+    renderOffAxisReferenceLine,
     allRefLines,
     refLineCustom,
+    refLineOffAxisCustom,
+    refLineCustomTagWidths,
     overlayScrubFade,
     canvasMode,
   } = model;
@@ -988,8 +1118,23 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                 selectionColor={selectionColor}
                 dimOpacity={scrubCfg.dimOpacity}
                 liveDotExtent={liveDotExtent}
-                crosshairLineColor={scrubCfg.crosshairLineColor}
-                crosshairDash={scrubCfg.crosshairDash}
+                crosshairLineColor={
+                  seriesTooltipCfg?.guideColor ??
+                  scrubCfg.crosshairLineColor
+                }
+                crosshairStrokeWidth={
+                  seriesTooltipCfg?.guideWidth ??
+                  scrubCfg.crosshairStrokeWidth
+                }
+                crosshairOvershoot={scrubCfg.crosshairOvershoot}
+                crosshairFade={scrubCfg.crosshairFade}
+                crosshairFadeDistance={scrubCfg.crosshairFadeDistance}
+                crosshairLineCap={scrubCfg.crosshairLineCap}
+                crosshairDash={
+                  seriesTooltipCfg
+                    ? seriesTooltipCfg.guideDashPattern
+                    : scrubCfg.crosshairDash
+                }
                 crosshairDimColor={scrubCfg.crosshairDimColor}
                 opaqueCanvas={canvasMode === "opaque"}
               />
@@ -1017,7 +1162,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 +1186,43 @@ 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>
           )}
+
+          {/* 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} />}
         </View>
       </GestureDetector>
       {legendCfg.position === "bottom" ? legend : null}