@envive-ai/react-widgets-v3 0.3.38 → 0.3.40

package/src/CXIntegration/implementations/useHelpScoutUnifiedCXButton.ts

@@ -1,102 +1,232 @@
 import { SelectorFactory } from '@envive-ai/react-hooks/application/utils';
 import { useElementObserver } from '@envive-ai/react-hooks/hooks/ElementObserver';
+import { useEffect, useRef } from 'react';
 import { FLOATING_BUTTON_ID } from '../../widgets/FloatingChatWidget/constants';
 import { CustomerServiceImplProps, UnifiedCXButton } from '../types';
 
 const BEACON_CONTAINER_ID = 'beacon-container';
+const FAB_BUTTON_SELECTOR = '.BeaconFabButtonFrame';
+const BEACON_WIDGET_SELECTOR = '.BeaconContainer';
+// HelpScout's container may render the widget either as a styled `.BeaconContainer` or
+// (e.g. in the "Instant Answers" view) inside an iframe. We treat either as "open".
+const BEACON_OPEN_CHILD_SELECTOR = '.BeaconContainer, iframe, [class*="Beacon"][class*="ontainer"]';
 
 interface UseHelpScoutUnifiedCXButtonProps extends CustomerServiceImplProps {}
 
+type BeaconApi = (command: string, ...args: unknown[]) => void;
+
+const getBeaconApi = (): BeaconApi | undefined => {
+  const beacon = (window as unknown as { Beacon?: BeaconApi }).Beacon;
+  return typeof beacon === 'function' ? beacon : undefined;
+};
+
+const getBeaconContainer = (): HTMLElement | null => document.getElementById(BEACON_CONTAINER_ID);
+
+const getFabButton = (): HTMLElement | null => {
+  return (getBeaconContainer()?.querySelector(FAB_BUTTON_SELECTOR) as HTMLElement) ?? null;
+};
+
+const getFloatingButtonEl = (): HTMLElement | null => document.getElementById(FLOATING_BUTTON_ID);
+
+/**
+ * Detects whether the HelpScout beacon is currently visible/open.
+ * We use multiple signals because HelpScout has different "views"
+ * (chat, instant answers) that may use different class names.
+ */
+const isBeaconCurrentlyOpen = (): boolean => {
+  const container = getBeaconContainer();
+  if (!container) return false;
+
+  // Signal 1: a `.BeaconContainer` exists with an enter-* class
+  const beaconWidget = container.querySelector(BEACON_WIDGET_SELECTOR);
+  if (beaconWidget) {
+    const cl = beaconWidget.classList;
+    if (
+      cl.contains('BeaconContainer-enter-done') ||
+      cl.contains('BeaconContainer-enter-active') ||
+      cl.contains('BeaconContainer-enter')
+    ) {
+      return true;
+    }
+    if (
+      cl.contains('BeaconContainer-exit') ||
+      cl.contains('BeaconContainer-exit-active') ||
+      cl.contains('BeaconContainer-exit-done')
+    ) {
+      return false;
+    }
+  }
+
+  // Signal 2: any non-FAB visible child in the container means the panel is rendered
+  const children = Array.from(container.children);
+  return children.some(child => {
+    if (child.matches(FAB_BUTTON_SELECTOR)) return false;
+    const rect = (child as HTMLElement).getBoundingClientRect();
+    return rect.width > 50 && rect.height > 50;
+  });
+};
+
+/**
+ * Force-hides the Envive floating button via direct DOM manipulation. This is a
+ * safety net for cases where React state alone doesn't unmount the element fast
+ * enough (or at all), so we never get a flash of the floating button on top of
+ * the merchant's CX UI.
+ */
+const forceHideFloatingButton = () => {
+  const el = getFloatingButtonEl();
+  if (el) el.style.display = 'none';
+};
+
+/**
+ * Restores the Envive floating button display, letting React's render logic take
+ * over again.
+ */
+const forceShowFloatingButton = () => {
+  const el = getFloatingButtonEl();
+  if (el && el.style.display === 'none') el.style.display = '';
+};
+
 export const useHelpScoutUnifiedCXButton = ({
   onSwitchToAgent,
+  onCXClose,
   suppressMerchantButton,
 }: UseHelpScoutUnifiedCXButtonProps): UnifiedCXButton => {
   const beaconContainer = useElementObserver(SelectorFactory.id(BEACON_CONTAINER_ID));
   const enviveFloatingButton = useElementObserver(SelectorFactory.id(FLOATING_BUTTON_ID));
 
+  // Track previous open state so we only fire onCXClose on a real open→closed
+  // transition, not on initial render or during the open animation.
+  const wasOpenRef = useRef(false);
+
+  // Keep latest callbacks/flags in refs so the Beacon API effect can read them
+  // without re-binding listeners on every render.
+  const onCXCloseRef = useRef(onCXClose);
+  const suppressMerchantButtonRef = useRef(suppressMerchantButton);
+  useEffect(() => {
+    onCXCloseRef.current = onCXClose;
+    suppressMerchantButtonRef.current = suppressMerchantButton;
+  }, [onCXClose, suppressMerchantButton]);
+
+  const handleBeaconOpened = () => {
+    wasOpenRef.current = true;
+    // Always force-hide the Envive floating button when the merchant CX opens.
+    // This is the safety net regardless of suppressMerchantButton.
+    forceHideFloatingButton();
+    if (suppressMerchantButtonRef.current) {
+      const fabButton = getFabButton();
+      if (fabButton) fabButton.style.display = '';
+      enviveFloatingButton.hide();
+    }
+  };
+
+  const handleBeaconClosed = () => {
+    if (!wasOpenRef.current) return;
+    wasOpenRef.current = false;
+    onCXCloseRef.current?.();
+    forceShowFloatingButton();
+    if (suppressMerchantButtonRef.current) {
+      const fabButton = getFabButton();
+      if (fabButton) fabButton.style.display = 'none';
+      enviveFloatingButton.show();
+    }
+  };
+
   const toggle = () => {
     onSwitchToAgent();
+    // Force hide BEFORE opening HelpScout so there's no flash of the floating
+    // button next to the merchant's CX panel.
+    wasOpenRef.current = true;
+    forceHideFloatingButton();
+    if (suppressMerchantButton) {
+      enviveFloatingButton.hide();
+    }
 
-    // Try using the Help Scout Beacon API first
-    if (typeof (window as any).Beacon !== 'undefined') {
-      (window as any).Beacon('open');
+    const beacon = getBeaconApi();
+    if (beacon) {
+      beacon('open');
     } else {
-      // Fallback: Find and click the FAB button
-      const container = document.getElementById(BEACON_CONTAINER_ID);
-      const fabButton = container?.querySelector('.BeaconFabButtonFrame') as HTMLElement;
+      // Fallback: find and click the FAB button
+      const fabButton = getFabButton();
       if (fabButton) {
         fabButton.style.display = '';
         fabButton.click();
       }
     }
-
-    if (suppressMerchantButton) {
-      enviveFloatingButton.hide();
-    }
   };
 
   const isHelpScoutButtonEnabled = () => {
-    // Check for the main Help Scout Beacon container
-    const beaconContainerEl = document.getElementById('beacon-container');
+    const beaconContainerEl = getBeaconContainer();
     if (!beaconContainerEl) return false;
-
-    // Check for the FAB button (Floating Action Button) or the global Beacon API
-    const fabButton = beaconContainerEl.querySelector('.BeaconFabButtonFrame');
-    const hasBeaconAPI = typeof (window as any).Beacon !== 'undefined';
-
+    const fabButton = beaconContainerEl.querySelector(FAB_BUTTON_SELECTOR);
+    const hasBeaconAPI = !!getBeaconApi();
     return !!(fabButton || hasBeaconAPI);
   };
 
   const isSwitchEnabled = () => isHelpScoutButtonEnabled();
 
-  // Hide Help Scout FAB button when beacon container is added
+  // Use the official HelpScout Beacon API events for the most reliable open/close
+  // detection. We use empty deps + refs so this binds exactly once per mount, not
+  // every render — important because the Beacon listener registry doesn't dedupe.
+  useEffect(() => {
+    const beacon = getBeaconApi();
+    if (!beacon) return undefined;
+
+    try {
+      beacon('on', 'open', handleBeaconOpened);
+      beacon('on', 'close', handleBeaconClosed);
+    } catch {
+      // Beacon may not be initialized yet — the MutationObserver fallback will
+      // still detect the open/close transitions below.
+    }
+
+    return () => {
+      try {
+        beacon('off', 'open', handleBeaconOpened);
+        beacon('off', 'close', handleBeaconClosed);
+      } catch {
+        // ignore — beacon may already be torn down
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Hide the merchant's FAB button when the beacon container is added. Do NOT
+  // blindly re-show the Envive floating button here — if `Beacon('open')` creates
+  // the container in response to a "live support" click, this would un-hide the
+  // floating button the user just hid via toggle().
   beaconContainer.onAdd(() => {
     if (suppressMerchantButton) {
-      const fabButton = document
-        .getElementById(BEACON_CONTAINER_ID)
-        ?.querySelector('.BeaconFabButtonFrame') as HTMLElement;
-      if (fabButton) {
-        fabButton.style.display = 'none';
-      }
+      const fabButton = getFabButton();
+      if (fabButton) fabButton.style.display = 'none';
+    }
+    // If the beacon happens to mount in an already-open state, treat it like a
+    // proper open transition so the floating button is hidden.
+    if (isBeaconCurrentlyOpen()) {
+      handleBeaconOpened();
+    } else if (suppressMerchantButton) {
       enviveFloatingButton.show();
     }
   });
 
-  // Observe the beacon container for visibility changes
-  // Help Scout Beacon adds/removes classes to show/hide the widget
+  // MutationObserver fallback for cases where the Beacon API events don't fire
+  // (older Beacon versions, opened via direct DOM manipulation, etc.). The logic
+  // here is broader than just checking enter/exit classes because the "Instant
+  // Answers" view can use different DOM markers.
   beaconContainer.onChange(el => {
-    if (el && suppressMerchantButton) {
-      // Check if the BeaconContainer widget is open
-      const beaconWidget = el.querySelector('.BeaconContainer');
-      const fabButton = el.querySelector('.BeaconFabButtonFrame') as HTMLElement;
-
-      if (beaconWidget && fabButton) {
-        const { classList } = beaconWidget;
-
-        // When beacon is open (has enter-done class)
-        if (
-          classList.contains('BeaconContainer-enter-done') ||
-          classList.contains('BeaconContainer-enter-active')
-        ) {
-          fabButton.style.display = '';
-          enviveFloatingButton.hide();
-        }
-
-        // When beacon is closed (has exit class)
-        if (
-          classList.contains('BeaconContainer-exit') ||
-          classList.contains('BeaconContainer-exit-active')
-        ) {
-          fabButton.style.display = 'none';
-          enviveFloatingButton.show();
-        }
-      }
+    if (!el) return;
+    const open = isBeaconCurrentlyOpen();
+    if (open && !wasOpenRef.current) {
+      handleBeaconOpened();
+    } else if (!open && wasOpenRef.current) {
+      handleBeaconClosed();
     }
   });
 
-  // Cleanup when container is removed
+  // Cleanup when the entire container is removed.
   beaconContainer.onRemove(() => {
-    if (suppressMerchantButton) {
+    if (wasOpenRef.current) {
+      handleBeaconClosed();
+    } else if (suppressMerchantButton) {
       enviveFloatingButton.show();
     }
   });

package/src/CXIntegration/implementations/useTalkdeskUnifiedCXButton.ts

@@ -7,6 +7,7 @@ interface UseTalkdeskUnifiedCXButtonProps extends CustomerServiceImplProps {}
 
 export const useTalkdeskUnifiedCXButton = ({
   onSwitchToAgent,
+  onCXClose,
   suppressMerchantButton,
 }: UseTalkdeskUnifiedCXButtonProps): UnifiedCXButton => {
   const talkdeskButton = useElementObserver(SelectorFactory.id('talkdesk-chat-widget-trigger'));
@@ -62,25 +63,31 @@ export const useTalkdeskUnifiedCXButton = ({
 
   // Track widget visibility changes
   talkdeskWidget.onChange(el => {
-    if (el && suppressMerchantButton) {
+    if (el) {
       const ariaHidden = el.getAttribute('aria-hidden');
 
       // Widget is open (aria-hidden="false")
       if (ariaHidden === 'false') {
-        talkdeskButton.show();
-        enviveFloatingButton.hide();
+        if (suppressMerchantButton) {
+          talkdeskButton.show();
+          enviveFloatingButton.hide();
+        }
       }
 
       // Widget is closed (aria-hidden="true")
       if (ariaHidden === 'true') {
-        talkdeskButton.hide();
-        enviveFloatingButton.show();
+        onCXClose?.();
+        if (suppressMerchantButton) {
+          talkdeskButton.hide();
+          enviveFloatingButton.show();
+        }
       }
     }
   });
 
   // Cleanup when container is removed
   talkdeskContainer.onRemove(() => {
+    onCXClose?.();
     if (suppressMerchantButton) {
       talkdeskButton.hide();
       enviveFloatingButton.show();

package/src/CXIntegration/types.ts

@@ -12,6 +12,7 @@ export enum CustomerServiceType {
   helpscout = 'helpscout',
   talkdesk = 'talkdesk',
   eightByEight = '8x8',
+  freshchat = 'freshchat',
   unsupported = 'unsupported',
 }
 

package/src/CXIntegration/utils/functions.ts

@@ -13,6 +13,7 @@ import { useKustomerUnifiedCXButton } from '../implementations/useKustomerUnifie
 import { useHelpScoutUnifiedCXButton } from '../implementations/useHelpScoutUnifiedCXButton';
 import { useTalkdeskUnifiedCXButton } from '../implementations/useTalkdeskUnifiedCXButton';
 import { useEightByEightUnifiedCXButton } from '../implementations/useEightByEightUnifiedCXButton';
+import { useFreshChatUnifiedCXButton } from '../implementations/useFreshChatUnifiedCXButton';
 import { useDefaultUnifiedCXButton } from '../implementations/useDefaultUnifiedCXButton';
 
 export const findCustomerServiceImpl = (
@@ -57,6 +58,9 @@ export const findCustomerServiceImpl = (
   if (provider === CustomerServiceType.eightByEight) {
     return useEightByEightUnifiedCXButton;
   }
+  if (provider === CustomerServiceType.freshchat) {
+    return useFreshChatUnifiedCXButton;
+  }
 
   return useDefaultUnifiedCXButton;
 };

package/src/widgets/FloatingChatWidget/FloatingChatOverlay.tsx

@@ -137,6 +137,9 @@ export const FloatingChatOverlay = ({
               }}
               className="envive-tw-shadow-md"
               onClick={e => e.stopPropagation()}
+              role="dialog"
+              aria-modal="true"
+              aria-label="Envive Chat Window"
             >
               {children}
             </motion.div>