react-native-livechart 4.18.0 → 4.20.0

package/src/types.ts

@@ -422,6 +422,15 @@ export interface LineConfig {
    * pair with `join: "miter"` + `cap: "butt"` for true sharp corners (no rounding).
    */
   curve?: "monotone" | "linear";
+  /**
+   * Screen-space path simplification tolerance in pixels. Values above `0`
+   * remove intermediate points that deviate by no more than this amount while
+   * retaining endpoints and larger peaks/valleys. This changes only the drawn
+   * line/fill; axis fitting, live values, markers, and scrubbing still use the
+   * original data. Default `0` (off). Start around `0.75`–`1.5` for sub-pixel
+   * noise reduction.
+   */
+  simplify?: number;
   /** Line color override. Defaults to palette-derived accent. */
   color?: string;
   /**
@@ -639,6 +648,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**
@@ -854,13 +872,36 @@ export interface ScrubConfig {
    */
   seriesTooltip?: boolean | PerSeriesTooltipConfig;
   /**
-   * Opacity of the chart content to the *right* of the crosshair (the "future")
-   * while scrubbing — `0` fully fades it out, `1` disables the dim. Implemented
-   * by erasing the content's alpha (`dstOut`), so it reveals the real background
-   * and works on any background color. Default `0.3`. Ignored when
-   * `crosshairDimColor` is set (that uses the legacy colored mask instead).
+   * Which content {@link dimOpacity} fades while scrubbing.
+   *
+   * - `"future"` fades all chart content to the right of the crosshair.
+   * - `"otherCandles"` keeps the candle under the finger at full strength and
+   *   fades every other candle body and wick. Outside candle mode it falls back
+   *   to the standard `"future"` behavior. When the finger is in a gap between
+   *   candle buckets no candle is selected. Volume bars are unchanged. The
+   *   vertical crosshair and scrub selection dot are hidden so the focused
+   *   candle is the sole position indicator.
+   *
+   * Default `"future"`.
+   */
+  dimTarget?: "future" | "otherCandles";
+  /**
+   * Opacity of the content selected by {@link dimTarget} while scrubbing — `0`
+   * fully fades it out, `1` disables the dim. Values are clamped to `[0, 1]`.
+   *
+   * With the default `dimTarget: "future"`, the fade is implemented by erasing
+   * the trailing content's alpha (`dstOut`), so it reveals the real background
+   * and works on any background color. Default `0.3`. `crosshairDimColor`
+   * overrides this opacity only for the `"future"` target.
    */
   dimOpacity?: number;
+  /**
+   * Duration in milliseconds for other candles to ease toward
+   * {@link dimOpacity} when a focused-candle scrub starts, and back to full
+   * strength on release. Used only with `dimTarget: "otherCandles"`.
+   * Set `0` for an instant change. Negative values clamp to `0`. Default `60`.
+   */
+  dimFadeMs?: number;
   /** Vertical crosshair line stroke. Omit to use theme `crosshairLine`. */
   crosshairLineColor?: string;
   /** Vertical crosshair line width in px. Default `1`. */
@@ -1522,11 +1563,23 @@ export interface DegenShakePayload {
   direction: "up" | "down";
 }
 
-/** Contrasting outer ring drawn behind each series dot — the "haloed" look the
- *  single-series live dot has, so dots stand out against the lines and one
- *  another. */
+/** Optional soft, static color glow drawn behind a live dot. */
+export interface DotGlowConfig {
+  /** Glow color. Defaults to the dot's resolved fill color. */
+  color?: string;
+  /** Radius of the glow's source circle in pixels. Default `7`. */
+  radius?: number;
+  /** Skia blur radius in pixels. Default `5`. */
+  blur?: number;
+  /** Glow opacity (0–1). Default `0.18`. */
+  opacity?: number;
+}
+
+/** Contrasting outer ring drawn behind each series dot — the crisp backing
+ *  circle the single-series live dot has, so dots stand out against the lines
+ *  and one another. */
 export interface DotRingConfig {
-  /** Ring color. Default: theme `badgeOuterBg` (a near-background halo). */
+  /** Ring color. Default: theme `badgeOuterBg` (a near-background backing). */
   color?: string;
   /** Ring thickness in pixels — how far the halo extends past the dot. Default `2.5`. */
   width?: number;
@@ -1535,7 +1588,8 @@ export interface DotRingConfig {
 /**
  * Shared live-dot styling, used by both `LiveChart` (`dot`) and
  * `LiveChartSeries` (`dot`, which extends this). A dot is a color-filled circle
- * of `radius` with an optional contrasting outer `ring` (halo).
+ * of `radius` with an optional contrasting outer `ring` and opt-in soft
+ * `glow`. The glow is static; use `pulse` for an animated heartbeat.
  */
 export interface DotConfig {
   /** Radius of the (color-filled) dot in pixels. Default `3.5`. */
@@ -1546,6 +1600,12 @@ export interface DotConfig {
    * `DotRingConfig`. Default `true`.
    */
   ring?: boolean | DotRingConfig;
+  /**
+   * Soft static glow behind the dot. `true` = restrained defaults, `false` =
+   * off, or pass `DotGlowConfig` to tune its color, radius, blur, and opacity.
+   * Default `false`.
+   */
+  glow?: boolean | DotGlowConfig;
   /**
    * Show the dot. `false` hides it (line, badge, and labels still render). Default `true`.
    *
@@ -1637,6 +1697,13 @@ export interface SeriesConfig {
    *   anchored to this series snap to the straight chord to match.
    */
   curve?: "monotone" | "linear";
+  /**
+   * Per-series screen-space path simplification tolerance in pixels. Overrides
+   * `LiveChartSeries.line.simplify`; `0` disables simplification for this series.
+   * Only rendered geometry is simplified — values, range fitting, and scrubbing
+   * continue to use the original points.
+   */
+  simplify?: number;
   /** Per-series stroke width override (px). Falls back to the chart line width. */
   strokeWidth?: number;
   /** Render a soft glow behind this series' line. Default `false`. */
@@ -1884,6 +1951,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}.
  *
@@ -1986,9 +2069,11 @@ export interface LiveChartCoreProps {
   /**
    * UI-thread opacity multiplier for the plotted data. Set a value from `0`
    * (hidden) to `1` (fully visible), such as `0.5` while replacement data loads.
-   * Applies to every plotted series — line/fill/candles, live dots, value lines,
-   * and inline values — without affecting axes, reference lines, legends, or
-   * scrub UI. Default `1`.
+   * Applies to every plotted series — line/fill/candles, value lines, and inline
+   * values — without affecting axes, reference lines, legends, or scrub UI.
+   * While the multiplier is below `1`, live dots and pulse rings fade completely
+   * out so the dimmed stroke cannot show through them; they fade back in when it
+   * returns to `1`. Default `1`.
    */
   seriesOpacity?: SharedValue<number>;
   /**
@@ -2326,7 +2411,8 @@ export interface LiveChartProps extends LiveChartCoreProps {
   pulse?: boolean | PulseConfig;
   /**
    * Live dot styling. `true`/omitted = shown defaults, `false` = hidden, or pass
-   * `DotConfig` (`radius`, `ring` halo, `color`). See {@link DotConfig}. Default `true`.
+   * `DotConfig` (`radius`, `ring`, opt-in `glow`, `color`). See
+   * {@link DotConfig}. Default `true`.
    */
   dot?: boolean | DotConfig;
   /** Horizontal dashed line at the current live value. `true` = defaults, or pass `ValueLineConfig`. */
@@ -2374,8 +2460,9 @@ export interface LiveChartProps extends LiveChartCoreProps {
   /** Render once with no per-frame animation loop — for many small charts (sparklines)
    *  in a list. The continuous animations (pulse, degen, the entry reveal) are disabled,
    *  but `scrub` / `scrubAction` stay available — they're on-demand touch gestures with
-   *  no per-frame cost, so a still chart is still scrubbable. Frame the data with
-   *  `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
+   *  no per-frame cost, so a still chart is still scrubbable. May be toggled at runtime:
+   *  switching back to live restarts the suspended loops and catches up. Frame the data
+   *  with `timeWindow` + `nowOverride` (see the historical-data-fill pattern). */
   static?: boolean;
   /**
    * Render a custom overlay floated over the chart canvas, handed a price↔pixel /