@cognior/iap-sdk 0.1.0

package/src/experiences/modal.ts

@@ -0,0 +1,1337 @@
+// src/experiences/modal.ts
+// Simple modal experience renderer
+
+import { sanitizeHtml } from "../utils/sanitize";
+import { register } from "./registry";
+import { modalCssText } from "../styles/modal.css";
+import type { ModalPayload, ModalContent, ModalSize } from "./types";
+
+type ModalFlow = { id: string; type: "modal"; payload: ModalPayload };
+
+export function registerModal() {
+  register("modal", renderModal);
+}
+
+export async function renderModal(flow: ModalFlow): Promise<void> {
+  const { payload, id } = flow;
+  
+  console.debug("[DAP] renderModal called with payload:", payload);
+  console.debug("[DAP] Modal flow ID:", id);
+  
+  // Extract completion tracker
+  const completionTracker = payload._completionTracker;
+  
+  // Ensure CSS is injected
+  ensureStyles();
+  
+  // Create modal elements
+  const { overlay, modal, header, body, footer } = createModalElements(payload);
+  
+  // Add to DOM
+  document.documentElement.appendChild(overlay);
+  
+  // Focus management
+  const prevActive = document.activeElement as HTMLElement | null;
+  modal.setAttribute("role", "dialog");
+  modal.setAttribute("aria-modal", "true");
+  modal.setAttribute("aria-labelledby", "modal-title");
+  
+  // Enhanced accessibility setup
+  setupModalAccessibility(modal, overlay);
+  
+  // Event handlers
+  function closeModal() {
+    // Cleanup accessibility handlers
+    if ((modal as any)._accessibilityCleanup) {
+      (modal as any)._accessibilityCleanup();
+    }
+    
+    overlay.style.animation = "modalFadeOut 0.2s ease-in";
+    modal.style.animation = "modalSlideOut 0.2s ease-in";
+    
+    setTimeout(() => {
+      overlay.remove();
+      prevActive?.focus();
+      
+      // Signal completion
+      if (completionTracker?.onComplete) {
+        console.debug(`[DAP] Completing modal flow: ${id}`);
+        completionTracker.onComplete();
+      }
+    }, 200);
+  }
+  
+  // Close on overlay click
+  overlay.addEventListener("click", (e) => {
+    if (e.target === overlay) {
+      closeModal();
+    }
+  });
+  
+  // Close button
+  const closeBtn = modal.querySelector(".dap-modal-close") as HTMLButtonElement;
+  if (closeBtn) {
+    closeBtn.addEventListener("click", closeModal);
+  }
+  
+  // Escape key
+  function handleKeyboard(e: KeyboardEvent) {
+    if (e.key === "Escape") {
+      closeModal();
+      document.removeEventListener("keydown", handleKeyboard);
+    }
+  }
+  document.addEventListener("keydown", handleKeyboard);
+  
+  // Add exit animations
+  if (!document.getElementById("dap-modal-exit-styles")) {
+    const style = document.createElement("style");
+    style.id = "dap-modal-exit-styles";
+    style.textContent = `
+      @keyframes modalFadeOut {
+        from { opacity: 1; backdrop-filter: blur(4px); }
+        to { opacity: 0; backdrop-filter: blur(0px); }
+      }
+      @keyframes modalSlideOut {
+        from { opacity: 1; transform: scale(1) translateY(0); }
+        to { opacity: 0; transform: scale(0.95) translateY(-10px); }
+      }
+    `;
+    document.head.appendChild(style);
+  }
+  
+  // Enterprise dragging functionality
+  setupModalDragging(modal, header, overlay);
+  
+  // Media lifecycle management
+  setupMediaHandling(modal, overlay);
+}
+
+function setupModalDragging(modal: HTMLElement, header: HTMLElement, overlay: HTMLElement): void {
+  let isDragging = false;
+  let dragStartX = 0;
+  let dragStartY = 0;
+  let modalStartX = 0;
+  let modalStartY = 0;
+  
+  // Make header the drag handle
+  header.style.cursor = "move";
+  
+  const startDrag = (e: MouseEvent) => {
+    isDragging = true;
+    dragStartX = e.clientX;
+    dragStartY = e.clientY;
+    
+    const rect = modal.getBoundingClientRect();
+    modalStartX = rect.left;
+    modalStartY = rect.top;
+    
+    header.classList.add("dragging");
+    overlay.classList.add("dragging");
+    
+    document.addEventListener("mousemove", drag);
+    document.addEventListener("mouseup", endDrag);
+    e.preventDefault();
+  };
+  
+  const drag = (e: MouseEvent) => {
+    if (!isDragging) return;
+    
+    const deltaX = e.clientX - dragStartX;
+    const deltaY = e.clientY - dragStartY;
+    
+    let newX = modalStartX + deltaX;
+    let newY = modalStartY + deltaY;
+    
+    // Constrain to viewport with 10px margin
+    const modalRect = modal.getBoundingClientRect();
+    const viewport = {
+      width: window.innerWidth,
+      height: window.innerHeight
+    };
+    
+    newX = Math.max(10, Math.min(newX, viewport.width - modalRect.width - 10));
+    newY = Math.max(10, Math.min(newY, viewport.height - modalRect.height - 10));
+    
+    // Position modal
+    modal.style.position = "fixed";
+    modal.style.left = `${newX}px`;
+    modal.style.top = `${newY}px`;
+    modal.style.transform = "none";
+  };
+  
+  const endDrag = () => {
+    isDragging = false;
+    header.classList.remove("dragging");
+    overlay.classList.remove("dragging");
+    
+    document.removeEventListener("mousemove", drag);
+    document.removeEventListener("mouseup", endDrag);
+  };
+  
+  header.addEventListener("mousedown", startDrag);
+}
+
+function setupModalAccessibility(modal: HTMLElement, overlay: HTMLElement): void {
+  // Enhanced focus management - Focus trap
+  const focusableElements = modal.querySelectorAll(
+    'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
+  ) as NodeListOf<HTMLElement>;
+  
+  const firstFocusable = focusableElements[0];
+  const lastFocusable = focusableElements[focusableElements.length - 1];
+  
+  // Initial focus to first focusable element
+  if (firstFocusable) {
+    firstFocusable.focus();
+  }
+  
+  // Focus trap on Tab/Shift+Tab
+  const handleTabKey = (e: KeyboardEvent) => {
+    if (e.key === "Tab") {
+      if (e.shiftKey) {
+        // Shift + Tab - focus previous
+        if (document.activeElement === firstFocusable) {
+          e.preventDefault();
+          lastFocusable?.focus();
+        }
+      } else {
+        // Tab - focus next
+        if (document.activeElement === lastFocusable) {
+          e.preventDefault();
+          firstFocusable?.focus();
+        }
+      }
+    }
+  };
+  
+  modal.addEventListener("keydown", handleTabKey);
+  
+  // Store cleanup function
+  (modal as any)._accessibilityCleanup = () => {
+    modal.removeEventListener("keydown", handleTabKey);
+  };
+}
+
+function setupMediaHandling(modal: HTMLElement, overlay: HTMLElement): void {
+  const videos = modal.querySelectorAll("video") as NodeListOf<HTMLVideoElement>;
+  const pausedVideos: HTMLVideoElement[] = [];
+  
+  // Store original overlay.remove to intercept it
+  const originalRemove = overlay.remove.bind(overlay);
+  
+  overlay.remove = () => {
+    // Pause all videos and track which ones were playing
+    videos.forEach((video) => {
+      if (!video.paused) {
+        video.pause();
+        pausedVideos.push(video);
+      }
+    });
+    
+    // Call original remove
+    originalRemove();
+    
+    // Resume videos after a short delay (if they're still in DOM)
+    setTimeout(() => {
+      pausedVideos.forEach((video) => {
+        if (document.contains(video)) {
+          video.play().catch(() => {
+            // Ignore autoplay policy errors
+          });
+        }
+      });
+    }, 100);
+  };
+}
+
+function createModalElements(payload: ModalPayload) {
+  console.log("[DAP] Creating modal elements with payload:", payload);
+  const overlay = document.createElement("div");
+  overlay.className = "dap-modal-overlay";
+  
+  const modal = document.createElement("div");
+  modal.className = "dap-modal";
+  
+  // Apply size class if specified
+  if (payload.size) {
+    modal.classList.add(`dap-modal-${payload.size}`);
+  } else {
+    modal.classList.add("dap-modal-medium"); // Default to medium size
+  }
+  
+  // Header - always include header for consistent layout
+  const header = document.createElement("div");
+  header.className = "dap-modal-header";
+  
+  // Title (if provided)
+  if (payload.title) {
+    const title = document.createElement("h2");
+    title.className = "dap-modal-title";
+    title.id = "modal-title";
+    title.textContent = payload.title;
+    header.appendChild(title);
+  } else {
+    // Add empty space to maintain header layout
+    const title = document.createElement("h2");
+    title.className = "dap-modal-title";
+    title.id = "modal-title";
+    title.style.visibility = "hidden";
+    title.innerHTML = "&nbsp;";
+    header.appendChild(title);
+  }
+  
+  // Close button - always present
+  const closeBtn = document.createElement("button");
+  closeBtn.className = "dap-modal-close";
+  closeBtn.setAttribute("aria-label", "Close modal");
+  closeBtn.innerHTML = "×";
+  header.appendChild(closeBtn);
+  
+  // Body
+  const body = document.createElement("div");
+  body.className = "dap-modal-body";
+  
+  console.debug("[DAP] Processing modal body:", payload.body);
+  console.debug("[DAP] Body type:", typeof payload.body);
+  console.debug("[DAP] Is body array:", Array.isArray(payload.body));
+  
+  if (payload.body && Array.isArray(payload.body)) {
+    payload.body.forEach((content, index) => {
+      console.debug(`[DAP] Processing body content ${index}:`, content);
+      const contentEl = renderModalContent(content);
+      if (contentEl) body.appendChild(contentEl);
+    });
+  } else if (payload.body) {
+    console.warn("[DAP] Body is not an array:", payload.body);
+    // Handle non-array body content
+    const textEl = document.createElement("div");
+    textEl.className = "dap-content-text";
+    textEl.textContent = String(payload.body);
+    body.appendChild(textEl);
+  }
+  
+  // Footer - always include for consistent layout
+  const footer = document.createElement("div");
+  footer.className = "dap-modal-footer";
+  
+  if (payload.footerText) {
+    const footerText = document.createElement("p");
+    footerText.className = "dap-footer-text";
+    footerText.innerHTML = sanitizeHtml(payload.footerText);
+    footer.appendChild(footerText);
+  }
+  
+  // Assemble modal - always include header and footer
+  modal.appendChild(header);
+  modal.appendChild(body);
+  modal.appendChild(footer);
+  overlay.appendChild(modal);
+  
+  return { overlay, modal, header, body, footer };
+}
+
+function renderModalContent(content: ModalContent): HTMLElement | null {
+  console.log("[DAP] Rendering modal content with kind:", content.kind);
+  switch (content.kind) {
+    case "text":
+      const textEl = document.createElement("div");
+      textEl.className = "dap-content-text";
+      textEl.innerHTML = sanitizeHtml(content.html);
+      return textEl;
+      
+    case "link":
+      const linkEl = document.createElement("a");
+      linkEl.className = "dap-content-link";
+      linkEl.href = content.href;
+      linkEl.textContent = content.label || content.href;
+      linkEl.target = "_blank";
+      linkEl.rel = "noopener noreferrer";
+      return linkEl;
+      
+    case "image":
+      const imgEl = document.createElement("img");
+      imgEl.className = "dap-content-image";
+      imgEl.src = content.url;
+      imgEl.alt = content.alt || "";
+      return imgEl;
+      
+    case "video":
+      if (content.sources && content.sources.length > 0) {
+        const videoEl = document.createElement("video");
+        videoEl.className = "dap-content-video";
+        videoEl.controls = true;
+        
+        content.sources.forEach(source => {
+          const sourceEl = document.createElement("source");
+          sourceEl.src = source.src;
+          if (source.type) sourceEl.type = source.type;
+          videoEl.appendChild(sourceEl);
+        });
+        
+        return videoEl;
+      }
+      return null;
+      
+    case "youtube":
+      const iframeEl = document.createElement("iframe");
+      iframeEl.className = "dap-content-youtube";
+      iframeEl.src = content.href;
+      iframeEl.setAttribute("frameborder", "0");
+      iframeEl.setAttribute("allowfullscreen", "true");
+      return iframeEl;
+      
+    case "kb":
+      // Knowledge base rendering with in-modal viewing
+      console.debug("[DAP] Rendering KB content:", content);
+      return renderKnowledgeBase(content);
+      
+    case "kb-item-viewer":
+      // Knowledge base item viewer
+      console.debug("[DAP] Rendering KB item viewer:", content);
+      return renderKBItemViewer(content);
+      
+    case "article":
+      // Article content rendering with inline viewing
+      console.debug("[DAP] Rendering Article content:", content);
+      console.debug("[DAP] Detected MIME type:", content.mime);
+      return createArticleViewer(content);
+      
+    default:
+      console.warn("[DAP] Unknown content kind:", (content as any)?.kind);
+      return null;
+  }
+}
+
+function renderKnowledgeBase(content: any): HTMLElement {
+  const kbEl = document.createElement("div");
+  kbEl.className = "dap-content-kb";
+  
+  // Initialize KB state when rendering list for the first time
+  if (!kbState || kbState.view === "item") {
+    console.debug("[DAP] Initializing KB state with items:", content.items);
+    kbState = {
+      view: "list",
+      items: content.items || [],
+      selectedItem: null,
+      title: content.title || "Knowledge Base",
+      modalBodyRef: null
+    };
+    console.debug("[DAP] KB state initialized, items count:", kbState.items.length);
+  }
+  
+  if (content.title) {
+    const title = document.createElement("h3");
+    title.textContent = content.title;
+    kbEl.appendChild(title);
+  }
+  
+  if (content.items && Array.isArray(content.items)) {
+    console.debug("[DAP] Processing KB items:", content.items);
+    
+    content.items.forEach((item: any, index: number) => {
+      console.debug(`[DAP] Processing KB item ${index}:`, item);
+      
+      const itemEl = document.createElement("div");
+      itemEl.className = "dap-kb-item";
+      
+      // Handle KBItem structure from flows.ts
+      let itemUrl = "";
+      let itemTitle = "";
+      let itemDescription = "";
+      let itemType = "";
+      
+      if (typeof item === "string") {
+        // If item is just a string, treat it as URL
+        itemUrl = item;
+        itemTitle = item;
+        itemType = "link";
+      } else if (item && typeof item === "object") {
+        // Handle KBItem structure with proper property access
+        const kbItem = item as any;
+        itemUrl = kbItem.url || "";
+        itemTitle = kbItem.title || "";
+        itemDescription = kbItem.description || "";
+        itemType = kbItem.itemType || detectContentType(itemUrl, kbItem.fileName);
+        
+        console.debug(`[DAP] Extracted: url=${itemUrl}, title=${itemTitle}, description=${itemDescription}, type=${itemType}`);
+      } else {
+        console.warn("[DAP] Invalid KB item structure:", item);
+        return; // Skip this item
+      }
+      
+      if (!itemUrl || !itemTitle) {
+        console.warn("[DAP] KB item missing required fields (url or title), skipping:", item);
+        return; // Skip items without required fields
+      }
+      
+      // Create clickable item (NO external navigation)
+      const button = document.createElement("button");
+      button.className = "dap-kb-item-button dap-modal-button primary";
+      button.textContent = itemTitle;
+      button.title = itemDescription || itemTitle;
+      
+      // Add content type icon
+      const icon = document.createElement("span");
+      icon.className = `dap-kb-icon dap-kb-icon-${itemType}`;
+      button.insertBefore(icon, button.firstChild);
+      
+      // In-modal viewing click handler
+      button.addEventListener("click", (e) => {
+        e.preventDefault();
+        e.stopPropagation();
+        openKBItemInModal(item, content.title || "Knowledge Base");
+      });
+      
+      itemEl.appendChild(button);
+      
+      // Add description if available
+      if (itemDescription) {
+        const desc = document.createElement("p");
+        desc.className = "dap-kb-description";
+        desc.textContent = itemDescription;
+        itemEl.appendChild(desc);
+      }
+      
+      kbEl.appendChild(itemEl);
+    });
+  } else {
+    console.warn("[DAP] KB content has no items or items is not an array:", content);
+    
+    // Add fallback message
+    const noItemsMsg = document.createElement("p");
+    noItemsMsg.className = "dap-kb-no-items";
+    noItemsMsg.textContent = "No knowledge base items available.";
+    kbEl.appendChild(noItemsMsg);
+  }
+  
+  return kbEl;
+}
+
+function renderKBItemViewer(content: any): HTMLElement {
+  const viewerEl = document.createElement("div");
+  viewerEl.className = "dap-kb-item-viewer";
+  
+  // Back navigation header
+  const headerEl = document.createElement("div");
+  headerEl.className = "dap-kb-viewer-header";
+  
+  const backBtn = document.createElement("button");
+  backBtn.className = "dap-kb-back-button dap-modal-button outline";
+  backBtn.innerHTML = "← Back to " + (content.kbTitle || "Knowledge Base");
+  backBtn.addEventListener("click", () => {
+    goBackToKBList();
+  });
+  headerEl.appendChild(backBtn);
+  
+  // File type badge
+  const itemType = content.item.itemType || detectContentType(content.item.url, content.item.fileName);
+  const badge = createFileTypeBadge(itemType, content.item.fileName);
+  headerEl.appendChild(badge);
+  
+  // Item title
+  const title = document.createElement("h3");
+  title.className = "dap-kb-item-title";
+  title.textContent = content.item.title || "Content";
+  headerEl.appendChild(title);
+  
+  // File metadata
+  if (content.item.fileName) {
+    const fileInfo = document.createElement("p");
+    fileInfo.className = "dap-file-metadata";
+    fileInfo.innerHTML = `<strong>File:</strong> ${content.item.fileName}`;
+    headerEl.appendChild(fileInfo);
+  }
+  
+  viewerEl.appendChild(headerEl);
+  
+  // Content viewer
+  const contentEl = renderKBItemContent(content.item);
+  if (contentEl) {
+    viewerEl.appendChild(contentEl);
+  }
+  
+  return viewerEl;
+}
+
+function renderKBItemContent(item: any): HTMLElement | null {
+  const itemType = item.itemType || detectContentType(item.url, item.fileName);
+  console.debug("[DAP] Rendering KB item content, type:", itemType, "url:", item.url);
+  
+  switch (itemType) {
+    case "video":
+      return createVideoViewer(item.url);
+      
+    case "image":
+      return createImageViewer(item.url, item.title);
+      
+    case "pdf":
+      return createPDFViewer(item.url, item.fileName);
+      
+    case "article":
+      return createArticleViewer(item);
+      
+    case "doc":
+    case "docx":
+      return createDocumentViewer(item.url, item.fileName, itemType);
+      
+    case "youtube":
+      return createYouTubeViewer(item.url);
+      
+    case "link":
+    default:
+      return createLinkViewer(item.url, item.title, item.description);
+  }
+}
+
+function createVideoViewer(url: string): HTMLElement {
+  const videoEl = document.createElement("video");
+  videoEl.className = "dap-kb-video";
+  videoEl.controls = true;
+  videoEl.preload = "metadata";
+  videoEl.style.width = "100%";
+  videoEl.style.maxHeight = "400px";
+  
+  const source = document.createElement("source");
+  source.src = url;
+  videoEl.appendChild(source);
+  
+  return videoEl;
+}
+
+function createImageViewer(url: string, alt?: string): HTMLElement {
+  const imgEl = document.createElement("img");
+  imgEl.className = "dap-kb-image";
+  imgEl.src = url;
+  imgEl.alt = alt || "";
+  imgEl.style.width = "100%";
+  imgEl.style.maxHeight = "500px";
+  imgEl.style.objectFit = "contain";
+  
+  return imgEl;
+}
+
+function createPDFViewer(url: string, fileName?: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-kb-pdf-container";
+  
+  // Try embedded PDF viewer first
+  const iframe = document.createElement("iframe");
+  iframe.className = "dap-kb-pdf-iframe";
+  iframe.src = url;
+  iframe.style.width = "100%";
+  iframe.style.height = "500px";
+  iframe.style.border = "1px solid #ddd";
+  
+  // Fallback controls
+  const fallback = document.createElement("div");
+  fallback.className = "dap-kb-pdf-fallback";
+  fallback.innerHTML = `
+    <p>PDF preview not available in this browser.</p>
+    <button class="dap-kb-download-btn dap-modal-button secondary" onclick="window.open('${url}', '_blank')">
+      Open PDF in New Tab
+    </button>
+  `;
+  
+  // Error handling
+  iframe.addEventListener("error", () => {
+    iframe.style.display = "none";
+    fallback.style.display = "block";
+  });
+  
+  container.appendChild(iframe);
+  container.appendChild(fallback);
+  
+  return container;
+}
+
+// Centralized Article Viewer Resolver - determines appropriate viewer based on MIME type and file extension
+function resolveArticleViewer(articleContent: any): { viewer: string; mimeType: string | null } {
+  console.debug("[DAP] Resolving Article viewer for:", articleContent);
+  
+  const url = articleContent.url || articleContent.presignedUrl || "";
+  const mimeType = articleContent.mime || articleContent.mimeType || null;
+  const fileName = articleContent.fileName || "";
+  
+  console.debug("[DAP] Detected MIME type:", mimeType || "none");
+  console.debug("[DAP] File URL:", url);
+  console.debug("[DAP] File name:", fileName);
+  
+  // Check MIME type first (preferred)
+  if (mimeType) {
+    if (mimeType === "application/pdf") {
+      console.debug("[DAP] Selected viewer: pdf");
+      return { viewer: "pdf", mimeType };
+    }
+    if (mimeType.includes("word") || mimeType.includes("msword") || 
+        mimeType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") {
+      console.debug("[DAP] Selected viewer: document");
+      return { viewer: "document", mimeType };
+    }
+    if (mimeType.includes("presentation") || mimeType.includes("powerpoint") ||
+        mimeType === "application/vnd.openxmlformats-officedocument.presentationml.presentation") {
+      console.debug("[DAP] Selected viewer: presentation");
+      return { viewer: "presentation", mimeType };
+    }
+    if (mimeType === "text/html" || mimeType.includes("text/")) {
+      console.debug("[DAP] Selected viewer: web");
+      return { viewer: "web", mimeType };
+    }
+  }
+  
+  // Fallback to file extension detection
+  const urlLower = url.toLowerCase();
+  const fileNameLower = fileName.toLowerCase();
+  
+  if (urlLower.includes(".pdf") || fileNameLower.endsWith(".pdf")) {
+    console.debug("[DAP] Selected viewer: pdf (by extension)");
+    return { viewer: "pdf", mimeType: "application/pdf" };
+  }
+  if (urlLower.match(/\.(doc|docx)/) || fileNameLower.match(/\.(doc|docx)$/)) {
+    console.debug("[DAP] Selected viewer: document (by extension)");
+    return { viewer: "document", mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document" };
+  }
+  if (urlLower.match(/\.(ppt|pptx)/) || fileNameLower.match(/\.(ppt|pptx)$/)) {
+    console.debug("[DAP] Selected viewer: presentation (by extension)");
+    return { viewer: "presentation", mimeType: "application/vnd.openxmlformats-officedocument.presentationml.presentation" };
+  }
+  if (urlLower.match(/\.(html?|htm)/) || fileNameLower.match(/\.(html?|htm)$/)) {
+    console.debug("[DAP] Selected viewer: web (by extension)");
+    return { viewer: "web", mimeType: "text/html" };
+  }
+  
+  // Check URL patterns for web content
+  if (url && (url.startsWith('http://') || url.startsWith('https://'))) {
+    // If it's a web URL and doesn't have a specific file extension, treat as web content
+    if (!urlLower.match(/\.(pdf|doc|docx|ppt|pptx|xls|xlsx|zip|rar)$/)) {
+      console.debug("[DAP] Selected viewer: web (by URL pattern)");
+      return { viewer: "web", mimeType: "text/html" };
+    }
+  }
+  
+  console.debug("[DAP] Selected viewer: fallback");
+  return { viewer: "fallback", mimeType: mimeType };
+}
+
+// Create Article Viewer - handles all document-based assets with inline preview and fallback
+function createArticleViewer(articleContent: any): HTMLElement {
+  console.debug("[DAP] Rendering Article");
+  
+  const container = document.createElement("div");
+  container.className = "dap-kb-article-viewer";
+  
+  const url = articleContent.url || articleContent.presignedUrl || "";
+  const fileName = articleContent.fileName || "Document";
+  const title = articleContent.title || fileName;
+  const description = articleContent.description || "";
+  const content = articleContent.content || "";
+  
+  // Add title
+  const titleEl = document.createElement("h4");
+  titleEl.className = "dap-article-title";
+  titleEl.textContent = title;
+  container.appendChild(titleEl);
+  
+  // Add description if available
+  if (description) {
+    const descEl = document.createElement("p");
+    descEl.className = "dap-article-description";
+    descEl.textContent = description;
+    container.appendChild(descEl);
+  }
+  
+  // Handle different content scenarios
+  if (content && content.trim()) {
+    // Rich HTML content provided directly
+    console.debug("[DAP] Rendering direct HTML content");
+    const contentEl = document.createElement("div");
+    contentEl.className = "dap-article-content";
+    contentEl.innerHTML = content;
+    container.appendChild(contentEl);
+    
+    // Add action buttons if URL is also provided
+    if (url) {
+      const actions = createDocumentActions(url, fileName);
+      container.appendChild(actions);
+    }
+  } else if (url) {
+    // URL-based content - create loading state first
+    const loadingEl = document.createElement("div");
+    loadingEl.className = "dap-article-loading";
+    loadingEl.innerHTML = `
+      <div class="dap-loading-spinner"></div>
+      <p>Loading article content...</p>
+    `;
+    container.appendChild(loadingEl);
+    
+    // Resolve viewer type
+    const { viewer, mimeType } = resolveArticleViewer(articleContent);
+    console.debug("[DAP] Selected viewer type:", viewer, "for URL:", url);
+    
+    // Remove loading state after a brief delay to show it
+    setTimeout(() => {
+      loadingEl.remove();
+      
+      // Create appropriate viewer
+      switch (viewer) {
+        case "pdf":
+          const pdfViewer = createInlinePDFViewer(url, fileName);
+          container.appendChild(pdfViewer);
+          break;
+          
+        case "document":
+          const docViewer = createInlineDocumentViewer(url, fileName, mimeType);
+          container.appendChild(docViewer);
+          break;
+          
+        case "presentation":
+          const pptViewer = createInlinePresentationViewer(url, fileName, mimeType);
+          container.appendChild(pptViewer);
+          break;
+          
+        case "web":
+          const webViewer = createWebContentViewer(url, title);
+          container.appendChild(webViewer);
+          break;
+          
+        case "fallback":
+        default:
+          console.debug("[DAP] Fallback activated for URL:", url);
+          const fallbackViewer = createEnhancedFallbackViewer(articleContent, "This document cannot be previewed inline.");
+          container.appendChild(fallbackViewer);
+          break;
+      }
+    }, 300);
+  } else {
+    // No content or URL provided
+    console.error("[DAP] No content or URL provided for Article");
+    const errorViewer = createEnhancedFallbackViewer(articleContent, "No article content available to display.");
+    container.appendChild(errorViewer);
+  }
+  
+  return container;
+}
+
+// Inline PDF Viewer - uses iframe for PDF preview
+function createInlinePDFViewer(url: string, fileName: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-pdf-viewer-container";
+  
+  // Try iframe first
+  const iframe = document.createElement("iframe");
+  iframe.className = "dap-pdf-iframe";
+  iframe.src = url;
+  iframe.style.width = "100%";
+  iframe.style.height = "500px";
+  iframe.style.border = "1px solid #ddd";
+  iframe.setAttribute("frameborder", "0");
+  
+  // Add fallback handling
+  iframe.onerror = () => {
+    console.warn("[DAP] PDF iframe failed, showing fallback");
+    container.innerHTML = "";
+    const fallback = createFallbackViewer({ url, fileName, title: fileName }, 
+      "PDF preview failed. Please download or open in a new tab.");
+    container.appendChild(fallback);
+  };
+  
+  container.appendChild(iframe);
+  
+  // Add action buttons below PDF
+  const actions = createDocumentActions(url, fileName);
+  container.appendChild(actions);
+  
+  return container;
+}
+
+// Inline Document Viewer - attempts preview with Office Online, falls back gracefully
+function createInlineDocumentViewer(url: string, fileName: string, mimeType?: string | null): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-document-viewer-container";
+  
+  // Try Office Online viewer for DOC/DOCX
+  if (mimeType && (mimeType.includes("word") || mimeType.includes("msword"))) {
+    const iframe = document.createElement("iframe");
+    iframe.className = "dap-document-iframe";
+    iframe.src = `https://view.officeapps.live.com/op/embed.aspx?src=${encodeURIComponent(url)}`;
+    iframe.style.width = "100%";
+    iframe.style.height = "500px";
+    iframe.style.border = "1px solid #ddd";
+    iframe.setAttribute("frameborder", "0");
+    
+    // Add fallback handling
+    iframe.onerror = () => {
+      console.warn("[DAP] Office Online viewer failed, showing fallback");
+      container.innerHTML = "";
+      const fallback = createFallbackViewer({ url, fileName, title: fileName }, 
+        "Document preview is not available. Please download or open in a new tab.");
+      container.appendChild(fallback);
+    };
+    
+    container.appendChild(iframe);
+  } else {
+    // Direct fallback for unsupported document types
+    const fallback = createFallbackViewer({ url, fileName, title: fileName }, 
+      "Document preview is not supported for this file type.");
+    container.appendChild(fallback);
+  }
+  
+  // Add action buttons
+  const actions = createDocumentActions(url, fileName);
+  container.appendChild(actions);
+  
+  return container;
+}
+
+// Inline Presentation Viewer - attempts preview for PPT/PPTX
+function createInlinePresentationViewer(url: string, fileName: string, mimeType?: string | null): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-presentation-viewer-container";
+  
+  // Try Office Online viewer for PPT/PPTX
+  if (mimeType && mimeType.includes("presentation")) {
+    const iframe = document.createElement("iframe");
+    iframe.className = "dap-presentation-iframe";
+    iframe.src = `https://view.officeapps.live.com/op/embed.aspx?src=${encodeURIComponent(url)}`;
+    iframe.style.width = "100%";
+    iframe.style.height = "500px";
+    iframe.style.border = "1px solid #ddd";
+    iframe.setAttribute("frameborder", "0");
+    
+    // Add fallback handling
+    iframe.onerror = () => {
+      console.warn("[DAP] Office Online presentation viewer failed, showing fallback");
+      container.innerHTML = "";
+      const fallback = createFallbackViewer({ url, fileName, title: fileName }, 
+        "Presentation preview is not available. Please download or open in a new tab.");
+      container.appendChild(fallback);
+    };
+    
+    container.appendChild(iframe);
+  } else {
+    // Direct fallback for unsupported presentation types
+    const fallback = createFallbackViewer({ url, fileName, title: fileName }, 
+      "Presentation preview is not supported for this file type.");
+    container.appendChild(fallback);
+  }
+  
+  // Add action buttons
+  const actions = createDocumentActions(url, fileName);
+  container.appendChild(actions);
+  
+  return container;
+}
+
+// Fallback Viewer - shows clear message and action buttons when inline preview is not possible
+function createFallbackViewer(articleContent: any, message: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-fallback-viewer";
+  
+  const url = articleContent.url || articleContent.presignedUrl || "";
+  const fileName = articleContent.fileName || "Document";
+  
+  // Message
+  const messageEl = document.createElement("div");
+  messageEl.className = "dap-fallback-message";
+  messageEl.innerHTML = `
+    <p><strong>${message}</strong></p>
+    <p>File: ${fileName}</p>
+  `;
+  container.appendChild(messageEl);
+  
+  // Action buttons
+  const actions = createDocumentActions(url, fileName);
+  container.appendChild(actions);
+  
+  return container;
+}
+
+// Enhanced Fallback Viewer - improved version with better UX and error handling
+function createEnhancedFallbackViewer(articleContent: any, message: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-enhanced-fallback-viewer";
+  
+  const url = articleContent.url || articleContent.presignedUrl || "";
+  const fileName = articleContent.fileName || "Document";
+  const title = articleContent.title || fileName;
+  const fileExtension = fileName.split('.').pop()?.toUpperCase() || "";
+  
+  // Icon based on file type
+  const iconEl = document.createElement("div");
+  iconEl.className = "dap-fallback-icon";
+  if (fileExtension.includes('PDF')) {
+    iconEl.innerHTML = "📄";
+  } else if (['DOC', 'DOCX'].includes(fileExtension)) {
+    iconEl.innerHTML = "📝";
+  } else if (['PPT', 'PPTX'].includes(fileExtension)) {
+    iconEl.innerHTML = "📊";
+  } else if (['XLS', 'XLSX'].includes(fileExtension)) {
+    iconEl.innerHTML = "📈";
+  } else {
+    iconEl.innerHTML = "📰";
+  }
+  container.appendChild(iconEl);
+  
+  // Message with better formatting
+  const messageEl = document.createElement("div");
+  messageEl.className = "dap-enhanced-fallback-message";
+  messageEl.innerHTML = `
+    <h4>${title}</h4>
+    <p class="dap-fallback-primary">${message}</p>
+    ${fileName !== title ? `<p class="dap-fallback-filename">File: ${fileName}</p>` : ''}
+    ${fileExtension ? `<p class="dap-fallback-type">Type: ${fileExtension} Document</p>` : ''}
+  `;
+  container.appendChild(messageEl);
+  
+  // Action buttons with better styling
+  if (url) {
+    const actions = createEnhancedDocumentActions(url, fileName);
+    container.appendChild(actions);
+  } else {
+    const noUrlMessage = document.createElement("p");
+    noUrlMessage.className = "dap-fallback-no-url";
+    noUrlMessage.textContent = "No document link available.";
+    container.appendChild(noUrlMessage);
+  }
+  
+  return container;
+}
+
+// Web Content Viewer - for displaying web pages in an iframe
+function createWebContentViewer(url: string, title: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-web-viewer-container";
+  
+  // Create iframe for web content
+  const iframe = document.createElement("iframe");
+  iframe.className = "dap-web-iframe";
+  iframe.src = url;
+  iframe.style.width = "100%";
+  iframe.style.height = "600px";
+  iframe.style.border = "1px solid var(--dap-border)";
+  iframe.style.borderRadius = "4px";
+  iframe.setAttribute("frameborder", "0");
+  iframe.setAttribute("loading", "lazy");
+  
+  // Add error handling
+  iframe.onerror = () => {
+    console.warn("[DAP] Web content iframe failed, showing fallback");
+    container.innerHTML = "";
+    const fallback = createEnhancedFallbackViewer({ url, title, fileName: title }, 
+      "Web content could not be loaded. Please open in a new tab.");
+    container.appendChild(fallback);
+  };
+  
+  // Add iframe to container
+  container.appendChild(iframe);
+  
+  // Add action buttons
+  const actions = document.createElement("div");
+  actions.className = "dap-web-actions";
+  const openBtn = document.createElement("button");
+  openBtn.className = "dap-action-btn dap-open-btn";
+  openBtn.textContent = "Open in New Tab";
+  openBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    window.open(url, "_blank", "noopener,noreferrer");
+  });
+  actions.appendChild(openBtn);
+  container.appendChild(actions);
+  
+  return container;
+}
+
+// Enhanced Document Actions - improved version with better UX
+function createEnhancedDocumentActions(url: string, fileName: string): HTMLElement {
+  const actions = document.createElement("div");
+  actions.className = "dap-enhanced-document-actions";
+  
+  // Download button with icon
+  const downloadBtn = document.createElement("button");
+  downloadBtn.className = "dap-action-btn dap-download-btn dap-primary-btn";
+  downloadBtn.innerHTML = `
+    <span class="dap-btn-icon">⬇️</span>
+    <span class="dap-btn-text">Download</span>
+  `;
+  downloadBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    
+    // Create temporary download link
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = fileName || "download";
+    link.target = "_blank";
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    
+    // Show feedback
+    downloadBtn.innerHTML = `<span class="dap-btn-icon">✅</span><span class="dap-btn-text">Downloaded</span>`;
+    setTimeout(() => {
+      downloadBtn.innerHTML = `<span class="dap-btn-icon">⬇️</span><span class="dap-btn-text">Download</span>`;
+    }, 2000);
+  });
+  
+  // Open in new tab button with icon
+  const openBtn = document.createElement("button");
+  openBtn.className = "dap-action-btn dap-open-btn dap-secondary-btn";
+  openBtn.innerHTML = `
+    <span class="dap-btn-icon">🔗</span>
+    <span class="dap-btn-text">Open in New Tab</span>
+  `;
+  openBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    window.open(url, "_blank", "noopener,noreferrer");
+  });
+  
+  actions.appendChild(downloadBtn);
+  actions.appendChild(openBtn);
+  
+  return actions;
+}
+
+// Document Actions - reusable download and open buttons with proper event listeners
+function createDocumentActions(url: string, fileName: string): HTMLElement {
+  const actions = document.createElement("div");
+  actions.className = "dap-document-actions dap-modal-buttons";
+  
+  // Download button
+  const downloadBtn = document.createElement("button");
+  downloadBtn.className = "dap-action-btn dap-download-btn dap-modal-button primary";
+  downloadBtn.textContent = "Download";
+  downloadBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    
+    // Create temporary download link
+    const link = document.createElement("a");
+    link.href = url;
+    link.download = fileName || "download";
+    link.target = "_blank";
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+  });
+  
+  // Open in new tab button
+  const openBtn = document.createElement("button");
+  openBtn.className = "dap-action-btn dap-open-btn dap-modal-button secondary";
+  openBtn.textContent = "Open in New Tab";
+  openBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    window.open(url, "_blank", "noopener,noreferrer");
+  });
+  
+  actions.appendChild(downloadBtn);
+  actions.appendChild(openBtn);
+  
+  return actions;
+}
+
+function createDocumentViewer(url: string, fileName?: string, type?: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-kb-document-container";
+  
+  // For docs, provide download/open options since inline viewing is limited
+  container.innerHTML = `
+    <div class="dap-kb-document-info">
+      <h4>${fileName || "Document"}</h4>
+      <p>Document type: ${type?.toUpperCase()}</p>
+      <div class="dap-kb-document-actions">
+        <button class="dap-kb-download-btn" onclick="window.open('${url}', '_blank')">
+          Open in New Tab
+        </button>
+        <button class="dap-kb-download-btn" onclick="downloadFile('${url}', '${fileName}')">
+          Download
+        </button>
+      </div>
+    </div>
+  `;
+  
+  return container;
+}
+
+function createYouTubeViewer(url: string): HTMLElement {
+  const iframe = document.createElement("iframe");
+  iframe.className = "dap-kb-youtube";
+  iframe.src = url;
+  iframe.style.width = "100%";
+  iframe.style.height = "315px";
+  iframe.setAttribute("frameborder", "0");
+  iframe.setAttribute("allowfullscreen", "true");
+  
+  return iframe;
+}
+
+function createLinkViewer(url: string, title?: string, description?: string): HTMLElement {
+  const container = document.createElement("div");
+  container.className = "dap-kb-link-container";
+  
+  container.innerHTML = `
+    <div class="dap-kb-link-info">
+      <h4>${title || "External Link"}</h4>
+      ${description ? `<p>${description}</p>` : ''}
+      <p><strong>URL:</strong> ${url}</p>
+      <button class="dap-kb-external-btn" onclick="window.open('${url}', '_blank')">
+        Open Link in New Tab
+      </button>
+    </div>
+  `;
+  
+  return container;
+}
+
+function detectContentType(url: string, fileName?: string): string {
+  const path = fileName || url;
+  const ext = path.split('.').pop()?.toLowerCase();
+  
+  if (ext === 'pdf') return 'pdf';
+  if (['doc', 'docx'].includes(ext || '')) return ext || 'doc';
+  if (['mp4', 'webm', 'ogg', 'avi', 'mov'].includes(ext || '')) return 'video';
+  if (['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg'].includes(ext || '')) return 'image';
+  if (url.includes('youtube.com') || url.includes('youtu.be')) return 'youtube';
+  
+  return 'link';
+}
+
+// KB State Management - maintains explicit state across view transitions
+let kbState: {
+  view: "list" | "item";
+  items: any[];
+  selectedItem: any | null;
+  title: string;
+  modalBodyRef: HTMLElement | null;
+} | null = null;
+
+// Helper function to create file type badge
+function createFileTypeBadge(itemType: string, fileName?: string): HTMLElement {
+  const badge = document.createElement("div");
+  badge.className = `dap-file-type-badge ${itemType}`;
+  
+  let icon = "";
+  let label = "";
+  
+  switch (itemType) {
+    case "video":
+      icon = "🎥";
+      label = "Video";
+      break;
+    case "image":
+      icon = "🖼️";
+      label = "Image";
+      break;
+    case "pdf":
+      icon = "📄";
+      label = "PDF";
+      break;
+    case "docx":
+    case "doc":
+      icon = "📝";
+      label = "Document";
+      break;
+    case "pptx":
+    case "ppt":
+      icon = "📊";
+      label = "Presentation";
+      break;
+    case "xlsx":
+    case "xls":
+      icon = "📈";
+      label = "Spreadsheet";
+      break;
+    case "article":
+    default:
+      icon = "📰";
+      label = "Article";
+      break;
+  }
+  
+  badge.innerHTML = `<span>${icon}</span> ${label}`;
+  
+  return badge;
+}
+
+function openKBItemInModal(item: any, kbTitle?: string) {
+  console.debug("[DAP] Opening KB item in modal:", item);
+  console.debug("[DAP] KB view changed to item");
+  
+  // Find the current modal body
+  const modalBody = document.querySelector('.dap-modal-body') as HTMLElement;
+  if (!modalBody) {
+    console.error("[DAP] Could not find modal body for KB item viewing");
+    return;
+  }
+  
+  // Update KB state for item view
+  if (kbState) {
+    kbState.view = "item";
+    kbState.selectedItem = item;
+    kbState.modalBodyRef = modalBody;
+    
+    console.debug("[DAP] KB items count:", kbState.items.length);
+  } else {
+    console.error("[DAP] KB state not initialized when opening item");
+    return;
+  }
+  
+  // Create KB item viewer content
+  const viewerContent = {
+    kind: "kb-item-viewer",
+    item: item,
+    kbTitle: kbTitle
+  };
+  
+  // Clear modal body and add viewer
+  modalBody.innerHTML = '';
+  const viewerEl = renderKBItemViewer(viewerContent);
+  modalBody.appendChild(viewerEl);
+}
+
+function goBackToKBList() {
+  console.debug("[DAP] Going back to KB list");
+  console.debug("[DAP] KB view changed to list");
+  
+  if (!kbState || !kbState.modalBodyRef) {
+    console.error("[DAP] Cannot go back: missing KB state or modal reference");
+    return;
+  }
+  
+  console.debug("[DAP] KB items count:", kbState.items.length);
+  
+  // Update KB state for list view
+  kbState.view = "list";
+  kbState.selectedItem = null;
+  
+  // Prepare KB content for rendering
+  const kbContent = {
+    title: kbState.title,
+    items: kbState.items
+  };
+  
+  // Clear modal body and restore KB list using preserved state
+  kbState.modalBodyRef.innerHTML = '';
+  const kbListEl = renderKnowledgeBase(kbContent);
+  kbState.modalBodyRef.appendChild(kbListEl);
+}
+
+// Utility function for file downloads
+function downloadFile(url: string, fileName?: string) {
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = fileName || 'download';
+  document.body.appendChild(a);
+  a.click();
+  document.body.removeChild(a);
+}
+
+function ensureStyles() {
+  if (!document.getElementById("dap-modal-style")) {
+    const style = document.createElement("style");
+    style.id = "dap-modal-style";
+    style.textContent = modalCssText;
+    document.head.appendChild(style);
+  }
+}