react-native-livechart 3.8.2 → 3.10.0

package/src/core/resolveConfig.ts

@@ -10,6 +10,7 @@ import type {
   LeftEdgeFadeConfig,
   LegendConfig,
   LegendStyle,
+  LineStyleConfig,
   LiveChartMetrics,
   LiveChartMetricsOverride,
   DotConfig,
@@ -61,12 +62,35 @@ export interface ResolvedYAxisConfig {
   minGap: number;
 }
 
+/** Resolved straight-line styling (connector, etc.). `color: undefined` → caller default. */
+export interface ResolvedLineStyleConfig {
+  color: string | undefined;
+  strokeWidth: number;
+  /** undefined → solid (no dash). */
+  intervals: [number, number] | undefined;
+}
+
 export interface ResolvedAxisLabelConfig {
   /** undefined → use the chart's `formatValue` at render time. */
   format?: (v: number) => string;
   /** undefined → use the muted default label color at render time. */
   color?: string;
-  position: "left" | "right";
+  /** `"left"`/`"right"` pin to that edge; `"extrema"`(-`edge`) tracks the data point. */
+  position: "left" | "right" | "extrema" | "extrema-edge";
+  /** undefined → the built-in default text size (11). */
+  fontSize?: number;
+  /** undefined → the platform `<Text>` default weight. */
+  fontWeight?: FontWeight;
+  /** undefined → the platform `<Text>` default family. */
+  fontFamily?: string;
+  /** Extrema dot color; undefined → use `color`. */
+  dotColor?: string;
+  /** Extrema dot diameter (px); undefined → the built-in default (7). */
+  dotSize?: number;
+  /** Extrema — whether to draw the marker dot. */
+  dot: boolean;
+  /** `"extrema-edge"` connector line (dot → edge label); null → none. */
+  connector: ResolvedLineStyleConfig | null;
   /** When set, the built-in value label is replaced by this custom element. */
   render?: () => ReactElement | null;
 }
@@ -81,6 +105,8 @@ export interface ResolvedScrubConfig {
   dimOpacity: number;
   /** undefined → palette.crosshairLine */
   crosshairLineColor: string | undefined;
+  /** Dash intervals `[on, off, …]` for the crosshair line; undefined → solid. */
+  crosshairDash: number[] | undefined;
   /** undefined → palette.crosshairDim */
   crosshairDimColor: string | undefined;
   /** undefined → palette.tooltipBg */
@@ -331,18 +357,65 @@ const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
   format: undefined,
   color: undefined,
   position: "right",
+  fontSize: undefined,
+  fontWeight: undefined,
+  fontFamily: undefined,
+  dotColor: undefined,
+  dotSize: undefined,
+  dot: true,
+  // Always overwritten by resolveAxisLabel (per-position default-on); placeholder.
+  connector: null,
   render: undefined,
 };
 
+/** Dashed by default — a subtle guide tying the extrema dot to its edge label. */
+const CONNECTOR_DEFAULTS: ResolvedLineStyleConfig = {
+  color: undefined,
+  strokeWidth: 1,
+  intervals: [2, 3],
+};
+
+/**
+ * Resolves the extrema-label `connector` sub-prop to a line style or null.
+ * `defaultOn` (true in `"extrema-edge"` mode) means an unset connector draws the
+ * dashed default; `false` → null; an object → merged; a `LineStyleConfig` is
+ * normalized (its `intervals` may be omitted for a solid line).
+ */
+export function resolveConnector(
+  prop: boolean | LineStyleConfig | undefined,
+  defaultOn: boolean,
+): ResolvedLineStyleConfig | null {
+  if (prop === false) return null;
+  if (prop == null) return defaultOn ? CONNECTOR_DEFAULTS : null;
+  if (prop === true) return CONNECTOR_DEFAULTS;
+  return {
+    color: prop.color,
+    strokeWidth: prop.strokeWidth ?? CONNECTOR_DEFAULTS.strokeWidth,
+    // An explicit object opts into its own dash (or solid when omitted).
+    intervals: prop.intervals,
+  };
+}
+
 /**
  * Resolves a `topLabel` / `bottomLabel` prop to a fully-typed config or null
  * (no label). Opt-in, so `undefined`/`false` → null; `true` → the built-in
  * value label with defaults; object → configured built-in (or a custom `render`).
+ * The `connector` defaults on (dashed) in `"extrema-edge"` mode, else off.
  */
 export function resolveAxisLabel(
   prop: boolean | AxisLabelConfig | undefined,
 ): ResolvedAxisLabelConfig | null {
-  return resolveToggle(prop, AXIS_LABEL_DEFAULTS, false);
+  const resolved = resolveToggle(prop, AXIS_LABEL_DEFAULTS, false);
+  if (!resolved) return null;
+  const connectorProp =
+    typeof prop === "object" ? prop.connector : undefined;
+  return {
+    ...resolved,
+    connector: resolveConnector(
+      connectorProp,
+      resolved.position === "extrema-edge",
+    ),
+  };
 }
 
 const X_AXIS_DEFAULTS: ResolvedXAxisConfig = {
@@ -363,6 +436,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   tooltip: true,
   dimOpacity: 0.3,
   crosshairLineColor: undefined,
+  crosshairDash: undefined,
   crosshairDimColor: undefined,
   tooltipBackground: undefined,
   tooltipColor: undefined,
@@ -382,7 +456,14 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
 export function resolveScrub(
   prop: boolean | ScrubConfig | undefined,
 ): ResolvedScrubConfig | null {
-  return resolveToggle(prop, SCRUB_DEFAULTS, false);
+  const resolved = resolveToggle(prop, SCRUB_DEFAULTS, false);
+  if (resolved) {
+    // Normalize the dash shorthand: `true` → a default dash, an array passes
+    // through, anything falsy → solid (undefined).
+    const dash = typeof prop === "object" ? prop.crosshairDash : undefined;
+    resolved.crosshairDash = dash === true ? [4, 4] : dash || undefined;
+  }
+  return resolved;
 }
 
 const SCRUB_ACTION_DEFAULTS: ResolvedScrubActionConfig = {

package/src/core/useLiveChartEngine.ts

@@ -63,13 +63,26 @@ export interface ChartEngineLayout {
   timestamp: SharedValue<number>;
 }
 
-export interface SingleEngineState extends ChartEngineLayout {
+/**
+ * Live extrema (value + time of the lowest / highest data point in the visible
+ * window) — the raw data high/low, not the smoothed display bounds. Each field
+ * is `NaN` when the window holds no data. Provided by both engines so an
+ * `"extrema"`-positioned `topLabel` / `bottomLabel` can be pinned at the point.
+ */
+export interface ChartEngineExtrema {
+  extremaMinValue: SharedValue<number>;
+  extremaMaxValue: SharedValue<number>;
+  extremaMinTime: SharedValue<number>;
+  extremaMaxTime: SharedValue<number>;
+}
+
+export interface SingleEngineState extends ChartEngineLayout, ChartEngineExtrema {
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
   displayValue: SharedValue<number>;
 }
 
-export interface MultiEngineState extends ChartEngineLayout {
+export interface MultiEngineState extends ChartEngineLayout, ChartEngineExtrema {
   data: SharedValue<LiveChartPoint[]>;
   value: SharedValue<number>;
   displayValue: SharedValue<number>;
@@ -109,6 +122,10 @@ export interface EngineFrameRefs {
   modeSV: SharedValue<"line" | "candle">;
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
+  extremaMinValue: SharedValue<number>;
+  extremaMaxValue: SharedValue<number>;
+  extremaMinTime: SharedValue<number>;
+  extremaMaxTime: SharedValue<number>;
 }
 
 /**
@@ -127,6 +144,10 @@ export function applyLiveChartEngineFrame(
     displayMax: sv.displayMax.value,
     displayWindow: sv.displayWindow.value,
     timestamp: sv.timestamp.value,
+    extremaMinValue: sv.extremaMinValue.value,
+    extremaMaxValue: sv.extremaMaxValue.value,
+    extremaMinTime: sv.extremaMinTime.value,
+    extremaMaxTime: sv.extremaMaxTime.value,
   };
   tickLiveChartEngineFrame(state, {
     dt,
@@ -155,6 +176,10 @@ export function applyLiveChartEngineFrame(
   sv.displayMax.value = state.displayMax;
   sv.displayWindow.value = state.displayWindow;
   sv.timestamp.value = state.timestamp;
+  sv.extremaMinValue.value = state.extremaMinValue;
+  sv.extremaMaxValue.value = state.extremaMaxValue;
+  sv.extremaMinTime.value = state.extremaMinTime;
+  sv.extremaMaxTime.value = state.extremaMaxTime;
 }
 
 export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
@@ -187,6 +212,13 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   const [initialTimestamp] = useState(() => Date.now() / 1000);
   const timestamp = useSharedValue(initialTimestamp);
 
+  // Live data extrema (value + time of the visible high / low). NaN until the
+  // first tick finds data — the extrema label stays hidden until then.
+  const extremaMinValue = useSharedValue(NaN);
+  const extremaMaxValue = useSharedValue(NaN);
+  const extremaMinTime = useSharedValue(NaN);
+  const extremaMaxTime = useSharedValue(NaN);
+
   // High-frequency data reads directly from the caller's shared values —
   // no useDerivedValue bridging, no closure serialization per tick.
   const { data, value, candles, liveCandle } = config;
@@ -221,6 +253,10 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     modeSV,
     candles,
     liveCandle,
+    extremaMinValue,
+    extremaMaxValue,
+    extremaMinTime,
+    extremaMaxTime,
   };
 
   // `autostart=false` registers the frame callback without running it — the live
@@ -271,5 +307,9 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
     canvasWidth,
     canvasHeight,
     timestamp,
+    extremaMinValue,
+    extremaMaxValue,
+    extremaMinTime,
+    extremaMaxTime,
   };
 }

package/src/core/useLiveChartSeriesEngine.ts

@@ -47,6 +47,10 @@ export interface MultiEngineFrameRefs {
   nowOverrideSV?: SharedValue<number | undefined>;
   windowBufferSV?: SharedValue<number>;
   pausedSV: SharedValue<boolean>;
+  extremaMinValue: SharedValue<number>;
+  extremaMaxValue: SharedValue<number>;
+  extremaMinTime: SharedValue<number>;
+  extremaMaxTime: SharedValue<number>;
 }
 
 /**
@@ -103,6 +107,10 @@ export function applyLiveChartSeriesEngineFrame(
     timestamp: sv.timestamp.value,
     displayValues,
     opacities,
+    extremaMinValue: sv.extremaMinValue.value,
+    extremaMaxValue: sv.extremaMaxValue.value,
+    extremaMinTime: sv.extremaMinTime.value,
+    extremaMaxTime: sv.extremaMaxTime.value,
   };
   tickLiveChartSeriesEngineFrame(state, {
     dt,
@@ -128,6 +136,10 @@ export function applyLiveChartSeriesEngineFrame(
   sv.timestamp.value = state.timestamp;
   sv.displaySeriesValues.value = state.displayValues;
   sv.seriesOpacities.value = state.opacities;
+  sv.extremaMinValue.value = state.extremaMinValue;
+  sv.extremaMaxValue.value = state.extremaMaxValue;
+  sv.extremaMinTime.value = state.extremaMinTime;
+  sv.extremaMaxTime.value = state.extremaMaxTime;
 }
 
 /**
@@ -161,6 +173,12 @@ export function useLiveChartSeriesEngine(
   const displaySeriesValues = useSharedValue<number[]>([]);
   const seriesOpacities = useSharedValue<number[]>([]);
 
+  // Live data extrema (value + time of the visible high / low across series).
+  const extremaMinValue = useSharedValue(NaN);
+  const extremaMaxValue = useSharedValue(NaN);
+  const extremaMinTime = useSharedValue(NaN);
+  const extremaMaxTime = useSharedValue(NaN);
+
   const data = useSharedValue<LiveChartPoint[]>([]);
   const value = useSharedValue(0);
   const displayValue = useSharedValue(0);
@@ -199,6 +217,10 @@ export function useLiveChartSeriesEngine(
         nowOverrideSV,
         windowBufferSV,
         pausedSV,
+        extremaMinValue,
+        extremaMaxValue,
+        extremaMinTime,
+        extremaMaxTime,
       },
       scratch,
     );
@@ -218,5 +240,9 @@ export function useLiveChartSeriesEngine(
     series,
     displaySeriesValues,
     seriesOpacities,
+    extremaMinValue,
+    extremaMaxValue,
+    extremaMinTime,
+    extremaMaxTime,
   };
 }

package/src/hooks/crosshairShared.ts

@@ -4,6 +4,7 @@ import type { SharedValue } from "react-native-reanimated";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import { type ChartPadding } from "../draw/line";
 import { interpolateAtTime } from "../math/interpolate";
+import type { CandlePoint } from "../types";
 
 const TOOLTIP_PAD_X = 8;
 const TOOLTIP_PAD_Y = 6;
@@ -57,6 +58,17 @@ export interface CrosshairState {
   /** Scrub intersection Y in canvas px; -1 when there's no dot to draw
    *  (inactive / no value / degenerate range). See {@link computeScrubDotY}. */
   scrubDotY: SharedValue<number>;
+  /** OHLC candle under the crosshair in candle mode (`null` in line mode or when
+   *  inactive) — single-series `useCrosshair` only; undefined on the multi-series
+   *  crosshair. Surfaced for a custom candle `renderTooltip`. */
+  scrubCandle?: SharedValue<CandlePoint | null>;
+  /** Canvas-Y where the crosshair line should start so it stops at a top-pinned
+   *  custom tooltip's bottom edge instead of running up through it. Written by
+   *  {@link CustomTooltipOverlay} (the label's measured bottom) when
+   *  `tooltipPlacement: "top"` is active, read by {@link CrosshairOverlay}; -1
+   *  means "no top tooltip" → the line starts at `padding.top` as before.
+   *  Single-series `useCrosshair` only; undefined on the multi-series crosshair. */
+  tooltipLineTop?: SharedValue<number>;
   gesture: ReturnType<typeof Gesture.Pan>;
 
   // ── Scrub-action ("order ticket") lock state — single-series `useCrosshair`
@@ -383,7 +395,7 @@ export function computeCandleTooltipLayout(
     { text: `C ${formatValue(candle.close)}`, dim: false },
     { text: formatTime(scrubTime), dim: true },
   ];
-  return computeTooltipLayoutMulti(
+  const layout = computeTooltipLayoutMulti(
     scrubActive,
     scrubX,
     lines,
@@ -392,6 +404,13 @@ export function computeCandleTooltipLayout(
     font,
     monoCharWidth,
   );
+  // Surface the close + time as the single-value strings too. The built-in
+  // OHLC stack renders `stackedLines`, but a custom `renderTooltip` reads
+  // `valueStr` / `timeStr` off the layout (same as line mode) — so a custom
+  // candle tooltip gets a ready-made close + time without its own formatter.
+  layout.valueStr = formatValue(candle.close);
+  layout.timeStr = formatTime(scrubTime);
+  return layout;
 }
 
 /** Single-series scrub value at window time — extracted for tests. */

package/src/hooks/useCrosshair.ts

@@ -143,6 +143,10 @@ export function useCrosshair(
   // Tracks whether the active scrub phase actually began, so a tap that never
   // activates doesn't emit a spurious onGestureEnd.
   const gestureStarted = useSharedValue(false);
+  // Where the crosshair line should start (canvas Y) so it stops at a top-pinned
+  // custom tooltip instead of running through it. -1 = no top tooltip → the line
+  // starts at padding.top. Written by CustomTooltipOverlay, read by CrosshairOverlay.
+  const tooltipLineTop = useSharedValue(-1);
 
   // Scrub-action lock state. Created unconditionally (hooks must be), but the
   // lock gestures are only wired by the controller when `scrubAction` is set.
@@ -634,9 +638,11 @@ export function useCrosshair(
     scrubActive,
     scrubTime,
     scrubValue,
+    scrubCandle,
     crosshairOpacity,
     tooltipLayout,
     scrubDotY,
+    tooltipLineTop,
     gesture,
     lockActive,
     lockX,

package/src/types.ts

@@ -228,6 +228,20 @@ export interface ValueLineConfig {
   color?: string;
 }
 
+/**
+ * Shared styling for a simple straight line — color, thickness, and an optional
+ * dash. The common shape behind the chart's secondary lines (the `valueLine`,
+ * the extrema-label `connector`, etc.), so they configure the same way.
+ */
+export interface LineStyleConfig {
+  /** Line color. Defaults per usage (e.g. the connector uses the label color). */
+  color?: string;
+  /** Line thickness in pixels. Default `1`. */
+  strokeWidth?: number;
+  /** Dash pattern as `[dashLength, gapLength]` in pixels. Omit for a solid line. */
+  intervals?: [number, number];
+}
+
 /** Main chart line styling. */
 export interface LineConfig {
   /** Stroke width of the main line in pixels. Default `2`. */
@@ -356,9 +370,52 @@ export interface AxisLabelConfig {
   format?: (v: number) => string;
   /** Text color. Defaults to a muted label color (`palette.gridLabel`). */
   color?: string;
-  /** Horizontal alignment within the plot width. Default `"right"`. */
-  position?: "left" | "right";
-  /** Full custom element, floated at the edge. Overrides the built-in value label. */
+  /**
+   * Where the label sits.
+   * - `"left"` / `"right"` (default `"right"`) — pin to that edge of the plot,
+   *   horizontally aligned.
+   * - `"extrema"` — float at the **actual data point** where the value occurs
+   *   (`topLabel` tracks the highest point, `bottomLabel` the lowest), anchored
+   *   over the point with a marker dot, so you can see *when* the high / low
+   *   happened. The dot and label track the point on the UI thread.
+   * - `"extrema-edge"` — like `"extrema"`, but the value label is pinned to the
+   *   **top / bottom edge**, horizontally aligned with the extremum (not floated
+   *   over the point). The marker dot still sits on the data point, joined to the
+   *   edge label by a {@link AxisLabelConfig.connector} line. Keeps the readout on
+   *   a clean rail while still showing where the extremum is.
+   */
+  position?: "left" | "right" | "extrema" | "extrema-edge";
+  /** Built-in value text size in px. Default `11`. */
+  fontSize?: number;
+  /** Built-in value text weight. Default the platform `<Text>` default. */
+  fontWeight?: FontWeight;
+  /** Built-in value text font family (e.g. a loaded monospace face). */
+  fontFamily?: string;
+  /**
+   * Extrema modes only — color of the marker dot at the data point. Defaults to
+   * `color`. Lets the dot and the value text differ.
+   */
+  dotColor?: string;
+  /** Extrema modes only — marker dot diameter in px. Default `7`. */
+  dotSize?: number;
+  /**
+   * Extrema modes only — draw the marker dot at the data point. Default `true`.
+   * Set `false` for a value label with no dot.
+   */
+  dot?: boolean;
+  /**
+   * `"extrema-edge"` only — the line joining the marker dot (on the data point)
+   * to the edge value label. `true` = a dashed default, `false` = none, or pass a
+   * {@link LineStyleConfig} to style it (`color` defaults to the label `color`).
+   * Default on (dashed) in `"extrema-edge"` mode.
+   */
+  connector?: boolean | LineStyleConfig;
+  /**
+   * Full custom element, floated at the edge (or, in an extrema mode, centered
+   * over the extremum point). Overrides the built-in value label (and the
+   * `fontSize` / `fontWeight` / `fontFamily` / `dot*` knobs above — you own the
+   * styling).
+   */
   render?: () => ReactElement | null;
 }
 
@@ -382,6 +439,12 @@ export interface ScrubConfig {
   dimOpacity?: number;
   /** Vertical crosshair line stroke. Omit to use theme `crosshairLine`. */
   crosshairLineColor?: string;
+  /**
+   * Dash the vertical crosshair line. `true` → a default `[4, 4]` dash; an array
+   * sets explicit Skia dash intervals `[on, off, …]` in px. Omit / `false` → a
+   * solid line.
+   */
+  crosshairDash?: number[] | boolean;
   /**
    * Legacy: fill the region right of the crosshair with this solid (usually
    * semi-transparent) color — a mask painted *over* the chart, so it only looks
@@ -521,16 +584,30 @@ export interface SelectionDotProps {
  * for the value/date to update on the UI thread too.
  */
 export interface TooltipRenderProps {
-  /** Interpolated value under the crosshair; `null` when none. */
+  /**
+   * Value under the crosshair; `null` when none. In line mode this is the
+   * interpolated value at the scrub time; in candle mode it's the scrubbed
+   * candle's close (use {@link TooltipRenderProps.candle} for full OHLC).
+   */
   value: SharedValue<number | null>;
   /** Window time (unix seconds) under the crosshair. */
   time: SharedValue<number>;
-  /** Value formatted with the chart's `formatValue` (computed UI-side). */
+  /**
+   * Value formatted with the chart's `formatValue` (computed UI-side). In candle
+   * mode this is the formatted close.
+   */
   valueStr: SharedValue<string>;
   /** Time formatted with the chart's `formatTime` (computed UI-side). */
   timeStr: SharedValue<string>;
   /** Whether scrubbing is currently active. */
   active: SharedValue<boolean>;
+  /**
+   * In candle mode, the OHLC candle under the crosshair (`null` when none or
+   * while inactive). Always `null` in line mode — bind it to render OHLC in a
+   * custom candlestick tooltip. Format the individual prices with your own
+   * worklet-safe formatter (e.g. the chart's `formatValue`).
+   */
+  candle: SharedValue<CandlePoint | null>;
 }
 
 /** Outer ring drawn around the built-in selection dot (the subtle halo). */
@@ -1094,9 +1171,13 @@ export interface LiveChartCoreProps {
    * background are plain RN styles) and content — bind the {@link
    * TooltipRenderProps} SharedValues to animated text for the value/date.
    *
-   * Return `null`/`undefined` to fall back to the built-in pill. Replaces the
-   * default pill entirely while active. Single-series **line mode only** —
-   * ignored in candle mode (the OHLC stack owns the tooltip there).
+   * Supplying `renderTooltip` replaces the built-in tooltip entirely while
+   * scrubbing (the line pill in line mode, the OHLC stack in candle mode).
+   * Returning `null`/`undefined` from a frame renders nothing for that frame
+   * (e.g. to hide the tooltip in certain states) — it does *not* restore the
+   * built-in pill. Works in **both line and candle mode**: in candle mode the
+   * scrubbed candle is available as {@link TooltipRenderProps.candle} for
+   * rendering your own OHLC readout.
    */
   renderTooltip?: (ctx: TooltipRenderProps) => ReactElement | null | undefined;
   /**