react-native-livechart 4.20.0 → 4.21.1

package/src/math/candleGaps.ts

@@ -0,0 +1,120 @@
+import type { CandleGap, CandleGapKind, CandlePoint } from "../types";
+
+/** Built-in, overridable copy for gap bands and scrub tooltips. */
+export function candleGapDefaultLabel(kind: CandleGapKind): string {
+  "worklet";
+  if (kind === "no-trades") return "No trades";
+  if (kind === "unavailable") return "Trading unavailable";
+  return "Data unavailable";
+}
+
+/** Find the explicit half-open gap containing `time`. Input must be start-sorted. */
+export function pickCandleGapAtTime(
+  gaps: CandleGap[],
+  time: number,
+): CandleGap | null {
+  "worklet";
+  let lo = 0;
+  let hi = gaps.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (gaps[mid].from <= time) lo = mid + 1;
+    else hi = mid - 1;
+  }
+  if (hi < 0) return null;
+  const gap = gaps[hi];
+  return time >= gap.from && time < gap.to ? gap : null;
+}
+
+/** Latest real candle strictly before `time`, preferring a newer live candle. */
+export function previousCandleAtTime(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  time: number,
+): CandlePoint | null {
+  "worklet";
+  let lo = 0;
+  let hi = candles.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (candles[mid].time < time) lo = mid + 1;
+    else hi = mid;
+  }
+  let result = lo > 0 ? candles[lo - 1] : null;
+  if (
+    liveCandle &&
+    liveCandle.time < time &&
+    (!result || liveCandle.time > result.time)
+  ) {
+    result = liveCandle;
+  }
+  return result;
+}
+
+/** Previous observed close for a bridged gap; `null` when no anchor exists. */
+export function previousCandleCloseAtTime(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  time: number,
+): number | null {
+  "worklet";
+  return previousCandleAtTime(candles, liveCandle, time)?.close ?? null;
+}
+
+/** Whether a real candle starts in the bucket beginning at `bucketTime`. */
+export function candleAtBucketTime(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  bucketTime: number,
+  candleWidthSecs: number,
+): CandlePoint | null {
+  "worklet";
+  let lo = 0;
+  let hi = candles.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const t = candles[mid].time;
+    if (t < bucketTime) lo = mid + 1;
+    else if (t > bucketTime) hi = mid - 1;
+    else return candles[mid];
+  }
+  if (
+    liveCandle &&
+    Math.abs(liveCandle.time - bucketTime) < candleWidthSecs * 1e-6
+  ) {
+    return liveCandle;
+  }
+  return null;
+}
+
+/**
+ * Bucket start under `time`, aligned to the nearest preceding real candle.
+ * Returns `null` for a partial edge bucket, a bucket with real OHLC, or a gap
+ * without a previous-close anchor.
+ */
+export function candleGapBucketStartAtTime(
+  gap: CandleGap,
+  time: number,
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  candleWidthSecs: number,
+): number | null {
+  "worklet";
+  if (
+    candleWidthSecs <= 0 ||
+    time < gap.from ||
+    time >= gap.to ||
+    gap.kind !== "no-trades"
+  ) {
+    return null;
+  }
+  const previous = previousCandleAtTime(candles, liveCandle, time);
+  if (!previous) return null;
+  const steps = Math.floor((time - previous.time) / candleWidthSecs);
+  const bucket = previous.time + steps * candleWidthSecs;
+  if (bucket < gap.from || bucket + candleWidthSecs > gap.to) return null;
+  if (candleAtBucketTime(candles, liveCandle, bucket, candleWidthSecs)) {
+    return null;
+  }
+  return bucket;
+}

package/src/math/referenceLineSeries.ts

@@ -0,0 +1,83 @@
+import type { ChartPadding } from "../draw/line";
+import type { LiveChartPoint } from "../types";
+import { interpolateAtTime } from "./interpolate";
+import { thresholdLineY } from "./threshold";
+
+/**
+ * Project a historical reference-line series into screen-space `[x, y, …]`
+ * points for the visible time window. Window-edge values are interpolated so
+ * the path enters and leaves the plot cleanly. The series clamps to its first
+ * value on the left and, by default, to its last value at the live edge.
+ *
+ * Worklet-safe. When `out` is supplied it is cleared and reused.
+ */
+export function buildReferenceLineSeriesPoints(
+  points: LiveChartPoint[],
+  now: number,
+  windowSecs: number,
+  displayMin: number,
+  displayMax: number,
+  canvasWidth: number,
+  canvasHeight: number,
+  padding: ChartPadding,
+  extendToNow: boolean,
+  out?: number[],
+): number[] {
+  "worklet";
+  const result = out ?? [];
+  result.length = 0;
+
+  const plotLeft = padding.left;
+  const plotRight = canvasWidth - padding.right;
+  const plotWidth = plotRight - plotLeft;
+  const plotHeight = canvasHeight - padding.top - padding.bottom;
+  const valueRange = displayMax - displayMin;
+  if (
+    points.length === 0 ||
+    !(windowSecs > 0) ||
+    plotWidth <= 0 ||
+    plotHeight <= 0 ||
+    !(valueRange > 0)
+  ) {
+    return result;
+  }
+
+  const windowStart = now - windowSecs;
+  const lastTime = points[points.length - 1].time;
+  const endTime = extendToNow ? now : Math.min(now, lastTime);
+  if (endTime < windowStart) return result;
+
+  const startValue = interpolateAtTime(points, windowStart);
+  const endValue = interpolateAtTime(points, endTime);
+  if (
+    startValue === null ||
+    endValue === null ||
+    !Number.isFinite(startValue) ||
+    !Number.isFinite(endValue)
+  ) {
+    return result;
+  }
+
+  const toX = (time: number) =>
+    plotLeft + ((time - windowStart) / windowSecs) * plotWidth;
+  const toY = (value: number) =>
+    thresholdLineY(
+      value,
+      displayMin,
+      displayMax,
+      canvasHeight,
+      padding.top,
+      padding.bottom,
+    );
+
+  result.push(plotLeft, toY(startValue));
+  for (let i = 0; i < points.length; i++) {
+    const point = points[i];
+    if (point.time <= windowStart) continue;
+    if (point.time >= endTime) break;
+    if (!Number.isFinite(point.time) || !Number.isFinite(point.value)) continue;
+    result.push(toX(point.time), toY(point.value));
+  }
+  result.push(toX(endTime), toY(endValue));
+  return result;
+}

package/src/math/referenceLines.ts

@@ -4,16 +4,22 @@ import type {
   ReferenceLineBadgeConfig,
 } from "../types";
 
-/** Which of the three reference-line forms a `ReferenceLine` resolves to. */
-export type ReferenceLineForm = "line" | "value-band" | "time-band" | "none";
+/** Which of the four reference-line forms a `ReferenceLine` resolves to. */
+export type ReferenceLineForm =
+  | "line"
+  | "series"
+  | "value-band"
+  | "time-band"
+  | "none";
 
 /**
- * Classify a `ReferenceLine` into one of its three forms, applying the
- * documented precedence A (line) > B (value band) > C (time band).
+ * Classify a `ReferenceLine` into one of its four forms, applying the
+ * documented precedence A (line) > B (series) > C (value band) > D (time band).
  */
 export function referenceLineForm(rl: ReferenceLine): ReferenceLineForm {
   "worklet";
   if (rl.value !== undefined) return "line";
+  if (rl.series !== undefined) return "series";
   if (rl.valueFrom !== undefined && rl.valueTo !== undefined) {
     return "value-band";
   }
@@ -24,7 +30,7 @@ export function referenceLineForm(rl: ReferenceLine): ReferenceLineForm {
 /**
  * Gather every Y value a set of reference lines should contribute to the
  * axis-range computation. Lines flagged `excludeFromRange` are skipped, as are
- * time bands (Form C) which constrain time, not value.
+ * time bands (Form D) which constrain time, not value.
  */
 export function collectReferenceValues(lines: ReferenceLine[]): number[] {
   const out: number[] = [];
@@ -35,6 +41,22 @@ export function collectReferenceValues(lines: ReferenceLine[]): number[] {
       case "line":
         out.push(rl.value as number);
         break;
+      case "series": {
+        const points = rl.series;
+        if (!points || points.length === 0) break;
+        let min = Infinity;
+        let max = -Infinity;
+        for (let j = 0; j < points.length; j++) {
+          const value = points[j].value;
+          if (!Number.isFinite(value)) continue;
+          if (value < min) min = value;
+          if (value > max) max = value;
+        }
+        // Only the extrema are needed by the engine, avoiding a per-frame scan
+        // through the full historical annotation series.
+        if (min !== Infinity) out.push(min, max);
+        break;
+      }
       case "value-band":
         out.push(rl.valueFrom as number, rl.valueTo as number);
         break;
@@ -56,7 +78,13 @@ export function referenceLineReactKeys(
   const occurrences = new Map<string, number>();
   const keys: string[] = [];
   for (const line of lines) {
-    const base = line.id ?? stableReferenceLineSignature(line);
+    // A series' samples are render data, not identity. Omitting their contents
+    // keeps a growing historical series from remounting its overlay every render.
+    const base =
+      line.id ??
+      stableReferenceLineSignature(
+        line.series === undefined ? line : { ...line, series: "series" },
+      );
     const occurrence = occurrences.get(base) ?? 0;
     occurrences.set(base, occurrence + 1);
     keys.push(`${base}:${occurrence}`);

package/src/math/spline.ts

@@ -56,16 +56,26 @@ export function drawSpline(
   /** Straight polyline (`lineTo` per point) instead of the monotone cubic — an
    *  angular, hard-edged line. The caller has already `moveTo`'d point 0. */
   linear = false,
+  /** First point index to draw (inclusive). The caller must moveTo this point. */
+  startPoint = 0,
+  /** Last point index to draw (exclusive). Defaults to the full array. */
+  endPoint = pts.length >> 1,
 ) {
   "worklet";
-  const n = pts.length >> 1;
+  const start = Math.max(0, startPoint);
+  const end = Math.min(pts.length >> 1, endPoint);
+  const n = end - start;
   if (n < 2) return;
   if (linear) {
-    for (let i = 1; i < n; i++) path.lineTo(pts[i * 2], pts[i * 2 + 1]);
+    for (let i = 1; i < n; i++) {
+      const point = (start + i) * 2;
+      path.lineTo(pts[point], pts[point + 1]);
+    }
     return;
   }
   if (n === 2) {
-    path.lineTo(pts[2], pts[3]);
+    const point = (start + 1) * 2;
+    path.lineTo(pts[point], pts[point + 1]);
     return;
   }
 
@@ -73,7 +83,7 @@ export function drawSpline(
   const delta: number[] = scratch ? scratch.delta : new Array(n - 1);
   const h: number[] = scratch ? scratch.h : new Array(n - 1);
   for (let i = 0; i < n - 1; i++) {
-    const i2 = i * 2;
+    const i2 = (start + i) * 2;
     const j2 = i2 + 2;
     h[i] = pts[j2] - pts[i2];
     delta[i] = h[i] === 0 ? 0 : (pts[j2 + 1] - pts[i2 + 1]) / h[i];
@@ -110,7 +120,7 @@ export function drawSpline(
 
   // 4. Draw bezier curves
   for (let i = 0; i < n - 1; i++) {
-    const i2 = i * 2;
+    const i2 = (start + i) * 2;
     const j2 = i2 + 2;
     const hi = h[i];
     path.cubicTo(

package/src/types.ts

@@ -56,11 +56,12 @@ export type CanvasMode = "transparent" | "opaque";
 export type BadgeVariant = "default" | "minimal";
 
 /**
- * A reference line or band drawn into the chart. Three mutually-exclusive forms,
- * with precedence A > B > C when fields from more than one are present:
+ * A reference line or band drawn into the chart. Four mutually-exclusive forms,
+ * with precedence A > B > C > D when fields from more than one are present:
  * - **Form A** — horizontal line at `value`.
- * - **Form B** — horizontal band between `valueFrom` and `valueTo`.
- * - **Form C** — vertical time band between `from` and `to` (unix seconds).
+ * - **Form B** — time-varying line following `series`.
+ * - **Form C** — horizontal band between `valueFrom` and `valueTo`.
+ * - **Form D** — vertical time band between `from` and `to` (unix seconds).
  */
 export interface ReferenceLine {
   /**
@@ -70,13 +71,25 @@ export interface ReferenceLine {
   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`). */
+  /**
+   * 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.
+   */
+  series?: LiveChartPoint[];
+  /**
+   * Form B — extend the series' last value flat to the chart's live edge.
+   * Set `false` to stop at the last point. Default `true`.
+   */
+  extendToNow?: boolean;
+  /** Form C — horizontal band lower Y bound (paired with `valueTo`). */
   valueFrom?: number;
-  /** Form B — horizontal band upper Y bound (paired with `valueFrom`). */
+  /** Form C — horizontal band upper Y bound (paired with `valueFrom`). */
   valueTo?: number;
-  /** Form C — vertical time-band start, unix seconds (paired with `to`). */
+  /** Form D — vertical time-band start, unix seconds (paired with `to`). */
   from?: number;
-  /** Form C — vertical time-band end, unix seconds (paired with `from`). */
+  /** Form D — vertical time-band end, unix seconds (paired with `from`). */
   to?: number;
   /** Optional right-gutter label (e.g. `"Entry"`). */
   label?: string;
@@ -86,7 +99,7 @@ export interface ReferenceLine {
    * (top/bottom for value bands, left/right for time bands); omit for no border.
    */
   strokeWidth?: number;
-  /** Dash pattern as `[dashLength, gapLength]` in pixels (line stroke + band border). */
+  /** Dash pattern as `[dashLength, gapLength]` in pixels (line/series stroke + band border). */
   intervals?: [number, number];
   /**
    * Span the **full chart width** — edge to edge through the Y-axis gutter, not
@@ -94,13 +107,20 @@ export interface ReferenceLine {
    * value on the axis (like a price tag). Only the line/band extends; any
    * `label`/`badge` stays anchored inside the plot. For a Form-A line with a
    * `badge`, the full-width line replaces the dashed connector. No effect on a
-   * vertical time band. Default `false` (stops at the plot edge). Form A / B.
+   * vertical time band. Default `false` (stops at the plot edge). Form A / C.
    */
   fullWidth?: boolean;
   /** Line / band color override. Defaults to palette `refLine`. */
   color?: string;
+  /**
+   * Band fill color override. Defaults to {@link color}, then palette `refLine`.
+   * Form C / D only.
+   */
+  fillColor?: string;
   /** Fill opacity for a value / time band (0–1). Default `0.16`. */
   fillOpacity?: number;
+  /** Opacity for the line, series, or band border stroke (0–1). Default `1`. */
+  strokeOpacity?: number;
   /** Label text color. Defaults to `color`, then palette `refLabel`. */
   labelColor?: string;
   /**
@@ -109,7 +129,7 @@ export interface ReferenceLine {
    * (default `"left"`).
    */
   labelPosition?: "left" | "center" | "right";
-  /** Append the formatted `value` to the label (Form A only). Default `false`. */
+  /** Append the formatted value to the label (Form A/B). Default `false`. */
   showValue?: boolean;
   /**
    * Exclude this line's value(s) from the Y-axis range computation, so it may sit
@@ -541,6 +561,13 @@ export interface ThresholdLineConfig {
    * gutter like a legacy reference line (may overlap y-axis labels). Default `"left"`.
    */
   labelPosition?: "left" | "right";
+  /**
+   * Time-varying threshold series only: which visible endpoint supplies the
+   * label badge's Y position and optional value. `"first"` samples the
+   * threshold at the visible window's left edge; `"last"` uses the live/right
+   * edge. Independent of {@link labelPosition}. Default `"last"`.
+   */
+  labelAnchor?: "first" | "last";
   /** Line + label color. Defaults to palette `refLine` / `refLabel`. */
   color?: string;
   /** Dash pattern `[dashLength, gapLength]` in pixels. Default `[4, 4]`. */
@@ -554,6 +581,25 @@ export interface ThresholdLineConfig {
   labelColor?: string;
 }
 
+/**
+ * Context passed to {@link LiveChartProps.renderThresholdBadge}. The chart
+ * floats the returned React Native element over the canvas and pins it to the
+ * live threshold on the UI thread. Bind the SharedValues to animated content
+ * when its displayed value must update without React re-renders.
+ */
+export interface ThresholdBadgeRenderProps {
+  /** Resolved marker-line config for the badge being rendered. */
+  line: ThresholdLineConfig;
+  /** Live threshold value in Y-axis units. */
+  value: SharedValue<number>;
+  /** The threshold value formatted with the chart's `formatValue`. */
+  valueStr: SharedValue<string>;
+  /** Canvas Y pixel of the threshold (`NaN` when geometry is unavailable). */
+  y: SharedValue<number>;
+  /** Whether the threshold badge currently belongs inside the visible plot. */
+  visible: SharedValue<boolean>;
+}
+
 /** Object form of {@link ThresholdConfig.fill} — band tuning. */
 export interface ThresholdFillConfig {
   /** Band fill opacity (0–1), applied to the above/below colors. Multiplies an
@@ -1143,6 +1189,12 @@ export interface TooltipRenderProps {
    * worklet-safe formatter (e.g. the chart's `formatValue`).
    */
   candle: SharedValue<CandlePoint | null>;
+  /**
+   * Explicit line or candle gap under the crosshair (`null` outside a
+   * configured gap). A gap never fabricates {@link candle}; inspect this field
+   * for no-trade, unavailable, or unknown-data treatment.
+   */
+  gap: SharedValue<ChartGap | null>;
 }
 
 /** Inner plot rectangle in canvas pixels (a snapshot field of {@link ChartScale}). */
@@ -1743,6 +1795,8 @@ export interface ScrubPointCore {
 export interface ScrubPoint extends ScrubPointCore {
   /** In candle mode, the OHLC data of the candle under the crosshair. */
   candle?: CandlePoint;
+  /** Explicit chart gap under the crosshair, when a bridged gap supplies the value. */
+  gap?: ChartGap;
 }
 
 /** Scrub callback payload for multi-series charts. */
@@ -1772,6 +1826,110 @@ export interface CandlePoint {
   volume?: number;
 }
 
+/** Why a chart time range contains no observed market sample. */
+export type CandleGapKind = "no-trades" | "unavailable" | "unknown";
+
+/**
+ * Explicit metadata for a chart interval without an observed sample. The range
+ * is half-open (`[from, to)`) and uses Unix seconds, matching line points and
+ * {@link CandlePoint.time}. Gaps do not replace or mutate real data.
+ */
+export interface CandleGap {
+  /** Inclusive range start as a Unix timestamp in seconds. */
+  from: number;
+  /** Exclusive range end as a Unix timestamp in seconds. Must be greater than {@link from}. */
+  to: number;
+  /** Semantic reason the interval has no observation. */
+  kind: CandleGapKind;
+  /** Optional localized label, e.g. `"Exchange maintenance"`. */
+  label?: string;
+}
+
+/** Previous-value bridge styling for a chart gap. */
+export interface CandleGapBridgeStyle {
+  /** Mark color. Defaults to palette `refLine`. */
+  color?: string;
+  /** Mark opacity. Default `0.7` when enabled (`0.55` for unavailable gaps). */
+  opacity?: number;
+  /** Mark stroke width in pixels. Default `2`. */
+  strokeWidth?: number;
+  /** Mark cap style. Default `"round"`. */
+  strokeCap?: "butt" | "round" | "square";
+}
+
+/** Full-height time-band styling for a chart gap. */
+export interface CandleGapBandStyle {
+  /** Band fill color. Defaults to palette `refLine`. */
+  fillColor?: string;
+  /** Band fill opacity. Default `0.12` when enabled (`0.08` for unknown gaps). */
+  fillOpacity?: number;
+  /** Band-edge color. Defaults to palette `refLine`. */
+  borderColor?: string;
+  /** Band-edge opacity. Default `1`. */
+  borderOpacity?: number;
+  /**
+   * Band-edge width in pixels. `0` hides the border. Default `2` (`1` for
+   * unknown gaps).
+   */
+  borderWidth?: number;
+  /** Band-edge dash pattern. Default `[4, 4]`. */
+  intervals?: [number, number];
+}
+
+/** Label styling for a chart-gap time band. Text comes from {@link CandleGap.label}. */
+export interface CandleGapLabelStyle {
+  /** Label color. Defaults to palette `refLabel`. */
+  color?: string;
+  /** Label position inside the band. Default `"left"`. */
+  position?: "left" | "right";
+}
+
+/** Per-kind presentation overrides for {@link CandleGapsConfig}. */
+export interface CandleGapStyle {
+  /**
+   * Previous-close marks. `false` disables them; an object enables and styles
+   * them. Omission preserves the semantic default for the gap kind.
+   */
+  bridge?: false | CandleGapBridgeStyle;
+  /**
+   * Full-height time band. `false` disables it; an object enables and styles it.
+   * Omission preserves the semantic default for the gap kind.
+   */
+  band?: false | CandleGapBandStyle;
+  /**
+   * Band label. `false` hides it; an object enables and styles it. Omission
+   * preserves the semantic default for the gap kind.
+   */
+  label?: false | CandleGapLabelStyle;
+}
+
+/**
+ * Data and optional per-kind styling for explicit chart gaps. Gap metadata is
+ * low-frequency React data (like `referenceLines`); live market data remains in
+ * its SharedValue.
+ */
+export interface CandleGapsConfig {
+  /** Sorted, non-overlapping gap ranges. Invalid ranges are ignored. */
+  gaps: CandleGap[];
+  /** Presentation overrides keyed by semantic gap kind. */
+  styles?: Partial<Record<CandleGapKind, CandleGapStyle>>;
+}
+
+/** Semantic reason for a chart interval with no observed market sample. */
+export type ChartGapKind = CandleGapKind;
+/** Shared gap metadata used by both line and candlestick charts. */
+export type ChartGap = CandleGap;
+/** Previous-value bridge styling shared by line and candlestick gaps. */
+export type ChartGapBridgeStyle = CandleGapBridgeStyle;
+/** Full-height time-band styling shared by line and candlestick gaps. */
+export type ChartGapBandStyle = CandleGapBandStyle;
+/** Time-band label styling shared by line and candlestick gaps. */
+export type ChartGapLabelStyle = CandleGapLabelStyle;
+/** Per-kind gap presentation shared by line and candlestick charts. */
+export type ChartGapStyle = CandleGapStyle;
+/** Gap data and per-kind styles shared by line and candlestick charts. */
+export type ChartGapsConfig = CandleGapsConfig;
+
 // ── Metrics (sizing & motion tokens) ─────────────────────────────────────────
 
 /**
@@ -2103,7 +2261,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`
@@ -2172,8 +2330,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)`. */
@@ -2207,7 +2365,7 @@ export interface LiveChartCoreProps {
    * `render`). Default off.
    */
   bottomLabel?: boolean | AxisLabelConfig;
-  /** Reference lines / bands drawn into the chart. Supports all three `ReferenceLine` forms. */
+  /** Reference lines / bands drawn into the chart. Supports all four `ReferenceLine` forms. */
   referenceLines?: ReferenceLine[];
   /** Per-instance grid-line styling. Pass an object to override color / width / dash / opacity. */
   gridStyle?: GridStyleConfig;
@@ -2426,10 +2584,21 @@ export interface LiveChartProps extends LiveChartCoreProps {
   segments?: ChartSegment[];
   /**
    * Color the line above vs. below a live threshold value (break-even / average
-   * cost, VWAP, previous close, a peg). Always a `SharedValue` so the split tracks
-   * live on the UI thread. See {@link ThresholdConfig}.
+   * cost, VWAP, previous close, a peg). Supports a live scalar or a static/live
+   * time-varying series. See {@link ThresholdConfig}.
    */
   threshold?: ThresholdConfig;
+  /**
+   * Render the threshold line's badge as a custom **React Native** element
+   * instead of the built-in Skia pill. The chart measures and pins the element
+   * to the threshold's live Y position and configured `labelPosition` on the UI
+   * thread (see {@link ThresholdBadgeRenderProps}); the dashed marker line stays
+   * built in. Requires `threshold.line`. Return `null`/`undefined` to keep the
+   * built-in badge. Single-series line mode only.
+   */
+  renderThresholdBadge?: (
+    ctx: ThresholdBadgeRenderProps,
+  ) => ReactElement | null | undefined;
   /** Render the live value as a large text overlay in the top-left. Default `false`. */
   showValue?: boolean;
   /** Tint the `showValue` text by momentum (green up / red down). Default `false`. */
@@ -2444,6 +2613,22 @@ export interface LiveChartProps extends LiveChartCoreProps {
   candleWidth?: number;
   /** In-progress candle updated each tick. Must be a SharedValue for UI-thread reads. */
   liveCandle?: SharedValue<CandlePoint | null>;
+  /**
+   * Explicit candle-chart gaps. Pass a sorted array for semantic defaults, or a
+   * {@link CandleGapsConfig} to override per-kind styling. Missing timestamps
+   * are never inferred: `"no-trades"` draws neutral previous-close marks,
+   * `"unavailable"` adds a labeled time band, and `"unknown"` leaves price
+   * unfilled. Candle mode only. Default off.
+   */
+  candleGaps?: CandleGap[] | CandleGapsConfig;
+  /**
+   * Explicit line-chart gaps. Pass a sorted array for semantic defaults, or a
+   * {@link ChartGapsConfig} to override per-kind styling. The normal line and
+   * every area fill stop at the interval boundaries; bridge-enabled kinds draw
+   * a flat previous-value segment. Real samples inside a range take precedence
+   * over its metadata. Line mode only. Default off.
+   */
+  lineGaps?: ChartGap[] | ChartGapsConfig;
   /**
    * Live trade fills for optional on-chart markers. Read on the UI thread only —
    * pass a `SharedValue` and update from JS via `.value` (same pattern as `data` / `value`).