@userflow-tech/react-native 0.1.0

package/src/surfaces/tooltip/TooltipNotch.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { tooltipNotchDiamondSide } from './computeTooltipPosition';
+
+export interface TooltipNotchProps {
+  notchSize: number;
+  notchColor: string;
+  /**
+   * Shrink the diamond by this much on every edge, keeping the same center.
+   * Bordered themes stamp an inset fill diamond so the stroke stays even.
+   */
+  inset?: number;
+  style?: StyleProp<ViewStyle>;
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+  testID?: string;
+}
+
+export { tooltipNotchDiamondSide };
+
+/**
+ * Tooltip arrow as a rotated square half-hidden under the opaque card fill.
+ *
+ * Web uses a CSS border-triangle under `filter: drop-shadow`, so the notch and
+ * card share one silhouette. RN box-shadow can't follow alpha, and border
+ * triangles render poorly — a diamond behind the card reads as a real tooltip
+ * pointer and joins the fill without a seam.
+ */
+export function TooltipNotch({
+  notchSize,
+  notchColor,
+  inset = 0,
+  style,
+  top,
+  bottom,
+  left,
+  right,
+  testID = 'userflow-tooltip-notch',
+}: TooltipNotchProps): React.ReactElement {
+  const side = Math.max(0, tooltipNotchDiamondSide(notchSize) - inset * 2);
+
+  return (
+    <View
+      pointerEvents="none"
+      testID={testID}
+      style={[
+        styles.notch,
+        { width: side, height: side, backgroundColor: notchColor },
+        top !== undefined ? { top: top + inset } : null,
+        bottom !== undefined ? { bottom: bottom + inset } : null,
+        left !== undefined ? { left: left + inset } : null,
+        right !== undefined ? { right: right + inset } : null,
+        style,
+      ]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  notch: {
+    position: 'absolute',
+    transform: [{ rotate: '45deg' }],
+  },
+});

package/src/surfaces/tooltip/computeTooltipPosition.ts

@@ -0,0 +1,125 @@
+import type {
+  Position,
+  Rect,
+  Size,
+  TooltipPlacementSide,
+  WindowSize,
+} from './inferTooltipPlacement';
+import { VIEWPORT_PADDING } from './inferTooltipPlacement';
+
+export interface NotchPosition {
+  top?: number;
+  bottom?: number;
+  left?: number;
+  right?: number;
+}
+
+export interface TooltipLayout {
+  cardPosition: Position;
+  notchPosition: NotchPosition;
+  /** Padded target rect used for the cutout hole. */
+  targetHighlightRect: { top: number; left: number; width: number; height: number };
+}
+
+/**
+ * Side length of the axis-aligned square that, when rotated 45°, yields a
+ * tip that protrudes `notchSize` beyond the card edge (half-diagonal = N).
+ */
+export function tooltipNotchDiamondSide(notchSize: number): number {
+  return notchSize * Math.SQRT2;
+}
+
+/**
+ * TOOLTIP card + notch layout. Port of FlowChrome.tsx placement/clamp.
+ *
+ * The notch is a square of side `N√2` rotated 45° whose center sits on the card
+ * edge, so a tip of length `N` points at the target. When the card has a border,
+ * pull the diamond toward the card by `borderWidth` so the tip still clears the
+ * stroke without leaving a seam.
+ */
+export function computeTooltipPosition(opts: {
+  target: Rect;
+  bubbleSize: Size;
+  placement: TooltipPlacementSide;
+  notchSize: number;
+  backdropPadding?: number;
+  windowSize: WindowSize;
+  bubbleBorderRadius: number;
+  bubbleBorderWidth?: number;
+  viewportPadding?: number;
+}): TooltipLayout {
+  const {
+    target,
+    bubbleSize,
+    placement,
+    notchSize,
+    backdropPadding = 0,
+    windowSize,
+    bubbleBorderRadius,
+    bubbleBorderWidth = 0,
+    viewportPadding = VIEWPORT_PADDING,
+  } = opts;
+  const { width: cw, height: ch } = windowSize;
+  const { width: bw, height: bh } = bubbleSize;
+
+  const targetRect = {
+    top: target.y - backdropPadding,
+    right: target.x + target.width + backdropPadding,
+    bottom: target.y + target.height + backdropPadding,
+    left: target.x - backdropPadding,
+    width: target.width + backdropPadding * 2,
+    height: target.height + backdropPadding * 2,
+  };
+
+  let cx = 0;
+  let cy = 0;
+  const notch: NotchPosition = {};
+  const side = tooltipNotchDiamondSide(notchSize);
+  const half = side / 2;
+  const edgeOffset = -half + Math.max(0, bubbleBorderWidth) + 1;
+
+  if (placement === 'BELOW' || placement === 'ABOVE') {
+    cx = targetRect.left + targetRect.width / 2 - bw / 2;
+    cx = Math.max(viewportPadding, Math.min(cw - bw - viewportPadding, cx));
+
+    const rawLeft = targetRect.left + targetRect.width / 2 - half - cx;
+    notch.left = Math.max(bubbleBorderRadius, Math.min(bw - bubbleBorderRadius - side, rawLeft));
+
+    if (placement === 'BELOW') {
+      cy = targetRect.bottom + notchSize;
+      cy = Math.max(notchSize, Math.min(ch - bh, cy));
+      notch.top = edgeOffset;
+    } else {
+      cy = targetRect.top - notchSize - bh;
+      cy = Math.max(0, Math.min(ch - bh - notchSize, cy));
+      notch.bottom = edgeOffset;
+    }
+  } else {
+    cy = targetRect.top + targetRect.height / 2 - bh / 2;
+    cy = Math.max(viewportPadding, Math.min(ch - bh - viewportPadding, cy));
+
+    const rawTop = targetRect.top + targetRect.height / 2 - half - cy;
+    notch.top = Math.max(bubbleBorderRadius, Math.min(bh - bubbleBorderRadius - side, rawTop));
+
+    if (placement === 'RIGHT') {
+      cx = targetRect.right + notchSize;
+      cx = Math.max(notchSize, Math.min(cw - bw, cx));
+      notch.left = edgeOffset;
+    } else {
+      cx = targetRect.left - notchSize - bw;
+      cx = Math.max(0, Math.min(cw - bw - notchSize, cx));
+      notch.right = edgeOffset;
+    }
+  }
+
+  return {
+    cardPosition: { x: cx, y: cy },
+    notchPosition: notch,
+    targetHighlightRect: {
+      top: target.y - backdropPadding,
+      left: target.x - backdropPadding,
+      width: target.width + backdropPadding * 2,
+      height: target.height + backdropPadding * 2,
+    },
+  };
+}

package/src/surfaces/tooltip/inferTooltipPlacement.ts

@@ -0,0 +1,109 @@
+/** Placement sides — string union so Jest protocol mocks stay empty. */
+export type TooltipPlacementSide = 'ABOVE' | 'BELOW' | 'LEFT' | 'RIGHT';
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface Position {
+  x: number;
+  y: number;
+}
+
+export interface WindowSize {
+  width: number;
+  height: number;
+}
+
+import { TOOLTIP_VIEWPORT_PADDING } from '../resolveTooltipLayout';
+
+export const VIEWPORT_PADDING = TOOLTIP_VIEWPORT_PADDING;
+
+/**
+ * Port of web FlowChrome `inferTooltipPlacement` with distance-sorted flip
+ * (not the prototype's fixed BELOW→ABOVE→RIGHT→LEFT priority).
+ */
+export function inferTooltipPlacement({
+  target,
+  bubbleSize,
+  notchSize,
+  windowSize,
+  currentPlacement,
+  desiredPlacement,
+}: {
+  target: Rect;
+  bubbleSize: Size;
+  notchSize: number;
+  windowSize: WindowSize;
+  currentPlacement: TooltipPlacementSide | null;
+  desiredPlacement: TooltipPlacementSide | null;
+}): TooltipPlacementSide {
+  const { width: cw, height: ch } = windowSize;
+  const { width: bw, height: bh } = bubbleSize;
+  const clip = { top: 0, right: cw, bottom: ch, left: 0 };
+
+  const targetRect = {
+    top: target.y,
+    right: target.x + target.width,
+    bottom: target.y + target.height,
+    left: target.x,
+    width: target.width,
+    height: target.height,
+  };
+
+  if (targetRect.bottom <= clip.top) {
+    return ch - clip.top > bh + notchSize ? 'BELOW' : 'ABOVE';
+  }
+  if (targetRect.top >= clip.bottom) {
+    return clip.bottom > bh + notchSize ? 'ABOVE' : 'BELOW';
+  }
+  if (targetRect.right <= clip.left) {
+    return cw - clip.left > bw + notchSize ? 'RIGHT' : 'LEFT';
+  }
+  if (targetRect.left >= clip.right) {
+    return clip.right > bw + notchSize ? 'LEFT' : 'RIGHT';
+  }
+
+  const fits = (p: TooltipPlacementSide): boolean => {
+    const midX = targetRect.left + targetRect.width / 2;
+    const midY = targetRect.top + targetRect.height / 2;
+    const midXIn = midX >= clip.left && midX <= clip.right;
+    const midYIn = midY >= clip.top && midY <= clip.bottom;
+    switch (p) {
+      case 'BELOW':
+        return ch - targetRect.bottom > bh + notchSize && midXIn;
+      case 'ABOVE':
+        return targetRect.top > bh + notchSize && midXIn;
+      case 'RIGHT':
+        return cw - targetRect.right > bw + notchSize && midYIn;
+      case 'LEFT':
+        return targetRect.left > bw + notchSize && midYIn;
+      default:
+        return false;
+    }
+  };
+
+  if (desiredPlacement && fits(desiredPlacement)) return desiredPlacement;
+  if (currentPlacement && fits(currentPlacement)) return currentPlacement;
+
+  const options: { placement: TooltipPlacementSide; dist: number }[] = [
+    { placement: 'BELOW', dist: targetRect.top },
+    { placement: 'ABOVE', dist: ch - targetRect.bottom },
+    { placement: 'RIGHT', dist: targetRect.left },
+    { placement: 'LEFT', dist: cw - targetRect.right },
+  ];
+  options.sort((a, b) => a.dist - b.dist);
+  for (const { placement } of options) {
+    if (fits(placement)) return placement;
+  }
+
+  return desiredPlacement ?? 'BELOW';
+}

package/src/surfaces/tooltip/parseBackdropPadding.ts

@@ -0,0 +1,8 @@
+/** Parse step `backdropPadding` (px). Web accepts CSS shorthand; MVP: first number. */
+export function parseBackdropPadding(value: string | null | undefined): number {
+  if (value == null || value === '') return 0;
+  const match = String(value).match(/-?\d+(\.\d+)?/);
+  if (!match) return 0;
+  const n = parseFloat(match[0]);
+  return Number.isFinite(n) ? Math.max(0, n) : 0;
+}

package/src/surfaces/tooltip/rect.ts

@@ -0,0 +1,62 @@
+import type { Rect, WindowSize } from './inferTooltipPlacement';
+
+/** True when two rects are identical (used to avoid redundant setState). */
+export function rectsEqual(a: Rect | null, b: Rect | null): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+
+/** Fully outside the window (no intersection). Kept for callers that need it. */
+export function isRectOffScreen(rect: Rect, windowSize: WindowSize): boolean {
+  return (
+    rect.y + rect.height <= 0 ||
+    rect.y >= windowSize.height ||
+    rect.x + rect.width <= 0 ||
+    rect.x >= windowSize.width
+  );
+}
+
+/**
+ * Viewport used for scroll-into-view / visibility checks. May be smaller than
+ * the raw window (keyboard, safe-area, sticky chrome via scroll padding).
+ */
+export interface EffectiveViewport {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * True when every edge of `rect` lies inside `viewport` (inclusive).
+ * Partially clipped targets return false — matching web `block: 'nearest'`
+ * scroll-into-view gating.
+ */
+export function isRectFullyVisible(rect: Rect, viewport: EffectiveViewport): boolean {
+  if (rect.width <= 0 || rect.height <= 0) return false;
+  if (viewport.width <= 0 || viewport.height <= 0) return false;
+  return (
+    rect.x >= viewport.x &&
+    rect.y >= viewport.y &&
+    rect.x + rect.width <= viewport.x + viewport.width &&
+    rect.y + rect.height <= viewport.y + viewport.height
+  );
+}
+
+/** Build an effective viewport from window size + optional insets. */
+export function buildEffectiveViewport(
+  windowSize: WindowSize,
+  insets?: { top?: number; right?: number; bottom?: number; left?: number },
+): EffectiveViewport {
+  const top = Math.max(0, insets?.top ?? 0);
+  const right = Math.max(0, insets?.right ?? 0);
+  const bottom = Math.max(0, insets?.bottom ?? 0);
+  const left = Math.max(0, insets?.left ?? 0);
+  return {
+    x: left,
+    y: top,
+    width: Math.max(0, windowSize.width - left - right),
+    height: Math.max(0, windowSize.height - top - bottom),
+  };
+}

package/src/useUserflowScreen.ts

@@ -0,0 +1,17 @@
+import { useEffect } from 'react';
+
+import { handleScreenChange } from './screenTracker';
+
+/**
+ * Reports the active React Navigation (or manual) screen name to Userflow when
+ * it changes. Sent to the backend as `clientContext.screen`.
+ *
+ * Prefer {@link UserflowProvider} + {@link WithUserflowReactNavigation} when
+ * using React Navigation. For Expo Router pathnames, prefer
+ * {@link UserflowProvider} (it wires pathname tracking automatically).
+ */
+export function useUserflowScreen(screenName: string | undefined): void {
+  useEffect(() => {
+    handleScreenChange(screenName ? { screen: screenName } : undefined);
+  }, [screenName]);
+}

package/src/version.ts

@@ -0,0 +1,2 @@
+/** Generated by scripts/write-version.mjs — do not edit. */
+export const SDK_VERSION = '0.1.0';