@gemx-dev/clarity-visualize 0.8.52 → 0.8.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemx-dev/clarity-visualize",
-  "version": "0.8.52",
+  "version": "0.8.54",
   "description": "Clarity visualize",
   "author": "Microsoft Corp.",
   "license": "MIT",
@@ -9,7 +9,7 @@
   "unpkg": "build/clarity.visualize.min.js",
   "types": "types/index.d.ts",
   "dependencies": {
-    "@gemx-dev/clarity-decode": "^0.8.52"
+    "@gemx-dev/clarity-decode": "^0.8.54"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^24.0.0",

package/src/custom/README.md

@@ -12,6 +12,33 @@ All custom modules follow the functional module pattern:
 
 ## Modules
 
+### Canvas Layer Module (`canvas-layer.ts`)
+
+Manages canvas z-index and stacking context with top-layer elements (modal dialogs).
+
+**Functions:**
+
+- `getOpenDialogs(doc)` - Gets all open modal dialogs
+- `hideDialogsTemporarily(doc)` - Hides modal dialogs and returns restore function
+- `setupCanvasLayer(canvas, options)` - Sets up canvas with proper layer handling
+- `applyCanvasLayerWithDialogAwareness(canvas, onShow, onHide)` - Dialog-aware canvas management
+
+**Usage:**
+
+```typescript
+import * as canvasLayer from "./custom/canvas-layer";
+
+// Hide dialogs when showing heatmap
+const restoreDialogs = canvasLayer.hideDialogsTemporarily(doc);
+
+// Later, restore dialogs
+restoreDialogs();
+```
+
+**Why this is needed:**
+
+Modal dialogs use the browser's **top-layer**, which has a higher stacking context than any z-index value (even `z-index: 2147483647`). This module temporarily hides modal dialogs when the heatmap canvas is active, ensuring the canvas is visible.
+
 ### Dialog Module (`dialog.ts`)
 
 Renders HTML `<dialog>` elements with proper top-layer and backdrop support.

package/src/custom/canvas-layer.ts

@@ -0,0 +1,351 @@
+import { Constant, Setting } from "@clarity-types/visualize";
+
+/**
+ * Custom module for managing canvas layer z-index with dialog top-layer
+ * Handles stacking context when modal dialogs are present
+ *
+ * Strategy: Render canvas in parent window (outside iframe) to avoid
+ * z-index conflicts with top-layer elements inside the iframe
+ */
+
+export interface CanvasLayerOptions {
+    strategy: 'parent-window' | 'max-z-index' | 'hide-dialogs' | 'popover';
+}
+
+export interface ParentCanvasInfo {
+    canvas: HTMLCanvasElement;
+    iframe: HTMLIFrameElement;
+    cleanup: () => void;
+}
+
+/**
+ * Creates a canvas as sibling to the iframe (same parent container)
+ * This allows the canvas to avoid z-index conflicts with top-layer elements inside iframe
+ *
+ * @param iframeDoc - Document inside the iframe
+ * @param canvasId - ID for the canvas element
+ * @returns Canvas info with cleanup function
+ */
+export function createParentWindowCanvas(
+    iframeDoc: Document,
+): ParentCanvasInfo | null {
+    // Check if we're inside an iframe
+    if (iframeDoc.defaultView === iframeDoc.defaultView?.top) {
+        throw new Error('Not in iframe: ' + iframeDoc.defaultView);
+    }
+
+    try {
+        const parentWindow = iframeDoc.defaultView?.parent;
+        const parentDoc = parentWindow?.document;
+        if (!parentDoc) throw new Error('Parent document not found');
+
+        const iframe = parentDoc.getElementById('clarity-iframe');
+        if (!iframe) throw new Error('Iframe not found');
+
+        const targetIframe = iframe as HTMLIFrameElement;
+        const iframeParent = targetIframe.parentElement;
+        if (!iframeParent) throw new Error('Iframe parent not found');
+
+        // Create canvas as sibling to iframe
+        let canvas = parentDoc.getElementById(Constant.HeatmapCanvas) as HTMLCanvasElement;
+        if (canvas === null) {
+            canvas = parentDoc.createElement('canvas');
+            canvas.id = Constant.HeatmapCanvas;
+            canvas.width = 0;
+            canvas.height = 0;
+            // canvas.style.position = Constant.Absolute;
+            canvas.style.zIndex = `${Setting.ZIndex}`;
+            canvas.style.pointerEvents = 'none'; // Allow clicks to pass through
+            iframeParent.appendChild(canvas);
+        }
+
+        // // Set canvas size to match iframe
+        // const updateCanvasSize = () => {
+        //     canvas.width = targetIframe!.offsetWidth;
+        //     canvas.height = targetIframe!.offsetHeight;
+        // };
+
+        // updateCanvasSize();
+
+        // Insert canvas as sibling to iframe (in same parent container)
+        // iframeParent.appendChild(canvas);
+
+        // Update size on resize
+        // const handleUpdate = () => updateCanvasSize();
+        // parentWindow!.addEventListener('resize', handleUpdate, true);
+
+        const cleanup = () => {
+            // parentWindow!.removeEventListener('resize', handleUpdate, true);
+            if (canvas.parentNode) {
+                canvas.parentNode.removeChild(canvas);
+            }
+        };
+
+        return {
+            canvas,
+            iframe: targetIframe,
+            cleanup
+        };
+    } catch (e) {
+        throw new Error(e);
+    }
+}
+
+// ======================================================== //
+// ======================================================== //
+
+
+/**
+ * Gets all open modal dialogs in the document
+ */
+export function getOpenDialogs(doc: Document): HTMLDialogElement[] {
+    const dialogs = Array.from(doc.querySelectorAll('dialog[open]'));
+    return dialogs.filter(d => {
+        const dialog = d as HTMLDialogElement;
+        // Check if it's a modal dialog (in top-layer)
+        try {
+            const backdropStyle = window.getComputedStyle(dialog, '::backdrop');
+            return backdropStyle.getPropertyValue('display') !== 'none';
+        } catch {
+            return false;
+        }
+    }) as HTMLDialogElement[];
+}
+
+/**
+ * Temporarily hides modal dialogs to allow canvas to be visible
+ * Returns a restore function to bring dialogs back
+ */
+export function hideDialogsTemporarily(doc: Document): () => void {
+    const dialogs = getOpenDialogs(doc);
+    const dialogStates: Array<{ dialog: HTMLDialogElement; wasOpen: boolean }> = [];
+
+    dialogs.forEach(dialog => {
+        if (dialog.open) {
+            dialogStates.push({ dialog, wasOpen: true });
+            dialog.close();
+        }
+    });
+
+    // Return restore function
+    return () => {
+        dialogStates.forEach(({ dialog, wasOpen }) => {
+            if (wasOpen && !dialog.open) {
+                try {
+                    dialog.showModal();
+                } catch (e) {
+                    console.warn('Failed to restore dialog:', e);
+                }
+            }
+        });
+    };
+}
+
+/**
+ * Sets up canvas with proper z-index handling
+ *
+ * @param canvas - The canvas element
+ * @param options - Layer options
+ * @returns Cleanup function
+ */
+export function setupCanvasLayer(
+    canvas: HTMLCanvasElement,
+    options: CanvasLayerOptions = { strategy: 'max-z-index' }
+): () => void {
+    switch (options.strategy) {
+        case 'hide-dialogs':
+            // Hide dialogs when canvas is active
+            return hideDialogsTemporarily(canvas.ownerDocument);
+
+        case 'popover':
+            // Use Popover API if available (also uses top-layer)
+            if ('popover' in canvas) {
+                try {
+                    (canvas as any).popover = 'manual';
+                    (canvas as any).showPopover();
+                    return () => {
+                        try {
+                            (canvas as any).hidePopover();
+                        } catch (e) {
+                            // Ignore
+                        }
+                    };
+                } catch (e) {
+                    console.warn('Popover API not available, falling back to max z-index');
+                }
+            }
+            // Fallback to max-z-index
+            return () => {};
+
+        case 'max-z-index':
+        default:
+            // Use maximum z-index (works for non-modal content)
+            // Modal dialogs will still be on top due to top-layer
+            return () => {};
+    }
+}
+
+
+
+/**
+ * Synchronizes canvas content from iframe to parent window canvas
+ *
+ * @param iframeCanvas - Canvas inside iframe
+ * @param parentCanvas - Canvas in parent window
+ */
+export function syncCanvasContent(
+    iframeCanvas: HTMLCanvasElement,
+    parentCanvas: HTMLCanvasElement
+): void {
+    const ctx = parentCanvas.getContext('2d');
+    if (ctx) {
+        ctx.clearRect(0, 0, parentCanvas.width, parentCanvas.height);
+        ctx.drawImage(iframeCanvas, 0, 0);
+    }
+}
+
+/**
+ * Alternative approach: Make dialogs "transparent" for rendering
+ * Sets pointer-events: none on dialogs so canvas can render on top
+ */
+export function makeDialogsTransparent(doc: Document): () => void {
+    const dialogs = Array.from(doc.querySelectorAll('dialog[open]')) as HTMLDialogElement[];
+    const originalStyles: Map<HTMLDialogElement, string> = new Map();
+
+    dialogs.forEach((dialog) => {
+        originalStyles.set(dialog, dialog.style.pointerEvents || '');
+        dialog.style.pointerEvents = 'none';
+        dialog.style.zIndex = '2147483646'; // Just below canvas
+    });
+
+    // Return restore function
+    return () => {
+        dialogs.forEach((dialog) => {
+            const original = originalStyles.get(dialog);
+            if (original !== undefined) {
+                dialog.style.pointerEvents = original;
+                dialog.style.zIndex = '';
+            }
+        });
+    };
+}
+
+/**
+ * Solution 3: Lower dialog z-index temporarily
+ * Moves dialog out of top-layer by closing and re-showing as non-modal
+ */
+export function lowerDialogZIndex(doc: Document): () => void {
+    const dialogs = getOpenDialogs(doc);
+    const dialogStates: Array<{ dialog: HTMLDialogElement; wasModal: boolean }> = [];
+
+    dialogs.forEach((dialog) => {
+        const wasModal = true; // If it's in getOpenDialogs, it's modal
+        dialogStates.push({ dialog, wasModal });
+
+        // Close modal and reopen as non-modal (removes from top-layer)
+        dialog.close();
+        dialog.show(); // Non-modal, can be controlled by z-index
+        dialog.style.zIndex = '2147483646'; // Below canvas
+    });
+
+    // Return restore function
+    return () => {
+        dialogStates.forEach(({ dialog, wasModal }) => {
+            if (wasModal) {
+                dialog.close();
+                try {
+                    dialog.showModal(); // Restore to top-layer
+                    dialog.style.zIndex = '';
+                } catch (e) {
+                    console.warn('Failed to restore modal dialog:', e);
+                }
+            }
+        });
+    };
+}
+
+/**
+ * Solution 4: Use mix-blend-mode to render canvas "through" dialog
+ * This is experimental and may not work in all browsers
+ */
+export function setupCanvasBlendMode(canvas: HTMLCanvasElement): void {
+    canvas.style.mixBlendMode = 'multiply';
+    canvas.style.isolation = 'isolate';
+}
+
+/**
+ * Master function: Apply best strategy based on context
+ * Tries multiple approaches in order of preference
+ */
+export function applyBestCanvasStrategy(
+    doc: Document,
+    canvasId: string,
+    strategy?: 'parent-window' | 'lower-dialog' | 'transparent' | 'auto'
+): { canvas: HTMLCanvasElement | null; cleanup: () => void } | null {
+    const selectedStrategy = strategy || 'auto';
+
+    // Strategy 1: Parent window canvas (best for iframe contexts)
+    if (selectedStrategy === 'auto' || selectedStrategy === 'parent-window') {
+        const parentCanvas = createParentWindowCanvas(doc);
+        if (parentCanvas) {
+            return {
+                canvas: parentCanvas.canvas,
+                cleanup: parentCanvas.cleanup
+            };
+        }
+    }
+
+    // Strategy 2: Lower dialog z-index (converts modal to non-modal temporarily)
+    if (selectedStrategy === 'auto' || selectedStrategy === 'lower-dialog') {
+        const canvas = doc.getElementById(canvasId) as HTMLCanvasElement;
+        if (canvas) {
+            const restore = lowerDialogZIndex(doc);
+            return {
+                canvas,
+                cleanup: restore
+            };
+        }
+    }
+
+    // Strategy 3: Make dialogs transparent (least intrusive)
+    if (selectedStrategy === 'auto' || selectedStrategy === 'transparent') {
+        const canvas = doc.getElementById(canvasId) as HTMLCanvasElement;
+        if (canvas) {
+            const restore = makeDialogsTransparent(doc);
+            return {
+                canvas,
+                cleanup: restore
+            };
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Applies canvas layer with dialog awareness
+ * This is the recommended approach: hide dialogs temporarily while heatmap is active
+ */
+export function applyCanvasLayerWithDialogAwareness(
+    canvas: HTMLCanvasElement,
+    onShow?: () => void,
+    onHide?: () => void
+): { show: () => void; hide: () => void } {
+    let restoreDialogs: (() => void) | null = null;
+
+    return {
+        show: () => {
+            // Hide dialogs when showing canvas
+            restoreDialogs = hideDialogsTemporarily(canvas.ownerDocument);
+            if (onShow) onShow();
+        },
+        hide: () => {
+            // Restore dialogs when hiding canvas
+            if (restoreDialogs) {
+                restoreDialogs();
+                restoreDialogs = null;
+            }
+            if (onHide) onHide();
+        }
+    };
+}

package/src/custom/dialog.ts

@@ -11,6 +11,47 @@ export interface DialogRenderOptions {
     isExistingDialog: boolean;
 }
 
+/**
+ * Pending dialogs tracking for synchronization
+ * Used to track when all dialogs have finished rendering
+ * Uses Set to avoid counting the same dialog multiple times
+ */
+let pendingDialogs: Set<HTMLDialogElement> = new Set();
+let resolveDialogsRendered: (() => void) | null = null;
+let dialogsRenderedPromise: Promise<void> | null = null;
+
+/**
+ * Returns a promise that resolves when all pending dialogs are rendered
+ */
+export function waitForDialogsRendered(): Promise<void> {
+    if (pendingDialogs.size === 0) {
+        // No pending dialogs, resolve immediately
+        return Promise.resolve();
+    }
+
+    // Return existing promise if already waiting
+    if (dialogsRenderedPromise) {
+        return dialogsRenderedPromise;
+    }
+
+    // Create new promise
+    dialogsRenderedPromise = new Promise<void>((resolve) => {
+        resolveDialogsRendered = resolve;
+    });
+
+    return dialogsRenderedPromise;
+}
+
+/**
+ * Resets the dialog rendering state
+ * Should be called before starting a new render cycle
+ */
+export function resetDialogRenderState(): void {
+    pendingDialogs.clear();
+    resolveDialogsRendered = null;
+    dialogsRenderedPromise = null;
+}
+
 /**
  * Extracts dialog rendering options from node attributes
  *
@@ -45,27 +86,101 @@ export function showDialog(
 ): void {
     try {
         if (!dialogElement.isConnected) {
-            console.warn('⚠️ Dialog not connected to DOM, skipping show');
+            notifyDialogComplete(dialogElement);
             return;
         }
-
-        // IMPORTANT: If dialog is already open (from HTML attribute),
-        // we need to close and reopen to ensure showModal() is called
-        // and dialog enters top-layer properly
-        if (dialogElement.open) {
-            dialogElement.close();
+        if (!dialogElement.open) {
+            notifyDialogComplete(dialogElement);
+            return;
         }
 
+        dialogElement.close();
         if (isModal) {
             dialogElement.showModal();
         } else {
             dialogElement.show();
         }
+
+        // Wait for animations/transitions to complete
+        waitForDialogAnimation(dialogElement).then(() => {
+            notifyDialogComplete(dialogElement);
+        });
     } catch (e) {
         console.error('❌ Error showing dialog:', e);
         if (onError) {
             onError(e as Error);
         }
+        // Still mark as complete even on error
+        notifyDialogComplete(dialogElement);
+    }
+}
+
+/**
+ * Waits for dialog animations/transitions to complete
+ * Listens for animationend and transitionend events with timeout fallback
+ */
+function waitForDialogAnimation(dialogElement: HTMLDialogElement): Promise<void> {
+    return new Promise((resolve) => {
+        let resolved = false;
+        const timeoutMs = 1000; // Maximum wait time for animations
+
+        const complete = () => {
+            if (resolved) return;
+            resolved = true;
+            cleanup();
+            resolve();
+        };
+
+        // Fallback timeout in case no animation events fire
+        const timeout = setTimeout(complete, timeoutMs);
+
+        // Listen for animation end
+        const onAnimationEnd = (e: AnimationEvent) => {
+            if (e.target === dialogElement) {
+                complete();
+            }
+        };
+
+        // Listen for transition end
+        const onTransitionEnd = (TransitionEvent: TransitionEvent) => {
+            if (TransitionEvent.target === dialogElement) {
+                complete();
+            }
+        };
+
+        const cleanup = () => {
+            clearTimeout(timeout);
+            dialogElement.removeEventListener('animationend', onAnimationEnd as EventListener);
+            dialogElement.removeEventListener('transitionend', onTransitionEnd as EventListener);
+        };
+
+        dialogElement.addEventListener('animationend', onAnimationEnd as EventListener, { once: true });
+        dialogElement.addEventListener('transitionend', onTransitionEnd as EventListener, { once: true });
+
+        // If no animations/transitions, resolve after one frame
+        requestAnimationFrame(() => {
+            const computedStyle = window.getComputedStyle(dialogElement);
+            const hasAnimation = computedStyle.animationName !== 'none';
+            const hasTransition = computedStyle.transitionDuration !== '0s';
+
+            if (!hasAnimation && !hasTransition) {
+                complete();
+            }
+        });
+    });
+}
+
+/**
+ * Internal: Notify that a dialog has completed rendering
+ */
+function notifyDialogComplete(dialogElement: HTMLDialogElement): void {
+    pendingDialogs.delete(dialogElement);
+
+    // If all dialogs are done, resolve the promise
+    if (pendingDialogs.size === 0 && resolveDialogsRendered) {
+        resolveDialogsRendered();
+        resolveDialogsRendered = null;
+        dialogsRenderedPromise = null;
     }
 }
 
@@ -98,20 +213,16 @@ export function renderDialog(
     onError?: (error: Error) => void
 ): void {
     const { isModal, shouldBeOpen, isExistingDialog } = options;
+    if (!shouldBeOpen) return;
 
-    if (shouldBeOpen) {
-        const doShow = () => showDialog(dialogElement, isModal, onError);
+    // Add dialog to pending set (Set automatically handles duplicates)
+    pendingDialogs.add(dialogElement);
 
-        if (isExistingDialog) {
-            // Dialog already exists, call immediately
-            doShow();
-        } else {
-            // New dialog, wait for DOM insertion
-            setTimeout(doShow, 0);
-        }
-    } else if (dialogElement.open) {
-        // Dialog should be closed
-        closeDialog(dialogElement);
+    const doShow = () => showDialog(dialogElement, isModal, onError);
+    if (isExistingDialog) {
+        doShow();
+    } else {
+        setTimeout(doShow, 0);
     }
 }
 

package/src/custom/index.ts

@@ -4,3 +4,4 @@
  */
 
 export * from "./dialog";
+export * from "./canvas-layer";