react-native-livechart 4.21.0 → 4.22.0

package/src/hooks/useThreshold.ts

@@ -22,6 +22,8 @@ export type ThresholdValue = SharedValue<number> | LiveChartPoint[];
 
 /** `clipRight` sentinel when the threshold extends to "now" (no forward cutoff). */
 export const THRESHOLD_NO_CLIP = 1e9;
+/** `clipLeft` sentinel when the threshold extends to the window start. */
+export const THRESHOLD_NO_CLIP_LEFT = -1e9;
 
 export interface ThresholdGeometry {
   /** Threshold pixel-Y within the canvas, or NaN before layout / degenerate range. */
@@ -104,6 +106,9 @@ export interface ThresholdSeriesGeometry {
    *  part of the threshold. (`visible` can still be true when that one endpoint
    *  is off-plot.) */
   badgeVisible: SharedValue<boolean>;
+  /** Pixel-X where the threshold starts: the first point's X with
+   *  `extendToStart` off, else {@link THRESHOLD_NO_CLIP_LEFT}. */
+  clipLeftX: SharedValue<number>;
   /** Pixel-X where the threshold ends: the last point's X with `extendToNow`
    *  off, else {@link THRESHOLD_NO_CLIP}. The shader paints its plain
    *  `restColor` right of it; the marker polyline stops there. */
@@ -119,7 +124,7 @@ const EMPTY_SAMPLES: number[] = new Array(THRESHOLD_SAMPLE_COUNT).fill(0);
  * `LiveChartPoint[]` `value` or a live `SharedValue<LiveChartPoint[]>` `series`
  * (which wins when both are given): the screen polyline (marker line +
  * fill-band bottom), the shader's pixel-Y `samples[]`, the configured endpoint
- * value/anchor for the badge, and the `extendToNow` cutoff X. The array buffers
+ * value/anchor for the badge, and the endpoint cutoff X values. The array buffers
  * ping-pong (Reanimated only re-notifies subscribers when the returned reference
  * changes). When the threshold is a constant `SharedValue<number>` every
  * worklet short-circuits cheaply and {@link useThreshold} drives the render
@@ -131,6 +136,7 @@ export function useThresholdSeries(
   value: ThresholdValue,
   series: SharedValue<LiveChartPoint[]> | null = null,
   extendToNow = true,
+  extendToStart = true,
   labelAnchor: "first" | "last" = "last",
 ): ThresholdSeriesGeometry {
   const cacheRef = useRef<{
@@ -176,6 +182,19 @@ export function useThresholdSeries(
     );
   });
 
+  const clipLeftX = useDerivedValue(() => {
+    if (extendToStart) return THRESHOLD_NO_CLIP_LEFT;
+    const pts = series ? series.get() : Array.isArray(value) ? value : null;
+    if (pts === null || pts.length === 0) return THRESHOLD_NO_CLIP_LEFT;
+    const win = engine.displayWindow.get();
+    const plotLeft = padding.left;
+    const plotRight = engine.canvasWidth.get() - padding.right;
+    if (!(win > 0) || plotRight <= plotLeft) return THRESHOLD_NO_CLIP_LEFT;
+    const winStart = engine.timestamp.get() - win;
+    const firstT = pts[0].time;
+    return plotLeft + ((firstT - winStart) / win) * (plotRight - plotLeft);
+  });
+
   const clipRightX = useDerivedValue(() => {
     if (extendToNow) return THRESHOLD_NO_CLIP;
     const pts = series ? series.get() : Array.isArray(value) ? value : null;
@@ -206,8 +225,9 @@ export function useThresholdSeries(
     if (n < 2) return EMPTY_PTS;
     const plotLeft = padding.left;
     const plotRight = engine.canvasWidth.get() - padding.right;
+    const startX = Math.max(plotLeft, clipLeftX.get());
     const endX = Math.min(plotRight, clipRightX.get());
-    if (endX <= plotLeft) return EMPTY_PTS;
+    if (endX <= startX) return EMPTY_PTS;
     const cache = cacheRef.current!;
     cache.ptsTick = !cache.ptsTick;
     const buf = cache.ptsTick ? cache.ptsA : cache.ptsB;
@@ -219,11 +239,11 @@ export function useThresholdSeries(
       plotRight,
       n,
     );
-    buf.push(plotLeft, sampleThresholdYAt(s, x0, x1, plotLeft));
+    buf.push(startX, sampleThresholdYAt(s, x0, x1, startX));
     const step = (x1 - x0) / (n - 1);
     for (let i = 0; i < n; i++) {
       const sx = x0 + step * i;
-      if (sx > plotLeft && sx < endX) buf.push(sx, s[i]);
+      if (sx > startX && sx < endX) buf.push(sx, s[i]);
     }
     buf.push(endX, sampleThresholdYAt(s, x0, x1, endX));
     return buf;
@@ -242,10 +262,13 @@ export function useThresholdSeries(
   const badgeValue = useDerivedValue(() => {
     const pts = series ? series.get() : Array.isArray(value) ? value : null;
     if (pts === null) return NaN;
-    const time =
-      labelAnchor === "first"
-        ? engine.timestamp.get() - engine.displayWindow.get()
-        : engine.timestamp.get();
+    let time = engine.timestamp.get();
+    if (labelAnchor === "first") {
+      time -= engine.displayWindow.get();
+      if (!extendToStart && pts.length > 0 && pts[0].time > time) {
+        time = pts[0].time;
+      }
+    }
     return interpolateAtTime(pts, time) ?? NaN;
   });
 
@@ -261,11 +284,11 @@ export function useThresholdSeries(
   );
 
   const badgeVisible = useDerivedValue(() => {
-    if (labelAnchor === "first") {
-      // If the non-extended series ended before this window, there is no left
-      // endpoint to label even though interpolation can still clamp a value.
-      if (screenPts.get().length < 4) return false;
-    } else if (!extendToNow) {
+    // There is no endpoint to label when the series does not intersect the
+    // effective [first point, last point] window, even though interpolation can
+    // still clamp a value outside it.
+    if (screenPts.get().length < 4) return false;
+    if (labelAnchor === "last" && !extendToNow) {
       // The threshold ends at its last point — no badge past it.
       const pts = series ? series.get() : Array.isArray(value) ? value : null;
       if (pts === null || pts.length === 0) return false;
@@ -286,6 +309,7 @@ export function useThresholdSeries(
     badgeValue,
     badgeLineY,
     badgeVisible,
+    clipLeftX,
     clipRightX,
   };
 }
@@ -295,8 +319,8 @@ export function useThresholdSeries(
  * uniforms (one `SharedValue` per paint — stroke vs. the alpha-reduced fill band).
  * The object is rebuilt each frame so the shader re-paints as `samples` advance;
  * `sampleLeft`/`sampleRight` are the gliding pixel-X span of the sample grid and
- * `clipRight`/`restColor` implement the `extendToNow: false` cutoff (plain line
- * color for the stroke, transparent for the band).
+ * `clipLeft`/`clipRight`/`restColor` implement the series endpoint cutoffs
+ * (plain line color for the stroke, transparent for the band).
  */
 export function useThresholdSplitUniforms(
   samples: SharedValue<number[]>,
@@ -305,6 +329,7 @@ export function useThresholdSplitUniforms(
   aboveColor: number[],
   belowColor: number[],
   restColor: number[],
+  clipLeftX: SharedValue<number>,
   clipRightX: SharedValue<number>,
 ): SharedValue<Uniforms> {
   return useDerivedValue<Uniforms>(() => {
@@ -319,6 +344,7 @@ export function useThresholdSplitUniforms(
     return {
       sampleLeft: x0,
       sampleRight: x1,
+      clipLeft: clipLeftX.get(),
       clipRight: clipRightX.get(),
       aboveColor,
       belowColor,

package/src/math/referenceLineSeries.ts

@@ -20,6 +20,7 @@ export function buildReferenceLineSeriesPoints(
   canvasWidth: number,
   canvasHeight: number,
   padding: ChartPadding,
+  extendToStart: boolean,
   extendToNow: boolean,
   out?: number[],
 ): number[] {
@@ -43,11 +44,15 @@ export function buildReferenceLineSeriesPoints(
   }
 
   const windowStart = now - windowSecs;
+  const firstTime = points[0].time;
   const lastTime = points[points.length - 1].time;
+  const startTime = extendToStart
+    ? windowStart
+    : Math.max(windowStart, firstTime);
   const endTime = extendToNow ? now : Math.min(now, lastTime);
-  if (endTime < windowStart) return result;
+  if (endTime < startTime) return result;
 
-  const startValue = interpolateAtTime(points, windowStart);
+  const startValue = interpolateAtTime(points, startTime);
   const endValue = interpolateAtTime(points, endTime);
   if (
     startValue === null ||
@@ -70,10 +75,10 @@ export function buildReferenceLineSeriesPoints(
       padding.bottom,
     );
 
-  result.push(plotLeft, toY(startValue));
+  result.push(toX(startTime), toY(startValue));
   for (let i = 0; i < points.length; i++) {
     const point = points[i];
-    if (point.time <= windowStart) continue;
+    if (point.time <= startTime) continue;
     if (point.time >= endTime) break;
     if (!Number.isFinite(point.time) || !Number.isFinite(point.value)) continue;
     result.push(toX(point.time), toY(point.value));

package/src/math/threshold.ts

@@ -237,8 +237,9 @@ export function thresholdDashPhase(
  * Min/max of a threshold series over the visible window `[now - windowSecs,
  * now]` — the values folded into the engine's Y-range fit when
  * `threshold.includeInRange` is set (like reference-line values). Uses the
- * clamped window-edge values plus every interior point; with `extendToNow` off,
- * the window end clamps to the series' last point (nothing projects forward).
+ * clamped window-edge values plus every interior point. With `extendToStart`
+ * off, the window start clamps to the series' first point; with `extendToNow`
+ * off, the window end clamps to its last point.
  * Writes `[min, max]` into `out` and returns it, or returns null when the
  * series is empty / entirely outside the effective window / non-finite.
  */
@@ -246,18 +247,24 @@ export function thresholdRangeMinMax(
   points: LiveChartPoint[],
   now: number,
   windowSecs: number,
+  extendToStart: boolean,
   extendToNow: boolean,
   out: [number, number],
 ): [number, number] | null {
   "worklet";
   if (points.length === 0 || !(windowSecs > 0)) return null;
-  const tStart = now - windowSecs;
+  let tStart = now - windowSecs;
   let tEnd = now;
+  if (!extendToStart) {
+    const firstT = points[0].time;
+    if (firstT > tStart) tStart = firstT;
+  }
   if (!extendToNow) {
     const lastT = points[points.length - 1].time;
     if (lastT < tStart) return null;
     if (lastT < tEnd) tEnd = lastT;
   }
+  if (tEnd < tStart) return null;
   let mn = interpolateAtTime(points, tStart)!;
   let mx = mn;
   const vEnd = interpolateAtTime(points, tEnd)!;

package/src/types.ts

@@ -74,10 +74,16 @@ export interface ReferenceLine {
   /**
    * Form B — a time-varying reference line. Points use unix-second timestamps
    * and should be sorted oldest to newest. The first value extends to the left
-   * edge; the last value extends to the live edge unless {@link extendToNow} is
-   * `false`. Supported by line and candle charts.
+   * edge unless {@link extendToStart} is `false`; the last value extends to the
+   * live edge unless {@link extendToNow} is `false`. Supported by line and
+   * candle charts.
    */
   series?: LiveChartPoint[];
+  /**
+   * Form B — extend the series' first value flat to the chart's left edge.
+   * Set `false` to start at the first point. Default `true`.
+   */
+  extendToStart?: boolean;
   /**
    * Form B — extend the series' last value flat to the chart's live edge.
    * Set `false` to stop at the last point. Default `true`.
@@ -493,8 +499,8 @@ export interface ThresholdConfig {
    * - **`LiveChartPoint[]`** — a *time-varying* threshold (e.g. a historical
    *   break-even that steps up as you average in). The stroke split, fill band
    *   and marker line follow the series point-for-point. The series clamps to its
-   *   first/last value outside its own time range, so a threshold whose last
-   *   point sits behind the live edge extends as a flat line to "now" (see
+   *   first/last value outside its own time range, so it extends flat to the
+   *   visible edges by default (see {@link extendToStart} and
    *   {@link extendToNow}). Flows in on re-render — pass a stable (memoized)
    *   array and reserve it for thresholds that change occasionally; for a
    *   threshold series that updates live, use {@link series} instead.
@@ -531,10 +537,19 @@ export interface ThresholdConfig {
    * Fold the threshold into the Y-axis range fit — like reference lines — so a
    * benchmark outside the data's own range stays on-plot instead of rendering
    * invisibly (marker off-plot, whole line one color). For a series, the values
-   * visible in the current window count (respecting {@link extendToNow}).
+   * visible in the current window count (respecting {@link extendToStart} and
+   * {@link extendToNow}).
    * Default `false` (range fits the data only).
    */
   includeInRange?: boolean;
+  /**
+   * Series forms only: extend the threshold **flat before its first point to the
+   * visible window's left edge**, carrying the first known benchmark backward.
+   * Set `false` when the benchmark did not exist yet (for example, a break-even
+   * before the first trade) — left of the first point the stroke keeps its plain
+   * line color and the band / marker do not begin. Default `true`.
+   */
+  extendToStart?: boolean;
   /**
    * Series forms only: extend the threshold **flat past its last point to
    * "now"**, carrying the last known benchmark forward. Set `false` for a
@@ -2261,7 +2276,7 @@ export interface LiveChartCoreProps {
   transitions?: boolean | TransitionConfig;
   /**
    * Breathing-line loading shell. When this becomes `false`, the chart reveals
-   * only if there is data (≥2 line points or ≥2 committed candles).
+   * only if there is data (≥1 line point or ≥1 committed candle).
    *
    * `true` shows the shell with the defaults; pass a {@link LoadingConfig} to
    * restyle it — `color` / `strokeWidth` for the squiggle + skeleton, `amplitude`
@@ -2330,8 +2345,8 @@ export interface LiveChartCoreProps {
    */
   yRangeScale?: SharedValue<number>;
   /**
-   * Label in the empty state when `loading` is false and there are fewer than
-   * two samples (line points or committed candles). Default `"No data"`.
+   * Label in the empty state when `loading` is false and there are no line
+   * points or committed candles. Default `"No data"`.
    */
   emptyText?: string;
   /** Custom formatter for value labels (axes, badge, tooltips). Default `v => v.toFixed(2)`. */