@perspective-ai/sdk 1.0.0-alpha.2

package/src/styles.ts

@@ -0,0 +1,395 @@
+/**
+ * CSS styles injected by the embed script
+ * SSR-safe - DOM access is guarded
+ */
+
+import { hasDom } from "./config";
+
+let stylesInjected = false;
+
+const LIGHT_THEME = `
+  --perspective-overlay-bg: rgba(0, 0, 0, 0.5);
+  --perspective-modal-bg: #ffffff;
+  --perspective-modal-text: #151B23;
+  --perspective-close-bg: rgba(0, 0, 0, 0.1);
+  --perspective-close-text: #666666;
+  --perspective-close-hover-bg: rgba(0, 0, 0, 0.2);
+  --perspective-close-hover-text: #333333;
+  --perspective-border: hsl(240 6% 90%);
+`;
+
+const DARK_THEME = `
+  --perspective-overlay-bg: rgba(0, 0, 0, 0.7);
+  --perspective-modal-bg: #02040a;
+  --perspective-modal-text: #ffffff;
+  --perspective-close-bg: rgba(255, 255, 255, 0.1);
+  --perspective-close-text: #a0a0a0;
+  --perspective-close-hover-bg: rgba(255, 255, 255, 0.2);
+  --perspective-close-hover-text: #ffffff;
+  --perspective-border: hsl(217 33% 17%);
+`;
+
+export function injectStyles(): void {
+  if (!hasDom()) return;
+  if (stylesInjected) return;
+  stylesInjected = true;
+
+  const style = document.createElement("style");
+  style.id = "perspective-embed-styles";
+  style.textContent = `
+    /* Theme-aware color variables */
+    .perspective-embed-root, .perspective-light-theme {
+      ${LIGHT_THEME}
+      --perspective-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
+      --perspective-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+      --perspective-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
+      --perspective-shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
+      --perspective-radius: 1.2rem;
+      --perspective-radius-sm: calc(var(--perspective-radius) - 4px);
+    }
+
+    /* Dark theme */
+    .perspective-dark-theme {
+      ${DARK_THEME}
+    }
+
+    /* System dark mode support */
+    @media (prefers-color-scheme: dark) {
+      .perspective-embed-root:not(.perspective-light-theme) {
+        ${DARK_THEME}
+      }
+    }
+
+    /* Scrollbar styling */
+    .perspective-modal,
+    .perspective-slider,
+    .perspective-float-window,
+    .perspective-chat-window {
+      scrollbar-width: thin;
+      scrollbar-color: var(--perspective-border) transparent;
+    }
+
+    .perspective-modal::-webkit-scrollbar,
+    .perspective-slider::-webkit-scrollbar,
+    .perspective-float-window::-webkit-scrollbar,
+    .perspective-chat-window::-webkit-scrollbar {
+      width: 10px;
+      height: 10px;
+    }
+
+    .perspective-modal::-webkit-scrollbar-track,
+    .perspective-slider::-webkit-scrollbar-track,
+    .perspective-float-window::-webkit-scrollbar-track,
+    .perspective-chat-window::-webkit-scrollbar-track {
+      background: transparent;
+    }
+
+    .perspective-modal::-webkit-scrollbar-thumb,
+    .perspective-slider::-webkit-scrollbar-thumb,
+    .perspective-float-window::-webkit-scrollbar-thumb,
+    .perspective-chat-window::-webkit-scrollbar-thumb {
+      background-color: var(--perspective-border);
+      border-radius: 9999px;
+      border: 2px solid transparent;
+      background-clip: padding-box;
+    }
+
+    .perspective-modal::-webkit-scrollbar-thumb:hover,
+    .perspective-slider::-webkit-scrollbar-thumb:hover,
+    .perspective-float-window::-webkit-scrollbar-thumb:hover,
+    .perspective-chat-window::-webkit-scrollbar-thumb:hover {
+      background-color: color-mix(in srgb, var(--perspective-border) 80%, currentColor);
+    }
+
+    /* Overlay for popup/modal */
+    .perspective-overlay {
+      position: fixed;
+      inset: 0;
+      background: var(--perspective-overlay-bg);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 9999;
+      animation: perspective-fade-in 0.2s ease-out;
+    }
+
+    @keyframes perspective-fade-in {
+      from { opacity: 0; }
+      to { opacity: 1; }
+    }
+
+    @keyframes perspective-spin {
+      to { transform: rotate(360deg); }
+    }
+
+    /* Modal container */
+    .perspective-modal {
+      position: relative;
+      width: 90%;
+      max-width: 600px;
+      height: 80vh;
+      max-height: 700px;
+      background: var(--perspective-modal-bg);
+      color: var(--perspective-modal-text);
+      border-radius: var(--perspective-radius);
+      overflow: hidden;
+      box-shadow: var(--perspective-shadow-xl);
+      animation: perspective-slide-up 0.3s ease-out;
+    }
+
+    @keyframes perspective-slide-up {
+      from {
+        opacity: 0;
+        transform: translateY(20px) scale(0.95);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+      }
+    }
+
+    .perspective-modal iframe {
+      width: 100%;
+      height: 100%;
+      border: none;
+    }
+
+    /* Close button */
+    .perspective-close {
+      position: absolute;
+      top: 1rem;
+      right: 1.5rem;
+      width: 2rem;
+      height: 2rem;
+      border: none;
+      background: var(--perspective-close-bg);
+      color: var(--perspective-close-text);
+      border-radius: 50%;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font-size: 1rem;
+      z-index: 10;
+      transition: background-color 0.2s ease, color 0.2s ease;
+    }
+
+    .perspective-close:hover {
+      background: var(--perspective-close-hover-bg);
+      color: var(--perspective-close-hover-text);
+    }
+
+    .perspective-close:focus-visible {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+
+    .perspective-close svg {
+      width: 1rem;
+      height: 1rem;
+      stroke-width: 2;
+    }
+
+    /* Slider drawer */
+    .perspective-slider {
+      position: fixed;
+      top: 0;
+      right: 0;
+      width: 100%;
+      max-width: 450px;
+      height: 100%;
+      background: var(--perspective-modal-bg);
+      color: var(--perspective-modal-text);
+      box-shadow: var(--perspective-shadow-xl);
+      z-index: 9999;
+      animation: perspective-slide-in 0.3s ease-out;
+    }
+
+    @keyframes perspective-slide-in {
+      from { transform: translateX(100%); }
+      to { transform: translateX(0); }
+    }
+
+    .perspective-slider iframe {
+      width: 100%;
+      height: 100%;
+      border: none;
+    }
+
+    .perspective-slider .perspective-close {
+      top: 1rem;
+      right: 2rem;
+    }
+
+    /* Slider backdrop */
+    .perspective-slider-backdrop {
+      position: fixed;
+      inset: 0;
+      background: var(--perspective-overlay-bg);
+      z-index: 9998;
+      animation: perspective-fade-in 0.2s ease-out;
+    }
+
+    /* Float bubble (and legacy chat-bubble alias) */
+    .perspective-float-bubble,
+    .perspective-chat-bubble {
+      position: fixed;
+      bottom: 1.5rem;
+      right: 1.5rem;
+      width: 3.75rem;
+      height: 3.75rem;
+      border-radius: 50%;
+      background: var(--perspective-float-bg, var(--perspective-chat-bg, #7629C8));
+      color: white;
+      border: none;
+      cursor: pointer;
+      box-shadow: var(--perspective-float-shadow, var(--perspective-chat-shadow, 0 4px 12px rgba(118, 41, 200, 0.4)));
+      z-index: 9996;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      transition: transform 0.2s ease, box-shadow 0.2s ease;
+    }
+
+    .perspective-float-bubble:hover,
+    .perspective-chat-bubble:hover {
+      transform: scale(1.05);
+      box-shadow: var(--perspective-float-shadow-hover, var(--perspective-chat-shadow-hover, 0 6px 16px rgba(118, 41, 200, 0.5)));
+    }
+
+    .perspective-float-bubble:focus-visible,
+    .perspective-chat-bubble:focus-visible {
+      outline: 2px solid currentColor;
+      outline-offset: 2px;
+    }
+
+    .perspective-float-bubble svg,
+    .perspective-chat-bubble svg {
+      width: 1.75rem;
+      height: 1.75rem;
+      stroke-width: 2;
+    }
+
+    /* Float window (and legacy chat-window alias) */
+    .perspective-float-window,
+    .perspective-chat-window {
+      position: fixed;
+      bottom: 6.25rem;
+      right: 1.5rem;
+      width: 380px;
+      height: calc(100vh - 8.75rem);
+      max-height: 600px;
+      background: var(--perspective-modal-bg);
+      color: var(--perspective-modal-text);
+      border-radius: var(--perspective-radius);
+      overflow: hidden;
+      box-shadow: var(--perspective-shadow-xl);
+      z-index: 9997;
+      animation: perspective-float-open 0.3s ease-out;
+    }
+
+    @keyframes perspective-float-open {
+      from {
+        opacity: 0;
+        transform: translateY(20px) scale(0.9);
+      }
+      to {
+        opacity: 1;
+        transform: translateY(0) scale(1);
+      }
+    }
+
+    .perspective-float-window iframe,
+    .perspective-chat-window iframe {
+      width: 100%;
+      height: 100%;
+      border: none;
+    }
+
+    .perspective-float-window .perspective-close,
+    .perspective-chat-window .perspective-close {
+      top: 1rem;
+      right: 1.5rem;
+    }
+
+    /* Fullpage */
+    .perspective-fullpage {
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      background: var(--perspective-modal-bg);
+    }
+
+    .perspective-fullpage iframe {
+      width: 100%;
+      height: 100%;
+      border: none;
+    }
+
+    /* Responsive */
+    @media (max-width: 640px) {
+      .perspective-modal {
+        width: 100%;
+        height: 100%;
+        max-width: none;
+        max-height: none;
+        border-radius: 0;
+      }
+
+      .perspective-slider {
+        max-width: 100%;
+      }
+
+      .perspective-float-window,
+      .perspective-chat-window {
+        width: calc(100% - 2rem);
+        right: 1rem;
+        bottom: 5.625rem;
+        height: calc(100vh - 7.5rem);
+      }
+
+      .perspective-float-bubble,
+      .perspective-chat-bubble {
+        bottom: 1rem;
+        right: 1rem;
+      }
+    }
+
+    @media (max-width: 450px) {
+      .perspective-float-window,
+      .perspective-chat-window {
+        width: calc(100% - 1rem);
+        right: 0.5rem;
+        bottom: 5rem;
+        height: calc(100vh - 6.5rem);
+      }
+
+      .perspective-float-bubble,
+      .perspective-chat-bubble {
+        bottom: 0.75rem;
+        right: 0.75rem;
+        width: 3.5rem;
+        height: 3.5rem;
+      }
+
+      .perspective-float-bubble svg,
+      .perspective-chat-bubble svg {
+        width: 1.5rem;
+        height: 1.5rem;
+      }
+    }
+  `;
+
+  document.head.appendChild(style);
+}
+
+export const MIC_ICON = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M12 18.75a6 6 0 006-6v-1.5m-6 7.5a6 6 0 01-6-6v-1.5m6 7.5v3.75m-3.75 0h7.5M12 15.75a3 3 0 01-3-3V4.5a3 3 0 116 0v8.25a3 3 0 01-3 3z" />
+</svg>`;
+
+/** @deprecated Use MIC_ICON instead */
+export const CHAT_ICON = MIC_ICON;
+
+export const CLOSE_ICON = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+  <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" />
+</svg>`;

package/src/types.ts

@@ -0,0 +1,148 @@
+/**
+ * Type definitions for the Perspective Embed SDK
+ * This file is TYPE-ONLY - no runtime value imports or exports
+ * SSR-safe by design
+ */
+
+import type {
+  ThemeValue,
+  ParamKey,
+  BrandKey,
+  MessageType,
+  ErrorCode,
+} from "./constants";
+
+// Re-export types only
+export type { ThemeValue, ParamKey, BrandKey, MessageType, ErrorCode };
+
+export type EmbedType =
+  | "widget"
+  | "popup"
+  | "slider"
+  | "float"
+  | "fullpage"
+  | "chat";
+
+/** Brand colors that can be passed via embed code */
+export interface BrandColors {
+  /** Primary accent color (buttons, links, focus states) */
+  primary?: string;
+  /** Secondary accent color */
+  secondary?: string;
+  /** Background color of the embed */
+  bg?: string;
+  /** Primary text color */
+  text?: string;
+}
+
+export interface EmbedConfig {
+  researchId: string;
+  type?: EmbedType;
+  /** Custom button text for popup/slider triggers */
+  buttonText?: string;
+  /** Custom params to pass to the interview (for tracking/attribution) */
+  params?: Record<string, string>;
+  /** Brand colors to override Research settings */
+  brand?: {
+    light?: BrandColors;
+    dark?: BrandColors;
+  };
+  /** Force theme mode: 'dark', 'light', or 'system' (default) */
+  theme?: ThemeValue;
+  /** Override the default host (defaults to https://getperspective.ai) */
+  host?: string;
+  /** Callback when embed is ready */
+  onReady?: () => void;
+  /** Callback when interview is submitted/completed */
+  onSubmit?: (data: { researchId: string }) => void;
+  /** Callback when embed wants to navigate. If provided, parent handles navigation; otherwise SDK navigates via window.location.href */
+  onNavigate?: (url: string) => void;
+  /** Callback when embed is closed */
+  onClose?: () => void;
+  /** Callback on any error */
+  onError?: (error: EmbedError) => void;
+}
+
+/** Embed error with code for programmatic handling */
+export interface EmbedError extends Error {
+  code?: ErrorCode;
+}
+
+export interface EmbedInstance {
+  researchId: string;
+  type: EmbedType;
+  iframe: HTMLIFrameElement;
+  container: HTMLElement;
+  destroy: () => void;
+}
+
+/** Handle returned by embed creation functions */
+export interface EmbedHandle {
+  unmount: () => void;
+  update: (
+    options: Partial<
+      Pick<
+        EmbedConfig,
+        "onReady" | "onSubmit" | "onNavigate" | "onClose" | "onError"
+      >
+    >
+  ) => void;
+  /** @deprecated Use unmount() instead */
+  destroy: () => void;
+  /** @deprecated For legacy compatibility */
+  readonly researchId: string;
+  /** @deprecated For legacy compatibility */
+  readonly type: EmbedType;
+  /** @deprecated For legacy compatibility - may be null on server */
+  readonly iframe: HTMLIFrameElement | null;
+  /** @deprecated For legacy compatibility - may be null on server */
+  readonly container: HTMLElement | null;
+}
+
+/** Handle for float bubble with open/close control (persistent UI element) */
+export interface FloatHandle extends Omit<EmbedHandle, "type"> {
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  readonly isOpen: boolean;
+  readonly type: "float";
+}
+
+/** @deprecated Use FloatHandle for float bubble, EmbedHandle for popup/slider */
+export type ModalHandle = FloatHandle;
+
+/** Messages sent from SDK to iframe */
+export interface InitMessage {
+  type: "perspective:init";
+  version: string;
+  features: number;
+  researchId: string;
+}
+
+/** Messages sent from iframe to SDK */
+export type EmbedMessage =
+  | { type: "perspective:ready"; researchId: string }
+  | { type: "perspective:resize"; researchId: string; height: number }
+  | { type: "perspective:submit"; researchId: string; data?: unknown }
+  | { type: "perspective:close"; researchId: string }
+  | {
+      type: "perspective:error";
+      researchId: string;
+      error: string;
+      code?: string;
+    }
+  | { type: "perspective:redirect"; researchId: string; url: string };
+
+/** Theme configuration from API */
+export interface ThemeConfig {
+  primaryColor: string;
+  textColor: string;
+  darkPrimaryColor: string;
+  darkTextColor: string;
+}
+
+/** SDK global configuration */
+export interface SDKConfig {
+  /** Override the default host */
+  host?: string;
+}

package/src/utils.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import {
+  cn,
+  getThemeClass,
+  resolveIsDark,
+  resolveTheme,
+  normalizeHex,
+  hexToRgba,
+} from "./utils";
+import * as config from "./config";
+
+describe("cn", () => {
+  it("joins class names with spaces", () => {
+    expect(cn("foo", "bar", "baz")).toBe("foo bar baz");
+  });
+
+  it("filters out falsy values", () => {
+    expect(cn("foo", false, "bar", null, undefined, "baz")).toBe("foo bar baz");
+  });
+
+  it("handles empty strings", () => {
+    expect(cn("foo", "", "bar")).toBe("foo bar");
+  });
+
+  it("flattens space-separated classes", () => {
+    expect(cn("foo bar", "baz qux")).toBe("foo bar baz qux");
+  });
+
+  it("returns empty string for no valid classes", () => {
+    expect(cn(false, null, undefined)).toBe("");
+  });
+});
+
+describe("getThemeClass", () => {
+  it("returns theme class for light", () => {
+    expect(getThemeClass("light")).toBe("perspective-light-theme");
+  });
+
+  it("returns theme class for dark", () => {
+    expect(getThemeClass("dark")).toBe("perspective-dark-theme");
+  });
+
+  it("returns undefined for system theme", () => {
+    expect(getThemeClass("system")).toBeUndefined();
+  });
+
+  it("returns undefined for undefined", () => {
+    expect(getThemeClass(undefined)).toBeUndefined();
+  });
+});
+
+describe("resolveIsDark", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns true for explicit dark theme", () => {
+    expect(resolveIsDark("dark")).toBe(true);
+  });
+
+  it("returns false for explicit light theme", () => {
+    expect(resolveIsDark("light")).toBe(false);
+  });
+
+  it("returns false when no DOM available", () => {
+    vi.spyOn(config, "hasDom").mockReturnValue(false);
+    expect(resolveIsDark("system")).toBe(false);
+    expect(resolveIsDark(undefined)).toBe(false);
+  });
+
+  it("uses system preference when theme is system and DOM available", () => {
+    vi.spyOn(config, "hasDom").mockReturnValue(true);
+
+    // Mock dark mode preference
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn().mockImplementation((query: string) => ({
+        matches: query === "(prefers-color-scheme: dark)",
+        media: query,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+      })),
+    });
+
+    expect(resolveIsDark("system")).toBe(true);
+    expect(resolveIsDark(undefined)).toBe(true);
+  });
+});
+
+describe("resolveTheme", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns 'dark' for dark theme", () => {
+    expect(resolveTheme("dark")).toBe("dark");
+  });
+
+  it("returns 'light' for light theme", () => {
+    expect(resolveTheme("light")).toBe("light");
+  });
+
+  it("returns based on system when theme is system", () => {
+    vi.spyOn(config, "hasDom").mockReturnValue(false);
+    expect(resolveTheme("system")).toBe("light");
+  });
+});
+
+describe("normalizeHex", () => {
+  it("passes through valid 6-char hex with #", () => {
+    expect(normalizeHex("#ff0000")).toBe("#ff0000");
+    expect(normalizeHex("#AABBCC")).toBe("#AABBCC");
+  });
+
+  it("adds # prefix if missing", () => {
+    expect(normalizeHex("ff0000")).toBe("#ff0000");
+    expect(normalizeHex("abc")).toBe("#abc");
+  });
+
+  it("handles 3-char hex", () => {
+    expect(normalizeHex("#abc")).toBe("#abc");
+    expect(normalizeHex("ABC")).toBe("#ABC");
+  });
+
+  it("handles 8-char hex with alpha", () => {
+    expect(normalizeHex("#ff000080")).toBe("#ff000080");
+  });
+
+  it("returns undefined for empty string", () => {
+    expect(normalizeHex("")).toBeUndefined();
+    expect(normalizeHex("   ")).toBeUndefined();
+  });
+
+  it("extracts valid hex from invalid strings", () => {
+    // #gg0000 -> extracts "0000" -> returns 3-char "#000"
+    expect(normalizeHex("#gg0000")).toBe("#000");
+    // #ff00gg -> extracts "ff00" -> only 4 chars, returns 3-char "#ff0"
+    expect(normalizeHex("#ff00gg")).toBe("#ff0");
+  });
+
+  it("returns undefined for completely invalid input", () => {
+    expect(normalizeHex("notacolor")).toBeUndefined();
+    expect(normalizeHex("#gg")).toBeUndefined();
+  });
+});
+
+describe("hexToRgba", () => {
+  it("converts hex to rgba", () => {
+    expect(hexToRgba("#ff0000", 0.5)).toBe("rgba(255, 0, 0, 0.5)");
+    expect(hexToRgba("#00ff00", 1)).toBe("rgba(0, 255, 0, 1)");
+    expect(hexToRgba("#0000ff", 0)).toBe("rgba(0, 0, 255, 0)");
+  });
+
+  it("handles hex without #", () => {
+    expect(hexToRgba("ff0000", 0.5)).toBe("rgba(255, 0, 0, 0.5)");
+  });
+
+  it("returns default color for invalid hex", () => {
+    expect(hexToRgba("invalid", 0.5)).toBe("rgba(118, 41, 200, 0.5)");
+    expect(hexToRgba("#abc", 0.5)).toBe("rgba(118, 41, 200, 0.5)"); // 3-char hex not supported
+  });
+});