@userflow-tech/react-native 0.4.5 → 0.5.0

package/src/runtime/bannerEngine.ts

@@ -1,4 +1,5 @@
 import { BannerSessionEngine, type UserflowCore } from '@userflow-tech/core';
+import type { EndFlowReasonInput } from '@userflow-tech/protocol';
 
 import { evalJsController } from '../evalJs/evalJsController';
 import { openFlowNavigateUrl } from '../navigation/openFlowNavigateUrl';
@@ -44,8 +45,15 @@ export function resetBannerSessionEngine(): void {
 }
 
 /** Drop the local banner without detaching (preview exit, user switch). */
-export function clearBannerSessionEngineLocalSession(): void {
-  bannerEngine?.clearLocalSession();
+export function clearBannerSessionEngineLocalSession(options?: {
+  rememberDraftForPreviewEnd?: boolean;
+}): void {
+  bannerEngine?.clearLocalSession(options);
+}
+
+/** Best-effort end of a Builder preview banner draft (including after local clear). */
+export async function endDraftBannerSession(): Promise<void> {
+  await bannerEngine?.endDraftBannerSession('USER_CLOSED' as EndFlowReasonInput);
 }
 
 /** Test helper: drop the singleton so the next get recreates it. */

package/src/runtime/bannerFlowSpacer.tsx

@@ -0,0 +1,70 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import * as React from 'react';
+import { View } from 'react-native';
+
+import { bannerEdge } from './bannerPlacement';
+import { useBannerSession } from './useBannerSession';
+
+type SpacerEdge = 'top' | 'bottom';
+
+const heights: Record<SpacerEdge, number> = { top: 0, bottom: 0 };
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+/** @internal */
+export function setBannerFlowSpacerHeight(edge: SpacerEdge, height: number): void {
+  const next = Math.max(0, Math.ceil(height));
+  if (heights[edge] === next) {
+    return;
+  }
+  heights[edge] = next;
+  emit();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getHeight(edge: SpacerEdge): number {
+  return heights[edge];
+}
+
+/**
+ * Reserves layout space when a custom-css WebView banner is painted in the
+ * overlay host but the builder marked it `overlay: false` (push layout).
+ */
+export function BannerWebViewFlowSpacer({
+  engine,
+  edge,
+}: {
+  engine: BannerSessionEngine;
+  edge: SpacerEdge;
+}): React.ReactElement | null {
+  const session = useBannerSession(engine);
+  const height = React.useSyncExternalStore(
+    subscribe,
+    () => getHeight(edge),
+    () => getHeight(edge),
+  );
+
+  if (!session?.version.banner || height <= 0) {
+    return null;
+  }
+  const pinnedEdge = bannerEdge(session.version.banner.embedMode);
+  if (pinnedEdge !== edge) {
+    return null;
+  }
+
+  // Layout-only: the painted banner lives in the overlay host (lower z-index).
+  return (
+    <View pointerEvents="none" testID={`userflow-banner-flow-spacer-${edge}`} style={{ height }} />
+  );
+}

package/src/runtime/flowEngine.ts

@@ -31,6 +31,17 @@ export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
       updateUser: (attributes) => core.updateUser(attributes),
       updateGroup: (attributes, options) => core.updateGroup(attributes, options),
     });
+    flowEngine.on((event) => {
+      if (event.type !== 'sessionChange' || event.session !== null) {
+        return;
+      }
+      // Drop a flow's eval page when the tour ends. A banner WebView reuses the
+      // same controller and must keep its page alive until the banner dismisses.
+      if (evalJsController.getSnapshot().bannerOwnsWebView) {
+        return;
+      }
+      evalJsController.reset();
+    });
     if (endDraftOnArrival) watchForRestoredDraft();
   }
   return flowEngine;

package/src/runtime/previewStart.ts

@@ -0,0 +1,49 @@
+import type { UserflowCore } from '@userflow-tech/core';
+import type { EndFlowReasonInput } from '@userflow-tech/protocol';
+
+import { evalJsController } from '../evalJs/evalJsController';
+
+import {
+  clearBannerSessionEngineLocalSession,
+  endDraftBannerSession,
+  getBannerSessionEngine,
+} from './bannerEngine';
+import {
+  cancelPendingDraftEnd,
+  clearFlowSessionEngineLocalSession,
+  endDraftFlowSession,
+} from './flowEngine';
+
+/**
+ * Drop local tour state and reset eval before a Builder `startFlowWithToken`.
+ *
+ * When a draft banner is still active, end it on the server first. The channel
+ * dedupes an unchanged `SetBannerSession`, so clearing the banner locally
+ * without ending the draft leaves nothing visible on a second preview of the
+ * same banner.
+ */
+export async function prepareForBuilderPreviewStart(core: UserflowCore): Promise<void> {
+  cancelPendingDraftEnd();
+  clearFlowSessionEngineLocalSession();
+  core.setFlowSessionId(null);
+
+  const bannerEngine = getBannerSessionEngine(core);
+  const hasDraftBanner =
+    bannerEngine.getBannerSession()?.draftMode === true ||
+    bannerEngine.getDeferredDraftBannerSessionId() !== null;
+
+  if (hasDraftBanner) {
+    await bannerEngine.endDraftBannerForPreview('USER_CLOSED' as EndFlowReasonInput);
+  } else {
+    clearBannerSessionEngineLocalSession();
+    core.setBannerSessionId(null);
+  }
+
+  evalJsController.reset();
+}
+
+/** End tour and banner Builder drafts on the server (preview exit). */
+export async function endDraftPreviewSessions(): Promise<void> {
+  await endDraftFlowSession();
+  await endDraftBannerSession();
+}

package/src/runtime/pushBannerLayoutContext.tsx

@@ -0,0 +1,121 @@
+import * as React from 'react';
+import type { LayoutChangeEvent } from 'react-native';
+
+export type PushBannerLayoutEdge = 'top' | 'bottom';
+
+interface PushBannerLayoutContextValue {
+  /** Push-layout banner chrome mounted; host safe-area may follow this edge. */
+  register: (edge: PushBannerLayoutEdge, token: string) => void;
+  unregister: (token: string) => void;
+}
+
+const PushBannerLayoutContext = React.createContext<PushBannerLayoutContextValue | null>(null);
+
+function pickEdge(registrations: Map<string, PushBannerLayoutEdge>): PushBannerLayoutEdge | null {
+  let top = false;
+  let bottom = false;
+  for (const edge of registrations.values()) {
+    if (edge === 'top') {
+      top = true;
+    }
+    if (edge === 'bottom') {
+      bottom = true;
+    }
+  }
+  if (top) {
+    return 'top';
+  }
+  if (bottom) {
+    return 'bottom';
+  }
+  return null;
+}
+
+export function PushBannerLayoutProvider({
+  children,
+  onActiveEdgeChange,
+}: {
+  children: React.ReactNode;
+  onActiveEdgeChange: (edge: PushBannerLayoutEdge | null) => void;
+}): React.ReactElement {
+  const registrations = React.useRef(new Map<string, PushBannerLayoutEdge>());
+  const onActiveEdgeChangeRef = React.useRef(onActiveEdgeChange);
+  onActiveEdgeChangeRef.current = onActiveEdgeChange;
+
+  const sync = React.useCallback(() => {
+    onActiveEdgeChangeRef.current(pickEdge(registrations.current));
+  }, []);
+
+  const value = React.useMemo<PushBannerLayoutContextValue>(
+    () => ({
+      register: (edge, token) => {
+        registrations.current.set(token, edge);
+        sync();
+      },
+      unregister: (token) => {
+        if (registrations.current.delete(token)) {
+          sync();
+        }
+      },
+    }),
+    [sync],
+  );
+
+  React.useLayoutEffect(() => {
+    sync();
+  }, [sync]);
+
+  return (
+    <PushBannerLayoutContext.Provider value={value}>{children}</PushBannerLayoutContext.Provider>
+  );
+}
+
+/** @internal */
+export function usePushBannerLayoutRegistration(
+  edge: PushBannerLayoutEdge | null | undefined,
+  sessionId: string | undefined,
+): void {
+  const ctx = React.useContext(PushBannerLayoutContext);
+  React.useLayoutEffect(() => {
+    if (!ctx || !edge || !sessionId) {
+      return;
+    }
+    const token = `${sessionId}:${edge}`;
+    ctx.register(edge, token);
+    return () => {
+      ctx.unregister(token);
+    };
+  }, [ctx, edge, sessionId]);
+}
+
+/**
+ * Clears the host top/bottom safe-area override only after push-layout chrome
+ * has laid out, so a session without visible chrome cannot leave a white strip.
+ *
+ * @internal
+ */
+export function usePushBannerHostInsetRegistration(
+  edge: PushBannerLayoutEdge | null | undefined,
+  sessionId: string,
+  enabled: boolean,
+): (event: LayoutChangeEvent) => void {
+  const [laidOut, setLaidOut] = React.useState(false);
+
+  React.useEffect(() => {
+    setLaidOut(false);
+  }, [edge, enabled]);
+
+  usePushBannerLayoutRegistration(enabled && laidOut && edge ? edge : null, sessionId);
+
+  return React.useCallback(
+    (event: LayoutChangeEvent) => {
+      if (!enabled || !edge) {
+        return;
+      }
+      if (event.nativeEvent.layout.height > 0) {
+        setLaidOut(true);
+      }
+    },
+    [edge, enabled],
+  );
+}

package/src/screenTracker.ts

@@ -24,6 +24,17 @@ function locationKey(location: ClientLocationUpdate): string {
   return 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
 }
 
+/**
+ * The screen id stored on an AUTO envelope (`path` for Expo Router, `screen`
+ * otherwise). Missing or blank locations are `'unknown'`, the same sentinel
+ * the element picker writes when it has not seen a screen yet.
+ */
+export function screenIdFromLocation(location: ClientLocationUpdate | null | undefined): string {
+  if (!location) return 'unknown';
+  const id = 'path' in location ? location.path : location.screen;
+  return id || 'unknown';
+}
+
 /** Event attributes for `screen_viewed`, or `null` when the location has no identity. */
 export function screenViewedAttributes(
   location: ClientLocationUpdate,

package/src/surfaces/BannerBar.tsx

@@ -11,14 +11,18 @@ 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 { usePushBannerHostInsetRegistration } from '../runtime/pushBannerLayoutContext';
 
 import {
   BANNER_CLOSE_SLOT_SIZE,
   BANNER_ROOT_PADDING,
+  bannerBarRootStyle,
   bannerFrameStyle,
   bannerInnerStyle,
+  bannerPushLayoutChrome,
   resolveBannerBarBorderRadius,
 } from './bannerBarLayout';
+import { useUserflowSafeAreaInsets } from './safeArea';
 import {
   BANNER_BUTTON_GAP,
   BANNER_CLOSE_BORDER_RADIUS,
@@ -28,6 +32,8 @@ import { resolveBannerBackgroundColor, resolveBannerForegroundColor } from './re
 
 export interface BannerBarProps {
   session: BannerSessionFragment;
+  pushLayoutEdge?: 'top' | 'bottom' | null;
+  overlaySafeEdge?: 'top' | 'bottom' | null;
   onActions: (actions: FlowActionFragment[]) => void;
   onDismiss: (endReason: EndFlowReasonInput) => void;
 }
@@ -38,6 +44,8 @@ export interface BannerBarProps {
  */
 export function BannerBar({
   session,
+  pushLayoutEdge = null,
+  overlaySafeEdge = null,
   onActions,
   onDismiss,
 }: BannerBarProps): React.ReactElement | null {
@@ -50,10 +58,20 @@ export function BannerBar({
     [theme, backgroundColor, foregroundColor],
   );
   const lookupAttribute = React.useMemo(() => genSessionDataLookup(session.data), [session.data]);
-  const opacity = React.useRef(new Animated.Value(banner?.animate ? 0 : 1)).current;
+  const insets = useUserflowSafeAreaInsets();
+  const overlay = banner?.overlay !== false;
+  const hostInsetEdge = !overlay && pushLayoutEdge ? pushLayoutEdge : null;
+  const safeAreaEdge = hostInsetEdge ?? overlaySafeEdge ?? null;
+  const onPushChromeLayout = usePushBannerHostInsetRegistration(
+    hostInsetEdge,
+    session.id,
+    hostInsetEdge != null,
+  );
+  const fadeIn = banner?.animate === true && hostInsetEdge == null;
+  const opacity = React.useRef(new Animated.Value(fadeIn ? 0 : 1)).current;
 
   React.useEffect(() => {
-    if (!banner?.animate) {
+    if (!fadeIn) {
       opacity.setValue(1);
       return;
     }
@@ -67,73 +85,93 @@ export function BannerBar({
     return () => {
       animation.stop();
     };
-  }, [banner?.animate, opacity, session.id]);
+  }, [fadeIn, opacity, session.id]);
 
   if (!banner) return null;
 
-  const overlay = banner.overlay !== false;
   const frameStyle = bannerFrameStyle(banner);
+  const rootStyle = bannerBarRootStyle(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);
+  const insetChrome = safeAreaEdge
+    ? bannerPushLayoutChrome(safeAreaEdge, insets, backgroundColor)
+    : null;
+  const insetChromeOutsideFade = insetChrome != null && fadeIn;
 
-  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={[]}
+  const bar = (
+    <View
+      testID="userflow-banner"
+      style={[
+        styles.root,
+        rootStyle,
+        { 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}
-                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>
+        ) : 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>
+  );
+
+  const animatedBar = (
+    <Animated.View
+      onLayout={hostInsetEdge ? onPushChromeLayout : undefined}
+      style={[
+        { opacity },
+        overlay ? bannerOverlayShadowStyle(overlayEdge) : null,
+        insetChromeOutsideFade ? null : insetChrome,
+      ]}
+    >
+      {bar}
+    </Animated.View>
+  );
+
+  return (
+    <View testID="userflow-banner-frame" style={frameStyle}>
+      {insetChromeOutsideFade ? <View style={insetChrome}>{animatedBar}</View> : animatedBar}
     </View>
   );
 }

package/src/surfaces/BannerSurface.tsx

@@ -15,6 +15,10 @@ import { bannerNeedsWebView } from './bannerWebView/bannerNeedsWebView';
 
 export interface BannerSurfaceProps {
   session: BannerSessionFragment;
+  /** When set, the banner pushes host layout and fills the safe-area inset on this edge. */
+  pushLayoutEdge?: 'top' | 'bottom' | null;
+  /** Overlay host edge — paints safe-area padding without pushing layout. */
+  overlaySafeEdge?: 'top' | 'bottom' | null;
   onActions: (actions: FlowActionFragment[]) => void | Promise<void>;
   onDismiss: (endReason: EndFlowReasonInput) => void;
 }
@@ -27,6 +31,8 @@ let warnedMissingWebView = false;
  */
 export function BannerSurface({
   session,
+  pushLayoutEdge = null,
+  overlaySafeEdge = null,
   onActions,
   onDismiss,
 }: BannerSurfaceProps): React.ReactElement | null {
@@ -35,6 +41,34 @@ export function BannerSurface({
   const needsWebView = banner != null && bannerNeedsWebView(banner, theme);
   const webView = needsWebView ? getEvalJsWebView() : null;
 
+  React.useEffect(() => {
+    if (!banner || !__DEV__) {
+      return;
+    }
+    // eslint-disable-next-line no-console -- intentional development diagnostic
+    console.log('[Userflow] banner shown', {
+      flowId: session.flow.id,
+      flowName: session.flow.name,
+      bannerSessionId: session.id,
+      versionId: session.version.id,
+      embedMode: banner.embedMode,
+      overlay: banner.overlay !== false,
+      webView: needsWebView,
+      pushLayoutEdge: pushLayoutEdge ?? null,
+      overlaySafeEdge: overlaySafeEdge ?? null,
+      hostAsOverlay: banner.overlay !== false || needsWebView,
+    });
+  }, [
+    banner,
+    needsWebView,
+    overlaySafeEdge,
+    pushLayoutEdge,
+    session.flow.id,
+    session.flow.name,
+    session.id,
+    session.version.id,
+  ]);
+
   React.useLayoutEffect(() => {
     if (!needsWebView || !webView) {
       return;
@@ -69,13 +103,35 @@ export function BannerSurface({
           );
         }
       }
-      return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+      return (
+        <BannerBar
+          session={session}
+          pushLayoutEdge={pushLayoutEdge}
+          overlaySafeEdge={overlaySafeEdge}
+          onActions={onActions}
+          onDismiss={onDismiss}
+        />
+      );
     }
     return (
-      <BannerWebViewBar session={session} onActions={onActions} onDismiss={dismissWebViewBanner} />
+      <BannerWebViewBar
+        session={session}
+        pushLayoutEdge={pushLayoutEdge}
+        overlaySafeEdge={overlaySafeEdge}
+        onActions={onActions}
+        onDismiss={dismissWebViewBanner}
+      />
     );
   }
-  return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
+  return (
+    <BannerBar
+      session={session}
+      pushLayoutEdge={pushLayoutEdge}
+      overlaySafeEdge={overlaySafeEdge}
+      onActions={onActions}
+      onDismiss={onDismiss}
+    />
+  );
 }
 
 /** @internal */