@cognior/iap-sdk 0.1.0

package/src/experiences/hotspotTour.ts

@@ -0,0 +1,654 @@
+// src/experiences/hotspotTour.ts
+// Sequential guided tour experience with hotspots
+
+import { sanitizeHtml } from "../utils/sanitize";
+import { register } from "./registry";
+import { waitForElement } from "../utils/triggerNormalizer";
+import type { HotspotTourPayload, HotspotTourStep, CornerPlacement } from "./types";
+
+type HotspotTourFlow = { id: string; type: "hotspotTour"; payload: HotspotTourPayload };
+
+const hotspotTourCssText = `
+:root {
+  --dap-z-tour: 2147483635;
+  --dap-tour-primary: #3b82f6;
+  --dap-tour-bg: #ffffff;
+  --dap-tour-border: #e2e8f0;
+  --dap-tour-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
+  --dap-tour-text: #1e293b;
+  --dap-tour-text-muted: #64748b;
+  --dap-tour-overlay: rgba(15, 23, 42, 0.5);
+}
+
+.dap-tour-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--dap-tour-overlay);
+  z-index: var(--dap-z-tour);
+  pointer-events: none;
+  opacity: 0;
+  animation: tourOverlayFadeIn 0.3s ease-out forwards;
+}
+
+@keyframes tourOverlayFadeIn {
+  to { opacity: 1; }
+}
+
+.dap-tour-spotlight {
+  position: absolute;
+  border: 3px solid var(--dap-tour-primary);
+  border-radius: 8px;
+  pointer-events: none;
+  z-index: calc(var(--dap-z-tour) + 1);
+  box-shadow: 0 0 0 9999px rgba(15, 23, 42, 0.5);
+  transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1);
+  animation: tourSpotlightPulse 2s ease-in-out infinite;
+}
+
+@keyframes tourSpotlightPulse {
+  0%, 100% { 
+    border-color: var(--dap-tour-primary);
+    box-shadow: 0 0 0 9999px rgba(15, 23, 42, 0.5), 0 0 20px rgba(59, 130, 246, 0.3);
+  }
+  50% { 
+    border-color: #60a5fa;
+    box-shadow: 0 0 0 9999px rgba(15, 23, 42, 0.4), 0 0 30px rgba(59, 130, 246, 0.5);
+  }
+}
+
+.dap-tour-tooltip {
+  position: absolute;
+  background: var(--dap-tour-bg);
+  border: 1px solid var(--dap-tour-border);
+  border-radius: 12px;
+  box-shadow: var(--dap-tour-shadow);
+  padding: 20px;
+  max-width: 360px;
+  z-index: calc(var(--dap-z-tour) + 2);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  opacity: 0;
+  transform: scale(0.9);
+  animation: tourTooltipIn 0.3s ease-out 0.2s forwards;
+  pointer-events: auto;
+}
+
+@keyframes tourTooltipIn {
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.dap-tour-tooltip::before {
+  content: '';
+  position: absolute;
+  width: 0;
+  height: 0;
+  border: 12px solid transparent;
+}
+
+.dap-tour-tooltip.top::before {
+  bottom: -24px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-top-color: var(--dap-tour-bg);
+}
+
+.dap-tour-tooltip.bottom::before {
+  top: -24px;
+  left: 50%;
+  transform: translateX(-50%);
+  border-bottom-color: var(--dap-tour-bg);
+}
+
+.dap-tour-tooltip.left::before {
+  right: -24px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-left-color: var(--dap-tour-bg);
+}
+
+.dap-tour-tooltip.right::before {
+  left: -24px;
+  top: 50%;
+  transform: translateY(-50%);
+  border-right-color: var(--dap-tour-bg);
+}
+
+.dap-tour-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 12px;
+}
+
+.dap-tour-title {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--dap-tour-text);
+  margin: 0;
+}
+
+.dap-tour-step-indicator {
+  font-size: 12px;
+  color: var(--dap-tour-text-muted);
+  background: var(--dap-tour-border);
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-weight: 500;
+}
+
+.dap-tour-description {
+  font-size: 14px;
+  color: var(--dap-tour-text-muted);
+  line-height: 1.5;
+  margin: 0 0 16px 0;
+}
+
+.dap-tour-actions {
+  display: flex;
+  gap: 8px;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.dap-tour-nav {
+  display: flex;
+  gap: 8px;
+}
+
+.dap-tour-btn {
+  padding: 8px 16px;
+  border: 1px solid var(--dap-tour-border);
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dap-tour-text);
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.dap-tour-btn:hover {
+  background: var(--dap-tour-border);
+}
+
+.dap-tour-btn.primary {
+  background: var(--dap-tour-primary);
+  border-color: var(--dap-tour-primary);
+  color: white;
+}
+
+.dap-tour-btn.primary:hover {
+  background: #2563eb;
+  border-color: #2563eb;
+}
+
+.dap-tour-skip {
+  font-size: 12px;
+  color: var(--dap-tour-text-muted);
+  text-decoration: underline;
+  cursor: pointer;
+  padding: 4px;
+  border: none;
+  background: none;
+}
+
+.dap-tour-skip:hover {
+  color: var(--dap-tour-text);
+}
+
+.dap-tour-progress {
+  position: fixed;
+  top: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+  background: var(--dap-tour-bg);
+  border: 1px solid var(--dap-tour-border);
+  border-radius: 20px;
+  padding: 8px 16px;
+  z-index: calc(var(--dap-z-tour) + 1);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  box-shadow: var(--dap-tour-shadow);
+  animation: tourProgressIn 0.3s ease-out forwards;
+  opacity: 0;
+}
+
+@keyframes tourProgressIn {
+  to { opacity: 1; }
+}
+
+.dap-tour-progress-text {
+  font-size: 12px;
+  color: var(--dap-tour-text-muted);
+  margin-bottom: 4px;
+  text-align: center;
+}
+
+.dap-tour-progress-bar {
+  width: 200px;
+  height: 3px;
+  background: var(--dap-tour-border);
+  border-radius: 2px;
+  overflow: hidden;
+}
+
+.dap-tour-progress-fill {
+  height: 100%;
+  background: var(--dap-tour-primary);
+  border-radius: 2px;
+  transition: width 0.4s ease;
+  width: 0%;
+}
+
+.dap-tour-close {
+  position: fixed;
+  top: 20px;
+  right: 20px;
+  background: var(--dap-tour-bg);
+  border: 1px solid var(--dap-tour-border);
+  border-radius: 50%;
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  z-index: calc(var(--dap-z-tour) + 1);
+  box-shadow: var(--dap-tour-shadow);
+  color: var(--dap-tour-text-muted);
+  font-size: 18px;
+  transition: all 0.15s ease;
+}
+
+.dap-tour-close:hover {
+  background: var(--dap-tour-border);
+  color: var(--dap-tour-text);
+}
+
+@media (max-width: 640px) {
+  .dap-tour-tooltip {
+    max-width: 320px;
+    padding: 16px;
+  }
+  
+  .dap-tour-progress {
+    top: 10px;
+    padding: 6px 12px;
+  }
+  
+  .dap-tour-progress-bar {
+    width: 160px;
+  }
+  
+  .dap-tour-close {
+    top: 10px;
+    right: 10px;
+    width: 36px;
+    height: 36px;
+  }
+  
+  .dap-tour-actions {
+    flex-direction: column;
+    gap: 8px;
+  }
+  
+  .dap-tour-nav {
+    width: 100%;
+    justify-content: space-between;
+  }
+}
+`;
+
+export function registerHotspotTour() {
+  register("hotspotTour", renderHotspotTour);
+}
+
+export async function renderHotspotTour(flow: HotspotTourFlow): Promise<void> {
+  const { payload, id } = flow;
+  
+  // Extract completion tracker
+  const completionTracker = payload._completionTracker;
+  
+  // Ensure CSS is injected
+  ensureStyles();
+  
+  // Tour state
+  let currentStepIndex = 0;
+  let currentSpotlight: HTMLElement | null = null;
+  let currentTooltip: HTMLElement | null = null;
+  let autoAdvanceTimer: number | undefined;
+  
+  // Create overlay and UI elements
+  const overlay = createTourOverlay();
+  const progressEl = payload.showProgress ? createProgressIndicator(payload) : null;
+  const closeEl = createCloseButton();
+  
+  document.documentElement.appendChild(overlay);
+  if (progressEl) document.documentElement.appendChild(progressEl);
+  document.documentElement.appendChild(closeEl);
+  
+  // Event listeners
+  closeEl.addEventListener("click", completeTour);
+  
+  // Keyboard navigation
+  document.addEventListener("keydown", handleKeyboard);
+  
+  // Start the tour
+  await showStep(currentStepIndex);
+  
+  async function showStep(stepIndex: number) {
+    if (stepIndex >= payload.steps.length) {
+      completeTour();
+      return;
+    }
+    
+    const step = payload.steps[stepIndex];
+    currentStepIndex = stepIndex;
+    
+    // Clear auto-advance timer
+    if (autoAdvanceTimer) {
+      clearTimeout(autoAdvanceTimer);
+      autoAdvanceTimer = undefined;
+    }
+    
+    try {
+      // Wait for target element
+      const element = await waitForElement(step.selector, { timeout: 3000 });
+      if (!(element instanceof HTMLElement)) {
+        console.warn(`[DAP] Element not found for step: ${step.selector}`);
+        nextStep();
+        return;
+      }
+      
+      // Create spotlight
+      createSpotlight(element);
+      
+      // Create tooltip
+      createTooltip(step, element);
+      
+      // Update progress
+      if (progressEl) {
+        updateProgress();
+      }
+      
+      // Auto-advance if configured
+      if (payload.autoAdvance && payload.autoAdvance > 0) {
+        autoAdvanceTimer = window.setTimeout(() => {
+          nextStep();
+        }, payload.autoAdvance * 1000);
+      }
+      
+    } catch (error) {
+      console.warn(`[DAP] Failed to show step ${stepIndex}:`, error);
+      nextStep();
+    }
+  }
+  
+  function createSpotlight(element: HTMLElement) {
+    // Remove previous spotlight
+    if (currentSpotlight) {
+      currentSpotlight.remove();
+    }
+    
+    const rect = element.getBoundingClientRect();
+    const spotlight = document.createElement("div");
+    spotlight.className = "dap-tour-spotlight";
+    
+    // Position spotlight around element with padding
+    const padding = 8;
+    spotlight.style.left = `${rect.left + window.scrollX - padding}px`;
+    spotlight.style.top = `${rect.top + window.scrollY - padding}px`;
+    spotlight.style.width = `${rect.width + padding * 2}px`;
+    spotlight.style.height = `${rect.height + padding * 2}px`;
+    
+    document.documentElement.appendChild(spotlight);
+    currentSpotlight = spotlight;
+    
+    // Scroll element into view if needed
+    element.scrollIntoView({ behavior: "smooth", block: "center" });
+  }
+  
+  function createTooltip(step: HotspotTourStep, element: HTMLElement) {
+    // Remove previous tooltip
+    if (currentTooltip) {
+      currentTooltip.remove();
+    }
+    
+    const tooltip = document.createElement("div");
+    tooltip.className = "dap-tour-tooltip";
+    
+    // Header
+    const header = document.createElement("div");
+    header.className = "dap-tour-header";
+    
+    const title = document.createElement("h3");
+    title.className = "dap-tour-title";
+    title.textContent = step.title;
+    
+    const indicator = document.createElement("span");
+    indicator.className = "dap-tour-step-indicator";
+    indicator.textContent = `${currentStepIndex + 1} / ${payload.steps.length}`;
+    
+    header.appendChild(title);
+    header.appendChild(indicator);
+    
+    // Description
+    const description = document.createElement("div");
+    description.className = "dap-tour-description";
+    description.innerHTML = sanitizeHtml(step.description);
+    
+    // Actions
+    const actions = document.createElement("div");
+    actions.className = "dap-tour-actions";
+    
+    // Skip button (if allowed)
+    if (payload.allowSkip) {
+      const skipBtn = document.createElement("button");
+      skipBtn.className = "dap-tour-skip";
+      skipBtn.textContent = "Skip tour";
+      skipBtn.addEventListener("click", completeTour);
+      actions.appendChild(skipBtn);
+    } else {
+      actions.appendChild(document.createElement("div")); // spacer
+    }
+    
+    // Navigation
+    const nav = document.createElement("div");
+    nav.className = "dap-tour-nav";
+    
+    // Previous button
+    if (currentStepIndex > 0) {
+      const prevBtn = document.createElement("button");
+      prevBtn.className = "dap-tour-btn";
+      prevBtn.textContent = "Previous";
+      prevBtn.addEventListener("click", previousStep);
+      nav.appendChild(prevBtn);
+    }
+    
+    // Next/Close button
+    const nextBtn = document.createElement("button");
+    nextBtn.className = "dap-tour-btn primary";
+    
+    if (currentStepIndex === payload.steps.length - 1) {
+      nextBtn.textContent = step.action === "close" ? "Close" : "Finish";
+      nextBtn.addEventListener("click", () => {
+        if (step.action === "custom" && step.customAction) {
+          window.dispatchEvent(new CustomEvent("dap-tour-action", {
+            detail: { action: step.customAction, tourId: id, stepId: step.id }
+          }));
+        }
+        completeTour();
+      });
+    } else {
+      nextBtn.textContent = "Next";
+      nextBtn.addEventListener("click", nextStep);
+    }
+    
+    nav.appendChild(nextBtn);
+    actions.appendChild(nav);
+    
+    // Assemble tooltip
+    tooltip.appendChild(header);
+    tooltip.appendChild(description);
+    tooltip.appendChild(actions);
+    
+    // Position tooltip
+    positionTooltip(tooltip, element, step.placement || "bottom");
+    
+    document.documentElement.appendChild(tooltip);
+    currentTooltip = tooltip;
+  }
+  
+  function positionTooltip(tooltip: HTMLElement, element: HTMLElement, placement: CornerPlacement) {
+    const rect = element.getBoundingClientRect();
+    
+    // Apply placement class for arrow
+    tooltip.classList.add(placement);
+    
+    let left = 0;
+    let top = 0;
+    
+    switch (placement) {
+      case "top":
+        left = rect.left + window.scrollX + rect.width / 2 - 180; // tooltip width / 2
+        top = rect.top + window.scrollY - 16 - 140; // tooltip height estimate
+        break;
+      case "bottom":
+        left = rect.left + window.scrollX + rect.width / 2 - 180;
+        top = rect.bottom + window.scrollY + 16;
+        break;
+      case "left":
+        left = rect.left + window.scrollX - 360 - 16;
+        top = rect.top + window.scrollY + rect.height / 2 - 70;
+        break;
+      case "right":
+        left = rect.right + window.scrollX + 16;
+        top = rect.top + window.scrollY + rect.height / 2 - 70;
+        break;
+      default:
+        left = rect.left + window.scrollX + rect.width / 2 - 180;
+        top = rect.bottom + window.scrollY + 16;
+    }
+    
+    // Keep within viewport bounds
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    
+    left = Math.max(10, Math.min(left, viewportWidth - 370));
+    top = Math.max(10, Math.min(top, viewportHeight - 160));
+    
+    tooltip.style.left = `${left}px`;
+    tooltip.style.top = `${top}px`;
+  }
+  
+  function nextStep() {
+    showStep(currentStepIndex + 1);
+  }
+  
+  function previousStep() {
+    if (currentStepIndex > 0) {
+      showStep(currentStepIndex - 1);
+    }
+  }
+  
+  function updateProgress() {
+    if (!progressEl) return;
+    
+    const progress = ((currentStepIndex + 1) / payload.steps.length) * 100;
+    const progressText = progressEl.querySelector(".dap-tour-progress-text") as HTMLElement;
+    const progressFill = progressEl.querySelector(".dap-tour-progress-fill") as HTMLElement;
+    
+    if (progressText) {
+      progressText.textContent = `Step ${currentStepIndex + 1} of ${payload.steps.length}`;
+    }
+    if (progressFill) {
+      progressFill.style.width = `${progress}%`;
+    }
+  }
+  
+  function handleKeyboard(e: KeyboardEvent) {
+    switch (e.key) {
+      case "Escape":
+        if (payload.allowSkip) {
+          completeTour();
+        }
+        break;
+      case "ArrowRight":
+        e.preventDefault();
+        nextStep();
+        break;
+      case "ArrowLeft":
+        e.preventDefault();
+        previousStep();
+        break;
+    }
+  }
+  
+  function completeTour() {
+    // Clear timer
+    if (autoAdvanceTimer) {
+      clearTimeout(autoAdvanceTimer);
+    }
+    
+    // Remove event listener
+    document.removeEventListener("keydown", handleKeyboard);
+    
+    // Clean up elements
+    overlay.remove();
+    if (currentSpotlight) currentSpotlight.remove();
+    if (currentTooltip) currentTooltip.remove();
+    if (progressEl) progressEl.remove();
+    closeEl.remove();
+    
+    // Signal completion
+    if (completionTracker?.onComplete) {
+      console.debug(`[DAP] Completing hotspot tour flow: ${id}`);
+      completionTracker.onComplete();
+    }
+  }
+}
+
+function createTourOverlay(): HTMLElement {
+  const overlay = document.createElement("div");
+  overlay.className = "dap-tour-overlay";
+  return overlay;
+}
+
+function createProgressIndicator(payload: HotspotTourPayload): HTMLElement {
+  const progress = document.createElement("div");
+  progress.className = "dap-tour-progress";
+  
+  const text = document.createElement("div");
+  text.className = "dap-tour-progress-text";
+  text.textContent = `Step 1 of ${payload.steps.length}`;
+  
+  const bar = document.createElement("div");
+  bar.className = "dap-tour-progress-bar";
+  
+  const fill = document.createElement("div");
+  fill.className = "dap-tour-progress-fill";
+  
+  bar.appendChild(fill);
+  progress.appendChild(text);
+  progress.appendChild(bar);
+  
+  return progress;
+}
+
+function createCloseButton(): HTMLElement {
+  const closeBtn = document.createElement("button");
+  closeBtn.className = "dap-tour-close";
+  closeBtn.innerHTML = "×";
+  closeBtn.setAttribute("aria-label", "Close tour");
+  return closeBtn;
+}
+
+function ensureStyles() {
+  if (!document.getElementById("dap-tour-style")) {
+    const style = document.createElement("style");
+    style.id = "dap-tour-style";
+    style.textContent = hotspotTourCssText;
+    document.head.appendChild(style);
+  }
+}