react-native-livechart 4.17.0 → 4.19.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;
   /**
@@ -591,7 +600,11 @@ export interface AreaDotsConfig {
 export interface BadgeConfig extends BadgeStyleConfig {
   /** Visual style of the badge pill. Default `"default"`. */
   variant?: BadgeVariant;
-  /** Show the pointed tail toward the live dot. Default `true`. */
+  /**
+   * Show the pointed tail toward the live dot. When `false`, no tail space is
+   * reserved: the pill body sits flush at the gutter edge (right after the dot
+   * gap) and the auto right padding shrinks accordingly. Default `true`.
+   */
   tail?: boolean;
   /** Which side of the chart the badge appears on. Default `"right"`. */
   position?: "right" | "left";
@@ -850,13 +863,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`. */
@@ -961,6 +997,15 @@ export interface ScrubConfig {
    * Default `false`.
    */
   clampToPlot?: boolean;
+  /**
+   * Candle mode: snap the crosshair to candle centers. The scrub X is
+   * quantized to the hovered candle's center before it drives the crosshair,
+   * so the line — and everything derived from it (the time, tooltip, and
+   * trailing dim) — jumps from candle to candle instead of gliding, the
+   * tick-to-tick feel of pro charting tools. A position in a gap between
+   * candles keeps the raw finger X; no effect in line mode. Default `false`.
+   */
+  snapToCandles?: boolean;
 }
 
 /**
@@ -1509,11 +1554,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;
@@ -1522,7 +1579,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`. */
@@ -1533,6 +1591,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`.
    *
@@ -1542,6 +1606,21 @@ export interface DotConfig {
   show?: boolean;
   /** Dot fill color. Defaults to the chart line color (per series for multi-series). */
   color?: string;
+  /**
+   * Keep the dot on the **true live point** while scrolled back or overscrolled
+   * with `timeScroll`: it tracks the live point's x (instead of staying pinned
+   * to the plot's right edge), keeps its heartbeat pulse (the dot still marks
+   * an honest live position), stays visible under
+   * `timeScroll.hideLiveOnScrollBack`, and hides once the live point leaves the
+   * visible window. Ignored when `badge.followViewEdge` is set — an edge-pinned
+   * dot must stay aligned with its badge. Single-series `LiveChart` only
+   * (multi-series dots already ride each line's end while scrolled). Default
+   * `false` (the dot stays pinned to the right edge with its pulse suppressed
+   * while scrolled back).
+   *
+   * @experimental
+   */
+  trackWhileParked?: boolean;
 }
 
 /** Live dot configuration for multi-series charts (extends the shared {@link DotConfig}). */
@@ -1609,6 +1688,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`. */
@@ -1958,9 +2044,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>;
   /**
@@ -2298,7 +2386,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`. */
@@ -2346,8 +2435,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 /