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

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();
+  });
+});

package/src/hooks/useSlider.ts

@@ -0,0 +1,181 @@
+import { useCallback, useState, useEffect, useRef } from "react";
+import {
+  openSlider,
+  type EmbedConfig,
+  type EmbedHandle,
+} from "@perspective-ai/sdk";
+import { useStableCallback } from "./useStableCallback";
+
+/** Options for useSlider hook */
+export interface UseSliderOptions extends Omit<EmbedConfig, "type"> {
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback when open state changes */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/** Return type for useSlider hook */
+export interface UseSliderReturn {
+  /** Open the slider */
+  open: () => void;
+  /** Close the slider */
+  close: () => void;
+  /** Toggle the slider */
+  toggle: () => void;
+  /** Whether the slider is currently open */
+  isOpen: boolean;
+  /** The underlying SDK handle (null when closed) */
+  handle: EmbedHandle | null;
+}
+
+/**
+ * Headless hook for programmatic slider control.
+ * Use this when you need custom trigger elements or programmatic control.
+ *
+ * @example
+ * ```tsx
+ * const { open, isOpen } = useSlider({ researchId: "abc" });
+ * <MyCustomButton onClick={open}>Give Feedback</MyCustomButton>
+ * ```
+ */
+export function useSlider(options: UseSliderOptions): UseSliderReturn {
+  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 createSlider = useCallback(() => {
+    if (handleRef.current) return handleRef.current;
+
+    const newHandle = openSlider({
+      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 destroySlider = useCallback(() => {
+    if (handleRef.current) {
+      handleRef.current.destroy();
+      handleRef.current = null;
+      setHandle(null);
+    }
+  }, []);
+
+  const openFn = useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(true);
+    } else {
+      createSlider();
+      setInternalOpen(true);
+    }
+  }, [isControlled, onOpenChange, createSlider]);
+
+  const closeFn = useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(false);
+    } else {
+      destroySlider();
+      setInternalOpen(false);
+    }
+  }, [isControlled, onOpenChange, destroySlider]);
+
+  const toggleFn = useCallback(() => {
+    if (isOpen) {
+      closeFn();
+    } else {
+      openFn();
+    }
+  }, [isOpen, openFn, closeFn]);
+
+  useEffect(() => {
+    if (!isControlled) return;
+
+    if (controlledOpen && !handleRef.current) {
+      createSlider();
+    } else if (!controlledOpen && handleRef.current) {
+      destroySlider();
+    }
+  }, [controlledOpen, isControlled, createSlider, destroySlider]);
+
+  useEffect(() => {
+    return () => {
+      if (handleRef.current) {
+        handleRef.current.destroy();
+        handleRef.current = null;
+      }
+    };
+  }, []);
+
+  return {
+    open: openFn,
+    close: closeFn,
+    toggle: toggleFn,
+    isOpen,
+    handle,
+  };
+}

package/src/hooks/useStableCallback.test.ts

@@ -0,0 +1,97 @@
+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("returns undefined when callback is undefined", () => {
+    const { result } = renderHook(() => useStableCallback(undefined));
+    expect(result.current).toBeUndefined();
+  });
+
+  it("transitions between undefined and defined", () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(({ cb }) => useStableCallback(cb), {
+      initialProps: { cb: undefined as (() => void) | undefined },
+    });
+
+    expect(result.current).toBeUndefined();
+
+    rerender({ cb: callback });
+    expect(result.current).toBeDefined();
+    const stableRef = result.current;
+
+    // Remains stable across re-renders with different callback instances
+    rerender({ cb: vi.fn() });
+    expect(result.current).toBe(stableRef);
+
+    rerender({ cb: undefined });
+    expect(result.current).toBeUndefined();
+  });
+
+  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,24 @@
+import { useRef, useCallback, useLayoutEffect, useEffect } from "react";
+
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+export function useStableCallback<
+  T extends ((...args: any[]) => any) | undefined,
+>(callback: T): T {
+  const callbackRef = useRef(callback);
+
+  useIsomorphicLayoutEffect(() => {
+    callbackRef.current = callback;
+  });
+
+  // Always create the stable wrapper (hooks can't be conditional),
+  // but return undefined when no callback is provided to preserve
+  // truthiness semantics for consumers that branch on it.
+  const stable = useCallback(
+    ((...args: any[]) => callbackRef.current?.(...args)) as NonNullable<T>,
+    []
+  );
+
+  return callback ? stable : callback;
+}

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

package/src/index.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * Perspective Embed SDK - React
+ *
+ * Hooks (for overlays - popup, slider, float bubble):
+ *   import { usePopup, useSlider, useFloatBubble } from '@perspective-ai/sdk-react';
+ *
+ *   const { open } = usePopup({ researchId: "xxx" });
+ *   <button onClick={open}>Take Survey</button>
+ *
+ * Components (for embeds - widget, fullpage):
+ *   import { Widget, Fullpage, FloatBubble } from '@perspective-ai/sdk-react';
+ *
+ *   <Widget researchId="xxx" />
+ *   <Fullpage researchId="xxx" />
+ *   <FloatBubble researchId="xxx" />
+ */
+
+export {
+  usePopup,
+  type UsePopupOptions,
+  type UsePopupReturn,
+} from "./hooks/usePopup";
+export {
+  useSlider,
+  type UseSliderOptions,
+  type UseSliderReturn,
+} from "./hooks/useSlider";
+export {
+  useFloatBubble,
+  type UseFloatBubbleOptions,
+  type UseFloatBubbleReturn,
+} from "./hooks/useFloatBubble";
+export {
+  useAutoOpen,
+  type UseAutoOpenOptions,
+  type UseAutoOpenReturn,
+} from "./hooks/useAutoOpen";
+export { useThemeSync } from "./hooks/useThemeSync";
+export { useStableCallback } from "./hooks/useStableCallback";
+
+export { Widget, type WidgetProps } from "./Widget";
+export { Fullpage, type FullpageProps } from "./Fullpage";
+export { FloatBubble, type FloatBubbleProps } from "./FloatBubble";
+
+export type {
+  EmbedConfig,
+  EmbedHandle,
+  FloatHandle,
+  BrandColors,
+  ThemeValue,
+  EmbedError,
+  TriggerConfig,
+  ShowOnce,
+  AutoOpenConfig,
+} from "@perspective-ai/sdk";