react-native-livechart 4.19.0 → 4.21.0

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
@@ -648,6 +694,15 @@ export interface VolumeConfig {
 export interface YAxisConfig {
   /** Minimum pixel gap between grid lines. Default `36`. */
   minGap?: number;
+  /**
+   * Multiplier used to choose and align dynamic "nice" intervals without
+   * changing plotted values. Pair it with a `formatValue` that applies the
+   * same multiplier. Must be positive and finite; invalid values use `1`.
+   * If applying the multiplier to the live range would overflow or underflow,
+   * interval selection falls back to source units for that range.
+   * Ignored when {@link count} is set. Default `1`.
+   */
+  intervalScale?: number;
   /**
    * Show a fixed number of price labels instead of the dynamic nice-interval
    * grid. When set (≥ 2), exactly `count` labels are spaced evenly **in pixels**
@@ -1134,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}). */
@@ -1734,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. */
@@ -1763,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) ─────────────────────────────────────────
 
 /**
@@ -1942,6 +2109,22 @@ export interface ZoomConfig {
   maxTimeWindow?: number;
 }
 
+/** Imperative methods exposed by `LiveChart` and `LiveChartSeries`. */
+export interface LiveChartHandle {
+  /**
+   * Reset built-in pinch/time-window zoom to the configured `timeWindow` and
+   * clear the focal-point offset so the chart follows the live edge again.
+   * Safe to call when already reset. A paused chart remains paused.
+   *
+   * ```tsx
+   * const chartRef = useRef<LiveChartHandle>(null);
+   * <Button title="Reset zoom" onPress={() => chartRef.current?.resetZoom()} />
+   * <LiveChart ref={chartRef} data={data} value={value} zoom />
+   * ```
+   */
+  resetZoom(): void;
+}
+
 /**
  * The visible time range reported by {@link LiveChartCoreProps.onVisibleRangeChange}.
  *
@@ -2182,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;
@@ -2401,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`. */
@@ -2419,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`).