@userflow-tech/react-native 0.1.0 → 0.2.0

package/src/surfaces/tooltip/TooltipBubble.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import {
+  Platform,
   StyleSheet,
   View,
   type LayoutChangeEvent,
@@ -7,6 +8,7 @@ import {
   type ViewStyle,
 } from 'react-native';
 
+import { CardFade } from '../CardFade';
 import { ABSOLUTE_FILL } from '../absoluteFill';
 import type { BubbleChrome } from '../themeChrome';
 
@@ -19,17 +21,32 @@ export interface TooltipBubbleProps {
   style?: StyleProp<ViewStyle>;
   onLayout?: (event: LayoutChangeEvent) => void;
   children: React.ReactNode;
+  /** Pixel cap for the fill so tall content scrolls instead of painting past the viewport. */
+  maxHeight?: number;
+  /**
+   * Hide the pointer when the clamped card is no longer adjacent to the
+   * target. Defaults to true so isolated chrome tests keep the diamond.
+   */
+  showNotch?: boolean;
 }
 
 /**
  * Tooltip chrome shell: diamond notch + card fill sharing one shadow family.
  *
  * Web draws card and notch as a single silhouette under `filter: drop-shadow`.
- * RN has no silhouette filter, so the card uses a dedicated shadow layer and
- * `elevation` on the fill (Android). The notch itself is not shadowed — a
- * second blurred shadow on the rotated square leaves a gray band at the pointer
- * base when it points up into the anchor. An inset fill diamond on top erases
- * that seam (and bordered stroke gaps) without clipping the outer tip.
+ * RN has no silhouette filter — on both platforms a view's shadow is derived
+ * from that view's own bounds, and the notch hangs at a negative offset
+ * *outside* the card's bounds. No shadow cast by the card or by the shell can
+ * ever reach it, so the diamond has to cast its own, and the two shadows
+ * together trace the card + tip outline.
+ *
+ * The order is what keeps that honest. A shadow is painted with its own layer,
+ * so only a layer drawn *before* the notch may cast a card-sized shadow —
+ * otherwise it lands on the exposed tip as a gray band. Hence: shadow layer,
+ * then notch, then the fill and seam cover, both silent.
+ *
+ * iOS gets `shadow*` on the notch (`elevation` is inert there); Android gets
+ * `elevation`, which is the only shadow it honors on a rotated view.
  */
 export function TooltipBubble({
   chrome,
@@ -37,16 +54,45 @@ export function TooltipBubble({
   style,
   onLayout,
   children,
+  maxHeight,
+  showNotch: showNotchProp = true,
 }: TooltipBubbleProps): React.ReactElement {
-  const showNotch = chrome.notchSize > 0;
+  const showNotch = showNotchProp && chrome.notchSize > 0;
   const bordered = chrome.borderWidth > 0;
+  // Only bordered themes need the diamond seam cover, to keep the stroke even
+  // where the notch meets the card. It is opaque and sits above the fill, so
+  // borderless themes must skip it or it paints over the card's own text.
+  const showSeamCover = showNotch && bordered;
+  // Borderless: a 2pt strip of fill color on the pointer edge covers the iOS
+  // hairline where `overflow: hidden` anti-aliases the card against the dim.
+  // Inset by the radius so it does not square off the corners. Bordered cards
+  // already have a stroke there — painting fill over it would hide the border.
+  const notchEdge = showNotch && !bordered ? protrudingNotchEdge(notchPosition) : null;
   // Web paints the notch with border color when bordered, otherwise the card
   // fill. Never use literal `transparent` — that hides the pointer entirely.
   const notchColor =
     bordered && chrome.borderColor !== 'transparent' ? chrome.borderColor : chrome.backgroundColor;
-  // Android draws by elevation, so every layer above the card shadow has to be
+  // Android draws by elevation, so every layer above the shadow layer has to be
   // raised with it or the opaque shadow layer paints over the card body.
   const elevation = chrome.shadowStyle.elevation ?? 0;
+  // Raising a layer on Android also makes it cast its own elevation shadow,
+  // painted directly beneath that layer, so anything above the notch has to
+  // give its shadow up. `shadowColor: 'transparent'` does that on both
+  // platforms — it is the one shadow prop Android honors (API 28+), and on iOS
+  // it cancels the shadow outright — so this needs no platform split.
+  const raisedSilent: ViewStyle = { elevation, shadowColor: 'transparent' };
+  // The one caster above the shadow layer. iOS reads this diamond's own
+  // bounds, and the 45° layer rotation carries the shadow with it, so the tip
+  // gets a shadow shaped like the tip.
+  const notchShadow: ViewStyle =
+    Platform.OS === 'ios'
+      ? {
+          shadowColor: chrome.shadowStyle.shadowColor,
+          shadowOffset: chrome.shadowStyle.shadowOffset,
+          shadowOpacity: chrome.shadowStyle.shadowOpacity,
+          shadowRadius: chrome.shadowStyle.shadowRadius,
+        }
+      : { elevation };
   const notchProps = {
     notchSize: chrome.notchSize,
     ...(notchPosition.top !== undefined ? { top: notchPosition.top } : {}),
@@ -56,21 +102,24 @@ export function TooltipBubble({
   };
 
   return (
-    <View
+    <CardFade
       testID="userflow-tooltip-card"
       accessibilityViewIsModal
       pointerEvents="auto"
       onLayout={onLayout}
       style={[styles.shell, style]}
     >
-      {/* iOS-only: Android gets the same shadow from the fill's elevation. */}
+      {/* Bottom layer, so its shadow reads as the card's on both platforms and
+          the notch can sit on top of it instead of inside it. It carries the
+          card's radius and an opaque fill, which is what lets iOS derive a
+          rounded shadow path from it rather than clipping one. */}
       <View
         pointerEvents="none"
+        testID="userflow-tooltip-card-shadow"
         style={[
           styles.cardShadow,
           chrome.shadowStyle,
           {
-            elevation: 0,
             borderRadius: chrome.borderRadius,
             backgroundColor: chrome.backgroundColor,
           },
@@ -78,33 +127,107 @@ export function TooltipBubble({
       />
 
       {showNotch ? (
-        <TooltipNotch {...notchProps} notchColor={notchColor} style={styles.notchLayer} />
+        <TooltipNotch
+          {...notchProps}
+          notchColor={notchColor}
+          style={[styles.notchLayer, notchShadow]}
+        />
       ) : null}
 
-      <View style={[chrome.fillStyle, styles.fill, { elevation }]}>{children}</View>
+      <View
+        testID="userflow-tooltip-card-fill"
+        style={[
+          chrome.fillStyle,
+          styles.fill,
+          // Keep the opaque rounded skin unclipped so its top edge composites
+          // onto this layer instead of the dim. Content still clips inside.
+          styles.fillSkin,
+          raisedSilent,
+          maxHeight != null ? { maxHeight } : null,
+        ]}
+      >
+        <View
+          testID="userflow-tooltip-card-fill-clip"
+          style={[
+            styles.fillClip,
+            { borderRadius: chrome.borderRadius },
+            maxHeight != null ? { maxHeight } : null,
+          ]}
+        >
+          {children}
+        </View>
+      </View>
 
-      {/* Inset fill diamond above the card body: hides the notch shadow/base seam
-          where the pointer meets the card (especially visible on upward pointers).
-          Bordered themes use borderWidth; borderless themes still need ≥1px overlap. */}
-      {showNotch ? (
+      {notchEdge ? (
+        <View
+          pointerEvents="none"
+          testID="userflow-tooltip-notch-edge-cap"
+          style={[
+            styles.notchSeamCover,
+            edgeCapStyle(notchEdge, chrome.borderRadius, chrome.backgroundColor),
+            raisedSilent,
+          ]}
+        />
+      ) : null}
+
+      {/* Bordered themes only: an inset fill diamond above the card body closes
+          the stroke gap where the pointer meets the card. Silent on both
+          platforms — it is the topmost layer, right over the tip. */}
+      {showSeamCover ? (
         <TooltipNotch
           {...notchProps}
           notchColor={chrome.backgroundColor}
           inset={Math.max(chrome.borderWidth, 1)}
-          style={[styles.notchSeamCover, { elevation }]}
+          style={[styles.notchSeamCover, raisedSilent]}
           testID="userflow-tooltip-notch-seam"
         />
       ) : null}
-    </View>
+    </CardFade>
   );
 }
 
+/** Pixel-thick cover for the fill hairline on the pointer's card edge. */
+const EDGE_CAP_THICKNESS = 2;
+
+/**
+ * The pointer hangs *outside* the card, so its edge offset is negative.
+ * Along-edge alignment (the other axis) is positive and must be ignored.
+ */
+function protrudingNotchEdge(position: NotchPosition): 'top' | 'bottom' | 'left' | 'right' | null {
+  if (position.top != null && position.top < 0) return 'top';
+  if (position.bottom != null && position.bottom < 0) return 'bottom';
+  if (position.left != null && position.left < 0) return 'left';
+  if (position.right != null && position.right < 0) return 'right';
+  return null;
+}
+
+function edgeCapStyle(
+  edge: 'top' | 'bottom' | 'left' | 'right',
+  borderRadius: number,
+  backgroundColor: string,
+): ViewStyle {
+  const inset = borderRadius;
+  const along: ViewStyle = {
+    position: 'absolute',
+    backgroundColor,
+  };
+  switch (edge) {
+    case 'top':
+      return { ...along, top: 0, left: inset, right: inset, height: EDGE_CAP_THICKNESS };
+    case 'bottom':
+      return { ...along, bottom: 0, left: inset, right: inset, height: EDGE_CAP_THICKNESS };
+    case 'left':
+      return { ...along, left: 0, top: inset, bottom: inset, width: EDGE_CAP_THICKNESS };
+    case 'right':
+      return { ...along, right: 0, top: inset, bottom: inset, width: EDGE_CAP_THICKNESS };
+  }
+}
+
 const styles = StyleSheet.create({
   shell: {
     position: 'relative',
     backgroundColor: 'transparent',
     overflow: 'visible',
-    maxHeight: '80%',
     flexShrink: 1,
   },
   cardShadow: {
@@ -116,6 +239,18 @@ const styles = StyleSheet.create({
   },
   fill: {
     zIndex: 2,
+    minHeight: 0,
+    flexShrink: 1,
+  },
+  fillSkin: {
+    overflow: 'visible',
+  },
+  fillClip: {
+    overflow: 'hidden',
+    minHeight: 0,
+    flexShrink: 1,
+    // Do not set flexGrow / flex: 1. The card sizes to its content; grow in an
+    // auto-height parent collapses the fill to 0 and leaves only the notch.
   },
   notchSeamCover: {
     zIndex: 3,

package/src/surfaces/tooltip/TooltipCutout.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { Dimensions, StyleSheet, View } from 'react-native';
 
 import { ABSOLUTE_FILL } from '../absoluteFill';
+import { getSurfaceInteractionBlocking } from '../surfaceInteractionConfig';
 
 export interface HighlightRect {
   top: number;
@@ -11,27 +12,64 @@ export interface HighlightRect {
 }
 
 export interface TooltipCutoutProps {
-  targetRect: HighlightRect;
+  /** `null` until the target is measured — dims the screen with no hole yet. */
+  targetRect: HighlightRect | null;
   backdropColor: string;
   backdropOpacity: number;
   /**
-   * When true, a transparent capture layer covers only the highlight hole so
-   * the tooltip target cannot be pressed. Dim bands stay visual-only either way.
+   * When true, a transparent capture layer covers the highlight hole so the
+   * tooltip target cannot be pressed (used with surface interaction blocking).
    */
   targetBlocked: boolean;
 }
 
+/** No hole yet: collapses the top/left/right bands, leaving one full-screen band. */
+const NO_HOLE: HighlightRect = { top: 0, left: 0, width: 0, height: 0 };
+
+/**
+ * Intersect the hole with the screen, or drop it when the target is off-screen.
+ *
+ * Targets are measured before `scrollAnchorIntoView` has brought them in, so an
+ * unclamped rect can sit above the viewport. The bands then disagree — the top
+ * one collapses while the side ones still paint at y=0 — and leave phantom dim
+ * blocks pinned to the top edge that reflow as the scroll settles.
+ */
+function clampToScreen(
+  rect: HighlightRect | null,
+  screenWidth: number,
+  screenHeight: number,
+): HighlightRect | null {
+  if (rect == null) {
+    return null;
+  }
+  const top = Math.max(0, rect.top);
+  const left = Math.max(0, rect.left);
+  const bottom = Math.min(screenHeight, rect.top + rect.height);
+  const right = Math.min(screenWidth, rect.left + rect.width);
+  if (bottom <= top || right <= left) {
+    return null;
+  }
+  return { top, left, width: right - left, height: bottom - top };
+}
+
 /**
  * Four-block dimmed cutout around the padded target (web tooltip backdrop).
  *
- * Dim bands use `pointerEvents="none"` so touches reach the app — React Native
- * cannot block taps while allowing scroll the way web's `mousedown`-only
- * swallow does. When `targetBlocked`, only the hole (target) is covered with a
- * transparent `pointerEvents="auto"` layer.
+ * When surface interaction blocking is enabled (default), dim bands use
+ * `pointerEvents="auto"` so taps outside the hole are swallowed. The target
+ * hole stays open for guided-tour taps unless `targetBlocked` seals it.
+ *
+ * When blocking is disabled (`Userflow.setSurfaceInteractionBlocking(false)`),
+ * bands revert to `pointerEvents="none"` so the host app stays scrollable and
+ * tappable — legacy pass-through behavior. The `targetBlocked` hole seal is
+ * unchanged and still mounts when set.
  *
- * MVP note: each block uses its own translucent opacity. That matches non-overlapping
- * tiles well, but can look slightly uneven vs web’s single shadow-hole when other
- * translucent overlays stack. Acceptable for Phase 3; a single masked layer can come later.
+ * The bands are opaque and share one translucent parent, so the dim is composited
+ * once. Per-band opacity looks identical while the tiles truly abut, but any frame
+ * where two of them overlap darkens twice: going from no hole to a measured one
+ * grows the top band while the bottom band still covers the screen, which painted a
+ * doubled rectangle over the upper screen until the geometry settled. Group opacity
+ * makes overlap invisible instead of relying on the four rects always agreeing.
  */
 export function TooltipCutout({
   targetRect,
@@ -40,51 +78,70 @@ export function TooltipCutout({
   targetBlocked,
 }: TooltipCutoutProps): React.ReactElement {
   const { width: sw, height: sh } = Dimensions.get('window');
-  const { top, left, width, height } = targetRect;
+  const hole = clampToScreen(targetRect, sw, sh);
+  const { top, left, width, height } = hole ?? NO_HOLE;
   const right = left + width;
   const bottom = top + height;
-  const blockStyle = { backgroundColor: backdropColor, opacity: backdropOpacity };
+  const blockStyle = { backgroundColor: backdropColor };
+  const blockInteraction = getSurfaceInteractionBlocking();
+  const bandPointerEvents = blockInteraction ? 'auto' : 'none';
+  const dimPointerEvents = blockInteraction ? 'box-none' : 'none';
 
   return (
     <View style={ABSOLUTE_FILL} pointerEvents="box-none" testID="userflow-tooltip-cutout">
       <View
-        pointerEvents="none"
-        testID="userflow-tooltip-cutout-top"
-        style={[styles.block, blockStyle, { top: 0, left: 0, width: sw, height: Math.max(0, top) }]}
-      />
-      <View
-        pointerEvents="none"
-        testID="userflow-tooltip-cutout-left"
-        style={[
-          styles.block,
-          blockStyle,
-          { top: Math.max(0, top), left: 0, width: Math.max(0, left), height: Math.max(0, height) },
-        ]}
-      />
-      <View
-        pointerEvents="none"
-        testID="userflow-tooltip-cutout-right"
-        style={[
-          styles.block,
-          blockStyle,
-          {
-            top: Math.max(0, top),
-            left: Math.max(0, right),
-            width: Math.max(0, sw - right),
-            height: Math.max(0, height),
-          },
-        ]}
-      />
-      <View
-        pointerEvents="none"
-        testID="userflow-tooltip-cutout-bottom"
-        style={[
-          styles.block,
-          blockStyle,
-          { top: Math.max(0, bottom), left: 0, width: sw, height: Math.max(0, sh - bottom) },
-        ]}
-      />
-      {targetBlocked ? (
+        pointerEvents={dimPointerEvents}
+        testID="userflow-tooltip-cutout-dim"
+        style={[ABSOLUTE_FILL, { opacity: backdropOpacity }]}
+      >
+        <View
+          pointerEvents={bandPointerEvents}
+          testID="userflow-tooltip-cutout-top"
+          style={[
+            styles.block,
+            blockStyle,
+            { top: 0, left: 0, width: sw, height: Math.max(0, top) },
+          ]}
+        />
+        <View
+          pointerEvents={bandPointerEvents}
+          testID="userflow-tooltip-cutout-left"
+          style={[
+            styles.block,
+            blockStyle,
+            {
+              top: Math.max(0, top),
+              left: 0,
+              width: Math.max(0, left),
+              height: Math.max(0, height),
+            },
+          ]}
+        />
+        <View
+          pointerEvents={bandPointerEvents}
+          testID="userflow-tooltip-cutout-right"
+          style={[
+            styles.block,
+            blockStyle,
+            {
+              top: Math.max(0, top),
+              left: Math.max(0, right),
+              width: Math.max(0, sw - right),
+              height: Math.max(0, height),
+            },
+          ]}
+        />
+        <View
+          pointerEvents={bandPointerEvents}
+          testID="userflow-tooltip-cutout-bottom"
+          style={[
+            styles.block,
+            blockStyle,
+            { top: Math.max(0, bottom), left: 0, width: sw, height: Math.max(0, sh - bottom) },
+          ]}
+        />
+      </View>
+      {targetBlocked && hole != null ? (
         <View
           pointerEvents="auto"
           testID="userflow-tooltip-target-block"

package/src/surfaces/tooltip/TooltipHighlight.tsx

@@ -0,0 +1,144 @@
+import * as React from 'react';
+import { Platform, StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { isHighlightVisible, type HighlightChrome } from '../resolveHighlightChrome';
+
+import type { HighlightRect } from './TooltipCutout';
+
+export interface TooltipHighlightProps {
+  targetRect: HighlightRect;
+  chrome: HighlightChrome;
+}
+
+interface Ring {
+  testID: string;
+  style: StyleProp<ViewStyle>;
+}
+
+/**
+ * Mobile focus ring for the tooltip hole (mockup: thin brand stroke + soft
+ * halo). Web uses one CSS `box-shadow`; RN approximates that with a 2px
+ * stroke, one translucent band, and a real blur where the platform can
+ * paint a colored shadow (`shadow*` on iOS, `boxShadow` on RN 0.76+).
+ *
+ * Ring chrome is passed as a style array so `StyleSheet.create` numeric IDs
+ * are not object-spread (that drops `position: 'absolute'` on device).
+ */
+export function TooltipHighlight({
+  targetRect,
+  chrome,
+}: TooltipHighlightProps): React.ReactElement | null {
+  if (!isHighlightVisible(chrome)) return null;
+
+  const rings = buildHighlightRings(targetRect, chrome);
+  if (rings.length === 0) return null;
+
+  return (
+    <View pointerEvents="none" testID="userflow-tooltip-highlight">
+      {rings.map((ring) => (
+        <View key={ring.testID} pointerEvents="none" testID={ring.testID} style={ring.style} />
+      ))}
+    </View>
+  );
+}
+
+export function buildHighlightRings(rect: HighlightRect, chrome: HighlightChrome): Ring[] {
+  if (rect.width <= 0 || rect.height <= 0) return [];
+
+  const inset = chrome.type === 'INSIDE';
+  const rings: Ring[] = [];
+  let consumed = 0;
+
+  if (chrome.strokeWidth > 0) {
+    const frame = ringFrame(rect, chrome.strokeWidth, consumed, inset, chrome.borderRadius);
+    if (frame) {
+      rings.push({
+        testID: 'userflow-tooltip-highlight-stroke',
+        style: [
+          styles.ring,
+          frame,
+          {
+            borderWidth: chrome.strokeWidth,
+            borderColor: chrome.color,
+            ...strokeGlow(chrome),
+          },
+        ],
+      });
+      consumed += chrome.strokeWidth;
+    }
+  }
+
+  if (chrome.radius > 0) {
+    const frame = ringFrame(rect, chrome.radius, consumed, inset, chrome.borderRadius);
+    if (frame) {
+      rings.push({
+        testID: 'userflow-tooltip-highlight-glow',
+        style: [
+          styles.ring,
+          frame,
+          {
+            borderWidth: chrome.radius,
+            borderColor: chrome.glowColor,
+          },
+        ],
+      });
+    }
+  }
+
+  return rings;
+}
+
+function strokeGlow(chrome: HighlightChrome): ViewStyle {
+  const blur = Math.max(chrome.radius, 6);
+  const glow: ViewStyle = {
+    shadowColor: chrome.color,
+    shadowOffset: { width: 0, height: 0 },
+    shadowOpacity: Math.min(0.45, chrome.opacity),
+    shadowRadius: blur,
+  };
+  if (Platform?.OS !== 'ios') {
+    glow.boxShadow = `0px 0px ${blur}px 0px ${chrome.glowColor}`;
+  }
+  return glow;
+}
+
+function ringFrame(
+  rect: HighlightRect,
+  borderWidth: number,
+  alreadyConsumed: number,
+  inset: boolean,
+  cornerRadius: number,
+): { top: number; left: number; width: number; height: number; borderRadius: number } | null {
+  if (borderWidth <= 0) return null;
+  const { top, left, width, height } = rect;
+
+  if (inset) {
+    const nextWidth = width - alreadyConsumed * 2;
+    const nextHeight = height - alreadyConsumed * 2;
+    if (nextWidth < borderWidth * 2 || nextHeight < borderWidth * 2) return null;
+    return {
+      top: top + alreadyConsumed,
+      left: left + alreadyConsumed,
+      width: nextWidth,
+      height: nextHeight,
+      borderRadius: Math.max(0, cornerRadius - alreadyConsumed),
+    };
+  }
+
+  const outset = alreadyConsumed + borderWidth;
+  return {
+    top: top - outset,
+    left: left - outset,
+    width: width + outset * 2,
+    height: height + outset * 2,
+    borderRadius: cornerRadius + outset,
+  };
+}
+
+const styles = StyleSheet.create({
+  ring: {
+    position: 'absolute',
+    backgroundColor: 'transparent',
+    overflow: 'visible',
+  },
+});