@gemx-dev/heatmap-react 3.5.45 → 3.5.46

package/src/hooks/viz-scrollmap/useScrollmapZones.ts

@@ -0,0 +1,165 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useHeatmapDataStore } from '../../stores';
+import { IScrollZone, ScrollMapInfoItem } from '../../types';
+import { useZonePositions } from './useZonePositions';
+
+export interface ScrollMapDataPoint {
+  scrollReachY: number;
+  cumulativeSum: number;
+  percUsers: number;
+}
+
+export type ScrollMapMode = 'basic' | 'metrics';
+
+const SCROLL_GRADIENT_COLORS: [number, number, number][] = [
+  [255, 0, 0], // Red
+  [255, 255, 0], // Yellow
+  [0, 255, 0], // Green
+];
+
+interface UseScrollmapOptions {
+  mode?: ScrollMapMode;
+  enabled?: boolean;
+  iframeRef: React.RefObject<HTMLIFrameElement>;
+  wrapperRef: React.RefObject<HTMLElement>;
+}
+
+interface UseScrollmapReturn {
+  zones: IScrollZone[];
+  isReady: boolean;
+  maxUsers: number;
+  getZonePosition: (zone: IScrollZone) => { top: number; height: number } | null;
+}
+
+export const useScrollmapZones = (options: UseScrollmapOptions): UseScrollmapReturn => {
+  const { mode = 'basic', enabled = true, iframeRef, wrapperRef } = options;
+
+  const [isReady, setIsReady] = useState(false);
+  const [zones, setZones] = useState<IScrollZone[]>([]);
+
+  const scrollmap = useHeatmapDataStore((state) => state.scrollmap);
+  const scrollMapInfo = useHeatmapDataStore((state) => state.dataInfo?.scrollMapInfo);
+
+  const { getZonePosition } = useZonePositions({ iframeRef, wrapperRef });
+
+  const maxUsers = useMemo(() => {
+    if (!scrollmap || scrollmap.length === 0) return 100;
+    return Math.max(...scrollmap.map((d) => d.percUsers));
+  }, [scrollmap]);
+
+  const createZones = useCallback(
+    (data: ScrollMapDataPoint[]): IScrollZone[] => {
+      if (mode === 'basic') {
+        const breakpoints = [0, 25, 50, 75, 100];
+        const zones: IScrollZone[] = [];
+
+        for (let i = 0; i < breakpoints.length - 1; i++) {
+          const startY = breakpoints[i];
+          const endY = breakpoints[i + 1];
+
+          const pointsInRange = data.filter(
+            (d) => d.scrollReachY >= startY && d.scrollReachY < endY,
+          );
+
+          const avgUsers =
+            pointsInRange.length > 0
+              ? pointsInRange.reduce((sum, p) => sum + p.percUsers, 0) / pointsInRange.length
+              : 0;
+
+          zones.push({
+            id: `zone_${startY}_${endY}`,
+            startY,
+            endY,
+            percUsers: avgUsers,
+            label: `${startY}% - ${endY}%`,
+          });
+        }
+
+        return zones;
+      } else {
+        // Metrics mode: 20 zones (5% intervals)
+        const zones: IScrollZone[] = [];
+        const interval = 5;
+
+        // Prepare metrics map
+        let metricsMap: Map<number, ScrollMapInfoItem> | undefined;
+
+        if (scrollMapInfo && Object.keys(scrollMapInfo).length > 0) {
+          metricsMap = new Map();
+          Object.entries(scrollMapInfo).forEach(([key, value]) => {
+            metricsMap!.set(Number(key), value);
+          });
+        }
+
+        for (let i = 0; i < 100; i += interval) {
+          const startY = i;
+          const endY = i + interval;
+
+          const point = data.find((d) => d.scrollReachY === startY) || {
+            scrollReachY: startY,
+            cumulativeSum: 0,
+            percUsers: 0,
+          };
+
+          const metrics = metricsMap?.get(startY);
+
+          zones.push({
+            id: `zone_${startY}_${endY}`,
+            startY,
+            endY,
+            percUsers: point.percUsers,
+            metrics,
+            label: `${startY}% - ${endY}%`,
+          });
+        }
+
+        return zones;
+      }
+    },
+    [mode, scrollMapInfo],
+  );
+
+  /**
+   * Initialize zones
+   */
+  useEffect(() => {
+    if (!enabled || !scrollmap || scrollmap.length === 0) {
+      setIsReady(false);
+      return;
+    }
+
+    try {
+      const newZones = createZones(scrollmap);
+      setZones(newZones);
+      setIsReady(true);
+      console.log(`[useScrollmap] Created ${newZones.length} zones in ${mode} mode`);
+    } catch (error) {
+      console.error('[useScrollmap] Error:', error);
+      setIsReady(false);
+    }
+  }, [enabled, scrollmap, mode, createZones]);
+
+  return {
+    zones,
+    isReady,
+    maxUsers,
+    getZonePosition,
+  };
+};
+
+/**
+ * Get scroll gradient color for minimap
+ */
+export const getScrollGradientColor = (normalized: number): string => {
+  const idx = Math.min(Math.floor(normalized * 2), 1);
+  const [r1, g1, b1] = SCROLL_GRADIENT_COLORS[idx];
+  const [r2, g2, b2] = SCROLL_GRADIENT_COLORS[idx + 1];
+
+  const localPercent = (normalized * 2) % 1;
+
+  const r = Math.round(r1 + (r2 - r1) * localPercent);
+  const g = Math.round(g1 + (g2 - g1) * localPercent);
+  const b = Math.round(b1 + (b2 - b1) * localPercent);
+
+  return `rgb(${r}, ${g}, ${b})`;
+};

package/src/hooks/viz-scrollmap/useZonePositions.ts

@@ -0,0 +1,38 @@
+import { useCallback } from 'react';
+import { useHeatmapSingleStore } from '../../stores';
+import { IScrollZone, IScrollZonePosition } from '../../types';
+
+interface ZonePositionsOptions {
+  iframeRef: React.RefObject<HTMLIFrameElement>;
+  wrapperRef: React.RefObject<HTMLElement>;
+}
+
+type ZonePositionsInput = Pick<IScrollZone, 'startY' | 'endY'>;
+interface ZonePositionsReturn {
+  getZonePosition: (zone: ZonePositionsInput) => IScrollZonePosition | null;
+}
+
+export const useZonePositions = (options: ZonePositionsOptions): ZonePositionsReturn => {
+  const iframeHeight = useHeatmapSingleStore((state) => state.iframeHeight);
+
+  const getZonePosition = useCallback(
+    (zone: ZonePositionsInput): IScrollZonePosition | null => {
+      if (!iframeHeight) {
+        return null;
+      }
+
+      const startYPx = (zone.startY / 100) * iframeHeight;
+      const heightPx = ((zone.endY - zone.startY) / 100) * iframeHeight;
+
+      return {
+        top: startYPx,
+        height: heightPx,
+      };
+    },
+    [iframeHeight],
+  );
+
+  return {
+    getZonePosition,
+  };
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+export * from './components';
+export * from './types';
+
+export {
+  useHeatmapConfigStore,
+  useHeatmapDataStore,
+  useHeatmapInteractionStore,
+  useHeatmapLiveStore,
+  useHeatmapVizStore,
+} from './stores';

package/src/stores/comp.ts

@@ -0,0 +1,31 @@
+import { create } from 'zustand';
+import { IHeatmapControl } from '../types/control';
+
+export interface IHeatmapControlStore {
+  controls: IHeatmapControl;
+  registerControl: (
+    key: keyof IHeatmapControl,
+    control: IHeatmapControl[keyof IHeatmapControl],
+  ) => void;
+}
+
+export const useHeatmapControlStore = create<IHeatmapControlStore>()((set, get) => {
+  return {
+    controls: {
+      Sidebar: null,
+      TopBar: null,
+      Toolbar: null,
+      MetricBar: null,
+      VizLoading: null,
+      ElementCallout: null,
+    },
+    registerControl: (key, control) => {
+      set({
+        controls: {
+          ...get().controls,
+          [key]: control,
+        },
+      });
+    },
+  };
+});

package/src/stores/config.ts

@@ -0,0 +1,37 @@
+import { create } from 'zustand';
+import { DEFAULT_SIDEBAR_WIDTH } from '../configs';
+import { IClickType, IHeatmapType, IScrollType } from '../types';
+
+export interface IHeatmapConfigStore {
+  mode: 'live' | 'compare' | 'single';
+  width: number;
+  sidebarWidth: number;
+  heatmapType: IHeatmapType;
+  clickType: IClickType;
+  scrollType: IScrollType;
+  setMode: (mode: 'live' | 'compare' | 'single') => void;
+  resetMode: () => void;
+  setWidth: (width: number) => void;
+  setSidebarWidth: (sidebarWidth: number) => void;
+  setHeatmapType: (heatmapType: IHeatmapType) => void;
+  setClickType: (clickType: IClickType) => void;
+  setScrollType: (scrollType: IScrollType) => void;
+}
+
+export const useHeatmapConfigStore = create<IHeatmapConfigStore>()((set, get) => {
+  return {
+    mode: 'single',
+    width: 1440,
+    sidebarWidth: DEFAULT_SIDEBAR_WIDTH,
+    heatmapType: IHeatmapType.Scroll,
+    clickType: IClickType.Total,
+    scrollType: IScrollType.Depth,
+    setMode: (mode) => set({ mode }),
+    resetMode: () => set({ mode: 'single' }),
+    setWidth: (width) => set({ width }),
+    setSidebarWidth: (sidebarWidth) => set({ sidebarWidth }),
+    setHeatmapType: (heatmapType) => set({ heatmapType }),
+    setClickType: (clickType) => set({ clickType }),
+    setScrollType: (scrollType) => set({ scrollType }),
+  };
+});

package/src/stores/data.ts

@@ -0,0 +1,30 @@
+import { create } from 'zustand';
+import { ClickMapPoint, DecodedPayload, IHeatmapInfo, ScrollMapPoint } from '../types';
+
+export interface IHeatmapDataStore {
+  data?: DecodedPayload[];
+  clickmap?: ClickMapPoint[];
+  dataInfo?: IHeatmapInfo;
+  isRendering: boolean;
+  setIsRendering: (isRendering: boolean) => void;
+  setDataInfo: (dataInfo: IHeatmapInfo) => void;
+  setData: (data: DecodedPayload[]) => void;
+  setClickmap: (clickmap: ClickMapPoint[]) => void;
+  scrollmap?: ScrollMapPoint[];
+  setScrollmap: (scrollmap: ScrollMapPoint[]) => void;
+}
+
+export const useHeatmapDataStore = create<IHeatmapDataStore>()((set, get) => {
+  return {
+    data: undefined,
+    clickmap: undefined,
+    dataInfo: undefined,
+    scrollmap: undefined,
+    isRendering: true,
+    setIsRendering: (isRendering) => set({ isRendering }),
+    setDataInfo: (dataInfo) => set({ dataInfo }),
+    setData: (data) => set({ data }),
+    setClickmap: (clickmap) => set({ clickmap }),
+    setScrollmap: (scrollmap) => set({ scrollmap }),
+  };
+});

package/src/stores/index.ts

@@ -0,0 +1,10 @@
+export * from './comp';
+export * from './config';
+export * from './data';
+export * from './interaction';
+
+export * from './viz';
+export * from './viz-scrollmap';
+
+export * from './mode-live';
+export * from './mode-single';

package/src/stores/interaction.ts

@@ -0,0 +1,32 @@
+import { create } from 'zustand';
+import { ElementInfo } from '../types';
+
+export interface IHeatmapState {
+  hideSidebar: boolean;
+}
+
+export interface IHeatmapInteractionStore {
+  state: IHeatmapState;
+  setState: (state: IHeatmapState) => void;
+  selectedElement: string | null;
+  setSelectedElement: (selectedElement: string | null) => void;
+  hoveredElement: ElementInfo | null;
+  setHoveredElement: (hoveredElement: ElementInfo | null) => void;
+  shouldShowCallout: boolean;
+  setShouldShowCallout: (shouldShowCallout: boolean) => void;
+}
+
+export const useHeatmapInteractionStore = create<IHeatmapInteractionStore>()((set, get) => {
+  return {
+    state: {
+      hideSidebar: false,
+    },
+    setState: (state) => set({ state }),
+    selectedElement: null,
+    setSelectedElement: (selectedElement) => set({ selectedElement }),
+    hoveredElement: null,
+    setHoveredElement: (hoveredElement) => set({ hoveredElement }),
+    shouldShowCallout: false,
+    setShouldShowCallout: (shouldShowCallout) => set({ shouldShowCallout }),
+  };
+});

package/src/stores/mode-live.ts

@@ -0,0 +1,38 @@
+import { create } from 'zustand';
+import { DecodedPayload } from '../types';
+
+interface IHeatmapLiveStoreState {
+  payloads: DecodedPayload[];
+  htmlContent: string;
+  iframeHeight: number;
+  wrapperHeight: number;
+}
+interface IHeatmapLiveStoreActions {
+  setPayloads: (payloads: DecodedPayload[]) => void;
+  addPayload: (payload: DecodedPayload) => void;
+  reset: () => void;
+  setHtmlContent: (htmlContent: string) => void;
+  setWrapperHeight: (wrapperHeight: number) => void;
+  setIframeHeight: (iframeHeight: number) => void;
+}
+
+interface IHeatmapLiveStore extends IHeatmapLiveStoreState, IHeatmapLiveStoreActions {}
+
+const initialState: IHeatmapLiveStoreState = {
+  payloads: [],
+  htmlContent: '',
+  wrapperHeight: 0,
+  iframeHeight: 0,
+};
+
+export const useHeatmapLiveStore = create<IHeatmapLiveStore>()((set, get) => {
+  return {
+    ...initialState,
+    reset: () => set(initialState),
+    setPayloads: (payloads) => set({ payloads }),
+    addPayload: (payload) => set((state) => ({ payloads: [...state.payloads, payload] })),
+    setHtmlContent: (htmlContent) => set({ htmlContent }),
+    setWrapperHeight: (wrapperHeight) => set({ wrapperHeight }),
+    setIframeHeight: (iframeHeight) => set({ iframeHeight }),
+  };
+});

package/src/stores/mode-single.ts

@@ -0,0 +1,18 @@
+import { Visualizer } from '@gemx-dev/clarity-visualize';
+import { create } from 'zustand';
+
+export interface IHeatmapSingleStore {
+  vizRef: Visualizer | null;
+  setVizRef: (vizRef: Visualizer | null) => void;
+  iframeHeight: number;
+  setIframeHeight: (iframeHeight: number) => void;
+}
+
+export const useHeatmapSingleStore = create<IHeatmapSingleStore>()((set, get) => {
+  return {
+    vizRef: null,
+    iframeHeight: 0,
+    setVizRef: (vizRef) => set({ vizRef }),
+    setIframeHeight: (iframeHeight) => set({ iframeHeight }),
+  };
+});

package/src/stores/viz-scrollmap.ts

@@ -0,0 +1,22 @@
+import { create } from 'zustand';
+import { IScrollZone } from '../types';
+
+export interface IHeatmapVizScrollmapStore {
+  zones: IScrollZone[];
+  setZones: (zones: IScrollZone[]) => void;
+  hoveredZone: IScrollZone | null;
+  setHoveredZone: (hoveredZone: IScrollZone | null) => void;
+  showMinimap: boolean;
+  setShowMinimap: (showMinimap: boolean) => void;
+}
+
+export const useHeatmapVizScrollmapStore = create<IHeatmapVizScrollmapStore>()((set, get) => {
+  return {
+    zones: [],
+    hoveredZone: null,
+    showMinimap: true,
+    setZones: (zones) => set({ zones }),
+    setHoveredZone: (hoveredZone) => set({ hoveredZone }),
+    setShowMinimap: (showMinimap) => set({ showMinimap }),
+  };
+});

package/src/stores/viz.ts

@@ -0,0 +1,17 @@
+import { create } from 'zustand';
+
+export interface IHeatmapVizStore {
+  isRenderViz: boolean;
+  setIsRenderViz: (isRenderViz: boolean) => void;
+  scale: number;
+  setScale: (scale: number) => void;
+}
+
+export const useHeatmapVizStore = create<IHeatmapVizStore>()((set, get) => {
+  return {
+    isRenderViz: false,
+    setIsRenderViz: (isRenderViz) => set({ isRenderViz }),
+    scale: 1,
+    setScale: (scale) => set({ scale }),
+  };
+});

package/src/styles/base.css

@@ -0,0 +1 @@
+@import '@xyflow/react/dist/style.css';

package/src/styles/style.css

@@ -0,0 +1,137 @@
+/* ================= Global CSS ================= */
+.gx-hm-divider {
+  width: 100%;
+  height: var(--gx-hm-border-width, 1px);
+  background-color: var(--gx-hm-border-color, #CCC);
+}
+
+.gx-hm-border-inline-end {
+  border-inline-end-width: var(--gx-hm-border-width, 1px);
+  border-inline-end-color: var(--gx-hm-border-color, #CCC);
+  border-inline-end-style: solid;
+}
+
+.gx-hm-shadow {
+  box-shadow: 0px 0px 6px 1px #1A1A1A33;
+}
+
+/* ================= Heatmap Wrapper CSS ================= */
+
+.gx-hm-wrapper iframe {
+  display: block;
+  /* border: 1px solid #CCC; */
+  border-radius: 8px;
+  border-width: var(--gx-hm-border-width-iframe, 1px);
+  border-color: var(--gx-hm-border-color, #CCC);
+  border-style: solid;
+  /* box-shadow: 0px 1px 0px 0px #1A1A1A12;
+  box-shadow: 0px 1px 0px 0px #CCCCCC80 inset;
+  box-shadow: 0px -1px 0px 0px #0000002B inset;
+  box-shadow: -1px 0px 0px 0px #00000021 inset;
+  box-shadow: 1px 0px 0px 0px #00000021 inset; */
+}
+
+.gx-hm-wrapper .gx-hm-elements {
+  position: absolute;
+  z-index: 2;
+}
+
+.gx-hm-rank-badge {
+  position: absolute;
+  width: 28px;
+  height: 28px;
+  background: #0078D4;
+  color: white;
+  border: 1px solid #FFFFFF;
+  border-radius: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  text-align: center;
+  filter: drop-shadow(0px 1.2px 3.6px rgba(0, 0, 0, 0.1));
+  cursor: default;
+}
+
+.heatmapElement {
+  position: absolute;
+  border: 1px solid white;
+  outline: 1px solid #0078D4;
+}
+
+
+/* ================= Callout CSS ================= */
+
+.clarity-callout {
+  /* box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15); */
+  min-width: 200px;
+  max-width: 280px;
+  width: 230px;
+  height: 263px;
+  animation: clarity-callout-fade-in 0.2s ease-out;
+  pointer-events: auto;
+  /* overflow: hidden; */
+}
+
+@keyframes clarity-callout-fade-in {
+  from {
+    opacity: 0;
+    /* transform: scale(0.95); */
+  }
+
+  to {
+    opacity: 1;
+    /* transform: scale(1); */
+  }
+}
+
+.clarity-callout__arrow {
+  position: absolute;
+  width: 16px;
+  height: 16px;
+  background: white;
+  transform: rotate(45deg);
+}
+
+
+/* ================= Loading CSS ================= */
+.gx-hm-loading {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  background: rgba(255, 255, 255, 0.95);
+  backdrop-filter: blur(2px);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  z-index: 10;
+  border-radius: 8px;
+}
+
+.gx-hm-loading--spinner {
+  width: 48px;
+  height: 48px;
+  border: 4px solid #f3f3f3;
+  border-top: 4px solid #4f46e5;
+  border-radius: 50%;
+  animation: spin 1s linear infinite;
+}
+
+.gx-hm-loading--text {
+  margin-top: 16px;
+  font-size: 14px;
+  font-weight: 500;
+  color: #666;
+}
+
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+
+  to {
+    transform: rotate(360deg);
+  }
+}

package/src/types/clarity.ts

@@ -0,0 +1,45 @@
+import type { Data, MergedPayload } from '@gemx-dev/clarity-visualize';
+
+export interface HeatmapProject {
+  id: string;
+  name: string;
+  domain: string;
+  apiKey: string;
+  _count?: {
+    sessions: number;
+  };
+}
+
+export interface SessionData {
+  id: string;
+  projectId: string;
+  userId?: string;
+  startTime: Date;
+  endTime?: Date;
+  pageUrl: string;
+  userAgent?: string;
+  screenWidth?: number;
+  screenHeight?: number;
+  deviceType?: string;
+  browser?: string;
+}
+
+export interface ClickMapPoint {
+  hash: string;
+  selector: string;
+  totalclicks: number;
+  x: number[];
+  y: number[];
+  clicks: number[];
+  points: number;
+}
+
+export interface ScrollMapPoint {
+  scrollReachY: number; // % scroll depth (0-100)
+  cumulativeSum: number;
+  percUsers: number;
+}
+
+export type DecodedPayload = Data.DecodedPayload;
+export type DecodedEvents = MergedPayload['events'];
+export type DecodedEvent = DecodedEvents[number];

package/src/types/control.ts

@@ -0,0 +1,10 @@
+export interface IHeatmapControl {
+  Sidebar: React.ReactNode;
+  Toolbar: React.ReactNode;
+  TopBar: React.FC;
+  MetricBar: React.ReactNode;
+  VizLoading: React.ReactNode;
+  ElementCallout?: React.FC<{
+    elementHash: string;
+  }>;
+}

package/src/types/elm-callout.ts

@@ -0,0 +1,9 @@
+export type ICalloutPlacement = 'top' | 'bottom' | 'left' | 'right';
+export type IHorizontalAlignment = 'left' | 'center' | 'right';
+
+export interface ICalloutPosition {
+  top: number;
+  left: number;
+  placement: ICalloutPlacement;
+  horizontalAlign: IHorizontalAlignment;
+}

package/src/types/heatmap-info.ts

@@ -0,0 +1,11 @@
+import { ElementMapInfo, HeatmapElement } from './viz-element';
+import { ScrollMapInfo } from './viz-scrollmap';
+
+export interface IHeatmapInfo {
+  sortedElements?: HeatmapElement[];
+  elementMapInfo?: ElementMapInfo;
+  scrollMapInfo?: ScrollMapInfo;
+  totalClicks?: number;
+  width?: number;
+  averageFold?: number;
+}