@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/authoring/chrome/DoubleTapBridge.tsx

@@ -0,0 +1,60 @@
+import * as React from 'react';
+import { StyleSheet, View, type GestureResponderEvent } from 'react-native';
+
+import { changedTouchPoints, forEachChangedTouch } from '../../runtime/changedTouchPoints';
+
+import { doubleTapMonitor } from './doubleTapMonitor';
+
+export interface DoubleTapBridgeProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Observes screen-wide touches for {@link doubleTapMonitor} without claiming
+ * the responder. Must wrap **both** host app content and authoring chrome —
+ * preview-bar taps never bubble through `TargetPressBridge`, which only
+ * wraps the app tree.
+ */
+export function DoubleTapBridge({ children }: DoubleTapBridgeProps): React.ReactElement {
+  const onTouchStart = React.useCallback((event: GestureResponderEvent) => {
+    forEachChangedTouch(event, (identifier, pageX, pageY) => {
+      doubleTapMonitor.handleTouchStart(identifier, pageX, pageY);
+    });
+  }, []);
+
+  const onTouchEnd = React.useCallback((event: GestureResponderEvent) => {
+    forEachChangedTouch(event, (identifier, pageX, pageY) => {
+      doubleTapMonitor.handleTouchEnd(identifier, pageX, pageY);
+    });
+  }, []);
+
+  const onTouchCancel = React.useCallback((event: GestureResponderEvent) => {
+    const points = changedTouchPoints(event);
+    if (points.length === 0) {
+      doubleTapMonitor.cancelTouch();
+      return;
+    }
+    for (const touch of points) {
+      doubleTapMonitor.cancelTouch(touch.identifier);
+    }
+  }, []);
+
+  return (
+    <View
+      style={styles.root}
+      collapsable={false}
+      onTouchStart={onTouchStart}
+      onTouchEnd={onTouchEnd}
+      onTouchCancel={onTouchCancel}
+      testID="userflow-double-tap-bridge"
+    >
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+  },
+});

package/src/authoring/chrome/doubleTapMonitor.ts

@@ -0,0 +1,80 @@
+import {
+  TARGET_PRESS_TAP_SLOP,
+  type TouchIdentifier,
+  type TouchPoint,
+} from '../../anchors/targetPressMonitor';
+import { isDoubleTap, type TapSample } from '../doubleTap';
+
+export interface DoubleTapSubscription {
+  onDoubleTap: () => void;
+}
+
+/**
+ * Screen-wide double-tap observer. Never claims the responder — the host app
+ * keeps scrolling and tapping. Used by preview-mode chrome, which has no
+ * capture layer of its own.
+ *
+ * Distinct from `targetPressMonitor`: that singleton is bound to a tooltip
+ * target rect and fires `onPress`, not a double-tap toggle.
+ */
+export class DoubleTapMonitor {
+  private subscription: DoubleTapSubscription | null = null;
+  private touchStarts = new Map<TouchIdentifier, TouchPoint>();
+  private lastTap: TapSample | null = null;
+
+  set(subscription: DoubleTapSubscription | null): void {
+    this.subscription = subscription;
+    if (!subscription) {
+      this.touchStarts.clear();
+      this.lastTap = null;
+    }
+  }
+
+  handleTouchStart(identifier: TouchIdentifier, pageX: number, pageY: number): void {
+    if (!this.subscription) {
+      this.touchStarts.clear();
+      return;
+    }
+    this.touchStarts.set(identifier, { pageX, pageY });
+  }
+
+  handleTouchEnd(identifier: TouchIdentifier, pageX: number, pageY: number): void {
+    const start = this.touchStarts.get(identifier) ?? null;
+    this.touchStarts.delete(identifier);
+    const sub = this.subscription;
+    if (!start || !sub) return;
+
+    const dx = pageX - start.pageX;
+    const dy = pageY - start.pageY;
+    if (dx * dx + dy * dy > TARGET_PRESS_TAP_SLOP * TARGET_PRESS_TAP_SLOP) {
+      this.lastTap = null;
+      return;
+    }
+
+    const sample: TapSample = { pageX, pageY, timestamp: Date.now() };
+    if (isDoubleTap(this.lastTap, sample)) {
+      this.lastTap = null;
+      sub.onDoubleTap();
+      return;
+    }
+    this.lastTap = sample;
+  }
+
+  cancelTouch(identifier?: TouchIdentifier): void {
+    if (identifier == null) {
+      this.touchStarts.clear();
+      return;
+    }
+    this.touchStarts.delete(identifier);
+  }
+
+  /** Test helper. */
+  resetForTests(): void {
+    this.subscription = null;
+    this.touchStarts.clear();
+    this.lastTap = null;
+  }
+}
+
+/** Shared singleton used by PreviewModeBanner and DoubleTapBridge. */
+export const doubleTapMonitor = new DoubleTapMonitor();

package/src/authoring/chrome/tokens.ts

@@ -0,0 +1,106 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+/**
+ * Authoring-chrome tokens from the Userflow React Native Figma file
+ * (`BojC6qdlFUytdD1bRsNLV8`). These are independent of end-user flow
+ * `ThemeFragment` — pairing / picker UI is not themed by the server.
+ *
+ * Typography omits `fontFamily` so RN uses SF Pro / Roboto.
+ */
+
+export const chromeColors = {
+  primaryText: '#132b39',
+  invertedText: '#ffffff',
+  blue500: '#1a57e6',
+  overlay: 'rgba(0, 0, 0, 0.2)',
+  /** Figma Colors/Effect/Focus Ring (`#2f69ee59`). */
+  focusRing: 'rgba(47, 105, 238, 0.35)',
+  bgMiddle: '#f4f8fb',
+  danger: '#57000e',
+  white: '#ffffff',
+  /** Figma Shadow/Button. Opacity is applied in `chromeShadows`. */
+  shadowButton: 'rgb(54, 107, 214)',
+} as const;
+
+/**
+ * `chromeColors.overlay` split for TooltipCutout's composite-once contract
+ * (`backdropColor` + `backdropOpacity` rather than a single rgba string).
+ */
+export const chromeOverlay = { color: '#000000', opacity: 0.2 } as const;
+
+export const chromeSpace = {
+  0: 0,
+  8: 8,
+  12: 12,
+  16: 16,
+  20: 20,
+  24: 24,
+} as const;
+
+export const chromeRadius = {
+  md: 4,
+  lg: 8,
+  fullyRounded: 9999,
+} as const;
+
+export const chromeText = {
+  barTitle: { fontSize: 16, fontWeight: '600', lineHeight: 20 },
+  buttonLabel: { fontSize: 16, fontWeight: '600', lineHeight: 20 },
+  /** Figma Labels/SM Bold — bottom-sheet helper copy (3869:521). */
+  labelSmBold: { fontSize: 14, fontWeight: '600', lineHeight: 16 },
+  dialogTitle: { fontSize: 18, fontWeight: '500', lineHeight: 24 },
+  dialogBody: { fontSize: 16, fontWeight: '400', lineHeight: 24 },
+  tooltip: { fontSize: 14, fontWeight: '500', lineHeight: 16 },
+} as const satisfies Record<string, TextStyle>;
+
+/**
+ * Figma drop shadows approximated as RN `shadow*` + Android `elevation`.
+ * There is no shared chrome shadow helper — TooltipBubble's elevation pairing
+ * is tooltip-specific and is not reused here.
+ */
+export const chromeShadows = {
+  /** Shadow/Button — primary pill. */
+  button: {
+    shadowColor: chromeColors.shadowButton,
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.5,
+    shadowRadius: 8,
+    elevation: 4,
+  },
+  /** Shadow/Button (Subtle) — secondary / icon pills. */
+  buttonSubtle: {
+    shadowColor: chromeColors.shadowButton,
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.5,
+    shadowRadius: 4,
+    elevation: 2,
+  },
+  /** Shadow/Card — full-bleed top/bottom bars. */
+  card: {
+    shadowColor: chromeColors.primaryText,
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.1,
+    shadowRadius: 12,
+    elevation: 8,
+  },
+  /** Shadow/Default (Subtle) — onboarding tooltip. */
+  tooltip: {
+    shadowColor: chromeColors.primaryText,
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.1,
+    shadowRadius: 12,
+    elevation: 4,
+  },
+  /**
+   * Dialog card. Carries the values ChromeDialog shipped with (shadowRadius 6 /
+   * elevation 6). Figma names this Shadow/Default (Subtle) — the same token as
+   * `tooltip` — but the radius-convention audit across chrome shadows is Phase 6.
+   */
+  dialog: {
+    shadowColor: chromeColors.primaryText,
+    shadowOffset: { width: 0, height: 4 },
+    shadowOpacity: 0.1,
+    shadowRadius: 6,
+    elevation: 6,
+  },
+} as const satisfies Record<string, ViewStyle>;

package/src/authoring/doubleTap.ts

@@ -0,0 +1,27 @@
+export const DOUBLE_TAP_WINDOW_MS = 300;
+export const DOUBLE_TAP_SLOP = 40;
+
+export interface TapSample {
+  pageX: number;
+  pageY: number;
+  timestamp: number;
+}
+
+/**
+ * True when `next` lands close enough in space and time to `prev` to count as
+ * the second half of a double tap. Inclusive on both the time window and slop
+ * so a tap at exactly the boundary still toggles chrome rather than selecting.
+ */
+export function isDoubleTap(
+  prev: TapSample | null,
+  next: TapSample,
+  windowMs: number = DOUBLE_TAP_WINDOW_MS,
+  slop: number = DOUBLE_TAP_SLOP,
+): boolean {
+  if (prev == null) return false;
+  const dt = next.timestamp - prev.timestamp;
+  if (dt < 0 || dt > windowMs) return false;
+  const dx = next.pageX - prev.pageX;
+  const dy = next.pageY - prev.pageY;
+  return dx * dx + dy * dy <= slop * slop;
+}

package/src/authoring/elementPickerController.ts

@@ -0,0 +1,135 @@
+import type { AutoAnchorInstance } from '../anchors/AutoAnchorRegistry';
+
+import type { HitRect } from './hitTest';
+
+export interface ElementPickerScreenshot {
+  dataUrl: string;
+  width: number;
+  height: number;
+  targetX1: number;
+  targetY1: number;
+  targetX2: number;
+  targetY2: number;
+}
+
+export interface ElementPickerResult {
+  instance: AutoAnchorInstance;
+  autoData: string;
+  text?: string | null;
+  rect: HitRect;
+  screenshot?: ElementPickerScreenshot;
+}
+
+export interface ElementPickerRequest {
+  /** Caller-supplied id (pairing `idempotency_key`). Minted when omitted. */
+  requestId?: string;
+  elementType?: string | null;
+  onResult: (result: ElementPickerResult) => void | Promise<void>;
+  onCancel?: () => void;
+}
+
+export interface ElementPickerState {
+  active: boolean;
+  requestId?: string;
+  elementType?: string | null;
+}
+
+export type ElementPickerListener = (state: ElementPickerState) => void;
+
+const IDLE: ElementPickerState = { active: false };
+
+interface ActiveRequest extends ElementPickerRequest {
+  requestId: string;
+}
+
+/**
+ * Module singleton for the in-app element picker. Pairing glue (and the QA
+ * harness) call {@link beginSelection}; {@link ElementPickerOverlay} reads
+ * state and commits/cancels.
+ */
+export class ElementPickerController {
+  private request: ActiveRequest | null = null;
+  private nextId = 1;
+  private readonly listeners = new Set<ElementPickerListener>();
+
+  getState(): ElementPickerState {
+    if (!this.request) return { ...IDLE };
+    return {
+      active: true,
+      requestId: this.request.requestId,
+      ...(this.request.elementType != null ? { elementType: this.request.elementType } : {}),
+    };
+  }
+
+  subscribe(listener: ElementPickerListener): () => void {
+    this.listeners.add(listener);
+    listener(this.getState());
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  beginSelection(request: ElementPickerRequest): void {
+    if (this.request) {
+      this.request.onCancel?.();
+    }
+    const requestId = request.requestId ?? `pick-${this.nextId++}`;
+    this.request = { ...request, requestId };
+    this.emit();
+  }
+
+  /**
+   * Deliver `result` to the active request. When `expectedId` is passed, a
+   * mismatch (stale Confirm after a newer `beginSelection`) is a no-op.
+   * Omitting `expectedId` is for synchronous tests/QA.
+   *
+   * If `onResult` returns a rejected promise (e.g. relay not connected), the
+   * request stays active so the overlay can retry. Ack timeouts should be
+   * swallowed by the caller of `onResult`, not thrown here.
+   */
+  async commit(result: ElementPickerResult, expectedId?: string): Promise<boolean> {
+    const req = this.request;
+    if (!req) return false;
+    if (expectedId != null && req.requestId !== expectedId) return false;
+    try {
+      await req.onResult(result);
+    } catch {
+      return this.request === req ? false : true;
+    }
+    if (this.request !== req) return true;
+    this.request = null;
+    this.emit();
+    return true;
+  }
+
+  cancel(): void {
+    const req = this.request;
+    this.request = null;
+    this.emit();
+    if (!req) return;
+    try {
+      req.onCancel?.();
+    } catch {
+      // Authoring callbacks must not break the host.
+    }
+  }
+
+  resetForTests(): void {
+    this.request = null;
+    this.nextId = 1;
+    this.listeners.clear();
+  }
+
+  private emit(): void {
+    const state = this.getState();
+    for (const listener of this.listeners) {
+      try {
+        listener(state);
+      } catch {
+        // listeners are infrastructure
+      }
+    }
+  }
+}
+
+export const elementPickerController = new ElementPickerController();

package/src/authoring/fingerprintFromInstance.ts

@@ -0,0 +1,152 @@
+import {
+  encodeMobileAutoData,
+  MOBILE_AUTODATA_VERSION,
+  MOBILE_FINGERPRINT_VERSION,
+  type DeviceMetadata,
+  type IdentityStrength,
+  type MobileAutoData,
+  type MobileFingerprint,
+} from '@userflow-tech/protocol';
+import { Dimensions, Platform } from 'react-native';
+
+import { autoAnchorRegistry, type AutoAnchorInstance } from '../anchors/AutoAnchorRegistry';
+import * as semanticMatcher from '../anchors/semanticMatcher';
+import type { MatchMissReason } from '../anchors/semanticMatcher';
+import { getCurrentScreenLocation } from '../screenTracker';
+
+function deriveIdentityStrength(inst: AutoAnchorInstance): IdentityStrength {
+  const hasId = !!(
+    inst.userflowId ||
+    inst.testID ||
+    inst.manualId ||
+    (inst.nativeID && !inst.nativeID.startsWith('uf_'))
+  );
+  if (hasId) return 'id';
+  if (inst.childText || inst.accessibilityLabel || inst.iconName || inst.imageSrc) {
+    return 'content';
+  }
+  return 'structural';
+}
+
+function screenFromLocation(): { screenId: string; screenName?: string } {
+  const location = getCurrentScreenLocation();
+  if (!location) return { screenId: 'unknown' };
+  if ('path' in location) return { screenId: location.path, screenName: location.path };
+  return { screenId: location.screen, screenName: location.screen };
+}
+
+function deviceMetadata(): DeviceMetadata | undefined {
+  try {
+    const window = Dimensions.get('window');
+    return {
+      screenWidth: window.width,
+      screenHeight: window.height,
+      scale: window.scale,
+      platform: Platform.OS === 'android' ? 'android' : 'ios',
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Inverse of `scoreInstance` field-reads: snapshot a live registry instance
+ * into the fingerprint the scored matcher consumes at play time.
+ */
+export function fingerprintFromInstance(inst: AutoAnchorInstance): MobileFingerprint {
+  autoAnchorRegistry.refreshLiveContent([
+    inst,
+    ...autoAnchorRegistry.orderedSiblingsIncludingSelf(inst.instanceId),
+  ]);
+  const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
+  return {
+    version: MOBILE_FINGERPRINT_VERSION,
+    structuralPath: inst.structuralPath,
+    templatePath: inst.templatePath,
+    ...(inst.instanceScope ? { instanceScope: inst.instanceScope } : {}),
+    kind: inst.kind,
+    role: inst.role,
+    ...(inst.manualId ? { manualId: inst.manualId } : {}),
+    ...(inst.userflowId ? { userflowId: inst.userflowId } : {}),
+    ...(inst.testID ? { testID: inst.testID } : {}),
+    ...(inst.nativeID ? { nativeID: inst.nativeID } : {}),
+    ...(inst.childText ? { childText: inst.childText } : {}),
+    ...(inst.accessibilityLabel ? { accessibilityLabel: inst.accessibilityLabel } : {}),
+    ...(inst.childShape ? { childShape: inst.childShape } : {}),
+    ...(inst.iconName ? { iconName: inst.iconName } : {}),
+    ...(inst.imageSrc ? { imageSrc: inst.imageSrc } : {}),
+    ancestors: inst.ancestors ? [...inst.ancestors] : [],
+    previousSiblings: window.previous,
+    nextSiblings: window.next,
+    ...(inst.ordinal !== undefined ? { ordinal: inst.ordinal } : {}),
+    ...(inst.siblingIndex !== undefined ? { siblingIndex: inst.siblingIndex } : {}),
+    isPressable: inst.isPressable,
+    ambiguous: inst.ambiguous,
+    identityStrength: deriveIdentityStrength(inst),
+  };
+}
+
+/** Wrap a live instance in the `FlowSelector.autoData` envelope. */
+export function autoDataFromInstance(inst: AutoAnchorInstance): MobileAutoData {
+  const fingerprint = fingerprintFromInstance(inst);
+  const { screenId, screenName } = screenFromLocation();
+  const device = deviceMetadata();
+  const selector = inst.structuralPath || inst.templatePath || inst.registryKey;
+  return {
+    version: MOBILE_AUTODATA_VERSION,
+    platform: 'react-native',
+    selector,
+    displayName: inst.kind,
+    ...(inst.manualId ? { anchorId: inst.manualId, manualId: inst.manualId } : {}),
+    primary: {
+      ufid: inst.structuralPath || inst.registryKey,
+      ...(inst.nativeID ? { nativeId: inst.nativeID } : {}),
+    },
+    fingerprint,
+    screenId,
+    ...(screenName ? { screenName } : {}),
+    platformData: {
+      ...(inst.testID ? { testID: inst.testID } : {}),
+      ...(inst.accessibilityLabel ? { accessibilityLabel: inst.accessibilityLabel } : {}),
+      ...(inst.childText ? { childText: inst.childText } : {}),
+      ...(inst.childShape ? { childShape: inst.childShape } : {}),
+      ...(inst.structuralPath ? { structuralPath: inst.structuralPath } : {}),
+      ...(inst.templatePath ? { templatePath: inst.templatePath } : {}),
+      ...(inst.instanceScope ? { instanceScope: inst.instanceScope } : {}),
+      isPressable: inst.isPressable,
+    },
+    ...(device ? { device } : {}),
+  };
+}
+
+export function encodeInstanceAutoData(inst: AutoAnchorInstance): string {
+  return encodeMobileAutoData(autoDataFromInstance(inst));
+}
+
+export type PickerFingerprintFailure = {
+  ok: false;
+  reason: MatchMissReason | 'wrong-instance';
+};
+
+export type PickerFingerprintSuccess = {
+  ok: true;
+  autoData: string;
+};
+
+export type PickerFingerprintValidation = PickerFingerprintSuccess | PickerFingerprintFailure;
+
+/**
+ * Encode `inst` and run the play-time matcher. Confirm may proceed only on a
+ * unique hit of this same instance.
+ */
+export function validatePickerFingerprint(inst: AutoAnchorInstance): PickerFingerprintValidation {
+  const autoData = encodeInstanceAutoData(inst);
+  const match = semanticMatcher.matchAutoData(autoData);
+  if (!match.instance) {
+    return { ok: false, reason: match.reason ?? 'no-candidates' };
+  }
+  if (match.instance.instanceId !== inst.instanceId) {
+    return { ok: false, reason: 'wrong-instance' };
+  }
+  return { ok: true, autoData };
+}