react-native-livechart 1.0.0 → 2.0.0

package/src/core/liveChartEngineTick.ts

@@ -1,6 +1,6 @@
 import type { CandlePoint, LiveChartPoint } from "../types";
 
-import { ADAPTIVE_SPEED_BOOST } from "../constants";
+import { MOTION_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
 
 export interface EngineTickMutable {
@@ -18,6 +18,8 @@ export interface EngineTickInput {
   timeWindow: number;
   smoothing: number;
   exaggerate: boolean;
+  /** Extra catch-up speed added to `smoothing` when the live value lags. Default `0.12`. */
+  adaptiveSpeedBoost?: number;
   referenceValue: number | undefined;
   /** Additional reference values (lines + bands) folded into the Y range. */
   referenceValues?: number[];
@@ -68,7 +70,10 @@ export function tickLiveChartEngineFrame(
   const range = state.displayMax - state.displayMin;
   const gapRatio =
     range > 0 ? Math.min(Math.abs(target - state.displayValue) / range, 1) : 0;
-  const adaptiveSpeed = speed + (1 - gapRatio) * ADAPTIVE_SPEED_BOOST;
+  const adaptiveSpeed =
+    speed +
+    (1 - gapRatio) *
+      (input.adaptiveSpeedBoost ?? MOTION_METRICS_DEFAULTS.adaptiveSpeedBoost);
 
   state.displayValue = lerp(
     state.displayValue,

package/src/core/liveChartSeriesEngineTick.ts

@@ -1,4 +1,4 @@
-import { ADAPTIVE_SPEED_BOOST } from "../constants";
+import { MOTION_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
 import type { SeriesConfig } from "../types";
 
@@ -18,6 +18,8 @@ export interface MultiEngineTickInput {
   timeWindow: number;
   smoothing: number;
   exaggerate: boolean;
+  /** Extra catch-up speed added to `smoothing` when a series tip lags. Default `0.12`. */
+  adaptiveSpeedBoost?: number;
   referenceValue: number | undefined;
   /** Additional reference values (lines + bands) folded into the Y range. */
   referenceValues?: number[];
@@ -80,7 +82,11 @@ export function tickLiveChartSeriesEngineFrame(
     const cur = state.displayValues[i];
     const gapRatio =
       range > 0 ? Math.min(Math.abs(target - cur) / range, 1) : 0;
-    const adaptiveSpeed = speed + (1 - gapRatio) * ADAPTIVE_SPEED_BOOST;
+    const adaptiveSpeed =
+      speed +
+      (1 - gapRatio) *
+        (input.adaptiveSpeedBoost ??
+          MOTION_METRICS_DEFAULTS.adaptiveSpeedBoost);
     state.displayValues[i] = lerp(cur, target, adaptiveSpeed, input.dt);
 
     const targetOp = series[i].visible !== false ? 1 : 0;

package/src/core/resolveConfig.ts

@@ -9,6 +9,10 @@ import type {
   LeftEdgeFadeConfig,
   LegendConfig,
   LegendStyle,
+  LiveChartMetrics,
+  LiveChartMetricsOverride,
+  DotConfig,
+  DotRingConfig,
   MultiSeriesDotConfig,
   PulseConfig,
   ReferenceLine,
@@ -20,7 +24,14 @@ import type {
 } from "../types";
 
 import type { SharedValue } from "react-native-reanimated";
-import { FADE_EDGE_WIDTH } from "../constants";
+import {
+  BADGE_METRICS_DEFAULTS,
+  CANDLE_METRICS_DEFAULTS,
+  EMPTY_STATE_METRICS_DEFAULTS,
+  FADE_EDGE_WIDTH,
+  GRID_METRICS_DEFAULTS,
+  MOTION_METRICS_DEFAULTS,
+} from "../constants";
 
 // ─── Resolved types (all fields required, no optionals) ──────────────────────
 
@@ -60,6 +71,8 @@ export interface ResolvedScrubConfig {
   tooltipColor: string | undefined;
   /** undefined → palette.tooltipBorder */
   tooltipBorderColor: string | undefined;
+  /** Press-and-hold delay (ms) before scrubbing activates. 0 = immediate. */
+  panGestureDelay: number;
 }
 
 export interface ResolvedGradientConfig {
@@ -135,6 +148,28 @@ export interface ResolvedLeftEdgeFadeConfig {
 
 // ─── Resolver functions ───────────────────────────────────────────────────────
 
+/**
+ * Uniform `boolean | Config` feature-flag resolver, shared by every toggle below.
+ * - `false` → `null` (explicitly disabled)
+ * - `undefined` → `defaultOn ? defaults : null` (the feature's default state)
+ * - `true` → `defaults`
+ * - object → defaults shallow-merged with the caller's overrides
+ *
+ * `defaultOn` makes each toggle's default explicit at the resolver. Toggles whose
+ * default-on is owned by the component prop (e.g. `badge = true`) pass
+ * `defaultOn: false` here, so a bare resolver call without that default stays off.
+ */
+function resolveToggle<C extends object, R extends object>(
+  prop: boolean | C | undefined,
+  defaults: R,
+  defaultOn: boolean,
+): R | null {
+  if (prop === false) return null;
+  if (prop == null) return defaultOn ? defaults : null;
+  if (prop === true) return defaults;
+  return { ...defaults, ...prop } as R;
+}
+
 const VALUE_LINE_DEFAULTS: ResolvedValueLineConfig = {
   strokeWidth: 1,
   intervals: [4, 4],
@@ -148,9 +183,7 @@ const VALUE_LINE_DEFAULTS: ResolvedValueLineConfig = {
 export function resolveValueLine(
   prop: boolean | ValueLineConfig | undefined,
 ): ResolvedValueLineConfig | null {
-  if (!prop) return null;
-  if (prop === true) return VALUE_LINE_DEFAULTS;
-  return { ...VALUE_LINE_DEFAULTS, ...prop };
+  return resolveToggle(prop, VALUE_LINE_DEFAULTS, false);
 }
 
 const BADGE_DEFAULTS: ResolvedBadgeConfig = {
@@ -167,9 +200,7 @@ const BADGE_DEFAULTS: ResolvedBadgeConfig = {
 export function resolveBadge(
   prop: boolean | BadgeConfig | undefined,
 ): ResolvedBadgeConfig | null {
-  if (!prop) return null;
-  if (prop === true) return BADGE_DEFAULTS;
-  return { ...BADGE_DEFAULTS, ...prop };
+  return resolveToggle(prop, BADGE_DEFAULTS, false);
 }
 
 const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
@@ -183,9 +214,7 @@ const Y_AXIS_DEFAULTS: ResolvedYAxisConfig = {
 export function resolveYAxis(
   prop: boolean | YAxisConfig | undefined,
 ): ResolvedYAxisConfig | null {
-  if (!prop) return null;
-  if (prop === true) return Y_AXIS_DEFAULTS;
-  return { ...Y_AXIS_DEFAULTS, ...prop };
+  return resolveToggle(prop, Y_AXIS_DEFAULTS, false);
 }
 
 const X_AXIS_DEFAULTS: ResolvedXAxisConfig = {
@@ -194,14 +223,12 @@ const X_AXIS_DEFAULTS: ResolvedXAxisConfig = {
 
 /**
  * Resolves `xAxis` prop to a fully-typed config or null (disabled).
- * Defaults to enabled (`true`) so `undefined` also returns the defaults.
+ * Defaults to enabled (`true`) so a bare `undefined` also returns the defaults.
  */
 export function resolveXAxis(
   prop: boolean | XAxisConfig | undefined,
 ): ResolvedXAxisConfig | null {
-  if (prop === false) return null;
-  if (prop === undefined || prop === true) return X_AXIS_DEFAULTS;
-  return { ...X_AXIS_DEFAULTS, ...prop };
+  return resolveToggle(prop, X_AXIS_DEFAULTS, true);
 }
 
 const SCRUB_DEFAULTS: ResolvedScrubConfig = {
@@ -212,6 +239,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
   tooltipBackground: undefined,
   tooltipColor: undefined,
   tooltipBorderColor: undefined,
+  panGestureDelay: 0,
 };
 
 /**
@@ -221,9 +249,7 @@ const SCRUB_DEFAULTS: ResolvedScrubConfig = {
 export function resolveScrub(
   prop: boolean | ScrubConfig | undefined,
 ): ResolvedScrubConfig | null {
-  if (!prop) return null;
-  if (prop === true) return SCRUB_DEFAULTS;
-  return { ...SCRUB_DEFAULTS, ...prop };
+  return resolveToggle(prop, SCRUB_DEFAULTS, false);
 }
 
 const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
@@ -238,9 +264,7 @@ const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
 export function resolveGradient(
   prop: boolean | GradientConfig | undefined,
 ): ResolvedGradientConfig | null {
-  if (!prop) return null;
-  if (prop === true) return GRADIENT_DEFAULTS;
-  return { ...GRADIENT_DEFAULTS, ...prop };
+  return resolveToggle(prop, GRADIENT_DEFAULTS, false);
 }
 
 /** Fallback when no theme background is passed (e.g. unit tests). */
@@ -290,9 +314,7 @@ const PULSE_DEFAULTS: ResolvedPulseConfig = {
 export function resolvePulse(
   prop: boolean | PulseConfig | undefined,
 ): ResolvedPulseConfig | null {
-  if (!prop) return null;
-  if (prop === true) return PULSE_DEFAULTS;
-  return { ...PULSE_DEFAULTS, ...prop };
+  return resolveToggle(prop, PULSE_DEFAULTS, false);
 }
 
 const REFERENCE_LINE_VISUAL_DEFAULTS = {
@@ -477,31 +499,78 @@ export function resolveTradeStream(
   };
 }
 
-// ─── Multi-series dot ─────────────────────────────────────────────────────────
+// ─── Dot (shared) ─────────────────────────────────────────────────────────────
 
-export interface ResolvedMultiSeriesDotConfig {
+/** Resolved halo ring. `color: undefined` means "use the theme `badgeOuterBg`". */
+export interface ResolvedDotRingConfig {
+  color: string | undefined;
+  width: number;
+}
+
+const RING_DEFAULTS: ResolvedDotRingConfig = {
+  color: undefined,
+  width: 2.5,
+};
+
+/** `undefined`/`true` → haloed defaults; `false` → null (flat circle). */
+export function resolveDotRing(
+  prop: boolean | DotRingConfig | undefined,
+): ResolvedDotRingConfig | null {
+  return resolveToggle(prop, RING_DEFAULTS, true);
+}
+
+/** Shared, fully-resolved dot styling (single- and multi-series). */
+export interface ResolvedDotConfig {
   radius: number;
-  pulse: ResolvedPulseConfig | null;
-  valueLine: ResolvedValueLineConfig | null;
-  valueLabel: boolean;
+  ring: ResolvedDotRingConfig | null;
+  show: boolean;
+  color: string | undefined;
 }
 
-const MULTI_DOT_DEFAULTS: ResolvedMultiSeriesDotConfig = {
+const DOT_DEFAULTS: ResolvedDotConfig = {
   radius: 3.5,
-  pulse: PULSE_DEFAULTS,
-  valueLine: null,
-  valueLabel: true,
+  ring: RING_DEFAULTS,
+  show: true,
+  color: undefined,
 };
 
+/**
+ * Resolves the `dot` prop. Always returns a config (the live dot's geometry is
+ * read unconditionally); visibility rides on `show`.
+ * - `false` → defaults with `show: false` (the canonical "hide the dot")
+ * - `undefined`/`true` → shown defaults
+ * - object → merged with defaults (honoring an explicit `show`)
+ */
+export function resolveDot(
+  prop: boolean | DotConfig | undefined,
+): ResolvedDotConfig {
+  if (prop === false) return { ...DOT_DEFAULTS, show: false };
+  if (prop == null || prop === true) return DOT_DEFAULTS;
+  return {
+    radius: prop.radius ?? DOT_DEFAULTS.radius,
+    ring: resolveDotRing(prop.ring),
+    show: prop.show ?? DOT_DEFAULTS.show,
+    color: prop.color,
+  };
+}
+
+// ─── Multi-series dot ─────────────────────────────────────────────────────────
+
+export interface ResolvedMultiSeriesDotConfig extends ResolvedDotConfig {
+  pulse: ResolvedPulseConfig | null;
+  valueLine: ResolvedValueLineConfig | null;
+  valueLabel: boolean;
+}
+
 export function resolveMultiSeriesDot(
-  prop: MultiSeriesDotConfig | undefined,
+  prop: boolean | MultiSeriesDotConfig | undefined,
 ): ResolvedMultiSeriesDotConfig {
-  if (!prop) return MULTI_DOT_DEFAULTS;
+  const cfg = typeof prop === "object" && prop !== null ? prop : undefined;
   return {
-    radius: prop.radius ?? MULTI_DOT_DEFAULTS.radius,
-    pulse: resolvePulse(prop.pulse ?? true),
-    valueLine: resolveValueLine(prop.valueLine),
-    valueLabel: prop.valueLabel ?? MULTI_DOT_DEFAULTS.valueLabel,
+    ...resolveDot(prop),
+    pulse: resolvePulse(cfg?.pulse ?? true),
+    valueLine: resolveValueLine(cfg?.valueLine),
+    valueLabel: cfg?.valueLabel ?? true,
   };
 }
 
@@ -536,3 +605,33 @@ export function resolveLegend(
     style: prop.style,
   };
 }
+
+// ─── Metrics (sizing & motion tokens) ─────────────────────────────────────────
+
+/** Canonical resolved metrics — every namespace/field present. */
+const METRICS_DEFAULTS: LiveChartMetrics = {
+  badge: BADGE_METRICS_DEFAULTS,
+  candle: CANDLE_METRICS_DEFAULTS,
+  grid: GRID_METRICS_DEFAULTS,
+  motion: MOTION_METRICS_DEFAULTS,
+  emptyState: EMPTY_STATE_METRICS_DEFAULTS,
+};
+
+/**
+ * Resolve the `metrics` prop into a fully-typed config. Per-namespace shallow
+ * merge over the defaults — only the keys the caller sets are replaced, the same
+ * model as `applyPaletteOverride`. Returns the shared defaults object when no
+ * override is supplied (treated read-only by consumers).
+ */
+export function resolveMetrics(
+  prop: LiveChartMetricsOverride | undefined,
+): LiveChartMetrics {
+  if (!prop) return METRICS_DEFAULTS;
+  return {
+    badge: { ...METRICS_DEFAULTS.badge, ...prop.badge },
+    candle: { ...METRICS_DEFAULTS.candle, ...prop.candle },
+    grid: { ...METRICS_DEFAULTS.grid, ...prop.grid },
+    motion: { ...METRICS_DEFAULTS.motion, ...prop.motion },
+    emptyState: { ...METRICS_DEFAULTS.emptyState, ...prop.emptyState },
+  };
+}

package/src/core/useLiveChartEngine.ts

@@ -21,6 +21,8 @@ export interface EngineConfig {
   value: SharedValue<number>;
   timeWindow: number;
   smoothing: number;
+  /** Extra catch-up speed added to `smoothing` when the live value lags. */
+  adaptiveSpeedBoost?: number;
   exaggerate?: boolean;
   referenceValue?: number;
   referenceValues?: number[];
@@ -78,6 +80,7 @@ export interface EngineFrameRefs {
   timestamp: SharedValue<number>;
   timeWindow: SharedValue<number>;
   smoothing: SharedValue<number>;
+  adaptiveSpeedBoostSV?: SharedValue<number | undefined>;
   exaggerateSV: SharedValue<boolean>;
   referenceValue: SharedValue<number | undefined>;
   referenceValues?: SharedValue<number[] | undefined>;
@@ -114,6 +117,7 @@ export function applyLiveChartEngineFrame(
     canvasHeight: sv.canvasHeight.value,
     timeWindow: sv.timeWindow.value,
     smoothing: sv.smoothing.value,
+    adaptiveSpeedBoost: sv.adaptiveSpeedBoostSV?.value,
     exaggerate: sv.exaggerateSV.value,
     referenceValue: sv.referenceValue.value,
     referenceValues: sv.referenceValues?.value,
@@ -140,6 +144,7 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
   // Low-frequency config → UI thread via useDerivedValue
   const timeWindow = useDerivedValue(() => config.timeWindow);
   const smoothing = useDerivedValue(() => config.smoothing);
+  const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
   const referenceValues = useDerivedValue(() => config.referenceValues);
@@ -179,6 +184,7 @@ export function useLiveChartEngine(config: EngineConfig): SingleEngineState {
       canvasHeight,
       timeWindow,
       smoothing,
+      adaptiveSpeedBoostSV,
       exaggerateSV,
       referenceValue,
       referenceValues,

package/src/core/useLiveChartSeriesEngine.ts

@@ -14,6 +14,8 @@ export interface MultiSeriesEngineConfig {
   series: SharedValue<SeriesConfig[]>;
   timeWindow: number;
   smoothing: number;
+  /** Extra catch-up speed added to `smoothing` when a series tip lags. */
+  adaptiveSpeedBoost?: number;
   exaggerate?: boolean;
   referenceValue?: number;
   referenceValues?: number[];
@@ -36,6 +38,7 @@ export interface MultiEngineFrameRefs {
   canvasHeight: SharedValue<number>;
   timeWindow: SharedValue<number>;
   smoothing: SharedValue<number>;
+  adaptiveSpeedBoostSV?: SharedValue<number | undefined>;
   exaggerateSV: SharedValue<boolean>;
   referenceValue: SharedValue<number | undefined>;
   referenceValues?: SharedValue<number[] | undefined>;
@@ -107,6 +110,7 @@ export function applyLiveChartSeriesEngineFrame(
     canvasHeight: sv.canvasHeight.value,
     timeWindow: sv.timeWindow.value,
     smoothing: sv.smoothing.value,
+    adaptiveSpeedBoost: sv.adaptiveSpeedBoostSV?.value,
     exaggerate: sv.exaggerateSV.value,
     referenceValue: sv.referenceValue.value,
     referenceValues: sv.referenceValues?.value,
@@ -135,6 +139,7 @@ export function useLiveChartSeriesEngine(
 ): MultiEngineState {
   const timeWindow = useDerivedValue(() => config.timeWindow);
   const smoothing = useDerivedValue(() => config.smoothing);
+  const adaptiveSpeedBoostSV = useDerivedValue(() => config.adaptiveSpeedBoost);
   const exaggerateSV = useDerivedValue(() => config.exaggerate ?? false);
   const referenceValue = useDerivedValue(() => config.referenceValue);
   const referenceValues = useDerivedValue(() => config.referenceValues);
@@ -185,6 +190,7 @@ export function useLiveChartSeriesEngine(
         canvasHeight,
         timeWindow,
         smoothing,
+        adaptiveSpeedBoostSV,
         exaggerateSV,
         referenceValue,
         referenceValues,

package/src/draw/candle.ts

@@ -1,4 +1,5 @@
-import type { CandlePoint } from "../types";
+import { CANDLE_METRICS_DEFAULTS } from "../constants";
+import type { CandleMetrics, CandlePoint } from "../types";
 import type { ChartPadding } from "./line";
 
 export interface CandleRect {
@@ -21,9 +22,6 @@ export interface CandleGeometry {
   wicks: CandleWick[];
 }
 
-const MIN_BODY_PX = 1;
-const MAX_BODY_PX = 40;
-
 function candleTimeToX(
   t: number,
   padLeft: number,
@@ -62,6 +60,7 @@ function appendCandleShapes(
   valRange: number,
   candleWidthSecs: number,
   bodyW: number,
+  minBodyPx: number,
   bodies: CandleRect[],
   wicks: CandleWick[],
 ): void {
@@ -94,7 +93,7 @@ function appendCandleShapes(
     valRange,
     chartH,
   );
-  const bodyH = Math.max(MIN_BODY_PX, bodyBot - bodyTop);
+  const bodyH = Math.max(minBodyPx, bodyBot - bodyTop);
 
   let bx = xCenter - bodyW / 2;
   let bw = bodyW;
@@ -132,6 +131,7 @@ export function buildCandleGeometry(
   displayMin: number,
   displayMax: number,
   candleWidthSecs: number,
+  metrics: CandleMetrics = CANDLE_METRICS_DEFAULTS,
 ): CandleGeometry {
   "worklet";
   const chartW = canvasW - padding.left - padding.right;
@@ -142,7 +142,10 @@ export function buildCandleGeometry(
     return { bodies: [], wicks: [] };
 
   const slotPx = (candleWidthSecs / windowSecs) * chartW;
-  const bodyW = Math.max(1, Math.min(slotPx * 0.8, slotPx - 2, MAX_BODY_PX));
+  const bodyW = Math.max(
+    1,
+    Math.min(slotPx * metrics.bodyWidthRatio, slotPx - 2, metrics.maxBodyPx),
+  );
 
   const bodies: CandleRect[] = [];
   const wicks: CandleWick[] = [];
@@ -180,6 +183,7 @@ export function buildCandleGeometry(
       valRange,
       candleWidthSecs,
       bodyW,
+      metrics.minBodyPx,
       bodies,
       wicks,
     );
@@ -201,6 +205,7 @@ export function buildCandleGeometry(
       valRange,
       candleWidthSecs,
       bodyW,
+      metrics.minBodyPx,
       bodies,
       wicks,
     );

package/src/draw/grid.ts

@@ -1,4 +1,6 @@
+import { GRID_METRICS_DEFAULTS } from "../constants";
 import { lerp } from "../math/lerp";
+import type { GridMetrics } from "../types";
 
 export interface YAxisEntry {
   y: number;
@@ -64,9 +66,6 @@ function divisible(val: number, interval: number): boolean {
   return Math.abs(ratio - Math.round(ratio)) < 0.01;
 }
 
-const FADE_IN = 0.18;
-const FADE_OUT = 0.12;
-
 /** Map data value → canvas Y (nested arrows inside worklets are not UI-thread-safe). */
 function gridValueToY(
   val: number,
@@ -94,6 +93,7 @@ export function computeGridEntries(
   formatValue: (v: number) => string,
   dt: number,
   minGap = 36,
+  grid: GridMetrics = GRID_METRICS_DEFAULTS,
 ): { entries: YAxisEntry[]; interval: number } {
   "worklet";
   const chartH = canvasHeight - padTop - padBottom;
@@ -135,7 +135,7 @@ export function computeGridEntries(
     const key = Number(keys[i]);
     const alpha = labelAlphas[key];
     const target = targets[key] ?? 0;
-    const speed = target >= alpha ? FADE_IN : FADE_OUT;
+    const speed = target >= alpha ? grid.fadeInSpeed : grid.fadeOutSpeed;
     let next = lerp(alpha, target, speed, dt);
     if (Math.abs(next - target) < 0.02) next = target;
     if (next < 0.01 && target === 0) {
@@ -152,7 +152,7 @@ export function computeGridEntries(
     /* istanbul ignore else -- key already tracked after phase 2 when targets repeat across frames */
     if (labelAlphas[key] === undefined) {
       /* istanbul ignore next -- targets keys always map to a number; ?? keeps types safe */
-      labelAlphas[key] = (targets[key] ?? 0) * FADE_IN;
+      labelAlphas[key] = (targets[key] ?? 0) * grid.fadeInSpeed;
     }
   }