fix(PopoverContainer): Give popover better scroll awareness

packages/gamut/package.json

@@ -20,7 +20,7 @@
     "polished": "^4.1.2",
     "react-aria-components": "1.8.0",
     "react-aria-tabpanel": "^4.4.0",
-    "react-focus-on": "^3.5.1",
+    "react-focus-on": "^3.10.0",
     "react-hook-form": "^7.53.1",
     "react-player": "^2.16.0",
     "react-select": "^5.2.2",

packages/gamut/src/Overlay/index.tsx

@@ -81,6 +81,7 @@ export const Overlay: React.FC<OverlayProps> = ({
     <OverlayContainer
       center
       className={className}
+      data-floating="overlay"
       data-testid="overlay-content-container"
       inline={inline}
       inset={0}

packages/gamut/src/Popover/Popover.tsx

@@ -2,6 +2,10 @@ import { useCallback, useEffect, useState } from 'react';
 import { useWindowScroll, useWindowSize } from 'react-use';
 
 import { FocusTrap } from '../FocusTrap';
+import {
+  useResizingParentEffect,
+  useScrollingParentsEffect,
+} from '../PopoverContainer/hooks';
 import {
   Beak,
   BeakBox,
@@ -12,11 +16,7 @@ import {
 } from './elements';
 import { getBeakVariant } from './styles/beak';
 import { PopoverProps } from './types';
-import {
-  findResizingParent,
-  findScrollingParent,
-  getDefaultOffset,
-} from './utils';
+import { getDefaultOffset } from './utils';
 
 export const Popover: React.FC<PopoverProps> = ({
   animation,
@@ -105,39 +105,21 @@ export const Popover: React.FC<PopoverProps> = ({
     setTargetRect(targetRef?.current?.getBoundingClientRect());
   }, [targetRef, isOpen, width, height, x, y]);
 
-  useEffect(() => {
-    if (!targetRef.current) {
-      return;
-    }
-    const scrollingParent = findScrollingParent(
-      targetRef.current as HTMLElement
-    );
-    if (!scrollingParent?.addEventListener) {
-      return;
-    }
-    const handler = () => {
-      setTargetRect(targetRef?.current?.getBoundingClientRect());
-    };
-    scrollingParent.addEventListener('scroll', handler);
-    return () => scrollingParent.removeEventListener('scroll', handler);
-  }, [targetRef]);
+  // Update target rectangle when parent size/scroll changes
+  const updateTargetPosition = useCallback(
+    (rect?: DOMRect) => {
+      const target = targetRef?.current;
+      if (!target) return;
 
-  useEffect(() => {
-    // handles movement of target within a clipped container e.g. Drawer
-    if (!targetRef.current || typeof ResizeObserver === 'undefined') {
-      return;
-    }
-    const resizingParent = findResizingParent(targetRef.current as HTMLElement);
-    if (!resizingParent?.addEventListener) {
-      return;
-    }
-    const handler = () => {
-      setTargetRect(targetRef?.current?.getBoundingClientRect());
-    };
-    const ro = new ResizeObserver(handler);
-    ro.observe(resizingParent);
-    return () => ro.unobserve(resizingParent);
-  }, [targetRef]);
+      const newRect = rect || target.getBoundingClientRect();
+      setTargetRect(newRect);
+    },
+    [targetRef]
+  );
+
+  useScrollingParentsEffect(targetRef, updateTargetPosition);
+
+  useResizingParentEffect(targetRef, setTargetRect);
 
   useEffect(() => {
     if (targetRect) {
@@ -155,11 +137,16 @@ export const Popover: React.FC<PopoverProps> = ({
 
   const handleClickOutside = useCallback(
     (e: MouseEvent) => {
+      const target = e.target as Node;
+      const targetElement = targetRef.current;
+
+      if (!targetElement) return;
+
       /**
        * Allows targetRef to be or contain a button that toggles the popover open and closed.
        * Without this check it would toggle closed then back open immediately.
        */
-      if (targetRef.current?.contains(e.target as Node)) return;
+      if (targetElement.contains(target)) return;
 
       onRequestClose?.();
     },
@@ -175,6 +162,7 @@ export const Popover: React.FC<PopoverProps> = ({
     <PopoverContainer
       align={align}
       className={className}
+      data-floating="popover"
       data-testid="popover-content-container"
       position={position}
       {...(popoverContainerRef ? { ref: popoverContainerRef } : {})}

packages/gamut/src/Popover/utils.ts

@@ -1,35 +1,5 @@
 import { PopoverProps } from './types';
 
-export const findScrollingParent = ({
-  parentElement,
-}: HTMLElement): HTMLElement | null => {
-  if (parentElement) {
-    const { overflow, overflowY, overflowX } = getComputedStyle(parentElement);
-    if (
-      [overflow, overflowY, overflowX].some((val) =>
-        ['scroll', 'auto'].includes(val)
-      )
-    ) {
-      return parentElement;
-    }
-    return findScrollingParent(parentElement); // parent of this parent is used via prop destructure
-  }
-  return null;
-};
-
-export const findResizingParent = ({
-  parentElement,
-}: HTMLElement): HTMLElement | null => {
-  if (parentElement) {
-    const { overflow, overflowY, overflowX } = getComputedStyle(parentElement);
-    if ([overflow, overflowY, overflowX].some((val) => val === 'clip')) {
-      return parentElement;
-    }
-    return findResizingParent(parentElement); // parent of this parent is used via prop destructure
-  }
-  return null;
-};
-
 const offsets = {
   primary: 20,
   secondary: 15,

packages/gamut/src/PopoverContainer/PopoverContainer.tsx

@@ -11,6 +11,7 @@ import {
 
 import { BodyPortal } from '../BodyPortal';
 import { FocusTrap } from '../FocusTrap';
+import { useResizingParentEffect, useScrollingParentsEffect } from './hooks';
 import { ContainerState, PopoverContainerProps } from './types';
 import { getContainers, getPosition, isInView } from './utils';
 
@@ -35,12 +36,15 @@ export const PopoverContainer: React.FC<PopoverContainerProps> = ({
   isOpen,
   onRequestClose,
   targetRef,
+  allowPageInteraction,
   ...rest
 }) => {
   const popoverRef = useRef<HTMLDivElement>(null);
+  const hasRequestedCloseRef = useRef(false);
   const { width: winW, height: winH } = useWindowSize();
   const { x: winX, y: winY } = useWindowScroll();
   const [containers, setContainers] = useState<ContainerState>();
+  const [targetRect, setTargetRect] = useState<DOMRect>();
   const parent = containers?.parent;
 
   const popoverPosition = useMemo(() => {
@@ -61,33 +65,140 @@ export const PopoverContainer: React.FC<PopoverContainerProps> = ({
     const target = targetRef?.current;
     if (!target) return;
     setContainers(getContainers(target, inline, { x: winX, y: winY }));
-  }, [targetRef, inline, winW, winH, winX, winY]);
+  }, [targetRef, inline, winW, winH, winX, winY, targetRect]);
+
+  // Update target rectangle when window size/scroll changes
+  useEffect(() => {
+    setTargetRect(targetRef?.current?.getBoundingClientRect());
+  }, [targetRef, isOpen, winW, winH, winX, winY]);
+
+  // Update target rectangle when parent size/scroll changes
+  const updateTargetPosition = useCallback(
+    (rect?: DOMRect) => {
+      const target = targetRef?.current;
+      if (!target) return;
+
+      const newRect = rect || target.getBoundingClientRect();
+      setTargetRect(newRect);
+
+      const currentScrollX =
+        window.pageXOffset || document.documentElement.scrollLeft;
+      const currentScrollY =
+        window.pageYOffset || document.documentElement.scrollTop;
+
+      setContainers(
+        getContainers(target, inline, { x: currentScrollX, y: currentScrollY })
+      );
+    },
+    [targetRef, inline]
+  );
+
+  useScrollingParentsEffect(targetRef, updateTargetPosition);
+
+  useResizingParentEffect(targetRef, setTargetRect);
 
   useIsomorphicLayoutEffect(() => {
-    if (containers?.viewport && !isInView(containers?.viewport)) {
+    if (
+      containers?.viewport &&
+      !isInView(containers?.viewport) &&
+      !hasRequestedCloseRef.current
+    ) {
+      hasRequestedCloseRef.current = true;
       onRequestClose?.();
+    } else if (containers?.viewport && isInView(containers?.viewport)) {
+      hasRequestedCloseRef.current = false;
     }
   }, [containers?.viewport, onRequestClose]);
 
   /**
    * Allows targetRef to be or contain a button that toggles the popover open and closed.
    * Without this check it would toggle closed then back open immediately.
+   *
    */
   const handleClickOutside = useCallback(
-    (e: MouseEvent | TouchEvent) =>
-      !targetRef.current?.contains(e.target as Node) && onRequestClose?.(),
+    (e: MouseEvent | TouchEvent) => {
+      const target = e.target as Node;
+      const targetElement = targetRef.current;
+
+      if (!targetElement) return;
+      if (targetElement.contains(target)) return;
+      if (popoverRef.current?.contains(target)) return;
+
+      // If we get here, it's a genuine outside click
+      onRequestClose?.();
+    },
     [onRequestClose, targetRef]
   );
 
+  /**
+   * Backup click outside handler for cases where FocusTrap detection might be interfered with
+   * by our own floating elements
+   */
+  const handleGlobalClickOutside = useCallback(
+    (e: MouseEvent) => {
+      const target = e.target as Node;
+      const targetElement = targetRef.current;
+
+      if (!targetElement || !isOpen) return;
+
+      if (
+        targetElement.contains(target) ||
+        popoverRef.current?.contains(target)
+      )
+        return;
+
+      // Check if the clicked element is within an Overlay component
+      const clickedElement = target as Element;
+      if (clickedElement.closest('[data-floating="overlay"]')) {
+        return;
+      }
+
+      // Check if the clicked element is within another Popover or PopoverContainer
+      const isFloatingElement = clickedElement.closest(
+        '[data-floating="popover"]'
+      );
+      if (
+        isFloatingElement &&
+        !popoverRef.current?.contains(isFloatingElement)
+      ) {
+        onRequestClose?.();
+        return;
+      }
+
+      onRequestClose?.();
+    },
+    [onRequestClose, targetRef, isOpen]
+  );
+
+  // Backup global click listener for when a Popover or PopoverContainer is open
+  useEffect(() => {
+    if (isOpen) {
+      // Use a small delay to ensure this doesn't interfere with the FocusTrap's own detection
+      const timeoutId = setTimeout(() => {
+        document.addEventListener('mousedown', handleGlobalClickOutside, true);
+      }, 50);
+
+      return () => {
+        clearTimeout(timeoutId);
+        document.removeEventListener(
+          'mousedown',
+          handleGlobalClickOutside,
+          true
+        );
+      };
+    }
+  }, [isOpen, handleGlobalClickOutside]);
+
   if (!isOpen || !targetRef) return null;
 
   const content = (
     <FocusTrap
-      allowPageInteraction={inline}
+      allowPageInteraction={inline || allowPageInteraction}
       onClickOutside={handleClickOutside}
       onEscapeKey={onRequestClose}
     >
       <PopoverContent
+        data-floating="popover"
         data-testid="popover-content-container"
         position="absolute"
         ref={popoverRef}

packages/gamut/src/PopoverContainer/hooks.ts

@@ -0,0 +1,71 @@
+import { useEffect } from 'react';
+
+import { findAllAdditionalScrollingParents, findResizingParent } from './utils';
+
+export const useScrollingParentsEffect = (
+  targetRef: React.RefObject<
+    Pick<HTMLDivElement, 'getBoundingClientRect' | 'contains'>
+  >,
+  setTargetRect: (rect: DOMRect | undefined) => void
+) => {
+  useEffect(() => {
+    if (!targetRef.current) {
+      return;
+    }
+
+    const target = targetRef.current as unknown as HTMLElement;
+    const scrollingParents = findAllAdditionalScrollingParents(target);
+
+    const updatePosition = () => {
+      setTargetRect(targetRef?.current?.getBoundingClientRect());
+    };
+
+    // For immediate updates during scroll
+    const immediateUpdate = () => {
+      updatePosition();
+    };
+
+    const cleanup: (() => void)[] = [];
+
+    // Add listeners to all scrolling parents (window scroll handled by useWindowScroll)
+    scrollingParents.forEach((parent) => {
+      if (parent.addEventListener) {
+        // Use immediate update for smoother experience
+        parent.addEventListener('scroll', immediateUpdate, { passive: true });
+        cleanup.push(() =>
+          parent.removeEventListener('scroll', immediateUpdate)
+        );
+      }
+    });
+
+    return () => {
+      cleanup.forEach((fn) => fn());
+    };
+  }, [targetRef, setTargetRect]);
+};
+
+export const useResizingParentEffect = (
+  targetRef: React.RefObject<
+    Pick<HTMLDivElement, 'getBoundingClientRect' | 'contains'>
+  >,
+  setTargetRect: (rect: DOMRect | undefined) => void
+) => {
+  useEffect(() => {
+    // handles movement of target within a clipped container e.g. Drawer
+    if (!targetRef.current || typeof ResizeObserver === 'undefined') {
+      return;
+    }
+    const resizingParent = findResizingParent(
+      targetRef.current as unknown as HTMLElement
+    );
+    if (!resizingParent?.addEventListener) {
+      return;
+    }
+    const handler = () => {
+      setTargetRect(targetRef?.current?.getBoundingClientRect());
+    };
+    const ro = new ResizeObserver(handler);
+    ro.observe(resizingParent);
+    return () => ro.unobserve(resizingParent);
+  }, [targetRef, setTargetRect]);
+};