@probat/react 0.1.0 → 0.1.1

package/src/utils/documentClickTracker.ts

@@ -0,0 +1,200 @@
+/**
+ * Document-level click tracking for Probat experiments
+ * 
+ * This module implements event delegation at the document level to track clicks
+ * even when components don't have onClick handlers or when stopPropagation() is called.
+ */
+
+import { sendMetric } from './api';
+import { extractClickMeta } from './api';
+
+// Cache for proposal metadata to avoid repeated DOM queries
+const proposalCache = new Map<string, {
+    proposalId: string;
+    experimentId: string | null;
+    variantLabel: string;
+    apiBaseUrl: string;
+}>();
+
+// Track if listener is already attached
+let isListenerAttached = false;
+
+// Rate limiting: prevent duplicate rapid clicks
+const lastClickTime = new Map<string, number>();
+const DEBOUNCE_MS = 100; // Ignore clicks within 100ms of each other
+
+/**
+ * Get proposal metadata from DOM element
+ * Looks for the nearest [data-probat-proposal] wrapper
+ */
+function getProposalMetadata(element: HTMLElement): {
+    proposalId: string;
+    experimentId: string | null;
+    variantLabel: string;
+    apiBaseUrl: string;
+} | null {
+    // Find the nearest probat wrapper
+    const probatWrapper = element.closest('[data-probat-proposal]') as HTMLElement | null;
+    
+    if (!probatWrapper) return null;
+    
+    const proposalId = probatWrapper.getAttribute('data-probat-proposal');
+    if (!proposalId) return null;
+    
+    // Check cache first
+    const cacheKey = `${proposalId}`;
+    const cached = proposalCache.get(cacheKey);
+    if (cached) return cached;
+    
+    // Extract metadata from data attributes
+    const experimentId = probatWrapper.getAttribute('data-probat-experiment-id');
+    const variantLabel = probatWrapper.getAttribute('data-probat-variant-label') || 'control';
+    const apiBaseUrl = probatWrapper.getAttribute('data-probat-api-base-url') || 
+                       (typeof window !== 'undefined' && (window as any).__PROBAT_API) ||
+                       'https://gushi.onrender.com';
+    
+    const metadata = {
+        proposalId,
+        experimentId: experimentId || null,
+        variantLabel,
+        apiBaseUrl,
+    };
+    
+    // Cache it
+    proposalCache.set(cacheKey, metadata);
+    return metadata;
+}
+
+/**
+ * Handle click event at document level
+ * Uses capture phase to catch events before stopPropagation()
+ */
+function handleDocumentClick(event: MouseEvent): void {
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    
+    // Get proposal metadata
+    const metadata = getProposalMetadata(target);
+    if (!metadata) return;
+    
+    // Rate limiting: prevent duplicate rapid clicks
+    const now = Date.now();
+    const lastClick = lastClickTime.get(metadata.proposalId) || 0;
+    if (now - lastClick < DEBOUNCE_MS) {
+        return; // Ignore rapid duplicate clicks
+    }
+    lastClickTime.set(metadata.proposalId, now);
+    
+    // Extract click metadata (your existing function)
+    const clickMeta = extractClickMeta(event);
+    
+    // Determine if we should track this click
+    // Track if:
+    // 1. It's an actionable element (button, link, etc.) - clickMeta exists
+    // 2. Element has data-probat-track attribute
+    // 3. Parent has data-probat-track attribute
+    const hasTrackAttribute = target.hasAttribute('data-probat-track') || 
+                              target.closest('[data-probat-track]') !== null;
+    
+    const shouldTrack = clickMeta !== undefined || hasTrackAttribute;
+    
+    if (!shouldTrack) {
+        // Optional: Track "dead clicks" for UX insights
+        // Uncomment the code below if you want to track clicks on non-interactive elements
+        /*
+        const deadClickMeta = {
+            dead_click: true,
+            target_tag: target.tagName,
+            target_class: target.className || '',
+            target_id: target.id || '',
+        };
+        
+        void sendMetric(
+            metadata.apiBaseUrl,
+            metadata.proposalId,
+            'dead_click',
+            metadata.variantLabel,
+            metadata.experimentId,
+            deadClickMeta
+        );
+        */
+        return;
+    }
+    
+    // Send click metric
+    void sendMetric(
+        metadata.apiBaseUrl,
+        metadata.proposalId,
+        'click',
+        metadata.variantLabel,
+        metadata.experimentId || undefined,
+        clickMeta
+    );
+}
+
+/**
+ * Initialize document-level click tracking
+ * Call this once when your app initializes (typically in ProbatProvider)
+ */
+export function initDocumentClickTracking(): void {
+    if (isListenerAttached) {
+        console.warn('[PROBAT] Document click listener already attached');
+        return;
+    }
+    
+    if (typeof document === 'undefined') {
+        // Server-side rendering - skip
+        return;
+    }
+    
+    // Use capture phase (true) to catch events before they bubble
+    // This ensures we catch clicks even if stopPropagation() is called
+    document.addEventListener('click', handleDocumentClick, true);
+    
+    isListenerAttached = true;
+    console.log('[PROBAT] Document-level click tracking initialized');
+}
+
+/**
+ * Clean up the listener (useful for testing or cleanup)
+ */
+export function cleanupDocumentClickTracking(): void {
+    if (!isListenerAttached) return;
+    
+    if (typeof document !== 'undefined') {
+        document.removeEventListener('click', handleDocumentClick, true);
+    }
+    
+    isListenerAttached = false;
+    proposalCache.clear();
+    lastClickTime.clear();
+}
+
+/**
+ * Update proposal metadata cache (call this when proposal data changes)
+ * This is useful if you want to update the cache without waiting for DOM queries
+ */
+export function updateProposalMetadata(
+    proposalId: string,
+    metadata: {
+        experimentId?: string | null;
+        variantLabel?: string;
+        apiBaseUrl?: string;
+    }
+): void {
+    const existing = proposalCache.get(proposalId);
+    if (existing) {
+        proposalCache.set(proposalId, {
+            ...existing,
+            ...metadata,
+        });
+    }
+}
+
+/**
+ * Clear the proposal cache (useful for testing)
+ */
+export function clearProposalCache(): void {
+    proposalCache.clear();
+}
+