@atlaskit/top-layer 0.1.0

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

@@ -0,0 +1,238 @@
+import { useCallback, useEffect } from 'react';
+import { bind } from 'bind-event-listener';
+import { getDocument } from '@atlaskit/browser-apis';
+import { KEY_DOWN, KEY_END, KEY_HOME, KEY_TAB, KEY_UP } from '@atlaskit/ds-lib/keycodes';
+import { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus';
+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.
+ *
+ * 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 a child level and should be excluded.
+ *
+ * Supports two container patterns:
+ *
+ * **1. Container has `role="menu"` directly** (preferred — used by avatar-group):
+ *   ```
+ *   <div ref={containerRef} role="menu">
+ *     <button role="menuitem" />   ← isAtCurrentMenuLevel → true
+ *     <div role="menu">            ← nested sub-menu
+ *       <button role="menuitem" /> ← isAtCurrentMenuLevel → false
+ *     </div>
+ *   </div>
+ *   ```
+ *   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):
+ *   ```
+ *   <div ref={containerRef}>         ← wrapper (no role="menu")
+ *     <MenuGroup role="menu">
+ *       <button role="menuitem" />   ← isAtCurrentMenuLevel → true
+ *       <div role="menu">            ← nested sub-menu
+ *         <button role="menuitem" /> ← isAtCurrentMenuLevel → false
+ *       </div>
+ *     </MenuGroup>
+ *   </div>
+ *   ```
+ *   Falls back to walking the DOM to check that the element's closest
+ *   `role="menu"` is the container's own menu (not doubly nested).
+ *
+ * Ideally all consumers should use pattern 1 (place the ref directly on the
+ * `role="menu"` element). Pattern 2 exists because `@atlaskit/menu`'s
+ * `MenuGroup` does not currently accept a ref. If `MenuGroup` gains ref
+ * support in the future, dropdown-menu should switch to pattern 1 and the
+ * fallback path can be removed.
+ *
+ * Used both as a `TFocusableFilter` (to scope getNextFocusable etc.) and as
+ * a guard to prevent parent menu handlers from acting on events that
+ * belong to a nested menu.
+ */
+export function isAtCurrentMenuLevel(element, container) {
+  const closestMenu = element.closest(menuScope);
+
+  // 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;
+  }
+
+  // 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.
+  if (closestMenu === null) {
+    return true;
+  }
+
+  // Walk up from the closest menu to see if it's "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.
+      return false;
+    }
+    parent = parent.parentElement;
+  }
+
+  // The closest menu is directly inside the container (no nesting).
+  return parent === container;
+}
+/**
+ * Provides arrow key navigation for menu containers.
+ *
+ * Uses the focusable helpers from `@atlaskit/top-layer/focus` to manage
+ * DOM-based focus movement within a container.
+ *
+ * - **ArrowDown / ArrowUp**: Move focus to the next/previous item (wraps).
+ * - **Home / End**: Move focus to the first/last item.
+ * - **Tab**: Calls `onClose` to exit the menu.
+ *
+ * When a `filter` is provided, it is used both for scoping focusable
+ * elements and as a guard to prevent parent menu handlers from acting
+ * on events that belong to a nested menu.
+ *
+ * @example Basic usage
+ * ```tsx
+ * useArrowNavigation({
+ *   containerRef: menuRef,
+ *   onClose: () => setIsOpen(false),
+ *   isEnabled: isOpen,
+ * });
+ * ```
+ *
+ * @example With nested menu filter
+ * ```tsx
+ * import { useArrowNavigation, isAtCurrentMenuLevel } from '@atlaskit/top-layer/use-arrow-navigation';
+ *
+ * useArrowNavigation({
+ *   containerRef: menuRef,
+ *   onClose: () => setIsOpen(false),
+ *   isEnabled: isOpen,
+ *   filter: isAtCurrentMenuLevel,
+ * });
+ * ```
+ */
+export function useArrowNavigation({
+  containerRef,
+  onClose,
+  onNestedOpen,
+  onNestedClose,
+  isEnabled = true,
+  filter
+}) {
+  const handleKeyDown = useCallback(event => {
+    var _getDocument;
+    const container = containerRef.current;
+    if (!container) {
+      return;
+    }
+
+    // Guard: only handle the event if the currently focused element
+    // belongs to this menu level. The focused element's closest
+    // [role="menu"] must be this container (not a nested sub-menu).
+    // When no filter is provided, fall back to the closest-menu check
+    // if the container has role="menu".
+    const focused = (_getDocument = getDocument()) === null || _getDocument === void 0 ? void 0 : _getDocument.activeElement;
+    if (focused instanceof HTMLElement) {
+      if (filter) {
+        if (!filter(focused, container)) {
+          return;
+        }
+      }
+      if (!filter && container.getAttribute('role') === 'menu' && focused.closest(menuScope) !== container) {
+        return;
+      }
+    }
+    if (event.key === KEY_DOWN) {
+      var _getNextFocusable;
+      // Prevent page scroll while navigating menu items.
+      event.preventDefault();
+      (_getNextFocusable = getNextFocusable({
+        container,
+        direction: 'forwards',
+        filter
+      })) === null || _getNextFocusable === void 0 ? void 0 : _getNextFocusable.focus();
+      return;
+    }
+    if (event.key === KEY_UP) {
+      var _getNextFocusable2;
+      // Prevent page scroll while navigating menu items.
+      event.preventDefault();
+      (_getNextFocusable2 = getNextFocusable({
+        container,
+        direction: 'backwards',
+        filter
+      })) === null || _getNextFocusable2 === void 0 ? void 0 : _getNextFocusable2.focus();
+      return;
+    }
+    if (event.key === KEY_HOME) {
+      var _getFirstFocusable;
+      // Prevent browser default (e.g. scrolling to top of page).
+      event.preventDefault();
+      (_getFirstFocusable = getFirstFocusable({
+        container,
+        filter
+      })) === null || _getFirstFocusable === void 0 ? void 0 : _getFirstFocusable.focus();
+      return;
+    }
+    if (event.key === KEY_END) {
+      var _getLastFocusable;
+      // Prevent browser default (e.g. scrolling to bottom of page).
+      event.preventDefault();
+      (_getLastFocusable = getLastFocusable({
+        container,
+        filter
+      })) === null || _getLastFocusable === void 0 ? void 0 : _getLastFocusable.focus();
+      return;
+    }
+    if (event.key === KEY_TAB) {
+      onClose();
+      return;
+    }
+
+    // ── Nested menu navigation (WAI-ARIA menu pattern) ──
+    // ArrowRight on a menuitem with aria-haspopup opens the submenu.
+    if (event.key === 'ArrowRight') {
+      if (onNestedOpen && focused instanceof HTMLElement && focused.hasAttribute('aria-haspopup')) {
+        event.preventDefault();
+        onNestedOpen({
+          trigger: focused
+        });
+      }
+      return;
+    }
+
+    // ArrowLeft closes the current menu if it is nested inside a parent menu.
+    if (event.key === 'ArrowLeft') {
+      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).
+        // 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) {
+          event.preventDefault();
+          onNestedClose();
+        }
+      }
+      return;
+    }
+  }, [containerRef, onClose, onNestedOpen, onNestedClose, filter]);
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container || !isEnabled) {
+      return;
+    }
+    return bind(container, {
+      type: 'keydown',
+      listener: handleKeyDown
+    });
+  }, [containerRef, handleKeyDown, isEnabled]);
+}

package/dist/es2019/use-simple-light-dismiss/index.js

@@ -0,0 +1,79 @@
+import { useEffect, useRef } from 'react';
+import { bind } from 'bind-event-listener';
+/**
+ * Simple light-dismiss hook for `popover="manual"` elements.
+ *
+ * Provides Escape-to-close and click-outside-to-close behavior without
+ * relying on the browser's `popover="auto"` light-dismiss stack.
+ *
+ * **No stacking awareness:** This hook does not track a popover stack.
+ * If multiple manual popovers are open and all use this hook, a single
+ * Escape press or outside click will dismiss **all of them simultaneously**.
+ * This is by design — the hook is intentionally simple for cases where
+ * only one manual popover is open at a time.
+ *
+ * For stacked/nested popovers that should dismiss one-at-a-time, use
+ * `popover="auto"` mode instead, which provides native stack-aware
+ * light dismiss via the browser's top-layer stack.
+ */
+export function useSimpleLightDismiss({
+  popoverRef,
+  isOpen,
+  onClose
+}) {
+  // Keep a stable ref to onClose so the effect doesn't re-bind on every render.
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- binding to document for light dismiss
+    const unbindEscape = bind(document, {
+      type: 'keydown',
+      listener: event => {
+        if (event.key === 'Escape') {
+          onCloseRef.current({
+            reason: 'escape'
+          });
+        }
+      }
+    });
+
+    // Listen for click-outside in the **capture** phase.
+    //
+    // The click that opened the popover propagates in bubble phase
+    // (trigger onClick → setIsOpen(true) → React render → useEffect).
+    // By the time this effect runs, the opening click has finished
+    // bubbling. A capture-phase listener added now cannot retroactively
+    // fire for that event — it only fires for *future* clicks.
+    //
+    // This avoids the need for timestamp guards or deferred binding.
+    // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- binding to document for light dismiss
+    const unbindClickOutside = bind(document, {
+      type: 'click',
+      listener: event => {
+        const el = popoverRef.current;
+        if (!el) {
+          return;
+        }
+
+        // If the click target is inside the popover, don't dismiss.
+        if (event.target instanceof Node && el.contains(event.target)) {
+          return;
+        }
+        onCloseRef.current({
+          reason: 'light-dismiss'
+        });
+      },
+      options: {
+        capture: true
+      }
+    });
+    return () => {
+      unbindEscape();
+      unbindClickOutside();
+    };
+  }, [isOpen, popoverRef]);
+}

package/dist/esm/animations/presets.js

@@ -0,0 +1,190 @@
+import { getPlacement } from '../internal/use-anchor-positioning';
+
+// ── slideAndFade ──
+
+function getSlideAndFadeProperties(_ref) {
+  var placement = _ref.placement,
+    distance = _ref.distance;
+  var pos = "".concat(distance, "px");
+  var neg = "-".concat(distance, "px");
+  var _getPlacement = getPlacement({
+      placement: placement
+    }),
+    axis = _getPlacement.axis,
+    edge = _getPlacement.edge;
+  if (axis === 'block' && edge === 'start') {
+    return {
+      '--ds-popover-tx': '0',
+      '--ds-popover-ty': pos
+    };
+  }
+  if (axis === 'block' && edge === 'end') {
+    return {
+      '--ds-popover-tx': '0',
+      '--ds-popover-ty': neg
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    return {
+      '--ds-popover-tx': pos,
+      '--ds-popover-ty': '0'
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    return {
+      '--ds-popover-tx': neg,
+      '--ds-popover-ty': '0'
+    };
+  }
+  return {
+    '--ds-popover-tx': '0',
+    '--ds-popover-ty': neg
+  };
+}
+var SLIDE_AND_FADE_CSS = "\n[data-ds-popover-slide-and-fade] {\n  opacity: 0;\n  transform: translate3d(var(--ds-popover-tx, 0), var(--ds-popover-ty, 0), 0);\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-popover-slide-and-fade]:popover-open {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-popover-slide-and-fade]:popover-open {\n    opacity: 0;\n    transform: translate3d(var(--ds-popover-tx, 0), var(--ds-popover-ty, 0), 0);\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-popover-slide-and-fade],\n  [data-ds-popover-slide-and-fade]:popover-open {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Directional slide + opacity animation.
+ *
+ * The popover slides in from the direction opposite its placement edge
+ * (e.g. a `block-end` popover slides down from above).
+ *
+ * @param options.distance - Slide distance in pixels. Defaults to `4`.
+ *
+ * @example
+ * ```tsx
+ * import { slideAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * // Default 4px slide (tooltip)
+ * <Popup.Content animate={slideAndFade()} />
+ *
+ * // Custom 8px slide (popup / dropdown)
+ * <Popup.Content animate={slideAndFade({ distance: 8 })} />
+ * ```
+ */
+export function slideAndFade(options) {
+  var _options$distance;
+  var distance = (_options$distance = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance !== void 0 ? _options$distance : 4;
+  return {
+    name: 'slide-and-fade',
+    css: SLIDE_AND_FADE_CSS,
+    getProperties: function getProperties(_ref2) {
+      var placement = _ref2.placement;
+      return getSlideAndFadeProperties({
+        placement: placement,
+        distance: distance
+      });
+    },
+    exitDurationMs: 175
+  };
+}
+
+// ── fade ──
+
+var FADE_CSS = "\n[data-ds-popover-fade] {\n  opacity: 0;\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-popover-fade]:popover-open {\n  opacity: 1;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-popover-fade]:popover-open {\n    opacity: 0;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-popover-fade],\n  [data-ds-popover-fade]:popover-open {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Simple opacity transition, no transform.
+ *
+ * Suitable for popup dialogs or content that does not need directional motion.
+ *
+ * @example
+ * ```tsx
+ * import { fade } from '@atlaskit/top-layer/animations';
+ *
+ * <Popup.Content animate={fade()} />
+ * ```
+ */
+export function fade() {
+  return {
+    name: 'fade',
+    css: FADE_CSS,
+    exitDurationMs: 175
+  };
+}
+
+// ── scaleAndFade ──
+
+var SCALE_AND_FADE_CSS = "\n[data-ds-popover-scale-and-fade] {\n  opacity: 0;\n  transform: scale(0.95);\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-popover-scale-and-fade]:popover-open {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-popover-scale-and-fade]:popover-open {\n    opacity: 0;\n    transform: scale(0.95);\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-popover-scale-and-fade],\n  [data-ds-popover-scale-and-fade]:popover-open {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Scale from 0.95 + opacity transition.
+ *
+ * Suitable for menus, dropdowns, and select options.
+ *
+ * @example
+ * ```tsx
+ * import { scaleAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * <Popup.Content animate={scaleAndFade()} />
+ * ```
+ */
+export function scaleAndFade() {
+  return {
+    name: 'scale-and-fade',
+    css: SCALE_AND_FADE_CSS,
+    exitDurationMs: 175
+  };
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+// Dialog presets
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── dialogSlideUpAndFade ──
+
+var DIALOG_SLIDE_UP_AND_FADE_CSS = "\n[data-ds-dialog-slide-up-and-fade] {\n  opacity: 0;\n  transform: translateY(calc(-1 * var(--ds-dialog-ty, 12px)));\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-slide-up-and-fade][open] {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-slide-up-and-fade][open] {\n    opacity: 0;\n    transform: translateY(var(--ds-dialog-ty, 12px));\n  }\n}\n\n[data-ds-dialog-slide-up-and-fade]::backdrop {\n  background-color: transparent;\n  transition:\n    background-color 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-slide-up-and-fade][open]::backdrop {\n  background-color: var(--ds-blanket, #050C1F75);\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-slide-up-and-fade][open]::backdrop {\n    background-color: transparent;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-dialog-slide-up-and-fade],\n  [data-ds-dialog-slide-up-and-fade][open],\n  [data-ds-dialog-slide-up-and-fade]::backdrop,\n  [data-ds-dialog-slide-up-and-fade][open]::backdrop {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Slide up + opacity animation for dialogs.
+ *
+ * Entry slides up from below; exit slides up and out (asymmetric).
+ * Includes backdrop fade animation.
+ *
+ * @param options.distance - Slide distance in pixels. Defaults to `12`.
+ *
+ * @example
+ * ```tsx
+ * import { dialogSlideUpAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * const animation = dialogSlideUpAndFade();
+ * <Dialog animate={animation} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+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;
+  return {
+    name: distance === 12 ? 'dialog-slide-up-and-fade' : "dialog-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
+  };
+}
+
+// ── dialogFade ──
+
+var DIALOG_FADE_CSS = "\n[data-ds-dialog-fade] {\n  opacity: 0;\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-fade][open] {\n  opacity: 1;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-fade][open] {\n    opacity: 0;\n  }\n}\n\n[data-ds-dialog-fade]::backdrop {\n  background-color: transparent;\n  transition:\n    background-color 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-fade][open]::backdrop {\n  background-color: var(--ds-blanket, #050C1F75);\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-fade][open]::backdrop {\n    background-color: transparent;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-dialog-fade],\n  [data-ds-dialog-fade][open],\n  [data-ds-dialog-fade]::backdrop,\n  [data-ds-dialog-fade][open]::backdrop {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Simple opacity transition for dialogs, no transform.
+ *
+ * Includes backdrop fade animation.
+ *
+ * @example
+ * ```tsx
+ * import { dialogFade } from '@atlaskit/top-layer/animations';
+ *
+ * <Dialog animate={dialogFade()} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+export function dialogFade() {
+  return {
+    name: 'dialog-fade',
+    css: DIALOG_FADE_CSS,
+    exitDurationMs: 175
+  };
+}

package/dist/esm/animations/types.js

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

package/dist/esm/arrow/index.js

@@ -0,0 +1,123 @@
+import once from '@atlaskit/ds-lib/once';
+import { getPlacement, placementToPositionArea } from '../internal/use-anchor-positioning';
+/**
+ * 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(1px) 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, 1px)) 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/* Single-axis centered */\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}\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}\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}\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}\n\n/* Block edge + inline span */\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}\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}\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}\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}\n\n/* Inline edge + block span */\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}\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}\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}\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}\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
+ * don't 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/create-close-event.js

@@ -0,0 +1,33 @@
+/**
+ * Creates a synthetic DOM event from a `TDialogCloseReason`.
+ *
+ * Useful when bridging the Dialog primitive's `onClose({ reason })` callback
+ * to a legacy API that expects a `KeyboardEvent` or `MouseEvent` — for example,
+ * `@atlaskit/modal-dialog`'s `onClose(event, analyticsEvent)` contract.
+ *
+ * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
+ * - `'overlay-click'` → `MouseEvent('click')`
+ *
+ * @example
+ * ```tsx
+ * import { createCloseEvent } from '@atlaskit/top-layer/create-close-event';
+ * import { type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
+ *
+ * function onDialogClose({ reason }: { reason: TDialogCloseReason }) {
+ *   legacyOnClose(createCloseEvent({ reason }));
+ * }
+ * ```
+ */
+export function createCloseEvent(_ref) {
+  var reason = _ref.reason;
+  if (reason === 'escape') {
+    return new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true
+    });
+  }
+  return new MouseEvent('click', {
+    bubbles: true,
+    cancelable: true
+  });
+}