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

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/index.ts

@@ -1,47 +1,44 @@
 "use client";
 
 /**
- * Perspective Embed SDK - React Components
+ * Perspective Embed SDK - React
  *
- * Usage:
- *   import { Widget, PopupButton, SliderButton, FloatBubble } from '@perspective-ai/sdk-react';
+ * Hooks (for overlays - popup, slider, float bubble):
+ *   import { usePopup, useSlider, useFloatBubble } from '@perspective-ai/sdk-react';
  *
- *   // Inline widget
- *   <Widget researchId="xxx" onReady={() => {}} />
+ *   const { open } = usePopup({ researchId: "xxx" });
+ *   <button onClick={open}>Take Survey</button>
  *
- *   // Popup button
- *   <PopupButton researchId="xxx">Take the interview</PopupButton>
+ * Components (for embeds - widget, fullpage):
+ *   import { Widget, Fullpage, FloatBubble } from '@perspective-ai/sdk-react';
  *
- *   // Slider button
- *   <SliderButton researchId="xxx">Open Interview</SliderButton>
- *
- *   // Floating bubble
- *   <FloatBubble researchId="xxx" />
- *
- *   // Full page
+ *   <Widget researchId="xxx" />
  *   <Fullpage researchId="xxx" />
+ *   <FloatBubble researchId="xxx" />
  */
 
-// Components
-export { Widget, type WidgetProps } from "./Widget";
 export {
-  PopupButton,
-  type PopupButtonProps,
-  type PopupButtonHandle,
-} from "./PopupButton";
+  usePopup,
+  type UsePopupOptions,
+  type UsePopupReturn,
+} from "./hooks/usePopup";
 export {
-  SliderButton,
-  type SliderButtonProps,
-  type SliderButtonHandle,
-} from "./SliderButton";
-export { FloatBubble, type FloatBubbleProps } from "./FloatBubble";
-export { Fullpage, type FullpageProps } from "./Fullpage";
-
-// Hooks
+  useSlider,
+  type UseSliderOptions,
+  type UseSliderReturn,
+} from "./hooks/useSlider";
+export {
+  useFloatBubble,
+  type UseFloatBubbleOptions,
+  type UseFloatBubbleReturn,
+} from "./hooks/useFloatBubble";
 export { useThemeSync } from "./hooks/useThemeSync";
 export { useStableCallback } from "./hooks/useStableCallback";
 
-// Re-export types from core package for convenience
+export { Widget, type WidgetProps } from "./Widget";
+export { Fullpage, type FullpageProps } from "./Fullpage";
+export { FloatBubble, type FloatBubbleProps } from "./FloatBubble";
+
 export type {
   EmbedConfig,
   EmbedHandle,

package/src/PopupButton.test.tsx

@@ -1,273 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { render, screen, cleanup, fireEvent } from "@testing-library/react";
-import { createRef } from "react";
-import { PopupButton, type PopupButtonHandle } from "./PopupButton";
-
-// Mock the core embed package
-const mockDestroy = vi.fn();
-const mockUnmount = vi.fn();
-
-vi.mock("@perspective-ai/sdk", () => ({
-  openPopup: vi.fn(() => ({
-    unmount: mockUnmount,
-    update: vi.fn(),
-    destroy: mockDestroy,
-    researchId: "test-research-id",
-    type: "popup",
-    iframe: null,
-    container: null,
-  })),
-}));
-
-import { openPopup } from "@perspective-ai/sdk";
-const mockOpenPopup = vi.mocked(openPopup);
-
-describe("PopupButton", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-  });
-
-  afterEach(() => {
-    cleanup();
-  });
-
-  it("renders a button with children", () => {
-    render(
-      <PopupButton researchId="test-research-id">Open Interview</PopupButton>
-    );
-
-    const button = screen.getByRole("button");
-    expect(button).toBeDefined();
-    expect(button.textContent).toBe("Open Interview");
-  });
-
-  it("has correct test id", () => {
-    render(<PopupButton researchId="test-research-id">Open</PopupButton>);
-
-    const button = screen.getByTestId("perspective-popup-button");
-    expect(button).toBeDefined();
-  });
-
-  it("opens popup on click", () => {
-    render(<PopupButton researchId="test-research-id">Open</PopupButton>);
-
-    const button = screen.getByRole("button");
-    fireEvent.click(button);
-
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-    expect(mockOpenPopup).toHaveBeenCalledWith(
-      expect.objectContaining({
-        researchId: "test-research-id",
-      })
-    );
-  });
-
-  it("closes popup on second click", () => {
-    render(<PopupButton researchId="test-research-id">Open</PopupButton>);
-
-    const button = screen.getByRole("button");
-
-    // First click opens
-    fireEvent.click(button);
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-
-    // Second click closes
-    fireEvent.click(button);
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
-  });
-
-  it("passes config to openPopup", () => {
-    const onReady = vi.fn();
-    const onSubmit = vi.fn();
-
-    render(
-      <PopupButton
-        researchId="test-research-id"
-        params={{ source: "test" }}
-        theme="dark"
-        host="https://custom.example.com"
-        onReady={onReady}
-        onSubmit={onSubmit}
-      >
-        Open
-      </PopupButton>
-    );
-
-    fireEvent.click(screen.getByRole("button"));
-
-    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("calls custom onClick handler", () => {
-    const onClick = vi.fn();
-
-    render(
-      <PopupButton researchId="test-research-id" onClick={onClick}>
-        Open
-      </PopupButton>
-    );
-
-    fireEvent.click(screen.getByRole("button"));
-
-    expect(onClick).toHaveBeenCalledTimes(1);
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not open popup if onClick prevents default", () => {
-    const onClick = vi.fn((e: React.MouseEvent) => e.preventDefault());
-
-    render(
-      <PopupButton researchId="test-research-id" onClick={onClick}>
-        Open
-      </PopupButton>
-    );
-
-    fireEvent.click(screen.getByRole("button"));
-
-    expect(onClick).toHaveBeenCalledTimes(1);
-    expect(mockOpenPopup).not.toHaveBeenCalled();
-  });
-
-  it("supports controlled mode via open prop", () => {
-    const onOpenChange = vi.fn();
-
-    const { rerender } = render(
-      <PopupButton
-        researchId="test-research-id"
-        open={false}
-        onOpenChange={onOpenChange}
-      >
-        Open
-      </PopupButton>
-    );
-
-    // Should not auto-open
-    expect(mockOpenPopup).not.toHaveBeenCalled();
-
-    // When open becomes true, popup should open
-    rerender(
-      <PopupButton
-        researchId="test-research-id"
-        open={true}
-        onOpenChange={onOpenChange}
-      >
-        Open
-      </PopupButton>
-    );
-
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-
-    // When open becomes false, popup should close
-    rerender(
-      <PopupButton
-        researchId="test-research-id"
-        open={false}
-        onOpenChange={onOpenChange}
-      >
-        Open
-      </PopupButton>
-    );
-
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
-  });
-
-  it("exposes handle via embedRef", () => {
-    const embedRef = createRef<PopupButtonHandle | null>();
-
-    render(
-      <PopupButton researchId="test-research-id" embedRef={embedRef}>
-        Open
-      </PopupButton>
-    );
-
-    expect(embedRef.current).not.toBeNull();
-    expect(typeof embedRef.current?.open).toBe("function");
-    expect(typeof embedRef.current?.close).toBe("function");
-    expect(typeof embedRef.current?.toggle).toBe("function");
-    expect(embedRef.current?.researchId).toBe("test-research-id");
-  });
-
-  it("embedRef.open() opens popup", () => {
-    const embedRef = createRef<PopupButtonHandle | null>();
-
-    render(
-      <PopupButton researchId="test-research-id" embedRef={embedRef}>
-        Open
-      </PopupButton>
-    );
-
-    embedRef.current?.open();
-
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-  });
-
-  it("embedRef.close() closes popup", () => {
-    const embedRef = createRef<PopupButtonHandle | null>();
-
-    render(
-      <PopupButton researchId="test-research-id" embedRef={embedRef}>
-        Open
-      </PopupButton>
-    );
-
-    // First open
-    embedRef.current?.open();
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-
-    // Then close
-    embedRef.current?.close();
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
-  });
-
-  it("embedRef.toggle() toggles popup state", async () => {
-    const embedRef = createRef<PopupButtonHandle | null>();
-    const onOpenChange = vi.fn();
-
-    render(
-      <PopupButton
-        researchId="test-research-id"
-        embedRef={embedRef}
-        onOpenChange={onOpenChange}
-      >
-        Open
-      </PopupButton>
-    );
-
-    // Toggle on
-    embedRef.current?.toggle();
-    expect(mockOpenPopup).toHaveBeenCalledTimes(1);
-
-    // Toggle off
-    embedRef.current?.toggle();
-    expect(mockDestroy).toHaveBeenCalledTimes(1);
-  });
-
-  it("passes button props", () => {
-    render(
-      <PopupButton
-        researchId="test-research-id"
-        className="custom-button"
-        disabled
-        aria-label="Open interview popup"
-      >
-        Open
-      </PopupButton>
-    );
-
-    const button = screen.getByRole("button");
-    expect(button.classList.contains("custom-button")).toBe(true);
-    expect(button.hasAttribute("disabled")).toBe(true);
-    expect(button.getAttribute("aria-label")).toBe("Open interview popup");
-  });
-
-  it("has type button", () => {
-    render(<PopupButton researchId="test-research-id">Open</PopupButton>);
-
-    const button = screen.getByRole("button");
-    expect(button.getAttribute("type")).toBe("button");
-  });
-});