react-native-livechart 4.3.0 → 4.5.0

package/src/components/LiveChartSeries.tsx

@@ -6,12 +6,14 @@
  */
 import { Canvas, Group } from "@shopify/react-native-skia";
 import { useLayoutEffect, useState } from "react";
-import { View } from "react-native";
+import { StyleSheet, View } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
-import {
+import Animated, {
   useAnimatedReaction,
+  useAnimatedStyle,
   useDerivedValue,
   useSharedValue,
+  withTiming,
   type SharedValue,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
@@ -19,6 +21,7 @@ import {
   DEFAULT_ACCENT_COLOR,
   HOLD_TO_SCRUB_MS,
   MAX_MULTI_SERIES,
+  SCRUB_OVERLAY_FADE_MS,
 } from "../constants";
 import {
   lineColorsSignatureFromArray,
@@ -33,12 +36,14 @@ import {
   resolveGridStyle,
   resolveLeftEdgeFade,
   resolveLegend,
+  resolveLoading,
   resolveMarkerCluster,
   resolveMetrics,
   resolveMultiSeriesDot,
   resolveReturnToLiveMs,
   resolveScrub,
   resolveSelectionDot,
+  resolveTransitions,
   resolveXAxis,
   resolveYAxis,
   resolveZoom,
@@ -126,6 +131,7 @@ function useLiveChartSeriesController({
   timeWindow = 30,
   paused = false,
   loading = false,
+  transitions,
   smoothing = 0.08,
   exaggerate = false,
   nonNegative = false,
@@ -289,7 +295,18 @@ function useLiveChartSeriesController({
     return false;
   });
 
-  const reveal = useChartReveal(loading, hasData);
+  // Resolve the loading shell: null = not loading, else the styled config.
+  const loadingCfg = resolveLoading(loading);
+  const loadingActive = loadingCfg !== null;
+  // Multi-series is always lines, so only the reveal transition applies (no
+  // candle↔line crossfade); `transitions.mode` is accepted but inert here.
+  const transitionsCfg = resolveTransitions(transitions);
+  const reveal = useChartReveal(
+    loadingActive,
+    hasData,
+    false,
+    transitionsCfg.reveal,
+  );
 
   const effectiveSeries = useMultiSeriesReverseMorphInputs({
     series,
@@ -453,6 +470,23 @@ function useLiveChartSeriesController({
 
   const backgroundColor = `rgb(${palette.bgRgb[0]}, ${palette.bgRgb[1]}, ${palette.bgRgb[2]})`;
 
+  // Fade markers + reference lines out while scrubbing when
+  // `scrub.hideOverlaysOnScrub` is set. Eased off the scrub-ACTIVE flag (not the
+  // crosshair edge fade, which would resurface them near the live dot); only a
+  // group opacity animates — the overlay draws stay intact. See `LiveChart`.
+  const fadeOverlaysOnScrub =
+    scrubCfg !== null && scrubCfg.hideOverlaysOnScrub === true;
+  const overlayScrubFade = useDerivedValue(() =>
+    fadeOverlaysOnScrub
+      ? withTiming(crosshair.scrubActive.get() ? 0 : 1, {
+          duration: SCRUB_OVERLAY_FADE_MS,
+        })
+      : 1,
+  );
+  const markerGroupOpacity = useDerivedValue(
+    () => reveal.dotOpacity.get() * overlayScrubFade.get(),
+  );
+
   return {
     // passthrough props the render needs
     series,
@@ -484,6 +518,11 @@ function useLiveChartSeriesController({
     // engine + reveal
     engine,
     reveal,
+    // loading shell styling (null → not loading)
+    loadingLineColor: loadingCfg?.color,
+    loadingStrokeWidth: loadingCfg?.strokeWidth,
+    loadingAmplitude: loadingCfg?.amplitude,
+    loadingSpeed: loadingCfg?.speed,
     effectiveSeries,
     layoutHeight,
     onLayout,
@@ -500,6 +539,8 @@ function useLiveChartSeriesController({
     markersActive,
     markersSV,
     markerClusterCfg,
+    markerGroupOpacity,
+    overlayScrubFade,
     renderMarker,
     // selection dot: resolved config + fallback color (the leading series' color)
     selectionDot: selectionDotCfg,
@@ -545,10 +586,16 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     markersActive,
     markersSV,
     markerClusterCfg,
+    markerGroupOpacity,
+    overlayScrubFade,
     renderMarker,
     series,
     emptyText,
     metricsCfg,
+    loadingLineColor,
+    loadingStrokeWidth,
+    loadingAmplitude,
+    loadingSpeed,
   } = model;
 
   return (
@@ -570,18 +617,21 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
 
       {/* Index keys: reference lines are a positional array and two may share
           value + label (e.g. duplicate working orders at the same price), which a
-          content-derived key would collapse to one. */}
-      {allRefLines.map((rl, i) => (
-        <ReferenceLineOverlay
-          key={i}
-          engine={engine}
-          padding={effectivePadding}
-          line={rl}
-          palette={palette}
-          formatValue={formatValue}
-          font={skiaFont}
-        />
-      ))}
+          content-derived key would collapse to one. Fade group lets
+          `scrub.hideOverlaysOnScrub` ease the lines out while scrubbing. */}
+      <Group opacity={overlayScrubFade}>
+        {allRefLines.map((rl, i) => (
+          <ReferenceLineOverlay
+            key={i}
+            engine={engine}
+            padding={effectivePadding}
+            line={rl}
+            palette={palette}
+            formatValue={formatValue}
+            font={skiaFont}
+          />
+        ))}
+      </Group>
 
       {dotCfg.valueLine && (
         <Group opacity={reveal.lineOpacity}>
@@ -654,7 +704,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
       )}
 
       {markersActive && (
-        <Group opacity={reveal.dotOpacity}>
+        <Group opacity={markerGroupOpacity}>
           <MarkerOverlay
             markers={markersSV}
             engine={engine}
@@ -680,6 +730,10 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
         strokeWidth={strokeWidth}
         badge={false}
         emptyMetrics={metricsCfg.emptyState}
+        lineColor={loadingLineColor}
+        lineStrokeWidth={loadingStrokeWidth}
+        waveAmplitude={loadingAmplitude}
+        waveSpeed={loadingSpeed}
       />
     </Group>
   );
@@ -726,10 +780,11 @@ function SeriesRefBadgeLayer({ model }: { model: LiveChartSeriesModel }) {
     formatValue,
     skiaFont,
     degenShakeTransform,
+    overlayScrubFade,
   } = model;
   if (allRefLines.length === 0) return null;
   return (
-    <Group transform={degenShakeTransform}>
+    <Group transform={degenShakeTransform} opacity={overlayScrubFade}>
       {allRefLines.map((rl, i) => (
         <ReferenceLineOverlay
           key={i}
@@ -778,8 +833,15 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     markersSV,
     markerClusterCfg,
     renderMarker,
+    overlayScrubFade,
   } = model;
 
+  // Mirror the Skia overlay fade onto the RN custom-marker sibling so
+  // `scrub.hideOverlaysOnScrub` hides it with the Skia markers.
+  const overlayFadeStyle = useAnimatedStyle(() => ({
+    opacity: overlayScrubFade.get(),
+  }));
+
   // Extend the scrub dim past the plot's right edge to fully cover the series
   // dots (with their halo) and pulse rings, all centered on that edge. The
   // gutter reserves room beyond this for the value/Y-axis labels, drawn on top.
@@ -876,16 +938,23 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
           />
 
           {/* Custom-rendered markers — RN views floated over the canvas
-              (non-Skia), pinned to each marker's live position. */}
+              (non-Skia), pinned to each marker's live position. Box-none fade
+              wrapper so `scrub.hideOverlaysOnScrub` hides them with the Skia
+              markers (full-bleed; children keep their own absolute positions). */}
           {markersActive && renderMarker && (
-            <CustomMarkerOverlay
-              markers={markersSV}
-              renderMarker={renderMarker}
-              engine={engine}
-              padding={effectivePadding}
-              series={series}
-              cluster={markerClusterCfg}
-            />
+            <Animated.View
+              pointerEvents="box-none"
+              style={[StyleSheet.absoluteFill, overlayFadeStyle]}
+            >
+              <CustomMarkerOverlay
+                markers={markersSV}
+                renderMarker={renderMarker}
+                engine={engine}
+                padding={effectivePadding}
+                series={series}
+                cluster={markerClusterCfg}
+              />
+            </Animated.View>
           )}
         </View>
       </GestureDetector>

package/src/components/LoadingOverlay.tsx

@@ -62,6 +62,10 @@ export function LoadingOverlay({
   badgeTail = true,
   badgeMetrics = BADGE_METRICS_DEFAULTS,
   emptyMetrics = EMPTY_STATE_METRICS_DEFAULTS,
+  lineColor,
+  lineStrokeWidth,
+  waveAmplitude = 14,
+  waveSpeed = 1,
 }: {
   engine: ChartEngineLayout;
   padding: ChartPadding;
@@ -73,6 +77,14 @@ export function LoadingOverlay({
   isEmpty: SharedValue<boolean> | { value: boolean };
   emptyText: string;
   strokeWidth: number;
+  /** Loading squiggle + skeleton color. Omit → theme `gridLine`. */
+  lineColor?: string;
+  /** Loading squiggle stroke width. Omit → `strokeWidth`. */
+  lineStrokeWidth?: number;
+  /** Breathing-wave base amplitude (px). */
+  waveAmplitude?: number;
+  /** Breathing-wave speed multiplier. */
+  waveSpeed?: number;
   /** Mirror the badge prop so labels align with GridOverlay's label positions. */
   badge?: boolean;
   /** Whether the badge tail spike is shown; affects the left inset used for skeleton alignment. */
@@ -86,6 +98,11 @@ export function LoadingOverlay({
   const leftInset =
     badgeMetrics.dotGap + badgeTailAndCap(font.getSize(), badgeTail, badgeMetrics);
 
+  // Loading-shell color (squiggle + skeleton placeholders) and squiggle stroke,
+  // both overridable via `loading={{ color, strokeWidth }}`.
+  const loadingColor = lineColor ?? palette.gridLine;
+  const loadingStroke = lineStrokeWidth ?? strokeWidth;
+
   // Squiggly path — built into a reused PathBuilder and detach()-ed each frame.
   const squigglyBuilder = usePathBuilder();
 
@@ -100,6 +117,8 @@ export function LoadingOverlay({
       engine.canvasHeight.get(),
       padding,
       engine.timestamp.get(),
+      waveAmplitude,
+      waveSpeed,
     );
     return buildSplineDetached(b, pts);
   });
@@ -225,8 +244,8 @@ export function LoadingOverlay({
       <Path
         path={squigglyPath}
         style="stroke"
-        strokeWidth={strokeWidth}
-        color={palette.gridLine}
+        strokeWidth={loadingStroke}
+        color={loadingColor}
         strokeCap="round"
         strokeJoin="round"
       />
@@ -255,7 +274,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
       <RoundedRect
         x={lx}
@@ -263,7 +282,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
       <RoundedRect
         x={lx}
@@ -271,7 +290,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
       <RoundedRect
         x={lx}
@@ -279,7 +298,7 @@ export function LoadingOverlay({
         width={RECT_W}
         height={RECT_H}
         r={RECT_R}
-        color={palette.gridLine}
+        color={loadingColor}
       />
 
       {/* Empty state label */}

package/src/components/MarkerOverlay.tsx

@@ -4,6 +4,8 @@ import {
   Path,
   Skia,
   type SkFont,
+  type SkRect,
+  type SkRSXform,
 } from "@shopify/react-native-skia";
 import { useMemo, useRef, useState } from "react";
 import { PixelRatio } from "react-native";
@@ -20,6 +22,7 @@ import {
   BADGE_TEXT_SCALE,
   buildMarkerAtlas,
   defaultMarkerColor,
+  GROUP_BADGE_SIG,
   groupBgSig,
   groupCountText,
   groupGlyphSig,
@@ -47,6 +50,77 @@ import type {
 
 const OFF = -9999;
 
+/** Size of the `showGroupCount` corner badge relative to a full count badge. */
+const GROUP_CORNER_SCALE = 0.62;
+/** How far the corner count badge sits toward the glyph's top-right corner
+ *  (1 = centered exactly on the corner; < 1 pulls it inward). */
+const GROUP_CORNER_INSET = 0.82;
+
+/**
+ * Append a collapsed-cluster count badge (round bg + centered, proportionally
+ * kerned digits) to the atlas blit lists at `(cx, cy)`, scaled by `mul` — full
+ * size as the default group badge, shrunk in a glyph's corner for `showGroupCount`.
+ *
+ * A **module-level** worklet (not a closure inside the per-frame derived value):
+ * the `transforms` / `sprites` arrays are passed in by reference so the pushes land
+ * on the real per-frame lists. A nested `"worklet"` closure would capture them by
+ * serialized copy, so its pushes would be silently dropped and the badge never drawn.
+ */
+function pushGroupCountBadge(
+  transforms: SkRSXform[],
+  sprites: SkRect[],
+  cells: Record<string, AtlasCell>,
+  digitWidths: Record<string, number>,
+  invScale: number,
+  cx: number,
+  cy: number,
+  repColor: string,
+  count: number,
+  mul: number,
+): void {
+  "worklet";
+  const text = groupCountText(count);
+  const bg = cells[groupBgSig(repColor)];
+  if (bg) {
+    transforms.push(
+      Skia.RSXform(invScale * mul, 0, cx - (bg.w * mul) / 2, cy - (bg.h * mul) / 2),
+    );
+    sprites.push(bg.rect);
+  }
+  // Lay digits out proportionally (each by its own ink width), scaled to fit the
+  // small round badge, centered. A negative kern (fraction of a digit) closes the
+  // font's side-bearing gap so "12" reads tight, not "1 2".
+  const S = BADGE_TEXT_SCALE;
+  let maxDW = 1;
+  for (let d = 0; d < 10; d++) {
+    const dw = digitWidths["" + d] ?? 0;
+    if (dw > maxDW) maxDW = dw;
+  }
+  const kern = -maxDW * S * 0.42;
+  let totalW = 0;
+  for (let c = 0; c < text.length; c++) {
+    totalW += (digitWidths[text[c]] ?? 0) * S + (c > 0 ? kern : 0);
+  }
+  let dx = cx - (totalW * mul) / 2;
+  for (let c = 0; c < text.length; c++) {
+    const w = (digitWidths[text[c]] ?? 0) * S * mul;
+    const gc = cells[groupGlyphSig(text[c])];
+    if (gc) {
+      const gcx = dx + w / 2;
+      transforms.push(
+        Skia.RSXform(
+          invScale * S * mul,
+          0,
+          gcx - (gc.w * S * mul) / 2,
+          cy - (gc.h * S * mul) / 2,
+        ),
+      );
+      sprites.push(gc.rect);
+    }
+    dx += w + kern * mul;
+  }
+}
+
 /**
  * Self-projecting fallback for the axis-anchored kinds (graduation stem + flag,
  * clawback box) that can't be fixed-size atlas sprites. Rare, so the per-glyph
@@ -246,6 +320,14 @@ export function MarkerOverlay({
   // retina canvases instead of being upscaled from a logical-sized texture.
   const dpr = PixelRatio.get();
   const clusterStacked = cluster.mode === "stacked";
+  // A dedicated group badge (object form) bakes one extra atlas cell; its image
+  // identity + styling drive the rebuild key alongside the marker appearances.
+  const groupBadgeCfg =
+    typeof cluster.groupBadge === "object" ? cluster.groupBadge : undefined;
+  const groupBadgeImage = groupBadgeCfg?.image;
+  const groupBadgeKey = groupBadgeCfg
+    ? `${groupBadgeCfg.icon ?? ""}|${groupBadgeCfg.color ?? ""}|${groupBadgeCfg.pill ? 1 : 0}|${groupBadgeCfg.size ?? ""}`
+    : "";
   const atlas = useMemo(
     () =>
       buildMarkerAtlas(
@@ -254,9 +336,10 @@ export function MarkerOverlay({
         font,
         dpr,
         clusterStacked,
+        groupBadgeCfg,
       ),
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- appearanceKey/paletteKey capture the inputs that change cell pixels
-    [appearanceKey, paletteKey, font, dpr, clusterStacked],
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- appearanceKey/paletteKey/groupBadgeKey capture the inputs that change cell pixels
+    [appearanceKey, paletteKey, font, dpr, clusterStacked, groupBadgeKey, groupBadgeImage],
   );
   const cells: Record<string, AtlasCell> = atlas.cells;
   const atlasImage = atlas.image;
@@ -301,8 +384,8 @@ export function MarkerOverlay({
         lineLinear,
       });
       clusterMarkers(ms, buf, { config: cluster });
-      const transforms = [];
-      const sprites = [];
+      const transforms: SkRSXform[] = [];
+      const sprites: SkRect[] = [];
       for (let i = 0; i < ms.length; i++) {
         const pt = buf[i];
         // Collapsed-cluster members fold into their representative's badge.
@@ -311,46 +394,61 @@ export function MarkerOverlay({
         if (isConnectorMarker(m)) continue;
         // Custom-rendered markers are floated as RN views, not drawn here.
         if (customIds[m.id]) continue;
-        // Collapsed cluster: draw a count badge (bg stadium + composed digits)
-        // instead of the marker's own glyph, all within this one `drawAtlas`.
+        // Collapsed cluster. By default a round count badge; with
+        // `groupBadge: "marker"` the representative marker's own glyph, or with a
+        // `MarkerGroupBadge` object a dedicated baked badge — either optionally
+        // carrying a corner count, all within this one `drawAtlas`.
         if (pt.isGrouped) {
           const repColor = m.color ?? defaultMarkerColor(m.kind, palette);
-          const text = groupCountText(pt.groupCount);
-          const bg = cells[groupBgSig(repColor)];
-          if (bg) {
+          const gb = cluster.groupBadge;
+          // Pick the non-count glyph cell: a dedicated group badge (object form)
+          // or the representative marker's own appearance.
+          const glyphCell =
+            typeof gb === "object" && gb !== null
+              ? cells[GROUP_BADGE_SIG]
+              : gb === "marker"
+                ? cells[markerAppearanceSig(m)]
+                : undefined;
+          if (glyphCell) {
             transforms.push(
-              Skia.RSXform(invScale, 0, pt.x - bg.w / 2, pt.y - bg.h / 2),
+              Skia.RSXform(
+                invScale,
+                0,
+                pt.x - glyphCell.w / 2,
+                pt.y - glyphCell.h / 2,
+              ),
             );
-            sprites.push(bg.rect);
-          }
-          // Lay the digits out proportionally (each by its own ink width), scaled
-          // down to fit the small round badge, and center the whole number. A
-          // negative kern (fraction of a digit) closes the font's side-bearing gap
-          // so "12" reads tight, not "1 2".
-          const S = BADGE_TEXT_SCALE;
-          let maxDW = 1;
-          for (let d = 0; d < 10; d++) {
-            const dw = digitWidths["" + d] ?? 0;
-            if (dw > maxDW) maxDW = dw;
-          }
-          const kern = -maxDW * S * 0.42;
-          let totalW = 0;
-          for (let c = 0; c < text.length; c++) {
-            totalW += (digitWidths[text[c]] ?? 0) * S + (c > 0 ? kern : 0);
-          }
-          let dx = pt.x - totalW / 2;
-          for (let c = 0; c < text.length; c++) {
-            const w = (digitWidths[text[c]] ?? 0) * S;
-            const gc = cells[groupGlyphSig(text[c])];
-            if (gc) {
-              const cx = dx + w / 2;
-              transforms.push(
-                Skia.RSXform(invScale * S, 0, cx - (gc.w * S) / 2, pt.y - (gc.h * S) / 2),
+            sprites.push(glyphCell.rect);
+            if (cluster.showGroupCount) {
+              pushGroupCountBadge(
+                transforms,
+                sprites,
+                cells,
+                digitWidths,
+                invScale,
+                pt.x + (glyphCell.w / 2) * GROUP_CORNER_INSET,
+                pt.y - (glyphCell.h / 2) * GROUP_CORNER_INSET,
+                repColor,
+                pt.groupCount,
+                GROUP_CORNER_SCALE,
               );
-              sprites.push(gc.rect);
             }
-            dx += w + kern;
+            continue;
           }
+          // Default — or fall back here when a non-count badge has no baked cell
+          // (e.g. an empty group-badge config): the round count badge.
+          pushGroupCountBadge(
+            transforms,
+            sprites,
+            cells,
+            digitWidths,
+            invScale,
+            pt.x,
+            pt.y,
+            repColor,
+            pt.groupCount,
+            1,
+          );
           continue;
         }
         const cell = cells[markerAppearanceSig(m)];

package/src/constants.ts

@@ -31,6 +31,23 @@ export const HOLD_TO_SCRUB_MS = 500;
  */
 export const RETURN_TO_LIVE_MS = 450;
 
+/**
+ * Duration (ms) of the fade applied to annotation overlays (markers + reference
+ * lines) when `scrub.hideOverlaysOnScrub` is on — how long they take to ease out as a
+ * scrub starts and back in on release. Driven by the scrub-active flag, eased on
+ * the UI thread. Shared by `LiveChart` and `LiveChartSeries`.
+ */
+export const SCRUB_OVERLAY_FADE_MS = 150;
+
+/**
+ * Base wave amplitude (px) of the breathing loading squiggle — it breathes
+ * between `0.4×` and `1.0×` this. Overridable via `loading={{ amplitude }}`.
+ */
+export const LOADING_WAVE_AMPLITUDE = 14;
+
+/** Default breathing-wave speed multiplier (`1` = built-in cadence). */
+export const LOADING_WAVE_SPEED = 1;
+
 // ─── Metric default tokens (single source of truth for LiveChartMetrics) ─────
 // The resolved `metrics` config (see resolveMetrics) is assembled from these
 // objects. Draw/worklet helpers default their metric params to the matching