@atlaskit/top-layer 0.9.0 → 0.11.0

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

@@ -2,10 +2,7 @@ import _defineProperty from "@babel/runtime/helpers/defineProperty";
 import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
-/**
- * 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
@@ -17,9 +14,11 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  * | ------------------- | --------------------------------------------------- |
  * | `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' }`    |
@@ -31,7 +30,10 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  * | `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
@@ -43,103 +45,6 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-var 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(_ref) {
   var legacy = _ref.legacy,
     offset = _ref.offset;
@@ -160,10 +65,4 @@ export function fromLegacyPlacement(_ref) {
       }
     }
   });
-}
-
-/**
- * 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/esm/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 var 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 var 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/esm/popover/popover.js

@@ -7,7 +7,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';
@@ -58,15 +57,14 @@ var 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 var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   var children = _ref.children,
     _ref$mode = _ref.mode,
     modeProp = _ref$mode === void 0 ? 'auto' : _ref$mode,
-    _ref$onClose = _ref.onClose,
-    onClose = _ref$onClose === void 0 ? noop : _ref$onClose,
+    onClose = _ref.onClose,
     onOpenChange = _ref.onOpenChange,
     onExitFinish = _ref.onExitFinish,
     animate = _ref.animate,
@@ -81,7 +79,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   var autoId = useId();
   var ownRef = useRef(null);
   var 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
@@ -99,7 +97,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   // ── 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({
@@ -120,7 +118,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   // Passive/informational roles (tooltip, note, status, alert, log) and
   // no-role cases do not map to LayerType 'popup', so type is left undefined.
   var handleObserverClose = useCallback(function () {
-    onClose({
+    onClose === null || onClose === void 0 || onClose({
       reason: 'programmatic'
     });
   }, [onClose]);
@@ -142,8 +140,8 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   var 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.
   var programmaticCloseRef = useRef(false);
 
   // Escape key tracking: set in a capture-phase keydown listener (fires before
@@ -176,7 +174,11 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
       // Browser dismiss (Escape or click-outside). Notify consumer.
       var 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 || onClose({
         reason: reason
       });
     }
@@ -211,7 +213,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
 
   // 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(function () {
     var el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -233,7 +235,7 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
   // 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(function () {

package/dist/esm/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';
@@ -31,7 +31,8 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     placementProp = _ref.placement,
     onCloseProp = _ref.onClose,
     testIdProp = _ref.testId,
-    forceFallbackPositioningProp = _ref.forceFallbackPositioning;
+    forceFallbackPositioningProp = _ref.forceFallbackPositioning,
+    idProp = _ref.id;
   // When inside <Popup>, context provides defaults. Props always win.
   var ctx = useMaybePopupContext();
   var triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
@@ -74,7 +75,7 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
   // 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 var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     // 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 var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     if (!args.isOpen) {
       var trigger = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current;
       var focusStillInPopover = trigger && args.element.contains(document.activeElement);
-      if (focusStillInPopover) {
-        var 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: role
+      })) {
+        trigger.focus({
+          preventScroll: true
+        });
       }
     }
   }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
@@ -136,8 +139,8 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
   var 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.
   var popoverProps = {
     isOpen: isOpen,
     animate: animate,
@@ -150,7 +153,10 @@ export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, re
     onOpenChange: handleOpenChange,
     testId: testId,
     children: 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: xcss
   };
   return /*#__PURE__*/React.createElement(Popover, _extends({

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

@@ -14,6 +14,12 @@ var 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(_ref) {
   var children = _ref.children;

package/dist/esm/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/esm/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(_ref) {
   var children = _ref.children;
@@ -31,35 +22,24 @@ export function PopupTrigger(_ref) {
     ariaHasPopup = _usePopupContext.ariaHasPopup;
   var 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).
   var isOpenRef = React.useRef(isOpen);
   isOpenRef.current = isOpen;
   var handleClick = useCallback(function (event) {
     var 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 (_unused) {}
+        } catch (_unused) {
+          // 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 || childOnClick(event);
   }, [popoverRef, childOnClick]);

package/dist/esm/popup/popup.js

@@ -2,10 +2,10 @@ import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
 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.
  *
@@ -13,18 +13,24 @@ import { PopupProvider } from './popup-context';
  * `Popup.Content` reads and forwards to the underlying `Popover`.
  */
 export function PopupRoot(props) {
-  var _props$mode;
-  var placement = props.placement,
-    children = props.children,
+  var _props$placement, _props$mode;
+  var children = props.children,
     testId = props.testId,
     forceFallbackPositioning = props.forceFallbackPositioning,
     onOpenChange = props.onOpenChange;
+  // `{}` resolves to "below the trigger, centered, with `space.100` gap"
+  // inside `useAnchorPosition`, which is the common case.
+  var placement = (_props$placement = props.placement) !== null && _props$placement !== void 0 ? _props$placement : {};
   var mode = (_props$mode = props.mode) !== null && _props$mode !== void 0 ? _props$mode : 'auto';
-  var 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.
+  var onClose = props.onClose;
   var 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.
   var sanitizedId = id.replace(/:/g, '');
   var popoverId = "popover-".concat(sanitizedId);
   var triggerRef = useRef(null);
@@ -33,6 +39,8 @@ export function PopupRoot(props) {
     _useState2 = _slicedToArray(_useState, 2),
     isOpen = _useState2[0],
     setIsOpen = _useState2[1];
+  // Initial seed before `Popup.Content`'s layout effect resolves the
+  // real role on first paint.
   var _useState3 = useState('dialog'),
     _useState4 = _slicedToArray(_useState3, 2),
     ariaHasPopup = _useState4[0],
@@ -43,7 +51,10 @@ export function PopupRoot(props) {
   var contextValue = {
     popoverId: popoverId,
     placement: 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: triggerRef,
     popoverRef: popoverRef,
     isOpen: isOpen,