react-native-livechart 3.9.0 → 3.11.0

package/src/components/ExtremaConnectorOverlay.tsx

@@ -0,0 +1,193 @@
+import { DashPathEffect, Path } from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type {
+  ResolvedAxisLabelConfig,
+  ResolvedLineStyleConfig,
+} from "../core/resolveConfig";
+import type {
+  ChartEngineExtrema,
+  ChartEngineLayout,
+} from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import { usePathBuilder } from "../hooks/usePathBuilder";
+import { EXTREMA_EDGE_INSET, EXTREMA_LABEL_FONT_SIZE } from "./AxisLabelOverlay";
+
+/** How far off-plot (px) the extremum may sit before the connector is dropped. */
+const CONNECTOR_CULL = 24;
+/** Gap (px) between the connector's end and the value label. */
+const LABEL_GAP = 3;
+/** Single-line text height as a fraction of font size — a safe over-estimate, so
+ *  the connector stops just shy of the label rather than running under it. */
+const LABEL_HEIGHT_FACTOR = 1.5;
+
+/** Connector style + the label font size (to estimate where the label edge is). */
+export interface ResolvedConnector {
+  line: ResolvedLineStyleConfig;
+  fontSize: number;
+}
+
+/**
+ * The connector config for one axis-label side — non-null only when it's an
+ * `"extrema-edge"` label with its connector enabled. The line `color` defaults
+ * to the label color (then `defaultColor`), so the connector matches its readout.
+ */
+export function labelConnector(
+  cfg: ResolvedAxisLabelConfig | null,
+  defaultColor: string,
+): ResolvedConnector | null {
+  if (!cfg || cfg.position !== "extrema-edge" || !cfg.connector) return null;
+  return {
+    line: {
+      ...cfg.connector,
+      color: cfg.connector.color ?? cfg.color ?? defaultColor,
+    },
+    fontSize: cfg.fontSize ?? EXTREMA_LABEL_FONT_SIZE,
+  };
+}
+
+/** A single vertical connector from the edge value label down/up to its dot. */
+function ConnectorLine({
+  side,
+  timeSV,
+  valueSV,
+  timeOffset,
+  engine,
+  padding,
+  config,
+}: {
+  side: "top" | "bottom";
+  timeSV: SharedValue<number>;
+  valueSV: SharedValue<number>;
+  timeOffset: number;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  config: ResolvedConnector;
+}) {
+  const builder = usePathBuilder();
+  const { line, fontSize } = config;
+
+  const path = useDerivedValue(() => {
+    const b = builder.value;
+    const value = valueSV.get();
+    const time = timeSV.get();
+    const cw = engine.canvasWidth.get();
+    const ch = engine.canvasHeight.get();
+    const displayMin = engine.displayMin.get();
+    const displayMax = engine.displayMax.get();
+    const win = engine.displayWindow.get();
+    const ts = engine.timestamp.get();
+
+    const chartLeft = padding.left;
+    const chartRight = cw - padding.right;
+    const chartW = chartRight - chartLeft;
+    const chartTop = padding.top;
+    const chartBottom = ch - padding.bottom;
+    const chartH = chartBottom - chartTop;
+    const valRange = displayMax - displayMin;
+
+    if (
+      !Number.isFinite(value) ||
+      cw === 0 ||
+      ch === 0 ||
+      chartW <= 0 ||
+      chartH <= 0 ||
+      win <= 0 ||
+      valRange <= 0
+    ) {
+      return b.detach();
+    }
+
+    const winStart = ts - win;
+    const px = chartLeft + ((time + timeOffset - winStart) / win) * chartW;
+    // Off-plot (scrolled out) — emit nothing this frame.
+    if (px < chartLeft - CONNECTOR_CULL || px > chartRight + CONNECTOR_CULL) {
+      return b.detach();
+    }
+    const py = chartTop + ((displayMax - value) / valRange) * chartH;
+
+    // Stop the line just shy of the value label (which sits on the rail), not at
+    // the plot edge — so it never runs through the text. The label's inner edge
+    // is estimated from its font height (the label measures itself in RN; an
+    // over-estimate keeps a clean gap). Skip when the dot is inside the band.
+    const band = fontSize * LABEL_HEIGHT_FACTOR;
+    if (side === "top") {
+      const edgeY = EXTREMA_EDGE_INSET + band + LABEL_GAP;
+      if (py <= edgeY) return b.detach();
+      b.moveTo(px, edgeY);
+      b.lineTo(px, py);
+    } else {
+      const edgeY = chartBottom - band - LABEL_GAP;
+      if (py >= edgeY) return b.detach();
+      b.moveTo(px, py);
+      b.lineTo(px, edgeY);
+    }
+    return b.detach();
+  });
+
+  return (
+    <Path
+      path={path}
+      style="stroke"
+      strokeWidth={line.strokeWidth}
+      color={line.color}
+    >
+      {line.intervals ? <DashPathEffect intervals={line.intervals} /> : null}
+    </Path>
+  );
+}
+
+/**
+ * Skia connector lines for `"extrema-edge"` axis labels — a vertical line at the
+ * extremum's x joining its edge value label to the marker dot on the data point.
+ * Drawn in the canvas (so it dashes "like all lines"); the dot + label are RN
+ * overlays positioned with the same projection, so the three pieces line up. The
+ * line stops at the label edge, not the plot edge, so it never crosses the text.
+ *
+ * `top` / `bottom` are non-null only for a side in `"extrema-edge"` mode with its
+ * connector enabled.
+ */
+export function ExtremaConnectorOverlay({
+  engine,
+  padding,
+  extremaTimeOffset = 0,
+  top,
+  bottom,
+}: {
+  engine: ChartEngineLayout & Partial<ChartEngineExtrema>;
+  padding: ChartPadding;
+  extremaTimeOffset?: number;
+  top: ResolvedConnector | null;
+  bottom: ResolvedConnector | null;
+}) {
+  const hasTop = top != null && engine.extremaMaxTime != null;
+  const hasBottom = bottom != null && engine.extremaMinTime != null;
+  if (!hasTop && !hasBottom) return null;
+
+  return (
+    <>
+      {hasTop && (
+        <ConnectorLine
+          side="top"
+          timeSV={engine.extremaMaxTime!}
+          valueSV={engine.extremaMaxValue!}
+          timeOffset={extremaTimeOffset}
+          engine={engine}
+          padding={padding}
+          config={top!}
+        />
+      )}
+      {hasBottom && (
+        <ConnectorLine
+          side="bottom"
+          timeSV={engine.extremaMinTime!}
+          valueSV={engine.extremaMinValue!}
+          timeOffset={extremaTimeOffset}
+          engine={engine}
+          padding={padding}
+          config={bottom!}
+        />
+      )}
+    </>
+  );
+}

package/src/components/LiveChart.tsx

@@ -19,6 +19,7 @@ import {
 
 import { DEFAULT_ACCENT_COLOR } from "../constants";
 import {
+  resolveAreaDots,
   resolveAxisLabel,
   resolveBadge,
   resolveDegen,
@@ -73,6 +74,7 @@ import {
   applyPaletteOverride,
   leftEdgeFadeColorsFromBgRgb,
   parseColorRgb,
+  parseColorRgba,
   resolveTheme,
 } from "../theme";
 import type {
@@ -85,7 +87,12 @@ import {
   ThresholdBadgeOverlay,
   ThresholdLineOverlay,
 } from "./ThresholdLineOverlay";
+import { AreaDotsOverlay } from "./AreaDotsOverlay";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
+import {
+  ExtremaConnectorOverlay,
+  labelConnector,
+} from "./ExtremaConnectorOverlay";
 import { CustomMarkerOverlay } from "./CustomMarkerOverlay";
 import { CustomTooltipOverlay } from "./CustomTooltipOverlay";
 import { BadgeOverlay } from "./BadgeOverlay";
@@ -146,6 +153,7 @@ function useLiveChartController({
   theme = "dark",
   accentColor = DEFAULT_ACCENT_COLOR,
   gradient = true,
+  areaDots,
   line: lineProp,
   font: fontProp,
   insets,
@@ -232,6 +240,9 @@ function useLiveChartController({
   // 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);
+  // Dot-lattice area fill (clipped to the under-line region). Inert in candle
+  // mode, same as the gradient fill.
+  const areaDotsCfg = isCandle ? null : resolveAreaDots(areaDots);
   // Threshold split is a line-mode feature (candle bodies carry their own up/down
   // colors), so it's inert in candle mode — same as the area gradient.
   const thresholdCfg = isCandle ? null : resolveThreshold(threshold);
@@ -405,6 +416,22 @@ function useLiveChartController({
     // Straight polyline instead of the monotone cubic when line.curve === "linear".
     lineProp?.curve === "linear",
   );
+
+  // Area-dots fill shader color as a vec4 (channels 0..1), with the config
+  // `opacity` folded into the alpha. Defaults to a faint tint of the line/accent
+  // color (theme-aware) so out-of-the-box dots read as a subtle field.
+  const areaDotRgb = parseColorRgb(lineProp?.color ?? palette.line);
+  const [adR, adG, adB, adA] = parseColorRgba(
+    areaDotsCfg?.color ??
+      `rgba(${areaDotRgb[0]}, ${areaDotRgb[1]}, ${areaDotRgb[2]}, 0.22)`,
+  );
+  const areaDotColorVec = [
+    adR / 255,
+    adG / 255,
+    adB / 255,
+    adA * (areaDotsCfg?.opacity ?? 1),
+  ];
+
   const { upBodiesPath, downBodiesPath, upWicksPath, downWicksPath } =
     useCandlePaths(
       engine,
@@ -625,6 +652,9 @@ function useLiveChartController({
     lineProp,
     formatValue,
     isCandle,
+    // Half a candle width (seconds) so an "extrema" axis label's dot lands on the
+    // candle's drawn center, not its bucket-start (left) edge. 0 in line mode.
+    extremaTimeOffset: isCandle ? candleWidth / 2 : 0,
     // configs
     yAxisCfg,
     xAxisCfg,
@@ -632,6 +662,8 @@ function useLiveChartController({
     scrubCfg,
     scrubActionCfg,
     gradientCfg,
+    areaDotsCfg,
+    areaDotColorVec,
     valueLineCfg,
     pulseCfg,
     dotCfg,
@@ -700,6 +732,9 @@ function useLiveChartController({
     // RN axis edge labels (floated over the canvas as a sibling layer)
     topLabelCfg,
     bottomLabelCfg,
+    // Skia connector lines for "extrema-edge" labels (dot → edge readout).
+    topConnector: labelConnector(topLabelCfg, palette.gridLabel),
+    bottomConnector: labelConnector(bottomLabelCfg, palette.gridLabel),
   };
 }
 
@@ -726,6 +761,8 @@ function ChartFillLayer({ model }: { model: LiveChartModel }) {
     gridStyleCfg,
     metricsCfg,
     gradientCfg,
+    areaDotsCfg,
+    areaDotColorVec,
     fillPath,
     gradientEnd,
     gradientColors,
@@ -755,6 +792,20 @@ function ChartFillLayer({ model }: { model: LiveChartModel }) {
         </Group>
       )}
 
+      {/* Dot-lattice area fill (the under-line `fillPath` painted with a dot
+          shader). Drawn before the gradient so a gradient (if also enabled)
+          composites on top. */}
+      {areaDotsCfg && (
+        <Group opacity={reveal.fillOpacity}>
+          <AreaDotsOverlay
+            fillPath={fillPath}
+            color={areaDotColorVec}
+            spacing={areaDotsCfg.spacing}
+            size={areaDotsCfg.size}
+          />
+        </Group>
+      )}
+
       {/* Area gradient fill */}
       {gradientCfg && (
         <Group opacity={reveal.fillOpacity}>
@@ -1072,10 +1123,10 @@ function ChartScrubLayer({ model }: { model: LiveChartModel }) {
     renderTooltip,
   } = model;
 
-  // A custom line-mode tooltip is an RN overlay (sibling of <Canvas>), so the
-  // default Skia pill is suppressed here while it's active. Candle keeps its
-  // built-in OHLC stack (renderTooltip is ignored in candle mode).
-  const customTooltipActive = !isCandle && renderTooltip != null;
+  // A custom tooltip is an RN overlay (sibling of <Canvas>), so the built-in
+  // Skia tooltip is suppressed here while it's active — the line pill in line
+  // mode, and the OHLC stack in candle mode (see the stack gate below).
+  const customTooltipActive = renderTooltip != null;
 
   if (!tradeStreamResolved && !scrubCfg) return null;
 
@@ -1110,6 +1161,7 @@ function ChartScrubLayer({ model }: { model: LiveChartModel }) {
           palette={palette}
           font={skiaFont}
           showTooltip={scrubCfg.tooltip && !customTooltipActive}
+          lineTop={crosshair.tooltipLineTop}
           selectionDot={selectionDot}
           selectionY={crosshair.scrubDotY}
           scrubActive={crosshair.scrubActive}
@@ -1128,8 +1180,9 @@ function ChartScrubLayer({ model }: { model: LiveChartModel }) {
         >
           {/* Candle charts render a multi-line OHLC tooltip; the line
               chart falls back to CrosshairOverlay's default value/time
-              body. Composed as children rather than a JSX-valued prop. */}
-          {isCandle ? (
+              body. Composed as children rather than a JSX-valued prop.
+              Suppressed when a custom `renderTooltip` owns the readout. */}
+          {isCandle && !customTooltipActive ? (
             <MultiSeriesTooltipStack
               tooltipLayout={crosshair.tooltipLayout}
               font={skiaFont}
@@ -1282,6 +1335,9 @@ export function LiveChart(props: LiveChartProps) {
     scrubCfg,
     crosshair,
     isCandle,
+    extremaTimeOffset,
+    topConnector,
+    bottomConnector,
   } = model;
 
   return (
@@ -1312,6 +1368,16 @@ export function LiveChart(props: LiveChartProps) {
           {/* Line stack above the fade so the line stays crisp at the left edge. */}
           <ChartStack model={model} />
 
+          {/* "extrema-edge" connector lines (dot → edge readout), above the chart
+              content so the dashed guide reads over the line / candles. */}
+          <ExtremaConnectorOverlay
+            engine={engine}
+            padding={effectivePadding}
+            extremaTimeOffset={extremaTimeOffset}
+            top={topConnector}
+            bottom={bottomConnector}
+          />
+
           {/* Reference-line badges + labels above the fade so they stay crisp. */}
           <ChartRefBadgeLayer model={model} />
 
@@ -1336,6 +1402,7 @@ export function LiveChart(props: LiveChartProps) {
           formatValue={formatValue}
           defaultColor={palette.gridLabel}
           padding={effectivePadding}
+          extremaTimeOffset={extremaTimeOffset}
         />
 
         {/* Custom-rendered markers — RN views floated over the canvas (non-Skia),
@@ -1351,20 +1418,23 @@ export function LiveChart(props: LiveChartProps) {
         )}
 
         {/* Custom scrub tooltip — an RN view floated over the canvas (non-Skia),
-            positioned on the UI thread. Sibling of <Canvas>. Line mode only. */}
-        {scrubCfg && renderTooltip && !isCandle && (
+            positioned on the UI thread. Sibling of <Canvas>. Works in line and
+            candle mode (candle exposes the OHLC via `scrubCandle`). */}
+        {scrubCfg && renderTooltip && (
           <CustomTooltipOverlay
             renderTooltip={renderTooltip}
             scrubX={crosshair.scrubX}
             scrubValue={crosshair.scrubValue}
             scrubTime={crosshair.scrubTime}
             scrubActive={crosshair.scrubActive}
+            scrubCandle={crosshair.scrubCandle}
             crosshairOpacity={crosshair.crosshairOpacity}
             tooltipLayout={crosshair.tooltipLayout}
             engine={engine}
             padding={effectivePadding}
             placement={scrubCfg.tooltipPlacement}
             margin={scrubCfg.tooltipMargin}
+            lineTop={crosshair.tooltipLineTop}
           />
         )}
       </View>

package/src/components/LiveChartSeries.tsx

@@ -63,6 +63,10 @@ import {
 } from "../theme";
 import type { LiveChartSeriesProps, Marker, SeriesConfig } from "../types";
 import { AxisLabelOverlay } from "./AxisLabelOverlay";
+import {
+  ExtremaConnectorOverlay,
+  labelConnector,
+} from "./ExtremaConnectorOverlay";
 import { CustomMarkerOverlay } from "./CustomMarkerOverlay";
 import { CrosshairLine } from "./CrosshairLine";
 import { DegenParticlesOverlay } from "./DegenParticlesOverlay";
@@ -395,6 +399,9 @@ function useLiveChartSeriesController({
     // RN axis edge labels (floated over the canvas as a sibling layer)
     topLabelCfg,
     bottomLabelCfg,
+    // Skia connector lines for "extrema-edge" labels (dot → edge readout).
+    topConnector: labelConnector(topLabelCfg, palette.gridLabel),
+    bottomConnector: labelConnector(bottomLabelCfg, palette.gridLabel),
   };
 }
 
@@ -654,6 +661,8 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     formatValue,
     topLabelCfg,
     bottomLabelCfg,
+    topConnector,
+    bottomConnector,
     markersActive,
     markersSV,
     renderMarker,
@@ -696,6 +705,15 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
           <Canvas style={{ flex: 1, minHeight: layoutHeight || 1 }}>
             <SeriesChartStack model={model} />
 
+            {/* "extrema-edge" connector lines (dot → edge readout). Outside the
+                stack's degen-shake group so they track the (unshaken) RN dot. */}
+            <ExtremaConnectorOverlay
+              engine={engine}
+              padding={effectivePadding}
+              top={topConnector}
+              bottom={bottomConnector}
+            />
+
             {leftEdgeFadeCfg && (
               <LeftEdgeFade
                 paddingLeft={effectivePadding.left}

package/src/core/liveChartEngineTick.ts

@@ -9,6 +9,17 @@ export interface EngineTickMutable {
   displayMax: number;
   displayWindow: number;
   timestamp: number;
+  /**
+   * Value + time of the lowest / highest data point in the visible window —
+   * the actual extrema, NOT the smoothed display bounds (which carry margin and
+   * fold in the live value / reference lines). `NaN` when the window holds no
+   * data. Used to float `topLabel` / `bottomLabel` at their occurrence point
+   * (see {@link AxisLabelConfig.position} `"extrema"`).
+   */
+  extremaMinValue: number;
+  extremaMaxValue: number;
+  extremaMinTime: number;
+  extremaMaxTime: number;
 }
 
 export interface EngineTickInput {
@@ -93,6 +104,12 @@ export function tickLiveChartEngineFrame(
 
   let tMin = Infinity;
   let tMax = -Infinity;
+  // Time of the running min / max — captured alongside the value so an extrema
+  // label can be pinned at the point's x. Holds the data extrema only (folded
+  // below with the live value / references for the Y range, but snapshotted
+  // before that into `extrema*` so the label tracks the real high/low).
+  let minTime = 0;
+  let maxTime = 0;
 
   if (input.mode === "candle") {
     const candles = input.candles;
@@ -107,17 +124,29 @@ export function tickLiveChartEngineFrame(
       for (let i = lo; i < candles.length; i++) {
         if (candles[i].time > state.timestamp) break;
         /* istanbul ignore next -- trivial min/max */
-        if (candles[i].low < tMin) tMin = candles[i].low;
+        if (candles[i].low < tMin) {
+          tMin = candles[i].low;
+          minTime = candles[i].time;
+        }
         /* istanbul ignore next -- trivial min/max */
-        if (candles[i].high > tMax) tMax = candles[i].high;
+        if (candles[i].high > tMax) {
+          tMax = candles[i].high;
+          maxTime = candles[i].time;
+        }
       }
     }
     const lc = input.liveCandle;
     if (lc) {
       /* istanbul ignore next -- trivial min/max */
-      if (lc.low < tMin) tMin = lc.low;
+      if (lc.low < tMin) {
+        tMin = lc.low;
+        minTime = lc.time;
+      }
       /* istanbul ignore next -- trivial min/max */
-      if (lc.high > tMax) tMax = lc.high;
+      if (lc.high > tMax) {
+        tMax = lc.high;
+        maxTime = lc.time;
+      }
     }
   } else {
     const points = input.points;
@@ -130,11 +159,27 @@ export function tickLiveChartEngineFrame(
     }
     for (let i = lo; i < points.length; i++) {
       const v = points[i].value;
-      if (v < tMin) tMin = v;
-      if (v > tMax) tMax = v;
+      if (v < tMin) {
+        tMin = v;
+        minTime = points[i].time;
+      }
+      if (v > tMax) {
+        tMax = v;
+        maxTime = points[i].time;
+      }
     }
   }
 
+  // Snapshot the raw data extrema (value + time) before the live value /
+  // reference values fold into tMin/tMax for the Y range. NaN when the window
+  // is empty so the extrema label hides rather than pinning to a fake point.
+  const hasMin = tMin !== Infinity;
+  const hasMax = tMax !== -Infinity;
+  state.extremaMinValue = hasMin ? tMin : NaN;
+  state.extremaMaxValue = hasMax ? tMax : NaN;
+  state.extremaMinTime = hasMin ? minTime : NaN;
+  state.extremaMaxTime = hasMax ? maxTime : NaN;
+
   const cv = state.displayValue;
   if (cv < tMin) tMin = cv;
   if (cv > tMax) tMax = cv;

package/src/core/liveChartSeriesEngineTick.ts

@@ -9,6 +9,16 @@ export interface MultiEngineTickMutable {
   timestamp: number;
   displayValues: number[];
   opacities: number[];
+  /**
+   * Value + time of the lowest / highest point across the visible series — the
+   * actual extrema, NOT the smoothed display bounds. `NaN` when no visible
+   * series has data in the window. Used to float `topLabel` / `bottomLabel` at
+   * their occurrence point (see {@link AxisLabelConfig.position} `"extrema"`).
+   */
+  extremaMinValue: number;
+  extremaMaxValue: number;
+  extremaMinTime: number;
+  extremaMaxTime: number;
 }
 
 export interface MultiEngineTickInput {
@@ -95,6 +105,13 @@ export function tickLiveChartSeriesEngineFrame(
 
   let tMin = Infinity;
   let tMax = -Infinity;
+  // Time of the running global min / max data point — captured so an extrema
+  // label can be pinned at its x (data extrema only; the live tips folded below
+  // into the Y range are snapshotted out before that).
+  let minTime = 0;
+  let maxTime = 0;
+  let dataMin = Infinity;
+  let dataMax = -Infinity;
 
   for (let i = 0; i < n; i++) {
     if (series[i].visible === false) continue;
@@ -112,12 +129,29 @@ export function tickLiveChartSeriesEngineFrame(
       if (v < tMin) tMin = v;
       /* istanbul ignore next -- trivial min/max */
       if (v > tMax) tMax = v;
+      if (v < dataMin) {
+        dataMin = v;
+        minTime = points[j].time;
+      }
+      if (v > dataMax) {
+        dataMax = v;
+        maxTime = points[j].time;
+      }
     }
     const cv = state.displayValues[i];
     if (cv < tMin) tMin = cv;
     if (cv > tMax) tMax = cv;
   }
 
+  // Snapshot the raw data extrema before the references fold in. NaN when no
+  // visible series has data in the window so the extrema label hides.
+  const hasMin = dataMin !== Infinity;
+  const hasMax = dataMax !== -Infinity;
+  state.extremaMinValue = hasMin ? dataMin : NaN;
+  state.extremaMaxValue = hasMax ? dataMax : NaN;
+  state.extremaMinTime = hasMin ? minTime : NaN;
+  state.extremaMaxTime = hasMax ? maxTime : NaN;
+
   const ref = input.referenceValue;
   if (ref !== undefined) {
     if (ref < tMin) tMin = ref;