react-native-livechart 3.0.0 → 3.2.0

package/src/components/SelectionDot.tsx

@@ -0,0 +1,92 @@
+import { Circle, Group } from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { ResolvedSelectionDotConfig } from "../core/resolveConfig";
+
+/**
+ * Built-in selection dot: a filled circle at the scrub intersection plus an
+ * optional subtle outer ring (the `ring` config). Drawn only when `y >= 0` (the
+ * sentinel for "no dot") — an off-screen Y hides it naturally.
+ */
+export function DefaultSelectionDot({
+  x,
+  y,
+  opacity,
+  color,
+  size,
+  ring,
+}: {
+  x: SharedValue<number>;
+  y: SharedValue<number>;
+  opacity: SharedValue<number>;
+  color: string;
+  size: number;
+  ring: ResolvedSelectionDotConfig["ring"];
+}) {
+  // Push the dot off-screen when there's no value to mark (y < 0), so the
+  // sentinel never paints a stray dot at the top of the plot.
+  const cy = useDerivedValue(() => (y.get() < 0 ? -size * 4 : y.get()));
+  return (
+    <Group opacity={opacity}>
+      {ring && (
+        <Circle
+          cx={x}
+          cy={cy}
+          r={size + ring.width}
+          color={ring.color ?? color}
+          opacity={0.25}
+        />
+      )}
+      <Circle cx={x} cy={cy} r={size} color={color} />
+    </Group>
+  );
+}
+
+/**
+ * Resolves the selection-dot slot inside a crosshair overlay: renders nothing
+ * when `config` is null or the position is unavailable, the consumer's custom
+ * `component` when one is given, and the built-in dot otherwise.
+ *
+ * `color` is the resolved fallback (line / leading-series color) used when the
+ * config's own `color` is unset.
+ */
+export function SelectionDotSlot({
+  config,
+  x,
+  y,
+  active,
+  opacity,
+  color,
+}: {
+  config?: ResolvedSelectionDotConfig | null;
+  x: SharedValue<number>;
+  y?: SharedValue<number>;
+  active?: SharedValue<number> | SharedValue<boolean>;
+  opacity: SharedValue<number>;
+  color: string;
+}) {
+  if (!config || y === undefined || !active) return null;
+  const dotColor = config.color ?? color;
+  if (config.component) {
+    const Custom = config.component;
+    return (
+      <Custom
+        x={x}
+        y={y}
+        active={active as SharedValue<boolean>}
+        opacity={opacity}
+        color={dotColor}
+        size={config.size}
+      />
+    );
+  }
+  return (
+    <DefaultSelectionDot
+      x={x}
+      y={y}
+      opacity={opacity}
+      color={dotColor}
+      size={config.size}
+      ring={config.ring}
+    />
+  );
+}

package/src/core/resolveConfig.ts

@@ -1,4 +1,5 @@
 import type {
+  AxisLabelConfig,
   BadgeConfig,
   BadgeVariant,
   DegenOptions,
@@ -17,12 +18,16 @@ import type {
   PulseConfig,
   ReferenceLine,
   ScrubConfig,
+  SelectionDotConfig,
+  SelectionDotProps,
+  SelectionDotRingConfig,
   TradeEvent,
   ValueLineConfig,
   XAxisConfig,
   YAxisConfig,
 } from "../types";
 
+import type { ComponentType, ReactElement } from "react";
 import type { SharedValue } from "react-native-reanimated";
 import {
   BADGE_METRICS_DEFAULTS,
@@ -53,6 +58,16 @@ export interface ResolvedYAxisConfig {
   minGap: number;
 }
 
+export interface ResolvedAxisLabelConfig {
+  /** undefined → use the chart's `formatValue` at render time. */
+  format?: (v: number) => string;
+  /** undefined → use the muted default label color at render time. */
+  color?: string;
+  position: "left" | "right";
+  /** When set, the built-in value label is replaced by this custom element. */
+  render?: () => ReactElement | null;
+}
+
 export interface ResolvedXAxisConfig {
   minGap: number;
 }
@@ -80,6 +95,10 @@ export interface ResolvedGradientConfig {
   topOpacity: number | undefined;
   /** undefined → use palette.fillBottom (transparent) at render time */
   bottomOpacity: number | undefined;
+  /** Explicit color stops (top → bottom); overrides the opacity stops. */
+  colors: string[] | undefined;
+  /** Stop positions (0..1) matching `colors` length. */
+  positions: number[] | undefined;
 }
 
 export interface ResolvedPulseConfig {
@@ -217,6 +236,24 @@ export function resolveYAxis(
   return resolveToggle(prop, Y_AXIS_DEFAULTS, false);
 }
 
+const AXIS_LABEL_DEFAULTS: ResolvedAxisLabelConfig = {
+  format: undefined,
+  color: undefined,
+  position: "right",
+  render: undefined,
+};
+
+/**
+ * Resolves a `topLabel` / `bottomLabel` prop to a fully-typed config or null
+ * (no label). Opt-in, so `undefined`/`false` → null; `true` → the built-in
+ * value label with defaults; object → configured built-in (or a custom `render`).
+ */
+export function resolveAxisLabel(
+  prop: boolean | AxisLabelConfig | undefined,
+): ResolvedAxisLabelConfig | null {
+  return resolveToggle(prop, AXIS_LABEL_DEFAULTS, false);
+}
+
 const X_AXIS_DEFAULTS: ResolvedXAxisConfig = {
   minGap: 60,
 };
@@ -255,6 +292,8 @@ export function resolveScrub(
 const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
   topOpacity: undefined,
   bottomOpacity: undefined,
+  colors: undefined,
+  positions: undefined,
 };
 
 /**
@@ -574,6 +613,65 @@ export function resolveMultiSeriesDot(
   };
 }
 
+// ─── Selection dot ──────────────────────────────────────────────────────────
+
+/** Resolved selection-dot ring. `color: undefined` → use the dot color. */
+export interface ResolvedSelectionDotRingConfig {
+  color: string | undefined;
+  width: number;
+}
+
+const SELECTION_DOT_RING_DEFAULTS: ResolvedSelectionDotRingConfig = {
+  color: undefined,
+  width: 2,
+};
+
+/** `undefined`/`true` → ring defaults; `false` → null (no ring). */
+export function resolveSelectionDotRing(
+  prop: boolean | SelectionDotRingConfig | undefined,
+): ResolvedSelectionDotRingConfig | null {
+  return resolveToggle(prop, SELECTION_DOT_RING_DEFAULTS, true);
+}
+
+/** Fully-resolved selection-dot styling. */
+export interface ResolvedSelectionDotConfig {
+  size: number;
+  /** undefined → use the line / leading-series color at render time. */
+  color: string | undefined;
+  ring: ResolvedSelectionDotRingConfig | null;
+  /** When set, the built-in size/color/ring knobs are ignored. */
+  component?: ComponentType<SelectionDotProps>;
+}
+
+const SELECTION_DOT_SIZE_DEFAULT = 4;
+
+const SELECTION_DOT_DEFAULTS: ResolvedSelectionDotConfig = {
+  size: SELECTION_DOT_SIZE_DEFAULT,
+  color: undefined,
+  ring: SELECTION_DOT_RING_DEFAULTS,
+};
+
+/**
+ * Resolves the `selectionDot` prop to a fully-typed config or null (hidden).
+ * Defaults to ON, so `undefined`/`true` yield the built-in dot.
+ * - `false` → `null` (no dot)
+ * - `undefined`/`true` → built-in dot with defaults
+ * - object → configured built-in dot, or the custom `component` when set
+ *   (the size/color/ring knobs are still resolved but ignored by the slot)
+ */
+export function resolveSelectionDot(
+  prop: boolean | SelectionDotConfig | undefined,
+): ResolvedSelectionDotConfig | null {
+  if (prop === false) return null;
+  if (prop == null || prop === true) return SELECTION_DOT_DEFAULTS;
+  return {
+    size: prop.size ?? SELECTION_DOT_DEFAULTS.size,
+    color: prop.color,
+    ring: resolveSelectionDotRing(prop.ring),
+    component: prop.component,
+  };
+}
+
 // ─── Legend ───────────────────────────────────────────────────────────────────
 
 export interface ResolvedLegendConfig {

package/src/core/useLiveChartEngine.ts

@@ -7,6 +7,7 @@
  */
 import { useState } from "react";
 import {
+  useAnimatedReaction,
   useDerivedValue,
   useFrameCallback,
   useSharedValue,
@@ -31,6 +32,12 @@ export interface EngineConfig {
   nowOverride?: number;
   windowBuffer?: number;
   paused?: boolean;
+  /**
+   * Loop-free render: settle the display state once (smoothing forced to 1, no
+   * per-frame frame callback) for many small charts in a list. See
+   * {@link LiveChartProps.static}.
+   */
+  static?: boolean;
   mode?: "line" | "candle";
   candles?: SharedValue<CandlePoint[]>;
   liveCandle?: SharedValue<CandlePoint | null>;
@@ -143,7 +150,11 @@ export function applyLiveChartEngineFrame(
 export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   // Low-frequency config → UI thread via useDerivedValue
   const timeWindow = useDerivedValue(() => config.timeWindow);
-  const smoothing = useDerivedValue(() => config.smoothing);
+  // Static charts snap to their target in one tick (smoothing=1), so the single
+  // settle reaction below produces the final state with no per-frame easing.
+  const smoothing = useDerivedValue(() =>
+    config.static ? 1 : config.smoothing,
+  );
   const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
@@ -170,34 +181,74 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   // no useDerivedValue bridging, no closure serialization per tick.
   const { data, value, candles, liveCandle } = config;
 
+  // Static charts run zero per-frame loops. `isStaticSV` gates both the
+  // frame-callback autostart and the one-shot settle reaction below.
+  const isStaticSV = useDerivedValue(() => config.static ?? false);
+
+  // Single refs object shared by the frame callback and the settle reaction so
+  // they can never drift out of sync.
+  const frameRefs: EngineFrameRefs = {
+    data,
+    value,
+    displayValue,
+    displayMin,
+    displayMax,
+    displayWindow,
+    timestamp,
+    canvasWidth,
+    canvasHeight,
+    timeWindow,
+    smoothing,
+    adaptiveSpeedBoostSV,
+    exaggerateSV,
+    referenceValue,
+    referenceValues,
+    nonNegativeSV,
+    maxValueSV,
+    nowOverrideSV,
+    windowBufferSV,
+    pausedSV,
+    modeSV,
+    candles,
+    liveCandle,
+  };
+
+  // `autostart=false` registers the frame callback without running it — the live
+  // loop is fully inert in static mode (the invariant that makes this worth it).
   useFrameCallback((frameInfo) => {
     "worklet";
-    applyLiveChartEngineFrame(frameInfo, {
-      data,
-      value,
-      displayValue,
-      displayMin,
-      displayMax,
-      displayWindow,
-      timestamp,
-      canvasWidth,
-      canvasHeight,
-      timeWindow,
-      smoothing,
-      adaptiveSpeedBoostSV,
-      exaggerateSV,
-      referenceValue,
-      referenceValues,
-      nonNegativeSV,
-      maxValueSV,
-      nowOverrideSV,
-      windowBufferSV,
-      pausedSV,
-      modeSV,
-      candles,
-      liveCandle,
-    });
-  });
+    applyLiveChartEngineFrame(frameInfo, frameRefs);
+  }, !config.static);
+
+  // One-shot settle for static charts: the fingerprint changes when the canvas
+  // lays out (width 0→real) or the framing inputs change, and the handler runs a
+  // single snap tick (smoothing=1). Inert when not static — `prepare` returns a
+  // constant so it never fires.
+  useAnimatedReaction(
+    () => {
+      if (!isStaticSV.get()) return 0; // inert when not static — never changes
+      const d = data.get();
+      const n = d.length;
+      return [
+        n,
+        n ? d[0].time : 0,
+        n ? d[0].value : 0,
+        n ? d[n - 1].time : 0,
+        n ? d[n - 1].value : 0,
+        value.get(),
+        canvasWidth.get(),
+        canvasHeight.get(),
+        timeWindow.get(),
+      ].join(",");
+    },
+    (curr, prev) => {
+      if (!isStaticSV.get() || curr === prev) return;
+      applyLiveChartEngineFrame(
+        { timeSincePreviousFrame: MS_PER_FRAME_60FPS },
+        frameRefs,
+      );
+    },
+  );
 
   return {
     data,

package/src/draw/particleAtlas.ts

@@ -0,0 +1,95 @@
+import {
+  Skia,
+  PaintStyle,
+  drawAsImageFromPicture,
+  type SkImage,
+} from "@shopify/react-native-skia";
+import { DEGEN_STRIDE } from "../constants";
+
+/** Reference radius of the rasterized white circle sprite (px). */
+const SPRITE_RADIUS = 16;
+/** Anti-alias breathing room baked around the circle so it never clips. */
+const SPRITE_MARGIN = 2;
+
+/** A rasterized white-circle sprite + its geometry. */
+export interface ParticleSprite {
+  image: SkImage | null;
+  /** Side length of the square sprite box (px). */
+  size: number;
+  /** Radius of the white circle inside the box (px). */
+  radius: number;
+}
+
+/**
+ * Rasterize ONE anti-aliased **white** filled circle into a square sprite, once
+ * (NOT per frame). Drawing it white lets each particle's per-sprite color
+ * modulate (multiply) the texture to its own tint + alpha via `drawAtlas`.
+ *
+ * Mirrors the PictureRecorder pattern in `markerAtlas.ts`.
+ */
+export function buildParticleSprite(): ParticleSprite {
+  const R = SPRITE_RADIUS;
+  const S = 2 * (R + SPRITE_MARGIN);
+  const paint = Skia.Paint();
+  paint.setAntiAlias(true);
+  paint.setColor(Skia.Color("#ffffff"));
+  paint.setStyle(PaintStyle.Fill);
+
+  const recorder = Skia.PictureRecorder();
+  const canvas = recorder.beginRecording(Skia.XYWHRect(0, 0, S, S));
+  canvas.drawCircle(S / 2, S / 2, R, paint);
+  const picture = recorder.finishRecordingAsPicture();
+  const image = drawAsImageFromPicture(picture, { width: S, height: S });
+  return { image, size: S, radius: R };
+}
+
+/** One particle ready to blit: world position + per-sprite scale/alpha/color. */
+export interface ParticleInstance {
+  x: number;
+  y: number;
+  scale: number;
+  alpha: number;
+  colorIndex: number;
+}
+
+/**
+ * Pure, worklet-safe projection of the packed particle ring buffer into render
+ * instances. No Skia — plain numbers only — so it's directly unit-testable.
+ *
+ * Preserves the exact size/opacity formulas the old per-slot `<Circle>` used:
+ *   life  = max(0, 1 - (now - t0) / burstDur)   (skip if dt = now - t0 < 0)
+ *   r     = size * (0.5 + life * 0.5),  size = buf[base+6] || 1
+ *   scale = r / spriteRadius
+ *   alpha = life * particleOpacity
+ * Inactive (active <= 0.5), pre-spawn (dt < 0) and fully-faded (life <= 0)
+ * slots are skipped.
+ */
+export function buildParticleInstances(
+  buf: Float64Array,
+  slots: number,
+  now: number,
+  burstDur: number,
+  particleOpacity: number,
+  spriteRadius: number,
+): ParticleInstance[] {
+  "worklet";
+  const out: ParticleInstance[] = [];
+  for (let i = 0; i < slots; i++) {
+    const base = i * DEGEN_STRIDE;
+    if (!(buf[base + 5] > 0.5)) continue;
+    const dt = now - buf[base + 4];
+    if (dt < 0) continue;
+    const life = Math.max(0, 1 - dt / burstDur);
+    if (life <= 0) continue;
+    const size = buf[base + 6] || 1;
+    const r = size * (0.5 + life * 0.5);
+    out.push({
+      x: buf[base + 0],
+      y: buf[base + 1],
+      scale: r / spriteRadius,
+      alpha: life * particleOpacity,
+      colorIndex: Math.max(0, Math.floor(buf[base + 7])),
+    });
+  }
+  return out;
+}

package/src/hooks/crosshairShared.ts

@@ -54,9 +54,35 @@ export interface CrosshairState {
   scrubValue: SharedValue<number | null>;
   crosshairOpacity: SharedValue<number>;
   tooltipLayout: SharedValue<TooltipLayout>;
+  /** Scrub intersection Y in canvas px; -1 when there's no dot to draw
+   *  (inactive / no value / degenerate range). See {@link computeScrubDotY}. */
+  scrubDotY: SharedValue<number>;
   gesture: ReturnType<typeof Gesture.Pan>;
 }
 
+/**
+ * Maps a scrub value to its Y pixel at the crosshair intersection — the same
+ * mapping the live dot and tooltip use. Returns -1 when there is no dot to draw
+ * (value is null or the canvas isn't laid out); a degenerate (zero) range pins
+ * the dot to the vertical center of the plot.
+ */
+export function computeScrubDotY(
+  value: number | null,
+  displayMin: number,
+  displayMax: number,
+  canvasHeight: number,
+  padTop: number,
+  padBottom: number,
+): number {
+  "worklet";
+  if (value === null) return -1;
+  const chartH = canvasHeight - padTop - padBottom;
+  if (chartH <= 0) return -1;
+  const valRange = displayMax - displayMin;
+  if (valRange === 0) return padTop + chartH / 2;
+  return padTop + ((displayMax - value) / valRange) * chartH;
+}
+
 /**
  * Maps a scrub X position to a window timestamp.
  * Returns -1 when inactive or when the canvas is not yet laid out.

package/src/hooks/useCandlePaths.ts

@@ -29,6 +29,8 @@ export function useCandlePaths(
   candleWidthSecs: number,
   active: boolean,
   candleMetrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+  /** Static charts run no loops: register without starting. Default `true`. */
+  autostart = true,
 ) {
   const targetCandleWidth = useDerivedValue(() => candleWidthSecs);
   const displayCandleWidth = useSharedValue(candleWidthSecs);
@@ -50,7 +52,7 @@ export function useCandlePaths(
         dt,
       ),
     );
-  });
+  }, autostart);
 
   /* istanbul ignore next -- worklet */
   const geometry = useDerivedValue(() => {

package/src/hooks/useCanvasLayout.ts

@@ -5,18 +5,20 @@ import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 
 /**
  * Track canvas dimensions via `onLayout` and sync them into engine shared values.
- * Returns `{ layoutHeight, onLayout }` — pass `onLayout` to the container View
- * and use `layoutHeight` for conditional rendering (e.g. minimum height guards).
+ * Returns `{ layoutWidth, layoutHeight, onLayout }` — pass `onLayout` to the
+ * container View and use dimensions for conditional rendering or gradient coordinates.
  */
 export function useCanvasLayout(engine: ChartEngineLayout) {
+  const [layoutWidth, setLayoutWidth] = useState(0);
   const [layoutHeight, setLayoutHeight] = useState(0);
 
   const onLayout = (e: LayoutChangeEvent) => {
     const { width, height } = e.nativeEvent.layout;
     engine.canvasWidth.set(width);
     engine.canvasHeight.set(height);
+    setLayoutWidth(width);
     setLayoutHeight(height);
   };
 
-  return { layoutHeight, onLayout } as const;
+  return { layoutWidth, layoutHeight, onLayout } as const;
 }

package/src/hooks/useChartColors.ts

@@ -12,6 +12,11 @@ export interface ChartColors {
   gradientTopColor: string;
   /** Bottom gradient stop — custom opacity or palette default. */
   gradientBottomColor: string;
+  /** Gradient color stops (top → bottom). Custom `colors` when provided, else the
+   *  2-stop `[gradientTopColor, gradientBottomColor]` fallback. */
+  gradientColors: string[];
+  /** Stop positions matching `gradientColors`, or undefined for even spacing. */
+  gradientPositions: number[] | undefined;
 }
 
 /**
@@ -39,10 +44,24 @@ export function useChartColors(
       ? `rgba(${r}, ${g}, ${b}, ${gradientCfg.bottomOpacity})`
       : palette.fillBottom;
 
+  const customColors = gradientCfg?.colors;
+  const hasCustomColors = Array.isArray(customColors) && customColors.length >= 2;
+  const gradientColors = hasCustomColors
+    ? customColors
+    : [gradientTopColor, gradientBottomColor];
+  const gradientPositions =
+    hasCustomColors &&
+    gradientCfg?.positions !== undefined &&
+    gradientCfg.positions.length === customColors.length
+      ? gradientCfg.positions
+      : undefined;
+
   return {
     backgroundColor,
     gradientEnd,
     gradientTopColor,
     gradientBottomColor,
+    gradientColors,
+    gradientPositions,
   };
 }

package/src/hooks/useChartReveal.ts

@@ -58,6 +58,8 @@ export interface ChartRevealState {
 export function useChartReveal(
   loading: boolean,
   hasData: SharedValue<boolean>,
+  /** Static charts skip the entry ramp: morphT snaps to its target, no `withTiming`. */
+  isStatic = false,
 ): 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
@@ -71,13 +73,14 @@ export function useChartReveal(
 
   // The reaction reads presence/loading on the UI thread (a worklet, never during
   // render — so no Reanimated "reading `value` during render" warning), seeds the
-  // exact reveal state on its first run, then animates on later changes.
+  // exact reveal state on its first run, then animates on later changes. Static
+  // charts always snap (no `withTiming` ramp) so no entry animation ever runs.
   useAnimatedReaction(
     () => !isLoading.get() && hasData.get(),
     (chartVisible, prev) => {
       "worklet";
-      if (prev === null || prev === undefined) {
-        // First run: snap to the correct initial reveal state (no animation).
+      if (isStatic || prev === null || prev === undefined) {
+        // Static, or first run: snap to the correct reveal state (no animation).
         morphT.set(chartVisible ? 1 : 0);
         return;
       }
@@ -90,7 +93,7 @@ export function useChartReveal(
         );
       }
     },
-    [hasData],
+    [hasData, isStatic],
   );
 
   const isEmpty = useDerivedValue(() => !isLoading.get() && !hasData.get());