@probat/react 0.1.5 → 0.2.1

package/src/context/ProbatContext.tsx

@@ -1,7 +1,8 @@
 "use client";
 
-import React, { createContext, useContext, useMemo } from "react";
+import React, { createContext, useContext, useMemo, useEffect } from "react";
 import { detectEnvironment } from "../utils/environment";
+import { initHeatmapTracking, stopHeatmapTracking } from "../utils/heatmapTracker";
 
 declare global {
     interface Window {
@@ -14,6 +15,8 @@ export interface ProbatContextValue {
     environment: "dev" | "prod";
     clientKey?: string;
     repoFullName?: string; // Repository full name (e.g., "owner/repo") for component-based experiments
+    proposalId?: string;
+    variantLabel?: string;
 }
 
 const ProbatContext = createContext<ProbatContextValue | null>(null);
@@ -28,6 +31,14 @@ export interface ProbatProviderProps {
      * - Default: "https://gushi.onrender.com"
      */
     apiBaseUrl?: string;
+    /**
+     * Optional: proposal/experiment id for heatmap segregation
+     */
+    proposalId?: string;
+    /**
+     * Optional: variant label for heatmap segregation
+     */
+    variantLabel?: string;
     /**
      * Client key for identification (optional)
      */
@@ -53,8 +64,20 @@ export function ProbatProvider({
     clientKey,
     environment: explicitEnvironment,
     repoFullName: explicitRepoFullName,
+    proposalId,
+    variantLabel,
     children,
 }: ProbatProviderProps) {
+    // Fallback to localStorage for experiment info if props are not provided
+    const storedProposalId =
+        typeof window !== "undefined"
+            ? window.localStorage.getItem("probat_active_proposal_id") || undefined
+            : undefined;
+    const storedVariantLabel =
+        typeof window !== "undefined"
+            ? window.localStorage.getItem("probat_active_variant_label") || undefined
+            : undefined;
+
     const contextValue = useMemo<ProbatContextValue>(() => {
         // Determine API base URL
         const resolvedApiBaseUrl =
@@ -79,13 +102,65 @@ export function ProbatProvider({
             (typeof window !== "undefined" && (window as any).__PROBAT_REPO) ||
             undefined;
 
+        // Check for URL overrides (used for Live Heatmap visualization)
+        const params = (typeof window !== "undefined") ? new URLSearchParams(window.location.search) : null;
+        const isHeatmapMode = params?.get('heatmap') === 'true';
+
+        let urlProposalId: string | undefined;
+        let urlVariantLabel: string | undefined;
+
+        if (isHeatmapMode && params) {
+            urlProposalId = params.get('proposal_id') || undefined;
+            urlVariantLabel = params.get('variant_label') || undefined;
+            console.log('[PROBAT] Heatmap mode: Overriding variant from URL', { urlProposalId, urlVariantLabel });
+        }
+
+        // Priority Logic:
+        // 1. URL params (if in heatmap mode)
+        // 2. Explicit props passed to Provider
+        // 3. Stored values in localStorage (ONLY if NOT in heatmap mode)
+        const finalProposalId = urlProposalId || proposalId || (!isHeatmapMode ? storedProposalId : undefined);
+        const finalVariantLabel = urlVariantLabel || variantLabel || (!isHeatmapMode ? storedVariantLabel : undefined);
+
         return {
             apiBaseUrl: resolvedApiBaseUrl,
             environment,
             clientKey,
             repoFullName: resolvedRepoFullName,
+            proposalId: finalProposalId,
+            variantLabel: finalVariantLabel,
+        };
+    }, [apiBaseUrl, clientKey, explicitEnvironment, explicitRepoFullName, proposalId, variantLabel, storedProposalId, storedVariantLabel]);
+
+    // Initialize heatmap tracking when provider mounts
+    useEffect(() => {
+        // Only initialize on client-side
+        if (typeof window !== 'undefined') {
+            initHeatmapTracking({
+                apiBaseUrl: contextValue.apiBaseUrl,
+                batchSize: 10,
+                batchInterval: 5000,
+                enabled: true,
+                excludeSelectors: [
+                    '[data-heatmap-exclude]',
+                    'input[type="password"]',
+                    'input[type="email"]',
+                    'textarea',
+                ],
+                // Explicitly enable cursor tracking with sensible defaults
+                trackCursor: true,
+                cursorThrottle: 100,    // capture every 100ms
+                cursorBatchSize: 50,    // send every 50 movements (or after batchInterval)
+                proposalId: contextValue.proposalId,
+                variantLabel: contextValue.variantLabel,
+            });
+        }
+
+        // Cleanup on unmount
+        return () => {
+            stopHeatmapTracking();
         };
-    }, [apiBaseUrl, clientKey, explicitEnvironment, explicitRepoFullName]);
+    }, [contextValue.apiBaseUrl, contextValue.proposalId, contextValue.variantLabel]);
 
     return (
         <ProbatContext.Provider value={contextValue}>

package/src/hoc/itrt-frontend.code-workspace

@@ -1,38 +1,10 @@
 {
-	"folders": [
-		{
-			"path": "../../../../../itrt-frontend"
-		},
-		{
-			"path": "../../../.."
-		},
-		{
-			"path": "../../../../../../onelab_projects/gushi_test_repo"
-		},
-		{
-			"path": "../../../../../../react-jsx-test-repo"
-		},
-		{
-			"path": "../../../../../../testforprobat"
-		},
-		{
-			"path": "../../../../../portfolio"
-		},
-		{
-			"path": "../../../../../portfolio-nextjs"
-		},
-		{
-			"path": "../../../../../react-native-test"
-		},
-		{
-			"path": "../../../../../../tbg_test"
-		},
-		{
-			"path": "../../../../../../probattestforecho"
-		},
-		{
-			"path": "../../../../../zingexample"
-		}
-	],
-	"settings": {}
+    "folders": [
+        {
+            "path": "../../../.."
+        },
+        {
+            "path": "../../../../../itrt-frontend"
+        }
+    ]
 }

package/src/hoc/withExperiment.tsx

@@ -160,32 +160,83 @@ export function withExperiment<P = any>(
             if (useNewAPI && configLoading) return;
 
             let alive = true;
-            const cached = readChoice(proposalId);
 
-            if (cached) {
+            // Detect if we are in heatmap mode
+            const isHeatmapMode = typeof window !== 'undefined' &&
+                new URLSearchParams(window.location.search).get('heatmap') === 'true';
+
+            // HIGH PRIORITY: Check if context is already forcing a specific variant for this proposal
+            // (This happens during Live Heatmap visualization)
+            if (context.proposalId === proposalId && context.variantLabel) {
+                console.log(`[PROBAT HOC] Forced variant from context: ${context.variantLabel}`);
                 setChoice({
+                    experiment_id: `forced_${proposalId}`,
+                    label: context.variantLabel
+                });
+                return;
+            }
+
+            // If we are in heatmap mode, bypass the cache to avoid showing stale variants
+            const cached = isHeatmapMode ? null : readChoice(proposalId);
+
+            if (cached) {
+                const choiceData = {
                     experiment_id: cached.experiment_id,
                     label: cached.label,
-                });
+                };
+                setChoice(choiceData);
+                // Set localStorage for heatmap tracking
+                if (typeof window !== 'undefined' && !isHeatmapMode) {
+                    try {
+                        window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                        window.localStorage.setItem('probat_active_variant_label', cached.label);
+                    } catch (e) {
+                        console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
+                    }
+                }
             } else {
                 (async () => {
                     try {
                         const { experiment_id, label } = await fetchDecision(apiBaseUrl, proposalId);
                         if (!alive) return;
-                        writeChoice(proposalId, experiment_id, label);
-                        setChoice({ experiment_id, label });
+
+                        // Only write to choice cache and localStorage if NOT in heatmap mode
+                        if (!isHeatmapMode) {
+                            writeChoice(proposalId, experiment_id, label);
+                            if (typeof window !== 'undefined') {
+                                try {
+                                    window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                                    window.localStorage.setItem('probat_active_variant_label', label);
+                                } catch (e) {
+                                    console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
+                                }
+                            }
+                        }
+
+                        const choiceData = { experiment_id, label };
+                        setChoice(choiceData);
                     } catch (e) {
                         if (!alive) return;
-                        setChoice({
+                        const choiceData = {
                             experiment_id: `exp_${proposalId}`,
                             label: "control",
-                        });
+                        };
+                        setChoice(choiceData);
+
+                        if (typeof window !== 'undefined' && !isHeatmapMode) {
+                            try {
+                                window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                                window.localStorage.setItem('probat_active_variant_label', 'control');
+                            } catch (err) {
+                                console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', err);
+                            }
+                        }
                     }
                 })();
             }
 
             return () => { alive = false; };
-        }, [proposalId, apiBaseUrl, useNewAPI, configLoading]);
+        }, [proposalId, apiBaseUrl, useNewAPI, configLoading, context.proposalId, context.variantLabel]);
 
         // Track visit
         useEffect(() => {

package/src/hooks/useExperiment.ts

@@ -59,7 +59,8 @@ export function useExperiment(
     proposalId: string,
     options?: { autoTrackImpression?: boolean }
 ): UseExperimentReturn {
-    const { apiBaseUrl } = useProbatContext();
+    const context = useProbatContext();
+    const { apiBaseUrl } = context;
     const [choice, setChoice] = useState<{
         experiment_id: string;
         label: string;
@@ -73,7 +74,25 @@ export function useExperiment(
     useEffect(() => {
         let alive = true;
 
-        const cached = readChoice(proposalId);
+        // Detect if we are in heatmap mode
+        const isHeatmapMode = typeof window !== 'undefined' &&
+            new URLSearchParams(window.location.search).get('heatmap') === 'true';
+
+        // HIGH PRIORITY: Check if context is already forcing a specific variant for this proposal
+        // (This happens during Live Heatmap visualization)
+        if (context.proposalId === proposalId && context.variantLabel) {
+            console.log(`[PROBAT] Forced variant from context: ${context.variantLabel}`);
+            setChoice({
+                experiment_id: `forced_${proposalId}`,
+                label: context.variantLabel
+            });
+            setIsLoading(false);
+            return;
+        }
+
+        // If we are in heatmap mode, bypass the cache to avoid showing stale variants
+        const cached = isHeatmapMode ? null : readChoice(proposalId);
+
         if (cached) {
             setChoice({ experiment_id: cached.experiment_id, label: cached.label });
             setIsLoading(false);
@@ -86,7 +105,12 @@ export function useExperiment(
                         proposalId
                     );
                     if (!alive) return;
-                    writeChoice(proposalId, experiment_id, label);
+
+                    // Only write to choice cache if NOT in heatmap mode
+                    if (!isHeatmapMode) {
+                        writeChoice(proposalId, experiment_id, label);
+                    }
+
                     setChoice({ experiment_id, label });
                     setError(null);
                 } catch (e) {
@@ -108,7 +132,7 @@ export function useExperiment(
         return () => {
             alive = false;
         };
-    }, [proposalId, apiBaseUrl]);
+    }, [proposalId, apiBaseUrl, context.proposalId, context.variantLabel]);
 
     // Track impression when variant is determined
     useEffect(() => {

package/src/index.ts

@@ -28,6 +28,8 @@ export type { WithExperimentOptions } from "./hoc/withExperiment";
 export { detectEnvironment } from "./utils/environment";
 export { fetchDecision, sendMetric, extractClickMeta } from "./utils/api";
 export type { RetrieveResponse } from "./utils/api";
+// Heatmap tracking (automatically initialized by ProbatProvider)
+export { initHeatmapTracking, stopHeatmapTracking, getHeatmapTracker } from "./utils/heatmapTracker";
 export {
     readChoice,
     writeChoice,

package/src/utils/api.ts

@@ -51,6 +51,16 @@ export async function fetchDecision(
             const experiment_id = (data.experiment_id || `exp_${proposalId}`).toString();
             const label = data.label && data.label.trim() ? data.label : "control";
 
+            // Auto-set localStorage for heatmap tracking
+            if (typeof window !== 'undefined') {
+                try {
+                    window.localStorage.setItem('probat_active_proposal_id', proposalId);
+                    window.localStorage.setItem('probat_active_variant_label', label);
+                } catch (e) {
+                    console.warn('[PROBAT] Failed to set proposal/variant in localStorage:', e);
+                }
+            }
+
             return { experiment_id, label };
         } finally {
             // Remove from pending cache after completion
@@ -161,6 +171,18 @@ export async function fetchComponentExperimentConfig(
             }
 
             const data = (await res.json()) as ComponentExperimentConfig;
+
+            // Auto-set localStorage for heatmap tracking when component config is loaded
+            // This will be updated when a specific variant is selected via fetchDecision
+            if (typeof window !== 'undefined' && data?.proposal_id) {
+                try {
+                    window.localStorage.setItem('probat_active_proposal_id', data.proposal_id);
+                    // Variant label will be set when fetchDecision is called
+                } catch (e) {
+                    console.warn('[PROBAT] Failed to set proposal_id in localStorage:', e);
+                }
+            }
+
             return data;
         } catch (e) {
             console.warn(`[PROBAT] Failed to fetch component config: ${e}`);