@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/authoring/ElementPickerOverlay.tsx

@@ -0,0 +1,553 @@
+import * as React from 'react';
+import { StyleSheet, View, type GestureResponderEvent, type ViewStyle } from 'react-native';
+
+import { pointInRect, TARGET_PRESS_TAP_SLOP } from '../anchors/targetPressMonitor';
+import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+import {
+  useReportAuthoringBottomHeight,
+  useReportPreviewBannerHeight,
+} from '../surfaces/surfaceLayoutInsets';
+import { TooltipCutout } from '../surfaces/tooltip/TooltipCutout';
+
+import { capturePickerScreenshot } from './capturePickerScreenshot';
+import { ChromeBarTransition, useChromeBarMounted } from './chrome/ChromeBarTransition';
+import { ChromeBottomSheet } from './chrome/ChromeBottomSheet';
+import { ChromeButton } from './chrome/ChromeButton';
+import { ChromeTooltip } from './chrome/ChromeTooltip';
+import { ChromeTopBar } from './chrome/ChromeTopBar';
+import { chromeColors, chromeOverlay, chromeRadius } from './chrome/tokens';
+import { DOUBLE_TAP_WINDOW_MS, isDoubleTap, type TapSample } from './doubleTap';
+import { elementPickerController, type ElementPickerState } from './elementPickerController';
+import {
+  validatePickerFingerprint,
+  type PickerFingerprintFailure,
+} from './fingerprintFromInstance';
+import { hitTestAt, nextContainingIndex, type HitCandidate, type HitRect } from './hitTest';
+
+function statusForValidationFailure(reason: PickerFingerprintFailure['reason']): string {
+  if (reason === 'not-unique' || reason === 'ambiguous-explicit-id') {
+    return 'This element is not uniquely identifiable — add a testID or userflowId, or it may match the wrong item at play time.';
+  }
+  if (reason === 'wrong-instance') {
+    return 'That fingerprint matches a different element — pick again or add a testID.';
+  }
+  return 'Could not uniquely match that element at play time.';
+}
+
+type PickerMode = 'navigate' | 'select';
+type PickerPhase = 'selecting' | 'navigating' | 'selected';
+
+const CONFIRM_HELPER = 'Navigate back to the Userflow app after confirming';
+const ONBOARDING_COPY = 'Double tap anywhere to access the menu';
+
+/** Yield until chrome has left the native tree so captureScreen cannot include it. */
+function waitForCapturePaint(): Promise<void> {
+  return new Promise((resolve) => {
+    const raf = globalThis.requestAnimationFrame;
+    if (typeof raf === 'function') {
+      raf.call(globalThis, () => {
+        raf.call(globalThis, () => resolve());
+      });
+      return;
+    }
+    setTimeout(resolve, 0);
+  });
+}
+
+function ringStyle(rect: HitRect, inset: number): ViewStyle {
+  return {
+    position: 'absolute',
+    left: rect.x - inset,
+    top: rect.y - inset,
+    width: rect.width + inset * 2,
+    height: rect.height + inset * 2,
+    borderRadius: chromeRadius.lg,
+  };
+}
+
+/**
+ * Overlay chrome for in-app element picking. Mounted by UserflowProvider;
+ * renders nothing until {@link elementPickerController.beginSelection}.
+ */
+export function ElementPickerOverlay(): React.ReactElement | null {
+  const [state, setState] = React.useState<ElementPickerState>(() =>
+    elementPickerController.getState(),
+  );
+  const [mode, setMode] = React.useState<PickerMode>('select');
+  const [candidates, setCandidates] = React.useState<HitCandidate[]>([]);
+  const [index, setIndex] = React.useState(0);
+  const [busy, setBusy] = React.useState(false);
+  const [status, setStatus] = React.useState<string | null>(null);
+  const [chromeVisible, setChromeVisible] = React.useState(true);
+  const [hidingForCapture, setHidingForCapture] = React.useState(false);
+  const [showOnboarding, setShowOnboarding] = React.useState(false);
+  const [barHeight, setBarHeight] = React.useState(0);
+  const [sheetHeight, setSheetHeight] = React.useState(0);
+  const tapStartRef = React.useRef<{ pageX: number; pageY: number } | null>(null);
+  const lastTapRef = React.useRef<TapSample | null>(null);
+  const tapGenRef = React.useRef(0);
+  const applyTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const applyResolveRef = React.useRef<(() => void) | null>(null);
+  const modeRef = React.useRef<PickerMode>('select');
+  const armedRequestIdRef = React.useRef<string | undefined>(undefined);
+  const setBannerHeight = useReportPreviewBannerHeight('picker');
+  const setBottomHeight = useReportAuthoringBottomHeight('picker');
+
+  const cancelPendingSelection = React.useCallback(() => {
+    tapGenRef.current += 1;
+    if (applyTimerRef.current != null) {
+      clearTimeout(applyTimerRef.current);
+      applyTimerRef.current = null;
+    }
+    const resolveWait = applyResolveRef.current;
+    applyResolveRef.current = null;
+    resolveWait?.();
+    setBusy(false);
+  }, []);
+
+  const resetTransient = React.useCallback(
+    (options?: { resetCaptureHide?: boolean }) => {
+      cancelPendingSelection();
+      lastTapRef.current = null;
+      setMode('select');
+      setCandidates([]);
+      setIndex(0);
+      setBusy(false);
+      setStatus(null);
+      setChromeVisible(true);
+      setBarHeight(0);
+      setSheetHeight(0);
+      modeRef.current = 'select';
+      if (options?.resetCaptureHide !== false) {
+        setHidingForCapture(false);
+      }
+    },
+    [cancelPendingSelection],
+  );
+
+  React.useEffect(() => {
+    return elementPickerController.subscribe((next) => {
+      setState(next);
+      if (!next.active) {
+        armedRequestIdRef.current = undefined;
+        resetTransient({ resetCaptureHide: false });
+        setShowOnboarding(false);
+        return;
+      }
+      // Successful confirm leaves hidingForCapture true so chrome does not
+      // flash back during teardown. Clear it with the new session's setState
+      // so the first paint of this pick has bars.
+      if (armedRequestIdRef.current !== next.requestId) {
+        setHidingForCapture(false);
+      }
+    });
+  }, [resetTransient]);
+
+  React.useEffect(() => {
+    if (!state.active || state.requestId == null) return;
+    if (armedRequestIdRef.current === state.requestId) return;
+    armedRequestIdRef.current = state.requestId;
+    resetTransient();
+    setShowOnboarding(true);
+  }, [resetTransient, state.active, state.requestId]);
+
+  React.useEffect(() => {
+    return () => {
+      cancelPendingSelection();
+    };
+  }, [cancelPendingSelection]);
+
+  React.useEffect(() => {
+    if (!state.active) {
+      setBannerHeight(0);
+      return;
+    }
+    if (hidingForCapture) {
+      return;
+    }
+    if (!chromeVisible) {
+      setBannerHeight(0);
+      return;
+    }
+    if (barHeight > 0) {
+      setBannerHeight(barHeight);
+    }
+  }, [barHeight, chromeVisible, hidingForCapture, setBannerHeight, state.active]);
+
+  React.useEffect(() => {
+    if (!state.active) {
+      setBottomHeight(0);
+      return;
+    }
+    if (hidingForCapture) {
+      return;
+    }
+    if (!chromeVisible) {
+      setBottomHeight(0);
+      return;
+    }
+    if (sheetHeight > 0) {
+      setBottomHeight(sheetHeight);
+    }
+  }, [chromeVisible, hidingForCapture, setBottomHeight, sheetHeight, state.active]);
+
+  const onMeasureHeight = React.useCallback((height: number) => {
+    setBarHeight(Math.max(0, height));
+  }, []);
+
+  const onMeasureSheetHeight = React.useCallback((height: number) => {
+    setSheetHeight(Math.max(0, height));
+  }, []);
+
+  const selected = candidates[index] ?? null;
+  const phase: PickerPhase = selected ? 'selected' : mode === 'select' ? 'selecting' : 'navigating';
+  modeRef.current = mode;
+
+  // Bars slide/fade in with the picker, out on double-tap hide, and out again
+  // on teardown. Keep them mounted through the exit even after the picker goes
+  // inactive; the dim, capture, and spotlight below drop immediately instead.
+  const chromeBarsVisible = state.active && chromeVisible && !hidingForCapture;
+  const chromeBarsMounted = useChromeBarMounted(chromeBarsVisible);
+  const showChromeBars = hidingForCapture ? false : chromeBarsMounted;
+
+  React.useEffect(() => {
+    if (phase !== 'selecting') {
+      setShowOnboarding(false);
+    }
+  }, [phase]);
+
+  const applyHits = React.useCallback((hits: HitCandidate[]) => {
+    if (modeRef.current !== 'select') return;
+    lastTapRef.current = null;
+    setChromeVisible(true);
+    if (hits.length === 0) {
+      setCandidates([]);
+      setIndex(0);
+      setStatus('No stamped element under that tap.');
+      return;
+    }
+    setCandidates(hits);
+    setIndex(0);
+    setStatus(null);
+  }, []);
+
+  const scheduleSelection = React.useCallback(
+    (pageX: number, pageY: number) => {
+      cancelPendingSelection();
+      const gen = tapGenRef.current;
+      setBusy(true);
+      setStatus(null);
+      const hitsPromise = hitTestAt(pageX, pageY);
+      const wait = new Promise<void>((resolve) => {
+        applyResolveRef.current = resolve;
+        applyTimerRef.current = setTimeout(() => {
+          applyTimerRef.current = null;
+          applyResolveRef.current = null;
+          resolve();
+        }, DOUBLE_TAP_WINDOW_MS);
+      });
+      void (async () => {
+        try {
+          const [hits] = await Promise.all([hitsPromise, wait]);
+          if (tapGenRef.current !== gen) return;
+          applyHits(hits);
+        } finally {
+          if (tapGenRef.current === gen) setBusy(false);
+        }
+      })();
+    },
+    [applyHits, cancelPendingSelection],
+  );
+
+  const onTap = React.useCallback(
+    async (pageX: number, pageY: number) => {
+      if (selected && candidates.length > 1 && pointInRect(pageX, pageY, selected.rect)) {
+        setIndex((current) => nextContainingIndex(candidates, current));
+        setStatus(null);
+        return;
+      }
+      setBusy(true);
+      setStatus(null);
+      try {
+        const hits = await hitTestAt(pageX, pageY);
+        if (hits.length === 0) {
+          setCandidates([]);
+          setIndex(0);
+          setStatus('No stamped element under that tap.');
+          return;
+        }
+        setCandidates(hits);
+        setIndex(0);
+      } finally {
+        setBusy(false);
+      }
+    },
+    [candidates, selected],
+  );
+
+  const onGrant = React.useCallback((event: GestureResponderEvent) => {
+    const { pageX, pageY } = event.nativeEvent;
+    tapStartRef.current = { pageX, pageY };
+  }, []);
+
+  const onRelease = React.useCallback(
+    (event: GestureResponderEvent) => {
+      const start = tapStartRef.current;
+      tapStartRef.current = null;
+      if (!start) return;
+      const { pageX, pageY } = event.nativeEvent;
+      const dx = pageX - start.pageX;
+      const dy = pageY - start.pageY;
+      if (dx * dx + dy * dy > TARGET_PRESS_TAP_SLOP * TARGET_PRESS_TAP_SLOP) return;
+
+      const sample: TapSample = { pageX, pageY, timestamp: Date.now() };
+      if (!selected && isDoubleTap(lastTapRef.current, sample)) {
+        cancelPendingSelection();
+        lastTapRef.current = null;
+        setShowOnboarding(false);
+        setChromeVisible((visible) => !visible);
+        return;
+      }
+      lastTapRef.current = sample;
+
+      if (selected) {
+        void onTap(pageX, pageY);
+        return;
+      }
+      scheduleSelection(pageX, pageY);
+    },
+    [cancelPendingSelection, onTap, scheduleSelection, selected],
+  );
+
+  const deselect = React.useCallback(() => {
+    setCandidates([]);
+    setIndex(0);
+    setStatus(null);
+    setChromeVisible(true);
+  }, []);
+
+  const confirm = React.useCallback(async () => {
+    if (!selected) return;
+    const requestId = elementPickerController.getState().requestId;
+    if (!requestId) return;
+    setBusy(true);
+    setStatus(null);
+    try {
+      const validated = validatePickerFingerprint(selected.instance);
+      if (!validated.ok) {
+        setStatus(statusForValidationFailure(validated.reason));
+        return;
+      }
+      setHidingForCapture(true);
+      await waitForCapturePaint();
+      const screenshot = await capturePickerScreenshot(selected.rect);
+      const delivered = await elementPickerController.commit(
+        {
+          instance: selected.instance,
+          autoData: validated.autoData,
+          text: selected.instance.childText ?? selected.instance.accessibilityLabel ?? null,
+          rect: selected.rect,
+          ...(screenshot ? { screenshot } : {}),
+        },
+        requestId,
+      );
+      if (!delivered && elementPickerController.getState().requestId === requestId) {
+        setHidingForCapture(false);
+        setStatus("Couldn't send to Builder");
+      }
+    } catch {
+      setHidingForCapture(false);
+      setStatus('Could not serialize that element.');
+    } finally {
+      setBusy(false);
+    }
+  }, [selected]);
+
+  if (!state.active && !chromeBarsMounted) return null;
+
+  const barLabel =
+    phase === 'selected'
+      ? 'Confirm selected element'
+      : phase === 'selecting'
+        ? 'Tap an element to select it'
+        : 'Navigate screens';
+
+  const helperText = status ?? (phase === 'selected' ? CONFIRM_HELPER : undefined);
+  const tooltipVisible = state.active && showOnboarding && chromeVisible && phase === 'selecting';
+
+  return (
+    <View pointerEvents="box-none" style={styles.root} testID="userflow-element-picker">
+      {state.active && phase === 'selecting' ? (
+        <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
+          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} />
+        </ChromeBarTransition>
+      ) : null}
+
+      {tooltipVisible ? (
+        <View pointerEvents="none" style={[styles.tooltip, { top: barHeight }]}>
+          <ChromeTooltip
+            onDismiss={() => {
+              setShowOnboarding(false);
+            }}
+          >
+            {ONBOARDING_COPY}
+          </ChromeTooltip>
+        </View>
+      ) : null}
+
+      {showChromeBars ? (
+        <ChromeBarTransition
+          edge="bottom"
+          pointerEvents="box-none"
+          style={styles.bottom}
+          visible={chromeBarsVisible}
+        >
+          <ChromeBottomSheet helperText={helperText} onMeasureHeight={onMeasureSheetHeight}>
+            {phase === 'selected' ? (
+              <>
+                <ChromeButton
+                  accessibilityLabel="Deselect"
+                  label="Deselect"
+                  onPress={deselect}
+                  testID="userflow-element-picker-deselect"
+                  variant="secondary"
+                />
+                <ChromeButton
+                  accessibilityLabel="Confirm element"
+                  disabled={busy}
+                  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' ? (
+                  <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>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    ...ABSOLUTE_FILL,
+    zIndex: 1100,
+  },
+  dim: {
+    ...ABSOLUTE_FILL,
+    backgroundColor: chromeOverlay.color,
+    opacity: chromeOverlay.opacity,
+  },
+  capture: {
+    ...ABSOLUTE_FILL,
+  },
+  top: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    right: 0,
+  },
+  tooltip: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    alignItems: 'center',
+  },
+  bottom: {
+    position: 'absolute',
+    bottom: 0,
+    left: 0,
+    right: 0,
+  },
+});

package/src/authoring/capturePickerScreenshot.ts

@@ -0,0 +1,90 @@
+import { Dimensions } from 'react-native';
+
+import type { ElementPickerScreenshot } from './elementPickerController';
+import type { HitRect } from './hitTest';
+
+const MAX_CAPTURE_WIDTH = 480;
+
+const MISSING_VIEW_SHOT_WARNING =
+  '[Userflow] Required peer react-native-view-shot is not installed; ' +
+  'skipping picker screenshot. Install react-native-view-shot (>=5.0.0) and rebuild native.';
+
+interface ViewShotModule {
+  captureScreen: (options: {
+    format?: 'jpg' | 'png';
+    quality?: number;
+    result?: 'tmpfile' | 'base64' | 'data-uri';
+    width?: number;
+    height?: number;
+  }) => Promise<string>;
+}
+
+let didWarnMissingViewShot = false;
+
+function warnMissingViewShot(): void {
+  if (didWarnMissingViewShot) return;
+  didWarnMissingViewShot = true;
+  if (__DEV__) {
+    // eslint-disable-next-line no-console -- intentional missing-required-peer diagnostic
+    console.warn(MISSING_VIEW_SHOT_WARNING);
+  }
+}
+
+function loadViewShot(): ViewShotModule | null {
+  try {
+    // Required peer; degrade if unlinked or the JS package is missing.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
+    return require('react-native-view-shot') as ViewShotModule;
+  } catch {
+    warnMissingViewShot();
+    return null;
+  }
+}
+
+/**
+ * Capture a downscaled JPEG of the current screen and map `rect` (window DIP)
+ * onto the captured pixel grid. Returns null when the native module is missing
+ * or capture fails.
+ */
+export async function capturePickerScreenshot(
+  rect: HitRect,
+): Promise<ElementPickerScreenshot | null> {
+  const viewShot = loadViewShot();
+  if (!viewShot?.captureScreen) return null;
+
+  try {
+    const window = Dimensions.get('window');
+    const winW = window.width || 1;
+    const winH = window.height || 1;
+    const captureWidth = Math.min(Math.round(winW), MAX_CAPTURE_WIDTH);
+    const captureHeight = Math.max(1, Math.round(winH * (captureWidth / winW)));
+
+    const dataUrl = await viewShot.captureScreen({
+      format: 'jpg',
+      quality: 0.55,
+      result: 'data-uri',
+      width: captureWidth,
+      height: captureHeight,
+    });
+    if (typeof dataUrl !== 'string' || dataUrl.length === 0) return null;
+
+    const sx = captureWidth / winW;
+    const sy = captureHeight / winH;
+    return {
+      dataUrl,
+      width: captureWidth,
+      height: captureHeight,
+      targetX1: Math.round(rect.x * sx),
+      targetY1: Math.round(rect.y * sy),
+      targetX2: Math.round((rect.x + rect.width) * sx),
+      targetY2: Math.round((rect.y + rect.height) * sy),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** @internal */
+export function resetViewShotWarningForTests(): void {
+  didWarnMissingViewShot = false;
+}