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

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/useStableCallback.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useStableCallback } from "./useStableCallback";
+
+describe("useStableCallback", () => {
+  it("returns a stable function reference", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(({ cb }) => useStableCallback(cb), {
+      initialProps: { cb: callback },
+    });
+
+    const firstRef = result.current;
+
+    // Rerender with same callback
+    rerender({ cb: callback });
+    expect(result.current).toBe(firstRef);
+
+    // Rerender with new callback
+    const newCallback = vi.fn();
+    rerender({ cb: newCallback });
+    expect(result.current).toBe(firstRef); // Still same reference
+  });
+
+  it("calls the latest callback", () => {
+    const callback1 = vi.fn();
+    const callback2 = vi.fn();
+
+    const { result, rerender } = renderHook(({ cb }) => useStableCallback(cb), {
+      initialProps: { cb: callback1 },
+    });
+
+    // Call with first callback
+    act(() => {
+      result.current("arg1");
+    });
+    expect(callback1).toHaveBeenCalledWith("arg1");
+    expect(callback2).not.toHaveBeenCalled();
+
+    // Update to second callback
+    rerender({ cb: callback2 });
+
+    // Call should now use second callback
+    act(() => {
+      result.current("arg2");
+    });
+    expect(callback2).toHaveBeenCalledWith("arg2");
+    expect(callback1).toHaveBeenCalledTimes(1); // Still only called once
+  });
+
+  it("handles undefined callback", () => {
+    const { result } = renderHook(() => useStableCallback(undefined));
+
+    // Should not throw when called
+    expect(() => {
+      act(() => {
+        result.current("test");
+      });
+    }).not.toThrow();
+  });
+
+  it("passes through all arguments", () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useStableCallback(callback));
+
+    act(() => {
+      result.current("a", "b", 123, { key: "value" });
+    });
+
+    expect(callback).toHaveBeenCalledWith("a", "b", 123, { key: "value" });
+  });
+
+  it("returns the callback's return value", () => {
+    const callback = vi.fn().mockReturnValue("result");
+    const { result } = renderHook(() => useStableCallback(callback));
+
+    let returnValue: string | undefined;
+    act(() => {
+      returnValue = result.current();
+    });
+
+    expect(returnValue).toBe("result");
+  });
+});

package/src/hooks/useStableCallback.ts

@@ -0,0 +1,20 @@
+import { useRef, useCallback, useLayoutEffect, useEffect } from "react";
+
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useStableCallback<T extends (...args: any[]) => any>(
+  callback: T | undefined
+): T {
+  const callbackRef = useRef(callback);
+
+  useIsomorphicLayoutEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  return useCallback(
+    ((...args: Parameters<T>) => callbackRef.current?.(...args)) as T,
+    []
+  );
+}

package/src/hooks/useThemeSync.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useThemeSync } from "./useThemeSync";
+
+describe("useThemeSync", () => {
+  let mediaQueryListeners: Array<(e: MediaQueryListEvent) => void> = [];
+  let mockMatches = false;
+
+  beforeEach(() => {
+    mediaQueryListeners = [];
+    mockMatches = false;
+
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn().mockImplementation((query: string) => ({
+        matches: query === "(prefers-color-scheme: dark)" ? mockMatches : false,
+        media: query,
+        addEventListener: vi.fn((_, handler) => {
+          mediaQueryListeners.push(handler);
+        }),
+        removeEventListener: vi.fn((_, handler) => {
+          mediaQueryListeners = mediaQueryListeners.filter(
+            (h) => h !== handler
+          );
+        }),
+      })),
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns light for explicit light theme", () => {
+    const { result } = renderHook(() => useThemeSync("light"));
+    expect(result.current).toBe("light");
+  });
+
+  it("returns dark for explicit dark theme", () => {
+    const { result } = renderHook(() => useThemeSync("dark"));
+    expect(result.current).toBe("dark");
+  });
+
+  it("returns light initially for SSR safety when theme is system", () => {
+    // Before useEffect runs, should return "light" for consistent SSR
+    const { result } = renderHook(() => useThemeSync("system"));
+    // After effect runs, it will update based on system preference
+    // But the initial render should be "light" for SSR
+    expect(result.current).toBe("light"); // mockMatches is false
+  });
+
+  it("returns dark when system prefers dark and theme is system", () => {
+    mockMatches = true;
+    const { result } = renderHook(() => useThemeSync("system"));
+    // After useEffect runs, should be dark
+    expect(result.current).toBe("dark");
+  });
+
+  it("defaults to system when no theme provided", () => {
+    mockMatches = true;
+    const { result } = renderHook(() => useThemeSync());
+    expect(result.current).toBe("dark");
+  });
+
+  it("updates when theme prop changes", () => {
+    type ThemeValue = "light" | "dark" | "system";
+    const { result, rerender } = renderHook(
+      ({ theme }: { theme: ThemeValue }) => useThemeSync(theme),
+      { initialProps: { theme: "light" as ThemeValue } }
+    );
+
+    expect(result.current).toBe("light");
+
+    rerender({ theme: "dark" as ThemeValue });
+    expect(result.current).toBe("dark");
+
+    rerender({ theme: "light" as ThemeValue });
+    expect(result.current).toBe("light");
+  });
+
+  it("responds to system theme changes when theme is system", () => {
+    mockMatches = false;
+    const { result } = renderHook(() => useThemeSync("system"));
+
+    expect(result.current).toBe("light");
+
+    // Simulate system theme change
+    act(() => {
+      mediaQueryListeners.forEach((handler) => {
+        handler({ matches: true } as MediaQueryListEvent);
+      });
+    });
+
+    expect(result.current).toBe("dark");
+
+    // Change back
+    act(() => {
+      mediaQueryListeners.forEach((handler) => {
+        handler({ matches: false } as MediaQueryListEvent);
+      });
+    });
+
+    expect(result.current).toBe("light");
+  });
+
+  it("cleans up listener on unmount", () => {
+    const { unmount } = renderHook(() => useThemeSync("system"));
+
+    expect(mediaQueryListeners.length).toBe(1);
+
+    unmount();
+
+    expect(mediaQueryListeners.length).toBe(0);
+  });
+
+  it("cleans up listener when theme changes from system to explicit", () => {
+    const { rerender } = renderHook(({ theme }) => useThemeSync(theme), {
+      initialProps: { theme: "system" as "light" | "dark" | "system" },
+    });
+
+    expect(mediaQueryListeners.length).toBe(1);
+
+    rerender({ theme: "dark" });
+
+    expect(mediaQueryListeners.length).toBe(0);
+  });
+});

package/src/hooks/useThemeSync.ts

@@ -0,0 +1,36 @@
+import { useState, useEffect } from "react";
+
+type Theme = "light" | "dark";
+type ThemeInput = "light" | "dark" | "system";
+
+/**
+ * Hook to resolve theme based on override and system preference.
+ * Listens for system preference changes when theme is "system".
+ */
+export function useThemeSync(theme: ThemeInput = "system"): Theme {
+  // Always start with a deterministic value for SSR hydration safety.
+  // The actual system preference is synced in useEffect.
+  const [resolved, setResolved] = useState<Theme>(
+    theme !== "system" ? theme : "light"
+  );
+
+  useEffect(() => {
+    if (theme !== "system") {
+      setResolved(theme);
+      return;
+    }
+
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+
+    // Set initial value
+    setResolved(mq.matches ? "dark" : "light");
+
+    const handler = (e: MediaQueryListEvent) =>
+      setResolved(e.matches ? "dark" : "light");
+
+    mq.addEventListener("change", handler);
+    return () => mq.removeEventListener("change", handler);
+  }, [theme]);
+
+  return resolved;
+}