fixup! feat(react-headless-components-preview): add headless Popover built on native CSS anchor positioning

Author: mainframev

packages/react-components/react-headless-components-preview/library/etc/react-headless-components-preview.api.md

@@ -392,7 +392,7 @@ export const Popover: {
 };
 
 // @public
-export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'trapFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
+export type PopoverContextValue = Pick<PopoverState, 'open' | 'setOpen' | 'toggleOpen' | 'triggerRef' | 'contentRef' | 'arrowRef' | 'openOnHover' | 'openOnContext' | 'trapFocus' | 'disableAutoFocus' | 'withArrow' | 'inline' | 'mountNode'> & {
     positioning: {
         targetRef: React_2.RefCallback<HTMLElement>;
         containerRef: React_2.RefCallback<HTMLElement>;

packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.test.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import { render, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { Popover } from './Popover';
 import { PopoverTrigger } from './PopoverTrigger/PopoverTrigger';
 import { PopoverSurface } from './PopoverSurface/PopoverSurface';
@@ -55,7 +56,7 @@ describe('Popover', () => {
 
     expect(queryByText('Surface content')).not.toBeInTheDocument();
 
-    fireEvent.click(getByText('Trigger'));
+    userEvent.click(getByText('Trigger'));
 
     expect(getByText('Surface content')).toBeInTheDocument();
   });
@@ -72,7 +73,7 @@ describe('Popover', () => {
 
     expect(getByText('Surface content')).toBeInTheDocument();
 
-    fireEvent.click(getByText('Trigger'));
+    userEvent.click(getByText('Trigger'));
 
     expect(queryByText('Surface content')).not.toBeInTheDocument();
   });
@@ -89,7 +90,7 @@ describe('Popover', () => {
       </Popover>,
     );
 
-    fireEvent.click(getByText('Trigger'));
+    userEvent.click(getByText('Trigger'));
 
     expect(onOpenChange).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ open: true }));
   });
@@ -131,7 +132,7 @@ describe('Popover', () => {
     const trigger = getByText('Trigger');
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
 
-    fireEvent.click(trigger);
+    userEvent.click(trigger);
 
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
   });

packages/react-components/react-headless-components-preview/library/src/components/Popover/Popover.types.ts

@@ -32,19 +32,31 @@ export type PopoverProps = {
   /** Controlled open state. */
   open?: boolean;
 
-  /** Default open state for uncontrolled mode. @default false */
+  /**
+   * Default open state for uncontrolled mode.
+   * @default false
+   */
   defaultOpen?: boolean;
 
   /** Callback when the open state changes. */
   onOpenChange?: EventHandler<OnOpenChangeData>;
 
-  /** Open on hover. @default false */
+  /**
+   * Open on hover.
+   * @default false
+   */
   openOnHover?: boolean;
 
-  /** Open on context menu (right-click). @default false */
+  /**
+   * Open on context menu (right-click).
+   * @default false
+   */
   openOnContext?: boolean;
 
-  /** Delay in ms before closing on mouse leave. @default 500 */
+  /**
+   * Delay in ms before closing on mouse leave.
+   * @default 500
+   */
   mouseLeaveDelay?: number;
 
   /**
@@ -53,10 +65,16 @@ export type PopoverProps = {
    */
   positioning?: PositioningShorthand;
 
-  /** Display an arrow pointing to the target. @default false */
+  /**
+   * Display an arrow pointing to the target.
+   * @default false
+   */
   withArrow?: boolean;
 
-  /** Enable focus trap. @default false */
+  /**
+   * Enable focus trap.
+   * @default false
+   */
   trapFocus?: boolean;
 
   /**
@@ -67,13 +85,22 @@ export type PopoverProps = {
    */
   disableAutoFocus?: boolean;
 
-  /** Close when scrolling outside. @default false */
+  /**
+   * Close when scrolling outside.
+   * @default false
+   */
   closeOnScroll?: boolean;
 
-  /** Close when an iframe outside focuses. @default true */
+  /**
+   * Close when an iframe outside focuses.
+   * @default true
+   */
   closeOnIframeFocus?: boolean;
 
-  /** Render inline instead of using native popover top-layer. @default false */
+  /**
+   * Render inline instead of using native popover top-layer.
+   * @default false
+   */
   inline?: boolean;
 
   /**
@@ -110,7 +137,10 @@ export type PopoverState = Required<Pick<PopoverProps, 'open' | 'inline'>> &
  */
 export type PopoverTriggerProps = {
   children: React.ReactElement;
-  /** Disable ARIA button enhancement on the trigger. @default false */
+  /**
+   * Disable ARIA button enhancement on the trigger.
+   * @default false
+   */
   disableButtonEnhancement?: boolean;
 };
 
@@ -152,6 +182,7 @@ export type PopoverContextValue = Pick<
   | 'openOnHover'
   | 'openOnContext'
   | 'trapFocus'
+  | 'disableAutoFocus'
   | 'withArrow'
   | 'inline'
   | 'mountNode'

packages/react-components/react-headless-components-preview/library/src/components/Popover/PopoverSurface/usePopoverSurface.ts

@@ -3,6 +3,7 @@
 import type * as React from 'react';
 import { useMergedRefs, slot, useEventCallback } from '@fluentui/react-utilities';
 import { usePopoverContext } from '../popoverContext';
+import { useFocusScope } from '../../../hooks';
 import { stringifyDataAttribute } from '../../../utils';
 import type { PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface.types';
 
@@ -16,10 +17,30 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
   const arrowRef = usePopoverContext(context => context.arrowRef);
   const withArrow = usePopoverContext(context => context.withArrow);
   const trapFocus = usePopoverContext(context => context.trapFocus);
+  const disableAutoFocus = usePopoverContext(context => context.disableAutoFocus);
   const inline = usePopoverContext(context => context.inline);
   const open = usePopoverContext(context => context.open);
   const mountNode = usePopoverContext(context => context.mountNode);
   const positioningCtx = usePopoverContext(context => context.positioning);
+  const tabIndex = typeof props.tabIndex === 'number' ? props.tabIndex : undefined;
+
+  const onMountAutoFocus = useEventCallback((event: Event) => {
+    if (disableAutoFocus) {
+      event.preventDefault();
+      return;
+    }
+
+    if (tabIndex !== undefined) {
+      event.preventDefault();
+      contentRef.current?.focus({ preventScroll: true });
+    }
+  });
+
+  const focusScope = useFocusScope({
+    trapped: trapFocus,
+    loop: trapFocus,
+    onMountAutoFocus,
+  });
 
   const mergedArrowRef = useMergedRefs(arrowRef, positioningCtx.arrowRef);
 
@@ -31,14 +52,17 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
     components: { root: 'div' },
     root: slot.always(
       {
-        ref: useMergedRefs(ref, contentRef, positioningCtx.containerRef) as React.Ref<HTMLDivElement>,
+        ref: useMergedRefs(
+          ref,
+          contentRef,
+          positioningCtx.containerRef,
+          focusScope.containerRef,
+        ) as React.Ref<HTMLDivElement>,
         role: trapFocus ? 'dialog' : 'group',
         'aria-modal': trapFocus ? true : undefined,
-        // The `popover` attribute is applied at runtime in `usePopover`'s
-        // effect — only when the browser supports the native Popover API.
-        // Emitting it unconditionally here would trigger console errors on
-        // older browsers (Chrome <114, Safari <17) during SSR/hydration.
+        tabIndex: focusScope.containerProps.tabIndex,
         ...props,
+        'data-popover-surface': '',
         'data-open': stringifyDataAttribute(open),
       },
       { elementType: 'div' },
@@ -66,14 +90,20 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
     onMouseLeaveOriginal?.(e);
   });
 
+  const focusScopeKeyDown = focusScope.containerProps.onKeyDown;
+
   state.root.onKeyDown = useEventCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
-    if (e.key === 'Escape' && contentRef.current?.contains(e.target as HTMLElement)) {
-      e.preventDefault();
-      // Stop bubbling so nested popovers don't all close at once — each
-      // Escape press should dismiss only the innermost open popover.
-      e.stopPropagation();
-      setOpen(e, false);
+    focusScopeKeyDown(e);
+
+    if (e.key === 'Escape') {
+      const target = e.target as HTMLElement;
+      const surface = contentRef.current;
+      if (surface && target.closest('[data-popover-surface]') === surface) {
+        e.preventDefault();
+        setOpen(e, false);
+      }
     }
+
     onKeyDownOriginal?.(e);
   });
 

packages/react-components/react-headless-components-preview/library/src/components/Popover/popoverContext.ts

@@ -18,6 +18,7 @@ const popoverContextDefaultValue: PopoverContextValue = {
   openOnContext: false,
   openOnHover: false,
   trapFocus: false,
+  disableAutoFocus: false,
   withArrow: false,
   inline: false,
   mountNode: null,

packages/react-components/react-headless-components-preview/library/src/components/Popover/usePopover.ts

@@ -10,13 +10,9 @@ import {
   useTimeout,
 } from '@fluentui/react-utilities';
 import { useFluent_unstable as useFluent } from '@fluentui/react-shared-contexts';
-import { usePositioning, useFocusTrap, useInert, resolvePositioningShorthand } from '../../hooks';
-import { findFirstFocusable } from '../../utils';
+import { usePositioning, resolvePositioningShorthand } from '../../hooks';
 import type { PopoverProps, PopoverState, PopoverContextValue, OpenPopoverEvents } from './Popover.types';
 
-const SUPPORTS_POPOVER_OPEN_SELECTOR =
-  typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('selector(:popover-open)');
-
 /**
  * Returns the state for a Popover component, given its props and ref.
  */
@@ -102,34 +98,6 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
     disabled: !open || !(openOnContext || closeOnScroll),
   });
 
-  useFocusTrap(contentRef, open && trapFocus);
-  useInert(contentRef, open && trapFocus);
-
-  const previouslyFocusedRef = React.useRef<HTMLElement | null>(null);
-  const wasOpenRef = React.useRef(false);
-
-  React.useEffect(() => {
-    if (open) {
-      previouslyFocusedRef.current = (targetDocument?.activeElement as HTMLElement | null) ?? null;
-
-      if (!disableAutoFocus) {
-        const contentElement = contentRef.current;
-        if (contentElement) {
-          const tabIndexValue = contentElement.getAttribute('tabIndex');
-          const shouldFocusContainer = tabIndexValue !== null && !isNaN(Number(tabIndexValue));
-          const firstFocusable = shouldFocusContainer ? contentElement : findFirstFocusable(contentElement);
-          firstFocusable?.focus({ preventScroll: true });
-        }
-      }
-      wasOpenRef.current = true;
-    } else if (wasOpenRef.current) {
-      const restoreTarget = triggerRef.current ?? previouslyFocusedRef.current;
-      restoreTarget?.focus({ preventScroll: true });
-      previouslyFocusedRef.current = null;
-      wasOpenRef.current = false;
-    }
-  }, [open, disableAutoFocus, targetDocument]);
-
   React.useEffect(() => {
     const surface = contentRef.current;
 
@@ -145,10 +113,6 @@ export const usePopover = (props: PopoverProps, ref: React.Ref<HTMLElement>): Po
       surface.setAttribute('popover', 'manual');
     }
 
-    if (SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open')) {
-      return;
-    }
-
     surface.showPopover();
   }, [open, inline]);
 
@@ -210,6 +174,7 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
     openOnHover,
     openOnContext,
     trapFocus,
+    disableAutoFocus,
     withArrow,
     inline,
     mountNode,
@@ -227,6 +192,7 @@ export const usePopoverContextValues = (state: PopoverState): { popover: Popover
       openOnHover,
       openOnContext,
       trapFocus,
+      disableAutoFocus,
       withArrow,
       inline,
       mountNode,

packages/react-components/react-headless-components-preview/library/src/hooks/index.ts

@@ -1,6 +1,6 @@
 export { usePositioning } from './usePositioning';
-export { useFocusTrap } from './useFocusTrap';
-export { useInert } from './useInert';
+export { useFocusScope } from './useFocusScope';
+export type { UseFocusScopeOptions, UseFocusScopeReturn } from './useFocusScope';
 export type {
   Position,
   Alignment,