@userflow-tech/react-native 0.2.0 → 0.3.0

package/src/content/BannerStepButton.tsx

@@ -0,0 +1,91 @@
+import { interpolateSessionData } from '@userflow-tech/core';
+import type {
+  FlowActionFragment,
+  FlowButtonFragment,
+  ThemeFragment,
+} from '@userflow-tech/protocol';
+import * as React from 'react';
+import type { TextStyle } from 'react-native';
+import { Platform, Pressable, StyleSheet, Text } from 'react-native';
+
+import {
+  resolveBannerBackgroundColor,
+  resolveBannerForegroundColor,
+} from '../surfaces/resolveBannerTheme';
+
+import { resolveBannerButtonChrome } from './resolveBannerButtonChrome';
+import { stepButtonContainerStyle } from './resolveStepButtonChrome';
+
+export interface BannerStepButtonProps {
+  button: FlowButtonFragment;
+  theme: ThemeFragment;
+  sessionData: { name: string; value: string | string[] }[];
+  onActions: (actions: FlowActionFragment[]) => void;
+}
+
+/** Step actions on the embed banner bar (Figma SDK Embed Banner). */
+export function BannerStepButton({
+  button,
+  theme,
+  sessionData,
+  onActions,
+}: BannerStepButtonProps): React.ReactElement {
+  const label = interpolateSessionData(button.text, sessionData);
+  const bannerBackground = resolveBannerBackgroundColor(theme);
+  const bannerForeground = resolveBannerForegroundColor(theme);
+  const chrome = resolveBannerButtonChrome(
+    theme,
+    button.appearance,
+    bannerBackground,
+    bannerForeground,
+  );
+
+  return (
+    <Pressable
+      testID={`userflow-button-${button.cvid}`}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      onPress={() => onActions(button.actions)}
+      style={({ pressed }) => [
+        styles.button,
+        stepButtonContainerStyle(chrome),
+        { opacity: pressed ? 0.88 : 1 },
+      ]}
+    >
+      <Text
+        style={[
+          styles.label,
+          {
+            color: chrome.fontColor,
+            fontFamily: theme.fontFamily || undefined,
+            fontSize: chrome.fontSize,
+            fontWeight: chrome.fontWeight,
+            ...labelMetrics(chrome.lineHeight),
+          } satisfies TextStyle,
+        ]}
+      >
+        {label}
+      </Text>
+    </Pressable>
+  );
+}
+
+function labelMetrics(lineHeight: number): TextStyle {
+  if (Platform.OS === 'android') {
+    return {
+      includeFontPadding: false,
+      textAlignVertical: 'center',
+    };
+  }
+  return { lineHeight };
+}
+
+const styles = StyleSheet.create({
+  button: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  label: {
+    textAlign: 'center',
+  },
+});

package/src/content/buttonAppearance.ts

@@ -9,3 +9,19 @@ export function isPrimaryButtonAppearance(appearance: string | null | undefined)
   const normalized = appearance.toLowerCase();
   return normalized === 'primary' || normalized === 'banner-primary';
 }
+
+/** Figma / web `userflowjs-bubble-button--banner-primary` (inverted CTA on the bar). */
+export function isBannerPrimaryAppearance(appearance: string | null | undefined): boolean {
+  if (!appearance) return false;
+  const normalized = appearance.toLowerCase();
+  return normalized === 'banner-primary' || normalized === 'primary';
+}
+
+/** Figma / web `userflowjs-bubble-button--banner-secondary` (outline on the bar). */
+export function isBannerSecondaryAppearance(appearance: string | null | undefined): boolean {
+  if (!appearance) return false;
+  const normalized = appearance.toLowerCase();
+  return (
+    normalized === 'banner-secondary' || normalized === 'default' || normalized === 'secondary'
+  );
+}

package/src/content/resolveBannerButtonChrome.ts

@@ -0,0 +1,49 @@
+import type { ThemeFragment } from '@userflow-tech/protocol';
+
+import { BANNER_BUTTON_PADDING_HORIZONTAL } from '../surfaces/bannerBarTokens';
+
+import {
+  isBannerPrimaryAppearance,
+  isBannerSecondaryAppearance,
+  isPrimaryButtonAppearance,
+} from './buttonAppearance';
+import { resolveStepButtonChrome, type StepButtonChrome } from './resolveStepButtonChrome';
+
+/**
+ * Banner bar buttons (`userflowjs-bubble-button--banner-primary` /
+ * `--banner-secondary`). Primary is inverted on the bar; secondary is an outline.
+ */
+export function resolveBannerButtonChrome(
+  theme: ThemeFragment,
+  appearance: string | null | undefined,
+  bannerBackground: string,
+  bannerForeground: string,
+): StepButtonChrome {
+  const metrics = resolveStepButtonChrome(theme, false);
+  if (isBannerPrimaryAppearance(appearance)) {
+    const primaryMetrics = resolveStepButtonChrome(theme, true);
+    return {
+      ...primaryMetrics,
+      minWidth: 0,
+      backgroundColor: bannerForeground,
+      fontColor: bannerBackground,
+      borderColor: bannerForeground,
+      borderWidth: 0,
+      paddingHorizontal: BANNER_BUTTON_PADDING_HORIZONTAL,
+    };
+  }
+
+  if (isBannerSecondaryAppearance(appearance) || appearance == null || appearance === '') {
+    return {
+      ...metrics,
+      minWidth: 0,
+      backgroundColor: bannerBackground,
+      fontColor: bannerForeground,
+      borderColor: bannerForeground,
+      borderWidth: 1,
+      paddingHorizontal: BANNER_BUTTON_PADDING_HORIZONTAL,
+    };
+  }
+
+  return { ...resolveStepButtonChrome(theme, isPrimaryButtonAppearance(appearance)), minWidth: 0 };
+}

package/src/content/themeColor.ts

@@ -88,6 +88,21 @@ export function foregroundAlpha(color: string | null | undefined, alpha: number)
   return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})`;
 }
 
+function byteToHex(n: number): string {
+  return clampByte(n).toString(16).padStart(2, '0');
+}
+
+/** Linear blend between two theme colors (web hover/active approximations). */
+export function mixThemeColors(base: string, overlay: string, overlayWeight: number): string {
+  const b = parseThemeRgb(base) ?? FALLBACK_FG;
+  const o = parseThemeRgb(overlay) ?? FALLBACK_FG;
+  const w = Math.max(0, Math.min(1, overlayWeight));
+  const r = clampByte(b.r + (o.r - b.r) * w);
+  const g = clampByte(b.g + (o.g - b.g) * w);
+  const bCh = clampByte(b.b + (o.b - b.b) * w);
+  return `#${byteToHex(r)}${byteToHex(g)}${byteToHex(bCh)}`;
+}
+
 /**
  * Web's default `backdropHighlightColor` is `#ffffff`. An opaque white stroke
  * on a dimmed backdrop reads as a thick frame, not the mobile focus ring.

package/src/content/types.ts

@@ -101,6 +101,7 @@ export interface ColumnGroupElement {
 
 export interface ContainerElement {
   type: 'container';
+  className?: string;
   children: RichContentBlockElement[];
 }
 

package/src/deepLinking.ts

@@ -1,10 +1,10 @@
 /**
  * Inbound deep-link handling for builder preview.
  *
- * Host apps register their environment's `scheme_id` (e.g. `userflow-257587`) as
- * a URL scheme at build time. The SDK matches inbound URLs by prefix + root
- * query (no init config) and starts a draft flow via `StartFlowWithToken` once
- * a user is identified.
+ * Host apps register their environment's `scheme_id` (e.g.
+ * `userflow-v7twv2fw2ja2jaco7kesvowmem`) as a URL scheme at build time. The SDK
+ * matches inbound URLs by prefix + root query (no init config) and starts a
+ * draft flow via `StartFlowWithToken` once a user is identified.
  */
 
 import { Linking } from 'react-native';

package/src/evalJs/EvalJsHost.tsx

@@ -0,0 +1,255 @@
+import * as React from 'react';
+import { Platform, useColorScheme, useWindowDimensions, View, type ViewStyle } from 'react-native';
+
+import { getCurrentScreenLocation, subscribeScreenLocation } from '../screenTracker';
+import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+import { useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+
+import { buildBootstrapHtml, EVAL_JS_BASE_URL, isBootstrapUrl } from './bootstrap';
+import { parseBridgeMessage } from './bridgeMessages';
+import { formatEvalJsError, getEvalJsBridgeHandlers } from './evalJsBridge';
+import { evalJsController } from './evalJsController';
+import { getEvalJsWebView, type EvalJsWebViewHandle } from './getWebView';
+import type { EvalJsContext, EvalJsLayout, EvalJsScreen } from './types';
+import { useEvalJsWebViewInjection } from './useEvalJsWebViewInjection';
+
+export interface EvalJsHostProps {
+  /** Hide the page (picker is up) without destroying script state. */
+  suppressed: boolean;
+}
+
+function screenFromLocation(location: { path: string } | { screen: string } | null): EvalJsScreen {
+  if (!location) return {};
+  if ('path' in location) return location.path ? { path: location.path } : {};
+  return location.screen ? { name: location.screen } : {};
+}
+
+function useEvalJsScreen(): EvalJsScreen {
+  const [screen, setScreen] = React.useState<EvalJsScreen>(() =>
+    screenFromLocation(getCurrentScreenLocation()),
+  );
+  React.useEffect(() => {
+    return subscribeScreenLocation((location) => {
+      setScreen(screenFromLocation(location));
+    });
+  }, []);
+  return screen;
+}
+
+interface Clip {
+  interactive: boolean;
+  outer: ViewStyle;
+  web: ViewStyle;
+}
+
+function clipFor(
+  layout: EvalJsLayout,
+  viewport: { width: number; height: number },
+  suppressed: boolean,
+): Clip {
+  const fullWeb: ViewStyle = {
+    width: viewport.width,
+    height: viewport.height,
+    backgroundColor: 'transparent',
+  };
+  const hidden = suppressed || (layout.mode !== 'fitted' && layout.mode !== 'fullscreen');
+  if (hidden) {
+    return {
+      interactive: false,
+      outer: { ...ABSOLUTE_FILL, opacity: 0 },
+      web: fullWeb,
+    };
+  }
+  if (layout.mode === 'fullscreen') {
+    return { interactive: true, outer: ABSOLUTE_FILL, web: fullWeb };
+  }
+  const rect = layout.rect;
+  if (!rect) {
+    return {
+      interactive: false,
+      outer: { ...ABSOLUTE_FILL, opacity: 0 },
+      web: fullWeb,
+    };
+  }
+  return {
+    interactive: true,
+    outer: {
+      position: 'absolute',
+      left: rect.x,
+      top: rect.y,
+      width: rect.width,
+      height: rect.height,
+      overflow: 'hidden',
+    },
+    web: {
+      position: 'absolute',
+      left: -rect.x,
+      top: -rect.y,
+      width: viewport.width,
+      height: viewport.height,
+      backgroundColor: 'transparent',
+    },
+  };
+}
+
+/**
+ * One shared WebView for Evaluate JavaScript. Mounted by the SDK overlay,
+ * created on first use, destroyed on {@link evalJsController.reset}.
+ *
+ * Fitted mode clips a full-size WebView to the script's rectangle so the
+ * page viewport does not change (and the rest of the app still receives taps).
+ */
+export function EvalJsHost({ suppressed }: EvalJsHostProps): React.ReactElement | null {
+  const snapshot = React.useSyncExternalStore(
+    evalJsController.subscribe,
+    evalJsController.getSnapshot,
+    evalJsController.getSnapshot,
+  );
+  if (!snapshot.active) return null;
+  if (snapshot.bannerOwnsWebView) return null;
+  return (
+    <EvalJsWebView
+      key={snapshot.generation}
+      suppressed={suppressed}
+      generation={snapshot.generation}
+      pendingCount={snapshot.pendingCount}
+      layout={snapshot.layout}
+      host={snapshot.host}
+    />
+  );
+}
+
+interface WebViewProps {
+  suppressed: boolean;
+  generation: number;
+  pendingCount: number;
+  layout: EvalJsLayout;
+  host: Record<string, unknown>;
+}
+
+function EvalJsWebView({
+  suppressed,
+  generation,
+  pendingCount,
+  layout,
+  host,
+}: WebViewProps): React.ReactElement | null {
+  const WebView = getEvalJsWebView();
+  const webRef = React.useRef<EvalJsWebViewHandle>(null);
+  const [pageReady, setPageReady] = React.useState(false);
+  const generationRef = React.useRef(generation);
+  const colorScheme = useColorScheme();
+  const viewport = useWindowDimensions();
+  const insets = useUserflowSafeAreaInsets();
+  const screen = useEvalJsScreen();
+
+  const context = React.useMemo<EvalJsContext>(
+    () => ({
+      platform: Platform.OS,
+      colorScheme: colorScheme === 'dark' ? 'dark' : 'light',
+      safeAreaInsets: insets,
+      viewport: { width: viewport.width, height: viewport.height },
+      screen,
+      host,
+    }),
+    [colorScheme, host, insets, screen, viewport.height, viewport.width],
+  );
+
+  const initialContext = React.useRef(context);
+  const html = React.useMemo(() => buildBootstrapHtml(initialContext.current), []);
+
+  useEvalJsWebViewInjection(webRef, { pageReady, context, pendingCount });
+
+  const openExternal = React.useCallback((url: string) => {
+    if (!url || isBootstrapUrl(url)) return;
+    getEvalJsBridgeHandlers().openUrl(url);
+  }, []);
+
+  const onMessage = React.useCallback(
+    (event: { nativeEvent: { data?: string } }) => {
+      if (generationRef.current !== generation) return;
+      const message = parseBridgeMessage(event.nativeEvent.data);
+      if (!message) return;
+      const bridge = getEvalJsBridgeHandlers();
+      switch (message.type) {
+        case 'ready':
+          setPageReady(true);
+          return;
+        case 'close':
+          evalJsController.reset();
+          return;
+        case 'endFlow':
+          bridge.endFlow(evalJsController.sessionIds());
+          evalJsController.reset();
+          return;
+        case 'setLayout':
+          evalJsController.setLayout(message.layout);
+          return;
+        case 'track':
+          bridge.track(message.name, message.attributes);
+          return;
+        case 'updateUser':
+          bridge.updateUser(message.attributes);
+          return;
+        case 'updateGroup':
+          bridge.updateGroup(message.attributes, message.options);
+          return;
+        case 'openUrl':
+          bridge.openUrl(message.url);
+          return;
+        case 'error':
+          bridge.warn(formatEvalJsError(message.message, message.code));
+          return;
+        default:
+          return;
+      }
+    },
+    [generation],
+  );
+
+  if (!WebView) return null;
+
+  const clip = clipFor(layout, { width: viewport.width, height: viewport.height }, suppressed);
+  const debugging = typeof __DEV__ !== 'undefined' && __DEV__ ? true : undefined;
+
+  return (
+    <View pointerEvents="box-none" style={ABSOLUTE_FILL}>
+      <View pointerEvents={clip.interactive ? 'auto' : 'none'} style={clip.outer}>
+        <WebView
+          ref={webRef}
+          source={{ html, baseUrl: EVAL_JS_BASE_URL }}
+          style={clip.web}
+          pointerEvents={clip.interactive ? 'auto' : 'none'}
+          originWhitelist={['*']}
+          javaScriptEnabled
+          domStorageEnabled
+          scrollEnabled={false}
+          bounces={false}
+          showsHorizontalScrollIndicator={false}
+          showsVerticalScrollIndicator={false}
+          mediaPlaybackRequiresUserAction={false}
+          allowsInlineMediaPlayback
+          setSupportMultipleWindows={false}
+          androidLayerType="hardware"
+          {...(debugging !== undefined ? { webviewDebuggingEnabled: debugging } : {})}
+          onMessage={onMessage}
+          onShouldStartLoadWithRequest={(request) => {
+            if (isBootstrapUrl(request.url)) return true;
+            openExternal(request.url);
+            return false;
+          }}
+          onOpenWindow={(event) => {
+            const url = event.nativeEvent.targetUrl;
+            if (url) openExternal(url);
+          }}
+          onError={(event) => {
+            const description = event.nativeEvent.description;
+            if (description) {
+              getEvalJsBridgeHandlers().warn(formatEvalJsError(description));
+            }
+          }}
+        />
+      </View>
+    </View>
+  );
+}

package/src/evalJs/bootstrap.ts

@@ -0,0 +1,83 @@
+import type { EvalJsContext } from './types';
+
+/** Document URL of the empty page that hosts customer scripts. */
+export const EVAL_JS_BASE_URL = 'https://userflow.local/';
+
+export function isBootstrapUrl(url: string): boolean {
+  if (!url || url === 'about:blank' || url.startsWith('about:blank')) return true;
+  if (url.startsWith('data:text/html')) return true;
+  return url === EVAL_JS_BASE_URL || url.startsWith(EVAL_JS_BASE_URL);
+}
+
+function embedJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+/**
+ * Empty transparent page plus the `window.userflow` bridge.
+ * The bridge runs in the document itself, before any customer code is injected.
+ */
+export function buildBootstrapHtml(context: EvalJsContext, bodyHtml = ''): string {
+  const contextJson = embedJson(context);
+  return `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+<style>
+  html, body { margin: 0; padding: 0; background: transparent; }
+</style>
+<script>
+(function () {
+  function post(msg) {
+    try {
+      if (window.ReactNativeWebView && window.ReactNativeWebView.postMessage) {
+        window.ReactNativeWebView.postMessage(JSON.stringify(Object.assign({ __userflow: 1 }, msg)));
+      }
+    } catch (e) {}
+  }
+  window.__userflowApplyContext = function (next) {
+    window.userflowContext = next || {};
+    try { window.dispatchEvent(new Event('userflow:contextchange')); } catch (e) {}
+  };
+  window.__userflowApplyContext(${contextJson});
+  window.userflow = {
+    track: function (name, attributes) { post({ type: 'track', name: name, attributes: attributes }); },
+    updateUser: function (attributes) { post({ type: 'updateUser', attributes: attributes }); },
+    updateGroup: function (attributes, options) { post({ type: 'updateGroup', attributes: attributes, options: options }); },
+    openUrl: function (url) { post({ type: 'openUrl', url: String(url || '') }); },
+    close: function () { post({ type: 'close' }); },
+    endFlow: function () { post({ type: 'endFlow' }); },
+    setLayout: function (layout) { post({ type: 'setLayout', layout: layout }); }
+  };
+  window.addEventListener('error', function (event) {
+    post({ type: 'error', message: String((event && event.message) || 'error') });
+  });
+  post({ type: 'ready' });
+})();
+</script>
+</head>
+<body>${bodyHtml}</body>
+</html>`;
+}
+
+/** Push a fresh `userflowContext` and notify scripts. Does not reload the page. */
+export function contextUpdateScript(context: EvalJsContext): string {
+  return `window.__userflowApplyContext&&window.__userflowApplyContext(${embedJson(context)});true;`;
+}
+
+/**
+ * Same execution model as web userflow.js: `new Function('"use strict";\\n' + code)`.
+ * The code is a JSON string literal so it cannot break out of the wrapper.
+ * `true;` is required so `injectJavaScript` settles on iOS.
+ */
+export function wrapCode(code: string): string {
+  const literal = embedJson(code);
+  return (
+    `try{var __uf=new Function('"use strict";\\n'+${literal});__uf();}` +
+    `catch(e){var __m=(e&&(e.stack||e.message))||String(e);` +
+    `if(window.ReactNativeWebView&&window.ReactNativeWebView.postMessage){` +
+    `window.ReactNativeWebView.postMessage(JSON.stringify({__userflow:1,type:'error',message:String(__m),code:${literal}}));}}` +
+    `true;`
+  );
+}

package/src/evalJs/bridgeMessages.ts

@@ -0,0 +1,134 @@
+import type { EvalJsLayout, EvalJsRect } from './types';
+
+const MESSAGE_TYPES = new Set([
+  'ready',
+  'close',
+  'endFlow',
+  'setLayout',
+  'track',
+  'updateUser',
+  'updateGroup',
+  'openUrl',
+  'error',
+]);
+
+export type BridgeMessage =
+  | { type: 'ready' }
+  | { type: 'close' }
+  | { type: 'endFlow' }
+  | { type: 'setLayout'; layout: EvalJsLayout }
+  | { type: 'track'; name: string; attributes?: Record<string, unknown> }
+  | { type: 'updateUser'; attributes: Record<string, unknown> }
+  | {
+      type: 'updateGroup';
+      attributes: Record<string, unknown>;
+      options?: { membership?: Record<string, unknown> };
+    }
+  | { type: 'openUrl'; url: string }
+  | { type: 'error'; message: string; code?: string };
+
+/**
+ * Accept only JSON objects tagged `__userflow: 1` with an allowlisted type.
+ * Anything else (page noise, unexpected shapes) is ignored.
+ */
+export function parseBridgeMessage(raw: unknown): BridgeMessage | null {
+  let value = raw;
+  if (typeof raw === 'string') {
+    try {
+      value = JSON.parse(raw) as unknown;
+    } catch {
+      return null;
+    }
+  }
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (record.__userflow !== 1) return null;
+  if (typeof record.type !== 'string' || !MESSAGE_TYPES.has(record.type)) return null;
+
+  switch (record.type) {
+    case 'ready':
+      return { type: 'ready' };
+    case 'close':
+      return { type: 'close' };
+    case 'endFlow':
+      return { type: 'endFlow' };
+    case 'error':
+      return {
+        type: 'error',
+        message: typeof record.message === 'string' ? record.message : 'error',
+        ...(typeof record.code === 'string' ? { code: record.code } : {}),
+      };
+    case 'openUrl':
+      if (typeof record.url !== 'string' || record.url.length === 0) return null;
+      return { type: 'openUrl', url: record.url };
+    case 'track': {
+      if (typeof record.name !== 'string' || record.name.length === 0) return null;
+      if (record.attributes != null && !isRecord(record.attributes)) return null;
+      return {
+        type: 'track',
+        name: record.name,
+        ...(isRecord(record.attributes) ? { attributes: record.attributes } : {}),
+      };
+    }
+    case 'updateUser': {
+      if (!isRecord(record.attributes)) return null;
+      return { type: 'updateUser', attributes: record.attributes };
+    }
+    case 'updateGroup': {
+      if (!isRecord(record.attributes)) return null;
+      const options = record.options;
+      if (options == null) return { type: 'updateGroup', attributes: record.attributes };
+      if (!isRecord(options)) return null;
+      if (options.membership != null && !isRecord(options.membership)) return null;
+      return {
+        type: 'updateGroup',
+        attributes: record.attributes,
+        ...(isRecord(options.membership) ? { options: { membership: options.membership } } : {}),
+      };
+    }
+    case 'setLayout': {
+      const layout = parseLayout(record.layout);
+      if (!layout) return null;
+      return { type: 'setLayout', layout };
+    }
+    default:
+      return null;
+  }
+}
+
+function parseLayout(value: unknown): EvalJsLayout | null {
+  if (!isRecord(value)) return null;
+  if (value.mode === 'hidden' || value.mode === 'fullscreen') {
+    return { mode: value.mode };
+  }
+  if (value.mode !== 'fitted') return null;
+  const rect = parseRect(value.rect);
+  if (!rect) return null;
+  return { mode: 'fitted', rect };
+}
+
+function parseRect(value: unknown): EvalJsRect | null {
+  if (!isRecord(value)) return null;
+  const x = value.x;
+  const y = value.y;
+  const width = value.width;
+  const height = value.height;
+  if (
+    !isFiniteNumber(x) ||
+    !isFiniteNumber(y) ||
+    !isFiniteNumber(width) ||
+    !isFiniteNumber(height)
+  ) {
+    return null;
+  }
+  if (width <= 0 || height <= 0) return null;
+  return { x, y, width, height };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}