From 5811cd3b00f295ff88b4a7fd55931c6a3d4134ab Mon Sep 17 00:00:00 2001
From: Andrey Goder <andy.goder@gmail.com>
Date: Fri, 7 Aug 2026 11:42:10 -0700
Subject: [PATCH] Fix Popover focus restoration

---
 src/components/Popover/Popover.test.tsx | 47 +++++++++++++++++++++++++
 src/components/Popover/usePopover.tsx   | 44 +++++++++++++++++++++--
 2 files changed, 88 insertions(+), 3 deletions(-)

diff --git a/src/components/Popover/Popover.test.tsx b/src/components/Popover/Popover.test.tsx
index 5785b550..93a6c313 100644
--- a/src/components/Popover/Popover.test.tsx
+++ b/src/components/Popover/Popover.test.tsx
@@ -434,6 +434,53 @@ describe('Popover', () => {
     );
   });
 
+  it('restores focus after Escape closes a popover that moved focus', async () => {
+    render(
+      <Popover content={<button type="button">Inside</button>} label="Actions">
+        <Button label="Open" />
+      </Popover>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Open'});
+    trigger.focus();
+    fireEvent.click(trigger);
+
+    await waitFor(() =>
+      expect(
+        screen.getByRole('button', {hidden: true, name: 'Inside'}),
+      ).toHaveFocus(),
+    );
+
+    fireEvent.keyDown(document, {key: 'Escape'});
+
+    expect(trigger).toHaveFocus();
+  });
+
+  it('leaves focus alone when opening did not move focus', async () => {
+    render(
+      <>
+        <Popover
+          content={<div>Nothing focusable</div>}
+          hasCloseButton={false}
+          label="Actions">
+          <Button label="Open" />
+        </Popover>
+        <Button label="Elsewhere" />
+      </>,
+    );
+
+    const trigger = screen.getByRole('button', {name: 'Open'});
+    trigger.focus();
+    fireEvent.click(trigger);
+    await nextAnimationFrame();
+
+    const elsewhere = screen.getByRole('button', {name: 'Elsewhere'});
+    elsewhere.focus();
+    fireEvent(getPopoverElement(), closeToggleEvent());
+
+    expect(elsewhere).toHaveFocus();
+  });
+
   it('does not move focus when hasAutoFocus is false', async () => {
     showPopoverMock.mockClear();
 
diff --git a/src/components/Popover/usePopover.tsx b/src/components/Popover/usePopover.tsx
index a7081e8a..1ddd8c5e 100644
--- a/src/components/Popover/usePopover.tsx
+++ b/src/components/Popover/usePopover.tsx
@@ -142,6 +142,19 @@ export function usePopover({
   layerId,
 }: UsePopoverOptions = {}): UsePopoverReturn {
   const skipAutoFocusRef = useRef(false);
+  const autoFocusFrameRef = useRef<number | null>(null);
+  const restoreFocusTargetRef = useRef<HTMLElement | null>(null);
+
+  const restoreFocus = useCallback(() => {
+    if (autoFocusFrameRef.current != null) {
+      cancelAnimationFrame(autoFocusFrameRef.current);
+      autoFocusFrameRef.current = null;
+    }
+
+    restoreFocusTargetRef.current?.focus();
+    restoreFocusTargetRef.current = null;
+  }, []);
+
   // Guards against a light-dismiss close immediately re-opening the popover.
   // When the trigger is clicked while the popover is open, the browser's native
   // light dismiss closes it (firing `onHide`) *before* the trigger's own click
@@ -156,8 +169,9 @@ export function usePopover({
     requestAnimationFrame(() => {
       isDismissingRef.current = false;
     });
+    restoreFocus();
     onHide?.();
-  }, [onHide]);
+  }, [onHide, restoreFocus]);
 
   const layer = useLayer({
     isDismissable,
@@ -177,9 +191,33 @@ export function usePopover({
     }
 
     if (hasAutoFocus && !skipAutoFocusRef.current) {
-      requestAnimationFrame(() => focusFirst());
+      const previouslyFocusedElement =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : null;
+      autoFocusFrameRef.current = requestAnimationFrame(() => {
+        autoFocusFrameRef.current = null;
+        const activeElementBeforeFocus = document.activeElement;
+        focusFirst();
+        const activeElementAfterFocus = document.activeElement;
+
+        if (
+          previouslyFocusedElement != null &&
+          activeElementAfterFocus !== activeElementBeforeFocus &&
+          contentRef.current?.contains(activeElementAfterFocus) === true
+        ) {
+          restoreFocusTargetRef.current = previouslyFocusedElement;
+        }
+      });
     }
-  }, [focusFirst, hasAutoFocus, layer.isOpen]);
+
+    return () => {
+      if (autoFocusFrameRef.current != null) {
+        cancelAnimationFrame(autoFocusFrameRef.current);
+        autoFocusFrameRef.current = null;
+      }
+    };
+  }, [contentRef, focusFirst, hasAutoFocus, layer.isOpen]);
 
   const show = useCallback(
     (options?: {isAutoFocusSkipped?: boolean}) => {