react-native-livechart 3.11.0 → 4.0.0

package/src/draw/grid.ts

@@ -114,7 +114,19 @@ export function computeGridEntries(
   // Phase 1: compute target alpha for every grid line
   const targets: Record<number, number> = {};
   const first = Math.ceil(displayMin / fine) * fine;
-  for (let val = first; val <= displayMax; val += fine) {
+  // Guard against a non-advancing loop. On a near-flat (but not bit-identical)
+  // range, `fine` can drop below ulp(val), so `val += fine === val` and the loop
+  // never terminates — freezing the UI thread, since this runs in a worklet every
+  // frame. `stepResolves` skips the degenerate range (also catches fine === 0);
+  // MAX_GRID_LINES is a hard backstop in case the step stalls mid-loop (real
+  // grids only have a handful of lines, so it never bites normal data).
+  const stepResolves = first + fine !== first;
+  const MAX_GRID_LINES = 1000;
+  for (
+    let val = first, lineCount = 0;
+    stepResolves && val <= displayMax && lineCount < MAX_GRID_LINES;
+    val += fine, lineCount++
+  ) {
     const y = gridValueToY(val, displayMax, valRange, padTop, chartH);
     /* istanbul ignore next -- y stays in chart band for v in [first, displayMax] with consistent toY */
     if (y < padTop - 2 || y > canvasHeight - padBottom + 2) continue;

package/src/draw/markerAtlas.ts

@@ -21,11 +21,42 @@ const PILL_TEXT_COLOR = "#ffffff";
 /** Anti-alias breathing room baked around every cell so sprites don't clip. */
 const CELL_MARGIN = 2;
 
-/** Default glyph color per kind when `marker.color` is unset. */
+/** Glyphs composed into a collapsed-cluster count badge (digits only; capped "99"). */
+const GROUP_CHARS = "0123456789";
+/** Padding (px) between the digits and the inner circle edge. */
+const BADGE_PAD = 2;
+/** Background-colored halo ring around the badge — matches the icon-pill border. */
+const BADGE_BORDER = 2;
+/** Count-badge digits render at this fraction of the chart font, so two digits fit
+ *  a small round badge. Shared with the overlay's per-frame digit layout. */
+export const BADGE_TEXT_SCALE = 0.75;
+
+/** Atlas cell sig for one count-badge glyph (`0`-`9`), drawn white. */
+export function groupGlyphSig(ch: string): string {
+  "worklet";
+  return `gd\x1f${ch}`;
+}
+
+/** Atlas cell sig for the round count-badge background (one fixed circle per color). */
+export function groupBgSig(color: string): string {
+  "worklet";
+  return `gbg\x1f${color}`;
+}
+
+/** Text shown in a collapsed-cluster count badge — exact up to `"99"`, capped there
+ *  so it always fits the fixed round badge (≤ 2 digits). */
+export function groupCountText(count: number): string {
+  "worklet";
+  return count > 99 ? "99" : `${count}`;
+}
+
+/** Default glyph color per kind when `marker.color` is unset. Worklet-safe so the
+ *  per-frame overlay worklet can resolve a collapsed cluster's badge color. */
 export function defaultMarkerColor(
   kind: MarkerKind,
   palette: LiveChartPalette,
 ): string {
+  "worklet";
   switch (kind) {
     case "trade":
       return palette.line;
@@ -93,9 +124,13 @@ export interface MarkerAtlas {
    * hi-res cell back to its logical on-canvas size. See `buildMarkerAtlas`.
    */
   scale: number;
+  /** Logical ink width (px) of each count-badge digit `"0"`–`"9"`, for laying them
+   *  out proportionally (so narrow digits like `1` don't leave gaps). Empty when
+   *  the atlas carries no group cells (clustering off). */
+  digitWidths: Record<string, number>;
 }
 
-const EMPTY_ATLAS: MarkerAtlas = { image: null, cells: {}, scale: 1 };
+const EMPTY_ATLAS: MarkerAtlas = { image: null, cells: {}, scale: 1, digitWidths: {} };
 
 function fillPaint(color: string): SkPaint {
   const p = Skia.Paint();
@@ -260,6 +295,51 @@ function cellSpec(m: Marker, palette: LiveChartPalette, font: SkFont): CellSpec
   };
 }
 
+/** One count-badge glyph (`0`-`9` / `+`) in white, on a uniform-width box so the
+ *  digits lay out tabular. `uw`/`gh` are the shared logical glyph metrics. */
+function groupGlyphCellSpec(
+  ch: string,
+  uw: number,
+  gh: number,
+  font: SkFont,
+): CellSpec {
+  const b = font.measureText(ch);
+  const dx = b.x + b.width / 2;
+  const dy = b.y + b.height / 2;
+  const m2 = CELL_MARGIN * 2;
+  return {
+    w: uw + m2,
+    h: gh + m2,
+    draw: (canvas, cx, cy) =>
+      canvas.drawText(ch, cx - dx, cy - dy, fillPaint(PILL_TEXT_COLOR), font),
+  };
+}
+
+/** Round count-badge background — a single fixed-size circle (independent of digit
+ *  count) with a background-colored halo ring like the icon pills. Sized to fit the
+ *  scaled two-digit text, so the badge stays small, round, and never changes size.
+ *  `uw`/`gh` are the shared (full-size) glyph metrics; the text is drawn scaled. */
+function groupBgCellSpec(
+  color: string,
+  bgColor: string,
+  uw: number,
+  gh: number,
+): CellSpec {
+  const m2 = CELL_MARGIN * 2;
+  // Inner circle fits a centered two-digit string at BADGE_TEXT_SCALE plus padding.
+  const innerR = Math.ceil(Math.max(2 * uw, gh) * BADGE_TEXT_SCALE) / 2 + BADGE_PAD;
+  const outerR = innerR + BADGE_BORDER;
+  const diameter = 2 * outerR;
+  return {
+    w: diameter + m2,
+    h: diameter + m2,
+    draw: (canvas, cx, cy) => {
+      canvas.drawCircle(cx, cy, outerR, fillPaint(bgColor)); // halo ring
+      canvas.drawCircle(cx, cy, innerR, fillPaint(color)); // colored badge
+    },
+  };
+}
+
 /**
  * Rasterize every distinct marker appearance into a single packed atlas image,
  * once per appearance-set change (NOT per frame). The per-frame worklet then
@@ -279,6 +359,9 @@ export function buildMarkerAtlas(
   palette: LiveChartPalette,
   font: SkFont,
   scale = 1,
+  /** Also bake count-badge cells (digits + per-color backgrounds) for
+   *  `markerCluster: "stacked"` collapse. Off by default — no atlas bloat. */
+  withGroups = false,
 ): MarkerAtlas {
   const seen = new Set<string>();
   const specs: { sig: string; spec: CellSpec }[] = [];
@@ -290,6 +373,37 @@ export function buildMarkerAtlas(
     seen.add(sig);
     specs.push({ sig, spec: cellSpec(m, 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`.
+  const digitWidths: Record<string, number> = {};
+  if (withGroups && specs.length > 0) {
+    let uw = 1;
+    let gh = 1;
+    for (const ch of GROUP_CHARS) {
+      const b = font.measureText(ch);
+      digitWidths[ch] = Math.max(1, Math.ceil(b.width));
+      if (b.width > uw) uw = b.width;
+      if (b.height > gh) gh = b.height;
+    }
+    uw = Math.ceil(uw);
+    gh = Math.ceil(gh);
+    for (const ch of GROUP_CHARS) {
+      specs.push({ sig: groupGlyphSig(ch), spec: groupGlyphCellSpec(ch, uw, gh, font) });
+    }
+    const bgColor = `rgb(${palette.bgRgb[0]}, ${palette.bgRgb[1]}, ${palette.bgRgb[2]})`;
+    const colors = new Set<string>();
+    for (let i = 0; i < markers.length; i++) {
+      const m = markers[i];
+      if (isConnectorMarker(m)) continue;
+      colors.add(m.color ?? defaultMarkerColor(m.kind, palette));
+    }
+    for (const color of colors) {
+      specs.push({ sig: groupBgSig(color), spec: groupBgCellSpec(color, bgColor, uw, gh) });
+    }
+  }
+
   if (specs.length === 0) return EMPTY_ATLAS;
 
   let totalW = 0;
@@ -326,5 +440,5 @@ export function buildMarkerAtlas(
   }
   const picture = recorder.finishRecordingAsPicture();
   const image = drawAsImageFromPicture(picture, { width: texW, height: texH });
-  return { image, cells, scale };
+  return { image, cells, scale, digitWidths };
 }

package/src/draw/volume.ts

@@ -0,0 +1,190 @@
+import { CANDLE_METRICS_DEFAULTS } from "../constants";
+import type { CandleMetrics, CandlePoint } from "../types";
+import type { ChartPadding } from "./line";
+
+export interface VolumeBar {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  up: boolean;
+}
+
+export interface VolumeGeometry {
+  bars: VolumeBar[];
+}
+
+function volumeTimeToX(
+  t: number,
+  padLeft: number,
+  winStart: number,
+  windowSecs: number,
+  chartW: number,
+): number {
+  "worklet";
+  return padLeft + ((t - winStart) / windowSecs) * chartW;
+}
+
+/** Whether a candle's bucket overlaps the visible window. Only the live candle
+ *  needs this — committed candles are pre-filtered by the binary search + break. */
+function candleVisible(
+  c: CandlePoint,
+  winStart: number,
+  winEnd: number,
+  candleWidthSecs: number,
+): boolean {
+  "worklet";
+  return c.time + candleWidthSecs >= winStart && c.time <= winEnd;
+}
+
+/** One candle → a volume bar appended to `bars` (skips zero/empty volume). */
+function appendVolumeBar(
+  c: CandlePoint,
+  winStart: number,
+  windowSecs: number,
+  chartW: number,
+  chartLeft: number,
+  chartRight: number,
+  padLeft: number,
+  candleWidthSecs: number,
+  bodyW: number,
+  maxVol: number,
+  baseline: number,
+  bandHeight: number,
+  bars: VolumeBar[],
+): void {
+  "worklet";
+  const vol = c.volume ?? 0;
+  if (vol <= 0) return;
+
+  const xCenter = volumeTimeToX(
+    c.time + candleWidthSecs / 2,
+    padLeft,
+    winStart,
+    windowSecs,
+    chartW,
+  );
+  if (xCenter < chartLeft - bodyW / 2 || xCenter > chartRight + bodyW / 2)
+    return;
+
+  let bx = xCenter - bodyW / 2;
+  let bw = bodyW;
+  if (bx < chartLeft) {
+    bw -= chartLeft - bx;
+    bx = chartLeft;
+  }
+  if (bx + bw > chartRight) {
+    bw = chartRight - bx;
+  }
+  /* istanbul ignore next -- clipped to zero width */
+  if (bw <= 0) return;
+
+  const h = (vol / maxVol) * bandHeight;
+  bars.push({ x: bx, y: baseline - h, w: bw, h, up: c.close >= c.open });
+}
+
+/**
+ * Build screen-space volume bars for the reserved band below the candles. Bars
+ * align under the candle bodies (same width + center) and grow up from the band
+ * baseline (the x-axis line). Heights are normalized to the largest *visible*
+ * volume so the tallest bar fills `bandHeight`. Pure worklet — no Skia imports,
+ * consumed by {@link useCandlePaths}.
+ *
+ * `padding.bottom` is the already-reserved bottom (it includes `bandHeight`), so
+ * `canvasH - padding.bottom` is the candle plot's bottom = the top of the band,
+ * and the baseline sits `bandHeight` below it (the x-axis line).
+ */
+export function buildVolumeGeometry(
+  candles: CandlePoint[],
+  liveCandle: CandlePoint | null,
+  padding: ChartPadding,
+  canvasW: number,
+  canvasH: number,
+  winStart: number,
+  windowSecs: number,
+  bandHeight: number,
+  candleWidthSecs: number,
+  metrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
+): VolumeGeometry {
+  "worklet";
+  const chartW = canvasW - padding.left - padding.right;
+  if (bandHeight <= 0 || chartW <= 0) return { bars: [] };
+
+  const slotPx = (candleWidthSecs / windowSecs) * chartW;
+  const bodyW = Math.max(
+    1,
+    Math.min(slotPx * metrics.bodyWidthRatio, slotPx - 2, metrics.maxBodyPx),
+  );
+
+  const winEnd = winStart + windowSecs;
+  const chartLeft = padding.left;
+  const chartRight = canvasW - padding.right;
+  const padLeft = padding.left;
+  const baseline = canvasH - padding.bottom + bandHeight;
+
+  // Binary search for the first candle overlapping the window (same as candles).
+  let lo = 0;
+  let hi = candles.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (candles[mid].time + candleWidthSecs < winStart) lo = mid + 1;
+    else hi = mid;
+  }
+
+  // Pass 1 — largest visible volume (the bar that fills the band). The live
+  // candle counts too so a tall in-progress bar doesn't overflow the band.
+  let maxVol = 0;
+  for (let i = lo; i < candles.length; i++) {
+    /* istanbul ignore next -- past visible window */
+    if (candles[i].time > winEnd) break;
+    const v = candles[i].volume ?? 0;
+    if (v > maxVol) maxVol = v;
+  }
+  if (liveCandle && candleVisible(liveCandle, winStart, winEnd, candleWidthSecs)) {
+    const v = liveCandle.volume ?? 0;
+    if (v > maxVol) maxVol = v;
+  }
+
+  if (maxVol <= 0) return { bars: [] };
+
+  // Pass 2 — build the bars normalized to maxVol.
+  const bars: VolumeBar[] = [];
+  for (let i = lo; i < candles.length; i++) {
+    /* istanbul ignore next -- past visible window */
+    if (candles[i].time > winEnd) break;
+    appendVolumeBar(
+      candles[i],
+      winStart,
+      windowSecs,
+      chartW,
+      chartLeft,
+      chartRight,
+      padLeft,
+      candleWidthSecs,
+      bodyW,
+      maxVol,
+      baseline,
+      bandHeight,
+      bars,
+    );
+  }
+  if (liveCandle && candleVisible(liveCandle, winStart, winEnd, candleWidthSecs)) {
+    appendVolumeBar(
+      liveCandle,
+      winStart,
+      windowSecs,
+      chartW,
+      chartLeft,
+      chartRight,
+      padLeft,
+      candleWidthSecs,
+      bodyW,
+      maxVol,
+      baseline,
+      bandHeight,
+      bars,
+    );
+  }
+
+  return { bars };
+}

package/src/hooks/crosshairShared.ts

@@ -204,16 +204,22 @@ export function computeTooltipLayout(
   monoCharWidth = 0,
   /** Where the pill sits relative to the scrub line. `"side"` offsets it right
    *  (flipping left near the edge); `"top"`/`"bottom"` center it over the line,
-   *  clamped into the plot and pinned to the plot's top/bottom. */
-  placement: "side" | "top" | "bottom" = "side",
+   *  clamped into the plot and pinned to the plot's top/bottom; `"point"`
+   *  centers it over the line and floats it just above the scrub dot (flipping
+   *  below when there's no room), deriving its Y from `scrubDotY`. */
+  placement: "side" | "top" | "bottom" | "point" = "side",
   /** Render the value row. */
   showValue = true,
   /** Render the time row. */
   showTime = true,
-  /** Canvas height in px — needed to pin `"bottom"` placement. */
+  /** Canvas height in px — needed to pin `"bottom"`/`"point"` placement. */
   canvasHeight = 0,
-  /** Gap in px between the pill and the plot edge it's pinned to. */
+  /** Gap in px between the pill and the plot edge it's pinned to — and, for
+   *  `"point"`, between the scrub dot's center and the pill's nearest edge. */
   margin = TOOLTIP_TOP_MARGIN,
+  /** Scrub intersection Y in canvas px (see {@link computeScrubDotY}) — the
+   *  anchor for `"point"` placement. -1 (default) falls back to a top pin. */
+  scrubDotY = -1,
 ): TooltipLayout {
   "worklet";
   if (!scrubActive || scrubValue === null) return HIDDEN_TOOLTIP;
@@ -267,10 +273,30 @@ export function computeTooltipLayout(
       Math.max(scrubX - pillW / 2, leftBound),
       Math.max(leftBound, rightBound),
     );
-    pillY =
-      placement === "top"
-        ? padding.top + margin
-        : canvasHeight - padding.bottom - margin - totalH;
+    if (placement === "point") {
+      // Float just above the scrub dot, flipping below when there's no room
+      // above; clamp into the plot so the pill never spills past the top/bottom.
+      // A missing dot Y (canvas not laid out) falls back to a top pin.
+      if (scrubDotY < 0) {
+        pillY = padding.top + margin;
+      } else {
+        const topLimit = padding.top + TOOLTIP_EDGE_GAP;
+        const bottomLimit =
+          canvasHeight - padding.bottom - TOOLTIP_EDGE_GAP - totalH;
+        const aboveY = scrubDotY - margin - totalH;
+        const belowY = scrubDotY + margin;
+        pillY = aboveY >= topLimit ? aboveY : belowY;
+        pillY = Math.min(
+          Math.max(pillY, topLimit),
+          Math.max(topLimit, bottomLimit),
+        );
+      }
+    } else {
+      pillY =
+        placement === "top"
+          ? padding.top + margin
+          : canvasHeight - padding.bottom - margin - totalH;
+    }
   }
 
   // line1Y = first rendered row's baseline; line2Y = second (when both shown).
@@ -679,11 +705,12 @@ export function deriveCrosshairTooltipSingle(
   formatTime: (t: number) => string,
   font: SkFont,
   monoCharWidth = 0,
-  placement: "side" | "top" | "bottom" = "side",
+  placement: "side" | "top" | "bottom" | "point" = "side",
   showValue = true,
   showTime = true,
   canvasHeight = 0,
   margin = TOOLTIP_TOP_MARGIN,
+  scrubDotY = -1,
 ): TooltipLayout {
   "worklet";
   if (!scrubActive || scrubTime < 0) return HIDDEN_TOOLTIP;
@@ -703,5 +730,6 @@ export function deriveCrosshairTooltipSingle(
     showTime,
     canvasHeight,
     margin,
+    scrubDotY,
   );
 }

package/src/hooks/overlayScale.ts

@@ -0,0 +1,59 @@
+import type { ChartScale } from "../types";
+
+/**
+ * Pure worklet projections for the `renderOverlay` bridge ({@link ChartOverlayContext}).
+ *
+ * Each takes a {@link ChartScale} **snapshot** rather than reading any SharedValue
+ * itself — so the consumer's `useAnimatedStyle` / `useDerivedValue` becomes
+ * reactive simply by reading `scale.get()` (which subscribes it to the per-frame
+ * scale), and these stay trivially unit-testable as plain functions of data.
+ */
+
+/** Maps a price (Y-axis value) to its canvas Y pixel. -1 when not laid out. */
+export function priceToY(price: number, scale: ChartScale): number {
+  "worklet";
+  const { top, bottom } = scale.plot;
+  const chartH = bottom - top;
+  if (chartH <= 0) return -1;
+  const range = scale.max - scale.min;
+  if (range === 0) return top + chartH / 2;
+  return top + ((scale.max - price) / range) * chartH;
+}
+
+/**
+ * Inverse of {@link priceToY}: maps a canvas Y pixel back to a price. Clamps to
+ * the visible range (a level can't sit beyond the axis bounds); null when not
+ * laid out.
+ */
+export function yToPrice(y: number, scale: ChartScale): number | null {
+  "worklet";
+  const { top, bottom } = scale.plot;
+  const chartH = bottom - top;
+  if (chartH <= 0) return null;
+  const range = scale.max - scale.min;
+  if (range === 0) return scale.min;
+  const clampedY = Math.min(bottom, Math.max(top, y));
+  const frac = (clampedY - top) / chartH; // 0 at top, 1 at bottom
+  return scale.max - frac * range;
+}
+
+/** Maps a unix-seconds timestamp to its canvas X pixel. -1 when not laid out. */
+export function timeToX(time: number, scale: ChartScale): number {
+  "worklet";
+  const { left, right } = scale.plot;
+  const chartW = right - left;
+  if (chartW <= 0) return -1;
+  if (scale.window <= 0) return left;
+  const winStart = scale.now - scale.window;
+  return left + ((time - winStart) / scale.window) * chartW;
+}
+
+/** Inverse of {@link timeToX}: maps a canvas X pixel back to a unix-seconds timestamp. */
+export function xToTime(x: number, scale: ChartScale): number {
+  "worklet";
+  const { left, right } = scale.plot;
+  const chartW = right - left;
+  if (chartW <= 0) return -1;
+  const winStart = scale.now - scale.window;
+  return winStart + ((x - left) / chartW) * scale.window;
+}

package/src/hooks/resolveChartLayout.ts

@@ -16,6 +16,8 @@ export interface ChartLayoutConfig {
   lineWidthOverride?: number;
   insetsOverride?: ChartInsets;
   yAxis: boolean;
+  /** Float the y-axis over a full-width plot (no reserved right gutter). */
+  yAxisFloat?: boolean;
   badge: boolean;
   /** Badge pill geometry tokens. Omit for built-in defaults. */
   badgeMetrics?: BadgeMetrics;
@@ -26,6 +28,13 @@ export interface ChartLayoutConfig {
   badgeUsesRightGutter?: boolean;
   /** When false, bottom inset shrinks (no x-axis labels). Default true. */
   xAxis?: boolean;
+  /**
+   * Reserved volume-bar band height (px) below the candles. Added to the bottom
+   * padding so the candle/price plot shrinks by this much; the x-axis offsets
+   * back down by it so its labels stay pinned to the bottom (see XAxisOverlay).
+   * `0`/omitted = no band. An explicit `insetsOverride.bottom` suppresses it.
+   */
+  volumeBandHeight?: number;
   /** Skia font for measuring label width. When provided with formatValue + currentValue, padding auto-sizes. */
   font?: SkFont;
   /** Worklet formatter — called on JS thread here to measure label width */
@@ -52,6 +61,9 @@ export interface ChartLayoutResult {
   padding: ChartPadding;
 }
 
+/** Right inset (px) for a floating y-axis — just keeps the plot off the edge. */
+const FLOAT_AXIS_RIGHT_INSET = 6;
+
 export function resolveChartLayout(
   config: ChartLayoutConfig,
 ): ChartLayoutResult {
@@ -156,6 +168,27 @@ export function resolveChartLayout(
     };
   }
 
+  // Floating axis: collapse the right gutter LAST so it wins over the label,
+  // pulse, and badge reservations above — the plot runs full-width with the price
+  // axis (and the live-value badge) floating on top. An explicit right inset still
+  // wins. (The live-dot pulse may clip at the right edge in this mode.)
+  if (config.yAxisFloat && config.insetsOverride?.right == null) {
+    padding = { ...padding, right: FLOAT_AXIS_RIGHT_INSET };
+  }
+
+  // Volume band: reserve extra space at the bottom by ADDING the band height to
+  // the (already finalized) bottom padding, so every price Y-projection shrinks
+  // for free. The x-axis is shifted back down by the same amount (XAxisOverlay)
+  // so its labels stay at the very bottom, below the band. An explicit bottom
+  // inset opts out (the caller owns the full bottom space).
+  if (
+    config.volumeBandHeight &&
+    config.volumeBandHeight > 0 &&
+    config.insetsOverride?.bottom == null
+  ) {
+    padding = { ...padding, bottom: padding.bottom + config.volumeBandHeight };
+  }
+
   return {
     strokeWidth: config.lineWidthOverride ?? config.palette.lineWidth,
     padding,