react-native-livechart 1.0.0

package/src/hooks/crosshairShared.ts

@@ -0,0 +1,296 @@
+import { type SkFont } from "@shopify/react-native-skia";
+import { type Gesture } from "react-native-gesture-handler";
+import type { SharedValue } from "react-native-reanimated";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import { type ChartPadding } from "../draw/line";
+import { interpolateAtTime } from "../math/interpolate";
+
+const TOOLTIP_PAD_X = 8;
+const TOOLTIP_PAD_Y = 6;
+const TOOLTIP_LINE_GAP = 4;
+const TOOLTIP_OFFSET_X = 12;
+const TOOLTIP_EDGE_GAP = 4;
+const TOOLTIP_TOP_MARGIN = 8;
+const FADE_ZONE = 4;
+
+export interface TooltipLayout {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  valueStr: string;
+  timeStr: string;
+  valueTextX: number;
+  timeTextX: number;
+  line1Y: number;
+  line2Y: number;
+  /** Multi-series tooltip: time + per-series rows (replaces valueStr/timeStr rendering). */
+  stackedLines?: {
+    text: string;
+    textX: number;
+    baselineY: number;
+    dim: boolean;
+  }[];
+}
+
+export const HIDDEN_TOOLTIP: TooltipLayout = {
+  x: -400,
+  y: 0,
+  w: 0,
+  h: 0,
+  valueStr: "",
+  timeStr: "",
+  valueTextX: -400,
+  timeTextX: -400,
+  line1Y: 0,
+  line2Y: 0,
+  stackedLines: undefined,
+};
+
+export interface CrosshairState {
+  scrubX: SharedValue<number>;
+  scrubActive: SharedValue<boolean>;
+  scrubTime: SharedValue<number>;
+  scrubValue: SharedValue<number | null>;
+  crosshairOpacity: SharedValue<number>;
+  tooltipLayout: SharedValue<TooltipLayout>;
+  gesture: ReturnType<typeof Gesture.Pan>;
+}
+
+/**
+ * Maps a scrub X position to a window timestamp.
+ * Returns -1 when inactive or when the canvas is not yet laid out.
+ */
+export function computeScrubTime(
+  scrubActive: boolean,
+  scrubX: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  timestamp: number,
+  windowSecs: number,
+): number {
+  "worklet";
+  if (!scrubActive) return -1;
+  const chartW = canvasWidth - padding.left - padding.right;
+  if (chartW <= 0) return -1;
+  const winStart = timestamp - windowSecs;
+  const fraction = (scrubX - padding.left) / chartW;
+  return winStart + fraction * windowSecs;
+}
+
+/**
+ * Crosshair opacity: fades 1→0 over FADE_ZONE px as the crosshair
+ * approaches the live dot at the right chart edge.
+ */
+export function computeCrosshairOpacity(
+  scrubActive: boolean,
+  scrubX: number,
+  canvasWidth: number,
+  paddingRight: number,
+): number {
+  "worklet";
+  if (!scrubActive) return 0;
+  const dotX = canvasWidth - paddingRight;
+  const dist = dotX - scrubX;
+  return Math.min(1, Math.max(0, dist / FADE_ZONE));
+}
+
+/**
+ * Full tooltip pill layout. Returns HIDDEN_TOOLTIP when the scrub is
+ * inactive or no value can be interpolated at the current time.
+ */
+export function computeTooltipLayout(
+  scrubActive: boolean,
+  scrubX: number,
+  scrubValue: number | null,
+  scrubTime: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  formatValue: (v: number) => string,
+  formatTime: (t: number) => string,
+  font: SkFont,
+): TooltipLayout {
+  "worklet";
+  if (!scrubActive || scrubValue === null) return HIDDEN_TOOLTIP;
+
+  const v = scrubValue;
+  const t = scrubTime;
+  const valueStr = formatValue(v);
+  const timeStr = formatTime(t);
+
+  const fm = font.getMetrics();
+  const lineH = -fm.ascent + fm.descent;
+  const totalH = TOOLTIP_PAD_Y * 2 + lineH * 2 + TOOLTIP_LINE_GAP;
+
+  const valueW = measureFontTextWidth(font, valueStr);
+  const timeW = measureFontTextWidth(font, timeStr);
+  const contentW = Math.max(valueW, timeW);
+  const pillW = contentW + TOOLTIP_PAD_X * 2;
+
+  const rightEdge = canvasWidth - padding.right;
+
+  let pillX = scrubX + TOOLTIP_OFFSET_X;
+  if (pillX + pillW > rightEdge - TOOLTIP_EDGE_GAP) {
+    pillX = scrubX - pillW - TOOLTIP_OFFSET_X;
+  }
+  const pillY = padding.top + TOOLTIP_TOP_MARGIN;
+
+  const line1Y = pillY + TOOLTIP_PAD_Y - fm.ascent;
+  const line2Y = line1Y + lineH + TOOLTIP_LINE_GAP;
+
+  const valueTextX = pillX + TOOLTIP_PAD_X + (contentW - valueW) / 2;
+  const timeTextX = pillX + TOOLTIP_PAD_X + (contentW - timeW) / 2;
+
+  return {
+    x: pillX,
+    y: pillY,
+    w: pillW,
+    h: totalH,
+    valueStr,
+    timeStr,
+    valueTextX,
+    timeTextX,
+    line1Y,
+    line2Y,
+    stackedLines: undefined,
+  };
+}
+
+/**
+ * Multi-series scrub tooltip — stacked lines (first row typically time, dim).
+ */
+export function computeTooltipLayoutMulti(
+  scrubActive: boolean,
+  scrubX: number,
+  lines: { text: string; dim: boolean }[],
+  padding: ChartPadding,
+  canvasWidth: number,
+  font: SkFont,
+): TooltipLayout {
+  "worklet";
+  if (!scrubActive || lines.length === 0) return HIDDEN_TOOLTIP;
+
+  const fm = font.getMetrics();
+  const lineH = -fm.ascent + fm.descent;
+  const lineGap = TOOLTIP_LINE_GAP;
+  const n = lines.length;
+  const totalH = TOOLTIP_PAD_Y * 2 + lineH * n + lineGap * Math.max(0, n - 1);
+
+  let contentW = 0;
+  const lineWidths: number[] = [];
+  for (let i = 0; i < n; i++) {
+    const w = measureFontTextWidth(font, lines[i].text);
+    lineWidths.push(w);
+    if (w > contentW) contentW = w;
+  }
+  const pillW = contentW + TOOLTIP_PAD_X * 2;
+
+  const rightEdge = canvasWidth - padding.right;
+  let pillX = scrubX + TOOLTIP_OFFSET_X;
+  if (pillX + pillW > rightEdge - TOOLTIP_EDGE_GAP) {
+    pillX = scrubX - pillW - TOOLTIP_OFFSET_X;
+  }
+  const pillY = padding.top + TOOLTIP_TOP_MARGIN;
+
+  const stackedLines: {
+    text: string;
+    textX: number;
+    baselineY: number;
+    dim: boolean;
+  }[] = [];
+  let y = pillY + TOOLTIP_PAD_Y - fm.ascent;
+  for (let i = 0; i < n; i++) {
+    stackedLines.push({
+      text: lines[i].text,
+      textX: pillX + TOOLTIP_PAD_X + (contentW - lineWidths[i]) / 2,
+      baselineY: y,
+      dim: lines[i].dim,
+    });
+    y += lineH + lineGap;
+  }
+
+  return {
+    x: pillX,
+    y: pillY,
+    w: pillW,
+    h: totalH,
+    valueStr: "",
+    timeStr: "",
+    valueTextX: -400,
+    timeTextX: -400,
+    line1Y: 0,
+    line2Y: 0,
+    stackedLines,
+  };
+}
+
+/**
+ * Candle-mode tooltip — 5 stacked rows: O, H, L, C (bright) + time (dim).
+ */
+export function computeCandleTooltipLayout(
+  scrubActive: boolean,
+  scrubX: number,
+  candle: { open: number; high: number; low: number; close: number } | null,
+  scrubTime: number,
+  padding: ChartPadding,
+  canvasWidth: number,
+  formatValue: (v: number) => string,
+  formatTime: (t: number) => string,
+  font: SkFont,
+): TooltipLayout {
+  "worklet";
+  if (!scrubActive || !candle) return HIDDEN_TOOLTIP;
+  const lines: { text: string; dim: boolean }[] = [
+    { text: `O ${formatValue(candle.open)}`, dim: false },
+    { text: `H ${formatValue(candle.high)}`, dim: false },
+    { text: `L ${formatValue(candle.low)}`, dim: false },
+    { text: `C ${formatValue(candle.close)}`, dim: false },
+    { text: formatTime(scrubTime), dim: true },
+  ];
+  return computeTooltipLayoutMulti(
+    scrubActive,
+    scrubX,
+    lines,
+    padding,
+    canvasWidth,
+    font,
+  );
+}
+
+/** Single-series scrub value at window time — extracted for tests. */
+export function deriveScrubValueSingle(
+  scrubActive: boolean,
+  scrubTime: number,
+  data: { time: number; value: number }[],
+): number | null {
+  "worklet";
+  if (!scrubActive || scrubTime < 0) return null;
+  return interpolateAtTime(data, scrubTime);
+}
+
+/** Single-series crosshair tooltip — extracted for tests. */
+export function deriveCrosshairTooltipSingle(
+  scrubActive: boolean,
+  scrubX: number,
+  scrubTime: number,
+  scrubValue: number | null,
+  padding: ChartPadding,
+  canvasWidth: number,
+  formatValue: (v: number) => string,
+  formatTime: (t: number) => string,
+  font: SkFont,
+): TooltipLayout {
+  "worklet";
+  if (!scrubActive || scrubTime < 0) return HIDDEN_TOOLTIP;
+  return computeTooltipLayout(
+    scrubActive,
+    scrubX,
+    scrubValue,
+    scrubTime,
+    padding,
+    canvasWidth,
+    formatValue,
+    formatTime,
+    font,
+  );
+}

package/src/hooks/index.ts

@@ -0,0 +1,26 @@
+export { resolveChartLayout } from "./resolveChartLayout";
+export { useBadge } from "./useBadge";
+export { useCandlePaths } from "./useCandlePaths";
+export { useCanvasLayout } from "./useCanvasLayout";
+export { useChartColors } from "./useChartColors";
+export { useChartPaths } from "./useChartPaths";
+export { useChartReveal } from "./useChartReveal";
+export { useChartSkiaFont } from "./useChartSkiaFont";
+export { useCrosshair } from "./useCrosshair";
+export { useCrosshairSeries } from "./useCrosshairSeries";
+export { useDegen } from "./useDegen";
+export { useLiveChartHasData } from "./useLiveChartHasData";
+export { useLiveDot } from "./useLiveDot";
+export { useMarkers } from "./useMarkers";
+export { useModeBlend } from "./useModeBlend";
+export { useMomentum } from "./useMomentum";
+export { useMultiSeriesDegen } from "./useMultiSeriesDegen";
+export { useMultiSeriesLinePaths } from "./useMultiSeriesLinePaths";
+export { useReferenceLine } from "./useReferenceLine";
+export {
+  useMultiSeriesReverseMorphInputs,
+  useSingleChartReverseMorphInputs,
+} from "./useReverseMorphEngineInputs";
+export { useTradeStream } from "./useTradeStream";
+export { useXAxis } from "./useXAxis";
+export { useYAxis } from "./useYAxis";

package/src/hooks/resolveChartLayout.ts

@@ -0,0 +1,144 @@
+import type { SkFont } from "@shopify/react-native-skia";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import {
+  minPaddingRightForBadgeYAxisAlign,
+  minPaddingRightForYAxisWithPulse,
+  pulseRadialOutset,
+  resolveAutoLeft,
+  resolveAutoRight,
+  resolvePadding,
+  type ChartPadding,
+} from "../draw/line";
+import type { ChartInsets, LiveChartPalette } from "../types";
+
+export interface ChartLayoutConfig {
+  palette: LiveChartPalette;
+  lineWidthOverride?: number;
+  insetsOverride?: ChartInsets;
+  yAxis: boolean;
+  badge: boolean;
+  /**
+   * When true (default if omitted and `badge` is true), reserve the wide right gutter for the badge.
+   * Set false when the badge is anchored left of the live dot (`position: "left"`).
+   */
+  badgeUsesRightGutter?: boolean;
+  /** When false, bottom inset shrinks (no x-axis labels). Default true. */
+  xAxis?: boolean;
+  /** 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 */
+  formatValue?: (v: number) => string;
+  /** Current value read from SharedValue on JS thread — used to produce a sample label for measurement */
+  currentValue?: number;
+  /** Live dot pulse (LiveChart); expands top/right/bottom insets so the ring is not clipped. */
+  pulse?: { maxRadius: number; strokeWidth: number } | null;
+  /** When false and badge uses the right gutter, omit BADGE_TAIL_LEN from the right padding. */
+  badgeShowTail?: boolean;
+  /** Multi-series dot radius — used to add spacing between dots and Y-axis labels. */
+  multiSeriesDotRadius?: number;
+  /** When true, inline series labels sit right of dots and need extra right padding. */
+  multiSeriesValueLabel?: boolean;
+  /** Measured width of the widest series label (e.g. "Maybe"). Used when `multiSeriesValueLabel` is true. */
+  multiSeriesMaxLabelWidth?: number;
+}
+
+export interface ChartLayoutResult {
+  strokeWidth: number;
+  padding: ChartPadding;
+}
+
+export function resolveChartLayout(
+  config: ChartLayoutConfig,
+): ChartLayoutResult {
+  const badgeUsesRightGutter =
+    config.badge && (config.badgeUsesRightGutter ?? true);
+  const showTail = config.badgeShowTail ?? true;
+  const xAxis = config.xAxis ?? true;
+
+  let measuredYAxisLabelWidth: number | undefined;
+
+  // ── Right inset ──────────────────────────────────────────────────────────
+  let rightPad: number;
+  if (config.insetsOverride?.right != null) {
+    rightPad = config.insetsOverride.right;
+  } else if (
+    config.font &&
+    config.formatValue &&
+    config.currentValue != null &&
+    (badgeUsesRightGutter || !config.badge || config.yAxis)
+  ) {
+    const v = config.currentValue;
+    const samples = [v, v / 10, v / 100, v * 10].map(config.formatValue);
+    measuredYAxisLabelWidth = Math.max(
+      ...samples.map((s) => measureFontTextWidth(config.font!, s)),
+    );
+    const dotR = config.multiSeriesDotRadius ?? 0;
+    const seriesLabelW = config.multiSeriesMaxLabelWidth ?? 0;
+    rightPad = badgeUsesRightGutter
+      ? minPaddingRightForBadgeYAxisAlign(
+          config.font.getSize(),
+          measuredYAxisLabelWidth,
+          showTail,
+        )
+      : config.multiSeriesValueLabel && config.yAxis
+        ? Math.max(
+            dotR + 8 + seriesLabelW + 8 + measuredYAxisLabelWidth + 8,
+            44,
+          )
+        : config.multiSeriesValueLabel
+          ? Math.max(dotR + 8 + seriesLabelW + 8, 44)
+          : config.yAxis
+            ? Math.max(measuredYAxisLabelWidth + 16 + dotR * 2, 44)
+            : resolveAutoRight(false, false);
+  } else {
+    rightPad = resolveAutoRight(config.yAxis, badgeUsesRightGutter, showTail);
+  }
+
+  if (config.pulse && config.yAxis && config.insetsOverride?.right == null) {
+    const outlet = pulseRadialOutset(
+      config.pulse.maxRadius,
+      config.pulse.strokeWidth,
+    );
+    const labelW = measuredYAxisLabelWidth ?? 49;
+    rightPad = Math.max(
+      rightPad,
+      minPaddingRightForYAxisWithPulse(outlet, labelW),
+    );
+  }
+
+  // ── Left inset ───────────────────────────────────────────────────────────
+  let leftPad: number;
+  if (config.insetsOverride?.left != null) {
+    leftPad = config.insetsOverride.left;
+  } else {
+    leftPad = resolveAutoLeft(false);
+  }
+
+  const base = resolvePadding(
+    config.insetsOverride,
+    config.yAxis,
+    badgeUsesRightGutter,
+    false,
+    xAxis,
+    showTail,
+  );
+
+  let padding: ChartPadding = { ...base, right: rightPad, left: leftPad };
+  if (config.pulse) {
+    const outlet = pulseRadialOutset(
+      config.pulse.maxRadius,
+      config.pulse.strokeWidth,
+    );
+    padding = {
+      ...padding,
+      right: Math.max(padding.right, outlet),
+      top: Math.max(padding.top, outlet),
+      bottom: Math.max(padding.bottom, outlet),
+    };
+  }
+
+  return {
+    strokeWidth: config.lineWidthOverride ?? config.palette.lineWidth,
+    padding,
+  };
+}

package/src/hooks/useBadge.ts

@@ -0,0 +1,192 @@
+import { Skia, type SkFont, type SkPath } from "@shopify/react-native-skia";
+import { useRef } from "react";
+import {
+  useDerivedValue,
+  useSharedValue,
+  type SharedValue,
+} from "react-native-reanimated";
+import {
+  BADGE_DOT_GAP,
+  BADGE_MARGIN_RIGHT,
+  BADGE_PILL_PAD_X,
+  BADGE_PILL_PAD_Y,
+  BADGE_TAIL_LEN,
+  MS_PER_FRAME_60FPS,
+} from "../constants";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import type { ChartEngineWithLiveValue } from "../core/useLiveChartEngine";
+import {
+  badgeTailAndCap,
+  pillTextLeftX,
+  type ChartPadding,
+} from "../draw/line";
+import { hexToRgb, lerpColor } from "../math/color";
+import { lerp } from "../math/lerp";
+import type { BadgeVariant, LiveChartPalette, Momentum } from "../types";
+
+const TAIL_SPREAD = 2.5;
+
+export function useBadge(
+  engine: ChartEngineWithLiveValue,
+  padding: ChartPadding,
+  palette: LiveChartPalette,
+  formatValue: (v: number) => string,
+  font: SkFont,
+  variant: BadgeVariant = "default",
+  showTail = true,
+  momentum?: SharedValue<Momentum>,
+  position: "right" | "left" = "right",
+  background?: string,
+) {
+  const colorR = useSharedValue(0);
+  const colorG = useSharedValue(0);
+  const colorB = useSharedValue(0);
+
+  const upRgb = hexToRgb(palette.dotUp);
+  const downRgb = hexToRgb(palette.dotDown);
+  const accentRgb = hexToRgb(palette.badgeBg);
+
+  // Ping-pong between two persistent badge paths so the derived value always
+  // returns a freshly-mutated SkPath without allocating a new one every frame.
+  // See useChartPaths for the full rationale on per-frame Skia.Path.Make().
+  const cacheRef = useRef<{
+    a: SkPath;
+    b: SkPath;
+    tick: boolean;
+  } | null>(null);
+  if (cacheRef.current === null) {
+    cacheRef.current = {
+      a: Skia.Path.Make(),
+      b: Skia.Path.Make(),
+      tick: false,
+    };
+  }
+
+  const badge = useDerivedValue(() => {
+    const cache = cacheRef.current!;
+    const w = engine.canvasWidth.get();
+    const h = engine.canvasHeight.get();
+    cache.tick = !cache.tick;
+    const path = cache.tick ? cache.a : cache.b;
+    path.reset();
+    if (w === 0 || h === 0) {
+      return {
+        path,
+        textX: 0,
+        textY: 0,
+        text: "",
+        bgColor: palette.badgeBg,
+        textColor: palette.badgeText,
+      };
+    }
+
+    const chartH = h - padding.top - padding.bottom;
+    const dMin = engine.displayMin.get();
+    const dMax = engine.displayMax.get();
+    const valRange = dMax - dMin;
+    const dotY =
+      valRange === 0
+        ? padding.top + chartH / 2
+        : padding.top +
+          ((dMax - engine.displayValue.get()) / valRange) * chartH;
+
+    const text = formatValue(engine.displayValue.get());
+    const textW = measureFontTextWidth(font, text);
+
+    const pillH = font.getSize() + BADGE_PILL_PAD_Y * 2;
+    const r = pillH / 2;
+    const badgeY = dotY - pillH / 2;
+    let textX: number;
+
+    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 * BADGE_PILL_PAD_X + textW;
+      const bodyRight = dotXPos - BADGE_DOT_GAP;
+      const bodyLeft = Math.max(BADGE_MARGIN_RIGHT, bodyRight - pillW);
+      const pillBodyW = bodyRight - bodyLeft;
+      textX = (bodyLeft + bodyRight - textW) / 2;
+      path.addRRect({
+        rect: { x: bodyLeft, y: badgeY, width: pillBodyW, height: pillH },
+        rx: r,
+        ry: r,
+      });
+    } else {
+      // Right-gutter badge (default): asymmetric layout with optional tail.
+      const tl = badgeTailAndCap(font.getSize(), showTail);
+      const bodyLeft = w - padding.right + BADGE_DOT_GAP + tl;
+      const bodyRight = w - BADGE_MARGIN_RIGHT;
+      const pillW = bodyRight - bodyLeft;
+      // Text centered in pill body — same formula used by GridOverlay.
+      textX = pillTextLeftX(w, padding.right, BADGE_DOT_GAP + tl, textW);
+
+      if (showTail) {
+        const badgeX = w - padding.right + BADGE_DOT_GAP;
+        const cx = tl + pillW - r;
+
+        path.moveTo(badgeX + tl, badgeY);
+        path.lineTo(badgeX + cx, badgeY);
+        path.arcToOval(
+          { x: badgeX + cx - r, y: badgeY, width: r * 2, height: pillH },
+          -90,
+          180,
+          false,
+        );
+        path.lineTo(badgeX + tl, badgeY + pillH);
+        path.cubicTo(
+          badgeX + BADGE_TAIL_LEN + 2,
+          badgeY + pillH,
+          badgeX + 3,
+          badgeY + r + TAIL_SPREAD,
+          badgeX,
+          badgeY + r,
+        );
+        path.cubicTo(
+          badgeX + 3,
+          badgeY + r - TAIL_SPREAD,
+          badgeX + BADGE_TAIL_LEN + 2,
+          badgeY,
+          badgeX + tl,
+          badgeY,
+        );
+        path.close();
+      } else {
+        path.addRRect({
+          rect: { x: bodyLeft, y: badgeY, width: pillW, height: pillH },
+          rx: r,
+          ry: r,
+        });
+      }
+    }
+
+    const fm = font.getMetrics();
+    const textY = dotY - (fm.ascent + fm.descent) / 2;
+
+    let bgColor: string;
+    if (background) {
+      bgColor = background;
+    } else if (variant === "minimal") {
+      bgColor = "rgba(255,255,255,0.95)";
+    } else if (momentum) {
+      const m = momentum.get();
+      const targetRgb = m === "up" ? upRgb : m === "down" ? downRgb : accentRgb;
+      colorR.set(lerp(colorR.get(), targetRgb[0], 0.08, MS_PER_FRAME_60FPS));
+      colorG.set(lerp(colorG.get(), targetRgb[1], 0.08, MS_PER_FRAME_60FPS));
+      colorB.set(lerp(colorB.get(), targetRgb[2], 0.08, MS_PER_FRAME_60FPS));
+      bgColor = lerpColor(
+        [colorR.get(), colorG.get(), colorB.get()],
+        [colorR.get(), colorG.get(), colorB.get()],
+        0,
+      );
+    } else {
+      bgColor = palette.badgeBg;
+    }
+
+    const textColor =
+      variant === "minimal" ? "rgba(100,100,100,1)" : palette.badgeText;
+
+    return { path, textX, textY, text, bgColor, textColor };
+  });
+
+  return badge;
+}