react-native-livechart 3.3.0 → 3.4.0

package/src/components/ReferenceLineOverlay.tsx

@@ -12,23 +12,21 @@ import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import { usePathBuilder } from "../hooks/usePathBuilder";
 import { useReferenceLine } from "../hooks/useReferenceLine";
-import { measureFontTextWidth } from "../lib/measureFontTextWidth";
-import { referenceLineForm } from "../math/referenceLines";
+import { referenceLineForm, resolveReferenceBadge } from "../math/referenceLines";
 import type { LiveChartPalette, ReferenceLine } from "../types";
 
 /** Translucent fill alpha for value / time bands. */
 const BAND_FILL_OPACITY = 0.16;
 
-/** Padding inside the off-axis badge pill, in px. */
-const OFF_AXIS_PILL_PAD_X = 6;
-const OFF_AXIS_PILL_PAD_Y = 3;
-const OFF_AXIS_PILL_RADIUS = 5;
+/** Vertical padding inside the badge pill, in px (kept in sync with the layout). */
+const BADGE_PILL_PAD_Y = 3;
+const BADGE_PILL_RADIUS = 5;
 
 /**
  * Renders one reference line or band into the chart canvas. Handles all three
  * `ReferenceLine` forms (horizontal line, horizontal value band, vertical time
- * band) plus the off-axis badge for an off-screen Form-A value. Self-contained
- * so callers can `.map()` over a variable-length `referenceLines` array.
+ * band) plus the Form-A pill badge (in-range tag + off-screen chevron pin).
+ * Self-contained so callers can `.map()` over a variable-length array.
  */
 export function ReferenceLineOverlay({
   engine,
@@ -37,6 +35,7 @@ export function ReferenceLineOverlay({
   palette,
   formatValue,
   font,
+  badgeLayer = false,
 }: {
   engine: ChartEngineLayout;
   padding: ChartPadding;
@@ -44,6 +43,13 @@ export function ReferenceLineOverlay({
   palette: LiveChartPalette;
   formatValue: (v: number) => string;
   font: SkFont;
+  /**
+   * Render only the badge + label (`true`) or only the lines / bands (`false`,
+   * default). The caller draws the base pass behind the chart content and the
+   * badge pass **above** the left-edge fade, so badges/labels stay crisp instead
+   * of being erased by the fade's `dstOut` blend.
+   */
+  badgeLayer?: boolean;
 }) {
   const form = referenceLineForm(line);
   const isBand = form === "value-band" || form === "time-band";
@@ -58,21 +64,24 @@ export function ReferenceLineOverlay({
   const bandFillOpacity = line.fillOpacity ?? BAND_FILL_OPACITY;
   const hasBandBorder = isBand && line.strokeWidth !== undefined;
 
-  // Off-axis target pill styling.
-  const badgeBackground = line.badgeBackground ?? palette.tooltipBg;
-  const badgeBorderColor = line.badgeBorderColor ?? color;
-  const badgeRadius = line.badgeRadius ?? OFF_AXIS_PILL_RADIUS;
+  // Resolved badge appearance (badge config → fallback flat fields → theme).
+  const badge = resolveReferenceBadge(line);
+  const badgeBackground = badge?.background ?? palette.tooltipBg;
+  const badgeBorderColor = badge?.borderColor ?? color;
+  const badgeRadius = badge?.radius ?? BADGE_PILL_RADIUS;
 
   const lineBuilder = usePathBuilder();
   const bandBuilder = usePathBuilder();
   const borderBuilder = usePathBuilder();
-  const offBuilder = usePathBuilder();
+  const connBuilder = usePathBuilder();
   const chevBuilder = usePathBuilder();
 
   const linePath = useDerivedValue(() => {
     const b = lineBuilder.value;
     const l = layout.get();
-    if (l.visible && !l.offAxis && !isBand) {
+    // A plain full-width line. A badge instead draws a pill + a connector to the
+    // opposite edge, below.
+    if (l.visible && !l.badge && !isBand) {
       b.moveTo(l.x1, l.y);
       b.lineTo(l.x2, l.y);
     }
@@ -113,19 +122,13 @@ export function ReferenceLineOverlay({
     return b.detach();
   });
 
-  const offLinePath = useDerivedValue(() => {
-    const b = offBuilder.value;
+  // Badge connector — the dashed line from the pill out to the opposite edge.
+  const connPath = useDerivedValue(() => {
+    const b = connBuilder.value;
     const l = layout.get();
-    if (l.visible && l.offAxis) {
-      // Start the connector just past the badge pill's right edge so the dashed
-      // line runs out to the chart edge rather than behind the badge.
-      const pillRight =
-        l.labelX + measureFontTextWidth(font, l.label) + OFF_AXIS_PILL_PAD_X;
-      const start = pillRight + 4;
-      if (start < l.x2) {
-        b.moveTo(start, l.y);
-        b.lineTo(l.x2, l.y);
-      }
+    if (l.visible && l.badge && l.connStart >= 0) {
+      b.moveTo(l.connStart, l.y);
+      b.lineTo(l.connEnd, l.y);
     }
     return b.detach();
   });
@@ -133,8 +136,8 @@ export function ReferenceLineOverlay({
   const chevronPath = useDerivedValue(() => {
     const b = chevBuilder.value;
     const l = layout.get();
-    if (l.visible && l.offAxis) {
-      const cx = l.x1 + 6;
+    if (l.visible && l.offAxis && l.chevronCx >= 0) {
+      const cx = l.chevronCx;
       const cy = l.y;
       const s = 4;
       if (l.chevronUp) {
@@ -150,55 +153,64 @@ export function ReferenceLineOverlay({
     return b.detach();
   });
 
-  const lineOpacity = useDerivedValue(() =>
-    layout.get().visible && !layout.get().offAxis && !isBand ? 1 : 0,
-  );
+  const lineOpacity = useDerivedValue(() => {
+    const l = layout.get();
+    return l.visible && !l.badge && !isBand ? 1 : 0;
+  });
   const bandOpacity = useDerivedValue(() =>
     layout.get().visible && isBand ? bandFillOpacity : 0,
   );
   const bandBorderOpacity = useDerivedValue(() =>
     layout.get().visible && hasBandBorder ? 1 : 0,
   );
-  const offOpacity = useDerivedValue(() =>
-    layout.get().visible && layout.get().offAxis ? 1 : 0,
-  );
-  const labelOpacity = useDerivedValue(() => (layout.get().visible ? 1 : 0));
+  const badgeOpacity = useDerivedValue(() => {
+    const l = layout.get();
+    return l.visible && l.badge ? 1 : 0;
+  });
+  // Text + icon ride in the badge pass too, so they stay crisp above the fade.
+  const labelOpacity = useDerivedValue(() => {
+    const l = layout.get();
+    return l.visible && l.label.length > 0 ? 1 : 0;
+  });
+  const iconOpacity = useDerivedValue(() => {
+    const l = layout.get();
+    return l.visible && l.icon.length > 0 ? 1 : 0;
+  });
 
   const labelX = useDerivedValue(() => layout.get().labelX);
   const labelY = useDerivedValue(() => layout.get().labelY);
   const labelText = useDerivedValue(() => layout.get().label);
+  const iconX = useDerivedValue(() => layout.get().iconX);
+  const iconText = useDerivedValue(() => layout.get().icon);
 
   // Font metrics depend only on the (stable) font, so read them once instead of
-  // on every frame inside the pill worklets (`getMetrics` allocates + crosses
-  // JSI). The off-axis pill's ascent offset and height are then plain constants.
+  // on every frame inside the pill worklet (`getMetrics` allocates + crosses JSI).
   const { ascent: fontAscent, height: pillH } = (() => {
     const fm = font.getMetrics();
     return {
       ascent: fm.ascent,
-      height: fm.descent - fm.ascent + OFF_AXIS_PILL_PAD_Y * 2,
+      height: fm.descent - fm.ascent + BADGE_PILL_PAD_Y * 2,
     };
   })();
 
-  // Off-axis badge pill — a rounded background behind the chevron + label.
-  const pillX = useDerivedValue(() => layout.get().x1 + 2);
+  // Pill rect — position/size from the layout; vertically centered on the line.
+  const pillX = useDerivedValue(() => layout.get().pillX);
+  const pillW = useDerivedValue(() => layout.get().pillW);
   const pillY = useDerivedValue(
-    () => layout.get().labelY + fontAscent - OFF_AXIS_PILL_PAD_Y,
+    () => layout.get().labelY + fontAscent - BADGE_PILL_PAD_Y,
   );
-  const pillW = useDerivedValue(() => {
-    const l = layout.get();
-    const textW = measureFontTextWidth(font, l.label);
-    return l.labelX + textW + OFF_AXIS_PILL_PAD_X - (l.x1 + 2);
-  });
 
   return (
     <Group>
-      {isBand && (
+      {/* Base pass — bands + lines, drawn behind the chart content (and faded at
+          the left edge like the rest of the content). */}
+      {!badgeLayer && isBand && (
         <Group opacity={bandOpacity}>
           <Path path={bandPath} style="fill" color={color} />
         </Group>
       )}
 
-      {hasBandBorder && (
+      {!badgeLayer && hasBandBorder && (
         <Group opacity={bandBorderOpacity}>
           <Path
             path={bandBorderPath}
@@ -211,7 +223,7 @@ export function ReferenceLineOverlay({
         </Group>
       )}
 
-      {!isBand && (
+      {!badgeLayer && !isBand && (
         <Group opacity={lineOpacity}>
           <Path
             path={linePath}
@@ -224,52 +236,67 @@ export function ReferenceLineOverlay({
         </Group>
       )}
 
-      <Group opacity={offOpacity}>
-        <Path
-          path={offLinePath}
-          style="stroke"
-          strokeWidth={strokeWidth}
-          color={color}
-        >
-          <DashPathEffect intervals={intervals} />
-        </Path>
-        <RoundedRect
-          x={pillX}
-          y={pillY}
-          width={pillW}
-          height={pillH}
-          r={badgeRadius}
-          color={badgeBackground}
-        />
-        <RoundedRect
-          x={pillX}
-          y={pillY}
-          width={pillW}
-          height={pillH}
-          r={badgeRadius}
-          color={badgeBorderColor}
-          style="stroke"
-          strokeWidth={1}
-        />
-        <Path
-          path={chevronPath}
-          style="stroke"
-          strokeWidth={1.5}
-          color={color}
-          strokeCap="round"
-          strokeJoin="round"
-        />
-      </Group>
+      {/* Badge pass — connector + pill + chevron + icon, above the left-edge fade. */}
+      {badgeLayer && (
+        <Group opacity={badgeOpacity}>
+          <Path
+            path={connPath}
+            style="stroke"
+            strokeWidth={strokeWidth}
+            color={color}
+          >
+            <DashPathEffect intervals={intervals} />
+          </Path>
+          <RoundedRect
+            x={pillX}
+            y={pillY}
+            width={pillW}
+            height={pillH}
+            r={badgeRadius}
+            color={badgeBackground}
+          />
+          <RoundedRect
+            x={pillX}
+            y={pillY}
+            width={pillW}
+            height={pillH}
+            r={badgeRadius}
+            color={badgeBorderColor}
+            style="stroke"
+            strokeWidth={1}
+          />
+          <Path
+            path={chevronPath}
+            style="stroke"
+            strokeWidth={1.5}
+            color={color}
+            strokeCap="round"
+            strokeJoin="round"
+          />
+          <Group opacity={iconOpacity}>
+            <SkiaText
+              x={iconX}
+              y={labelY}
+              text={iconText}
+              font={font}
+              color={labelColor}
+            />
+          </Group>
+        </Group>
+      )}
 
-      <Group opacity={labelOpacity}>
-        <SkiaText
-          x={labelX}
-          y={labelY}
-          text={labelText}
-          font={font}
-          color={labelColor}
-        />
-      </Group>
+      {/* Labels ride in the badge pass too, so they stay crisp above the fade. */}
+      {badgeLayer && (
+        <Group opacity={labelOpacity}>
+          <SkiaText
+            x={labelX}
+            y={labelY}
+            text={labelText}
+            font={font}
+            color={labelColor}
+          />
+        </Group>
+      )}
     </Group>
   );
 }

package/src/components/ScrubActionOverlay.tsx

@@ -0,0 +1,187 @@
+import {
+  Circle,
+  DashPathEffect,
+  Group,
+  Line,
+  RoundedRect,
+  Text as SkiaText,
+  type SkFont,
+} from "@shopify/react-native-skia";
+import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+
+import type { ChartEngineLayout } from "../core/useLiveChartEngine";
+import type { ChartPadding } from "../draw/line";
+import type {
+  ActionBadgeLayout,
+  TimeBadgeLayout,
+} from "../hooks/crosshairShared";
+import type { LiveChartPalette } from "../types";
+
+/**
+ * Scrub-action ("order ticket") overlay: the locked reticle (a horizontal price
+ * level line + a faint vertical line crossing at the reticle) and the right-gutter
+ * action badge — a circular icon button + a separate price pill. All keyed off the
+ * lock SharedValues, so it tracks the reticle on the UI thread without re-renders.
+ *
+ * Mounted by `LiveChart` **outside** the degen-shake group so the rendered badge
+ * stays aligned with the (untransformed) tap hit-test in {@link useCrosshair}.
+ * Visibility rides on a 0/1 opacity driven by `lockActive` (no React remount).
+ */
+export function ScrubActionOverlay({
+  lockActive,
+  lockX,
+  lockY,
+  actionBadge,
+  timeBadge,
+  engine,
+  padding,
+  palette,
+  font,
+  icon,
+  lineColor,
+  background,
+  iconColor,
+}: {
+  lockActive: SharedValue<boolean>;
+  lockX: SharedValue<number>;
+  lockY: SharedValue<number>;
+  actionBadge: SharedValue<ActionBadgeLayout>;
+  timeBadge?: SharedValue<TimeBadgeLayout>;
+  engine: ChartEngineLayout;
+  padding: ChartPadding;
+  palette: LiveChartPalette;
+  font: SkFont;
+  icon: string;
+  lineColor?: string;
+  background?: string;
+  iconColor?: string;
+}) {
+  const opacity = useDerivedValue(() => (lockActive.value ? 1 : 0), [lockActive]);
+
+  // Horizontal level line (the chosen price), full plot width.
+  const hLeft = useDerivedValue(
+    () => ({ x: padding.left, y: lockY.value }),
+    [padding.left, lockY],
+  );
+  const hRight = useDerivedValue(
+    () => ({ x: engine.canvasWidth.value - padding.right, y: lockY.value }),
+    [engine.canvasWidth, padding.right, lockY],
+  );
+
+  // Faint vertical line at the reticle X, full plot height.
+  const vTop = useDerivedValue(
+    () => ({ x: lockX.value, y: padding.top }),
+    [lockX, padding.top],
+  );
+  const vBottom = useDerivedValue(
+    () => ({ x: lockX.value, y: engine.canvasHeight.value - padding.bottom }),
+    [lockX, engine.canvasHeight, padding.bottom],
+  );
+
+  // Action badge — a circular icon button + a separate price pill (2px gap).
+  // Center the icon by its *visual* bounds (not advance box) so a symbol like
+  // "+" sits dead-center in the circle. The glyph bounds are constant, so measure
+  // once and offset the per-frame circle center.
+  const iconBounds = icon ? font.measureText(icon) : null;
+  const iconOffX = iconBounds ? -iconBounds.x - iconBounds.width / 2 : 0;
+  const iconOffY = iconBounds ? -iconBounds.y - iconBounds.height / 2 : 0;
+
+  const iconOpacity = useDerivedValue(() =>
+    actionBadge.value.hasIcon ? 1 : 0,
+  );
+  const iconCx = useDerivedValue(() => actionBadge.value.iconCx);
+  const iconCy = useDerivedValue(() => actionBadge.value.iconCy);
+  const iconR = useDerivedValue(() => actionBadge.value.iconR);
+  const iconGlyphX = useDerivedValue(() => actionBadge.value.iconCx + iconOffX);
+  const iconGlyphY = useDerivedValue(() => actionBadge.value.iconCy + iconOffY);
+
+  const priceOpacity = useDerivedValue(() =>
+    actionBadge.value.hasPrice ? 1 : 0,
+  );
+  const priceX = useDerivedValue(() => actionBadge.value.priceX);
+  const priceY = useDerivedValue(() => actionBadge.value.priceY);
+  const priceW = useDerivedValue(() => actionBadge.value.priceW);
+  const priceH = useDerivedValue(() => actionBadge.value.priceH);
+  const priceR = useDerivedValue(() => actionBadge.value.priceH / 2);
+  const priceTextX = useDerivedValue(() => actionBadge.value.priceTextX);
+  const priceText = useDerivedValue(() => actionBadge.value.priceText);
+
+  const textY = useDerivedValue(() => actionBadge.value.textY);
+
+  // X-axis time pill (opt-in). `timeBadge` may be omitted; default to hidden.
+  const tb = timeBadge;
+  const timeOpacity = useDerivedValue(() => (tb?.value.visible ? 1 : 0), [tb]);
+  const timeX = useDerivedValue(() => tb?.value.x ?? -400, [tb]);
+  const timeY = useDerivedValue(() => tb?.value.y ?? 0, [tb]);
+  const timeW = useDerivedValue(() => tb?.value.w ?? 0, [tb]);
+  const timeH = useDerivedValue(() => tb?.value.h ?? 0, [tb]);
+  const timeR = useDerivedValue(() => (tb?.value.h ?? 0) / 2, [tb]);
+  const timeTextX = useDerivedValue(() => tb?.value.textX ?? -400, [tb]);
+  const timeTextY = useDerivedValue(() => tb?.value.textY ?? 0, [tb]);
+  const timeText = useDerivedValue(() => tb?.value.timeText ?? "", [tb]);
+
+  const levelColor = lineColor ?? palette.crosshairLine;
+  const pillColor = background ?? palette.badgeBg;
+  const labelColor = iconColor ?? palette.badgeText;
+
+  return (
+    <Group opacity={opacity}>
+      <Line p1={hLeft} p2={hRight} color={levelColor} strokeWidth={1}>
+        <DashPathEffect intervals={[4, 4]} />
+      </Line>
+      <Line p1={vTop} p2={vBottom} color={levelColor} strokeWidth={1}>
+        <DashPathEffect intervals={[2, 4]} />
+      </Line>
+
+      {/* Circular icon button (the action). */}
+      <Group opacity={iconOpacity}>
+        <Circle cx={iconCx} cy={iconCy} r={iconR} color={pillColor} />
+        <SkiaText
+          x={iconGlyphX}
+          y={iconGlyphY}
+          text={icon}
+          font={font}
+          color={labelColor}
+        />
+      </Group>
+
+      {/* Price pill (capsule). */}
+      <Group opacity={priceOpacity}>
+        <RoundedRect
+          x={priceX}
+          y={priceY}
+          width={priceW}
+          height={priceH}
+          r={priceR}
+          color={pillColor}
+        />
+        <SkiaText
+          x={priceTextX}
+          y={textY}
+          text={priceText}
+          font={font}
+          color={labelColor}
+        />
+      </Group>
+
+      {/* X-axis time pill (capsule) where the vertical line meets the axis. */}
+      <Group opacity={timeOpacity}>
+        <RoundedRect
+          x={timeX}
+          y={timeY}
+          width={timeW}
+          height={timeH}
+          r={timeR}
+          color={pillColor}
+        />
+        <SkiaText
+          x={timeTextX}
+          y={timeTextY}
+          text={timeText}
+          font={font}
+          color={labelColor}
+        />
+      </Group>
+    </Group>
+  );
+}

package/src/components/XAxisOverlay.tsx

@@ -1,5 +1,6 @@
 import { Group, Path, type SkFont } from "@shopify/react-native-skia";
 import { useDerivedValue, type SharedValue } from "react-native-reanimated";
+import { X_AXIS_LABEL_OFFSET_Y } from "../constants";
 import type { ChartEngineLayout } from "../core/useLiveChartEngine";
 import type { ChartPadding } from "../draw/line";
 import type { XAxisEntry } from "../hooks/useXAxis";
@@ -10,7 +11,7 @@ import { AnimatedLabel } from "./AnimatedLabel";
 
 const MAX_X_LABELS = 10;
 const TICK_HEIGHT = 5;
-const LABEL_OFFSET_Y = 19;
+const LABEL_OFFSET_Y = X_AXIS_LABEL_OFFSET_Y;
 
 export function XAxisOverlay({
   entries,

package/src/constants.ts

@@ -62,6 +62,11 @@ export const BADGE_MARGIN_RIGHT = BADGE_METRICS_DEFAULTS.marginEdge;
 /** Gap between the live dot and the badge tail tip. */
 export const BADGE_DOT_GAP = BADGE_METRICS_DEFAULTS.dotGap;
 
+/** Baseline offset (px) below the plot bottom where x-axis time labels sit.
+ *  Shared so overlays that align to the time-axis row (e.g. the scrub-action
+ *  time badge) match the {@link XAxisOverlay} labels. */
+export const X_AXIS_LABEL_OFFSET_Y = 19;
+
 /** Maximum simultaneous series rendered (paths/dots slots). */
 export const MAX_MULTI_SERIES = 12;
 

package/src/core/resolveConfig.ts

@@ -17,6 +17,7 @@ import type {
   MultiSeriesDotConfig,
   PulseConfig,
   ReferenceLine,
+  ScrubActionConfig,
   ScrubConfig,
   SelectionDotConfig,
   SelectionDotProps,
@@ -90,6 +91,24 @@ export interface ResolvedScrubConfig {
   panGestureDelay: number;
 }
 
+export interface ResolvedScrubActionConfig {
+  /** Glyph drawn in the action badge. */
+  icon: string;
+  /** undefined → palette.badgeBg */
+  background: string | undefined;
+  /** undefined → palette.badgeText */
+  iconColor: string | undefined;
+  /** undefined → palette.crosshairLine */
+  lineColor: string | undefined;
+  /** Show the price readout pill; false → icon-only badge. */
+  text: boolean;
+  /** Show the date/time pill where the vertical line meets the x-axis. */
+  timeBadge: boolean;
+  /** undefined → no rounding */
+  snap: number | undefined;
+  dismissOnTapOutside: boolean;
+}
+
 export interface ResolvedGradientConfig {
   /** undefined → use palette.fillTop (theme-aware) at render time */
   topOpacity: number | undefined;
@@ -289,6 +308,27 @@ export function resolveScrub(
   return resolveToggle(prop, SCRUB_DEFAULTS, false);
 }
 
+const SCRUB_ACTION_DEFAULTS: ResolvedScrubActionConfig = {
+  icon: "+",
+  background: undefined,
+  iconColor: undefined,
+  lineColor: undefined,
+  text: true,
+  timeBadge: false,
+  snap: undefined,
+  dismissOnTapOutside: false,
+};
+
+/**
+ * Resolves `scrubAction` prop to a fully-typed config or null (disabled).
+ * Opt-in: `false`/`undefined` → null; `true` → defaults; object → merged.
+ */
+export function resolveScrubAction(
+  prop: boolean | ScrubActionConfig | undefined,
+): ResolvedScrubActionConfig | null {
+  return resolveToggle(prop, SCRUB_ACTION_DEFAULTS, false);
+}
+
 const GRADIENT_DEFAULTS: ResolvedGradientConfig = {
   topOpacity: undefined,
   bottomOpacity: undefined,