@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/surfaces/cardTransition.ts

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { Animated } from 'react-native';
+
+/** Outgoing card leaves fast; the incoming one gets web's `opacity 250ms` feel. */
+export const CARD_EXIT_MS = 120;
+export const CARD_ENTER_MS = 200;
+
+export type CardTransitionPhase = 'entering' | 'exiting';
+
+const CardTransitionContext = React.createContext<CardTransitionPhase | null>(null);
+
+export const CardTransitionProvider = CardTransitionContext.Provider;
+
+/**
+ * Phase of the surrounding step transition, or `null` outside one.
+ *
+ * Surfaces use this to hold side effects while they fade out: an exiting card is
+ * still mounted for `CARD_EXIT_MS`, and anything it measures or arms in that
+ * window belongs to a step the user has already left.
+ */
+export function useCardTransitionPhase(): CardTransitionPhase | null {
+  return React.useContext(CardTransitionContext);
+}
+
+/**
+ * Fade for a surface's card chrome, so step swaps move the card alone and leave
+ * the backdrop and cutout steady (same as web, where `FlowChrome` animates the
+ * bubble alone).
+ *
+ * Each card owns its value and starts the fade from its own mount rather than
+ * sharing one animation across the swap. Cards can appear well after the step
+ * changes — `TooltipSurface` renders nothing until its anchor measures — and a
+ * shared animation would already have finished by then, leaving the card at the
+ * stale JS value of 0 forever, since native-driven animations never write back
+ * to JS.
+ *
+ * Returns `null` outside a flow transition (unit tests), leaving opacity alone.
+ */
+export function useCardOpacity(): Animated.Value | null {
+  const phase = React.useContext(CardTransitionContext);
+  const opacityRef = React.useRef<Animated.Value | null>(null);
+  if (phase != null && opacityRef.current == null) {
+    opacityRef.current = new Animated.Value(phase === 'exiting' ? 1 : 0);
+  }
+  const opacity = opacityRef.current;
+
+  React.useLayoutEffect(() => {
+    if (phase == null || opacity == null) {
+      return;
+    }
+    const exiting = phase === 'exiting';
+    // Pin the start point: a native-driven ramp is computed from the JS value,
+    // which the previous native animation left behind.
+    opacity.setValue(exiting ? 1 : 0);
+    const animation = Animated.timing(opacity, {
+      toValue: exiting ? 0 : 1,
+      duration: exiting ? CARD_EXIT_MS : CARD_ENTER_MS,
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => {
+      animation.stop();
+    };
+  }, [opacity, phase]);
+
+  return opacity;
+}

package/src/surfaces/resolveHighlightChrome.ts

@@ -0,0 +1,139 @@
+import type { ThemeFragment } from '@userflow-tech/protocol';
+
+import { foregroundAlpha, isNearWhite } from '../content/themeColor';
+
+export type HighlightType = 'OUTSIDE' | 'INSIDE';
+
+/**
+ * Mobile highlight corner radius when the target's own radius is unknown.
+ * Web copies `getComputedStyle(target).borderRadius`; RN measure cannot.
+ * 8 matches typical controls and the mobile tooltip mockup.
+ */
+export const HIGHLIGHT_CORNER_RADIUS = 8;
+
+/** Crisp focus-ring stroke — the mockup's inner blue line. */
+export const HIGHLIGHT_STROKE_WIDTH = 2;
+
+/** Web theme default (`themes.backdrop_highlight_radius`) — halo thickness. */
+export const HIGHLIGHT_RADIUS_DEFAULT = 4;
+
+/** Web theme default (`themes.backdrop_highlight_spread`) — placement gap only. */
+export const HIGHLIGHT_SPREAD_DEFAULT = 0;
+
+/** Cap the painted halo so it stays a wash, not a second solid stroke. */
+export const HIGHLIGHT_HALO_ALPHA_MAX = 0.32;
+
+export interface HighlightChrome {
+  /** Opaque stroke color (mockup's crisp ring). */
+  color: string;
+  /** Same color at the painted halo alpha. */
+  glowColor: string;
+  opacity: number;
+  /** Halo thickness — web `backdropHighlightRadius`. */
+  radius: number;
+  /** Placement gap only — web `backdropHighlightSpread`. Not stroke width. */
+  spread: number;
+  strokeWidth: number;
+  type: HighlightType;
+  borderRadius: number;
+}
+
+function readNumber(theme: ThemeFragment, key: string, fallback: number): number {
+  const value = theme[key];
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const parsed = parseFloat(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return fallback;
+}
+
+function readString(theme: ThemeFragment, key: string, fallback: string): string {
+  const value = theme[key];
+  return typeof value === 'string' && value.length > 0 ? value : fallback;
+}
+
+function firstString(theme: ThemeFragment, keys: string[], fallback: string): string {
+  for (const key of keys) {
+    const value = theme[key];
+    if (typeof value === 'string' && value.length > 0) return value;
+  }
+  return fallback;
+}
+
+function readHighlightType(theme: ThemeFragment): HighlightType {
+  const raw = theme.backdropHighlightType;
+  if (typeof raw !== 'string') return 'OUTSIDE';
+  return raw.toUpperCase() === 'INSIDE' ? 'INSIDE' : 'OUTSIDE';
+}
+
+function resolveHighlightColor(theme: ThemeFragment): string {
+  const brand = firstString(
+    theme,
+    ['widgetBackgroundColor', 'brandBackgroundColor', 'defaultButtonBackgroundColor'],
+    '#1a57e6',
+  );
+  const explicit = readString(theme, 'backdropHighlightColor', '');
+  if (explicit && !isNearWhite(explicit)) return explicit;
+  return brand;
+}
+
+/**
+ * Web tooltip-backdrop highlight as a mobile focus ring: thin brand stroke +
+ * a single soft halo. Web's default white highlight is treated as unset so it
+ * does not paint a thick white frame on the dimmed cutout.
+ */
+export function resolveHighlightChrome(
+  theme: ThemeFragment,
+  backdropPadding: number = 0,
+): HighlightChrome {
+  const color = resolveHighlightColor(theme);
+  const opacity = parseHighlightOpacity(theme.backdropHighlightOpacity);
+  const radius = Math.max(
+    0,
+    readNumber(theme, 'backdropHighlightRadius', HIGHLIGHT_RADIUS_DEFAULT),
+  );
+  const spread = Math.max(
+    0,
+    readNumber(theme, 'backdropHighlightSpread', HIGHLIGHT_SPREAD_DEFAULT),
+  );
+  const pad = Math.max(0, backdropPadding);
+  const haloAlpha = Math.min(HIGHLIGHT_HALO_ALPHA_MAX, opacity);
+
+  return {
+    color,
+    glowColor: foregroundAlpha(color, haloAlpha),
+    opacity,
+    radius,
+    spread,
+    strokeWidth: HIGHLIGHT_STROKE_WIDTH,
+    type: readHighlightType(theme),
+    borderRadius: HIGHLIGHT_CORNER_RADIUS + pad,
+  };
+}
+
+export function isHighlightVisible(chrome: HighlightChrome): boolean {
+  return chrome.strokeWidth > 0 || chrome.radius > 0;
+}
+
+/**
+ * Extra pixels an OUTSIDE ring extends past the hole: theme spread plus the
+ * painted stroke and halo. Used so the tooltip notch aims at the outer edge
+ * of the focus ring, not the cutout.
+ */
+export function outsideHighlightOutset(chrome: HighlightChrome): number {
+  if (chrome.type !== 'OUTSIDE' || !isHighlightVisible(chrome)) return 0;
+  return chrome.spread + chrome.strokeWidth + chrome.radius;
+}
+
+/** Web default highlight opacity is 0.5 (`themes.backdrop_highlight_opacity`). */
+function parseHighlightOpacity(value: unknown): number {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return Math.min(1, Math.max(0, value));
+  }
+  if (typeof value === 'string') {
+    const parsed = Number.parseFloat(value);
+    if (Number.isFinite(parsed)) return Math.min(1, Math.max(0, parsed));
+  }
+  return 0.5;
+}

package/src/surfaces/resolveModalLayout.ts

@@ -40,20 +40,28 @@ export function resolveModalCardMaxWidth(
   return Math.min(desiredWidth, maxInViewport);
 }
 
-export function resolveModalCenterPadding(insets: {
-  top: number;
-  bottom: number;
-  left: number;
-  right: number;
-}): {
+export function resolveModalCenterPadding(
+  insets: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+  },
+  previewBannerHeight = 0,
+  previewBottomInset = 0,
+): {
   paddingTop: number;
   paddingBottom: number;
   paddingLeft: number;
   paddingRight: number;
 } {
+  const baseTop = Math.max(MODAL_VIEWPORT_PADDING, insets.top + 8);
+  const bannerTop = previewBannerHeight > 0 ? previewBannerHeight + MODAL_VIEWPORT_PADDING : 0;
+  const baseBottom = Math.max(MODAL_VIEWPORT_PADDING, insets.bottom + 8);
+  const bannerBottom = previewBottomInset > 0 ? previewBottomInset + MODAL_VIEWPORT_PADDING : 0;
   return {
-    paddingTop: Math.max(MODAL_VIEWPORT_PADDING, insets.top + 8),
-    paddingBottom: Math.max(MODAL_VIEWPORT_PADDING, insets.bottom + 8),
+    paddingTop: Math.max(baseTop, bannerTop),
+    paddingBottom: Math.max(baseBottom, bannerBottom),
     paddingLeft: Math.max(MODAL_VIEWPORT_PADDING, insets.left + 8),
     paddingRight: Math.max(MODAL_VIEWPORT_PADDING, insets.right + 8),
   };

package/src/surfaces/resolveTooltipLayout.ts

@@ -3,11 +3,7 @@ import type { ViewStyle } from 'react-native';
 
 import type { JustifyContent } from '../content/types';
 
-import {
-  MODAL_COMPACT_LAYOUT_MAX_WIDTH,
-  MODAL_VIEWPORT_PADDING,
-  resolveModalCenterPadding,
-} from './resolveModalLayout';
+import { MODAL_COMPACT_LAYOUT_MAX_WIDTH, MODAL_VIEWPORT_PADDING } from './resolveModalLayout';
 
 /** Screen margin for anchored tooltips (mobile design spec: 24px). */
 export const TOOLTIP_VIEWPORT_PADDING = MODAL_VIEWPORT_PADDING;
@@ -53,15 +49,6 @@ export function resolveTooltipCardLayout(
   return { maxWidth: cardMaxWidth };
 }
 
-export function resolveTooltipCenterPadding(insets: {
-  top: number;
-  bottom: number;
-  left: number;
-  right: number;
-}): ReturnType<typeof resolveModalCenterPadding> {
-  return resolveModalCenterPadding(insets);
-}
-
 /**
  * Web `--userflow-buttons-bubble-justify-content` (bubble + tooltip): default is end.
  */

package/src/surfaces/surfaceInteractionConfig.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether flow surfaces (modals, tooltips) intercept taps on the host app
+ * underneath. Default-on; integrators can restore the legacy pass-through
+ * tooltip backdrop via {@link setSurfaceInteractionBlocking}.
+ */
+
+let surfaceInteractionBlocking = true;
+
+/**
+ * When true (default), tooltip cutout bands and crossfade exit block host taps.
+ * Surfaces read this flag at render time — toggling mid-flow applies on the next
+ * re-render of the active surface tree (same as {@link setScrollPadding}).
+ */
+export function setSurfaceInteractionBlocking(enabled: boolean | null | undefined): void {
+  surfaceInteractionBlocking = enabled ?? true;
+}
+
+export function getSurfaceInteractionBlocking(): boolean {
+  return surfaceInteractionBlocking;
+}
+
+/** Test helper — reset to default (blocking enabled). */
+export function resetSurfaceInteractionConfig(): void {
+  surfaceInteractionBlocking = true;
+}

package/src/surfaces/surfaceLayoutInsets.tsx

@@ -0,0 +1,135 @@
+import * as React from 'react';
+
+import { resolveModalCenterPadding } from './resolveModalLayout';
+import { type EdgeInsets, useUserflowSafeAreaInsets } from './safeArea';
+
+export type SurfaceLayoutPadding = {
+  paddingTop: number;
+  paddingBottom: number;
+  paddingLeft: number;
+  paddingRight: number;
+};
+
+/** Independent writers so preview and picker chrome cannot clobber each other. */
+export type AuthoringChromeInsetSlot = 'preview' | 'picker';
+
+type ChromeInsetHeights = Record<AuthoringChromeInsetSlot, number>;
+
+type ChromeInsetEdges = {
+  top: ChromeInsetHeights;
+  bottom: ChromeInsetHeights;
+};
+
+interface SurfaceLayoutInsetsContextValue {
+  previewBannerHeight: number;
+  previewBottomInset: number;
+  setTopSlotHeight: (slot: AuthoringChromeInsetSlot, height: number) => void;
+  setBottomSlotHeight: (slot: AuthoringChromeInsetSlot, height: number) => void;
+}
+
+function effectiveChromeInsetHeight(heights: ChromeInsetHeights): number {
+  return heights.picker > 0 ? heights.picker : heights.preview;
+}
+
+const SurfaceLayoutInsetsContext = React.createContext<SurfaceLayoutInsetsContextValue>({
+  previewBannerHeight: 0,
+  previewBottomInset: 0,
+  setTopSlotHeight: () => {},
+  setBottomSlotHeight: () => {},
+});
+
+/**
+ * Holds measured authoring chrome heights so modal/tooltip layout can clear
+ * them. The overlay stays full-screen; only card padding grows.
+ *
+ * Preview and picker report into separate slots on each edge. The picker slot
+ * wins while it is non-zero (the preview bar is suppressed for that stretch).
+ */
+export function SurfaceLayoutInsetsProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}): React.ReactElement {
+  const [heights, setHeights] = React.useState<ChromeInsetEdges>({
+    top: { preview: 0, picker: 0 },
+    bottom: { preview: 0, picker: 0 },
+  });
+  const setTopSlotHeight = React.useCallback((slot: AuthoringChromeInsetSlot, height: number) => {
+    setHeights((prev) =>
+      prev.top[slot] === height ? prev : { ...prev, top: { ...prev.top, [slot]: height } },
+    );
+  }, []);
+  const setBottomSlotHeight = React.useCallback(
+    (slot: AuthoringChromeInsetSlot, height: number) => {
+      setHeights((prev) =>
+        prev.bottom[slot] === height
+          ? prev
+          : { ...prev, bottom: { ...prev.bottom, [slot]: height } },
+      );
+    },
+    [],
+  );
+  const previewBannerHeight = effectiveChromeInsetHeight(heights.top);
+  const previewBottomInset = effectiveChromeInsetHeight(heights.bottom);
+  const value = React.useMemo(
+    () => ({ previewBannerHeight, previewBottomInset, setTopSlotHeight, setBottomSlotHeight }),
+    [previewBannerHeight, previewBottomInset, setTopSlotHeight, setBottomSlotHeight],
+  );
+  return (
+    <SurfaceLayoutInsetsContext.Provider value={value}>
+      {children}
+    </SurfaceLayoutInsetsContext.Provider>
+  );
+}
+
+/**
+ * Report an authoring top bar's laid-out height (0 when that bar is hidden).
+ * Defaults to the preview slot; the picker must pass `'picker'`.
+ */
+export function useReportPreviewBannerHeight(
+  slot: AuthoringChromeInsetSlot = 'preview',
+): (height: number) => void {
+  const { setTopSlotHeight } = React.useContext(SurfaceLayoutInsetsContext);
+  return React.useCallback(
+    (height: number) => {
+      setTopSlotHeight(slot, height);
+    },
+    [setTopSlotHeight, slot],
+  );
+}
+
+/**
+ * Report an authoring bottom sheet's laid-out height (0 when that sheet is hidden).
+ * Defaults to the preview slot; the picker must pass `'picker'`.
+ */
+export function useReportAuthoringBottomHeight(
+  slot: AuthoringChromeInsetSlot = 'preview',
+): (height: number) => void {
+  const { setBottomSlotHeight } = React.useContext(SurfaceLayoutInsetsContext);
+  return React.useCallback(
+    (height: number) => {
+      setBottomSlotHeight(slot, height);
+    },
+    [setBottomSlotHeight, slot],
+  );
+}
+
+/**
+ * Padding that keeps flow cards inside the screen: safe area, 24px margin,
+ * and authoring chrome when it is mounted.
+ */
+export function useSurfaceLayoutInsets(): SurfaceLayoutPadding {
+  const safe = useUserflowSafeAreaInsets();
+  const { previewBannerHeight, previewBottomInset } = React.useContext(SurfaceLayoutInsetsContext);
+  return resolveModalCenterPadding(safe, previewBannerHeight, previewBottomInset);
+}
+
+/** @internal */
+export function paddingAsEdgeInsets(padding: SurfaceLayoutPadding): EdgeInsets {
+  return {
+    top: padding.paddingTop,
+    right: padding.paddingRight,
+    bottom: padding.paddingBottom,
+    left: padding.paddingLeft,
+  };
+}

package/src/surfaces/themeChrome.ts

@@ -3,13 +3,16 @@ import type { ViewStyle } from 'react-native';
 
 export type BubbleChromeKind = 'modal' | 'tooltip';
 
+/** Mobile modal/tooltip inset — tighter than web `modalPadding` (default 40). */
+export const BUBBLE_CONTENT_PADDING = 24;
+
 export interface BubbleChrome {
   backgroundColor: string;
   borderRadius: number;
   borderWidth: number;
   borderColor: string;
   notchSize: number;
-  /** Inner content padding (modal: theme `modalPadding` or 32; tooltip/bubble 24). */
+  /** Inner content padding ({@link BUBBLE_CONTENT_PADDING}). */
   contentPadding: number;
   /**
    * Outer shell — shadow + overflow. Tooltips keep overflow visible so the
@@ -59,8 +62,7 @@ export function resolveBubbleChrome(
   const borderColor = readString(theme, 'bubbleBorderColor', 'transparent');
   // Web default tooltipNotchSize is 10.
   const notchSize = Math.max(0, readNumber(theme, 'tooltipNotchSize', 10));
-  const contentPadding =
-    kind === 'tooltip' ? 24 : Math.max(0, readNumber(theme, 'modalPadding', 32));
+  const contentPadding = BUBBLE_CONTENT_PADDING;
 
   // Web often leaves `backgroundColor` empty and paints via `mainBackgroundColor`.
   // An empty string makes RN cards fully transparent (missing-target UI looks broken).