@atlaskit/top-layer 0.8.0 → 0.10.0

package/dist/cjs/internal/use-initial-focus.js

@@ -24,8 +24,8 @@ var _focus = require("../focus/focus");
  * React 19+ reflects the JSX prop as the HTML attribute automatically.
  */
 function getInitialFocusTarget(_ref) {
-  var container = _ref.container;
-  var role = container.getAttribute('role');
+  var container = _ref.container,
+    role = _ref.role;
   if (role === 'dialog' || role === 'alertdialog') {
     // Prefer element with the native HTML autofocus attribute.
     var autofocusEl = container.querySelector('[autofocus]');
@@ -66,14 +66,15 @@ function getInitialFocusTarget(_ref) {
 /**
  * Moves focus into a popover element when it opens, based on its ARIA role.
  *
- * This implements WCAG 2.4.3 (Focus Order) initial focus placement:
+ * Follows the WAI-ARIA APG initial-focus patterns for each role:
  * - `dialog` / `alertdialog` → focus first focusable (or `[autofocus]`)
  * - `menu` → focus first menu item
  * - `listbox` → focus selected or first option
- * - `tooltip` / no role → no focus movement
+ * - `tooltip` / no role → no focus movement (focus must remain on trigger;
+ *   moving focus into the tooltip would dismiss it)
  *
- * The role is read from the element's `role` attribute (not passed as a prop),
- * following the same pattern as `useFocusWrap`.
+ * Role is taken from the typed `role` prop - this is the consumer's contract
+ * and is not subject to drift from a directly-mutated DOM attribute.
  *
  * Always call this hook unconditionally. Focus is only moved when `isOpen`
  * transitions to `true` and the role requires it.
@@ -82,6 +83,12 @@ function useInitialFocus(_ref2) {
   var elementRef = _ref2.elementRef,
     isOpen = _ref2.isOpen,
     role = _ref2.role;
+  // Track the most recently scheduled RAF so a rapid `isOpen → false → true`
+  // transition can cancel the previous frame before its closure runs against
+  // a stale popover element. Without this, the RAF queued during the first
+  // open could fire after the second open had begun and focus the wrong
+  // instance.
+  var pendingRafRef = (0, _react.useRef)(null);
   (0, _react.useEffect)(function () {
     if (!isOpen) {
       return;
@@ -91,6 +98,11 @@ function useInitialFocus(_ref2) {
       return;
     }
 
+    // Cancel any RAF queued by the previous open cycle.
+    if (pendingRafRef.current !== null) {
+      cancelAnimationFrame(pendingRafRef.current);
+    }
+
     // Use requestAnimationFrame to ensure the popover is fully rendered
     // and visible in the top layer before attempting to move focus.
     // showPopover() is called in useLayoutEffect (which runs before this
@@ -98,15 +110,24 @@ function useInitialFocus(_ref2) {
     // element is guaranteed to be in the top layer.
     var rafId = requestAnimationFrame(function () {
       var _getInitialFocusTarge;
+      pendingRafRef.current = null;
+      // Verify the element we captured is still the live popover. In
+      // rapid-toggle scenarios the ref may already point to a different
+      // instance - skip rather than focus the wrong popover.
+      if (elementRef.current !== el) {
+        return;
+      }
       (_getInitialFocusTarge = getInitialFocusTarget({
-        container: el
+        container: el,
+        role: role
       })) === null || _getInitialFocusTarge === void 0 || _getInitialFocusTarge.focus();
     });
+    pendingRafRef.current = rafId;
     return function () {
       cancelAnimationFrame(rafId);
+      if (pendingRafRef.current === rafId) {
+        pendingRafRef.current = null;
+      }
     };
-    // We intentionally depend on `role` even though `getInitialFocusTarget`
-    // reads from the DOM attribute. This ensures the effect re-runs if
-    // the role prop changes while the popover is open.
   }, [elementRef, isOpen, role]);
 }

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

@@ -5,16 +5,11 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.fromLegacyPlacement = fromLegacyPlacement;
-exports.placementMapping = void 0;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _legacyPlacements = require("./legacy-placements");
 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) { (0, _defineProperty2.default)(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.).
- */
-
 /**
  * Maps legacy Popper.js placement values to the new object-based
  * `Placement` values used by `@atlaskit/top-layer/popover`.
@@ -25,9 +20,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' }`    |
@@ -39,7 +36,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
@@ -51,107 +51,10 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-var placementMapping = exports.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.
- */
 function fromLegacyPlacement(_ref) {
   var legacy = _ref.legacy,
     offset = _ref.offset;
-  var basePlacement = placementMapping[legacy];
+  var basePlacement = _legacyPlacements.placementMapping[legacy];
   if (!offset) {
     return basePlacement;
   }
@@ -168,8 +71,4 @@ function fromLegacyPlacement(_ref) {
       }
     }
   });
-}
-
-/**
- * The full mapping record, exposed for consumers that need to iterate or introspect.
- */
+}

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

@@ -0,0 +1,113 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.placementMapping = exports.LEGACY_PLACEMENTS = void 0;
+/**
+ * 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
+var LEGACY_PLACEMENTS = exports.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
+var placementMapping = exports.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/cjs/popover/popover.js

@@ -15,8 +15,8 @@ var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/sli
 var _react = _interopRequireWildcard(require("react"));
 var _bindEventListener = require("bind-event-listener");
 var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
-var _noop = _interopRequireDefault(require("@atlaskit/ds-lib/noop"));
 var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
+var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
 var _useAnimatedVisibility = require("../internal/use-animated-visibility");
 var _useFocusWrap = require("../internal/use-focus-wrap");
 var _useInitialFocus = require("../internal/use-initial-focus");
@@ -40,6 +40,18 @@ var supportsPopoverHint = (0, _once.default)(function () {
 var styles = {
   root: "_19itglyw _ca0qidpf _u5f3idpf _n3tdidpf _19bvidpf _19pkidpf _2hwxidpf _otyridpf _18u0idpf _1r041wug _1reoewfl _18m9ewfl _bfhk1j28"
 };
+/**
+ * ARIA roles on the Popover primitive that register with the open layer observer
+ * as LayerType 'popup'. These are interactive overlays that should be tracked
+ * and dismissed when closeLayers() is called (e.g. when the side nav resizes).
+ *
+ * Note on open layer observer types not included here:
+ * - 'modal' only ever comes from the Dialog primitive, not Popover.
+ * - Other layer types (e.g. 'tooltip') do not yet exist in LayerType because
+ *   there is no current use case for distinguishing them in the observer.
+ */
+var POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', 'grid']);
+
 /**
  * Unopinionated top-layer primitive.
  *
@@ -54,15 +66,14 @@ var styles = {
  *
  * 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.
  */
 var Popover = exports.Popover = /*#__PURE__*/(0, _react.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.default : _ref$onClose,
+    onClose = _ref.onClose,
     onOpenChange = _ref.onOpenChange,
     onExitFinish = _ref.onExitFinish,
     animate = _ref.animate,
@@ -77,7 +88,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   var autoId = (0, _react.useId)();
   var ownRef = (0, _react.useRef)(null);
   var combinedRef = (0, _mergeRefs.default)([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
@@ -95,7 +106,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   // ── 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
   (0, _useFocusWrap.useFocusWrap)({
@@ -108,6 +119,24 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     role: role
   });
 
+  // ── Open layer observer registration ──
+  // Notifies the open layer observer so app-coordination features
+  // (closeLayers(), open-count subscriptions) work with top-layer popovers.
+  //
+  // Only set type: 'popup' for roles that are interactive overlay popups.
+  // 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 = (0, _react.useCallback)(function () {
+    onClose === null || onClose === void 0 || onClose({
+      reason: 'programmatic'
+    });
+  }, [onClose]);
+  (0, _openLayerObserver.useNotifyOpenLayerObserver)({
+    type: role && POPUP_ROLES.has(role) ? 'popup' : undefined,
+    isOpen: isOpen,
+    onClose: handleObserverClose
+  });
+
   // Hint mode fallback: "hint" downgrades to "auto" if unsupported.
   //
   // Decision (2026-03-17 audit): We keep "auto" as the fallback (not "manual")
@@ -120,8 +149,8 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   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 = (0, _react.useRef)(false);
 
   // Escape key tracking: set in a capture-phase keydown listener (fires before
@@ -154,7 +183,11 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       // 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
       });
     }
@@ -189,7 +222,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
 
   // 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.
   (0, _react.useLayoutEffect)(function () {
     var el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -211,7 +244,7 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
   // 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).
   (0, _react.useLayoutEffect)(function () {

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

@@ -40,7 +40,8 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     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 = (0, _popupContext.useMaybePopupContext)();
   var triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
@@ -83,7 +84,7 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
   // 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).
   //
@@ -100,7 +101,7 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     // 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:
@@ -109,13 +110,15 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     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 && (0, _roleTypes.shouldFocusIntoPopover)({
+        role: role
+      })) {
+        trigger.focus({
+          preventScroll: true
+        });
       }
     }
   }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
@@ -145,8 +148,8 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
   var combinedRef = (0, _mergeRefs.default)([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,
@@ -159,7 +162,10 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
     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.default.createElement(_popover.Popover, (0, _extends2.default)({

package/dist/cjs/popup/popup-context.js

@@ -23,6 +23,7 @@ var PopupProvider = exports.PopupProvider = PopupContext.Provider;
  *
  * Throws if called outside of a `<Popup>` compound component.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function usePopupContext() {
   var ctx = (0, _react.useContext)(PopupContext);
   if (ctx === null) {
@@ -37,6 +38,7 @@ function usePopupContext() {
  * Used by `PopupContent` to support standalone usage (e.g. tooltip)
  * where values are passed as props instead of coming from a compound component.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function useMaybePopupContext() {
   return (0, _react.useContext)(PopupContext);
 }

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

@@ -21,6 +21,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.
  */
 function PopupSurface(_ref) {
   var children = _ref.children;

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

@@ -13,7 +13,7 @@ var _popupContext = require("./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.
  *