react-native-livechart 1.0.0 → 2.0.0

package/src/hooks/useBadge.ts

@@ -6,11 +6,8 @@ import {
   type SharedValue,
 } from "react-native-reanimated";
 import {
-  BADGE_DOT_GAP,
-  BADGE_MARGIN_RIGHT,
-  BADGE_PILL_PAD_X,
-  BADGE_PILL_PAD_Y,
-  BADGE_TAIL_LEN,
+  BADGE_METRICS_DEFAULTS,
+  MOTION_METRICS_DEFAULTS,
   MS_PER_FRAME_60FPS,
 } from "../constants";
 import { measureFontTextWidth } from "../lib/measureFontTextWidth";
@@ -22,9 +19,12 @@ import {
 } 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;
+import type {
+  BadgeMetrics,
+  BadgeVariant,
+  LiveChartPalette,
+  Momentum,
+} from "../types";
 
 export function useBadge(
   engine: ChartEngineWithLiveValue,
@@ -37,6 +37,8 @@ export function useBadge(
   momentum?: SharedValue<Momentum>,
   position: "right" | "left" = "right",
   background?: string,
+  badgeMetrics: BadgeMetrics = BADGE_METRICS_DEFAULTS,
+  badgeColorSpeed: number = MOTION_METRICS_DEFAULTS.badgeColorSpeed,
 ) {
   const colorR = useSharedValue(0);
   const colorG = useSharedValue(0);
@@ -93,7 +95,7 @@ export function useBadge(
     const text = formatValue(engine.displayValue.get());
     const textW = measureFontTextWidth(font, text);
 
-    const pillH = font.getSize() + BADGE_PILL_PAD_Y * 2;
+    const pillH = font.getSize() + badgeMetrics.padY * 2;
     const r = pillH / 2;
     const badgeY = dotY - pillH / 2;
     let textX: number;
@@ -101,9 +103,9 @@ export function useBadge(
     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 pillW = 2 * badgeMetrics.padX + textW;
+      const bodyRight = dotXPos - badgeMetrics.dotGap;
+      const bodyLeft = Math.max(badgeMetrics.marginEdge, bodyRight - pillW);
       const pillBodyW = bodyRight - bodyLeft;
       textX = (bodyLeft + bodyRight - textW) / 2;
       path.addRRect({
@@ -113,15 +115,21 @@ export function useBadge(
       });
     } 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 tl = badgeTailAndCap(font.getSize(), showTail, badgeMetrics);
+      const bodyLeft = w - padding.right + badgeMetrics.dotGap + tl;
+      const bodyRight = w - badgeMetrics.marginEdge;
       const pillW = bodyRight - bodyLeft;
       // Text centered in pill body — same formula used by GridOverlay.
-      textX = pillTextLeftX(w, padding.right, BADGE_DOT_GAP + tl, textW);
+      textX = pillTextLeftX(
+        w,
+        padding.right,
+        badgeMetrics.dotGap + tl,
+        textW,
+        badgeMetrics,
+      );
 
       if (showTail) {
-        const badgeX = w - padding.right + BADGE_DOT_GAP;
+        const badgeX = w - padding.right + badgeMetrics.dotGap;
         const cx = tl + pillW - r;
 
         path.moveTo(badgeX + tl, badgeY);
@@ -134,17 +142,17 @@ export function useBadge(
         );
         path.lineTo(badgeX + tl, badgeY + pillH);
         path.cubicTo(
-          badgeX + BADGE_TAIL_LEN + 2,
+          badgeX + badgeMetrics.tailLength + 2,
           badgeY + pillH,
           badgeX + 3,
-          badgeY + r + TAIL_SPREAD,
+          badgeY + r + badgeMetrics.tailSpread,
           badgeX,
           badgeY + r,
         );
         path.cubicTo(
           badgeX + 3,
-          badgeY + r - TAIL_SPREAD,
-          badgeX + BADGE_TAIL_LEN + 2,
+          badgeY + r - badgeMetrics.tailSpread,
+          badgeX + badgeMetrics.tailLength + 2,
           badgeY,
           badgeX + tl,
           badgeY,
@@ -170,9 +178,15 @@ export function useBadge(
     } 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));
+      colorR.set(
+        lerp(colorR.get(), targetRgb[0], badgeColorSpeed, MS_PER_FRAME_60FPS),
+      );
+      colorG.set(
+        lerp(colorG.get(), targetRgb[1], badgeColorSpeed, MS_PER_FRAME_60FPS),
+      );
+      colorB.set(
+        lerp(colorB.get(), targetRgb[2], badgeColorSpeed, MS_PER_FRAME_60FPS),
+      );
       bgColor = lerpColor(
         [colorR.get(), colorG.get(), colorB.get()],
         [colorR.get(), colorG.get(), colorB.get()],

package/src/hooks/useCandlePaths.ts

@@ -6,12 +6,12 @@ import {
   useSharedValue,
   type SharedValue,
 } from "react-native-reanimated";
-import { MS_PER_FRAME_60FPS } from "../constants";
+import { CANDLE_METRICS_DEFAULTS, MS_PER_FRAME_60FPS } from "../constants";
 import type { SingleEngineState } from "../core/useLiveChartEngine";
 import { buildCandleGeometry } from "../draw/candle";
 import type { ChartPadding } from "../draw/line";
 import { lerp } from "../math/lerp";
-import type { CandlePoint } from "../types";
+import type { CandleMetrics, CandlePoint } from "../types";
 
 const CANDLE_WIDTH_LERP_SPEED = 0.08;
 
@@ -29,6 +29,7 @@ export function useCandlePaths(
   liveCandle: SharedValue<CandlePoint | null> | undefined,
   candleWidthSecs: number,
   active: boolean,
+  candleMetrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
 ) {
   const targetCandleWidth = useDerivedValue(() => candleWidthSecs);
   const displayCandleWidth = useSharedValue(candleWidthSecs);
@@ -92,6 +93,7 @@ export function useCandlePaths(
       engine.displayMin.value,
       engine.displayMax.value,
       displayCandleWidth.get(),
+      candleMetrics,
     );
   });
 

package/src/hooks/useCrosshair.ts

@@ -55,6 +55,8 @@ export function useCrosshair(
   enabled: boolean,
   onScrub?: (point: ScrubPoint | null) => void,
   candleOpts?: CrosshairCandleOpts,
+  /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
+  panGestureDelay = 0,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -110,6 +112,11 @@ export function useCrosshair(
     ),
   );
 
+  // Monospace advance width, measured once per render (not per scrub frame) so
+  // the tooltip layout worklet can size text by character count instead of a
+  // per-frame Skia measureText.
+  const monoCharWidth = font.measureText("0").width;
+
   const tooltipLayout = useDerivedValue(() => {
     if (isCandleMode) {
       return computeCandleTooltipLayout(
@@ -122,6 +129,7 @@ export function useCrosshair(
         formatValue,
         formatTime,
         font,
+        monoCharWidth,
       );
     }
     return deriveCrosshairTooltipSingle(
@@ -134,6 +142,7 @@ export function useCrosshair(
       formatValue,
       formatTime,
       font,
+      monoCharWidth,
     );
   });
 
@@ -207,10 +216,14 @@ export function useCrosshair(
 
   let gesture = Gesture.Pan()
     .minDistance(Platform.OS === "android" ? 10 : 0)
-    .activateAfterLongPress(0)
+    .activateAfterLongPress(panGestureDelay)
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
-    .onBegin(
+    // Start scrubbing on ACTIVE (onStart), not on touch-down (onBegin):
+    // `activateAfterLongPress` only delays activation, so onBegin still fires
+    // immediately — using it would scrub instantly and ignore panGestureDelay,
+    // and leave scrubActive stuck for taps that never reach the long-press.
+    .onStart(
       /* istanbul ignore next */ (e) => {
         "worklet";
         if (!enabled) return;

package/src/hooks/useCrosshairSeries.ts

@@ -28,6 +28,8 @@ export function useCrosshairSeries(
   padding: ChartPadding,
   enabled: boolean,
   onScrub?: (point: ScrubPointMulti | null) => void,
+  /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
+  panGestureDelay = 0,
 ): CrosshairState {
   const scrubX = useSharedValue(-1);
   const scrubActive = useSharedValue(false);
@@ -121,10 +123,14 @@ export function useCrosshairSeries(
 
   let gesture = Gesture.Pan()
     .minDistance(Platform.OS === "android" ? 10 : 0)
-    .activateAfterLongPress(0)
+    .activateAfterLongPress(panGestureDelay)
     .maxPointers(1)
     .shouldCancelWhenOutside(false)
-    .onBegin(
+    // Start scrubbing on ACTIVE (onStart), not on touch-down (onBegin):
+    // `activateAfterLongPress` only delays activation, so onBegin still fires
+    // immediately — using it would scrub instantly and ignore panGestureDelay,
+    // and leave scrubActive stuck for taps that never reach the long-press.
+    .onStart(
       /* istanbul ignore next */ (e) => {
         "worklet";
         if (!enabled) return;

package/src/hooks/useYAxis.ts

@@ -1,10 +1,11 @@
 import { useDerivedValue, useSharedValue } from "react-native-reanimated";
 
 import type { SkFont } from "@shopify/react-native-skia";
-import { MS_PER_FRAME_60FPS } from "../constants";
+import { GRID_METRICS_DEFAULTS, MS_PER_FRAME_60FPS } from "../constants";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import { computeGridEntries } from "../draw/grid";
 import type { ChartPadding } from "../draw/line";
+import type { GridMetrics } from "../types";
 
 /**
  * Compute Y-axis grid entries (values + labels) with animated fade-in/out.
@@ -17,6 +18,7 @@ export function useYAxis(
   formatValue: (v: number) => string,
   font: SkFont,
   minGap = 36,
+  gridMetrics: GridMetrics = GRID_METRICS_DEFAULTS,
 ) {
   const prevInterval = useSharedValue(0);
   const labelAlphas = useSharedValue<Record<number, number>>({});
@@ -36,6 +38,7 @@ export function useYAxis(
       formatValue,
       dt,
       minGap,
+      gridMetrics,
     );
 
     prevInterval.set(result.interval);

package/src/index.ts

@@ -29,20 +29,26 @@ export { useTradeStream } from "./hooks/useTradeStream";
 
 export type {
   BadgeConfig,
+  BadgeMetrics,
   BadgeVariant,
+  CandleMetrics,
   CandlePoint,
   ChartInsets,
   DegenOptions,
   DegenShakePayload,
+  EmptyStateMetrics,
   FontConfig,
   FontWeight,
   GradientConfig,
+  GridMetrics,
   GridStyleConfig,
   LeftEdgeFadeConfig,
   LegendConfig,
   LegendStyle,
   LineConfig,
   LiveChartCoreProps,
+  LiveChartMetrics,
+  LiveChartMetricsOverride,
   LiveChartPalette,
   LiveChartPoint,
   LiveChartProps,
@@ -52,6 +58,7 @@ export type {
   MarkerKind,
   Momentum,
   MomentumConfig,
+  MotionMetrics,
   MultiSeriesDotConfig,
   PulseConfig,
   ReferenceLine,

package/src/types.ts

@@ -203,6 +203,14 @@ export interface ScrubConfig {
   tooltipColor?: string;
   /** Tooltip pill border color. Omit to use theme `tooltipBorder`. */
   tooltipBorderColor?: string;
+  /**
+   * Press-and-hold delay in milliseconds before scrubbing activates — think of
+   * it as "press and hold to scrub." During the delay the pan is not captured,
+   * so a quick horizontal swipe falls through to a parent gesture (e.g. a
+   * navigator's swipe-back-to-previous-route). `0` = scrub immediately on drag.
+   * Default `0`.
+   */
+  panGestureDelay?: number;
 }
 
 /** Left-edge fade — soft erase so the chart blends into the left gutter (web liveline parity). */
@@ -392,10 +400,43 @@ export interface DegenShakePayload {
   direction: "up" | "down";
 }
 
-/** Live dot configuration for multi-series charts. */
-export interface MultiSeriesDotConfig {
-  /** Dot radius in pixels. Default `3.5`. */
+/** Contrasting outer ring drawn behind each series dot — the "haloed" look the
+ *  single-series live dot has, so dots stand out against the lines and one
+ *  another. */
+export interface DotRingConfig {
+  /** Ring color. Default: theme `badgeOuterBg` (a near-background halo). */
+  color?: string;
+  /** Ring thickness in pixels — how far the halo extends past the dot. Default `2.5`. */
+  width?: number;
+}
+
+/**
+ * Shared live-dot styling, used by both `LiveChart` (`dot`) and
+ * `LiveChartSeries` (`dot`, which extends this). A dot is a color-filled circle
+ * of `radius` with an optional contrasting outer `ring` (halo).
+ */
+export interface DotConfig {
+  /** Radius of the (color-filled) dot in pixels. Default `3.5`. */
   radius?: number;
+  /**
+   * Contrasting outer ring (halo) behind the dot, so it reads clearly against
+   * the line(s). `true` = defaults, `false` = a flat circle, or pass
+   * `DotRingConfig`. Default `true`.
+   */
+  ring?: boolean | DotRingConfig;
+  /**
+   * Show the dot. `false` hides it (line, badge, and labels still render). Default `true`.
+   *
+   * @deprecated Pass `dot={false}` to hide the dot — the uniform `boolean | Config`
+   * convention. `show` still works and is equivalent to `dot={{ show: false }}`.
+   */
+  show?: boolean;
+  /** Dot fill color. Defaults to the chart line color (per series for multi-series). */
+  color?: string;
+}
+
+/** Live dot configuration for multi-series charts (extends the shared {@link DotConfig}). */
+export interface MultiSeriesDotConfig extends DotConfig {
   /** Pulsing ring animation on each series dot. `true` = defaults, or pass `PulseConfig`. Default `true`. */
   pulse?: boolean | PulseConfig;
   /** Horizontal dashed line at each series' live value. `true` = defaults, or pass `ValueLineConfig`. Default `false`. */
@@ -513,6 +554,92 @@ export interface CandlePoint {
   close: number;
 }
 
+// ── Metrics (sizing & motion tokens) ─────────────────────────────────────────
+
+/**
+ * Spatial sizing & motion tokens — the geometry/timing analogue of
+ * {@link LiveChartPalette}. Where `palette` controls *color*, `metrics` controls
+ * *shape* (badge geometry, candle bounds) and *feel* (fade/lerp speeds). Override
+ * via the `metrics` prop; only the namespaces/keys you set are replaced.
+ */
+export interface LiveChartMetrics {
+  /** Value-badge pill geometry. */
+  badge: BadgeMetrics;
+  /** Candlestick body/wick geometry. */
+  candle: CandleMetrics;
+  /** Grid + axis-label fade animation. */
+  grid: GridMetrics;
+  /** Per-frame lerp speeds for value/color transitions. */
+  motion: MotionMetrics;
+  /** Empty-state (no-data) layout. */
+  emptyState: EmptyStateMetrics;
+}
+
+/** Value-badge pill geometry (the "metrics" analogue of badge colors). */
+export interface BadgeMetrics {
+  /** Horizontal padding inside the pill, each side of the label. Default `10`. */
+  padX: number;
+  /** Vertical padding above and below the label. Default `3`. */
+  padY: number;
+  /** Length of the pointed tail toward the live dot. Default `5`. */
+  tailLength: number;
+  /** Gap between the pill's outer edge and the canvas edge. Default `4`. */
+  marginEdge: number;
+  /** Gap between the live dot and the badge tail tip. Default `12`. */
+  dotGap: number;
+  /** Vertical spread of the tail curve's control points. Default `2.5`. */
+  tailSpread: number;
+}
+
+/** Candlestick body/wick geometry. */
+export interface CandleMetrics {
+  /** Minimum candle body height in pixels (so dojis stay visible). Default `1`. */
+  minBodyPx: number;
+  /** Maximum candle body width in pixels. Default `40`. */
+  maxBodyPx: number;
+  /** Body width as a fraction of the per-candle slot width (0–1). Default `0.8`. */
+  bodyWidthRatio: number;
+}
+
+/** Grid-line and axis-label fade animation speeds. */
+export interface GridMetrics {
+  /** Per-frame alpha lerp speed when a grid line / label fades in. Default `0.18`. */
+  fadeInSpeed: number;
+  /** Per-frame alpha lerp speed when a grid line / label fades out. Default `0.12`. */
+  fadeOutSpeed: number;
+}
+
+/** Per-frame lerp speeds for value/color transitions. */
+export interface MotionMetrics {
+  /** Per-frame lerp speed for the badge background color transition. Default `0.08`. */
+  badgeColorSpeed: number;
+  /** Extra catch-up speed added to `smoothing` when the live value lags its target. Default `0.12`. */
+  adaptiveSpeedBoost: number;
+}
+
+/** Empty-state (no-data) layout. */
+export interface EmptyStateMetrics {
+  /** Opacity of the empty-state label. Default `0.35`. */
+  labelOpacity: number;
+  /** Half-padding (px) around the empty text for the squiggle "gap" erase band. Default `20`. */
+  gapPad: number;
+  /** Horizontal fade width (px) on each side of the empty-text gap. Default `30`. */
+  gapFadeWidth: number;
+}
+
+/**
+ * Caller-supplied `metrics` override — every namespace and field is optional, and
+ * only the keys you set replace the resolved default (per-namespace shallow merge,
+ * same model as `palette`).
+ */
+export interface LiveChartMetricsOverride {
+  badge?: Partial<BadgeMetrics>;
+  candle?: Partial<CandleMetrics>;
+  grid?: Partial<GridMetrics>;
+  motion?: Partial<MotionMetrics>;
+  emptyState?: Partial<EmptyStateMetrics>;
+}
+
 // ── Component Props ──────────────────────────────────────────────────────────
 
 /** Props shared between `LiveChart` and `LiveChartSeries`. */
@@ -586,6 +713,12 @@ export interface LiveChartCoreProps {
    * `accentColor` + `theme`. Only the keys you set are replaced.
    */
   palette?: Partial<LiveChartPalette>;
+  /**
+   * Override sizing & motion tokens — the geometry/feel analogue of `palette`.
+   * Namespaced (`badge`, `candle`, `grid`, `motion`, `emptyState`); only the keys
+   * you set are replaced. See {@link LiveChartMetrics}.
+   */
+  metrics?: LiveChartMetricsOverride;
   /**
    * Right-edge buffer as a fraction of `timeWindow`. Pushes the live edge past the
    * current time so the latest point has breathing room; pass `0` to land the latest
@@ -629,6 +762,11 @@ export interface LiveChartProps extends LiveChartCoreProps {
   momentum?: boolean | Momentum | MomentumConfig;
   /** Pulsing ring animation on the live dot. `true` = defaults, or pass `PulseConfig`. Default `true`. */
   pulse?: boolean | PulseConfig;
+  /**
+   * Live dot styling. `true`/omitted = shown defaults, `false` = hidden, or pass
+   * `DotConfig` (`radius`, `ring` halo, `color`). See {@link DotConfig}. Default `true`.
+   */
+  dot?: boolean | DotConfig;
   /** Horizontal dashed line at the current live value. `true` = defaults, or pass `ValueLineConfig`. */
   valueLine?: boolean | ValueLineConfig;
   /** Render the live value as a large text overlay in the top-left. Default `false`. */
@@ -673,8 +811,12 @@ export interface LiveChartSeriesProps extends LiveChartCoreProps {
   series: SharedValue<SeriesConfig[]>;
   /** Called when a series toggle chip is tapped. */
   onSeriesToggle?: (id: string, visible: boolean) => void;
-  /** Live dot configuration (radius, pulse, value line, inline labels). */
-  dot?: MultiSeriesDotConfig;
+  /**
+   * Per-series live dot configuration. `true`/omitted = shown defaults, `false` =
+   * hidden, or pass `MultiSeriesDotConfig` (radius, pulse, value line, inline
+   * labels). Default `true`.
+   */
+  dot?: boolean | MultiSeriesDotConfig;
   /** Legend (toggle chips) configuration. `true` = defaults, `false` = hidden, or pass `LegendConfig`. Default `true`. */
   legend?: boolean | LegendConfig;
   /**