react-native-livechart 3.12.0 → 4.0.0

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,

package/src/hooks/useBadge.ts

@@ -39,6 +39,27 @@ export function useBadge(
   background?: string,
   badgeMetrics: BadgeMetrics = BADGE_METRICS_DEFAULTS,
   badgeColorSpeed: number = MOTION_METRICS_DEFAULTS.badgeColorSpeed,
+  /**
+   * Floating-axis mode: render a tail-less pill right-aligned at the canvas edge
+   * (over a full-width plot) instead of inside a reserved right gutter. See
+   * {@link YAxisConfig.float}.
+   */
+  float = false,
+  /**
+   * Smoothed value at the visible window's right edge (engine `edgeValue`). When
+   * {@link followViewEdge} is set, the badge tracks this instead of the live value.
+   */
+  edgeValue?: SharedValue<number>,
+  /** Track the visible window's right-edge price while scrolled back. */
+  followViewEdge = false,
+  /**
+   * Pill corner radius in pixels. `undefined` → capsule (`pillHeight / 2`).
+   * Clamped to `[0, pillHeight / 2]`. The pointed tail (right-gutter mode) keeps
+   * anchoring on the vertical center regardless of this value.
+   */
+  radius?: number,
+  /** Label text color override; falls back to the variant/theme rule. */
+  textColorOverride?: string,
 ) {
   const colorR = useSharedValue(0);
   const colorG = useSharedValue(0);
@@ -71,21 +92,41 @@ export function useBadge(
     const dMin = engine.displayMin.get();
     const dMax = engine.displayMax.get();
     const valRange = dMax - dMin;
+    // Follow the visible window's right-edge price while scrolled back, else the
+    // live value (badge.followViewEdge). engine `edgeValue` already collapses to
+    // the live value when not scrolled, so the live badge is unchanged.
+    const liveVal =
+      followViewEdge && edgeValue ? edgeValue.get() : engine.displayValue.get();
     const dotY =
       valRange === 0
         ? padding.top + chartH / 2
-        : padding.top +
-          ((dMax - engine.displayValue.get()) / valRange) * chartH;
+        : padding.top + ((dMax - liveVal) / valRange) * chartH;
 
-    const text = formatValue(engine.displayValue.get());
+    const text = formatValue(liveVal);
     const textW = measureFontTextWidth(font, text);
 
     const pillH = font.getSize() + badgeMetrics.padY * 2;
-    const r = pillH / 2;
+    // `midY` is the pill's vertical center (the tail anchors here); `capR` is the
+    // corner radius — the capsule (midY) by default, or a clamped custom radius.
+    const midY = pillH / 2;
+    const capR = radius == null ? midY : Math.max(0, Math.min(radius, midY));
     const badgeY = dotY - pillH / 2;
     let textX: number;
 
-    if (position === "left") {
+    if (float) {
+      // Floating price tag: a tail-less pill right-aligned at the canvas edge,
+      // floating over the full-width plot (no reserved gutter). Its pill bg keeps
+      // the live value readable over the candles.
+      const pillW = 2 * badgeMetrics.padX + textW;
+      const bodyRight = w - badgeMetrics.marginEdge;
+      const bodyLeft = bodyRight - pillW;
+      textX = (bodyLeft + bodyRight - textW) / 2;
+      b.addRRect({
+        rect: { x: bodyLeft, y: badgeY, width: pillW, height: pillH },
+        rx: capR,
+        ry: capR,
+      });
+    } else if (position === "left") {
       // Pill to the left of the live dot; no tail (`showTail` applies to right gutter only).
       const dotXPos = w - padding.right;
       const pillW = 2 * badgeMetrics.padX + textW;
@@ -95,8 +136,8 @@ export function useBadge(
       textX = (bodyLeft + bodyRight - textW) / 2;
       b.addRRect({
         rect: { x: bodyLeft, y: badgeY, width: pillBodyW, height: pillH },
-        rx: r,
-        ry: r,
+        rx: capR,
+        ry: capR,
       });
     } else {
       // Right-gutter badge (default): asymmetric layout with optional tail.
@@ -115,28 +156,54 @@ export function useBadge(
 
       if (showTail) {
         const badgeX = w - padding.right + badgeMetrics.dotGap;
-        const cx = tl + pillW - r;
+        const bodyRightX = badgeX + tl + pillW;
 
         b.moveTo(badgeX + tl, badgeY);
-        b.lineTo(badgeX + cx, badgeY);
-        b.arcToOval(
-          { x: badgeX + cx - r, y: badgeY, width: r * 2, height: pillH },
-          -90,
-          180,
-          false,
-        );
+        if (capR >= midY) {
+          // Capsule cap: a single right-hand semicircle (the default badge).
+          const cx = tl + pillW - capR;
+          b.lineTo(badgeX + cx, badgeY);
+          b.arcToOval(
+            { x: badgeX + cx - capR, y: badgeY, width: capR * 2, height: pillH },
+            -90,
+            180,
+            false,
+          );
+        } else {
+          // Custom (smaller) corner radius: square body with rounded right corners.
+          b.lineTo(bodyRightX - capR, badgeY);
+          b.arcToOval(
+            { x: bodyRightX - capR * 2, y: badgeY, width: capR * 2, height: capR * 2 },
+            -90,
+            90,
+            false,
+          );
+          b.lineTo(bodyRightX, badgeY + pillH - capR);
+          b.arcToOval(
+            {
+              x: bodyRightX - capR * 2,
+              y: badgeY + pillH - capR * 2,
+              width: capR * 2,
+              height: capR * 2,
+            },
+            0,
+            90,
+            false,
+          );
+        }
         b.lineTo(badgeX + tl, badgeY + pillH);
+        // Tail tip stays on the vertical center (`midY`) regardless of corner radius.
         b.cubicTo(
           badgeX + badgeMetrics.tailLength + 2,
           badgeY + pillH,
           badgeX + 3,
-          badgeY + r + badgeMetrics.tailSpread,
+          badgeY + midY + badgeMetrics.tailSpread,
           badgeX,
-          badgeY + r,
+          badgeY + midY,
         );
         b.cubicTo(
           badgeX + 3,
-          badgeY + r - badgeMetrics.tailSpread,
+          badgeY + midY - badgeMetrics.tailSpread,
           badgeX + badgeMetrics.tailLength + 2,
           badgeY,
           badgeX + tl,
@@ -146,8 +213,8 @@ export function useBadge(
       } else {
         b.addRRect({
           rect: { x: bodyLeft, y: badgeY, width: pillW, height: pillH },
-          rx: r,
-          ry: r,
+          rx: capR,
+          ry: capR,
         });
       }
     }
@@ -182,7 +249,8 @@ export function useBadge(
     }
 
     const textColor =
-      variant === "minimal" ? "rgba(100,100,100,1)" : palette.badgeText;
+      textColorOverride ??
+      (variant === "minimal" ? "rgba(100,100,100,1)" : palette.badgeText);
 
     return { path: b.detach(), textX, textY, text, bgColor, textColor };
   });