react-native-livechart 3.11.0 → 4.0.0

package/src/math/markers.ts

@@ -1,4 +1,5 @@
 import type { LiveChartPoint, Marker, SeriesConfig } from "../types";
+import { interpolateAtTime } from "./interpolate";
 import { splineValueAtTime } from "./spline";
 
 /** Screen-space position for one marker, index-aligned with the marker array. */
@@ -6,6 +7,16 @@ export interface ProjectedMarker {
   x: number;
   y: number;
   visible: boolean;
+  /** Collapsed cluster member that the representative stands in for — not drawn,
+   *  not hit-tested. Set by the cluster pass; `false` outside `markerCluster`. */
+  hidden: boolean;
+  /** This marker is the representative (count badge) of a collapsed cluster. */
+  isGrouped: boolean;
+  /** Size of the collapsed cluster this marker represents (`0` when not grouped). */
+  groupCount: number;
+  /** Index of the cluster's representative marker for collapsed members (and the
+   *  representative itself), else `-1`. Used to gather members on tap. */
+  groupRep: number;
 }
 
 export interface ProjectMarkersOpts {
@@ -23,6 +34,11 @@ export interface ProjectMarkersOpts {
   series?: SeriesConfig[];
   /** Single-series line data; anchors markers that omit `value` (and `seriesId`). */
   lineData?: LiveChartPoint[];
+  /** When the single-series line is drawn with `line.curve === "linear"`, anchor
+   *  `lineData` markers on the straight chord (linear interpolation) instead of the
+   *  monotone spline so the glyph sits exactly on the rendered line. Multi-series
+   *  markers read their curve per-series from {@link SeriesConfig.curve}. */
+  lineLinear?: boolean;
 }
 
 /** How far off-chart (px) a marker may sit before it is culled. */
@@ -41,6 +57,12 @@ function projectInto(
   target: ProjectedMarker,
 ): void {
   "worklet";
+  // Reset cluster fields so a reused buffer slot defaults to un-clustered; the
+  // cluster pass (when it runs) overwrites them. Lets anchored mode skip the pass.
+  target.hidden = false;
+  target.isGrouped = false;
+  target.groupCount = 0;
+  target.groupRep = -1;
   const w = opts.canvasWidth;
   const h = opts.canvasHeight;
   const chartLeft = opts.padLeft;
@@ -66,16 +88,23 @@ function projectInto(
   } else if (seriesId !== undefined && opts.series) {
     for (let j = 0; j < opts.series.length; j++) {
       if (opts.series[j].id === seriesId) {
-        // Evaluate the rendered spline (not the linear chord) so the glyph sits
-        // exactly on the curve between data points.
-        v = splineValueAtTime(opts.series[j].data, time);
+        // Anchor on the same interpolation the series is rendered with, so the
+        // glyph sits exactly on the line: the linear chord for `curve: "linear"`,
+        // the monotone spline otherwise.
+        v =
+          opts.series[j].curve === "linear"
+            ? interpolateAtTime(opts.series[j].data, time)
+            : splineValueAtTime(opts.series[j].data, time);
         break;
       }
     }
   } else if (opts.lineData) {
-    // Single-series anchor: omit `value` to pin the marker to the line at `time`
-    // (on the rendered spline curve, not the linear chord between points).
-    v = splineValueAtTime(opts.lineData, time);
+    // Single-series anchor: omit `value` to pin the marker to the line at `time`.
+    // Match the rendered curve — straight chord when `line.curve === "linear"`,
+    // the monotone spline otherwise.
+    v = opts.lineLinear
+      ? interpolateAtTime(opts.lineData, time)
+      : splineValueAtTime(opts.lineData, time);
   }
   if (v === null) {
     target.visible = false;
@@ -108,7 +137,15 @@ export function projectMarkers(
   for (let i = 0; i < markers.length; i++) {
     let cur = out[i];
     if (!cur) {
-      cur = { x: 0, y: 0, visible: false };
+      cur = {
+        x: 0,
+        y: 0,
+        visible: false,
+        hidden: false,
+        isGrouped: false,
+        groupCount: 0,
+        groupRep: -1,
+      };
       out[i] = cur;
     }
     const m = markers[i];
@@ -129,7 +166,15 @@ export function projectPoint(
   opts: ProjectMarkersOpts,
 ): ProjectedMarker {
   "worklet";
-  const target: ProjectedMarker = { x: 0, y: 0, visible: false };
+  const target: ProjectedMarker = {
+    x: 0,
+    y: 0,
+    visible: false,
+    hidden: false,
+    isGrouped: false,
+    groupCount: 0,
+    groupRep: -1,
+  };
   projectInto(time, value, seriesId, opts, target);
   return target;
 }
@@ -162,7 +207,7 @@ export function nearestMarkerIndex(
   let bestD = radius * radius;
   for (let i = 0; i < positions.length; i++) {
     const p = positions[i];
-    if (!p.visible) continue;
+    if (!p.visible || p.hidden) continue;
     const dx = p.x - x;
     const dy = p.y - y;
     const d = dx * dx + dy * dy;

package/src/math/referenceDrag.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure, worklet-safe helpers for dragging a Form-A reference line along the
+ * Y-axis. Kept free of hooks / SharedValues so they unit-test without Reanimated
+ * (the gesture wiring lives in {@link useReferenceDrag}).
+ */
+
+/** Clamp a value to an optional `[min, max]` bound (order-independent). No-op when
+ *  `bounds` is omitted. */
+export function clampToBounds(
+  value: number,
+  bounds?: [number, number],
+): number {
+  "worklet";
+  if (!bounds) return value;
+  const lo = Math.min(bounds[0], bounds[1]);
+  const hi = Math.max(bounds[0], bounds[1]);
+  return Math.min(hi, Math.max(lo, value));
+}
+
+/**
+ * Index of the draggable line whose handle-Y is nearest the touch `y`, within
+ * `slop` px — or `-1` when none is in reach. `handleYs` is index-aligned with the
+ * chart's `referenceLines`; entries `< 0` (not draggable / off-screen / not laid
+ * out) are skipped. Ties favor the later (topmost-drawn) line.
+ */
+export function nearestDraggableIndex(
+  handleYs: number[],
+  y: number,
+  slop: number,
+): number {
+  "worklet";
+  let best = -1;
+  let bestDist = slop;
+  for (let i = 0; i < handleYs.length; i++) {
+    const hy = handleYs[i];
+    if (hy < 0) continue;
+    const d = Math.abs(hy - y);
+    if (d <= bestDist) {
+      bestDist = d;
+      best = i;
+    }
+  }
+  return best;
+}
+
+/**
+ * Whether a line's value sits **outside** its watched interval — the trigger for
+ * `onDragOut` / `onDragIn` (edge-detected by the caller). When `bounds` is set the
+ * watched interval is `bounds` (at-or-past a bound counts as out, since the drag
+ * clamps there); otherwise it's the visible `[min, max]` Y-range (out = scrolled /
+ * dragged off-screen).
+ */
+export function referenceValueOut(
+  value: number,
+  min: number,
+  max: number,
+  bounds?: [number, number],
+): boolean {
+  "worklet";
+  if (bounds) {
+    const lo = Math.min(bounds[0], bounds[1]);
+    const hi = Math.max(bounds[0], bounds[1]);
+    return value <= lo || value >= hi;
+  }
+  return value < min || value > max;
+}

package/src/math/referenceGroup.ts

@@ -0,0 +1,65 @@
+/**
+ * Pure, worklet-safe clustering for reference-line grouping — collapse Form-A
+ * lines whose value-Y positions sit near each other into one count handle. Free of
+ * hooks / SharedValues so it unit-tests without Reanimated; the per-frame call +
+ * rendering live in the controller / `ReferenceLineGroupOverlay`.
+ */
+
+/** One collapsed cluster of nearby reference lines. */
+export interface ReferenceGroup {
+  /** Centroid Y (canvas px) of the cluster — where the count handle is drawn. */
+  cy: number;
+  /** Number of lines collapsed into the cluster (≥ 2). */
+  count: number;
+}
+
+/** Result of clustering a frame's reference-line Y positions. */
+export interface ReferenceGrouping {
+  /**
+   * Index-aligned with the input Ys: `true` when this line's individual tag is
+   * collapsed into a cluster (a multi-line group) and should be suppressed.
+   */
+  hidden: boolean[];
+  /** One entry per multi-line cluster (singletons render normally, never here). */
+  groups: ReferenceGroup[];
+}
+
+/**
+ * Single-linkage cluster of reference-line handle Ys: lines whose sorted Y gaps are
+ * all `<= radius` chain into one group. Entries `< 0` (not a Form-A line / off the
+ * canvas) are ignored. Returns which lines are collapsed (`hidden`) plus a centroid
+ * + count per multi-line cluster. A non-positive `radius` disables grouping.
+ */
+export function groupReferenceLines(
+  ys: number[],
+  radius: number,
+): ReferenceGrouping {
+  "worklet";
+  const hidden: boolean[] = [];
+  for (let i = 0; i < ys.length; i++) hidden.push(false);
+  const groups: ReferenceGroup[] = [];
+  if (radius <= 0) return { hidden, groups };
+
+  const pts: { i: number; y: number }[] = [];
+  for (let i = 0; i < ys.length; i++) {
+    if (ys[i] >= 0) pts.push({ i, y: ys[i] });
+  }
+  pts.sort((a, b) => a.y - b.y);
+
+  let c = 0;
+  while (c < pts.length) {
+    let j = c;
+    let sum = pts[c].y;
+    while (j + 1 < pts.length && pts[j + 1].y - pts[j].y <= radius) {
+      j++;
+      sum += pts[j].y;
+    }
+    const count = j - c + 1;
+    if (count > 1) {
+      for (let k = c; k <= j; k++) hidden[pts[k].i] = true;
+      groups.push({ cy: sum / count, count });
+    }
+    c = j + 1;
+  }
+  return { hidden, groups };
+}

package/src/math/referenceLines.ts

@@ -1,4 +1,8 @@
-import type { ReferenceLine } from "../types";
+import type {
+  FontWeight,
+  ReferenceLine,
+  ReferenceLineBadgeConfig,
+} from "../types";
 
 /** Which of the three reference-line forms a `ReferenceLine` resolves to. */
 export type ReferenceLineForm = "line" | "value-band" | "time-band" | "none";
@@ -40,24 +44,86 @@ export function collectReferenceValues(lines: ReferenceLine[]): number[] {
   return out;
 }
 
-/** Fully-resolved badge presentation for a Form-A reference line. */
-export interface ResolvedReferenceBadge {
-  position: "left" | "right";
+/**
+ * Fully-resolved badge **style/shape** + anchor — the resolved counterpart of
+ * {@link BadgeStyleConfig} (`position` / `icon` / `showText` plus the style knobs).
+ * Shared by the reference-line badge ({@link ResolvedReferenceBadge}) and the
+ * grouping count pill ({@link ResolvedReferenceGroupBadge}). Unset colors stay
+ * `undefined` so the overlay applies the appropriate theme default at render time.
+ */
+export interface ResolvedReferenceBadgeStyle {
+  position: "left" | "center" | "right";
   /** Leading glyph, or "" for none. */
   icon: string;
-  /** Whether the text label is shown. */
+  /** Whether the text label is shown (false → icon-only). */
   showText: boolean;
-  /** undefined → theme tooltipBg at render time. */
   background: string | undefined;
-  /** undefined → the line color at render time. */
   borderColor: string | undefined;
+  /** Border stroke width in px. Default `1`. */
+  borderWidth: number;
   radius: number;
+  textColor: string | undefined;
+  /** Per-badge font knobs; undefined → the chart font. */
+  fontSize: number | undefined;
+  fontFamily: string | undefined;
+  fontWeight: FontWeight | undefined;
+  /** Nudge the whole badge from its anchor, in px. Default `0`. */
+  offsetX: number;
+  offsetY: number;
+}
+
+/** Fully-resolved presentation for a Form-A reference-line badge — the shared
+ *  style/shape plus the in-range / legacy-text flags. */
+export interface ResolvedReferenceBadge extends ResolvedReferenceBadgeStyle {
   /** Show the pill at the value when in range (`badge`) vs only off-screen (legacy `offAxisBadge`). */
   inRange: boolean;
   /** Legacy `"word: value"` text format (off-axis badge) vs the `label`/value format. */
   legacyText: boolean;
 }
 
+/** Fully-resolved styling for the grouping **count pill** — exactly the shared
+ *  badge style/shape (no in-range / legacy concepts). */
+export type ResolvedReferenceGroupBadge = ResolvedReferenceBadgeStyle;
+
+/**
+ * Resolves the shared style/shape + anchor of a {@link BadgeStyleConfig}-shaped
+ * badge config. `flat` supplies a reference line's flat `badge*` fallbacks
+ * (`badgeBackground` / `badgeBorderColor` / `badgeRadius`); omit it for the group
+ * pill. Theme defaults for the unset colors are applied at render time. Worklet —
+ * also called from the {@link resolveReferenceBadge} worklet.
+ */
+function resolveReferenceBadgeStyle(
+  cfg: ReferenceLineBadgeConfig | undefined,
+  flat?: ReferenceLine,
+): ResolvedReferenceBadgeStyle {
+  "worklet";
+  return {
+    position: cfg?.position ?? "left",
+    icon: cfg?.icon ?? "",
+    showText: cfg?.text ?? true,
+    background: cfg?.background ?? flat?.badgeBackground,
+    borderColor: cfg?.borderColor ?? flat?.badgeBorderColor,
+    borderWidth: cfg?.borderWidth ?? 1,
+    radius: cfg?.radius ?? flat?.badgeRadius ?? 5,
+    textColor: cfg?.textColor,
+    fontSize: cfg?.fontSize,
+    fontFamily: cfg?.fontFamily,
+    fontWeight: cfg?.fontWeight,
+    offsetX: cfg?.offsetX ?? 0,
+    offsetY: cfg?.offsetY ?? 0,
+  };
+}
+
+/**
+ * Resolves the grouping count-pill styling from a {@link ReferenceLineBadgeConfig}
+ * (the same shape a per-line badge uses). Pure — driven only by the config.
+ */
+export function resolveReferenceGroupBadge(
+  badge?: ReferenceLineBadgeConfig,
+): ResolvedReferenceGroupBadge {
+  return resolveReferenceBadgeStyle(badge);
+}
+
 /**
  * Resolves a Form-A reference line's badge presentation from the new `badge`
  * config or the legacy `offAxisBadge` flag (the `badge` config wins). Returns
@@ -70,24 +136,15 @@ export function resolveReferenceBadge(
   if (rl.badge) {
     const cfg = rl.badge === true ? undefined : rl.badge;
     return {
-      position: cfg?.position ?? "left",
-      icon: cfg?.icon ?? "",
-      showText: cfg?.text ?? true,
-      background: cfg?.background ?? rl.badgeBackground,
-      borderColor: cfg?.borderColor ?? rl.badgeBorderColor,
-      radius: cfg?.radius ?? rl.badgeRadius ?? 5,
+      ...resolveReferenceBadgeStyle(cfg, rl),
       inRange: true,
       legacyText: false,
     };
   }
   if (rl.offAxisBadge) {
+    // Legacy off-axis badge: no config object, but the flat `badge*` fallbacks apply.
     return {
-      position: "left",
-      icon: "",
-      showText: true,
-      background: rl.badgeBackground,
-      borderColor: rl.badgeBorderColor,
-      radius: rl.badgeRadius ?? 5,
+      ...resolveReferenceBadgeStyle(undefined, rl),
       inRange: false,
       legacyText: true,
     };