@perspective-ai/sdk-react 0.0.0-pr-21-20260224144030

package/src/Widget.test.tsx

@@ -0,0 +1,308 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { createRef, StrictMode } from "react";
+import { Widget } from "./Widget";
+import type { EmbedHandle } from "@perspective-ai/sdk";
+
+// Mock the core embed package
+vi.mock("@perspective-ai/sdk", () => ({
+  createWidget: vi.fn(() => ({
+    unmount: vi.fn(),
+    update: vi.fn(),
+    destroy: vi.fn(),
+    researchId: "test-research-id",
+    type: "widget",
+    iframe: null,
+    container: null,
+  })),
+}));
+
+import { createWidget } from "@perspective-ai/sdk";
+const mockCreateWidget = vi.mocked(createWidget);
+
+describe("Widget", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders a div container", () => {
+    render(<Widget researchId="test-research-id" />);
+
+    const container = screen.getByTestId("perspective-widget");
+    expect(container).toBeDefined();
+    expect(container.tagName).toBe("DIV");
+  });
+
+  it("has default minHeight of 500px", () => {
+    render(<Widget researchId="test-research-id" />);
+
+    const container = screen.getByTestId("perspective-widget");
+    expect(container.style.minHeight).toBe("500px");
+  });
+
+  it("accepts custom className", () => {
+    render(<Widget researchId="test-research-id" className="custom-class" />);
+
+    const container = screen.getByTestId("perspective-widget");
+    expect(container.classList.contains("custom-class")).toBe(true);
+  });
+
+  it("accepts custom style", () => {
+    render(
+      <Widget
+        researchId="test-research-id"
+        style={{ backgroundColor: "red", minHeight: 600 }}
+      />
+    );
+
+    const container = screen.getByTestId("perspective-widget");
+    expect(container.style.backgroundColor).toBe("red");
+    expect(container.style.minHeight).toBe("600px"); // Custom overrides default
+  });
+
+  it("calls createWidget with correct config", () => {
+    const onReady = vi.fn();
+    const onSubmit = vi.fn();
+
+    render(
+      <Widget
+        researchId="test-research-id"
+        params={{ source: "test" }}
+        theme="dark"
+        host="https://custom.example.com"
+        onReady={onReady}
+        onSubmit={onSubmit}
+      />
+    );
+
+    expect(mockCreateWidget).toHaveBeenCalledTimes(1);
+    const [container, config] = mockCreateWidget.mock.calls[0]!;
+    expect(container).toBeInstanceOf(HTMLDivElement);
+    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("calls unmount on cleanup", () => {
+    const mockUnmount = vi.fn();
+    mockCreateWidget.mockReturnValueOnce({
+      unmount: mockUnmount,
+      update: vi.fn(),
+      destroy: vi.fn(),
+      researchId: "test-research-id",
+      type: "widget",
+      iframe: null,
+      container: null,
+    });
+
+    const { unmount } = render(<Widget researchId="test-research-id" />);
+
+    expect(mockUnmount).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(mockUnmount).toHaveBeenCalled();
+  });
+
+  it("exposes handle via embedRef", () => {
+    const mockHandle: EmbedHandle = {
+      unmount: vi.fn(),
+      update: vi.fn(),
+      destroy: vi.fn(),
+      researchId: "test-research-id",
+      type: "widget",
+      iframe: null,
+      container: null,
+    };
+    mockCreateWidget.mockReturnValueOnce(mockHandle);
+
+    const embedRef = createRef<EmbedHandle | null>();
+
+    render(<Widget researchId="test-research-id" embedRef={embedRef} />);
+
+    expect(embedRef.current).toBe(mockHandle);
+  });
+
+  it("clears embedRef on unmount", () => {
+    const embedRef = createRef<EmbedHandle | null>();
+
+    const { unmount } = render(
+      <Widget researchId="test-research-id" embedRef={embedRef} />
+    );
+
+    expect(embedRef.current).not.toBeNull();
+
+    unmount();
+
+    expect(embedRef.current).toBeNull();
+  });
+
+  it("re-creates widget when researchId changes", () => {
+    const { rerender } = render(<Widget researchId="research-1" />);
+
+    expect(mockCreateWidget).toHaveBeenCalledTimes(1);
+
+    rerender(<Widget researchId="research-2" />);
+
+    expect(mockCreateWidget).toHaveBeenCalledTimes(2);
+  });
+
+  it("passes additional div props", () => {
+    render(
+      <Widget
+        researchId="test-research-id"
+        aria-label="Interview widget"
+        role="region"
+      />
+    );
+
+    const container = screen.getByTestId("perspective-widget");
+    expect(container.getAttribute("aria-label")).toBe("Interview widget");
+    expect(container.getAttribute("role")).toBe("region");
+  });
+
+  describe("StrictMode behavior", () => {
+    it("creates only one iframe in StrictMode (mock inserts real DOM)", () => {
+      const mockUnmount = vi.fn();
+      mockCreateWidget.mockImplementation((containerEl: HTMLElement | null) => {
+        if (!containerEl) {
+          return {
+            unmount: vi.fn(),
+            update: vi.fn(),
+            destroy: vi.fn(),
+            researchId: "test-research-id",
+            type: "widget" as const,
+            iframe: null,
+            container: null,
+          };
+        }
+        const iframe = document.createElement("iframe");
+        iframe.setAttribute("data-perspective", "true");
+        containerEl.appendChild(iframe);
+        return {
+          unmount: () => {
+            mockUnmount();
+            iframe.remove();
+          },
+          update: vi.fn(),
+          destroy: vi.fn(),
+          researchId: "test-research-id",
+          type: "widget" as const,
+          iframe,
+          container: containerEl,
+        };
+      });
+
+      render(
+        <StrictMode>
+          <Widget researchId="test-research-id" />
+        </StrictMode>
+      );
+
+      const container = screen.getByTestId("perspective-widget");
+      const iframes = container.querySelectorAll("iframe[data-perspective]");
+      expect(iframes.length).toBe(1);
+    });
+
+    it("properly cleans up in StrictMode double-mount cycle", () => {
+      const mockUnmount = vi.fn();
+      mockCreateWidget.mockImplementation((containerEl: HTMLElement | null) => {
+        if (!containerEl) {
+          return {
+            unmount: vi.fn(),
+            update: vi.fn(),
+            destroy: vi.fn(),
+            researchId: "test-research-id",
+            type: "widget" as const,
+            iframe: null,
+            container: null,
+          };
+        }
+        const iframe = document.createElement("iframe");
+        iframe.setAttribute("data-perspective", "true");
+        containerEl.appendChild(iframe);
+        return {
+          unmount: () => {
+            mockUnmount();
+            iframe.remove();
+          },
+          update: vi.fn(),
+          destroy: vi.fn(),
+          researchId: "test-research-id",
+          type: "widget" as const,
+          iframe,
+          container: containerEl,
+        };
+      });
+
+      const { unmount } = render(
+        <StrictMode>
+          <Widget researchId="test-research-id" />
+        </StrictMode>
+      );
+
+      unmount();
+
+      expect(mockUnmount).toHaveBeenCalled();
+      const container = screen.queryByTestId("perspective-widget");
+      if (container) {
+        const iframes = container.querySelectorAll("iframe[data-perspective]");
+        expect(iframes.length).toBe(0);
+      }
+    });
+
+    it("StrictMode double-mount calls createWidget twice but cleanup prevents duplicates", () => {
+      const createCalls: number[] = [];
+      const unmountCalls: number[] = [];
+      let callCount = 0;
+
+      mockCreateWidget.mockImplementation((containerEl: HTMLElement | null) => {
+        if (!containerEl) {
+          return {
+            unmount: vi.fn(),
+            update: vi.fn(),
+            destroy: vi.fn(),
+            researchId: "test-research-id",
+            type: "widget" as const,
+            iframe: null,
+            container: null,
+          };
+        }
+        const thisCall = ++callCount;
+        createCalls.push(thisCall);
+        const iframe = document.createElement("iframe");
+        iframe.setAttribute("data-perspective", "true");
+        iframe.setAttribute("data-call", String(thisCall));
+        containerEl.appendChild(iframe);
+        return {
+          unmount: () => {
+            unmountCalls.push(thisCall);
+            iframe.remove();
+          },
+          update: vi.fn(),
+          destroy: vi.fn(),
+          researchId: "test-research-id",
+          type: "widget" as const,
+          iframe,
+          container: containerEl,
+        };
+      });
+
+      render(
+        <StrictMode>
+          <Widget researchId="test-research-id" />
+        </StrictMode>
+      );
+
+      const container = screen.getByTestId("perspective-widget");
+      const iframes = container.querySelectorAll("iframe[data-perspective]");
+      expect(iframes.length).toBe(1);
+      expect(createCalls.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+});

package/src/Widget.tsx

@@ -0,0 +1,100 @@
+import { useRef, useEffect, type HTMLAttributes, type RefObject } from "react";
+import {
+  createWidget,
+  type EmbedConfig,
+  type EmbedHandle,
+} from "@perspective-ai/sdk";
+import { useStableCallback } from "./hooks/useStableCallback";
+
+export interface WidgetProps
+  extends
+    Omit<EmbedConfig, "type">,
+    Omit<HTMLAttributes<HTMLDivElement>, "onError" | "onSubmit"> {
+  /** Ref to access the embed handle for programmatic control */
+  embedRef?: RefObject<EmbedHandle | null>;
+}
+
+/**
+ * Inline widget embed component.
+ * Renders the interview directly in a container.
+ */
+export function Widget({
+  researchId,
+  params,
+  brand,
+  theme,
+  host,
+  onReady,
+  onSubmit,
+  onNavigate,
+  onClose,
+  onError,
+  embedRef,
+  className,
+  style,
+  ...divProps
+}: WidgetProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const handleRef = useRef<EmbedHandle | null>(null);
+
+  // Stable callbacks to avoid re-mounting on callback changes
+  const stableOnReady = useStableCallback(onReady);
+  const stableOnSubmit = useStableCallback(onSubmit);
+  const stableOnNavigate = useStableCallback(onNavigate);
+  const stableOnClose = useStableCallback(onClose);
+  const stableOnError = useStableCallback(onError);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const handle = createWidget(container, {
+      researchId,
+      params,
+      brand,
+      theme,
+      host,
+      onReady: stableOnReady,
+      onSubmit: stableOnSubmit,
+      onNavigate: stableOnNavigate,
+      onClose: stableOnClose,
+      onError: stableOnError,
+    });
+
+    handleRef.current = handle;
+
+    if (embedRef) {
+      embedRef.current = handle;
+    }
+
+    return () => {
+      handle.unmount();
+      handleRef.current = null;
+      if (embedRef) {
+        embedRef.current = null;
+      }
+    };
+  }, [
+    researchId,
+    params,
+    brand,
+    theme,
+    host,
+    stableOnReady,
+    stableOnSubmit,
+    stableOnNavigate,
+    stableOnClose,
+    stableOnError,
+    embedRef,
+  ]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{ minHeight: 500, ...style }}
+      data-testid="perspective-widget"
+      {...divProps}
+    />
+  );
+}

package/src/hooks/useAutoOpen.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, cleanup, act } from "@testing-library/react";
+import { useAutoOpen } from "./useAutoOpen";
+
+vi.mock("@perspective-ai/sdk", () => ({
+  openPopup: vi.fn(() => ({
+    unmount: vi.fn(),
+    update: vi.fn(),
+    destroy: vi.fn(),
+    researchId: "test-id",
+    type: "popup",
+    iframe: null,
+    container: null,
+  })),
+  setupTrigger: vi.fn(() => vi.fn()),
+  shouldShow: vi.fn(() => true),
+  markShown: vi.fn(),
+}));
+
+// useStableCallback just passes through in tests
+vi.mock("./useStableCallback", () => ({
+  useStableCallback: (cb: unknown) => cb,
+}));
+
+import {
+  openPopup,
+  setupTrigger,
+  shouldShow,
+  markShown,
+} from "@perspective-ai/sdk";
+
+const mockOpenPopup = vi.mocked(openPopup);
+const mockSetupTrigger = vi.mocked(setupTrigger);
+const mockShouldShow = vi.mocked(shouldShow);
+const mockMarkShown = vi.mocked(markShown);
+
+describe("useAutoOpen", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Restore defaults after clearAllMocks resets implementations
+    mockShouldShow.mockReturnValue(true);
+    mockSetupTrigger.mockReturnValue(vi.fn());
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    cleanup();
+  });
+
+  it("calls setupTrigger on mount when shouldShow returns true", () => {
+    renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "timeout", delay: 5000 },
+      })
+    );
+
+    expect(mockShouldShow).toHaveBeenCalledWith("test-id", "session");
+    expect(mockSetupTrigger).toHaveBeenCalledWith(
+      { type: "timeout", delay: 5000 },
+      expect.any(Function)
+    );
+  });
+
+  it("does not call setupTrigger when shouldShow returns false", () => {
+    mockShouldShow.mockReturnValue(false);
+
+    renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "timeout", delay: 5000 },
+      })
+    );
+
+    expect(mockSetupTrigger).not.toHaveBeenCalled();
+  });
+
+  it("calls markShown and openPopup when trigger fires", () => {
+    let triggerCallback: () => void;
+    mockSetupTrigger.mockImplementation((_config, cb) => {
+      triggerCallback = cb;
+      return vi.fn();
+    });
+
+    const { result } = renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "timeout", delay: 5000 },
+        showOnce: "visitor",
+      })
+    );
+
+    expect(result.current.triggered).toBe(false);
+
+    act(() => triggerCallback!());
+
+    expect(mockMarkShown).toHaveBeenCalledWith("test-id", "visitor");
+    expect(mockOpenPopup).toHaveBeenCalledWith(
+      expect.objectContaining({ researchId: "test-id" })
+    );
+    expect(result.current.triggered).toBe(true);
+  });
+
+  it("only fires once even if trigger callback called multiple times", () => {
+    let triggerCallback: () => void;
+    mockSetupTrigger.mockImplementation((_config, cb) => {
+      triggerCallback = cb;
+      return vi.fn();
+    });
+
+    const { result } = renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "timeout", delay: 5000 },
+      })
+    );
+
+    act(() => triggerCallback!());
+    act(() => triggerCallback!());
+
+    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
+    expect(result.current.triggered).toBe(true);
+  });
+
+  it("defaults showOnce to session", () => {
+    renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "exit-intent" },
+      })
+    );
+
+    expect(mockShouldShow).toHaveBeenCalledWith("test-id", "session");
+  });
+
+  it("calls cleanup on unmount", () => {
+    const mockCleanup = vi.fn();
+    mockSetupTrigger.mockReturnValue(mockCleanup);
+
+    const { unmount } = renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "timeout", delay: 5000 },
+      })
+    );
+
+    unmount();
+
+    expect(mockCleanup).toHaveBeenCalled();
+  });
+
+  it("cancel() stops the trigger", () => {
+    const mockCleanup = vi.fn();
+    mockSetupTrigger.mockReturnValue(mockCleanup);
+
+    const { result } = renderHook(() =>
+      useAutoOpen({
+        researchId: "test-id",
+        trigger: { type: "timeout", delay: 5000 },
+      })
+    );
+
+    result.current.cancel();
+
+    expect(mockCleanup).toHaveBeenCalled();
+  });
+});

package/src/hooks/useAutoOpen.ts

@@ -0,0 +1,63 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+import {
+  openPopup,
+  setupTrigger,
+  shouldShow,
+  markShown,
+} from "@perspective-ai/sdk";
+import type { EmbedConfig, TriggerConfig, ShowOnce } from "@perspective-ai/sdk";
+import { useStableCallback } from "./useStableCallback";
+
+export interface UseAutoOpenOptions extends Omit<
+  EmbedConfig,
+  "type" | "autoOpen"
+> {
+  trigger: TriggerConfig;
+  showOnce?: ShowOnce; // default: "session"
+}
+
+export interface UseAutoOpenReturn {
+  /** Cancel the pending trigger */
+  cancel: () => void;
+  /** Whether the trigger has fired */
+  triggered: boolean;
+}
+
+export function useAutoOpen(options: UseAutoOpenOptions): UseAutoOpenReturn {
+  const { trigger, showOnce = "session", researchId, ...embedConfig } = options;
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const [triggered, setTriggered] = useState(false);
+  const triggerDelay = trigger.type === "timeout" ? trigger.delay : undefined;
+
+  // Fix #5: useStableCallback so the trigger always calls with latest config
+  const stableOnTrigger = useStableCallback(() => {
+    markShown(researchId, showOnce);
+    openPopup({ researchId, ...embedConfig });
+  });
+
+  useEffect(() => {
+    if (!shouldShow(researchId, showOnce)) return;
+
+    cleanupRef.current = setupTrigger(trigger, () => {
+      setTriggered((prev) => {
+        if (prev) return prev; // already fired
+        stableOnTrigger();
+        return true;
+      });
+    });
+
+    return () => {
+      cleanupRef.current?.();
+      cleanupRef.current = null;
+    };
+    // Primitive deps only — avoids re-triggering on object identity changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [researchId, trigger.type, triggerDelay, showOnce]);
+
+  const cancel = useCallback(() => {
+    cleanupRef.current?.();
+    cleanupRef.current = null;
+  }, []);
+
+  return { cancel, triggered };
+}