@userflow-tech/react-native 0.1.0

package/src/anchors/scrollAnchorIntoView.ts

@@ -0,0 +1,251 @@
+/**
+ * Scroll a tooltip anchor into view by walking fiber scroll ancestors
+ * (or an explicit scroll-container registry override).
+ *
+ * Content offset is derived from two `measureInWindow` calls — container
+ * origin minus content origin — so the host app does not need to wire
+ * `onScroll`. Semantics match web `scrollIntoView({ block: 'nearest' })`:
+ * the minimal delta that brings the padded target fully inside the viewport.
+ */
+
+import type { Rect } from '../surfaces/tooltip/inferTooltipPlacement';
+
+import type { AnchorHost } from './AnchorRegistry';
+import { scrollContainerRegistry } from './ScrollContainerRegistry';
+import type { AnyFiber } from './fiber/fiberInternals';
+import { findScrollAncestors, type ScrollAncestor } from './fiber/findScrollAncestors';
+import { measureHostFiber } from './fiber/measureHostFiber';
+import { getCustomScrollIntoView, getScrollPadding, type ScrollPadding } from './scrollConfig';
+
+/** Padding applied inside a scroll container when bringing a target into view. */
+const INTO_VIEW_PADDING = 24;
+
+export interface ScrollAnchorIntoViewOptions {
+  /** Measured window rect of the tooltip target. */
+  rect: Rect;
+  /** Measurable host (registry or fiber-backed). */
+  host: AnchorHost;
+  /**
+   * Cached anchor host fiber — enables automatic scroll-ancestor discovery.
+   * When omitted, only the registry / custom / host.scrollIntoView paths run.
+   */
+  fiber?: AnyFiber | null;
+}
+
+/**
+ * Best-effort scroll so `opts.rect` becomes fully visible.
+ *
+ * Order:
+ * 1. `setCustomScrollIntoView` override (replaces everything)
+ * 2. Explicit `useUserflowScrollContainer` registry (opt-in override)
+ * 3. Fiber scroll-ancestor walk (automatic for testID anchors)
+ * 4. `host.scrollIntoView` (RN Web / DOM)
+ *
+ * Returns `true` when at least one scroll was attempted.
+ */
+export function scrollAnchorIntoView(opts: ScrollAnchorIntoViewOptions): boolean {
+  const { rect, host, fiber } = opts;
+
+  const custom = getCustomScrollIntoView();
+  if (custom) {
+    try {
+      custom({ rect, measureInWindow: host.measureInWindow.bind(host) });
+    } catch {
+      // Best-effort.
+    }
+    return true;
+  }
+
+  let attempted = false;
+
+  // Explicit registry wins over the fiber walk (mirrors anchorRegistry vs scan).
+  if (scrollContainerRegistry.list().length > 0) {
+    try {
+      scrollContainerRegistry.scrollTargetIntoView(rect);
+      attempted = true;
+    } catch {
+      // Fall through.
+    }
+  } else if (fiber) {
+    attempted = scrollFiberAncestors(fiber, rect) || attempted;
+  }
+
+  if (typeof host.scrollIntoView === 'function') {
+    try {
+      host.scrollIntoView();
+      attempted = true;
+    } catch {
+      // Best-effort.
+    }
+  }
+
+  return attempted;
+}
+
+/**
+ * Drive every scroll ancestor of `fiber`, innermost first, so nested
+ * scrollers compose correctly.
+ */
+export function scrollFiberAncestors(fiber: AnyFiber, target: Rect): boolean {
+  const ancestors = findScrollAncestors(fiber);
+  if (ancestors.length === 0) return false;
+
+  const padding = mergePadding(getScrollPadding());
+  let attempted = false;
+  for (const ancestor of ancestors) {
+    if (scrollOneAncestor(ancestor, target, padding)) {
+      attempted = true;
+    }
+  }
+  return attempted;
+}
+
+function mergePadding(configured: ScrollPadding | null): Required<ScrollPadding> {
+  return {
+    top: (configured?.top ?? 0) + INTO_VIEW_PADDING,
+    right: (configured?.right ?? 0) + INTO_VIEW_PADDING,
+    bottom: (configured?.bottom ?? 0) + INTO_VIEW_PADDING,
+    left: (configured?.left ?? 0) + INTO_VIEW_PADDING,
+  };
+}
+
+function scrollOneAncestor(
+  ancestor: ScrollAncestor,
+  target: Rect,
+  padding: Required<ScrollPadding>,
+): boolean {
+  const { instance, containerFiber, contentFiber, horizontal } = ancestor;
+
+  // Need both fibers to derive offset from measure. Without them, try a
+  // best-effort scrollTo that assumes offset 0 (first paint / unmounted content).
+  if (!containerFiber) {
+    return scrollWithAssumedOffset(instance, target, padding, horizontal, { x: 0, y: 0 }, null);
+  }
+
+  // measureInWindow is async on Paper — fire-and-forget; callers treat a
+  // kicked-off measure as an attempted scroll.
+  measureHostFiber(containerFiber, (cx, cy, cw, ch) => {
+    if (cw <= 0 || ch <= 0) return;
+
+    const finish = (offsetX: number, offsetY: number): void => {
+      scrollWithAssumedOffset(
+        instance,
+        target,
+        padding,
+        horizontal,
+        { x: Math.max(0, offsetX), y: Math.max(0, offsetY) },
+        { x: cx, y: cy, width: cw, height: ch },
+      );
+    };
+
+    if (!contentFiber) {
+      finish(0, 0);
+      return;
+    }
+
+    measureHostFiber(contentFiber, (contentX, contentY) => {
+      // Content is translated up/left by the scroll offset.
+      const offsetY = cy - contentY;
+      const offsetX = cx - contentX;
+      finish(offsetX, offsetY);
+    });
+  });
+
+  return true;
+}
+
+function scrollWithAssumedOffset(
+  instance: ScrollAncestor['instance'],
+  target: Rect,
+  padding: Required<ScrollPadding>,
+  horizontal: boolean,
+  offset: { x: number; y: number },
+  container: Rect | null,
+): boolean {
+  // Without a measured container, we can only nudge based on window-space
+  // heuristics via scrollToOffset-style APIs when the target is clearly
+  // off-screen relative to a zero origin — skip rather than guess badly.
+  if (!container) {
+    return false;
+  }
+
+  const targetContentY = offset.y + (target.y - container.y);
+  const targetContentX = offset.x + (target.x - container.x);
+
+  let nextY: number | null = null;
+  let nextX: number | null = null;
+
+  if (target.y < container.y + padding.top) {
+    nextY = Math.max(0, targetContentY - padding.top);
+  } else if (target.y + target.height > container.y + container.height - padding.bottom) {
+    nextY = Math.max(0, targetContentY + target.height - container.height + padding.bottom);
+  }
+
+  if (target.x < container.x + padding.left) {
+    nextX = Math.max(0, targetContentX - padding.left);
+  } else if (target.x + target.width > container.x + container.width - padding.right) {
+    nextX = Math.max(0, targetContentX + target.width - container.width + padding.right);
+  }
+
+  const yChanged = nextY != null && Math.abs(nextY - offset.y) >= 1;
+  const xChanged = nextX != null && Math.abs(nextX - offset.x) >= 1;
+  if (!yChanged && !xChanged) return false;
+
+  const y = yChanged ? nextY! : offset.y;
+  const x = xChanged ? nextX! : offset.x;
+
+  try {
+    if (typeof instance.scrollTo === 'function') {
+      instance.scrollTo({ x, y, animated: true });
+      return true;
+    }
+    if (typeof instance.scrollToOffset === 'function') {
+      instance.scrollToOffset({
+        offset: horizontal ? x : y,
+        animated: true,
+      });
+      return true;
+    }
+    // SectionList without a numeric offset path — cannot target by testID index.
+  } catch {
+    // Best-effort.
+  }
+  return false;
+}
+
+/**
+ * Pure helper exported for unit tests: compute the next content offset that
+ * brings `target` fully inside `container` with `block: 'nearest'` semantics.
+ */
+export function computeNearestScrollOffset(opts: {
+  target: Rect;
+  container: Rect;
+  contentOffset: { x: number; y: number };
+  padding?: Partial<ScrollPadding>;
+}): { x: number; y: number; changed: boolean } {
+  const padding = mergePadding(opts.padding ?? null);
+  const { target, container, contentOffset } = opts;
+  const targetContentY = contentOffset.y + (target.y - container.y);
+  const targetContentX = contentOffset.x + (target.x - container.x);
+
+  let nextY = contentOffset.y;
+  let nextX = contentOffset.x;
+
+  if (target.y < container.y + padding.top) {
+    nextY = Math.max(0, targetContentY - padding.top);
+  } else if (target.y + target.height > container.y + container.height - padding.bottom) {
+    nextY = Math.max(0, targetContentY + target.height - container.height + padding.bottom);
+  }
+
+  if (target.x < container.x + padding.left) {
+    nextX = Math.max(0, targetContentX - padding.left);
+  } else if (target.x + target.width > container.x + container.width - padding.right) {
+    nextX = Math.max(0, targetContentX + target.width - container.width + padding.right);
+  }
+
+  return {
+    x: nextX,
+    y: nextY,
+    changed: Math.abs(nextX - contentOffset.x) >= 1 || Math.abs(nextY - contentOffset.y) >= 1,
+  };
+}

package/src/anchors/scrollConfig.ts

@@ -0,0 +1,61 @@
+/**
+ * Integrator-level scroll configuration, mirroring web userflow.js
+ * `setScrollPadding` / `setCustomScrollIntoView`.
+ */
+
+import type { Rect } from '../surfaces/tooltip/inferTooltipPlacement';
+
+export interface ScrollPadding {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+
+/** Target passed to a custom scroll-into-view override. */
+export interface ScrollIntoViewTarget {
+  rect: Rect;
+  measureInWindow: (
+    callback: (x: number, y: number, width: number, height: number) => void,
+  ) => void;
+}
+
+export type CustomScrollIntoView = (target: ScrollIntoViewTarget) => void;
+
+interface ScrollConfig {
+  scrollPadding: ScrollPadding | null;
+  customScrollIntoView: CustomScrollIntoView | null;
+}
+
+const config: ScrollConfig = {
+  scrollPadding: null,
+  customScrollIntoView: null,
+};
+
+/** Sticky header/footer insets applied when deciding whether / how far to scroll. */
+export function setScrollPadding(padding: ScrollPadding | null | undefined): void {
+  config.scrollPadding = padding ?? null;
+}
+
+export function getScrollPadding(): ScrollPadding | null {
+  return config.scrollPadding;
+}
+
+/**
+ * Replace the SDK's scroll-into-view behavior entirely. Useful for scroll
+ * libraries the fiber walk cannot drive (some FlashList / Reanimated setups).
+ * Pass `null` to restore the default.
+ */
+export function setCustomScrollIntoView(fn: CustomScrollIntoView | null | undefined): void {
+  config.customScrollIntoView = fn ?? null;
+}
+
+export function getCustomScrollIntoView(): CustomScrollIntoView | null {
+  return config.customScrollIntoView;
+}
+
+/** Test helper — reset to defaults. */
+export function resetScrollConfig(): void {
+  config.scrollPadding = null;
+  config.customScrollIntoView = null;
+}

package/src/anchors/targetPressMonitor.ts

@@ -0,0 +1,127 @@
+/**
+ * Active tooltip target-press subscription.
+ *
+ * {@link TooltipSurface} registers while a TOOLTIP step has a measured target,
+ * non-empty `actions`, and `tooltipTargetBlocked === false`. The bridge reads
+ * this at touch time so rAF measure updates do not re-render the provider.
+ */
+export interface TargetPressRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface TargetPressSubscription {
+  /** Latest measured target bounds (window coordinates). */
+  getRect: () => TargetPressRect | null;
+  /** Runs step.actions — same role as web `onTooltipTargetClick`. */
+  onPress: () => void;
+}
+
+/** Max finger travel (px) between start and end to count as a tap, not a scroll. */
+export const TARGET_PRESS_TAP_SLOP = 10;
+
+export function pointInRect(x: number, y: number, rect: TargetPressRect): boolean {
+  return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
+}
+
+export interface TouchPoint {
+  pageX: number;
+  pageY: number;
+}
+
+/**
+ * True when start and end both land in `rect` and movement stays within tap
+ * slop — mirrors a DOM click on the target without claiming the responder.
+ */
+export function isTargetTap(
+  start: TouchPoint,
+  end: TouchPoint,
+  rect: TargetPressRect,
+  slop: number = TARGET_PRESS_TAP_SLOP,
+): boolean {
+  if (!pointInRect(start.pageX, start.pageY, rect)) return false;
+  if (!pointInRect(end.pageX, end.pageY, rect)) return false;
+  const dx = end.pageX - start.pageX;
+  const dy = end.pageY - start.pageY;
+  return dx * dx + dy * dy <= slop * slop;
+}
+
+/**
+ * Module singleton for the active tooltip target-click listener.
+ * At most one subscription (one visible tooltip step).
+ *
+ * In-progress touches are keyed by native `identifier` so multi-touch start/end
+ * pairs correctly when several fingers are down. RN types `identifier` as
+ * `string`; accept `number | string` for tests and older typings.
+ */
+export type TouchIdentifier = number | string;
+
+export class TargetPressMonitor {
+  private subscription: TargetPressSubscription | null = null;
+  private touchStarts = new Map<TouchIdentifier, TouchPoint>();
+
+  set(subscription: TargetPressSubscription | null): void {
+    this.subscription = subscription;
+    if (!subscription) {
+      this.touchStarts.clear();
+    }
+  }
+
+  clear(): void {
+    this.set(null);
+  }
+
+  get(): TargetPressSubscription | null {
+    return this.subscription;
+  }
+
+  /** Record touch start for `identifier`; ignores when no active subscription. */
+  handleTouchStart(identifier: TouchIdentifier, pageX: number, pageY: number): void {
+    if (!this.subscription) {
+      this.touchStarts.clear();
+      return;
+    }
+    this.touchStarts.set(identifier, { pageX, pageY });
+  }
+
+  /**
+   * If the gesture for `identifier` is a tap on the registered target, invoke
+   * `onPress`. Never claims the responder — app controls still receive the press.
+   */
+  handleTouchEnd(identifier: TouchIdentifier, pageX: number, pageY: number): void {
+    const start = this.touchStarts.get(identifier) ?? null;
+    this.touchStarts.delete(identifier);
+    const sub = this.subscription;
+    if (!start || !sub) return;
+
+    const rect = sub.getRect();
+    if (!rect || rect.width <= 0 || rect.height <= 0) return;
+
+    if (isTargetTap(start, { pageX, pageY }, rect)) {
+      sub.onPress();
+    }
+  }
+
+  /**
+   * Drop in-progress gesture(s). With `identifier`, cancels that finger only;
+   * otherwise clears all (e.g. blanket `onTouchCancel`).
+   */
+  cancelTouch(identifier?: TouchIdentifier): void {
+    if (identifier == null) {
+      this.touchStarts.clear();
+      return;
+    }
+    this.touchStarts.delete(identifier);
+  }
+
+  /** Test helper. */
+  resetForTests(): void {
+    this.subscription = null;
+    this.touchStarts.clear();
+  }
+}
+
+/** Shared singleton used by TooltipSurface and TargetPressBridge. */
+export const targetPressMonitor = new TargetPressMonitor();

package/src/anchors/useUserflowAnchor.ts

@@ -0,0 +1,88 @@
+import * as React from 'react';
+import type { View } from 'react-native';
+
+import { anchorRegistry, type AnchorHost } from './AnchorRegistry';
+
+/**
+ * Register a view as a manual Userflow tooltip / embed target.
+ *
+ * Prefer tagging with a plain `testID` (or `nativeID` / `accessibilityLabel`)
+ * on the target view — the SDK resolves those via a fiber-tree scan without a
+ * hook. Use this hook when you need an explicit override (e.g. a third-party
+ * component that does not forward `testID`, or when the same string appears on
+ * multiple views).
+ *
+ * Usage (override):
+ * ```tsx
+ * const anchorRef = useUserflowAnchor('invite-teammates');
+ * return <Pressable ref={anchorRef}>Invite</Pressable>;
+ * ```
+ *
+ * Preferred (no hook):
+ * ```tsx
+ * return <Pressable testID="invite-teammates">Invite</Pressable>;
+ * ```
+ *
+ * When the target can sit inside a scrollable screen, also register the parent
+ * {@link ScrollView} with {@link useUserflowScrollContainer} so off-screen
+ * anchors are scrolled into view before the tooltip places.
+ *
+ * Phase 3 resolves targets via `step.selector.css` (leading `#` stripped).
+ */
+export function useUserflowAnchor(id: string): React.RefCallback<View> {
+  const hostRef = React.useRef<AnchorHost | null>(null);
+  const idRef = React.useRef(id);
+
+  React.useEffect(() => {
+    const previousId = idRef.current;
+    const host = hostRef.current;
+    if (previousId !== id && host) {
+      anchorRegistry.unregister(previousId, host);
+      if (id) {
+        anchorRegistry.register(id, host);
+      }
+    }
+    idRef.current = id;
+  }, [id]);
+
+  React.useEffect(() => {
+    return () => {
+      const host = hostRef.current;
+      if (host) {
+        anchorRegistry.unregister(idRef.current, host);
+        hostRef.current = null;
+      }
+    };
+  }, []);
+
+  return React.useCallback((node: View | null) => {
+    const previous = hostRef.current;
+    const currentId = idRef.current;
+    if (previous) {
+      anchorRegistry.unregister(currentId, previous);
+    }
+    if (!node) {
+      hostRef.current = null;
+      return;
+    }
+
+    // Wrap the view so we can add optional best-effort scrollIntoView (e.g. RN Web).
+    const host: AnchorHost = {
+      measureInWindow: (callback) => {
+        node.measureInWindow(callback);
+      },
+      scrollIntoView: () => {
+        const scrollable = node as View & {
+          scrollIntoView?: (options?: { block?: string; inline?: string }) => void;
+        };
+        if (typeof scrollable.scrollIntoView === 'function') {
+          scrollable.scrollIntoView({ block: 'nearest', inline: 'nearest' });
+        }
+      },
+    };
+    hostRef.current = host;
+    if (currentId) {
+      anchorRegistry.register(currentId, host);
+    }
+  }, []);
+}

package/src/anchors/useUserflowScrollContainer.ts

@@ -0,0 +1,86 @@
+import * as React from 'react';
+import type { NativeScrollEvent, NativeSyntheticEvent, ScrollView } from 'react-native';
+
+import {
+  createScrollContainerHost,
+  scrollContainerRegistry,
+  type ScrollContainerHost,
+} from './ScrollContainerRegistry';
+
+export interface UserflowScrollContainerProps {
+  /** Attach to the host ScrollView (or merge with an existing ref). */
+  ref: React.RefCallback<ScrollView>;
+  /** Forward to ScrollView so content offsets stay in sync for scroll-into-view. */
+  onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  /** Required for frequent offset updates while scrolling. */
+  scrollEventThrottle: number;
+}
+
+/**
+ * Register a host {@link ScrollView} so tooltip anchors can be scrolled into view
+ * when their measured window rect is not fully visible.
+ *
+ * Usually unnecessary — the SDK discovers ScrollView / FlatList ancestors via
+ * the fiber walk for `testID` anchors. Use this hook as an explicit override
+ * for scroll libraries the walk cannot drive, or when the target is only
+ * registered via {@link useUserflowAnchor} without a discoverable fiber.
+ *
+ * Usage:
+ * ```tsx
+ * const scroll = useUserflowScrollContainer();
+ * return (
+ *   <ScrollView {...scroll}>
+ *     <Pressable testID="invite-teammates">Invite</Pressable>
+ *   </ScrollView>
+ * );
+ * ```
+ *
+ * Screen tracking ≠ scroll registration — only ScrollViews you pass through this
+ * hook participate in the registry override path.
+ */
+export function useUserflowScrollContainer(
+  onScrollProp?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void,
+): UserflowScrollContainerProps {
+  const hostRef = React.useRef<ScrollContainerHost | null>(null);
+  const nodeRef = React.useRef<ScrollView | null>(null);
+  const offsetRef = React.useRef({ x: 0, y: 0 });
+
+  React.useEffect(() => {
+    return () => {
+      const host = hostRef.current;
+      if (host) {
+        scrollContainerRegistry.unregister(host);
+        hostRef.current = null;
+      }
+    };
+  }, []);
+
+  const ref = React.useCallback((node: ScrollView | null) => {
+    const previous = hostRef.current;
+    if (previous) {
+      scrollContainerRegistry.unregister(previous);
+      hostRef.current = null;
+    }
+    nodeRef.current = node;
+    if (!node) return;
+
+    const host = createScrollContainerHost(node, () => offsetRef.current);
+    hostRef.current = host;
+    scrollContainerRegistry.register(host);
+  }, []);
+
+  const onScroll = React.useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const { contentOffset } = event.nativeEvent;
+      offsetRef.current = { x: contentOffset.x, y: contentOffset.y };
+      onScrollProp?.(event);
+    },
+    [onScrollProp],
+  );
+
+  return {
+    ref,
+    onScroll,
+    scrollEventThrottle: 16,
+  };
+}

package/src/anonymousId.ts

@@ -0,0 +1,38 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { UserflowAuthError } from '@userflow-tech/core';
+
+/** Matches the web SDK's `userflow:anonymousId` localStorage key. */
+export const ANONYMOUS_ID_STORAGE_KEY = 'userflow:anonymousId';
+
+function uuid(): string {
+  const webcrypto = globalThis.crypto;
+  if (webcrypto?.randomUUID) return webcrypto.randomUUID();
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (char) => {
+    const rand = (Math.random() * 16) | 0;
+    const value = char === 'x' ? rand : (rand & 0x3) | 0x8;
+    return value.toString(16);
+  });
+}
+
+export async function getOrCreateAnonymousId(): Promise<string> {
+  try {
+    let externalId = await AsyncStorage.getItem(ANONYMOUS_ID_STORAGE_KEY);
+    if (!externalId) {
+      externalId = `anon-${uuid()}`;
+      await AsyncStorage.setItem(ANONYMOUS_ID_STORAGE_KEY, externalId);
+    }
+    return externalId;
+  } catch {
+    throw new UserflowAuthError(
+      'Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.',
+    );
+  }
+}
+
+export async function clearAnonymousId(): Promise<void> {
+  try {
+    await AsyncStorage.removeItem(ANONYMOUS_ID_STORAGE_KEY);
+  } catch {
+    // Best-effort clear, mirroring the web SDK when storage access is denied.
+  }
+}