@cognior/iap-sdk 0.1.0

package/src/experiences/hotspots.ts

@@ -0,0 +1,566 @@
+// src/experiences/hotspots.ts
+// Interactive hotspots experience renderer
+
+import { sanitizeHtml } from "../utils/sanitize";
+import { register } from "./registry";
+import { resolveSelector } from "../utils/selectors";
+import { waitForElement } from "../utils/triggerNormalizer";
+import type { HotspotsPayload, HotspotItem, CornerPlacement } from "./types";
+
+type HotspotsFlow = { id: string; type: "hotspots"; payload: HotspotsPayload };
+
+const hotspotsCssText = `
+:root {
+  --dap-z-hotspots: 2147483630;
+  --dap-hotspot-primary: #3b82f6;
+  --dap-hotspot-bg: #ffffff;
+  --dap-hotspot-border: #e2e8f0;
+  --dap-hotspot-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
+  --dap-hotspot-text: #1e293b;
+  --dap-hotspot-text-muted: #64748b;
+}
+
+.dap-hotspots-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(15, 23, 42, 0.4);
+  z-index: var(--dap-z-hotspots);
+  pointer-events: none;
+  opacity: 0;
+  animation: hotspotsOverlayFadeIn 0.3s ease-out forwards;
+}
+
+@keyframes hotspotsOverlayFadeIn {
+  to { opacity: 1; }
+}
+
+.dap-hotspot-marker {
+  position: absolute;
+  width: 24px;
+  height: 24px;
+  background: var(--dap-hotspot-primary);
+  border: 3px solid white;
+  border-radius: 50%;
+  cursor: pointer;
+  z-index: calc(var(--dap-z-hotspots) + 1);
+  animation: hotspotPulse 2s infinite;
+  transition: all 0.2s ease;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
+}
+
+.dap-hotspot-marker:hover {
+  transform: scale(1.1);
+  animation-play-state: paused;
+}
+
+.dap-hotspot-marker.completed {
+  background: #10b981;
+  animation: none;
+}
+
+.dap-hotspot-marker.required {
+  background: #f59e0b;
+  animation-duration: 1.5s;
+}
+
+@keyframes hotspotPulse {
+  0% {
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2), 0 0 0 0 rgba(59, 130, 246, 0.7);
+  }
+  70% {
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2), 0 0 0 10px rgba(59, 130, 246, 0);
+  }
+  100% {
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2), 0 0 0 0 rgba(59, 130, 246, 0);
+  }
+}
+
+.dap-hotspot-tooltip {
+  position: absolute;
+  background: var(--dap-hotspot-bg);
+  border: 1px solid var(--dap-hotspot-border);
+  border-radius: 8px;
+  box-shadow: var(--dap-hotspot-shadow);
+  padding: 16px;
+  max-width: 320px;
+  z-index: calc(var(--dap-z-hotspots) + 2);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  opacity: 0;
+  transform: scale(0.9);
+  animation: hotspotTooltipIn 0.2s ease-out forwards;
+  pointer-events: auto;
+}
+
+@keyframes hotspotTooltipIn {
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.dap-hotspot-tooltip::before {
+  content: '';
+  position: absolute;
+  width: 0;
+  height: 0;
+  border: 8px solid transparent;
+}
+
+.dap-hotspot-tooltip.top::before {
+  bottom: -16px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-top-color: var(--dap-hotspot-bg);
+}
+
+.dap-hotspot-tooltip.bottom::before {
+  top: -16px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-bottom-color: var(--dap-hotspot-bg);
+}
+
+.dap-hotspot-tooltip.left::before {
+  right: -16px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-left-color: var(--dap-hotspot-bg);
+}
+
+.dap-hotspot-tooltip.right::before {
+  left: -16px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-right-color: var(--dap-hotspot-bg);
+}
+
+.dap-hotspot-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: var(--dap-hotspot-text);
+  margin: 0 0 8px 0;
+}
+
+.dap-hotspot-description {
+  font-size: 14px;
+  color: var(--dap-hotspot-text-muted);
+  line-height: 1.4;
+  margin: 0 0 12px 0;
+}
+
+.dap-hotspot-actions {
+  display: flex;
+  gap: 8px;
+  justify-content: flex-end;
+}
+
+.dap-hotspot-btn {
+  padding: 6px 12px;
+  border: 1px solid var(--dap-hotspot-primary);
+  border-radius: 4px;
+  background: transparent;
+  color: var(--dap-hotspot-primary);
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.dap-hotspot-btn:hover {
+  background: var(--dap-hotspot-primary);
+  color: white;
+}
+
+.dap-hotspot-btn.primary {
+  background: var(--dap-hotspot-primary);
+  color: white;
+}
+
+.dap-hotspot-btn.primary:hover {
+  background: #2563eb;
+  border-color: #2563eb;
+}
+
+.dap-hotspots-progress {
+  position: fixed;
+  top: 20px;
+  right: 20px;
+  background: var(--dap-hotspot-bg);
+  border: 1px solid var(--dap-hotspot-border);
+  border-radius: 8px;
+  padding: 12px 16px;
+  z-index: calc(var(--dap-z-hotspots) + 1);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  box-shadow: var(--dap-hotspot-shadow);
+  animation: hotspotProgressIn 0.3s ease-out forwards;
+  opacity: 0;
+}
+
+@keyframes hotspotProgressIn {
+  to { opacity: 1; }
+}
+
+.dap-hotspots-progress-text {
+  font-size: 14px;
+  color: var(--dap-hotspot-text);
+  margin-bottom: 4px;
+}
+
+.dap-hotspots-progress-bar {
+  width: 120px;
+  height: 4px;
+  background: var(--dap-hotspot-border);
+  border-radius: 2px;
+  overflow: hidden;
+}
+
+.dap-hotspots-progress-fill {
+  height: 100%;
+  background: var(--dap-hotspot-primary);
+  border-radius: 2px;
+  transition: width 0.3s ease;
+  width: 0%;
+}
+
+.dap-hotspots-controls {
+  position: fixed;
+  bottom: 20px;
+  right: 20px;
+  display: flex;
+  gap: 8px;
+  z-index: calc(var(--dap-z-hotspots) + 1);
+}
+
+.dap-hotspots-skip {
+  padding: 8px 16px;
+  background: var(--dap-hotspot-bg);
+  border: 1px solid var(--dap-hotspot-border);
+  border-radius: 6px;
+  color: var(--dap-hotspot-text);
+  font-size: 14px;
+  cursor: pointer;
+  transition: all 0.15s ease;
+  box-shadow: var(--dap-hotspot-shadow);
+}
+
+.dap-hotspots-skip:hover {
+  background: var(--dap-hotspot-border);
+}
+
+@media (max-width: 640px) {
+  .dap-hotspots-progress {
+    top: 10px;
+    right: 10px;
+    padding: 8px 12px;
+  }
+  
+  .dap-hotspots-controls {
+    bottom: 10px;
+    right: 10px;
+  }
+  
+  .dap-hotspot-tooltip {
+    max-width: 280px;
+    padding: 12px;
+  }
+}
+`;
+
+export function registerHotspots() {
+  register("hotspots", renderHotspots);
+}
+
+export async function renderHotspots(flow: HotspotsFlow): Promise<void> {
+  const { payload, id } = flow;
+  
+  // Extract completion tracker
+  const completionTracker = payload._completionTracker;
+  
+  // Ensure CSS is injected
+  ensureStyles();
+  
+  // Track completed hotspots
+  const completedHotspots = new Set<string>();
+  let currentTooltip: HTMLElement | null = null;
+  
+  // Create overlay
+  const overlay = document.createElement("div");
+  overlay.className = "dap-hotspots-overlay";
+  document.documentElement.appendChild(overlay);
+  
+  // Create progress indicator if enabled
+  let progressEl: HTMLElement | null = null;
+  if (payload.showProgress) {
+    progressEl = createProgressIndicator(payload);
+    document.documentElement.appendChild(progressEl);
+  }
+  
+  // Create skip controls if allowed
+  let skipEl: HTMLElement | null = null;
+  if (payload.allowSkip) {
+    skipEl = createSkipControls();
+    document.documentElement.appendChild(skipEl);
+    skipEl.addEventListener("click", completeHotspots);
+  }
+  
+  // Create hotspot markers
+  const markers: HTMLElement[] = [];
+  const waitForElements = payload.hotspots.map(async (hotspot) => {
+    try {
+      const element = await waitForElement(hotspot.selector, { timeout: 2000 });
+      if (element && element instanceof HTMLElement) {
+        createHotspotMarker(hotspot, element);
+      }
+    } catch (error) {
+      console.warn(`[DAP] Failed to find element for hotspot: ${hotspot.selector}`);
+    }
+  });
+  
+  await Promise.allSettled(waitForElements);
+  
+  function createHotspotMarker(hotspot: HotspotItem, element: HTMLElement) {
+    const rect = element.getBoundingClientRect();
+    const marker = document.createElement("div");
+    marker.className = "dap-hotspot-marker";
+    marker.dataset.hotspotId = hotspot.id;
+    
+    if (hotspot.required) {
+      marker.classList.add("required");
+    }
+    
+    if (hotspot.pulseColor) {
+      marker.style.background = hotspot.pulseColor;
+    }
+    
+    // Position marker at element center
+    marker.style.left = `${rect.left + window.scrollX + rect.width / 2 - 12}px`;
+    marker.style.top = `${rect.top + window.scrollY + rect.height / 2 - 12}px`;
+    
+    marker.addEventListener("click", () => showTooltip(hotspot, marker, element));
+    
+    document.documentElement.appendChild(marker);
+    markers.push(marker);
+  }
+  
+  function showTooltip(hotspot: HotspotItem, marker: HTMLElement, element: HTMLElement) {
+    // Hide current tooltip if any
+    if (currentTooltip) {
+      currentTooltip.remove();
+    }
+    
+    const tooltip = document.createElement("div");
+    tooltip.className = "dap-hotspot-tooltip";
+    
+    const title = document.createElement("h3");
+    title.className = "dap-hotspot-title";
+    title.textContent = hotspot.title;
+    
+    const description = document.createElement("div");
+    description.className = "dap-hotspot-description";
+    description.innerHTML = sanitizeHtml(hotspot.description);
+    
+    const actions = document.createElement("div");
+    actions.className = "dap-hotspot-actions";
+    
+    const gotItBtn = document.createElement("button");
+    gotItBtn.className = "dap-hotspot-btn primary";
+    gotItBtn.textContent = "Got it!";
+    gotItBtn.addEventListener("click", () => {
+      markHotspotCompleted(hotspot, marker);
+      tooltip.remove();
+      currentTooltip = null;
+    });
+    
+    actions.appendChild(gotItBtn);
+    tooltip.appendChild(title);
+    tooltip.appendChild(description);
+    tooltip.appendChild(actions);
+    
+    // Position tooltip
+    positionTooltip(tooltip, marker, element, hotspot.placement || "top");
+    
+    document.documentElement.appendChild(tooltip);
+    currentTooltip = tooltip;
+    
+    // Click outside to close
+    setTimeout(() => {
+      const closeOnOutside = (e: MouseEvent) => {
+        if (!tooltip.contains(e.target as Node) && !marker.contains(e.target as Node)) {
+          tooltip.remove();
+          currentTooltip = null;
+          document.removeEventListener("click", closeOnOutside);
+        }
+      };
+      document.addEventListener("click", closeOnOutside);
+    }, 100);
+  }
+  
+  function positionTooltip(tooltip: HTMLElement, marker: HTMLElement, element: HTMLElement, placement: CornerPlacement) {
+    const rect = element.getBoundingClientRect();
+    const markerRect = marker.getBoundingClientRect();
+    
+    // Apply placement class for arrow positioning
+    tooltip.classList.add(placement);
+    
+    let left = 0;
+    let top = 0;
+    
+    switch (placement) {
+      case "top":
+        left = markerRect.left - 160 + markerRect.width / 2;
+        top = markerRect.top - 16 - 120; // tooltip height estimate
+        break;
+      case "bottom":
+        left = markerRect.left - 160 + markerRect.width / 2;
+        top = markerRect.bottom + 16;
+        break;
+      case "left":
+        left = markerRect.left - 320 - 16;
+        top = markerRect.top - 60 + markerRect.height / 2;
+        break;
+      case "right":
+        left = markerRect.right + 16;
+        top = markerRect.top - 60 + markerRect.height / 2;
+        break;
+      default:
+        left = markerRect.left - 160 + markerRect.width / 2;
+        top = markerRect.top - 16 - 120;
+    }
+    
+    // Keep within viewport bounds
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    
+    left = Math.max(10, Math.min(left, viewportWidth - 330));
+    top = Math.max(10, Math.min(top, viewportHeight - 150));
+    
+    tooltip.style.left = `${left + window.scrollX}px`;
+    tooltip.style.top = `${top + window.scrollY}px`;
+  }
+  
+  function markHotspotCompleted(hotspot: HotspotItem, marker: HTMLElement) {
+    completedHotspots.add(hotspot.id);
+    marker.classList.add("completed");
+    
+    // Update progress
+    if (progressEl) {
+      updateProgress();
+    }
+    
+    // Check if all required hotspots are completed
+    const requiredHotspots = payload.hotspots.filter(h => h.required);
+    const completedRequired = requiredHotspots.filter(h => completedHotspots.has(h.id));
+    
+    if (completedRequired.length === requiredHotspots.length) {
+      // Allow completion after a short delay
+      setTimeout(() => {
+        if (canComplete()) {
+          completeHotspots();
+        }
+      }, 1000);
+    }
+  }
+  
+  function updateProgress() {
+    if (!progressEl) return;
+    
+    const total = payload.hotspots.length;
+    const completed = completedHotspots.size;
+    const percentage = (completed / total) * 100;
+    
+    const progressText = progressEl.querySelector(".dap-hotspots-progress-text") as HTMLElement;
+    const progressFill = progressEl.querySelector(".dap-hotspots-progress-fill") as HTMLElement;
+    
+    if (progressText) {
+      progressText.textContent = `${completed} / ${total} explored`;
+    }
+    if (progressFill) {
+      progressFill.style.width = `${percentage}%`;
+    }
+  }
+  
+  function canComplete(): boolean {
+    const requiredHotspots = payload.hotspots.filter(h => h.required);
+    return requiredHotspots.every(h => completedHotspots.has(h.id));
+  }
+  
+  function completeHotspots() {
+    // Clean up
+    overlay.remove();
+    markers.forEach(marker => marker.remove());
+    if (currentTooltip) {
+      currentTooltip.remove();
+    }
+    if (progressEl) {
+      progressEl.remove();
+    }
+    if (skipEl) {
+      skipEl.remove();
+    }
+    
+    // Signal completion
+    if (completionTracker?.onComplete) {
+      console.debug(`[DAP] Completing hotspots flow: ${id}`);
+      completionTracker.onComplete();
+    }
+  }
+  
+  // Keyboard accessibility
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape") {
+      if (currentTooltip) {
+        currentTooltip.remove();
+        currentTooltip = null;
+      } else if (payload.allowSkip) {
+        completeHotspots();
+      }
+    }
+  });
+  
+  // Update progress initially
+  if (progressEl) {
+    updateProgress();
+  }
+}
+
+function createProgressIndicator(payload: HotspotsPayload): HTMLElement {
+  const progress = document.createElement("div");
+  progress.className = "dap-hotspots-progress";
+  
+  const text = document.createElement("div");
+  text.className = "dap-hotspots-progress-text";
+  text.textContent = "0 / " + payload.hotspots.length + " explored";
+  
+  const bar = document.createElement("div");
+  bar.className = "dap-hotspots-progress-bar";
+  
+  const fill = document.createElement("div");
+  fill.className = "dap-hotspots-progress-fill";
+  
+  bar.appendChild(fill);
+  progress.appendChild(text);
+  progress.appendChild(bar);
+  
+  return progress;
+}
+
+function createSkipControls(): HTMLElement {
+  const controls = document.createElement("div");
+  controls.className = "dap-hotspots-controls";
+  
+  const skipBtn = document.createElement("button");
+  skipBtn.className = "dap-hotspots-skip";
+  skipBtn.textContent = "Skip tour";
+  
+  controls.appendChild(skipBtn);
+  return controls;
+}
+
+function ensureStyles() {
+  if (!document.getElementById("dap-hotspots-style")) {
+    const style = document.createElement("style");
+    style.id = "dap-hotspots-style";
+    style.textContent = hotspotsCssText;
+    document.head.appendChild(style);
+  }
+}