react-native-livechart 4.3.0 → 4.5.0

package/src/core/resolveConfig.ts

@@ -14,6 +14,7 @@ import type {
   LineStyleConfig,
   LiveChartMetrics,
   LiveChartMetricsOverride,
+  LoadingConfig,
   MarkerClusterConfig,
   DotConfig,
   DotRingConfig,
@@ -29,6 +30,7 @@ import type {
   ThresholdConfig,
   ThresholdLineConfig,
   TradeEvent,
+  TransitionConfig,
   ValueLineConfig,
   VolumeConfig,
   XAxisConfig,
@@ -45,6 +47,8 @@ import {
   EMPTY_STATE_METRICS_DEFAULTS,
   FADE_EDGE_WIDTH,
   GRID_METRICS_DEFAULTS,
+  LOADING_WAVE_AMPLITUDE,
+  LOADING_WAVE_SPEED,
   MOTION_METRICS_DEFAULTS,
   RETURN_TO_LIVE_MS,
 } from "../constants";
@@ -165,6 +169,8 @@ export interface ResolvedScrubConfig {
   tooltipShowTime: boolean;
   /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
   panGestureDelay: number;
+  /** Fade markers + reference lines out while scrubbing. */
+  hideOverlaysOnScrub: boolean;
 }
 
 export interface ResolvedScrubActionConfig {
@@ -477,6 +483,32 @@ export function resolveReturnToLiveMs(
   return d > 0 ? d : 0;
 }
 
+/**
+ * Resolved transition durations. `undefined` for a field means "use the
+ * component's built-in default" (so we don't duplicate the default constants
+ * here); a number is an explicit duration in ms (clamped to ≥ 0).
+ */
+export interface ResolvedTransitionConfig {
+  reveal: number | undefined;
+  mode: number | undefined;
+}
+
+const clampMs = (v: number | undefined): number | undefined =>
+  v == null ? undefined : v > 0 ? v : 0;
+
+/**
+ * Resolves the `transitions` prop. `false` → all transitions instant (`0`);
+ * `true` / omitted → defaults (both `undefined` = use the built-in durations);
+ * an object → per-transition overrides (an omitted field keeps its default).
+ */
+export function resolveTransitions(
+  prop: boolean | TransitionConfig | undefined,
+): ResolvedTransitionConfig {
+  if (prop === false) return { reveal: 0, mode: 0 };
+  if (prop == null || prop === true) return { reveal: undefined, mode: undefined };
+  return { reveal: clampMs(prop.reveal), mode: clampMs(prop.mode) };
+}
+
 const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
   format: undefined,
   color: undefined,
@@ -571,6 +603,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   tooltipShowValue: true,
   tooltipShowTime: true,
   panGestureDelay: 0,
+  hideOverlaysOnScrub: false,
 };
 
 /**
@@ -590,6 +623,36 @@ export function resolveScrub(
   return resolved;
 }
 
+export interface ResolvedLoadingConfig {
+  /** undefined → palette.gridLine */
+  color: string | undefined;
+  /** undefined → the chart's line strokeWidth */
+  strokeWidth: number | undefined;
+  /** Base breathing-wave amplitude (px). */
+  amplitude: number;
+  /** Breathing-wave speed multiplier. */
+  speed: number;
+}
+
+const LOADING_DEFAULTS: ResolvedLoadingConfig = {
+  color: undefined,
+  strokeWidth: undefined,
+  amplitude: LOADING_WAVE_AMPLITUDE,
+  speed: LOADING_WAVE_SPEED,
+};
+
+/**
+ * Resolves the `loading` prop to a fully-typed config or null (not loading).
+ * `true` → defaults (loading on, built-in look), object → merged with defaults
+ * (loading on, restyled), `false` / omitted → null. So a non-null result is the
+ * "is loading" flag and carries the resolved styling.
+ */
+export function resolveLoading(
+  prop: boolean | LoadingConfig | undefined,
+): ResolvedLoadingConfig | null {
+  return resolveToggle(prop, LOADING_DEFAULTS, false);
+}
+
 const SCRUB_ACTION_DEFAULTS: ResolvedScrubActionConfig = {
   icon: "+",
   background: undefined,
@@ -634,6 +697,8 @@ export function resolveMarkerCluster(
       overlap: clamp01(prop.overlap ?? MARKER_CLUSTER_OVERLAP),
       gap: MARKER_CLUSTER_GAP,
       maxBeforeGroup: prop.maxBeforeGroup ?? MARKER_CLUSTER_MAX_BEFORE_GROUP,
+      groupBadge: prop.groupBadge ?? "count",
+      showGroupCount: prop.showGroupCount ?? false,
     };
   }
   return {
@@ -642,6 +707,8 @@ export function resolveMarkerCluster(
     overlap: MARKER_CLUSTER_OVERLAP,
     gap: MARKER_CLUSTER_GAP,
     maxBeforeGroup: MARKER_CLUSTER_MAX_BEFORE_GROUP,
+    groupBadge: "count",
+    showGroupCount: false,
   };
 }
 

package/src/draw/markerAtlas.ts

@@ -10,7 +10,12 @@ import {
   type SkPaint,
   type SkRect,
 } from "@shopify/react-native-skia";
-import type { LiveChartPalette, Marker, MarkerKind } from "../types";
+import type {
+  LiveChartPalette,
+  Marker,
+  MarkerGroupBadge,
+  MarkerKind,
+} from "../types";
 
 /** Default icon box (px) when `marker.size` is unset. */
 export const DEFAULT_ICON_SIZE = 16;
@@ -37,6 +42,10 @@ export function groupGlyphSig(ch: string): string {
   return `gd\x1f${ch}`;
 }
 
+/** Atlas cell sig for a dedicated group badge (one per chart — its own custom
+ *  image/icon, independent of the member markers). */
+export const GROUP_BADGE_SIG = "grpbadge";
+
 /** Atlas cell sig for the round count-badge background (one fixed circle per color). */
 export function groupBgSig(color: string): string {
   "worklet";
@@ -362,6 +371,10 @@ export function buildMarkerAtlas(
   /** Also bake count-badge cells (digits + per-color backgrounds) for
    *  `markerCluster: "stacked"` collapse. Off by default — no atlas bloat. */
   withGroups = false,
+  /** A dedicated group badge (custom image/icon) to bake one cell for, under
+   *  {@link GROUP_BADGE_SIG} — drawn for a collapsed cluster instead of the count.
+   *  Only baked when it carries an `image` or `icon`. */
+  groupBadge?: MarkerGroupBadge,
 ): MarkerAtlas {
   const seen = new Set<string>();
   const specs: { sig: string; spec: CellSpec }[] = [];
@@ -374,6 +387,22 @@ export function buildMarkerAtlas(
     specs.push({ sig, spec: cellSpec(m, palette, font) });
   }
 
+  // Dedicated group badge: bake one cell from its custom image/icon (reusing the
+  // marker cell geometry) so a collapsed cluster can blit it like any other glyph.
+  if (groupBadge && (groupBadge.image || groupBadge.icon)) {
+    const synthetic: Marker = {
+      id: GROUP_BADGE_SIG,
+      time: 0,
+      kind: "trade",
+      image: groupBadge.image,
+      icon: groupBadge.icon,
+      color: groupBadge.color,
+      pill: groupBadge.pill,
+      size: groupBadge.size,
+    };
+    specs.push({ sig: GROUP_BADGE_SIG, spec: cellSpec(synthetic, palette, font) });
+  }
+
   // Count-badge cells: 10 uniform white digit cells shared across colors, plus one
   // fixed round background per cluster color. A collapsed group composes its number
   // (centered, ≤ 2 digits) over the circle in the same `drawAtlas`.

package/src/hooks/useChartPaths.ts

@@ -35,6 +35,10 @@ export function useChartPaths(
    */
   edgeValue?: SharedValue<number>,
   followViewEdge = false,
+  /** Loading squiggle wave amplitude (px) for the reveal morph. Default 14. */
+  squiggleAmplitude = 14,
+  /** Loading squiggle wave speed multiplier for the reveal morph. Default 1. */
+  squiggleSpeed = 1,
 ) {
   const lineBuilder = usePathBuilder();
   const fillBuilder = usePathBuilder();
@@ -86,7 +90,13 @@ export function useChartPaths(
     // Compute squiggly Y values at the same X positions as the real line
     const centerY =
       (engine.canvasHeight.get() - padding.bottom + padding.top) / 2;
-    const squigglyPts = squigglifyPts(realPts, engine.timestamp.get(), centerY);
+    const squigglyPts = squigglifyPts(
+      realPts,
+      engine.timestamp.get(),
+      centerY,
+      squiggleAmplitude,
+      squiggleSpeed,
+    );
 
     // Blend center-out: centre of chart reveals first, edges last
     return blendPtsY(

package/src/hooks/useChartReveal.ts

@@ -60,6 +60,8 @@ export function useChartReveal(
   hasData: SharedValue<boolean>,
   /** Static charts skip the entry ramp: morphT snaps to its target, no `withTiming`. */
   isStatic = false,
+  /** Reveal/collapse duration (ms). Default {@link CHART_REVEAL_DURATION_MS}; `0` snaps. */
+  revealDuration: number = CHART_REVEAL_DURATION_MS,
 ): ChartRevealState {
   // Best-guess initial so the common case — a live chart that already has data
   // and isn't loading — paints fully revealed with no flash. The reaction below
@@ -85,15 +87,18 @@ export function useChartReveal(
         return;
       }
       if (prev !== chartVisible) {
+        // 0ms → withTiming resolves on the next frame (effectively a snap), so an
+        // explicit `transitions={{ reveal: 0 }}` / `transitions={false}` removes
+        // the grow-in without a special-case branch.
         morphT.set(
           withTiming(chartVisible ? 1 : 0, {
-            duration: CHART_REVEAL_DURATION_MS,
+            duration: revealDuration,
             easing: Easing.out(Easing.cubic),
           }),
         );
       }
     },
-    [hasData, isStatic],
+    [hasData, isStatic, revealDuration],
   );
 
   const isEmpty = useDerivedValue(() => !isLoading.get() && !hasData.get());

package/src/hooks/useMarkers.ts

@@ -28,6 +28,8 @@ const ANCHORED_CLUSTER: ResolvedMarkerCluster = {
   overlap: 0.75,
   gap: 2,
   maxBeforeGroup: 5,
+  groupBadge: "count",
+  showGroupCount: false,
 };
 
 /**

package/src/hooks/useModeBlend.ts

@@ -7,7 +7,7 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 
-const MODE_BLEND_DURATION_MS = 300;
+export const MODE_BLEND_DURATION_MS = 300;
 
 export interface ModeBlendState {
   /** 0 = fully line, 1 = fully candle */
@@ -28,17 +28,19 @@ export interface ModeBlendState {
 export function useModeBlend(
   isCandle: boolean,
   lineOpacity: SharedValue<number>,
+  /** Crossfade duration (ms). Default {@link MODE_BLEND_DURATION_MS}; `0` snaps. */
+  duration: number = MODE_BLEND_DURATION_MS,
 ): ModeBlendState {
   const modeBlend = useSharedValue(isCandle ? 1 : 0);
 
   useEffect(() => {
     modeBlend.set(
       withTiming(isCandle ? 1 : 0, {
-        duration: MODE_BLEND_DURATION_MS,
+        duration,
         easing: Easing.inOut(Easing.ease),
       }),
     );
-  }, [isCandle, modeBlend]);
+  }, [isCandle, modeBlend, duration]);
 
   const lineGroupOpacity = useDerivedValue(
     () => lineOpacity.get() * (1 - modeBlend.get()),

package/src/index.ts

@@ -64,8 +64,10 @@ export type {
   LiveChartPoint,
   LiveChartProps,
   LiveChartSeriesProps,
+  LoadingConfig,
   Marker,
   MarkerClusterConfig,
+  MarkerGroupBadge,
   MarkerKind,
   MarkerPressEvent,
   MarkerRenderContext,
@@ -96,6 +98,7 @@ export type {
   ThresholdLineConfig,
   TooltipRenderProps,
   TradeEvent,
+  TransitionConfig,
   ValueLineConfig,
   VisibleRange,
   VolumeConfig,

package/src/math/markerCluster.ts

@@ -1,4 +1,4 @@
-import type { Marker, MarkerSide } from "../types";
+import type { Marker, MarkerGroupBadge, MarkerSide } from "../types";
 import type { ProjectedMarker } from "./markers";
 
 /**
@@ -20,6 +20,13 @@ export interface ResolvedMarkerCluster {
   gap: number;
   /** Collapse a co-located run to a single count badge once it exceeds this many. */
   maxBeforeGroup: number;
+  /** What a collapsed group draws: `"count"` = the round count badge (default);
+   *  `"marker"` = the representative marker's own glyph; a {@link MarkerGroupBadge}
+   *  = a dedicated badge (custom image/icon) independent of the members. */
+  groupBadge: "count" | "marker" | MarkerGroupBadge;
+  /** With `groupBadge: "marker"` or a dedicated badge, also stamp the member count
+   *  in the glyph's top-right corner. Ignored for `"count"`. */
+  showGroupCount: boolean;
 }
 
 export interface ClusterMarkersOpts {

package/src/math/squiggly.ts

@@ -4,16 +4,26 @@ import type { ChartPadding } from "../draw/line";
  * Composite sine squiggly — two overlapping frequencies with a breathing
  * amplitude envelope. Matches the original web LiveChart loading animation.
  *
- * amplitude = 14 * (0.4 + 0.6 * sin(0.8 * t))   // 5.6 → 22.4px breathing range
- * y = centerY + amplitude * (sin(0.035*x + 1.2*t) + 0.45*sin(0.08*x + 2.1*t))
+ * amplitude = base * (0.4 + 0.6 * sin(0.8 * t·speed))   // 0.4×→1.0× base
+ * y = centerY + amplitude * (sin(0.035*x + 1.2*t·speed) + 0.45*sin(0.08*x + 2.1*t·speed))
+ *
+ * `base` (default `14`) scales the wave height; `speed` (default `1`) scales the
+ * time phase so the ripple/breathing runs faster or slower (`0` freezes it).
  */
-export function squigglyYAt(x: number, centerY: number, t: number): number {
+export function squigglyYAt(
+  x: number,
+  centerY: number,
+  t: number,
+  base = 14,
+  speed = 1,
+): number {
   "worklet";
-  const amplitude = 14 * (0.4 + 0.6 * Math.sin(0.8 * t));
+  const ts = t * speed;
+  const amplitude = base * (0.4 + 0.6 * Math.sin(0.8 * ts));
   return (
     centerY +
     amplitude *
-      (Math.sin(0.035 * x + 1.2 * t) + 0.45 * Math.sin(0.08 * x + 2.1 * t))
+      (Math.sin(0.035 * x + 1.2 * ts) + 0.45 * Math.sin(0.08 * x + 2.1 * ts))
   );
 }
 
@@ -27,6 +37,8 @@ export function buildSquigglyPts(
   canvasHeight: number,
   padding: ChartPadding,
   t: number,
+  base = 14,
+  speed = 1,
 ): number[] {
   "worklet";
   const leftEdge = padding.left;
@@ -41,7 +53,7 @@ export function buildSquigglyPts(
   for (let i = 0; i < count; i++) {
     const x = leftEdge + Math.min(i * step, chartW);
     pts[i * 2] = x;
-    pts[i * 2 + 1] = squigglyYAt(x, centerY, t);
+    pts[i * 2 + 1] = squigglyYAt(x, centerY, t, base, speed);
   }
   return pts;
 }
@@ -54,13 +66,15 @@ export function squigglifyPts(
   flatPts: number[],
   t: number,
   centerY: number,
+  base = 14,
+  speed = 1,
 ): number[] {
   "worklet";
   const n = flatPts.length;
   const out: number[] = new Array(n);
   for (let i = 0; i < n; i += 2) {
     out[i] = flatPts[i];
-    out[i + 1] = squigglyYAt(flatPts[i], centerY, t);
+    out[i + 1] = squigglyYAt(flatPts[i], centerY, t, base, speed);
   }
   return out;
 }

package/src/types.ts

@@ -720,6 +720,23 @@ export interface ScrubConfig {
    * Default `0`.
    */
   panGestureDelay?: number;
+  /**
+   * Fade the annotation overlays — buy/sell **markers** and **reference lines**
+   * (both the built-in Skia tags/lines and any custom `renderMarker` /
+   * `renderReferenceLine` RN views) — out while scrubbing, so they don't clutter
+   * the crosshair read-out. Reverses on release.
+   *
+   * The fade is driven by the **scrub-active** state (not the crosshair's
+   * edge-proximity fade, which would resurface the overlays as the crosshair
+   * nears the live dot) and eased on the UI thread over `SCRUB_OVERLAY_FADE_MS`.
+   * It animates only a **group opacity** — the marker atlas and reference-line
+   * geometry are left intact (still one batched draw each), so it's far cheaper
+   * than emptying / rebuilding overlay data per scrub. The leading dot is
+   * governed separately by `selectionDot`.
+   *
+   * `false` / omitted keeps the overlays visible while scrubbing (default).
+   */
+  hideOverlaysOnScrub?: boolean;
 }
 
 /**
@@ -1133,6 +1150,53 @@ export interface MarkerClusterConfig {
   /** Collapse a co-located run to a single count badge once it exceeds this many.
    *  Default `5`. */
   maxBeforeGroup?: number;
+  /**
+   * What a collapsed cluster draws in place of its members:
+   *  - `"count"` (default) — the built-in round count badge (a circle with the
+   *    member count inside).
+   *  - `"marker"` — the **representative marker's own glyph** (its `image`, `icon`
+   *    /`pill`, or `kind` shape). The representative is the newest marker in the run,
+   *    so a run of buy pills collapses to a buy pill — handy when the group should
+   *    look like its members.
+   *  - {@link MarkerGroupBadge} — a **dedicated group badge you supply** (your own
+   *    Skia `image`, or an `icon`/`pill`), independent of the member markers. Use
+   *    this when the collapse should look *different* from the individual markers —
+   *    e.g. tiny dots that collapse into a distinct "Buy 5" badge image.
+   *
+   * All three are Skia-drawn in the same `drawAtlas` batch (not a `renderMarker`
+   * RN overlay). Pair any non-`"count"` form with {@link showGroupCount} for a
+   * corner count. Default `"count"`.
+   */
+  groupBadge?: "count" | "marker" | MarkerGroupBadge;
+  /**
+   * When {@link groupBadge} is `"marker"` or a {@link MarkerGroupBadge}, also stamp
+   * the member count as a small badge in the glyph's top-right corner — the
+   * "Buy **5**" look. Ignored when `groupBadge` is `"count"` (the count *is* the
+   * badge). Default `false`.
+   */
+  showGroupCount?: boolean;
+}
+
+/**
+ * A dedicated badge drawn for a collapsed marker cluster — your own Skia design,
+ * independent of the member markers. Pass it as
+ * {@link MarkerClusterConfig.groupBadge}. Glyph precedence mirrors a single marker:
+ * `image` → `icon` (`pill`) → a filled dot. Requires `image` or `icon` (otherwise
+ * the group falls back to the count badge).
+ */
+export interface MarkerGroupBadge {
+  /** Custom Skia image for the collapsed group (e.g. from `useImage`). Takes
+   *  precedence over {@link icon}. */
+  image?: SkImage;
+  /** Text / emoji glyph for the collapsed group (used when {@link image} is unset).
+   *  Rendered with the chart font. */
+  icon?: string;
+  /** Color of the `icon` (and its `pill`). Defaults to a palette accent. */
+  color?: string;
+  /** Wrap the `icon` in a filled circular badge in {@link color} (icon drawn white). */
+  pill?: boolean;
+  /** Glyph box size in px (icon font size, or image width+height). Default `16`. */
+  size?: number;
 }
 
 /** Context passed to `renderMarker` alongside the marker (cluster / position state). */
@@ -1539,6 +1603,55 @@ export interface VisibleRange {
   following: boolean;
 }
 
+/**
+ * Per-transition animation durations (ms). Passed as the object form of
+ * {@link LiveChartCoreProps.transitions} to tune or disable the built-in
+ * animations. Omit a field to keep its default; `0` makes that transition
+ * instant (snap). Setting `transitions={false}` is shorthand for all `0`.
+ */
+export interface TransitionConfig {
+  /**
+   * Reveal / collapse transition — the grow-in when data first appears (and the
+   * fade-out when it goes away or `loading` toggles). This is what plays on a
+   * timeframe change and when a `line` chart's data appears (e.g. switching from
+   * candle to line). Default `600`. `0` = instant.
+   */
+  reveal?: number;
+  /**
+   * Candle ↔ line crossfade duration when `mode` changes. Single-series
+   * `LiveChart` only (multi-series is always lines). Default `300`. `0` = instant.
+   */
+  mode?: number;
+}
+
+/**
+ * Styling for the breathing-line loading shell (the {@link LiveChartCoreProps.loading}
+ * state). Every field is optional — pass it as the object form of `loading` to
+ * restyle the shell; omit a field to keep its default.
+ */
+export interface LoadingConfig {
+  /**
+   * Color of the loading squiggle **and** the skeleton Y-axis placeholders.
+   * Default: the theme's `gridLine` color.
+   */
+  color?: string;
+  /**
+   * Stroke width (px) of the loading squiggle. Default: the chart's line
+   * `strokeWidth`.
+   */
+  strokeWidth?: number;
+  /**
+   * Base wave amplitude (px) of the breathing squiggle — it breathes between
+   * `0.4×` and `1.0×` this. Default `14`.
+   */
+  amplitude?: number;
+  /**
+   * Multiplier on the breathing-wave animation cadence: `>1` ripples faster,
+   * `<1` slower, `0` freezes it. Default `1`.
+   */
+  speed?: number;
+}
+
 /** Props shared between `LiveChart` and `LiveChartSeries`. */
 export interface LiveChartCoreProps {
   /** Color scheme. Default `"dark"`. */
@@ -1555,11 +1668,27 @@ export interface LiveChartCoreProps {
   timeWindow?: number;
   /** Freeze chart scrolling. Resume catches up to real time. Default `false`. */
   paused?: boolean;
+  /**
+   * Tune or disable the built-in transition animations. `true` / omitted keeps
+   * the defaults; `false` makes them all instant (no grow-in on data
+   * appear/timeframe change, no candle↔line crossfade); a {@link TransitionConfig}
+   * sets per-transition durations in ms (`reveal`, `mode`), where `0` snaps that
+   * one. Live value tracking is governed separately by `smoothing`; static-entry
+   * suppression by `static`.
+   */
+  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).
-   */
-  loading?: boolean;
+   *
+   * `true` shows the shell with the defaults; pass a {@link LoadingConfig} to
+   * restyle it — `color` / `strokeWidth` for the squiggle + skeleton, `amplitude`
+   * / `speed` for the breathing wave. `false` / omitted is "not loading". Toggle
+   * between the config and `false` as data loads (e.g. `loading={isLoading && cfg}`).
+   * The loading→live reveal duration is governed separately by
+   * {@link TransitionConfig.reveal} (the `transitions` prop).
+   */
+  loading?: boolean | LoadingConfig;
   /**
    * Value-lerp speed — how quickly the drawn value, time window, and Y-range chase
    * their targets each frame (0 = frozen, 1 = instant). Equivalent to liveline's