@atlaskit/top-layer 0.8.0 → 0.10.0

package/dist/es2019/internal/use-focus-wrap.js

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
 import { bind } from 'bind-event-listener';
-import { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus/focus';
+import { getFirstFocusable, getLastFocusable, getNextFocusable, isNestedLayerFocused } from '../focus/focus';
 
 /**
  * Roles that require focus wrapping per WAI-ARIA APG.
@@ -14,7 +14,7 @@ import { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus/
  * not Tab. Tab/Shift+Tab should move focus OUT of a menu entirely.
  *
  * Menu keyboard behavior (arrow keys, Home/End, type-ahead, Enter/Space)
- * is context-dependent — it varies by orientation, nesting depth, item
+ * is context-dependent. It varies by orientation, nesting depth, item
  * type, and control pattern (menu button vs menubar). This makes it
  * impossible to implement generically here. The consumer component
  * (e.g. `dropdown-menu`) owns all menu keyboard navigation.
@@ -55,6 +55,17 @@ export function useFocusWrap({
         if (event.key !== 'Tab') {
           return;
         }
+
+        // If focus is already in a nested layer, then
+        // we continue to let that nested layer own focus
+        if (isNestedLayerFocused({
+          container: element
+        })) {
+          return;
+        }
+
+        // Prevent the browser giving focus to where it wants to
+        // (we will be handling it, including with wrapping)
         event.preventDefault();
         const direction = event.shiftKey ? 'backwards' : 'forwards';
 
@@ -70,7 +81,7 @@ export function useFocusWrap({
         }
 
         // Nothing is currently focused inside the container (or the
-        // focused element isn't in the focusable list). Fall back to
+        // focused element is not in the focusable list). Fall back to
         // the first or last focusable element depending on direction.
         const fallback = direction === 'forwards' ? getFirstFocusable({
           container: element

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

@@ -1,4 +1,4 @@
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 import { getFirstFocusable } from '../focus/focus';
 
 /**
@@ -19,9 +19,9 @@ import { getFirstFocusable } from '../focus/focus';
  * React 19+ reflects the JSX prop as the HTML attribute automatically.
  */
 function getInitialFocusTarget({
-  container
+  container,
+  role
 }) {
-  const role = container.getAttribute('role');
   if (role === 'dialog' || role === 'alertdialog') {
     // Prefer element with the native HTML autofocus attribute.
     const autofocusEl = container.querySelector('[autofocus]');
@@ -62,14 +62,15 @@ function getInitialFocusTarget({
 /**
  * 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.
@@ -79,6 +80,12 @@ export function useInitialFocus({
   isOpen,
   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.
+  const pendingRafRef = useRef(null);
   useEffect(() => {
     if (!isOpen) {
       return;
@@ -88,6 +95,11 @@ export function useInitialFocus({
       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
@@ -95,15 +107,24 @@ export function useInitialFocus({
     // element is guaranteed to be in the top layer.
     const rafId = requestAnimationFrame(() => {
       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
       })) === null || _getInitialFocusTarge === void 0 ? void 0 : _getInitialFocusTarge.focus();
     });
+    pendingRafRef.current = rafId;
     return () => {
       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/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,9 +61,4 @@ export function fromLegacyPlacement({
       }
     }
   };
-}
-
-/**
- * The full mapping record, exposed for consumers that need to iterate or introspect.
- */
-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,8 +5,8 @@ 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';
 import { useFocusWrap } from '../internal/use-focus-wrap';
 import { useInitialFocus } from '../internal/use-initial-focus';
@@ -29,6 +29,18 @@ const supportsPopoverHint = once(() => {
 const 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.
+ */
+const POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', 'grid']);
+
 /**
  * Unopinionated top-layer primitive.
  *
@@ -43,13 +55,13 @@ const 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.
  */
 export const Popover = /*#__PURE__*/forwardRef(function Popover({
   children,
   mode: modeProp = 'auto',
-  onClose = noop,
+  onClose,
   onOpenChange,
   onExitFinish,
   animate,
@@ -66,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
@@ -85,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({
@@ -98,6 +110,24 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     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.
+  const handleObserverClose = useCallback(() => {
+    onClose === null || onClose === void 0 ? void 0 : onClose({
+      reason: 'programmatic'
+    });
+  }, [onClose]);
+  useNotifyOpenLayerObserver({
+    type: role && POPUP_ROLES.has(role) ? 'popup' : undefined,
+    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")
@@ -110,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
@@ -144,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
       });
     }
@@ -179,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) {
@@ -198,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-context.js

@@ -15,6 +15,7 @@ export const PopupProvider = PopupContext.Provider;
  *
  * Throws if called outside of a `<Popup>` compound component.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function usePopupContext() {
   const ctx = useContext(PopupContext);
   if (ctx === null) {
@@ -29,6 +30,7 @@ export 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
 export function useMaybePopupContext() {
   return useContext(PopupContext);
 }

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.
  *