@cognior/iap-sdk 0.1.0

package/src/experiences/walkthrough.ts

@@ -0,0 +1,670 @@
+// src/experiences/walkthrough.ts
+// Guided walkthrough experience renderer with step-by-step navigation
+
+import { sanitizeHtml } from "../utils/sanitize";
+import { waitForElement, resolveSelector } from "../utils/selectors";
+import { register } from "./registry";
+import type { WalkthroughPayload, WalkthroughStep } from "./types";
+
+type WalkthroughFlow = { id: string; type: "walkthrough"; payload: WalkthroughPayload };
+
+const walkthroughCssText = `
+:root {
+  --dap-z-walkthrough: 2147483630;
+  --dap-walkthrough-overlay: rgba(15, 23, 42, 0.75);
+  --dap-walkthrough-bg: #ffffff;
+  --dap-walkthrough-border: #e2e8f0;
+  --dap-walkthrough-shadow: 0 20px 40px rgba(0, 0, 0, 0.2);
+  --dap-walkthrough-text: #1e293b;
+  --dap-walkthrough-text-muted: #64748b;
+  --dap-walkthrough-primary: #3b82f6;
+  --dap-walkthrough-success: #10b981;
+  --dap-walkthrough-highlight: #fef3c7;
+}
+
+.dap-walkthrough-overlay {
+  position: fixed;
+  inset: 0;
+  background: var(--dap-walkthrough-overlay);
+  z-index: var(--dap-z-walkthrough);
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.dap-walkthrough-overlay.active {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.dap-walkthrough-spotlight {
+  position: absolute;
+  border: 2px solid var(--dap-walkthrough-primary);
+  border-radius: 8px;
+  box-shadow: 0 0 0 9999px var(--dap-walkthrough-overlay);
+  pointer-events: none;
+  transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1);
+  z-index: calc(var(--dap-z-walkthrough) + 1);
+}
+
+.dap-walkthrough-tooltip {
+  position: absolute;
+  background: var(--dap-walkthrough-bg);
+  border: 1px solid var(--dap-walkthrough-border);
+  border-radius: 12px;
+  box-shadow: var(--dap-walkthrough-shadow);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  width: 320px;
+  max-width: 90vw;
+  z-index: calc(var(--dap-z-walkthrough) + 2);
+  opacity: 0;
+  transform: scale(0.95);
+  transition: all 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  pointer-events: auto;
+}
+
+.dap-walkthrough-tooltip.visible {
+  opacity: 1;
+  transform: scale(1);
+}
+
+.dap-walkthrough-tooltip::before {
+  content: '';
+  position: absolute;
+  width: 12px;
+  height: 12px;
+  background: var(--dap-walkthrough-bg);
+  border: 1px solid var(--dap-walkthrough-border);
+  border-bottom: none;
+  border-right: none;
+  transform: rotate(45deg);
+}
+
+.dap-walkthrough-tooltip.position-top {
+  transform-origin: bottom center;
+}
+
+.dap-walkthrough-tooltip.position-top::before {
+  bottom: -7px;
+  left: 50%;
+  margin-left: -6px;
+  border-top: none;
+  border-left: none;
+  border-bottom: 1px solid var(--dap-walkthrough-border);
+  border-right: 1px solid var(--dap-walkthrough-border);
+  transform: rotate(-135deg);
+}
+
+.dap-walkthrough-tooltip.position-bottom {
+  transform-origin: top center;
+}
+
+.dap-walkthrough-tooltip.position-bottom::before {
+  top: -7px;
+  left: 50%;
+  margin-left: -6px;
+}
+
+.dap-walkthrough-tooltip.position-left {
+  transform-origin: right center;
+}
+
+.dap-walkthrough-tooltip.position-left::before {
+  right: -7px;
+  top: 50%;
+  margin-top: -6px;
+  border-top: none;
+  border-left: none;
+  border-bottom: 1px solid var(--dap-walkthrough-border);
+  border-right: 1px solid var(--dap-walkthrough-border);
+  transform: rotate(-45deg);
+}
+
+.dap-walkthrough-tooltip.position-right {
+  transform-origin: left center;
+}
+
+.dap-walkthrough-tooltip.position-right::before {
+  left: -7px;
+  top: 50%;
+  margin-top: -6px;
+  border-bottom: none;
+  border-right: none;
+  border-top: 1px solid var(--dap-walkthrough-border);
+  border-left: 1px solid var(--dap-walkthrough-border);
+  transform: rotate(135deg);
+}
+
+.dap-walkthrough-header {
+  padding: 20px 20px 16px;
+  border-bottom: 1px solid var(--dap-walkthrough-border);
+  position: relative;
+}
+
+.dap-walkthrough-step-indicator {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--dap-walkthrough-primary);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-bottom: 8px;
+}
+
+.dap-walkthrough-title {
+  font-size: 18px;
+  font-weight: 600;
+  color: var(--dap-walkthrough-text);
+  margin: 0;
+  line-height: 1.3;
+}
+
+.dap-walkthrough-close {
+  position: absolute;
+  top: 16px;
+  right: 16px;
+  background: none;
+  border: none;
+  font-size: 18px;
+  color: var(--dap-walkthrough-text-muted);
+  cursor: pointer;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 4px;
+  transition: background-color 0.15s ease;
+}
+
+.dap-walkthrough-close:hover {
+  background: var(--dap-walkthrough-border);
+}
+
+.dap-walkthrough-body {
+  padding: 16px 20px;
+}
+
+.dap-walkthrough-content {
+  font-size: 14px;
+  color: var(--dap-walkthrough-text);
+  line-height: 1.6;
+  margin: 0;
+}
+
+.dap-walkthrough-footer {
+  padding: 16px 20px;
+  border-top: 1px solid var(--dap-walkthrough-border);
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.dap-walkthrough-progress {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+}
+
+.dap-walkthrough-progress-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--dap-walkthrough-border);
+  transition: all 0.2s ease;
+}
+
+.dap-walkthrough-progress-dot.active {
+  background: var(--dap-walkthrough-primary);
+  transform: scale(1.25);
+}
+
+.dap-walkthrough-progress-dot.completed {
+  background: var(--dap-walkthrough-success);
+}
+
+.dap-walkthrough-nav {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+.dap-walkthrough-btn {
+  padding: 8px 16px;
+  border: 1px solid var(--dap-walkthrough-border);
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dap-walkthrough-text);
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.dap-walkthrough-btn:hover {
+  background: var(--dap-walkthrough-border);
+}
+
+.dap-walkthrough-btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.dap-walkthrough-btn.primary {
+  background: var(--dap-walkthrough-primary);
+  border-color: var(--dap-walkthrough-primary);
+  color: white;
+}
+
+.dap-walkthrough-btn.primary:hover:not(:disabled) {
+  background: #2563eb;
+  border-color: #2563eb;
+}
+
+.dap-walkthrough-btn.success {
+  background: var(--dap-walkthrough-success);
+  border-color: var(--dap-walkthrough-success);
+  color: white;
+}
+
+.dap-walkthrough-btn.success:hover:not(:disabled) {
+  background: #059669;
+  border-color: #059669;
+}
+
+.dap-walkthrough-step-count {
+  font-size: 12px;
+  color: var(--dap-walkthrough-text-muted);
+  margin-right: 12px;
+}
+
+.dap-walkthrough-highlight {
+  position: relative;
+  z-index: calc(var(--dap-z-walkthrough) + 1);
+}
+
+.dap-walkthrough-highlight::after {
+  content: '';
+  position: absolute;
+  inset: -4px;
+  background: var(--dap-walkthrough-highlight);
+  border-radius: 6px;
+  opacity: 0.6;
+  z-index: -1;
+  animation: walkthroughPulse 2s infinite;
+}
+
+@keyframes walkthroughPulse {
+  0%, 100% { opacity: 0.6; transform: scale(1); }
+  50% { opacity: 0.8; transform: scale(1.02); }
+}
+
+@media (max-width: 640px) {
+  .dap-walkthrough-tooltip {
+    width: 280px;
+    max-width: calc(100vw - 32px);
+  }
+  
+  .dap-walkthrough-header {
+    padding: 16px;
+  }
+  
+  .dap-walkthrough-body {
+    padding: 12px 16px;
+  }
+  
+  .dap-walkthrough-footer {
+    padding: 12px 16px;
+    flex-direction: column;
+    gap: 12px;
+    align-items: stretch;
+  }
+  
+  .dap-walkthrough-nav {
+    justify-content: space-between;
+    width: 100%;
+  }
+  
+  .dap-walkthrough-step-count {
+    margin-right: 0;
+    text-align: center;
+  }
+}
+`;
+
+export function registerWalkthrough() {
+  register("walkthrough", renderWalkthrough);
+}
+
+export async function renderWalkthrough(flow: WalkthroughFlow): Promise<void> {
+  const { payload, id } = flow;
+  const completionTracker = payload._completionTracker;
+  
+  // Ensure CSS is injected
+  ensureStyles();
+  
+  let currentStepIndex = 0;
+  let isActive = false;
+  
+  // Create overlay and spotlight
+  const overlay = createWalkthroughOverlay();
+  const spotlight = createSpotlight();
+  const tooltip = createTooltip();
+  
+  document.documentElement.appendChild(overlay);
+  document.documentElement.appendChild(spotlight);
+  document.documentElement.appendChild(tooltip);
+  
+  // Start walkthrough
+  await showStep(currentStepIndex);
+  
+  async function showStep(stepIndex: number): Promise<void> {
+    if (stepIndex < 0 || stepIndex >= payload.steps.length) return;
+    
+    const step = payload.steps[stepIndex];
+    currentStepIndex = stepIndex;
+    
+    // Highlight target element
+    let targetElement: Element | null = null;
+    
+    if (step.target) {
+      try {
+        targetElement = await waitForElement(step.target, { timeout: step.waitTimeout || 5000 });
+      } catch (error) {
+        console.warn(`[DAP] Walkthrough target not found: ${step.target}`, error);
+      }
+    }
+    
+    // Position spotlight
+    if (targetElement) {
+      positionSpotlight(targetElement);
+      
+      // Add highlight class
+      targetElement.classList.add('dap-walkthrough-highlight');
+      
+      // Scroll into view
+      if (step.autoScroll !== false) {
+        targetElement.scrollIntoView({ 
+          behavior: 'smooth', 
+          block: 'center',
+          inline: 'center'
+        });
+      }
+    } else {
+      hideSpotlight();
+    }
+    
+    // Update tooltip content
+    updateTooltipContent(step, stepIndex);
+    
+    // Position tooltip
+    if (targetElement) {
+      positionTooltip(tooltip, targetElement, step.position || 'bottom');
+    } else {
+      positionTooltipCenter(tooltip);
+    }
+    
+    // Show elements
+    overlay.classList.add('active');
+    spotlight.style.opacity = targetElement ? '1' : '0';
+    tooltip.classList.add('visible');
+    isActive = true;
+    
+    // Auto-advance
+    if (step.autoAdvance && step.autoAdvanceDelay) {
+      setTimeout(() => {
+        if (isActive && currentStepIndex === stepIndex) {
+          nextStep();
+        }
+      }, step.autoAdvanceDelay);
+    }
+    
+    // Clean up previous highlights
+    document.querySelectorAll('.dap-walkthrough-highlight').forEach(el => {
+      if (el !== targetElement) {
+        el.classList.remove('dap-walkthrough-highlight');
+      }
+    });
+  }
+  
+  function positionSpotlight(element: Element) {
+    const rect = element.getBoundingClientRect();
+    const padding = 8;
+    
+    spotlight.style.left = `${rect.left - padding}px`;
+    spotlight.style.top = `${rect.top - padding}px`;
+    spotlight.style.width = `${rect.width + padding * 2}px`;
+    spotlight.style.height = `${rect.height + padding * 2}px`;
+  }
+  
+  function hideSpotlight() {
+    spotlight.style.opacity = '0';
+  }
+  
+  function updateTooltipContent(step: WalkthroughStep, stepIndex: number) {
+    // Header
+    const stepIndicator = tooltip.querySelector('.dap-walkthrough-step-indicator') as HTMLElement;
+    const title = tooltip.querySelector('.dap-walkthrough-title') as HTMLElement;
+    
+    stepIndicator.textContent = `Step ${stepIndex + 1} of ${payload.steps.length}`;
+    title.textContent = step.title;
+    
+    // Body
+    const content = tooltip.querySelector('.dap-walkthrough-content') as HTMLElement;
+    content.innerHTML = sanitizeHtml(step.content);
+    
+    // Progress dots
+    const progressContainer = tooltip.querySelector('.dap-walkthrough-progress') as HTMLElement;
+    progressContainer.innerHTML = '';
+    
+    payload.steps.forEach((_: WalkthroughStep, index: number) => {
+      const dot = document.createElement('div');
+      dot.className = 'dap-walkthrough-progress-dot';
+      
+      if (index < stepIndex) {
+        dot.classList.add('completed');
+      } else if (index === stepIndex) {
+        dot.classList.add('active');
+      }
+      
+      progressContainer.appendChild(dot);
+    });
+    
+    // Navigation buttons
+    const prevBtn = tooltip.querySelector('.dap-walkthrough-prev') as HTMLButtonElement;
+    const nextBtn = tooltip.querySelector('.dap-walkthrough-next') as HTMLButtonElement;
+    const stepCount = tooltip.querySelector('.dap-walkthrough-step-count') as HTMLElement;
+    
+    prevBtn.disabled = stepIndex === 0;
+    
+    if (stepIndex === payload.steps.length - 1) {
+      nextBtn.textContent = 'Complete';
+      nextBtn.className = 'dap-walkthrough-btn success dap-walkthrough-next';
+    } else {
+      nextBtn.textContent = 'Next';
+      nextBtn.className = 'dap-walkthrough-btn primary dap-walkthrough-next';
+    }
+    
+    stepCount.textContent = `${stepIndex + 1} / ${payload.steps.length}`;
+  }
+  
+  function positionTooltip(tooltip: HTMLElement, target: Element, position: string = 'bottom') {
+    const targetRect = target.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+    const gap = 16;
+    
+    // Reset classes
+    tooltip.className = 'dap-walkthrough-tooltip visible';
+    
+    let left = 0;
+    let top = 0;
+    
+    switch (position) {
+      case 'top':
+        left = targetRect.left + (targetRect.width - tooltipRect.width) / 2;
+        top = targetRect.top - tooltipRect.height - gap;
+        tooltip.classList.add('position-top');
+        break;
+        
+      case 'bottom':
+        left = targetRect.left + (targetRect.width - tooltipRect.width) / 2;
+        top = targetRect.bottom + gap;
+        tooltip.classList.add('position-bottom');
+        break;
+        
+      case 'left':
+        left = targetRect.left - tooltipRect.width - gap;
+        top = targetRect.top + (targetRect.height - tooltipRect.height) / 2;
+        tooltip.classList.add('position-left');
+        break;
+        
+      case 'right':
+        left = targetRect.right + gap;
+        top = targetRect.top + (targetRect.height - tooltipRect.height) / 2;
+        tooltip.classList.add('position-right');
+        break;
+    }
+    
+    // Keep tooltip in viewport
+    left = Math.max(16, Math.min(left, viewportWidth - tooltipRect.width - 16));
+    top = Math.max(16, Math.min(top, viewportHeight - tooltipRect.height - 16));
+    
+    tooltip.style.left = `${left}px`;
+    tooltip.style.top = `${top}px`;
+  }
+  
+  function positionTooltipCenter(tooltip: HTMLElement) {
+    tooltip.className = 'dap-walkthrough-tooltip visible';
+    tooltip.style.left = '50%';
+    tooltip.style.top = '50%';
+    tooltip.style.transform = 'translate(-50%, -50%)';
+  }
+  
+  function nextStep() {
+    if (currentStepIndex < payload.steps.length - 1) {
+      showStep(currentStepIndex + 1);
+    } else {
+      completeWalkthrough();
+    }
+  }
+  
+  function prevStep() {
+    if (currentStepIndex > 0) {
+      showStep(currentStepIndex - 1);
+    }
+  }
+  
+  function completeWalkthrough() {
+    isActive = false;
+    
+    // Clean up highlights
+    document.querySelectorAll('.dap-walkthrough-highlight').forEach(el => {
+      el.classList.remove('dap-walkthrough-highlight');
+    });
+    
+    // Fade out
+    overlay.style.opacity = '0';
+    tooltip.style.opacity = '0';
+    spotlight.style.opacity = '0';
+    
+    setTimeout(() => {
+      overlay.remove();
+      tooltip.remove();
+      spotlight.remove();
+      
+      // Signal completion
+      if (completionTracker?.onComplete) {
+        console.debug(`[DAP] Completing walkthrough flow: ${id}`);
+        completionTracker.onComplete();
+      }
+    }, 300);
+    
+    document.removeEventListener('keydown', handleKeyboard);
+  }
+  
+  // Event handlers
+  const closeBtn = tooltip.querySelector('.dap-walkthrough-close') as HTMLButtonElement;
+  const prevBtn = tooltip.querySelector('.dap-walkthrough-prev') as HTMLButtonElement;
+  const nextBtn = tooltip.querySelector('.dap-walkthrough-next') as HTMLButtonElement;
+  
+  closeBtn.addEventListener('click', completeWalkthrough);
+  prevBtn.addEventListener('click', prevStep);
+  nextBtn.addEventListener('click', nextStep);
+  
+  // Keyboard navigation
+  document.addEventListener('keydown', handleKeyboard);
+  
+  function handleKeyboard(e: KeyboardEvent) {
+    if (!isActive) return;
+    
+    switch (e.key) {
+      case 'Escape':
+        completeWalkthrough();
+        break;
+      case 'ArrowRight':
+      case ' ':
+        e.preventDefault();
+        nextStep();
+        break;
+      case 'ArrowLeft':
+        e.preventDefault();
+        prevStep();
+        break;
+    }
+  }
+  
+  // Prevent clicks on overlay from closing
+  overlay.addEventListener('click', (e) => {
+    e.stopPropagation();
+  });
+}
+
+function createWalkthroughOverlay(): HTMLElement {
+  const overlay = document.createElement('div');
+  overlay.className = 'dap-walkthrough-overlay';
+  return overlay;
+}
+
+function createSpotlight(): HTMLElement {
+  const spotlight = document.createElement('div');
+  spotlight.className = 'dap-walkthrough-spotlight';
+  return spotlight;
+}
+
+function createTooltip(): HTMLElement {
+  const tooltip = document.createElement('div');
+  tooltip.className = 'dap-walkthrough-tooltip';
+  tooltip.setAttribute('role', 'dialog');
+  tooltip.setAttribute('aria-modal', 'true');
+  
+  tooltip.innerHTML = `
+    <div class="dap-walkthrough-header">
+      <div class="dap-walkthrough-step-indicator">Step 1 of 1</div>
+      <h3 class="dap-walkthrough-title">Step Title</h3>
+      <button class="dap-walkthrough-close" aria-label="Close walkthrough">×</button>
+    </div>
+    <div class="dap-walkthrough-body">
+      <div class="dap-walkthrough-content">Step content goes here</div>
+    </div>
+    <div class="dap-walkthrough-footer">
+      <div class="dap-walkthrough-progress"></div>
+      <div class="dap-walkthrough-nav">
+        <span class="dap-walkthrough-step-count">1 / 1</span>
+        <button class="dap-walkthrough-btn dap-walkthrough-prev">Previous</button>
+        <button class="dap-walkthrough-btn primary dap-walkthrough-next">Next</button>
+      </div>
+    </div>
+  `;
+  
+  return tooltip;
+}
+
+function ensureStyles() {
+  if (!document.getElementById('dap-walkthrough-style')) {
+    const style = document.createElement('style');
+    style.id = 'dap-walkthrough-style';
+    style.textContent = walkthroughCssText;
+    document.head.appendChild(style);
+  }
+}