react-native-livechart 3.2.0 → 3.4.0

package/src/components/LiveChart.tsx

@@ -1,7 +1,7 @@
 import { useLayoutEffect, useState } from "react";
 import { View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import { useSharedValue } from "react-native-reanimated";
+import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 
 /**
  * Single-series live chart. UX and prop vocabulary parallel Benji Taylor’s
@@ -29,12 +29,14 @@ import {
   resolveMetrics,
   resolvePulse,
   resolveScrub,
+  resolveScrubAction,
   resolveSelectionDot,
   resolveTradeStream,
   resolveValueLine,
   resolveXAxis,
   resolveYAxis,
 } from "../core/resolveConfig";
+import { resolveSegment } from "../core/resolveSegment";
 import { useLiveChartEngine } from "../core/useLiveChartEngine";
 import { pulseRadialOutset } from "../draw/line";
 import { resolveChartLayout } from "../hooks/resolveChartLayout";
@@ -50,8 +52,10 @@ import { useDegen } from "../hooks/useDegen";
 import { useLiveChartHasData } from "../hooks/useLiveChartHasData";
 import { useLiveDot } from "../hooks/useLiveDot";
 import { useMarkers } from "../hooks/useMarkers";
+import { useReferenceLinePress } from "../hooks/useReferenceLinePress";
 import { useModeBlend } from "../hooks/useModeBlend";
 import { useMomentum } from "../hooks/useMomentum";
+import { useSegmentLineGradient } from "../hooks/useSegmentLineGradient";
 import { useSingleChartReverseMorphInputs } from "../hooks/useReverseMorphEngineInputs";
 import { useTradeStream } from "../hooks/useTradeStream";
 import { useXAxis } from "../hooks/useXAxis";
@@ -79,6 +83,8 @@ import { MarkerOverlay } from "./MarkerOverlay";
 import { MultiSeriesTooltipStack } from "./MultiSeriesTooltipStack";
 import { ValueTextOverlay } from "./ValueTextOverlay";
 import { ReferenceLineOverlay } from "./ReferenceLineOverlay";
+import { ScrubActionOverlay } from "./ScrubActionOverlay";
+import { SegmentDividerOverlay } from "./SegmentDividerOverlay";
 import { TradeStreamOverlay } from "./TradeStreamOverlay";
 import { ValueLineOverlay } from "./ValueLineOverlay";
 import { XAxisOverlay } from "./XAxisOverlay";
@@ -141,10 +147,12 @@ function useLiveChartController({
   showValue = false,
   valueMomentumColor = false,
   referenceLines,
+  segments,
   gridStyle,
   palette: paletteOverride,
   metrics,
   scrub = true,
+  scrubAction,
   selectionDot,
   tradeStream,
   degen,
@@ -155,6 +163,8 @@ function useLiveChartController({
 
   // ── Callbacks ───────────────────────────────────────────────────────────
   onScrub,
+  onScrubAction,
+  onReferenceLinePress,
   onGestureStart,
   onGestureEnd,
   onDegenShake,
@@ -172,6 +182,8 @@ function useLiveChartController({
   const bottomLabelCfg = resolveAxisLabel(bottomLabel);
   const badgeCfg = resolveBadge(badge);
   const scrubCfg = resolveScrub(scrub);
+  // Static charts run no gestures, so scrub-action (tap/drag to lock a price) is off.
+  const scrubActionCfg = isStatic ? null : resolveScrubAction(scrubAction);
   const gradientCfg = isCandle ? null : resolveGradient(gradient);
   const valueLineCfg = resolveValueLine(valueLine);
   // Static charts run zero loops: force the pulse off so its `withRepeat`-driven
@@ -200,6 +212,20 @@ function useLiveChartController({
     paletteOverride,
   );
 
+  // Time-range segments (sessions, after-hours, …). Resolved once per render like
+  // reference lines; the divider/label/muted colors default to the chart palette
+  // (no per-segment base color needed). `hasRecolorSegments` is a render-time gate
+  // for the line-recolor gradient pass (per-frame visibility is handled by the
+  // gradient's transparent stops, not by mounting/unmounting the Path).
+  const resolvedSegments = (segments ?? []).map((s) =>
+    resolveSegment(s, {
+      muted: palette.gridLabel,
+      divider: palette.refLine,
+      label: palette.refLabel,
+    }),
+  );
+  const hasRecolorSegments = resolvedSegments.some((s) => s.recolorLine);
+
   const leftEdgeFadeCfg = resolveLeftEdgeFade(
     leftEdgeFade,
     leftEdgeFadeColorsFromBgRgb(palette.bgRgb),
@@ -386,6 +412,46 @@ function useLiveChartController({
       }
     : undefined;
 
+  const markersActive = markers != null;
+  // `projected` is used internally by the hit-test gesture; the overlay
+  // self-projects, so we only need the gesture + hit-test here. Built BEFORE
+  // `useCrosshair` so the scrub-action tap can defer to a marker under the finger.
+  const { tapGesture: markerTapGesture, hitTest: markerHitTest } = useMarkers(
+    engine,
+    effectivePadding,
+    markersSV,
+    !isStatic && markersActive,
+    markerHitRadius,
+    onMarkerHover,
+    undefined, // seriesSV — single-series has none
+    engine.data, // anchor value-less markers to the line
+    !isStatic, // static: no marker-projection loop
+  );
+
+  // Pressable reference-line badges (working orders / alerts). Built before
+  // `useCrosshair` so the scrub-action tap can defer to a badge under the finger.
+  const refPressActive = onReferenceLinePress != null && allRefLines.length > 0;
+  const { tapGesture: refLineTapGesture, hitTest: refLineHitTest } =
+    useReferenceLinePress(
+      engine,
+      effectivePadding,
+      allRefLines,
+      skiaFont,
+      formatValue,
+      !isStatic && refPressActive,
+      markerHitRadius,
+      onReferenceLinePress,
+    );
+
+  // Combined "defer" hit-test for the scrub-action place-tap: yield to a marker or
+  // a pressable badge under the finger so the tap is routed there instead of
+  // dropping a reticle. (Both hit-tests return false when their feature is off.)
+  /* istanbul ignore next -- worklet runs on the UI thread, not in Jest */
+  const deferTapHit = (x: number, y: number): boolean => {
+    "worklet";
+    return markerHitTest(x, y) || refLineHitTest(x, y);
+  };
+
   const crosshair = useCrosshair(
     engine,
     effectivePadding,
@@ -394,32 +460,51 @@ function useLiveChartController({
     formatTime,
     skiaFont,
     // Static charts have an inert pan gesture — no scrub work on the UI thread.
-    !isStatic && scrubCfg !== null,
+    // Scrub-action also needs the gesture live even when plain scrub is off.
+    !isStatic && (scrubCfg !== null || scrubActionCfg !== null),
     onScrub,
     candleOpts,
     scrubCfg?.panGestureDelay ?? 0,
     onGestureStart,
     onGestureEnd,
+    scrubActionCfg,
+    onScrubAction,
+    metricsCfg.badge,
+    markersActive || refPressActive ? deferTapHit : undefined,
   );
 
-  const markersActive = markers != null;
-  // `projected` is used internally by the hit-test gesture; the overlay
-  // self-projects, so we only need the gesture here.
-  const { tapGesture: markerTapGesture } = useMarkers(
-    engine,
-    effectivePadding,
-    markersSV,
-    !isStatic && markersActive,
-    markerHitRadius,
-    onMarkerHover,
-    undefined, // seriesSV — single-series has none
-    engine.data, // anchor value-less markers to the line
-    !isStatic, // static: no marker-projection loop
-  );
-
-  const rootGesture = markersActive
-    ? Gesture.Race(crosshair.gesture, markerTapGesture)
-    : crosshair.gesture;
+  // Scrub-action composes a Tap (place/move the reticle, press the badge, dismiss)
+  // ahead of the pan via Exclusive, so a tap is tried first and only becomes a
+  // drag (live-scrub, or lock-adjust once placed) if the finger moves. `Exclusive`
+  // (not `Race`) prevents a jittery tap from being swallowed by the pan.
+  const baseGesture =
+    scrubActionCfg !== null && crosshair.tapGesture
+      ? Gesture.Exclusive(crosshair.tapGesture, crosshair.gesture)
+      : crosshair.gesture;
+
+  // Overlay taps that hit-test discrete targets (marker dots, reference-line
+  // badges). They must all see each tap, so they're combined with `Simultaneous`
+  // (not `Race`, which cancels the loser and would drop one). The scrub-action
+  // action tap defers to them via `deferTapHit`, so a tap on an overlay is routed
+  // there instead of placing a reticle.
+  const overlayTaps = [
+    markersActive ? markerTapGesture : null,
+    refPressActive ? refLineTapGesture : null,
+  ].filter((g): g is NonNullable<typeof g> => g !== null);
+
+  let rootGesture = baseGesture;
+  if (overlayTaps.length > 0) {
+    const tapGroup =
+      overlayTaps.length === 1
+        ? overlayTaps[0]
+        : Gesture.Simultaneous(overlayTaps[0], overlayTaps[1]);
+    // With scrub-action the action tap shares the gesture space with the overlay
+    // taps (Simultaneous); without it the pan only needs to race the tap group.
+    rootGesture =
+      scrubActionCfg !== null
+        ? Gesture.Simultaneous(baseGesture, tapGroup)
+        : Gesture.Race(baseGesture, tapGroup);
+  }
 
   // ── Derived render values ──────────────────────────────────────────────
   const {
@@ -437,6 +522,29 @@ function useLiveChartController({
     effectivePadding,
   );
 
+  // Scrub-focus gradient painted onto the line stroke: uniform at rest, and while
+  // scrubbing (or with an `active` segment) the focused segment stays full while
+  // the others are de-emphasized. Declared after `crosshair` so it can read the
+  // live scrub state.
+  const segmentGradient = useSegmentLineGradient(
+    engine,
+    resolvedSegments,
+    effectivePadding,
+    lineProp?.color ?? palette.line,
+    crosshair.scrubX,
+    crosshair.scrubActive,
+  );
+
+  // Hide the live dot while scrubbing when a selection dot is marking the scrub
+  // point instead — otherwise both dots show at once.
+  const selectionDotDuringScrub =
+    !isStatic && scrubCfg !== null && selectionDotCfg !== null;
+  const liveDotOpacity = useDerivedValue(
+    () =>
+      reveal.dotOpacity.value *
+      (selectionDotDuringScrub && crosshair.scrubActive.value ? 0 : 1),
+  );
+
   return {
     // passthrough props the render needs
     style,
@@ -453,6 +561,7 @@ function useLiveChartController({
     xAxisCfg,
     badgeCfg,
     scrubCfg,
+    scrubActionCfg,
     gradientCfg,
     valueLineCfg,
     pulseCfg,
@@ -464,6 +573,9 @@ function useLiveChartController({
     leftEdgeFadeCfg,
     metricsCfg,
     allRefLines,
+    resolvedSegments,
+    hasRecolorSegments,
+    segmentGradient,
     badgeUsesRightGutter,
     // theme / layout / fonts
     palette,
@@ -493,6 +605,7 @@ function useLiveChartController({
     downWicksPath,
     dotX,
     dotY,
+    liveDotOpacity,
     momentumSV,
     tradeMarkers,
     degenPack,
@@ -540,6 +653,9 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     valueLineCfg,
     dotY,
     allRefLines,
+    resolvedSegments,
+    hasRecolorSegments,
+    segmentGradient,
     formatValue,
     lineGroupOpacity,
     linePath,
@@ -553,6 +669,7 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     xAxisCfg,
     xAxisEntries,
     dotX,
+    liveDotOpacity,
     pulseCfg,
     dotCfg,
     degenCfg,
@@ -598,6 +715,18 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         </Group>
       )}
 
+      {/* Segment dividers + labels (behind the line). The scrub-focus emphasis is
+          painted on the line stroke itself, below — this overlay draws no fill. */}
+      {resolvedSegments.map((seg, i) => (
+        <SegmentDividerOverlay
+          key={`seg-${seg.from ?? "start"}-${seg.to ?? "end"}-${i}`}
+          engine={engine}
+          padding={effectivePadding}
+          segment={seg}
+          font={skiaFont}
+        />
+      ))}
+
       {/* Value line + reference line (behind chart line) */}
       {valueLineCfg && (
         <Group opacity={reveal.lineOpacity}>
@@ -612,9 +741,12 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         </Group>
       )}
 
-      {allRefLines.map((rl) => (
+      {/* Index keys: reference lines are a positional array and two may share
+          value + label (e.g. duplicate working orders at the same price), which a
+          content-derived key would collapse to one. */}
+      {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
-          key={`${rl.value ?? ""}:${rl.valueFrom ?? ""}:${rl.valueTo ?? ""}:${rl.from ?? ""}:${rl.to ?? ""}:${rl.label ?? ""}`}
+          key={i}
           engine={engine}
           padding={effectivePadding}
           line={rl}
@@ -624,7 +756,10 @@ function ChartStack({ model }: { model: LiveChartModel }) {
         />
       ))}
 
-      {/* Chart line (fades out in candle mode) */}
+      {/* Chart line (fades out in candle mode). When segments recolor the line, a
+          full-width gradient paints the base color outside segments and each
+          segment's color within — so the line itself is recolored/faded (alpha in
+          the segment color reduces the line's opacity), not covered by an overlay. */}
       <Group opacity={lineGroupOpacity}>
         <Path
           path={linePath}
@@ -634,7 +769,14 @@ function ChartStack({ model }: { model: LiveChartModel }) {
           strokeJoin="round"
           color={lineProp?.color ?? palette.line}
         >
-          {lineProp?.colors?.length ? (
+          {hasRecolorSegments ? (
+            <LinearGradient
+              start={vec(0, 0)}
+              end={segmentGradient.gradientEnd}
+              colors={segmentGradient.colors}
+              positions={segmentGradient.positions}
+            />
+          ) : lineProp?.colors?.length ? (
             <LinearGradient
               start={vec(0, 0)}
               end={vec(layoutWidth, 0)}
@@ -678,9 +820,10 @@ function ChartStack({ model }: { model: LiveChartModel }) {
       )}
 
       {/* Live dot — the badge is drawn later (after the scrub layer) so the
-          scrub dim never clips the live-price badge's left edge. */}
+          scrub dim never clips the live-price badge's left edge. Hidden while
+          scrubbing when a selection dot marks the scrub point instead. */}
       {dotCfg.show && (
-        <Group opacity={reveal.dotOpacity}>
+        <Group opacity={liveDotOpacity}>
           <DotOverlay
             dotX={dotX}
             dotY={dotY}
@@ -873,6 +1016,73 @@ function ChartBadgeLayer({ model }: { model: LiveChartModel }) {
   );
 }
 
+/** Reference-line badges + labels, drawn ABOVE the left-edge fade so a
+ *  left-pinned badge (off-axis / `labelBadge`) and any label stay crisp instead
+ *  of being erased by the fade's dstOut. The lines/bands themselves render in the
+ *  base pass inside ChartStack (behind the chart content). */
+function ChartRefBadgeLayer({ model }: { model: LiveChartModel }) {
+  const {
+    allRefLines,
+    engine,
+    effectivePadding,
+    palette,
+    formatValue,
+    skiaFont,
+    degenShakeTransform,
+  } = model;
+  if (allRefLines.length === 0) return null;
+  return (
+    <Group transform={degenShakeTransform}>
+      {allRefLines.map((rl, i) => (
+        <ReferenceLineOverlay
+          key={i}
+          engine={engine}
+          padding={effectivePadding}
+          line={rl}
+          palette={palette}
+          formatValue={formatValue}
+          font={skiaFont}
+          badgeLayer
+        />
+      ))}
+    </Group>
+  );
+}
+
+/** Scrub-action ("order ticket") reticle + action badge. Drawn OUTSIDE the degen
+ *  shake group so the rendered badge stays aligned with the untransformed tap
+ *  hit-test; it tracks the locked reticle, not the shaken stack. */
+function ChartScrubActionLayer({ model }: { model: LiveChartModel }) {
+  const { scrubActionCfg, crosshair, engine, effectivePadding, palette, skiaFont } =
+    model;
+  if (
+    !scrubActionCfg ||
+    !crosshair.lockActive ||
+    !crosshair.lockX ||
+    !crosshair.lockY ||
+    !crosshair.actionBadge
+  ) {
+    return null;
+  }
+  return (
+    <ScrubActionOverlay
+      lockActive={crosshair.lockActive}
+      lockX={crosshair.lockX}
+      lockY={crosshair.lockY}
+      actionBadge={crosshair.actionBadge}
+      timeBadge={crosshair.timeBadge}
+      engine={engine}
+      padding={effectivePadding}
+      palette={palette}
+      font={skiaFont}
+      icon={scrubActionCfg.icon}
+      lineColor={scrubActionCfg.lineColor}
+      background={scrubActionCfg.background}
+      iconColor={scrubActionCfg.iconColor}
+    />
+  );
+}
+
 export function LiveChart(props: LiveChartProps) {
   const model = useLiveChartController(props);
   const {
@@ -914,6 +1124,9 @@ export function LiveChart(props: LiveChartProps) {
             />
           )}
 
+          {/* Reference-line badges + labels above the fade so they stay crisp. */}
+          <ChartRefBadgeLayer model={model} />
+
           <ChartValueOverlay model={model} />
 
           <ChartScrubLayer model={model} />
@@ -921,6 +1134,9 @@ export function LiveChart(props: LiveChartProps) {
           {/* Live-price badge on top of the scrub dim so the dim never clips
               its left edge (the badge tracks the live value, not the scrub). */}
           <ChartBadgeLayer model={model} />
+
+          {/* Scrub-action reticle + action badge — top-most, no shake transform. */}
+          <ChartScrubActionLayer model={model} />
         </Canvas>
 
         {/* RN labels floated over the canvas (sibling of <Canvas>, an RN view).

package/src/components/LiveChartSeries.tsx

@@ -448,9 +448,12 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
         </Group>
       )}
 
-      {allRefLines.map((rl) => (
+      {/* Index keys: reference lines are a positional array and two may share
+          value + label (e.g. duplicate working orders at the same price), which a
+          content-derived key would collapse to one. */}
+      {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
-          key={`${rl.value ?? ""}:${rl.valueFrom ?? ""}:${rl.valueTo ?? ""}:${rl.from ?? ""}:${rl.to ?? ""}:${rl.label ?? ""}`}
+          key={i}
           engine={engine}
           padding={effectivePadding}
           line={rl}
@@ -589,6 +592,37 @@ function SeriesValueLabelLayer({ model }: { model: LiveChartSeriesModel }) {
   );
 }
 
+/** Reference-line badges + labels, drawn ABOVE the left-edge fade so they stay
+ *  crisp (the lines/bands render in the base pass inside SeriesChartStack). */
+function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
+  const {
+    allRefLines,
+    engine,
+    effectivePadding,
+    palette,
+    formatValue,
+    skiaFont,
+    degenShakeTransform,
+  } = model;
+  if (allRefLines.length === 0) return null;
+  return (
+    <Group transform={degenShakeTransform}>
+      {allRefLines.map((rl, i) => (
+        <ReferenceLineOverlay
+          key={i}
+          engine={engine}
+          padding={effectivePadding}
+          line={rl}
+          palette={palette}
+          formatValue={formatValue}
+          font={skiaFont}
+          badgeLayer
+        />
+      ))}
+    </Group>
+  );
+}
+
 export function LiveChartSeries(props: LiveChartSeriesProps) {
   const model = useLiveChartSeriesController(props);
   const {
@@ -664,6 +698,9 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
               />
             )}
 
+            {/* Reference-line badges + labels above the fade so they stay crisp. */}
+            <SeriesRefBadgeLayer model={model} />
+
             {scrubCfg && (
               <CrosshairLine
                 scrubX={crosshair.scrubX}