fix: close Popover when focus escapes outside while trapFocus is enabled

change/@fluentui-react-popover-ea9e0418-25e8-45e1-8dda-ffbe8169164a.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: close Popover when focus escapes outside while trapFocus is enabled",
+  "packageName": "@fluentui/react-popover",
+  "email": "petrduda@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-popover/library/src/components/Popover/Popover.test.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { Popover } from './Popover';
-import { renderHook } from '@testing-library/react-hooks';
+import { renderHook, act } from '@testing-library/react-hooks';
 import { usePopover_unstable } from './usePopover';
 import { isConformant } from '../../testing/isConformant';
 
@@ -37,4 +37,117 @@ describe('Popover', () => {
     // Assert
     expect(result.current.withArrow).toBe(false);
   });
+
+  describe('close on focus outside', () => {
+    it('should close when trapFocus is enabled and focus moves outside', () => {
+      const onOpenChange = jest.fn();
+      const outsideButton = document.createElement('button');
+      const popoverContent = document.createElement('div');
+      document.body.appendChild(outsideButton);
+      document.body.appendChild(popoverContent);
+
+      const { result } = renderHook(
+        ({ open }) =>
+          usePopover_unstable({
+            open,
+            trapFocus: true,
+            onOpenChange,
+            children: <div />,
+          }),
+        { initialProps: { open: true } },
+      );
+
+      // Set the contentRef to simulate mounted popover content
+      act(() => {
+        (result.current.contentRef as React.MutableRefObject<HTMLElement | null>).current = popoverContent;
+      });
+
+      // Simulate focus moving outside the popover
+      act(() => {
+        outsideButton.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+      });
+
+      expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), { open: false });
+
+      document.body.removeChild(outsideButton);
+      document.body.removeChild(popoverContent);
+    });
+
+    it('should not close when trapFocus is not enabled and focus moves outside', () => {
+      const onOpenChange = jest.fn();
+      const outsideButton = document.createElement('button');
+      document.body.appendChild(outsideButton);
+
+      renderHook(() =>
+        usePopover_unstable({
+          open: true,
+          trapFocus: false,
+          onOpenChange,
+          children: <div />,
+        }),
+      );
+
+      act(() => {
+        outsideButton.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+      });
+
+      expect(onOpenChange).not.toHaveBeenCalled();
+
+      document.body.removeChild(outsideButton);
+    });
+
+    it('should not close when popover is not open', () => {
+      const onOpenChange = jest.fn();
+      const outsideButton = document.createElement('button');
+      document.body.appendChild(outsideButton);
+
+      renderHook(() =>
+        usePopover_unstable({
+          open: false,
+          trapFocus: true,
+          onOpenChange,
+          children: <div />,
+        }),
+      );
+
+      act(() => {
+        outsideButton.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+      });
+
+      expect(onOpenChange).not.toHaveBeenCalled();
+
+      document.body.removeChild(outsideButton);
+    });
+
+    it('should also close when inertTrapFocus is enabled and focus moves to a page element outside', () => {
+      const onOpenChange = jest.fn();
+      const outsideButton = document.createElement('button');
+      const popoverContent = document.createElement('div');
+      document.body.appendChild(outsideButton);
+      document.body.appendChild(popoverContent);
+
+      const { result } = renderHook(() =>
+        usePopover_unstable({
+          open: true,
+          trapFocus: true,
+          inertTrapFocus: true,
+          onOpenChange,
+          children: <div />,
+        }),
+      );
+
+      act(() => {
+        (result.current.contentRef as React.MutableRefObject<HTMLElement | null>).current = popoverContent;
+      });
+
+      act(() => {
+        outsideButton.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
+      });
+
+      expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), { open: false });
+
+      document.body.removeChild(outsideButton);
+      document.body.removeChild(popoverContent);
+    });
+  });
 });

packages/react-components/react-popover/library/src/components/Popover/Popover.types.ts

@@ -236,6 +236,7 @@ export type OnOpenChangeData = { open: boolean };
 export type OpenPopoverEvents =
   | MouseEvent
   | TouchEvent
+  | FocusEvent
   | React.FocusEvent<HTMLElement>
   | React.KeyboardEvent<HTMLElement>
   | React.MouseEvent<HTMLElement>;

packages/react-components/react-popover/library/src/components/Popover/usePopover.ts

@@ -168,6 +168,38 @@ export const usePopoverBase_unstable = (props: PopoverBaseProps): PopoverBaseSta
     disabled: !open || !closeOnScroll,
   });
 
+  // When trapFocus is enabled, close the popover if focus escapes outside.
+  // The focusin event only fires for elements within the document, not for browser chrome
+  // (address bar, dev tools), so this won't interfere with inertTrapFocus's spec-compliant
+  // focus escape to browser toolbar.
+  const closeOnFocusOutCallback = useEventCallback((ev: FocusEvent) => {
+    const target = ev.target as HTMLElement;
+    const contentElement = positioningRefs.contentRef.current;
+
+    // Skip if content element isn't mounted yet (e.g. during initial open/auto-focus)
+    if (!contentElement) {
+      return;
+    }
+
+    const isOutside =
+      !elementContains(contentElement, target) && !elementContains(positioningRefs.triggerRef.current || null, target);
+
+    if (isOutside) {
+      setOpen(ev, false);
+    }
+  });
+
+  React.useEffect(() => {
+    if (!open || !props.trapFocus) {
+      return;
+    }
+
+    targetDocument?.addEventListener('focusin', closeOnFocusOutCallback, true);
+    return () => {
+      targetDocument?.removeEventListener('focusin', closeOnFocusOutCallback, true);
+    };
+  }, [open, props.trapFocus, targetDocument, closeOnFocusOutCallback]);
+
   const { findFirstFocusable } = useFocusFinders();
   const activateModal = useActivateModal();