@cognior/iap-sdk 0.1.0

package/src/experiences/popover.ts

@@ -0,0 +1,652 @@
+import { sanitizeHtml } from "../utils/sanitize";
+import { register } from "./registry";
+import type { PopoverPayload, PopoverButton } from "./types";
+import { resolveSelector } from "../utils/selectors";
+
+type PopoverFlow = { id: string; type: "popover"; payload: PopoverPayload };
+
+interface PopoverState {
+  id: string;
+  element: HTMLElement;
+  targetElement: HTMLElement;
+  observer: MutationObserver | null;
+  cleanup: (() => void)[];
+  isActive: boolean;
+}
+
+const activePopovers = new Map<string, PopoverState>();
+
+export function registerPopover() { 
+  register("popover", renderPopover);
+}
+
+export async function renderPopover(flow: PopoverFlow): Promise<void> {
+  const { payload, id } = flow;
+  
+  console.debug("[DAP] Popover initialized", { id, payload });
+  console.debug("[DAP] Popover targetSelector:", payload.targetSelector);
+  console.debug("[DAP] Popover trigger:", payload.trigger);
+  console.debug("[DAP] Popover body:", payload.body);
+  console.debug("[DAP] Popover bodyBlocks:", payload.bodyBlocks);
+  
+  if (!payload.targetSelector) {
+    console.error("[DAP] Popover missing required elementSelector");
+    payload._completionTracker?.onComplete?.();
+    return;
+  }
+  
+  if (!payload.body && !payload.bodyBlocks) {
+    console.error("[DAP] Popover missing required content");
+    payload._completionTracker?.onComplete?.();
+    return;
+  }
+  
+  const targetSelector = payload.targetSelector;
+  const trigger = payload.trigger || "click";
+  
+  console.debug("[DAP] Popover looking for target element:", targetSelector);
+  
+  if (activePopovers.has(id)) {
+    cleanupPopover(id);
+  }
+  
+  const targetElement = await waitForTargetElement(targetSelector);
+  
+  if (!targetElement) {
+    console.warn("[DAP] Popover target not found:", targetSelector);
+    console.debug("[DAP] Available elements with IDs:", Array.from(document.querySelectorAll('[id]')).map(el => el.id));
+    console.debug("[DAP] Available elements with classes:", Array.from(document.querySelectorAll('[class]')).slice(0, 10).map(el => el.className));
+    payload._completionTracker?.onComplete?.();
+    return;
+  }
+  
+  console.debug("[DAP] Popover anchor resolved successfully", { targetSelector, targetElement });
+  
+  const popoverElement = createPopoverElement(payload, id);
+  console.debug("[DAP] Popover element created:", popoverElement);
+  
+  const popoverState: PopoverState = {
+    id,
+    element: popoverElement,
+    targetElement,
+    observer: null,
+    cleanup: [],
+    isActive: false
+  };
+  
+  activePopovers.set(id, popoverState);
+  
+  setupTriggerHandling(popoverState, trigger, payload);
+  setupTargetObservation(popoverState);
+  
+  console.debug("[DAP] Popover setup complete", { id, trigger });
+}
+
+async function waitForTargetElement(
+  selector: string, 
+  timeout = 5000
+): Promise<HTMLElement | null> {
+  
+  const existing = resolveSelector(selector);
+  if (existing) {
+    return existing as HTMLElement;
+  }
+  
+  return new Promise((resolve) => {
+    let timeoutId: number;
+    let observer: MutationObserver;
+    
+    const cleanup = () => {
+      if (timeoutId) clearTimeout(timeoutId);
+      if (observer) observer.disconnect();
+    };
+    
+    timeoutId = setTimeout(() => {
+      cleanup();
+      resolve(null);
+    }, timeout);
+    
+    observer = new MutationObserver(() => {
+      const element = resolveSelector(selector);
+      if (element) {
+        cleanup();
+        resolve(element as HTMLElement);
+      }
+    });
+    
+    observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: false
+    });
+  });
+}
+
+function createPopoverElement(payload: PopoverPayload, id: string): HTMLElement {
+  const popover = document.createElement('div');
+  popover.className = 'dap-popover';
+  popover.id = `dap-popover-${id}`;
+  popover.setAttribute('role', 'dialog');
+  popover.setAttribute('aria-live', 'polite');
+  
+  Object.assign(popover.style, {
+    position: 'absolute',
+    zIndex: '9999',
+    background: '#f0f9ff',
+    border: '1px solid #bae6fd',
+    borderRadius: '12px',
+    boxShadow: '0 8px 32px rgba(59, 130, 246, 0.12), 0 4px 16px rgba(0, 0, 0, 0.08)',
+    padding: '18px',
+    maxWidth: '320px',
+    minWidth: '200px',
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+    fontSize: '14px',
+    lineHeight: '1.5',
+    color: '#1e293b',
+    opacity: '0',
+    transform: 'scale(0.95)',
+    transition: 'all 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
+    pointerEvents: 'none'
+  });
+  
+  if (payload.title) {
+    const title = document.createElement('h4');
+    title.style.cssText = `
+      margin: 0 0 10px 0; 
+      font-size: 16px; 
+      font-weight: 600; 
+      color: #0f172a;
+      line-height: 1.25;
+      text-shadow: 0 1px 2px rgba(255, 255, 255, 0.5);
+    `;
+    title.textContent = payload.title;
+    popover.appendChild(title);
+  }
+  
+  if (payload.body) {
+    const body = document.createElement('div');
+    body.style.cssText = `
+      color: #475569; 
+      line-height: 1.6;
+      margin: 0;
+      text-shadow: 0 1px 1px rgba(255, 255, 255, 0.3);
+    `;
+    body.innerHTML = sanitizeHtml(payload.body);
+    popover.appendChild(body);
+  }
+  
+  const ctaContainer = createCTAButtons(payload, id);
+  if (ctaContainer) {
+    popover.appendChild(ctaContainer);
+  }
+  
+  if (payload.showArrow !== false) {
+    const arrow = createPopoverArrow();
+    popover.appendChild(arrow);
+  }
+  
+  return popover;
+}
+
+function createCTAButtons(payload: PopoverPayload, id: string): HTMLElement | null {
+  const hasButtons = payload.bodyBlocks?.some(block => block.kind === 'button');
+  
+  if (!hasButtons) return null;
+  
+  const container = document.createElement('div');
+  container.style.cssText = `
+    margin-top: 12px;
+    display: flex;
+    gap: 8px;
+    justify-content: flex-end;
+  `;
+  
+  payload.bodyBlocks?.forEach(block => {
+    if (block.kind === 'button') {
+      const buttonBlock = block as PopoverButton;
+      const button = document.createElement('button');
+      button.style.cssText = `
+        padding: 8px 16px;
+        border: 1px solid ${buttonBlock.variant === 'primary' ? '#3b82f6' : '#cbd5e1'};
+        border-radius: 8px;
+        background: ${buttonBlock.variant === 'primary' ? '#3b82f6' : '#ffffff'};
+        color: ${buttonBlock.variant === 'primary' ? '#ffffff' : '#1e293b'};
+        font-size: 13px;
+        font-weight: 500;
+        cursor: pointer;
+        transition: all 0.2s ease;
+        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+      `;
+      
+      button.textContent = buttonBlock.label;
+      
+      button.addEventListener('click', () => {
+        console.debug("[DAP] Popover CTA clicked", { id, action: buttonBlock.action });
+        
+        if (buttonBlock.action === 'advance') {
+          payload._completionTracker?.onStepAdvance?.(payload.stepId || id);
+        } else if (buttonBlock.action === 'dismiss') {
+          dismissPopover(id);
+        }
+        
+        payload._completionTracker?.onComplete?.();
+      });
+      
+      button.addEventListener('mouseenter', () => {
+        if (buttonBlock.variant === 'primary') {
+          button.style.background = '#2563eb';
+          button.style.transform = 'translateY(-1px)';
+        } else {
+          button.style.background = '#f1f5f9';
+          button.style.transform = 'translateY(-1px)';
+        }
+      });
+      
+      button.addEventListener('mouseleave', () => {
+        button.style.background = buttonBlock.variant === 'primary' ? '#3b82f6' : '#ffffff';
+        button.style.transform = 'translateY(0)';
+      });
+      
+      container.appendChild(button);
+    }
+  });
+  
+  return container.children.length > 0 ? container : null;
+}
+
+function createPopoverArrow(): HTMLElement {
+  const arrow = document.createElement('div');
+  arrow.className = 'dap-popover-arrow';
+  arrow.style.cssText = `
+    position: absolute;
+    width: 10px;
+    height: 10px;
+    background: #f0f9ff;
+    border: 1px solid #bae6fd;
+    transform: rotate(45deg);
+    z-index: -1;
+  `;
+  return arrow;
+}
+
+function setupTriggerHandling(
+  state: PopoverState, 
+  trigger: string, 
+  payload: PopoverPayload
+): void {
+  
+  const { targetElement, element } = state;
+  
+  // Normalize trigger names
+  const normalizedTrigger = trigger === 'on click' ? 'click' : 
+                           trigger === 'on hover' ? 'hover' :
+                           trigger === 'on focus' ? 'focus' :
+                           trigger === 'on page load' ? 'on page load' :
+                           trigger;
+  
+  console.debug("[DAP] Popover setting up trigger:", { originalTrigger: trigger, normalizedTrigger, targetElement });
+  
+  switch (normalizedTrigger) {
+    case 'click':
+      const clickHandler = (e: Event) => {
+        console.debug("[DAP] Popover click triggered", e);
+        e.preventDefault();
+        e.stopPropagation();
+        showPopover(state, payload);
+      };
+      targetElement.addEventListener('click', clickHandler);
+      state.cleanup.push(() => targetElement.removeEventListener('click', clickHandler));
+      console.debug("[DAP] Popover click listener attached");
+      break;
+      
+    case 'hover':
+      const showHandler = () => {
+        console.debug("[DAP] Popover hover show triggered");
+        showPopover(state, payload);
+      };
+      const hideHandler = () => {
+        console.debug("[DAP] Popover hover hide triggered");
+        hidePopover(state, payload);
+      };
+      
+      targetElement.addEventListener('mouseenter', showHandler);
+      targetElement.addEventListener('mouseleave', hideHandler);
+      element.addEventListener('mouseenter', showHandler);
+      element.addEventListener('mouseleave', hideHandler);
+      
+      state.cleanup.push(() => {
+        targetElement.removeEventListener('mouseenter', showHandler);
+        targetElement.removeEventListener('mouseleave', hideHandler);
+        element.removeEventListener('mouseenter', showHandler);
+        element.removeEventListener('mouseleave', hideHandler);
+      });
+      console.debug("[DAP] Popover hover listeners attached");
+      break;
+      
+    case 'focus':
+      const focusHandler = () => {
+        console.debug("[DAP] Popover focus triggered");
+        showPopover(state, payload);
+      };
+      const blurHandler = () => {
+        console.debug("[DAP] Popover blur triggered");
+        hidePopover(state, payload);
+      };
+      
+      targetElement.addEventListener('focus', focusHandler);
+      targetElement.addEventListener('blur', blurHandler);
+      
+      state.cleanup.push(() => {
+        targetElement.removeEventListener('focus', focusHandler);
+        targetElement.removeEventListener('blur', blurHandler);
+      });
+      console.debug("[DAP] Popover focus listeners attached");
+      break;
+      
+    case 'on page load':
+    default:
+      setTimeout(() => showPopover(state, payload), 100);
+      break;
+  }
+}
+
+function setupTargetObservation(state: PopoverState): void {
+  const observer = new MutationObserver(() => {
+    const isStillConnected = state.targetElement.isConnected;
+    
+    if (!isStillConnected) {
+      console.debug("[DAP] Popover target element disappeared", { id: state.id });
+      cleanupPopover(state.id);
+    }
+  });
+  
+  observer.observe(document.documentElement, {
+    childList: true,
+    subtree: true
+  });
+  
+  state.observer = observer;
+  state.cleanup.push(() => observer.disconnect());
+}
+
+function showPopover(state: PopoverState, payload: PopoverPayload): void {
+  console.debug("[DAP] showPopover called", { id: state.id, isActive: state.isActive });
+  
+  if (state.isActive) {
+    console.debug("[DAP] Popover already active, skipping");
+    return;
+  }
+  
+  state.isActive = true;
+  
+  console.debug("[DAP] Popover shown", { id: state.id });
+  
+  document.body.appendChild(state.element);
+  console.debug("[DAP] Popover element appended to body");
+  
+  positionPopover(state, payload.placement || "bottom", payload.showArrow !== false);
+  console.debug("[DAP] Popover positioned");
+  
+  setTimeout(() => {
+    state.element.style.pointerEvents = 'auto';
+    state.element.style.opacity = '1';
+    state.element.style.transform = 'scale(1)';
+    console.debug("[DAP] Popover animation started");
+  }, 10);
+  
+  setupGlobalEventHandlers(state, payload);
+  
+  if (hasButtons(payload)) {
+    state.element.setAttribute('tabindex', '-1');
+    state.element.focus();
+    trapFocus(state.element);
+  }
+  
+  console.debug("[DAP] Popover show complete");
+}
+
+function hidePopover(state: PopoverState, payload: PopoverPayload): void {
+  if (!state.isActive) return;
+  
+  state.isActive = false;
+  
+  console.debug("[DAP] Popover dismissed", { id: state.id });
+  
+  state.element.style.opacity = '0';
+  state.element.style.transform = 'scale(0.95)';
+  state.element.style.pointerEvents = 'none';
+  
+  setTimeout(() => {
+    if (state.element.parentNode) {
+      state.element.parentNode.removeChild(state.element);
+    }
+  }, 150);
+  
+  payload._completionTracker?.onComplete?.();
+}
+
+function dismissPopover(id: string): void {
+  const state = activePopovers.get(id);
+  if (state) {
+    hidePopover(state, {} as PopoverPayload);
+  }
+}
+
+function positionPopover(state: PopoverState, placement: string, showArrow: boolean): void {
+  const { element, targetElement } = state;
+  const targetRect = targetElement.getBoundingClientRect();
+  const popoverRect = element.getBoundingClientRect();
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const scrollX = window.scrollX;
+  const scrollY = window.scrollY;
+  
+  const spacing = 8;
+  const viewportPadding = 16;
+  
+  let top: number;
+  let left: number;
+  let actualPlacement = placement;
+  
+  const positions = {
+    top: {
+      top: targetRect.top + scrollY - popoverRect.height - spacing,
+      left: targetRect.left + scrollX + (targetRect.width - popoverRect.width) / 2
+    },
+    bottom: {
+      top: targetRect.bottom + scrollY + spacing,
+      left: targetRect.left + scrollX + (targetRect.width - popoverRect.width) / 2
+    },
+    left: {
+      top: targetRect.top + scrollY + (targetRect.height - popoverRect.height) / 2,
+      left: targetRect.left + scrollX - popoverRect.width - spacing
+    },
+    right: {
+      top: targetRect.top + scrollY + (targetRect.height - popoverRect.height) / 2,
+      left: targetRect.right + scrollX + spacing
+    }
+  };
+  
+  const preferred = positions[placement as keyof typeof positions];
+  if (!preferred || !fitsInViewport(preferred, popoverRect, viewportPadding)) {
+    actualPlacement = findBestPlacement(positions, popoverRect, viewportPadding) || placement;
+  }
+  
+  const finalPosition = positions[actualPlacement as keyof typeof positions] || positions.bottom;
+  top = finalPosition.top;
+  left = finalPosition.left;
+  
+  left = Math.max(viewportPadding, Math.min(left, viewportWidth - popoverRect.width - viewportPadding));
+  top = Math.max(viewportPadding, Math.min(top, viewportHeight - popoverRect.height - viewportPadding));
+  
+  element.style.top = `${top}px`;
+  element.style.left = `${left}px`;
+  
+  if (showArrow) {
+    positionArrow(element, targetRect, actualPlacement, { top, left }, scrollX, scrollY);
+  }
+}
+
+function fitsInViewport(
+  position: { top: number; left: number }, 
+  rect: DOMRect, 
+  padding: number
+): boolean {
+  return position.top >= padding &&
+         position.left >= padding &&
+         position.top + rect.height <= window.innerHeight - padding &&
+         position.left + rect.width <= window.innerWidth - padding;
+}
+
+function findBestPlacement(
+  positions: Record<string, { top: number; left: number }>,
+  rect: DOMRect,
+  padding: number
+): string | null {
+  
+  const placements = ['bottom', 'top', 'right', 'left'];
+  
+  for (const placement of placements) {
+    const pos = positions[placement];
+    if (pos && fitsInViewport(pos, rect, padding)) {
+      return placement;
+    }
+  }
+  
+  return null;
+}
+
+function positionArrow(
+  popover: HTMLElement,
+  targetRect: DOMRect,
+  placement: string,
+  popoverPos: { top: number; left: number },
+  scrollX: number,
+  scrollY: number
+): void {
+  
+  const arrow = popover.querySelector('.dap-popover-arrow') as HTMLElement;
+  if (!arrow) return;
+  
+  const arrowSize = 8;
+  const targetCenterX = targetRect.left + scrollX + targetRect.width / 2;
+  const targetCenterY = targetRect.top + scrollY + targetRect.height / 2;
+  
+  switch (placement) {
+    case 'top':
+      arrow.style.top = `calc(100% - 1px)`;
+      arrow.style.left = `${Math.max(12, Math.min(targetCenterX - popoverPos.left - arrowSize/2, popover.offsetWidth - 20))}px`;
+      arrow.style.borderBottomColor = 'transparent';
+      arrow.style.borderRightColor = 'transparent';
+      break;
+      
+    case 'bottom':
+      arrow.style.top = `-${arrowSize/2}px`;
+      arrow.style.left = `${Math.max(12, Math.min(targetCenterX - popoverPos.left - arrowSize/2, popover.offsetWidth - 20))}px`;
+      arrow.style.borderTopColor = 'transparent';
+      arrow.style.borderLeftColor = 'transparent';
+      break;
+      
+    case 'left':
+      arrow.style.left = `calc(100% - 1px)`;
+      arrow.style.top = `${Math.max(12, Math.min(targetCenterY - popoverPos.top - arrowSize/2, popover.offsetHeight - 20))}px`;
+      arrow.style.borderRightColor = 'transparent';
+      arrow.style.borderBottomColor = 'transparent';
+      break;
+      
+    case 'right':
+      arrow.style.left = `-${arrowSize/2}px`;
+      arrow.style.top = `${Math.max(12, Math.min(targetCenterY - popoverPos.top - arrowSize/2, popover.offsetHeight - 20))}px`;
+      arrow.style.borderLeftColor = 'transparent';
+      arrow.style.borderTopColor = 'transparent';
+      break;
+  }
+}
+
+function setupGlobalEventHandlers(state: PopoverState, payload: PopoverPayload): void {
+  const outsideClickHandler = (e: Event) => {
+    const target = e.target as Node;
+    if (!state.element.contains(target) && !state.targetElement.contains(target)) {
+      hidePopover(state, payload);
+    }
+  };
+  
+  const keyHandler = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      hidePopover(state, payload);
+    }
+  };
+  
+  const navigationHandler = () => {
+    hidePopover(state, payload);
+  };
+  
+  setTimeout(() => {
+    document.addEventListener('click', outsideClickHandler);
+    document.addEventListener('keydown', keyHandler);
+    window.addEventListener('beforeunload', navigationHandler);
+    window.addEventListener('popstate', navigationHandler);
+  }, 100);
+  
+  state.cleanup.push(() => {
+    document.removeEventListener('click', outsideClickHandler);
+    document.removeEventListener('keydown', keyHandler);
+    window.removeEventListener('beforeunload', navigationHandler);
+    window.removeEventListener('popstate', navigationHandler);
+  });
+}
+
+function hasButtons(payload: PopoverPayload): boolean {
+  return payload.bodyBlocks?.some(block => block.kind === 'button') || false;
+}
+
+function trapFocus(element: HTMLElement): void {
+  const focusableElements = element.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  );
+  
+  if (focusableElements.length === 0) return;
+  
+  const firstElement = focusableElements[0] as HTMLElement;
+  const lastElement = focusableElements[focusableElements.length - 1] as HTMLElement;
+  
+  const handleTab = (e: KeyboardEvent) => {
+    if (e.key !== 'Tab') return;
+    
+    if (e.shiftKey) {
+      if (document.activeElement === firstElement) {
+        e.preventDefault();
+        lastElement.focus();
+      }
+    } else {
+      if (document.activeElement === lastElement) {
+        e.preventDefault();
+        firstElement.focus();
+      }
+    }
+  };
+  
+  element.addEventListener('keydown', handleTab);
+}
+
+function cleanupPopover(id: string): void {
+  console.debug("[DAP] Popover destroyed", { id });
+  
+  const state = activePopovers.get(id);
+  if (!state) return;
+  
+  state.cleanup.forEach(cleanup => {
+    try {
+      cleanup();
+    } catch (error) {
+      console.warn("[DAP] Error during popover cleanup:", error);
+    }
+  });
+  
+  if (state.element && state.element.parentNode) {
+    state.element.parentNode.removeChild(state.element);
+  }
+  
+  activePopovers.delete(id);
+}

package/src/experiences/registry.ts

@@ -0,0 +1,21 @@
+// src/experiences/registry.ts
+// A minimal, generic renderer registry. No coupling to flow types.
+
+export type Renderer<T = any> = (flow: T) => Promise<void> | void;
+
+const REGISTRY = new Map<string, Renderer>();
+
+/** Register a renderer for a normalized flow type (e.g., "modalSequence", "modal", "tooltip", "popover"). */
+export function register(type: string, renderer: Renderer): void {
+  REGISTRY.set(type, renderer);
+}
+
+/** Look up the renderer for a normalized flow type. */
+export function getRenderer<T = any>(type: string): Renderer<T> | undefined {
+  return REGISTRY.get(type) as Renderer<T> | undefined;
+}
+
+/** For tests/dev: clears all registered renderers. */
+export function resetRegistry(): void {
+  REGISTRY.clear();
+}