@perspective-ai/sdk-react 1.3.0 → 1.4.0-pr-25-20260306102715

package/src/hooks/usePopup.test.ts

@@ -3,34 +3,90 @@ import { renderHook, act, cleanup } from "@testing-library/react";
 import { usePopup } from "./usePopup";
 
 const mockDestroy = vi.fn();
-const mockUnmount = vi.fn();
 const mockUpdate = vi.fn();
+const mockShow = vi.fn();
+const mockHide = vi.fn();
+let invokeSdkClose: (() => void) | null = null;
 
 vi.mock("@perspective-ai/sdk", () => ({
-  openPopup: vi.fn(() => ({
-    unmount: mockUnmount,
-    update: mockUpdate,
-    destroy: mockDestroy,
-    researchId: "test-research-id",
-    type: "popup",
-    iframe: null,
-    container: null,
-  })),
+  openPopup: vi.fn(
+    (config: {
+      researchId?: string;
+      onClose?: () => void;
+      host?: string;
+      _startHidden?: boolean;
+    }) => {
+      const currentConfig = { ...config };
+      let open = !config._startHidden;
+
+      const show = vi.fn(() => {
+        if (open) return;
+        mockShow();
+        open = true;
+      });
+
+      const hide = vi.fn(() => {
+        if (!open) return;
+        mockHide();
+        open = false;
+        currentConfig.onClose?.();
+      });
+
+      const destroy = vi.fn(() => {
+        mockDestroy();
+        const wasOpen = open;
+        open = false;
+        if (wasOpen) {
+          currentConfig.onClose?.();
+        }
+      });
+
+      const update = vi.fn(
+        (options: Partial<{ onClose?: () => void; host?: string }>) => {
+          mockUpdate(options);
+          Object.assign(currentConfig, options);
+        }
+      );
+
+      invokeSdkClose = () => {
+        if (!open) return;
+        open = false;
+        currentConfig.onClose?.();
+      };
+
+      return {
+        unmount: destroy,
+        update,
+        destroy,
+        show,
+        hide,
+        get isOpen() {
+          return open;
+        },
+        researchId: config.researchId ?? "test-research-id",
+        type: "popup",
+        iframe: null,
+        container: null,
+      };
+    }
+  ),
 }));
 
 import { openPopup } from "@perspective-ai/sdk";
+
 const mockOpenPopup = vi.mocked(openPopup);
 
 describe("usePopup", () => {
   beforeEach(() => {
     vi.clearAllMocks();
+    invokeSdkClose = null;
   });
 
   afterEach(() => {
     cleanup();
   });
 
-  it("returns open, close, toggle functions and isOpen state", () => {
+  it("returns open, close, toggle functions and initial state", () => {
     const { result } = renderHook(() =>
       usePopup({ researchId: "test-research-id" })
     );
@@ -39,47 +95,37 @@ describe("usePopup", () => {
     expect(result.current.close).toBeInstanceOf(Function);
     expect(result.current.toggle).toBeInstanceOf(Function);
     expect(result.current.isOpen).toBe(false);
-    expect(result.current.handle).toBeNull();
+    expect(result.current.handle).not.toBeNull();
   });
 
-  it("does not call openPopup on mount", () => {
+  it("preloads a hidden popup on mount", () => {
     renderHook(() => usePopup({ researchId: "test-research-id" }));
 
-    expect(mockOpenPopup).not.toHaveBeenCalled();
-  });
-
-  it("calls openPopup when open() is called", () => {
-    const { result } = renderHook(() =>
-      usePopup({ researchId: "test-research-id" })
-    );
-
-    act(() => {
-      result.current.open();
-    });
-
     expect(mockOpenPopup).toHaveBeenCalledTimes(1);
     expect(mockOpenPopup).toHaveBeenCalledWith(
       expect.objectContaining({
         researchId: "test-research-id",
+        _startHidden: true,
       })
     );
   });
 
-  it("sets isOpen to true when open() is called", () => {
+  it("opens the preloaded popup without recreating it", () => {
     const { result } = renderHook(() =>
       usePopup({ researchId: "test-research-id" })
     );
 
-    expect(result.current.isOpen).toBe(false);
-
     act(() => {
       result.current.open();
     });
 
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(mockShow).toHaveBeenCalledTimes(1);
     expect(result.current.isOpen).toBe(true);
+    expect(result.current.handle).not.toBeNull();
   });
 
-  it("calls destroy and sets isOpen to false when close() is called", () => {
+  it("hides the popup on close but keeps the handle for instant reopen", () => {
     const { result } = renderHook(() =>
       usePopup({ researchId: "test-research-id" })
     );
@@ -88,22 +134,37 @@ describe("usePopup", () => {
       result.current.open();
     });
 
-    expect(result.current.isOpen).toBe(true);
-
     act(() => {
       result.current.close();
     });
 
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(mockHide).toHaveBeenCalledTimes(1);
+    expect(mockDestroy).not.toHaveBeenCalled();
     expect(result.current.isOpen).toBe(false);
+    expect(result.current.handle).not.toBeNull();
   });
 
-  it("toggles open state", () => {
+  it("reuses the same popup on reopen after close", () => {
     const { result } = renderHook(() =>
       usePopup({ researchId: "test-research-id" })
     );
 
-    expect(result.current.isOpen).toBe(false);
+    act(() => {
+      result.current.open();
+      result.current.close();
+      result.current.open();
+    });
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(mockShow).toHaveBeenCalledTimes(2);
+    expect(mockHide).toHaveBeenCalledTimes(1);
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("toggles open state using the same underlying popup", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
 
     act(() => {
       result.current.toggle();
@@ -111,20 +172,22 @@ describe("usePopup", () => {
 
     expect(result.current.isOpen).toBe(true);
     expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(mockShow).toHaveBeenCalledTimes(1);
 
     act(() => {
       result.current.toggle();
     });
 
     expect(result.current.isOpen).toBe(false);
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(mockHide).toHaveBeenCalledTimes(1);
+    expect(mockDestroy).not.toHaveBeenCalled();
   });
 
-  it("passes config to openPopup", () => {
+  it("passes config to openPopup during preload creation", () => {
     const onReady = vi.fn();
     const onSubmit = vi.fn();
 
-    const { result } = renderHook(() =>
+    renderHook(() =>
       usePopup({
         researchId: "test-research-id",
         params: { source: "test" },
@@ -135,22 +198,19 @@ describe("usePopup", () => {
       })
     );
 
-    act(() => {
-      result.current.open();
-    });
-
     expect(mockOpenPopup).toHaveBeenCalledTimes(1);
     const config = mockOpenPopup.mock.calls[0]![0];
     expect(config.researchId).toBe("test-research-id");
     expect(config.params).toEqual({ source: "test" });
     expect(config.theme).toBe("dark");
     expect(config.host).toBe("https://custom.example.com");
+    expect(config._startHidden).toBe(true);
   });
 
-  it("supports controlled mode with open prop", () => {
+  it("supports controlled mode with open prop using show and hide", () => {
     const onOpenChange = vi.fn();
 
-    const { result, rerender } = renderHook(
+    const { rerender } = renderHook(
       ({ open }) =>
         usePopup({
           researchId: "test-research-id",
@@ -160,15 +220,15 @@ describe("usePopup", () => {
       { initialProps: { open: false } }
     );
 
-    expect(result.current.isOpen).toBe(false);
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
 
     rerender({ open: true });
-
     expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(mockShow).toHaveBeenCalledTimes(1);
 
     rerender({ open: false });
-
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(mockHide).toHaveBeenCalledTimes(1);
+    expect(mockDestroy).not.toHaveBeenCalled();
   });
 
   it("calls onOpenChange in controlled mode when open() is called", () => {
@@ -189,31 +249,140 @@ describe("usePopup", () => {
     expect(onOpenChange).toHaveBeenCalledWith(true);
   });
 
-  it("cleans up on unmount", () => {
-    const { result, unmount } = renderHook(() =>
+  it("destroys the popup on component unmount", () => {
+    const { unmount } = renderHook(() =>
       usePopup({ researchId: "test-research-id" })
     );
 
+    unmount();
+
+    expect(mockUpdate).toHaveBeenCalledWith({ onClose: undefined });
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the handle available after mount", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.handle).not.toBeNull();
+  });
+
+  it("updates state when the SDK triggers onClose without destroying the popup", () => {
+    const onClose = vi.fn();
+    const { result } = renderHook(() =>
+      usePopup({
+        researchId: "test-research-id",
+        onClose,
+      })
+    );
+
     act(() => {
       result.current.open();
     });
 
-    unmount();
+    act(() => {
+      invokeSdkClose?.();
+    });
 
-    expect(mockDestroy).toHaveBeenCalled();
+    expect(mockDestroy).not.toHaveBeenCalled();
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.handle).not.toBeNull();
+    expect(onClose).toHaveBeenCalledTimes(1);
   });
 
-  it("makes handle reactive - handle is available after open", () => {
-    const { result } = renderHook(() =>
-      usePopup({ researchId: "test-research-id" })
+  it("recreates the popup when researchId changes", () => {
+    const { rerender } = renderHook(
+      ({ researchId }) =>
+        usePopup({
+          researchId,
+        }),
+      { initialProps: { researchId: "research-1" } }
     );
 
-    expect(result.current.handle).toBeNull();
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+
+    rerender({ researchId: "research-2" });
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(2);
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("recreates a hidden popup when iframe-defining config changes", () => {
+    const onClose = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ params }) =>
+        usePopup({
+          researchId: "test-research-id",
+          params,
+          onClose,
+        }),
+      { initialProps: { params: { source: "first" } } }
+    );
+
+    expect(result.current.isOpen).toBe(false);
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+
+    rerender({ params: { source: "second" } });
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(2);
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(onClose).not.toHaveBeenCalled();
+    expect(result.current.isOpen).toBe(false);
+  });
+
+  it("keeps controlled popup open when recreated while open", () => {
+    const onOpenChange = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ researchId }) =>
+        usePopup({
+          researchId,
+          open: true,
+          onOpenChange,
+        }),
+      { initialProps: { researchId: "research-1" } }
+    );
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(result.current.isOpen).toBe(true);
+
+    rerender({ researchId: "research-2" });
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(2);
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(result.current.handle).not.toBeNull();
+    expect(result.current.isOpen).toBe(true);
+    expect(onOpenChange).not.toHaveBeenCalled();
+  });
+
+  it("keeps uncontrolled popup open when recreated while open", () => {
+    const onClose = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ params }) =>
+        usePopup({
+          researchId: "test-research-id",
+          params,
+          onClose,
+        }),
+      { initialProps: { params: { source: "first" } } }
+    );
 
     act(() => {
       result.current.open();
     });
 
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(result.current.isOpen).toBe(true);
+
+    rerender({ params: { source: "second" } });
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(2);
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
     expect(result.current.handle).not.toBeNull();
+    expect(result.current.isOpen).toBe(true);
+    expect(onClose).not.toHaveBeenCalled();
   });
 });

package/src/hooks/usePopup.ts

@@ -5,6 +5,9 @@ import {
   type EmbedHandle,
 } from "@perspective-ai/sdk";
 import { useStableCallback } from "./useStableCallback";
+import { useStableValue } from "./useStableValue";
+
+type PopupHandle = ReturnType<typeof openPopup>;
 
 /** Options for usePopup hook */
 export interface UsePopupOptions extends Omit<EmbedConfig, "type"> {
@@ -24,7 +27,7 @@ export interface UsePopupReturn {
   toggle: () => void;
   /** Whether the popup is currently open */
   isOpen: boolean;
-  /** The underlying SDK handle (null when closed) */
+  /** The underlying SDK handle (created on mount; may be null during initial render) */
   handle: EmbedHandle | null;
 }
 
@@ -65,10 +68,14 @@ export function usePopup(options: UsePopupOptions): UsePopupReturn {
 
   const [handle, setHandle] = useState<EmbedHandle | null>(null);
   const [internalOpen, setInternalOpen] = useState(false);
-  const handleRef = useRef<EmbedHandle | null>(null);
+  const handleRef = useRef<PopupHandle | null>(null);
 
   const isControlled = controlledOpen !== undefined;
   const isOpen = isControlled ? controlledOpen : internalOpen;
+  const initialHiddenRef = useRef(!isOpen);
+
+  const stableParams = useStableValue(params);
+  const stableBrand = useStableValue(brand);
 
   const stableOnReady = useStableCallback(onReady);
   const stableOnSubmit = useStableCallback(onSubmit);
@@ -86,72 +93,115 @@ export function usePopup(options: UsePopupOptions): UsePopupReturn {
     [isControlled, onOpenChange]
   );
 
+  const destroyPopup = useCallback(
+    (targetHandle: PopupHandle | null = handleRef.current) => {
+      if (!targetHandle) return;
+
+      targetHandle.update({ onClose: undefined });
+      targetHandle.destroy();
+
+      if (handleRef.current === targetHandle) {
+        handleRef.current = null;
+        setHandle(null);
+      }
+    },
+    []
+  );
+
   const handleClose = useCallback(() => {
-    handleRef.current = null;
-    setHandle(null);
     setOpen(false);
     onClose?.();
   }, [setOpen, onClose]);
 
   const stableOnClose = useStableCallback(handleClose);
 
-  const createPopup = useCallback(() => {
-    if (handleRef.current) return handleRef.current;
-
-    const newHandle = openPopup({
+  const createPopupHandle = useCallback(
+    (startHidden: boolean) =>
+      openPopup({
+        researchId,
+        params: stableParams,
+        brand: stableBrand,
+        theme,
+        host,
+        onReady: stableOnReady,
+        onSubmit: stableOnSubmit,
+        onNavigate: stableOnNavigate,
+        onClose: stableOnClose,
+        onError: stableOnError,
+        _startHidden: startHidden,
+      }),
+    [
       researchId,
-      params,
-      brand,
+      stableParams,
+      stableBrand,
       theme,
       host,
-      onReady: stableOnReady,
-      onSubmit: stableOnSubmit,
-      onNavigate: stableOnNavigate,
-      onClose: stableOnClose,
-      onError: stableOnError,
-    });
-
-    handleRef.current = newHandle;
-    setHandle(newHandle);
-    return newHandle;
-  }, [
-    researchId,
-    params,
-    brand,
-    theme,
-    host,
-    stableOnReady,
-    stableOnSubmit,
-    stableOnNavigate,
-    stableOnClose,
-    stableOnError,
-  ]);
-
-  const destroyPopup = useCallback(() => {
-    if (handleRef.current) {
-      handleRef.current.destroy();
-      handleRef.current = null;
-      setHandle(null);
+      stableOnReady,
+      stableOnSubmit,
+      stableOnNavigate,
+      stableOnClose,
+      stableOnError,
+    ]
+  );
+
+  const setPopupHandle = useCallback(
+    (startHidden: boolean) => {
+      const newHandle = createPopupHandle(startHidden);
+      handleRef.current = newHandle;
+      setHandle(newHandle);
+      return newHandle;
+    },
+    [createPopupHandle]
+  );
+
+  useEffect(() => {
+    const currentHandle = handleRef.current;
+    if (!currentHandle) return;
+
+    if (isOpen) {
+      currentHandle.show();
+    } else {
+      currentHandle.hide();
     }
-  }, []);
+  }, [isOpen]);
+
+  useEffect(() => {
+    // Stable callback/value wrappers are part of this hook's contract.
+    // When any iframe-defining input changes, recreate the underlying embed.
+    const nextHandle = setPopupHandle(
+      handleRef.current ? !handleRef.current.isOpen : initialHiddenRef.current
+    );
+
+    return () => {
+      if (handleRef.current === nextHandle) {
+        destroyPopup(nextHandle);
+      }
+    };
+  }, [destroyPopup, setPopupHandle]);
+
+  const ensurePopup = useCallback(() => {
+    if (handleRef.current) return handleRef.current;
+
+    return setPopupHandle(false);
+  }, [setPopupHandle]);
 
   const openFn = useCallback(() => {
     if (isControlled) {
       onOpenChange?.(true);
     } else {
-      createPopup();
+      ensurePopup().show();
       setInternalOpen(true);
     }
-  }, [isControlled, onOpenChange, createPopup]);
+  }, [ensurePopup, isControlled, onOpenChange]);
 
   const closeFn = useCallback(() => {
     if (isControlled) {
       onOpenChange?.(false);
     } else {
-      destroyPopup();
+      handleRef.current?.hide();
       setInternalOpen(false);
     }
-  }, [isControlled, onOpenChange, destroyPopup]);
+  }, [isControlled, onOpenChange]);
 
   const toggleFn = useCallback(() => {
     if (isOpen) {
@@ -161,25 +211,6 @@ export function usePopup(options: UsePopupOptions): UsePopupReturn {
     }
   }, [isOpen, openFn, closeFn]);
 
-  useEffect(() => {
-    if (!isControlled) return;
-
-    if (controlledOpen && !handleRef.current) {
-      createPopup();
-    } else if (!controlledOpen && handleRef.current) {
-      destroyPopup();
-    }
-  }, [controlledOpen, isControlled, createPopup, destroyPopup]);
-
-  useEffect(() => {
-    return () => {
-      if (handleRef.current) {
-        handleRef.current.destroy();
-        handleRef.current = null;
-      }
-    };
-  }, []);
-
   return {
     open: openFn,
     close: closeFn,