feat: QR modal wallet-connection auto-detection via polling (#211) (#258)

- Add isWalletConnected() helper to freighter.ts (checks WalletConnect then Freighter)
- Replace placeholder effect in QRModal with 2s polling loop
- firedRef ensures onConnected fires exactly once per open cycle
- Interval cleared on unmount and when open becomes false
- pollingInterval prop (default 2000ms) makes interval configurable
- 6 unit tests: fires once, no double-fire, not connected, stops on close, no leak, custom interval

Author: Nuel-ship-it

src/__tests__/QRModal.test.tsx

@@ -0,0 +1,162 @@
+/**
+ * Unit tests for QRModal polling (#211).
+ *
+ * Covers:
+ *  - onConnected fires exactly once when wallet connects
+ *  - polling stops (no extra calls) after connection detected
+ *  - polling stops when open becomes false
+ *  - no interval leak across open/close cycles
+ *  - pollingInterval prop controls the delay
+ */
+
+import React from "react";
+import { render, act } from "@testing-library/react";
+import QRModal from "@/components/QRModal";
+
+// ── mock isWalletConnected ────────────────────────────────────────────────────
+const mockIsWalletConnected = jest.fn();
+jest.mock("@/lib/freighter", () => ({
+  isWalletConnected: (...args: unknown[]) => mockIsWalletConnected(...args),
+}));
+
+// ── mock FocusTrap (renders children) ────────────────────────────────────────
+jest.mock("@/components/FocusTrap", () => ({
+  __esModule: true,
+  default: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}));
+
+// ── mock qrcode.react ─────────────────────────────────────────────────────────
+jest.mock("qrcode.react", () => ({
+  QRCodeCanvas: () => <canvas />,
+}));
+
+const baseProps = {
+  open: true,
+  uri: "wc:test-uri",
+  onClose: jest.fn(),
+};
+
+beforeEach(() => {
+  jest.useFakeTimers();
+  mockIsWalletConnected.mockResolvedValue(false);
+});
+
+afterEach(() => {
+  jest.useRealTimers();
+  jest.clearAllMocks();
+});
+
+test("onConnected fires exactly once when wallet connects", async () => {
+  const onConnected = jest.fn();
+  mockIsWalletConnected.mockResolvedValue(true);
+
+  render(<QRModal {...baseProps} onConnected={onConnected} pollingInterval={2000} />);
+
+  await act(async () => {
+    jest.advanceTimersByTime(2000);
+  });
+
+  expect(onConnected).toHaveBeenCalledTimes(1);
+});
+
+test("onConnected does not fire again if connection stays true", async () => {
+  const onConnected = jest.fn();
+  mockIsWalletConnected.mockResolvedValue(true);
+
+  render(<QRModal {...baseProps} onConnected={onConnected} pollingInterval={2000} />);
+
+  // Advance tick-by-tick so the async callback resolves and sets firedRef before the next tick
+  for (let i = 0; i < 4; i++) {
+    await act(async () => {
+      jest.advanceTimersByTime(2000);
+    });
+  }
+
+  expect(onConnected).toHaveBeenCalledTimes(1);
+});
+
+test("onConnected does not fire while wallet not connected", async () => {
+  const onConnected = jest.fn();
+  mockIsWalletConnected.mockResolvedValue(false);
+
+  render(<QRModal {...baseProps} onConnected={onConnected} pollingInterval={2000} />);
+
+  await act(async () => {
+    jest.advanceTimersByTime(6000); // 3 ticks, never connected
+  });
+
+  expect(onConnected).not.toHaveBeenCalled();
+});
+
+test("polling stops when open becomes false", async () => {
+  const onConnected = jest.fn();
+  mockIsWalletConnected.mockResolvedValue(false);
+
+  const { rerender } = render(
+    <QRModal {...baseProps} onConnected={onConnected} pollingInterval={2000} />
+  );
+
+  // close modal
+  rerender(
+    <QRModal {...baseProps} open={false} onConnected={onConnected} pollingInterval={2000} />
+  );
+
+  // wallet connects, but modal is closed
+  mockIsWalletConnected.mockResolvedValue(true);
+
+  await act(async () => {
+    jest.advanceTimersByTime(6000);
+  });
+
+  expect(onConnected).not.toHaveBeenCalled();
+});
+
+test("no interval leak: re-opening fires onConnected exactly once per cycle", async () => {
+  const onConnected = jest.fn();
+
+  // First open: wallet not connected
+  const { rerender } = render(
+    <QRModal {...baseProps} onConnected={onConnected} pollingInterval={2000} />
+  );
+
+  await act(async () => {
+    jest.advanceTimersByTime(2000);
+  });
+  expect(onConnected).toHaveBeenCalledTimes(0);
+
+  // Close modal
+  rerender(
+    <QRModal {...baseProps} open={false} onConnected={onConnected} pollingInterval={2000} />
+  );
+
+  // Re-open, wallet now connected
+  mockIsWalletConnected.mockResolvedValue(true);
+  rerender(
+    <QRModal {...baseProps} open={true} onConnected={onConnected} pollingInterval={2000} />
+  );
+
+  await act(async () => {
+    jest.advanceTimersByTime(2000);
+  });
+
+  // Should fire exactly once for the new cycle, not multiple times from leaked intervals
+  expect(onConnected).toHaveBeenCalledTimes(1);
+});
+
+test("pollingInterval prop controls tick frequency", async () => {
+  const onConnected = jest.fn();
+  mockIsWalletConnected.mockResolvedValue(true);
+
+  render(<QRModal {...baseProps} onConnected={onConnected} pollingInterval={500} />);
+
+  // Should not have fired before 500ms
+  await act(async () => {
+    jest.advanceTimersByTime(400);
+  });
+  expect(onConnected).toHaveBeenCalledTimes(0);
+
+  await act(async () => {
+    jest.advanceTimersByTime(100); // reaches 500ms
+  });
+  expect(onConnected).toHaveBeenCalledTimes(1);
+});

src/components/QRModal.tsx

@@ -1,15 +1,17 @@
 "use client";
 
-import { useEffect } from "react";
+import { useEffect, useRef } from "react";
 import FocusTrap from "./FocusTrap";
 import { QRCodeCanvas } from "qrcode.react";
+import { isWalletConnected } from "@/lib/freighter";
 
 type QRModalProps = {
   open: boolean;
   uri: string;
   onClose: () => void;
   onCopied?: () => void;
   onConnected?: () => void;
+  pollingInterval?: number;
 };
 
 export default function QRModal({
@@ -18,16 +20,28 @@ export default function QRModal({
   onClose,
   onCopied,
   onConnected,
+  pollingInterval = 2000,
 }: QRModalProps) {
-  // Escape and focus trapping handled by FocusTrap when open
+  const firedRef = useRef(false);
 
   useEffect(() => {
-    if (!open) return;
-    // If the wallet successfully connected elsewhere in the UI,
-    // consumers can trigger onConnected manually. This effect is left
-    // as a placeholder for future integration and does not auto-fire.
-    void onConnected;
-  }, [open, onConnected]);
+    if (!open) {
+      firedRef.current = false;
+      return;
+    }
+
+    const id = setInterval(async () => {
+      if (firedRef.current) return;
+      const connected = await isWalletConnected();
+      if (connected) {
+        firedRef.current = true;
+        clearInterval(id);
+        onConnected?.();
+      }
+    }, pollingInterval);
+
+    return () => clearInterval(id);
+  }, [open, onConnected, pollingInterval]);
 
   if (!open) return null;
 

src/lib/freighter.ts

@@ -91,6 +91,21 @@ export async function disconnectWalletConnect(): Promise<void> {
   }
 }
 
+/** Returns true if any supported wallet is currently connected. */
+export async function isWalletConnected(): Promise<boolean> {
+  if (typeof window === "undefined") return false;
+  try {
+    const wcKey = await getWalletConnectPublicKey();
+    if (wcKey) return true;
+  } catch { /* fall through */ }
+  try {
+    const key = await getFreighterPublicKey();
+    return !!key;
+  } catch {
+    return false;
+  }
+}
+
 /** Sign a transaction with the currently connected wallet adapter. */
 export async function signTransaction(xdr: string): Promise<string> {
   if (typeof window === "undefined") throw new Error("Browser only");