@userflow-tech/react-native 0.1.0

package/src/runtime/FlowSurfaceFade.tsx

@@ -0,0 +1,55 @@
+import * as React from 'react';
+import { Animated, StyleSheet, View } from 'react-native';
+
+import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+
+const FADE_MS = 180;
+
+export interface FlowSurfaceFadeProps {
+  children: React.ReactNode;
+  /** Bumps when the active step changes so we fade in again. */
+  animationKey: string;
+}
+
+/**
+ * Short opacity fade for flow surface entry (FLOW_RENDERING_SPEC minimum).
+ * Exit fades when the keyed surface unmounts via a brief hold are deferred —
+ * step swaps remount with a fresh fade-in.
+ */
+export function FlowSurfaceFade({
+  children,
+  animationKey,
+}: FlowSurfaceFadeProps): React.ReactElement {
+  const opacity = React.useRef(new Animated.Value(0)).current;
+
+  React.useEffect(() => {
+    opacity.setValue(0);
+    const animation = Animated.timing(opacity, {
+      toValue: 1,
+      duration: FADE_MS,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => {
+      animation.stop();
+    };
+  }, [animationKey, opacity]);
+
+  return (
+    <Animated.View
+      testID="userflow-surface-fade"
+      style={[styles.fill, { opacity }]}
+      pointerEvents="box-none"
+    >
+      <View style={styles.fill} pointerEvents="box-none">
+        {children}
+      </View>
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  fill: {
+    ...ABSOLUTE_FILL,
+  },
+});

package/src/runtime/TargetPressBridge.tsx

@@ -0,0 +1,86 @@
+import * as React from 'react';
+import { StyleSheet, View, type GestureResponderEvent, type NativeTouchEvent } from 'react-native';
+
+import { targetPressMonitor } from '../anchors/targetPressMonitor';
+
+export interface TargetPressBridgeProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Touches that just started/ended/cancelled for this event. Prefer
+ * `changedTouches` so multi-touch uses the finger(s) that actually changed —
+ * `touches[0]` may be an already-active finger. Each touch carries `identifier`
+ * so the monitor can pair start/end per finger.
+ */
+function changedTouchPoints(
+  event: GestureResponderEvent,
+): Array<Pick<NativeTouchEvent, 'identifier' | 'pageX' | 'pageY'>> {
+  const { changedTouches, touches, identifier, pageX, pageY } = event.nativeEvent;
+  if (changedTouches && changedTouches.length > 0) {
+    return changedTouches.map((touch) => ({
+      identifier: touch.identifier,
+      pageX: touch.pageX,
+      pageY: touch.pageY,
+    }));
+  }
+  if (touches && touches.length > 0) {
+    const touch = touches[touches.length - 1]!;
+    return [{ identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY }];
+  }
+  return [{ identifier: identifier ?? 0, pageX, pageY }];
+}
+
+/**
+ * Wraps app content so tooltip target taps can be observed without stealing
+ * them from the underlying control (web parity: click listener, no preventDefault).
+ *
+ * The Userflow overlay is a sibling above the app, so hole Pressables would
+ * intercept presses. Instead we hit-test bubbled `onTouchStart` / `onTouchEnd`
+ * against the rect registered by {@link TooltipSurface}.
+ *
+ * Does not claim the gesture responder.
+ */
+export function TargetPressBridge({ children }: TargetPressBridgeProps): React.ReactElement {
+  const onTouchStart = React.useCallback((event: GestureResponderEvent) => {
+    for (const touch of changedTouchPoints(event)) {
+      targetPressMonitor.handleTouchStart(touch.identifier, touch.pageX, touch.pageY);
+    }
+  }, []);
+
+  const onTouchEnd = React.useCallback((event: GestureResponderEvent) => {
+    for (const touch of changedTouchPoints(event)) {
+      targetPressMonitor.handleTouchEnd(touch.identifier, touch.pageX, touch.pageY);
+    }
+  }, []);
+
+  const onTouchCancel = React.useCallback((event: GestureResponderEvent) => {
+    const points = changedTouchPoints(event);
+    if (points.length === 0) {
+      targetPressMonitor.cancelTouch();
+      return;
+    }
+    for (const touch of points) {
+      targetPressMonitor.cancelTouch(touch.identifier);
+    }
+  }, []);
+
+  return (
+    <View
+      style={styles.root}
+      collapsable={false}
+      onTouchStart={onTouchStart}
+      onTouchEnd={onTouchEnd}
+      onTouchCancel={onTouchCancel}
+      testID="userflow-target-press-bridge"
+    >
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+});

package/src/runtime/UserflowProvider.tsx

@@ -0,0 +1,89 @@
+import type { FlowSessionEngine } from '@userflow-tech/core';
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { FiberScanRoot } from '../anchors/fiber/FiberScanRoot';
+import { PreviewModeBanner } from '../pairing/PreviewModeBanner';
+import { getPairingController } from '../pairing/pairingRuntime';
+import { usePairingState } from '../pairing/usePairingState';
+import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+
+import { FlowRenderer } from './FlowRenderer';
+import { TargetPressBridge } from './TargetPressBridge';
+import { getFlowSessionEngine } from './flowEngine';
+import { getUserflowCore } from './userflowCore';
+
+export interface UserflowContextValue {
+  engine: FlowSessionEngine;
+}
+
+const UserflowContext = React.createContext<UserflowContextValue | null>(null);
+
+export interface UserflowProviderProps {
+  children: React.ReactNode;
+  /** Override the module singleton engine (tests). */
+  engine?: FlowSessionEngine;
+}
+
+/**
+ * Mount once at the application root, above the navigation container
+ * (for example the root `_layout.tsx` or `App` component), after
+ * calling {@link Userflow.init}.
+ *
+ * Children render normally. An absolute overlay sits above them with
+ * `pointerEvents="box-none"` so taps pass through except where flow UI sits.
+ * We deliberately do not use RN `<Modal>` — it is the wrong primitive for
+ * non-modal tooltips (WS6).
+ *
+ * **Expo Router:** also mount `UserflowExpoRouterScreenTracker` from
+ * `@userflow-tech/react-native/expo-router` under this provider so pathname changes
+ * and path-like NAVIGATE actions are wired. The tracker is a separate entry so
+ * apps without `expo-router` are not forced to install that peer.
+ *
+ * **React Navigation:** wrap `NavigationContainer` with
+ * {@link WithUserflowReactNavigation} from `@userflow-tech/react-native/navigation`.
+ */
+export function UserflowProvider({
+  children,
+  engine: engineProp,
+}: UserflowProviderProps): React.ReactElement {
+  const engine = engineProp ?? getFlowSessionEngine(getUserflowCore());
+  const contextValue = React.useMemo<UserflowContextValue>(() => ({ engine }), [engine]);
+  const pairingState = usePairingState();
+
+  const onExitPreview = React.useCallback(() => {
+    void getPairingController(getUserflowCore()).exitPreview();
+  }, []);
+
+  return (
+    <UserflowContext.Provider value={contextValue}>
+      <View style={styles.root} collapsable={false}>
+        <TargetPressBridge>
+          <FiberScanRoot>{children}</FiberScanRoot>
+        </TargetPressBridge>
+        <View style={styles.overlay} pointerEvents="box-none">
+          <PreviewModeBanner state={pairingState} onExit={onExitPreview} />
+          <FlowRenderer engine={engine} />
+        </View>
+      </View>
+    </UserflowContext.Provider>
+  );
+}
+
+/** Access the flow session engine from inside {@link UserflowProvider}. */
+export function useUserflow(): UserflowContextValue {
+  const ctx = React.useContext(UserflowContext);
+  if (!ctx) {
+    throw new Error('useUserflow() must be called inside <UserflowProvider>');
+  }
+  return ctx;
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+  overlay: {
+    ...ABSOLUTE_FILL,
+  },
+});

package/src/runtime/clientConditions.ts

@@ -0,0 +1,42 @@
+import { ClientConditionEngine, type UserflowCore } from '@userflow-tech/core';
+
+import { createElementConditionEvaluator } from '../anchors/elementConditionEvaluator';
+
+let clientConditionEngine: ClientConditionEngine | null = null;
+
+/** Build (once) the module-level client-condition engine over a {@link UserflowCore} transport. */
+export function getClientConditionEngine(core: UserflowCore): ClientConditionEngine {
+  if (!clientConditionEngine) {
+    clientConditionEngine = new ClientConditionEngine({
+      transport: {
+        send: (message) => core.send(message),
+        onServerMessage: (handler) => core.onServerMessage(handler),
+        setClientConditions: (list) => core.setClientConditions(list),
+      },
+      evaluators: {
+        // String key matches FlowConditionType.ELEMENT; avoid importing the
+        // ESM-only @userflow-tech/protocol package at runtime under Jest.
+        ELEMENT: createElementConditionEvaluator(),
+      },
+    });
+  }
+  return clientConditionEngine;
+}
+
+/** Subscribe the engine to inbound server messages. Call after identify. */
+export function attachClientConditionEngine(core: UserflowCore): ClientConditionEngine {
+  const engine = getClientConditionEngine(core);
+  engine.attach();
+  return engine;
+}
+
+/** Clear tracked conditions. Call from {@link Userflow.reset}. */
+export function resetClientConditionEngine(): void {
+  clientConditionEngine?.reset();
+}
+
+/** Test helper: drop the singleton so the next get recreates it. */
+export function __resetClientConditionEngineForTests(): void {
+  clientConditionEngine?.reset();
+  clientConditionEngine = null;
+}

package/src/runtime/flowEngine.ts

@@ -0,0 +1,53 @@
+import { FlowSessionEngine, type UserflowCore } from '@userflow-tech/core';
+
+import { openFlowNavigateUrl } from '../navigation/openFlowNavigateUrl';
+
+let flowEngine: FlowSessionEngine | null = null;
+
+/** Build (once) the module-level flow session engine over a {@link UserflowCore} transport. */
+export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
+  if (!flowEngine) {
+    flowEngine = new FlowSessionEngine({
+      transport: {
+        send: (message) => core.send(message),
+        onServerMessage: (handler) => core.onServerMessage(handler),
+        setFlowSessionId: (id) => core.setFlowSessionId(id),
+      },
+      onOpenExternalUrl: (url) => {
+        void openFlowNavigateUrl(url);
+      },
+    });
+  }
+  return flowEngine;
+}
+
+/** Subscribe the engine to inbound server messages. Call after identify. */
+export function attachFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
+  const engine = getFlowSessionEngine(core);
+  engine.attach();
+  return engine;
+}
+
+/** Clear session/clocks/timers. Call from {@link Userflow.reset}. */
+export function resetFlowSessionEngine(): void {
+  flowEngine?.reset();
+}
+
+/**
+ * Drop the local mid-flow session without detaching the transport subscription.
+ * Used after a long background when mid-flow resume would be stale.
+ */
+export function clearFlowSessionEngineLocalSession(): void {
+  flowEngine?.clearLocalSession();
+}
+
+/** Whether any mid-flow session (live or draft/preview) is currently on screen. */
+export function hasActiveFlowSession(): boolean {
+  return flowEngine?.getFlowSession() != null;
+}
+
+/** Test helper: drop the singleton so the next get recreates it. */
+export function __resetFlowSessionEngineForTests(): void {
+  flowEngine?.reset();
+  flowEngine = null;
+}

package/src/runtime/flowSessionViewState.ts

@@ -0,0 +1,55 @@
+import type { FlowSessionEngineEvent } from '@userflow-tech/core';
+import type { FlowSessionFragment, FlowStepFragment } from '@userflow-tech/protocol';
+
+/** React-facing view of the active flow session (derived from engine events). */
+export interface FlowSessionViewState {
+  session: FlowSessionFragment | null;
+  currentStepId: string | null;
+}
+
+export function initialFlowSessionViewState(
+  session: FlowSessionFragment | null,
+): FlowSessionViewState {
+  return {
+    session,
+    currentStepId: session?.currentStep?.id ?? null,
+  };
+}
+
+/**
+ * Reduces engine events into view state.
+ *
+ * Important: `goToStep` updates `currentStepId` without requiring a new
+ * `sessionChange` — the engine mutates `session.currentStep` in place and
+ * `ForceGoToStep` does not update it at all.
+ */
+export function reduceFlowSessionViewState(
+  state: FlowSessionViewState,
+  event: FlowSessionEngineEvent,
+): FlowSessionViewState {
+  switch (event.type) {
+    case 'sessionChange':
+      return {
+        session: event.session,
+        currentStepId: event.session?.currentStep?.id ?? null,
+      };
+    case 'goToStep':
+      return {
+        ...state,
+        currentStepId: event.stepId,
+      };
+    case 'flowEnded':
+      return {
+        session: null,
+        currentStepId: null,
+      };
+  }
+}
+
+export function resolveCurrentStep(
+  session: FlowSessionFragment | null,
+  currentStepId: string | null,
+): FlowStepFragment | null {
+  if (!session || !currentStepId) return null;
+  return session.version.steps.find((step) => step.id === currentStepId) ?? null;
+}

package/src/runtime/useFlowSessionState.ts

@@ -0,0 +1,36 @@
+import type { FlowSessionEngine } from '@userflow-tech/core';
+import type { FlowSessionFragment, FlowStepFragment } from '@userflow-tech/protocol';
+import { useEffect, useReducer } from 'react';
+
+import {
+  initialFlowSessionViewState,
+  reduceFlowSessionViewState,
+  resolveCurrentStep,
+} from './flowSessionViewState';
+
+export interface FlowSessionState {
+  session: FlowSessionFragment | null;
+  currentStepId: string | null;
+  currentStep: FlowStepFragment | null;
+}
+
+/** Subscribe to a {@link FlowSessionEngine} and derive React-friendly session/step state. */
+export function useFlowSessionState(engine: FlowSessionEngine): FlowSessionState {
+  const [state, dispatch] = useReducer(reduceFlowSessionViewState, undefined, () =>
+    initialFlowSessionViewState(engine.getFlowSession()),
+  );
+
+  useEffect(() => {
+    dispatch({
+      type: 'sessionChange',
+      session: engine.getFlowSession(),
+    });
+    return engine.on(dispatch);
+  }, [engine]);
+
+  return {
+    session: state.session,
+    currentStepId: state.currentStepId,
+    currentStep: resolveCurrentStep(state.session, state.currentStepId),
+  };
+}

package/src/runtime/userflowCore.ts

@@ -0,0 +1,8 @@
+import { UserflowCore } from '@userflow-tech/core';
+
+/** Shared {@link UserflowCore} singleton for the RN package facade + provider. */
+const core = new UserflowCore();
+
+export function getUserflowCore(): UserflowCore {
+  return core;
+}

package/src/screenTracker.ts

@@ -0,0 +1,83 @@
+import type { ClientLocationUpdate } from '@userflow-tech/protocol';
+
+/** Called when a new location is accepted (after enable + dedupe). */
+export type ScreenChangeReporter = (location: ClientLocationUpdate) => void;
+
+let enabled = false;
+let currentKey: string | null = null;
+/** Latest location seen while tracking was disabled; flushed on enable. */
+let pendingLocation: ClientLocationUpdate | null = null;
+let reporter: ScreenChangeReporter | null = null;
+
+function locationKey(location: ClientLocationUpdate): string {
+  return 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
+}
+
+/**
+ * Registers the callback invoked when the active screen/path changes.
+ * The React Native facade wires this to `UserflowCore.updateScreen`.
+ */
+export function setScreenChangeReporter(next: ScreenChangeReporter | null): void {
+  reporter = next;
+}
+
+function report(location: ClientLocationUpdate): void {
+  currentKey = locationKey(location);
+  reporter?.(location);
+}
+
+/** Activates screen-change tracking after a successful {@link Userflow.init}. */
+export function enableScreenTracking(): void {
+  enabled = true;
+  if (pendingLocation && locationKey(pendingLocation) !== currentKey) {
+    const location = pendingLocation;
+    pendingLocation = null;
+    report(location);
+  } else {
+    pendingLocation = null;
+  }
+}
+
+/** Deactivates screen-change tracking and clears the last known screen. */
+export function disableScreenTracking(): void {
+  enabled = false;
+  currentKey = null;
+  pendingLocation = null;
+}
+
+/**
+ * Records a navigation to `location` when tracking is enabled.
+ * Duplicate consecutive locations are ignored. On change, notifies the reporter
+ * so the SDK can push `UpdateClientContext` to the backend.
+ *
+ * Locations observed before {@link enableScreenTracking} are remembered and
+ * flushed when tracking is enabled (so init-after-mount still picks up the
+ * active route).
+ *
+ * - Expo Router: `{ path: "/settings/billing" }` → wire `screenPath`
+ * - React Navigation / manual: `{ screen: "BillingSettings" }` → wire `screenName`
+ */
+export function handleScreenChange(location: ClientLocationUpdate | undefined): void {
+  if (!location) return;
+  if ('path' in location) {
+    if (!location.path) return;
+  } else if (!location.screen) {
+    return;
+  }
+
+  if (!enabled) {
+    pendingLocation = location;
+    return;
+  }
+
+  if (locationKey(location) === currentKey) return;
+  pendingLocation = null;
+  report(location);
+}
+
+/** @internal Resets tracker state between tests. Does not clear the reporter. */
+export function resetScreenTrackerForTests(): void {
+  enabled = false;
+  currentKey = null;
+  pendingLocation = null;
+}

package/src/surfaces/CloseButton.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import { Pressable, StyleSheet, Text } from 'react-native';
+
+export interface CloseButtonProps {
+  onPress: () => void;
+  color: string;
+}
+
+/** Web close control: 24×24 hit target, 8px from the top-trailing corner. Pass muted color from {@link resolveCloseButtonColor}. */
+export function CloseButton({ onPress, color }: CloseButtonProps): React.ReactElement {
+  return (
+    <Pressable
+      testID="userflow-modal-close"
+      accessibilityRole="button"
+      accessibilityLabel="Close"
+      onPress={onPress}
+      style={({ pressed }) => [styles.button, { opacity: pressed ? 0.6 : 1 }]}
+      hitSlop={8}
+    >
+      <Text style={[styles.icon, { color }]}>×</Text>
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  button: {
+    position: 'absolute',
+    top: 8,
+    right: 8,
+    zIndex: 2,
+    width: 24,
+    height: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  icon: {
+    fontSize: 18,
+    fontWeight: '300',
+    lineHeight: 22,
+  },
+});

package/src/surfaces/MadeWithUserflow.tsx

@@ -0,0 +1,103 @@
+import type { CompanyFragment } from '@userflow-tech/protocol';
+import * as React from 'react';
+import { Image, Pressable, StyleSheet, Text, View } from 'react-native';
+
+import { openSafeUrl } from '../content/openSafeUrl';
+
+import logomark from './assets/userflow-logomark.png';
+
+export interface MadeWithUserflowProps {
+  company: Pick<CompanyFragment, 'slug' | 'flowBranding'>;
+  /** Theme main foreground (`fontColor`) — matches web `--userflow-main-foreground-color`. */
+  color: string;
+  /**
+   * Bubble content inset (modal 40 / tooltip 24). Applied as horizontal + bottom
+   * padding so the legend aligns with the step body, matching the modal mockup.
+   */
+  contentPadding: number;
+  /**
+   * When true, horizontal inset comes from the parent ScrollView; only vertical
+   * spacing and bottom inset are applied here (modal body).
+   */
+  embedded?: boolean;
+}
+
+/**
+ * Web "Made with Userflow" attribution (FlowChrome). Shown when the company
+ * has `flowBranding` enabled; opens the Userflow homepage with UTM params.
+ *
+ * Rendered as a card footer (not absolutely pinned to the card corner) so left
+ * and bottom insets match the surface content padding.
+ */
+export function MadeWithUserflow({
+  company,
+  color,
+  contentPadding,
+  embedded = false,
+}: MadeWithUserflowProps): React.ReactElement | null {
+  if (!company.flowBranding) return null;
+
+  const href =
+    `https://userflow.com/?utm_source=made-with-userflow&utm_medium=link&utm_campaign=made-with-userflow-` +
+    company.slug;
+
+  return (
+    <View
+      style={[
+        styles.footer,
+        embedded
+          ? {
+              marginTop: MADE_WITH_USERFLOW_GAP,
+              paddingBottom: contentPadding,
+            }
+          : {
+              paddingHorizontal: contentPadding,
+              paddingBottom: contentPadding,
+            },
+      ]}
+      pointerEvents="box-none"
+    >
+      <Pressable
+        testID="userflow-made-with-userflow"
+        accessibilityRole="link"
+        accessibilityLabel="Made with Userflow"
+        onPress={() => {
+          void openSafeUrl(href);
+        }}
+        style={({ pressed }) => [styles.link, { opacity: pressed ? 0.75 : 0.5 }]}
+        hitSlop={4}
+      >
+        <Image
+          source={logomark}
+          style={[styles.logomark, { tintColor: color }]}
+          accessibilityIgnoresInvertColors
+        />
+        <Text style={[styles.label, { color }]}>Made with Userflow</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+/** Gap between step content/buttons and the branding footer (web spacer height). */
+export const MADE_WITH_USERFLOW_GAP = 16;
+
+const styles = StyleSheet.create({
+  footer: {
+    flexShrink: 0,
+  },
+  link: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    alignSelf: 'flex-start',
+  },
+  logomark: {
+    width: 14,
+    height: 14,
+    marginRight: 6,
+  },
+  label: {
+    fontSize: 12,
+    fontWeight: '500',
+    lineHeight: 14,
+  },
+});