@userflow-tech/react-native 0.1.0 → 0.2.0

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,10 +1,20 @@
 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;
@@ -13,6 +23,18 @@ 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_path: string } | { screen_name: string } | null {
+  if ('path' in location) {
+    if (!location.path) return null;
+    return { screen_path: location.path };
+  }
+  if (!location.screen) return null;
+  return { screen_name: location.screen };
+}
+
 /**
  * Registers the callback invoked when the active screen/path changes.
  * The React Native facade wires this to `UserflowCore.updateScreen`.
@@ -23,9 +45,15 @@ export function setScreenChangeReporter(next: ScreenChangeReporter | null): void
 
 function report(location: ClientLocationUpdate): void {
   currentKey = locationKey(location);
+  currentLocation = location;
   reporter?.(location);
 }
 
+/** 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}. */
 export function enableScreenTracking(): void {
   enabled = true;
@@ -42,13 +70,16 @@ 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
@@ -57,7 +88,10 @@ export function disableScreenTracking(): void {
  * - Expo Router: `{ path: "/settings/billing" }` → wire `screenPath`
  * - 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 +104,22 @@ 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;
 }

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,7 +11,7 @@ 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
+   * Bubble content inset (modal 24 / tooltip 24). Applied as horizontal + bottom
    * padding so the legend aligns with the step body, matching the modal mockup.
    */
   contentPadding: number;

package/src/surfaces/ModalSurface.tsx

@@ -11,20 +11,20 @@ import { Pressable, ScrollView, StyleSheet, View, useWindowDimensions } from 're
 import { RichContentRenderer } from '../content/RichContentRenderer';
 import type { LookupAttribute } from '../content/types';
 
-import { CloseButton } from './CloseButton';
+import { CardFade } from './CardFade';
+import { CLOSE_BUTTON_INSET, CLOSE_BUTTON_SIZE, CloseButton } from './CloseButton';
 import { resolveCloseButtonColor } from './resolveCloseButtonColor';
 import { MadeWithUserflow } from './MadeWithUserflow';
 import { ProgressBar } from './ProgressBar';
 import { ABSOLUTE_FILL } from './absoluteFill';
 import { parseBackdropOpacity } from './parseBackdropOpacity';
 import { resolveStepProgress } from './progress';
-import { useUserflowSafeAreaInsets } from './safeArea';
 import {
   resolveModalButtonsAlign,
   resolveModalCardMaxHeight,
   resolveModalCardMaxWidth,
-  resolveModalCenterPadding,
 } from './resolveModalLayout';
+import { useSurfaceLayoutInsets } from './surfaceLayoutInsets';
 import { resolveBubbleChrome } from './themeChrome';
 
 export interface ModalSurfaceProps {
@@ -37,7 +37,7 @@ export interface ModalSurfaceProps {
 
 /**
  * Modal chrome: full-screen backdrop + centered themed card with TreeDoc body.
- * Also used as a temporary fallback for BUBBLE/HIDDEN until dedicated surfaces.
+ * Also used as a temporary fallback for BUBBLE until a dedicated surface.
  *
  * Touch model: backdrop is a full-screen Pressable; the centering wrapper is
  * `box-none` so taps outside the card hit the backdrop, while the card itself
@@ -63,9 +63,14 @@ export function ModalSurface({
     void engine.endFlow('USER_CLOSED' as EndFlowReasonInput);
   }, [engine]);
 
-  const insets = useUserflowSafeAreaInsets();
+  const onBackdropPress = React.useCallback(() => {
+    if (canDismissBackdrop) {
+      endAsUserClosed();
+    }
+  }, [canDismissBackdrop, endAsUserClosed]);
+
   const windowDims = useWindowDimensions();
-  const centerPadding = resolveModalCenterPadding(insets);
+  const centerPadding = useSurfaceLayoutInsets();
   const cardMaxWidth = resolveModalCardMaxWidth(theme, currentStep.width, windowDims.width);
   const cardMaxHeight = resolveModalCardMaxHeight(windowDims.height, centerPadding);
   const buttonsAlign = resolveModalButtonsAlign(theme, windowDims.width);
@@ -73,6 +78,9 @@ export function ModalSurface({
   const progressBottom = theme.progressBarEnabled && theme.progressBarPosition === 'BOTTOM';
   const showBranding = session.flow.company.flowBranding;
   const contentPadding = chrome.contentPadding;
+  const closeClearance = CLOSE_BUTTON_INSET + CLOSE_BUTTON_SIZE;
+  const scrollPaddingTop = showClose ? Math.max(contentPadding, closeClearance) : contentPadding;
+  const scrollPaddingRight = showClose ? Math.max(contentPadding, closeClearance) : contentPadding;
 
   return (
     <View style={styles.root} testID="userflow-modal-surface" pointerEvents="box-none">
@@ -82,8 +90,7 @@ export function ModalSurface({
         accessibilityLabel={canDismissBackdrop ? 'Dismiss' : undefined}
         accessibilityElementsHidden={!canDismissBackdrop}
         importantForAccessibility={canDismissBackdrop ? 'yes' : 'no-hide-descendants'}
-        disabled={!canDismissBackdrop}
-        onPress={canDismissBackdrop ? endAsUserClosed : undefined}
+        onPress={onBackdropPress}
         style={[
           ABSOLUTE_FILL,
           {
@@ -94,7 +101,7 @@ export function ModalSurface({
       />
 
       <View style={[styles.center, centerPadding]} pointerEvents="box-none">
-        <View
+        <CardFade
           testID="userflow-modal-card"
           accessibilityViewIsModal
           pointerEvents="auto"
@@ -103,7 +110,6 @@ export function ModalSurface({
             styles.cardShadow,
             {
               maxWidth: cardMaxWidth,
-              maxHeight: cardMaxHeight,
               width: '100%',
               borderRadius: chrome.borderRadius,
             },
@@ -116,13 +122,10 @@ export function ModalSurface({
               styles.cardFill,
               {
                 borderRadius: chrome.borderRadius,
+                maxHeight: cardMaxHeight,
               },
             ]}
           >
-            {showClose ? (
-              <CloseButton onPress={endAsUserClosed} color={resolveCloseButtonColor(theme)} />
-            ) : null}
-
             {progressTop ? (
               <ProgressBar
                 enabled
@@ -140,8 +143,9 @@ export function ModalSurface({
               contentContainerStyle={[
                 styles.scrollContent,
                 {
-                  paddingHorizontal: contentPadding,
-                  paddingTop: contentPadding,
+                  paddingLeft: contentPadding,
+                  paddingRight: scrollPaddingRight,
+                  paddingTop: scrollPaddingTop,
                   paddingBottom: showBranding ? 0 : contentPadding,
                 },
               ]}
@@ -150,24 +154,30 @@ export function ModalSurface({
               bounces={false}
               showsVerticalScrollIndicator
             >
-              <RichContentRenderer
-                content={currentStep.content}
-                buttons={currentStep.buttons}
-                theme={theme}
-                sessionData={session.data}
-                lookupAttribute={lookupAttribute}
-                defaultButtonsAlign={buttonsAlign}
-                onActions={(actions) => {
-                  void engine.handleActions(actions);
-                }}
-              />
-              <MadeWithUserflow
-                company={session.flow.company}
-                color={theme.fontColor}
-                contentPadding={contentPadding}
-                embedded
-              />
+              <View testID="userflow-modal-content" style={styles.content}>
+                <RichContentRenderer
+                  content={currentStep.content}
+                  buttons={currentStep.buttons}
+                  theme={theme}
+                  sessionData={session.data}
+                  lookupAttribute={lookupAttribute}
+                  defaultButtonsAlign={buttonsAlign}
+                  heading1FontWeight="normal"
+                  onActions={(actions) => {
+                    void engine.handleActions(actions);
+                  }}
+                />
+                <MadeWithUserflow
+                  company={session.flow.company}
+                  color={theme.fontColor}
+                  contentPadding={contentPadding}
+                  embedded
+                />
+              </View>
             </ScrollView>
+            {showClose ? (
+              <CloseButton onPress={endAsUserClosed} color={resolveCloseButtonColor(theme)} />
+            ) : null}
 
             {progressBottom ? (
               <ProgressBar
@@ -180,7 +190,7 @@ export function ModalSurface({
               />
             ) : null}
           </View>
-        </View>
+        </CardFade>
       </View>
     </View>
   );
@@ -205,11 +215,14 @@ const styles = StyleSheet.create({
     flexShrink: 1,
   },
   scroll: {
-    flexGrow: 0,
+    flexGrow: 1,
     flexShrink: 1,
     minHeight: 0,
   },
   scrollContent: {
     flexGrow: 1,
   },
+  content: {
+    position: 'relative',
+  },
 });