@benji-money/connect-sdk 1.1.0-beta.1 → 1.1.0-beta.2

package/README.md

@@ -90,6 +90,69 @@ The SDK accepts the following configuration options:
 - `onError` (optional): Callback function called when error occurs in the connect flow
 - `onExit` (optional): Callback function called when the user exits the connect flow
 - `onEvent` (optional): Callback function for handling various events
+- `anchor` (optional): Live anchor binding — `HTMLElement`, CSS selector, getter `() => HTMLElement | null`, or ref `{ value: HTMLElement | null }`. Re-resolved on every layout pass. Falls back to centered when missing or invalid. See [Placement](#placement)
+- `placement` (optional): Placement relative to `anchor` — see [Placement](#placement) below
+- `offset` (optional): Pixel gap after placement — `{ top?: number; left?: number }` (default `{ top: 0, left: 0 }`)
+
+### Placement
+
+Placement uses [Floating UI](https://floating-ui.com/docs/computePosition#placement) / CSS logical naming (`start` / `end`). In **LTR** layouts:
+
+| Value | Meaning |
+| ----- | ------- |
+| `center` (default) | Full-viewport backdrop with iframe centered |
+| `bottom-end` | Below the anchor, right edge aligned with anchor's right edge |
+| `bottom-start` | Below the anchor, left edge aligned with anchor's left edge |
+
+**Defaults:**
+
+- No `anchor` → centered modal (unchanged behavior for existing integrations)
+- `anchor` set, no `placement` → `bottom-end`
+- If the anchor is missing or invalid on **initial open**, there is not enough viewport space below, or the viewport is narrower than the iframe (400px + padding), the SDK falls back to centered
+- While the modal is **already open**, a temporarily hidden or detached anchor (e.g. crossing a responsive layout breakpoint) keeps the last anchored position instead of jumping to center; when the anchor becomes visible again, placement re-anchors automatically
+
+**Live anchor bindings** (re-resolved on scroll, resize, and visual viewport changes):
+
+| Form | Example | When to use |
+| ---- | ------- | ----------- |
+| CSS selector | `'#login-btn'` | Stable id on the anchor element |
+| Ref object | `loginButtonRef` (Vue `{ value: el }`) | Anchor may re-render after async work |
+| Getter | `() => document.querySelector('#login-btn')` | Custom lookup |
+| `HTMLElement` | Snapshot at click time | Only when the node will not be replaced before `open()` |
+
+Prefer selector, ref, or getter when the anchor can re-render (e.g. disabled/loading state) before the modal opens. A stale `HTMLElement` snapshot falls back to a centered modal on open instead of clipping to the top-left; while open, resize across breakpoints preserves the last anchored position until the anchor is visible again or the modal is closed.
+
+**Viewport sizing:**
+
+- Design size is **400×645** px (`IFRAME_WIDTH` / `IFRAME_HEIGHT`)
+- **Centered** modals (default, explicit, or fallback) scale down proportionally when the viewport is smaller than the design size so the modal fits with 8px padding on each side
+- **Anchored** popovers use the full design size when width and height checks pass; otherwise they fall back to a scaled centered modal
+- Scroll, resize, and visual viewport changes while open recompute placement and size
+
+**LOGIN popover example** (dropdown under a top-right button):
+
+```typescript
+import {
+  ConnectSDK,
+  BenjiConnectMode,
+  BenjiConnectPlacement,
+} from "@benji-money/connect-sdk";
+
+// Prefer a live binding (selector or ref) when the button may re-render before open()
+const sdk = new ConnectSDK({
+  environment: "sandbox",
+  token: connectToken,
+  mode: BenjiConnectMode.LOGIN,
+  anchor: "#login-btn",
+  placement: BenjiConnectPlacement.BOTTOM_END,
+  offset: { top: 8 },
+  onSuccess: (token) => { /* ... */ },
+});
+
+await sdk.open();
+```
+
+> **`bottom-end`** opens below the anchor with the modal's right edge aligned to the anchor's right edge — matching a dropdown under a top-right LOGIN button.
 
 ### Environments
 

package/dist/connect-sdk.umd.d.ts

@@ -0,0 +1,14 @@
+// These are compile-time constants replaced by tsup's `define` option.
+// Declaring them globally prevents TypeScript errors.
+
+
+declare global {
+  const __VERSION__: string;
+  const __NAMESPACE__: string;
+
+  // Global browser exposure for UMD builds 
+  interface Window {
+    // SDK main class (UMD builds attach this)
+    ConnectSDK?: any;
+  }
+}

package/dist/connect-sdk.umd.global.js

@@ -110,7 +110,7 @@ var ConnectSDK = (() => {
   // src/utils/config.ts
   var buildContext = () => ({
     namespace: "benji-connect-sdk" ? "benji-connect-sdk" : "benji-connect-sdk",
-    version: "1.1.0-beta.1" ? String("1.1.0-beta.1") : "0.0.0"
+    version: "1.1.0-beta.2" ? String("1.1.0-beta.2") : "0.0.0"
   });
   function isBenjiConnectEnvironment(environment) {
     return environment === "local" /* LOCAL */ || environment === "development" /* DEVELOPMENT */ || environment === "sandbox" /* SANDBOX */ || environment === "production" /* PRODUCTION */;
@@ -130,6 +130,287 @@ var ConnectSDK = (() => {
     return defaultEnvironment;
   }
 
+  // src/utils/placement.ts
+  var IFRAME_WIDTH = 400;
+  var IFRAME_HEIGHT = 645;
+  var IFRAME_STATIC_STYLE = {
+    border: "none",
+    borderRadius: "20px",
+    overflow: "hidden"
+  };
+  var CONTAINER_BASE_STYLE = {
+    position: "fixed",
+    top: "0",
+    left: "0",
+    width: "100%",
+    height: "100%",
+    backgroundColor: "rgba(0,0,0,0.5)",
+    zIndex: "9999"
+  };
+  var VIEWPORT_PADDING = 8;
+  function isPreservableAnchoredLayout(layout) {
+    return layout != null && layout.placement !== "center" /* CENTER */;
+  }
+  function clampPreservedAnchoredLayout(layout, viewport) {
+    const maxLeft = viewport.width - layout.width - VIEWPORT_PADDING;
+    const maxTop = viewport.height - layout.height - VIEWPORT_PADDING;
+    const minLeft = VIEWPORT_PADDING;
+    const minTop = VIEWPORT_PADDING;
+    return {
+      ...layout,
+      left: maxLeft < minLeft ? minLeft : Math.min(Math.max(layout.left, minLeft), maxLeft),
+      top: maxTop < minTop ? minTop : Math.min(Math.max(layout.top, minTop), maxTop)
+    };
+  }
+  function preservedAnchoredLayoutOrCenter(viewport, options) {
+    const { preserveAnchoredLayout } = options;
+    if (isPreservableAnchoredLayout(preserveAnchoredLayout)) {
+      return clampPreservedAnchoredLayout(preserveAnchoredLayout, viewport);
+    }
+    return centerLayout(viewport);
+  }
+  function isRefLikeAnchor(anchor) {
+    return typeof anchor === "object" && anchor !== null && !(anchor instanceof HTMLElement) && "value" in anchor;
+  }
+  function resolveAnchor(anchor) {
+    if (!anchor) {
+      return null;
+    }
+    if (typeof anchor === "string") {
+      return document.querySelector(anchor);
+    }
+    if (typeof anchor === "function") {
+      const resolved = anchor();
+      return resolved instanceof HTMLElement ? resolved : null;
+    }
+    if (isRefLikeAnchor(anchor)) {
+      const el = anchor.value;
+      return el instanceof HTMLElement ? el : null;
+    }
+    return anchor instanceof HTMLElement ? anchor : null;
+  }
+  function isAnchorVisible(el) {
+    if (!el.isConnected) {
+      return false;
+    }
+    const style = window.getComputedStyle(el);
+    if (style.display === "none" || style.visibility === "hidden") {
+      return false;
+    }
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 || rect.height > 0;
+  }
+  function resolveEffectivePlacement(config) {
+    var _a;
+    if (!config.anchor) {
+      return "center" /* CENTER */;
+    }
+    return (_a = config.placement) != null ? _a : "bottom-end" /* BOTTOM_END */;
+  }
+  function defaultOffset(offset) {
+    var _a, _b;
+    return {
+      top: (_a = offset == null ? void 0 : offset.top) != null ? _a : 0,
+      left: (_b = offset == null ? void 0 : offset.left) != null ? _b : 0
+    };
+  }
+  function resolveIframeDimensions(viewport) {
+    const maxW = viewport.width - 2 * VIEWPORT_PADDING;
+    const maxH = viewport.height - 2 * VIEWPORT_PADDING;
+    const scale = Math.min(1, maxW / IFRAME_WIDTH, maxH / IFRAME_HEIGHT);
+    return {
+      width: Math.floor(IFRAME_WIDTH * scale),
+      height: Math.floor(IFRAME_HEIGHT * scale)
+    };
+  }
+  function iframeFitsHorizontally(viewportWidth, iframeWidth = IFRAME_WIDTH) {
+    return viewportWidth >= iframeWidth + 2 * VIEWPORT_PADDING;
+  }
+  function centerLayout(viewport) {
+    const { width, height } = resolveIframeDimensions(viewport);
+    return {
+      top: 0,
+      left: 0,
+      width,
+      height,
+      placement: "center" /* CENTER */
+    };
+  }
+  function fitsBelow(anchorBottom, offsetTop, viewportHeight, iframeHeight = IFRAME_HEIGHT) {
+    const top = anchorBottom + offsetTop;
+    const bottom = top + iframeHeight;
+    return top >= VIEWPORT_PADDING && bottom <= viewportHeight - VIEWPORT_PADDING;
+  }
+  function clampHorizontal(left, viewportWidth) {
+    const min = VIEWPORT_PADDING;
+    const max = viewportWidth - IFRAME_WIDTH - VIEWPORT_PADDING;
+    if (max < min) {
+      return min;
+    }
+    return Math.min(Math.max(left, min), max);
+  }
+  function warnInvalidAnchor(message) {
+    console.warn(`[Benji Connect SDK] ${message}`);
+  }
+  function computeIframeRect(anchorElement, placement, offset, viewport, options = {}) {
+    const { warnOnInvalidAnchor = false } = options;
+    const resolvedOffset = defaultOffset(offset);
+    if (placement === "center" /* CENTER */) {
+      return centerLayout(viewport);
+    }
+    if (!isAnchorVisible(anchorElement)) {
+      if (isPreservableAnchoredLayout(options.preserveAnchoredLayout)) {
+        return clampPreservedAnchoredLayout(
+          options.preserveAnchoredLayout,
+          viewport
+        );
+      }
+      if (warnOnInvalidAnchor) {
+        warnInvalidAnchor(
+          "anchor is hidden or detached; falling back to centered modal"
+        );
+      }
+      return centerLayout(viewport);
+    }
+    const rect = anchorElement.getBoundingClientRect();
+    if (!fitsBelow(rect.bottom, resolvedOffset.top, viewport.height)) {
+      return centerLayout(viewport);
+    }
+    if (!iframeFitsHorizontally(viewport.width)) {
+      return centerLayout(viewport);
+    }
+    const top = rect.bottom + resolvedOffset.top;
+    const idealLeft = placement === "bottom-end" /* BOTTOM_END */ ? rect.right - IFRAME_WIDTH + resolvedOffset.left : rect.left + resolvedOffset.left;
+    if (idealLeft < VIEWPORT_PADDING) {
+      if (warnOnInvalidAnchor) {
+        warnInvalidAnchor(
+          "anchor rect is unusable for placement; falling back to centered modal"
+        );
+      }
+      return centerLayout(viewport);
+    }
+    const left = clampHorizontal(idealLeft, viewport.width);
+    return {
+      top,
+      left,
+      width: IFRAME_WIDTH,
+      height: IFRAME_HEIGHT,
+      placement
+    };
+  }
+  function resolveIframeLayout(config, viewport = {
+    width: window.innerWidth,
+    height: window.innerHeight
+  }, options = {}) {
+    const { warnOnInvalidAnchor = true } = options;
+    const placement = resolveEffectivePlacement(config);
+    const anchorElement = resolveAnchor(config.anchor);
+    if (warnOnInvalidAnchor && placement !== "center" /* CENTER */ && !anchorElement) {
+      warnInvalidAnchor("anchor not found; falling back to centered modal");
+      return preservedAnchoredLayoutOrCenter(viewport, options);
+    }
+    if (placement === "center" /* CENTER */) {
+      return centerLayout(viewport);
+    }
+    if (!anchorElement) {
+      return preservedAnchoredLayoutOrCenter(viewport, options);
+    }
+    return computeIframeRect(
+      anchorElement,
+      placement,
+      config.offset,
+      viewport,
+      options
+    );
+  }
+  function applyOverlayBaseStyle(container) {
+    Object.assign(container.style, CONTAINER_BASE_STYLE);
+  }
+  function getVisualViewportOffset() {
+    const vv = window.visualViewport;
+    if (!vv) {
+      return { top: 0, left: 0 };
+    }
+    return { top: vv.offsetTop, left: vv.offsetLeft };
+  }
+  function getRepositionScrollTargets(anchor) {
+    const targets = /* @__PURE__ */ new Set([window]);
+    const anchorElement = resolveAnchor(anchor);
+    if (!anchorElement) {
+      return [...targets];
+    }
+    targets.add(anchorElement);
+    let parent = anchorElement.parentElement;
+    while (parent) {
+      const { overflow, overflowX, overflowY } = window.getComputedStyle(parent);
+      const overflowValue = `${overflow} ${overflowX} ${overflowY}`;
+      if (/(auto|scroll|overlay)/.test(overflowValue)) {
+        targets.add(parent);
+      }
+      parent = parent.parentElement;
+    }
+    return [...targets];
+  }
+  function applyIframeLayoutToElements(config, container, iframe, state, options = { warnOnInvalidAnchor: false }) {
+    state.layout = resolveIframeLayout(config, void 0, {
+      ...options,
+      preserveAnchoredLayout: state.lastValidAnchoredLayout
+    });
+    if (state.layout.placement !== "center" /* CENTER */) {
+      state.lastValidAnchoredLayout = state.layout;
+    }
+    const iframeStyle = {
+      ...IFRAME_STATIC_STYLE,
+      width: `${state.layout.width}px`,
+      height: `${state.layout.height}px`
+    };
+    if (state.layout.placement === "center" /* CENTER */) {
+      Object.assign(container.style, {
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        overflow: "auto"
+      });
+      Object.assign(iframe.style, iframeStyle, {
+        position: "relative",
+        top: "",
+        left: ""
+      });
+      return;
+    }
+    Object.assign(container.style, {
+      display: "block",
+      overflow: "auto"
+    });
+    const viewportOffset = getVisualViewportOffset();
+    Object.assign(iframe.style, iframeStyle, {
+      position: "fixed",
+      top: `${state.layout.top + viewportOffset.top}px`,
+      left: `${state.layout.left + viewportOffset.left}px`
+    });
+  }
+  function attachRepositionListeners(config, onReposition) {
+    const repositionHandler = onReposition;
+    const repositionScrollTargets = getRepositionScrollTargets(config.anchor);
+    repositionScrollTargets.forEach((target) => {
+      target.addEventListener("scroll", repositionHandler, { passive: true });
+    });
+    window.addEventListener("resize", repositionHandler);
+    const visualViewport = window.visualViewport;
+    visualViewport == null ? void 0 : visualViewport.addEventListener("resize", repositionHandler);
+    visualViewport == null ? void 0 : visualViewport.addEventListener("scroll", repositionHandler);
+    return {
+      remove() {
+        repositionScrollTargets.forEach((target) => {
+          target.removeEventListener("scroll", repositionHandler);
+        });
+        window.removeEventListener("resize", repositionHandler);
+        visualViewport == null ? void 0 : visualViewport.removeEventListener("resize", repositionHandler);
+        visualViewport == null ? void 0 : visualViewport.removeEventListener("scroll", repositionHandler);
+      }
+    };
+  }
+
   // src/types/event.ts
   var BenjiConnectEventType = /* @__PURE__ */ ((BenjiConnectEventType2) => {
     BenjiConnectEventType2["AUTH_SUCCESS"] = "AUTH_SUCCESS";
@@ -369,18 +650,21 @@ var ConnectSDK = (() => {
   var MessageRouter = _MessageRouter;
 
   // src/connect-sdk.ts
-  var IFRAME_STYLE = {
-    position: "relative",
-    width: "400px",
-    height: "645px",
-    border: "none",
-    borderRadius: "20px",
-    overflow: "hidden"
-  };
   var ConnectSDK = class {
     constructor(config) {
       this.iframe = null;
       this.container = null;
+      this.layoutState = {
+        layout: {
+          top: 0,
+          left: 0,
+          width: IFRAME_WIDTH,
+          height: IFRAME_HEIGHT,
+          placement: "center" /* CENTER */
+        },
+        lastValidAnchoredLayout: null
+      };
+      this.repositionListeners = null;
       this.sdkConfig = config;
       if (!this.sdkConfig.environment) throw new Error("Environment is required");
       if (!this.sdkConfig.token) throw new Error("Connect token is required");
@@ -407,19 +691,7 @@ var ConnectSDK = (() => {
     openUI() {
       if (this.iframe) return;
       this.container = document.createElement("div");
-      Object.assign(this.container.style, {
-        position: "fixed",
-        top: "0",
-        left: "0",
-        width: "100%",
-        height: "100%",
-        backgroundColor: "rgba(0,0,0,0.5)",
-        zIndex: "9999",
-        display: "flex",
-        alignItems: "center",
-        justifyContent: "center",
-        overflow: "auto"
-      });
+      applyOverlayBaseStyle(this.container);
       console.debug("[Connect SDK] endpoints", Endpoints);
       console.log("[Connect SDK] opeining URL", Endpoints.benji_connect_auth_url);
       const url = new URL(Endpoints.benji_connect_auth_url);
@@ -430,10 +702,28 @@ var ConnectSDK = (() => {
         url.searchParams.set("mode", String(this.sdkConfig.mode));
       }
       this.iframe = document.createElement("iframe");
-      Object.assign(this.iframe.style, IFRAME_STYLE);
       this.iframe.src = url.toString();
       this.container.appendChild(this.iframe);
       document.body.appendChild(this.container);
+      applyIframeLayoutToElements(
+        this.sdkConfig,
+        this.container,
+        this.iframe,
+        this.layoutState,
+        { warnOnInvalidAnchor: true }
+      );
+      this.repositionListeners = attachRepositionListeners(
+        this.sdkConfig,
+        () => {
+          if (!this.iframe || !this.container) return;
+          applyIframeLayoutToElements(
+            this.sdkConfig,
+            this.container,
+            this.iframe,
+            this.layoutState
+          );
+        }
+      );
       this.container.addEventListener("click", (e) => {
         var _a, _b;
         if (e.target === this.container) {
@@ -446,9 +736,12 @@ var ConnectSDK = (() => {
       });
     }
     close() {
-      var _a;
+      var _a, _b;
       if (!this.iframe) return;
-      if ((_a = this.container) == null ? void 0 : _a.parentNode) {
+      (_a = this.repositionListeners) == null ? void 0 : _a.remove();
+      this.repositionListeners = null;
+      this.layoutState.lastValidAnchoredLayout = null;
+      if ((_b = this.container) == null ? void 0 : _b.parentNode) {
         this.container.parentNode.removeChild(this.container);
       }
       MessageRouter.removeEventListeners();