react-native-livechart 3.0.0 → 3.2.0

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,
@@ -289,7 +307,7 @@ function useLiveChartController({
   );
 
   // ── Per-frame derived values ───────────────────────────────────────────
-  const { layoutHeight, onLayout } = useCanvasLayout(engine);
+  const { layoutWidth, layoutHeight, onLayout } = useCanvasLayout(engine);
 
   const { linePath, fillPath } = useChartPaths(
     engine,
@@ -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,8 +479,11 @@ function useLiveChartController({
     gradientEnd,
     gradientTopColor,
     gradientBottomColor,
+    gradientColors,
+    gradientPositions,
     lineGroupOpacity,
     candleGroupOpacity,
+    layoutWidth,
     onLayout,
     linePath,
     fillPath,
@@ -476,6 +505,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 +535,8 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     gradientCfg,
     fillPath,
     gradientEnd,
-    gradientTopColor,
-    gradientBottomColor,
+    gradientColors,
+    gradientPositions,
     valueLineCfg,
     dotY,
     allRefLines,
@@ -527,6 +562,7 @@ function ChartStack({ model }: { model: LiveChartModel }) {
     markersSV,
     emptyText,
     metricsCfg,
+    layoutWidth,
   } = model;
 
   return (
@@ -555,7 +591,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>
@@ -593,10 +630,18 @@ function ChartStack({ model }: { model: LiveChartModel }) {
           path={linePath}
           style="stroke"
           strokeWidth={strokeWidth}
-          color={lineProp?.color ?? palette.line}
           strokeCap="round"
           strokeJoin="round"
-        />
+          color={lineProp?.color ?? palette.line}
+        >
+          {lineProp?.colors?.length ? (
+            <LinearGradient
+              start={vec(0, 0)}
+              end={vec(layoutWidth, 0)}
+              colors={lineProp.colors}
+            />
+          ) : null}
+        </Path>
       </Group>
 
       {/* Candle bodies/wicks (fades in in candle mode) */}
@@ -713,6 +758,8 @@ function ChartScrubLayer({ model }: { model: LiveChartModel }) {
     isCandle,
     pulseCfg,
     dotOuterRadius,
+    selectionDot,
+    selectionColor,
   } = model;
 
   if (!tradeStreamResolved && !scrubCfg) return null;
@@ -748,6 +795,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 +885,10 @@ export function LiveChart(props: LiveChartProps) {
     leftEdgeFadeCfg,
     effectivePadding,
     engine,
+    palette,
+    formatValue,
+    topLabelCfg,
+    bottomLabelCfg,
   } = model;
 
   return (
@@ -867,6 +922,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>
   );

package/src/components/LiveChartSeries.tsx

@@ -24,6 +24,7 @@ import {
   type SeriesLineStyle,
 } from "../core/multiSeriesLayout";
 import {
+  resolveAxisLabel,
   resolveDegen,
   resolveGridStyle,
   resolveLeftEdgeFade,
@@ -31,6 +32,7 @@ import {
   resolveMetrics,
   resolveMultiSeriesDot,
   resolveScrub,
+  resolveSelectionDot,
   resolveXAxis,
   resolveYAxis,
 } from "../core/resolveConfig";
@@ -60,6 +62,7 @@ import {
   resolveTheme,
 } from "../theme";
 import type { LiveChartSeriesProps, Marker, SeriesConfig } from "../types";
+import { AxisLabelOverlay } from "./AxisLabelOverlay";
 import { CrosshairLine } from "./CrosshairLine";
 import { DegenParticlesOverlay } from "./DegenParticlesOverlay";
 import { LeftEdgeFade } from "./LeftEdgeFade";
@@ -121,12 +124,17 @@ function useLiveChartSeriesController({
   formatTime = defaultFormatTime,
   yAxis = true,
   xAxis = true,
+  topLabel,
+  bottomLabel,
   referenceLines,
   gridStyle,
   palette: paletteOverride,
   metrics,
   scrub = true,
+  selectionDot,
   onScrub,
+  onGestureStart,
+  onGestureEnd,
   onSeriesToggle,
   dot: dotProp,
   legend: legendProp,
@@ -142,8 +150,11 @@ function useLiveChartSeriesController({
   const markersActive = markers != null;
   const yAxisCfg = resolveYAxis(yAxis);
   const xAxisCfg = resolveXAxis(xAxis);
+  const topLabelCfg = resolveAxisLabel(topLabel);
+  const bottomLabelCfg = resolveAxisLabel(bottomLabel);
   const scrubCfg = resolveScrub(scrub);
   const scrubEnabled = scrubCfg !== null;
+  const selectionDotCfg = resolveSelectionDot(selectionDot);
   const gridStyleCfg = resolveGridStyle(gridStyle);
   const dotCfg = resolveMultiSeriesDot(dotProp);
   // Outer footprint of a dot (the color-filled radius plus the halo ring).
@@ -307,6 +318,8 @@ function useLiveChartSeriesController({
     scrubEnabled,
     onScrub,
     scrubCfg?.panGestureDelay ?? 0,
+    onGestureStart,
+    onGestureEnd,
   );
 
   // `projected` is used internally by the hit-test gesture; the overlay
@@ -373,6 +386,12 @@ function useLiveChartSeriesController({
     rootGesture,
     markersActive,
     markersSV,
+    // selection dot: resolved config + fallback color (the leading series' color)
+    selectionDot: selectionDotCfg,
+    selectionColor: lineColors[0],
+    // RN axis edge labels (floated over the canvas as a sibling layer)
+    topLabelCfg,
+    bottomLabelCfg,
   };
 }
 
@@ -591,6 +610,11 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     palette,
     dotCfg,
     dotOuterRadius,
+    selectionDot,
+    selectionColor,
+    formatValue,
+    topLabelCfg,
+    bottomLabelCfg,
   } = model;
 
   // Extend the scrub dim past the plot's right edge to fully cover the series
@@ -647,6 +671,10 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                 engine={engine}
                 padding={effectivePadding}
                 palette={palette}
+                selectionDot={selectionDot}
+                selectionY={crosshair.scrubDotY}
+                scrubActive={crosshair.scrubActive}
+                selectionColor={selectionColor}
                 dimOpacity={scrubCfg.dimOpacity}
                 liveDotExtent={liveDotExtent}
                 crosshairLineColor={scrubCfg.crosshairLineColor}
@@ -658,6 +686,18 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
                 clips them (they track each series' live value, not the scrub). */}
             <SeriesValueLabelLayer model={model} />
           </Canvas>
+
+          {/* RN labels floated over the canvas (sibling of <Canvas>, an RN
+              view). Inside the canvas wrapper so its top/bottom edges align
+              with the plot area, not the legend row. */}
+          <AxisLabelOverlay
+            topLabel={topLabelCfg}
+            bottomLabel={bottomLabelCfg}
+            engine={engine}
+            formatValue={formatValue}
+            defaultColor={palette.gridLabel}
+            padding={effectivePadding}
+          />
         </View>
       </GestureDetector>
       {legendCfg.position === "bottom" ? legend : null}