@gem-sdk/clarity-visualize 0.8.94

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@gem-sdk/clarity-visualize",
+  "version": "0.8.94",
+  "description": "Clarity visualize",
+  "author": "Microsoft Corp.",
+  "license": "MIT",
+  "main": "build/clarity.visualize.js",
+  "module": "build/clarity.visualize.module.js",
+  "unpkg": "build/clarity.visualize.min.js",
+  "types": "types/index.d.ts",
+  "dependencies": {
+    "@gem-sdk/clarity-decode": "^0.8.94"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^24.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-terser": "^0.4.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "rollup-plugin-string-import": "^1.2.5",
+    "del-cli": "^5.0.0",
+    "husky": "^8.0.0",
+    "lint-staged": "^13.1.0",
+    "rollup": "^3.0.0",
+    "tslint": "^6.1.3",
+    "typescript": "^4.3.5"
+  },
+  "scripts": {
+    "build": "yarn build:clean && yarn build:main",
+    "build:main": "rollup -c rollup.config.ts --configPlugin @rollup/plugin-typescript",
+    "build:clean": "del-cli build/*",
+    "tslint": "tslint --project ./",
+    "tslint:fix": "tslint --fix --project ./ --force"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.ts": [
+      "tslint --format codeFrame"
+    ]
+  },
+  "source": "src/index.ts"
+}

package/rollup.config.ts

@@ -0,0 +1,79 @@
+import commonjs from "@rollup/plugin-commonjs";
+import resolve from "@rollup/plugin-node-resolve";
+import terser from "@rollup/plugin-terser";
+import typescript from "@rollup/plugin-typescript";
+import { importAsString } from 'rollup-plugin-string-import';
+import { readFileSync } from "fs";
+
+const pkg = JSON.parse(readFileSync("./package.json", "utf-8"));
+
+function wrapWithBackground(svg){
+  return `background: url("data:image/svg+xml,${svg}") no-repeat center center;`;
+}
+
+function regexEncode(svg){
+  svg = svg.replace(/>\s{1,}</g, `><`);
+  svg = svg.replace(/\s{2,}/g, ` `);
+  return svg.replace(/[\r\n%#()<>?[\\\]^`{|}]/g, encodeURIComponent)
+}
+
+function doublesToSingles(svg){
+  return svg.replace(/"/g, "'")
+}
+
+function preprocessFile(content: string, fileName: string): string {
+  if (fileName.endsWith(".css")) {
+    // remove comments/newlines
+    return content.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, "").replace(/\r\n/g, "");
+  }
+  else if (fileName.endsWith(".svg")) {
+    // removes comments/newlines while also encoding the svg and adding some scaffolding to import it
+    return wrapWithBackground(regexEncode(doublesToSingles(content)));
+  }
+  return "";
+}
+
+export default [
+  {
+    input: "src/index.ts",
+    output: [
+      { file: pkg.main, format: "cjs", exports: "named" },
+      { file: pkg.module, format: "es", exports: "named" }
+    ],
+    plugins: [
+      resolve(),
+      importAsString({ 
+        include: ["**/*.css", "**/*.svg"],
+        transform: preprocessFile,
+      }),
+      typescript(),
+      commonjs({ include: ["node_modules/**"] })
+    ],
+    onwarn(message, warn) {
+      if (message.code === 'NON_EXISTENT_EXPORT') { return; }
+      if (message.code === 'CIRCULAR_DEPENDENCY') { return; }
+      if (message.code === 'SOURCEMAP_ERROR') { return; }
+      warn(message);
+    }
+  },
+  {
+    input: "src/global.ts",
+    output: [ { file: pkg.unpkg, format: "iife", exports: "named" } ],
+    plugins: [
+      resolve(),      
+      importAsString({ 
+        include: ["**/*.css", "**/*.svg"],
+        transform: preprocessFile,
+      }),
+      typescript(),
+      terser({output: {comments: false}}),
+      commonjs({ include: ["node_modules/**"] })
+    ],
+    onwarn(message, warn) {
+      if (message.code === 'NON_EXISTENT_EXPORT') { return; }
+      if (message.code === 'CIRCULAR_DEPENDENCY') { return; }
+      if (message.code === 'SOURCEMAP_ERROR') { return; }
+      warn(message);
+    }
+  }
+];

package/src/clarity.ts

@@ -0,0 +1,3 @@
+import { Visualizer } from "./visualizer";
+
+export const { state, dom, get, html, time, clickmap, clearmap, scrollmap, merge, setup, render } = new Visualizer();

package/src/custom/README.md

@@ -0,0 +1,87 @@
+# Custom Clarity Visualize Modules
+
+This directory contains custom rendering modules that extend the base Clarity visualization for GemX.
+
+## Structure
+
+All custom modules follow the functional module pattern:
+- Pure functions for testability
+- No side effects in utility functions
+- Clear separation of concerns
+- Type-safe interfaces
+
+## 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.
+
+**Functions:**
+
+- `getDialogRenderOptions(attributes, dialogElement)` - Extracts rendering options from attributes
+- `showDialog(dialogElement, isModal, onError)` - Shows dialog with proper modal/non-modal handling
+- `closeDialog(dialogElement)` - Safely closes a dialog
+- `renderDialog(dialogElement, options, onError)` - Main entry point for dialog rendering
+- `cleanDialogAttributes(attributes)` - Removes internal tracking attributes
+
+**Usage:**
+
+```typescript
+import * as dialogCustom from "./custom/dialog";
+
+const renderOptions = dialogCustom.getDialogRenderOptions(node.attributes, dialogElement);
+node.attributes = dialogCustom.cleanDialogAttributes(node.attributes);
+
+dialogCustom.renderDialog(
+    dialogElement,
+    renderOptions,
+    this.state.options.logerror
+);
+```
+
+**Features:**
+
+- Automatic detection of modal vs non-modal dialogs
+- Proper top-layer rendering via `showModal()`
+- Backdrop support for modal dialogs
+- Handles dialogs already open from HTML attributes
+- Error handling and logging
+
+## Adding New Custom Modules
+
+1. Create a new file in this directory (e.g., `my-feature.ts`)
+2. Follow the functional module pattern
+3. Export functions with clear type signatures
+4. Add exports to `index.ts`
+5. Document the module in this README
+
+## Testing
+
+Custom modules should be unit tested separately from the main Clarity codebase.

package/src/custom/canvas-layer.ts

@@ -0,0 +1,355 @@
+import { Constant } 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,
+    portalCanvasId: string
+): 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 iframeId = `clarity-iframe-${portalCanvasId}`;
+        const iframe = parentDoc.getElementById(iframeId);
+        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
+        const canvasId = `${Constant.HeatmapCanvas}-${portalCanvasId}`;
+        let canvas = parentDoc.getElementById(canvasId) as HTMLCanvasElement;
+        if (canvas === null) {
+            canvas = parentDoc.createElement('canvas');
+            canvas.id = canvasId;
+            canvas.classList.add(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, canvasId);
+        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();
+        }
+    };
+}