@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/pairing/resolvePreviewChrome.ts

@@ -0,0 +1,57 @@
+import type { PairingEngineState } from '@userflow-tech/core';
+
+import type { ChromeTopBarTone } from '../authoring/chrome/ChromeTopBar';
+
+export type PreviewChrome =
+  | { visible: false }
+  | { visible: true; tone: ChromeTopBarTone; label: string; numberOfLines: number };
+
+function isBannerVisible(state: PairingEngineState): boolean {
+  if (!state.previewActive && state.status === 'idle') return false;
+  if (
+    !state.previewActive &&
+    state.status !== 'token_expired' &&
+    state.status !== 'device_already_paired' &&
+    state.status !== 'error'
+  ) {
+    return false;
+  }
+  return true;
+}
+
+function shown(
+  tone: ChromeTopBarTone,
+  label: string,
+  numberOfLines = 1,
+): Extract<PreviewChrome, { visible: true }> {
+  return { visible: true, tone, label, numberOfLines };
+}
+
+/**
+ * Maps pairing-engine state onto the preview top-bar chrome.
+ * Pure: no React, so the nine-case table can be asserted without a renderer.
+ */
+export function resolvePreviewChrome(state: PairingEngineState): PreviewChrome {
+  if (!isBannerVisible(state)) return { visible: false };
+
+  switch (state.status) {
+    case 'connecting':
+      return shown('default', 'Connecting to Builder…');
+    case 'reconnecting':
+      return shown('default', 'Reconnecting…');
+    case 'token_expired':
+      return shown('error', 'Pairing ended - rescan to continue', 2);
+    case 'device_already_paired':
+      return shown('error', 'Another device is already paired', 2);
+    case 'error':
+      if (state.pairingId === null) {
+        return shown('error', 'Preview unavailable');
+      }
+      return shown('error', 'Pairing ended - rescan to continue', 2);
+    default:
+      if (state.awaitingStartCondition) {
+        return shown('default', 'Waiting for auto-start condition…');
+      }
+      return shown('default', 'Preview mode');
+  }
+}

package/src/pairing/tokenStorage.ts

@@ -1,14 +1,29 @@
 /**
- * Persist the pairing JWT for reconnect within the current app session.
- * Cleared on SDK init / exit preview / app restart (pairing exits on restart).
+ * Persist the pairing JWT so a relaunch can resume Builder pairing until the
+ * token expires or preview is exited. Resume requires `expo-secure-store`;
+ * the in-memory fallback does not survive a process restart.
  */
 
-const STORAGE_KEY = 'userflow:pairingToken';
+import type { PairingPurpose } from '@userflow-tech/core';
+
+import { parsePairingPurpose } from './deepLink';
+
+// SecureStore rejects keys outside [A-Za-z0-9._-], so no `userflow:` prefix here.
+export const PAIRING_TOKEN_STORAGE_KEY = 'userflow.pairingToken';
+export const PAIRING_PURPOSE_STORAGE_KEY = 'userflow.pairingPurpose';
 
 export interface PairingTokenStore {
   get(): Promise<string | null>;
   set(token: string): Promise<void>;
+  /** Clears the token and its purpose. */
   clear(): Promise<void>;
+  /**
+   * Purpose of the link that wrote the token, so a resume keeps the same
+   * preview chrome. Optional so custom stores keep working; a store without
+   * it resumes with no purpose.
+   */
+  getPurpose?(): Promise<PairingPurpose | null>;
+  setPurpose?(purpose: PairingPurpose | null): Promise<void>;
 }
 
 type SecureStoreModule = {
@@ -17,19 +32,44 @@ type SecureStoreModule = {
   deleteItemAsync(key: string): Promise<void>;
 };
 
+let cachedSecureStore: SecureStoreModule | null | undefined;
+
+/** Expo modules must be installed natively — not just the JS package. */
+function isExpoModulesRuntimeAvailable(): boolean {
+  const expo = (globalThis as { expo?: { EventEmitter?: unknown } }).expo;
+  return typeof expo?.EventEmitter === 'function';
+}
+
 function tryLoadExpoSecureStore(): SecureStoreModule | null {
+  if (cachedSecureStore !== undefined) return cachedSecureStore;
+
+  if (typeof require !== 'function' || !isExpoModulesRuntimeAvailable()) {
+    cachedSecureStore = null;
+    return cachedSecureStore;
+  }
+
   try {
     // Optional peer — absent in bare RN without expo-secure-store.
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
-    return require('expo-secure-store') as SecureStoreModule;
+    cachedSecureStore = require('expo-secure-store') as SecureStoreModule;
   } catch {
-    return null;
+    cachedSecureStore = null;
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
+      console.warn(
+        '[Userflow] Optional peer expo-secure-store is unavailable; ' +
+          'pairing JWT persistence falls back to in-memory storage.',
+      );
+    }
   }
+
+  return cachedSecureStore;
 }
 
 /** In-memory store used when SecureStore is unavailable (and in tests). */
 export function createMemoryPairingTokenStore(): PairingTokenStore {
   let value: string | null = null;
+  let purposeValue: PairingPurpose | null = null;
   return {
     async get() {
       return value;
@@ -39,6 +79,13 @@ export function createMemoryPairingTokenStore(): PairingTokenStore {
     },
     async clear() {
       value = null;
+      purposeValue = null;
+    },
+    async getPurpose() {
+      return purposeValue;
+    },
+    async setPurpose(purpose: PairingPurpose | null) {
+      purposeValue = purpose;
     },
   };
 }
@@ -53,24 +100,59 @@ export function createPairingTokenStore(): PairingTokenStore {
   return {
     async get() {
       try {
-        return await secure.getItemAsync(STORAGE_KEY);
+        return await secure.getItemAsync(PAIRING_TOKEN_STORAGE_KEY);
       } catch {
         return null;
       }
     },
     async set(token: string) {
       try {
-        await secure.setItemAsync(STORAGE_KEY, token);
-      } catch {
+        await secure.setItemAsync(PAIRING_TOKEN_STORAGE_KEY, token);
+      } catch (error) {
         // Best-effort; reconnect still works from in-memory PairingEngine token.
+        if (__DEV__) {
+          // eslint-disable-next-line no-console -- intentional persistence diagnostic
+          console.warn(
+            '[Userflow] Could not save the pairing token, so preview will not resume after a relaunch:',
+            error instanceof Error ? error.message : String(error),
+          );
+        }
       }
     },
     async clear() {
       try {
-        await secure.deleteItemAsync(STORAGE_KEY);
+        await secure.deleteItemAsync(PAIRING_TOKEN_STORAGE_KEY);
       } catch {
         // ignore
       }
+      try {
+        await secure.deleteItemAsync(PAIRING_PURPOSE_STORAGE_KEY);
+      } catch {
+        // ignore
+      }
+    },
+    async getPurpose() {
+      try {
+        return parsePairingPurpose(await secure.getItemAsync(PAIRING_PURPOSE_STORAGE_KEY));
+      } catch {
+        return null;
+      }
+    },
+    async setPurpose(purpose: PairingPurpose | null) {
+      try {
+        if (purpose) {
+          await secure.setItemAsync(PAIRING_PURPOSE_STORAGE_KEY, purpose);
+        } else {
+          await secure.deleteItemAsync(PAIRING_PURPOSE_STORAGE_KEY);
+        }
+      } catch {
+        // Best-effort; a resume without it falls back to the default reveal.
+      }
     },
   };
 }
+
+/** @internal Resets module cache between tests. */
+export function resetPairingTokenStoreCacheForTests(): void {
+  cachedSecureStore = undefined;
+}

package/src/pairing/usePairingState.ts

@@ -12,6 +12,10 @@ const IDLE: PairingEngineState = {
   lastError: null,
   needsRescan: false,
   awaitingStartCondition: false,
+  canRestartPreview: false,
+  previewRestartGeneration: 0,
+  pairingSessionGeneration: 0,
+  previewStartGeneration: 0,
 };
 
 /** Subscribe to Builder pairing / preview-mode state (dev builds only). */

package/src/pairing/usePreviewBarHold.ts

@@ -0,0 +1,160 @@
+import type { PairingEngineState, PairingPurpose } from '@userflow-tech/core';
+import * as React from 'react';
+
+import { resolvePreviewChrome } from './resolvePreviewChrome';
+
+/**
+ * How long a new pairing session with no `purpose` on its link keeps the
+ * default preview bar hidden, so a `selectElement` that arrives after the join
+ * never flashes "Preview mode". Restarts once when the socket first reaches
+ * `connected` while the hold is still up: a slow connect still shows
+ * "Connecting…" after this delay, and a pick that starts shortly after the
+ * join stays inside the window.
+ */
+export const INITIAL_REVEAL_DELAY_MS = 2000;
+
+interface HoldInputs {
+  session: number;
+  previewStart: number;
+  chromeVisible: boolean;
+  pickerActive: boolean;
+  status: PairingEngineState['status'];
+  purpose: PairingPurpose | null;
+  connectRestarted: boolean;
+}
+
+interface HoldDecision {
+  introHeld: boolean;
+  selectionHeld: boolean;
+  restartTimer: boolean;
+  inputs: HoldInputs;
+}
+
+/**
+ * A new session (or chrome appearing) is decided by the link's purpose:
+ * `select_element` starts in the selection hold, `preview` is never held, and
+ * no purpose falls back to the intro hold. The intro hold hides the bar when
+ * preview chrome appears, and again when the session changes while a hold is
+ * already hiding it. A bar that is already showing stays up across a re-scan
+ * with no purpose. Selection hold replaces the intro once the picker is active
+ * and outlives the picker until a Builder preview, a `preview` re-scan, or a
+ * re-scan with no purpose. A `select_element` re-scan starts held, including
+ * when the bar is already up.
+ */
+function decideHold(
+  prev: HoldInputs,
+  holds: { introHeld: boolean; selectionHeld: boolean },
+  input: HoldInputs,
+): HoldDecision {
+  let introHeld = holds.introHeld;
+  let selectionHeld = holds.selectionHeld;
+  let connectRestarted = prev.connectRestarted;
+  let restartTimer = false;
+
+  const armIntro = (): void => {
+    introHeld = true;
+    connectRestarted = false;
+    restartTimer = true;
+  };
+
+  if (!input.chromeVisible) {
+    return {
+      introHeld: false,
+      selectionHeld: false,
+      restartTimer: false,
+      inputs: { ...input, connectRestarted: false },
+    };
+  }
+
+  const sessionChanged = input.session !== prev.session;
+  const previewStarted = input.previewStart > prev.previewStart;
+
+  if (previewStarted) {
+    introHeld = false;
+    selectionHeld = false;
+    connectRestarted = true;
+  } else if (input.pickerActive) {
+    selectionHeld = true;
+    introHeld = false;
+  } else if (sessionChanged || !prev.chromeVisible) {
+    if (input.purpose === 'select_element') {
+      selectionHeld = true;
+      introHeld = false;
+    } else if (input.purpose === 'preview') {
+      selectionHeld = false;
+      introHeld = false;
+    } else if (introHeld || selectionHeld || !prev.chromeVisible) {
+      selectionHeld = false;
+      armIntro();
+    }
+  }
+
+  if (introHeld && input.status === 'connected' && !connectRestarted) {
+    connectRestarted = true;
+    restartTimer = true;
+  }
+
+  return {
+    introHeld,
+    selectionHeld,
+    restartTimer,
+    inputs: { ...input, connectRestarted },
+  };
+}
+
+/**
+ * Whether the preview top bar should stay down.
+ *
+ * The decision is applied during render. Waiting for an effect would mount
+ * the bar for a frame and play its slide-in before the hold could hide it.
+ * The reveal timer stays in an effect.
+ */
+export function usePreviewBarHold(state: PairingEngineState, pickerActive: boolean): boolean {
+  const chromeVisible = resolvePreviewChrome(state).visible;
+  const [introHeld, setIntroHeld] = React.useState(false);
+  const [selectionHeld, setSelectionHeld] = React.useState(false);
+  const [introEpoch, setIntroEpoch] = React.useState(0);
+  const purpose = state.pairingPurpose ?? null;
+  const inputsRef = React.useRef<HoldInputs>({
+    session: state.pairingSessionGeneration,
+    previewStart: state.previewStartGeneration,
+    chromeVisible: false,
+    pickerActive: false,
+    status: state.status,
+    purpose,
+    connectRestarted: false,
+  });
+
+  const decision = decideHold(
+    inputsRef.current,
+    { introHeld, selectionHeld },
+    {
+      session: state.pairingSessionGeneration,
+      previewStart: state.previewStartGeneration,
+      chromeVisible,
+      pickerActive,
+      status: state.status,
+      purpose,
+      connectRestarted: false,
+    },
+  );
+  inputsRef.current = decision.inputs;
+
+  if (decision.introHeld !== introHeld) {
+    setIntroHeld(decision.introHeld);
+  }
+  if (decision.selectionHeld !== selectionHeld) {
+    setSelectionHeld(decision.selectionHeld);
+  }
+  if (decision.restartTimer) {
+    setIntroEpoch((epoch) => epoch + 1);
+  }
+
+  React.useEffect(() => {
+    if (!introHeld) return;
+    const timer = setTimeout(() => setIntroHeld(false), INITIAL_REVEAL_DELAY_MS);
+    return () => clearTimeout(timer);
+  }, [introEpoch, introHeld]);
+
+  return decision.introHeld || decision.selectionHeld;
+}

package/src/runtime/BannerHost.tsx

@@ -0,0 +1,102 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import type { BannerSessionFragment } from '@userflow-tech/protocol';
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { BannerSurface } from '../surfaces/BannerSurface';
+import { bannerOverlayHostPadding } from '../surfaces/bannerBarLayout';
+import { resolveBannerBackgroundColor } from '../surfaces/resolveBannerTheme';
+import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+
+import { SdkErrorBoundary } from './SdkErrorBoundary';
+import { bannerEdge, embedBannerPlaceholderId, warnBannerOnce } from './bannerPlacement';
+import { hasEmbedBannerPlaceholder } from './embedBannerRegistry';
+import { useBannerSession } from './useBannerSession';
+
+/**
+ * Top or bottom banner bar. Element modes render in {@link EmbedBannerPlaceholder}.
+ *
+ * `overlay` floats over the host. `flow` sits in layout and pushes the app.
+ * The bar does not participate in the host accessibility trap.
+ */
+export function BannerHost({
+  engine,
+  hidden,
+  placement = 'overlay',
+  edge: edgeFilter,
+}: {
+  engine: BannerSessionEngine;
+  hidden?: boolean;
+  placement?: 'overlay' | 'flow';
+  /** When set, render only the banner pinned to this edge. */
+  edge?: 'top' | 'bottom';
+}): React.ReactElement | null {
+  const session = useBannerSession(engine);
+  const banner = session?.version.banner ?? null;
+  const edge = banner ? bannerEdge(banner.embedMode) : null;
+  const insets = useUserflowSafeAreaInsets();
+
+  React.useEffect(() => {
+    if (!session || !banner || edge) return;
+    const placeholderId = embedBannerPlaceholderId(banner);
+    if (placeholderId && hasEmbedBannerPlaceholder(placeholderId)) return;
+    const message = placeholderId
+      ? `Userflow: no EmbedBannerPlaceholder with id "${placeholderId}" is mounted; the banner is not shown`
+      : `Userflow: banner embed mode ${banner.embedMode} needs a manual embed selector and an EmbedBannerPlaceholder with that id`;
+    warnBannerOnce(`embed:${session.id}:${banner.embedMode}:${placeholderId ?? 'none'}`, message);
+  }, [banner, edge, session]);
+
+  if (hidden || !session || !banner || !edge) return null;
+  if (edgeFilter && edge !== edgeFilter) return null;
+
+  const floats = banner.overlay !== false;
+  if ((placement === 'overlay') !== floats) return null;
+
+  const bar = (
+    <SdkErrorBoundary scope="banner" resetKey={session.id}>
+      <BannerSurface
+        session={session}
+        onActions={(actions) => engine.handleActions(actions)}
+        onDismiss={(endReason) => {
+          void engine.endBanner(endReason);
+        }}
+      />
+    </SdkErrorBoundary>
+  );
+
+  if (placement === 'flow') {
+    const backgroundColor = bannerBackground(session);
+    const safePad = edge === 'top' ? { paddingTop: insets.top } : { paddingBottom: insets.bottom };
+    return (
+      <View testID="userflow-banner-flow" style={[styles.flow, safePad, { backgroundColor }]}>
+        {bar}
+      </View>
+    );
+  }
+
+  const edgeStyle = edge === 'top' ? { top: insets.top } : { bottom: insets.bottom };
+
+  return (
+    <View
+      pointerEvents="box-none"
+      style={[styles.pin, edgeStyle, bannerOverlayHostPadding(insets)]}
+    >
+      {bar}
+    </View>
+  );
+}
+
+function bannerBackground(session: BannerSessionFragment): string {
+  return resolveBannerBackgroundColor(session.version.theme);
+}
+
+const styles = StyleSheet.create({
+  pin: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+  },
+  flow: {
+    alignSelf: 'stretch',
+  },
+});

package/src/runtime/EmbedBannerPlaceholder.tsx

@@ -0,0 +1,115 @@
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { elementPickerController } from '../authoring/elementPickerController';
+import { BannerSurface } from '../surfaces/BannerSurface';
+import { bannerOverlayHostPadding } from '../surfaces/bannerBarLayout';
+import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+
+import { SdkErrorBoundary } from './SdkErrorBoundary';
+import { BannerEngineContext } from './bannerEngineContext';
+import { embedBannerPlaceholderId, warnBannerOnce } from './bannerPlacement';
+import { registerEmbedBannerPlaceholder } from './embedBannerRegistry';
+import { useBannerSession } from './useBannerSession';
+
+export interface EmbedBannerPlaceholderProps {
+  /**
+   * Matches the banner's manual embed selector. `#welcome-banner` and
+   * `welcome-banner` both match this id.
+   */
+  id: string;
+}
+
+/**
+ * Host slot for an element-mode banner (`ELEMENT_BEFORE`, `ELEMENT_AFTER`,
+ * `ELEMENT_FIRST`, `ELEMENT_LAST`). Mount it where the bar should appear.
+ * Until a matching banner is active the slot renders nothing, so it takes no
+ * space and is not visible. Top and bottom bars ignore this slot.
+ * `overlay: false` keeps the bar in layout; `overlay: true` paints it over
+ * the content below the slot.
+ */
+export function EmbedBannerPlaceholder({
+  id,
+}: EmbedBannerPlaceholderProps): React.ReactElement | null {
+  const engine = React.useContext(BannerEngineContext);
+  const placeholderId = id.trim();
+  const session = useBannerSession(engine);
+  const insets = useUserflowSafeAreaInsets();
+  const [pickerActive, setPickerActive] = React.useState(
+    () => elementPickerController.getState().active,
+  );
+
+  React.useEffect(() => {
+    return elementPickerController.subscribe((next) => {
+      setPickerActive(next.active);
+    });
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (!placeholderId) {
+      warnBannerOnce('embed-banner-empty-id', 'Userflow: EmbedBannerPlaceholder requires an id');
+      return;
+    }
+    return registerEmbedBannerPlaceholder(placeholderId);
+  }, [placeholderId]);
+
+  React.useEffect(() => {
+    if (engine) return;
+    warnBannerOnce(
+      'embed-banner-outside-provider',
+      'Userflow: EmbedBannerPlaceholder must be rendered inside UserflowProvider',
+    );
+  }, [engine]);
+
+  // No host view until a banner is actually shown. An empty slot would still
+  // participate in flex gap and stretch layout.
+  if (!engine || !placeholderId || pickerActive || !session) return null;
+
+  const banner = session.version.banner ?? null;
+  if (!banner || embedBannerPlaceholderId(banner) !== placeholderId) return null;
+
+  const bar = (
+    <BannerSurface
+      session={session}
+      onActions={(actions) => engine.handleActions(actions)}
+      onDismiss={(endReason) => {
+        void engine.endBanner(endReason);
+      }}
+    />
+  );
+
+  return (
+    <SdkErrorBoundary scope="banner" resetKey={session.id}>
+      {banner.overlay !== false ? (
+        <View pointerEvents="box-none" testID="userflow-embed-banner" style={styles.overlaySlot}>
+          <View
+            pointerEvents="box-none"
+            style={[styles.overlayBar, bannerOverlayHostPadding(insets)]}
+          >
+            {bar}
+          </View>
+        </View>
+      ) : (
+        <View testID="userflow-embed-banner" style={styles.slot}>
+          {bar}
+        </View>
+      )}
+    </SdkErrorBoundary>
+  );
+}
+
+const styles = StyleSheet.create({
+  slot: {
+    alignSelf: 'stretch',
+  },
+  overlaySlot: {
+    height: 0,
+    alignSelf: 'stretch',
+  },
+  overlayBar: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: 0,
+  },
+});