@userflow-tech/react-native 0.1.0

package/lib/typescript/module/src/surfaces/tooltip/computeTooltipPosition.d.ts

@@ -0,0 +1,43 @@
+import type { Position, Rect, Size, TooltipPlacementSide, WindowSize } from './inferTooltipPlacement';
+export interface NotchPosition {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+}
+export interface TooltipLayout {
+    cardPosition: Position;
+    notchPosition: NotchPosition;
+    /** Padded target rect used for the cutout hole. */
+    targetHighlightRect: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Side length of the axis-aligned square that, when rotated 45°, yields a
+ * tip that protrudes `notchSize` beyond the card edge (half-diagonal = N).
+ */
+export declare function tooltipNotchDiamondSide(notchSize: number): number;
+/**
+ * TOOLTIP card + notch layout. Port of FlowChrome.tsx placement/clamp.
+ *
+ * The notch is a square of side `N√2` rotated 45° whose center sits on the card
+ * edge, so a tip of length `N` points at the target. When the card has a border,
+ * pull the diamond toward the card by `borderWidth` so the tip still clears the
+ * stroke without leaving a seam.
+ */
+export declare function computeTooltipPosition(opts: {
+    target: Rect;
+    bubbleSize: Size;
+    placement: TooltipPlacementSide;
+    notchSize: number;
+    backdropPadding?: number;
+    windowSize: WindowSize;
+    bubbleBorderRadius: number;
+    bubbleBorderWidth?: number;
+    viewportPadding?: number;
+}): TooltipLayout;
+//# sourceMappingURL=computeTooltipPosition.d.ts.map

package/lib/typescript/module/src/surfaces/tooltip/computeTooltipPosition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computeTooltipPosition.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/computeTooltipPosition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,oBAAoB,EACpB,UAAU,EACX,MAAM,yBAAyB,CAAC;AAGjC,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,QAAQ,CAAC;IACvB,aAAa,EAAE,aAAa,CAAC;IAC7B,mDAAmD;IACnD,mBAAmB,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,oBAAoB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,UAAU,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,aAAa,CA2EhB"}

package/lib/typescript/module/src/surfaces/tooltip/inferTooltipPlacement.d.ts

@@ -0,0 +1,34 @@
+/** Placement sides — string union so Jest protocol mocks stay empty. */
+export type TooltipPlacementSide = 'ABOVE' | 'BELOW' | 'LEFT' | 'RIGHT';
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Position {
+    x: number;
+    y: number;
+}
+export interface WindowSize {
+    width: number;
+    height: number;
+}
+export declare const VIEWPORT_PADDING = 24;
+/**
+ * Port of web FlowChrome `inferTooltipPlacement` with distance-sorted flip
+ * (not the prototype's fixed BELOW→ABOVE→RIGHT→LEFT priority).
+ */
+export declare function inferTooltipPlacement({ target, bubbleSize, notchSize, windowSize, currentPlacement, desiredPlacement, }: {
+    target: Rect;
+    bubbleSize: Size;
+    notchSize: number;
+    windowSize: WindowSize;
+    currentPlacement: TooltipPlacementSide | null;
+    desiredPlacement: TooltipPlacementSide | null;
+}): TooltipPlacementSide;
+//# sourceMappingURL=inferTooltipPlacement.d.ts.map

package/lib/typescript/module/src/surfaces/tooltip/inferTooltipPlacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferTooltipPlacement.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/inferTooltipPlacement.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;AAExE,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,eAAO,MAAM,gBAAgB,KAA2B,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,UAAU,EACV,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,gBAAgB,GACjB,EAAE;IACD,MAAM,EAAE,IAAI,CAAC;IACb,UAAU,EAAE,IAAI,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,gBAAgB,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC/C,GAAG,oBAAoB,CA6DvB"}

package/lib/typescript/module/src/surfaces/tooltip/parseBackdropPadding.d.ts

@@ -0,0 +1,3 @@
+/** Parse step `backdropPadding` (px). Web accepts CSS shorthand; MVP: first number. */
+export declare function parseBackdropPadding(value: string | null | undefined): number;
+//# sourceMappingURL=parseBackdropPadding.d.ts.map

package/lib/typescript/module/src/surfaces/tooltip/parseBackdropPadding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseBackdropPadding.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/parseBackdropPadding.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAM7E"}

package/lib/typescript/module/src/surfaces/tooltip/rect.d.ts

@@ -0,0 +1,29 @@
+import type { Rect, WindowSize } from './inferTooltipPlacement';
+/** True when two rects are identical (used to avoid redundant setState). */
+export declare function rectsEqual(a: Rect | null, b: Rect | null): boolean;
+/** Fully outside the window (no intersection). Kept for callers that need it. */
+export declare function isRectOffScreen(rect: Rect, windowSize: WindowSize): boolean;
+/**
+ * Viewport used for scroll-into-view / visibility checks. May be smaller than
+ * the raw window (keyboard, safe-area, sticky chrome via scroll padding).
+ */
+export interface EffectiveViewport {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * True when every edge of `rect` lies inside `viewport` (inclusive).
+ * Partially clipped targets return false — matching web `block: 'nearest'`
+ * scroll-into-view gating.
+ */
+export declare function isRectFullyVisible(rect: Rect, viewport: EffectiveViewport): boolean;
+/** Build an effective viewport from window size + optional insets. */
+export declare function buildEffectiveViewport(windowSize: WindowSize, insets?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}): EffectiveViewport;
+//# sourceMappingURL=rect.d.ts.map

package/lib/typescript/module/src/surfaces/tooltip/rect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rect.d.ts","sourceRoot":"","sources":["../../../../../../src/surfaces/tooltip/rect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEhE,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAIlE;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAO3E;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CASnF;AAED,sEAAsE;AACtE,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,UAAU,EACtB,MAAM,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACxE,iBAAiB,CAWnB"}

package/lib/typescript/module/src/useUserflowScreen.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reports the active React Navigation (or manual) screen name to Userflow when
+ * it changes. Sent to the backend as `clientContext.screen`.
+ *
+ * Prefer {@link UserflowProvider} + {@link WithUserflowReactNavigation} when
+ * using React Navigation. For Expo Router pathnames, prefer
+ * {@link UserflowProvider} (it wires pathname tracking automatically).
+ */
+export declare function useUserflowScreen(screenName: string | undefined): void;
+//# sourceMappingURL=useUserflowScreen.d.ts.map

package/lib/typescript/module/src/useUserflowScreen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUserflowScreen.d.ts","sourceRoot":"","sources":["../../../../src/useUserflowScreen.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAItE"}

package/lib/typescript/module/src/version.d.ts

@@ -0,0 +1,3 @@
+/** Generated by scripts/write-version.mjs — do not edit. */
+export declare const SDK_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/lib/typescript/module/src/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../../../src/version.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,eAAO,MAAM,WAAW,UAAU,CAAC"}

package/package.json

@@ -0,0 +1,144 @@
+{
+  "name": "@userflow-tech/react-native",
+  "version": "0.1.0",
+  "description": "Userflow SDK for React Native — onboarding flows, tooltips, and modals.",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./lib/commonjs/index.js",
+  "module": "./lib/module/index.js",
+  "types": "./lib/typescript/commonjs/src/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/src/index.d.ts",
+        "default": "./lib/module/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      }
+    },
+    "./navigation": {
+      "react-native": "./src/navigation/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/src/navigation/index.d.ts",
+        "default": "./lib/module/navigation/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/navigation/index.d.ts",
+        "default": "./lib/commonjs/navigation/index.js"
+      }
+    },
+    "./expo-router": {
+      "react-native": "./src/expo-router/index.ts",
+      "import": {
+        "types": "./lib/typescript/module/src/expo-router/index.d.ts",
+        "default": "./lib/module/expo-router/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/src/expo-router/index.d.ts",
+        "default": "./lib/commonjs/expo-router/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "docs",
+    "!**/__tests__",
+    "!**/*.test.*",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": ">=1.23.0",
+    "@react-native-community/netinfo": ">=11.0.0",
+    "@react-navigation/native": ">=6.0.0",
+    "expo-router": ">=3.0.0",
+    "expo-secure-store": ">=13.0.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0",
+    "react-native-safe-area-context": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-native-community/netinfo": {
+      "optional": true
+    },
+    "@react-navigation/native": {
+      "optional": true
+    },
+    "expo-router": {
+      "optional": true
+    },
+    "expo-secure-store": {
+      "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@userflow-tech/protocol": "0.1.0",
+    "@userflow-tech/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.0",
+    "@react-native-async-storage/async-storage": "^2.1.2",
+    "@react-native-community/netinfo": "^11.4.1",
+    "@react-native/babel-preset": "^0.81.5",
+    "@react-navigation/native": "^7.1.6",
+    "@types/jest": "^29.5.12",
+    "@types/react": "~19.1.10",
+    "@types/react-test-renderer": "^19.1.0",
+    "babel-jest": "^29.7.0",
+    "expo-router": "^5.1.0",
+    "jest": "^29.7.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-builder-bob": "^0.30.0",
+    "react-native-safe-area-context": "~5.6.0",
+    "react-native-screens": "~4.16.0",
+    "react-test-renderer": "19.1.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.0",
+    "@userflow-tech/tsconfig": "0.0.0",
+    "@userflow-tech/eslint-config": "0.0.0"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "commonjs",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "esm": true
+        }
+      ]
+    ]
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "scripts": {
+    "build": "node ../../scripts/write-version.mjs SDK_VERSION && bob build",
+    "test": "jest",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "pretest": "node ../../scripts/write-version.mjs SDK_VERSION",
+    "clean": "rimraf lib"
+  }
+}

package/src/anchors/AnchorRegistry.ts

@@ -0,0 +1,81 @@
+/** Host view that can be measured in window coordinates. */
+export interface AnchorHost {
+  measureInWindow: (
+    callback: (x: number, y: number, width: number, height: number) => void,
+  ) => void;
+  /**
+   * Optional best-effort: scroll ancestors so this host enters the viewport.
+   * Called when the measured rect is not fully visible (bounded retries per step).
+   */
+  scrollIntoView?: () => void;
+}
+
+type Listener = () => void;
+
+/**
+ * Manual-anchor registry for Phase 3 (WS6). Codeless resolution is Phase 4.
+ * Multiple mounts of the same id keep a set; {@link get} returns the most
+ * recently registered host.
+ */
+export class AnchorRegistry {
+  private readonly anchors = new Map<string, Set<AnchorHost>>();
+  private readonly listeners = new Set<Listener>();
+
+  register(id: string, host: AnchorHost): void {
+    if (!id) return;
+    let set = this.anchors.get(id);
+    if (!set) {
+      set = new Set();
+      this.anchors.set(id, set);
+    }
+    set.add(host);
+    this.emit();
+  }
+
+  unregister(id: string, host: AnchorHost): void {
+    const set = this.anchors.get(id);
+    if (!set) return;
+    set.delete(host);
+    if (set.size === 0) {
+      this.anchors.delete(id);
+    }
+    this.emit();
+  }
+
+  get(id: string): AnchorHost | null {
+    const set = this.anchors.get(id);
+    if (!set || set.size === 0) return null;
+    let last: AnchorHost | null = null;
+    for (const host of set) {
+      last = host;
+    }
+    return last;
+  }
+
+  /** True when more than one host is registered for the same id. */
+  isAmbiguous(id: string): boolean {
+    return (this.anchors.get(id)?.size ?? 0) > 1;
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Test helper — clear all anchors. */
+  clear(): void {
+    this.anchors.clear();
+    this.emit();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}
+
+/** Module singleton used by {@link useUserflowAnchor} and TooltipSurface. */
+export const anchorRegistry = new AnchorRegistry();