@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/runtime/useBannerSession.ts

@@ -0,0 +1,35 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import type { BannerSessionFragment } from '@userflow-tech/protocol';
+import * as React from 'react';
+
+import { isolateSync } from './isolateCall';
+
+/** Subscribe to the active banner. A throw while reading the session stays off the host tree. */
+export function useBannerSession(engine: BannerSessionEngine | null): BannerSessionFragment | null {
+  const [session, setSession] = React.useState<BannerSessionFragment | null>(() => {
+    if (!engine) return null;
+    try {
+      return engine.getBannerSession();
+    } catch {
+      return null;
+    }
+  });
+
+  React.useEffect(() => {
+    if (!engine) {
+      setSession(null);
+      return;
+    }
+    const read = () => {
+      isolateSync('banner-session', () => {
+        setSession(engine.getBannerSession());
+      });
+    };
+    read();
+    return engine.on(() => {
+      read();
+    });
+  }, [engine]);
+
+  return session;
+}

package/src/runtime/useFlowSessionState.ts

@@ -12,6 +12,7 @@ export interface FlowSessionState {
   session: FlowSessionFragment | null;
   currentStepId: string | null;
   currentStep: FlowStepFragment | null;
+  stepShowNonce: number;
 }
 
 /** Subscribe to a {@link FlowSessionEngine} and derive React-friendly session/step state. */
@@ -32,5 +33,6 @@ export function useFlowSessionState(engine: FlowSessionEngine): FlowSessionState
     session: state.session,
     currentStepId: state.currentStepId,
     currentStep: resolveCurrentStep(state.session, state.currentStepId),
+    stepShowNonce: state.stepShowNonce,
   };
 }

package/src/screenTracker.ts

@@ -1,18 +1,38 @@
 import type { ClientLocationUpdate } from '@userflow-tech/protocol';
 
+/** Predefined mobile screen-view event (web analogue: `page_viewed`). */
+export const SCREEN_VIEWED_EVENT = 'screen_viewed';
+
 /** Called when a new location is accepted (after enable + dedupe). */
 export type ScreenChangeReporter = (location: ClientLocationUpdate) => void;
 
+export type HandleScreenChangeOptions = {
+  /** Re-run the reporter even when the location matches the last report. */
+  force?: boolean;
+};
+
 let enabled = false;
 let currentKey: string | null = null;
+/** Last accepted (or pending) location — used by the in-app element picker. */
+let currentLocation: ClientLocationUpdate | null = null;
 /** Latest location seen while tracking was disabled; flushed on enable. */
 let pendingLocation: ClientLocationUpdate | null = null;
 let reporter: ScreenChangeReporter | null = null;
+const screenListeners = new Set<ScreenChangeReporter>();
 
 function locationKey(location: ClientLocationUpdate): string {
   return 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
 }
 
+/** Event attributes for `screen_viewed`, or `null` when the location has no identity. */
+export function screenViewedAttributes(
+  location: ClientLocationUpdate,
+): { screen_name: string } | null {
+  const screenName = 'path' in location ? location.path : location.screen;
+  if (!screenName) return null;
+  return { screen_name: screenName };
+}
+
 /**
  * Registers the callback invoked when the active screen/path changes.
  * The React Native facade wires this to `UserflowCore.updateScreen`.
@@ -21,9 +41,42 @@ export function setScreenChangeReporter(next: ScreenChangeReporter | null): void
   reporter = next;
 }
 
+/**
+ * Observe accepted screen changes (Evaluate JavaScript context, and similar).
+ * Fires immediately with the latest known location when one exists.
+ * A throwing listener does not block the reporter or the other listeners.
+ */
+export function subscribeScreenLocation(listener: ScreenChangeReporter): () => void {
+  screenListeners.add(listener);
+  const current = getCurrentScreenLocation();
+  if (current) {
+    try {
+      listener(current);
+    } catch {
+      // Listener failures must not break screen tracking.
+    }
+  }
+  return () => {
+    screenListeners.delete(listener);
+  };
+}
+
 function report(location: ClientLocationUpdate): void {
   currentKey = locationKey(location);
+  currentLocation = location;
   reporter?.(location);
+  for (const listener of screenListeners) {
+    try {
+      listener(location);
+    } catch {
+      // Listener failures must not break screen tracking.
+    }
+  }
+}
+
+/** Latest screen/path the SDK has recorded, or `null` before the first report. */
+export function getCurrentScreenLocation(): ClientLocationUpdate | null {
+  return currentLocation ?? pendingLocation;
 }
 
 /** Activates screen-change tracking after a successful {@link Userflow.init}. */
@@ -42,22 +95,28 @@ export function enableScreenTracking(): void {
 export function disableScreenTracking(): void {
   enabled = false;
   currentKey = null;
+  currentLocation = 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.
+ * Duplicate consecutive locations are ignored unless `{ force: true }` (used
+ * after overlay dismiss, AppState resume, and first identify). On change,
+ * notifies the reporter so the SDK can push `UpdateClientContext` and
+ * `screen_viewed`.
  *
  * 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`
+ * - Expo Router: `{ path: "/settings/billing" }` → wire `screenName`
  * - React Navigation / manual: `{ screen: "BillingSettings" }` → wire `screenName`
  */
-export function handleScreenChange(location: ClientLocationUpdate | undefined): void {
+export function handleScreenChange(
+  location: ClientLocationUpdate | undefined,
+  options?: HandleScreenChangeOptions,
+): void {
   if (!location) return;
   if ('path' in location) {
     if (!location.path) return;
@@ -70,14 +129,23 @@ export function handleScreenChange(location: ClientLocationUpdate | undefined):
     return;
   }
 
-  if (locationKey(location) === currentKey) return;
+  if (!options?.force && locationKey(location) === currentKey) return;
   pendingLocation = null;
   report(location);
 }
 
+/** Re-report the current screen, bypassing consecutive dedupe (resume / identify). */
+export function reportCurrentScreen(): void {
+  const location = getCurrentScreenLocation();
+  if (!location) return;
+  handleScreenChange(location, { force: true });
+}
+
 /** @internal Resets tracker state between tests. Does not clear the reporter. */
 export function resetScreenTrackerForTests(): void {
   enabled = false;
+  currentLocation = null;
   currentKey = null;
   pendingLocation = null;
+  screenListeners.clear();
 }

package/src/surfaces/BannerBar.tsx

@@ -0,0 +1,176 @@
+import { genSessionDataLookup } from '@userflow-tech/core';
+import type { FlowActionFragment } from '@userflow-tech/protocol';
+import {
+  BannerEmbedMode,
+  EndFlowReasonInput,
+  type BannerSessionFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+import { Animated, Pressable, StyleSheet, Text, View } from 'react-native';
+
+import { BannerStepButton } from '../content/BannerStepButton';
+import { RichContentRenderer } from '../content/RichContentRenderer';
+import { mixThemeColors } from '../content/themeColor';
+
+import {
+  BANNER_CLOSE_SLOT_SIZE,
+  BANNER_ROOT_PADDING,
+  bannerFrameStyle,
+  bannerInnerStyle,
+  resolveBannerBarBorderRadius,
+} from './bannerBarLayout';
+import {
+  BANNER_BUTTON_GAP,
+  BANNER_CLOSE_BORDER_RADIUS,
+  bannerOverlayShadowStyle,
+} from './bannerBarTokens';
+import { resolveBannerBackgroundColor, resolveBannerForegroundColor } from './resolveBannerTheme';
+
+export interface BannerBarProps {
+  session: BannerSessionFragment;
+  onActions: (actions: FlowActionFragment[]) => void;
+  onDismiss: (endReason: EndFlowReasonInput) => void;
+}
+
+/**
+ * Banner chrome. An overlay parent floats this over the host. A flow parent
+ * keeps it in layout so the app is pushed instead of covered.
+ */
+export function BannerBar({
+  session,
+  onActions,
+  onDismiss,
+}: BannerBarProps): React.ReactElement | null {
+  const banner = session.version.banner;
+  const theme = session.version.theme;
+  const backgroundColor = resolveBannerBackgroundColor(theme);
+  const foregroundColor = resolveBannerForegroundColor(theme);
+  const bannerTheme = React.useMemo(
+    () => ({ ...theme, backgroundColor, fontColor: foregroundColor }),
+    [theme, backgroundColor, foregroundColor],
+  );
+  const lookupAttribute = React.useMemo(() => genSessionDataLookup(session.data), [session.data]);
+  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+
+  React.useEffect(() => {
+    if (!banner?.animate) {
+      opacity.setValue(1);
+      return;
+    }
+    opacity.setValue(0);
+    const animation = Animated.timing(opacity, {
+      toValue: 1,
+      duration: 200,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => {
+      animation.stop();
+    };
+  }, [banner?.animate, opacity, session.id]);
+
+  if (!banner) return null;
+
+  const overlay = banner.overlay !== false;
+  const frameStyle = bannerFrameStyle(banner);
+  const innerStyle = bannerInnerStyle(banner);
+  const closePressedBackground = mixThemeColors(backgroundColor, foregroundColor, 0.12);
+  const overlayEdge = banner.embedMode === BannerEmbedMode.BODY_LAST ? 'bottom' : 'top';
+  const barRadius = resolveBannerBarBorderRadius(banner);
+
+  return (
+    <View testID="userflow-banner-frame" style={frameStyle}>
+      <Animated.View style={[{ opacity }, overlay ? bannerOverlayShadowStyle(overlayEdge) : null]}>
+        <View
+          testID="userflow-banner"
+          style={[
+            styles.root,
+            { backgroundColor },
+            barRadius != null ? { borderRadius: barRadius, overflow: 'hidden' as const } : null,
+          ]}
+        >
+          <View style={styles.startSpacer} />
+          <View style={innerStyle}>
+            <View style={styles.content}>
+              <RichContentRenderer
+                content={banner.content}
+                buttons={[]}
+                theme={bannerTheme}
+                sessionData={session.data}
+                lookupAttribute={lookupAttribute}
+                onActions={onActions}
+              />
+            </View>
+            {banner.buttons.length > 0 ? (
+              <View style={styles.buttons}>
+                {banner.buttons.map((button) => (
+                  <BannerStepButton
+                    key={button.id}
+                    button={button}
+                    theme={bannerTheme}
+                    sessionData={session.data}
+                    onActions={onActions}
+                  />
+                ))}
+              </View>
+            ) : null}
+          </View>
+          {session.version.closeDisabled ? (
+            <View style={styles.startSpacer} />
+          ) : (
+            <Pressable
+              testID="userflow-banner-dismiss"
+              accessibilityRole="button"
+              accessibilityLabel="Dismiss"
+              hitSlop={8}
+              onPress={() => onDismiss(EndFlowReasonInput.USER_CLOSED)}
+              style={({ pressed }) => [
+                styles.close,
+                pressed ? { backgroundColor: closePressedBackground } : null,
+              ]}
+            >
+              <Text style={[styles.dismissIcon, { color: foregroundColor }]}>×</Text>
+            </Pressable>
+          )}
+        </View>
+      </Animated.View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    padding: BANNER_ROOT_PADDING,
+  },
+  startSpacer: {
+    flexGrow: 1,
+    flexShrink: 1,
+    maxWidth: BANNER_CLOSE_SLOT_SIZE,
+    height: BANNER_CLOSE_SLOT_SIZE,
+  },
+  content: {
+    flexShrink: 1,
+    minWidth: 0,
+  },
+  buttons: {
+    flexDirection: 'row',
+    flexWrap: 'nowrap',
+    alignItems: 'center',
+    gap: BANNER_BUTTON_GAP,
+  },
+  close: {
+    width: BANNER_CLOSE_SLOT_SIZE,
+    height: BANNER_CLOSE_SLOT_SIZE,
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    borderRadius: BANNER_CLOSE_BORDER_RADIUS,
+  },
+  dismissIcon: {
+    fontSize: 18,
+    lineHeight: 22,
+    fontWeight: '300',
+  },
+});

package/src/surfaces/BannerSurface.tsx

@@ -0,0 +1,82 @@
+import type {
+  BannerSessionFragment,
+  EndFlowReasonInput,
+  FlowActionFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+
+import { evalJsController } from '../evalJs/evalJsController';
+import { getEvalJsWebView } from '../evalJs/getWebView';
+
+import { BannerBar } from './BannerBar';
+import { BannerWebViewBar } from './bannerWebView/BannerWebViewBar';
+import { clearBannerAutoRunEvalSession } from './bannerWebView/bannerAutoRunSession';
+import { bannerNeedsWebView } from './bannerWebView/bannerNeedsWebView';
+
+export interface BannerSurfaceProps {
+  session: BannerSessionFragment;
+  onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
+  onDismiss: (endReason: EndFlowReasonInput) => void;
+}
+
+let warnedMissingWebView = false;
+
+/**
+ * Native banner bar, or a WebView when a button runs Evaluate JavaScript or the
+ * theme has published custom CSS (same CDN stylesheet as userflow.js iframes).
+ */
+export function BannerSurface({
+  session,
+  onActions,
+  onDismiss,
+}: BannerSurfaceProps): React.ReactElement | null {
+  const banner = session.version.banner;
+  const theme = session.version.theme;
+  const needsWebView = banner != null && bannerNeedsWebView(banner, theme);
+  const webView = needsWebView ? getEvalJsWebView() : null;
+
+  React.useLayoutEffect(() => {
+    if (!needsWebView || !webView) {
+      return;
+    }
+    evalJsController.setBannerOwnsWebView(true);
+    return () => {
+      evalJsController.setBannerOwnsWebView(false);
+    };
+  }, [needsWebView, webView, session.id]);
+
+  const dismissWebViewBanner = React.useCallback(
+    (endReason: EndFlowReasonInput) => {
+      clearBannerAutoRunEvalSession(session.id);
+      evalJsController.reset();
+      onDismiss(endReason);
+    },
+    [onDismiss, session.id],
+  );
+
+  if (!banner) {
+    return null;
+  }
+  if (needsWebView) {
+    if (!webView) {
+      if (!warnedMissingWebView) {
+        warnedMissingWebView = true;
+        console.warn(
+          'Userflow: WebView banner requires react-native-webview in the native binary. ' +
+            'Add it to your app (e.g. npx expo install react-native-webview), run pod install under ios/, ' +
+            'then rebuild with expo run:ios (not Expo Go). Falling back to the native banner bar.',
+        );
+      }
+      return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+    }
+    return (
+      <BannerWebViewBar session={session} onActions={onActions} onDismiss={dismissWebViewBanner} />
+    );
+  }
+  return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+}
+
+/** @internal */
+export function resetBannerSurfaceWarningsForTests(): void {
+  warnedMissingWebView = false;
+}

package/src/surfaces/CardFade.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { Animated } from 'react-native';
+
+import { useCardOpacity } from './cardTransition';
+
+export type CardFadeProps = React.ComponentProps<typeof Animated.View>;
+
+/**
+ * Card chrome root that fades itself through step transitions.
+ *
+ * This has to wrap the card view itself, not sit higher up in a surface: the
+ * fade starts from this component's mount, and a tooltip's surface renders long
+ * before its card does.
+ */
+export function CardFade({ style, ...rest }: CardFadeProps): React.ReactElement {
+  const opacity = useCardOpacity();
+  return <Animated.View {...rest} style={opacity ? [style, { opacity }] : style} />;
+}

package/src/surfaces/CloseButton.tsx

@@ -1,20 +1,32 @@
 import * as React from 'react';
 import { Pressable, StyleSheet, Text } from 'react-native';
 
+export const CLOSE_BUTTON_SIZE = 24;
+export const CLOSE_BUTTON_INSET = 8;
+
 export interface CloseButtonProps {
   onPress: () => void;
   color: string;
+  /** Distance from the top of the positioned parent. Default {@link CLOSE_BUTTON_INSET}. */
+  top?: number;
+  /** Distance from the trailing edge. Default {@link CLOSE_BUTTON_INSET}. */
+  right?: number;
 }
 
-/** 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 {
+/** Web close control: 24×24 hit target. Pass muted color from {@link resolveCloseButtonColor}. */
+export function CloseButton({
+  onPress,
+  color,
+  top = CLOSE_BUTTON_INSET,
+  right = CLOSE_BUTTON_INSET,
+}: CloseButtonProps): React.ReactElement {
   return (
     <Pressable
       testID="userflow-modal-close"
       accessibilityRole="button"
       accessibilityLabel="Close"
       onPress={onPress}
-      style={({ pressed }) => [styles.button, { opacity: pressed ? 0.6 : 1 }]}
+      style={({ pressed }) => [styles.button, { top, right, opacity: pressed ? 0.6 : 1 }]}
       hitSlop={8}
     >
       <Text style={[styles.icon, { color }]}>×</Text>
@@ -25,11 +37,9 @@ export function CloseButton({ onPress, color }: CloseButtonProps): React.ReactEl
 const styles = StyleSheet.create({
   button: {
     position: 'absolute',
-    top: 8,
-    right: 8,
     zIndex: 2,
-    width: 24,
-    height: 24,
+    width: CLOSE_BUTTON_SIZE,
+    height: CLOSE_BUTTON_SIZE,
     alignItems: 'center',
     justifyContent: 'center',
   },

package/src/surfaces/MadeWithUserflow.tsx

@@ -11,13 +11,14 @@ export interface MadeWithUserflowProps {
   /** 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.
+   * Bubble content inset (modal 24 / tooltip 24). Only used when `embedded`,
+   * to pull the legend back out to the card edge.
    */
   contentPadding: number;
   /**
-   * When true, horizontal inset comes from the parent ScrollView; only vertical
-   * spacing and bottom inset are applied here (modal body).
+   * When true, the footer sits inside a ScrollView whose start padding is
+   * `contentPadding` and owns the gap above itself (modal body). Otherwise the
+   * parent supplies {@link MADE_WITH_USERFLOW_GAP} and the footer spans the card.
    */
   embedded?: boolean;
 }
@@ -26,8 +27,9 @@ export interface MadeWithUserflowProps {
  * 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.
+ * Sits in the card corner (Figma: 8pt from the start and bottom edges) rather
+ * than on the content inset. Rendered in flow instead of absolutely so a
+ * scaled-up label pushes the card taller instead of overlapping the body.
  */
 export function MadeWithUserflow({
   company,
@@ -48,11 +50,10 @@ export function MadeWithUserflow({
         embedded
           ? {
               marginTop: MADE_WITH_USERFLOW_GAP,
-              paddingBottom: contentPadding,
+              marginStart: MADE_WITH_USERFLOW_INSET - contentPadding,
             }
           : {
-              paddingHorizontal: contentPadding,
-              paddingBottom: contentPadding,
+              paddingStart: MADE_WITH_USERFLOW_INSET,
             },
       ]}
       pointerEvents="box-none"
@@ -81,9 +82,13 @@ export function MadeWithUserflow({
 /** Gap between step content/buttons and the branding footer (web spacer height). */
 export const MADE_WITH_USERFLOW_GAP = 16;
 
+/** Legend offset from the card's start and bottom edges. */
+export const MADE_WITH_USERFLOW_INSET = 8;
+
 const styles = StyleSheet.create({
   footer: {
     flexShrink: 0,
+    paddingBottom: MADE_WITH_USERFLOW_INSET,
   },
   link: {
     flexDirection: 'row',
@@ -98,6 +103,6 @@ const styles = StyleSheet.create({
   label: {
     fontSize: 12,
     fontWeight: '500',
-    lineHeight: 14,
+    lineHeight: 16,
   },
 });