react-native-livechart 1.0.0

package/src/components/TradeStreamOverlay.tsx

@@ -0,0 +1,117 @@
+import {
+  Group,
+  Text as SkiaText,
+  type SkFont,
+} from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { ChartPadding } from "../draw/line";
+import type { TradeMarker } from "../draw/trade";
+import { lerpColor } from "../math/color";
+import type { LiveChartPalette } from "../types";
+
+const MAX_TRADE_LABELS = 20;
+
+// Stable per-slot keys for the fixed-size, positional label pool: slot `i` always
+// renders ring-buffer index `i` and the tape never reorders, so each label keeps a
+// permanent identity. Keying by these ids (instead of the bare array index) makes
+// that explicit and avoids remounting labels as the tape scrolls.
+const TAPE_SLOT_KEYS = Array.from(
+  { length: MAX_TRADE_LABELS },
+  (_, i) => `trade-label-${i}`,
+);
+
+const GREEN: [number, number, number] = [34, 197, 94];
+const RED: [number, number, number] = [239, 68, 68];
+
+function TapeLabel({
+  index,
+  markers,
+  bgRgb,
+  labelX,
+  font,
+  groupOpacity,
+}: {
+  index: number;
+  markers: SharedValue<TradeMarker[]>;
+  bgRgb: [number, number, number];
+  labelX: number;
+  font: SkFont;
+  groupOpacity: SharedValue<number>;
+}) {
+  /* istanbul ignore next -- worklet */
+  const y = useDerivedValue(() => markers.value[index]?.y ?? -200);
+  /* istanbul ignore next -- worklet */
+  const text = useDerivedValue(() => markers.value[index]?.label ?? " ");
+
+  /* istanbul ignore next -- worklet */
+  const fillColor = useDerivedValue(() => {
+    const m = markers.value[index];
+    if (!m) return "transparent";
+    const base = m.green ? GREEN : RED;
+    return lerpColor(base, bgRgb, 1 - m.alpha);
+  });
+
+  /* istanbul ignore next -- worklet */
+  const outlineColor = useDerivedValue(() => {
+    const m = markers.value[index];
+    if (!m) return "transparent";
+    return `rgb(${bgRgb[0]},${bgRgb[1]},${bgRgb[2]})`;
+  });
+
+  /* istanbul ignore next -- worklet */
+  const opacity = useDerivedValue(() => {
+    const m = markers.value[index];
+    if (!m) return 0;
+    return groupOpacity.value;
+  });
+
+  return (
+    <Group opacity={opacity}>
+      <SkiaText
+        x={labelX}
+        y={y}
+        text={text}
+        font={font}
+        color={outlineColor}
+        style="stroke"
+        strokeWidth={0.5}
+        opacity={0.75}
+      />
+      <SkiaText x={labelX} y={y} text={text} font={font} color={fillColor} />
+    </Group>
+  );
+}
+
+export function TradeStreamOverlay({
+  markers,
+  palette,
+  padding,
+  font,
+  opacity,
+  labelOffsetX = 8,
+}: {
+  markers: SharedValue<TradeMarker[]>;
+  palette: LiveChartPalette;
+  padding: ChartPadding;
+  font: SkFont;
+  opacity: SharedValue<number>;
+  labelOffsetX?: number;
+}) {
+  const labelX = padding.left + labelOffsetX;
+  // Fixed-size persistent slot pool (MAX_TRADE_LABELS). Each <TapeLabel> renders
+  // whatever trade currently occupies slot `i` (read from `markers` by index);
+  // the list never reorders or filters, so each slot keys by its stable per-slot
+  // id (see TAPE_SLOT_KEYS) rather than the bare array index.
+  const slots = TAPE_SLOT_KEYS.map((slotKey, i) => (
+    <TapeLabel
+      key={slotKey}
+      index={i}
+      markers={markers}
+      bgRgb={palette.bgRgb}
+      labelX={labelX}
+      font={font}
+      groupOpacity={opacity}
+    />
+  ));
+  return <Group>{slots}</Group>;
+}

package/src/components/ValueLineOverlay.tsx

@@ -0,0 +1,63 @@
+import {
+  DashPathEffect,
+  Path,
+  Skia,
+  type SkPath,
+} from "@shopify/react-native-skia";
+import { useRef } from "react";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartPadding } from "../draw/line";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+
+/**
+ * A dashed horizontal line that tracks the live display value — sitting at
+ * the same Y as the badge and live dot. Rendered behind the chart line.
+ */
+export function ValueLineOverlay({
+  dotY,
+  engine,
+  padding,
+  strokeWidth,
+  intervals,
+  color,
+}: {
+  dotY: SharedValue<number>;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  strokeWidth: number;
+  intervals: [number, number];
+  color: string;
+}) {
+  // Ping-pong persistent paths — avoid allocating a JSI-backed SkPath per frame.
+  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 path = useDerivedValue(() => {
+    const cache = cacheRef.current!;
+    cache.tick = !cache.tick;
+    const p = cache.tick ? cache.a : cache.b;
+    p.reset();
+    const y = dotY.get();
+    if (y < 0) return p;
+    p.moveTo(padding.left, y);
+    p.lineTo(engine.canvasWidth.get() - padding.right, y);
+    return p;
+  });
+
+  return (
+    <Path path={path} style="stroke" strokeWidth={strokeWidth} color={color}>
+      <DashPathEffect intervals={intervals} />
+    </Path>
+  );
+}

package/src/components/ValueTextOverlay.tsx

@@ -0,0 +1,43 @@
+import { Text as SkiaText, type SkFont } from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { ChartEngineWithLiveValue } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import type { LiveChartPalette, Momentum } from "../types";
+
+/**
+ * Large live-value text rendered in the top-left of the plot. Tracks the
+ * engine's smoothed display value on the UI thread; optionally tinted by
+ * momentum (green up / red down / accent flat).
+ */
+export function ValueTextOverlay({
+  engine,
+  padding,
+  palette,
+  font,
+  formatValue,
+  momentum,
+  momentumColor,
+}: {
+  engine: ChartEngineWithLiveValue;
+  padding: ChartPadding;
+  palette: LiveChartPalette;
+  font: SkFont;
+  formatValue: (v: number) => string;
+  momentum?: SharedValue<Momentum>;
+  momentumColor: boolean;
+}) {
+  const text = useDerivedValue(() => formatValue(engine.displayValue.value));
+
+  const color = useDerivedValue(() => {
+    if (!momentumColor || !momentum) return palette.line;
+    const m = momentum.value;
+    if (m === "up") return palette.dotUp;
+    if (m === "down") return palette.dotDown;
+    return palette.dotFlat;
+  });
+
+  const x = padding.left + 6;
+  const y = padding.top + font.getSize();
+
+  return <SkiaText x={x} y={y} text={text} font={font} color={color} />;
+}

package/src/components/XAxisOverlay.tsx

@@ -0,0 +1,109 @@
+import {
+  Group,
+  Path,
+  Skia,
+  type SkFont,
+  type SkPath,
+} from "@shopify/react-native-skia";
+import { useRef } from "react";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import type { XAxisEntry } from "../hooks/useXAxis";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import type { LiveChartPalette } from "../types";
+import { AnimatedLabel } from "./AnimatedLabel";
+
+const MAX_X_LABELS = 10;
+const TICK_HEIGHT = 5;
+const LABEL_OFFSET_Y = 19;
+
+export function XAxisOverlay({
+  entries,
+  engine,
+  padding,
+  palette,
+  font,
+}: {
+  entries: SharedValue<XAxisEntry[]>;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  palette: LiveChartPalette;
+  font: SkFont;
+}) {
+  const axisCacheRef = useRef<{
+    a: SkPath;
+    b: SkPath;
+    tick: boolean;
+  } | null>(null);
+  if (axisCacheRef.current === null) {
+    axisCacheRef.current = {
+      a: Skia.Path.Make(),
+      b: Skia.Path.Make(),
+      tick: false,
+    };
+  }
+
+  const axisPath = useDerivedValue(() => {
+    "worklet";
+    const axisCache = axisCacheRef.current!;
+    axisCache.tick = !axisCache.tick;
+    const path = axisCache.tick ? axisCache.a : axisCache.b;
+    path.reset();
+    const w = engine.canvasWidth.get();
+    const h = engine.canvasHeight.get();
+    const lineY = h - padding.bottom;
+
+    // Bottom axis line
+    path.moveTo(padding.left, lineY);
+    path.lineTo(w - padding.right, lineY);
+
+    // Tick marks
+    const items = entries.get();
+    for (let i = 0; i < items.length; i++) {
+      path.moveTo(items[i].x, lineY);
+      path.lineTo(items[i].x, lineY + TICK_HEIGHT);
+    }
+    return path;
+  });
+
+  // Transform XAxisEntry[] into { x, y, label, alpha } for AnimatedLabel
+  const labelEntries = useDerivedValue(() => {
+    "worklet";
+    const items = entries.get();
+    const h = engine.canvasHeight.get();
+    const y = h - padding.bottom + LABEL_OFFSET_Y;
+    const n = items.length;
+    const out: { x: number; y: number; label: string; alpha: number }[] = [];
+    for (let i = 0; i < n; i++) {
+      const e = items[i];
+      out.push({
+        x: e.x - measureFontTextWidth(font, e.label) / 2,
+        y,
+        label: e.label,
+        alpha: e.alpha,
+      });
+    }
+    return out;
+  });
+
+  return (
+    <Group>
+      <Path
+        path={axisPath}
+        style="stroke"
+        strokeWidth={1}
+        color={palette.gridLine}
+      />
+      {Array.from({ length: MAX_X_LABELS }, (_, i) => (
+        <AnimatedLabel
+          key={i}
+          entries={labelEntries}
+          index={i}
+          font={font}
+          color={palette.timeLabel}
+        />
+      ))}
+    </Group>
+  );
+}

package/src/components/YAxisOverlay.tsx

@@ -0,0 +1,135 @@
+import {
+  DashPathEffect,
+  Group,
+  Path,
+  Skia,
+  type SkFont,
+  type SkPath,
+} from "@shopify/react-native-skia";
+import { useRef } from "react";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import { BADGE_DOT_GAP } from "../constants";
+import type { ResolvedGridStyleConfig } from "../core/resolveConfig";
+import type { YAxisEntry } from "../draw/grid";
+import {
+  badgeTailAndCap,
+  gutterCenteredTextLeftX,
+  gutterRightAlignedTextLeftX,
+  pillTextLeftX,
+  type ChartPadding,
+} from "../draw/line";
+import { measureFontTextWidth } from "../lib/measureFontTextWidth";
+import type { LiveChartPalette } from "../types";
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import { AnimatedLabel } from "./AnimatedLabel";
+
+const MAX_Y_LABELS = 15;
+
+export function YAxisOverlay({
+  entries,
+  engine,
+  padding,
+  palette,
+  font,
+  badge = false,
+  badgeTail = true,
+  seriesLabelInset = 0,
+  gridStyle,
+}: {
+  entries: SharedValue<YAxisEntry[]>;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  palette: LiveChartPalette;
+  font: SkFont;
+  /** When true, use the asymmetric pill centering formula so labels align with badge text. */
+  badge?: boolean;
+  /** Whether the badge tail spike is shown; affects the left inset used for label alignment. */
+  badgeTail?: boolean;
+  /** When > 0, series labels occupy the left portion of the gutter; Y-axis labels right-align. */
+  seriesLabelInset?: number;
+  /** Grid-line styling overrides. Omit for the legacy solid 1px line. */
+  gridStyle?: ResolvedGridStyleConfig;
+}) {
+  const gridColor = gridStyle?.color ?? palette.gridLine;
+  const gridWidth = gridStyle?.strokeWidth ?? 1;
+  const gridIntervals = gridStyle?.intervals ?? [];
+  const gridOpacity = gridStyle?.opacity ?? 1;
+  const gridCacheRef = useRef<{
+    a: SkPath;
+    b: SkPath;
+    tick: boolean;
+  } | null>(null);
+  if (gridCacheRef.current === null) {
+    gridCacheRef.current = {
+      a: Skia.Path.Make(),
+      b: Skia.Path.Make(),
+      tick: false,
+    };
+  }
+
+  const gridLinesPath = useDerivedValue(() => {
+    const gridCache = gridCacheRef.current!;
+    gridCache.tick = !gridCache.tick;
+    const path = gridCache.tick ? gridCache.a : gridCache.b;
+    path.reset();
+    const items = entries.get();
+    const w = engine.canvasWidth.get();
+    for (let i = 0; i < items.length; i++) {
+      path.moveTo(padding.left, items[i].y);
+      path.lineTo(w - padding.right, items[i].y);
+    }
+    return path;
+  });
+
+  const leftInset = BADGE_DOT_GAP + badgeTailAndCap(font.getSize(), badgeTail);
+
+  const labelEntries = useDerivedValue(() => {
+    const items = entries.get();
+    const w = engine.canvasWidth.get();
+    const fm = font.getMetrics();
+    const baselineOffset = (fm.ascent + fm.descent) / 2;
+    const result: { x: number; y: number; label: string; alpha: number }[] = [];
+    for (let i = 0; i < items.length; i++) {
+      const e = items[i];
+      const textW = measureFontTextWidth(font, e.label);
+      const x = badge
+        ? pillTextLeftX(w, padding.right, leftInset, textW)
+        : seriesLabelInset > 0
+          ? gutterRightAlignedTextLeftX(w, textW)
+          : gutterCenteredTextLeftX(w, padding.right, textW);
+      result.push({
+        x,
+        y: e.y - baselineOffset,
+        label: e.label,
+        alpha: e.alpha,
+      });
+    }
+    return result;
+  });
+
+  return (
+    <Group>
+      <Group opacity={gridOpacity}>
+        <Path
+          path={gridLinesPath}
+          style="stroke"
+          strokeWidth={gridWidth}
+          color={gridColor}
+        >
+          {gridIntervals.length > 0 && (
+            <DashPathEffect intervals={gridIntervals} />
+          )}
+        </Path>
+      </Group>
+      {Array.from({ length: MAX_Y_LABELS }, (_, i) => (
+        <AnimatedLabel
+          key={i}
+          entries={labelEntries}
+          index={i}
+          font={font}
+          color={palette.gridLabel}
+        />
+      ))}
+    </Group>
+  );
+}

package/src/components/seriesMetaSig.ts

@@ -0,0 +1,13 @@
+import type { SeriesConfig } from "../types";
+
+/** Exported for tests — mirrors chip labels without subscribing to every data tick. */
+export function seriesMetaSig(s: SeriesConfig[]): string {
+  "worklet";
+  let out = "";
+  for (let i = 0; i < s.length; i++) {
+    if (i > 0) out += "\x1e";
+    const x = s[i];
+    out += `${x.id}\x1f${x.label ?? ""}\x1f${x.color ?? ""}\x1f${x.visible === false ? 0 : 1}`;
+  }
+  return out;
+}

package/src/constants.ts

@@ -0,0 +1,44 @@
+/** Milliseconds per frame at 60 fps — baseline for frame-rate-independent lerp. */
+export const MS_PER_FRAME_60FPS = 16.67;
+
+/** Extra speed applied to catch up when the live dot lags behind the target. */
+export const ADAPTIVE_SPEED_BOOST = 0.12;
+
+/** Horizontal padding inside the badge pill, on each side of the label. */
+export const BADGE_PILL_PAD_X = 10;
+/** Vertical padding above and below the label inside the badge pill. */
+export const BADGE_PILL_PAD_Y = 3;
+/** Length of the badge tail (the pointed spike toward the dot). */
+export const BADGE_TAIL_LEN = 5;
+/** Gap between the pill's right edge and the canvas right edge. */
+export const BADGE_MARGIN_RIGHT = 4;
+/** Gap between the live dot and the badge tail tip. */
+export const BADGE_DOT_GAP = 12;
+
+/** Maximum simultaneous series rendered (paths/dots slots). */
+export const MAX_MULTI_SERIES = 12;
+
+/** Default width (px) of the left-edge fade band */
+export const FADE_EDGE_WIDTH = 40;
+
+/** Empty-state label opacity. */
+export const EMPTY_STATE_LABEL_ALPHA = 0.35;
+/** Half-padding (px) around empty text for the squiggle “gap” erase band. */
+export const EMPTY_TEXT_GAP_PAD = 20;
+/** Horizontal fade width (px) on each side of the empty-text gap. */
+export const EMPTY_GAP_FADE_WIDTH = 30;
+
+/**
+ * Floats per degen particle slot: `x, y, vx, vy, t0, active, size, colorIndex`.
+ * `colorIndex` selects which entry of the renderer's color list a particle uses
+ * (multi-series sets it per series; single-series cycles it per particle).
+ * Layout is fixed; not on `DegenOptions` because changing it needs matching renderer changes.
+ */
+export const DEGEN_STRIDE = 8;
+
+/**
+ * Default chart accent color — the full light/dark palette is derived from this
+ * when a consumer omits `accentColor`. Single source of truth for the brand
+ * default; change it here to re-brand the default everywhere.
+ */
+export const DEFAULT_ACCENT_COLOR = "#3323E6";