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

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@perspective-ai/sdk-react",
+  "version": "1.0.0-alpha.2",
+  "description": "React components for Perspective AI embed SDK",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "perspective",
+    "embed",
+    "react",
+    "interview",
+    "widget"
+  ],
+  "author": "Perspective AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Perspective-AI/perspective.git",
+    "directory": "packages/sdk-react"
+  },
+  "bugs": {
+    "url": "https://github.com/Perspective-AI/perspective/issues"
+  },
+  "homepage": "https://getperspective.ai",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@perspective-ai/sdk": "^1.0.0-alpha.2"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.1",
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/FloatBubble.test.tsx

@@ -0,0 +1,173 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import { FloatBubble } from "./FloatBubble";
+import type { FloatHandle } from "@perspective-ai/sdk";
+
+const mockUnmount = vi.fn();
+const mockOpen = vi.fn();
+const mockClose = vi.fn();
+const mockToggle = vi.fn();
+const mockUpdate = vi.fn();
+
+vi.mock("@perspective-ai/sdk", () => ({
+  createFloatBubble: vi.fn(() => ({
+    unmount: mockUnmount,
+    update: mockUpdate,
+    destroy: mockUnmount,
+    open: mockOpen,
+    close: mockClose,
+    toggle: mockToggle,
+    researchId: "test-research-id",
+    type: "float",
+    iframe: null,
+    container: null,
+    isOpen: false,
+  })),
+}));
+
+import { createFloatBubble } from "@perspective-ai/sdk";
+const mockCreateFloatBubble = vi.mocked(createFloatBubble);
+
+describe("FloatBubble", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders nothing (bubble is added to document.body)", () => {
+    const { container } = render(<FloatBubble researchId="test-research-id" />);
+
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("calls createFloatBubble on mount", () => {
+    render(<FloatBubble researchId="test-research-id" />);
+
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(1);
+    expect(mockCreateFloatBubble).toHaveBeenCalledWith(
+      expect.objectContaining({
+        researchId: "test-research-id",
+      })
+    );
+  });
+
+  it("calls unmount on cleanup", () => {
+    const { unmount } = render(<FloatBubble researchId="test-research-id" />);
+
+    expect(mockUnmount).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes config to createFloatBubble", () => {
+    const onReady = vi.fn();
+    const onSubmit = vi.fn();
+    const onClose = vi.fn();
+    const onError = vi.fn();
+
+    render(
+      <FloatBubble
+        researchId="test-research-id"
+        params={{ source: "test" }}
+        theme="dark"
+        host="https://custom.example.com"
+        onReady={onReady}
+        onSubmit={onSubmit}
+        onClose={onClose}
+        onError={onError}
+      />
+    );
+
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(1);
+    const config = mockCreateFloatBubble.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("exposes handle via embedRef", () => {
+    const mockHandle: FloatHandle = {
+      unmount: mockUnmount,
+      update: mockUpdate,
+      destroy: mockUnmount,
+      open: mockOpen,
+      close: mockClose,
+      toggle: mockToggle,
+      researchId: "test-research-id",
+      type: "float",
+      iframe: null,
+      container: null,
+      isOpen: false,
+    };
+    mockCreateFloatBubble.mockReturnValueOnce(mockHandle);
+
+    const embedRef = createRef<FloatHandle | null>();
+
+    render(<FloatBubble researchId="test-research-id" embedRef={embedRef} />);
+
+    expect(embedRef.current).toBe(mockHandle);
+  });
+
+  it("clears embedRef on unmount", () => {
+    const embedRef = createRef<FloatHandle | null>();
+
+    const { unmount } = render(
+      <FloatBubble researchId="test-research-id" embedRef={embedRef} />
+    );
+
+    expect(embedRef.current).not.toBeNull();
+
+    unmount();
+
+    expect(embedRef.current).toBeNull();
+  });
+
+  it("re-creates float bubble when researchId changes", () => {
+    const { rerender } = render(<FloatBubble researchId="research-1" />);
+
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(1);
+
+    rerender(<FloatBubble researchId="research-2" />);
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-creates float bubble when theme changes", () => {
+    const { rerender } = render(
+      <FloatBubble researchId="test-research-id" theme="light" />
+    );
+
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(1);
+
+    rerender(<FloatBubble researchId="test-research-id" theme="dark" />);
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(2);
+  });
+
+  it("passes brand colors to createFloatBubble", () => {
+    render(
+      <FloatBubble
+        researchId="test-research-id"
+        brand={{
+          light: { primary: "#ff0000", bg: "#ffffff" },
+          dark: { primary: "#0000ff", bg: "#000000" },
+        }}
+      />
+    );
+
+    const config = mockCreateFloatBubble.mock.calls[0]![0];
+    expect(config.brand).toEqual({
+      light: { primary: "#ff0000", bg: "#ffffff" },
+      dark: { primary: "#0000ff", bg: "#000000" },
+    });
+  });
+});

package/src/FloatBubble.tsx

@@ -0,0 +1,83 @@
+import { useRef, useEffect, type RefObject } from "react";
+import {
+  createFloatBubble,
+  type EmbedConfig,
+  type FloatHandle,
+} from "@perspective-ai/sdk";
+import { useStableCallback } from "./hooks/useStableCallback";
+
+export interface FloatBubbleProps extends Omit<EmbedConfig, "type"> {
+  /** Ref to access the handle for programmatic control */
+  embedRef?: RefObject<FloatHandle | null>;
+}
+
+/**
+ * Floating bubble widget that expands into a chat window.
+ * Renders a floating button in the corner of the screen.
+ */
+export function FloatBubble({
+  researchId,
+  params,
+  brand,
+  theme,
+  host,
+  onReady,
+  onSubmit,
+  onNavigate,
+  onClose,
+  onError,
+  embedRef,
+}: FloatBubbleProps) {
+  const handleRef = useRef<FloatHandle | null>(null);
+
+  // Stable callbacks
+  const stableOnReady = useStableCallback(onReady);
+  const stableOnSubmit = useStableCallback(onSubmit);
+  const stableOnNavigate = useStableCallback(onNavigate);
+  const stableOnClose = useStableCallback(onClose);
+  const stableOnError = useStableCallback(onError);
+
+  useEffect(() => {
+    const handle = createFloatBubble({
+      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,
+  ]);
+
+  // This component doesn't render anything - the bubble is added to document.body
+  return null;
+}

package/src/Fullpage.test.tsx

@@ -0,0 +1,164 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import { Fullpage } from "./Fullpage";
+import type { EmbedHandle } from "@perspective-ai/sdk";
+
+const mockUnmount = vi.fn();
+const mockUpdate = vi.fn();
+
+vi.mock("@perspective-ai/sdk", () => ({
+  createFullpage: vi.fn(() => ({
+    unmount: mockUnmount,
+    update: mockUpdate,
+    destroy: mockUnmount,
+    researchId: "test-research-id",
+    type: "fullpage",
+    iframe: null,
+    container: null,
+  })),
+}));
+
+import { createFullpage } from "@perspective-ai/sdk";
+const mockCreateFullpage = vi.mocked(createFullpage);
+
+describe("Fullpage", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("renders nothing (fullpage overlay is added to document.body)", () => {
+    const { container } = render(<Fullpage researchId="test-research-id" />);
+
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("calls createFullpage on mount", () => {
+    render(<Fullpage researchId="test-research-id" />);
+
+    expect(mockCreateFullpage).toHaveBeenCalledTimes(1);
+    expect(mockCreateFullpage).toHaveBeenCalledWith(
+      expect.objectContaining({
+        researchId: "test-research-id",
+      })
+    );
+  });
+
+  it("calls unmount on cleanup", () => {
+    const { unmount } = render(<Fullpage researchId="test-research-id" />);
+
+    expect(mockUnmount).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes config to createFullpage", () => {
+    const onReady = vi.fn();
+    const onSubmit = vi.fn();
+    const onClose = vi.fn();
+    const onNavigate = vi.fn();
+    const onError = vi.fn();
+
+    render(
+      <Fullpage
+        researchId="test-research-id"
+        params={{ source: "test" }}
+        theme="dark"
+        host="https://custom.example.com"
+        onReady={onReady}
+        onSubmit={onSubmit}
+        onClose={onClose}
+        onNavigate={onNavigate}
+        onError={onError}
+      />
+    );
+
+    expect(mockCreateFullpage).toHaveBeenCalledTimes(1);
+    const config = mockCreateFullpage.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("exposes handle via embedRef", () => {
+    const mockHandle: EmbedHandle = {
+      unmount: mockUnmount,
+      update: mockUpdate,
+      destroy: mockUnmount,
+      researchId: "test-research-id",
+      type: "fullpage",
+      iframe: null,
+      container: null,
+    };
+    mockCreateFullpage.mockReturnValueOnce(mockHandle);
+
+    const embedRef = createRef<EmbedHandle | null>();
+
+    render(<Fullpage researchId="test-research-id" embedRef={embedRef} />);
+
+    expect(embedRef.current).toBe(mockHandle);
+  });
+
+  it("clears embedRef on unmount", () => {
+    const embedRef = createRef<EmbedHandle | null>();
+
+    const { unmount } = render(
+      <Fullpage researchId="test-research-id" embedRef={embedRef} />
+    );
+
+    expect(embedRef.current).not.toBeNull();
+
+    unmount();
+
+    expect(embedRef.current).toBeNull();
+  });
+
+  it("re-creates fullpage when researchId changes", () => {
+    const { rerender } = render(<Fullpage researchId="research-1" />);
+
+    expect(mockCreateFullpage).toHaveBeenCalledTimes(1);
+
+    rerender(<Fullpage researchId="research-2" />);
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+    expect(mockCreateFullpage).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-creates fullpage when theme changes", () => {
+    const { rerender } = render(
+      <Fullpage researchId="test-research-id" theme="light" />
+    );
+
+    expect(mockCreateFullpage).toHaveBeenCalledTimes(1);
+
+    rerender(<Fullpage researchId="test-research-id" theme="dark" />);
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+    expect(mockCreateFullpage).toHaveBeenCalledTimes(2);
+  });
+
+  it("passes brand colors to createFullpage", () => {
+    render(
+      <Fullpage
+        researchId="test-research-id"
+        brand={{
+          light: { primary: "#ff0000", bg: "#ffffff" },
+          dark: { primary: "#0000ff", bg: "#000000" },
+        }}
+      />
+    );
+
+    const config = mockCreateFullpage.mock.calls[0]![0];
+    expect(config.brand).toEqual({
+      light: { primary: "#ff0000", bg: "#ffffff" },
+      dark: { primary: "#0000ff", bg: "#000000" },
+    });
+  });
+});

package/src/Fullpage.tsx

@@ -0,0 +1,83 @@
+import { useRef, useEffect, type RefObject } from "react";
+import {
+  createFullpage,
+  type EmbedConfig,
+  type EmbedHandle,
+} from "@perspective-ai/sdk";
+import { useStableCallback } from "./hooks/useStableCallback";
+
+export interface FullpageProps extends Omit<EmbedConfig, "type"> {
+  /** Ref to access the embed handle for programmatic control */
+  embedRef?: RefObject<EmbedHandle | null>;
+}
+
+/**
+ * Full viewport embed component.
+ * Takes over the entire screen with the interview.
+ */
+export function Fullpage({
+  researchId,
+  params,
+  brand,
+  theme,
+  host,
+  onReady,
+  onSubmit,
+  onNavigate,
+  onClose,
+  onError,
+  embedRef,
+}: FullpageProps) {
+  const handleRef = useRef<EmbedHandle | null>(null);
+
+  // Stable callbacks
+  const stableOnReady = useStableCallback(onReady);
+  const stableOnSubmit = useStableCallback(onSubmit);
+  const stableOnNavigate = useStableCallback(onNavigate);
+  const stableOnClose = useStableCallback(onClose);
+  const stableOnError = useStableCallback(onError);
+
+  useEffect(() => {
+    const handle = createFullpage({
+      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,
+  ]);
+
+  // This component doesn't render anything - the fullpage overlay is added to document.body
+  return null;
+}