@cognior/iap-sdk 0.1.0

package/src/experiences/tooltip.ts

@@ -0,0 +1,740 @@
+import { sanitizeHtml } from "../utils/sanitize";
+import { register } from "./registry";
+import type { TooltipPayload } from "./types";
+import { resolveSelector } from "../utils/selectors";
+
+type TooltipFlow = { id: string; type: "tooltip"; payload: TooltipPayload };
+type Placement = "top" | "right" | "bottom" | "left";
+type Trigger = "hover" | "click" | "focus" | "pageload";
+
+export function registerTooltip() { 
+  register("tooltip", renderTooltip); 
+}
+
+// Main tooltip rendering function
+export async function renderTooltip(flow: TooltipFlow): Promise<void> {
+  const { payload, id } = flow;
+  
+  console.debug("[DAP] Tooltip initialized", { id, selector: payload.targetSelector });
+  
+  // Validate required fields from uxExperience
+  if (!payload.targetSelector || !payload.text) {
+    console.error("[DAP] Tooltip missing required fields", { 
+      targetSelector: payload.targetSelector,
+      hasText: !!payload.text 
+    });
+    return;
+  }
+
+  // Wait for target element
+  const target = await waitForTarget(payload.targetSelector, 5000);
+  if (!target) {
+    console.warn("[DAP] Tooltip target not found", { selector: payload.targetSelector });
+    return;
+  }
+
+  console.debug("[DAP] Tooltip target resolved", { selector: payload.targetSelector });
+
+  // Create and initialize tooltip
+  const tooltip = new DAPTooltip(id, target, payload);
+  tooltip.initialize();
+}
+
+// Direct tooltip rendering for validation
+export async function renderDirectTooltip(payload: TooltipPayload): Promise<void> {
+  const directFlow: TooltipFlow = {
+    id: `validation-${Date.now()}`,
+    type: "tooltip",
+    payload: payload
+  };
+  
+  await renderTooltip(directFlow);
+}
+
+// Clean tooltip implementation
+class DAPTooltip {
+  private id: string;
+  private target: HTMLElement;
+  private payload: TooltipPayload;
+  private container: HTMLElement | null = null;
+  private overlay: HTMLElement | null = null;
+  private isVisible: boolean = false;
+  private listeners: Array<() => void> = [];
+  private targetObserver: MutationObserver | null = null;
+  private trigger: Trigger;
+
+  constructor(id: string, target: HTMLElement, payload: TooltipPayload) {
+    this.id = id;
+    this.target = target;
+    this.payload = payload;
+    this.trigger = this.normalizeTrigger(payload.trigger);
+  }
+
+  initialize(): void {
+    this.setupTrigger();
+    this.setupGlobalListeners();
+    this.setupTargetObserver();
+  }
+
+  private normalizeTrigger(trigger: any): Trigger {
+    if (typeof trigger === "string" && ["hover", "click", "focus", "pageload"].includes(trigger)) {
+      return trigger as Trigger;
+    }
+    return "hover"; // default
+  }
+
+  private setupTrigger(): void {
+    switch (this.trigger) {
+      case "hover":
+        this.setupHoverTrigger();
+        break;
+      case "click":
+        this.setupClickTrigger();
+        break;
+      case "focus":
+        this.setupFocusTrigger();
+        break;
+      case "pageload":
+        // Show immediately
+        this.show();
+        break;
+    }
+  }
+
+  private setupHoverTrigger(): void {
+    const onMouseEnter = () => this.show();
+    const onMouseLeave = (e: MouseEvent) => {
+      // Don't hide if hovering over tooltip
+      const related = e.relatedTarget as Element | null;
+      if (related && this.container?.contains(related)) return;
+      this.hide();
+    };
+
+    this.target.addEventListener("mouseenter", onMouseEnter);
+    this.target.addEventListener("mouseleave", onMouseLeave);
+
+    this.listeners.push(
+      () => this.target.removeEventListener("mouseenter", onMouseEnter),
+      () => this.target.removeEventListener("mouseleave", onMouseLeave)
+    );
+  }
+
+  private setupClickTrigger(): void {
+    const onClick = (e: MouseEvent) => {
+      e.stopPropagation();
+      this.isVisible ? this.hide() : this.show();
+    };
+
+    const onDocumentClick = (e: MouseEvent) => {
+      const target = e.target as Element;
+      if (!this.container?.contains(target) && !this.target.contains(target)) {
+        this.hide();
+      }
+    };
+
+    this.target.addEventListener("click", onClick);
+    document.addEventListener("click", onDocumentClick, true);
+
+    this.listeners.push(
+      () => this.target.removeEventListener("click", onClick),
+      () => document.removeEventListener("click", onDocumentClick, true)
+    );
+  }
+
+  private setupFocusTrigger(): void {
+    const onFocus = () => this.show();
+    const onBlur = () => this.hide();
+
+    this.target.addEventListener("focus", onFocus);
+    this.target.addEventListener("blur", onBlur);
+
+    this.listeners.push(
+      () => this.target.removeEventListener("focus", onFocus),
+      () => this.target.removeEventListener("blur", onBlur)
+    );
+  }
+
+  private setupGlobalListeners(): void {
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape" && this.isVisible) {
+        this.hide();
+      }
+    };
+
+    const onScroll = () => {
+      if (this.isVisible) {
+        if (!this.isTargetInViewport()) {
+          this.hide();
+        } else {
+          this.position();
+        }
+      }
+    };
+
+    const onResize = () => {
+      if (this.isVisible) {
+        this.position();
+      }
+    };
+
+    const onVisibilityChange = () => {
+      if (document.hidden && this.isVisible) {
+        this.hide();
+      }
+    };
+
+    document.addEventListener("keydown", onKeyDown);
+    window.addEventListener("scroll", onScroll, true);
+    window.addEventListener("resize", onResize);
+    document.addEventListener("visibilitychange", onVisibilityChange);
+
+    this.listeners.push(
+      () => document.removeEventListener("keydown", onKeyDown),
+      () => window.removeEventListener("scroll", onScroll, true),
+      () => window.removeEventListener("resize", onResize),
+      () => document.removeEventListener("visibilitychange", onVisibilityChange)
+    );
+  }
+
+  private setupTargetObserver(): void {
+    this.targetObserver = new MutationObserver(() => {
+      if (!document.contains(this.target)) {
+        this.destroy();
+      }
+    });
+
+    this.targetObserver.observe(document.documentElement, {
+      childList: true,
+      subtree: true
+    });
+  }
+
+  private show(): void {
+    if (this.isVisible) return;
+
+    console.debug("[DAP] Tooltip shown", { id: this.id });
+    
+    this.createTooltip();
+    this.position();
+    this.isVisible = true;
+
+    // Add visible class for animation
+    requestAnimationFrame(() => {
+      if (this.container) {
+        this.container.classList.add("dap-tooltip-visible");
+      }
+    });
+
+    // Complete the flow step
+    if (this.payload._completionTracker?.onComplete) {
+      console.debug("[DAP] Completing tooltip flow", { id: this.id });
+      this.payload._completionTracker.onComplete();
+    }
+  }
+
+  private hide(): void {
+    if (!this.isVisible) return;
+
+    console.debug("[DAP] Tooltip dismissed", { id: this.id });
+
+    // Animate out before removing
+    if (this.container) {
+      this.container.style.animation = "dap-tooltip-exit 0.2s cubic-bezier(0.4, 0.0, 0.2, 1) forwards";
+      
+      setTimeout(() => {
+        this.removeTooltip();
+      }, 200);
+    } else {
+      this.removeTooltip();
+    }
+    
+    this.isVisible = false;
+  }
+
+  private createTooltip(): void {
+    // Create overlay if it doesn't exist
+    this.overlay = this.getOrCreateOverlay();
+
+    // Create tooltip container
+    this.container = document.createElement("div");
+    this.container.className = "dap-tooltip";
+    this.container.id = `dap-tooltip-${this.id}`;
+    this.container.setAttribute("role", "tooltip");
+    this.container.setAttribute("aria-live", "polite");
+
+    // Create content
+    const content = document.createElement("div");
+    content.className = "dap-tooltip-content";
+    content.textContent = this.payload.text || "";
+
+    // Create arrow
+    const arrow = document.createElement("div");
+    arrow.className = "dap-tooltip-arrow";
+
+    this.container.appendChild(content);
+    this.container.appendChild(arrow);
+
+    // Add hover behavior for hover trigger
+    if (this.trigger === "hover") {
+      const onTooltipMouseLeave = () => this.hide();
+      this.container.addEventListener("mouseleave", onTooltipMouseLeave);
+      this.listeners.push(
+        () => this.container?.removeEventListener("mouseleave", onTooltipMouseLeave)
+      );
+    }
+
+    this.overlay.appendChild(this.container);
+
+    // Set ARIA relationship
+    const tooltipId = this.container.id;
+    const prevDesc = this.target.getAttribute("aria-describedby") || "";
+    this.target.setAttribute("aria-describedby", [prevDesc, tooltipId].filter(Boolean).join(" ").trim());
+  }
+
+  private removeTooltip(): void {
+    if (this.container) {
+      // Clean up ARIA relationship
+      const tooltipId = this.container.id;
+      const currentDesc = this.target.getAttribute("aria-describedby") || "";
+      const newDesc = currentDesc.split(/\s+/).filter(Boolean).filter(id => id !== tooltipId).join(" ");
+      
+      if (newDesc) {
+        this.target.setAttribute("aria-describedby", newDesc);
+      } else {
+        this.target.removeAttribute("aria-describedby");
+      }
+
+      this.container.remove();
+      this.container = null;
+    }
+  }
+
+  private position(): void {
+    if (!this.container) return;
+
+    const targetRect = this.target.getBoundingClientRect();
+    const placement = this.normalizePlacement(this.payload.placement);
+    
+    // Reset positioning for measurement
+    this.container.style.position = "fixed";
+    this.container.style.visibility = "hidden";
+    this.container.style.top = "0px";
+    this.container.style.left = "0px";
+    this.container.style.display = "block";
+
+    // Get tooltip dimensions
+    const tooltipRect = this.container.getBoundingClientRect();
+    const gap = 8;
+    const viewport = {
+      width: window.innerWidth,
+      height: window.innerHeight
+    };
+
+    // Calculate best position
+    const position = this.calculatePosition(targetRect, tooltipRect, placement, gap, viewport);
+    
+    // Apply position
+    this.container.style.top = `${position.top}px`;
+    this.container.style.left = `${position.left}px`;
+    this.container.setAttribute("data-placement", position.placement);
+    this.container.style.visibility = "visible";
+  }
+
+  private normalizePlacement(placement: any): Placement {
+    if (typeof placement === "string" && ["top", "right", "bottom", "left"].includes(placement)) {
+      return placement as Placement;
+    }
+    return "top"; // default
+  }
+
+  private calculatePosition(
+    targetRect: DOMRect,
+    tooltipRect: DOMRect,
+    preferredPlacement: Placement,
+    gap: number,
+    viewport: { width: number; height: number }
+  ): { top: number; left: number; placement: Placement } {
+    
+    const positions = {
+      top: {
+        top: targetRect.top - tooltipRect.height - gap,
+        left: targetRect.left + (targetRect.width - tooltipRect.width) / 2
+      },
+      right: {
+        top: targetRect.top + (targetRect.height - tooltipRect.height) / 2,
+        left: targetRect.right + gap
+      },
+      bottom: {
+        top: targetRect.bottom + gap,
+        left: targetRect.left + (targetRect.width - tooltipRect.width) / 2
+      },
+      left: {
+        top: targetRect.top + (targetRect.height - tooltipRect.height) / 2,
+        left: targetRect.left - tooltipRect.width - gap
+      }
+    };
+
+    // Check if position fits in viewport
+    const fits = (pos: { top: number; left: number }) => {
+      return pos.top >= 0 && 
+             pos.left >= 0 && 
+             pos.top + tooltipRect.height <= viewport.height &&
+             pos.left + tooltipRect.width <= viewport.width;
+    };
+
+    // Try preferred placement first
+    let finalPosition = positions[preferredPlacement];
+    let finalPlacement = preferredPlacement;
+
+    if (!fits(finalPosition)) {
+      // Try alternative placements
+      const alternatives: Placement[] = ["top", "right", "bottom", "left"];
+      for (const alt of alternatives) {
+        if (alt !== preferredPlacement) {
+          const altPos = positions[alt];
+          if (fits(altPos)) {
+            finalPosition = altPos;
+            finalPlacement = alt;
+            break;
+          }
+        }
+      }
+    }
+
+    // Clamp to viewport if still overflowing
+    const margin = 4;
+    finalPosition.top = Math.max(margin, Math.min(finalPosition.top, viewport.height - tooltipRect.height - margin));
+    finalPosition.left = Math.max(margin, Math.min(finalPosition.left, viewport.width - tooltipRect.width - margin));
+
+    return { ...finalPosition, placement: finalPlacement };
+  }
+
+  private isTargetInViewport(): boolean {
+    const rect = this.target.getBoundingClientRect();
+    return rect.top >= 0 && 
+           rect.left >= 0 && 
+           rect.bottom <= window.innerHeight && 
+           rect.right <= window.innerWidth;
+  }
+
+  private getOrCreateOverlay(): HTMLElement {
+    let overlay = document.getElementById("dap-tooltip-overlay");
+    
+    if (!overlay) {
+      overlay = document.createElement("div");
+      overlay.id = "dap-tooltip-overlay";
+      overlay.style.cssText = `
+        position: fixed;
+        top: 0;
+        left: 0;
+        right: 0;
+        bottom: 0;
+        pointer-events: none;
+        z-index: 2147483640;
+      `;
+
+      // Inject CSS
+      this.injectCSS();
+      document.body.appendChild(overlay);
+    }
+
+    return overlay;
+  }
+
+  private injectCSS(): void {
+    if (document.getElementById("dap-tooltip-styles")) return;
+
+    const style = document.createElement("style");
+    style.id = "dap-tooltip-styles";
+    style.textContent = `
+      .dap-tooltip {
+        position: fixed;
+        background: linear-gradient(135deg, #f8f9fa 0%, #ffffff 100%);
+        color: #2c3e50;
+        padding: 12px 16px;
+        border-radius: 8px;
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+        font-size: 14px;
+        font-weight: 400;
+        line-height: 1.5;
+        max-width: 320px;
+        min-width: 200px;
+        word-wrap: break-word;
+        z-index: 2147483641;
+        pointer-events: auto;
+        box-shadow: 
+          0 8px 32px rgba(0, 0, 0, 0.15),
+          0 4px 16px rgba(0, 0, 0, 0.08),
+          0 0 0 1px rgba(0, 0, 0, 0.05);
+        border: 1px solid rgba(0, 0, 0, 0.08);
+        backdrop-filter: blur(8px);
+        opacity: 0;
+        transform: scale(0.95) translateY(-4px);
+        transition: all 0.2s cubic-bezier(0.4, 0.0, 0.2, 1);
+        animation: dap-tooltip-enter 0.25s cubic-bezier(0.4, 0.0, 0.2, 1) forwards;
+      }
+
+      .dap-tooltip.dap-tooltip-visible {
+        opacity: 1;
+        transform: scale(1) translateY(0);
+      }
+
+      .dap-tooltip-content {
+        margin: 0;
+        color: #2c3e50;
+        text-shadow: none;
+        letter-spacing: 0.02em;
+      }
+
+      .dap-tooltip-content p {
+        margin: 0;
+      }
+
+      .dap-tooltip-content strong {
+        font-weight: 600;
+        color: #1a202c;
+      }
+
+      .dap-tooltip-arrow {
+        position: absolute;
+        width: 0;
+        height: 0;
+        filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.08));
+      }
+
+      /* Arrow positioning and styling */
+      .dap-tooltip[data-placement="top"] .dap-tooltip-arrow {
+        bottom: -8px;
+        left: 50%;
+        transform: translateX(-50%);
+        border-left: 8px solid transparent;
+        border-right: 8px solid transparent;
+        border-top: 8px solid #f8f9fa;
+      }
+
+      .dap-tooltip[data-placement="right"] .dap-tooltip-arrow {
+        left: -8px;
+        top: 50%;
+        transform: translateY(-50%);
+        border-top: 8px solid transparent;
+        border-bottom: 8px solid transparent;
+        border-right: 8px solid #f8f9fa;
+      }
+
+      .dap-tooltip[data-placement="bottom"] .dap-tooltip-arrow {
+        top: -8px;
+        left: 50%;
+        transform: translateX(-50%);
+        border-left: 8px solid transparent;
+        border-right: 8px solid transparent;
+        border-bottom: 8px solid #f8f9fa;
+      }
+
+      .dap-tooltip[data-placement="left"] .dap-tooltip-arrow {
+        right: -8px;
+        top: 50%;
+        transform: translateY(-50%);
+        border-top: 8px solid transparent;
+        border-bottom: 8px solid transparent;
+        border-left: 8px solid #f8f9fa;
+      }
+
+      /* Animation keyframes */
+      @keyframes dap-tooltip-enter {
+        0% {
+          opacity: 0;
+          transform: scale(0.9) translateY(-8px);
+        }
+        50% {
+          opacity: 0.8;
+        }
+        100% {
+          opacity: 1;
+          transform: scale(1) translateY(0);
+        }
+      }
+
+      @keyframes dap-tooltip-exit {
+        0% {
+          opacity: 1;
+          transform: scale(1) translateY(0);
+        }
+        100% {
+          opacity: 0;
+          transform: scale(0.95) translateY(-4px);
+        }
+      }
+
+      /* Hover states */
+      .dap-tooltip:hover {
+        background: linear-gradient(135deg, #ffffff 0%, #f1f3f5 100%);
+        box-shadow: 
+          0 12px 40px rgba(0, 0, 0, 0.18),
+          0 6px 20px rgba(0, 0, 0, 0.1),
+          0 0 0 1px rgba(0, 0, 0, 0.08);
+        transform: translateY(-1px);
+      }
+
+      /* High contrast mode support */
+      @media (prefers-contrast: high) {
+        .dap-tooltip {
+          background: #ffffff;
+          border: 2px solid #000000;
+          color: #000000;
+        }
+        
+        .dap-tooltip-arrow {
+          filter: none;
+        }
+        
+        .dap-tooltip[data-placement="top"] .dap-tooltip-arrow {
+          border-top-color: #ffffff;
+        }
+        
+        .dap-tooltip[data-placement="right"] .dap-tooltip-arrow {
+          border-right-color: #ffffff;
+        }
+        
+        .dap-tooltip[data-placement="bottom"] .dap-tooltip-arrow {
+          border-bottom-color: #ffffff;
+        }
+        
+        .dap-tooltip[data-placement="left"] .dap-tooltip-arrow {
+          border-left-color: #ffffff;
+        }
+      }
+
+      /* Reduced motion support */
+      @media (prefers-reduced-motion: reduce) {
+        .dap-tooltip {
+          transition: opacity 0.15s ease;
+          animation: none;
+        }
+        
+        .dap-tooltip:hover {
+          transform: none;
+        }
+      }
+
+      /* Dark mode support */
+      @media (prefers-color-scheme: dark) {
+        .dap-tooltip {
+          background: linear-gradient(135deg, #2d3748 0%, #4a5568 100%);
+          color: #ffffff;
+          border-color: rgba(255, 255, 255, 0.1);
+          box-shadow: 
+            0 8px 32px rgba(0, 0, 0, 0.4),
+            0 4px 16px rgba(0, 0, 0, 0.24),
+            0 0 0 1px rgba(255, 255, 255, 0.1);
+        }
+        
+        .dap-tooltip-content {
+          color: #ffffff;
+        }
+        
+        .dap-tooltip-content strong {
+          color: #e2e8f0;
+        }
+        
+        .dap-tooltip[data-placement="top"] .dap-tooltip-arrow {
+          border-top-color: #2d3748;
+        }
+        
+        .dap-tooltip[data-placement="right"] .dap-tooltip-arrow {
+          border-right-color: #2d3748;
+        }
+        
+        .dap-tooltip[data-placement="bottom"] .dap-tooltip-arrow {
+          border-bottom-color: #2d3748;
+        }
+        
+        .dap-tooltip[data-placement="left"] .dap-tooltip-arrow {
+          border-left-color: #2d3748;
+        }
+      }
+
+      /* Focus indicators for accessibility */
+      .dap-tooltip:focus-within {
+        outline: 2px solid #4a90e2;
+        outline-offset: 2px;
+      }
+
+      /* RTL support */
+      [dir="rtl"] .dap-tooltip {
+        text-align: right;
+      }
+
+      /* Mobile responsive adjustments */
+      @media (max-width: 768px) {
+        .dap-tooltip {
+          max-width: calc(100vw - 32px);
+          font-size: 16px;
+          padding: 16px 20px;
+        }
+      }
+
+      @media (max-width: 480px) {
+        .dap-tooltip {
+          max-width: calc(100vw - 16px);
+          border-radius: 12px;
+        }
+      }
+    `;
+
+    document.head.appendChild(style);
+  }
+
+  destroy(): void {
+    console.debug("[DAP] Tooltip destroyed", { id: this.id });
+    
+    this.hide();
+    
+    // Clean up all listeners
+    this.listeners.forEach(cleanup => cleanup());
+    this.listeners = [];
+
+    // Clean up target observer
+    if (this.targetObserver) {
+      this.targetObserver.disconnect();
+      this.targetObserver = null;
+    }
+  }
+}
+
+// Target resolution utility
+async function waitForTarget(selector: string, timeout: number): Promise<HTMLElement | null> {
+  const startTime = Date.now();
+  
+  // Try immediate resolution
+  let element = resolveSelector<HTMLElement>(selector);
+  if (element) return element;
+
+  return new Promise((resolve) => {
+    const observer = new MutationObserver(() => {
+      element = resolveSelector<HTMLElement>(selector);
+      if (element) {
+        observer.disconnect();
+        resolve(element);
+        return;
+      }
+
+      // Check timeout
+      if (Date.now() - startTime > timeout) {
+        observer.disconnect();
+        resolve(null);
+      }
+    });
+
+    observer.observe(document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true
+    });
+
+    // Fallback timeout
+    setTimeout(() => {
+      observer.disconnect();
+      resolve(resolveSelector<HTMLElement>(selector));
+    }, timeout);
+  });
+}