@cognior/iap-sdk 0.1.0

package/src/experiences/beacon.ts

@@ -0,0 +1,668 @@
+// src/experiences/beacon.ts
+// Beacon experience renderer - creates pulsing alert notifications
+
+import { sanitizeHtml } from "../utils/sanitize";
+import { register } from "./registry";
+import type { BeaconPayload } from "./types";
+import { resolveSelector } from "../utils/selectors";
+
+type BeaconFlow = { id: string; type: "beacon"; payload: BeaconPayload };
+
+interface BeaconState {
+  id: string;
+  element: HTMLElement;
+  targetElement?: HTMLElement;
+  cleanup: (() => void)[];
+  isActive: boolean;
+}
+
+const activeBeacons = new Map<string, BeaconState>();
+
+export function registerBeacon() {
+  register("beacon", renderBeacon);
+}
+
+export async function renderBeacon(flow: BeaconFlow): Promise<void> {
+  const { payload, id } = flow;
+  
+  console.debug("[DAP] Beacon initialized", { id, payload });
+  
+  // Validate required data
+  if (!payload.title && !payload.body) {
+    console.error("[DAP] Beacon missing required content (title or body)");
+    payload._completionTracker?.onComplete?.();
+    return;
+  }
+  
+  // Clean up any existing beacon with same ID
+  if (activeBeacons.has(id)) {
+    cleanupBeacon(id);
+  }
+  
+  // Find target element if selector provided
+  let targetElement: HTMLElement | undefined;
+  if (payload.targetSelector) {
+    const element = resolveSelector(payload.targetSelector);
+    if (element instanceof HTMLElement) {
+      targetElement = element;
+    } else {
+      console.warn(`[DAP] Beacon: Target element not found for selector: ${payload.targetSelector}`);
+    }
+  }
+  
+  // Create beacon element
+  const beaconElement = createBeaconElement(payload, id);
+  
+  const beaconState: BeaconState = {
+    id,
+    element: beaconElement,
+    targetElement,
+    cleanup: [],
+    isActive: false
+  };
+  
+  activeBeacons.set(id, beaconState);
+  
+  // Show beacon
+  showBeacon(beaconState, payload);
+  
+  console.debug("[DAP] Beacon setup complete", { id });
+}
+
+function createBeaconElement(payload: BeaconPayload, id: string): HTMLElement {
+  const beacon = document.createElement('div');
+  beacon.className = 'dap-beacon';
+  beacon.id = `dap-beacon-${id}`;
+  beacon.setAttribute('role', 'alert');
+  beacon.setAttribute('aria-live', 'assertive');
+  
+  // Position and base styling
+  const position = payload.position || 'top-right';
+  const positionStyles = getPositionStyles(position);
+  
+  Object.assign(beacon.style, {
+    position: 'fixed',
+    zIndex: '10000',
+    padding: '12px 16px',
+    borderRadius: '16px',
+    background: 'rgba(255, 255, 255, 0.95)',
+    border: '2px solid #3b82f6',
+    boxShadow: '0 8px 32px rgba(59, 130, 246, 0.15), 0 4px 16px rgba(0, 0, 0, 0.08)',
+    backdropFilter: 'blur(12px)',
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    fontSize: '13px',
+    lineHeight: '1.4',
+    color: '#1e40af',
+    maxWidth: '280px',
+    minWidth: '200px',
+    opacity: '0',
+    transform: 'translateY(-10px) scale(0.95)',
+    transition: 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)',
+    cursor: 'pointer',
+    pointerEvents: 'auto',
+    userSelect: 'none',
+    ...positionStyles
+  });
+  
+  // Add subtle pulsing animation
+  beacon.style.animation = 'dap-beacon-pulse 2s ease-in-out infinite';
+  
+  // Add beacon pulse animation styles if not already present
+  if (!document.querySelector('#dap-beacon-pulse-styles')) {
+    const pulseStyles = document.createElement('style');
+    pulseStyles.id = 'dap-beacon-pulse-styles';
+    pulseStyles.textContent = `
+      @keyframes dap-beacon-pulse {
+        0%, 100% { 
+          box-shadow: 0 8px 32px rgba(59, 130, 246, 0.15), 0 4px 16px rgba(0, 0, 0, 0.08), 0 0 0 0 rgba(59, 130, 246, 0.4);
+        }
+        50% { 
+          box-shadow: 0 8px 32px rgba(59, 130, 246, 0.25), 0 4px 16px rgba(0, 0, 0, 0.12), 0 0 0 8px rgba(59, 130, 246, 0.1);
+        }
+      }
+      
+      .dap-beacon:hover {
+        transform: translateY(-2px) scale(1.02) !important;
+        box-shadow: 0 12px 40px rgba(59, 130, 246, 0.25), 0 6px 20px rgba(0, 0, 0, 0.12) !important;
+        animation: none !important;
+      }
+    `;
+    document.head.appendChild(pulseStyles);
+  }
+  
+  // Add icon if specified
+  if (payload.icon) {
+    const icon = document.createElement('span');
+    icon.style.cssText = `
+      display: inline-block;
+      margin-right: 8px;
+      font-size: 18px;
+      vertical-align: middle;
+    `;
+    icon.textContent = payload.icon;
+    beacon.appendChild(icon);
+  }
+  
+  // Add title if provided
+  if (payload.title) {
+    const title = document.createElement('div');
+    title.style.cssText = `
+      font-weight: 600;
+      font-size: 15px;
+      color: #78350f;
+      margin-bottom: ${payload.body ? '6px' : '0'};
+      line-height: 1.3;
+    `;
+    title.textContent = payload.title;
+    beacon.appendChild(title);
+  }
+  
+  // Add body content if provided
+  if (payload.body) {
+    const body = document.createElement('div');
+    body.style.cssText = `
+      color: #a16207;
+      line-height: 1.4;
+      font-size: 13px;
+    `;
+    body.innerHTML = sanitizeHtml(payload.body);
+    beacon.appendChild(body);
+  }
+  
+  // Add close button
+  const closeButton = document.createElement('button');
+  closeButton.style.cssText = `
+    position: absolute;
+    top: 6px;
+    right: 6px;
+    background: rgba(59, 130, 246, 0.1);
+    border: none;
+    font-size: 14px;
+    color: #3b82f6;
+    cursor: pointer;
+    padding: 4px 6px;
+    border-radius: 8px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: all 0.15s ease;
+    font-weight: 500;
+    width: 24px;
+    height: 24px;
+  `;
+  closeButton.innerHTML = '×';
+  closeButton.title = 'Close beacon';
+  closeButton.setAttribute('aria-label', 'Close beacon');
+  
+  closeButton.addEventListener('mouseenter', () => {
+    closeButton.style.backgroundColor = 'rgba(59, 130, 246, 0.2)';
+    closeButton.style.transform = 'scale(1.1)';
+  });
+  
+  closeButton.addEventListener('mouseleave', () => {
+    closeButton.style.backgroundColor = 'rgba(59, 130, 246, 0.1)';
+    closeButton.style.transform = 'scale(1)';
+  });
+  
+  closeButton.addEventListener('click', (e) => {
+    e.stopPropagation();
+    dismissBeacon(id);
+  });
+  
+  beacon.appendChild(closeButton);
+  
+  // Store payload for later access
+  (beacon as any).__beaconPayload = payload;
+  
+  return beacon;
+}
+
+function getPositionStyles(position: string) {
+  const margin = '20px';
+  
+  switch (position) {
+    case 'top-left':
+      return { top: margin, left: margin };
+    case 'top-center':
+      return { top: margin, left: '50%', transform: 'translateX(-50%) translateY(-20px) scale(0.9)' };
+    case 'top-right':
+    default:
+      return { top: margin, right: margin };
+    case 'bottom-left':
+      return { bottom: margin, left: margin };
+    case 'bottom-center':
+      return { bottom: margin, left: '50%', transform: 'translateX(-50%) translateY(20px) scale(0.9)' };
+    case 'bottom-right':
+      return { bottom: margin, right: margin };
+    case 'center':
+      return { 
+        top: '50%', 
+        left: '50%', 
+        transform: 'translate(-50%, -50%) translateY(-20px) scale(0.9)'
+      };
+  }
+}
+
+function showBeacon(state: BeaconState, payload: BeaconPayload): void {
+  if (state.isActive) return;
+  
+  state.isActive = true;
+  
+  console.debug("[DAP] Beacon shown", { id: state.id, hasTarget: !!state.targetElement });
+  
+  // Add to DOM first
+  document.body.appendChild(state.element);
+  
+  // Wait for DOM to settle, then position
+  requestAnimationFrame(() => {
+    // Always position beacon relative to target element if available
+    if (state.targetElement) {
+      // Use default position if not specified
+      const position = payload.position ? parsePosition(payload.position) : { x: 'right', y: 'center' };
+      console.debug("[DAP] Positioning beacon with position:", position);
+      if (position) {
+        positionBeaconRelativeToElement(state.element, state.targetElement, position);
+      }
+    } else {
+      // Fallback positioning without target element
+      console.debug("[DAP] No target element, using fallback positioning");
+      const positionStyles = getPositionStyles(payload.position || 'top-right');
+      Object.assign(state.element.style, positionStyles);
+    }
+    
+    // Apply beacon pulsing animation
+    applyBeaconAnimation(state.element, payload.beaconStyles);
+    
+    // Show with smooth entrance animation after positioning
+    setTimeout(() => {
+      state.element.style.opacity = '1';
+      state.element.style.transform = 'scale(1)';
+      console.debug("[DAP] Beacon animation complete");
+    }, 50);
+  });
+  
+  // Setup click handler for main content (not close button)
+  const clickHandler = (e: Event) => {
+    const target = e.target as HTMLElement;
+    if (!target.closest('button')) {
+      console.debug("[DAP] Beacon clicked", { id: state.id });
+      
+      // Execute custom action if defined
+      if (payload.action) {
+        console.debug("[DAP] Executing beacon action", { action: payload.action });
+        // Custom actions can be handled by completion tracker
+      }
+      
+      dismissBeacon(state.id);
+    }
+  };
+  
+  state.element.addEventListener('click', clickHandler);
+  state.cleanup.push(() => state.element.removeEventListener('click', clickHandler));
+  
+  // Setup global event handlers
+  setupGlobalEventHandlers(state, payload);
+  
+  // Setup position observer for target element
+  if (state.targetElement) {
+    setupPositionObserver(state, payload);
+  }
+  
+  // Auto-dismiss if specified
+  if (payload.autoDismiss && payload.autoDismiss > 0) {
+    setTimeout(() => {
+      dismissBeacon(state.id);
+    }, payload.autoDismiss * 1000);
+  }
+}
+
+function applyBeaconAnimation(element: HTMLElement, beaconStyles?: any): void {
+  const styles = {
+    enabled: true,
+    color1: '#f59e0b',
+    color2: '#eab308',
+    duration: '2s',
+    padding: '8px',
+    borderWidth: '3px',
+    borderRadius: '16px',
+    shadowSize: '20px',
+    ...beaconStyles
+  };
+  
+  if (!styles.enabled) return;
+  
+  const animationId = `beacon-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  
+  const style = document.createElement('style');
+  style.dataset.beaconAnimation = animationId;
+  style.textContent = `
+    .dap-beacon[data-beacon-id="${animationId}"]::before {
+      content: '';
+      position: absolute;
+      top: -${styles.padding};
+      left: -${styles.padding};
+      right: -${styles.padding};
+      bottom: -${styles.padding};
+      border: ${styles.borderWidth} solid ${styles.color1};
+      border-radius: ${styles.borderRadius};
+      animation: beaconPulse-${animationId} ${styles.duration} ease-in-out infinite;
+      pointer-events: none;
+      z-index: -1;
+    }
+    
+    @keyframes beaconPulse-${animationId} {
+      0% {
+        border-color: ${styles.color1};
+        box-shadow: 0 0 0 0 ${styles.color1}40, 0 0 ${styles.shadowSize} ${styles.color1}30;
+        transform: scale(1);
+      }
+      50% {
+        border-color: ${styles.color2};
+        box-shadow: 0 0 0 10px ${styles.color2}20, 0 0 ${styles.shadowSize} ${styles.color2}40;
+        transform: scale(1.05);
+      }
+      100% {
+        border-color: ${styles.color1};
+        box-shadow: 0 0 0 0 ${styles.color1}40, 0 0 ${styles.shadowSize} ${styles.color1}30;
+        transform: scale(1);
+      }
+    }
+  `;
+  
+  document.head.appendChild(style);
+  element.setAttribute('data-beacon-id', animationId);
+  
+  // Cleanup function
+  const cleanup = () => {
+    if (style.parentNode) {
+      style.parentNode.removeChild(style);
+    }
+  };
+  
+  // Store cleanup in beacon state if available
+  const beaconId = element.id.replace('dap-beacon-', '');
+  const state = activeBeacons.get(beaconId);
+  if (state) {
+    state.cleanup.push(cleanup);
+  }
+}
+
+function setupGlobalEventHandlers(state: BeaconState, payload: BeaconPayload): void {
+  // ESC key handler
+  const keyHandler = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      dismissBeacon(state.id);
+    }
+  };
+  
+  // Navigation handler
+  const navigationHandler = () => {
+    dismissBeacon(state.id);
+  };
+  
+  document.addEventListener('keydown', keyHandler);
+  window.addEventListener('beforeunload', navigationHandler);
+  window.addEventListener('popstate', navigationHandler);
+  
+  state.cleanup.push(() => {
+    document.removeEventListener('keydown', keyHandler);
+    window.removeEventListener('beforeunload', navigationHandler);
+    window.removeEventListener('popstate', navigationHandler);
+  });
+}
+
+function dismissBeacon(id: string): void {
+  const state = activeBeacons.get(id);
+  if (!state || !state.isActive) return;
+  
+  state.isActive = false;
+  
+  console.debug("[DAP] Beacon dismissed", { id });
+  
+  // Animate out
+  state.element.style.opacity = '0';
+  state.element.style.transform = state.element.style.transform.replace(/translateY\([^)]+\)/, 'translateY(-20px)').replace(/scale\([^)]+\)/, 'scale(0.9)');
+  
+  // Complete the step
+  const beaconElement = state.element;
+  const payloadData = (beaconElement as any).__beaconPayload;
+  if (payloadData?._completionTracker?.onComplete) {
+    payloadData._completionTracker.onComplete();
+  }
+  
+  // Remove from DOM after animation
+  setTimeout(() => {
+    if (state.element.parentNode) {
+      state.element.parentNode.removeChild(state.element);
+    }
+    cleanupBeacon(id);
+  }, 300);
+}
+
+function cleanupBeacon(id: string): void {
+  console.debug("[DAP] Beacon destroyed", { id });
+  
+  const state = activeBeacons.get(id);
+  if (!state) return;
+  
+  // Run all cleanup functions
+  state.cleanup.forEach(cleanup => {
+    try {
+      cleanup();
+    } catch (error) {
+      console.warn("[DAP] Error during beacon cleanup:", error);
+    }
+  });
+  
+  // Remove from DOM if still attached
+  if (state.element && state.element.parentNode) {
+    state.element.parentNode.removeChild(state.element);
+  }
+  
+  // Signal completion
+  // Note: We don't call completion tracker here since dismiss already handles it
+  
+  // Remove from active beacons
+  activeBeacons.delete(id);
+}
+
+function parsePosition(position: string | { x: string; y: string }): { x: string; y: string } | null {
+  // If already an object, return it
+  if (typeof position === 'object' && position.x && position.y) {
+    return { x: position.x, y: position.y };
+  }
+  
+  // Parse string position into x,y coordinates
+  if (typeof position === 'string') {
+    switch (position) {
+      case 'top-left':
+        return { x: 'left', y: 'top' };
+      case 'top-center':
+        return { x: 'center', y: 'top' };
+      case 'top-right':
+        return { x: 'right', y: 'top' };
+      case 'bottom-left':
+        return { x: 'left', y: 'bottom' };
+      case 'bottom-center':
+        return { x: 'center', y: 'bottom' };
+      case 'bottom-right':
+        return { x: 'right', y: 'bottom' };
+      case 'center':
+        return { x: 'center', y: 'center' };
+      default:
+        return { x: 'center', y: 'center' };
+    }
+  }
+  
+  return null;
+}
+
+function positionBeaconRelativeToElement(
+  beaconElement: HTMLElement, 
+  targetElement: HTMLElement, 
+  position: { x: string; y: string }
+): void {
+  console.debug("[DAP] Starting beacon positioning", { 
+    targetElement: targetElement.tagName, 
+    targetSelector: targetElement.id || targetElement.className,
+    position 
+  });
+  
+  const targetRect = targetElement.getBoundingClientRect();
+  console.debug("[DAP] Target element bounds:", targetRect);
+  
+  // Ensure beacon is properly styled and in DOM for measurements
+  beaconElement.style.position = 'fixed';
+  beaconElement.style.display = 'block';
+  beaconElement.style.visibility = 'visible';
+  beaconElement.style.opacity = '0'; // Hidden but measurable
+  
+  if (!beaconElement.parentNode) {
+    document.body.appendChild(beaconElement);
+  }
+  
+  // Force a layout to get accurate measurements
+  beaconElement.offsetHeight; // Trigger layout
+  const beaconRect = beaconElement.getBoundingClientRect();
+  console.debug("[DAP] Beacon element bounds:", beaconRect);
+  
+  const spacing = 30; // Even more generous spacing
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  
+  let left = 0;
+  let top = 0;
+  let placement = 'right'; // Default
+  
+  // Try positioning to the right first (best for form elements)
+  left = targetRect.right + spacing;
+  top = targetRect.top + (targetRect.height - beaconRect.height) / 2;
+  
+  // Check if right position fits
+  if (left + beaconRect.width > viewportWidth - 10) {
+    // Try left position
+    left = targetRect.left - beaconRect.width - spacing;
+    placement = 'left';
+    
+    // If left doesn't fit either, try bottom
+    if (left < 10) {
+      left = targetRect.left + (targetRect.width - beaconRect.width) / 2;
+      top = targetRect.bottom + spacing;
+      placement = 'bottom';
+      
+      // If bottom doesn't fit, try top
+      if (top + beaconRect.height > viewportHeight - 10) {
+        top = targetRect.top - beaconRect.height - spacing;
+        placement = 'top';
+        
+        // If top doesn't fit, force right with viewport constraints
+        if (top < 10) {
+          left = Math.min(targetRect.right + spacing, viewportWidth - beaconRect.width - 10);
+          top = Math.max(10, Math.min(targetRect.top, viewportHeight - beaconRect.height - 10));
+          placement = 'right-constrained';
+        }
+      }
+    }
+  }
+  
+  // Apply final constraints
+  left = Math.max(10, Math.min(left, viewportWidth - beaconRect.width - 10));
+  top = Math.max(10, Math.min(top, viewportHeight - beaconRect.height - 10));
+  
+  console.debug("[DAP] Final beacon position:", { 
+    left, 
+    top, 
+    placement,
+    beaconWidth: beaconRect.width,
+    beaconHeight: beaconRect.height,
+    viewportWidth,
+    viewportHeight
+  });
+  
+  // Apply the position
+  beaconElement.style.left = `${Math.round(left)}px`;
+  beaconElement.style.top = `${Math.round(top)}px`;
+  beaconElement.style.transform = 'none';
+  beaconElement.style.zIndex = '10000';
+  
+  // Store placement info
+  beaconElement.setAttribute('data-placement', placement);
+  
+  console.debug("[DAP] Beacon positioned successfully");
+}
+
+function setupPositionObserver(state: BeaconState, payload: BeaconPayload): void {
+  if (!state.targetElement) return;
+  
+  console.debug("[DAP] Setting up position observer for beacon", { id: state.id });
+  
+  // More frequent updates for better responsiveness
+  let updateTimeout: number | null = null;
+  
+  const updatePosition = () => {
+    if (updateTimeout) clearTimeout(updateTimeout);
+    updateTimeout = setTimeout(() => {
+      if (state.targetElement && state.isActive) {
+        const position = payload.position ? parsePosition(payload.position) : { x: 'right', y: 'center' };
+        console.debug("[DAP] Updating beacon position on scroll");
+        if (position) {
+          positionBeaconRelativeToElement(state.element, state.targetElement, position);
+        }
+      }
+    }, 8) as any; // More frequent updates for smoother scrolling
+  };
+  
+  // Setup intersection observer to detect if target becomes visible/hidden
+  const intersectionObserver = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        state.element.style.display = 'block';
+        updatePosition();
+      } else {
+        state.element.style.display = 'none';
+      }
+    });
+  }, { threshold: 0.1 });
+  
+  intersectionObserver.observe(state.targetElement);
+  
+  // Add multiple scroll listeners for better coverage
+  const handleScroll = () => updatePosition();
+  const handleResize = () => updatePosition();
+  
+  // Listen to different scroll contexts
+  window.addEventListener('scroll', handleScroll, { passive: true });
+  window.addEventListener('resize', handleResize, { passive: true });
+  document.addEventListener('scroll', handleScroll, { passive: true, capture: true });
+  
+  // Also listen for any scroll on scrollable containers
+  let scrollableParent = state.targetElement.parentElement;
+  const scrollListeners: Array<{ element: Element; listener: () => void }> = [];
+  
+  while (scrollableParent) {
+    const style = window.getComputedStyle(scrollableParent);
+    if (style.overflow === 'auto' || style.overflow === 'scroll' || 
+        style.overflowY === 'auto' || style.overflowY === 'scroll') {
+      scrollableParent.addEventListener('scroll', handleScroll, { passive: true });
+      scrollListeners.push({ element: scrollableParent, listener: handleScroll });
+    }
+    scrollableParent = scrollableParent.parentElement;
+  }
+  
+  state.cleanup.push(() => {
+    intersectionObserver.disconnect();
+    window.removeEventListener('scroll', handleScroll);
+    window.removeEventListener('resize', handleResize);
+    document.removeEventListener('scroll', handleScroll, true);
+    
+    // Clean up scrollable parent listeners
+    scrollListeners.forEach(({ element, listener }) => {
+      element.removeEventListener('scroll', listener);
+    });
+    
+    if (updateTimeout) clearTimeout(updateTimeout);
+  });
+  
+  console.debug("[DAP] Position observer setup complete");
+}