@gemx-dev/heatmap-react 3.5.44 → 3.5.46

package/src/helpers/viz-canvas/hierarchical-area-clustering.ts

@@ -0,0 +1,420 @@
+import { ClickMapPoint, IClusterArea } from '../../types';
+
+export interface HierarchicalCluster extends IClusterArea {
+  parentHash: string | null; // Hash của parent chung
+  level: number; // Level trong DOM tree
+  children: Set<string>; // IDs của child clusters
+}
+
+interface ClickElement {
+  hash: string;
+  element: HTMLElement;
+  rect: Rect;
+  totalclicks: number;
+  level: number;
+  parents: string[]; // Danh sách hash của parents
+}
+
+const HEATMAP_GRADIENT_COLORS: [number, number, number][] = [
+  [0, 0, 255], // Blue
+  [0, 255, 255], // Cyan
+  [0, 255, 0], // Green
+  [255, 255, 0], // Yellow
+  [255, 0, 0], // Red
+];
+
+const GRADIENT_COLOR_COUNT = HEATMAP_GRADIENT_COLORS.length - 1;
+
+const CLUSTERING_CONFIG = {
+  maxDistance: 150, // Max distance để coi là cùng nhóm
+  minElements: 1, // Min elements trong cluster
+  maxClusterSize: 0.8, // Max 80% viewport size
+  minClusterSize: 30, // Min 30px
+  excludeTags: ['BODY', 'HTML', 'MAIN', 'SECTION', 'ARTICLE', 'DIV'], // Tags không nên làm parent trừ khi specific
+};
+
+export class HierarchicalAreaClusteringEngine {
+  /**
+   * Cluster areas với hierarchical logic
+   */
+  public clusterAreas(
+    clickData: ClickMapPoint[],
+    iframeDoc: Document,
+    totalClicks: number,
+  ): HierarchicalCluster[] {
+    // 1. Build click elements với hierarchy info
+    const clickElements = this.buildClickElements(clickData, iframeDoc);
+    if (clickElements.length === 0) return [];
+
+    console.log(`[HierarchicalClustering] Processing ${clickElements.length} elements`);
+
+    // 2. Group by common parent
+    const parentGroups = this.groupByCommonParent(clickElements);
+
+    console.log(`[HierarchicalClustering] Found ${parentGroups.size} parent groups`);
+
+    // 3. Create clusters from groups
+    let clusters = this.createClustersFromGroups(parentGroups, totalClicks, iframeDoc);
+
+    // 4. Remove nested clusters (child inside parent)
+    clusters = this.removeNestedClusters(clusters);
+
+    // 5. Filter out too large clusters
+    clusters = this.filterLargeClusters(clusters, iframeDoc);
+
+    // 6. Sort by click percentage
+    clusters.sort((a, b) => b.clickPercentage - a.clickPercentage);
+
+    console.log(`[HierarchicalClustering] Final: ${clusters.length} clusters`);
+
+    return clusters;
+  }
+
+  /**
+   * Build click elements với hierarchy info
+   */
+  private buildClickElements(clickData: ClickMapPoint[], iframeDoc: Document): ClickElement[] {
+    const elements: ClickElement[] = [];
+
+    clickData.forEach((item) => {
+      const element = iframeDoc.querySelector(
+        `[data-clarity-hashalpha="${item.hash}"]`,
+      ) as HTMLElement;
+
+      if (!element || item.totalclicks === 0) return;
+
+      const rect = this.getElementRect(element);
+
+      // Filter quá nhỏ
+      if (rect.width < 10 || rect.height < 10) return;
+
+      // Get DOM level
+      const level = this.getDOMLevel(element);
+
+      // Get all parent hashes
+      const parents = this.getParentHashes(element);
+
+      elements.push({
+        hash: item.hash,
+        element,
+        rect,
+        totalclicks: item.totalclicks,
+        level,
+        parents,
+      });
+    });
+
+    return elements;
+  }
+
+  /**
+   * Get DOM level (depth from body)
+   */
+  private getDOMLevel(element: HTMLElement): number {
+    let level = 0;
+    let current: HTMLElement | null = element;
+
+    while (current && current.tagName !== 'BODY') {
+      level++;
+      current = current.parentElement;
+    }
+
+    return level;
+  }
+
+  /**
+   * Get all parent hashes của element
+   */
+  private getParentHashes(element: HTMLElement): string[] {
+    const hashes: string[] = [];
+    let current: HTMLElement | null = element.parentElement;
+
+    while (current && current.tagName !== 'BODY') {
+      const hash = current.getAttribute('data-clarity-hashalpha');
+      if (hash) {
+        hashes.push(hash);
+      }
+      current = current.parentElement;
+    }
+
+    return hashes;
+  }
+
+  /**
+   * Group elements by common parent
+   */
+  private groupByCommonParent(clickElements: ClickElement[]): Map<string, ClickElement[]> {
+    const groups = new Map<string, ClickElement[]>();
+
+    // Tìm common parent cho mỗi cặp elements
+    for (let i = 0; i < clickElements.length; i++) {
+      const el1 = clickElements[i];
+      let foundGroup = false;
+
+      // Check xem el1 có thuộc group nào chưa
+      for (const [parentHash, group] of groups.entries()) {
+        // Check nếu el1 share parent với group
+        const hasCommonParent = group.some((el2) => {
+          return this.hasCommonParent(el1, el2);
+        });
+
+        if (hasCommonParent) {
+          group.push(el1);
+          foundGroup = true;
+          break;
+        }
+      }
+
+      // Nếu chưa có group, tạo group mới với parent gần nhất
+      if (!foundGroup) {
+        const parentHash = this.getBestParentHash(el1);
+        if (!groups.has(parentHash)) {
+          groups.set(parentHash, []);
+        }
+        groups.get(parentHash)!.push(el1);
+      }
+    }
+
+    return groups;
+  }
+
+  /**
+   * Check if two elements have common parent
+   */
+  private hasCommonParent(el1: ClickElement, el2: ClickElement): boolean {
+    // Check shared parents
+    const commonParents = el1.parents.filter((p) => el2.parents.includes(p));
+
+    if (commonParents.length === 0) return false;
+
+    // Cũng check khoảng cách để đảm bảo không quá xa
+    const distance = this.getDistance(el1.rect, el2.rect);
+    return distance <= CLUSTERING_CONFIG.maxDistance;
+  }
+
+  /**
+   * Get best parent hash (closest specific parent)
+   */
+  private getBestParentHash(el: ClickElement): string {
+    // Ưu tiên parent có semantic tag (không phải DIV, SECTION...)
+    for (const parentHash of el.parents) {
+      const parent = el.element.ownerDocument.querySelector(
+        `[data-clarity-hashalpha="${parentHash}"]`,
+      ) as HTMLElement;
+
+      if (parent && !CLUSTERING_CONFIG.excludeTags.includes(parent.tagName)) {
+        return parentHash;
+      }
+    }
+
+    // Fallback: parent gần nhất
+    return el.parents[0] || `element_${el.hash}`;
+  }
+
+  /**
+   * Create clusters from parent groups
+   */
+  private createClustersFromGroups(
+    groups: Map<string, ClickElement[]>,
+    totalClicks: number,
+    iframeDoc: Document,
+  ): HierarchicalCluster[] {
+    const clusters: HierarchicalCluster[] = [];
+    let index = 0;
+
+    groups.forEach((elements, parentHash) => {
+      if (elements.length === 0) return;
+
+      const totalClusterClicks = elements.reduce((sum, el) => sum + el.totalclicks || 0, 0);
+      const clickPercentage = (totalClusterClicks / totalClicks) * 100;
+
+      // Calculate smart bounding rect
+      const boundingRect = this.calculateSmartBoundingRect(elements, iframeDoc);
+
+      // Get average level
+      const avgLevel = Math.round(
+        elements.reduce((sum, el) => sum + el.level, 0) / elements.length,
+      );
+
+      const cluster: HierarchicalCluster = {
+        id: `cluster_${index++}`,
+        parentHash: parentHash === `element_${elements[0].hash}` ? null : parentHash,
+        level: avgLevel,
+        elements: elements.map((e) => e.element),
+        hashes: elements.map((e) => e.hash),
+        boundingRect,
+        totalClicks: totalClusterClicks,
+        clickPercentage,
+        color: this.getHeatmapColor(clickPercentage / 100),
+        hoverColor: this.getHoverColor(clickPercentage / 100),
+        children: new Set(),
+      };
+
+      clusters.push(cluster);
+    });
+
+    return clusters;
+  }
+
+  /**
+   * Calculate smart bounding rect - không bao trọn toàn bộ parent
+   */
+  private calculateSmartBoundingRect(elements: ClickElement[], iframeDoc: Document): Rect {
+    // Nếu chỉ có 1 element, dùng rect của nó
+    if (elements.length === 1) {
+      const rect = elements[0].rect;
+      return { ...rect, right: rect.left + rect.width, bottom: rect.top + rect.height };
+    }
+
+    // Calculate tight bounding box với moderate padding
+    const padding = 15;
+
+    const minLeft = Math.min(...elements.map((e) => e.rect.left)) - padding;
+    const minTop = Math.min(...elements.map((e) => e.rect.top)) - padding;
+    const maxRight = Math.max(...elements.map((e) => e.rect.left + e.rect.width)) + padding;
+    const maxBottom = Math.max(...elements.map((e) => e.rect.top + e.rect.height)) + padding;
+
+    return {
+      left: minLeft,
+      top: minTop,
+      width: maxRight - minLeft,
+      height: maxBottom - minTop,
+      right: maxRight,
+      bottom: maxBottom,
+    };
+  }
+
+  /**
+   * Remove nested clusters - Loại bỏ cluster con nếu nằm trong cluster cha
+   */
+  private removeNestedClusters(clusters: HierarchicalCluster[]): HierarchicalCluster[] {
+    const filtered: HierarchicalCluster[] = [];
+
+    // Sort by level (lower level = closer to root = parent)
+    const sorted = [...clusters].sort((a, b) => a.level - b.level);
+
+    for (const cluster of sorted) {
+      // Check if cluster is nested inside any existing filtered cluster
+      const isNested = filtered.some((parent) => {
+        return this.isClusterNested(cluster, parent);
+      });
+
+      if (!isNested) {
+        filtered.push(cluster);
+      } else {
+        console.log(`[HierarchicalClustering] Removed nested cluster ${cluster.id}`);
+      }
+    }
+
+    return filtered;
+  }
+
+  /**
+   * Check if cluster1 is nested inside cluster2
+   */
+  private isClusterNested(child: HierarchicalCluster, parent: HierarchicalCluster): boolean {
+    const childRect = child.boundingRect;
+    const parentRect = parent.boundingRect;
+
+    // Check bounding rect containment với threshold
+    const threshold = 0.9; // 90% overlap considered nested
+
+    const overlapArea = this.calculateOverlapArea(childRect, parentRect);
+    const childArea = childRect.width * childRect.height;
+
+    // Nếu > 90% diện tích child nằm trong parent -> nested
+    return overlapArea / childArea > threshold;
+  }
+
+  /**
+   * Calculate overlap area between two rects
+   */
+  private calculateOverlapArea(rect1: Rect, rect2: Rect): number {
+    const xOverlap = Math.max(
+      0,
+      Math.min(rect1.right, rect2.right) - Math.max(rect1.left, rect2.left),
+    );
+    const yOverlap = Math.max(
+      0,
+      Math.min(rect1.bottom, rect2.bottom) - Math.max(rect1.top, rect2.top),
+    );
+
+    return xOverlap * yOverlap;
+  }
+
+  /**
+   * Filter out too large clusters (không bao trọn body hoặc quá lớn)
+   */
+  private filterLargeClusters(
+    clusters: HierarchicalCluster[],
+    iframeDoc: Document,
+  ): HierarchicalCluster[] {
+    const viewportWidth = iframeDoc.documentElement.clientWidth;
+    const viewportHeight = iframeDoc.documentElement.clientHeight;
+
+    const maxWidth = viewportWidth * CLUSTERING_CONFIG.maxClusterSize;
+    const maxHeight = viewportHeight * CLUSTERING_CONFIG.maxClusterSize;
+
+    return clusters.filter((cluster) => {
+      const rect = cluster.boundingRect;
+
+      // Loại bỏ clusters quá lớn
+      if (rect.width > maxWidth || rect.height > maxHeight) {
+        console.log(
+          `[HierarchicalClustering] Filtered large cluster ${cluster.id}: ${rect.width}x${rect.height}`,
+        );
+        return false;
+      }
+
+      // Loại bỏ clusters quá nhỏ
+      if (
+        rect.width < CLUSTERING_CONFIG.minClusterSize ||
+        rect.height < CLUSTERING_CONFIG.minClusterSize
+      ) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+
+  // Utility methods
+  private getElementRect(element: HTMLElement): Rect {
+    const domRect = element.getBoundingClientRect();
+    return {
+      top: domRect.top,
+      left: domRect.left,
+      width: domRect.width,
+      height: domRect.height,
+      right: domRect.right,
+      bottom: domRect.bottom,
+    };
+  }
+
+  private getDistance(rect1: Rect, rect2: Rect): number {
+    const horizontalDistance = Math.max(0, rect1.left - rect2.right, rect2.left - rect1.right);
+    const verticalDistance = Math.max(0, rect1.top - rect2.bottom, rect2.top - rect1.bottom);
+    return Math.sqrt(horizontalDistance ** 2 + verticalDistance ** 2);
+  }
+
+  private getHeatmapColor(percentage: number): string {
+    const index = Math.min(Math.floor(percentage * GRADIENT_COLOR_COUNT), GRADIENT_COLOR_COUNT - 1);
+    const [r, g, b] = HEATMAP_GRADIENT_COLORS[index];
+    return `rgba(${r}, ${g}, ${b}, 0.5)`;
+  }
+
+  private getHoverColor(percentage: number): string {
+    const index = Math.min(Math.floor(percentage * GRADIENT_COLOR_COUNT), GRADIENT_COLOR_COUNT - 1);
+    const [r, g, b] = HEATMAP_GRADIENT_COLORS[index];
+    return `rgba(${r}, ${g}, ${b}, 0.8)`;
+  }
+}
+
+export interface Rect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+  right: number;
+  bottom: number;
+}

package/src/helpers/viz-canvas/index.ts

@@ -0,0 +1,2 @@
+export * from './area-overlay-manager';
+export * from './area-overlay-manager-v2';

package/src/helpers/viz-elements.ts

@@ -0,0 +1,43 @@
+import type { ElementRect } from '../types';
+
+export function formatPercentage(value: number, decimals = 2): string {
+  return value.toFixed(decimals);
+}
+
+export function calculateRankPosition(rect: ElementRect, widthScale: number) {
+  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,
+  };
+}
+
+export function isElementInViewport(
+  elementRect: ElementRect,
+  visualRef: React.RefObject<HTMLDivElement>,
+  scale: number,
+): boolean {
+  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;
+}

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export * from './register';
+
+export * from './viz-elements';
+export * from './viz-live';
+export * from './viz-render';
+export * from './viz-scale';
+
+export * from './viz-scrollmap';

package/src/hooks/register/index.ts

@@ -0,0 +1,4 @@
+export * from './useRegisterConfig';
+export * from './useRegisterControl';
+export * from './useRegisterData';
+export * from './useRegisterHeatmap';

package/src/hooks/register/useRegisterConfig.ts

@@ -0,0 +1,17 @@
+import { useEffect } from 'react';
+import { useHeatmapConfigStore, useHeatmapDataStore } from '../../stores';
+
+export const useRegisterConfig = () => {
+  const mode = useHeatmapConfigStore((state) => state.mode);
+  const width = useHeatmapConfigStore((state) => state.width);
+  const sidebarWidth = useHeatmapConfigStore((state) => state.sidebarWidth);
+  const heatmapType = useHeatmapConfigStore((state) => state.heatmapType);
+  const setIsRendering = useHeatmapDataStore((state) => state.setIsRendering);
+
+  useEffect(() => {
+    setIsRendering(true);
+    setTimeout(() => {
+      setIsRendering(false);
+    }, 1000);
+  }, [mode, width, sidebarWidth, heatmapType]);
+};

package/src/hooks/register/useRegisterControl.ts

@@ -0,0 +1,13 @@
+import { useHeatmapControlStore } from '../../stores';
+import { IHeatmapControl } from '../../types/control';
+
+export const useRegisterControl = (control: IHeatmapControl) => {
+  const registerControl = useHeatmapControlStore((state) => state.registerControl);
+
+  registerControl('Sidebar', control.Sidebar);
+  registerControl('TopBar', control.TopBar);
+  registerControl('Toolbar', control.Toolbar);
+  registerControl('MetricBar', control.MetricBar);
+  registerControl('VizLoading', control.VizLoading);
+  registerControl('ElementCallout', control.ElementCallout);
+};

package/src/hooks/register/useRegisterData.ts

@@ -0,0 +1,36 @@
+import { useCallback, useEffect } from 'react';
+import { useHeatmapDataStore } from '../../stores';
+import { DecodedPayload, IHeatmapInfo } from '../../types';
+
+export const useRegisterData = (data?: DecodedPayload[], dataInfo?: IHeatmapInfo) => {
+  const setData = useHeatmapDataStore((state) => state.setData);
+  const setIsRendering = useHeatmapDataStore((state) => state.setIsRendering);
+  const setDataInfo = useHeatmapDataStore((state) => state.setDataInfo);
+
+  const handleSetData = useCallback(
+    (data?: DecodedPayload[]) => {
+      if (!data) return;
+
+      setData(data);
+      setIsRendering(false);
+    },
+    [data],
+  );
+
+  const handleSetDataInfo = useCallback(
+    (dataInfo?: IHeatmapInfo) => {
+      if (!dataInfo) return;
+
+      setDataInfo(dataInfo);
+    },
+    [setDataInfo],
+  );
+
+  useEffect(() => {
+    handleSetData(data);
+  }, [data]);
+
+  useEffect(() => {
+    handleSetDataInfo(dataInfo);
+  }, [dataInfo]);
+};

package/src/hooks/register/useRegisterHeatmap.ts

@@ -0,0 +1,38 @@
+import { useCallback, useEffect } from 'react';
+import { useHeatmapDataStore } from '../../stores';
+import { ClickMapPoint, ScrollMapPoint } from '../../types';
+
+interface Props {
+  clickmap?: ClickMapPoint[];
+  scrollmap?: ScrollMapPoint[];
+}
+export const useRegisterHeatmap = ({ clickmap, scrollmap }: Props) => {
+  const setClickmap = useHeatmapDataStore((state) => state.setClickmap);
+  const setScrollmap = useHeatmapDataStore((state) => state.setScrollmap);
+
+  const handleSetClickmap = useCallback(
+    (clickmap?: ClickMapPoint[]) => {
+      if (!clickmap) return;
+
+      setClickmap(clickmap);
+    },
+    [clickmap],
+  );
+
+  const handleSetScrollmap = useCallback(
+    (scrollmap?: ScrollMapPoint[]) => {
+      if (!scrollmap) return;
+
+      setScrollmap(scrollmap);
+    },
+    [scrollmap],
+  );
+
+  useEffect(() => {
+    handleSetClickmap(clickmap);
+  }, [clickmap]);
+
+  useEffect(() => {
+    handleSetScrollmap(scrollmap);
+  }, [scrollmap]);
+};