react-native-livechart 4.10.0 → 4.12.0

package/src/math/lerp.ts

@@ -12,6 +12,13 @@ export function lerp(
   dt = MS_PER_FRAME_60FPS,
 ): number {
   "worklet";
+  // speed >= 1 means "snap in one frame". Computing it through the exponential
+  // would evaluate 0 ** (dt / frame), which is Infinity for a negative frame
+  // delta. When current === target, the resulting 0 * -Infinity becomes NaN
+  // and is permanent once written back into a SharedValue. No broader guard:
+  // NaN inputs must keep propagating (the engine tick relies on a NaN
+  // displayValue staying NaN so the y-range block stays skipped).
+  if (speed >= 1) return target;
   const factor = 1 - Math.pow(1 - speed, dt / MS_PER_FRAME_60FPS);
   return current + (target - current) * factor;
 }

package/src/math/momentum.ts

@@ -9,15 +9,32 @@ export function detectMomentum(
   points: LiveChartPoint[],
   lookback = 20,
   threshold = 0.12,
+  endTime?: number,
 ): Momentum {
   "worklet";
-  if (points.length < 5) return "flat";
+  // `badge.followViewEdge` needs momentum at the historical window edge rather
+  // than at the live dataset tail. Points are chronological, so find the first
+  // sample after the inclusive cutoff without allocating a sliced array on the
+  // UI thread. With no cutoff, preserve the normal live-tail behavior.
+  let end = points.length;
+  if (endTime !== undefined) {
+    let lo = 0;
+    let hi = points.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (points[mid].time <= endTime) lo = mid + 1;
+      else hi = mid;
+    }
+    end = lo;
+  }
+
+  if (end < 5) return "flat";
 
-  const start = Math.max(0, points.length - lookback);
+  const start = Math.max(0, end - lookback);
 
   let min = Infinity;
   let max = -Infinity;
-  for (let i = start; i < points.length; i++) {
+  for (let i = start; i < end; i++) {
     const v = points[i].value;
     if (v < min) min = v;
     if (v > max) max = v;
@@ -25,9 +42,9 @@ export function detectMomentum(
   const range = max - min;
   if (range === 0) return "flat";
 
-  const tailStart = Math.max(start, points.length - 5);
+  const tailStart = Math.max(start, end - 5);
   const first = points[tailStart].value;
-  const last = points[points.length - 1].value;
+  const last = points[end - 1].value;
   const delta = last - first;
 
   const absThreshold = range * threshold;

package/src/math/referenceLines.ts

@@ -44,6 +44,44 @@ export function collectReferenceValues(lines: ReferenceLine[]): number[] {
   return out;
 }
 
+/**
+ * Stable React keys for an ordered reference-line list. A caller-supplied `id`
+ * keeps the key stable across reordering; the visual config is a deterministic
+ * fallback for legacy lines. Equal fallback signatures receive a suffix so they
+ * remain distinct siblings.
+ */
+export function referenceLineReactKeys(
+  lines: readonly ReferenceLine[],
+): string[] {
+  const occurrences = new Map<string, number>();
+  const keys: string[] = [];
+  for (const line of lines) {
+    const base = line.id ?? stableReferenceLineSignature(line);
+    const occurrence = occurrences.get(base) ?? 0;
+    occurrences.set(base, occurrence + 1);
+    keys.push(`${base}:${occurrence}`);
+  }
+  return keys;
+}
+
+/** Serializes render-relevant config without callback identity churn. */
+function stableReferenceLineSignature(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableReferenceLineSignature).join(",")}]`;
+  }
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const entries: string[] = [];
+    for (const key of Object.keys(record).sort()) {
+      const entry = record[key];
+      if (typeof entry === "function" || entry === undefined) continue;
+      entries.push(`${key}:${stableReferenceLineSignature(entry)}`);
+    }
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "undefined";
+}
+
 /**
  * Fully-resolved badge **style/shape** + anchor — the resolved counterpart of
  * {@link BadgeStyleConfig} (`position` / `icon` / `showText` plus the style knobs).

package/src/math/squiggly.ts

@@ -31,6 +31,7 @@ export function squigglyYAt(
  * Build a flat [x0,y0,x1,y1,...] point array for a standalone squiggly line
  * spanning the full chart area (used in loading / empty state).
  * Points are spaced ~4px apart for smooth curves.
+ * Pass `out` to reuse a caller-owned frame scratch.
  */
 export function buildSquigglyPts(
   canvasWidth: number,
@@ -39,17 +40,22 @@ export function buildSquigglyPts(
   t: number,
   base = 14,
   speed = 1,
+  out?: number[],
 ): number[] {
   "worklet";
+  const pts = out ?? [];
   const leftEdge = padding.left;
   const rightEdge = canvasWidth - padding.right;
   const chartW = rightEdge - leftEdge;
-  if (chartW <= 0 || canvasHeight <= 0) return [];
+  if (chartW <= 0 || canvasHeight <= 0) {
+    pts.length = 0;
+    return pts;
+  }
 
   const centerY = (canvasHeight - padding.bottom + padding.top) / 2;
   const step = 4;
   const count = Math.ceil(chartW / step) + 1;
-  const pts: number[] = new Array(count * 2);
+  pts.length = count * 2;
   for (let i = 0; i < count; i++) {
     const x = leftEdge + Math.min(i * step, chartW);
     pts[i * 2] = x;
@@ -61,6 +67,7 @@ export function buildSquigglyPts(
 /**
  * Given a real flat-pts array (from buildLinePoints), replace each Y with the
  * squiggly Y at the same X. Used during the morph reveal.
+ * Pass `out` to reuse a caller-owned frame scratch.
  */
 export function squigglifyPts(
   flatPts: number[],
@@ -68,15 +75,17 @@ export function squigglifyPts(
   centerY: number,
   base = 14,
   speed = 1,
+  out?: number[],
 ): number[] {
   "worklet";
   const n = flatPts.length;
-  const out: number[] = new Array(n);
+  const target = out ?? [];
+  target.length = n;
   for (let i = 0; i < n; i += 2) {
-    out[i] = flatPts[i];
-    out[i + 1] = squigglyYAt(flatPts[i], centerY, t, base, speed);
+    target[i] = flatPts[i];
+    target[i + 1] = squigglyYAt(flatPts[i], centerY, t, base, speed);
   }
-  return out;
+  return target;
 }
 
 /**
@@ -97,6 +106,7 @@ export function smoothstep(t: number): number {
  *   distFromCentre = |x - chartCentreX| / (chartW / 2)   // 0=centre, 1=edge
  *   weight = smoothstep((morphT - distFromCentre * 0.5) / 0.5)
  *   blendedY = fromY + (toY - fromY) * weight
+ * Pass `out` to reuse a caller-owned frame scratch.
  */
 export function blendPtsY(
   from: number[],
@@ -104,19 +114,26 @@ export function blendPtsY(
   morphT: number,
   padding: ChartPadding,
   canvasWidth: number,
+  out?: number[],
 ): number[] {
   "worklet";
   const n = from.length;
-  if (n === 0) return to;
+  if (n === 0 && !out) return to;
   const chartCentreX = (padding.left + canvasWidth - padding.right) / 2;
   const halfChartW = (canvasWidth - padding.left - padding.right) / 2;
-  const out: number[] = new Array(n);
+  const target = out ?? [];
+  const outputLength = n === 0 ? to.length : n;
+  target.length = outputLength;
+  if (n === 0) {
+    for (let i = 0; i < to.length; i++) target[i] = to[i];
+    return target;
+  }
   for (let i = 0; i < n; i += 2) {
-    out[i] = to[i]; // X always from real pts
+    target[i] = to[i]; // X always from real pts
     const distFromCentre =
       halfChartW > 0 ? Math.abs(from[i] - chartCentreX) / halfChartW : 0;
     const weight = smoothstep((morphT - distFromCentre * 0.5) / 0.5);
-    out[i + 1] = from[i + 1] + (to[i + 1] - from[i + 1]) * weight;
+    target[i + 1] = from[i + 1] + (to[i + 1] - from[i + 1]) * weight;
   }
-  return out;
+  return target;
 }

package/src/math/threshold.ts

@@ -12,8 +12,8 @@ import type { LiveChartPoint } from "../types";
  * projected to this many evenly-spaced pixel-Y values across the plot, which the
  * shader linearly interpolates between. ~one sample per 6px on a phone plot —
  * fine enough that the line's crossing point is coloured accurately. The shader
- * walks these in an unrolled loop (`THRESHOLD_SAMPLE_COUNT - 1` iterations), so
- * keep it modest to stay within SkSL's unroll limits.
+ * selects between them through a balanced constant-index branch tree, so 64
+ * samples require at most six comparisons per covered fragment.
  */
 export const THRESHOLD_SAMPLE_COUNT = 64;
 

package/src/types.ts

@@ -44,6 +44,10 @@ export type FontWeight =
 /** Color scheme for the chart background, grid, and derived palette colors. */
 export type ThemeMode = "light" | "dark";
 
+/** Skia canvas composition mode. Android uses TextureView for `"transparent"`
+ * and an opaque SurfaceView for `"opaque"`. */
+export type CanvasMode = "transparent" | "opaque";
+
 /**
  * Badge pill style.
  * - `"default"` — accent-colored background with white text.
@@ -59,6 +63,11 @@ export type BadgeVariant = "default" | "minimal";
  * - **Form C** — vertical time band between `from` and `to` (unix seconds).
  */
 export interface ReferenceLine {
+  /**
+   * Stable identifier for this line. Supply a unique value when `referenceLines`
+   * may be reordered so the chart preserves the line's rendered identity.
+   */
+  id?: string;
   /** Form A — the Y-axis value where the horizontal line is drawn. */
   value?: number;
   /** Form B — horizontal band lower Y bound (paired with `valueTo`). */
@@ -249,14 +258,17 @@ export interface ReferenceLineBadgeConfig extends BadgeStyleConfig {
 }
 
 /**
- * Context passed to a custom {@link LiveChartProps.renderReferenceLine}. The chart
- * floats the element you return over the canvas and pins it to the line's value on
- * the UI thread (vertically centered on the line, horizontally at the badge /
- * label position) — so it tracks the rescaling axis and any drag smoothly without
- * JS re-renders, just like {@link TooltipRenderProps}. Replaces the built-in pill
- * badge / gutter label for that line; return `null`/`undefined` to keep the
- * built-in. Bind the SharedValues to animated text (e.g. an animated `TextInput`)
- * for the value to update on the UI thread too.
+ * Context passed to a custom {@link LiveChartProps.renderReferenceLine} or
+ * {@link LiveChartProps.renderOffAxisReferenceLine} (and their
+ * `LiveChartSeries` counterparts). The chart floats the element you return over
+ * the canvas and pins it to the line's value on the UI thread (vertically centered
+ * on the line, horizontally at the badge / label position) — so it tracks the
+ * rescaling axis and any drag smoothly without JS re-renders, just like
+ * {@link TooltipRenderProps}. `renderReferenceLine` replaces the built-in pill /
+ * gutter label in every state; `renderOffAxisReferenceLine` replaces it only while
+ * the value is pinned above or below the visible plot. Bind the SharedValues to
+ * animated text (e.g. an animated `TextInput`) for the value to update on the UI
+ * thread too.
  */
 export interface ReferenceLineRenderProps {
   /** The reference line being rendered. */
@@ -587,7 +599,9 @@ export interface BadgeConfig extends BadgeStyleConfig {
    * When the chart is scrolled back (see `timeScroll`), move the live-price
    * indicators — the badge, the value line, and the live dot — to the price at
    * the visible window's right edge instead of the live price, so they track the
-   * last visible price as you pan. Default `false`.
+   * last visible price as you pan. The badge's momentum color is derived at that
+   * same historical edge, so incoming live ticks do not recolor it. Default
+   * `false`.
    *
    * @experimental
    */
@@ -711,10 +725,102 @@ export interface XAxisConfig {
   minGap?: number;
 }
 
+/**
+ * Morfi-style on-canvas tooltip for {@link LiveChartSeries}: a time-range pill
+ * above the guide plus one value pill at every visible series intersection.
+ *
+ * Enable it with `scrub={{ seriesTooltip: true }}` or pass this object to style
+ * and format the readout. It is ignored by the single-series {@link LiveChart}.
+ */
+export interface PerSeriesTooltipConfig {
+  /**
+   * Keep the value pills pinned to the visible series endpoints while idle.
+   * The guide and time pill remain hidden until a scrub starts. Default `false`.
+   */
+  alwaysShow?: boolean;
+  /**
+   * Bucket width used by the time-range pill, in seconds. Omit to infer it from
+   * the latest positive interval in the first visible series.
+   */
+  bucketSeconds?: number;
+  /**
+   * Format a value pill. The second argument identifies the series so one chart
+   * can dispatch to different unit formatters. Defaults to the chart's
+   * `formatValue`.
+   *
+   * Runs on the UI thread and must be worklet-safe.
+   */
+  formatSeriesValue?: (value: number, seriesId: string) => string;
+  /**
+   * Format the time pill from the bucket's start/end unix seconds. The end is
+   * clamped to the chart's current-time anchor, so the live bucket never claims
+   * to end in the future. Defaults to two chart `formatTime` labels joined by
+   * an en dash.
+   *
+   * Runs on the UI thread and must be worklet-safe.
+   */
+  formatTimeRange?: (from: number, to: number) => string;
+  /** Truncate labels longer than this many characters with `…`. Default `14`. */
+  maxLabelChars?: number;
+
+  /** Guide color. Omit to use `scrub.crosshairLineColor`, then the theme. */
+  guideColor?: string;
+  /** Guide stroke width in px. Default `1`. */
+  guideWidth?: number;
+  /**
+   * Guide dash pattern. `true` uses `[3, 3]`; an array supplies explicit Skia
+   * dash intervals; `false` draws a solid guide. Default `[3, 3]`.
+   */
+  guideDashPattern?: boolean | number[];
+
+  /** Time-pill background. Omit to use `scrub.tooltipBackground`, then the theme. */
+  timePillBackground?: string;
+  /** Time-pill text color. Omit to use `scrub.tooltipColor`, then the theme. */
+  timePillColor?: string;
+  /** Time-pill border color. Omit to use `scrub.tooltipBorderColor`, then the theme. */
+  timePillBorderColor?: string;
+  /** Time-pill corner radius in px. Default `6`. */
+  timePillRadius?: number;
+  /** Time-pill horizontal padding in px. Default `8`. */
+  timePillPaddingX?: number;
+  /** Time-pill vertical padding in px. Default `4`. */
+  timePillPaddingY?: number;
+
+  /** Series-pill background. Omit to use `scrub.tooltipBackground`, then the theme. */
+  seriesPillBackground?: string;
+  /** Series label color. Omit to use the theme tooltip text. */
+  seriesPillLabelColor?: string;
+  /** Formatted series value color. Omit to use `seriesPillLabelColor`. */
+  seriesPillValueColor?: string;
+  /** Series-pill border color. Omit to use `scrub.tooltipBorderColor`, then the theme. */
+  seriesPillBorderColor?: string;
+  /** Series-pill corner radius in px. Default `6`. */
+  seriesPillRadius?: number;
+  /** Series-pill horizontal padding in px. Default `8`. */
+  seriesPillPaddingX?: number;
+  /** Series-pill vertical padding in px. Default `4`. */
+  seriesPillPaddingY?: number;
+  /** Diameter of the series-colour dot inside each pill, in px. Default `8`. */
+  seriesPillDotSize?: number;
+  /** Gap between the colour dot and label, in px. Default `6`. */
+  seriesPillDotGap?: number;
+  /** Gap between the label and formatted value, in px. Default `6`. */
+  seriesPillLabelValueGap?: number;
+  /** Diameter of the dot drawn at each line/guide intersection. Default `8`. */
+  intersectionDotSize?: number;
+}
+
 /** Crosshair scrub configuration. */
 export interface ScrubConfig {
   /** Show the value/time tooltip pill while scrubbing. Default `true`. */
   tooltip?: boolean;
+  /**
+   * Opt into the Morfi-style per-series pill tooltip on `LiveChartSeries`.
+   * `true` uses defaults; an object enables and configures it; `false`/omitted
+   * preserves the existing guide-only multi-series scrub. Ignored by
+   * single-series `LiveChart`. Default `false`.
+   */
+  seriesTooltip?: boolean | PerSeriesTooltipConfig;
   /**
    * Opacity of the chart content to the *right* of the crosshair (the "future")
    * while scrubbing — `0` fully fades it out, `1` disables the dim. Implemented
@@ -960,7 +1066,8 @@ export interface ChartScale {
 
 /**
  * The price↔pixel / time↔pixel bridge handed to a custom
- * {@link LiveChartProps.renderOverlay}.
+ * {@link LiveChartProps.renderOverlay} or
+ * {@link LiveChartSeriesProps.renderOverlay}.
  *
  * **Easiest path — the `usePriceY` / `useTimeX` hooks.** They project a price / time
  * to a `SharedValue<number>` that tracks the live axis for you; just read it in
@@ -1122,7 +1229,8 @@ export interface TradeEvent {
 }
 
 /** Built-in marker glyph kinds drawn into the chart canvas. */
-export type MarkerKind = "trade" | "boost" | "graduation" | "winner" | "clawback";
+export type MarkerKind =
+  "trade" | "boost" | "graduation" | "winner" | "clawback";
 
 /**
  * A marker rendered into the chart at `(time, y)`. Exactly one of `seriesId`
@@ -1614,6 +1722,15 @@ export interface TimeScrollConfig {
    * if set, otherwise `500`.
    */
   scrubHoldMs?: number;
+  /**
+   * Hide the live badge, dot, and dashed value line while scrolled back through
+   * history. Default `true`: all three mark the LIVE price, which is off-screen
+   * once the window is frozen behind the live edge, so they'd point at a price
+   * that isn't in view. Set `false` to keep them visible while scrolled back.
+   * Ignored when `badge.followViewEdge` is on — there the group tracks the
+   * visible edge price, which IS in view.
+   */
+  hideLiveOnScrollBack?: boolean;
 }
 
 /**
@@ -1748,6 +1865,18 @@ export interface LiveChartCoreProps {
   insets?: ChartInsets;
   /** Container View style. */
   style?: ViewStyle;
+  /**
+   * Canvas composition mode. `"transparent"` keeps Skia's default compositing
+   * path (TextureView on Android) and can reveal content behind the chart.
+   * `"opaque"` makes the canvas own and paint its palette background; on Android
+   * this selects SurfaceView and may reduce RenderThread work, but it cannot be
+   * used when the chart must reveal content behind it. Default `"transparent"`.
+   *
+   * @experimental Profile on representative physical Android hardware before
+   * enabling broadly; SurfaceView ordering, clipping, transforms, screenshots,
+   * and parent scrolling should be validated in the consuming layout.
+   */
+  canvasMode?: CanvasMode;
   /** Visible time window in seconds. Default `30`. */
   timeWindow?: number;
   /** Freeze chart scrolling. Resume catches up to real time. Default `false`. */
@@ -1990,8 +2119,9 @@ export interface LiveChartCoreProps {
    *
    * Defaults differ per chart: `LiveChart` shows it (`true`); `LiveChartSeries`
    * hides it (`false`) — with multiple lines the dot can only track the leading
-   * series, so the crosshair + per-series tooltips mark the scrub point instead.
-   * Pass `true` / a config to opt a multi-series chart in.
+   * series. The crosshair — and, when enabled, the per-series tooltip's own
+   * intersection dots — mark the scrub point instead. Pass `true` / a config to
+   * opt a multi-series chart in.
    */
   selectionDot?: boolean | SelectionDotConfig;
   /** Called once when the user starts scrubbing/panning the chart. */
@@ -2143,19 +2273,36 @@ export interface LiveChartProps extends LiveChartCoreProps {
    * pins it to the line's value on the UI thread (see {@link ReferenceLineRenderProps}),
    * so it tracks the rescaling axis and any drag without JS re-renders. Called per
    * Form-A line; return `null`/`undefined` to keep that line's built-in tag. Works
-   * with `badge: false` too (replace the plain gutter label). Single-series only.
+   * with `badge: false` too (replace the plain gutter label). For a left- or
+   * right-pinned `badge`, the chart retains the dashed connector and measures the
+   * custom tag so the connector starts at its outer edge. Single-series only.
    */
   renderReferenceLine?: (
     ctx: ReferenceLineRenderProps,
   ) => ReactElement | null | undefined;
+  /**
+   * Render only a Form-A line's **off-axis** tag as a custom React Native element.
+   * The chart keeps the standard Skia tag / gutter label while the value is in
+   * range, then switches to this element when it pins above or below the plot.
+   * With a left- or right-pinned `badge` (or legacy `offAxisBadge`), its dashed
+   * connector stays native and begins after the measured custom tag. Return
+   * `null`/`undefined` to opt a line out based on its static `line` / `index`;
+   * use the `edge` SharedValue inside the returned element to animate a caret.
+   * `renderReferenceLine` takes precedence if both callbacks handle one line.
+   * Single-series only.
+   */
+  renderOffAxisReferenceLine?: (
+    ctx: ReferenceLineRenderProps,
+  ) => ReactElement | null | undefined;
   /**
    * Collapse Form-A reference lines whose handles sit near the same value into a
    * single count handle (e.g. a stack of working orders at adjacent prices reads
    * as one "×3" tag). `true` = defaults, `false`/omitted = off, or pass a
    * {@link ReferenceLineGroupingConfig} to tune the proximity radius. Lines a
-   * {@link LiveChartProps.renderReferenceLine} owns are excluded (their custom tag
-   * draws itself), so the count reflects only collapsed built-in tags. Single-series
-   * only. Default off.
+   * {@link LiveChartProps.renderReferenceLine} or
+   * {@link LiveChartProps.renderOffAxisReferenceLine} owns are excluded (their
+   * custom tag draws itself), so the count reflects only collapsed built-in tags.
+   * Single-series only. Default off.
    */
   referenceLineGrouping?: boolean | ReferenceLineGroupingConfig;
   /**
@@ -2177,6 +2324,39 @@ export interface LiveChartProps extends LiveChartCoreProps {
 export interface LiveChartSeriesProps extends LiveChartCoreProps {
   /** Array of series definitions. Must be a SharedValue for UI-thread reads. */
   series: SharedValue<SeriesConfig[]>;
+  /**
+   * Render a custom overlay floated over the canvas, handed the live
+   * price↔pixel / time↔pixel {@link ChartOverlayContext}. Use its `scale` snapshot
+   * and mapping worklets to position React Native UI against this chart's resolved
+   * plot bounds (including any axis or explicit inset). The tree mounts full-bleed
+   * with `pointerEvents="box-none"`; return `null`/`undefined` for no overlay.
+   */
+  renderOverlay?: (ctx: ChartOverlayContext) => ReactElement | null | undefined;
+  /**
+   * Render a Form-A reference line's tag as a custom **React Native** element
+   * instead of the built-in Skia pill / gutter label. The chart pins the returned
+   * element to the line's live Y position on the UI thread (see
+   * {@link ReferenceLineRenderProps}), including off-axis edge pinning. Return
+   * `null`/`undefined` to keep that line's built-in tag. The line stroke always
+   * remains visible; a left- or right-pinned badge also keeps its dashed connector,
+   * starting after the measured custom tag. `badge.position` / `labelPosition`
+   * controls the custom tag's left, center, or right anchor.
+   */
+  renderReferenceLine?: (
+    ctx: ReferenceLineRenderProps,
+  ) => ReactElement | null | undefined;
+  /**
+   * Render only a Form-A line's **off-axis** tag as a custom React Native element.
+   * The normal in-range Skia tag / gutter label stays visible, while an edge-pinned
+   * custom tag replaces it above or below the plot. A left- or right-pinned
+   * `badge` (or legacy `offAxisBadge`) retains its native dashed connector, measured
+   * against the custom tag. Return `null`/`undefined` to opt a static `line` /
+   * `index` out; use the `edge` SharedValue inside the returned element to animate
+   * its caret. `renderReferenceLine` takes precedence for the same line.
+   */
+  renderOffAxisReferenceLine?: (
+    ctx: ReferenceLineRenderProps,
+  ) => ReactElement | null | undefined;
   /** Called when a series toggle chip is tapped. */
   onSeriesToggle?: (id: string, visible: boolean) => void;
   /**