react-native-livechart 4.8.0 → 4.9.0

package/src/components/ThresholdLineOverlay.tsx

@@ -12,6 +12,7 @@ import type { ResolvedThresholdLineConfig } from "../core/resolveConfig";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import { usePathBuilder } from "../hooks/usePathBuilder";
+import { thresholdDashPhase } from "../math/threshold";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
 import type { LiveChartPalette } from "../types";
 
@@ -32,6 +33,9 @@ interface ThresholdMarkerProps {
   palette: LiveChartPalette;
   font: SkFont;
   formatValue: (v: number) => string;
+  /** When set, draw the marker as this time-varying threshold polyline (`[x, y, …]`)
+   *  instead of a horizontal line at `lineY`. */
+  seriesPts?: SharedValue<number[]>;
 }
 
 /**
@@ -47,18 +51,44 @@ export function ThresholdLineOverlay({
   visible,
   cfg,
   palette,
+  seriesPts,
 }: ThresholdMarkerProps) {
   const lineColor = cfg.color ?? palette.refLine;
   const { strokeWidth, intervals } = cfg;
+  const isSeries = seriesPts !== undefined;
+  const dashCycle = intervals[0] + intervals[1];
+
+  // Series marker: advance the dash phase with the content scroll so the
+  // pattern rides the staircase instead of sitting screen-fixed under it (the
+  // path start is pinned at the plot edge, so a static phase reads as the dots
+  // marching right along the gliding line). The constant marker is a static
+  // level — its dashes stay screen-fixed (phase 0).
+  const dashPhase = useDerivedValue(() => {
+    if (!isSeries) return 0;
+    return thresholdDashPhase(
+      engine.timestamp.get(),
+      engine.displayWindow.get(),
+      padding.left,
+      engine.canvasWidth.get() - padding.right,
+      dashCycle,
+    );
+  });
 
   const builder = usePathBuilder();
 
   const linePath = useDerivedValue(() => {
     const b = builder.value;
     if (visible.get()) {
-      const y = lineY.get();
-      b.moveTo(padding.left, y);
-      b.lineTo(engine.canvasWidth.get() - padding.right, y);
+      const sp = seriesPts?.get();
+      if (sp && sp.length >= 4) {
+        // Time-varying threshold: trace the polyline across the plot.
+        b.moveTo(sp[0], sp[1]);
+        for (let i = 2; i < sp.length; i += 2) b.lineTo(sp[i], sp[i + 1]);
+      } else {
+        const y = lineY.get();
+        b.moveTo(padding.left, y);
+        b.lineTo(engine.canvasWidth.get() - padding.right, y);
+      }
     }
     return b.detach();
   });
@@ -73,7 +103,7 @@ export function ThresholdLineOverlay({
         strokeWidth={strokeWidth}
         color={lineColor}
       >
-        <DashPathEffect intervals={intervals} />
+        <DashPathEffect intervals={intervals} phase={dashPhase} />
       </Path>
     </Group>
   );
@@ -100,7 +130,7 @@ export function ThresholdBadgeOverlay({
   const { label, labelPosition, showValue } = cfg;
   const badgeBackground = palette.tooltipBg;
   const badgeBorderColor = cfg.color ?? palette.refLine;
-  const labelColor = cfg.color ?? palette.refLabel;
+  const labelColor = cfg.labelColor ?? cfg.color ?? palette.refLabel;
 
   // Font metrics are stable → read once (getMetrics allocates + crosses JSI).
   const { fontAscent, baselineOffset, pillH } = (() => {

package/src/components/ThresholdSplitShader.tsx

@@ -0,0 +1,92 @@
+import { Shader, Skia, type Uniforms } from "@shopify/react-native-skia";
+import type { SharedValue } from "react-native-reanimated";
+
+import { THRESHOLD_SAMPLE_COUNT } from "../math/threshold";
+
+/**
+ * Per-fragment split shader for a *time-varying* threshold. For each fragment it
+ * reads the threshold's Y at the fragment's X — linearly interpolated from
+ * `samples[]`, evenly spaced across `[plotLeft, plotRight]` — and paints
+ * `aboveColor` above the boundary (smaller Y), `belowColor` below. This is the
+ * polyline equivalent of the constant case's vertical hard-stop `LinearGradient`,
+ * which can only express a *horizontal* split.
+ *
+ * Used for both the line stroke and the profit/loss fill band (the band passes
+ * alpha-reduced colors). Output is premultiplied — Skia's shader convention, as in
+ * `AreaDotsOverlay`. One GPU draw, no per-frame clip / `saveLayer`.
+ */
+const SPLIT_SKSL = `
+// Pixel-X span of the sample grid (thresholdSampleSpanX) — overhangs the plot
+// and glides with the window so features move fluidly, frame to frame.
+uniform float sampleLeft;
+uniform float sampleRight;
+// X where the threshold ends (extendToNow: false → the last point's pixel-X,
+// else a huge sentinel). Fragments right of it paint restColor: the plain line
+// color for the stroke, transparent for the band.
+uniform float clipRight;
+uniform vec4 aboveColor; // straight-alpha rgba, 0..1
+uniform vec4 belowColor; // straight-alpha rgba, 0..1
+uniform vec4 restColor;  // straight-alpha rgba, 0..1
+uniform float samples[${THRESHOLD_SAMPLE_COUNT}];
+
+half4 main(vec2 xy) {
+  if (xy.x > clipRight) {
+    return half4(half3(restColor.rgb) * restColor.a, restColor.a);
+  }
+  float span = sampleRight - sampleLeft;
+  float u = span > 0.0 ? (xy.x - sampleLeft) / span : 0.0;
+  u = clamp(u, 0.0, 1.0) * float(${THRESHOLD_SAMPLE_COUNT - 1});
+  // SkSL forbids indexing a uniform array with a non-constant index, so walk the
+  // segments in an unrolled, constant-bound loop — the index is the loop variable
+  // (a compile-time constant per unrolled iteration) — and keep the last segment
+  // whose left edge is at or before the fragment's u.
+  float thrY = samples[0];
+  for (int j = 0; j < ${THRESHOLD_SAMPLE_COUNT - 1}; j++) {
+    if (u >= float(j)) {
+      thrY = mix(samples[j], samples[j + 1], clamp(u - float(j), 0.0, 1.0));
+    }
+  }
+  // 1 above the boundary, 0 below, with ~1px antialiasing across it.
+  float above = clamp(thrY - xy.y + 0.5, 0.0, 1.0);
+  vec4 c = mix(belowColor, aboveColor, above);
+  return half4(half3(c.rgb) * c.a, c.a);
+}`;
+
+// Compiled once. `RuntimeEffect.Make` THROWS on a compile error, so guard it —
+// a shader failure must degrade to "no split" (the line keeps its plain color),
+// never crash every chart screen at import. Null → the component no-ops.
+let SPLIT_EFFECT: ReturnType<typeof Skia.RuntimeEffect.Make> = null;
+try {
+  SPLIT_EFFECT = Skia.RuntimeEffect.Make(SPLIT_SKSL);
+} catch {
+  SPLIT_EFFECT = null;
+}
+
+/**
+ * Whether the split effect compiled. Callers must gate any `<Path>` whose ONLY
+ * paint is this shader on it — without the shader child the path fills with the
+ * default paint (opaque black). A fallback `color` prop can't stand in instead:
+ * Skia multiplies the shader output by the paint alpha, so a transparent color
+ * erases the shader's own output too.
+ */
+export const THRESHOLD_SPLIT_AVAILABLE = SPLIT_EFFECT !== null;
+
+interface ThresholdSplitShaderProps {
+  /**
+   * Per-frame uniforms (built in `useThresholdSplitUniforms`): `sampleLeft` /
+   * `sampleRight` (the gliding sample-grid span, px), `aboveColor` / `belowColor`
+   * (straight-alpha `[r, g, b, a]` vec4s, channels 0..1) and `samples`
+   * (`THRESHOLD_SAMPLE_COUNT` threshold pixel-Y values on the grid).
+   */
+  uniforms: SharedValue<Uniforms>;
+}
+
+/**
+ * The split `RuntimeShader` as a paint child — drop it inside a stroked line
+ * `<Path>` or a filled band `<Path>`, like a `<LinearGradient>`.
+ */
+export function ThresholdSplitShader({ uniforms }: ThresholdSplitShaderProps) {
+  /* istanbul ignore next -- defensive: SPLIT_SKSL is static and compiles */
+  if (!SPLIT_EFFECT) return null;
+  return <Shader source={SPLIT_EFFECT} uniforms={uniforms} />;
+}

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. */
@@ -285,6 +298,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/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);