react-native-livechart 3.12.0 → 4.0.0

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,
     };