@atlaskit/top-layer 0.9.0 → 0.10.0

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

@@ -7,16 +7,16 @@ const 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 @@ const 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 @@ const menuScope = '[role="menu"]';
 export function isAtCurrentMenuLevel(element, container) {
   const 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.
   let 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.
  *
@@ -215,7 +231,7 @@ export function useArrowNavigation({
       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.
         const isNested = ((_container$parentElem = container.parentElement) === null || _container$parentElem === void 0 ? void 0 : _container$parentElem.closest(menuScope)) !== null;
         if (isNested) {

package/dist/esm/animations/presets.js

@@ -1,4 +1,4 @@
-import { getPlacement } from '../internal/use-anchor-position';
+import { getPlacement } from '../internal/resolve-placement';
 
 // ── slideAndFade ──
 
@@ -159,8 +159,10 @@ var DIALOG_SLIDE_UP_AND_FADE_CSS = "\n[data-ds-dialog-slide-up-and-fade] {\n  op
 export function dialogSlideUpAndFade(options) {
   var _options$distance2;
   var distance = (_options$distance2 = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance2 !== void 0 ? _options$distance2 : 12;
+
+  // Bare preset name; `Dialog` prefixes it via `data-ds-dialog-{name}`.
   return {
-    name: distance === 12 ? 'dialog-slide-up-and-fade' : "dialog-slide-up-and-fade-".concat(distance),
+    name: distance === 12 ? 'slide-up-and-fade' : "slide-up-and-fade-".concat(distance),
     css: distance === 12 ? DIALOG_SLIDE_UP_AND_FADE_CSS : DIALOG_SLIDE_UP_AND_FADE_CSS.replace(/12px/g, "".concat(distance, "px")),
     exitDurationMs: 175
   };
@@ -186,8 +188,9 @@ var DIALOG_FADE_CSS = "\n[data-ds-dialog-fade] {\n  opacity: 0;\n  transition:\n
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function dialogFade() {
+  // Bare preset name; `Dialog` prefixes it via `data-ds-dialog-{name}`.
   return {
-    name: 'dialog-fade',
+    name: 'fade',
     css: DIALOG_FADE_CSS,
     exitDurationMs: 175
   };

package/dist/esm/arrow/index.js

@@ -0,0 +1,124 @@
+import once from '@atlaskit/ds-lib/once';
+import { getPlacement } from '../internal/resolve-placement';
+import { placementToPositionArea } from '../internal/use-anchor-position';
+/**
+ * CSS for popover arrows using the `clip-path: inset() margin-box` technique.
+ *
+ * How it works:
+ * 1. Four arrow shapes exist simultaneously as `::before` (top/bottom) and
+ *    `::after` (left/right) hexagonal pseudo-elements.
+ * 2. `clip-path: inset(0) margin-box` clips the popover to its margin-box.
+ * 3. Margin on the anchor-facing side pushes the popover away, creating space
+ *    where one arrow "escapes" the clip boundary and becomes visible.
+ * 4. `@position-try` rules change both `position-area` and `margin` when
+ *    flipping, ensuring the correct arrow is always shown.
+ *
+ * Constraints:
+ * - `box-shadow` must be `none` (interferes with `clip-path: inset() margin-box`)
+ * - `::before` and `::after` are consumed - consumers cannot use them
+ * - Arrow pseudo-elements use `background: inherit` from the popover element
+ *
+ * @see https://goulet.dev/posts/tooltip-with-popover-and-anchor-positioning/
+ */
+var ARROW_CSS = "\n[data-ds-popover-arrow] {\n  clip-path: inset(var(--ds-arrow-offset, 0px)) margin-box;\n  box-shadow: none;\n}\n\n/* Top and Bottom arrows (vertical hexagon) */\n[data-ds-popover-arrow]::before {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  left: 50%;\n  transform: translateX(-50%);\n  width: calc(var(--ds-arrow-size, 8px) * 2);\n  height: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  top: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    0 var(--ds-arrow-size, 8px),\n    50% 0,\n    100% var(--ds-arrow-size, 8px),\n    100% calc(100% - var(--ds-arrow-size, 8px)),\n    50% 100%,\n    0 calc(100% - var(--ds-arrow-size, 8px))\n  );\n}\n\n/* Left and Right arrows (horizontal hexagon) */\n[data-ds-popover-arrow]::after {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  top: 50%;\n  transform: translateY(-50%);\n  height: calc(var(--ds-arrow-size, 8px) * 2);\n  width: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  left: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    var(--ds-arrow-size, 8px) 0,\n    calc(100% - var(--ds-arrow-size, 8px)) 0,\n    100% 50%,\n    calc(100% - var(--ds-arrow-size, 8px)) 100%,\n    var(--ds-arrow-size, 8px) 100%,\n    0 50%\n  );\n}\n\n/* \u2500\u2500 @position-try rules \u2500\u2500\n * One rule per possible position-area value.\n * Each sets the position-area and the correct margin direction\n * so the arrow on the anchor-facing side is revealed.\n *\n * Margin direction per edge:\n *   block-start  (above anchor) \u2192 margin-block-end   (bottom, facing anchor)\n *   block-end    (below anchor) \u2192 margin-block-start  (top, facing anchor)\n *   inline-start (left of anchor) \u2192 margin-inline-end (right, facing anchor)\n *   inline-end   (right of anchor) \u2192 margin-inline-start (left, facing anchor)\n */\n\n/* Each rule sets two margins: the anchor-facing margin for the gap\n   (via --ds-arrow-size) and one cross-axis margin for the shift\n   (via one of --ds-cross-axis-shift-margin-start, --ds-cross-axis-shift-margin-end,\n   --ds-cross-axis-shift-margin-block-start, or --ds-cross-axis-shift-margin-block-end). The\n   side matches the popover's anchored cross-axis edge per align. Only\n   one of the four properties is non-zero at a time; useAnchorPosition\n   picks it. See notes/architecture/positioning.md for details. */\n/* Single-axis centered (align: center) */\n@position-try --ds-arrow-block-start {\n  position-area: block-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n@position-try --ds-arrow-block-end {\n  position-area: block-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n@position-try --ds-arrow-inline-start {\n  position-area: inline-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n@position-try --ds-arrow-inline-end {\n  position-area: inline-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n\n/* Block edge + inline span (align: start uses span-inline-end; align: end uses span-inline-start) */\n@position-try --ds-arrow-block-start-span-inline-start {\n  position-area: block-start span-inline-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);\n}\n@position-try --ds-arrow-block-start-span-inline-end {\n  position-area: block-start span-inline-end;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n@position-try --ds-arrow-block-end-span-inline-start {\n  position-area: block-end span-inline-start;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);\n}\n@position-try --ds-arrow-block-end-span-inline-end {\n  position-area: block-end span-inline-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);\n}\n\n/* Inline edge + block span (align: start uses span-block-end; align: end uses span-block-start) */\n@position-try --ds-arrow-inline-start-span-block-start {\n  position-area: inline-start span-block-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);\n}\n@position-try --ds-arrow-inline-start-span-block-end {\n  position-area: inline-start span-block-end;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n@position-try --ds-arrow-inline-end-span-block-start {\n  position-area: inline-end span-block-start;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);\n}\n@position-try --ds-arrow-inline-end-span-block-end {\n  position-area: inline-end span-block-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);\n}\n";
+
+// ── Placement utilities ──
+
+/**
+ * Converts a `position-area` value to a CSS rule name by replacing spaces with hyphens
+ * and prepending `--ds-arrow-`.
+ *
+ * @example positionAreaToRuleName('block-end span-inline-start') → '--ds-arrow-block-end-span-inline-start'
+ */
+function positionAreaToRuleName(_ref) {
+  var positionArea = _ref.positionArea;
+  return "--ds-arrow-".concat(positionArea.replace(/ /g, '-'));
+}
+
+/**
+ * Returns `position-try-fallbacks` using named `@position-try` rules
+ * that change both `position-area` and `margin` when flipping.
+ *
+ * This is required for the arrow technique because built-in keywords
+ * (`flip-block`, `flip-inline`) only flip `position-area` - they do
+ * not update the margin direction needed to reveal the correct arrow.
+ */
+function getTryFallbacks(_ref2) {
+  var placement = _ref2.placement;
+  var _getPlacement = getPlacement({
+      placement: placement
+    }),
+    axis = _getPlacement.axis,
+    edge = _getPlacement.edge,
+    align = _getPlacement.align;
+  if (align === 'center') {
+    // Single-axis: only flip the edge
+    var _flippedEdge = edge === 'start' ? 'end' : 'start';
+    return positionAreaToRuleName({
+      positionArea: placementToPositionArea({
+        placement: {
+          axis: axis,
+          edge: _flippedEdge
+        }
+      })
+    });
+  }
+
+  // Compound placement: try flipping edge, alignment, and both
+  var flippedEdge = edge === 'start' ? 'end' : 'start';
+  var flippedAlign = align === 'start' ? 'end' : 'start';
+  return [positionAreaToRuleName({
+    positionArea: placementToPositionArea({
+      placement: {
+        axis: axis,
+        edge: flippedEdge,
+        align: align
+      }
+    })
+  }), positionAreaToRuleName({
+    positionArea: placementToPositionArea({
+      placement: {
+        axis: axis,
+        edge: edge,
+        align: flippedAlign
+      }
+    })
+  }), positionAreaToRuleName({
+    positionArea: placementToPositionArea({
+      placement: {
+        axis: axis,
+        edge: flippedEdge,
+        align: flippedAlign
+      }
+    })
+  })].join(', ');
+}
+
+/**
+ * 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 var arrow = once(function () {
+  return {
+    name: 'arrow',
+    css: ARROW_CSS,
+    getTryFallbacks: getTryFallbacks
+  };
+});

package/dist/esm/arrow/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/dialog/dialog-content.js

@@ -16,7 +16,7 @@ var styles = {
 };
 
 /**
- * Low-level `<dialog>` primitive. No visual opinions — no width, height,
+ * Low-level `<dialog>` primitive. No visual opinions - no width, height,
  * background, border-radius, or layout. Consumers provide their own styling.
  *
  * Visibility is controlled declaratively via `isOpen`:
@@ -27,6 +27,10 @@ var styles = {
  *
  * Close flow: we never call `dialog.close()` from event handlers. We always call
  * `onClose`; the consumer decides whether to set `isOpen={false}`.
+ *
+ * Accessibility: render at least one focusable element (typically a close
+ * button) when `isOpen` becomes `true`. Tab is always trapped inside the
+ * dialog, so keyboard users need somewhere to land.
  */
 export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
   var children = _ref.children,
@@ -132,18 +136,19 @@ export var Dialog = /*#__PURE__*/forwardRef(function Dialog(_ref, ref) {
   return /*#__PURE__*/React.createElement("dialog", _extends({
     ref: combinedRef,
     id: dialogId
-    // Modern browsers infer modal semantics from `.showModal()` but
-    // some assistive tech still keys off `aria-modal="true"`. Setting
-    // it explicitly is recommended by WAI-ARIA APG dialog pattern.
+    // `aria-modal` is intentionally NOT set: native `<dialog>.showModal()`
+    // already conveys modal semantics to assistive tech, and double-
+    // declaring it forecloses non-modal use cases (consumers calling
+    // `.show()` would still appear modal). Modern AT (NVDA / JAWS /
+    // VoiceOver) infer modality from the platform accessibility API.
     ,
-    "aria-modal": "true",
     "aria-label": label,
     "aria-labelledby": label ? undefined : labelledBy,
     // eslint-disable-next-line @atlaskit/ui-styling-standard/enforce-style-prop
     style: style,
     onCancel: handleCancel,
     "data-testid": testId
-  }, preset ? _defineProperty({}, "data-ds-".concat(preset.name), '') : undefined, {
+  }, preset ? _defineProperty({}, "data-ds-dialog-".concat(preset.name), '') : undefined, {
     className: ax([styles.dialog])
   }), shouldHideBackdrop &&
   /*#__PURE__*/

package/dist/esm/entry-points/create-close-event.js

@@ -1,2 +1,9 @@
+/**
+ * @deprecated Combined entry-point retained for backwards-compatibility.
+ * Prefer the disjoint subpaths so that bundle analysis attributes the cost
+ * to the right consumer:
+ *   - `@atlaskit/top-layer/dialog/create-close-event` for `createCloseEvent`
+ *   - `@atlaskit/top-layer/popover/create-close-event` for `createPopoverCloseEvent`
+ */
 export { createCloseEvent } from '../dialog';
 export { createPopoverCloseEvent } from '../popover/create-close-event';

package/dist/esm/entry-points/dialog/create-close-event.js

@@ -0,0 +1 @@
+export { createCloseEvent } from '../../dialog/create-close-event';

package/dist/esm/entry-points/placement-map.js

@@ -1 +1,2 @@
-export { fromLegacyPlacement, placementMapping } from '../placement-map';
+export { fromLegacyPlacement } from '../placement-map';
+export { LEGACY_PLACEMENTS } from '../placement-map/legacy-placements';

package/dist/esm/entry-points/popover/create-close-event.js

@@ -0,0 +1 @@
+export { createPopoverCloseEvent } from '../../popover/create-close-event';

package/dist/esm/focus/focus.js

@@ -10,6 +10,7 @@
  * restrict which focusable elements are included.
  */
 
+import { getDocument } from '@atlaskit/browser-apis';
 var selectors = function () {
   // Common exclusion filter applied to every selector.
   var not = ':not([tabindex="-1"]):not([aria-disabled="true"]):not([aria-hidden="true"])';
@@ -17,9 +18,54 @@ var selectors = function () {
   var focusable = ["a[href]".concat(not), "area[href]".concat(not), "input".concat(notDisabled, ":not([type=\"hidden\"])"), "select".concat(notDisabled), "textarea".concat(notDisabled), "button".concat(notDisabled), "iframe".concat(not), "audio[controls]".concat(not), "video[controls]".concat(not), "[contenteditable]:not([contenteditable=\"false\"])".concat(not), "[tabindex]".concat(notDisabled).concat(not)];
   return {
     focusable: focusable.join(','),
-    focused: focusable.join(':focus,') + ':focus'
+    // Build the `:focus` selector
+    focused: focusable.map(function (selector) {
+      return "".concat(selector, ":focus");
+    }).join(',')
   };
 }();
+var 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).
+ */
+function isInSameLayer(_ref) {
+  var element = _ref.element,
+    container = _ref.container;
+  var elementLayer = element.closest(topLayerSelector);
+  var containerLayer = container.closest(topLayerSelector);
+  // Both elements are in the "document" layer
+  if (!elementLayer && !containerLayer) {
+    return true;
+  }
+  return elementLayer === containerLayer;
+}
+
+/**
+ * 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(_ref2) {
+  var _getDocument;
+  var container = _ref2.container;
+  var 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: container
+  });
+}
 
 /**
  * An optional callback to restrict which focusable elements are included.
@@ -29,17 +75,21 @@ var selectors = function () {
 /**
  * Returns all focusable HTMLElements within the container, optionally filtered.
  *
- * Note: this searches the full subtree and does not stop at nested
- * popover/dialog boundaries. In practice this is fine because nested
- * popovers are not rendered until they are opened, so their content
- * is not in the DOM when the parent's initial focus runs. If that
- * assumption changes, this would need to be scoped to the current layer.
+ * 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.
  */
-function getFocusables(_ref) {
-  var container = _ref.container,
-    filter = _ref.filter;
+function getFocusables(_ref3) {
+  var container = _ref3.container,
+    filter = _ref3.filter;
   return Array.from(container.querySelectorAll(selectors.focusable)).filter(function (element) {
     return element instanceof HTMLElement;
+  }).filter(function (element) {
+    return isInSameLayer({
+      element: element,
+      container: container
+    });
   }).filter(function (element) {
     return !filter || filter(element, container);
   });
@@ -48,9 +98,10 @@ function getFocusables(_ref) {
 /**
  * Returns the first focusable element within the container.
  */
-export function getFirstFocusable(_ref2) {
-  var container = _ref2.container,
-    filter = _ref2.filter;
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
+export function getFirstFocusable(_ref4) {
+  var container = _ref4.container,
+    filter = _ref4.filter;
   var items = getFocusables({
     container: container,
     filter: filter
@@ -62,9 +113,9 @@ export function getFirstFocusable(_ref2) {
  * Returns the last focusable element within the container.
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function getLastFocusable(_ref3) {
-  var container = _ref3.container,
-    filter = _ref3.filter;
+export function getLastFocusable(_ref5) {
+  var container = _ref5.container,
+    filter = _ref5.filter;
   var items = getFocusables({
     container: container,
     filter: filter
@@ -80,11 +131,11 @@ export function getLastFocusable(_ref3) {
  * the focused element is not in the list of focusable elements.
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function getNextFocusable(_ref4) {
+export function getNextFocusable(_ref6) {
   var _all$nextIndex;
-  var container = _ref4.container,
-    direction = _ref4.direction,
-    filter = _ref4.filter;
+  var container = _ref6.container,
+    direction = _ref6.direction,
+    filter = _ref6.filter;
   var all = getFocusables({
     container: container,
     filter: filter

package/dist/esm/index.js

@@ -1,7 +1,6 @@
 // This file exists for module resolution purposes.
 // Not exporting anything from the root entry point.
-// Please use individual entry points for minimum bundle size:
 //
-//   import { Popup } from '@atlaskit/top-layer/popup';
-//   import { Dialog } from '@atlaskit/top-layer/dialog';
-//   import { Popover } from '@atlaskit/top-layer/popover';
+// Use individual entry points for minimum bundle size - the full list of
+// available subpaths is the `"exports"` field in this package's
+// `package.json`. The README documents the most common ones.

package/dist/esm/internal/resolve-css-length-to-pixels.js

@@ -1,3 +1,32 @@
+var elementCaches = new WeakMap();
+function canCacheResolvedLength(value) {
+  // Custom-property values can be retargeted by inline overrides on the
+  // consumer's wrapper, so we cannot prove a cached pixel value is still valid.
+  return !value.includes('var(');
+}
+function getCachedResolvedLength(_ref) {
+  var _cacheForElement$get;
+  var element = _ref.element,
+    value = _ref.value;
+  if (!canCacheResolvedLength(value)) {
+    return null;
+  }
+  var cacheForElement = elementCaches.get(element);
+  return (_cacheForElement$get = cacheForElement === null || cacheForElement === void 0 ? void 0 : cacheForElement.get(value)) !== null && _cacheForElement$get !== void 0 ? _cacheForElement$get : null;
+}
+function cacheResolvedLength(_ref2) {
+  var _elementCaches$get;
+  var element = _ref2.element,
+    value = _ref2.value,
+    result = _ref2.result;
+  if (!canCacheResolvedLength(value)) {
+    return;
+  }
+  var cacheForElement = (_elementCaches$get = elementCaches.get(element)) !== null && _elementCaches$get !== void 0 ? _elementCaches$get : new Map();
+  cacheForElement.set(value, result);
+  elementCaches.set(element, cacheForElement);
+}
+
 /**
  * Resolves a CSS length value to a pixel number using a hidden DOM probe.
  *
@@ -8,27 +37,39 @@
  * the browser do the math.
  *
  * The probe is appended to `container` so it inherits the same containing
- * block, font size, and custom-property scope as the popover. We use `width`
- * because it accepts any CSS length, including negative `calc()` results
- * (negative widths are clamped to 0 — see note below).
+ * block, font size, and custom-property scope as the popover.
  *
- * Cost: one synchronous reflow per call. The fallback only resolves on
- * placement/offset changes, not on every scroll/resize update, so this is
- * not a hot path.
+ * Cost: one synchronous reflow on first cacheable resolution per
+ * (container, value) pair, then a `WeakMap` lookup. Resolutions involving
+ * `var(` are intentionally not cached.
  */
-export function resolveCssLengthToPixels(_ref) {
-  var value = _ref.value,
-    container = _ref.container;
+export function resolveCssLengthToPixels(_ref3) {
+  var value = _ref3.value,
+    container = _ref3.container;
   if (typeof value === 'number') {
     return value;
   }
 
+  // Fast path: unitless zero is universally zero pixels - accept `'0'` and
+  // `'-0'` without a probe. (Consumers occasionally pass `'0'` instead of
+  // the number `0`.)
+  if (value === '0' || value === '-0') {
+    return 0;
+  }
+
   // Fast path: bare `${n}px` strings come from the consumer normalisation
   // in `getPlacement`. Avoid a reflow when we can.
   var pxMatch = value.match(/^(-?\d+(?:\.\d+)?)px$/);
   if (pxMatch) {
     return Number(pxMatch[1]);
   }
+  var cached = getCachedResolvedLength({
+    element: container,
+    value: value
+  });
+  if (cached !== null) {
+    return cached;
+  }
   var probe = container.ownerDocument.createElement('div');
   probe.style.position = 'absolute';
   probe.style.visibility = 'hidden';
@@ -40,8 +81,18 @@ export function resolveCssLengthToPixels(_ref) {
   // preserved. `getComputedStyle` returns the resolved pixel value for
   // margin-* properties even when the source was a token / calc / var.
   probe.style.marginLeft = value;
+  // Hide the probe from assistive tech and event targeting; defensive
+  // against `getElementsByTagName('div')` walks in consumer code.
+  probe.setAttribute('aria-hidden', 'true');
+  probe.setAttribute('inert', '');
   container.appendChild(probe);
   var resolved = parseFloat(getComputedStyle(probe).marginLeft);
   container.removeChild(probe);
-  return Number.isFinite(resolved) ? resolved : 0;
+  var result = Number.isFinite(resolved) ? resolved : 0;
+  cacheResolvedLength({
+    element: container,
+    value: value,
+    result: result
+  });
+  return result;
 }

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

@@ -1,6 +1,15 @@
 /**
  * Valid values for the `aria-haspopup` attribute.
- * Derived from the HTML spec — maps popover roles to what the trigger announces.
+ *
+ * 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.
  */
 
 /**
@@ -22,21 +31,27 @@
 /**
  * ARIA role props where a role is always required.
  *
- * Used by `TPopupContentProps` — popup content must always declare
+ * 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
+ * Used by `TPopoverProps`. The low-level primitive allows omitting
  * the role for cases where it is set externally or not needed.
  */
 
 /**
  * Maps a popover content role to the correct `aria-haspopup` value
  * for its trigger element.
+ *
+ * Returns `undefined` for roles that are not popups in the ARIA sense
+ * (`tooltip`, `note`, `status`, `alert`, `log`). Triggers for those roles
+ * should not announce a popup at all - emitting `aria-haspopup="dialog"`
+ * on a tooltip trigger would mislead assistive technology.
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function roleToAriaHasPopup(_ref) {
   var role = _ref.role;
   if (role === 'menu') {
@@ -51,10 +66,25 @@ export function roleToAriaHasPopup(_ref) {
   if (role === 'grid') {
     return 'grid';
   }
-  // Default: return 'dialog' for all unmapped roles (tooltip, alertdialog,
-  // note, status, alert, log, etc). This is a kinder API — rather than
-  // throwing on unknown roles, we fall back to the most common popup type.
-  // New roles that need specific aria-haspopup values should be added
-  // as explicit cases above.
-  return 'dialog';
+  if (role === 'dialog' || role === 'alertdialog') {
+    return 'dialog';
+  }
+  // Non-popup roles (tooltip, note, status, alert, log) and the
+  // no-role case: omit `aria-haspopup` entirely. React drops the
+  // attribute when the value is `undefined`.
+  return undefined;
+}
+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(_ref2) {
+  var role = _ref2.role;
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
 }