@gem-sdk/clarity-visualize 0.8.94

package/src/custom/dialog.ts

@@ -0,0 +1,242 @@
+/**
+ * Custom module for rendering HTML Dialog elements
+ * Handles proper visualization of modal dialogs in the top-layer
+ */
+
+import { Constant as LayoutConstants } from "@gem-sdk/clarity-js/types/layout";
+
+export interface DialogRenderOptions {
+    isModal: boolean;
+    shouldBeOpen: boolean;
+    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
+ *
+ * @param attributes - Node attributes containing dialog state
+ * @param dialogElement - The dialog element being rendered
+ * @returns Dialog render options
+ */
+export function getDialogRenderOptions(
+    attributes: { [key: string]: string },
+    dialogElement: HTMLDialogElement | null
+): DialogRenderOptions {
+    return {
+        isModal: attributes[LayoutConstants.GXDialogModal] === "true",
+        shouldBeOpen: attributes["open"] !== undefined,
+        isExistingDialog: !!dialogElement
+    };
+}
+
+/**
+ * Shows a dialog element with proper modal/non-modal handling
+ * Modal dialogs are shown via showModal() to render in top-layer with backdrop
+ * Non-modal dialogs are shown via show() method
+ *
+ * @param dialogElement - The dialog element to show
+ * @param isModal - Whether this is a modal dialog
+ * @param onError - Optional error callback
+ */
+export function showDialog(
+    dialogElement: HTMLDialogElement,
+    isModal: boolean,
+    onError?: (error: Error) => void
+): void {
+    try {
+        if (!dialogElement.isConnected) {
+            notifyDialogComplete(dialogElement);
+            return;
+        }
+        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;
+    }
+}
+
+/**
+ * Closes a dialog element safely
+ *
+ * @param dialogElement - The dialog element to close
+ */
+export function closeDialog(dialogElement: HTMLDialogElement): void {
+    try {
+        if (dialogElement.open) {
+            dialogElement.close();
+        }
+    } catch (e) {
+        console.warn('⚠️ Error closing dialog:', e);
+    }
+}
+
+/**
+ * Handles dialog rendering based on its state
+ * This is the main entry point for dialog rendering logic
+ *
+ * @param dialogElement - The dialog element to render
+ * @param options - Dialog render options
+ * @param onError - Optional error callback
+ */
+export function renderDialog(
+    dialogElement: HTMLDialogElement,
+    options: DialogRenderOptions,
+    onError?: (error: Error) => void
+): void {
+    const { isModal, shouldBeOpen, isExistingDialog } = options;
+    if (!shouldBeOpen) return;
+
+    // Add dialog to pending set (Set automatically handles duplicates)
+    pendingDialogs.add(dialogElement);
+
+    const doShow = () => showDialog(dialogElement, isModal, onError);
+    if (isExistingDialog) {
+        doShow();
+    } else {
+        setTimeout(doShow, 0);
+    }
+}
+
+/**
+ * Removes custom tracking attributes before rendering
+ * These attributes are only for internal use
+ *
+ * @param attributes - Attributes object to clean
+ * @returns Cleaned attributes
+ */
+export function cleanDialogAttributes(
+    attributes: { [key: string]: string }
+): { [key: string]: string } {
+    const cleaned = { ...attributes };
+    delete cleaned[LayoutConstants.GXDialogModal];
+    return cleaned;
+}

package/src/custom/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Custom modules for GemX Clarity Visualize extensions
+ * Contains custom rendering logic that extends the base Clarity visualization
+ */
+
+export * from "./dialog";
+export * from "./canvas-layer";

package/src/data.ts

@@ -0,0 +1,103 @@
+import { Data, Layout } from "@gem-sdk/clarity-js";
+import type { Data as DecodedData, Layout as DecodedLayout } from "@gem-sdk/clarity-decode";
+import { PlaybackState, RegionState } from "@clarity-types/visualize";
+
+export class DataHelper {
+    regionMap = {};
+    regions: { [key: string]:  RegionState} = {};
+    metrics: {[key: number]: number} = {};
+    lean = false;
+    state: PlaybackState;
+
+    constructor(state: PlaybackState) {
+        this.state = state;
+    }
+
+    static METRIC_MAP = {
+        [Data.Metric.TotalBytes]: { name: "Total Bytes", unit: "KB" },
+        [Data.Metric.TotalCost]: { name: "Total Cost", unit: "ms" },
+        [Data.Metric.LayoutCost]: { name: "Layout Cost", unit: "ms" },
+        [Data.Metric.LargestPaint]: { name: "LCP", unit: "s" },
+        [Data.Metric.CumulativeLayoutShift]: { name: "CLS", unit: "cls" },
+        [Data.Metric.LongTaskCount]: { name: "Long Tasks" },
+        [Data.Metric.CartTotal]: { name: "Cart Total", unit: "html-price" },
+        [Data.Metric.ProductPrice]: { name: "Product Price", unit: "ld-price" },
+        [Data.Metric.ThreadBlockedTime]: { name: "Thread Blocked", unit: "ms" },
+        [Data.Dimension.InteractionNextPaint]: { name: "INP", unit: "ms" }
+    };
+
+    public reset = (): void => {
+        this.metrics = {};
+        this.lean = false;
+        this.regions = {};
+        this.regionMap = {};
+    }
+
+    public metric = (event: DecodedData.MetricEvent): void => {
+        if (this.state.options.metadata) {
+            let metricMarkup = [];
+            let regionMarkup = [];
+            // Copy over metrics for future reference
+            for (let m in event.data) {
+                const eventType = typeof event.data[m];
+                if (eventType === "number" || (event.event === Data.Event.Dimension && m === Data.Dimension.InteractionNextPaint.toString())) {
+                    if (!(m in this.metrics)) { this.metrics[m] = 0; }
+                    let key = parseInt(m, 10);
+                    let value =  eventType === "object" ? Number(event.data[m]?.[0]) : event.data[m];
+                    if (m in DataHelper.METRIC_MAP && (DataHelper.METRIC_MAP[m].unit === "html-price" ||DataHelper.METRIC_MAP[m].unit === "ld-price")) {
+                        this.metrics[m] = value;
+                    } else { this.metrics[m] += value; }
+                    this.lean = key === Data.Metric.Playback && value === 0 ? true : this.lean;
+                }
+            }
+
+            for (let entry in this.metrics) {
+                if (entry in DataHelper.METRIC_MAP) {
+                    let m = this.metrics[entry];
+                    let map = DataHelper.METRIC_MAP[entry];
+                    let unit = "unit" in map ? map.unit : Data.Constant.Empty;
+                    metricMarkup.push(`<li><h2>${this.value(m, unit)}<span>${this.key(unit)}</span></h2>${map.name}</li>`);
+                }
+            }
+
+            // Append region information to metadata
+            for (let name in this.regions) {
+                let r = this.regions[name];
+                let className = (r.visibility === Layout.RegionVisibility.Visible ? "visible" : (r.interaction === Layout.InteractionState.Clicked ? "clicked" : Data.Constant.Empty));
+                regionMarkup.push(`<span class="${className}">${name}</span>`);
+            }
+
+            this.state.options.metadata.innerHTML = `<ul>${metricMarkup.join(Data.Constant.Empty)}</ul><div>${regionMarkup.join(Data.Constant.Empty)}</div>`;
+        }
+    }
+
+    public region(event: DecodedLayout.RegionEvent): void {
+        let data = event.data;
+        for (let r of data) {
+            if (!(r.name in this.regions)) {
+                this.regions[r.name] = { interaction: r.interaction , visibility: r.visibility }
+            }
+            this.regionMap[r.id] = r.name;
+        }
+    }
+
+    private key = (unit: string): string => {
+        switch (unit) {
+            case "html-price":
+            case "ld-price":
+            case "cls":
+                return Data.Constant.Empty;
+            default: return unit;
+        }
+    }
+
+    private value = (num: number, unit: string): number => {
+        switch (unit) {
+            case "KB": return Math.round(num / 1024);
+            case "s": return Math.round(num / 10) / 100;
+            case "cls": return num / 1000;
+            case "html-price": return num / 100;
+            default: return num;
+        }
+    }
+}

package/src/enrich.ts

@@ -0,0 +1,80 @@
+import { helper, Layout } from "@gem-sdk/clarity-js";
+import { Layout as DecodedLayout } from "@gem-sdk/clarity-decode";
+import { NodeData } from "@clarity-types/visualize";
+
+export class EnrichHelper {
+
+    children: { [key: number]: number[] };
+    nodes: { [key: number]: NodeData };
+
+    constructor() {
+        this.reset();
+    }
+
+    public reset = (): void => {
+        this.children = {};
+        this.nodes = {};
+        helper.selector.reset();
+    }
+
+    public selectors = (event: DecodedLayout.DomEvent): DecodedLayout.DomEvent => {
+        event.data.forEach && event.data.forEach(d => {
+            let parent = this.nodes[d.parent];
+            let children = this.children[d.parent] || [];
+            let node = this.nodes[d.id] || { tag: d.tag, parent: d.parent, previous: d.previous };
+            let attributes = d.attributes || {};
+
+            /* Track parent-child relationship for this element */
+            if (node.parent !== d.parent) {
+                let childIndex = d.previous === null ? 0 : children.indexOf(d.previous) + 1;
+                children.splice(childIndex, 0, d.id);
+
+                // Stop tracking this node from children of previous parent
+                if (node.parent !== d.parent) {
+                    let exParent = this.children[node.parent];
+                    let nodeIndex = exParent ? exParent.indexOf(d.id) : -1;
+                    if (nodeIndex >= 0) {
+                        this.children[node.parent].splice(nodeIndex, 1);
+                    }
+                }
+                node.parent = d.parent;
+            } else if (children.indexOf(d.id) < 0) { children.push(d.id); }
+
+            /* Get current position */
+            node.position = this.position(d.id, d.tag, node, children, children.map(c => this.nodes[c]));
+
+            /* For backward compatibility, continue populating current selector and hash like before in addition to beta selector and hash */
+            let input: Layout.SelectorInput = { id: d.id, tag: d.tag, prefix: parent ? [parent.alpha, parent.beta] : null, position: node.position, attributes };
+
+            // Get stable selector
+            // We intentionally use "null" value for empty selectors to keep parity with v0.6.25 and before.
+            let selectorAlpha = helper.selector.get(input, Layout.Selector.Alpha);
+            d.selectorAlpha = selectorAlpha.length > 0 ? selectorAlpha : null;
+            d.hashAlpha = selectorAlpha.length > 0 ? helper.hash(d.selectorAlpha) : null;
+
+            // Get beta selector
+            let selectorBeta = helper.selector.get(input, Layout.Selector.Beta);
+            d.selectorBeta = selectorBeta.length > 0 ? selectorBeta : null;
+            d.hashBeta = selectorBeta.length > 0 ? helper.hash(d.selectorBeta) : null;
+
+            /* Track state for future reference */
+            node.alpha = selectorAlpha;
+            node.beta = selectorBeta;
+            this.nodes[d.id] = node;
+            if (d.parent) { this.children[d.parent] = children; }
+        });
+        return event;
+    }
+
+    private position = (id: number, tag: string, child: NodeData, children: number[], siblings: NodeData[]): number => {
+        child.position = 1;
+        let idx = children ? children.indexOf(id) : -1;
+        while (idx-- > 0) {
+            if (tag === siblings[idx].tag) {
+                child.position = siblings[idx].position + 1;
+                break;
+            }
+        }
+        return child.position;
+    }
+}

package/src/global.ts

@@ -0,0 +1,9 @@
+import * as visualize from "@src/clarity";
+
+// Expose clarity variable globally to allow access to public interface in a browser
+if (typeof window !== "undefined") {
+    if ((window as any).clarity === undefined || (window as any).clarity === null) {
+        (window as any).clarity = {};
+    }
+    (window as any).clarity.visualize = visualize;
+}