@gem-sdk/clarity-visualize 0.8.94

package/src/heatmap.ts

@@ -0,0 +1,512 @@
+import { Activity, Constant, Heatmap, Setting, ScrollMapInfo, PlaybackState } from "@clarity-types/visualize";
+import { Data } from "@gem-sdk/clarity-js";
+import { LayoutHelper } from "./layout";
+
+import * as canvasLayer from "./custom/canvas-layer";
+import * as dialogCustom from "./custom/dialog";
+
+export class HeatmapHelper {
+    static COLORS = ["blue", "cyan", "lime", "yellow", "red"];
+    data: Activity = null;
+    scrollData: ScrollMapInfo[] = null;
+    max: number = null;
+    offscreenRing: HTMLCanvasElement = null;
+    gradientPixels: ImageData = null;
+    timeout = null;
+    observer: ResizeObserver = null;
+    state: PlaybackState = null;
+    layout: LayoutHelper = null;
+    scrollAvgFold: number = null;
+    addScrollMakers: boolean = false;
+    parentCanvasInfo: canvasLayer.ParentCanvasInfo | null = null;
+
+    constructor(state: PlaybackState, layout: LayoutHelper) {
+        this.state = state;
+        this.layout = layout;
+    }
+
+    public reset = (): void => {
+        this.data = null;
+        this.scrollData = null;
+        this.max = null;
+        this.offscreenRing = null;
+        this.gradientPixels = null;
+        this.timeout = null;
+
+        // Cleanup parent canvas if it exists
+        if (this.parentCanvasInfo) {
+            this.parentCanvasInfo.cleanup();
+            this.parentCanvasInfo = null;
+        }
+
+        // Reset resize observer
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+
+        // Remove scroll, resize, and animation event listeners
+        if (this.state && this.state.window) {
+            let win = this.state.window;
+            win.removeEventListener("scroll", this.redraw, { capture: true });
+            win.removeEventListener("resize", this.redraw, { capture: true });
+            win.removeEventListener("animationend", this.redraw, true);
+            win.removeEventListener("transitionend", this.redraw, true);
+        }
+    }
+
+    public clear = (): void => {
+        let doc = this.state.window.document;
+        let win = this.state.window;
+        let canvas = doc.getElementById(Constant.HeatmapCanvas) as HTMLCanvasElement;
+        let de = doc.documentElement;
+        if (canvas) {
+            canvas.width = de.clientWidth;
+            canvas.height = de.clientHeight;
+            canvas.style.left = win.pageXOffset + Constant.Pixel;
+            canvas.style.top = win.pageYOffset + Constant.Pixel;
+            canvas.getContext(Constant.Context).clearRect(0, 0, canvas.width, canvas.height);
+        }
+
+        // Cleanup parent canvas before reset
+        if (this.parentCanvasInfo) {
+            this.parentCanvasInfo.cleanup();
+            this.parentCanvasInfo = null;
+        }
+
+        this.reset();
+    }
+
+    public scroll = async (activity: ScrollMapInfo[], avgFold: number, addMarkers: boolean): Promise<void> => {
+        await this.waitForDialogs();
+        await this.waitForAllAnimations();
+        
+        this.scrollData = this.scrollData || activity;
+        this.scrollAvgFold = avgFold != null ? avgFold : this.scrollAvgFold;
+        this.addScrollMakers = addMarkers != null ? addMarkers : this.addScrollMakers;
+
+        let canvas = this.overlay();
+        let context = canvas.getContext(Constant.Context);
+        let doc = this.state.window.document;
+        var body = doc.body;
+        var de = doc.documentElement;
+        var height = Math.max(body.scrollHeight, body.offsetHeight,
+            de.clientHeight, de.scrollHeight, de.offsetHeight);
+        canvas.height = Math.min(height, Setting.ScrollCanvasMaxHeight);
+        canvas.style.top = 0 + Constant.Pixel;
+        if (canvas.width > 0 && canvas.height > 0) {
+            if (this.scrollData) {
+                const grd = context.createLinearGradient(0, 0, 0, canvas.height);
+                for (const currentCombination of this.scrollData) {
+                    const huePercentView = 1 - (currentCombination.cumulativeSum / this.scrollData[0].cumulativeSum);
+                    const percentView = (currentCombination.scrollReachY / 100) * (height / canvas.height);
+                    const hue = huePercentView * Setting.MaxHue;
+                    if (percentView <= 1) {
+                        if (!isNaN(hue)) {
+                            grd.addColorStop(percentView, `hsla(${hue}, 100%, 50%, 0.6)`);
+                        }
+                    }
+                }
+
+                // Fill with gradient
+                context.fillStyle = grd;
+                context.fillRect(0, 0, canvas.width, canvas.height);
+                if (this.addScrollMakers) {
+                    this.addInfoMarkers(context, this.scrollData, canvas.width, canvas.height, this.scrollAvgFold);
+                }
+            }
+        };
+    }
+
+    private addInfoMarkers = (context: CanvasRenderingContext2D, scrollMapInfo: ScrollMapInfo[], width: number, height: number, avgFold: number): void => {
+        this.addMarker(context, width, Constant.AverageFold, avgFold, Setting.MarkerMediumWidth);
+        const markers = [75, 50, 25];
+        for (const marker of markers) {
+            const closest = scrollMapInfo.reduce((prev: ScrollMapInfo, curr: ScrollMapInfo): ScrollMapInfo => {
+                return ((Math.abs(curr.percUsers - marker)) < (Math.abs(prev.percUsers - marker)) ? curr : prev);
+            });
+            if (closest.percUsers >= marker - Setting.MarkerRange && closest.percUsers <= marker + Setting.MarkerRange) {
+                const markerLine = (closest.scrollReachY / 100) * height;
+                this.addMarker(context, width, `${marker}%`, markerLine, Setting.MarkerSmallWidth);
+            }
+        }
+    }
+
+    private addMarker = (context: CanvasRenderingContext2D, heatmapWidth: number, label: string, markerY: number, markerWidth: number): void => {
+        context.beginPath();
+        context.moveTo(0, markerY);
+        context.lineTo(heatmapWidth, markerY);
+        context.setLineDash([2, 2]);
+        context.lineWidth = Setting.MarkerLineHeight;
+        context.strokeStyle = Setting.MarkerColor;
+        context.stroke();
+        context.fillStyle = Setting.CanvasTextColor;
+        context.fillRect(0, (markerY - Setting.MarkerHeight / 2), markerWidth, Setting.MarkerHeight);
+        context.fillStyle = Setting.MarkerColor;
+        context.font = Setting.CanvasTextFont;
+        context.fillText(label, Setting.MarkerPadding, markerY + Setting.MarkerPadding);
+    }
+
+    public click = async (activity: Activity): Promise<void> => {
+        await this.waitForDialogs();
+        await this.waitForAllAnimations();
+        
+        this.data = this.data || activity;
+        let heat = this.transform();
+        let canvas = this.overlay();
+        let ctx = canvas.getContext(Constant.Context);
+
+        if (canvas.width > 0 && canvas.height > 0) {
+            // TODO: GEMX DEBUG Draw a test rectangle to verify canvas is working
+            // ctx.fillStyle = 'rgba(255, 0, 0, 0.3)';
+            // ctx.fillRect(10, 10, 100, 100);
+
+            // To speed up canvas rendering, we draw ring & gradient on an offscreen canvas, so we can use drawImage API
+            // Canvas performance tips: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API/Tutorial/Optimizing_canvas
+            // Pre-render similar primitives or repeating objects on an offscreen canvas
+            let ring = this.getRing();
+            let gradient = this.getGradient();
+
+            // Render activity for each (x,y) coordinate in our data
+            for (let entry of heat) {
+                ctx.globalAlpha = entry.a;
+                ctx.drawImage(ring, entry.x - Setting.Radius, entry.y - Setting.Radius);
+            }
+
+            // Add color to the canvas based on alpha value of each pixel
+            let pixels = ctx.getImageData(0, 0, canvas.width, canvas.height);
+            for (let i = 0; i < pixels.data.length; i += 4) {
+                // For each pixel, we have 4 entries in data array: (r,g,b,a)
+                // To pick the right color from gradient pixels, we look at the alpha value of the pixel
+                // Alpha value ranges from 0-255
+                let alpha = pixels.data[i + 3];
+                if (alpha > 0) {
+                    let offset = (alpha - 1) * 4;
+                    pixels.data[i] = gradient.data[offset];
+                    pixels.data[i + 1] = gradient.data[offset + 1];
+                    pixels.data[i + 2] = gradient.data[offset + 2];
+                }
+            }
+            ctx.putImageData(pixels, 0, 0);
+        }
+    }
+
+    public overlay = (): HTMLCanvasElement => {
+        // Create canvas for visualizing heatmap
+        let doc = this.state.window.document;
+        let win = this.state.window;
+        let de = doc.documentElement;
+
+        const isPortalCanvas = !!this.state.options.portalCanvasId;
+        if (isPortalCanvas) return this.createPortalCanvas(doc, win, de);
+
+        let canvas = doc.getElementById(Constant.HeatmapCanvas) as HTMLCanvasElement;
+        if (canvas === null) {
+            canvas = doc.createElement(Constant.Canvas) as HTMLCanvasElement;
+            canvas.id = Constant.HeatmapCanvas;
+            canvas.classList.add(Constant.HeatmapCanvas);
+            canvas.width = 0;
+            canvas.height = 0;
+            canvas.style.position = Constant.Absolute;
+            canvas.style.zIndex = `${Setting.ZIndex}`;
+            de.appendChild(canvas);
+            win.addEventListener("scroll", this.redraw, { passive: true, capture: true });
+            win.addEventListener("resize", this.redraw, { passive: true, capture: true });
+            win.addEventListener("animationend", this.redraw, true);
+            win.addEventListener("transitionend", this.redraw, true);
+            this.observer = this.state.window["ResizeObserver"] ? new ResizeObserver(this.redraw) : null;
+
+            if (this.observer) { this.observer.observe(doc.body); }
+        }
+
+        // Ensure canvas is positioned correctly
+        canvas.width = de.clientWidth;
+        canvas.height = de.clientHeight;
+        canvas.style.left = win.pageXOffset + Constant.Pixel;
+        canvas.style.top = win.pageYOffset + Constant.Pixel;
+        canvas.getContext(Constant.Context).clearRect(0, 0, canvas.width, canvas.height);
+
+        return canvas;
+    }
+
+    private getRing = (): HTMLCanvasElement => {
+        if (this.offscreenRing === null) {
+            let doc = this.state.window.document;
+            this.offscreenRing = doc.createElement(Constant.Canvas) as HTMLCanvasElement;
+            this.offscreenRing.width = Setting.Radius * 2;
+            this.offscreenRing.height = Setting.Radius * 2;
+            let ctx = this.offscreenRing.getContext(Constant.Context);
+            ctx.shadowOffsetX = Setting.Radius * 2;
+            ctx.shadowBlur = Setting.Radius / 2;
+            ctx.shadowColor = Constant.Black;
+            ctx.beginPath();
+            ctx.arc(-Setting.Radius, Setting.Radius, Setting.Radius / 2, 0, Math.PI * 2, true);
+            ctx.closePath();
+            ctx.fill();
+        }
+        return this.offscreenRing;
+    }
+
+    private getGradient = (): ImageData => {
+        if (this.gradientPixels === null) {
+            let doc = this.state.window.document;
+            let offscreenGradient = doc.createElement(Constant.Canvas) as HTMLCanvasElement;
+            offscreenGradient.width = 1;
+            offscreenGradient.height = Setting.Colors;
+            let ctx = offscreenGradient.getContext(Constant.Context);
+            let gradient = ctx.createLinearGradient(0, 0, 0, Setting.Colors);
+            let step = 1 / HeatmapHelper.COLORS.length;
+            for (let i = 0; i < HeatmapHelper.COLORS.length; i++) {
+                gradient.addColorStop(step * (i + 1), HeatmapHelper.COLORS[i]);
+            }
+            ctx.fillStyle = gradient;
+            ctx.fillRect(0, 0, 1, Setting.Colors);
+            this.gradientPixels = ctx.getImageData(0, 0, 1, Setting.Colors);
+        }
+        return this.gradientPixels;
+    }
+
+    private redraw = (event): void => {
+        if (this.data) {
+            if (this.timeout) { clearTimeout(this.timeout); }
+            this.timeout = setTimeout(this.click, Setting.Interval);
+        }
+        else if (this.scrollData) {
+            if (event.type != 'scroll') {
+                if (this.timeout) { clearTimeout(this.timeout); }
+                this.timeout = setTimeout(this.scroll, Setting.Interval);
+            }
+        }
+    }
+
+    private transform = (): Heatmap[] => {
+        let output: Heatmap[] = [];
+        let points: { [key: string]: number } = {};
+        let localMax = 0;
+        let height = this.state.window && this.state.window.document ? this.state.window.document.documentElement.clientHeight : 0;
+
+        // DEBUG LOG
+        console.groupCollapsed(`[Heatmap] transform — total elements: ${this.data.length}, height: ${height}, max: ${this.max}`);
+
+        for (let element of this.data) {
+            let el = this.layout.get(element.hash) as HTMLElement;
+            if (!el) {
+                console.warn(`[Heatmap] SKIP hash="${element.hash}" — element not found in DOM`);
+                continue;
+            }
+            if (typeof el.getBoundingClientRect !== "function") {
+                console.warn(`[Heatmap] SKIP hash="${element.hash}" — getBoundingClientRect not available`, el);
+                continue;
+            }
+
+            let r = el.getBoundingClientRect();
+            let v = this.visible(el, r, height, this.state.options.debugHash);
+
+            if (!v && this.max !== null) {
+                console.warn(`[Heatmap] SKIP hash="${element.hash}" — not visible on re-render`, { rect: { top: r.top, left: r.left, width: r.width, height: r.height }, maxIsSet: this.max !== null });
+                continue;
+            }
+
+            if (el && typeof el.getBoundingClientRect === "function") {
+                console.log(`[Heatmap] PROCESS hash="${element.hash}" visible=${v} points=${element.points}`, { rect: { top: r.top, left: r.left, width: r.width, height: r.height } });
+                // Process clicks for only visible elements
+                if (this.max === null || v) {
+                    for (let i = 0; i < element.points; i++) {
+                        let x = Math.round(r.left + (element.x[i] / Data.Setting.ClickPrecision) * r.width);
+                        let y = Math.round(r.top + (element.y[i] / Data.Setting.ClickPrecision) * r.height);
+                        let k = `${x}${Constant.Separator}${y}${Constant.Separator}${v ? 1 : 0}`;
+                        points[k] = k in points ? points[k] + element.clicks[i] : element.clicks[i];
+                        localMax = Math.max(points[k], localMax);
+                        console.log(`  point[${i}] x=${x} y=${y} visible=${v} clicks=${element.clicks[i]}`);
+                    }
+                }
+            }
+        }
+
+        // Set the max value from the firs t
+        this.max = this.max ? this.max : localMax;
+
+        // Once all points are accounted for, convert everything into absolute (x, y)
+        let skippedInvisible = 0;
+        for (let coordinates of Object.keys(points)) {
+            let parts = coordinates.split(Constant.Separator);
+            let alpha = Math.min((points[coordinates] / this.max) + Setting.AlphaBoost, 1);
+            if (parts[2] === "1") {
+                output.push({ x: parseInt(parts[0], 10), y: parseInt(parts[1], 10), a: alpha });
+            } else {
+                skippedInvisible++;
+            }
+        }
+
+        console.log(`[Heatmap] Result — drawn: ${output.length}, skipped invisible: ${skippedInvisible}, max: ${this.max}`);
+        console.groupEnd();
+
+        return output;
+    }
+
+    private visible = (el: HTMLElement, r: DOMRect, height: number, debugHash?: string): boolean => {
+        let doc: Document | ShadowRoot = this.state.window.document;
+        let visibility = r.height > height ? true : false;
+
+        if (debugHash) {
+            console.groupCollapsed(`[Heatmap visible] hash=${debugHash} tag=${el?.tagName}`);
+            console.log(`  rect: top=${r.top.toFixed(1)} bottom=${r.bottom.toFixed(1)} left=${r.left.toFixed(1)} width=${r.width.toFixed(1)} height=${r.height.toFixed(1)}`);
+            console.log(`  viewport height=${height} | r.height > height? ${r.height > height}`);
+        }
+
+        if (visibility === false && r.width > 0 && r.height > 0) {
+            const checkX = r.left + (r.width / 2);
+            const checkY = r.top + (r.height / 2);
+            if (debugHash) { console.log(`  elementsFromPoint(${checkX.toFixed(1)}, ${checkY.toFixed(1)})`); }
+
+            while (!visibility && doc) {
+                let shadowElement = null;
+                let caretEl: Node | null = null;
+                if ('caretPositionFromPoint' in doc) {
+                    caretEl = (doc as any).caretPositionFromPoint(checkX, checkY)?.offsetNode ?? null;
+                }
+                const elementAtPoint = caretEl as Element | null;
+                let elements = doc.elementsFromPoint(checkX, checkY);
+                if (elementAtPoint && !elements.includes(elementAtPoint)) { elements = [elementAtPoint, ...elements]; }
+
+                if (debugHash) {
+                    const topElements = elements.slice(0, 5).map(e => `${e.tagName}${e.id ? '#' + e.id : ''}${e.className ? '.' + String(e.className).trim().split(/\s+/).slice(0, 2).join('.') : ''}`);
+                    console.log(`  top elements at center: [${topElements.join(', ')}]`);
+                    console.log(`  is el in top elements? ${elements.includes(el)} | el matches first non-canvas? ${elements.find(e => !(e.tagName === Constant.Canvas || (e.id && e.id.indexOf(Constant.ClarityPrefix) === 0))) === el}`);
+                }
+
+                for (let e of elements) {
+                    // Ignore if top element ends up being the canvas element we added for heatmap visualization
+                    if (e.tagName === Constant.Canvas || (e.id && e.id.indexOf(Constant.ClarityPrefix) === 0)) { continue; }
+                    // Consider visible if the top element is the element itself OR a descendant of it
+                    // (e.g. a BUTTON containing P/SPAN children — children will appear on top in elementsFromPoint)
+                    visibility = e === el || el.contains(e) || e.contains(el);
+                    shadowElement = e.shadowRoot && e.shadowRoot != doc ? e.shadowRoot : null;
+                    break;
+                }
+                doc = shadowElement;
+            }
+        } else if (debugHash) {
+            if (r.width === 0 || r.height === 0) {
+                console.log(`  SKIP elementsFromPoint — zero dimension: width=${r.width} height=${r.height}`);
+            }
+        }
+
+        const result = visibility && r.bottom >= 0 && r.top <= height;
+        if (debugHash) {
+            console.log(`  visibility=${visibility} | r.bottom(${r.bottom.toFixed(1)}) >= 0? ${r.bottom >= 0} | r.top(${r.top.toFixed(1)}) <= height(${height})? ${r.top <= height}`);
+            console.log(`  => final result: ${result}`);
+            console.groupEnd();
+        }
+        return result;
+    }
+    
+    public waitForDialogs = async (): Promise<void> => {
+        const isPortalCanvas = !!this.state.options.portalCanvasId;
+        if (!isPortalCanvas) return ;
+
+        await dialogCustom.waitForDialogsRendered();
+        return;
+    }
+
+    private waitForAllAnimations = async (): Promise<void> => {
+        const win = this.state.window;
+        if (!win || !win.document) return;
+
+        const animations = win.document.getAnimations().filter(a =>
+            a.playState === 'running' &&
+            (a.effect as KeyframeEffect)?.getTiming().iterations !== Infinity
+        );
+        if (animations.length === 0) return;
+
+        const timeout = new Promise<void>(resolve => setTimeout(resolve, 1500));
+        await Promise.race([
+            Promise.allSettled(animations.map(a => a.finished)),
+            timeout
+        ]);
+    }
+
+    protected createPortalCanvas = (doc: Document, win: Window, de: HTMLElement): HTMLCanvasElement => {
+        let canvas = null;
+        try {
+            canvas = this.parentCanvasInfo?.canvas;
+            if (!canvas) {
+                this.parentCanvasInfo = canvasLayer.createParentWindowCanvas(doc, this.state.options.portalCanvasId);
+                canvas = this.parentCanvasInfo.canvas;
+
+                // Add event listeners only once when canvas is created
+                win.addEventListener("scroll", this.redraw, { passive: true, capture: true });
+                win.addEventListener("resize", this.redraw, { passive: true, capture: true });
+                win.addEventListener("animationend", this.redraw, true);
+                win.addEventListener("transitionend", this.redraw, true);
+                this.observer = this.state.window["ResizeObserver"] ? new ResizeObserver(this.redraw) : null;
+
+                if (this.observer) { this.observer.observe(doc.body); }
+            }
+
+            canvas.width = de.clientWidth;
+            canvas.height = de.clientHeight; // TODO: GEMX VERIFY
+            canvas.style.top = '0';
+            canvas.style.left = '0';
+            canvas.getContext(Constant.Context).clearRect(0, 0, canvas.width, canvas.height);
+
+            this.parentCanvasInfo.canvas = canvas;
+            return canvas;
+        } catch (error) {
+            console.error(`[Heatmap] createPortalCanvas:`, error);
+        }
+        return null;
+    }
+
+    // private _visibleV2 = (el: HTMLElement, r: DOMRect, height: number): boolean => {
+    //     let doc: Document | ShadowRoot = this.state.window.document;
+    //     let visibility = r.height > height ? true : false;
+    //     if (visibility === false && r.width > 0 && r.height > 0) {
+    //         while (!visibility && doc) {
+    //             let shadowElement = null;
+    //             let elements = doc.elementsFromPoint(r.left + (r.width / 2), r.top + (r.height / 2));
+
+    //             // Check if only dialog and HTML are returned (element is behind dialog)
+    //             let hasOnlyDialogAndHtml = elements.length === 2 &&
+    //                 elements[0].tagName === 'DIALOG' &&
+    //                 elements[1].tagName === 'HTML';
+
+    //             // If element is behind a dialog, assume it's visible
+    //             // (we can't check through top-layer, so trust the element exists)
+    //             if (hasOnlyDialogAndHtml) {
+    //                 visibility = true;
+    //                 break;
+    //             }
+
+    //             for (let e of elements) {
+    //                 // Check if this is the target element BEFORE skipping dialogs
+    //                 // This handles case where target element IS a dialog
+    //                 if (e === el) {
+    //                     visibility = true;
+    //                     shadowElement = e.shadowRoot && e.shadowRoot != doc ? e.shadowRoot : null;
+    //                     break;
+    //                 }
+
+    //                 // Skip dialog elements - treat as transparent for checking elements behind
+    //                 if (e.tagName === 'DIALOG') {
+    //                     continue;
+    //                 }
+
+    //                 // Skip canvas and clarity elements
+    //                 if (e.tagName === Constant.Canvas ||
+    //                     (e.id && e.id.indexOf(Constant.ClarityPrefix) === 0)) {
+    //                     continue;
+    //                 }
+
+    //                 // This is the first non-ignored element
+    //                 visibility = e === el;
+    //                 shadowElement = e.shadowRoot && e.shadowRoot != doc ? e.shadowRoot : null;
+    //                 break;
+    //             }
+
+    //             doc = shadowElement;
+    //         }
+    //     }
+    //     return visibility && r.bottom >= 0 && r.top <= height;
+    // }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * as visualize from "./clarity";
+export { Visualizer } from "./visualizer";
+export { HeatmapHelper } from "./heatmap";
+export { LayoutHelper } from "./layout";