react-native-livechart 4.2.1 → 4.4.0

package/src/core/useLiveChartSeriesEngine.ts

@@ -1,11 +1,15 @@
 import { useRef, useState } from "react";
 import {
+  cancelAnimation,
+  Easing,
+  useAnimatedReaction,
   useDerivedValue,
   useFrameCallback,
   useSharedValue,
+  withTiming,
   type SharedValue,
 } from "react-native-reanimated";
-import { MS_PER_FRAME_60FPS } from "../constants";
+import { MS_PER_FRAME_60FPS, RETURN_TO_LIVE_MS } from "../constants";
 import type { LiveChartPoint, SeriesConfig } from "../types";
 import { tickLiveChartSeriesEngineFrame } from "./liveChartSeriesEngineTick";
 import type { ChartEngineScroll, MultiEngineState } from "./useLiveChartEngine";
@@ -24,6 +28,19 @@ export interface MultiSeriesEngineConfig {
   nowOverride?: number;
   windowBuffer?: number;
   paused?: boolean;
+  /**
+   * Whether the `timeScroll` gesture is active. Flipping to `false` while scrolled
+   * back clears {@link ChartEngineScroll.viewEnd} and **glides** the window back to
+   * the live edge (eased, not an instant jump), so disabling time-scroll never
+   * strands the chart at a past position. See #164.
+   */
+  scrollEnabled?: boolean;
+  /**
+   * Duration (ms) of the return-to-live glide when {@link scrollEnabled} flips to
+   * `false` while scrolled back. `0` snaps instantly. Defaults to
+   * {@link RETURN_TO_LIVE_MS}. Resolved from `timeScroll.returnToLive`. See #164.
+   */
+  returnToLiveMs?: number;
 }
 
 export interface MultiEngineFrameRefs {
@@ -49,6 +66,10 @@ export interface MultiEngineFrameRefs {
   pausedSV: SharedValue<boolean>;
   /** Pan-scroll right-edge override (null = follow live). Optional for callers/tests. */
   viewEndSV?: SharedValue<number | null>;
+  /** "Return to live" glide progress (0→1); the right edge eases to live. Optional. */
+  returnTSV?: SharedValue<number>;
+  /** Frozen right-edge time the return glide starts from. Optional. */
+  returnFromSV?: SharedValue<number>;
   /** Pinch-zoom window-width override (null = follow timeWindow). Optional for callers/tests. */
   viewWindowSV?: SharedValue<number | null>;
   /** Receives the computed live edge each frame. Optional for callers/tests. */
@@ -137,6 +158,8 @@ export function applyLiveChartSeriesEngineFrame(
     nowSeconds: Date.now() / 1000,
     paused: sv.pausedSV.value,
     viewEnd: sv.viewEndSV?.value,
+    returnT: sv.returnTSV?.value,
+    returnFrom: sv.returnFromSV?.value,
     viewWindow: sv.viewWindowSV?.value,
   });
   sv.displayMin.value = state.displayMin;
@@ -173,6 +196,13 @@ export function useLiveChartSeriesEngine(
   const nowOverrideSV = useDerivedValue(() => config.nowOverride);
   const windowBufferSV = useDerivedValue(() => config.windowBuffer ?? 0);
   const pausedSV = useDerivedValue(() => config.paused ?? false);
+  // Whether time-scroll is active — drives the return-to-live reaction below.
+  // Defaults to enabled (legacy behavior).
+  const scrollEnabledSV = useDerivedValue(() => config.scrollEnabled ?? true);
+  // Return-to-live glide duration (ms); 0 = instant snap. Read by the reaction.
+  const returnToLiveMsSV = useDerivedValue(
+    () => config.returnToLiveMs ?? RETURN_TO_LIVE_MS,
+  );
 
   const displayMin = useSharedValue(0);
   const displayMax = useSharedValue(1);
@@ -186,6 +216,10 @@ export function useLiveChartSeriesEngine(
   // Pan-scroll state (see useLiveChartEngine). Defaults to following live.
   const viewEnd = useSharedValue<number | null>(null);
   const liveEdge = useSharedValue(initialTimestamp);
+  // "Return to live" glide (see #164) — `returnT` rests at 1; the reaction below
+  // animates it 0→1 from `returnFrom` when time-scroll is disabled while scrolled.
+  const returnT = useSharedValue(1);
+  const returnFrom = useSharedValue(0);
 
   const displaySeriesValues = useSharedValue<number[]>([]);
   const seriesOpacities = useSharedValue<number[]>([]);
@@ -235,6 +269,8 @@ export function useLiveChartSeriesEngine(
         windowBufferSV,
         pausedSV,
         viewEndSV: viewEnd,
+        returnTSV: returnT,
+        returnFromSV: returnFrom,
         viewWindowSV: viewWindow,
         liveEdgeSV: liveEdge,
         extremaMinValue,
@@ -246,6 +282,34 @@ export function useLiveChartSeriesEngine(
     );
   });
 
+  // Return the window to live when time-scroll is disabled while scrolled back
+  // (mirrors useLiveChartEngine): with a positive duration, glide — snapshot the
+  // frozen edge, clear `viewEnd`, and animate `returnT` 0→1 so the tick eases
+  // `returnFrom`→live; duration 0 just clears `viewEnd` for an instant snap.
+  // Clearing `viewEnd` also means a later re-enable resumes from live. See #164.
+  useAnimatedReaction(
+    () => scrollEnabledSV.value,
+    /* istanbul ignore next -- Reanimated reaction driven by a prop→derived change; not exercised under the SharedValue mock, verified in-app */
+    (enabled, prev) => {
+      if (prev === true && !enabled && viewEnd.value != null) {
+        const ms = returnToLiveMsSV.value;
+        if (ms > 0) {
+          returnFrom.value = viewEnd.value;
+          cancelAnimation(viewEnd);
+          viewEnd.value = null;
+          returnT.value = 0;
+          returnT.value = withTiming(1, {
+            duration: ms,
+            easing: Easing.out(Easing.cubic),
+          });
+        } else {
+          cancelAnimation(viewEnd);
+          viewEnd.value = null;
+        }
+      }
+    },
+  );
+
   return {
     data,
     value,

package/src/draw/markerAtlas.ts

@@ -10,7 +10,12 @@ import {
   type SkPaint,
   type SkRect,
 } from "@shopify/react-native-skia";
-import type { LiveChartPalette, Marker, MarkerKind } from "../types";
+import type {
+  LiveChartPalette,
+  Marker,
+  MarkerGroupBadge,
+  MarkerKind,
+} from "../types";
 
 /** Default icon box (px) when `marker.size` is unset. */
 export const DEFAULT_ICON_SIZE = 16;
@@ -37,6 +42,10 @@ export function groupGlyphSig(ch: string): string {
   return `gd\x1f${ch}`;
 }
 
+/** Atlas cell sig for a dedicated group badge (one per chart — its own custom
+ *  image/icon, independent of the member markers). */
+export const GROUP_BADGE_SIG = "grpbadge";
+
 /** Atlas cell sig for the round count-badge background (one fixed circle per color). */
 export function groupBgSig(color: string): string {
   "worklet";
@@ -362,6 +371,10 @@ export function buildMarkerAtlas(
   /** Also bake count-badge cells (digits + per-color backgrounds) for
    *  `markerCluster: "stacked"` collapse. Off by default — no atlas bloat. */
   withGroups = false,
+  /** A dedicated group badge (custom image/icon) to bake one cell for, under
+   *  {@link GROUP_BADGE_SIG} — drawn for a collapsed cluster instead of the count.
+   *  Only baked when it carries an `image` or `icon`. */
+  groupBadge?: MarkerGroupBadge,
 ): MarkerAtlas {
   const seen = new Set<string>();
   const specs: { sig: string; spec: CellSpec }[] = [];
@@ -374,6 +387,22 @@ export function buildMarkerAtlas(
     specs.push({ sig, spec: cellSpec(m, palette, font) });
   }
 
+  // Dedicated group badge: bake one cell from its custom image/icon (reusing the
+  // marker cell geometry) so a collapsed cluster can blit it like any other glyph.
+  if (groupBadge && (groupBadge.image || groupBadge.icon)) {
+    const synthetic: Marker = {
+      id: GROUP_BADGE_SIG,
+      time: 0,
+      kind: "trade",
+      image: groupBadge.image,
+      icon: groupBadge.icon,
+      color: groupBadge.color,
+      pill: groupBadge.pill,
+      size: groupBadge.size,
+    };
+    specs.push({ sig: GROUP_BADGE_SIG, spec: cellSpec(synthetic, palette, font) });
+  }
+
   // Count-badge cells: 10 uniform white digit cells shared across colors, plus one
   // fixed round background per cluster color. A collapsed group composes its number
   // (centered, ≤ 2 digits) over the circle in the same `drawAtlas`.

package/src/hooks/useMarkers.ts

@@ -28,6 +28,8 @@ const ANCHORED_CLUSTER: ResolvedMarkerCluster = {
   overlap: 0.75,
   gap: 2,
   maxBeforeGroup: 5,
+  groupBadge: "count",
+  showGroupCount: false,
 };
 
 /**

package/src/index.ts

@@ -66,6 +66,7 @@ export type {
   LiveChartSeriesProps,
   Marker,
   MarkerClusterConfig,
+  MarkerGroupBadge,
   MarkerKind,
   MarkerPressEvent,
   MarkerRenderContext,
@@ -79,6 +80,7 @@ export type {
   ReferenceLineBadgeConfig,
   ReferenceLineGroupingConfig,
   ReferenceLineRenderProps,
+  ReturnToLiveConfig,
   ScrubActionConfig,
   ScrubActionPoint,
   ScrubConfig,

package/src/math/markerCluster.ts

@@ -1,4 +1,4 @@
-import type { Marker, MarkerSide } from "../types";
+import type { Marker, MarkerGroupBadge, MarkerSide } from "../types";
 import type { ProjectedMarker } from "./markers";
 
 /**
@@ -20,6 +20,13 @@ export interface ResolvedMarkerCluster {
   gap: number;
   /** Collapse a co-located run to a single count badge once it exceeds this many. */
   maxBeforeGroup: number;
+  /** What a collapsed group draws: `"count"` = the round count badge (default);
+   *  `"marker"` = the representative marker's own glyph; a {@link MarkerGroupBadge}
+   *  = a dedicated badge (custom image/icon) independent of the members. */
+  groupBadge: "count" | "marker" | MarkerGroupBadge;
+  /** With `groupBadge: "marker"` or a dedicated badge, also stamp the member count
+   *  in the glyph's top-right corner. Ignored for `"count"`. */
+  showGroupCount: boolean;
 }
 
 export interface ClusterMarkersOpts {

package/src/types.ts

@@ -1133,6 +1133,53 @@ export interface MarkerClusterConfig {
   /** Collapse a co-located run to a single count badge once it exceeds this many.
    *  Default `5`. */
   maxBeforeGroup?: number;
+  /**
+   * What a collapsed cluster draws in place of its members:
+   *  - `"count"` (default) — the built-in round count badge (a circle with the
+   *    member count inside).
+   *  - `"marker"` — the **representative marker's own glyph** (its `image`, `icon`
+   *    /`pill`, or `kind` shape). The representative is the newest marker in the run,
+   *    so a run of buy pills collapses to a buy pill — handy when the group should
+   *    look like its members.
+   *  - {@link MarkerGroupBadge} — a **dedicated group badge you supply** (your own
+   *    Skia `image`, or an `icon`/`pill`), independent of the member markers. Use
+   *    this when the collapse should look *different* from the individual markers —
+   *    e.g. tiny dots that collapse into a distinct "Buy 5" badge image.
+   *
+   * All three are Skia-drawn in the same `drawAtlas` batch (not a `renderMarker`
+   * RN overlay). Pair any non-`"count"` form with {@link showGroupCount} for a
+   * corner count. Default `"count"`.
+   */
+  groupBadge?: "count" | "marker" | MarkerGroupBadge;
+  /**
+   * When {@link groupBadge} is `"marker"` or a {@link MarkerGroupBadge}, also stamp
+   * the member count as a small badge in the glyph's top-right corner — the
+   * "Buy **5**" look. Ignored when `groupBadge` is `"count"` (the count *is* the
+   * badge). Default `false`.
+   */
+  showGroupCount?: boolean;
+}
+
+/**
+ * A dedicated badge drawn for a collapsed marker cluster — your own Skia design,
+ * independent of the member markers. Pass it as
+ * {@link MarkerClusterConfig.groupBadge}. Glyph precedence mirrors a single marker:
+ * `image` → `icon` (`pill`) → a filled dot. Requires `image` or `icon` (otherwise
+ * the group falls back to the count badge).
+ */
+export interface MarkerGroupBadge {
+  /** Custom Skia image for the collapsed group (e.g. from `useImage`). Takes
+   *  precedence over {@link icon}. */
+  image?: SkImage;
+  /** Text / emoji glyph for the collapsed group (used when {@link image} is unset).
+   *  Rendered with the chart font. */
+  icon?: string;
+  /** Color of the `icon` (and its `pill`). Defaults to a palette accent. */
+  color?: string;
+  /** Wrap the `icon` in a filled circular badge in {@link color} (icon drawn white). */
+  pill?: boolean;
+  /** Glyph box size in px (icon font size, or image width+height). Default `16`. */
+  size?: number;
 }
 
 /** Context passed to `renderMarker` alongside the marker (cluster / position state). */
@@ -1492,6 +1539,22 @@ export interface TimeScrollConfig {
   scrubHoldMs?: number;
 }
 
+/**
+ * Tunes the "return to live" glide — the eased animation that carries the window
+ * back to the live edge when `timeScroll` is switched off while scrolled back. See
+ * {@link TimeScrollConfig.returnToLive}.
+ *
+ * @experimental
+ */
+export interface ReturnToLiveConfig {
+  /**
+   * Glide duration in milliseconds. Default `450`. The window decelerates onto the
+   * live edge (ease-out cubic). Lower = snappier; `0` is treated as no animation
+   * (an instant snap).
+   */
+  duration?: number;
+}
+
 /**
  * Pinch-to-zoom the visible time window (see {@link LiveChartCoreProps.zoom}).
  *
@@ -1683,6 +1746,11 @@ export interface LiveChartCoreProps {
    * live edge again. One-finger plot-area scrub is unchanged. Requires retained
    * history in `data` / `candles` to scroll into.
    *
+   * Setting this back to `false` while scrolled back — or switching `mode` so it's
+   * no longer passed — **glides** the window back to the live edge (a brief eased
+   * animation, not an instant jump); it never stays frozen at the previous scroll
+   * position. Tune or disable that glide with {@link returnToLive}.
+   *
    * `true` uses the default drag-to-scroll gesture (`"holdToScrub"`); pass a
    * {@link TimeScrollConfig} to pick the activation (`"holdToScrub"` or
    * `"axisDrag"`). Default `false`.
@@ -1690,6 +1758,22 @@ export interface LiveChartCoreProps {
    * @experimental Prototype — gesture model and API may change.
    */
   timeScroll?: boolean | TimeScrollConfig;
+  /**
+   * Controls the **return-to-live glide** — the animation that carries the window
+   * back to the live edge when {@link timeScroll} is switched off (set to `false`,
+   * or a `mode` switch stops passing it) while scrolled back into history:
+   *  - `true` (default) — glide back, easing onto the live edge over `450` ms.
+   *  - `false` — snap instantly, no animation.
+   *  - {@link ReturnToLiveConfig} — glide with a custom `{ duration }` (ms).
+   *
+   * Kept separate from {@link timeScroll} on purpose: the common way to leave
+   * time-scroll (`timeScroll={false}`) discards any `TimeScrollConfig`, so this
+   * lives alongside it to stay in effect through the toggle. Only governs that
+   * programmatic return; a finger fling back to live keeps its own inertia.
+   *
+   * @experimental
+   */
+  returnToLive?: boolean | ReturnToLiveConfig;
   /**
    * Pinch-to-zoom the visible time window. Two-finger pinch in/out narrows or
    * widens the window, anchored at the focal point between your fingers. Composes