@atlaskit/top-layer 0.13.0 → 0.14.0

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

@@ -1,207 +0,0 @@
-/* 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 { prefersReducedMotion } from '../internal/reduced-motion';
-import { roleToAriaHasPopup } from '../internal/role-to-aria-has-popup';
-import { shouldFocusIntoPopover } from '../internal/should-focus-into-popover';
-import { useAnchorPosition } from '../internal/use-anchor-position';
-import { useWidthFromAnchor } from '../internal/use-width-from-anchor';
-import { Popover } from '../popover/popover';
-import { useMaybePopupContext } from './use-maybe-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 const PopupContent = /*#__PURE__*/forwardRef(function PopupContent({
-  children,
-  role,
-  label,
-  labelledBy,
-  animate,
-  mode,
-  widthFromAnchor = 'none',
-  xcss,
-  isOpen: isOpenProp,
-  triggerRef: triggerRefProp,
-  placement: placementProp,
-  onClose: onCloseProp,
-  testId: testIdProp,
-  forceFallbackPositioning: forceFallbackPositioningProp,
-  id: idProp,
-  onEnterFinish,
-  onExitFinish
-}, ref) {
-  var _ref, _ctx$popoverRef;
-  // When inside <Popup>, context provides defaults. Props always win.
-  const ctx = useMaybePopupContext();
-  const triggerRef = triggerRefProp !== null && triggerRefProp !== void 0 ? triggerRefProp : ctx === null || ctx === void 0 ? void 0 : ctx.triggerRef;
-  const placement = (_ref = placementProp !== null && placementProp !== void 0 ? placementProp : ctx === null || ctx === void 0 ? void 0 : ctx.placement) !== null && _ref !== void 0 ? _ref : {};
-  const onClose = onCloseProp !== null && onCloseProp !== void 0 ? onCloseProp : ctx === null || ctx === void 0 ? void 0 : ctx.onClose;
-  const testId = testIdProp !== null && testIdProp !== void 0 ? testIdProp : ctx === null || ctx === void 0 ? void 0 : ctx.testId;
-  const forceFallbackPositioning = forceFallbackPositioningProp !== null && forceFallbackPositioningProp !== void 0 ? forceFallbackPositioningProp : ctx === null || ctx === void 0 ? void 0 : ctx.forceFallbackPositioning;
-
-  // isOpen: prop wins, otherwise derive from context popupState.
-  // 'animating-open' counts as open so <Popover> stays visible during entry animation.
-  const isOpen = isOpenProp !== null && isOpenProp !== void 0 ? isOpenProp : ctx !== null ? ctx.popupState === 'open' || ctx.popupState === 'animating-open' : false;
-  const setPopupState = ctx === null || ctx === void 0 ? void 0 : ctx.setPopupState;
-  const consumerOnOpenChange = ctx === null || ctx === void 0 ? void 0 : ctx.onOpenChange;
-
-  // ── TPopupState ──
-  //
-  // popupState is driven by handleOpenChange (below), which fires on every browser
-  // toggle event (showPopover / hidePopover / light-dismiss).
-  //
-  // Exception — initial mount with isOpen=true (prop-controlled usage):
-  //   handleOpenChange only fires from the Popover's toggle event listener, which
-  //   is registered in a useEffect. On the first render, useEffect hasn't run yet,
-  //   so handleOpenChange never fires. We sync popupState here instead.
-  //
-  // Transitions when animations are active:
-  //   closed → animating-open  → open     (enter)
-  //   open   → animating-closed → closed  (exit, via onExitFinish)
-  //
-  // Without animation: closed ↔ open directly.
-  const willAnimate = Boolean(animate) && !prefersReducedMotion();
-  const hasMountedRef = useRef(false);
-  useLayoutEffect(() => {
-    if (hasMountedRef.current) {
-      return;
-    }
-    hasMountedRef.current = true;
-    if (isOpen) {
-      setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState(willAnimate ? 'animating-open' : 'open');
-    }
-  }, [isOpen, setPopupState, willAnimate]);
-  const handleEnterFinish = useCallback(() => {
-    setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState('open');
-    onEnterFinish === null || onEnterFinish === void 0 ? void 0 : onEnterFinish();
-  }, [setPopupState, onEnterFinish]);
-  const handleExitFinish = useCallback(() => {
-    setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState('closed');
-    onExitFinish === null || onExitFinish === void 0 ? void 0 : onExitFinish();
-  }, [setPopupState, onExitFinish]);
-
-  // 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
-  const setAriaHasPopup = ctx === null || ctx === void 0 ? void 0 : ctx.setAriaHasPopup;
-  useLayoutEffect(() => {
-    setAriaHasPopup === null || setAriaHasPopup === void 0 ? void 0 : setAriaHasPopup(roleToAriaHasPopup({
-      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 did not. 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
-  const handleOpenChange = useCallback(args => {
-    // Sync compound state
-    if (args.isOpen) {
-      setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState(willAnimate ? 'animating-open' : 'open');
-    } else {
-      setPopupState === null || setPopupState === void 0 ? void 0 : setPopupState(willAnimate ? 'animating-closed' : 'closed');
-    }
-    consumerOnOpenChange === null || consumerOnOpenChange === void 0 ? 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 will not 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 did not 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) {
-      const trigger = triggerRef === null || triggerRef === void 0 ? void 0 : triggerRef.current;
-      const focusStillInPopover = trigger && args.element.contains(document.activeElement);
-      // Single source of truth for "this role moves focus on open
-      // and therefore needs to be restored on close" - see
-      // `shouldFocusIntoPopover` in `internal/role-types.tsx`.
-      if (focusStillInPopover && shouldFocusIntoPopover({
-        role
-      })) {
-        trigger.focus({
-          preventScroll: true
-        });
-      }
-    }
-  }, [consumerOnOpenChange, triggerRef, role, setPopupState, willAnimate]);
-
-  // 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.
-  const localRef = useRef(null);
-  const popoverRef = (_ctx$popoverRef = ctx === null || ctx === void 0 ? void 0 : ctx.popoverRef) !== null && _ctx$popoverRef !== void 0 ? _ctx$popoverRef : localRef;
-  useAnchorPosition({
-    anchorRef: triggerRef !== null && triggerRef !== void 0 ? triggerRef : {
-      current: null
-    },
-    popoverRef,
-    placement,
-    forceFallbackPositioning
-  });
-  useWidthFromAnchor({
-    mode: widthFromAnchor,
-    popoverRef,
-    anchorRef: triggerRef
-  });
-
-  // Merge: the popoverRef (shared with trigger + positioning) and the forwarded ref.
-  const combinedRef = mergeRefs([popoverRef, ref]);
-
-  // TPopupContentProps already validates the discriminated union (role + label,
-  // mode + onClose) at its API boundary. Popover accepts TPopoverForwardedProps
-  // internally so individual prop forwarding does not need to re-prove the union.
-  const popoverProps = {
-    isOpen,
-    animate,
-    placement,
-    mode,
-    role,
-    label,
-    labelledBy,
-    onClose: onClose !== null && onClose !== void 0 ? onClose : undefined,
-    onOpenChange: handleOpenChange,
-    onEnterFinish: handleEnterFinish,
-    onExitFinish: handleExitFinish,
-    testId,
-    children,
-    // Standalone consumers can pass an explicit `id` - used by their own
-    // trigger to wire `aria-controls`. Inside the `<Popup>` compound, the
-    // id flows from context (`ctx.popoverId`).
-    id: idProp !== null && idProp !== void 0 ? idProp : ctx === null || ctx === void 0 ? void 0 : ctx.popoverId,
-    xcss
-  };
-  return /*#__PURE__*/React.createElement(Popover, _extends({
-    ref: combinedRef
-  }, popoverProps));
-});

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

@@ -1,20 +0,0 @@
-import { createContext } from 'react';
-
-/**
- * Represents the lifecycle state of the popup.
- *
- * - `'closed'`: fully closed, not visible, no animation playing.
- * - `'animating-open'`: entry animation is playing (popup is opening but not yet settled).
- * - `'open'`: fully open, browser popover is showing, entry animation complete.
- * - `'animating-closed'`: exit animation is playing (popup is closing but still visible).
- *
- * Used to derive `aria-expanded` on the trigger:
- * - `aria-expanded` is `true` in `'animating-open'`, `'open'`, and `'animating-closed'`.
- *
- * This avoids screen readers announcing the popup as closed while it is
- * still visually present on screen during animations, and prevents consumers
- * that conditionally show/hide trigger UI based on `aria-expanded` from hiding
- * the trigger (and thus the popup anchor) mid-animation.
- */
-
-export const PopupContext = /*#__PURE__*/createContext(null);

package/dist/es2019/popup/popup-provider.js

@@ -1,10 +0,0 @@
-import { PopupContext } from './popup-context';
-
-/**
- * __Popup provider__
- *
- * Provides shared popup state (placement, popoverId, triggerRef,
- * isOpen, onClose) to compound child components such as `Popup.Trigger` and
- * `Popup.Content`.
- */
-export const PopupProvider = PopupContext.Provider;

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

@@ -1,30 +0,0 @@
-/* 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';
-const 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.
- *
- * **Presentational primitive - `children`-only by design.** This component
- * intentionally exposes no `style`, `className`, `xcss`, `id`, or `ref`
- * props. If you need any of those, render your own wrapper element inside
- * `Popup.Content` instead - `PopupSurface` is the no-config "give me the
- * default ADS overlay look" surface, nothing more.
- */
-export function PopupSurface({
-  children
-}) {
-  return /*#__PURE__*/React.createElement("div", {
-    className: ax([styles.root])
-  }, children);
-}

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

@@ -1,75 +0,0 @@
-import { useCallback, useMemo } from 'react';
-import { usePopupContext } from './use-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({
-  children
-}) {
-  const {
-    triggerRef,
-    popoverRef,
-    popoverId,
-    popupState,
-    ariaHasPopup
-  } = usePopupContext();
-  const ref = useCallback(node => {
-    triggerRef.current = node;
-  }, [triggerRef]);
-  const toggle = useCallback(() => {
-    const popoverEl = popoverRef.current;
-    if (popoverEl) {
-      // Defensive: element may be disconnected or in an unexpected state.
-      try {
-        popoverEl.togglePopover();
-      } catch {}
-    }
-  }, [popoverRef]);
-  const ariaAttributes = useMemo(() => ({
-    // aria-expanded stays true throughout entry and exit animations so screen readers
-    // don't announce the popup as closed while it's still visible, and consumers
-    // relying on aria-expanded to show/hide trigger UI don't lose the anchor mid-animation.
-    'aria-expanded': popupState === 'open' || popupState === 'animating-open' || popupState === 'animating-closed',
-    'aria-controls': popoverId,
-    'aria-haspopup': ariaHasPopup
-  }), [popupState, popoverId, ariaHasPopup]);
-  return children({
-    ref,
-    isOpen: popupState === 'open' || popupState === 'animating-open',
-    popoverId,
-    toggle,
-    ariaAttributes
-  });
-}

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

@@ -1,61 +0,0 @@
-import React, { isValidElement, useCallback } from 'react';
-import { Slot } from '../internal/slot';
-import { usePopupContext } from './use-popup-context';
-
-/**
- * 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.
- *
- * 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.
- */
-export function PopupTrigger({
-  children
-}) {
-  const {
-    triggerRef,
-    popoverRef,
-    popoverId,
-    popupState,
-    ariaHasPopup
-  } = usePopupContext();
-  const childOnClick = /*#__PURE__*/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).
-  const isOpenRef = React.useRef(popupState === 'open' || popupState === 'animating-open');
-  isOpenRef.current = popupState === 'open' || popupState === 'animating-open';
-  const handleClick = useCallback(event => {
-    const popoverEl = popoverRef.current;
-    if (popoverEl) {
-      // `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) {
-        try {
-          popoverEl.showPopover();
-        } catch {
-          // Element may be disconnected; ignore.
-        }
-      }
-    }
-    childOnClick === null || childOnClick === void 0 ? void 0 : childOnClick(event);
-  }, [popoverRef, childOnClick]);
-  return /*#__PURE__*/React.createElement(Slot, {
-    ref: triggerRef,
-    onClick: handleClick
-    // aria-expanded stays true throughout entry and exit animations so screen readers
-    // don't announce the popup as closed while it's still visible, and consumers
-    // relying on aria-expanded to show/hide trigger UI don't lose the anchor mid-animation.
-    ,
-    "aria-expanded": popupState === 'open' || popupState === 'animating-open' || popupState === 'animating-closed',
-    "aria-controls": popoverId,
-    "aria-haspopup": ariaHasPopup
-  }, children);
-}

package/dist/es2019/popup/popup.js

@@ -1,67 +0,0 @@
-import React, { useCallback, useId, useRef, useState } from 'react';
-import { PopupProvider } from './popup-provider';
-/**
- * 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$placement, _props$mode;
-  const {
-    children,
-    testId,
-    forceFallbackPositioning,
-    onOpenChange
-  } = props;
-  // `{}` resolves to "below the trigger, centered, with `space.100` gap"
-  // inside `useAnchorPosition`, which is the common case.
-  const placement = (_props$placement = props.placement) !== null && _props$placement !== void 0 ? _props$placement : {};
-  const mode = (_props$mode = props.mode) !== null && _props$mode !== void 0 ? _props$mode : 'auto';
-
-  // `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.
-  const onClose = props.onClose;
-  const id = useId();
-  // `useId()` returns IDs containing colons (`:r1:`), which are invalid
-  // in CSS selectors and `popover` target attributes. `replaceAll` is
-  // not in our browser matrix.
-  const sanitizedId = id.replace(/:/g, '');
-  const popoverId = `popover-${sanitizedId}`;
-  const triggerRef = useRef(null);
-  const popoverRef = useRef(null);
-  const [popupState, setPopupState] = useState('closed');
-  // Initial seed before `Popup.Content`'s layout effect resolves the
-  // real role on first paint.
-  const [ariaHasPopup, setAriaHasPopup] = useState('dialog');
-  const handleClose = useCallback(args => {
-    onClose === null || onClose === void 0 ? void 0 : onClose(args);
-  }, [onClose]);
-  const contextValue = {
-    popoverId,
-    placement,
-    // `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,
-    popoverRef,
-    popupState,
-    setPopupState,
-    onOpenChange,
-    mode,
-    ariaHasPopup,
-    setAriaHasPopup,
-    testId,
-    forceFallbackPositioning
-  };
-  return /*#__PURE__*/React.createElement(PopupProvider, {
-    value: contextValue
-  }, children);
-}

package/dist/es2019/popup/types.js

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

package/dist/es2019/popup/use-maybe-popup-context.js

@@ -1,12 +0,0 @@
-import { useContext } from 'react';
-import { PopupContext } from './popup-context';
-
-/**
- * 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/es2019/popup/use-popup-context.js

@@ -1,15 +0,0 @@
-import { useContext } from 'react';
-import { PopupContext } from './popup-context';
-
-/**
- * Returns the nearest `Popup` context value.
- *
- * Throws if called outside of a `<Popup>` compound component.
- */
-export function usePopupContext() {
-  const ctx = useContext(PopupContext);
-  if (ctx === null) {
-    throw new Error('@atlaskit/top-layer: Popup compound components must be used within <Popup>.');
-  }
-  return ctx;
-}

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

@@ -1 +0,0 @@
-export { PopupSurface } from '../popup/popup-surface';

package/dist/esm/entry-points/popup.js

@@ -1 +0,0 @@
-export { Popup } from '../popup';

package/dist/esm/popup/index.js

@@ -1,33 +0,0 @@
-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>
- * ```
- */
-var Popup = Object.assign(PopupRoot, {
-  Trigger: PopupTrigger,
-  TriggerFunction: PopupTriggerFunction,
-  Content: PopupContent,
-  Surface: PopupSurface
-});
-export { Popup };