@atlaskit/top-layer 0.8.0 → 0.10.0

package/dist/cjs/popup/popup-trigger.js

@@ -10,24 +10,15 @@ var _slot = require("../internal/slot");
 var _popupContext = require("./popup-context");
 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); }
 /**
- * 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.
  */
 function PopupTrigger(_ref) {
   var children = _ref.children;
@@ -39,35 +30,24 @@ function PopupTrigger(_ref) {
     ariaHasPopup = _usePopupContext.ariaHasPopup;
   var childOnClick = /*#__PURE__*/(0, _react.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.default.useRef(isOpen);
   isOpenRef.current = isOpen;
   var handleClick = (0, _react.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/cjs/popup/popup.js

@@ -11,10 +11,10 @@ var _react = _interopRequireWildcard(require("react"));
 var _popupContext = require("./popup-context");
 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); }
 /**
- * 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.
  *
@@ -22,18 +22,24 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * `Popup.Content` reads and forwards to the underlying `Popover`.
  */
 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 = (0, _react.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 = (0, _react.useRef)(null);
@@ -42,6 +48,8 @@ function PopupRoot(props) {
     _useState2 = (0, _slicedToArray2.default)(_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 = (0, _react.useState)('dialog'),
     _useState4 = (0, _slicedToArray2.default)(_useState3, 2),
     ariaHasPopup = _useState4[0],
@@ -52,7 +60,10 @@ 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/cjs/use-arrow-navigation/use-arrow-navigation.js

@@ -14,16 +14,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
@@ -35,7 +35,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">
@@ -62,7 +62,7 @@ var menuScope = '[role="menu"]';
 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;
@@ -71,18 +71,18 @@ 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;
@@ -91,6 +91,22 @@ 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.
  *
@@ -126,6 +142,7 @@ function isAtCurrentMenuLevel(element, container) {
  * });
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function useArrowNavigation(_ref) {
   var containerRef = _ref.containerRef,
     onClose = _ref.onClose,
@@ -221,7 +238,7 @@ 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/es2019/animations/presets.js

@@ -1,4 +1,4 @@
-import { getPlacement } from '../internal/use-anchor-position';
+import { getPlacement } from '../internal/resolve-placement';
 
 // ── slideAndFade ──
 
@@ -152,6 +152,7 @@ const FADE_CSS = `
  * <Popup.Content animate={fade()} />
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function fade() {
   return {
     name: 'fade',
@@ -206,6 +207,7 @@ const SCALE_AND_FADE_CSS = `
  * <Popup.Content animate={scaleAndFade()} />
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function scaleAndFade() {
   return {
     name: 'scale-and-fade',
@@ -291,11 +293,14 @@ const DIALOG_SLIDE_UP_AND_FADE_CSS = `
  * </Dialog>
  * ```
  */
+// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function dialogSlideUpAndFade(options) {
   var _options$distance2;
   const 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-${distance}`,
+    name: distance === 12 ? 'slide-up-and-fade' : `slide-up-and-fade-${distance}`,
     css: distance === 12 ? DIALOG_SLIDE_UP_AND_FADE_CSS : DIALOG_SLIDE_UP_AND_FADE_CSS.replace(/12px/g, `${distance}px`),
     exitDurationMs: 175
   };
@@ -366,9 +371,11 @@ const DIALOG_FADE_CSS = `
  * </Dialog>
  * ```
  */
+// 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/es2019/arrow/index.js

@@ -0,0 +1,269 @@
+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/
+ */
+const ARROW_CSS = `
+[data-ds-popover-arrow] {
+  clip-path: inset(var(--ds-arrow-offset, 0px)) margin-box;
+  box-shadow: none;
+}
+
+/* Top and Bottom arrows (vertical hexagon) */
+[data-ds-popover-arrow]::before {
+  content: "";
+  position: absolute;
+  z-index: -1;
+  background: inherit;
+  left: 50%;
+  transform: translateX(-50%);
+  width: calc(var(--ds-arrow-size, 8px) * 2);
+  height: calc(100% + var(--ds-arrow-size, 8px) * 2);
+  top: calc(var(--ds-arrow-size, 8px) * -1);
+  clip-path: polygon(
+    0 var(--ds-arrow-size, 8px),
+    50% 0,
+    100% var(--ds-arrow-size, 8px),
+    100% calc(100% - var(--ds-arrow-size, 8px)),
+    50% 100%,
+    0 calc(100% - var(--ds-arrow-size, 8px))
+  );
+}
+
+/* Left and Right arrows (horizontal hexagon) */
+[data-ds-popover-arrow]::after {
+  content: "";
+  position: absolute;
+  z-index: -1;
+  background: inherit;
+  top: 50%;
+  transform: translateY(-50%);
+  height: calc(var(--ds-arrow-size, 8px) * 2);
+  width: calc(100% + var(--ds-arrow-size, 8px) * 2);
+  left: calc(var(--ds-arrow-size, 8px) * -1);
+  clip-path: polygon(
+    var(--ds-arrow-size, 8px) 0,
+    calc(100% - var(--ds-arrow-size, 8px)) 0,
+    100% 50%,
+    calc(100% - var(--ds-arrow-size, 8px)) 100%,
+    var(--ds-arrow-size, 8px) 100%,
+    0 50%
+  );
+}
+
+/* ── @position-try rules ──
+ * One rule per possible position-area value.
+ * Each sets the position-area and the correct margin direction
+ * so the arrow on the anchor-facing side is revealed.
+ *
+ * Margin direction per edge:
+ *   block-start  (above anchor) → margin-block-end   (bottom, facing anchor)
+ *   block-end    (below anchor) → margin-block-start  (top, facing anchor)
+ *   inline-start (left of anchor) → margin-inline-end (right, facing anchor)
+ *   inline-end   (right of anchor) → margin-inline-start (left, facing anchor)
+ */
+
+/* Each rule sets two margins: the anchor-facing margin for the gap
+   (via --ds-arrow-size) and one cross-axis margin for the shift
+   (via one of --ds-cross-axis-shift-margin-start, --ds-cross-axis-shift-margin-end,
+   --ds-cross-axis-shift-margin-block-start, or --ds-cross-axis-shift-margin-block-end). The
+   side matches the popover's anchored cross-axis edge per align. Only
+   one of the four properties is non-zero at a time; useAnchorPosition
+   picks it. See notes/architecture/positioning.md for details. */
+/* Single-axis centered (align: center) */
+@position-try --ds-arrow-block-start {
+  position-area: block-start;
+  margin: 0;
+  margin-block-end: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
+}
+@position-try --ds-arrow-block-end {
+  position-area: block-end;
+  margin: 0;
+  margin-block-start: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
+}
+@position-try --ds-arrow-inline-start {
+  position-area: inline-start;
+  margin: 0;
+  margin-inline-end: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
+}
+@position-try --ds-arrow-inline-end {
+  position-area: inline-end;
+  margin: 0;
+  margin-inline-start: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
+}
+
+/* Block edge + inline span (align: start uses span-inline-end; align: end uses span-inline-start) */
+@position-try --ds-arrow-block-start-span-inline-start {
+  position-area: block-start span-inline-start;
+  margin: 0;
+  margin-block-end: var(--ds-arrow-size, 8px);
+  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);
+}
+@position-try --ds-arrow-block-start-span-inline-end {
+  position-area: block-start span-inline-end;
+  margin: 0;
+  margin-block-end: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
+}
+@position-try --ds-arrow-block-end-span-inline-start {
+  position-area: block-end span-inline-start;
+  margin: 0;
+  margin-block-start: var(--ds-arrow-size, 8px);
+  margin-inline-end: var(--ds-cross-axis-shift-margin-end, 0px);
+}
+@position-try --ds-arrow-block-end-span-inline-end {
+  position-area: block-end span-inline-end;
+  margin: 0;
+  margin-block-start: var(--ds-arrow-size, 8px);
+  margin-inline-start: var(--ds-cross-axis-shift-margin-start, 0px);
+}
+
+/* Inline edge + block span (align: start uses span-block-end; align: end uses span-block-start) */
+@position-try --ds-arrow-inline-start-span-block-start {
+  position-area: inline-start span-block-start;
+  margin: 0;
+  margin-inline-end: var(--ds-arrow-size, 8px);
+  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);
+}
+@position-try --ds-arrow-inline-start-span-block-end {
+  position-area: inline-start span-block-end;
+  margin: 0;
+  margin-inline-end: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
+}
+@position-try --ds-arrow-inline-end-span-block-start {
+  position-area: inline-end span-block-start;
+  margin: 0;
+  margin-inline-start: var(--ds-arrow-size, 8px);
+  margin-block-end: var(--ds-cross-axis-shift-margin-block-end, 0px);
+}
+@position-try --ds-arrow-inline-end-span-block-end {
+  position-area: inline-end span-block-end;
+  margin: 0;
+  margin-inline-start: var(--ds-arrow-size, 8px);
+  margin-block-start: var(--ds-cross-axis-shift-margin-block-start, 0px);
+}
+`;
+
+// ── 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({
+  positionArea
+}) {
+  return `--ds-arrow-${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({
+  placement
+}) {
+  const {
+    axis,
+    edge,
+    align
+  } = getPlacement({
+    placement
+  });
+  if (align === 'center') {
+    // Single-axis: only flip the edge
+    const flippedEdge = edge === 'start' ? 'end' : 'start';
+    return positionAreaToRuleName({
+      positionArea: placementToPositionArea({
+        placement: {
+          axis,
+          edge: flippedEdge
+        }
+      })
+    });
+  }
+
+  // Compound placement: try flipping edge, alignment, and both
+  const flippedEdge = edge === 'start' ? 'end' : 'start';
+  const flippedAlign = align === 'start' ? 'end' : 'start';
+  return [positionAreaToRuleName({
+    positionArea: placementToPositionArea({
+      placement: {
+        axis,
+        edge: flippedEdge,
+        align
+      }
+    })
+  }), positionAreaToRuleName({
+    positionArea: placementToPositionArea({
+      placement: {
+        axis,
+        edge,
+        align: flippedAlign
+      }
+    })
+  }), positionAreaToRuleName({
+    positionArea: placementToPositionArea({
+      placement: {
+        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 const arrow = once(() => ({
+  name: 'arrow',
+  css: ARROW_CSS,
+  getTryFallbacks
+}));

package/dist/es2019/arrow/types.js

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

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

@@ -5,6 +5,8 @@ import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useEffect, useId, useLayoutEffect, useRef } from 'react';
 import { bind } from 'bind-event-listener';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+import noop from '@atlaskit/ds-lib/noop';
+import { useNotifyOpenLayerObserver } from '@atlaskit/layering/experimental/open-layer-observer';
 import { useAnimatedVisibility } from '../internal/use-animated-visibility';
 import { useFocusWrap } from '../internal/use-focus-wrap';
 // eslint-disable-next-line @atlaskit/ui-styling-standard/no-unsafe-values -- dialog reset requires values not in cssMap's type union
@@ -13,7 +15,7 @@ const 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`:
@@ -24,6 +26,10 @@ const 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 const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   children,
@@ -63,6 +69,16 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
     role: 'dialog'
   });
 
+  // ── Open layer observer registration ──
+  // Notifies the open layer observer so app-coordination features
+  // (open-count subscriptions) work with top-layer dialogs.
+  useNotifyOpenLayerObserver({
+    type: 'modal',
+    isOpen,
+    // No-op: no current use case for programmatic close via OpenLayerObserver.
+    onClose: noop
+  });
+
   // Show/hide the dialog in response to isOpen changes.
   useLayoutEffect(() => {
     const dialog = ownRef.current;
@@ -121,11 +137,12 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
   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
@@ -133,7 +150,7 @@ export const Dialog = /*#__PURE__*/forwardRef(function Dialog({
     onCancel: handleCancel,
     "data-testid": testId
   }, preset ? {
-    [`data-ds-${preset.name}`]: ''
+    [`data-ds-dialog-${preset.name}`]: ''
   } : undefined, {
     className: ax([styles.dialog])
   }), shouldHideBackdrop &&

package/dist/es2019/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/es2019/entry-points/dialog/create-close-event.js

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

package/dist/es2019/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/es2019/entry-points/popover/create-close-event.js

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