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

package/src/hooks/useFloatBubble.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, cleanup, act } from "@testing-library/react";
+import { useFloatBubble } from "./useFloatBubble";
+
+const mockOpen = vi.fn();
+const mockClose = vi.fn();
+const mockUnmount = vi.fn();
+const mockToggle = vi.fn();
+const mockDestroy = vi.fn();
+const mockUpdate = vi.fn();
+
+const stableMockHandle = {
+  open: mockOpen,
+  close: mockClose,
+  unmount: mockUnmount,
+  toggle: mockToggle,
+  destroy: mockDestroy,
+  update: mockUpdate,
+  isOpen: false,
+  researchId: "test-research-id",
+  type: "float" as const,
+  iframe: null,
+  container: null,
+};
+
+vi.mock("@perspective-ai/sdk", () => ({
+  createFloatBubble: vi.fn(() => stableMockHandle),
+}));
+
+import { createFloatBubble } from "@perspective-ai/sdk";
+const mockCreateFloatBubble = vi.mocked(createFloatBubble);
+
+describe("useFloatBubble", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    stableMockHandle.isOpen = false;
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  it("creates bubble on mount and cleans up on unmount", () => {
+    const { unmount } = renderHook(() =>
+      useFloatBubble({ researchId: "test-research-id" })
+    );
+
+    expect(mockCreateFloatBubble).toHaveBeenCalledTimes(1);
+    expect(mockCreateFloatBubble).toHaveBeenCalledWith(
+      expect.objectContaining({ researchId: "test-research-id" })
+    );
+
+    unmount();
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns expected interface", () => {
+    const { result, unmount } = renderHook(() =>
+      useFloatBubble({ 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.unmount).toBeInstanceOf(Function);
+    expect(result.current.handle).not.toBeNull();
+    expect(typeof result.current.isOpen).toBe("boolean");
+
+    unmount();
+  });
+
+  it("manual unmount clears handle and prevents double cleanup", () => {
+    const { result, unmount } = renderHook(() =>
+      useFloatBubble({ researchId: "test-research-id" })
+    );
+
+    expect(result.current.handle).not.toBeNull();
+
+    act(() => {
+      result.current.unmount();
+    });
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+    expect(result.current.handle).toBeNull();
+
+    unmount();
+
+    expect(mockUnmount).toHaveBeenCalledTimes(1);
+  });
+});

package/src/hooks/useFloatBubble.ts

@@ -0,0 +1,180 @@
+import { useCallback, useState, useEffect, useRef } from "react";
+import {
+  createFloatBubble,
+  type EmbedConfig,
+  type FloatHandle,
+} from "@perspective-ai/sdk";
+import { useStableCallback } from "./useStableCallback";
+
+/** Options for useFloatBubble hook */
+export interface UseFloatBubbleOptions extends Omit<EmbedConfig, "type"> {
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/** Return type for useFloatBubble hook */
+export interface UseFloatBubbleReturn {
+  /** Open the float bubble window */
+  open: () => void;
+  /** Close the float bubble window */
+  close: () => void;
+  /** Toggle the float bubble window */
+  toggle: () => void;
+  /** Unmount the float bubble entirely */
+  unmount: () => void;
+  /** Whether the float bubble window is currently open */
+  isOpen: boolean;
+  /** The underlying SDK handle (null until mounted) */
+  handle: FloatHandle | null;
+}
+
+/**
+ * Headless hook for float bubble lifecycle management.
+ * Creates a floating bubble button that expands into a chat window.
+ * The bubble mounts on component mount and unmounts on component unmount.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage - bubble mounts on component mount
+ * useFloatBubble({ researchId: "abc" });
+ *
+ * // With programmatic control
+ * const { open, close, isOpen } = useFloatBubble({ researchId: "abc" });
+ * <button onClick={open}>Open Chat</button>
+ * ```
+ */
+export function useFloatBubble(
+  options: UseFloatBubbleOptions
+): UseFloatBubbleReturn {
+  const {
+    researchId,
+    params,
+    brand,
+    theme,
+    host,
+    onReady,
+    onSubmit,
+    onNavigate,
+    onClose,
+    onError,
+    open: controlledOpen,
+    onOpenChange,
+  } = options;
+
+  const [handle, setHandle] = useState<FloatHandle | null>(null);
+  const [internalOpen, setInternalOpen] = useState(false);
+  const handleRef = useRef<FloatHandle | null>(null);
+
+  const isControlled = controlledOpen !== undefined;
+
+  const stableOnReady = useStableCallback(onReady);
+  const stableOnSubmit = useStableCallback(onSubmit);
+  const stableOnNavigate = useStableCallback(onNavigate);
+  const stableOnError = useStableCallback(onError);
+
+  const handleClose = useCallback(() => {
+    setInternalOpen(false);
+    if (isControlled) {
+      onOpenChange?.(false);
+    }
+    onClose?.();
+  }, [isControlled, onOpenChange, onClose]);
+
+  const stableOnClose = useStableCallback(handleClose);
+
+  useEffect(() => {
+    const newHandle = createFloatBubble({
+      researchId,
+      params,
+      brand,
+      theme,
+      host,
+      onReady: stableOnReady,
+      onSubmit: stableOnSubmit,
+      onNavigate: stableOnNavigate,
+      onClose: stableOnClose,
+      onError: stableOnError,
+    });
+
+    handleRef.current = newHandle;
+    setHandle(newHandle);
+
+    return () => {
+      if (handleRef.current === newHandle) {
+        newHandle.unmount();
+        handleRef.current = null;
+        setHandle(null);
+      }
+    };
+  }, [
+    researchId,
+    params,
+    brand,
+    theme,
+    host,
+    stableOnReady,
+    stableOnSubmit,
+    stableOnNavigate,
+    stableOnClose,
+    stableOnError,
+  ]);
+
+  useEffect(() => {
+    if (!isControlled || !handle) return;
+
+    if (controlledOpen && !handle.isOpen) {
+      handle.open();
+    } else if (!controlledOpen && handle.isOpen) {
+      handle.close();
+    }
+  }, [controlledOpen, isControlled, handle]);
+
+  const openFn = useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(true);
+    } else {
+      handleRef.current?.open();
+      setInternalOpen(true);
+    }
+  }, [isControlled, onOpenChange]);
+
+  const closeFn = useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(false);
+    } else {
+      handleRef.current?.close();
+      setInternalOpen(false);
+    }
+  }, [isControlled, onOpenChange]);
+
+  const toggleFn = useCallback(() => {
+    const currentlyOpen = handleRef.current?.isOpen ?? internalOpen;
+    if (currentlyOpen) {
+      closeFn();
+    } else {
+      openFn();
+    }
+  }, [internalOpen, openFn, closeFn]);
+
+  const unmountFn = useCallback(() => {
+    handleRef.current?.unmount();
+    handleRef.current = null;
+    setHandle(null);
+    setInternalOpen(false);
+  }, []);
+
+  const isOpen = isControlled
+    ? controlledOpen
+    : (handle?.isOpen ?? internalOpen);
+
+  return {
+    open: openFn,
+    close: closeFn,
+    toggle: toggleFn,
+    unmount: unmountFn,
+    isOpen,
+    handle,
+  };
+}

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,
+  };
+}