@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/authoring/ElementPickerOverlay.tsx

@@ -0,0 +1,662 @@
+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 { ChromeDialog } from './chrome/ChromeDialog';
+import { ChromeTooltip } from './chrome/ChromeTooltip';
+import { ChromeTopBar } from './chrome/ChromeTopBar';
+import { doubleTapMonitor } from './chrome/doubleTapMonitor';
+import { chromeColors, chromeOverlay, chromeRadius } from './chrome/tokens';
+import { DOUBLE_TAP_WINDOW_MS, isDoubleTap, type TapSample } from './doubleTap';
+import { elementPickerController, type ElementPickerState } from './elementPickerController';
+import { assessPickerTarget, type PickerSelectionAssessment } from './fingerprintFromInstance';
+import {
+  defaultCandidateIndex,
+  hitTestAt,
+  nextContainingIndex,
+  type HitCandidate,
+  type HitRect,
+  type PickTarget,
+} from './hitTest';
+
+function targetText(target: PickTarget): string | null {
+  if (target.source === 'registry') {
+    return target.instance.childText ?? target.instance.accessibilityLabel ?? null;
+  }
+  return target.descriptor.childText ?? target.descriptor.accessibilityLabel ?? null;
+}
+
+type PickerMode = 'navigate' | 'select';
+type PickerPhase = 'selecting' | 'navigating' | 'selected' | 'blocked';
+type SelectionState = 'idle' | 'ok' | 'warning' | 'error-no-element' | 'error-unresolvable';
+
+const CONFIRM_HELPER = 'Return to the Userflow app after confirming';
+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 ONBOARDING_COPY = 'Double tap anywhere to access the menu';
+const RETURN_NUDGE_TITLE = 'Return to the Userflow app';
+const RETURN_NUDGE_BODY =
+  'The element was selected successfully. You may now return to the Userflow app to continue editing your flow.';
+
+function selectionFromAssessment(assessment: PickerSelectionAssessment): SelectionState {
+  if (assessment.kind === 'error') return 'error-unresolvable';
+  if (assessment.kind === 'warning') return 'warning';
+  return 'ok';
+}
+
+/** 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}.
+ * Every pick shows the menu and onboarding tooltip.
+ */
+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 [selection, setSelection] = React.useState<SelectionState>('idle');
+  const [chromeVisible, setChromeVisible] = React.useState(true);
+  const [hidingForCapture, setHidingForCapture] = React.useState(false);
+  const [showOnboarding, setShowOnboarding] = React.useState(false);
+  const [returnNudge, setReturnNudge] = 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);
+      setSelection('idle');
+      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 pick's setState so
+      // the first paint of this pick has its bars.
+      if (armedRequestIdRef.current !== next.requestId && next.requestId != null) {
+        setHidingForCapture(false);
+        setReturnNudge(false);
+        setChromeVisible(true);
+        setShowOnboarding(true);
+      }
+    });
+  }, [resetTransient]);
+
+  React.useEffect(() => {
+    if (!state.active || state.requestId == null) return;
+    if (armedRequestIdRef.current === state.requestId) return;
+    armedRequestIdRef.current = state.requestId;
+    resetTransient();
+    setShowOnboarding(true);
+    setReturnNudge(false);
+  }, [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 =
+    selection === 'error-no-element'
+      ? 'blocked'
+      : 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 applySelection = React.useCallback((hits: HitCandidate[]) => {
+    if (hits.length === 0) {
+      setCandidates([]);
+      setIndex(0);
+      setSelection('error-no-element');
+      setStatus(null);
+      return;
+    }
+    const nextIndex = defaultCandidateIndex(hits);
+    setCandidates(hits);
+    setIndex(nextIndex);
+    setSelection(selectionFromAssessment(assessPickerTarget(hits[nextIndex]!.target)));
+    setStatus(null);
+  }, []);
+
+  const applyHits = React.useCallback(
+    (hits: HitCandidate[]) => {
+      if (modeRef.current !== 'select') return;
+      lastTapRef.current = null;
+      setChromeVisible(true);
+      applySelection(hits);
+    },
+    [applySelection],
+  );
+
+  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)) {
+        const next = nextContainingIndex(candidates, index);
+        setIndex(next);
+        const nextHit = candidates[next];
+        if (nextHit) {
+          setSelection(selectionFromAssessment(assessPickerTarget(nextHit.target)));
+        }
+        setStatus(null);
+        return;
+      }
+      setBusy(true);
+      setStatus(null);
+      try {
+        const hits = await hitTestAt(pageX, pageY);
+        applySelection(hits);
+      } finally {
+        setBusy(false);
+      }
+    },
+    [applySelection, candidates, index, selected],
+  );
+
+  const hideOrShowChrome = React.useCallback(() => {
+    cancelPendingSelection();
+    lastTapRef.current = null;
+    setShowOnboarding(false);
+    setChromeVisible((visible) => !visible);
+  }, [cancelPendingSelection]);
+
+  // Navigate mode unmounts the capture layer so the host app can receive
+  // touches. Double-tap still has to reach the bars, via the screen-wide
+  // monitor the preview bar uses. Select mode keeps its own capture handler
+  // and must not also subscribe, or one double tap would toggle twice.
+  React.useEffect(() => {
+    if (!state.active || mode !== 'navigate') return;
+    const subscription = { onDoubleTap: hideOrShowChrome };
+    doubleTapMonitor.set(subscription);
+    return () => {
+      doubleTapMonitor.clearIfCurrent(subscription);
+    };
+  }, [hideOrShowChrome, mode, state.active]);
+
+  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() };
+      const engaged = selected != null || selection === 'error-no-element';
+      if (!engaged && isDoubleTap(lastTapRef.current, sample)) {
+        hideOrShowChrome();
+        return;
+      }
+      lastTapRef.current = sample;
+
+      if (engaged) {
+        void onTap(pageX, pageY);
+        return;
+      }
+      scheduleSelection(pageX, pageY);
+    },
+    [hideOrShowChrome, onTap, scheduleSelection, selected, selection],
+  );
+
+  const deselect = React.useCallback(() => {
+    setCandidates([]);
+    setIndex(0);
+    setSelection('idle');
+    setStatus(null);
+    setChromeVisible(true);
+  }, []);
+
+  const confirm = React.useCallback(async () => {
+    if (!selected) return;
+    if (selection === 'error-unresolvable' || selection === 'error-no-element') return;
+    const requestId = elementPickerController.getState().requestId;
+    if (!requestId) return;
+    setBusy(true);
+    setStatus(null);
+    try {
+      const assessed = assessPickerTarget(selected.target);
+      if (assessed.kind === 'error') {
+        setSelection('error-unresolvable');
+        return;
+      }
+      setHidingForCapture(true);
+      await waitForCapturePaint();
+      const screenshot = await capturePickerScreenshot(selected.rect);
+      const delivered = await elementPickerController.commit(
+        {
+          target: selected.target,
+          autoData: assessed.autoData,
+          text: targetText(selected.target),
+          rect: selected.rect,
+          ...(screenshot ? { screenshot } : {}),
+        },
+        requestId,
+      );
+      if (delivered && !elementPickerController.getState().active) {
+        setReturnNudge(true);
+      } else 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, selection]);
+
+  const dismissReturnNudge = () => {
+    setReturnNudge(false);
+  };
+
+  if (!state.active && !chromeBarsMounted && !returnNudge) return null;
+
+  const isError = selection === 'error-no-element' || selection === 'error-unresolvable';
+  const toneIcon = isError
+    ? { name: 'triangle-exclamation' as const, tintColor: chromeColors.dangerAccent }
+    : selection === 'warning'
+      ? { name: 'circle-exclamation' as const, tintColor: chromeColors.warningAccent }
+      : undefined;
+
+  const barLabel = isError
+    ? ERROR_LABEL
+    : phase === 'selected' || selection === 'warning'
+      ? 'Confirm selected element'
+      : phase === 'selecting'
+        ? 'Tap an element to select it'
+        : 'Navigate screens';
+
+  const helperText =
+    status ??
+    (isError
+      ? ERROR_HELPER
+      : selection === 'warning'
+        ? WARNING_HELPER
+        : phase === 'selected'
+          ? CONFIRM_HELPER
+          : undefined);
+  const helperIcon = status ? undefined : toneIcon;
+  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"
+          />
+          <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}
+            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}
+        >
+          <ChromeBottomSheet
+            helperText={helperText}
+            onMeasureHeight={onMeasureSheetHeight}
+            tone={isError ? 'error' : 'default'}
+            {...(helperIcon ? { helperIcon } : {})}
+          >
+            {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' ? (
+                  <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,
+  },
+});