@atlaskit/top-layer 0.9.0 → 0.10.0

package/dist/es2019/placement-map/index.js

@@ -1,7 +1,4 @@
-/**
- * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
- * `@atlaskit/tooltip`, etc.).
- */
+import { placementMapping } from './legacy-placements';
 
 /**
  * Maps legacy Popper.js placement values to the new object-based
@@ -13,9 +10,11 @@
  * | ------------------- | --------------------------------------------------- |
  * | `top`               | `{ axis: 'block', edge: 'start', align: 'center' }`  |
  * | `top-start`         | `{ axis: 'block', edge: 'start', align: 'start' }`   |
+ * | `top-center`        | `{ axis: 'block', edge: 'start', align: 'center' }`  |
  * | `top-end`           | `{ axis: 'block', edge: 'start', align: 'end' }`     |
  * | `bottom`            | `{ axis: 'block', edge: 'end', align: 'center' }`    |
  * | `bottom-start`      | `{ axis: 'block', edge: 'end', align: 'start' }`     |
+ * | `bottom-center`     | `{ axis: 'block', edge: 'end', align: 'center' }`    |
  * | `bottom-end`        | `{ axis: 'block', edge: 'end', align: 'end' }`       |
  * | `right`             | `{ axis: 'inline', edge: 'end', align: 'center' }`   |
  * | `right-start`       | `{ axis: 'inline', edge: 'end', align: 'start' }`    |
@@ -27,7 +26,10 @@
  * | `auto-start`        | `{ axis: 'block', edge: 'end', align: 'start' }`     |
  * | `auto-end`          | `{ axis: 'block', edge: 'end', align: 'end' }`       |
  *
- * The `position-try-fallbacks` CSS property handles flipping automatically.
+ * `auto*` is mapped to `block-end` (a reduction in expressiveness vs Popper's
+ * runtime auto-flip). CSS `position-try-fallbacks` provides flipping at the
+ * edge - but the initial placement is fixed. If migrating away from Popper's
+ * dynamic auto, prefer an explicit placement.
  *
  * @example
  * ```ts
@@ -39,103 +41,6 @@
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-const placementMapping = {
-  top: {
-    axis: 'block',
-    edge: 'start',
-    align: 'center'
-  },
-  'top-start': {
-    axis: 'block',
-    edge: 'start',
-    align: 'start'
-  },
-  'top-center': {
-    axis: 'block',
-    edge: 'start',
-    align: 'center'
-  },
-  'top-end': {
-    axis: 'block',
-    edge: 'start',
-    align: 'end'
-  },
-  bottom: {
-    axis: 'block',
-    edge: 'end',
-    align: 'center'
-  },
-  'bottom-start': {
-    axis: 'block',
-    edge: 'end',
-    align: 'start'
-  },
-  'bottom-center': {
-    axis: 'block',
-    edge: 'end',
-    align: 'center'
-  },
-  'bottom-end': {
-    axis: 'block',
-    edge: 'end',
-    align: 'end'
-  },
-  right: {
-    axis: 'inline',
-    edge: 'end',
-    align: 'center'
-  },
-  'right-start': {
-    axis: 'inline',
-    edge: 'end',
-    align: 'start'
-  },
-  'right-end': {
-    axis: 'inline',
-    edge: 'end',
-    align: 'end'
-  },
-  left: {
-    axis: 'inline',
-    edge: 'start',
-    align: 'center'
-  },
-  'left-start': {
-    axis: 'inline',
-    edge: 'start',
-    align: 'start'
-  },
-  'left-end': {
-    axis: 'inline',
-    edge: 'start',
-    align: 'end'
-  },
-  auto: {
-    axis: 'block',
-    edge: 'end',
-    align: 'center'
-  },
-  'auto-start': {
-    axis: 'block',
-    edge: 'end',
-    align: 'start'
-  },
-  'auto-end': {
-    axis: 'block',
-    edge: 'end',
-    align: 'end'
-  }
-};
-
-/**
- * Convert a legacy Popper.js placement to the new `position-area`-based Placement.
- * Optional `offset` is the legacy Popper `[along, away]` tuple (also known as
- * `[skidding, distance]`); negative `along` becomes `direction: 'backwards'`.
- *
- * The tuple keeps the historical popper names so call sites that already pass
- * `[along, away]` migrate without thinking; the new internal field names
- * (`gap` / `crossAxisShift`) are produced inside this adapter.
- */
 export function fromLegacyPlacement({
   legacy,
   offset
@@ -156,10 +61,4 @@ export function fromLegacyPlacement({
       }
     }
   };
-}
-
-/**
- * The full mapping record, exposed for consumers that need to iterate or introspect.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export { placementMapping };
+}

package/dist/es2019/placement-map/legacy-placements.js

@@ -0,0 +1,107 @@
+/**
+ * Legacy Popper.js placement values (used by `@atlaskit/popper`,
+ * `@atlaskit/popup`, `@atlaskit/tooltip`, etc.). Re-exported from
+ * `@atlaskit/top-layer/placement-map` for migration consumers that need
+ * to enumerate every placement (e.g. for a settings dropdown). New code
+ * should use the object-based `TPlacementOptions` directly.
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export const LEGACY_PLACEMENTS = ['auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-center', 'top-end', 'bottom', 'bottom-start', 'bottom-center', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'];
+/**
+ * The full mapping record. Internal - use `fromLegacyPlacement` from the
+ * public entry-point so the offset-tuple translation is applied consistently.
+ *
+ * Note: `auto`, `auto-start`, `auto-end` map to `block-end` placements. This
+ * is a reduction in expressiveness vs Popper.js (which picked the best
+ * placement at runtime). CSS `position-try-fallbacks` flips at the edge but
+ * the initial placement is fixed. Migration consumers who relied on Popper's
+ * dynamic auto-flip should pick an explicit placement instead.
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export const placementMapping = {
+  top: {
+    axis: 'block',
+    edge: 'start',
+    align: 'center'
+  },
+  'top-start': {
+    axis: 'block',
+    edge: 'start',
+    align: 'start'
+  },
+  'top-center': {
+    axis: 'block',
+    edge: 'start',
+    align: 'center'
+  },
+  'top-end': {
+    axis: 'block',
+    edge: 'start',
+    align: 'end'
+  },
+  bottom: {
+    axis: 'block',
+    edge: 'end',
+    align: 'center'
+  },
+  'bottom-start': {
+    axis: 'block',
+    edge: 'end',
+    align: 'start'
+  },
+  'bottom-center': {
+    axis: 'block',
+    edge: 'end',
+    align: 'center'
+  },
+  'bottom-end': {
+    axis: 'block',
+    edge: 'end',
+    align: 'end'
+  },
+  right: {
+    axis: 'inline',
+    edge: 'end',
+    align: 'center'
+  },
+  'right-start': {
+    axis: 'inline',
+    edge: 'end',
+    align: 'start'
+  },
+  'right-end': {
+    axis: 'inline',
+    edge: 'end',
+    align: 'end'
+  },
+  left: {
+    axis: 'inline',
+    edge: 'start',
+    align: 'center'
+  },
+  'left-start': {
+    axis: 'inline',
+    edge: 'start',
+    align: 'start'
+  },
+  'left-end': {
+    axis: 'inline',
+    edge: 'start',
+    align: 'end'
+  },
+  auto: {
+    axis: 'block',
+    edge: 'end',
+    align: 'center'
+  },
+  'auto-start': {
+    axis: 'block',
+    edge: 'end',
+    align: 'start'
+  },
+  'auto-end': {
+    axis: 'block',
+    edge: 'end',
+    align: 'end'
+  }
+};

package/dist/es2019/popover/popover.js

@@ -5,7 +5,6 @@ import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useEffect, useId, useLayoutEffect, useRef } from 'react';
 import { bind } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
-import noop from '@atlaskit/ds-lib/noop';
 import once from '@atlaskit/ds-lib/once';
 import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { useAnimatedVisibility } from '../internal/use-animated-visibility';
@@ -56,13 +55,13 @@ const POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree',
  *
  * For `mode="auto"`, the browser can dismiss the popover via light dismiss
  * (Escape, click outside). When that happens, `onClose` is called and the
- * consumer must set `isOpen` to `false`. The DOM owns the dismiss — React
+ * consumer must set `isOpen` to `false`. The DOM owns the dismiss; React
  * must follow.
  */
 export const Popover = /*#__PURE__*/forwardRef(function Popover({
   children,
   mode: modeProp = 'auto',
-  onClose = noop,
+  onClose,
   onOpenChange,
   onExitFinish,
   animate,
@@ -79,7 +78,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   const autoId = useId();
   const ownRef = useRef(null);
   const combinedRef = mergeRefs([ownRef, ref].filter(Boolean));
-  // Regex is intentional — `replaceAll` is not available in our supported
+  // Regex is intentional: `replaceAll` is not available in our supported
   // browser matrix. In React 18, `useId()` returns IDs containing colons
   // (e.g. `:r1:`) which are invalid in CSS selectors and `popover` target
   // attributes. React 19.2.0 replaced colons with underscores, making this
@@ -98,7 +97,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // ── Focus management ──
   // Initial focus: on open, moves focus into the popover (role-dependent).
   // Focus wrap: Tab/Shift+Tab cycle within the popover for dialog roles.
-  // Focus restoration: handled natively by the Popover API — the browser
+  // Focus restoration: handled natively by the Popover API. The browser
   //   tracks `previouslyFocusedElement` on show and restores it on hide.
   //   No custom restoration hook is needed. See: notes/architecture/focus-restoration.md
   useFocusWrap({
@@ -119,7 +118,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // Passive/informational roles (tooltip, note, status, alert, log) and
   // no-role cases do not map to LayerType 'popup', so type is left undefined.
   const handleObserverClose = useCallback(() => {
-    onClose({
+    onClose === null || onClose === void 0 ? void 0 : onClose({
       reason: 'programmatic'
     });
   }, [onClose]);
@@ -141,8 +140,8 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   const mode = modeProp === 'hint' && !supportsPopoverHint() ? 'auto' : modeProp;
 
   // Distinguishes programmatic hidePopover() from browser-initiated dismiss.
-  // When we call hidePopover() ourselves the beforetoggle event fires synchronously —
-  // this ref prevents the toggle handler from calling onClose redundantly.
+  // When we call hidePopover() ourselves the beforetoggle event fires synchronously,
+  // so this ref prevents the toggle handler from calling onClose redundantly.
   const programmaticCloseRef = useRef(false);
 
   // Escape key tracking: set in a capture-phase keydown listener (fires before
@@ -175,7 +174,11 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
       // Browser dismiss (Escape or click-outside). Notify consumer.
       const reason = closeReasonRef.current;
       closeReasonRef.current = 'light-dismiss'; // reset for next dismiss
-      onClose({
+      // `onClose` is required for `auto`/`hint` and forbidden for
+      // `manual`, but `TPopoverForwardedProps` is a flat type used
+      // internally by `PopupContent` - the optional check guards
+      // the manual-mode forwarded path where the field is undefined.
+      onClose === null || onClose === void 0 ? void 0 : onClose({
         reason
       });
     }
@@ -210,7 +213,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
 
   // Placement-dependent animation CSS vars (e.g. slide direction).
   // Separate from show/hide so that preset reference changes
-  // (e.g. inline `animate={slideAndFade()}`) don't re-trigger visibility.
+  // (e.g. inline `animate={slideAndFade()}`) do not re-trigger visibility.
   useLayoutEffect(() => {
     const el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -229,7 +232,7 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
   // in the target state (e.g. browser dismissed via light-dismiss before our
   // effect ran).
   // Defensive try/catch: these APIs throw InvalidStateError if the element
-  // is disconnected or missing the popover attribute. While we don't expect
+  // is disconnected or missing the popover attribute. While we do not expect
   // that to happen in normal usage, it can occur in edge cases (e.g. React
   // concurrent mode, StrictMode double-effects, or unmount races).
   useLayoutEffect(() => {

package/dist/es2019/popup/popup-content.js

@@ -3,7 +3,7 @@ import _extends from "@babel/runtime/helpers/extends";
 import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useLayoutEffect, useRef } from 'react';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
-import { roleToAriaHasPopup } from '../internal/role-types';
+import { roleToAriaHasPopup, shouldFocusIntoPopover } from '../internal/role-types';
 import { useAnchorPosition } from '../internal/use-anchor-position';
 import { useWidthFromAnchor } from '../internal/use-width-from-anchor';
 import { Popover } from '../popover/popover';
@@ -29,7 +29,8 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   placement: placementProp,
   onClose: onCloseProp,
   testId: testIdProp,
-  forceFallbackPositioning: forceFallbackPositioningProp
+  forceFallbackPositioning: forceFallbackPositioningProp,
+  id: idProp
 }, ref) {
   var _ref, _ref2, _ctx$popoverRef;
   // When inside <Popup>, context provides defaults. Props always win.
@@ -74,7 +75,7 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   // does not restore focus when they close.
   //
   // To handle this, we listen for the close transition via `onOpenChange` and
-  // restore focus to the trigger if the browser didn't. This runs after the
+  // restore focus to the trigger if the browser did not. This runs after the
   // browser's native restoration (which happens synchronously during hidePopover),
   // so it only takes effect when the browser skipped restoration (nested case).
   //
@@ -91,7 +92,7 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
     // focus when they close.
     //
     // We detect this case by checking if focus is still inside the
-    // closing popover element. If it is, the browser didn't restore,
+    // closing popover element. If it is, the browser did not restore,
     // and we need to move focus to the trigger ourselves.
     //
     // This does NOT fire for:
@@ -100,13 +101,15 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
     if (!args.isOpen) {
       const trigger = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current;
       const focusStillInPopover = trigger && args.element.contains(document.activeElement);
-      if (focusStillInPopover) {
-        const shouldRestore = role === 'dialog' || role === 'alertdialog' || role === 'menu' || role === 'listbox';
-        if (shouldRestore) {
-          trigger.focus({
-            preventScroll: true
-          });
-        }
+      // Single source of truth for "this role moves focus on open
+      // and therefore needs to be restored on close" - see
+      // `shouldFocusIntoPopover` in `internal/role-types.tsx`.
+      if (focusStillInPopover && shouldFocusIntoPopover({
+        role
+      })) {
+        trigger.focus({
+          preventScroll: true
+        });
       }
     }
   }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
@@ -136,8 +139,8 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
   const combinedRef = mergeRefs([popoverRef, ref]);
 
   // TPopupContentProps already validates the discriminated union (role + label,
-  // mode + onClose) at its API boundary. Popover accepts TPopoverInternalProps
-  // internally so individual prop forwarding doesn't need to re-prove the union.
+  // mode + onClose) at its API boundary. Popover accepts TPopoverForwardedProps
+  // internally so individual prop forwarding does not need to re-prove the union.
   const popoverProps = {
     isOpen,
     animate,
@@ -150,7 +153,10 @@ export const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
     onOpenChange: handleOpenChange,
     testId,
     children,
-    id: ctx === null || ctx === void 0 ? void 0 : ctx.popoverId,
+    // Standalone consumers can pass an explicit `id` - used by their own
+    // trigger to wire `aria-controls`. Inside the `<Popup>` compound, the
+    // id flows from context (`ctx.popoverId`).
+    id: idProp !== null && idProp !== void 0 ? idProp : ctx === null || ctx === void 0 ? void 0 : ctx.popoverId,
     xcss
   };
   return /*#__PURE__*/React.createElement(Popover, _extends({

package/dist/es2019/popup/popup-surface.js

@@ -14,6 +14,12 @@ const styles = {
  * should use `Popup.Content` without wrapping in `PopupSurface`.
  *
  * Exposed as `Popup.Surface` on the compound component.
+ *
+ * **Presentational primitive - `children`-only by design.** This component
+ * intentionally exposes no `style`, `className`, `xcss`, `id`, or `ref`
+ * props. If you need any of those, render your own wrapper element inside
+ * `Popup.Content` instead - `PopupSurface` is the no-config "give me the
+ * default ADS overlay look" surface, nothing more.
  */
 export function PopupSurface({
   children

package/dist/es2019/popup/popup-trigger-function.js

@@ -8,7 +8,7 @@ import { usePopupContext } from './popup-context';
 /**
  * Render-prop alternative to `Popup.Trigger`.
  *
- * Use when you need full control over the trigger element — for example,
+ * Use when you need full control over the trigger element. For example,
  * to compose your own trigger with custom event handlers, wrap a third-party
  * component, or build a trigger from multiple elements.
  *

package/dist/es2019/popup/popup-trigger.js

@@ -2,24 +2,15 @@ import React, { isValidElement, useCallback } from 'react';
 import { Slot } from '../internal/slot';
 import { usePopupContext } from './popup-context';
 /**
- * Wraps the trigger element. Attaches aria attributes and handles
- * click to toggle the popover. Sets the anchor-name on the trigger
- * for CSS Anchor Positioning.
+ * Wraps a single trigger element via `cloneElement`. Attaches aria
+ * attributes, the toggle handler, and the anchor-name. `aria-haspopup`
+ * is derived from `Popup.Content`'s role via context.
  *
- * `aria-haspopup` is derived from the content's role via context
- * (set by `Popup.Content`). This ensures the trigger always matches
- * the content's semantic role without the consumer specifying it
- * in two places.
- *
- * **Limitation:** Uses `cloneElement` internally (via `Slot`), which is
- * incompatible with Compiled's `css` prop on the direct child element.
- * The `@jsx jsx` pragma transforms the child before `cloneElement` can
- * inject `onClick` and `ref` onto the DOM node, preventing the popover
- * from opening.
- *
- * If you need Compiled `css` on the trigger, use `Popup.TriggerFunction`
- * instead - it hands you raw props via a render-prop and avoids
- * `cloneElement` entirely.
+ * Child constraints: must be a single ref-forwarding element. The child's
+ * `onClick` is composed (runs after); other event handlers are NOT.
+ * Children using Compiled's `css` prop swallow injected props - use
+ * `Popup.TriggerFunction` for these cases or any time you need handler
+ * composition.
  */
 export function PopupTrigger({
   children
@@ -33,35 +24,24 @@ export function PopupTrigger({
   } = usePopupContext();
   const childOnClick = /*#__PURE__*/isValidElement(children) ? children.props.onClick : undefined;
 
-  // Use a ref to track the latest isOpen value so the click handler
-  // does not need isOpen in its dependency array (which would recreate
-  // the handler on every open/close, breaking cloneElement identity).
+  // Track latest isOpen via ref so the click handler keeps a stable
+  // identity (cloneElement relies on it).
   const isOpenRef = React.useRef(isOpen);
   isOpenRef.current = isOpen;
   const handleClick = useCallback(event => {
     const popoverEl = popoverRef.current;
     if (popoverEl) {
-      // For popover="auto", clicking the trigger (which is outside
-      // the popover) can cause the browser's built-in light-dismiss
-      // to fire before our click handler runs. This means by the time
-      // we get here, the DOM may have already closed the popover.
-      //
-      // We use React's `isOpen` state (via ref) rather than the DOM
-      // state to determine intent:
-      // - If React thinks it was open → the user wants to close.
-      //   The browser already did this via light-dismiss, so do nothing.
-      // - If React thinks it was closed → the user wants to open.
-      //   Call showPopover().
+      // `popover="auto"` light-dismiss can close the popover BEFORE
+      // our click handler runs, so trust React's isOpen rather than
+      // DOM state. If React still thinks it is closed, open it; if
+      // it was open, the browser already closed it.
       if (!isOpenRef.current) {
-        // Defensive: element may be disconnected or in an unexpected state.
         try {
           popoverEl.showPopover();
-        } catch {}
+        } catch {
+          // Element may be disconnected; ignore.
+        }
       }
-      // When isOpenRef.current is true, the browser's light-dismiss
-      // already closed the popover and fired the toggle event, which
-      // will update React state via handleToggle → setIsOpen(false).
-      // No action needed here.
     }
     childOnClick === null || childOnClick === void 0 ? void 0 : childOnClick(event);
   }, [popoverRef, childOnClick]);

package/dist/es2019/popup/popup.js

@@ -1,10 +1,10 @@
 import React, { useCallback, useId, useRef, useState } from 'react';
 import { PopupProvider } from './popup-context';
 /**
- * Popup compound — trigger + popover content.
+ * Popup compound: trigger + popover content.
  *
  * Use when a button opens anchored content (dropdown, menu, dialog).
- * The browser manages visibility via `togglePopover()` — the consumer
+ * The browser manages visibility via `togglePopover()`; the consumer
  * never manages `isOpen`. For custom trigger lifecycles (hover, timers,
  * external state), use `Popover` directly instead.
  *
@@ -12,25 +12,33 @@ import { PopupProvider } from './popup-context';
  * `Popup.Content` reads and forwards to the underlying `Popover`.
  */
 export function PopupRoot(props) {
-  var _props$mode;
+  var _props$placement, _props$mode;
   const {
-    placement,
     children,
     testId,
     forceFallbackPositioning,
     onOpenChange
   } = props;
+  // `{}` resolves to "below the trigger, centered, with `space.100` gap"
+  // inside `useAnchorPosition`, which is the common case.
+  const placement = (_props$placement = props.placement) !== null && _props$placement !== void 0 ? _props$placement : {};
   const mode = (_props$mode = props.mode) !== null && _props$mode !== void 0 ? _props$mode : 'auto';
-  const onClose = mode === 'manual' ? null : props.onClose;
+
+  // `TPopupProps` discriminates on `mode`: `manual` types `onClose` as
+  // `never`, so for manual consumers `props.onClose` is always `undefined`
+  // here. No runtime guard needed; the type contract carries the rule.
+  const onClose = props.onClose;
   const id = useId();
-  // Regex is intentional — `replaceAll` is not available in our supported
-  // browser matrix. `useId()` returns IDs containing colons (e.g. `:r1:`)
-  // which are invalid in CSS selectors and `popover` target attributes.
+  // `useId()` returns IDs containing colons (`:r1:`), which are invalid
+  // in CSS selectors and `popover` target attributes. `replaceAll` is
+  // not in our browser matrix.
   const sanitizedId = id.replace(/:/g, '');
   const popoverId = `popover-${sanitizedId}`;
   const triggerRef = useRef(null);
   const popoverRef = useRef(null);
   const [isOpen, setIsOpen] = useState(false);
+  // Initial seed before `Popup.Content`'s layout effect resolves the
+  // real role on first paint.
   const [ariaHasPopup, setAriaHasPopup] = useState('dialog');
   const handleClose = useCallback(args => {
     onClose === null || onClose === void 0 ? void 0 : onClose(args);
@@ -38,7 +46,10 @@ export function PopupRoot(props) {
   const contextValue = {
     popoverId,
     placement,
-    onClose: mode === 'manual' ? null : handleClose,
+    // `null` when the consumer did not supply a handler (manual mode, or
+    // auto/hint without a light-dismiss handler). `Popup.Content` reads
+    // this to decide whether to forward an `onClose` to `Popover`.
+    onClose: onClose ? handleClose : null,
     triggerRef,
     popoverRef,
     isOpen,