refactor(react-headless-components-preview): split usePopover and usePopoverAuto for tree-shaking

No behaviour change. Tests, type-check, lint, and api-report all pass.

Author: mainframev

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

@@ -129,10 +129,10 @@ export const renderPopoverSurface: (state: PopoverSurfaceState) => JSXElement;
 // @public
 export const renderPopoverTrigger: (state: PopoverTriggerState) => JSXElement | null;
 
-// @public (undocumented)
+// @public
 export const usePopover: (props: PopoverProps) => PopoverState;
 
-// @public (undocumented)
+// @public
 export const usePopoverAuto: (props: PopoverProps) => PopoverState;
 
 // @public

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

@@ -2,7 +2,8 @@
 
 import type { PopoverProps } from './Popover.types';
 import type { JSXElement } from '@fluentui/react-utilities';
-import { usePopover, usePopoverContextValues } from './usePopover';
+import { usePopover } from './usePopover';
+import { usePopoverContextValues } from './usePopoverBase';
 import { renderPopover } from './renderPopover';
 
 /**

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

@@ -2,7 +2,8 @@
 
 import type { PopoverProps } from './Popover.types';
 import type { JSXElement } from '@fluentui/react-utilities';
-import { usePopoverAuto, usePopoverContextValues } from './usePopover';
+import { usePopoverAuto } from './usePopoverAuto';
+import { usePopoverContextValues } from './usePopoverBase';
 import { renderPopover } from './renderPopover';
 
 /**

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

@@ -11,6 +11,7 @@ import type { PopoverSurfaceProps, PopoverSurfaceState } from './PopoverSurface.
  */
 export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTMLDivElement>): PopoverSurfaceState => {
   const contentRef = usePopoverContext(context => context.contentRef);
+  const triggerRef = usePopoverContext(context => context.triggerRef);
   const openOnHover = usePopoverContext(context => context.openOnHover);
   const setOpen = usePopoverContext(context => context.setOpen);
   const arrowRef = usePopoverContext(context => context.arrowRef);
@@ -66,12 +67,20 @@ export const usePopoverSurface = (props: PopoverSurfaceProps, ref: React.Ref<HTM
   });
 
   state.root.onKeyDown = useEventCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
-    if (!browserHandlesDismiss && e.key === 'Escape') {
+    // `isDefaultPrevented` lets a nested trigger / inner surface close itself
+    // first and tell ancestors the Escape is already handled — without it,
+    // a single Escape would walk up the React tree and close every surface
+    // whose `data-popover-surface` ancestry happens to enclose `e.target`.
+    if (!browserHandlesDismiss && e.key === 'Escape' && !e.isDefaultPrevented()) {
       const target = e.target as HTMLElement;
       const surface = contentRef.current;
       if (surface && target.closest('[data-popover-surface]') === surface) {
         e.preventDefault();
         setOpen(e, false);
+        // Native `popover="manual"` does not restore focus; do it ourselves so
+        // Escape inside the surface lands back on the trigger (matches the
+        // chained Escape behaviour in nested popovers).
+        triggerRef.current?.focus();
       }
     }
 

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

@@ -1,7 +1,9 @@
 export { Popover } from './Popover';
 export { PopoverAuto } from './PopoverAuto';
 export { renderPopover } from './renderPopover';
-export { usePopover, usePopoverAuto, usePopoverContextValues } from './usePopover';
+export { usePopover } from './usePopover';
+export { usePopoverAuto } from './usePopoverAuto';
+export { usePopoverContextValues } from './usePopoverBase';
 export { usePopoverContext } from './popoverContext';
 export type {
   PopoverProps,

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

@@ -1,95 +1,33 @@
 'use client';
 
 import * as React from 'react';
-import {
-  useControllableState,
-  useEventCallback,
-  useOnClickOutside,
-  useOnScrollOutside,
-  elementContains,
-  useTimeout,
-} from '@fluentui/react-utilities';
+import { useOnClickOutside, useOnScrollOutside, elementContains } 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, PopoverType } from './Popover.types';
+import type { PopoverProps, PopoverState } from './Popover.types';
+import { usePopoverBase, ensureNativePopoverShown } from './usePopoverBase';
+
+export { usePopoverContextValues } from './usePopoverBase';
+
+/**
+ * Returns the state for a Popover component.
+ *
+ * Renders the surface with `popover="manual"`, leaving dismiss behaviour
+ * (click-outside, scroll, Escape) under React's control. Open state is
+ * the React state — the surface is in the top layer for painting only,
+ * never owns visibility decisions.
+ */
+export const usePopover = (props: PopoverProps): PopoverState => {
+  const base = usePopoverBase(props);
+  const { open, setOpen, triggerRef, contentRef, inline, openOnContext, closeOnScroll, closeOnIframeFocus } = base;
 
-const SUPPORTS_POPOVER_OPEN_SELECTOR =
-  typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('selector(:popover-open)');
-
-type ToggleEventLike = Event & { newState?: 'open' | 'closed' };
-
-function useInternalPopover(props: PopoverProps, popoverType: PopoverType): PopoverState {
-  const {
-    openOnHover = false,
-    openOnContext = false,
-    mouseLeaveDelay = 500,
-    withArrow = false,
-    disableAutoFocus = false,
-    closeOnScroll = false,
-    closeOnIframeFocus = true,
-    inline = false,
-    mountNode,
-  } = props;
-
-  const [open, setOpenState] = useControllableState({
-    state: props.open,
-    defaultState: props.defaultOpen,
-    initialState: false,
-  });
-
-  const [contextTarget, setContextTarget] = React.useState<{ x: number; y: number } | undefined>(undefined);
   const { targetDocument } = useFluent();
 
-  const onOpenChange = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
-    props.onOpenChange?.(e, { event: e, type: e.type, open: shouldOpen });
-  });
-
-  const [setOpenTimeout, clearOpenTimeout] = useTimeout();
-
-  const setOpen = useEventCallback((e: OpenPopoverEvents, shouldOpen: boolean) => {
-    clearOpenTimeout();
-
-    if (shouldOpen && e.type === 'contextmenu') {
-      const mouseEvent = e as React.MouseEvent<HTMLElement>;
-      setContextTarget({ x: mouseEvent.clientX, y: mouseEvent.clientY });
-    }
-
-    if (!shouldOpen) {
-      setContextTarget(undefined);
-    }
-
-    if (e.type === 'mouseleave') {
-      setOpenTimeout(() => {
-        setOpenState(shouldOpen);
-        onOpenChange(e, shouldOpen);
-      }, mouseLeaveDelay);
-    } else {
-      setOpenState(shouldOpen);
-      onOpenChange(e, shouldOpen);
-    }
-  });
-
-  const toggleOpen = React.useCallback(
-    (e: OpenPopoverEvents) => {
-      setOpen(e, !open);
-    },
-    [setOpen, open],
-  );
-
-  const triggerRef = React.useRef<HTMLElement>(null);
-  const contentRef = React.useRef<HTMLElement>(null);
-  const arrowRef = React.useRef<HTMLDivElement>(null);
-
-  const positioning = usePositioning(resolvePositioningShorthand(props.positioning));
-
-  const isAutoMode = popoverType === 'auto' && !inline;
-
   useOnClickOutside({
     contains: elementContains,
     element: targetDocument,
     callback: ev => setOpen(ev, false),
     refs: [triggerRef, contentRef],
-    disabled: !open || isAutoMode,
+    disabled: !open,
     disabledFocusOnIframe: !closeOnIframeFocus,
   });
 
@@ -98,142 +36,18 @@ function useInternalPopover(props: PopoverProps, popoverType: PopoverType): Popo
     element: targetDocument,
     callback: ev => setOpen(ev, false),
     refs: [triggerRef, contentRef],
-    disabled: !open || !(openOnContext || closeOnScroll) || isAutoMode,
+    disabled: !open || !(openOnContext || closeOnScroll),
   });
 
-  // Mirror the browser-driven toggle events into React state when in auto mode.
-  // Covers Escape, click-outside, and the popover-stack dismissal that happens
-  // when an unrelated `popover="auto"` opens. Skip the no-op transition the
-  // browser fires for our own `showPopover()` call (newState='open' while
-  // React already has `open=true`).
-  const onSurfaceToggle = useEventCallback((event: Event) => {
-    const toggle = event as ToggleEventLike;
-    const nextOpen = toggle.newState === 'open';
-    if (nextOpen === open) {
-      return;
-    }
-    setOpenState(nextOpen);
-    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
-  });
-
-  // The surface is unmounted while closed (`state.open ? popoverSurface : null`),
-  // so this effect must re-run when `open` flips so we attach `showPopover()`
-  // and the `toggle` listener to the freshly-mounted surface element.
   React.useEffect(() => {
     const surface = contentRef.current;
 
     if (!surface || inline || !open) {
       return;
     }
 
-    if (typeof surface.showPopover !== 'function') {
-      return;
-    }
-
-    if (!surface.hasAttribute('popover') || surface.getAttribute('popover') !== popoverType) {
-      surface.setAttribute('popover', popoverType);
-    }
-
-    if (!(SUPPORTS_POPOVER_OPEN_SELECTOR && surface.matches(':popover-open'))) {
-      surface.showPopover();
-    }
-
-    if (popoverType !== 'auto') {
-      return;
-    }
-
-    surface.addEventListener('toggle', onSurfaceToggle);
-    return () => surface.removeEventListener('toggle', onSurfaceToggle);
-  }, [open, inline, popoverType, onSurfaceToggle]);
-
-  const children = React.Children.toArray(props.children) as React.ReactElement[];
-
-  if (process.env.NODE_ENV !== 'production') {
-    if (children.length === 0) {
-      // eslint-disable-next-line no-console
-      console.warn('Popover must contain at least one child');
-    }
-
-    if (children.length > 2) {
-      // eslint-disable-next-line no-console
-      console.warn('Popover must contain at most two children');
-    }
-  }
-
-  let popoverTrigger: React.ReactElement | undefined;
-  let popoverSurface: React.ReactElement | undefined;
-
-  if (children.length === 2) {
-    popoverTrigger = children[0];
-    popoverSurface = children[1];
-  } else if (children.length === 1) {
-    popoverSurface = children[0];
-  }
-
-  return {
-    open,
-    setOpen,
-    toggleOpen,
-    triggerRef,
-    contentRef,
-    arrowRef,
-    popoverTrigger,
-    popoverSurface,
-    openOnHover,
-    openOnContext,
-    withArrow,
-    disableAutoFocus,
-    inline,
-    mountNode,
-    onOpenChange: props.onOpenChange,
-    contextTarget,
-    setContextTarget,
-    positioning,
-    popoverType,
-  };
-}
-
-export const usePopover = (props: PopoverProps): PopoverState => useInternalPopover(props, 'manual');
-
-export const usePopoverAuto = (props: PopoverProps): PopoverState => useInternalPopover(props, 'auto');
-
-export const usePopoverContextValues = (state: PopoverState): { popover: PopoverContextValue } => {
-  const {
-    open,
-    setOpen,
-    toggleOpen,
-    triggerRef,
-    contentRef,
-    arrowRef,
-    openOnHover,
-    openOnContext,
-    disableAutoFocus,
-    withArrow,
-    inline,
-    mountNode,
-    positioning,
-    popoverType,
-  } = state;
+    ensureNativePopoverShown(surface, 'manual');
+  }, [open, inline, contentRef]);
 
-  return {
-    popover: {
-      open,
-      setOpen,
-      toggleOpen,
-      triggerRef,
-      contentRef,
-      arrowRef,
-      openOnHover,
-      openOnContext,
-      disableAutoFocus,
-      withArrow,
-      inline,
-      mountNode,
-      popoverType,
-      positioning: {
-        targetRef: positioning.targetRef,
-        containerRef: positioning.containerRef,
-      },
-    },
-  };
+  return { ...base, popoverType: 'manual' };
 };

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

@@ -0,0 +1,52 @@
+'use client';
+
+import * as React from 'react';
+import { useEventCallback } from '@fluentui/react-utilities';
+import type { PopoverProps, PopoverState } from './Popover.types';
+import { usePopoverBase, ensureNativePopoverShown } from './usePopoverBase';
+
+type ToggleEventLike = Event & { newState?: 'open' | 'closed' };
+
+/**
+ * Returns the state for a PopoverAuto component.
+ *
+ * Renders the surface with `popover="auto"`, deferring light-dismiss
+ * (Escape, click-outside, popover-stack peer dismissal) to the browser.
+ * Browser `toggle` events are mirrored back into React state and
+ * `onOpenChange`. The library's React-driven dismiss hooks
+ * (`useOnClickOutside`, `useOnScrollOutside`) are never imported here, so
+ * a bundle that only uses `PopoverAuto` does not pull them in.
+ */
+export const usePopoverAuto = (props: PopoverProps): PopoverState => {
+  const base = usePopoverBase(props);
+  const { open, setOpenState, contentRef, inline } = base;
+
+  // Skip the no-op transition the browser fires for our own `showPopover()`
+  // call (newState='open' while React already has `open=true`).
+  const onSurfaceToggle = useEventCallback((event: Event) => {
+    const toggle = event as ToggleEventLike;
+    const nextOpen = toggle.newState === 'open';
+    if (nextOpen === open) {
+      return;
+    }
+    setOpenState(nextOpen);
+    props.onOpenChange?.(event, { event, type: event.type, open: nextOpen });
+  });
+
+  // The surface is unmounted while closed (`state.open ? popoverSurface : null`),
+  // so this effect must re-run when `open` flips so we attach `showPopover()`
+  // and the `toggle` listener to the freshly-mounted surface element.
+  React.useEffect(() => {
+    const surface = contentRef.current;
+
+    if (!surface || inline || !open) {
+      return;
+    }
+
+    ensureNativePopoverShown(surface, 'auto');
+    surface.addEventListener('toggle', onSurfaceToggle);
+    return () => surface.removeEventListener('toggle', onSurfaceToggle);
+  }, [open, inline, contentRef, onSurfaceToggle]);
+
+  return { ...base, popoverType: 'auto' };
+};