@atlaskit/top-layer 0.1.0

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

@@ -0,0 +1,192 @@
+/* popup-content.tsx generated by @compiled/babel-plugin v0.39.1 */
+import _extends from "@babel/runtime/helpers/extends";
+import { ax, ix } from "@compiled/react/runtime";
+import React, { forwardRef, useCallback, useLayoutEffect, useRef } from 'react';
+import mergeRefs from '@atlaskit/ds-lib/merge-refs';
+import { roleToAriaHasPopup } from '../internal/role-types';
+import { useAnchorPosition } from '../internal/use-anchor-positioning';
+import { usePresetStyles } from '../internal/use-preset-styles';
+import { Popover } from '../popover/popover';
+import { useMaybePopupContext } from './popup-context';
+/**
+ * Thin context wrapper that composes `Popover` + `useAnchorPosition`.
+ *
+ * Used inside the `<Popup>` compound — reads triggerRef, placement, isOpen,
+ * and onClose from context. For standalone usage (tooltip, spotlight, flag),
+ * use `Popover` + `useAnchorPosition` directly.
+ */
+export var PopupContent = /*#__PURE__*/forwardRef(function PopupContent(_ref, ref) {
+  var _ref2, _ref3, _ctx$popoverRef;
+  var children = _ref.children,
+    role = _ref.role,
+    label = _ref.label,
+    labelledBy = _ref.labelledBy,
+    animate = _ref.animate,
+    arrow = _ref.arrow,
+    mode = _ref.mode,
+    _ref$width = _ref.width,
+    width = _ref$width === void 0 ? 'content' : _ref$width,
+    isOpenProp = _ref.isOpen,
+    triggerRefProp = _ref.triggerRef,
+    placementProp = _ref.placement,
+    onCloseProp = _ref.onClose,
+    testIdProp = _ref.testId,
+    offsetProp = _ref.offset,
+    forceFallbackPositioningProp = _ref.forceFallbackPositioning;
+  // When inside <Popup>, context provides defaults. Props always win.
+  var ctx = useMaybePopupContext();
+  var triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
+  var placement = (_ref2 = placementProp !== null && placementProp !== void 0 ? placementProp : ctx === null || ctx === void 0 ? void 0 : ctx.placement) !== null && _ref2 !== void 0 ? _ref2 : {};
+  var onClose = onCloseProp !== null && onCloseProp !== void 0 ? onCloseProp : ctx === null || ctx === void 0 ? void 0 : ctx.onClose;
+  var testId = testIdProp !== null && testIdProp !== void 0 ? testIdProp : ctx === null || ctx === void 0 ? void 0 : ctx.testId;
+  var forceFallbackPositioning = forceFallbackPositioningProp !== null && forceFallbackPositioningProp !== void 0 ? forceFallbackPositioningProp : ctx === null || ctx === void 0 ? void 0 : ctx.forceFallbackPositioning;
+
+  // Resolve isOpen: prop wins, then context.
+  // Inside the <Popup> compound, ctx.isOpen tracks the browser's toggle state.
+  var isOpen = (_ref3 = isOpenProp !== null && isOpenProp !== void 0 ? isOpenProp : ctx === null || ctx === void 0 ? void 0 : ctx.isOpen) !== null && _ref3 !== void 0 ? _ref3 : false;
+
+  // Combine internal state sync with consumer's onOpenChange callback.
+  // The Popup compound needs setIsOpen to keep aria-expanded on the trigger
+  // in sync, and the consumer may also want to respond to open/close events
+  // (e.g. for focus management).
+  var setIsOpen = ctx === null || ctx === void 0 ? void 0 : ctx.setIsOpen;
+  var consumerOnOpenChange = ctx === null || ctx === void 0 ? void 0 : ctx.onOpenChange;
+  // Note: onOpenChange composition is handled by handleOpenChange below,
+  // which also adds nested-popover focus restoration.
+
+  // ── Sync aria-haspopup on the trigger with the content's role ──
+  var setAriaHasPopup = ctx === null || ctx === void 0 ? void 0 : ctx.setAriaHasPopup;
+  useLayoutEffect(function () {
+    setAriaHasPopup === null || setAriaHasPopup === void 0 || setAriaHasPopup(roleToAriaHasPopup({
+      role: role
+    }));
+  }, [role, setAriaHasPopup]);
+
+  // ── Focus restoration ──
+  // The native Popover API handles focus restoration automatically for
+  // popover="auto" and popover="hint":
+  //   - Escape → restores focus to the previously focused element (the trigger)
+  //   - Click-outside → does NOT restore (correct: the user clicked deliberately)
+  //   - hidePopover() → restores focus to the previously focused element
+  //
+  // However, for **nested** popover="auto" popovers, the browser only captures
+  // `previouslyFocusedElement` for the outermost popover in the auto stack.
+  // Inner popovers have `shouldRestoreFocus=false` per the spec, so the browser
+  // does not restore focus when they close.
+  //
+  // To handle this, we listen for the close transition via `onOpenChange` and
+  // restore focus to the trigger if the browser didn't. This runs after the
+  // browser's native restoration (which happens synchronously during hidePopover),
+  // so it only takes effect when the browser skipped restoration (nested case).
+  //
+  // See: notes/architecture/focus-restoration.md
+  var handleOpenChange = useCallback(function (args) {
+    // Sync compound state
+    setIsOpen === null || setIsOpen === void 0 || setIsOpen(args.isOpen);
+    consumerOnOpenChange === null || consumerOnOpenChange === void 0 || consumerOnOpenChange(args);
+
+    // ── Nested popover focus restoration fallback ──
+    // The browser only captures `previouslyFocusedElement` for the
+    // outermost popover="auto" in the stack. Inner (nested) popovers
+    // have shouldRestoreFocus=false, so the browser won't restore
+    // focus when they close.
+    //
+    // We detect this case by checking if focus is still inside the
+    // closing popover element. If it is, the browser didn't restore,
+    // and we need to move focus to the trigger ourselves.
+    //
+    // This does NOT fire for:
+    //   - Outermost popovers (browser already restored to trigger)
+    //   - Click-outside (focus is on the clicked element, not in popover)
+    if (!args.isOpen) {
+      var trigger = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current;
+      var focusStillInPopover = trigger && args.element.contains(document.activeElement);
+      if (focusStillInPopover) {
+        var shouldRestore = role === 'dialog' || role === 'alertdialog' || role === 'menu' || role === 'listbox';
+        if (shouldRestore) {
+          trigger.focus({
+            preventScroll: true
+          });
+        }
+      }
+    }
+  }, [setIsOpen, consumerOnOpenChange, triggerRef, role]);
+
+  // ── Anchor positioning ──
+  // Compose useAnchorPosition with Popover. The hook positions the popover
+  // relative to the trigger element via CSS Anchor Positioning (with JS fallback).
+  // Use ctx.popoverRef when inside the compound (so the trigger can also
+  // reach the same DOM element for togglePopover). Otherwise use a local ref.
+  var localRef = useRef(null);
+  var popoverRef = (_ctx$popoverRef = ctx === null || ctx === void 0 ? void 0 : ctx.popoverRef) !== null && _ctx$popoverRef !== void 0 ? _ctx$popoverRef : localRef;
+  var arrowPreset = usePresetStyles({
+    preset: arrow
+  });
+  useAnchorPosition({
+    anchorRef: triggerRef !== null && triggerRef !== void 0 ? triggerRef : {
+      current: null
+    },
+    popoverRef: popoverRef,
+    placement: placement,
+    offset: offsetProp,
+    forceFallbackPositioning: forceFallbackPositioning,
+    arrow: arrowPreset !== null && arrowPreset !== void 0 ? arrowPreset : undefined
+  });
+
+  // ── Width: match trigger ──
+  // When width="trigger" or width="min-trigger", size the popover relative
+  // to the trigger element. Uses CSS `anchor-size(width)` when supported,
+  // falling back to a one-off measurement of the trigger's offsetWidth.
+  useLayoutEffect(function () {
+    if (width === 'content') {
+      return;
+    }
+    var node = popoverRef.current;
+    if (!node) {
+      return;
+    }
+    var cssProperty = width === 'trigger' ? 'width' : 'min-width';
+    var anchorValue = 'anchor-size(width)';
+
+    // Feature-detect `anchor-size()` specifically (not just `anchor-name`)
+    // so the JS fallback fires correctly in browsers that support anchor
+    // positioning but not anchor sizing.
+    var supportsAnchorSize = typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('width', 'anchor-size(width)');
+    if (supportsAnchorSize) {
+      node.style.setProperty(cssProperty, anchorValue);
+    } else {
+      // JS fallback: one-off read of the trigger's width.
+      var trigger = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current;
+      if (trigger) {
+        node.style.setProperty(cssProperty, "".concat(trigger.offsetWidth, "px"));
+      }
+    }
+    return function () {
+      node.style.removeProperty(cssProperty);
+    };
+  }, [width, popoverRef, triggerRef]);
+
+  // Merge: the popoverRef (shared with trigger + positioning) and the forwarded ref.
+  var combinedRef = mergeRefs([popoverRef, ref]);
+
+  // TPopupContentProps already validates the discriminated union (role + label,
+  // mode + onClose) at its API boundary. Popover accepts TPopoverInternalProps
+  // internally so individual prop forwarding doesn't need to re-prove the union.
+  var popoverProps = {
+    isOpen: isOpen,
+    animate: animate,
+    placement: placement,
+    mode: mode,
+    role: role,
+    label: label,
+    labelledBy: labelledBy,
+    onClose: onClose !== null && onClose !== void 0 ? onClose : undefined,
+    onOpenChange: handleOpenChange,
+    testId: testId,
+    children: children,
+    id: ctx === null || ctx === void 0 ? void 0 : ctx.popoverId
+  };
+  return /*#__PURE__*/React.createElement(Popover, _extends({
+    ref: combinedRef
+  }, popoverProps));
+});

package/dist/esm/popup/popup-context.js

@@ -0,0 +1,34 @@
+import { createContext, useContext } from 'react';
+var PopupContext = /*#__PURE__*/createContext(null);
+
+/**
+ * __Popup provider__
+ *
+ * Provides shared popup state (placement, popoverId, triggerRef,
+ * isOpen, onClose) to compound child components such as `Popup.Trigger` and
+ * `Popup.Content`.
+ */
+export var PopupProvider = PopupContext.Provider;
+
+/**
+ * Returns the nearest `Popup` context value.
+ *
+ * Throws if called outside of a `<Popup>` compound component.
+ */
+export function usePopupContext() {
+  var ctx = useContext(PopupContext);
+  if (ctx === null) {
+    throw new Error('@atlaskit/top-layer: Popup compound components must be used within <Popup>.');
+  }
+  return ctx;
+}
+
+/**
+ * Returns the popup context if available, or `null` when used outside `<Popup>`.
+ *
+ * Used by `PopupContent` to support standalone usage (e.g. tooltip)
+ * where values are passed as props instead of coming from a compound component.
+ */
+export function useMaybePopupContext() {
+  return useContext(PopupContext);
+}

package/dist/esm/popup/popup-surface.compiled.css

@@ -0,0 +1,5 @@
+
+._2rkofajl{border-radius:var(--ds-radius-small,3px)}._16qs130s{box-shadow:var(--ds-shadow-overlay,0 8px 9pt #1e1f2126,0 0 1px #1e1f214f)}
+._18m91wug{overflow-y:auto}
+._1reo1wug{overflow-x:auto}
+._bfhk1bhr{background-color:var(--ds-surface-overlay,#fff)}

package/dist/esm/popup/popup-surface.js

@@ -0,0 +1,23 @@
+/* popup-surface.tsx generated by @compiled/babel-plugin v0.39.1 */
+import "./popup-surface.compiled.css";
+import { ax, ix } from "@compiled/react/runtime";
+import React from 'react';
+var styles = {
+  root: "_2rkofajl _1reo1wug _18m91wug _bfhk1bhr _16qs130s"
+};
+
+/**
+ * Optional styled wrapper for popup content.
+ *
+ * Adds default visual styling (background, border-radius, box-shadow)
+ * using design tokens. Consumers who want fully custom styling
+ * should use `Popup.Content` without wrapping in `PopupSurface`.
+ *
+ * Exposed as `Popup.Surface` on the compound component.
+ */
+export function PopupSurface(_ref) {
+  var children = _ref.children;
+  return /*#__PURE__*/React.createElement("div", {
+    className: ax([styles.root])
+  }, children);
+}

package/dist/esm/popup/popup-trigger-function.js

@@ -0,0 +1,69 @@
+import { useCallback, useMemo } from 'react';
+import { usePopupContext } from './popup-context';
+
+/**
+ * Props passed to the `TriggerFunction` render-prop child.
+ */
+
+/**
+ * Render-prop alternative to `Popup.Trigger`.
+ *
+ * Use when you need full control over the trigger element — for example,
+ * to compose your own trigger with custom event handlers, wrap a third-party
+ * component, or build a trigger from multiple elements.
+ *
+ * `Popup.Trigger` uses `cloneElement` internally, which limits composability.
+ * `Popup.TriggerFunction` hands you the raw props and lets you wire them up.
+ *
+ * **Note:** This sub-component uses a render-prop pattern and is not
+ * compatible with React Server Components (RSC). It must be used inside
+ * a client component boundary (`'use client'`).
+ *
+ * @example
+ * ```tsx
+ * <Popup placement={{ edge: 'end' }} onClose={handleClose}>
+ *   <Popup.TriggerFunction>
+ *     {({ ref, toggle, ariaAttributes }) => (
+ *       <button ref={ref} onClick={toggle} {...ariaAttributes}>
+ *         Open
+ *       </button>
+ *     )}
+ *   </Popup.TriggerFunction>
+ *   <Popup.Content role="dialog" label="My popup">
+ *     Content
+ *   </Popup.Content>
+ * </Popup>
+ * ```
+ */
+export function PopupTriggerFunction(_ref) {
+  var children = _ref.children;
+  var _usePopupContext = usePopupContext(),
+    triggerRef = _usePopupContext.triggerRef,
+    popoverRef = _usePopupContext.popoverRef,
+    popoverId = _usePopupContext.popoverId,
+    isOpen = _usePopupContext.isOpen,
+    ariaHasPopup = _usePopupContext.ariaHasPopup;
+  var ref = useCallback(function (node) {
+    triggerRef.current = node;
+  }, [triggerRef]);
+  var toggle = useCallback(function () {
+    var popoverEl = popoverRef.current;
+    if (popoverEl) {
+      popoverEl.togglePopover();
+    }
+  }, [popoverRef]);
+  var ariaAttributes = useMemo(function () {
+    return {
+      'aria-expanded': isOpen,
+      'aria-controls': popoverId,
+      'aria-haspopup': ariaHasPopup
+    };
+  }, [isOpen, popoverId, ariaHasPopup]);
+  return children({
+    ref: ref,
+    isOpen: isOpen,
+    popoverId: popoverId,
+    toggle: toggle,
+    ariaAttributes: ariaAttributes
+  });
+}

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

@@ -0,0 +1,74 @@
+import React, { isValidElement, useCallback } from 'react';
+import { Slot } from '../internal/slot';
+import { usePopupContext } from './popup-context';
+/**
+ * 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.
+ *
+ * `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.
+ */
+export function PopupTrigger(_ref) {
+  var children = _ref.children;
+  var _usePopupContext = usePopupContext(),
+    triggerRef = _usePopupContext.triggerRef,
+    popoverRef = _usePopupContext.popoverRef,
+    popoverId = _usePopupContext.popoverId,
+    isOpen = _usePopupContext.isOpen,
+    ariaHasPopup = _usePopupContext.ariaHasPopup;
+  var childOnClick = /*#__PURE__*/isValidElement(children) ? children.props.onClick : undefined;
+
+  // Use a ref to track the latest isOpen value so the click handler
+  // doesn't need isOpen in its dependency array (which would recreate
+  // the handler on every open/close, breaking cloneElement identity).
+  var isOpenRef = React.useRef(isOpen);
+  isOpenRef.current = isOpen;
+  var handleClick = 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().
+      if (!isOpenRef.current) {
+        try {
+          popoverEl.showPopover();
+        } catch (_unused) {
+          // Already showing — safe to 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]);
+  return /*#__PURE__*/React.createElement(Slot, {
+    ref: triggerRef,
+    onClick: handleClick,
+    "aria-expanded": isOpen,
+    "aria-controls": popoverId,
+    "aria-haspopup": ariaHasPopup
+  }, children);
+}

package/dist/esm/popup/popup.js

@@ -0,0 +1,61 @@
+import _slicedToArray from "@babel/runtime/helpers/slicedToArray";
+import React, { useCallback, useId, useRef, useState } from 'react';
+import { PopupProvider } from './popup-context';
+/**
+ * Popup compound — trigger + popover content.
+ *
+ * Use when a button opens anchored content (dropdown, menu, dialog).
+ * The browser manages visibility via `togglePopover()` — the consumer
+ * never manages `isOpen`. For custom trigger lifecycles (hover, timers,
+ * external state), use `Popover` directly instead.
+ *
+ * Provides context (triggerRef, placement, isOpen, onClose, mode) that
+ * `Popup.Content` reads and forwards to the underlying `Popover`.
+ */
+export function PopupRoot(props) {
+  var _props$mode;
+  var placement = props.placement,
+    children = props.children,
+    testId = props.testId,
+    forceFallbackPositioning = props.forceFallbackPositioning,
+    onOpenChange = props.onOpenChange;
+  var mode = (_props$mode = props.mode) !== null && _props$mode !== void 0 ? _props$mode : 'auto';
+  var onClose = mode === 'manual' ? null : props.onClose;
+  var id = 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.
+  var sanitizedId = id.replace(/:/g, '');
+  var popoverId = "popover-".concat(sanitizedId);
+  var triggerRef = useRef(null);
+  var popoverRef = useRef(null);
+  var _useState = useState(false),
+    _useState2 = _slicedToArray(_useState, 2),
+    isOpen = _useState2[0],
+    setIsOpen = _useState2[1];
+  var _useState3 = useState('dialog'),
+    _useState4 = _slicedToArray(_useState3, 2),
+    ariaHasPopup = _useState4[0],
+    setAriaHasPopup = _useState4[1];
+  var handleClose = useCallback(function (args) {
+    onClose === null || onClose === void 0 || onClose(args);
+  }, [onClose]);
+  var contextValue = {
+    popoverId: popoverId,
+    placement: placement,
+    onClose: mode === 'manual' ? null : handleClose,
+    triggerRef: triggerRef,
+    popoverRef: popoverRef,
+    isOpen: isOpen,
+    setIsOpen: setIsOpen,
+    onOpenChange: onOpenChange,
+    mode: mode,
+    ariaHasPopup: ariaHasPopup,
+    setAriaHasPopup: setAriaHasPopup,
+    testId: testId,
+    forceFallbackPositioning: forceFallbackPositioning
+  };
+  return /*#__PURE__*/React.createElement(PopupProvider, {
+    value: contextValue
+  }, children);
+}

package/dist/esm/popup/types.js

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

package/dist/esm/use-arrow-navigation/index.js

@@ -0,0 +1 @@
+export { useArrowNavigation, isAtCurrentMenuLevel } from './use-arrow-navigation';