@atlaskit/top-layer 0.1.0

package/dist/es2019/internal/use-initial-focus.js

@@ -0,0 +1,109 @@
+import { useEffect } from 'react';
+import { getFirstFocusable } from '../focus/focus';
+
+/**
+ * Determines the correct element to receive initial focus within a popover,
+ * based on its ARIA role.
+ *
+ * Focus rules by role (per WAI-ARIA APG):
+ * - `dialog` / `alertdialog`: first element with `[autofocus]`, or first focusable element
+ * - `menu`: first menu item (`[role="menuitem|menuitemcheckbox|menuitemradio"]`)
+ * - `listbox`: first selected option (`[aria-selected="true"]`), or first option (`[role="option"]`)
+ * - `tooltip`: no focus movement (tooltips are informational)
+ * - no role / other roles: no focus movement
+ *
+ * Note: React 18's `autoFocus` JSX prop does NOT set the HTML `autofocus`
+ * attribute — it only calls `.focus()` imperatively during commit, which
+ * has no effect on hidden popover content. Consumers must set the native
+ * attribute via a ref callback (e.g. `node.setAttribute('autofocus', '')`).
+ * React 19+ reflects the JSX prop as the HTML attribute automatically.
+ */
+function getInitialFocusTarget({
+  container
+}) {
+  const role = container.getAttribute('role');
+  if (role === 'dialog' || role === 'alertdialog') {
+    // Prefer element with the native HTML autofocus attribute.
+    const autofocusEl = container.querySelector('[autofocus]');
+    if (autofocusEl) {
+      return autofocusEl;
+    }
+    // Fall back to first focusable element
+    return getFirstFocusable({
+      container
+    });
+  }
+  if (role === 'menu') {
+    // Initial focus placement is the extent of what top-layer provides
+    // for menus. All subsequent keyboard navigation (arrow keys, Home/End,
+    // type-ahead, Enter/Space, submenu coordination) is the responsibility
+    // of the consumer component (e.g. dropdown-menu), because menu keyboard
+    // behavior varies by context (orientation, nesting, item type, control
+    // pattern). See: notes/outputs/menu-keyboard-decision.md
+    return getFirstFocusable({
+      container
+    });
+  }
+  if (role === 'listbox') {
+    // Prefer selected option, fall back to first focusable
+    const selectedOption = container.querySelector('[role="option"][aria-selected="true"]');
+    if (selectedOption) {
+      return selectedOption;
+    }
+    return getFirstFocusable({
+      container
+    });
+  }
+
+  // tooltip, no role, or other roles: no focus movement
+  return null;
+}
+
+/**
+ * Moves focus into a popover element when it opens, based on its ARIA role.
+ *
+ * This implements WCAG 2.4.3 (Focus Order) initial focus placement:
+ * - `dialog` / `alertdialog` → focus first focusable (or `[autofocus]`)
+ * - `menu` → focus first menu item
+ * - `listbox` → focus selected or first option
+ * - `tooltip` / no role → no focus movement
+ *
+ * The role is read from the element's `role` attribute (not passed as a prop),
+ * following the same pattern as `useFocusWrap`.
+ *
+ * Always call this hook unconditionally. Focus is only moved when `isOpen`
+ * transitions to `true` and the role requires it.
+ */
+export function useInitialFocus({
+  elementRef,
+  isOpen,
+  role
+}) {
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+    const el = elementRef.current;
+    if (!el) {
+      return;
+    }
+
+    // Use requestAnimationFrame to ensure the popover is fully rendered
+    // and visible in the top layer before attempting to move focus.
+    // showPopover() is called in useLayoutEffect (which runs before this
+    // useEffect), so by the time the RAF fires after the next paint the
+    // element is guaranteed to be in the top layer.
+    const rafId = requestAnimationFrame(() => {
+      var _getInitialFocusTarge;
+      (_getInitialFocusTarge = getInitialFocusTarget({
+        container: el
+      })) === null || _getInitialFocusTarge === void 0 ? void 0 : _getInitialFocusTarge.focus();
+    });
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+    // We intentionally depend on `role` even though `getInitialFocusTarget`
+    // reads from the DOM attribute. This ensures the effect re-runs if
+    // the role prop changes while the popover is open.
+  }, [elementRef, isOpen, role]);
+}

package/dist/es2019/internal/use-preset-styles.js

@@ -0,0 +1,22 @@
+import { useInsertionEffect } from 'react';
+import { ensurePresetStyles } from './ensure-preset-styles';
+/**
+ * Normalizes a preset prop to a value (or null) and ensures its CSS
+ * is injected once into `document.head`.
+ *
+ * Works with any preset that has `{ css, name }` — animation presets
+ * (TAnimationPreset) and arrow presets (TArrowPreset) both satisfy this shape.
+ */
+export function usePresetStyles({
+  preset
+}) {
+  const resolved = preset != null && preset !== false ? preset : null;
+  useInsertionEffect(() => {
+    if (resolved) {
+      ensurePresetStyles({
+        preset: resolved
+      });
+    }
+  }, [resolved]);
+  return resolved;
+}

package/dist/es2019/placement-map/index.js

@@ -0,0 +1,142 @@
+/**
+ * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
+ * `@atlaskit/tooltip`, etc.).
+ */
+
+/**
+ * Maps legacy Popper.js placement values to the new object-based
+ * `Placement` values used by `@atlaskit/top-layer/popover`.
+ *
+ * **Mapping logic:**
+ *
+ * | Legacy (Popper.js)  | New (Placement object)                              |
+ * | ------------------- | --------------------------------------------------- |
+ * | `top`               | `{ axis: 'block', edge: 'start', align: 'center' }`  |
+ * | `top-start`         | `{ axis: 'block', edge: 'start', align: 'start' }`   |
+ * | `top-end`           | `{ axis: 'block', edge: 'start', align: 'end' }`     |
+ * | `bottom`            | `{ axis: 'block', edge: 'end', align: 'center' }`    |
+ * | `bottom-start`      | `{ axis: 'block', edge: 'end', align: 'start' }`     |
+ * | `bottom-end`        | `{ axis: 'block', edge: 'end', align: 'end' }`       |
+ * | `right`             | `{ axis: 'inline', edge: 'end', align: 'center' }`   |
+ * | `right-start`       | `{ axis: 'inline', edge: 'end', align: 'start' }`    |
+ * | `right-end`         | `{ axis: 'inline', edge: 'end', align: 'end' }`      |
+ * | `left`              | `{ axis: 'inline', edge: 'start', align: 'center' }` |
+ * | `left-start`        | `{ axis: 'inline', edge: 'start', align: 'start' }`  |
+ * | `left-end`          | `{ axis: 'inline', edge: 'start', align: 'end' }`    |
+ * | `auto`              | `{ axis: 'block', edge: 'end', align: 'center' }`    |
+ * | `auto-start`        | `{ axis: 'block', edge: 'end', align: 'start' }`     |
+ * | `auto-end`          | `{ axis: 'block', edge: 'end', align: 'end' }`       |
+ *
+ * The `position-try-fallbacks` CSS property handles flipping automatically.
+ *
+ * @example
+ * ```ts
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ *
+ * // In a migration from @atlaskit/popup:
+ * const oldPlacement: TLegacyPlacement = 'bottom-start';
+ * const newPlacement: TPlacementOptions = fromLegacyPlacement({ legacy: oldPlacement });
+ * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
+ * ```
+ */
+const placementMapping = {
+  top: {
+    axis: 'block',
+    edge: 'start',
+    align: 'center'
+  },
+  'top-start': {
+    axis: 'block',
+    edge: 'start',
+    align: 'start'
+  },
+  'top-center': {
+    axis: 'block',
+    edge: 'start',
+    align: 'center'
+  },
+  'top-end': {
+    axis: 'block',
+    edge: 'start',
+    align: 'end'
+  },
+  bottom: {
+    axis: 'block',
+    edge: 'end',
+    align: 'center'
+  },
+  'bottom-start': {
+    axis: 'block',
+    edge: 'end',
+    align: 'start'
+  },
+  'bottom-center': {
+    axis: 'block',
+    edge: 'end',
+    align: 'center'
+  },
+  'bottom-end': {
+    axis: 'block',
+    edge: 'end',
+    align: 'end'
+  },
+  right: {
+    axis: 'inline',
+    edge: 'end',
+    align: 'center'
+  },
+  'right-start': {
+    axis: 'inline',
+    edge: 'end',
+    align: 'start'
+  },
+  'right-end': {
+    axis: 'inline',
+    edge: 'end',
+    align: 'end'
+  },
+  left: {
+    axis: 'inline',
+    edge: 'start',
+    align: 'center'
+  },
+  'left-start': {
+    axis: 'inline',
+    edge: 'start',
+    align: 'start'
+  },
+  'left-end': {
+    axis: 'inline',
+    edge: 'start',
+    align: 'end'
+  },
+  auto: {
+    axis: 'block',
+    edge: 'end',
+    align: 'center'
+  },
+  'auto-start': {
+    axis: 'block',
+    edge: 'end',
+    align: 'start'
+  },
+  'auto-end': {
+    axis: 'block',
+    edge: 'end',
+    align: 'end'
+  }
+};
+
+/**
+ * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ */
+export function fromLegacyPlacement({
+  legacy
+}) {
+  return placementMapping[legacy];
+}
+
+/**
+ * The full mapping record, exposed for consumers that need to iterate or introspect.
+ */
+export { placementMapping };

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

@@ -0,0 +1,39 @@
+/**
+ * Creates a synthetic DOM event from a `TPopoverCloseReason`.
+ *
+ * Useful when bridging the Popover primitive's `onClose({ reason })` callback
+ * to a legacy API that expects a native DOM event — for example,
+ * `@atlaskit/inline-dialog`'s `onClose(event)` contract.
+ *
+ * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
+ * - `'light-dismiss'` → `MouseEvent('click')`
+ *
+ * For any other reason, a generic `Event('close')` is returned as a fallback.
+ *
+ * @example
+ * ```tsx
+ * import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
+ * import { type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
+ *
+ * function onPopoverClose({ reason }: { reason: TPopoverCloseReason }) {
+ *   legacyOnClose(createPopoverCloseEvent({ reason }));
+ * }
+ * ```
+ */
+export function createPopoverCloseEvent({
+  reason
+}) {
+  if (reason === 'escape') {
+    return new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true
+    });
+  }
+  if (reason === 'light-dismiss') {
+    return new MouseEvent('click', {
+      bubbles: true,
+      cancelable: true
+    });
+  }
+  return new Event('close');
+}

package/dist/es2019/popover/index.js

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

package/dist/es2019/popover/popover.compiled.css

@@ -0,0 +1,13 @@
+
+._19itglyw{border:none}
+._1r041wug{inset:auto}._18m9ewfl{overflow-y:visible}
+._18u0idpf{margin-left:0}
+._19bvidpf{padding-left:0}
+._19pkidpf{margin-top:0}
+._1reoewfl{overflow-x:visible}
+._2hwxidpf{margin-right:0}
+._bfhk1j28{background-color:transparent}
+._ca0qidpf{padding-top:0}
+._n3tdidpf{padding-bottom:0}
+._otyridpf{margin-bottom:0}
+._u5f3idpf{padding-right:0}

package/dist/es2019/popover/popover.js

@@ -0,0 +1,240 @@
+/* popover.tsx generated by @compiled/babel-plugin v0.39.1 */
+import _extends from "@babel/runtime/helpers/extends";
+import "./popover.compiled.css";
+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 once from '@atlaskit/ds-lib/once';
+import { useAnimatedVisibility } from '../internal/use-animated-visibility';
+import { useFocusWrap } from '../internal/use-focus-wrap';
+import { useInitialFocus } from '../internal/use-initial-focus';
+/**
+ * Detects whether the browser supports the `popover="hint"` attribute value.
+ * Uses DOM reflection: unsupported browsers reflect the invalid value default ("manual").
+ * Safe for SSR. Result is cached via `once`.
+ */
+const supportsPopoverHint = once(() => {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+  // eslint-disable-next-line @atlaskit/platform/no-direct-document-usage -- feature detection
+  const el = document.createElement('div');
+  el.setAttribute('popover', 'hint');
+  return el.popover === 'hint';
+});
+
+// eslint-disable-next-line @atlaskit/ui-styling-standard/no-unsafe-values -- popover UA reset requires values not in cssMap's type union
+const styles = {
+  root: "_19itglyw _ca0qidpf _u5f3idpf _n3tdidpf _19bvidpf _19pkidpf _2hwxidpf _otyridpf _18u0idpf _1r041wug _1reoewfl _18m9ewfl _bfhk1j28"
+};
+/**
+ * Unopinionated top-layer primitive.
+ *
+ * Manages only visibility (isOpen) and animation (animate). Has no knowledge
+ * of positioning — compose with `useAnchorPosition` for anchor positioning.
+ *
+ * Visibility is driven by the `isOpen` prop:
+ * - `isOpen={true}` → `showPopover()`, entry animation via `@starting-style`
+ * - `isOpen={false}` → `hidePopover()`, exit animation via `allow-discrete`
+ *
+ * For `mode="auto"`, the browser can dismiss the popover via light dismiss
+ * (Escape, click outside). When that happens, `onClose` is called and the
+ * consumer must set `isOpen` to `false`. The DOM owns the dismiss — React
+ * must follow.
+ */
+export const Popover = /*#__PURE__*/forwardRef(function Popover({
+  children,
+  mode: modeProp = 'auto',
+  onClose = noop,
+  onOpenChange,
+  onExitFinish,
+  animate,
+  placement,
+  testId,
+  isOpen,
+  // ARIA
+  role,
+  label,
+  labelledBy,
+  id: idProp
+}, ref) {
+  const autoId = useId();
+  const ownRef = useRef(null);
+  const combinedRef = mergeRefs([ownRef, ref].filter(Boolean));
+  // Regex is intentional — `replaceAll` is not available in our supported
+  // browser matrix. In React 18, `useId()` returns IDs containing colons
+  // (e.g. `:r1:`) which are invalid in CSS selectors and `popover` target
+  // attributes. React 19.2.0 replaced colons with underscores, making this
+  // stripping unnecessary once React 18 support is dropped.
+  const popoverId = idProp !== null && idProp !== void 0 ? idProp : `popover-${autoId.replace(/:/g, '')}`;
+  const {
+    showChildren,
+    preset
+  } = useAnimatedVisibility({
+    isOpen,
+    animate,
+    elementRef: ownRef,
+    onExitFinish
+  });
+
+  // ── Focus management ──
+  // Initial focus: on open, moves focus into the popover (role-dependent).
+  // Focus wrap: Tab/Shift+Tab cycle within the popover for dialog roles.
+  // Focus restoration: handled natively by the Popover API — the browser
+  //   tracks `previouslyFocusedElement` on show and restores it on hide.
+  //   No custom restoration hook is needed. See: notes/architecture/focus-restoration.md
+  useFocusWrap({
+    elementRef: ownRef,
+    role
+  });
+  useInitialFocus({
+    elementRef: ownRef,
+    isOpen,
+    role
+  });
+
+  // Hint mode fallback: "hint" downgrades to "auto" if unsupported.
+  //
+  // Decision (2026-03-17 audit): We keep "auto" as the fallback (not "manual")
+  // because it provides the closest behavior to "hint" (light dismiss works).
+  // However, there is a behavioral difference: "auto" participates in the
+  // auto-dismiss stack and WILL close other "auto" popovers when it opens
+  // (e.g. a tooltip opening will close an open dropdown). "hint" does not
+  // have this side effect. This difference only affects browsers without
+  // popover="hint" support, and that set is shrinking rapidly.
+  const mode = modeProp === 'hint' && !supportsPopoverHint() ? 'auto' : modeProp;
+
+  // Distinguishes programmatic hidePopover() from browser-initiated dismiss.
+  // When we call hidePopover() ourselves the toggle event fires synchronously —
+  // this ref prevents the toggle handler from calling onClose redundantly.
+  const programmaticCloseRef = useRef(false);
+
+  // Escape key tracking: set in a capture-phase keydown listener (fires before
+  // the browser processes light dismiss), read in the toggle handler.
+  const closeReasonRef = useRef('light-dismiss');
+  const handleToggle = useCallback(event => {
+    const el = ownRef.current;
+    if (event.newState === 'open') {
+      if (el) {
+        onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange({
+          isOpen: true,
+          element: el
+        });
+      }
+      return;
+    }
+    if (event.newState === 'closed') {
+      if (el) {
+        onOpenChange === null || onOpenChange === void 0 ? void 0 : onOpenChange({
+          isOpen: false,
+          element: el
+        });
+      }
+
+      // Programmatic close (unmount or isOpen→false). Consumer already knows.
+      if (programmaticCloseRef.current) {
+        return;
+      }
+
+      // Browser dismiss (Escape or click-outside). Notify consumer.
+      const reason = closeReasonRef.current;
+      closeReasonRef.current = 'light-dismiss'; // reset for next dismiss
+      onClose({
+        reason
+      });
+    }
+  }, [onClose, onOpenChange]);
+  useEffect(() => {
+    const el = ownRef.current;
+    if (!el) {
+      return;
+    }
+
+    // Capture-phase: tag Escape before the browser processes light dismiss.
+    const unbindEscape = bind(el, {
+      type: 'keydown',
+      listener: event => {
+        if (event.key === 'Escape') {
+          closeReasonRef.current = 'escape';
+        }
+      },
+      options: {
+        capture: true
+      }
+    });
+    const unbindToggle = bind(el, {
+      type: 'toggle',
+      listener: handleToggle
+    });
+    return () => {
+      unbindEscape();
+      unbindToggle();
+    };
+  }, [handleToggle]);
+
+  // Placement-dependent animation CSS vars (e.g. slide direction).
+  // Separate from show/hide so that preset reference changes
+  // (e.g. inline `animate={slideAndFade()}`) don't re-trigger visibility.
+  useLayoutEffect(() => {
+    const el = ownRef.current;
+    if (!el || !(preset !== null && preset !== void 0 && preset.getProperties) || !placement) {
+      return;
+    }
+    const props = preset.getProperties({
+      placement
+    });
+    Object.entries(props).forEach(([key, value]) => {
+      el.style.setProperty(key, String(value));
+    });
+  }, [preset, placement]);
+
+  // Show/hide based on isOpen. try/catch because show/hide throw if the
+  // element is already in the target state (e.g. browser dismissed via
+  // light-dismiss before our effect ran).
+  useLayoutEffect(() => {
+    const el = ownRef.current;
+    if (!el) {
+      return;
+    }
+    if (isOpen) {
+      programmaticCloseRef.current = false;
+      try {
+        el.showPopover();
+      } catch {
+        // Already showing or unsupported — DOM matches intent.
+      }
+      return () => {
+        programmaticCloseRef.current = true;
+        try {
+          el.hidePopover();
+        } catch {
+          // Already hidden — DOM matches intent.
+        }
+      };
+    }
+    programmaticCloseRef.current = true;
+    try {
+      el.hidePopover();
+    } catch {
+      // Already hidden — DOM matches intent.
+    }
+  }, [isOpen]);
+  return /*#__PURE__*/React.createElement("div", _extends({
+    ref: combinedRef,
+    id: popoverId
+    // @ts-expect-error -- popover attribute not yet in React types
+    // eslint-disable-next-line react/no-unknown-property -- popover attribute not yet in React types
+    ,
+    popover: mode,
+    role: role,
+    "aria-label": label,
+    "aria-labelledby": labelledBy,
+    "data-testid": testId
+  }, preset ? {
+    [`data-ds-popover-${preset.name}`]: ''
+  } : undefined, {
+    className: ax([styles.root])
+  }), showChildren ? children : null);
+});

package/dist/es2019/popover/types.js

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

package/dist/es2019/popup/index.js

@@ -0,0 +1,33 @@
+import { PopupRoot } from './popup';
+import { PopupContent } from './popup-content';
+import { PopupSurface } from './popup-surface';
+import { PopupTrigger } from './popup-trigger';
+import { PopupTriggerFunction } from './popup-trigger-function';
+
+/**
+ * Compound component for rendering content in the browser's top layer
+ * using the native Popover API (`popover="auto"`).
+ * Placement is owned by this compound: root provides it via context, Content applies it
+ * (CSS Anchor Positioning or JS fallback).
+ *
+ * For default overlay styling (background, shadow, border-radius), see `PopupSurface` in the package examples.
+ *
+ * @example
+ * ```tsx
+ * <Popup placement={{ edge: 'end' }} onClose={handleClose}>
+ *   <Popup.Trigger>
+ *     <button>Open</button>
+ *   </Popup.Trigger>
+ *   <Popup.Content role="dialog" label="My popup">
+ *     Content goes here
+ *   </Popup.Content>
+ * </Popup>
+ * ```
+ */
+const Popup = Object.assign(PopupRoot, {
+  Trigger: PopupTrigger,
+  TriggerFunction: PopupTriggerFunction,
+  Content: PopupContent,
+  Surface: PopupSurface
+});
+export { Popup };