react-native-livechart 3.11.0 → 4.0.0

package/src/components/LiveChartSeries.tsx

@@ -15,7 +15,11 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 import { scheduleOnRN } from "react-native-worklets";
-import { DEFAULT_ACCENT_COLOR, MAX_MULTI_SERIES } from "../constants";
+import {
+  DEFAULT_ACCENT_COLOR,
+  HOLD_TO_SCRUB_MS,
+  MAX_MULTI_SERIES,
+} from "../constants";
 import {
   lineColorsSignatureFromArray,
   lineStyleSignatureFromArray,
@@ -29,12 +33,14 @@ import {
   resolveGridStyle,
   resolveLeftEdgeFade,
   resolveLegend,
+  resolveMarkerCluster,
   resolveMetrics,
   resolveMultiSeriesDot,
   resolveScrub,
   resolveSelectionDot,
   resolveXAxis,
   resolveYAxis,
+  resolveZoom,
 } from "../core/resolveConfig";
 import { useLiveChartSeriesEngine } from "../core/useLiveChartSeriesEngine";
 import { pulseRadialOutset } from "../draw/line";
@@ -46,7 +52,10 @@ import { useCrosshairSeries } from "../hooks/useCrosshairSeries";
 import { useMarkers } from "../hooks/useMarkers";
 import { useMultiSeriesDegen } from "../hooks/useMultiSeriesDegen";
 import { useMultiSeriesLinePaths } from "../hooks/useMultiSeriesLinePaths";
+import { usePanScroll } from "../hooks/usePanScroll";
+import { usePinchZoom } from "../hooks/usePinchZoom";
 import { useMultiSeriesReverseMorphInputs } from "../hooks/useReverseMorphEngineInputs";
+import { useVisibleRange } from "../hooks/useVisibleRange";
 import { useXAxis } from "../hooks/useXAxis";
 import { useYAxis } from "../hooks/useYAxis";
 import {
@@ -137,22 +146,28 @@ function useLiveChartSeriesController({
   metrics,
   scrub = true,
   selectionDot,
+  timeScroll = false,
+  zoom = false,
   onScrub,
   onGestureStart,
   onGestureEnd,
+  onVisibleRangeChange,
+  onReachStart,
   onSeriesToggle,
   dot: dotProp,
   legend: legendProp,
   degen,
   onDegenShake,
   markers,
-  onMarkerHover,
+  onMarkerPress,
   markerHitRadius = 16,
+  markerCluster,
   renderMarker,
   leftEdgeFade = true,
 }: LiveChartSeriesProps) {
   const emptyMarkers = useSharedValue<Marker[]>([]);
   const markersSV = markers ?? emptyMarkers;
+  const markerClusterCfg = resolveMarkerCluster(markerCluster);
   const markersActive = markers != null;
   const yAxisCfg = resolveYAxis(yAxis);
   const xAxisCfg = resolveXAxis(xAxis);
@@ -160,6 +175,27 @@ function useLiveChartSeriesController({
   const bottomLabelCfg = resolveAxisLabel(bottomLabel);
   const scrubCfg = resolveScrub(scrub);
   const scrubEnabled = scrubCfg !== null;
+
+  // Time-scroll + pinch-zoom (mirrors LiveChart). LiveChartSeries has no static
+  // mode, so these gate on the props alone. `holdToScrub` requires the scrub
+  // gesture to wait for a press-and-hold so a quick drag scrolls instead — the
+  // hold delay is threaded into `useCrosshairSeries` below.
+  const timeScrollEnabled = Boolean(timeScroll);
+  const zoomCfg = resolveZoom(zoom);
+  const zoomEnabled = zoomCfg !== null;
+  const scrollGestureMode =
+    typeof timeScroll === "object"
+      ? (timeScroll.gesture ?? "holdToScrub")
+      : "holdToScrub";
+  const timeScrollHoldMs =
+    typeof timeScroll === "object" ? timeScroll.scrubHoldMs : undefined;
+  // Precedence: explicit scrubHoldMs, then scrub.panGestureDelay, then default.
+  // `||` (not `??`) skips the resolved panGestureDelay's 0 default.
+  const scrubHoldMs =
+    timeScrollEnabled && scrollGestureMode === "holdToScrub"
+      ? (timeScrollHoldMs ?? (scrubCfg?.panGestureDelay || HOLD_TO_SCRUB_MS))
+      : (scrubCfg?.panGestureDelay ?? 0);
+
   const selectionDotCfg = resolveSelectionDot(selectionDot);
   const gridStyleCfg = resolveGridStyle(gridStyle);
   const dotCfg = resolveMultiSeriesDot(dotProp);
@@ -323,7 +359,7 @@ function useLiveChartSeriesController({
     effectivePadding,
     scrubEnabled,
     onScrub,
-    scrubCfg?.panGestureDelay ?? 0,
+    scrubHoldMs,
     onGestureStart,
     onGestureEnd,
   );
@@ -336,14 +372,77 @@ function useLiveChartSeriesController({
     markersSV,
     markersActive,
     markerHitRadius,
-    onMarkerHover,
+    onMarkerPress,
     series,
+    undefined, // lineData — multi-series anchors by seriesId
+    true, // autostart
+    false, // lineLinear — per-series curve handled in projection
+    markerClusterCfg,
   );
 
-  const rootGesture = markersActive
+  // Earliest retained time across all series — clamps how far the window pans
+  // back, and the `onReachStart` reference. Falls back to the live edge (no
+  // scrollable history) so panning is a no-op.
+  const scrollMinTime = useDerivedValue(() => {
+    const s = engine.series.get();
+    let min = Infinity;
+    for (let i = 0; i < s.length; i++) {
+      const d = s[i].data;
+      if (d.length > 0 && d[0].time < min) min = d[0].time;
+    }
+    return min === Infinity ? engine.liveEdge.get() : min;
+  });
+
+  const panScrollGesture = usePanScroll({
+    engine,
+    padding: effectivePadding,
+    minTime: scrollMinTime,
+    enabled: timeScrollEnabled,
+    mode: scrollGestureMode,
+    onScrollStart: () => {
+      "worklet";
+      crosshair.scrubActive.set(false);
+    },
+  });
+
+  const pinchZoomGesture = usePinchZoom({
+    engine,
+    padding: effectivePadding,
+    minTime: scrollMinTime,
+    timeWindow,
+    enabled: zoomEnabled,
+    minTimeWindow: zoomCfg?.minTimeWindow,
+    maxTimeWindow: zoomCfg?.maxTimeWindow,
+    onZoomStart: () => {
+      "worklet";
+      crosshair.scrubActive.set(false);
+    },
+  });
+
+  useVisibleRange({
+    engine,
+    minTime: scrollMinTime,
+    onVisibleRangeChange,
+    onReachStart,
+  });
+
+  let rootGesture = markersActive
     ? Gesture.Race(crosshair.gesture, markerTapGesture)
     : crosshair.gesture;
 
+  // holdToScrub races the scrub (quick drag scrolls; press-hold scrubs);
+  // axisDrag goes first via Exclusive (fails fast outside the bottom band).
+  if (timeScrollEnabled) {
+    rootGesture =
+      scrollGestureMode === "axisDrag"
+        ? Gesture.Exclusive(panScrollGesture, rootGesture)
+        : Gesture.Race(panScrollGesture, rootGesture);
+  }
+  // Pinch runs alongside (two-finger, disjoint from the one-finger gestures).
+  if (zoomEnabled) {
+    rootGesture = Gesture.Simultaneous(rootGesture, pinchZoomGesture);
+  }
+
   const backgroundColor = `rgb(${palette.bgRgb[0]}, ${palette.bgRgb[1]}, ${palette.bgRgb[2]})`;
 
   return {
@@ -392,6 +491,7 @@ function useLiveChartSeriesController({
     rootGesture,
     markersActive,
     markersSV,
+    markerClusterCfg,
     renderMarker,
     // selection dot: resolved config + fallback color (the leading series' color)
     selectionDot: selectionDotCfg,
@@ -436,6 +536,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
     degenPackRevision,
     markersActive,
     markersSV,
+    markerClusterCfg,
     renderMarker,
     series,
     emptyText,
@@ -520,6 +621,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             ringColor={palette.badgeOuterBg}
             color={dotCfg.color}
             pulse={dotCfg.pulse}
+            viewEnd={engine.viewEnd}
           />
         </Group>
       )}
@@ -553,6 +655,7 @@ function SeriesChartStack({ model }: { model: LiveChartSeriesModel }) {
             font={skiaFont}
             series={series}
             renderMarker={renderMarker}
+            cluster={markerClusterCfg}
           />
         </Group>
       )}
@@ -665,6 +768,7 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
     bottomConnector,
     markersActive,
     markersSV,
+    markerClusterCfg,
     renderMarker,
   } = model;
 
@@ -772,6 +876,7 @@ export function LiveChartSeries(props: LiveChartSeriesProps) {
               engine={engine}
               padding={effectivePadding}
               series={series}
+              cluster={markerClusterCfg}
             />
           )}
         </View>

package/src/components/MarkerOverlay.tsx

@@ -17,8 +17,12 @@ import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import { usePathBuilder } from "../hooks/usePathBuilder";
 import {
+  BADGE_TEXT_SCALE,
   buildMarkerAtlas,
   defaultMarkerColor,
+  groupBgSig,
+  groupCountText,
+  groupGlyphSig,
   isConnectorMarker,
   markerAppearanceSig,
   type AtlasCell,
@@ -29,10 +33,15 @@ import {
   projectPoint,
   type ProjectedMarker,
 } from "../math/markers";
+import {
+  clusterMarkers,
+  type ResolvedMarkerCluster,
+} from "../math/markerCluster";
 import type {
   LiveChartPalette,
   LiveChartPoint,
   Marker,
+  MarkerRenderContext,
   SeriesConfig,
 } from "../types";
 
@@ -51,6 +60,7 @@ function ConnectorGlyph({
   padding,
   seriesSV,
   lineDataSV,
+  lineLinear,
   axisY,
 }: {
   marker: Marker;
@@ -59,6 +69,7 @@ function ConnectorGlyph({
   padding: ChartPadding;
   seriesSV?: SharedValue<SeriesConfig[]>;
   lineDataSV?: SharedValue<LiveChartPoint[]>;
+  lineLinear?: boolean;
   axisY: SharedValue<number>;
 }) {
   const { kind } = marker;
@@ -80,6 +91,7 @@ function ConnectorGlyph({
       displayMax: engine.displayMax.get(),
       series: seriesSV?.get(),
       lineData: lineDataSV?.get(),
+      lineLinear,
     }),
   );
 
@@ -148,7 +160,9 @@ export function MarkerOverlay({
   font,
   series,
   lineData,
+  lineLinear,
   renderMarker,
+  cluster,
 }: {
   markers: SharedValue<Marker[]>;
   engine: ChartEngineLayout;
@@ -159,12 +173,16 @@ export function MarkerOverlay({
   series?: SharedValue<SeriesConfig[]>;
   /** Single-series line data; anchors markers that omit `value`. */
   lineData?: SharedValue<LiveChartPoint[]>;
+  /** Single-series line is drawn linear — anchor `lineData` markers on the chord. */
+  lineLinear?: boolean;
   /**
    * When provided, markers it returns an element for are rendered as RN views by
    * `CustomMarkerOverlay` instead — so they're excluded from the atlas here to
    * avoid a (blurry) glyph drawn behind the custom element.
    */
-  renderMarker?: (marker: Marker) => unknown;
+  renderMarker?: (marker: Marker, ctx: MarkerRenderContext) => unknown;
+  /** Collision config; `"stacked"` fans/collapses co-located markers. */
+  cluster: ResolvedMarkerCluster;
 }) {
   // Seed from the current markers at mount; the reaction below keeps it in sync.
   const [snapshot, setSnapshot] = useState<Marker[]>(() => markers.get().slice());
@@ -192,7 +210,15 @@ export function MarkerOverlay({
     let k = "";
     for (let i = 0; i < snapshot.length; i++) {
       const m = snapshot[i];
-      if (renderMarker(m) != null) k += `${m.id}\x1f`;
+      // Detection ctx (an element-vs-null result must not depend on cluster
+      // state — see CustomMarkerOverlay); the live ctx is applied there.
+      const ctx: MarkerRenderContext = {
+        index: i,
+        isGrouped: false,
+        groupCount: 0,
+        side: m.side ?? "center",
+      };
+      if (renderMarker(m, ctx) != null) k += `${m.id}\x1f`;
     }
     return k;
   }, [snapshot, renderMarker]);
@@ -219,13 +245,22 @@ export function MarkerOverlay({
   // Rasterize at the screen's device-pixel ratio so sprites stay crisp on
   // retina canvases instead of being upscaled from a logical-sized texture.
   const dpr = PixelRatio.get();
+  const clusterStacked = cluster.mode === "stacked";
   const atlas = useMemo(
-    () => buildMarkerAtlas(snapshot.filter((m) => !customIds[m.id]), palette, font, dpr),
+    () =>
+      buildMarkerAtlas(
+        snapshot.filter((m) => !customIds[m.id]),
+        palette,
+        font,
+        dpr,
+        clusterStacked,
+      ),
     // eslint-disable-next-line react-hooks/exhaustive-deps -- appearanceKey/paletteKey capture the inputs that change cell pixels
-    [appearanceKey, paletteKey, font, dpr],
+    [appearanceKey, paletteKey, font, dpr, clusterStacked],
   );
   const cells: Record<string, AtlasCell> = atlas.cells;
   const atlasImage = atlas.image;
+  const digitWidths = atlas.digitWidths;
   // Inverse of the texture's device-pixel scale; shrinks each hi-res cell back
   // to its logical on-canvas size in the per-frame blit.
   const invScale = 1 / atlas.scale;
@@ -263,16 +298,61 @@ export function MarkerOverlay({
         displayMax: engine.displayMax.get(),
         series: series?.get(),
         lineData: lineData?.get(),
+        lineLinear,
       });
+      clusterMarkers(ms, buf, { config: cluster });
       const transforms = [];
       const sprites = [];
       for (let i = 0; i < ms.length; i++) {
         const pt = buf[i];
-        if (!pt.visible) continue;
+        // Collapsed-cluster members fold into their representative's badge.
+        if (!pt.visible || pt.hidden) continue;
         const m = ms[i];
         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`.
+        if (pt.isGrouped) {
+          const repColor = m.color ?? defaultMarkerColor(m.kind, palette);
+          const text = groupCountText(pt.groupCount);
+          const bg = cells[groupBgSig(repColor)];
+          if (bg) {
+            transforms.push(
+              Skia.RSXform(invScale, 0, pt.x - bg.w / 2, pt.y - bg.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(gc.rect);
+            }
+            dx += w + kern;
+          }
+          continue;
+        }
         const cell = cells[markerAppearanceSig(m)];
         if (!cell) continue;
         // Center the cell on the projected point. The cell's source rect is in
@@ -284,7 +364,20 @@ export function MarkerOverlay({
       }
       return { transforms, sprites };
     },
-    [cells, customIds, invScale, markers, engine, padding, series, lineData],
+    [
+      cells,
+      customIds,
+      invScale,
+      digitWidths,
+      markers,
+      engine,
+      padding,
+      palette,
+      series,
+      lineData,
+      lineLinear,
+      cluster,
+    ],
   );
   const transforms = useDerivedValue(() => atlasData.get().transforms, [atlasData]);
   const sprites = useDerivedValue(() => atlasData.get().sprites, [atlasData]);
@@ -309,6 +402,7 @@ export function MarkerOverlay({
           padding={padding}
           seriesSV={series}
           lineDataSV={lineData}
+          lineLinear={lineLinear}
           axisY={axisY}
         />
       ))}

package/src/components/MultiSeriesDots.tsx

@@ -1,6 +1,6 @@
 import { Circle, Group } from "@shopify/react-native-skia";
 
-import { useDerivedValue } from "react-native-reanimated";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
 import { MAX_MULTI_SERIES } from "../constants";
 import type { ChartPadding } from "../draw/line";
 import type {
@@ -21,6 +21,7 @@ function SeriesDotAtIndex({
   ring,
   ringColor,
   pulse,
+  viewEnd,
 }: {
   index: number;
   engine: MultiEngineState;
@@ -32,6 +33,8 @@ function SeriesDotAtIndex({
   /** Fallback ring color when `ring.color` is unset (theme `badgeOuterBg`). */
   ringColor: string;
   pulse: ResolvedPulseConfig | null;
+  /** Pan/zoom right-edge override — pulse is frozen-out while scrolled back. */
+  viewEnd?: SharedValue<number | null>;
 }) {
   const dotX = useDerivedValue(() => {
     const w = engine.canvasWidth.value;
@@ -62,7 +65,9 @@ function SeriesDotAtIndex({
   });
 
   const pulseRadius = useDerivedValue(() => {
-    if (!pulse) return 0;
+    // A live heartbeat on a frozen historical point is wrong (and `timestamp` is
+    // frozen, so it wouldn't animate) — suppress the pulse while scrolled back.
+    if (!pulse || viewEnd?.value != null) return 0;
     const nowMs = engine.timestamp.value * 1000 + index * PULSE_STAGGER_MS;
     const t = (nowMs % pulse.interval) / pulse.duration;
     if (t >= 1) return 0;
@@ -70,7 +75,7 @@ function SeriesDotAtIndex({
   });
 
   const pulseOpacity = useDerivedValue(() => {
-    if (!pulse) return 0;
+    if (!pulse || viewEnd?.value != null) return 0;
     const nowMs = engine.timestamp.value * 1000 + index * PULSE_STAGGER_MS;
     const t = (nowMs % pulse.interval) / pulse.duration;
     if (t >= 1) return 0;
@@ -112,6 +117,7 @@ export function MultiSeriesDots({
   ringColor,
   color,
   pulse,
+  viewEnd,
 }: {
   engine: MultiEngineState;
   padding: ChartPadding;
@@ -124,6 +130,8 @@ export function MultiSeriesDots({
   /** Fill color override; falls back to each series' line color. */
   color: string | undefined;
   pulse: ResolvedPulseConfig | null;
+  /** Pan/zoom right-edge override — pulse is frozen-out while scrolled back. */
+  viewEnd?: SharedValue<number | null>;
 }) {
   return (
     <Group>
@@ -138,6 +146,7 @@ export function MultiSeriesDots({
           ring={ring}
           ringColor={ringColor}
           pulse={pulse}
+          viewEnd={viewEnd}
         />
       ))}
     </Group>