microsoft · Paul Mardling (PaulGMardling) · Sep 9, 2026 · Sep 10, 2026 · github-actions · Sep 9, 2026
diff --git a/change/@fluentui-react-headless-components-preview-e2bcd363-f078-44e2-92ba-52ad44fe0b24.json b/change/@fluentui-react-headless-components-preview-e2bcd363-f078-44e2-92ba-52ad44fe0b24.json
@@ -0,0 +1,6 @@
+{
+  "type": "patch",
+  "comment": "fix: restore Popover and TeachingPopover trigger focus after controlled and uncontrolled close without stealing intentional outside focus",
+  "packageName": "@fluentui/react-headless-components-preview",
+  "email": "paulmardling@microsoft.com"
+}
diff --git a/change/@fluentui-react-teaching-popover-587162ef-6182-49c0-9199-d1466f307969.json b/change/@fluentui-react-teaching-popover-587162ef-6182-49c0-9199-d1466f307969.json
@@ -0,0 +1,6 @@
+{
+  "type": "patch",
+  "comment": "fix: handle mount-time carousel focus and transfer focus after replacement navigation refs attach",
+  "packageName": "@fluentui/react-teaching-popover",
+  "email": "paulmardling@microsoft.com"
+}
diff --git a/change/@fluentui-react-teaching-popover-605d4544-c842-424e-b41f-d6e91ddbad69.json b/change/@fluentui-react-teaching-popover-605d4544-c842-424e-b41f-d6e91ddbad69.json
@@ -0,0 +1,6 @@
+{
+  "type": "patch",
+  "comment": "fix: move focus to the opposite carousel navigation button when null alternate text hides the focused button, including headless base hooks",
+  "packageName": "@fluentui/react-teaching-popover",
+  "email": "paulmardling@microsoft.com"
+}
@@ -15,33 +15,6 @@ const mount = (element: JSXElement) => {
 const popoverTriggerSelector = '[aria-expanded]';
 const popoverContentSelector = '[role="group"]';
 
-/**
- * Marks a focus-restoration scenario as a known gap of the native
- * `popover="auto"` model.
- *
- * Two distinct gaps put scenarios in this bucket:
- *
- * 1. Programmatic close: when React state flips `open: true → false`, the
- *    surface unmounts before any close-side effect can call `hidePopover()`,
- *    so the spec hide algorithm never runs and no focus restoration happens.
- *    The trailing pointer event from the close interaction (e.g. clicking a
- *    "Close" button) leaves focus on that button.
- *
- * 2. Hover and contextmenu opens: the spec hide algorithm restores focus to
- *    the element that was focused when `showPopover()` ran. Hover and
- *    contextmenu paths never move focus to the trigger before opening, so
- *    the snapshot points at whatever was focused before — usually `<body>` —
- *    and restoration after close lands on the wrong element.
- *
- * Both gaps require a manual focus snapshot taken at intent-to-open and
- * replayed when `open` transitions back to false. The tests below are kept
- * as executable documentation; un-skipping them is the canary that the
- * manual snapshot is in place.
- */
-const itSkipUnsupportedFocusRestore = (description: string, fn: () => void): void => {
-  it.skip(description, fn);
-};
-
 describe('Popover', () => {
   ['uncontrolled', 'controlled'].forEach(scenario => {
     const UncontrolledExample = () => (
@@ -241,8 +214,8 @@ describe('Popover', () => {
     });
   });
 
-  describe('Focus restore — unsupported scenarios', () => {
-    itSkipUnsupportedFocusRestore('programmatic close: should restore focus to trigger', () => {
+  describe('Focus restoration for controlled and non-click opens', () => {
+    it('programmatic close: preserves intentional focus on an outside control', () => {
       const Example = () => {
         const [open, setOpen] = React.useState(false);
         return (
@@ -264,10 +237,11 @@ describe('Popover', () => {
       cy.get('[data-testid=surface]').should('be.visible');
       cy.get('[data-testid=close]').click();
       cy.get('[data-testid=surface]').should('not.exist');
-      cy.focused().should('have.attr', 'data-testid', 'trigger');
+      cy.focused().should('have.attr', 'data-testid', 'close');
     });
 
-    itSkipUnsupportedFocusRestore('hover-leave close: should restore focus to trigger', () => {
+    // Keep the existing non-click-open scenarios skipped: native hover/dismissal timing is a separate gap.
+    it.skip('hover-leave close: should restore focus to trigger', () => {
       mount(
         <Popover openOnHover mouseLeaveDelay={0}>
           <PopoverTrigger disableButtonEnhancement>
@@ -283,7 +257,7 @@ describe('Popover', () => {
       cy.focused().should('have.attr', 'data-testid', 'trigger');
     });
 
-    itSkipUnsupportedFocusRestore('hover-open + Esc: should restore focus to trigger', () => {
+    it.skip('hover-open + Esc: should restore focus to trigger', () => {
       mount(
         <Popover openOnHover>
           <PopoverTrigger disableButtonEnhancement>
@@ -298,7 +272,7 @@ describe('Popover', () => {
       cy.focused().should('have.attr', 'data-testid', 'trigger');
     });
 
-    itSkipUnsupportedFocusRestore('context-open + Esc: should restore focus to trigger', () => {
+    it.skip('context-open + Esc: should restore focus to trigger', () => {
       mount(
         <Popover openOnContext>
           <PopoverTrigger disableButtonEnhancement>

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { useControllableState, useEventCallback, useId, useTimeout } from '@fluentui/react-utilities';
+import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
 import { usePositioning, resolvePositioningShorthand } from '../../hooks';
 import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents } from './Popover.types';
 
@@ -72,6 +73,17 @@ export const usePopover = (props: PopoverProps): PopoverState => {
   const triggerRef = React.useRef<HTMLElement>(null);
   const contentRef = React.useRef<HTMLElement>(null);
   const arrowRef = React.useRef<HTMLDivElement>(null);
+  const { targetDocument } = useFluent();
+  const wasOpen = React.useRef(open);
+
+  React.useEffect(() => {
+    // React removes the surface before the native hide algorithm can restore focus.
+    // Restore only after an actual close, without taking focus from an outside control.
+    if (wasOpen.current && !open && targetDocument?.activeElement === targetDocument?.body) {
+      triggerRef.current?.focus();
+    }
+    wasOpen.current = open;
+  }, [open, targetDocument]);
 
   const generatedSurfaceId = useId('fui-popover-surface-');
   const surfaceId = props.id ?? generatedSurfaceId;

@@ -8,6 +8,7 @@ import {
   TeachingPopoverCarouselCard,
   TeachingPopoverCarouselFooter,
   TeachingPopoverCarouselPageCount,
+  TeachingPopoverHeader,
   TeachingPopoverSurface,
   TeachingPopoverTitle,
   TeachingPopoverTrigger,
@@ -20,7 +21,146 @@ const mount = (element: JSXElement) => mountBase(element);
 const triggerSelector = '[aria-expanded]';
 const surfaceSelector = '[role="group"]';
 
+const FocusExample = ({
+  controlled = false,
+  initiallyOpen = false,
+  withTrigger = true,
+  trapFocus = false,
+}: {
+  controlled?: boolean;
+  initiallyOpen?: boolean;
+  withTrigger?: boolean;
+  trapFocus?: boolean;
+}) => {
+  const [open, setOpen] = React.useState(initiallyOpen);
+  const [value, setValue] = React.useState<string | undefined>('one');
+  const surface = (
+    <TeachingPopoverSurface key="surface">
+      <TeachingPopoverHeader>Tour</TeachingPopoverHeader>
+      <TeachingPopoverCarousel
+        value={controlled ? value : undefined}
+        defaultValue={controlled ? undefined : 'one'}
+        onValueChange={(_, data) => setValue(data.value)}
+        onFinish={() => {
+          setValue('one');
+          setOpen(false);
+        }}
+      >
+        <TeachingPopoverCarouselCard value="one">Feature Step 1</TeachingPopoverCarouselCard>
+        <TeachingPopoverCarouselCard value="two">Feature Step 2</TeachingPopoverCarouselCard>
+        <TeachingPopoverCarouselFooter
+          previous={{ navType: 'prev', altText: null, children: 'Previous', id: 'previous' }}
+          next={{ navType: 'next', altText: 'Got it', children: 'Next', id: 'next' }}
+        />
+      </TeachingPopoverCarousel>
+    </TeachingPopoverSurface>
+  );
+  return (
+    <>
+      <button data-testid="outside" onClick={() => setOpen(false)}>
+        Outside
+      </button>
+      <TeachingPopover
+        open={controlled ? open : undefined}
+        defaultOpen={controlled ? undefined : initiallyOpen}
+        trapFocus={trapFocus}
+        onOpenChange={(_, data) => setOpen(data.open)}
+      >
+        {withTrigger
+          ? [
+              <TeachingPopoverTrigger key="trigger">
+                <button>Open tour</button>
+              </TeachingPopoverTrigger>,
+              surface,
+            ]
+          : surface}
+      </TeachingPopover>
+    </>
+  );
+};
+
 describe('TeachingPopover', () => {
+  describe('focus management', () => {
+    [false, true].forEach(controlled => {
+      describe(controlled ? 'controlled' : 'uncontrolled', () => {
+        it('moves focus to Next when Previous becomes hidden on the first step', () => {
+          mount(<FocusExample controlled={controlled} initiallyOpen />);
+          cy.get('#next').realClick();
+          cy.get('#previous').focus().realPress('Enter');
+          cy.contains('Feature Step 1').should('be.visible');
+          cy.get('#previous').should('not.be.visible');
+          cy.get('#next').should('have.focus');
+        });
+
+        [false, true].forEach(initiallyOpen => {
+          (['finish', 'escape', 'dismiss'] as const).forEach(action => {
+            it(`restores trigger focus on ${action} (initiallyOpen=${initiallyOpen})`, () => {
+              mount(<FocusExample controlled={controlled} initiallyOpen={initiallyOpen} />);
+              if (!initiallyOpen) {
+                cy.get(triggerSelector).realClick();
+              }
+              cy.get('#next').should('be.visible').focus();
+              if (action === 'finish') {
+                cy.realPress('Enter');
+                cy.get('#next').should('have.text', 'Got it').realPress('Enter');
+              } else if (action === 'escape') {
+                cy.realPress('Escape');
+              } else {
+                cy.get('[aria-label="dismiss"]').realClick();
+              }
+              cy.get(surfaceSelector).should('not.exist');
+              cy.get(triggerSelector).should('have.focus');
+            });
+          });
+        });
+      });
+    });
+
+    it('restores the trigger after light dismissal of an initially open tour', () => {
+      mount(<FocusExample controlled initiallyOpen />);
+      cy.get('#next').focus();
+      cy.get('body').realClick({ position: 'bottomRight' });
+      cy.get(surfaceSelector).should('not.exist');
+      cy.get(triggerSelector).should('have.focus');
+    });
+
+    it('preserves intentional outside focus on controlled close', () => {
+      mount(<FocusExample controlled initiallyOpen />);
+      cy.get('#next').focus();
+      cy.get('[data-testid="outside"]').realClick();
+      cy.get(surfaceSelector).should('not.exist');
+      cy.get('[data-testid="outside"]').should('have.focus');
+    });
+
+    it('does not move focus on an initially closed mount', () => {
+      mount(<FocusExample controlled />);
+      cy.get(surfaceSelector).should('not.exist');
+      cy.get(triggerSelector).should('not.have.focus');
+    });
+
+    it('can finish an initially open triggerless tour', () => {
+      mount(<FocusExample controlled initiallyOpen withTrigger={false} />);
+      cy.get('#next').realClick();
+      cy.get('#next').realClick();
+      cy.get(surfaceSelector).should('not.exist');
+      cy.get('[data-testid="outside"]').should('not.have.focus');
+    });
+
+    (['escape', 'dismiss'] as const).forEach(action => {
+      it(`restores trigger focus on modal ${action} when initially open`, () => {
+        mount(<FocusExample controlled initiallyOpen trapFocus />);
+        cy.get('[role="dialog"]').should('be.visible');
+        if (action === 'escape') {
+          cy.realPress('Escape');
+        } else {
+          cy.get('[aria-label="dismiss"]').realClick();
+        }
+        cy.get('[role="dialog"]').should('not.exist');
+        cy.get(triggerSelector).should('have.focus');
+      });
+    });
+  });
+
   (['uncontrolled', 'controlled'] as const).forEach(scenario => {
     const UncontrolledExample = () => (
       <TeachingPopover>

@@ -7,6 +7,9 @@ import { TeachingPopoverHeader } from './TeachingPopoverHeader';
 import { TeachingPopoverTrigger } from './TeachingPopoverTrigger';
 import { TeachingPopoverSurface } from './TeachingPopoverSurface';
 import { TeachingPopoverTitle } from './TeachingPopoverTitle';
+import { TeachingPopoverCarousel } from './TeachingPopoverCarousel';
+import { TeachingPopoverCarouselCard } from './TeachingPopoverCarouselCard';
+import { TeachingPopoverCarouselFooter } from './TeachingPopoverCarouselFooter';
 
 describe('TeachingPopover', () => {
   isConformant({
@@ -162,4 +165,46 @@ describe('TeachingPopover', () => {
     expect(getByText('Surface')).toBeInTheDocument();
     expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: true }));
   });
+
+  it('restores focus when a controlled open prop closes an initially open surface', () => {
+    const Example = ({ open }: { open: boolean }) => (
+      <TeachingPopover open={open}>
+        <TeachingPopoverTrigger>
+          <button>Trigger</button>
+        </TeachingPopoverTrigger>
+        <TeachingPopoverSurface>
+          <button>Inner</button>
+        </TeachingPopoverSurface>
+      </TeachingPopover>
+    );
+    const { getByText, rerender } = render(<Example open />);
+    getByText('Inner').focus();
+
+    rerender(<Example open={false} />);
+
+    expect(getByText('Trigger')).toHaveFocus();
+  });
+
+  it('does not restore focus when a consumer rejects a controlled close request', () => {
+    const onOpenChange = jest.fn();
+    const { getByRole, getByText } = render(
+      <TeachingPopover open onOpenChange={onOpenChange}>
+        <TeachingPopoverTrigger>
+          <button>Trigger</button>
+        </TeachingPopoverTrigger>
+        <TeachingPopoverSurface>
+          <TeachingPopoverCarousel defaultValue="one">
+            <TeachingPopoverCarouselCard value="one">First</TeachingPopoverCarouselCard>
+            <TeachingPopoverCarouselFooter next={{ navType: 'next', altText: 'Got it', children: 'Next' }} />
+          </TeachingPopoverCarousel>
+        </TeachingPopoverSurface>
+      </TeachingPopover>,
+    );
+
+    userEvent.click(getByRole('button', { name: 'Got it', hidden: true }));
+
+    expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: false }));
+    expect(getByRole('group', { hidden: true })).toBeInTheDocument();
+    expect(getByText('Trigger')).not.toHaveFocus();
+  });
 });