react-native-livechart 2.0.1 → 3.1.0

package/src/components/CrosshairLine.tsx

@@ -2,7 +2,9 @@ import { Group, Line, Rect } from "@shopify/react-native-skia";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { type ChartPadding } from "../draw/line";
 import type { LiveChartPalette } from "../types";
+import type { ResolvedSelectionDotConfig } from "../core/resolveConfig";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import { SelectionDotSlot } from "./SelectionDot";
 
 /**
  * Crosshair vertical line + dim region to the right. No tooltip pill —
@@ -14,6 +16,10 @@ export function CrosshairLine({
   engine,
   padding,
   palette,
+  selectionDot,
+  selectionY,
+  scrubActive,
+  selectionColor,
   dimOpacity = 0.3,
   liveDotExtent = 0,
   crosshairLineColor,
@@ -24,6 +30,16 @@ export function CrosshairLine({
   engine: ChartEngineLayout;
   padding: ChartPadding;
   palette: LiveChartPalette;
+  /** Resolved selection-dot config; `null` hides it, a `component` renders the
+   *  consumer's dot, otherwise the built-in dot. */
+  selectionDot?: ResolvedSelectionDotConfig | null;
+  /** Scrub intersection Y in canvas px (the value the dot marks); -1 hides it. */
+  selectionY?: SharedValue<number>;
+  /** Whether scrubbing is active (passed through to a custom dot). */
+  scrubActive?: SharedValue<number> | SharedValue<boolean>;
+  /** Fallback selection-dot color (leading-series color), used when the config's
+   *  own `color` is unset. */
+  selectionColor?: string;
   /** Opacity of content right of the crosshair (dstOut fade). Default 0.3. */
   dimOpacity?: number;
   /** How far the live series dots extend past the plot's right edge. The dim
@@ -104,6 +120,17 @@ export function CrosshairLine({
           color={crosshairLineColor ?? palette.crosshairLine}
           strokeWidth={1}
         />
+
+        {/* Selection dot at the scrub intersection (leading series). `null`
+            hides it; a custom component renders the consumer's dot. */}
+        <SelectionDotSlot
+          config={selectionDot}
+          x={scrubX}
+          y={selectionY}
+          active={scrubActive}
+          opacity={crosshairOpacity}
+          color={selectionColor ?? palette.line}
+        />
       </Group>
     </>
   );

package/src/components/CrosshairOverlay.tsx

@@ -11,7 +11,9 @@ import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { type ChartPadding } from "../draw/line";
 import { type TooltipLayout } from "../hooks/crosshairShared";
 import type { LiveChartPalette } from "../types";
+import type { ResolvedSelectionDotConfig } from "../core/resolveConfig";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import { SelectionDotSlot } from "./SelectionDot";
 
 const TOOLTIP_RADIUS = 5;
 
@@ -25,6 +27,11 @@ export function CrosshairOverlay({
   font,
   showTooltip = true,
   children,
+  renderTooltip,
+  selectionDot,
+  selectionY,
+  scrubActive,
+  selectionColor,
   dimOpacity = 0.3,
   liveDotExtent = 0,
   crosshairLineColor,
@@ -45,6 +52,19 @@ export function CrosshairOverlay({
    *  text (e.g. the multi-line candle stack). Passed as children so it composes
    *  instead of being threaded through as a JSX-valued prop. */
   children?: ReactNode;
+  /** Public custom-tooltip hook for line mode: when provided (and no `children`
+   *  are passed), its result replaces the default value/time tooltip body. */
+  renderTooltip?: () => ReactNode;
+  /** Resolved selection-dot config; `null` hides it, a `component` renders the
+   *  consumer's dot, otherwise the built-in dot. */
+  selectionDot?: ResolvedSelectionDotConfig | null;
+  /** Scrub intersection Y in canvas px (the value the dot marks); -1 hides it. */
+  selectionY?: SharedValue<number>;
+  /** Whether scrubbing is active (passed through to a custom dot). */
+  scrubActive?: SharedValue<number> | SharedValue<boolean>;
+  /** Fallback selection-dot color (accent / leading-series color), used when the
+   *  config's own `color` is unset. */
+  selectionColor?: string;
   /** Opacity of content right of the crosshair (dstOut fade). Default 0.3. */
   dimOpacity?: number;
   /** How far the live dot (and its pulse ring) extends past the plot's right
@@ -143,6 +163,17 @@ export function CrosshairOverlay({
           strokeWidth={1}
         />
 
+        {/* Selection dot at the scrub intersection. `null` hides it; a custom
+            component renders the consumer's dot; otherwise the built-in dot. */}
+        <SelectionDotSlot
+          config={selectionDot}
+          x={scrubX}
+          y={selectionY}
+          active={scrubActive}
+          opacity={crosshairOpacity}
+          color={selectionColor ?? palette.line}
+        />
+
         {showTooltip && (
         <>
           <RoundedRect
@@ -165,24 +196,25 @@ export function CrosshairOverlay({
             strokeWidth={1}
           />
 
-          {children ?? (
-            <Group>
-              <SkiaText
-                x={valueTextX}
-                y={line1Y}
-                text={valueStr}
-                font={font}
-                color={tooltipColor ?? palette.tooltipText}
-              />
-              <SkiaText
-                x={timeTextX}
-                y={line2Y}
-                text={timeStr}
-                font={font}
-                color={palette.gridLabel}
-              />
-            </Group>
-          )}
+          {children ??
+            renderTooltip?.() ?? (
+              <Group>
+                <SkiaText
+                  x={valueTextX}
+                  y={line1Y}
+                  text={valueStr}
+                  font={font}
+                  color={tooltipColor ?? palette.tooltipText}
+                />
+                <SkiaText
+                  x={timeTextX}
+                  y={line2Y}
+                  text={timeStr}
+                  font={font}
+                  color={palette.gridLabel}
+                />
+              </Group>
+            )}
         </>
       )}
       </Group>

package/src/components/DegenParticlesOverlay.tsx

@@ -1,99 +1,38 @@
-import { Circle, Group } from "@shopify/react-native-skia";
+import {
+  Atlas,
+  Skia,
+  type SkColor,
+  type SkRSXform,
+  type SkRect,
+} from "@shopify/react-native-skia";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
-import { DEGEN_STRIDE } from "../constants";
+import {
+  buildParticleInstances,
+  buildParticleSprite,
+} from "../draw/particleAtlas";
+import { parseColorRgb } from "../theme";
 import type { LiveChartPalette } from "../types";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 
 type DegenPack = SharedValue<Float64Array<ArrayBuffer>>;
 
 /**
- * Renders one particle slot from the packed ring buffer.
- * Buffer layout per slot (stride = DEGEN_STRIDE = 8):
- *   [0] x, [1] y, [2] vx, [3] vy, [4] t0, [5] active, [6] size, [7] colorIndex
- * See `math/degenTick.ts` for the authoritative layout documentation.
+ * Renders the degen particle burst with a single `drawAtlas` call.
  *
- * Each particle stores a `colorIndex` (set at spawn) that selects its color
- * from `colorList`, so multi-series bursts render in their own series' color.
+ * Every active particle shares one pre-rasterized white-circle sprite and
+ * differs only in position, scale, color, and opacity — the ideal `drawAtlas`
+ * case. A single per-frame worklet projects the packed ring buffer (layout:
+ * `[x, y, vx, vy, t0, active, size, colorIndex]`, stride = DEGEN_STRIDE = 8;
+ * see `math/degenTick.ts`) into transforms + per-sprite colors, replacing the
+ * old O(slots × 4 derived values + 1 `<Circle>` each) fan-out with O(1) mappers
+ * and one draw.
+ *
+ * Per-particle color/opacity is baked into the sprite color (`rgba(r,g,b,a)`)
+ * and applied with the `"modulate"` blend mode, which multiplies the white
+ * sprite by each color — so a white AA circle becomes a soft, correctly-tinted,
+ * correctly-faded particle, visually equivalent to the old `<Circle color
+ * opacity>`.
  */
-function DegenSlot({
-  index,
-  pack,
-  packRevision,
-  engine,
-  particleBurstDurationSec,
-  particleOpacity,
-  colorList,
-}: {
-  index: number;
-  pack: DegenPack;
-  packRevision: SharedValue<number>;
-  engine: ChartEngineLayout;
-  particleBurstDurationSec: number;
-  particleOpacity: number;
-  colorList: string[];
-}) {
-  const base = index * DEGEN_STRIDE;
-
-  /* istanbul ignore next -- useDerivedValue worklet runs on UI thread, not in Jest */
-  const cx = useDerivedValue(() => {
-    const rev = packRevision.value;
-    const buf = pack.value;
-    const active = buf[base + 5];
-    if (!(rev >= 0) || !(active > 0.5)) return -9999;
-    return buf[base + 0];
-  });
-
-  /* istanbul ignore next -- worklet */
-  const cy = useDerivedValue(() => {
-    const rev = packRevision.value;
-    const buf = pack.value;
-    const active = buf[base + 5];
-    if (!(rev >= 0) || !(active > 0.5)) return -9999;
-    return buf[base + 1];
-  });
-
-  /* istanbul ignore next -- worklet */
-  const r = useDerivedValue(() => {
-    const rev = packRevision.value;
-    const buf = pack.value;
-    const active = buf[base + 5];
-    if (!(rev >= 0) || !(active > 0.5)) return 0;
-    const now = engine.timestamp.value;
-    const dt = now - buf[base + 4];
-    if (dt < 0) return 0;
-    const life = Math.max(0, 1 - dt / particleBurstDurationSec);
-    const size = buf[base + 6] || 1;
-    return size * (0.5 + life * 0.5);
-  });
-
-  /* istanbul ignore next -- worklet */
-  const opacity = useDerivedValue(() => {
-    const rev = packRevision.value;
-    const buf = pack.value;
-    const active = buf[base + 5];
-    if (!(rev >= 0) || !(active > 0.5)) return 0;
-    const now = engine.timestamp.value;
-    const dt = now - buf[base + 4];
-    if (dt < 0) return 0;
-    const life = Math.max(0, 1 - dt / particleBurstDurationSec);
-    return life * particleOpacity;
-  });
-
-  /* istanbul ignore next -- worklet */
-  const color = useDerivedValue(() => {
-    // Read packRevision so this re-runs each frame — the pack buffer is mutated
-    // in place (stable reference), so without this the color would freeze at the
-    // mount-time colorIndex (0) for every particle.
-    const rev = packRevision.value;
-    const buf = pack.value;
-    if (!(rev >= 0)) return colorList[0];
-    const idx = Math.max(0, Math.floor(buf[base + 7]));
-    return colorList[idx % colorList.length];
-  });
-
-  return <Circle cx={cx} cy={cy} r={r} color={color} opacity={opacity} />;
-}
-
 export function DegenParticlesOverlay({
   pack,
   packRevision,
@@ -115,27 +54,72 @@ export function DegenParticlesOverlay({
 }) {
   /* istanbul ignore next -- branch depends on render-time props */
   const colorList = colors && colors.length > 0 ? colors : [palette.line];
-  // Fixed-size persistent slot pool. Each <DegenSlot> renders whatever particle
-  // currently occupies slot `i` (read from `pack` by index), and particles cycle
-  // through the slots over time. The pool is positional — slot `i` always renders
-  // ring-buffer index `i`, and the list only grows/shrinks at the tail, never
-  // reorders — so each slot has a permanent identity. Key by that stable per-slot
-  // id (`particle-slot-<i>`) rather than the bare array index.
-  const slotKeys = Array.from(
-    { length: particleSlotCount },
-    (_, i) => `particle-slot-${i}`,
-  );
-  const slots = slotKeys.map((slotKey, i) => (
-    <DegenSlot
-      key={slotKey}
-      index={i}
-      pack={pack}
-      packRevision={packRevision}
-      engine={engine}
-      particleBurstDurationSec={particleBurstDurationSec}
-      particleOpacity={particleOpacity}
-      colorList={colorList}
+
+  // White-circle sprite has no per-render inputs; React Compiler memoizes it.
+  const sprite = buildParticleSprite();
+
+  // Pre-parse the color list to [r,g,b] tuples so the per-frame worklet never
+  // parses arbitrary color strings (only formats `rgba(...)`). React Compiler
+  // memoizes this on `colorList`.
+  const colorRgb = colorList.map((c) => parseColorRgb(c));
+
+  // Single per-frame worklet. Reads `packRevision` so it re-runs each frame
+  // while a burst is alive (the pack buffer is mutated in place, so its
+  // reference is stable and wouldn't otherwise re-notify).
+  const atlasData = useDerivedValue(() => {
+    const rev = packRevision.get();
+    const transforms: SkRSXform[] = [];
+    const sprites: SkRect[] = [];
+    const colorsOut: SkColor[] = [];
+    if (rev >= 0) {
+      const instances = buildParticleInstances(
+        pack.get(),
+        particleSlotCount,
+        engine.timestamp.get(),
+        particleBurstDurationSec,
+        particleOpacity,
+        sprite.radius,
+      );
+      const half = sprite.size / 2;
+      for (let i = 0; i < instances.length; i++) {
+        const inst = instances[i];
+        // Center the scaled sprite on (x, y); RSXform has no rotation.
+        transforms.push(
+          Skia.RSXform(
+            inst.scale,
+            0,
+            inst.x - inst.scale * half,
+            inst.y - inst.scale * half,
+          ),
+        );
+        sprites.push(Skia.XYWHRect(0, 0, sprite.size, sprite.size));
+        const [r, g, b] = colorRgb[inst.colorIndex % colorRgb.length];
+        colorsOut.push(Skia.Color(`rgba(${r}, ${g}, ${b}, ${inst.alpha})`));
+      }
+    }
+    return { transforms, sprites, colors: colorsOut };
+  }, [
+    pack,
+    packRevision,
+    engine,
+    particleSlotCount,
+    particleBurstDurationSec,
+    particleOpacity,
+    sprite,
+    colorRgb,
+  ]);
+
+  const transforms = useDerivedValue(() => atlasData.get().transforms, [atlasData]);
+  const sprites = useDerivedValue(() => atlasData.get().sprites, [atlasData]);
+  const atlasColors = useDerivedValue(() => atlasData.get().colors, [atlasData]);
+
+  return (
+    <Atlas
+      image={sprite.image}
+      sprites={sprites}
+      transforms={transforms}
+      colors={atlasColors}
+      colorBlendMode="modulate"
     />
-  ));
-  return <Group>{slots}</Group>;
+  );
 }

package/src/components/LiveChart.tsx

@@ -19,6 +19,7 @@ import {
 
 import { DEFAULT_ACCENT_COLOR } from "../constants";
 import {
+  resolveAxisLabel,
   resolveBadge,
   resolveDegen,
   resolveDot,
@@ -28,6 +29,7 @@ import {
   resolveMetrics,
   resolvePulse,
   resolveScrub,
+  resolveSelectionDot,
   resolveTradeStream,
   resolveValueLine,
   resolveXAxis,
@@ -66,6 +68,7 @@ import {
   resolveTheme,
 } from "../theme";
 import type { LiveChartProps, Marker, TradeEvent } from "../types";
+import { AxisLabelOverlay } from "./AxisLabelOverlay";
 import { BadgeOverlay } from "./BadgeOverlay";
 import { CrosshairOverlay } from "./CrosshairOverlay";
 import { DegenParticlesOverlay } from "./DegenParticlesOverlay";
@@ -111,6 +114,8 @@ function useLiveChartController({
   timeWindow = 30,
   paused = false,
   loading = false,
+  // `static` is a reserved word — alias it so the destructure parses.
+  static: isStatic = false,
   smoothing = 0.08,
   exaggerate = false,
   nonNegative = false,
@@ -126,6 +131,8 @@ function useLiveChartController({
   // ── Overlays ────────────────────────────────────────────────────────────
   yAxis = true,
   xAxis = true,
+  topLabel,
+  bottomLabel,
   badge = true,
   momentum = true,
   pulse = true,
@@ -138,6 +145,7 @@ function useLiveChartController({
   palette: paletteOverride,
   metrics,
   scrub = true,
+  selectionDot,
   tradeStream,
   degen,
   markers,
@@ -147,6 +155,8 @@ function useLiveChartController({
 
   // ── Callbacks ───────────────────────────────────────────────────────────
   onScrub,
+  onGestureStart,
+  onGestureEnd,
   onDegenShake,
 }: LiveChartProps) {
   const emptyTradeStream = useSharedValue<TradeEvent[]>([]);
@@ -158,16 +168,23 @@ function useLiveChartController({
   // ── Resolve feature configs ────────────────────────────────────────────
   const yAxisCfg = resolveYAxis(yAxis);
   const xAxisCfg = resolveXAxis(xAxis);
+  const topLabelCfg = resolveAxisLabel(topLabel);
+  const bottomLabelCfg = resolveAxisLabel(bottomLabel);
   const badgeCfg = resolveBadge(badge);
   const scrubCfg = resolveScrub(scrub);
   const gradientCfg = isCandle ? null : resolveGradient(gradient);
   const valueLineCfg = resolveValueLine(valueLine);
-  const pulseCfg = resolvePulse(pulse);
+  // Static charts run zero loops: force the pulse off so its `withRepeat`-driven
+  // ring never starts (the DotOverlay reads `pulseCfg`, so null = no pulse).
+  const pulseCfg = isStatic ? null : resolvePulse(pulse);
   const dotCfg = resolveDot(dot);
+  const selectionDotCfg = resolveSelectionDot(selectionDot);
   // Outer footprint of the dot (color-filled radius plus the halo ring).
   const dotOuterRadius = dotCfg.radius + (dotCfg.ring?.width ?? 0);
   const gridStyleCfg = resolveGridStyle(gridStyle);
-  const degenCfg = resolveDegen(degen);
+  // Static charts run zero loops: force degen off so `useDegen`'s frame callback
+  // never starts (also passed `isStatic` below as a belt-and-braces autostart gate).
+  const degenCfg = isStatic ? null : resolveDegen(degen);
   const tradeStreamResolved = resolveTradeStream(tradeStream);
   const metricsCfg = resolveMetrics(metrics);
 
@@ -248,7 +265,7 @@ function useLiveChartController({
     candles,
   });
 
-  const reveal = useChartReveal(loading, hasData);
+  const reveal = useChartReveal(loading, hasData, isStatic);
 
   // After data clears, keep last snapshot until morphT finishes dropping (web parity).
   const { lineEngineData, candlesEngine, liveEngine } =
@@ -269,6 +286,7 @@ function useLiveChartController({
     value,
     timeWindow,
     paused,
+    static: isStatic,
     smoothing,
     adaptiveSpeedBoost: metricsCfg.motion.adaptiveSpeedBoost,
     exaggerate,
@@ -306,6 +324,7 @@ function useLiveChartController({
       candleWidth,
       isCandle,
       metricsCfg.candle,
+      !isStatic, // static: no candle-width lerp loop
     );
   const { dotX, dotY } = useLiveDot(engine, effectivePadding);
 
@@ -315,14 +334,15 @@ function useLiveChartController({
     engine,
     tradeStreamSV,
     effectivePadding,
-    tradeStreamResolved !== null,
+    !isStatic && tradeStreamResolved !== null,
+    !isStatic, // static: no trade-tape loop
   );
 
   const {
     pack: degenPack,
     packRevision: degenPackRevision,
     shakeTransform: degenShakeTransform,
-  } = useDegen(engine, dotX, dotY, momentumSV, degenCfg, onDegenShake);
+  } = useDegen(engine, dotX, dotY, momentumSV, degenCfg, onDegenShake, isStatic);
 
   // ── Overlay hooks ─────────────────────────────────────────────────────
   const { yAxisEntries } = useYAxis(
@@ -373,10 +393,13 @@ function useLiveChartController({
     formatValue,
     formatTime,
     skiaFont,
-    scrubCfg !== null,
+    // Static charts have an inert pan gesture — no scrub work on the UI thread.
+    !isStatic && scrubCfg !== null,
     onScrub,
     candleOpts,
     scrubCfg?.panGestureDelay ?? 0,
+    onGestureStart,
+    onGestureEnd,
   );
 
   const markersActive = markers != null;
@@ -386,11 +409,12 @@ function useLiveChartController({
     engine,
     effectivePadding,
     markersSV,
-    markersActive,
+    !isStatic && markersActive,
     markerHitRadius,
     onMarkerHover,
     undefined, // seriesSV — single-series has none
     engine.data, // anchor value-less markers to the line
+    !isStatic, // static: no marker-projection loop
   );
 
   const rootGesture = markersActive
@@ -403,6 +427,8 @@ function useLiveChartController({
     gradientEnd,
     gradientTopColor,
     gradientBottomColor,
+    gradientColors,
+    gradientPositions,
   } = useChartColors(
     palette,
     gradientCfg,
@@ -453,6 +479,8 @@ function useLiveChartController({
     gradientEnd,
     gradientTopColor,
     gradientBottomColor,
+    gradientColors,
+    gradientPositions,
     lineGroupOpacity,
     candleGroupOpacity,
     onLayout,
@@ -476,6 +504,12 @@ function useLiveChartController({
     rootGesture,
     markersActive,
     markersSV,
+    // selection dot: resolved config + fallback color (the chart line/accent color)
+    selectionDot: selectionDotCfg,
+    selectionColor: lineProp?.color ?? palette.line,
+    // RN axis edge labels (floated over the canvas as a sibling layer)
+    topLabelCfg,
+    bottomLabelCfg,
   };
 }
 
@@ -500,8 +534,8 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     gradientCfg,
     fillPath,
     gradientEnd,
-    gradientTopColor,
-    gradientBottomColor,
+    gradientColors,
+    gradientPositions,
     valueLineCfg,
     dotY,
     allRefLines,
@@ -555,7 +589,8 @@ function ChartStack({ model }: { model: LiveChartModel }) {
             <LinearGradient
               start={vec(0, effectivePadding.top)}
               end={vec(0, gradientEnd)}
-              colors={[gradientTopColor, gradientBottomColor]}
+              colors={gradientColors}
+              positions={gradientPositions}
             />
           </Path>
         </Group>
@@ -713,6 +748,8 @@ function ChartScrubLayer({ model }: { model: LiveChartModel }) {
     isCandle,
     pulseCfg,
     dotOuterRadius,
+    selectionDot,
+    selectionColor,
   } = model;
 
   if (!tradeStreamResolved && !scrubCfg) return null;
@@ -748,6 +785,10 @@ function ChartScrubLayer({ model }: { model: LiveChartModel }) {
           palette={palette}
           font={skiaFont}
           showTooltip={scrubCfg.tooltip}
+          selectionDot={selectionDot}
+          selectionY={crosshair.scrubDotY}
+          scrubActive={crosshair.scrubActive}
+          selectionColor={selectionColor}
           dimOpacity={scrubCfg.dimOpacity}
           liveDotExtent={liveDotExtent}
           crosshairLineColor={scrubCfg.crosshairLineColor}
@@ -834,6 +875,10 @@ export function LiveChart(props: LiveChartProps) {
     leftEdgeFadeCfg,
     effectivePadding,
     engine,
+    palette,
+    formatValue,
+    topLabelCfg,
+    bottomLabelCfg,
   } = model;
 
   return (
@@ -867,6 +912,17 @@ export function LiveChart(props: LiveChartProps) {
               its left edge (the badge tracks the live value, not the scrub). */}
           <ChartBadgeLayer model={model} />
         </Canvas>
+
+        {/* RN labels floated over the canvas (sibling of <Canvas>, an RN view).
+            Pinned to the plot's top/bottom edges via the resolved padding. */}
+        <AxisLabelOverlay
+          topLabel={topLabelCfg}
+          bottomLabel={bottomLabelCfg}
+          engine={engine}
+          formatValue={formatValue}
+          defaultColor={palette.gridLabel}
+          padding={effectivePadding}
+        />
       </View>
     </GestureDetector>
   );