@gemx-dev/heatmap-react 3.5.21 → 3.5.23

package/src/hooks/vix-elements/useHeatmapElementPosition.ts

@@ -0,0 +1,66 @@
+import type { ElementRect, HeatmapElement, WebVisualizer } from '../../types';
+
+import { useCallback } from 'react';
+import { getElementLayout } from '../../helpers/viz-elements';
+
+interface Params {
+  iframeRef: React.RefObject<HTMLIFrameElement>;
+  parentRef: React.RefObject<HTMLElement>;
+  visualizer?: WebVisualizer;
+  heatmapWidth?: number;
+  iframeHeight?: number;
+  widthScale: number;
+  projectId?: string;
+}
+
+export const useHeatmapElementPosition = ({
+  iframeRef,
+  parentRef,
+  visualizer,
+  heatmapWidth,
+  iframeHeight,
+  widthScale,
+  projectId,
+}: Params) => {
+  return useCallback(
+    (element?: HeatmapElement): ElementRect | null => {
+      const hash = element?.hash;
+      if (!iframeRef.current?.contentDocument || !hash || !visualizer) return null;
+
+      let domElement: HTMLElement | null = null;
+      try {
+        domElement = visualizer.get(hash);
+      } catch (error) {
+        console.error('Visualizer error:', { projectId, hash, error });
+        return null;
+      }
+
+      if (!domElement) return null;
+
+      const layout = getElementLayout(domElement);
+      if (!layout) return null;
+
+      const parentEl = parentRef.current;
+      if (!parentEl) return null;
+
+      const scrollOffset = parentEl.scrollTop / widthScale;
+      const adjustedTop = layout.top + scrollOffset;
+
+      const outOfBounds =
+        adjustedTop < 0 ||
+        adjustedTop > (iframeHeight || Infinity) ||
+        layout.left < 0 ||
+        (typeof heatmapWidth === 'number' && layout.left > heatmapWidth);
+
+      if (outOfBounds) return null;
+
+      return {
+        left: layout.left,
+        top: adjustedTop,
+        width: Math.min(layout.width, heatmapWidth || layout.width),
+        height: layout.height,
+      };
+    },
+    [iframeRef, parentRef, visualizer, heatmapWidth, iframeHeight, widthScale, projectId],
+  );
+};

package/src/hooks/vix-elements/useHoveredElement.ts

@@ -0,0 +1,135 @@
+import type { ElementInfo, HeatmapInfo } from '../../types';
+
+import { useCallback, useState } from 'react';
+
+const debounce = <T extends (...args: any[]) => void>(
+  fn: T,
+  delay: number,
+): ((...args: Parameters<T>) => void) => {
+  let timeout: ReturnType<typeof setTimeout>;
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => fn(...args), delay);
+  };
+};
+
+interface Params {
+  iframeRef: React.RefObject<HTMLIFrameElement>;
+  heatmapInfo?: HeatmapInfo;
+  widthScale: number;
+  getRect: (el?: any) => any;
+  onSelect?: (hash: string) => void;
+}
+
+export const useHoveredElement = ({
+  iframeRef,
+  heatmapInfo,
+  widthScale,
+  getRect,
+  onSelect,
+}: Params) => {
+  const [hoveredElement, setHoveredElement] = useState<ElementInfo | null>(null);
+
+  const handleMouseMove = useCallback(
+    debounce((event: React.MouseEvent<HTMLDivElement>) => {
+      if (!iframeRef.current?.contentDocument || !heatmapInfo?.elementMapInfo) {
+        setHoveredElement(null);
+        return;
+      }
+
+      const iframe = iframeRef.current;
+      const iframeRect = iframe.getBoundingClientRect();
+
+      let x = event.clientX - iframeRect.left;
+      console.log(`🚀 🐥 ~ useHoveredElement ~ iframeRect.left:`, iframeRect.left);
+      console.log(`🚀 🐥 ~ useHoveredElement ~ event.clientX:`, event.clientX);
+      let y = event.clientY - iframeRect.top;
+
+      if (widthScale !== 1) {
+        x /= widthScale;
+        y /= widthScale;
+      }
+      const doc: Document | null = iframe.contentDocument;
+      if (!doc) {
+        setHoveredElement(null);
+        return;
+      }
+
+      let targetElement: HTMLElement | null = null;
+
+      // Best: dùng caretPositionFromPoint nếu có (Chrome, Safari)
+      targetElement = getElementAtPoint(doc, x, y);
+
+      if (!targetElement) {
+        targetElement = doc.elementFromPoint(x, y) as HTMLElement | null;
+      }
+
+      if (!targetElement) {
+        setHoveredElement(null);
+        return;
+      }
+
+      // Lấy hash từ nhiều attribute khả dĩ
+      const hash =
+        targetElement.getAttribute('data-clarity-hash') ||
+        targetElement.getAttribute('data-clarity-hashalpha') ||
+        targetElement.getAttribute('data-clarity-hashbeta');
+
+      if (!hash || !heatmapInfo.elementMapInfo[hash]) {
+        setHoveredElement(null);
+        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);
+      }
+    }, 16), // ~60fps
+    [iframeRef, heatmapInfo, getRect],
+  );
+
+  const handleMouseLeave = useCallback(() => {
+    setHoveredElement(null);
+  }, []);
+
+  const handleClick = useCallback(() => {
+    if (hoveredElement?.hash && onSelect) {
+      onSelect(hoveredElement.hash);
+    }
+  }, [hoveredElement, onSelect]);
+
+  return {
+    hoveredElement,
+    handleMouseMove,
+    handleMouseLeave,
+    handleClick,
+  };
+};
+
+export const getElementAtPoint = (doc: Document, x: number, y: number): HTMLElement | null => {
+  let el: Node | null = null;
+
+  if ('caretPositionFromPoint' in doc) {
+    el = doc.caretPositionFromPoint(x, y)?.offsetNode ?? null;
+  }
+
+  el = el ?? doc.elementFromPoint(x, y);
+
+  let element = el as HTMLElement | null;
+  while (element && element.nodeType === Node.TEXT_NODE) {
+    element = element.parentElement;
+  }
+  return element;
+};

package/src/hooks/viz-render/index.ts

@@ -0,0 +1 @@
+export * from './useHeatmapVizRender';

package/src/hooks/viz-render/useHeatmapRender.ts

@@ -0,0 +1,98 @@
+import { Data } from '@gemx-dev/clarity-decode';
+import { Visualizer } from '@gemx-dev/clarity-visualize';
+import { useCallback, useEffect, useRef } from 'react';
+import { recreateIframe } from '../../helpers';
+import { useHeatmapDataStore } from '../../stores';
+import { DecodedPayload } from '../../types';
+import { isMobileDevice } from '../../utils/device';
+
+interface IUseHeatmapRenderResult {
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+  clarityVisualizer: Visualizer | null;
+}
+
+export const useHeatmapRender = (): IUseHeatmapRenderResult => {
+  const data = useHeatmapDataStore((state) => state.data);
+  const config = useHeatmapDataStore((state) => state.config);
+  const setConfig = useHeatmapDataStore((state) => state.setConfig);
+  const clickmap = useHeatmapDataStore((state) => state.clickmap);
+
+  const visualizerRef = useRef<Visualizer | null>(null);
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+
+  const initializeVisualizer = useCallback((envelope: Data.Envelope, userAgent: string) => {
+    const iframe = iframeRef.current;
+    if (!iframe?.contentWindow) return null;
+
+    const visualizer = new Visualizer();
+    const mobile = isMobileDevice(userAgent);
+    visualizer.setup(iframe.contentWindow, {
+      version: envelope.version,
+      onresize: (width: number) => {
+        setConfig({ width });
+      },
+      mobile,
+      vNext: true,
+      locale: 'en-us',
+    });
+
+    return visualizer;
+  }, []);
+
+  // Process and render heatmap HTML
+  const renderHeatmap = useCallback(
+    async (payloads: DecodedPayload[]) => {
+      if (!payloads || payloads.length === 0) return;
+
+      let visualizer = new Visualizer();
+      const iframe = recreateIframe(iframeRef, config);
+      // const merged = visualizer.merge(payloads);
+      // setIframeHeight(Number(iframeRef.current?.height || 0));
+      // for (const decoded of payloads) {
+      //   // Initialize on first sequence
+      //   if (decoded.envelope.sequence === 1) {
+      //     const userAgent = (decoded.dimension?.[0]?.data[0]?.[0] as string) || '';
+      //     visualizer = initializeVisualizer(decoded.envelope as any, userAgent);
+
+      //     if (!visualizer) return;
+      //     visualizerRef.current = visualizer;
+      //   }
+
+      //   if (!visualizer) continue;
+
+      //   // Merge and process DOM
+      //   const merged = visualizer.merge([decoded]);
+      //   visualizer.dom(merged.dom);
+      // }
+
+      // Render static HTML
+      if (visualizer && iframe?.contentWindow) {
+        await visualizer.html(payloads, iframe.contentWindow);
+        visualizerRef.current = visualizer;
+      }
+    },
+    [initializeVisualizer],
+  );
+
+  useEffect(() => {
+    if (!data || data.length === 0) return;
+
+    renderHeatmap(data);
+
+    return () => {
+      visualizerRef.current = null;
+    };
+  }, [config, data, renderHeatmap]);
+
+  useEffect(() => {
+    if (!visualizerRef.current || !clickmap || clickmap.length === 0) return;
+
+    visualizerRef.current.clearmap();
+    visualizerRef.current?.clickmap(clickmap);
+  }, [clickmap]);
+
+  return {
+    iframeRef,
+    clarityVisualizer: visualizerRef.current,
+  };
+};

package/src/hooks/viz-render/useHeatmapVizRender.ts

@@ -0,0 +1,22 @@
+import { useMemo } from 'react';
+import { useHeatmapRender } from './useHeatmapRender';
+import { useReplayRender } from './useReplayRender';
+import { Visualizer } from '@gemx-dev/clarity-visualize';
+
+interface IHeatmapVizRenderResult {
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+  clarityVisualizer: Visualizer | null;
+}
+
+export const useHeatmapVizRender = (mode: 'heatmap' | 'replay'): IHeatmapVizRenderResult => {
+  const heatmapResult = useMemo(() => {
+    switch (mode) {
+      case 'heatmap':
+        return useHeatmapRender;
+      case 'replay':
+        return useReplayRender;
+    }
+  }, [mode]);
+
+  return heatmapResult();
+};

package/src/hooks/viz-render/useReplayRender.ts

@@ -0,0 +1,162 @@
+import { Data } from '@gemx-dev/clarity-decode';
+import { Visualizer } from '@gemx-dev/clarity-visualize';
+import { useCallback, useEffect, useRef } from 'react';
+import { useHeatmapDataStore } from '../../stores';
+import { DecodedEvents, DecodedPayload } from '../../types';
+import { isMobileDevice } from '../../utils/device';
+import { sortEvents } from '../../utils/sort';
+
+interface IUseReplayRenderResult {
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+  isPlaying: boolean;
+  clarityVisualizer: Visualizer | null;
+  play: () => void;
+  pause: () => void;
+}
+
+export const useReplayRender = (): IUseReplayRenderResult => {
+  const data = useHeatmapDataStore((state) => state.data);
+  const setConfig = useHeatmapDataStore((state) => state.setConfig);
+
+  const visualizerRef = useRef<Visualizer | null>(null);
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const eventsRef = useRef<DecodedEvents>([]);
+  const animationFrameRef = useRef<number | null>(null);
+  const isPlayingRef = useRef<boolean>(false);
+
+  // Initialize visualizer for replay
+  const initializeVisualizer = useCallback(
+    (envelope: Data.Envelope, userAgent: string) => {
+      const iframe = iframeRef.current;
+      if (!iframe?.contentWindow) return null;
+
+      // Clear previous events
+      eventsRef.current = [];
+
+      const visualizer = new Visualizer();
+      const mobile = isMobileDevice(userAgent);
+
+      visualizer.setup(iframe.contentWindow, {
+        version: envelope.version,
+        onresize: (width: number) => {
+          setConfig({ width });
+        },
+        mobile,
+        vNext: true,
+        locale: 'en-us',
+      });
+
+      return visualizer;
+    },
+    [setConfig],
+  );
+
+  // Animation loop for replay
+  const replayLoop = useCallback(() => {
+    if (!isPlayingRef.current) return;
+
+    const events = eventsRef.current;
+    const visualizer = visualizerRef.current;
+
+    if (!visualizer || events.length === 0) {
+      animationFrameRef.current = requestAnimationFrame(replayLoop);
+      return;
+    }
+
+    const event = events[0];
+    const end = event.time + 16; // 60FPS => 16ms per frame
+    let index = 0;
+
+    // Get events within current frame
+    while (events[index] && events[index].time < end) {
+      index++;
+    }
+
+    // Render events for this frame
+    if (index > 0) {
+      visualizer.render(events.splice(0, index) as any);
+    }
+
+    animationFrameRef.current = requestAnimationFrame(replayLoop);
+  }, []);
+
+  // Start replay
+  const startReplay = useCallback(
+    async (payloads: DecodedPayload[]) => {
+      if (!payloads || payloads.length === 0) return;
+
+      let visualizer = visualizerRef.current;
+
+      for (const decoded of payloads) {
+        // Initialize on first sequence
+        if (decoded.envelope.sequence === 1) {
+          const userAgent = (decoded.dimension?.[0]?.data[0]?.[0] as string) || '';
+          visualizer = initializeVisualizer(decoded.envelope as any, userAgent);
+
+          if (!visualizer) return;
+          visualizerRef.current = visualizer;
+        }
+
+        if (!visualizer) continue;
+
+        // Merge events and DOM
+        const merged = visualizer.merge([decoded]);
+        eventsRef.current = eventsRef.current.concat(merged.events).sort(sortEvents);
+        visualizer.dom(merged.dom);
+      }
+
+      // Render HTML
+      if (visualizer && iframeRef.current?.contentWindow) {
+        await visualizer.html(payloads, iframeRef.current.contentWindow);
+      }
+
+      // Auto-start replay
+      isPlayingRef.current = true;
+      animationFrameRef.current = requestAnimationFrame(replayLoop);
+    },
+    [initializeVisualizer, replayLoop],
+  );
+
+  // Play control
+  const play = useCallback(() => {
+    if (!isPlayingRef.current) {
+      isPlayingRef.current = true;
+      animationFrameRef.current = requestAnimationFrame(replayLoop);
+    }
+  }, [replayLoop]);
+
+  // Pause control
+  const pause = useCallback(() => {
+    isPlayingRef.current = false;
+    if (animationFrameRef.current) {
+      cancelAnimationFrame(animationFrameRef.current);
+      animationFrameRef.current = null;
+    }
+  }, []);
+
+  // Main effect: Start replay when data changes
+  useEffect(() => {
+    if (!data || data.length === 0) return;
+
+    startReplay(data);
+
+    // Cleanup
+    return () => {
+      isPlayingRef.current = false;
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current);
+        animationFrameRef.current = null;
+      }
+      eventsRef.current = [];
+      visualizerRef.current = null;
+    };
+  }, [data, startReplay]);
+
+  return {
+    iframeRef,
+    isPlaying: isPlayingRef.current,
+    clarityVisualizer: visualizerRef.current,
+    play,
+    pause,
+  };
+};

package/src/hooks/viz-scale/index.ts

@@ -0,0 +1 @@
+export * from './useHeatmapScale';

package/src/hooks/viz-scale/useContainerDimensions.ts

@@ -0,0 +1,46 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+interface IUseContainerDimensionsProps {
+  wrapperRef: React.RefObject<HTMLDivElement | null>;
+}
+
+interface IUseContainerDimensionsResult {
+  containerWidth: number;
+  containerHeight: number;
+}
+
+export const useContainerDimensions = (
+  props: IUseContainerDimensionsProps,
+): IUseContainerDimensionsResult => {
+  const { wrapperRef } = props;
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [containerHeight, setContainerHeight] = useState(0);
+  const resizeObserverRef = useRef<ResizeObserver | null>(null);
+
+  const updateDimensions = useCallback(() => {
+    const scrollContainer = wrapperRef.current?.parentElement?.parentElement;
+    if (scrollContainer) {
+      setContainerWidth(scrollContainer.clientWidth);
+      setContainerHeight(scrollContainer.clientHeight);
+    }
+  }, [wrapperRef]);
+
+  useEffect(() => {
+    const scrollContainer = wrapperRef.current?.parentElement?.parentElement;
+    if (!scrollContainer || typeof window.ResizeObserver === 'undefined') {
+      return;
+    }
+
+    resizeObserverRef.current = new ResizeObserver(updateDimensions);
+    resizeObserverRef.current.observe(scrollContainer);
+    updateDimensions();
+
+    return () => {
+      if (resizeObserverRef.current && scrollContainer) {
+        resizeObserverRef.current.unobserve(scrollContainer);
+      }
+    };
+  }, [wrapperRef, updateDimensions]);
+
+  return { containerWidth, containerHeight };
+};

package/src/hooks/viz-scale/useContentDimensions.ts

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react';
+import { IHeatmapConfig } from '../../types';
+
+interface IUseContentDimensionsProps {
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+  config?: IHeatmapConfig;
+}
+
+interface IUseContentDimensionsResult {
+  contentWidth: number;
+}
+
+export const useContentDimensions = (
+  props: IUseContentDimensionsProps,
+): IUseContentDimensionsResult => {
+  const { iframeRef, config } = props;
+  const [contentWidth, setContentWidth] = useState(0);
+
+  useEffect(() => {
+    if (config?.width) {
+      if (iframeRef.current) {
+        iframeRef.current.width = `${config.width}px`;
+      }
+      setContentWidth(config.width);
+    }
+  }, [config?.width, iframeRef]);
+
+  return { contentWidth };
+};

package/src/hooks/viz-scale/useHeatmapScale.ts

@@ -0,0 +1,53 @@
+import { IHeatmapConfig } from '../../types';
+import { useContainerDimensions } from './useContainerDimensions';
+import { useContentDimensions } from './useContentDimensions';
+import { useIframeHeight } from './useIframeHeight';
+import { useScaleCalculation } from './useScaleCalculation';
+import { useScrollSync } from './useScrollSync';
+
+interface IHeatmapScaleProps {
+  wrapperRef: React.RefObject<HTMLDivElement | null>;
+  iframeRef: React.RefObject<HTMLIFrameElement | null>;
+  config?: IHeatmapConfig;
+}
+
+interface IUseHeatmapScaleResult {
+  containerWidth: number;
+  containerHeight: number;
+  contentWidth: number;
+  scaledWidth: number;
+  scaledHeight: number;
+  iframeHeight: number;
+  scale: number;
+  handleScroll: (scrollTop: number) => void;
+}
+
+export const useHeatmapScale = (props: IHeatmapScaleProps): IUseHeatmapScaleResult => {
+  const { wrapperRef, iframeRef, config } = props;
+
+  // 1. Observe container dimensions
+  const { containerWidth, containerHeight } = useContainerDimensions({ wrapperRef });
+
+  // 2. Get content dimensions from config
+  const { contentWidth } = useContentDimensions({ iframeRef, config });
+
+  // 3. Observe iframe height (now reacts to width changes)
+  const { iframeHeight } = useIframeHeight({ iframeRef, contentWidth });
+
+  // 4. Calculate scale
+  const { scale } = useScaleCalculation({ containerWidth, contentWidth });
+
+  // 5. Setup scroll sync
+  const { handleScroll } = useScrollSync({ iframeRef, scale });
+
+  return {
+    containerWidth,
+    containerHeight,
+    contentWidth,
+    iframeHeight,
+    scale,
+    scaledWidth: contentWidth * scale,
+    scaledHeight: iframeHeight * scale,
+    handleScroll,
+  };
+};