@atlaskit/top-layer 0.12.2 → 0.14.0

package/dist/cjs/popover/popover.js

@@ -17,14 +17,13 @@ var _bindEventListener = require("bind-event-listener");
 var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
 var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
 var _openLayerObserver = require("@atlaskit/layering/experimental/open-layer-observer");
+var _roleTypes = require("../internal/role-types");
 var _useAnimatedVisibility = require("../internal/use-animated-visibility");
 var _useFocusWrap = require("../internal/use-focus-wrap");
 var _useInitialFocus = require("../internal/use-initial-focus");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function _interopRequireWildcard(e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != _typeof(e) && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (var _t in e) "default" !== _t && {}.hasOwnProperty.call(e, _t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, _t)) && (i.get || i.set) ? o(f, _t, i) : f[_t] = e[_t]); return f; })(e, t); }
 /**
- * Detects whether the browser supports the `popover="hint"` attribute value.
- * Uses DOM reflection: unsupported browsers reflect the invalid value default ("manual").
- * Safe for SSR. Result is cached via `once`.
+ * Detects `popover="hint"` support via DOM reflection. SSR-safe, cached.
  */
 var supportsPopoverHint = (0, _once.default)(function () {
   if (typeof document === 'undefined') {
@@ -41,33 +40,20 @@ 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.
+ * Roles registered with the open layer observer as `popup`, so `closeLayers()`
+ * dismisses them. `modal` comes from Dialog only; other layer types are unused.
  */
 var POPUP_ROLES = new Set(['menu', 'listbox', 'dialog', 'alertdialog', 'tree', 'grid']);
 
 /**
- * Unopinionated top-layer primitive.
- *
- * Manages only visibility (isOpen) and animation (animate). Has no knowledge
- * of positioning - compose with `useAnchorPosition` for anchor positioning
- * and optionally `useWidthFromAnchor` for setting the width of a popover element
- * relative to its anchor trigger.
+ * Unopinionated top-layer primitive. Manages visibility and animation only;
+ * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
  *
- * Visibility is driven by the `isOpen` prop:
- * - `isOpen={true}` → `showPopover()`, entry animation via `@starting-style`
- * - `isOpen={false}` → `hidePopover()`, exit animation via `allow-discrete`
+ * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
+ * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
  *
- * 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
- * must follow.
+ * In `mode="auto"`, the browser can light-dismiss (Escape, click outside).
+ * `onClose` fires; the consumer must then set `isOpen` to `false`.
  */
 var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Popover(_ref, ref) {
   var children = _ref.children,
@@ -89,11 +75,9 @@ 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
-  // 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
-  // stripping unnecessary once React 18 support is dropped.
+  // React 18 `useId()` returns IDs with colons (invalid in CSS selectors
+  // and popover target attributes). Strip them; remove once React 18 is
+  // dropped (React 19.2 uses underscores).
   var popoverId = idProp !== null && idProp !== void 0 ? idProp : "popover-".concat(autoId.replace(/:/g, ''));
   var _useAnimatedVisibilit = (0, _useAnimatedVisibility.useAnimatedVisibility)({
       isOpen: isOpen,
@@ -105,12 +89,10 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     showChildren = _useAnimatedVisibilit.showChildren,
     preset = _useAnimatedVisibilit.preset;
 
-  // 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
-  //   tracks `previouslyFocusedElement` on show and restores it on hide.
-  //   No custom restoration hook is needed. See: notes/architecture/focus-restoration.md
+  // Focus management: initial focus on open (role-dependent), Tab cycling
+  // for dialog roles. Restoration is native for outermost popovers; nested
+  // focus-capturing roles are handled below via `beforetoggle` snapshot.
+  // See: notes/architecture/focus-restoration.md
   (0, _useFocusWrap.useFocusWrap)({
     elementRef: ownRef,
     role: role
@@ -121,13 +103,9 @@ 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.
+  // Register with open layer observer so `closeLayers()` and open-count
+  // subscriptions work. Only popup-like roles register as `popup`; passive
+  // roles (tooltip, status, etc.) leave `type` undefined.
   var handleObserverClose = (0, _react.useCallback)(function () {
     onClose === null || onClose === void 0 || onClose({
       reason: 'programmatic'
@@ -139,25 +117,29 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     onClose: handleObserverClose
   });
 
-  // Hint mode fallback: "hint" downgrades to "auto" if unsupported.
-  //
-  // Decision (2026-03-17 audit): We keep "auto" as the fallback (not "manual")
-  // because it provides the closest behavior to "hint" (light dismiss works).
-  // However, there is a behavioral difference: "auto" participates in the
-  // auto-dismiss stack and WILL close other "auto" popovers when it opens
-  // (e.g. a tooltip opening will close an open dropdown). "hint" does not
-  // have this side effect. This difference only affects browsers without
-  // popover="hint" support, and that set is shrinking rapidly.
+  // `hint` falls back to `auto` when unsupported: closest behavior (light
+  // dismiss works), but `auto` participates in the auto-dismiss stack so it
+  // will close other `auto` popovers when opened. Acceptable trade-off given
+  // shrinking browser set without `hint` support.
   var mode = modeProp === 'hint' && !supportsPopoverHint() ? 'auto' : modeProp;
 
-  // Distinguishes programmatic hidePopover() from browser-initiated dismiss.
-  // When we call hidePopover() ourselves the beforetoggle event fires synchronously,
-  // so this ref prevents the toggle handler from calling onClose redundantly.
+  // Prevents toggle handler from calling onClose for our own hidePopover() calls.
   var programmaticCloseRef = (0, _react.useRef)(false);
 
-  // Escape key tracking: set in a capture-phase keydown listener (fires before
-  // the browser processes light dismiss), read in the toggle handler.
+  // Set in capture-phase keydown so the toggle handler knows close reason.
   var closeReasonRef = (0, _react.useRef)('light-dismiss');
+
+  // Snapshot of pre-open focus, used to restore focus for nested popovers
+  // with focus-capturing roles (browser only restores the outermost).
+  var previouslyFocusedElementRef = (0, _react.useRef)(null);
+  var handleBeforeToggle = (0, _react.useCallback)(function (event) {
+    if (event.newState !== 'open') {
+      return;
+    }
+    // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- need active element snapshot
+    var active = document.activeElement;
+    previouslyFocusedElementRef.current = active instanceof HTMLElement ? active : null;
+  }, []);
   var handleToggle = (0, _react.useCallback)(function (event) {
     var element = ownRef.current;
     if (event.newState === 'open') {
@@ -175,32 +157,52 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
           isOpen: false,
           element: element
         });
+
+        // Nested-popover focus restoration fallback (browser only
+        // restores outermost; Firefox skips nested entirely).
+        // Restore only when the role moved focus in on open AND the
+        // close was Escape/programmatic. For light dismiss, the
+        // click target keeps focus per HTML spec
+        // (`focusPreviousElement=false`).
+        var previouslyFocused = previouslyFocusedElementRef.current;
+        var _reason = closeReasonRef.current;
+        var isProgrammatic = programmaticCloseRef.current;
+        var shouldRestore = previouslyFocused !== null && previouslyFocused.isConnected && (0, _roleTypes.shouldFocusIntoPopover)({
+          role: role
+        }) && (_reason === 'escape' || isProgrammatic);
+        if (shouldRestore && previouslyFocused) {
+          previouslyFocused.focus({
+            preventScroll: true
+          });
+        }
+        previouslyFocusedElementRef.current = null;
       }
 
-      // Programmatic close (unmount or isOpen→false). Consumer already knows.
+      // Programmatic close: consumer already knows.
       if (programmaticCloseRef.current) {
+        // Reset reason so a stale 'escape' from a race with Escape keydown
+        // does not corrupt the next browser-dismiss cycle.
+        closeReasonRef.current = 'light-dismiss';
         return;
       }
 
-      // Browser dismiss (Escape or click-outside). Notify consumer.
+      // Browser dismiss (Escape/click-outside).
       var reason = closeReasonRef.current;
-      closeReasonRef.current = 'light-dismiss'; // reset for next dismiss
-      // `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.
+      // reset for next dismiss
+      closeReasonRef.current = 'light-dismiss';
+      // Optional: `manual` mode has no `onClose` in the forwarded type.
       onClose === null || onClose === void 0 || onClose({
         reason: reason
       });
     }
-  }, [onClose, onOpenChange]);
+  }, [onClose, onOpenChange, role]);
   (0, _react.useEffect)(function () {
     var element = ownRef.current;
     if (!element) {
       return;
     }
 
-    // Capture-phase: tag Escape before the browser processes light dismiss.
+    // Tag Escape before the browser processes light dismiss.
     var unbindEscape = (0, _bindEventListener.bind)(element, {
       type: 'keydown',
       listener: function listener(event) {
@@ -216,15 +218,20 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
       type: 'toggle',
       listener: handleToggle
     });
+    // Snapshot `document.activeElement` before `useInitialFocus` moves it.
+    var unbindBeforeToggle = (0, _bindEventListener.bind)(element, {
+      type: 'beforetoggle',
+      listener: handleBeforeToggle
+    });
     return function () {
       unbindEscape();
       unbindToggle();
+      unbindBeforeToggle();
     };
-  }, [handleToggle]);
+  }, [handleToggle, handleBeforeToggle]);
 
-  // Placement-dependent animation CSS vars (e.g. slide direction).
-  // Separate from show/hide so that preset reference changes
-  // (e.g. inline `animate={slideAndFade()}`) do not re-trigger visibility.
+  // Placement-dependent animation CSS vars. Kept separate from show/hide
+  // so preset reference changes do not re-trigger visibility.
   (0, _react.useLayoutEffect)(function () {
     var el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -241,14 +248,9 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     });
   }, [preset, placement]);
 
-  // Show/hide based on isOpen.
-  // showPopover() and hidePopover() are no-ops when the popover is already
-  // 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 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).
+  // Show/hide based on isOpen. `showPopover`/`hidePopover` are no-ops when
+  // already in the target state. Try/catch guards `InvalidStateError` on
+  // disconnected elements (StrictMode/concurrent/unmount edge cases).
   (0, _react.useLayoutEffect)(function () {
     var el = ownRef.current;
     if (!el) {
@@ -256,20 +258,17 @@ var Popover = exports.Popover = /*#__PURE__*/(0, _react.forwardRef)(function Pop
     }
     if (isOpen) {
       programmaticCloseRef.current = false;
-      // Defensive: element may be disconnected or in an unexpected state.
       try {
         el.showPopover();
       } catch (_unused) {}
       return function () {
         programmaticCloseRef.current = true;
-        // Defensive: element may be disconnected or in an unexpected state.
         try {
           el.hidePopover();
         } catch (_unused2) {}
       };
     }
     programmaticCloseRef.current = true;
-    // Defensive: element may be disconnected or in an unexpected state.
     try {
       el.hidePopover();
     } catch (_unused3) {}

package/dist/cjs/popover-surface/index.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "PopoverSurface", {
+  enumerable: true,
+  get: function get() {
+    return _popoverSurface.PopoverSurface;
+  }
+});
+var _popoverSurface = require("./popover-surface");

package/dist/cjs/{popup/popup-surface.js → popover-surface/popover-surface.js}

@@ -1,12 +1,12 @@
-/* popup-surface.tsx generated by @compiled/babel-plugin v0.39.1 */
+/* popover-surface.tsx generated by @compiled/babel-plugin v0.39.1 */
 "use strict";
 
 var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.PopupSurface = PopupSurface;
-require("./popup-surface.compiled.css");
+exports.PopoverSurface = PopoverSurface;
+require("./popover-surface.compiled.css");
 var _runtime = require("@compiled/react/runtime");
 var _react = _interopRequireDefault(require("react"));
 var styles = {
@@ -14,21 +14,18 @@ var styles = {
 };
 
 /**
- * Optional styled wrapper for popup content.
+ * Optional styled wrapper for popover content.
  *
  * Adds default visual styling (background, border-radius, box-shadow)
- * using design tokens. Consumers who want fully custom styling
- * should use `Popup.Content` without wrapping in `PopupSurface`.
+ * using design tokens.
  *
- * Exposed as `Popup.Surface` on the compound component.
- *
- * **Presentational primitive - `children`-only by design.** This 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.
+ * `Popover` instead. `PopoverSurface` is the no-config "give me the default
+ * ADS overlay look" surface, nothing more.
  */
-function PopupSurface(_ref) {
+function PopoverSurface(_ref) {
   var children = _ref.children;
   return /*#__PURE__*/_react.default.createElement("div", {
     className: (0, _runtime.ax)([styles.root])

package/dist/cjs/testing/polyfill.js

@@ -104,7 +104,7 @@ function createToggleScheduler() {
       newState: newState
     });
 
-    // Task queue (setTimeout) - browser fires toggle after microtasks drain, not during
+    // Task queue (setTimeout): browser fires toggle after microtasks drain, not during
     setTimeout(function () {
       var entry = pending.get(element);
       if (!entry) {
@@ -534,10 +534,11 @@ if (typeof HTMLElement !== 'undefined') {
           element: this
         }), " is not connected to the document. Ensure the element has been added to the DOM (e.g. via render() or document.body.appendChild()) before calling showPopover()."), 'InvalidStateError');
       }
+      // No-op: already showing.
       if (isPopoverOpen({
         element: this
       })) {
-        return; // already showing - no-op
+        return;
       }
 
       // sync, cancelable on show only
@@ -731,8 +732,9 @@ if (typeof HTMLDialogElement !== 'undefined') {
         }), " is not connected to the document. Ensure the element has been added to the DOM (e.g. via render() or document.body.appendChild()) before calling showModal()."), 'InvalidStateError');
       }
       if (this.hasAttribute('open')) {
+        // No-op: already modal.
         if (this._isModal) {
-          return; // already modal - no-op
+          return;
         }
         throw new DOMException("Failed to execute 'showModal' on 'HTMLDialogElement': ".concat(describeElement({
           element: this
@@ -756,7 +758,7 @@ if (typeof HTMLDialogElement !== 'undefined') {
   }
   if (typeof proto.show !== 'function') {
     proto.show = function show() {
-      // Browser does not throw for disconnected elements on show - just no-op
+      // Browser does not throw for disconnected elements on show; no-op.
       if (!this.isConnected || this.hasAttribute('open')) {
         return;
       }
@@ -778,11 +780,12 @@ if (typeof HTMLDialogElement !== 'undefined') {
   }
   if (typeof proto.close !== 'function') {
     proto.close = function close(returnValue) {
+      // No-op: already closed.
       if (!this.hasAttribute('open')) {
-        return; // already closed - no-op
+        return;
       }
 
-      // Sync beforetoggle (not cancelable) - matches browser behavior
+      // Sync beforetoggle (not cancelable); matches browser behavior.
       fireToggleEvent({
         element: this,
         type: 'beforetoggle',

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

@@ -8,7 +8,9 @@ var _react = require("react");
 var _bindEventListener = require("bind-event-listener");
 var _browserApis = require("@atlaskit/browser-apis");
 var _keycodes = require("@atlaskit/ds-lib/keycodes");
-var _focus = require("../focus");
+var _getFirstFocusable2 = require("../focus/get-first-focusable");
+var _getLastFocusable2 = require("../focus/get-last-focusable");
+var _getNextFocusable3 = require("../focus/get-next-focusable");
 var menuScope = '[role="menu"]';
 
 /**
@@ -96,7 +98,7 @@ function useArrowNavigation(_ref) {
       var _getNextFocusable;
       // Prevent page scroll while navigating menu items.
       event.preventDefault();
-      (_getNextFocusable = (0, _focus.getNextFocusable)({
+      (_getNextFocusable = (0, _getNextFocusable3.getNextFocusable)({
         container: container,
         direction: 'forwards',
         filter: filter
@@ -107,7 +109,7 @@ function useArrowNavigation(_ref) {
       var _getNextFocusable2;
       // Prevent page scroll while navigating menu items.
       event.preventDefault();
-      (_getNextFocusable2 = (0, _focus.getNextFocusable)({
+      (_getNextFocusable2 = (0, _getNextFocusable3.getNextFocusable)({
         container: container,
         direction: 'backwards',
         filter: filter
@@ -118,7 +120,7 @@ function useArrowNavigation(_ref) {
       var _getFirstFocusable;
       // Prevent browser default (e.g. scrolling to top of page).
       event.preventDefault();
-      (_getFirstFocusable = (0, _focus.getFirstFocusable)({
+      (_getFirstFocusable = (0, _getFirstFocusable2.getFirstFocusable)({
         container: container,
         filter: filter
       })) === null || _getFirstFocusable === void 0 || _getFirstFocusable.focus();
@@ -128,7 +130,7 @@ function useArrowNavigation(_ref) {
       var _getLastFocusable;
       // Prevent browser default (e.g. scrolling to bottom of page).
       event.preventDefault();
-      (_getLastFocusable = (0, _focus.getLastFocusable)({
+      (_getLastFocusable = (0, _getLastFocusable2.getLastFocusable)({
         container: container,
         filter: filter
       })) === null || _getLastFocusable === void 0 || _getLastFocusable.focus();

package/dist/es2019/animations/presets.js

@@ -100,10 +100,10 @@ const SLIDE_AND_FADE_CSS = `
  * import { slideAndFade } from '@atlaskit/top-layer/animations';
  *
  * // Default 4px slide (tooltip)
- * <Popup.Content animate={slideAndFade()} />
+ * <Popover animate={slideAndFade()} />
  *
  * // Custom 8px slide (popup / dropdown)
- * <Popup.Content animate={slideAndFade({ distance: 8 })} />
+ * <Popover animate={slideAndFade({ distance: 8 })} />
  * ```
  */
 export function slideAndFade(options) {
@@ -162,7 +162,7 @@ const FADE_CSS = `
  * ```tsx
  * import { fade } from '@atlaskit/top-layer/animations';
  *
- * <Popup.Content animate={fade()} />
+ * <Popover animate={fade()} />
  * ```
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
@@ -218,7 +218,7 @@ const SCALE_AND_FADE_CSS = `
  * ```tsx
  * import { scaleAndFade } from '@atlaskit/top-layer/animations';
  *
- * <Popup.Content animate={scaleAndFade()} />
+ * <Popover animate={scaleAndFade()} />
  * ```
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports

package/dist/es2019/entry-points/focus.js

@@ -1 +1,3 @@
-export { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus';
+export { getFirstFocusable } from '../focus/get-first-focusable';
+export { getLastFocusable } from '../focus/get-last-focusable';
+export { getNextFocusable } from '../focus/get-next-focusable';

package/dist/es2019/entry-points/get-aria-for-trigger.js

@@ -0,0 +1 @@
+export { getAriaForTrigger } from '../internal/get-aria-for-trigger';

package/dist/es2019/entry-points/popover-surface.js

@@ -0,0 +1 @@
+export { PopoverSurface } from '../popover-surface';

package/dist/es2019/entry-points/use-anchor-position-at-point.js

@@ -0,0 +1 @@
+export { useAnchorPositionAtPoint } from '../internal/use-anchor-position-at-point';

package/dist/es2019/entry-points/use-popover-id.js

@@ -0,0 +1,15 @@
+import { useId } from '@atlaskit/ds-lib/use-id';
+/**
+ * Returns a stable HTML `id` used to wire a trigger element to its popover
+ * via ARIA (`aria-controls`) and the Popover API (`popovertarget`).
+ *
+ * The returned value is intended for the `id` attribute on the popover and
+ * for the matching `aria-controls` / `popovertarget` references on the
+ * trigger. It is NOT a CSS `anchor-name` value: CSS anchor positioning is
+ * handled internally by `useAnchorPosition`, which mints and applies its
+ * own `anchor-name` on the trigger element.
+ */
+export function usePopoverId() {
+  // prefixing for debug clarity in the DOM
+  return `popover-${useId()}`;
+}

package/dist/es2019/focus/get-first-focusable.js

@@ -0,0 +1,14 @@
+import { getFocusables } from './get-focusables';
+/**
+ * Returns the first focusable element within the container.
+ */
+export function getFirstFocusable({
+  container,
+  filter
+}) {
+  const items = getFocusables({
+    container,
+    filter
+  });
+  return items.length > 0 ? items[0] : null;
+}

package/dist/es2019/focus/get-focusables.js

@@ -0,0 +1,19 @@
+import { isInSameLayer } from './is-in-same-layer';
+import { selectors } from './selectors';
+/**
+ * Returns all focusable HTMLElements within the container, optionally filtered.
+ *
+ * Focusables that belong to a nested top-layer scope (a `[popover]` or
+ * `<dialog>` descendant of the container) are excluded - those elements
+ * are owned by the inner layer's focus management. The container itself
+ * is allowed to be a popover/dialog; only nested ones are filtered.
+ */
+export function getFocusables({
+  container,
+  filter
+}) {
+  return Array.from(container.querySelectorAll(selectors.focusable)).filter(element => element instanceof HTMLElement).filter(element => isInSameLayer({
+    element,
+    container
+  })).filter(element => !filter || filter(element, container));
+}

package/dist/es2019/focus/get-last-focusable.js

@@ -0,0 +1,14 @@
+import { getFocusables } from './get-focusables';
+/**
+ * Returns the last focusable element within the container.
+ */
+export function getLastFocusable({
+  container,
+  filter
+}) {
+  const items = getFocusables({
+    container,
+    filter
+  });
+  return items.length > 0 ? items[items.length - 1] : null;
+}

package/dist/es2019/focus/get-next-focusable.js

@@ -0,0 +1,38 @@
+/**
+ * Returns the next focusable element in the given direction relative to the
+ * currently focused element within the container. Wraps around at both ends.
+ *
+ * Returns `null` if there is no focused element within the container or if
+ * the focused element is not in the list of focusable elements.
+ */
+
+import { getFocusables } from './get-focusables';
+import { selectors } from './selectors';
+export function getNextFocusable({
+  container,
+  direction,
+  filter
+}) {
+  var _all$nextIndex;
+  const all = getFocusables({
+    container,
+    filter
+  });
+  const current = container.querySelector(selectors.focused);
+  if (!(current instanceof HTMLElement)) {
+    return null;
+  }
+  const index = all.indexOf(current);
+  if (index === -1) {
+    return null;
+  }
+  const nextIndex = (() => {
+    if (direction === 'forwards') {
+      return (index + 1) % all.length;
+    }
+    const proposed = index - 1;
+    // if going into negative numbers, loop back to the last item
+    return proposed < 0 ? all.length - 1 : proposed;
+  })();
+  return (_all$nextIndex = all[nextIndex]) !== null && _all$nextIndex !== void 0 ? _all$nextIndex : null;
+}

package/dist/es2019/focus/is-in-same-layer.js

@@ -0,0 +1,18 @@
+const topLayerSelector = '[popover], dialog, [role="dialog"], [role="alertdialog"]';
+
+/**
+ * Returns true when `element` and `container` resolve to the same nearest
+ * top-layer host (or both resolve to `null`, meaning the document layer).
+ */
+export function isInSameLayer({
+  element,
+  container
+}) {
+  const elementLayer = element.closest(topLayerSelector);
+  const containerLayer = container.closest(topLayerSelector);
+  // Both elements are in the "document" layer
+  if (!elementLayer && !containerLayer) {
+    return true;
+  }
+  return elementLayer === containerLayer;
+}

package/dist/es2019/focus/is-nested-layer-focused.js

@@ -0,0 +1,28 @@
+import { getDocument } from '@atlaskit/browser-apis';
+import { isInSameLayer } from './is-in-same-layer';
+
+/**
+ * Returns `true` when `document.activeElement` is inside a nested top-layer
+ * descendant of `container` (a `[popover]`, `<dialog>`, `[role="dialog"]` or
+ * `[role="alertdialog"]` that is itself a descendant of `container`).
+ */
+export function isNestedLayerFocused({
+  container
+}) {
+  var _getDocument;
+  const focused = (_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.activeElement;
+  if (!(focused instanceof HTMLElement)) {
+    return false;
+  }
+
+  // Cannot be in a nested layer if it is not in the container
+  if (!container.contains(focused)) {
+    return false;
+  }
+
+  // If not in the same layer, must be in a nested layer
+  return !isInSameLayer({
+    element: focused,
+    container
+  });
+}