@perspective-ai/sdk-react 1.0.0-alpha.2 → 1.0.0-alpha.3

package/src/hooks/usePopup.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+import { usePopup } from "./usePopup";
+
+const mockDestroy = vi.fn();
+const mockUnmount = vi.fn();
+const mockUpdate = vi.fn();
+
+vi.mock("@perspective-ai/sdk", () => ({
+  openPopup: vi.fn(() => ({
+    unmount: mockUnmount,
+    update: mockUpdate,
+    destroy: mockDestroy,
+    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();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("returns open, close, toggle functions and isOpen state", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.open).toBeInstanceOf(Function);
+    expect(result.current.close).toBeInstanceOf(Function);
+    expect(result.current.toggle).toBeInstanceOf(Function);
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.handle).toBeNull();
+  });
+
+  it("does not call openPopup 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",
+      })
+    );
+  });
+
+  it("sets isOpen to true when open() is called", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.isOpen).toBe(false);
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("calls destroy and sets isOpen to false when close() is called", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(result.current.isOpen).toBe(true);
+
+    act(() => {
+      result.current.close();
+    });
+
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(result.current.isOpen).toBe(false);
+  });
+
+  it("toggles open state", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.isOpen).toBe(false);
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.isOpen).toBe(true);
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.isOpen).toBe(false);
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes config to openPopup", () => {
+    const onReady = vi.fn();
+    const onSubmit = vi.fn();
+
+    const { result } = renderHook(() =>
+      usePopup({
+        researchId: "test-research-id",
+        params: { source: "test" },
+        theme: "dark",
+        host: "https://custom.example.com",
+        onReady,
+        onSubmit,
+      })
+    );
+
+    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");
+  });
+
+  it("supports controlled mode with open prop", () => {
+    const onOpenChange = vi.fn();
+
+    const { result, rerender } = renderHook(
+      ({ open }) =>
+        usePopup({
+          researchId: "test-research-id",
+          open,
+          onOpenChange,
+        }),
+      { initialProps: { open: false } }
+    );
+
+    expect(result.current.isOpen).toBe(false);
+
+    rerender({ open: true });
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+
+    rerender({ open: false });
+
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls onOpenChange in controlled mode when open() is called", () => {
+    const onOpenChange = vi.fn();
+
+    const { result } = renderHook(() =>
+      usePopup({
+        researchId: "test-research-id",
+        open: false,
+        onOpenChange,
+      })
+    );
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+  });
+
+  it("cleans up on unmount", () => {
+    const { result, unmount } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    act(() => {
+      result.current.open();
+    });
+
+    unmount();
+
+    expect(mockDestroy).toHaveBeenCalled();
+  });
+
+  it("makes handle reactive - handle is available after open", () => {
+    const { result } = renderHook(() =>
+      usePopup({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.handle).toBeNull();
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(result.current.handle).not.toBeNull();
+  });
+});

package/src/hooks/usePopup.ts

@@ -0,0 +1,190 @@
+import { useCallback, useState, useEffect, useRef } from "react";
+import {
+  openPopup,
+  type EmbedConfig,
+  type EmbedHandle,
+} from "@perspective-ai/sdk";
+import { useStableCallback } from "./useStableCallback";
+
+/** Options for usePopup hook */
+export interface UsePopupOptions extends Omit<EmbedConfig, "type"> {
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/** Return type for usePopup hook */
+export interface UsePopupReturn {
+  /** Open the popup */
+  open: () => void;
+  /** Close the popup */
+  close: () => void;
+  /** Toggle the popup */
+  toggle: () => void;
+  /** Whether the popup is currently open */
+  isOpen: boolean;
+  /** The underlying SDK handle (null when closed) */
+  handle: EmbedHandle | null;
+}
+
+/**
+ * Headless hook for programmatic popup control.
+ * Use this when you need custom trigger elements or programmatic control.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with custom trigger
+ * const { open, isOpen } = usePopup({ researchId: "abc" });
+ * <MyCustomButton onClick={open}>Open Survey</MyCustomButton>
+ *
+ * // Controlled mode
+ * const [isOpen, setIsOpen] = useState(false);
+ * const popup = usePopup({
+ *   researchId: "abc",
+ *   open: isOpen,
+ *   onOpenChange: setIsOpen
+ * });
+ * ```
+ */
+export function usePopup(options: UsePopupOptions): UsePopupReturn {
+  const {
+    researchId,
+    params,
+    brand,
+    theme,
+    host,
+    onReady,
+    onSubmit,
+    onNavigate,
+    onClose,
+    onError,
+    open: controlledOpen,
+    onOpenChange,
+  } = options;
+
+  const [handle, setHandle] = useState<EmbedHandle | null>(null);
+  const [internalOpen, setInternalOpen] = useState(false);
+  const handleRef = useRef<EmbedHandle | null>(null);
+
+  const isControlled = controlledOpen !== undefined;
+  const isOpen = isControlled ? controlledOpen : internalOpen;
+
+  const stableOnReady = useStableCallback(onReady);
+  const stableOnSubmit = useStableCallback(onSubmit);
+  const stableOnNavigate = useStableCallback(onNavigate);
+  const stableOnError = useStableCallback(onError);
+
+  const setOpen = useCallback(
+    (value: boolean) => {
+      if (isControlled) {
+        onOpenChange?.(value);
+      } else {
+        setInternalOpen(value);
+      }
+    },
+    [isControlled, onOpenChange]
+  );
+
+  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({
+      researchId,
+      params,
+      brand,
+      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);
+    }
+  }, []);
+
+  const openFn = useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(true);
+    } else {
+      createPopup();
+      setInternalOpen(true);
+    }
+  }, [isControlled, onOpenChange, createPopup]);
+
+  const closeFn = useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(false);
+    } else {
+      destroyPopup();
+      setInternalOpen(false);
+    }
+  }, [isControlled, onOpenChange, destroyPopup]);
+
+  const toggleFn = useCallback(() => {
+    if (isOpen) {
+      closeFn();
+    } else {
+      openFn();
+    }
+  }, [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,
+    toggle: toggleFn,
+    isOpen,
+    handle,
+  };
+}

package/src/hooks/useSlider.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+import { useSlider } from "./useSlider";
+
+const mockDestroy = vi.fn();
+const mockUnmount = vi.fn();
+const mockUpdate = vi.fn();
+
+vi.mock("@perspective-ai/sdk", () => ({
+  openSlider: vi.fn(() => ({
+    unmount: mockUnmount,
+    update: mockUpdate,
+    destroy: mockDestroy,
+    researchId: "test-research-id",
+    type: "slider",
+    iframe: null,
+    container: null,
+  })),
+}));
+
+import { openSlider } from "@perspective-ai/sdk";
+const mockOpenSlider = vi.mocked(openSlider);
+
+describe("useSlider", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("returns open, close, toggle functions and isOpen state", () => {
+    const { result } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.open).toBeInstanceOf(Function);
+    expect(result.current.close).toBeInstanceOf(Function);
+    expect(result.current.toggle).toBeInstanceOf(Function);
+    expect(result.current.isOpen).toBe(false);
+    expect(result.current.handle).toBeNull();
+  });
+
+  it("does not call openSlider on mount", () => {
+    renderHook(() => useSlider({ researchId: "test-research-id" }));
+
+    expect(mockOpenSlider).not.toHaveBeenCalled();
+  });
+
+  it("calls openSlider when open() is called", () => {
+    const { result } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(mockOpenSlider).toHaveBeenCalledTimes(1);
+    expect(mockOpenSlider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        researchId: "test-research-id",
+      })
+    );
+  });
+
+  it("sets isOpen to true when open() is called", () => {
+    const { result } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.isOpen).toBe(false);
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(result.current.isOpen).toBe(true);
+  });
+
+  it("calls destroy and sets isOpen to false when close() is called", () => {
+    const { result } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(result.current.isOpen).toBe(true);
+
+    act(() => {
+      result.current.close();
+    });
+
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+    expect(result.current.isOpen).toBe(false);
+  });
+
+  it("toggles open state", () => {
+    const { result } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.isOpen).toBe(false);
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.isOpen).toBe(true);
+    expect(mockOpenSlider).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      result.current.toggle();
+    });
+
+    expect(result.current.isOpen).toBe(false);
+    expect(mockDestroy).toHaveBeenCalledTimes(1);
+  });
+
+  it("cleans up on unmount", () => {
+    const { result, unmount } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    act(() => {
+      result.current.open();
+    });
+
+    unmount();
+
+    expect(mockDestroy).toHaveBeenCalled();
+  });
+
+  it("makes handle reactive - handle is available after open", () => {
+    const { result } = renderHook(() =>
+      useSlider({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.handle).toBeNull();
+
+    act(() => {
+      result.current.open();
+    });
+
+    expect(result.current.handle).not.toBeNull();
+  });
+});