react-native-livechart 4.8.0 → 4.9.1

package/src/core/liveChartEngineTick.ts

@@ -2,6 +2,10 @@ import type { CandlePoint, LiveChartPoint } from "../types";
 
 import { MOTION_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
+import { thresholdRangeMinMax } from "../math/threshold";
+
+/** Scratch for the threshold range fold — only alive within one tick call. */
+const THRESHOLD_RANGE_SCRATCH: [number, number] = [0, 0];
 
 export interface EngineTickMutable {
   displayValue: number;
@@ -48,6 +52,15 @@ export interface EngineTickInput {
   referenceValue: number | undefined;
   /** Additional reference values (lines + bands) folded into the Y range. */
   referenceValues?: number[];
+  /**
+   * Time-varying threshold series (`threshold.includeInRange`): its min/max over
+   * the visible window is folded into the Y range, like {@link referenceValues}
+   * but windowed each tick.
+   */
+  thresholdRangePoints?: LiveChartPoint[];
+  /** Whether {@link thresholdRangePoints} extends flat past its last point to
+   *  "now" (`threshold.extendToNow`). Default `true`. */
+  thresholdRangeExtendToNow?: boolean;
   /** Clamp the computed lower bound at 0. */
   nonNegative?: boolean;
   /** Hard cap for the computed upper bound. */
@@ -222,7 +235,9 @@ export function tickLiveChartEngineFrame(
       }
     }
     const lc = input.liveCandle;
-    if (lc) {
+    // Fold the in-progress candle in only while its bucket is visible — when
+    // scrolled back past it, the live candle must not stretch the Y range.
+    if (lc && (!scrolledBack || lc.time <= state.timestamp)) {
       /* istanbul ignore next -- trivial min/max */
       if (lc.low < tMin) {
         tMin = lc.low;
@@ -244,6 +259,11 @@ export function tickLiveChartEngineFrame(
       else hi = mid;
     }
     for (let i = lo; i < points.length; i++) {
+      // While scrolled back, stop at the frozen right edge (mirrors the candle
+      // scan) so newer points don't inflate the visible Y range. Following
+      // live, keep the tail inclusive — feed timestamps can run slightly ahead
+      // of the local clock and must not flicker out of the range.
+      if (scrolledBack && points[i].time > state.timestamp) break;
       const v = points[i].value;
       if (v < tMin) {
         tMin = v;
@@ -266,9 +286,15 @@ export function tickLiveChartEngineFrame(
   state.extremaMinTime = hasMin ? minTime : NaN;
   state.extremaMaxTime = hasMax ? maxTime : NaN;
 
-  const cv = state.displayValue;
-  if (cv < tMin) tMin = cv;
-  if (cv > tMax) tMax = cv;
+  // Keep the animated live tip inside the range — but only while it's actually
+  // in the window. Scrolled back, the live value sits beyond the frozen right
+  // edge; folding it in would pin the Y range to the live price and stop the
+  // axis from adapting to the visible history.
+  if (!scrolledBack) {
+    const cv = state.displayValue;
+    if (cv < tMin) tMin = cv;
+    if (cv > tMax) tMax = cv;
+  }
 
   const ref = input.referenceValue;
   if (ref !== undefined) {
@@ -285,6 +311,21 @@ export function tickLiveChartEngineFrame(
     }
   }
 
+  const thrPts = input.thresholdRangePoints;
+  if (thrPts !== undefined && thrPts.length > 0) {
+    const mm = thresholdRangeMinMax(
+      thrPts,
+      state.timestamp,
+      state.displayWindow,
+      input.thresholdRangeExtendToNow ?? true,
+      THRESHOLD_RANGE_SCRATCH,
+    );
+    if (mm !== null) {
+      if (mm[0] < tMin) tMin = mm[0];
+      if (mm[1] > tMax) tMax = mm[1];
+    }
+  }
+
   const isExaggerate = input.exaggerate;
   if (tMin !== Infinity && tMax !== -Infinity) {
     const rawRange = tMax - tMin;

package/src/core/liveChartSeriesEngineTick.ts

@@ -215,6 +215,12 @@ export function tickLiveChartSeriesEngineFrame(
       else hi = mid;
     }
     for (let j = lo; j < points.length; j++) {
+      // While scrolled back, stop at the frozen right edge so newer points
+      // don't inflate the visible Y range (the per-series tips folded below
+      // already track the edge value, so they stay in-range). Following live,
+      // keep the tail inclusive — feed timestamps can run slightly ahead of
+      // the local clock and must not flicker out of the range.
+      if (scrolledBack && points[j].time > state.timestamp) break;
       const v = points[j].value;
       /* istanbul ignore next -- trivial min/max */
       if (v < tMin) tMin = v;

package/src/core/resolveConfig.ts

@@ -14,6 +14,7 @@ import type {
   LineStyleConfig,
   LiveChartMetrics,
   LiveChartMetricsOverride,
+  LiveChartPoint,
   LoadingConfig,
   MarkerClusterConfig,
   DotConfig,
@@ -326,16 +327,31 @@ export interface ResolvedThresholdLineConfig {
   intervals: [number, number];
   strokeWidth: number;
   showValue: boolean;
+  /** undefined → fall back to `color`, then palette.refLabel at render time. */
+  labelColor: string | undefined;
 }
 
 export interface ResolvedThresholdConfig {
-  /** The live split value (Y-axis units). Read on the UI thread each frame. */
-  value: SharedValue<number>;
+  /**
+   * The split value (Y-axis units). A `SharedValue<number>` for a single live
+   * benchmark (read on the UI thread each frame), or a `LiveChartPoint[]` for a
+   * time-varying threshold the split follows point-for-point. `undefined` when
+   * {@link series} carries the threshold instead.
+   */
+  value: SharedValue<number> | LiveChartPoint[] | undefined;
+  /** Live time-varying threshold (`SharedValue<LiveChartPoint[]>`); wins over `value`. */
+  series: SharedValue<LiveChartPoint[]> | null;
   /** undefined → use palette.candleUp (up-green) at render time. */
   aboveColor: string | undefined;
   /** undefined → use palette.candleDown (down-red) at render time. */
   belowColor: string | undefined;
   fill: boolean;
+  /** Band opacity (0–1); {@link THRESHOLD_FILL_OPACITY_DEFAULT} unless tuned. */
+  fillOpacity: number;
+  /** Fold the threshold into the Y-axis range fit. */
+  includeInRange: boolean;
+  /** Series forms: extend flat past the last point to "now". */
+  extendToNow: boolean;
   line: ResolvedThresholdLineConfig | null;
 }
 
@@ -346,8 +362,12 @@ const THRESHOLD_LINE_DEFAULTS: ResolvedThresholdLineConfig = {
   intervals: [4, 4],
   strokeWidth: 1,
   showValue: false,
+  labelColor: undefined,
 };
 
+/** Default threshold band opacity — matches reference-line bands. */
+export const THRESHOLD_FILL_OPACITY_DEFAULT = 0.16;
+
 /**
  * Resolves the `threshold.line` sub-prop to a config or null (no marker line).
  * `true` → dashed defaults, object → merged, falsy/undefined → null.
@@ -360,18 +380,24 @@ export function resolveThresholdLine(
 
 /**
  * Resolves the `threshold` prop to a fully-typed config or null (disabled).
- * Presence-gated (like `referenceLines`/`markers`): the required `value`
- * SharedValue means there is no boolean form — a config object enables it.
+ * Presence-gated (like `referenceLines`/`markers`): a config object with a
+ * `value` or `series` enables it — there is no boolean form.
  */
 export function resolveThreshold(
   prop: ThresholdConfig | undefined,
 ): ResolvedThresholdConfig | null {
-  if (!prop) return null;
+  if (!prop || (prop.value == null && prop.series == null)) return null;
   return {
     value: prop.value,
+    series: prop.series ?? null,
     aboveColor: prop.aboveColor,
     belowColor: prop.belowColor,
-    fill: prop.fill ?? false,
+    fill: !!prop.fill,
+    fillOpacity:
+      (typeof prop.fill === "object" ? prop.fill.opacity : undefined) ??
+      THRESHOLD_FILL_OPACITY_DEFAULT,
+    includeInRange: prop.includeInRange ?? false,
+    extendToNow: prop.extendToNow ?? true,
     line: resolveThresholdLine(prop.line),
   };
 }

package/src/core/useLiveChartEngine.ts

@@ -37,6 +37,17 @@ export interface EngineConfig {
    * `referenceValues`). Read on the UI thread each frame; omit for non-draggable charts.
    */
   liveReferenceValues?: SharedValue<number[]>;
+  /**
+   * Time-varying threshold series folded into the axis-range fit
+   * (`threshold.includeInRange`): each tick contributes the series' min/max over
+   * the visible window — like {@link referenceValues}, but windowed. A
+   * `SharedValue` for the live `threshold.series` form, a plain array for the
+   * `LiveChartPoint[]` form.
+   */
+  thresholdRangePoints?: SharedValue<LiveChartPoint[]> | LiveChartPoint[];
+  /** With {@link thresholdRangePoints}: whether the series extends flat past its
+   *  last point to "now" (`threshold.extendToNow`). Default `true`. */
+  thresholdRangeExtendToNow?: boolean;
   nonNegative?: boolean;
   maxValue?: number;
   nowOverride?: number;
@@ -183,6 +194,9 @@ export interface EngineFrameRefs {
   exaggerateSV: SharedValue<boolean>;
   referenceValue: SharedValue<number | undefined>;
   referenceValues?: SharedValue<number[] | undefined>;
+  /** Series threshold folded into the range fit (`threshold.includeInRange`). */
+  thresholdRangePoints?: SharedValue<LiveChartPoint[] | undefined>;
+  thresholdRangeExtendToNow?: SharedValue<boolean>;
   nonNegativeSV?: SharedValue<boolean>;
   maxValueSV?: SharedValue<number | undefined>;
   nowOverrideSV?: SharedValue<number | undefined>;
@@ -251,6 +265,8 @@ export function applyLiveChartEngineFrame(
     exaggerate: sv.exaggerateSV.value,
     referenceValue: sv.referenceValue.value,
     referenceValues: sv.referenceValues?.value,
+    thresholdRangePoints: sv.thresholdRangePoints?.value,
+    thresholdRangeExtendToNow: sv.thresholdRangeExtendToNow?.value ?? true,
     nonNegative: sv.nonNegativeSV?.value ?? false,
     maxValue: sv.maxValueSV?.value,
     nowOverride: sv.nowOverrideSV?.value,
@@ -325,6 +341,23 @@ export function useLiveChartEngine(
     if (!live || live.length === 0) return base;
     return base && base.length > 0 ? base.concat(live) : live;
   });
+  // Threshold range fold (`threshold.includeInRange`, series forms). Captured
+  // directly (not via `config.`) like `liveReferenceValues`, so the live
+  // `threshold.series` SharedValue is tracked and the tick sees fresh points.
+  const thresholdRangeSourceSV =
+    config.thresholdRangePoints !== undefined &&
+    !Array.isArray(config.thresholdRangePoints)
+      ? config.thresholdRangePoints
+      : null;
+  const thresholdRangePoints = useDerivedValue<LiveChartPoint[] | undefined>(
+    () =>
+      thresholdRangeSourceSV
+        ? thresholdRangeSourceSV.value
+        : (config.thresholdRangePoints as LiveChartPoint[] | undefined),
+  );
+  const thresholdRangeExtendToNow = useDerivedValue(
+    () => config.thresholdRangeExtendToNow ?? true,
+  );
   const nonNegativeSV = useDerivedValue(() => config.nonNegative ?? false);
   const maxValueSV = useDerivedValue(() => config.maxValue);
   const nowOverrideSV = useDerivedValue(() => config.nowOverride);
@@ -412,6 +445,8 @@ export function useLiveChartEngine(
     exaggerateSV,
     referenceValue,
     referenceValues,
+    thresholdRangePoints,
+    thresholdRangeExtendToNow,
     nonNegativeSV,
     maxValueSV,
     nowOverrideSV,

package/src/hooks/useChartPaths.ts

@@ -4,6 +4,7 @@ import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import type { SingleEngineState } from "../core/useLiveChartEngine";
 import { buildLinePoints, type ChartPadding } from "../draw/line";
 import { drawSpline, makeSplineScratch } from "../math/spline";
+import { sampleThresholdYAt, thresholdSampleSpanX } from "../math/threshold";
 import { blendPtsY, squigglifyPts } from "../math/squiggly";
 import { usePathBuilder } from "./usePathBuilder";
 
@@ -39,6 +40,11 @@ export function useChartPaths(
   squiggleAmplitude = 14,
   /** Loading squiggle wave speed multiplier for the reveal morph. Default 1. */
   squiggleSpeed = 1,
+  /** When set, build `thresholdFillPath` as the band between the line and this
+   *  *time-varying* threshold — the split shader's evenly-spaced pixel-Y
+   *  `samples[]` (so band geometry matches the shader exactly). Takes precedence
+   *  over `thresholdY`, the constant (horizontal) case. */
+  thresholdSamples?: SharedValue<number[]>,
 ) {
   const lineBuilder = usePathBuilder();
   const fillBuilder = usePathBuilder();
@@ -134,17 +140,55 @@ export function useChartPaths(
     return b.detach();
   });
 
-  // Threshold-anchored fill: the same spline, closed at `thresholdY` instead of the
-  // baseline, so the band lies between the line and the threshold (the profit/loss
-  // area). Painted with the hard-split vertical gradient, the part above the split
-  // shows the above-color and the part below shows the below-color.
+  // Threshold-anchored fill: the same spline, closed along the threshold instead
+  // of the baseline, so the band lies between the line and the threshold (the
+  // profit/loss area). Painted with the split gradient/shader, the part above the
+  // split shows the above-color and the part below shows the below-color.
+  //
+  // `thresholdPts` (a time-varying series) closes the band along that polyline,
+  // right-to-left; otherwise `thresholdY` closes it at a single horizontal Y.
   const thresholdFillPath = useDerivedValue(() => {
     const cache = cacheRef.current!;
-    if (!thresholdY) return cache.emptyPath;
-    const yT = thresholdY.get();
     const pts = flatPts.get();
     const n = pts.length >> 1;
-    if (n < 2 || !Number.isFinite(yT)) return cache.emptyPath;
+    if (n < 2) return cache.emptyPath;
+
+    const tsamples = thresholdSamples?.get();
+    if (tsamples && tsamples.length >= 2) {
+      const b = thresholdFillBuilder.value;
+      b.moveTo(pts[0], pts[1]);
+      drawSpline(b, pts, cache.scratch, linear);
+      // Band bottom = the SAMPLED threshold (identical to what the split shader
+      // reads), pinned to the LINE's x-range. Because the geometry and the shader
+      // use the same evenly-spaced, linearly-interpolated samples, a step riser
+      // ramps the same way in both — no green/red sliver bleeds through — and the
+      // x-range pin keeps the band closing with clean vertical sides (no wedge).
+      const leftX = pts[0];
+      const rightX = pts[(n - 1) * 2];
+      const count = tsamples.length;
+      // The samples live on the time-anchored, gliding grid — interpolate them
+      // across that span (same as the shader), not the static plot edges.
+      const [x0, x1] = thresholdSampleSpanX(
+        engine.timestamp.get(),
+        engine.displayWindow.get(),
+        padding.left,
+        engine.canvasWidth.get() - padding.right,
+        count,
+      );
+      const step = (x1 - x0) / (count - 1);
+      b.lineTo(rightX, sampleThresholdYAt(tsamples, x0, x1, rightX));
+      for (let i = count - 1; i >= 0; i--) {
+        const sx = x0 + step * i;
+        if (sx > leftX && sx < rightX) b.lineTo(sx, tsamples[i]);
+      }
+      b.lineTo(leftX, sampleThresholdYAt(tsamples, x0, x1, leftX));
+      b.close();
+      return b.detach();
+    }
+
+    if (!thresholdY) return cache.emptyPath;
+    const yT = thresholdY.get();
+    if (!Number.isFinite(yT)) return cache.emptyPath;
     const b = thresholdFillBuilder.value;
     b.moveTo(pts[0], pts[1]);
     drawSpline(b, pts, cache.scratch, linear);

package/src/hooks/useChartSkiaFont.ts

@@ -3,14 +3,41 @@ import {
   Skia,
   useFont,
   type SkFont,
+  type SkFontMgr,
 } from "@shopify/react-native-skia";
 
 import { resolveFontConfig } from "../core/resolveConfig";
 import type { FontConfig } from "../types";
 
+/**
+ * System-font match cache. `matchFont` walks the platform font manager to
+ * resolve a typeface — a few ms per call — and every chart resolves several
+ * fonts per render, so a screen full of sparklines would otherwise re-match
+ * the same `{family, size, weight}` dozens of times. `SkFont` instances are
+ * immutable and safe to share across canvases. Custom `fontManager`s bypass
+ * the cache (their identity isn't part of the key).
+ */
+const systemFontCache = new Map<string, SkFont>();
+let systemFontMgr: SkFontMgr | null = null;
+
+function matchSystemFont(
+  fontFamily: string,
+  fontSize: number,
+  fontWeight: NonNullable<FontConfig["fontWeight"]>,
+): SkFont {
+  const key = `${fontFamily}|${fontSize}|${fontWeight}`;
+  const cached = systemFontCache.get(key);
+  if (cached) return cached;
+  systemFontMgr ??= Skia.FontMgr.System();
+  const font = matchFont({ fontFamily, fontSize, fontWeight }, systemFontMgr);
+  systemFontCache.set(key, font);
+  return font;
+}
+
 /**
  * Resolves Skia text for charts: optional bundled `typeface` via `useFont`, otherwise
- * `matchFont` with optional custom `fontManager`.
+ * `matchFont` with optional custom `fontManager`. System-font matches are cached
+ * module-wide, so many charts sharing a family/size/weight resolve it once.
  */
 export function useChartSkiaFont(
   fontProp: FontConfig | undefined,
@@ -22,10 +49,9 @@ export function useChartSkiaFont(
   const typefaceSource = fontProp?.typeface ?? null;
   const customFont = useFont(typefaceSource, fontSize);
 
-  const fallbackFont = matchFont(
-    { fontFamily, fontSize, fontWeight },
-    fontProp?.fontManager ?? Skia.FontMgr.System(),
-  );
+  const fallbackFont = fontProp?.fontManager
+    ? matchFont({ fontFamily, fontSize, fontWeight }, fontProp.fontManager)
+    : matchSystemFont(fontFamily, fontSize, fontWeight);
 
   if (typefaceSource != null) {
     return customFont ?? fallbackFont;