@atlaskit/top-layer 0.8.0 → 0.10.0

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,8 +7,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';
@@ -31,6 +31,18 @@ var supportsPopoverHint = once(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.
  *
@@ -45,15 +57,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.
  */
 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,
@@ -68,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
@@ -86,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({
@@ -99,6 +110,24 @@ export var Popover = /*#__PURE__*/forwardRef(function Popover(_ref, ref) {
     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 = useCallback(function () {
+    onClose === null || onClose === void 0 || onClose({
+      reason: 'programmatic'
+    });
+  }, [onClose]);
+  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")
@@ -111,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
@@ -145,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
       });
     }
@@ -180,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) {
@@ -202,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-context.js

@@ -15,6 +15,7 @@ export var 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() {
   var 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/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,

package/dist/esm/use-arrow-navigation/use-arrow-navigation.js

@@ -7,16 +7,16 @@ var menuScope = '[role="menu"]';
 
 /**
  * Returns true if the element belongs to the current menu level of the
- * container — i.e. it is NOT inside a nested `role="menu"` sub-container.
+ * container, i.e. it is NOT inside a nested `role="menu"` sub-container.
  *
  * Uses `element.closest('[role="menu"]')` to determine the nearest menu
  * scope. If the nearest scope is the container's own `role="menu"` element,
- * the element belongs to this level. If it's a different (nested) menu,
+ * the element belongs to this level. If it is a different (nested) menu,
  * the element belongs to a child level and should be excluded.
  *
  * Supports two container patterns:
  *
- * **1. Container has `role="menu"` directly** (preferred — used by avatar-group):
+ * **1. Container has `role="menu"` directly** (preferred, used by avatar-group):
  *   ```
  *   <div ref={containerRef} role="menu">
  *     <button role="menuitem" />   ← isAtCurrentMenuLevel → true
@@ -28,7 +28,7 @@ var menuScope = '[role="menu"]';
  *   Uses the simple check: `element.closest('[role="menu"]') === container`
  *
  * **2. Container is a wrapper without `role="menu"`** (used by dropdown-menu,
- *   where `MenuGroup` owns `role="menu"` but doesn't accept a ref):
+ *   where `MenuGroup` owns `role="menu"` but does not accept a ref):
  *   ```
  *   <div ref={containerRef}>         ← wrapper (no role="menu")
  *     <MenuGroup role="menu">
@@ -55,7 +55,7 @@ var menuScope = '[role="menu"]';
 export function isAtCurrentMenuLevel(element, container) {
   var closestMenu = element.closest(menuScope);
 
-  // Container itself has role="menu" — element belongs to this level
+  // Container itself has role="menu". Element belongs to this level
   // if its closest menu is the container.
   if (container.getAttribute('role') === 'menu') {
     return closestMenu === container;
@@ -64,18 +64,18 @@ export function isAtCurrentMenuLevel(element, container) {
   // Container is a wrapper without role="menu" (e.g. dropdown-menu
   // wraps a MenuGroup). The element belongs to the top level if its
   // closest role="menu" ancestor is a direct child of the container,
-  // i.e. there's no nested role="menu" between them.
+  // i.e. there is no nested role="menu" between them.
   if (closestMenu === null) {
     return true;
   }
 
-  // Walk up from the closest menu to see if it's "owned" by this
+  // Walk up from the closest menu to see if it is "owned" by this
   // container without passing through another role="menu" first.
   var parent = closestMenu.parentElement;
   while (parent && parent !== container) {
     if (parent.getAttribute('role') === 'menu') {
-      // There's a parent menu between the closest menu and the
-      // container — the element is in a nested sub-menu.
+      // There is a parent menu between the closest menu and the
+      // container, so the element is in a nested sub-menu.
       return false;
     }
     parent = parent.parentElement;
@@ -84,6 +84,22 @@ export function isAtCurrentMenuLevel(element, container) {
   // The closest menu is directly inside the container (no nesting).
   return parent === container;
 }
+
+/**
+ * Args for `useArrowNavigation`.
+ *
+ * Keyboard contract:
+ * - `ArrowDown` / `ArrowUp` move within the current menu level.
+ * - `Home` / `End` jump to first / last.
+ * - `ArrowRight` / `ArrowLeft` opens / closes nested submenus.
+ * - `Tab` / `Shift+Tab` dismiss the menu (matching the ARIA APG menu pattern,
+ *   plus Radix UI / Headless UI / React Aria / Floating UI conventions).
+ *   Symmetric in both directions: there is no special-case for the last
+ *   item that lets Tab leave the menu without dismissing it.
+ * - `Page Up` / `Page Down`: NOT handled - extend via your own listener if
+ *   your menu needs page-style scrolling.
+ */
+
 /**
  * Provides arrow key navigation for menu containers.
  *
@@ -119,6 +135,7 @@ export function isAtCurrentMenuLevel(element, container) {
  * });
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function useArrowNavigation(_ref) {
   var containerRef = _ref.containerRef,
     onClose = _ref.onClose,
@@ -214,7 +231,7 @@ export function useArrowNavigation(_ref) {
       if (onNestedClose) {
         var _container$parentElem;
         // Only close if this container is inside another role="menu"
-        // (i.e. it's a submenu, not the top-level menu).
+        // (i.e. it is a submenu, not the top-level menu).
         // Walk up from the parent to avoid matching the container itself.
         var isNested = ((_container$parentElem = container.parentElement) === null || _container$parentElem === void 0 ? void 0 : _container$parentElem.closest(menuScope)) !== null;
         if (isNested) {

package/dist/types/arrow/index.d.ts

@@ -0,0 +1,24 @@
+import { type TArrowPreset } from './types';
+/**
+ * Creates an arrow preset for popover content.
+ *
+ * The returned object is passed to `PopoverContent`'s `arrow` prop.
+ * It carries the CSS string and fallback logic so that consumers who
+ * do not use arrows pay no bundle cost.
+ *
+ * The arrows inherit their background from the popover element.
+ * When `arrow` is active, `PopoverContent` does not reset `background`
+ * to `transparent`, allowing the UA default (`canvas`) or a consumer-set
+ * background to show through.
+ *
+ * @example
+ * ```tsx
+ * import { arrow } from '@atlaskit/top-layer/arrow';
+ *
+ * const myArrow = arrow();
+ *
+ * <Popup.Content arrow={myArrow} />
+ * ```
+ */
+export declare const arrow: () => TArrowPreset;
+export type { TArrowPreset } from './types';