@atlaskit/top-layer 0.13.0 → 0.15.0

package/dist/es2019/internal/use-anchor-position.js

@@ -28,13 +28,13 @@ import { setStyle } from './set-style';
 // from `./resolve-placement` so search-and-jump lands at the source of truth.
 
 /**
- * Module-scope no-op `ResizeObserver` stub used in non-DOM jest environments where
+ * Module-scope no-op `ResizeObserver` used in non-DOM jest environments where
  * `ResizeObserver` is `undefined`. Hoisted out of the effect to avoid
- * re-allocating on every run.
+ * allocating a new class declaration on every run.
  */
-const noopResizeObserver = {
-  observe() {},
-  unobserve() {},
+const NoopResizeObserver = class {
+  observe() {}
+  unobserve() {}
   disconnect() {}
 };
 
@@ -197,6 +197,7 @@ function useStablePlacement(placement) {
  * comparison is used internally so re-runs are skipped when the resolved
  * placement shape is unchanged.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function useAnchorPosition({
   anchorRef,
   popoverRef,
@@ -402,17 +403,20 @@ export function useAnchorPosition({
     // Self-disconnects after one valid measurement; ongoing
     // scroll/resize is handled by the window listeners below.
     // `ResizeObserver` is missing in some non-DOM jest environments
-    // (e.g. post-office's `node` environment). Fall back to the
-    // module-scope `noopResizeObserver` stub there. The scroll/resize
-    // listeners below still keep the popover positioned in the rare
-    // case the consumer also polyfilled `showPopover` but not
-    // `ResizeObserver`. Real browsers always have it.
-    const resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(() => {
+    // (e.g. post-office's `node` environment). Fall back to a no-op
+    // observer there. The scroll/resize listeners below still keep
+    // the popover positioned in the rare case the consumer also
+    // polyfilled `showPopover` but not `ResizeObserver`. Real
+    // browsers always have it. The `NoopResizeObserver` class is
+    // hoisted to module scope (see top of file) so we do not allocate
+    // a new constructor on every effect run.
+    const ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
+    const resizeObserver = new ResizeObserverImpl(() => {
       if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
         update();
         resizeObserver.disconnect();
       }
-    }) : noopResizeObserver;
+    });
 
     // If the popover is already open by the time this effect runs (for
     // example, the parent `useAnchorPosition` effect runs after the child

package/dist/es2019/popover/create-close-event.js

@@ -12,8 +12,7 @@
  *
  * @example
  * ```tsx
- * import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
- * import { type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
+ * import { createPopoverCloseEvent, type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
  *
  * function onPopoverClose({ reason }: { reason: TPopoverCloseReason }) {
  *   legacyOnClose(createPopoverCloseEvent({ reason }));

package/dist/es2019/popover/popover.js

@@ -7,13 +7,12 @@ import { bind } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import once from '@atlaskit/ds-lib/once';
 import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
+import { shouldFocusIntoPopover } from '../internal/role-types';
 import { useAnimatedVisibility } from '../internal/use-animated-visibility';
 import { useFocusWrap } from '../internal/use-focus-wrap';
 import { useInitialFocus } from '../internal/use-initial-focus';
 /**
- * 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.
  */
 const supportsPopoverHint = once(() => {
   if (typeof document === 'undefined') {
@@ -30,33 +29,20 @@ 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.
+ * Roles registered with the open layer observer as `popup`, so `closeLayers()`
+ * dismisses them. `modal` comes from Dialog only; other layer types are unused.
  */
 const 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`.
  */
 export const Popover = /*#__PURE__*/forwardRef(function Popover({
   children,
@@ -79,11 +65,9 @@ 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
-  // 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).
   const popoverId = idProp !== null && idProp !== void 0 ? idProp : `popover-${autoId.replace(/:/g, '')}`;
   const {
     showChildren,
@@ -96,12 +80,10 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     onExitFinish
   });
 
-  // 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
   useFocusWrap({
     elementRef: ownRef,
     role
@@ -112,13 +94,9 @@ 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.
+  // 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.
   const handleObserverClose = useCallback(() => {
     onClose === null || onClose === void 0 ? void 0 : onClose({
       reason: 'programmatic'
@@ -130,25 +108,29 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     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.
   const 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.
   const programmaticCloseRef = 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.
   const closeReasonRef = useRef('light-dismiss');
+
+  // Snapshot of pre-open focus, used to restore focus for nested popovers
+  // with focus-capturing roles (browser only restores the outermost).
+  const previouslyFocusedElementRef = useRef(null);
+  const handleBeforeToggle = useCallback(event => {
+    if (event.newState !== 'open') {
+      return;
+    }
+    // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- need active element snapshot
+    const active = document.activeElement;
+    previouslyFocusedElementRef.current = active instanceof HTMLElement ? active : null;
+  }, []);
   const handleToggle = useCallback(event => {
     const element = ownRef.current;
     if (event.newState === 'open') {
@@ -166,32 +148,52 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
           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`).
+        const previouslyFocused = previouslyFocusedElementRef.current;
+        const reason = closeReasonRef.current;
+        const isProgrammatic = programmaticCloseRef.current;
+        const shouldRestore = previouslyFocused !== null && previouslyFocused.isConnected && shouldFocusIntoPopover({
+          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).
       const 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 ? void 0 : onClose({
         reason
       });
     }
-  }, [onClose, onOpenChange]);
+  }, [onClose, onOpenChange, role]);
   useEffect(() => {
     const element = ownRef.current;
     if (!element) {
       return;
     }
 
-    // Capture-phase: tag Escape before the browser processes light dismiss.
+    // Tag Escape before the browser processes light dismiss.
     const unbindEscape = bind(element, {
       type: 'keydown',
       listener: event => {
@@ -207,15 +209,20 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
       type: 'toggle',
       listener: handleToggle
     });
+    // Snapshot `document.activeElement` before `useInitialFocus` moves it.
+    const unbindBeforeToggle = bind(element, {
+      type: 'beforetoggle',
+      listener: handleBeforeToggle
+    });
     return () => {
       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.
   useLayoutEffect(() => {
     const el = ownRef.current;
     if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
@@ -229,14 +236,9 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     });
   }, [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).
   useLayoutEffect(() => {
     const el = ownRef.current;
     if (!el) {
@@ -244,20 +246,17 @@ export const Popover = /*#__PURE__*/forwardRef(function Popover({
     }
     if (isOpen) {
       programmaticCloseRef.current = false;
-      // Defensive: element may be disconnected or in an unexpected state.
       try {
         el.showPopover();
       } catch {}
       return () => {
         programmaticCloseRef.current = true;
-        // Defensive: element may be disconnected or in an unexpected state.
         try {
           el.hidePopover();
         } catch {}
       };
     }
     programmaticCloseRef.current = true;
-    // Defensive: element may be disconnected or in an unexpected state.
     try {
       el.hidePopover();
     } catch {}

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

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

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

@@ -0,0 +1,27 @@
+/* popover-surface.tsx generated by @compiled/babel-plugin v0.39.1 */
+import "./popover-surface.compiled.css";
+import { ax, ix } from "@compiled/react/runtime";
+import React from 'react';
+const styles = {
+  root: "_2rkofajl _1reo1wug _18m91wug _bfhk1bhr _16qs130s"
+};
+
+/**
+ * Optional styled wrapper for popover content.
+ *
+ * Adds default visual styling (background, border-radius, box-shadow)
+ * using design tokens.
+ *
+ * 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
+ * `Popover` instead. `PopoverSurface` is the no-config "give me the default
+ * ADS overlay look" surface, nothing more.
+ */
+export function PopoverSurface({
+  children
+}) {
+  return /*#__PURE__*/React.createElement("div", {
+    className: ax([styles.root])
+  }, children);
+}

package/dist/es2019/testing/polyfill.js

@@ -107,7 +107,7 @@ function createToggleScheduler() {
       newState
     });
 
-    // Task queue (setTimeout) - browser fires toggle after microtasks drain, not during
+    // Task queue (setTimeout): browser fires toggle after microtasks drain, not during
     setTimeout(() => {
       const entry = pending.get(element);
       if (!entry) {
@@ -552,10 +552,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
@@ -745,8 +746,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': ${describeElement({
           element: this
@@ -770,7 +772,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;
       }
@@ -792,11 +794,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/esm/animations/presets.js

@@ -58,10 +58,10 @@ var SLIDE_AND_FADE_CSS = "\n[data-ds-popover-slide-and-fade] {\n  opacity: 0;\n
  * 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) {
@@ -95,7 +95,7 @@ var FADE_CSS = "\n[data-ds-popover-fade] {\n  opacity: 0;\n  transition:\n    op
  * ```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
@@ -121,7 +121,7 @@ var SCALE_AND_FADE_CSS = "\n[data-ds-popover-scale-and-fade] {\n  opacity: 0;\n
  * ```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/esm/dialog/create-close-event.js

@@ -10,8 +10,7 @@
  *
  * @example
  * ```tsx
- * import { createCloseEvent } from '@atlaskit/top-layer/create-close-event';
- * import { type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
+ * import { createCloseEvent, type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
  *
  * function onDialogClose({ reason }: { reason: TDialogCloseReason }) {
  *   legacyOnClose(createCloseEvent({ reason }));

package/dist/esm/entry-points/dialog.js

@@ -1 +1 @@
-export { Dialog } from '../dialog';
+export { createCloseEvent, Dialog } from '../dialog';

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

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

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

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

package/dist/esm/entry-points/popover.js

@@ -1 +1 @@
-export { Popover } from '../popover';
+export { createPopoverCloseEvent, Popover } from '../popover';

package/dist/esm/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-".concat(useId());
+}

package/dist/esm/internal/get-aria-for-trigger.js

@@ -0,0 +1,83 @@
+import { roleToAriaHasPopup } from './role-to-aria-has-popup';
+
+/**
+ * Roles accepted by `getAriaForTrigger`.
+ *
+ * Excludes tooltip-family roles (`tooltip`, `note`, `status`, `alert`, `log`)
+ * because the correct trigger wiring for those is `aria-describedby`, not
+ * `aria-haspopup` / `aria-expanded` / `aria-controls`. Use `aria-describedby`
+ * manually for tooltip triggers.
+ */
+
+/**
+ * Non-undefined subset of `TAriaHasPopupValue`. Every role accepted by
+ * `getAriaForTrigger` maps to a concrete `aria-haspopup` string, so the
+ * trigger always receives a defined attribute value.
+ */
+
+/**
+ * Returns the ARIA attributes to spread onto a click-activated popover trigger.
+ *
+ * Centralises three attributes that are easy to forget or get wrong individually:
+ *
+ * - `aria-haspopup` - derived from the popover's role (e.g. `dialog → "dialog"`,
+ *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
+ *   the value is `undefined`.
+ * - `aria-expanded` - reflects the current open state.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
+ *
+ * **This function is for click/keyboard-activated popovers only.** For
+ * hover-driven tooltips, the trigger should use `aria-describedby` instead.
+ *
+ * @example
+ * ```tsx
+ * import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
+ * import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
+ *
+ * const popoverId = usePopoverId();
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * return (
+ *   <>
+ *     <button
+ *       ref={triggerRef}
+ *       onClick={() => setIsOpen((previous) => !previous)}
+ *       {...getAriaForTrigger({ role: 'dialog', isOpen, popoverId })}
+ *     >
+ *       Open
+ *     </button>
+ *     <Popover
+ *       id={popoverId}
+ *       role="dialog"
+ *       label="My dialog"
+ *       isOpen={isOpen}
+ *       triggerRef={triggerRef}
+ *       onClose={() => setIsOpen(false)}
+ *     >
+ *       …
+ *     </Popover>
+ *   </>
+ * );
+ * ```
+ */
+export function getAriaForTrigger(_ref) {
+  var role = _ref.role,
+    isOpen = _ref.isOpen,
+    popoverId = _ref.popoverId;
+  // `roleToAriaHasPopup` accepts a wider role union (including tooltip-family
+  // roles that map to `undefined`). `TAriaForTriggerRole` excludes those, so
+  // the returned value is guaranteed to be a defined string. The cast narrows
+  // the wider helper signature to match.
+  var ariaHasPopup = roleToAriaHasPopup({
+    role: role
+  });
+  return {
+    'aria-haspopup': ariaHasPopup,
+    'aria-expanded': isOpen,
+    // Keep the trigger-to-popover relationship stable. `aria-expanded`
+    // tells assistive technology whether the controlled popover is visible.
+    'aria-controls': popoverId
+  };
+}

package/dist/esm/internal/role-types.js

@@ -0,0 +1,58 @@
+/**
+ * Valid values for the `aria-haspopup` attribute.
+ *
+ * Derived from the HTML spec - maps popover roles to what the trigger
+ * announces. `undefined` means the attribute is omitted entirely (used for
+ * non-popup roles like `tooltip`/`status`/`alert`/`note`/`log` where
+ * `aria-haspopup` would be misleading).
+ *
+ * `true` is intentionally NOT in the union - the runtime only ever produces
+ * the explicit string forms, so widening the type would invite consumers to
+ * pass `true` and get an `aria-haspopup="true"` serialisation that the
+ * runtime no longer emits.
+ */
+
+/**
+ * Roles that require an accessible name (`label` or `labelledBy`) per WCAG 4.1.2.
+ * Without a name, assistive technology cannot identify these landmarks.
+ */
+
+/**
+ * Roles where the accessible name is derived from content or provided externally
+ * (e.g. a combobox labels its listbox, tooltip content IS the accessible name).
+ */
+
+// Shared ARIA role discrimination types
+//
+// These encode the WCAG 4.1.2 constraint: roles like `dialog`, `alertdialog`,
+// and `menu` MUST have an accessible name (either `label` or `labelledBy`).
+// TypeScript enforces this at compile time via discriminated unions.
+
+/**
+ * ARIA role props where a role is always required.
+ *
+ * Used by `TPopupContentProps`. Popup content must always declare
+ * its role so assistive technology can identify the layer.
+ */
+
+/**
+ * ARIA role props where a role is optional.
+ *
+ * Used by `TPopoverProps`. The low-level primitive allows omitting
+ * the role for cases where it is set externally or not needed.
+ */
+
+var rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
+
+/**
+ * Returns `true` when the given popover role moves focus into the popover
+ * on open, and `false` otherwise (including when `role` is `undefined`).
+ */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function shouldFocusIntoPopover(_ref) {
+  var role = _ref.role;
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
+}