@userflow-tech/react-native 0.1.1 → 0.2.0

package/src/authoring/hitTest.ts

@@ -0,0 +1,133 @@
+import { autoAnchorRegistry, type AutoAnchorInstance } from '../anchors/AutoAnchorRegistry';
+import { fiberFromPublicInstance } from '../anchors/fiber/fiberInternals';
+import { measureHostFiber } from '../anchors/fiber/measureHostFiber';
+import { isFiberOnVisibleScreen } from '../anchors/fiber/visibleScreens';
+import { pointInRect } from '../anchors/targetPressMonitor';
+
+export interface HitRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface HitCandidate {
+  instance: AutoAnchorInstance;
+  rect: HitRect;
+  area: number;
+}
+
+export type MeasureInstance = (inst: AutoAnchorInstance) => Promise<HitRect | null>;
+export type InstanceFilter = (inst: AutoAnchorInstance) => boolean;
+
+const MEASURE_TIMEOUT_MS = 400;
+
+type MeasureInWindowCallback = (x: number, y: number, width: number, height: number) => void;
+
+interface MeasurableNode {
+  measureInWindow: (callback: MeasureInWindowCallback) => void;
+}
+
+function isMeasurableNode(value: unknown): value is MeasurableNode {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { measureInWindow?: unknown }).measureInWindow === 'function'
+  );
+}
+
+function areaOf(rect: HitRect): number {
+  return rect.width * rect.height;
+}
+
+function isInstanceOnVisibleScreen(inst: AutoAnchorInstance): boolean {
+  const fiber = fiberFromPublicInstance(inst.ref.current);
+  if (!fiber) return true;
+  return isFiberOnVisibleScreen(fiber);
+}
+
+function measureWithTimeout(
+  run: (callback: MeasureInWindowCallback) => void,
+): Promise<HitRect | null> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      resolve(null);
+    }, MEASURE_TIMEOUT_MS);
+    try {
+      run((x, y, width, height) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        if (width <= 0 || height <= 0) {
+          resolve(null);
+          return;
+        }
+        resolve({ x, y, width, height });
+      });
+    } catch {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(null);
+    }
+  });
+}
+
+/**
+ * Measure a live auto-anchor instance in window coordinates. Prefers the
+ * public instance's `measureInWindow`, then the fiber host path.
+ */
+export function measureInstanceRect(inst: AutoAnchorInstance): Promise<HitRect | null> {
+  const node = inst.ref.current;
+  if (isMeasurableNode(node)) {
+    return measureWithTimeout((callback) => {
+      node.measureInWindow(callback);
+    });
+  }
+  const fiber = fiberFromPublicInstance(node);
+  if (fiber) {
+    return measureWithTimeout((callback) => {
+      measureHostFiber(fiber, callback);
+    });
+  }
+  return Promise.resolve(null);
+}
+
+/**
+ * Hit-test window coordinates against visible auto-anchor instances.
+ * Returns containing candidates sorted by area ascending (smallest / deepest first).
+ */
+export async function hitTestAt(
+  x: number,
+  y: number,
+  opts?: {
+    instanceFilter?: InstanceFilter;
+    measure?: MeasureInstance;
+    instances?: AutoAnchorInstance[];
+  },
+): Promise<HitCandidate[]> {
+  const filter = opts?.instanceFilter ?? isInstanceOnVisibleScreen;
+  const measure = opts?.measure ?? measureInstanceRect;
+  const pool = (opts?.instances ?? autoAnchorRegistry.allInstances()).filter(filter);
+  autoAnchorRegistry.refreshLiveContent(pool);
+
+  const measured = await Promise.all(
+    pool.map(async (instance) => {
+      const rect = await measure(instance);
+      if (!rect) return null;
+      if (!pointInRect(x, y, rect)) return null;
+      return { instance, rect, area: areaOf(rect) };
+    }),
+  );
+
+  return measured.filter((c): c is HitCandidate => c != null).sort((a, b) => a.area - b.area);
+}
+
+/** Cycle to the next-larger containing candidate (wraps). */
+export function nextContainingIndex(candidates: HitCandidate[], currentIndex: number): number {
+  if (candidates.length === 0) return -1;
+  return (currentIndex + 1) % candidates.length;
+}

package/src/content/RichContentRenderer.tsx

@@ -68,6 +68,10 @@ export interface RichContentRendererProps {
    * Web: modal → center, tooltip/bubble → end.
    */
   defaultButtonsAlign?: JustifyContent;
+  /** Override H1 weight (modal uses `normal`; tooltip keeps the default bold). */
+  heading1FontWeight?: TextStyle['fontWeight'];
+  /** Extra H1 styles (callers that need per-heading layout). */
+  heading1Style?: TextStyle;
 }
 
 export function RichContentRenderer({
@@ -78,6 +82,8 @@ export function RichContentRenderer({
   lookupAttribute,
   onActions,
   defaultButtonsAlign,
+  heading1FontWeight,
+  heading1Style,
 }: RichContentRendererProps): React.ReactElement {
   const doc = React.useMemo(() => {
     const raw =
@@ -95,6 +101,8 @@ export function RichContentRenderer({
         lookupAttribute={lookupAttribute}
         onActions={onActions}
         {...(defaultButtonsAlign !== undefined ? { defaultButtonsAlign } : {})}
+        {...(heading1FontWeight !== undefined ? { heading1FontWeight } : {})}
+        {...(heading1Style !== undefined ? { heading1Style } : {})}
       />
     </View>
   );
@@ -107,6 +115,8 @@ interface RenderContext {
   lookupAttribute: LookupAttribute;
   onActions: (actions: FlowActionFragment[]) => void;
   defaultButtonsAlign?: JustifyContent;
+  heading1FontWeight?: TextStyle['fontWeight'];
+  heading1Style?: TextStyle;
 }
 
 function RenderedNodeList({
@@ -155,7 +165,18 @@ function RenderedElement({
     case 'paragraph':
       return <TextBlock node={node} style={styles.paragraph} {...ctx} />;
     case 'heading1':
-      return <TextBlock node={node} style={styles.heading1} accessibilityRole="header" {...ctx} />;
+      return (
+        <TextBlock
+          node={node}
+          style={StyleSheet.flatten([
+            styles.heading1,
+            ctx.heading1Style,
+            ctx.heading1FontWeight ? { fontWeight: ctx.heading1FontWeight } : null,
+          ])}
+          accessibilityRole="header"
+          {...ctx}
+        />
+      );
     case 'heading2':
       return <TextBlock node={node} style={styles.heading2} accessibilityRole="header" {...ctx} />;
     case 'quote':

package/src/content/StepButton.tsx

@@ -47,9 +47,8 @@ export function StepButton({
             color: chrome.fontColor,
             fontFamily: theme.fontFamily || undefined,
             fontSize: chrome.fontSize,
-            lineHeight: chrome.lineHeight,
             fontWeight: chrome.fontWeight,
-            ...(Platform.OS === 'android' ? { includeFontPadding: false } : null),
+            ...labelMetrics(chrome.lineHeight),
           } satisfies TextStyle,
         ]}
       >
@@ -59,6 +58,22 @@ export function StepButton({
   );
 }
 
+/**
+ * iOS/SF can sit in the theme line box. Android/Roboto descenders (g, y, p)
+ * are taller; `includeFontPadding: false` plus that same `lineHeight` clips
+ * them. Skip lineHeight on Android and let font metrics size the label — the
+ * pressable already centers via `justifyContent`.
+ */
+function labelMetrics(lineHeight: number): TextStyle {
+  if (Platform.OS === 'android') {
+    return {
+      includeFontPadding: false,
+      textAlignVertical: 'center',
+    };
+  }
+  return { lineHeight };
+}
+
 const styles = StyleSheet.create({
   button: {
     alignItems: 'center',

package/src/content/resolveStepButtonChrome.ts

@@ -81,15 +81,21 @@ export function resolveStepButtonChrome(
     borderWidth = Math.max(0, readNumber(theme, 'primaryButtonBorderWidth', 0));
     fontWeight = readNumber(theme, 'primaryButtonFontWeight', fontWeightBold);
   } else {
-    backgroundColor = readString(theme, 'defaultButtonBackgroundColor', mainBackground);
-    fontColor = readString(theme, 'defaultButtonFontColor', widgetBackground);
-    borderColor = readString(theme, 'defaultButtonBorderColor', fontColor);
-    borderWidth = Math.max(0, readNumber(theme, 'defaultButtonBorderWidth', 1));
-    fontWeight = readNumber(theme, 'defaultButtonFontWeight', fontWeightBold);
+    // Mobile secondary is a neutral outline (white + gray border + body text),
+    // not the web brand-colored ghost (`defaultButtonFontColor` = widget blue).
+    backgroundColor = firstString(
+      theme,
+      ['defaultButtonBackgroundColor', 'mainBackgroundColor', 'backgroundColor'],
+      mainBackground,
+    );
+    fontColor = readString(theme, 'fontColor', '#111827');
+    borderColor = '#d1d5db';
+    borderWidth = 1;
+    fontWeight = readNumber(theme, 'defaultButtonFontWeight', 500);
   }
 
   const paddingVertical = Math.max(0, (buttonHeight - lineHeight) / 2 - borderWidth);
-  const paddingHorizontal = fontSize;
+  const paddingHorizontal = isPrimary ? fontSize : Math.max(fontSize, 20);
 
   return {
     backgroundColor,

package/src/content/themeColor.ts

@@ -88,6 +88,16 @@ export function foregroundAlpha(color: string | null | undefined, alpha: number)
   return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})`;
 }
 
+/**
+ * Web's default `backdropHighlightColor` is `#ffffff`. An opaque white stroke
+ * on a dimmed backdrop reads as a thick frame, not the mobile focus ring.
+ */
+export function isNearWhite(color: string | null | undefined): boolean {
+  const rgb = parseThemeRgb(color);
+  if (!rgb) return false;
+  return rgb.r >= 245 && rgb.g >= 245 && rgb.b >= 245;
+}
+
 /**
  * Extra margin below quote/code so that with {@link ROOT_CONTENT_GAP} the
  * visual spacing matches web `margin-bottom: $padding-16`.

package/src/deviceContext.ts

@@ -0,0 +1,168 @@
+/**
+ * Resolve mobile platform metadata for Userflow user attributes.
+ *
+ * Cached once during {@link Userflow.init} and merged into identify attributes
+ * (same lifecycle as {@link hostAppVersion.ts}).
+ */
+
+export type SdkPlatform = 'react_native';
+export type DeviceOs = 'ios' | 'android';
+export type DeviceType = 'phone' | 'tablet';
+
+export interface DeviceContext {
+  sdk: SdkPlatform;
+  deviceOs?: DeviceOs;
+  deviceType?: DeviceType;
+}
+
+/** Android `smallestScreenWidthDp` tablet threshold (sw600dp). */
+export const ANDROID_TABLET_SMALLEST_WIDTH_DP = 600;
+
+export const SDK_USER_ATTRIBUTE = 'sdk';
+export const DEVICE_OS_USER_ATTRIBUTE = 'device_os';
+export const DEVICE_TYPE_USER_ATTRIBUTE = 'device_type';
+
+interface PlatformShape {
+  OS?: string;
+  isPad?: boolean;
+}
+
+interface ScreenShape {
+  width: number;
+  height: number;
+}
+
+/** Visible for tests: map `Platform.OS` to a supported device OS value. */
+export function resolveDeviceOs(platformOs: string | undefined): DeviceOs | undefined {
+  if (platformOs === 'ios') return 'ios';
+  if (platformOs === 'android') return 'android';
+  return undefined;
+}
+
+/** Visible for tests: smallest screen width. `Dimensions` values are already dp. */
+export function smallestScreenWidthDp(screen: ScreenShape): number {
+  return Math.min(screen.width, screen.height);
+}
+
+/** Visible for tests: classify phone vs tablet for the current platform. */
+export function resolveDeviceTypeFromSources(sources: {
+  platform?: PlatformShape;
+  screen?: ScreenShape;
+}): DeviceType | undefined {
+  const os = sources.platform?.OS;
+  if (os === 'ios') {
+    return sources.platform?.isPad ? 'tablet' : 'phone';
+  }
+  if (os === 'android') {
+    const screen = sources.screen;
+    if (!screen) return undefined;
+    return smallestScreenWidthDp(screen) >= ANDROID_TABLET_SMALLEST_WIDTH_DP ? 'tablet' : 'phone';
+  }
+  return undefined;
+}
+
+/** Visible for tests: build the cached device context from RN platform APIs. */
+export function resolveDeviceContextFromSources(sources: {
+  platform?: PlatformShape;
+  screen?: ScreenShape;
+}): DeviceContext {
+  const deviceOs = resolveDeviceOs(sources.platform?.OS);
+  const deviceType = resolveDeviceTypeFromSources(sources);
+  return {
+    sdk: 'react_native',
+    ...(deviceOs ? { deviceOs } : {}),
+    ...(deviceType ? { deviceType } : {}),
+  };
+}
+
+function loadReactNativePlatformApis(): {
+  platform?: PlatformShape;
+  screen?: ScreenShape;
+} {
+  try {
+    // Lazy require so Node unit tests can inject sources without loading RN.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const rn = require('react-native') as {
+      Platform?: PlatformShape;
+      Dimensions?: { get: (kind: 'screen' | 'window') => ScreenShape };
+    };
+    const platform = rn.Platform;
+    const screen = rn.Dimensions?.get('screen');
+    return {
+      ...(platform ? { platform } : {}),
+      ...(screen ? { screen } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+export function resolveDeviceContext(): DeviceContext {
+  return resolveDeviceContextFromSources(loadReactNativePlatformApis());
+}
+
+/** `undefined` until the first {@link cacheDeviceContextAtInit}; then resolved. */
+let cachedDeviceContext: DeviceContext | undefined;
+
+/**
+ * Resolve and cache device metadata during {@link Userflow.init}.
+ * Re-running init replaces the cache.
+ */
+export function cacheDeviceContextAtInit(): DeviceContext {
+  cachedDeviceContext = resolveDeviceContext();
+  return cachedDeviceContext;
+}
+
+/** Returns the context cached at init, or `null` before init. */
+export function getCachedDeviceContext(): DeviceContext | null {
+  return cachedDeviceContext ?? null;
+}
+
+/** Returns cached device fields for UpsertUser, or `{}` before init. */
+export function deviceContextUserAttributes(): Record<string, string> {
+  const cached = getCachedDeviceContext();
+  if (!cached) return {};
+  return {
+    [SDK_USER_ATTRIBUTE]: cached.sdk,
+    ...(cached.deviceOs ? { [DEVICE_OS_USER_ATTRIBUTE]: cached.deviceOs } : {}),
+    ...(cached.deviceType ? { [DEVICE_TYPE_USER_ATTRIBUTE]: cached.deviceType } : {}),
+  };
+}
+
+/** Optional user-attribute keys added by {@link mergeDeviceContextUserAttributes}. */
+export type DeviceContextUserAttributeMap = Partial<{
+  [SDK_USER_ATTRIBUTE]: SdkPlatform;
+  [DEVICE_OS_USER_ATTRIBUTE]: DeviceOs;
+  [DEVICE_TYPE_USER_ATTRIBUTE]: DeviceType;
+}>;
+
+/** Merges cached device attrs into identify attributes; caller values win on key conflicts. */
+export function mergeDeviceContextUserAttributes<T extends Record<string, unknown>>(
+  attributes?: T,
+): (T & DeviceContextUserAttributeMap) | undefined {
+  const system = deviceContextUserAttributes();
+  if (Object.keys(system).length === 0) {
+    return attributes as (T & DeviceContextUserAttributeMap) | undefined;
+  }
+  return { ...system, ...(attributes ?? {}) } as T & DeviceContextUserAttributeMap;
+}
+
+export function formatDeviceContextLog(resolved: DeviceContext | null): string {
+  if (!resolved) {
+    return '[Userflow] device context is unavailable — call Userflow.init() first.';
+  }
+  const os = resolved.deviceOs ?? 'unknown';
+  const type = resolved.deviceType ?? 'unknown';
+  return `[Userflow] device context sdk=${resolved.sdk} device_os=${os} device_type=${type}`;
+}
+
+/** Log cached user-attribute values. Requires {@link cacheDeviceContextAtInit}. */
+export function logDeviceContext(): void {
+  // eslint-disable-next-line no-console -- public logDeviceContext()
+  console.log(formatDeviceContextLog(getCachedDeviceContext()));
+}
+
+/** @internal Resets init cache between tests. */
+export function resetCachedDeviceContextForTests(): void {
+  cachedDeviceContext = undefined;
+}

package/src/expo-router/useUserflowExpoRouter.ts

@@ -1,6 +1,11 @@
-import { usePathname, useRouter } from 'expo-router';
-import { useEffect } from 'react';
+import { useNavigationContainerRef, usePathname, useRouter } from 'expo-router';
+import { useCallback, useEffect, useRef } from 'react';
 
+import {
+  isOverlayPresentation,
+  readNavigationPresentation,
+  subscribeNavigationState,
+} from '../navigation/isOverlayPresentation';
 import { setExpoRouterNavigator } from '../navigation/openFlowNavigateUrl';
 import { handleScreenChange } from '../screenTracker';
 
@@ -22,10 +27,48 @@ import { handleScreenChange } from '../screenTracker';
 export function useUserflowExpoRouter(): void {
   const pathname = usePathname();
   const router = useRouter();
+  // Root container ref — `useNavigation()` is the route prop and has no getCurrentOptions.
+  const navigationRef = useNavigationContainerRef();
+  const overlayWasFocusedRef = useRef(false);
+  const pathnameRef = useRef(pathname);
+  pathnameRef.current = pathname;
+  const subscribedToStateRef = useRef(false);
+
+  const reportPath = useCallback(() => {
+    if (isOverlayPresentation(readNavigationPresentation(navigationRef))) {
+      overlayWasFocusedRef.current = true;
+      return;
+    }
+    handleScreenChange(
+      pathnameRef.current ? { path: pathnameRef.current } : undefined,
+      overlayWasFocusedRef.current ? { force: true } : undefined,
+    );
+    overlayWasFocusedRef.current = false;
+  }, [navigationRef]);
+
+  useEffect(() => {
+    // Pathname is the fallback when the container ref has no `state` listener
+    // (tests, or before the root container mounts). Once subscribed, navigation
+    // state is the source of truth so overlay options are read on the same tick
+    // as the transition — a pathname-only update can still see the previous
+    // route's options.
+    if (!subscribedToStateRef.current) {
+      reportPath();
+    }
+  }, [pathname, reportPath]);
 
   useEffect(() => {
-    handleScreenChange(pathname ? { path: pathname } : undefined);
-  }, [pathname]);
+    const unsubscribe = subscribeNavigationState(navigationRef, () => {
+      queueMicrotask(() => {
+        reportPath();
+      });
+    });
+    subscribedToStateRef.current = typeof unsubscribe === 'function';
+    return () => {
+      subscribedToStateRef.current = false;
+      unsubscribe?.();
+    };
+  }, [navigationRef, reportPath]);
 
   useEffect(() => {
     setExpoRouterNavigator({