@gemx-dev/heatmap-react 3.5.34 → 3.5.35

package/dist/esm/index.js

@@ -1,7 +1,7 @@
 "use client"
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import { useNodesState, ReactFlow, Controls, Background } from '@xyflow/react';
-import { useEffect, useCallback, useState, useRef, useMemo, Fragment as Fragment$1 } from 'react';
+import { useEffect, useCallback, useState, useRef, useMemo, forwardRef, Fragment as Fragment$1 } from 'react';
 import { create } from 'zustand';
 import { Visualizer } from '@gemx-dev/clarity-visualize';
 import { createPortal } from 'react-dom';
@@ -72,6 +72,7 @@ const useHeatmapControlStore = create()((set, get) => {
             Toolbar: null,
             MetricBar: null,
             VizLoading: null,
+            ElementCallout: null,
         },
         registerControl: (key, control) => {
             set({
@@ -120,6 +121,8 @@ const useHeatmapInteractionStore = create()((set, get) => {
         setSelectedElement: (selectedElement) => set({ selectedElement }),
         hoveredElement: null,
         setHoveredElement: (hoveredElement) => set({ hoveredElement }),
+        shouldShowCallout: false,
+        setShouldShowCallout: (shouldShowCallout) => set({ shouldShowCallout }),
     };
 });
 
@@ -152,6 +155,7 @@ const useRegisterControl = (control) => {
     registerControl('Toolbar', control.Toolbar);
     registerControl('MetricBar', control.MetricBar);
     registerControl('VizLoading', control.VizLoading);
+    registerControl('ElementCallout', control.ElementCallout);
 };
 
 const useRegisterData = (data, dataInfo) => {
@@ -189,47 +193,251 @@ const useRegisterHeatmap = (clickmap) => {
     }, [clickmap]);
 };
 
-const isElementInViewport = (elementRect, visualRef, scale) => {
-    const visualRect = visualRef.current?.getBoundingClientRect();
-    if (!visualRect)
-        return false;
-    // Absolute position of element so visual container (not scaled)
-    const elementTopRaw = elementRect.top - visualRect.top;
-    const elementBottomRaw = elementTopRaw + elementRect.height;
-    // Apply scale because wrapper is scaled
-    const elementTop = elementTopRaw * scale;
-    const elementBottom = elementBottomRaw * scale;
-    const scrollTop = visualRef.current?.scrollTop || 0;
-    const viewportHeight = visualRect.height;
-    const viewportTop = scrollTop;
-    const viewportBottom = scrollTop + viewportHeight;
-    return elementTop >= viewportTop && elementBottom <= viewportBottom;
+const PADDING = 0;
+const ARROW_SIZE = 8;
+const HORIZONTAL_OFFSET = 0;
+// ============================================================================
+// Viewport & Dimensions
+// ============================================================================
+const getViewportDimensions = () => ({
+    width: window.innerWidth,
+    height: window.innerHeight,
+});
+const getElementDimensions = (targetElm, calloutElm) => ({
+    targetRect: targetElm.getBoundingClientRect(),
+    calloutRect: calloutElm.getBoundingClientRect(),
+});
+// ============================================================================
+// Alignment Order
+// ============================================================================
+const getAlignmentOrder = (alignment) => {
+    switch (alignment) {
+        case 'center':
+            return ['center', 'left', 'right'];
+        case 'left':
+            return ['left', 'center', 'right'];
+        case 'right':
+            return ['right', 'center', 'left'];
+    }
+};
+// ============================================================================
+// Position Calculation
+// ============================================================================
+const calculateLeftPosition = ({ targetRect, calloutRect, hozOffset, align, }) => {
+    switch (align) {
+        case 'left':
+            return targetRect.left + hozOffset;
+        case 'right':
+            return targetRect.right - calloutRect.width - hozOffset;
+        case 'center':
+        default:
+            return targetRect.left + targetRect.width / 2 - calloutRect.width / 2;
+    }
+};
+const calculateVerticalPosition = (targetRect, calloutRect, placement, padding, arrowSize) => {
+    return placement === 'top'
+        ? targetRect.top - calloutRect.height - padding - arrowSize
+        : targetRect.bottom + padding + arrowSize;
+};
+const calculateHorizontalPlacementPosition = (targetRect, calloutRect, placement, padding, arrowSize) => {
+    const top = targetRect.top + targetRect.height / 2 - calloutRect.height / 2;
+    const left = placement === 'right'
+        ? targetRect.right + padding + arrowSize
+        : targetRect.left - calloutRect.width - padding - arrowSize;
+    return { top, left };
+};
+// ============================================================================
+// Validation
+// ============================================================================
+const isLeftPositionValid = (leftPos, calloutWidth, viewportWidth, padding) => {
+    return leftPos >= padding && leftPos + calloutWidth <= viewportWidth - padding;
+};
+const isVerticalPositionValid = (targetRect, calloutRect, placement, viewportHeight, padding, arrowSize) => {
+    return placement === 'top'
+        ? targetRect.top - calloutRect.height - padding - arrowSize > 0
+        : targetRect.bottom + calloutRect.height + padding + arrowSize < viewportHeight;
+};
+const isHorizontalPlacementValid = (targetRect, calloutRect, placement, viewportWidth, padding, arrowSize) => {
+    return placement === 'right'
+        ? targetRect.right + calloutRect.width + padding + arrowSize < viewportWidth
+        : targetRect.left - calloutRect.width - padding - arrowSize > 0;
+};
+// ============================================================================
+// Position Candidates Generation
+// ============================================================================
+const generateVerticalPositionCandidates = (targetRect, calloutRect, viewportHeight, viewportWidth, alignment, hozOffset, padding, arrowSize) => {
+    const candidates = [];
+    const placements = ['top', 'bottom'];
+    placements.forEach((placement) => {
+        const verticalPos = calculateVerticalPosition(targetRect, calloutRect, placement, padding, arrowSize);
+        const verticalValid = isVerticalPositionValid(targetRect, calloutRect, placement, viewportHeight, padding, arrowSize);
+        const alignmentOrder = getAlignmentOrder(alignment);
+        alignmentOrder.forEach((align) => {
+            const horizontalPos = calculateLeftPosition({
+                targetRect,
+                calloutRect,
+                hozOffset,
+                align,
+            });
+            candidates.push({
+                placement,
+                top: verticalPos,
+                left: horizontalPos,
+                horizontalAlign: align,
+                valid: verticalValid &&
+                    isLeftPositionValid(horizontalPos, calloutRect.width, viewportWidth, padding),
+            });
+        });
+    });
+    return candidates;
+};
+const generateHorizontalPositionCandidates = (targetRect, calloutRect, viewportWidth, padding, arrowSize) => {
+    const placements = ['left', 'right'];
+    return placements.map((placement) => {
+        const { top, left } = calculateHorizontalPlacementPosition(targetRect, calloutRect, placement, padding, arrowSize);
+        return {
+            placement,
+            top,
+            left,
+            horizontalAlign: 'center',
+            valid: isHorizontalPlacementValid(targetRect, calloutRect, placement, viewportWidth, padding, arrowSize),
+        };
+    });
+};
+const generateAllPositionCandidates = (rectDimensions, viewport, alignment, hozOffset, padding, arrowSize) => {
+    const { targetRect, calloutRect } = rectDimensions;
+    const verticalCandidates = generateVerticalPositionCandidates(targetRect, calloutRect, viewport.height, viewport.width, alignment, hozOffset, padding, arrowSize);
+    const horizontalCandidates = generateHorizontalPositionCandidates(targetRect, calloutRect, viewport.width, padding, arrowSize);
+    return [...verticalCandidates, ...horizontalCandidates];
+};
+// ============================================================================
+// Position Selection
+// ============================================================================
+const selectBestPosition = (candidates) => {
+    return candidates.find((p) => p.valid) || candidates[0];
+};
+// ============================================================================
+// Viewport Boundary Adjustment
+// ============================================================================
+const constrainToViewport = (position, calloutRect, viewport, padding) => {
+    const left = Math.max(padding, Math.min(position.left, viewport.width - calloutRect.width - padding));
+    const top = Math.max(padding, Math.min(position.top, viewport.height - calloutRect.height - padding));
+    return { top, left };
+};
+// ============================================================================
+// Main Function
+// ============================================================================
+const calcCalloutPosition = ({ targetElm, calloutElm, setPosition, hozOffset = HORIZONTAL_OFFSET, alignment = 'center', }) => {
+    return () => {
+        // 1. Get dimensions
+        const rectDimensions = getElementDimensions(targetElm, calloutElm);
+        const viewport = getViewportDimensions();
+        const padding = PADDING;
+        const arrowSize = ARROW_SIZE;
+        // 2. Generate all position candidates
+        const candidates = generateAllPositionCandidates(rectDimensions, viewport, alignment, hozOffset, padding, arrowSize);
+        // 3. Select best position
+        const bestPosition = selectBestPosition(candidates);
+        // 4. Constrain to viewport
+        const constrainedPosition = constrainToViewport({ top: bestPosition.top, left: bestPosition.left }, rectDimensions.calloutRect, viewport, padding);
+        // 5. Create final position object
+        const finalPosition = {
+            top: constrainedPosition.top,
+            left: constrainedPosition.left,
+            placement: bestPosition.placement,
+            horizontalAlign: bestPosition.horizontalAlign,
+        };
+        setPosition(finalPosition);
+    };
+};
+
+function getElementLayout(element) {
+    if (!element?.getBoundingClientRect)
+        return null;
+    const rect = element.getBoundingClientRect();
+    if (rect.width === 0 && rect.height === 0)
+        return null;
+    return {
+        top: rect.top,
+        left: rect.left,
+        width: rect.width,
+        height: rect.height,
+    };
+}
+const getElementAtPoint = (doc, x, y) => {
+    let el = null;
+    if ('caretPositionFromPoint' in doc) {
+        el = doc.caretPositionFromPoint(x, y)?.offsetNode ?? null;
+    }
+    el = el ?? doc.elementFromPoint(x, y);
+    let element = el;
+    while (element && element.nodeType === Node.TEXT_NODE) {
+        element = element.parentElement;
+    }
+    return element;
 };
-const calculateElementRank = (selectedElement, sortedElements) => {
-    if (!sortedElements)
+function getElementHash(element) {
+    return (element.getAttribute('data-clarity-hash') ||
+        element.getAttribute('data-clarity-hashalpha') ||
+        element.getAttribute('data-clarity-hashbeta'));
+}
+const getElementRank = (hash, elements) => {
+    if (!elements)
         return 0;
-    return sortedElements.findIndex((e) => e.hash === selectedElement) + 1;
+    return elements.findIndex((e) => e.hash === hash) + 1;
 };
-const buildElementInfo = (selectedElement, info, rect, rank) => {
+const buildElementInfo = (hash, rect, heatmapInfo) => {
+    if (!rect || !heatmapInfo)
+        return null;
+    const info = heatmapInfo.elementMapInfo?.[hash];
+    if (!info)
+        return null;
+    const rank = getElementRank(hash, heatmapInfo.sortedElements);
+    const clicks = info.totalclicks ?? 0;
+    const selector = info.selector ?? '';
     const baseInfo = {
-        hash: selectedElement,
-        clicks: info.totalclicks ?? 0,
+        hash,
+        clicks,
         rank,
-        selector: info.selector ?? '',
+        selector,
     };
-    if (rect) {
-        return { ...baseInfo, ...rect };
-    }
     return {
         ...baseInfo,
-        left: 0,
-        top: 0,
-        width: 0,
-        height: 0,
+        ...rect,
     };
 };
-const scrollToElementIfNeeded = (visualRef, wrapperRef, rect, scale) => {
-    if (!visualRef.current || !wrapperRef.current)
+
+function calculateRankPosition(rect, widthScale) {
+    const top = rect.top <= 18 ? rect.top + 3 : rect.top - 18;
+    const left = rect.left <= 18 ? rect.left + 3 : rect.left - 18;
+    return {
+        transform: `scale(${1.2 * widthScale})`,
+        top: Number.isNaN(top) ? undefined : top,
+        left: Number.isNaN(left) ? undefined : left,
+    };
+}
+function isElementInViewport(elementRect, visualRef, scale) {
+    if (!elementRect)
+        return false;
+    const visualRect = visualRef.current?.getBoundingClientRect();
+    if (!visualRect)
+        return false;
+    // Element position relative to the document (or container's content)
+    const elementTop = elementRect.top * scale;
+    const elementBottom = (elementRect.top + elementRect.height) * scale;
+    // Current scroll position
+    const scrollTop = visualRef.current?.scrollTop || 0;
+    const viewportHeight = visualRect.height;
+    // Visible viewport range in the scrollable content
+    const viewportTop = scrollTop;
+    const viewportBottom = scrollTop + viewportHeight;
+    // Check if element is within the visible viewport
+    // Element is visible if it overlaps with the viewport
+    return elementBottom > viewportTop && elementTop < viewportBottom;
+}
+
+const scrollToElementIfNeeded = (visualRef, rect, scale) => {
+    if (!visualRef.current)
         return;
     const visualRect = visualRef.current.getBoundingClientRect();
     if (isElementInViewport(rect, visualRef, scale)) {
@@ -245,13 +453,14 @@ const scrollToElementIfNeeded = (visualRef, wrapperRef, rect, scale) => {
         behavior: 'smooth',
     });
 };
-const useClickedElement = ({ visualRef, wrapperRef, getRect }) => {
+const useClickedElement = ({ visualRef, getRect }) => {
     const heatmapInfo = useHeatmapDataStore((state) => state.dataInfo);
     const selectedElement = useHeatmapInteractionStore((state) => state.selectedElement);
+    const shouldShowCallout = useHeatmapInteractionStore((state) => state.shouldShowCallout);
+    const setShouldShowCallout = useHeatmapInteractionStore((state) => state.setShouldShowCallout);
     const scale = useHeatmapVizStore((state) => state.scale);
     const [clickedElement, setClickedElement] = useState(null);
     const [showMissingElement, setShowMissingElement] = useState(false);
-    const [shouldShowCallout, setShouldShowCallout] = useState(false);
     const reset = () => {
         setClickedElement(null);
         setShowMissingElement(false);
@@ -267,26 +476,58 @@ const useClickedElement = ({ visualRef, wrapperRef, getRect }) => {
             setClickedElement(null);
             return;
         }
-        const rect = getRect({ hash: selectedElement, selector: info.selector });
-        const rank = calculateElementRank(selectedElement, heatmapInfo.sortedElements);
-        const elementInfo = buildElementInfo(selectedElement, info, rect, rank);
-        if (rect) {
-            setShowMissingElement(false);
-            scrollToElementIfNeeded(visualRef, wrapperRef, rect, scale);
-            setShouldShowCallout(true);
-            requestAnimationFrame(() => {
-                setClickedElement(elementInfo);
-            });
-        }
-        else {
+        const hash = selectedElement;
+        const selector = info.selector;
+        const rect = getRect({ hash: selectedElement, selector });
+        const elementInfo = buildElementInfo(hash, rect, heatmapInfo);
+        if (!rect) {
             setClickedElement(elementInfo);
             setShowMissingElement(true);
             setShouldShowCallout(false);
+            return;
         }
-    }, [selectedElement, heatmapInfo, getRect, visualRef, wrapperRef, scale]);
+        setShowMissingElement(false);
+        scrollToElementIfNeeded(visualRef, rect, scale);
+        setShouldShowCallout(true);
+        requestAnimationFrame(() => {
+            setClickedElement(elementInfo);
+        });
+    }, [selectedElement, heatmapInfo, getRect, visualRef, scale]);
     return { clickedElement, showMissingElement, shouldShowCallout, setShouldShowCallout };
 };
 
+const useElementCalloutVisible = ({ visualRef, getRect }) => {
+    const scale = useHeatmapVizStore((state) => state.scale);
+    const selectedElement = useHeatmapInteractionStore((state) => state.selectedElement);
+    const heatmapInfo = useHeatmapDataStore((state) => state.dataInfo);
+    const setShouldShowCallout = useHeatmapInteractionStore((state) => state.setShouldShowCallout);
+    useEffect(() => {
+        if (!selectedElement)
+            return;
+        const elementIsInViewportFn = () => {
+            const elementInfo = heatmapInfo?.elementMapInfo?.[selectedElement];
+            if (!elementInfo)
+                return;
+            const rect = getRect({ hash: selectedElement, selector: elementInfo.selector });
+            const isInViewport = isElementInViewport(rect, visualRef, scale);
+            setShouldShowCallout(isInViewport);
+        };
+        elementIsInViewportFn();
+        const handleUpdate = () => {
+            requestAnimationFrame(elementIsInViewportFn);
+        };
+        window.addEventListener('scroll', handleUpdate, true);
+        window.addEventListener('resize', handleUpdate);
+        visualRef?.current?.addEventListener('scroll', handleUpdate);
+        return () => {
+            window.removeEventListener('scroll', handleUpdate, true);
+            window.removeEventListener('resize', handleUpdate);
+            visualRef?.current?.removeEventListener('scroll', handleUpdate);
+        };
+    }, [selectedElement, visualRef, getRect, scale, heatmapInfo, setShouldShowCallout]);
+    return {};
+};
+
 const useHeatmapEffects = ({ isVisible, isElementSidebarOpen, setShouldShowCallout, resetAll, }) => {
     const selectedElement = useHeatmapInteractionStore((state) => state.selectedElement);
     // Reset khi ẩn
@@ -305,32 +546,6 @@ const useHeatmapEffects = ({ isVisible, isElementSidebarOpen, setShouldShowCallo
     }, [isElementSidebarOpen, selectedElement, setShouldShowCallout]);
 };
 
-function getElementLayout(element) {
-    if (!element?.getBoundingClientRect)
-        return null;
-    const rect = element.getBoundingClientRect();
-    if (rect.width === 0 && rect.height === 0)
-        return null;
-    return {
-        top: rect.top,
-        left: rect.left,
-        width: rect.width,
-        height: rect.height,
-    };
-}
-function formatPercentage(value, decimals = 2) {
-    return value.toFixed(decimals);
-}
-function calculateRankPosition(rect, widthScale) {
-    const top = rect.top <= 18 ? rect.top + 3 : rect.top - 18;
-    const left = rect.left <= 18 ? rect.left + 3 : rect.left - 18;
-    return {
-        transform: `scale(${1.2 * widthScale})`,
-        top: Number.isNaN(top) ? undefined : top,
-        left: Number.isNaN(left) ? undefined : left,
-    };
-}
-
 const useHeatmapElementPosition = ({ iframeRef, wrapperRef, visualizer }) => {
     const widthScale = useHeatmapVizStore((state) => state.scale);
     const iframeHeight = useHeatmapVizStore((state) => state.iframeHeight);
@@ -380,70 +595,63 @@ const debounce = (fn, delay) => {
         timeout = setTimeout(() => fn(...args), delay);
     };
 };
+
 const useHoveredElement = ({ iframeRef, getRect }) => {
     const hoveredElement = useHeatmapInteractionStore((state) => state.hoveredElement);
     const setHoveredElement = useHeatmapInteractionStore((state) => state.setHoveredElement);
     const onSelect = useHeatmapInteractionStore((state) => state.setSelectedElement);
     const widthScale = useHeatmapVizStore((state) => state.scale);
     const heatmapInfo = useHeatmapDataStore((state) => state.dataInfo);
-    const handleMouseMove = useCallback(debounce((event) => {
-        if (!iframeRef.current?.contentDocument || !heatmapInfo?.elementMapInfo) {
-            setHoveredElement(null);
+    const reset = useCallback(() => {
+        setHoveredElement(null);
+    }, [setHoveredElement]);
+    const handleMouseLeave = useCallback(() => {
+        reset();
+    }, [reset]);
+    const getHashFromEvent = useCallback((event) => {
+        if (!heatmapInfo || !isIframeReady(iframeRef, heatmapInfo)) {
+            reset();
             return;
         }
         const iframe = iframeRef.current;
-        const iframeRect = iframe.getBoundingClientRect();
-        let x = event.clientX - iframeRect.left;
-        let y = event.clientY - iframeRect.top;
-        if (widthScale !== 1) {
-            x /= widthScale;
-            y /= widthScale;
-        }
         const doc = iframe.contentDocument;
-        if (!doc) {
-            setHoveredElement(null);
+        const iframeRect = iframe.getBoundingClientRect();
+        const { x, y } = convertViewportToIframeCoords(event.clientX, event.clientY, iframeRect, widthScale);
+        const targetElement = findTargetElement(doc, x, y);
+        if (!targetElement || !isValidElement(targetElement, heatmapInfo)) {
+            reset();
             return;
         }
-        let targetElement = getElementAtPoint(doc, x, y) || null;
-        if (!targetElement) {
-            targetElement = doc.elementFromPoint(x, y);
-        }
-        if (!targetElement) {
-            setHoveredElement(null);
+        const hash = getElementHash(targetElement);
+        if (!!hash)
+            return hash;
+        reset();
+        return;
+    }, [heatmapInfo, iframeRef, getRect, widthScale, reset]);
+    const handleMouseMove = useCallback(debounce((event) => {
+        if (!heatmapInfo) {
+            reset();
             return;
         }
-        const hash = targetElement.getAttribute('data-clarity-hash') ||
-            targetElement.getAttribute('data-clarity-hashalpha') ||
-            targetElement.getAttribute('data-clarity-hashbeta');
-        if (!hash || !heatmapInfo.elementMapInfo[hash]) {
-            setHoveredElement(null);
+        const hash = getHashFromEvent(event);
+        if (!hash) {
+            reset();
             return;
         }
-        const info = heatmapInfo.elementMapInfo[hash];
-        const position = getRect({ hash, selector: info.selector });
-        if (position && heatmapInfo.sortedElements) {
-            const rank = heatmapInfo.sortedElements.findIndex((e) => e.hash === hash) + 1;
-            setHoveredElement({
-                ...position,
-                hash,
-                clicks: info.totalclicks ?? 0,
-                rank,
-                selector: info.selector ?? '',
-            });
-        }
-        else {
-            setHoveredElement(null);
+        const selector = heatmapInfo?.elementMapInfo?.[hash];
+        const rect = getRect({ hash, selector });
+        const elementInfo = buildElementInfo(hash, rect, heatmapInfo);
+        if (!elementInfo) {
+            reset();
+            return;
         }
-    }, 16), // ~60fps
-    [iframeRef, heatmapInfo, getRect]);
-    const handleMouseLeave = useCallback(() => {
-        setHoveredElement(null);
-    }, []);
+        setHoveredElement(elementInfo);
+    }, 16), [heatmapInfo, getRect, reset, getHashFromEvent]);
     const handleClick = useCallback(() => {
-        if (hoveredElement?.hash && onSelect) {
-            onSelect(hoveredElement.hash);
-        }
-    }, [hoveredElement, onSelect]);
+        if (!hoveredElement?.hash)
+            return;
+        onSelect(hoveredElement.hash);
+    }, [hoveredElement?.hash]);
     return {
         hoveredElement,
         handleMouseMove,
@@ -451,17 +659,32 @@ const useHoveredElement = ({ iframeRef, getRect }) => {
         handleClick,
     };
 };
-const getElementAtPoint = (doc, x, y) => {
-    let el = null;
-    if ('caretPositionFromPoint' in doc) {
-        el = doc.caretPositionFromPoint(x, y)?.offsetNode ?? null;
+const convertViewportToIframeCoords = (clientX, clientY, iframeRect, scale) => {
+    let x = clientX - iframeRect.left;
+    let y = clientY - iframeRect.top;
+    if (scale !== 1) {
+        x /= scale;
+        y /= scale;
     }
-    el = el ?? doc.elementFromPoint(x, y);
-    let element = el;
-    while (element && element.nodeType === Node.TEXT_NODE) {
-        element = element.parentElement;
+    return { x, y };
+};
+const findTargetElement = (doc, x, y) => {
+    let targetElement = getElementAtPoint(doc, x, y);
+    if (!targetElement) {
+        targetElement = doc.elementFromPoint(x, y);
     }
-    return element;
+    return targetElement;
+};
+const isIframeReady = (iframeRef, heatmapInfo) => {
+    return !!(iframeRef.current?.contentDocument && heatmapInfo?.elementMapInfo);
+};
+const isValidElement = (element, heatmapInfo) => {
+    if (!element)
+        return false;
+    const hash = getElementHash(element);
+    if (!hash)
+        return false;
+    return !!heatmapInfo?.elementMapInfo?.[hash];
 };
 
 const useHeatmapRender = () => {
@@ -834,7 +1057,7 @@ const useHeatmapScale = (props) => {
     };
 };
 
-const BoxStack = ({ children, ...props }) => {
+const BoxStack = forwardRef(({ children, ...props }, ref) => {
     const id = props.id;
     const flexDirection = props.flexDirection;
     const overflow = props.overflow || 'hidden';
@@ -845,6 +1068,8 @@ const BoxStack = ({ children, ...props }) => {
     const style = props.style || {};
     const gap = props.gap || 0;
     const height = props.height || 'auto';
+    const zIndex = props.zIndex || 0;
+    const backgroundColor = props.backgroundColor || 'transparent';
     const styleGap = useMemo(() => {
         switch (flexDirection) {
             case 'row':
@@ -866,15 +1091,17 @@ const BoxStack = ({ children, ...props }) => {
         justifyContent,
         alignItems,
         height,
+        zIndex,
+        backgroundColor,
         ...styleGap,
         ...style,
     };
-    return (jsx("div", { id: id, style: styleProps, children: children }));
-};
+    return (jsx("div", { id: id, style: styleProps, ref: ref, children: children }));
+});
 
 const ContentTopBar = () => {
     const controls = useHeatmapControlStore((state) => state.controls);
-    return (jsx(BoxStack, { id: "gx-hm-content-header", flexDirection: "row", alignItems: "center", overflow: "auto", style: {
+    return (jsx(BoxStack, { id: "gx-hm-content-header", flexDirection: "row", alignItems: "center", overflow: "auto", zIndex: 1, backgroundColor: "white", style: {
             borderBottom: `${HEATMAP_CONFIG.borderWidth}px solid ${HEATMAP_CONFIG.borderColor}`,
         }, children: controls.TopBar ?? null }));
 };
@@ -912,110 +1139,14 @@ const useHeatmapVizCanvas = ({ type }) => {
     return heatmapRender?.();
 };
 
-const CLICKED_ELEMENT_ID = 'clickedElement';
-const SECONDARY_CLICKED_ELEMENT_ID = 'secondaryClickedElementID';
-const HOVERED_ELEMENT_ID = 'hoveredElement';
-const SECONDARY_HOVERED_ELEMENT_ID = 'secondaryhoveredElementID';
-
-const ElementCallout = (props) => {
-    const { element, target, isSecondary, language, wrapperRef } = props;
-    const heatmapInfo = useHeatmapDataStore((state) => state.dataInfo);
-    const calloutRef = useRef(null);
-    const [position, setPosition] = useState({
-        top: 0,
-        left: 0,
-        placement: 'top',
-    });
-    const totalClicks = heatmapInfo?.totalClicks ?? 1;
-    const percentage = formatPercentage(((element.clicks ?? 0) / totalClicks) * 100, 2);
-    useEffect(() => {
-        const targetElement = document.querySelector(target);
-        const calloutElement = calloutRef.current;
-        if (!targetElement || !calloutElement)
-            return;
-        const calculatePosition = () => {
-            const targetRect = targetElement.getBoundingClientRect();
-            const calloutRect = calloutElement.getBoundingClientRect();
-            const viewportWidth = window.innerWidth;
-            const viewportHeight = window.innerHeight;
-            const padding = 12; // Space between target and callout
-            const arrowSize = 8;
-            let top = 0;
-            let left = 0;
-            let placement = 'top';
-            const positions = [
-                {
-                    placement: 'top',
-                    top: targetRect.top - calloutRect.height - padding - arrowSize,
-                    left: targetRect.left + targetRect.width / 2 - calloutRect.width / 2,
-                    valid: targetRect.top - calloutRect.height - padding - arrowSize > 0,
-                },
-                {
-                    placement: 'bottom',
-                    top: targetRect.bottom + padding + arrowSize,
-                    left: targetRect.left + targetRect.width / 2 - calloutRect.width / 2,
-                    valid: targetRect.bottom + calloutRect.height + padding + arrowSize < viewportHeight,
-                },
-                {
-                    placement: 'right',
-                    top: targetRect.top + targetRect.height / 2 - calloutRect.height / 2,
-                    left: targetRect.right + padding + arrowSize,
-                    valid: targetRect.right + calloutRect.width + padding + arrowSize < viewportWidth,
-                },
-                {
-                    placement: 'left',
-                    top: targetRect.top + targetRect.height / 2 - calloutRect.height / 2,
-                    left: targetRect.left - calloutRect.width - padding - arrowSize,
-                    valid: targetRect.left - calloutRect.width - padding - arrowSize > 0,
-                },
-            ];
-            // Find first valid position
-            const validPosition = positions.find((p) => p.valid) || positions[0];
-            top = validPosition.top;
-            left = validPosition.left;
-            placement = validPosition.placement;
-            // Keep within viewport bounds
-            left = Math.max(padding, Math.min(left, viewportWidth - calloutRect.width - padding));
-            top = Math.max(padding, Math.min(top, viewportHeight - calloutRect.height - padding));
-            setPosition({ top, left, placement });
-        };
-        calculatePosition();
-        const handleUpdate = () => {
-            requestAnimationFrame(calculatePosition);
-        };
-        window.addEventListener('scroll', handleUpdate, true);
-        window.addEventListener('resize', handleUpdate);
-        wrapperRef?.current?.addEventListener('scroll', handleUpdate);
-        return () => {
-            window.removeEventListener('scroll', handleUpdate, true);
-            window.removeEventListener('resize', handleUpdate);
-            wrapperRef?.current?.removeEventListener('scroll', handleUpdate);
-        };
-    }, [target, wrapperRef]);
-    const calloutContent = (jsxs("div", { ref: calloutRef, className: `clarity-callout clarity-callout--${position.placement} ${isSecondary ? 'clarity-callout--secondary' : ''}`, style: {
-            position: 'fixed',
-            top: position.top,
-            left: position.left,
-            zIndex: 2147483647,
-        }, "aria-live": "assertive", role: "tooltip", children: [jsx("div", { className: "clarity-callout__arrow" }), jsx("div", { className: "clarity-callout__content", children: jsxs("div", { className: "clarity-callout__stats", children: [jsx("div", { className: "clarity-callout__label", children: "Clicks" }), jsxs("div", { className: "clarity-callout__value", children: [jsx("span", { className: "clarity-callout__count", children: element.clicks?.toLocaleString(language) }), jsxs("span", { className: "clarity-callout__percentage", children: ["(", percentage, "%)"] })] })] }) })] }));
-    return createPortal(calloutContent, document.getElementById('gx-hm-viz-container'));
-};
+const CLICKED_ELEMENT_ID = 'gx-hm-clicked-element';
+const SECONDARY_CLICKED_ELEMENT_ID = 'gx-hm-secondary-clicked-element';
+const HOVERED_ELEMENT_ID = 'gx-hm-hovered-element';
+const SECONDARY_HOVERED_ELEMENT_ID = 'gx-hm-secondary-hovered-element';
 
 const RankBadge = ({ index, elementRect, widthScale, clickOnElement, }) => {
     const style = calculateRankPosition(elementRect, widthScale);
-    return (jsx("div", { className: "rankBadge", style: style, onClick: clickOnElement, "data-testid": "elementRank", children: index }));
-};
-
-const ClickedElementOverlay = ({ element, shouldShowCallout, isSecondary, targetId, }) => {
-    const widthScale = useHeatmapVizStore((state) => state.scale);
-    if (!element || (element.width === 0 && element.height === 0))
-        return null;
-    return (jsxs(Fragment$1, { children: [jsx("div", { className: "heatmapElement", id: targetId, style: {
-                    top: element.top,
-                    left: element.left,
-                    width: element.width,
-                    height: element.height,
-                } }), jsx(RankBadge, { index: element.rank, elementRect: element, widthScale: widthScale }), shouldShowCallout && (jsx(ElementCallout, { element: element, target: `#${targetId}`, isSecondary: isSecondary }))] }));
+    return (jsx("div", { className: "gx-hm-rank-badge", style: style, onClick: clickOnElement, children: index }));
 };
 
 const NUMBER_OF_TOP_ELEMENTS = 10;
@@ -1033,27 +1164,57 @@ const DefaultRankBadges = ({ getRect, hidden }) => {
         }) }));
 };
 
-const HoveredElementOverlay = ({ element, onClick, isSecondary, targetId, }) => {
-    if (!element)
-        return null;
-    // Iframe has border, so we need to add it to the top position
-    const top = element.top + HEATMAP_CONFIG['borderWidthIframe'];
-    const left = element.left + HEATMAP_CONFIG['borderWidthIframe'];
-    const width = element.width;
-    const height = element.height;
-    return (jsxs(Fragment$1, { children: [jsx("div", { onClick: onClick, className: "heatmapElement hovered", id: targetId, style: {
-                    top,
-                    left,
-                    width,
-                    height,
-                    cursor: 'pointer',
-                } }), jsx(RankBadge, { index: element.rank, elementRect: element, widthScale: 1, clickOnElement: onClick })] }));
+const DEFAULT_POSITION = {
+    top: 0,
+    left: 0,
+    placement: 'top',
+    horizontalAlign: 'center',
+};
+const ElementCallout = (props) => {
+    const CompElementCallout = useHeatmapControlStore((state) => state.controls.ElementCallout);
+    const { element, target, visualRef, hozOffset, alignment = 'left' } = props;
+    const calloutRef = useRef(null);
+    const [position, setPosition] = useState(DEFAULT_POSITION);
+    useEffect(() => {
+        const targetElm = document.querySelector(target);
+        const calloutElm = calloutRef.current;
+        if (!targetElm || !calloutElm)
+            return;
+        const positionFn = calcCalloutPosition({
+            targetElm,
+            calloutElm,
+            setPosition,
+            hozOffset,
+            alignment,
+        });
+        positionFn();
+        const handleUpdate = () => {
+            requestAnimationFrame(positionFn);
+        };
+        window.addEventListener('scroll', handleUpdate, true);
+        window.addEventListener('resize', handleUpdate);
+        visualRef?.current?.addEventListener('scroll', handleUpdate);
+        return () => {
+            window.removeEventListener('scroll', handleUpdate, true);
+            window.removeEventListener('resize', handleUpdate);
+            visualRef?.current?.removeEventListener('scroll', handleUpdate);
+        };
+    }, [target, visualRef, hozOffset, alignment]);
+    const calloutContent = (jsx("div", { ref: calloutRef, className: `clarity-callout clarity-callout--${position.placement} clarity-callout--align-${position.horizontalAlign}`, style: {
+            position: 'fixed',
+            top: position.top,
+            left: position.left,
+            zIndex: 2147483647,
+        }, "aria-live": "assertive", role: "tooltip", children: CompElementCallout && jsx(CompElementCallout, { elementHash: element.hash }) }));
+    return createPortal(calloutContent, document.getElementById('gx-hm-viz-container'));
 };
 
-const MissingElementMessage = () => {
+const ElementMissing = ({ show = true }) => {
+    if (!show)
+        return null;
     const widthScale = useHeatmapVizStore((state) => state.scale);
     return (jsx("div", { className: "missingElement", style: {
-            position: 'absolute',
+            position: 'fixed',
             top: '50%',
             left: '50%',
             transform: `translate(-50%, -50%) scale(${1 / widthScale})`,
@@ -1069,6 +1230,39 @@ const MissingElementMessage = () => {
         }, "aria-live": "assertive", children: "Element not visible on current screen" }));
 };
 
+const TARGET_ID_BY_TYPE = {
+    hovered: {
+        default: HOVERED_ELEMENT_ID,
+        secondary: SECONDARY_HOVERED_ELEMENT_ID,
+    },
+    clicked: {
+        default: CLICKED_ELEMENT_ID,
+        secondary: SECONDARY_CLICKED_ELEMENT_ID,
+    },
+};
+const ElementOverlay = ({ type, element, onClick, isSecondary }) => {
+    const widthScale = useHeatmapVizStore((state) => state.scale);
+    if (!element || (element.width === 0 && element.height === 0))
+        return null;
+    // Iframe has border, so we need to add it to the top position
+    const top = element.top + HEATMAP_CONFIG['borderWidthIframe'];
+    const left = element.left + HEATMAP_CONFIG['borderWidthIframe'];
+    const width = element.width;
+    const height = element.height;
+    const targetId = TARGET_ID_BY_TYPE[type][isSecondary ? 'secondary' : 'default'];
+    return (jsxs(Fragment$1, { children: [jsx("div", { onClick: onClick, className: "heatmapElement", id: targetId, style: {
+                    top,
+                    left,
+                    width,
+                    height,
+                    cursor: 'pointer',
+                } }), jsx(RankBadge, { index: element.rank, elementRect: element, widthScale: type === 'hovered' ? 1 : widthScale, clickOnElement: onClick })] }));
+};
+
+const ELEMENT_CALLOUT = {
+    hozOffset: -8,
+    alignment: 'left',
+};
 const HeatmapElements = (props) => {
     const height = useHeatmapVizStore((state) => state.iframeHeight);
     const { iframeRef, wrapperRef, visualRef, visualizer, iframeDimensions, isElementSidebarOpen, isVisible = true, areDefaultRanksHidden, isSecondary, ...rest } = props;
@@ -1078,15 +1272,17 @@ const HeatmapElements = (props) => {
         visualizer,
     });
     const { clickedElement, showMissingElement, shouldShowCallout, setShouldShowCallout } = useClickedElement({
-        iframeRef,
         visualRef,
-        wrapperRef,
         getRect,
     });
     const { hoveredElement, handleMouseMove, handleMouseLeave, handleClick } = useHoveredElement({
         iframeRef,
         getRect,
     });
+    useElementCalloutVisible({
+        visualRef,
+        getRect,
+    });
     const resetAll = () => {
         // setShouldShowCallout(false);
     };
@@ -1098,7 +1294,7 @@ const HeatmapElements = (props) => {
     });
     if (!isVisible)
         return null;
-    return (jsxs("div", { onMouseMove: handleMouseMove, onMouseLeave: handleMouseLeave, className: "heatmapElements gx-hm-elements", style: { ...iframeDimensions, height }, children: [jsx(DefaultRankBadges, { getRect: getRect, hidden: areDefaultRanksHidden }), jsx(ClickedElementOverlay, { element: clickedElement, shouldShowCallout: shouldShowCallout, isSecondary: isSecondary, targetId: isSecondary ? SECONDARY_CLICKED_ELEMENT_ID : CLICKED_ELEMENT_ID, ...rest }), showMissingElement && jsx(MissingElementMessage, {}), jsx(HoveredElementOverlay, { element: hoveredElement, onClick: handleClick, isSecondary: isSecondary, targetId: isSecondary ? SECONDARY_HOVERED_ELEMENT_ID : HOVERED_ELEMENT_ID }), hoveredElement?.hash !== clickedElement?.hash && hoveredElement && (jsx(ElementCallout, { element: hoveredElement, target: `#${props.isSecondary ? SECONDARY_HOVERED_ELEMENT_ID : HOVERED_ELEMENT_ID}`, isSecondary: props.isSecondary, wrapperRef: props.wrapperRef }))] }));
+    return (jsxs("div", { onMouseMove: handleMouseMove, onMouseLeave: handleMouseLeave, className: "gx-hm-elements", style: { ...iframeDimensions, height }, children: [jsx(ElementMissing, { show: showMissingElement }), jsx(DefaultRankBadges, { getRect: getRect, hidden: areDefaultRanksHidden }), jsx(ElementOverlay, { type: "clicked", element: clickedElement, isSecondary: isSecondary }), jsx(ElementOverlay, { type: "hovered", element: hoveredElement, isSecondary: isSecondary, onClick: handleClick }), hoveredElement?.hash !== clickedElement?.hash && hoveredElement && (jsx(ElementCallout, { element: hoveredElement, target: `#${HOVERED_ELEMENT_ID}`, visualRef: visualRef, ...ELEMENT_CALLOUT })), shouldShowCallout && clickedElement && (jsx(ElementCallout, { element: clickedElement, target: `#${CLICKED_ELEMENT_ID}`, visualRef: visualRef, ...ELEMENT_CALLOUT }))] }));
 };
 
 const VizElements = ({ iframeRef, visualRef, wrapperRef }) => {
@@ -1227,7 +1423,7 @@ const VizDomContainer = () => {
 
 const ContentMetricBar = () => {
     const controls = useHeatmapControlStore((state) => state.controls);
-    return (jsx(BoxStack, { id: "gx-hm-content-header", flexDirection: "row", alignItems: "center", overflow: "auto", style: {
+    return (jsx(BoxStack, { id: "gx-hm-content-metric-bar", flexDirection: "row", alignItems: "center", overflow: "auto", zIndex: 1, backgroundColor: "white", style: {
             borderBottom: `${HEATMAP_CONFIG.borderWidth}px solid ${HEATMAP_CONFIG.borderColor}`,
         }, children: controls.MetricBar ?? null }));
 };