react-native-livechart 3.9.0 → 3.11.0

package/src/components/AxisLabelOverlay.tsx

@@ -1,17 +1,61 @@
-import { TextInput, StyleSheet, View } from "react-native";
+import { useState } from "react";
+import {
+  TextInput,
+  StyleSheet,
+  Text,
+  View,
+  type LayoutChangeEvent,
+} from "react-native";
 import Animated, {
   useAnimatedProps,
+  useAnimatedReaction,
+  useAnimatedStyle,
   useDerivedValue,
+  useSharedValue,
 } from "react-native-reanimated";
 import type { SharedValue } from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
 
 import type { ResolvedAxisLabelConfig } from "../core/resolveConfig";
-import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type {
+  ChartEngineExtrema,
+  ChartEngineLayout,
+} from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
+import type { FontWeight } from "../types";
+
+/** Resolved text-styling knobs shared by the edge and extrema built-in labels. */
+interface LabelFontStyle {
+  fontSize?: number;
+  fontWeight?: FontWeight;
+  fontFamily?: string;
+}
+
+/** Pluck the font knobs off a resolved axis-label config. */
+function labelFont(cfg: ResolvedAxisLabelConfig): LabelFontStyle {
+  return {
+    fontSize: cfg.fontSize,
+    fontWeight: cfg.fontWeight,
+    fontFamily: cfg.fontFamily,
+  };
+}
 
 /** Editable={false} TextInput so its `text` prop can be animated on the UI thread. */
 const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);
 
+/** Marker dot drawn at the exact extrema point (built-in `"extrema"` label). */
+const EXTREMA_DOT_SIZE = 7;
+/** Gap (px) between the extrema dot and its value text. */
+const EXTREMA_GAP = 3;
+/** How far off-plot (px) the extrema point may sit before the label is hidden. */
+const EXTREMA_CULL = 24;
+/** `"extrema-edge"` top label's inset from the very top of the chart (px). The
+ *  connector ({@link ExtremaConnectorOverlay}) reads this to stop at the label. */
+export const EXTREMA_EDGE_INSET = 2;
+/** Default value-text size (px). Mirrors `styles.extremaText`; the connector
+ *  reads it to estimate where the edge label ends. */
+export const EXTREMA_LABEL_FONT_SIZE = 11;
+
 /**
  * The batteries-included axis edge label — an animated RN text driven by a
  * `SharedValue<number>` (the chart's current top / bottom Y-axis bound). The
@@ -26,11 +70,13 @@ function BuiltInAxisValueLabel({
   format,
   color,
   position,
+  font,
 }: {
   value: SharedValue<number>;
   format: (v: number) => string;
   color: string;
-  position: "left" | "right";
+  position: "left" | "right" | "extrema" | "extrema-edge";
+  font: LabelFontStyle;
 }) {
   const text = useDerivedValue(() => format(value.get()));
   const animatedProps = useAnimatedProps(() => {
@@ -45,12 +91,239 @@ function BuiltInAxisValueLabel({
         color,
         textAlign: position === "left" ? "left" : "right",
         padding: 0,
+        // undefined keys are ignored by RN, so each falls back to its default.
+        fontSize: font.fontSize,
+        fontWeight: font.fontWeight,
+        fontFamily: font.fontFamily,
       }}
       animatedProps={animatedProps}
     />
   );
 }
 
+/**
+ * An axis label floated at the *actual data point* where the extreme value
+ * occurs — `topLabel` over the highest point, `bottomLabel` under the lowest —
+ * rather than pinned to a fixed plot edge. The chart projects the extremum's
+ * (time, value) to a canvas pixel each frame and positions the label there on
+ * the UI thread, so the dot + value track the point as the chart scrolls and
+ * the Y-axis rescales (the same projection the markers / scrub dot use).
+ *
+ * The value text rides a JS-thread `useState` rather than UI-thread animated
+ * text: it changes only when a *new* extremum appears (not every frame), and a
+ * plain `<Text>` re-measures on change so the box stays correctly centered over
+ * the point (an animated `TextInput`'s width is fixed at its last layout, which
+ * would clip / drift as the digit count changes). Hidden (`opacity: 0`) when the
+ * window holds no data (value is `NaN`) or the point scrolls off-plot.
+ */
+function ExtremaAxisLabel({
+  side,
+  timeSV,
+  valueSV,
+  timeOffset,
+  edgeAnchor,
+  engine,
+  padding,
+  format,
+  color,
+  font,
+  dotColor,
+  dotSize,
+  dot,
+  render,
+}: {
+  /** `"top"` floats above the max point; `"bottom"` below the min point. */
+  side: "top" | "bottom";
+  timeSV: SharedValue<number>;
+  valueSV: SharedValue<number>;
+  /**
+   * `"extrema-edge"` mode: pin the value label to the plot's top / bottom edge
+   * (x-aligned with the extremum) instead of floating it over the point. The dot
+   * still sits on the point; a connector line (drawn in Skia) joins them.
+   */
+  edgeAnchor: boolean;
+  /**
+   * Seconds added to the extremum time before projecting to x. `0` for line /
+   * multi-series (the point sits at its exact time); half a candle width in
+   * candle mode so the dot lands on the candle's drawn center, not its left edge.
+   */
+  timeOffset: number;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  format: (v: number) => string;
+  color: string;
+  font: LabelFontStyle;
+  /** Dot color; falls back to `color`. */
+  dotColor?: string;
+  /** Dot diameter (px); falls back to the built-in default. */
+  dotSize?: number;
+  /** Whether to draw the marker dot. */
+  dot: boolean;
+  render?: () => React.ReactElement | null;
+}) {
+  const isCustom = render != null;
+  // Resolved dot geometry. `hasDot` also gates the label's vertical offset (it
+  // sits past the dot when shown, otherwise just past the point).
+  const dotSizePx = dotSize ?? EXTREMA_DOT_SIZE;
+  const hasDot = !isCustom && dot;
+  // Measured size of the content (text or custom element) — used only to center
+  // and clamp the LABEL horizontally. The dot is pinned to the point regardless.
+  const size = useSharedValue({ width: 0, height: 0 });
+  const onLayout = (e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout;
+    size.value = { width, height };
+  };
+
+  // The value text changes only when the extremum does, so push it to JS state
+  // (a re-measured <Text>) instead of UI-thread animated text. Skipped when a
+  // custom element owns the content.
+  const [valueText, setValueText] = useState("");
+  useAnimatedReaction(
+    () => {
+      const v = valueSV.get();
+      return isCustom || !Number.isFinite(v) ? "" : format(v);
+    },
+    (curr, prev) => {
+      if (curr !== prev) scheduleOnRN(setValueText, curr);
+    },
+  );
+
+  // Project the extremum's (time, value) to a canvas pixel once; the dot and the
+  // label both read it. `visible` is false when the window is empty or the point
+  // scrolls off-plot.
+  const proj = useDerivedValue(() => {
+    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 { px: 0, py: 0, visible: false };
+    }
+
+    const winStart = ts - win;
+    const px = chartLeft + ((time + timeOffset - winStart) / win) * chartW;
+    const py = chartTop + ((displayMax - value) / valRange) * chartH;
+    // Scrolled out of view — hide rather than clamp it to the edge.
+    const visible = px >= chartLeft - EXTREMA_CULL && px <= chartRight + EXTREMA_CULL;
+    return { px, py, visible };
+  });
+
+  // The dot sits EXACTLY on the data point (its center at px, py) — never
+  // clamped, so it always marks where the high / low occurred.
+  const dotStyle = useAnimatedStyle(() => {
+    const p = proj.get();
+    if (!p.visible) return { opacity: 0 };
+    return {
+      opacity: 1,
+      transform: [
+        { translateX: p.px - dotSizePx / 2 },
+        { translateY: p.py - dotSizePx / 2 },
+      ],
+    };
+  });
+
+  // The label is centered on the point but clamped into the plot width so it
+  // stays readable near an edge — independent of the dot, which stays on-point.
+  const labelStyle = useAnimatedStyle(() => {
+    const p = proj.get();
+    const s = size.get();
+    if (!p.visible) {
+      return { opacity: 0, transform: [{ translateX: 0 }, { translateY: 0 }] };
+    }
+    const cw = engine.canvasWidth.get();
+    const chartLeft = padding.left;
+    const chartRight = cw - padding.right;
+    const rightBound = chartRight - s.width;
+    const x = Math.min(
+      Math.max(p.px - s.width / 2, chartLeft),
+      Math.max(chartLeft, rightBound),
+    );
+    let y: number;
+    if (edgeAnchor) {
+      // Pin to the OUTERMOST edge (x stays aligned with the extremum): the top
+      // label rides the very top of the chart; the bottom label sits flush with
+      // the plot's bottom (clear of the x-axis below). The connector stops at the
+      // label, so the line never runs through the text.
+      const ch = engine.canvasHeight.get();
+      y =
+        side === "top"
+          ? EXTREMA_EDGE_INSET
+          : ch - padding.bottom - s.height;
+    } else {
+      // Sit just past the dot (max → above it, min → below it). With no dot (or a
+      // custom element), sit just past the point itself.
+      const gap = hasDot ? dotSizePx / 2 + EXTREMA_GAP : EXTREMA_GAP;
+      y = side === "top" ? p.py - gap - s.height : p.py + gap;
+    }
+    return { opacity: 1, transform: [{ translateX: x }, { translateY: y }] };
+  });
+
+  return (
+    <>
+      {hasDot && (
+        <Animated.View
+          pointerEvents="none"
+          style={[
+            styles.extremaDot,
+            {
+              width: dotSizePx,
+              height: dotSizePx,
+              borderRadius: dotSizePx / 2,
+              backgroundColor: dotColor ?? color,
+            },
+            dotStyle,
+          ]}
+        />
+      )}
+      <Animated.View
+        pointerEvents="none"
+        onLayout={onLayout}
+        style={[styles.extremaAnchor, labelStyle]}
+      >
+        {isCustom ? (
+          render()
+        ) : (
+          <Text
+            style={[
+              styles.extremaText,
+              {
+                color,
+                // undefined keys fall back to the base style / RN defaults.
+                fontSize: font.fontSize,
+                fontWeight: font.fontWeight,
+                fontFamily: font.fontFamily,
+              },
+            ]}
+          >
+            {valueText}
+          </Text>
+        )}
+      </Animated.View>
+    </>
+  );
+}
+
 /**
  * React Native overlay (NOT Skia) floating axis edge labels over the Skia
  * canvas — `topLabel` pinned to the plot's top edge and `bottomLabel` to its
@@ -62,6 +335,10 @@ function BuiltInAxisValueLabel({
  * bounds — formatted with the config's `format` (falling back to the chart's
  * `formatValue`) in the config `color` (falling back to `defaultColor`).
  *
+ * When a side's `position` is `"extrema"` (and the engine exposes the live
+ * extrema), it instead floats at the actual data point where the high / low
+ * occurs via {@link ExtremaAxisLabel}.
+ *
  * Because the chart's `<View>` is the canvas size, the plot's top edge sits
  * `padding.top` px from the top and its bottom edge `padding.bottom` px from
  * the bottom — so positioning needs only the resolved padding (no live height,
@@ -75,59 +352,135 @@ export function AxisLabelOverlay({
   formatValue,
   defaultColor,
   padding,
+  extremaTimeOffset = 0,
 }: {
   topLabel: ResolvedAxisLabelConfig | null;
   bottomLabel: ResolvedAxisLabelConfig | null;
-  engine: ChartEngineLayout;
+  engine: ChartEngineLayout & Partial<ChartEngineExtrema>;
   formatValue: (v: number) => string;
   defaultColor: string;
   padding: ChartPadding;
+  /**
+   * Seconds added to each extremum time before projecting (for `"extrema"`
+   * labels). Half a candle width in candle mode so the dot aligns with the
+   * candle's drawn center; `0` (default) for line / multi-series.
+   */
+  extremaTimeOffset?: number;
 }) {
   if (!topLabel && !bottomLabel) return null;
+
+  // Both extrema modes need the engine's live extrema SharedValues; without them
+  // (e.g. an engine that doesn't track them) fall back to the edge label.
+  const topMode = topLabel?.position;
+  const bottomMode = bottomLabel?.position;
+  const topExtrema =
+    (topMode === "extrema" || topMode === "extrema-edge") &&
+    engine.extremaMaxTime != null &&
+    engine.extremaMaxValue != null;
+  const bottomExtrema =
+    (bottomMode === "extrema" || bottomMode === "extrema-edge") &&
+    engine.extremaMinTime != null &&
+    engine.extremaMinValue != null;
+
   return (
     <View style={StyleSheet.absoluteFill} pointerEvents="none">
-      {topLabel && (
-        <View
-          style={{
-            position: "absolute",
-            top: padding.top,
-            left: padding.left,
-            right: padding.right,
-          }}
-        >
-          {topLabel.render ? (
-            topLabel.render()
-          ) : (
-            <BuiltInAxisValueLabel
-              value={engine.displayMax}
-              format={topLabel.format ?? formatValue}
-              color={topLabel.color ?? defaultColor}
-              position={topLabel.position}
-            />
-          )}
-        </View>
-      )}
-      {bottomLabel && (
-        <View
-          style={{
-            position: "absolute",
-            bottom: padding.bottom,
-            left: padding.left,
-            right: padding.right,
-          }}
-        >
-          {bottomLabel.render ? (
-            bottomLabel.render()
-          ) : (
-            <BuiltInAxisValueLabel
-              value={engine.displayMin}
-              format={bottomLabel.format ?? formatValue}
-              color={bottomLabel.color ?? defaultColor}
-              position={bottomLabel.position}
-            />
-          )}
-        </View>
-      )}
+      {topLabel &&
+        (topExtrema ? (
+          <ExtremaAxisLabel
+            side="top"
+            timeSV={engine.extremaMaxTime!}
+            valueSV={engine.extremaMaxValue!}
+            timeOffset={extremaTimeOffset}
+            edgeAnchor={topMode === "extrema-edge"}
+            engine={engine}
+            padding={padding}
+            format={topLabel.format ?? formatValue}
+            color={topLabel.color ?? defaultColor}
+            font={labelFont(topLabel)}
+            dotColor={topLabel.dotColor}
+            dotSize={topLabel.dotSize}
+            dot={topLabel.dot}
+            render={topLabel.render ?? undefined}
+          />
+        ) : (
+          <View
+            style={{
+              position: "absolute",
+              top: padding.top,
+              left: padding.left,
+              right: padding.right,
+            }}
+          >
+            {topLabel.render ? (
+              topLabel.render()
+            ) : (
+              <BuiltInAxisValueLabel
+                value={engine.displayMax}
+                format={topLabel.format ?? formatValue}
+                color={topLabel.color ?? defaultColor}
+                position={topLabel.position}
+                font={labelFont(topLabel)}
+              />
+            )}
+          </View>
+        ))}
+      {bottomLabel &&
+        (bottomExtrema ? (
+          <ExtremaAxisLabel
+            side="bottom"
+            timeSV={engine.extremaMinTime!}
+            valueSV={engine.extremaMinValue!}
+            timeOffset={extremaTimeOffset}
+            edgeAnchor={bottomMode === "extrema-edge"}
+            engine={engine}
+            padding={padding}
+            format={bottomLabel.format ?? formatValue}
+            color={bottomLabel.color ?? defaultColor}
+            font={labelFont(bottomLabel)}
+            dotColor={bottomLabel.dotColor}
+            dotSize={bottomLabel.dotSize}
+            dot={bottomLabel.dot}
+            render={bottomLabel.render ?? undefined}
+          />
+        ) : (
+          <View
+            style={{
+              position: "absolute",
+              bottom: padding.bottom,
+              left: padding.left,
+              right: padding.right,
+            }}
+          >
+            {bottomLabel.render ? (
+              bottomLabel.render()
+            ) : (
+              <BuiltInAxisValueLabel
+                value={engine.displayMin}
+                format={bottomLabel.format ?? formatValue}
+                color={bottomLabel.color ?? defaultColor}
+                position={bottomLabel.position}
+                font={labelFont(bottomLabel)}
+              />
+            )}
+          </View>
+        ))}
     </View>
   );
 }
+
+const styles = StyleSheet.create({
+  // top/left 0 + a measured transform places each piece over the point.
+  extremaAnchor: { position: "absolute", top: 0, left: 0, alignItems: "center" },
+  // The dot, pinned exactly on the data point (transform lands its center there).
+  // Size + radius are applied inline (configurable via `dotSize`).
+  extremaDot: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+  },
+  extremaText: {
+    fontSize: EXTREMA_LABEL_FONT_SIZE,
+    padding: 0,
+    fontVariant: ["tabular-nums"],
+  },
+});

package/src/components/CrosshairOverlay.tsx

@@ -27,6 +27,7 @@ export function CrosshairOverlay({
   showTooltip = true,
   children,
   renderTooltip,
+  lineTop,
   selectionDot,
   selectionY,
   scrubActive,
@@ -58,6 +59,10 @@ export function CrosshairOverlay({
   /** Public custom-tooltip hook for line mode: when provided (and no `children`
    *  are passed), its result replaces the default value/time tooltip body. */
   renderTooltip?: () => ReactNode;
+  /** Canvas-Y at which the crosshair line should start, so it stops just below a
+   *  top-pinned custom tooltip instead of running up through it. -1 (or omitted)
+   *  → start at `padding.top`. Fed by {@link CustomTooltipOverlay}. */
+  lineTop?: SharedValue<number>;
   /** Resolved selection-dot config; `null` hides it, a `component` renders the
    *  consumer's dot, otherwise the built-in dot. */
   selectionDot?: ResolvedSelectionDotConfig | null;
@@ -97,11 +102,16 @@ export function CrosshairOverlay({
   // captured plain values keeps the dependency array a constant size. SharedValue
   // reads stay reactive regardless of this list.
   const p1 = useDerivedValue(
-    () => ({
-      x: scrubX.value,
-      y: padding.top,
-    }),
-    [scrubX, padding.top],
+    () => {
+      // A top-pinned custom tooltip pushes the line's start down to its measured
+      // bottom (lineTop) so the line stops at the label; -1 → no top tooltip.
+      const lt = lineTop?.value ?? -1;
+      return {
+        x: scrubX.value,
+        y: lt >= 0 ? lt : padding.top,
+      };
+    },
+    [scrubX, padding.top, lineTop],
   );
   const p2 = useDerivedValue(
     () => ({

package/src/components/CustomTooltipOverlay.tsx

@@ -9,7 +9,7 @@ import Animated, {
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import type { TooltipLayout } from "../hooks/crosshairShared";
-import type { TooltipRenderProps } from "../types";
+import type { CandlePoint, TooltipRenderProps } from "../types";
 
 // Mirror the Skia tooltip's offsets (see crosshairShared.ts) so a custom pill
 // lines up with where the built-in one would sit. The vertical edge gap is
@@ -40,18 +40,22 @@ export function CustomTooltipOverlay({
   scrubValue,
   scrubTime,
   scrubActive,
+  scrubCandle,
   crosshairOpacity,
   tooltipLayout,
   engine,
   padding,
   placement,
   margin = 8,
+  lineTop,
 }: {
   renderTooltip: (ctx: TooltipRenderProps) => React.ReactElement | null | undefined;
   scrubX: SharedValue<number>;
   scrubValue: SharedValue<number | null>;
   scrubTime: SharedValue<number>;
   scrubActive: SharedValue<boolean>;
+  /** OHLC candle under the crosshair (candle mode); omitted/`null` in line mode. */
+  scrubCandle?: SharedValue<CandlePoint | null>;
   crosshairOpacity: SharedValue<number>;
   tooltipLayout: SharedValue<TooltipLayout>;
   engine: ChartEngineLayout;
@@ -59,11 +63,19 @@ export function CustomTooltipOverlay({
   placement: "side" | "top" | "bottom";
   /** Gap (px) between the pill and the plot edge it's pinned to. Default 8. */
   margin?: number;
+  /** When `placement` is `"top"`, the overlay publishes the label's bottom edge
+   *  (canvas Y) here so {@link CrosshairOverlay} can stop the crosshair line at
+   *  the label instead of running through it; -1 when not top-pinned/active. */
+  lineTop?: SharedValue<number>;
 }) {
   // Formatted strings come ready-made off the layout (formatted UI-side in
-  // computeTooltipLayout), so consumers don't need a worklet-safe formatter.
+  // computeTooltipLayout / computeCandleTooltipLayout), so consumers don't need
+  // a worklet-safe formatter for the value/time.
   const valueStr = useDerivedValue(() => tooltipLayout.get().valueStr);
   const timeStr = useDerivedValue(() => tooltipLayout.get().timeStr);
+  // A stable `null` candle SharedValue for line mode so `ctx.candle` is always
+  // present (a SharedValue), regardless of mode.
+  const nullCandle = useSharedValue<CandlePoint | null>(null);
 
   const ctx: TooltipRenderProps = {
     value: scrubValue,
@@ -71,6 +83,7 @@ export function CustomTooltipOverlay({
     valueStr,
     timeStr,
     active: scrubActive,
+    candle: scrubCandle ?? nullCandle,
   };
   const element = renderTooltip(ctx);
 
@@ -79,6 +92,12 @@ export function CustomTooltipOverlay({
   const onLayout = (e: LayoutChangeEvent) => {
     const { width, height } = e.nativeEvent.layout;
     size.value = { width, height };
+    // Publish the label's bottom edge (canvas Y) for a top-pinned tooltip so
+    // CrosshairOverlay stops the crosshair line at the label instead of running
+    // up through it; -1 for side/bottom → the line keeps its default start. The
+    // value when idle is irrelevant (the crosshair is hidden), so reacting to the
+    // measured height alone — no scrub-active dependency — is enough.
+    lineTop?.set(placement === "top" ? margin + height : -1);
   };
 
   const animatedStyle = useAnimatedStyle(() => {
@@ -96,15 +115,21 @@ export function CustomTooltipOverlay({
       if (x + s.width > rightEdge - EDGE_GAP) x = sx - s.width - OFFSET_X;
       y = padding.top + margin;
     } else {
-      const leftBound = padding.left + EDGE_GAP;
-      const rightBound = rightEdge - EDGE_GAP - s.width;
+      // Center on the crosshair, clamped to the *canvas* edges (not the plot's
+      // inner bounds) so a top/bottom-pinned label follows the crosshair all the
+      // way into the left/right gutters — e.g. past the wide Y-axis gutter on the
+      // right — instead of stopping short of the edge.
+      const leftBound = EDGE_GAP;
+      const rightBound = cw - EDGE_GAP - s.width;
       x = Math.min(
         Math.max(sx - s.width / 2, leftBound),
         Math.max(leftBound, rightBound),
       );
       y =
         placement === "top"
-          ? padding.top + margin
+          ? // Pin to the canvas top edge (not the plot's inner top), so the label
+            // sits above the data and the crosshair line can stop at it.
+            margin
           : ch - padding.bottom - margin - s.height;
     }