@userflow-tech/react-native 0.5.0 → 0.7.0

package/src/anchors/useUserflowAnchor.ts

@@ -1,7 +1,6 @@
 import * as React from 'react';
-import type { View } from 'react-native';
 
-import { anchorRegistry, type AnchorHost } from './AnchorRegistry';
+import { anchorRegistry, type AnchorHost, type MeasurableNode } from './AnchorRegistry';
 
 /**
  * Register a view as a manual Userflow tooltip / embed target.
@@ -29,7 +28,7 @@ import { anchorRegistry, type AnchorHost } from './AnchorRegistry';
  *
  * Phase 3 resolves targets via `step.selector.css` (leading `#` stripped).
  */
-export function useUserflowAnchor(id: string): React.RefCallback<View> {
+export function useUserflowAnchor(id: string): React.RefCallback<MeasurableNode> {
   const hostRef = React.useRef<AnchorHost | null>(null);
   const idRef = React.useRef(id);
 
@@ -55,7 +54,7 @@ export function useUserflowAnchor(id: string): React.RefCallback<View> {
     };
   }, []);
 
-  return React.useCallback((node: View | null) => {
+  return React.useCallback((node: MeasurableNode | null) => {
     const previous = hostRef.current;
     const currentId = idRef.current;
     if (previous) {
@@ -73,7 +72,7 @@ export function useUserflowAnchor(id: string): React.RefCallback<View> {
       },
       node,
       scrollIntoView: () => {
-        const scrollable = node as View & {
+        const scrollable = node as MeasurableNode & {
           scrollIntoView?: (options?: { block?: string; inline?: string }) => void;
         };
         if (typeof scrollable.scrollIntoView === 'function') {

package/src/anchors/useUserflowScrollContainer.ts

@@ -1,15 +1,16 @@
 import * as React from 'react';
-import type { NativeScrollEvent, NativeSyntheticEvent, ScrollView } from 'react-native';
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
 
 import {
   createScrollContainerHost,
   scrollContainerRegistry,
   type ScrollContainerHost,
+  type ScrollContainerNode,
 } from './ScrollContainerRegistry';
 
 export interface UserflowScrollContainerProps {
   /** Attach to the host ScrollView (or merge with an existing ref). */
-  ref: React.RefCallback<ScrollView>;
+  ref: React.RefCallback<ScrollContainerNode>;
   /** Forward to ScrollView so content offsets stay in sync for scroll-into-view. */
   onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
   /** Required for frequent offset updates while scrolling. */
@@ -42,7 +43,7 @@ export function useUserflowScrollContainer(
   onScrollProp?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void,
 ): UserflowScrollContainerProps {
   const hostRef = React.useRef<ScrollContainerHost | null>(null);
-  const nodeRef = React.useRef<ScrollView | null>(null);
+  const nodeRef = React.useRef<ScrollContainerNode | null>(null);
   const offsetRef = React.useRef({ x: 0, y: 0 });
 
   React.useEffect(() => {
@@ -55,7 +56,7 @@ export function useUserflowScrollContainer(
     };
   }, []);
 
-  const ref = React.useCallback((node: ScrollView | null) => {
+  const ref = React.useCallback((node: ScrollContainerNode | null) => {
     const previous = hostRef.current;
     if (previous) {
       scrollContainerRegistry.unregister(previous);

package/src/authoring/ElementPickerOverlay.tsx

@@ -1,7 +1,15 @@
 import * as React from 'react';
-import { StyleSheet, View, type GestureResponderEvent, type ViewStyle } from 'react-native';
+import {
+  Dimensions,
+  Keyboard,
+  StyleSheet,
+  View,
+  type GestureResponderEvent,
+  type ViewStyle,
+} from 'react-native';
 
 import { pointInRect, TARGET_PRESS_TAP_SLOP } from '../anchors/targetPressMonitor';
+import { WindowOverlayHost } from '../runtime/WindowOverlayHost';
 import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
 import {
   useReportAuthoringBottomHeight,
@@ -25,8 +33,10 @@ import {
   defaultCandidateIndex,
   hitTestAt,
   nextContainingIndex,
+  remeasureCandidates,
   type HitCandidate,
   type HitRect,
+  type ModalMiss,
   type PickTarget,
 } from './hitTest';
 
@@ -46,6 +56,10 @@ const WARNING_HELPER =
   'Element may have an unreliable ID. This element may be selected but could break later on.';
 const ERROR_LABEL = 'Can’t select this element';
 const ERROR_HELPER = 'Element ID not found — select a different element';
+const UNPLACEABLE_SHEET_HELPER =
+  'Can’t tell where this sheet is on screen — in Navigate screens, close the keyboard or expand the sheet';
+const BEHIND_SHEET_HELPER =
+  'This part of the screen is behind the sheet — select inside the sheet, or close it in Navigate screens';
 const ONBOARDING_COPY = 'Double tap anywhere to access the menu';
 const RETURN_NUDGE_TITLE = 'Return to the Userflow app';
 const RETURN_NUDGE_BODY =
@@ -71,6 +85,28 @@ function waitForCapturePaint(): Promise<void> {
   });
 }
 
+interface TapHits {
+  hits: HitCandidate[];
+  /** Why a tap on a presented sheet found nothing, so the helper can say so. */
+  modalMiss: ModalMiss | null;
+}
+
+async function hitsAtTap(pageX: number, pageY: number): Promise<TapHits> {
+  let modalMiss: ModalMiss | null = null;
+  const hits = await hitTestAt(pageX, pageY, {
+    onModalMiss: (miss) => {
+      modalMiss = miss;
+    },
+  });
+  return { hits, modalMiss };
+}
+
+function modalMissHelper(miss: ModalMiss | null): string | null {
+  if (miss === 'unplaceable') return UNPLACEABLE_SHEET_HELPER;
+  if (miss === 'outside') return BEHIND_SHEET_HELPER;
+  return null;
+}
+
 function ringStyle(rect: HitRect, inset: number): ViewStyle {
   return {
     position: 'absolute',
@@ -86,6 +122,10 @@ function ringStyle(rect: HitRect, inset: number): ViewStyle {
  * Overlay chrome for in-app element picking. Mounted by UserflowProvider;
  * renders nothing until {@link elementPickerController.beginSelection}.
  * Every pick shows the menu and onboarding tooltip.
+ *
+ * Drawn in {@link WindowOverlayHost} so native modal screens on iOS cannot
+ * cover it. It mounts only while there is something to show, so the window
+ * container exists only for the pick.
  */
 export function ElementPickerOverlay(): React.ReactElement | null {
   const [state, setState] = React.useState<ElementPickerState>(() =>
@@ -248,12 +288,12 @@ export function ElementPickerOverlay(): React.ReactElement | null {
     }
   }, [phase]);
 
-  const applySelection = React.useCallback((hits: HitCandidate[]) => {
+  const applySelection = React.useCallback(({ hits, modalMiss }: TapHits) => {
     if (hits.length === 0) {
       setCandidates([]);
       setIndex(0);
       setSelection('error-no-element');
-      setStatus(null);
+      setStatus(modalMissHelper(modalMiss));
       return;
     }
     const nextIndex = defaultCandidateIndex(hits);
@@ -264,11 +304,11 @@ export function ElementPickerOverlay(): React.ReactElement | null {
   }, []);
 
   const applyHits = React.useCallback(
-    (hits: HitCandidate[]) => {
+    (tapHits: TapHits) => {
       if (modeRef.current !== 'select') return;
       lastTapRef.current = null;
       setChromeVisible(true);
-      applySelection(hits);
+      applySelection(tapHits);
     },
     [applySelection],
   );
@@ -279,7 +319,7 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       const gen = tapGenRef.current;
       setBusy(true);
       setStatus(null);
-      const hitsPromise = hitTestAt(pageX, pageY);
+      const hitsPromise = hitsAtTap(pageX, pageY);
       const wait = new Promise<void>((resolve) => {
         applyResolveRef.current = resolve;
         applyTimerRef.current = setTimeout(() => {
@@ -290,9 +330,9 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       });
       void (async () => {
         try {
-          const [hits] = await Promise.all([hitsPromise, wait]);
+          const [tapHits] = await Promise.all([hitsPromise, wait]);
           if (tapGenRef.current !== gen) return;
-          applyHits(hits);
+          applyHits(tapHits);
         } finally {
           if (tapGenRef.current === gen) setBusy(false);
         }
@@ -316,8 +356,7 @@ export function ElementPickerOverlay(): React.ReactElement | null {
       setBusy(true);
       setStatus(null);
       try {
-        const hits = await hitTestAt(pageX, pageY);
-        applySelection(hits);
+        applySelection(await hitsAtTap(pageX, pageY));
       } finally {
         setBusy(false);
       }
@@ -377,6 +416,41 @@ export function ElementPickerOverlay(): React.ReactElement | null {
     [hideOrShowChrome, onTap, scheduleSelection, selected, selection],
   );
 
+  // The keyboard opening or closing moves a sheet under the selection, and a
+  // rotation moves everything. Measure the selection again so the ring, re-tap
+  // cycling, the crop and the rect sent to the Builder follow it.
+  const candidatesRef = React.useRef(candidates);
+  candidatesRef.current = candidates;
+  const hasSelection = candidates.length > 0;
+  React.useEffect(() => {
+    if (!hasSelection) return;
+    let latest = 0;
+    const refresh = () => {
+      const run = (latest += 1);
+      const before = candidatesRef.current;
+      void remeasureCandidates(before).then((next) => {
+        if (run !== latest || candidatesRef.current !== before) return;
+        if (next) {
+          setCandidates(next);
+          return;
+        }
+        setCandidates([]);
+        setIndex(0);
+        setSelection('idle');
+        setStatus(null);
+      });
+    };
+    const subscriptions = [
+      Keyboard.addListener('keyboardDidShow', refresh),
+      Keyboard.addListener('keyboardDidHide', refresh),
+      Dimensions.addEventListener('change', refresh),
+    ];
+    return () => {
+      latest += 1;
+      for (const subscription of subscriptions) subscription.remove();
+    };
+  }, [hasSelection]);
+
   const deselect = React.useCallback(() => {
     setCandidates([]);
     setIndex(0);
@@ -459,172 +533,174 @@ export function ElementPickerOverlay(): React.ReactElement | null {
   const tooltipVisible = state.active && showOnboarding && chromeVisible && phase === 'selecting';
 
   return (
-    <View pointerEvents="box-none" style={styles.root} testID="userflow-element-picker">
-      {returnNudge && !state.active ? (
-        <ChromeDialog
-          body={RETURN_NUDGE_BODY}
-          onClose={dismissReturnNudge}
-          title={RETURN_NUDGE_TITLE}
-        >
-          <ChromeButton
-            accessibilityLabel="Okay"
-            flex
-            label="Okay"
-            onPress={dismissReturnNudge}
-            testID="userflow-element-picker-return-okay"
-          />
-        </ChromeDialog>
-      ) : null}
-      {state.active && (phase === 'selecting' || phase === 'blocked') ? (
-        <View pointerEvents="none" style={styles.dim} testID="userflow-element-picker-dim" />
-      ) : null}
-
-      {state.active && selected ? (
-        <>
-          {/*
-           * Painter only. TooltipCutout's band pointerEvents follow the end-user
-           * surface-interaction setting; the capture layer above absorbs every
-           * touch first so that flag cannot leak into picking.
-           */}
-          <TooltipCutout
-            backdropColor={chromeOverlay.color}
-            backdropOpacity={chromeOverlay.opacity}
-            targetBlocked={false}
-            targetRect={{
-              top: selected.rect.y,
-              left: selected.rect.x,
-              width: selected.rect.width,
-              height: selected.rect.height,
-            }}
-          />
-          <View
-            pointerEvents="none"
-            style={[
-              ringStyle(selected.rect, 5),
-              { borderWidth: 4, borderColor: chromeColors.focusRing },
-            ]}
-            testID="userflow-element-picker-focus-ring"
-          />
+    <WindowOverlayHost>
+      <View pointerEvents="box-none" style={styles.root} testID="userflow-element-picker">
+        {returnNudge && !state.active ? (
+          <ChromeDialog
+            body={RETURN_NUDGE_BODY}
+            onClose={dismissReturnNudge}
+            title={RETURN_NUDGE_TITLE}
+          >
+            <ChromeButton
+              accessibilityLabel="Okay"
+              flex
+              label="Okay"
+              onPress={dismissReturnNudge}
+              testID="userflow-element-picker-return-okay"
+            />
+          </ChromeDialog>
+        ) : null}
+        {state.active && (phase === 'selecting' || phase === 'blocked') ? (
+          <View pointerEvents="none" style={styles.dim} testID="userflow-element-picker-dim" />
+        ) : null}
+
+        {state.active && selected ? (
+          <>
+            {/*
+             * Painter only. TooltipCutout's band pointerEvents follow the end-user
+             * surface-interaction setting; the capture layer above absorbs every
+             * touch first so that flag cannot leak into picking.
+             */}
+            <TooltipCutout
+              backdropColor={chromeOverlay.color}
+              backdropOpacity={chromeOverlay.opacity}
+              targetBlocked={false}
+              targetRect={{
+                top: selected.rect.y,
+                left: selected.rect.x,
+                width: selected.rect.width,
+                height: selected.rect.height,
+              }}
+            />
+            <View
+              pointerEvents="none"
+              style={[
+                ringStyle(selected.rect, 5),
+                { borderWidth: 4, borderColor: chromeColors.focusRing },
+              ]}
+              testID="userflow-element-picker-focus-ring"
+            />
+            <View
+              pointerEvents="none"
+              style={[
+                ringStyle(selected.rect, 1),
+                { borderWidth: 1, borderColor: chromeColors.white },
+              ]}
+              testID="userflow-element-picker-focus-ring-inner"
+            />
+          </>
+        ) : null}
+
+        {state.active && mode === 'select' ? (
           <View
-            pointerEvents="none"
-            style={[
-              ringStyle(selected.rect, 1),
-              { borderWidth: 1, borderColor: chromeColors.white },
-            ]}
-            testID="userflow-element-picker-focus-ring-inner"
+            testID="userflow-element-picker-capture"
+            style={styles.capture}
+            onStartShouldSetResponder={() => true}
+            onResponderGrant={onGrant}
+            onResponderRelease={onRelease}
           />
-        </>
-      ) : null}
-
-      {state.active && mode === 'select' ? (
-        <View
-          testID="userflow-element-picker-capture"
-          style={styles.capture}
-          onStartShouldSetResponder={() => true}
-          onResponderGrant={onGrant}
-          onResponderRelease={onRelease}
-        />
-      ) : null}
-
-      {showChromeBars ? (
-        <ChromeBarTransition
-          edge="top"
-          pointerEvents="box-none"
-          style={styles.top}
-          visible={chromeBarsVisible}
-        >
-          <ChromeTopBar
-            label={barLabel}
-            onMeasureHeight={onMeasureHeight}
-            tone={isError ? 'error' : 'default'}
-            {...(toneIcon ? { icon: toneIcon } : {})}
-          />
-        </ChromeBarTransition>
-      ) : null}
-
-      {tooltipVisible ? (
-        <View pointerEvents="none" style={[styles.tooltip, { top: barHeight }]}>
-          <ChromeTooltip
-            onDismiss={() => {
-              setShowOnboarding(false);
-              setChromeVisible(false);
-            }}
+        ) : null}
+
+        {showChromeBars ? (
+          <ChromeBarTransition
+            edge="top"
+            pointerEvents="box-none"
+            style={styles.top}
+            visible={chromeBarsVisible}
           >
-            {ONBOARDING_COPY}
-          </ChromeTooltip>
-        </View>
-      ) : null}
-
-      {showChromeBars ? (
-        <ChromeBarTransition
-          edge="bottom"
-          pointerEvents="box-none"
-          style={styles.bottom}
-          visible={chromeBarsVisible}
-        >
-          <ChromeBottomSheet
-            helperText={helperText}
-            onMeasureHeight={onMeasureSheetHeight}
-            tone={isError ? 'error' : 'default'}
-            {...(helperIcon ? { helperIcon } : {})}
+            <ChromeTopBar
+              label={barLabel}
+              onMeasureHeight={onMeasureHeight}
+              tone={isError ? 'error' : 'default'}
+              {...(toneIcon ? { icon: toneIcon } : {})}
+            />
+          </ChromeBarTransition>
+        ) : null}
+
+        {tooltipVisible ? (
+          <View pointerEvents="none" style={[styles.tooltip, { top: barHeight }]}>
+            <ChromeTooltip
+              onDismiss={() => {
+                setShowOnboarding(false);
+                setChromeVisible(false);
+              }}
+            >
+              {ONBOARDING_COPY}
+            </ChromeTooltip>
+          </View>
+        ) : null}
+
+        {showChromeBars ? (
+          <ChromeBarTransition
+            edge="bottom"
+            pointerEvents="box-none"
+            style={styles.bottom}
+            visible={chromeBarsVisible}
           >
-            {phase === 'selected' || phase === 'blocked' ? (
-              <>
-                <ChromeButton
-                  accessibilityLabel="Deselect"
-                  label="Deselect"
-                  onPress={deselect}
-                  testID="userflow-element-picker-deselect"
-                  variant="secondary"
-                />
-                <ChromeButton
-                  accessibilityLabel="Confirm element"
-                  disabled={busy || isError}
-                  label="Confirm element"
-                  onPress={() => {
-                    void confirm();
-                  }}
-                  testID="userflow-element-picker-confirm"
-                />
-              </>
-            ) : (
-              <>
-                <ChromeButton
-                  accessibilityLabel="Cancel element selection"
-                  label="Cancel"
-                  onPress={() => elementPickerController.cancel()}
-                  testID="userflow-element-picker-cancel"
-                  variant="secondary"
-                />
-                {phase === 'selecting' ? (
+            <ChromeBottomSheet
+              helperText={helperText}
+              onMeasureHeight={onMeasureSheetHeight}
+              tone={isError ? 'error' : 'default'}
+              {...(helperIcon ? { helperIcon } : {})}
+            >
+              {phase === 'selected' || phase === 'blocked' ? (
+                <>
                   <ChromeButton
-                    accessibilityLabel="Navigate screens"
-                    label="Navigate screens"
-                    onPress={() => {
-                      cancelPendingSelection();
-                      lastTapRef.current = null;
-                      setStatus(null);
-                      setMode('navigate');
-                    }}
-                    testID="userflow-element-picker-navigate"
+                    accessibilityLabel="Deselect"
+                    label="Deselect"
+                    onPress={deselect}
+                    testID="userflow-element-picker-deselect"
+                    variant="secondary"
                   />
-                ) : (
                   <ChromeButton
-                    accessibilityLabel="Select element here"
-                    label="Select element here"
+                    accessibilityLabel="Confirm element"
+                    disabled={busy || isError}
+                    label="Confirm element"
                     onPress={() => {
-                      setStatus(null);
-                      setMode('select');
+                      void confirm();
                     }}
-                    testID="userflow-element-picker-select-here"
+                    testID="userflow-element-picker-confirm"
+                  />
+                </>
+              ) : (
+                <>
+                  <ChromeButton
+                    accessibilityLabel="Cancel element selection"
+                    label="Cancel"
+                    onPress={() => elementPickerController.cancel()}
+                    testID="userflow-element-picker-cancel"
+                    variant="secondary"
                   />
-                )}
-              </>
-            )}
-          </ChromeBottomSheet>
-        </ChromeBarTransition>
-      ) : null}
-    </View>
+                  {phase === 'selecting' ? (
+                    <ChromeButton
+                      accessibilityLabel="Navigate screens"
+                      label="Navigate screens"
+                      onPress={() => {
+                        cancelPendingSelection();
+                        lastTapRef.current = null;
+                        setStatus(null);
+                        setMode('navigate');
+                      }}
+                      testID="userflow-element-picker-navigate"
+                    />
+                  ) : (
+                    <ChromeButton
+                      accessibilityLabel="Select element here"
+                      label="Select element here"
+                      onPress={() => {
+                        setStatus(null);
+                        setMode('select');
+                      }}
+                      testID="userflow-element-picker-select-here"
+                    />
+                  )}
+                </>
+              )}
+            </ChromeBottomSheet>
+          </ChromeBarTransition>
+        ) : null}
+      </View>
+    </WindowOverlayHost>
   );
 }